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 CheckCXXSourceCompiles 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 The following variables may be set before calling this macro to modify
736 the way the check is run:
737 CMAKE_REQUIRED_LINK_OPTIONS
739 New in version 3.14: A ;-list of options to add to the link com‐
740 mand (see try_compile() for further details).
741 CMAKE_REQUIRED_LIBRARIES
744 A ;-list of libraries to add to the link command. These can be
745 the name of system libraries or they can be Imported Targets
746 (see try_compile() for further details).
747 CheckFortranSourceCompiles
749 New in version 3.1.
750 Check if given Fortran source compiles and links into an executable.
753 check_fortran_source_compiles
755 check_fortran_source_compiles(<code> <resultVar>
757 [FAIL_REGEX <regex>...]
758 [SRC_EXT <extension>]
759 )
760 Checks that the source supplied in <code> can be compiled as a
762 Fortran source file and linked as an executable. The <code> must
763 be a Fortran program containing at least an end statement--for
764 example:
765 check_fortran_source_compiles("character :: b; error stop b; end" F2018ESTOPOK SRC_EXT F90)
767 This command can help avoid costly build processes when a com‐
769 piler lacks support for a necessary feature, or a particular
770 vendor library is not compatible with the Fortran compiler ver‐
771 sion being used. This generate-time check may advise the user of
772 such before the main build process. See also the check_for‐
773 tran_source_runs() command to actually run the compiled code.
774 The result will be stored in the internal cache variable <re‐
776 sultVar>, with a boolean true value for success and boolean
777 false for failure.
778 If FAIL_REGEX is provided, then failure is determined by check‐
780 ing if anything in the output matches any of the specified regu‐
781 lar expressions.
782 By default, the test source file will be given a .F file exten‐
784 sion. The SRC_EXT option can be used to override this with .<ex‐
785 tension> instead-- .F90 is a typical choice.
786 The underlying check is performed by the try_compile() command.
788 The compile and link commands can be influenced by setting any
789 of the following variables prior to calling check_for‐
790 tran_source_compiles():
791 CMAKE_REQUIRED_FLAGS
793 Additional flags to pass to the compiler. Note that the
794 contents of CMAKE_Fortran_FLAGS and its associated con‐
795 figuration-specific variable are automatically added to
796 the compiler command before the contents of CMAKE_RE‐
797 QUIRED_FLAGS.
798 CMAKE_REQUIRED_DEFINITIONS
800 A ;-list of compiler definitions of the form -DFOO or
801 -DFOO=bar. A definition for the name specified by <re‐
802 sultVar> will also be added automatically.
803 CMAKE_REQUIRED_INCLUDES
805 A ;-list of header search paths to pass to the compiler.
806 These will be the only header search paths used by
807 try_compile(), i.e. the contents of the INCLUDE_DIRECTO‐
808 RIES directory property will be ignored.
809 CMAKE_REQUIRED_LINK_OPTIONS
811 New in version 3.14.
812 A ;-list of options to add to the link command (see
815 try_compile() for further details).
816 CMAKE_REQUIRED_LIBRARIES
818 A ;-list of libraries to add to the link command. These
819 can be the name of system libraries or they can be Im‐
820 ported Targets (see try_compile() for further details).
821 CMAKE_REQUIRED_QUIET
823 If this variable evaluates to a boolean true value, all
824 status messages associated with the check will be sup‐
825 pressed.
826 The check is only performed once, with the result cached in the
828 variable named by <resultVar>. Every subsequent CMake run will
829 re-use this cached value rather than performing the check again,
830 even if the <code> changes. In order to force the check to be
831 re-evaluated, the variable named by <resultVar> must be manually
832 removed from the cache.
833 CheckFortranSourceRuns
835 New in version 3.14.
836 Check if given Fortran source compiles and links into an executable and
839 can subsequently be run.
840 check_fortran_source_runs
842 check_fortran_source_runs(<code> <resultVar>
844 [SRC_EXT <extension>])
845 Check that the source supplied in <code> can be compiled as a
847 Fortran source file, linked as an executable and then run. The
848 <code> must be a Fortran program containing at least an end
849 statement--for example:
850 check_fortran_source_runs("real :: x[*]; call co_sum(x); end" F2018coarrayOK)
852 This command can help avoid costly build processes when a com‐
854 piler lacks support for a necessary feature, or a particular
855 vendor library is not compatible with the Fortran compiler ver‐
856 sion being used. Some of these failures only occur at runtime
857 instead of linktime, and a trivial runtime example can catch the
858 issue before the main build process.
859 If the <code> could be built and run successfully, the internal
861 cache variable specified by <resultVar> will be set to 1, other‐
862 wise it will be set to an value that evaluates to boolean false
863 (e.g. an empty string or an error message).
864 By default, the test source file will be given a .F90 file ex‐
866 tension. The SRC_EXT option can be used to override this with
867 .<extension> instead.
868 The underlying check is performed by the try_run() command. The
870 compile and link commands can be influenced by setting any of
871 the following variables prior to calling check_for‐
872 tran_source_runs():
873 CMAKE_REQUIRED_FLAGS
875 Additional flags to pass to the compiler. Note that the
876 contents of CMAKE_Fortran_FLAGS and its associated con‐
877 figuration-specific variable are automatically added to
878 the compiler command before the contents of CMAKE_RE‐
879 QUIRED_FLAGS.
880 CMAKE_REQUIRED_DEFINITIONS
882 A ;-list of compiler definitions of the form -DFOO or
883 -DFOO=bar. A definition for the name specified by <re‐
884 sultVar> will also be added automatically.
885 CMAKE_REQUIRED_INCLUDES
887 A ;-list of header search paths to pass to the compiler.
888 These will be the only header search paths used by
889 try_run(), i.e. the contents of the INCLUDE_DIRECTORIES
890 directory property will be ignored.
891 CMAKE_REQUIRED_LINK_OPTIONS
893 A ;-list of options to add to the link command (see
894 try_run() for further details).
895 CMAKE_REQUIRED_LIBRARIES
897 A ;-list of libraries to add to the link command. These
898 can be the name of system libraries or they can be Im‐
899 ported Targets (see try_run() for further details).
900 CMAKE_REQUIRED_QUIET
902 If this variable evaluates to a boolean true value, all
903 status messages associated with the check will be sup‐
904 pressed.
905 The check is only performed once, with the result cached in the
907 variable named by <resultVar>. Every subsequent CMake run will
908 re-use this cached value rather than performing the check again,
909 even if the <code> changes. In order to force the check to be
910 re-evaluated, the variable named by <resultVar> must be manually
911 removed from the cache.
912 CheckFunctionExists
914 Check if a C function can be linked
915 check_function_exists
917 check_function_exists(<function> <variable>)
919 Checks that the <function> is provided by libraries on the sys‐
921 tem and store the result in a <variable>, which will be created
922 as an internal cache variable.
923 The following variables may be set before calling this macro to modify
925 the way the check is run:
926 CMAKE_REQUIRED_FLAGS
928 string of compile command line flags.
929 CMAKE_REQUIRED_DEFINITIONS
931 a ;-list of macros to define (-DFOO=bar).
932 CMAKE_REQUIRED_INCLUDES
934 a ;-list of header search paths to pass to the compiler.
935 CMAKE_REQUIRED_LINK_OPTIONS
937 New in version 3.14: a ;-list of options to add to the link com‐
938 mand.
939 CMAKE_REQUIRED_LIBRARIES
942 a ;-list of libraries to add to the link command. See policy
943 CMP0075.
944 CMAKE_REQUIRED_QUIET
946 New in version 3.1: execute quietly without messages.
947 NOTE:
950 Prefer using CheckSymbolExists instead of this module, for the fol‐
951 lowing reasons:
952 • check_function_exists() can't detect functions that are inlined in
954 headers or specified as a macro.
955 • check_function_exists() can't detect anything in the 32-bit ver‐
957 sions of the Win32 API, because of a mismatch in calling conven‐
958 tions.
959 • check_function_exists() only verifies linking, it does not verify
961 that the function is declared in system headers.
962 CheckIncludeFileCXX
964 Provides a macro to check if a header file can be included in CXX.
965 CHECK_INCLUDE_FILE_CXX
967 CHECK_INCLUDE_FILE_CXX(<include> <variable> [<flags>])
969 Check if the given <include> file may be included in a CXX
971 source file and store the result in an internal cache entry
972 named <variable>. The optional third argument may be used to
973 add compilation flags to the check (or use CMAKE_REQUIRED_FLAGS
974 below).
975 The following variables may be set before calling this macro to modify
977 the way the check is run:
978 CMAKE_REQUIRED_FLAGS
980 string of compile command line flags.
981 CMAKE_REQUIRED_DEFINITIONS
983 a ;-list of macros to define (-DFOO=bar).
984 CMAKE_REQUIRED_INCLUDES
986 a ;-list of header search paths to pass to the compiler.
987 CMAKE_REQUIRED_LINK_OPTIONS
989 New in version 3.14: a ;-list of options to add to the link com‐
990 mand.
991 CMAKE_REQUIRED_LIBRARIES
994 a ;-list of libraries to add to the link command. See policy
995 CMP0075.
996 CMAKE_REQUIRED_QUIET
998 New in version 3.1: execute quietly without messages.
999 See modules CheckIncludeFile and CheckIncludeFiles to check for one or
1002 more C headers.
1003 CheckIncludeFile
1005 Provides a macro to check if a header file can be included in C.
1006 CHECK_INCLUDE_FILE
1008 CHECK_INCLUDE_FILE(<include> <variable> [<flags>])
1010 Check if the given <include> file may be included in a C source
1012 file and store the result in an internal cache entry named
1013 <variable>. The optional third argument may be used to add com‐
1014 pilation flags to the check (or use CMAKE_REQUIRED_FLAGS below).
1015 The following variables may be set before calling this macro to modify
1017 the way the check is run:
1018 CMAKE_REQUIRED_FLAGS
1020 string of compile command line flags.
1021 CMAKE_REQUIRED_DEFINITIONS
1023 a ;-list of macros to define (-DFOO=bar).
1024 CMAKE_REQUIRED_INCLUDES
1026 a ;-list of header search paths to pass to the compiler.
1027 CMAKE_REQUIRED_LINK_OPTIONS
1029 New in version 3.14: a ;-list of options to add to the link com‐
1030 mand.
1031 CMAKE_REQUIRED_LIBRARIES
1034 a ;-list of libraries to add to the link command. See policy
1035 CMP0075.
1036 CMAKE_REQUIRED_QUIET
1038 New in version 3.1: execute quietly without messages.
1039 See the CheckIncludeFiles module to check for multiple headers at once.
1042 See the CheckIncludeFileCXX module to check for headers using the CXX
1043 language.
1044 CheckIncludeFiles
1046 Provides a macro to check if a list of one or more header files can be
1047 included together.
1048 CHECK_INCLUDE_FILES
1050 CHECK_INCLUDE_FILES("<includes>" <variable> [LANGUAGE <language>])
1052 Check if the given <includes> list may be included together in a
1054 source file and store the result in an internal cache entry
1055 named <variable>. Specify the <includes> argument as a ;-list
1056 of header file names.
1057 If LANGUAGE is set, the specified compiler will be used to per‐
1059 form the check. Acceptable values are C and CXX. If not set, the
1060 C compiler will be used if enabled. If the C compiler is not en‐
1061 abled, the C++ compiler will be used if enabled.
1062 The following variables may be set before calling this macro to modify
1064 the way the check is run:
1065 CMAKE_REQUIRED_FLAGS
1067 string of compile command line flags.
1068 CMAKE_REQUIRED_DEFINITIONS
1070 a ;-list of macros to define (-DFOO=bar).
1071 CMAKE_REQUIRED_INCLUDES
1073 a ;-list of header search paths to pass to the compiler.
1074 CMAKE_REQUIRED_LINK_OPTIONS
1076 New in version 3.14: a ;-list of options to add to the link com‐
1077 mand.
1078 CMAKE_REQUIRED_LIBRARIES
1081 a ;-list of libraries to add to the link command. See policy
1082 CMP0075.
1083 CMAKE_REQUIRED_QUIET
1085 New in version 3.1: execute quietly without messages.
1086 See modules CheckIncludeFile and CheckIncludeFileCXX to check for a
1089 single header file in C or CXX languages.
1090 CheckIPOSupported
1092 New in version 3.9.
1093 Check whether the compiler supports an interprocedural optimization
1096 (IPO/LTO). Use this before enabling the INTERPROCEDURAL_OPTIMIZATION
1097 target property.
1098 check_ipo_supported
1100 check_ipo_supported([RESULT <result>] [OUTPUT <output>]
1102 [LANGUAGES <lang>...])
1103 Options are:
1105 RESULT <result>
1107 Set <result> variable to YES if IPO is supported by the
1108 compiler and NO otherwise. If this option is not given
1109 then the command will issue a fatal error if IPO is not
1110 supported.
1111 OUTPUT <output>
1113 Set <output> variable with details about any error.
1114 LANGUAGES <lang>...
1116 Specify languages whose compilers to check. Languages C,
1117 CXX, and Fortran are supported.
1118 It makes no sense to use this module when CMP0069 is set to OLD so mod‐
1120 ule will return error in this case. See policy CMP0069 for details.
1121 New in version 3.13: Add support for Visual Studio generators.
1123 Examples
1126 check_ipo_supported() # fatal error if IPO is not supported
1127 set_property(TARGET foo PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
1128 # Optional IPO. Do not use IPO if it's not supported by compiler.
1130 check_ipo_supported(RESULT result OUTPUT output)
1131 if(result)
1132 set_property(TARGET foo PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
1133 else()
1134 message(WARNING "IPO is not supported: ${output}")
1135 endif()
1136 CheckLanguage
1138 Check if a language can be enabled
1139 Usage:
1141 check_language(<lang>)
1143 where <lang> is a language that may be passed to enable_language() such
1145 as Fortran. If CMAKE_<LANG>_COMPILER is already defined the check does
1146 nothing. Otherwise it tries enabling the language in a test project.
1147 The result is cached in CMAKE_<LANG>_COMPILER as the compiler that was
1148 found, or NOTFOUND if the language cannot be enabled. For CUDA which
1149 can have an explicit host compiler, the cache CMAKE_CUDA_HOST_COMPILER
1150 variable will be set if it was required for compilation (and cleared if
1151 it was not).
1152 Example:
1154 check_language(Fortran)
1156 if(CMAKE_Fortran_COMPILER)
1157 enable_language(Fortran)
1158 else()
1159 message(STATUS "No Fortran support")
1160 endif()
1161 CheckLibraryExists
1163 Check if the function exists.
1164 CHECK_LIBRARY_EXISTS
1166 CHECK_LIBRARY_EXISTS(LIBRARY FUNCTION LOCATION VARIABLE)
1168 LIBRARY - the name of the library you are looking for
1170 FUNCTION - the name of the function
1171 LOCATION - location where the library should be found
1172 VARIABLE - variable to store the result
1173 Will be created as an internal cache variable.
1174 The following variables may be set before calling this macro to modify
1176 the way the check is run:
1177 CMAKE_REQUIRED_FLAGS
1179 string of compile command line flags.
1180 CMAKE_REQUIRED_DEFINITIONS
1182 list of macros to define (-DFOO=bar).
1183 CMAKE_REQUIRED_LINK_OPTIONS
1185 New in version 3.14: list of options to pass to link command.
1186 CMAKE_REQUIRED_LIBRARIES
1189 list of libraries to link.
1190 CMAKE_REQUIRED_QUIET
1192 New in version 3.1: execute quietly without messages.
1193 CheckLinkerFlag
1196 New in version 3.18.
1197 Check whether the compiler supports a given link flag.
1200 check_linker_flag
1202 check_linker_flag(<lang> <flag> <var>)
1204 Check that the link <flag> is accepted by the <lang> compiler without a
1206 diagnostic. Stores the result in an internal cache entry named <var>.
1207 This command temporarily sets the CMAKE_REQUIRED_LINK_OPTIONS variable
1209 and calls the check_source_compiles() command from the CheckSourceCom‐
1210 piles module. See that module's documentation for a listing of vari‐
1211 ables that can otherwise modify the build.
1212 The underlying implementation relies on the LINK_OPTIONS property to
1214 check the specified flag. The LINKER: prefix, as described in the tar‐
1215 get_link_options() command, can be used as well.
1216 A positive result from this check indicates only that the compiler did
1218 not issue a diagnostic message when given the link flag. Whether the
1219 flag has any effect or even a specific one is beyond the scope of this
1220 module.
1221 NOTE:
1223 Since the try_compile() command forwards flags from variables like
1224 CMAKE_<LANG>_FLAGS, unknown flags in such variables may cause a
1225 false negative for this check.
1226 CheckOBJCCompilerFlag
1228 New in version 3.16.
1229 Check whether the Objective-C compiler supports a given flag.
1232 check_objc_compiler_flag
1234 check_objc_compiler_flag(<flag> <var>)
1236 Check that the <flag> is accepted by the compiler without a di‐
1238 agnostic. Stores the result in an internal cache entry named
1239 <var>.
1240 This command temporarily sets the CMAKE_REQUIRED_DEFINITIONS variable
1242 and calls the check_objc_source_compiles macro from the CheckOBJC‐
1243 SourceCompiles module. See documentation of that module for a listing
1244 of variables that can otherwise modify the build.
1245 A positive result from this check indicates only that the compiler did
1247 not issue a diagnostic message when given the flag. Whether the flag
1248 has any effect or even a specific one is beyond the scope of this mod‐
1249 ule.
1250 NOTE:
1252 Since the try_compile() command forwards flags from variables like
1253 CMAKE_OBJC_FLAGS, unknown flags in such variables may cause a false
1254 negative for this check.
1255 CheckOBJCSourceCompiles
1257 New in version 3.16.
1258 Check if given Objective-C source compiles and links into an exe‐
1261 cutable.
1262 check_objc_source_compiles
1264 check_objc_source_compiles(<code> <resultVar>
1266 [FAIL_REGEX <regex1> [<regex2>...]])
1267 Check that the source supplied in <code> can be compiled as a
1269 Objectie-C source file and linked as an executable (so it must
1270 contain at least a main() function). The result will be stored
1271 in the internal cache variable specified by <resultVar>, with a
1272 boolean true value for success and boolean false for failure. If
1273 FAIL_REGEX is provided, then failure is determined by checking
1274 if anything in the output matches any of the specified regular
1275 expressions.
1276 The underlying check is performed by the try_compile() command.
1278 The compile and link commands can be influenced by setting any
1279 of the following variables prior to calling
1280 check_objc_source_compiles():
1281 CMAKE_REQUIRED_FLAGS
1283 Additional flags to pass to the compiler. Note that the
1284 contents of CMAKE_OBJC_FLAGS and its associated configu‐
1285 ration-specific variable are automatically added to the
1286 compiler command before the contents of CMAKE_RE‐
1287 QUIRED_FLAGS.
1288 CMAKE_REQUIRED_DEFINITIONS
1290 A ;-list of compiler definitions of the form -DFOO or
1291 -DFOO=bar. A definition for the name specified by <re‐
1292 sultVar> will also be added automatically.
1293 CMAKE_REQUIRED_INCLUDES
1295 A ;-list of header search paths to pass to the compiler.
1296 These will be the only header search paths used by
1297 try_compile(), i.e. the contents of the INCLUDE_DIRECTO‐
1298 RIES directory property will be ignored.
1299 CMAKE_REQUIRED_LINK_OPTIONS
1301 A ;-list of options to add to the link command (see
1302 try_compile() for further details).
1303 CMAKE_REQUIRED_LIBRARIES
1305 A ;-list of libraries to add to the link command. These
1306 can be the name of system libraries or they can be Im‐
1307 ported Targets (see try_compile() for further details).
1308 CMAKE_REQUIRED_QUIET
1310 If this variable evaluates to a boolean true value, all
1311 status messages associated with the check will be sup‐
1312 pressed.
1313 The check is only performed once, with the result cached in the
1315 variable named by <resultVar>. Every subsequent CMake run will
1316 re-use this cached value rather than performing the check again,
1317 even if the <code> changes. In order to force the check to be
1318 re-evaluated, the variable named by <resultVar> must be manually
1319 removed from the cache.
1320 CheckOBJCSourceRuns
1322 New in version 3.16.
1323 Check if given Objective-C source compiles and links into an executable
1326 and can subsequently be run.
1327 check_objc_source_runs
1329 check_objc_source_runs(<code> <resultVar>)
1331 Check that the source supplied in <code> can be compiled as a
1333 Objective-C source file, linked as an executable and then run.
1334 The <code> must contain at least a main() function. If the
1335 <code> could be built and run successfully, the internal cache
1336 variable specified by <resultVar> will be set to 1, otherwise it
1337 will be set to an value that evaluates to boolean false (e.g. an
1338 empty string or an error message).
1339 The underlying check is performed by the try_run() command. The
1341 compile and link commands can be influenced by setting any of
1342 the following variables prior to calling
1343 check_objc_source_runs():
1344 CMAKE_REQUIRED_FLAGS
1346 Additional flags to pass to the compiler. Note that the
1347 contents of CMAKE_OBJC_FLAGS and its associated configu‐
1348 ration-specific variable are automatically added to the
1349 compiler command before the contents of CMAKE_RE‐
1350 QUIRED_FLAGS.
1351 CMAKE_REQUIRED_DEFINITIONS
1353 A ;-list of compiler definitions of the form -DFOO or
1354 -DFOO=bar. A definition for the name specified by <re‐
1355 sultVar> will also be added automatically.
1356 CMAKE_REQUIRED_INCLUDES
1358 A ;-list of header search paths to pass to the compiler.
1359 These will be the only header search paths used by
1360 try_run(), i.e. the contents of the INCLUDE_DIRECTORIES
1361 directory property will be ignored.
1362 CMAKE_REQUIRED_LINK_OPTIONS
1364 A ;-list of options to add to the link command (see
1365 try_run() for further details).
1366 CMAKE_REQUIRED_LIBRARIES
1368 A ;-list of libraries to add to the link command. These
1369 can be the name of system libraries or they can be Im‐
1370 ported Targets (see try_run() for further details).
1371 CMAKE_REQUIRED_QUIET
1373 If this variable evaluates to a boolean true value, all
1374 status messages associated with the check will be sup‐
1375 pressed.
1376 The check is only performed once, with the result cached in the
1378 variable named by <resultVar>. Every subsequent CMake run will
1379 re-use this cached value rather than performing the check again,
1380 even if the <code> changes. In order to force the check to be
1381 re-evaluated, the variable named by <resultVar> must be manually
1382 removed from the cache.
1383 CheckOBJCXXCompilerFlag
1385 New in version 3.16.
1386 Check whether the Objective-C++ compiler supports a given flag.
1389 check_objcxx_compiler_flag
1391 check_objcxx_compiler_flag(<flag> <var>)
1393 Check that the <flag> is accepted by the compiler without a di‐
1395 agnostic. Stores the result in an internal cache entry named
1396 <var>.
1397 This command temporarily sets the CMAKE_REQUIRED_DEFINITIONS variable
1399 and calls the check_objcxx_source_compiles macro from the CheckOB‐
1400 JCXXSourceCompiles module. See documentation of that module for a
1401 listing of variables that can otherwise modify the build.
1402 A positive result from this check indicates only that the compiler did
1404 not issue a diagnostic message when given the flag. Whether the flag
1405 has any effect or even a specific one is beyond the scope of this mod‐
1406 ule.
1407 NOTE:
1409 Since the try_compile() command forwards flags from variables like
1410 CMAKE_OBJCXX_FLAGS, unknown flags in such variables may cause a
1411 false negative for this check.
1412 CheckOBJCXXSourceCompiles
1414 New in version 3.16.
1415 Check if given Objective-C++ source compiles and links into an exe‐
1418 cutable.
1419 check_objcxx_source_compiles
1421 check_objcxx_source_compiles(<code> <resultVar>
1423 [FAIL_REGEX <regex1> [<regex2>...]])
1424 Check that the source supplied in <code> can be compiled as a
1426 Objective-C++ source file and linked as an executable (so it
1427 must contain at least a main() function). The result will be
1428 stored in the internal cache variable specified by <resultVar>,
1429 with a boolean true value for success and boolean false for
1430 failure. If FAIL_REGEX is provided, then failure is determined
1431 by checking if anything in the output matches any of the speci‐
1432 fied regular expressions.
1433 The underlying check is performed by the try_compile() command.
1435 The compile and link commands can be influenced by setting any
1436 of the following variables prior to calling check_ob‐
1437 jcxx_source_compiles():
1438 CMAKE_REQUIRED_FLAGS
1440 Additional flags to pass to the compiler. Note that the
1441 contents of CMAKE_OBJCXX_FLAGS and its associated config‐
1442 uration-specific variable are automatically added to the
1443 compiler command before the contents of CMAKE_RE‐
1444 QUIRED_FLAGS.
1445 CMAKE_REQUIRED_DEFINITIONS
1447 A ;-list of compiler definitions of the form -DFOO or
1448 -DFOO=bar. A definition for the name specified by <re‐
1449 sultVar> will also be added automatically.
1450 CMAKE_REQUIRED_INCLUDES
1452 A ;-list of header search paths to pass to the compiler.
1453 These will be the only header search paths used by
1454 try_compile(), i.e. the contents of the INCLUDE_DIRECTO‐
1455 RIES directory property will be ignored.
1456 CMAKE_REQUIRED_LINK_OPTIONS
1458 A ;-list of options to add to the link command (see
1459 try_compile() for further details).
1460 CMAKE_REQUIRED_LIBRARIES
1462 A ;-list of libraries to add to the link command. These
1463 can be the name of system libraries or they can be Im‐
1464 ported Targets (see try_compile() for further details).
1465 CMAKE_REQUIRED_QUIET
1467 If this variable evaluates to a boolean true value, all
1468 status messages associated with the check will be sup‐
1469 pressed.
1470 The check is only performed once, with the result cached in the
1472 variable named by <resultVar>. Every subsequent CMake run will
1473 re-use this cached value rather than performing the check again,
1474 even if the <code> changes. In order to force the check to be
1475 re-evaluated, the variable named by <resultVar> must be manually
1476 removed from the cache.
1477 CheckOBJCXXSourceRuns
1479 New in version 3.16.
1480 Check if given Objective-C++ source compiles and links into an exe‐
1483 cutable and can subsequently be run.
1484 check_objcxx_source_runs
1486 check_objcxx_source_runs(<code> <resultVar>)
1488 Check that the source supplied in <code> can be compiled as a
1490 Objective-C++ source file, linked as an executable and then run.
1491 The <code> must contain at least a main() function. If the
1492 <code> could be built and run successfully, the internal cache
1493 variable specified by <resultVar> will be set to 1, otherwise it
1494 will be set to an value that evaluates to boolean false (e.g. an
1495 empty string or an error message).
1496 The underlying check is performed by the try_run() command. The
1498 compile and link commands can be influenced by setting any of
1499 the following variables prior to calling check_ob‐
1500 jcxx_source_runs():
1501 CMAKE_REQUIRED_FLAGS
1503 Additional flags to pass to the compiler. Note that the
1504 contents of CMAKE_OBJCXX_FLAGS and its associated config‐
1505 uration-specific variable are automatically added to the
1506 compiler command before the contents of CMAKE_RE‐
1507 QUIRED_FLAGS.
1508 CMAKE_REQUIRED_DEFINITIONS
1510 A ;-list of compiler definitions of the form -DFOO or
1511 -DFOO=bar. A definition for the name specified by <re‐
1512 sultVar> will also be added automatically.
1513 CMAKE_REQUIRED_INCLUDES
1515 A ;-list of header search paths to pass to the compiler.
1516 These will be the only header search paths used by
1517 try_run(), i.e. the contents of the INCLUDE_DIRECTORIES
1518 directory property will be ignored.
1519 CMAKE_REQUIRED_LINK_OPTIONS
1521 A ;-list of options to add to the link command (see
1522 try_run() for further details).
1523 CMAKE_REQUIRED_LIBRARIES
1525 A ;-list of libraries to add to the link command. These
1526 can be the name of system libraries or they can be Im‐
1527 ported Targets (see try_run() for further details).
1528 CMAKE_REQUIRED_QUIET
1530 If this variable evaluates to a boolean true value, all
1531 status messages associated with the check will be sup‐
1532 pressed.
1533 The check is only performed once, with the result cached in the
1535 variable named by <resultVar>. Every subsequent CMake run will
1536 re-use this cached value rather than performing the check again,
1537 even if the <code> changes. In order to force the check to be
1538 re-evaluated, the variable named by <resultVar> must be manually
1539 removed from the cache.
1540 CheckPIESupported
1542 New in version 3.14.
1543 Check whether the linker supports Position Independent Code (PIE) or No
1546 Position Independent Code (NO_PIE) for executables. Use this to ensure
1547 that the POSITION_INDEPENDENT_CODE target property for executables will
1548 be honored at link time.
1549 check_pie_supported
1551 check_pie_supported([OUTPUT_VARIABLE <output>]
1553 [LANGUAGES <lang>...])
1554 Options are:
1556 OUTPUT_VARIABLE <output>
1558 Set <output> variable with details about any error.
1559 LANGUAGES <lang>...
1561 Check the linkers used for each of the specified lan‐
1562 guages. Supported languages are C, CXX, and Fortran.
1563 It makes no sense to use this module when CMP0083 is set to OLD, so the
1565 command will return an error in this case. See policy CMP0083 for de‐
1566 tails.
1567 Variables
1569 For each language checked, two boolean cache variables are defined.
1570 CMAKE_<lang>_LINK_PIE_SUPPORTED
1572 Set to YES if PIE is supported by the linker and NO other‐
1573 wise.
1574 CMAKE_<lang>_LINK_NO_PIE_SUPPORTED
1576 Set to YES if NO_PIE is supported by the linker and NO other‐
1577 wise.
1578 Examples
1580 check_pie_supported()
1581 set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE)
1582 # Retrieve any error message.
1584 check_pie_supported(OUTPUT_VARIABLE output LANGUAGES C)
1585 set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE)
1586 if(NOT CMAKE_C_LINK_PIE_SUPPORTED)
1587 message(WARNING "PIE is not supported at link time: ${output}.\n"
1588 "PIE link options will not be passed to linker.")
1589 endif()
1590 CheckPrototypeDefinition
1592 Check if the prototype we expect is correct.
1593 check_prototype_definition
1595 check_prototype_definition(FUNCTION PROTOTYPE RETURN HEADER VARIABLE)
1597 FUNCTION - The name of the function (used to check if prototype exists)
1599 PROTOTYPE- The prototype to check.
1600 RETURN - The return value of the function.
1601 HEADER - The header files required.
1602 VARIABLE - The variable to store the result.
1603 Will be created as an internal cache variable.
1604 Example:
1606 check_prototype_definition(getpwent_r
1608 "struct passwd *getpwent_r(struct passwd *src, char *buf, int buflen)"
1609 "NULL"
1610 "unistd.h;pwd.h"
1611 SOLARIS_GETPWENT_R)
1612 The following variables may be set before calling this function to mod‐
1614 ify the way the check is run:
1615 CMAKE_REQUIRED_FLAGS
1617 string of compile command line flags.
1618 CMAKE_REQUIRED_DEFINITIONS
1620 list of macros to define (-DFOO=bar).
1621 CMAKE_REQUIRED_INCLUDES
1623 list of include directories.
1624 CMAKE_REQUIRED_LINK_OPTIONS
1626 New in version 3.14: list of options to pass to link command.
1627 CMAKE_REQUIRED_LIBRARIES
1630 list of libraries to link.
1631 CMAKE_REQUIRED_QUIET
1633 New in version 3.1: execute quietly without messages.
1634 CheckSourceCompiles
1637 New in version 3.19.
1638 Check if given source compiles and links into an executable.
1641 check_source_compiles
1643 check_source_compiles(<lang> <code> <resultVar>
1645 [FAIL_REGEX <regex1> [<regex2>...]]
1646 [SRC_EXT <extension>])
1647 Check that the source supplied in <code> can be compiled as a
1649 source file for the requested language and linked as an exe‐
1650 cutable (so it must contain at least a main() function). The re‐
1651 sult will be stored in the internal cache variable specified by
1652 <resultVar>, with a boolean true value for success and boolean
1653 false for failure. If FAIL_REGEX is provided, then failure is
1654 determined by checking if anything in the output matches any of
1655 the specified regular expressions.
1656 By default, the test source file will be given a file extension
1658 that matches the requested language. The SRC_EXT option can be
1659 used to override this with .<extension> instead.
1660 The underlying check is performed by the try_compile() command.
1662 The compile and link commands can be influenced by setting any
1663 of the following variables prior to calling check_source_com‐
1664 piles():
1665 CMAKE_REQUIRED_FLAGS
1667 Additional flags to pass to the compiler. Note that the
1668 contents of CMAKE_<LANG>_FLAGS and its associated config‐
1669 uration-specific variable are automatically added to the
1670 compiler command before the contents of CMAKE_RE‐
1671 QUIRED_FLAGS.
1672 CMAKE_REQUIRED_DEFINITIONS
1674 A ;-list of compiler definitions of the form -DFOO or
1675 -DFOO=bar. A definition for the name specified by <re‐
1676 sultVar> will also be added automatically.
1677 CMAKE_REQUIRED_INCLUDES
1679 A ;-list of header search paths to pass to the compiler.
1680 These will be the only header search paths used by
1681 try_compile(), i.e. the contents of the INCLUDE_DIRECTO‐
1682 RIES directory property will be ignored.
1683 CMAKE_REQUIRED_LINK_OPTIONS
1685 A ;-list of options to add to the link command (see
1686 try_compile() for further details).
1687 CMAKE_REQUIRED_LIBRARIES
1689 A ;-list of libraries to add to the link command. These
1690 can be the name of system libraries or they can be Im‐
1691 ported Targets (see try_compile() for further details).
1692 CMAKE_REQUIRED_QUIET
1694 If this variable evaluates to a boolean true value, all
1695 status messages associated with the check will be sup‐
1696 pressed.
1697 The check is only performed once, with the result cached in the
1699 variable named by <resultVar>. Every subsequent CMake run will
1700 re-use this cached value rather than performing the check again,
1701 even if the <code> changes. In order to force the check to be
1702 re-evaluated, the variable named by <resultVar> must be manually
1703 removed from the cache.
1704 CheckSourceRuns
1706 New in version 3.19.
1707 Check if given source compiles and links into an executable and can
1710 subsequently be run.
1711 check_source_runs
1713 check_source_runs(<lang> <code> <resultVar>
1715 [SRC_EXT <extension>])
1716 Check that the source supplied in <code> can be compiled as a
1718 source file for the requested language, linked as an executable
1719 and then run. The <code> must contain at least a main() func‐
1720 tion. If the <code> could be built and run successfully, the in‐
1721 ternal cache variable specified by <resultVar> will be set to 1,
1722 otherwise it will be set to an value that evaluates to boolean
1723 false (e.g. an empty string or an error message).
1724 By default, the test source file will be given a file extension
1726 that matches the requested language. The SRC_EXT option can be
1727 used to override this with .<extension> instead.
1728 The underlying check is performed by the try_run() command. The
1730 compile and link commands can be influenced by setting any of
1731 the following variables prior to calling
1732 check_objc_source_runs():
1733 CMAKE_REQUIRED_FLAGS
1735 Additional flags to pass to the compiler. Note that the
1736 contents of CMAKE_OBJC_FLAGS and its associated configu‐
1737 ration-specific variable are automatically added to the
1738 compiler command before the contents of CMAKE_RE‐
1739 QUIRED_FLAGS.
1740 CMAKE_REQUIRED_DEFINITIONS
1742 A ;-list of compiler definitions of the form -DFOO or
1743 -DFOO=bar. A definition for the name specified by <re‐
1744 sultVar> will also be added automatically.
1745 CMAKE_REQUIRED_INCLUDES
1747 A ;-list of header search paths to pass to the compiler.
1748 These will be the only header search paths used by
1749 try_run(), i.e. the contents of the INCLUDE_DIRECTORIES
1750 directory property will be ignored.
1751 CMAKE_REQUIRED_LINK_OPTIONS
1753 A ;-list of options to add to the link command (see
1754 try_run() for further details).
1755 CMAKE_REQUIRED_LIBRARIES
1757 A ;-list of libraries to add to the link command. These
1758 can be the name of system libraries or they can be Im‐
1759 ported Targets (see try_run() for further details).
1760 CMAKE_REQUIRED_QUIET
1762 If this variable evaluates to a boolean true value, all
1763 status messages associated with the check will be sup‐
1764 pressed.
1765 The check is only performed once, with the result cached in the
1767 variable named by <resultVar>. Every subsequent CMake run will
1768 re-use this cached value rather than performing the check again,
1769 even if the <code> changes. In order to force the check to be
1770 re-evaluated, the variable named by <resultVar> must be manually
1771 removed from the cache.
1772 CheckStructHasMember
1774 Check if the given struct or class has the specified member variable
1775 CHECK_STRUCT_HAS_MEMBER
1777 CHECK_STRUCT_HAS_MEMBER(<struct> <member> <header> <variable>
1779 [LANGUAGE <language>])
1780 <struct> - the name of the struct or class you are interested in
1782 <member> - the member which existence you want to check
1783 <header> - the header(s) where the prototype should be declared
1784 <variable> - variable to store the result
1785 <language> - the compiler to use (C or CXX)
1786 The following variables may be set before calling this macro to modify
1788 the way the check is run:
1789 CMAKE_REQUIRED_FLAGS
1791 string of compile command line flags.
1792 CMAKE_REQUIRED_DEFINITIONS
1794 list of macros to define (-DFOO=bar).
1795 CMAKE_REQUIRED_INCLUDES
1797 list of include directories.
1798 CMAKE_REQUIRED_LINK_OPTIONS
1800 New in version 3.14: list of options to pass to link command.
1801 CMAKE_REQUIRED_LIBRARIES
1804 list of libraries to link.
1805 CMAKE_REQUIRED_QUIET
1807 New in version 3.1: execute quietly without messages.
1808 Example:
1811 CHECK_STRUCT_HAS_MEMBER("struct timeval" tv_sec sys/select.h
1813 HAVE_TIMEVAL_TV_SEC LANGUAGE C)
1814 CheckSymbolExists
1816 Provides a macro to check if a symbol exists as a function, variable,
1817 or macro in C.
1818 check_symbol_exists
1820 check_symbol_exists(<symbol> <files> <variable>)
1822 Check that the <symbol> is available after including given
1824 header <files> and store the result in a <variable>. Specify
1825 the list of files in one argument as a semicolon-separated list.
1826 <variable> will be created as an internal cache variable.
1827 If the header files define the symbol as a macro it is considered
1829 available and assumed to work. If the header files declare the symbol
1830 as a function or variable then the symbol must also be available for
1831 linking (so intrinsics may not be detected). If the symbol is a type,
1832 enum value, or intrinsic it will not be recognized (consider using
1833 CheckTypeSize or CheckCSourceCompiles). If the check needs to be done
1834 in C++, consider using CheckCXXSymbolExists instead.
1835 The following variables may be set before calling this macro to modify
1837 the way the check is run:
1838 CMAKE_REQUIRED_FLAGS
1840 string of compile command line flags.
1841 CMAKE_REQUIRED_DEFINITIONS
1843 a ;-list of macros to define (-DFOO=bar).
1844 CMAKE_REQUIRED_INCLUDES
1846 a ;-list of header search paths to pass to the compiler.
1847 CMAKE_REQUIRED_LINK_OPTIONS
1849 New in version 3.14: a ;-list of options to add to the link com‐
1850 mand.
1851 CMAKE_REQUIRED_LIBRARIES
1854 a ;-list of libraries to add to the link command. See policy
1855 CMP0075.
1856 CMAKE_REQUIRED_QUIET
1858 New in version 3.1: execute quietly without messages.
1859 For example:
1862 include(CheckSymbolExists)
1864 # Check for macro SEEK_SET
1866 check_symbol_exists(SEEK_SET "stdio.h" HAVE_SEEK_SET)
1867 # Check for function fopen
1868 check_symbol_exists(fopen "stdio.h" HAVE_FOPEN)
1869 CheckTypeSize
1871 Check sizeof a type
1872 CHECK_TYPE_SIZE
1874 CHECK_TYPE_SIZE(TYPE VARIABLE [BUILTIN_TYPES_ONLY]
1876 [LANGUAGE <language>])
1877 Check if the type exists and determine its size. On return,
1879 HAVE_${VARIABLE} holds the existence of the type, and ${VARI‐
1880 ABLE} holds one of the following:
1881 <size> = type has non-zero size <size>
1883 "0" = type has arch-dependent size (see below)
1884 "" = type does not exist
1885 Both HAVE_${VARIABLE} and ${VARIABLE} will be created as inter‐
1887 nal cache variables.
1888 Furthermore, the variable ${VARIABLE}_CODE holds C preprocessor
1890 code to define the macro ${VARIABLE} to the size of the type, or
1891 leave the macro undefined if the type does not exist.
1892 The variable ${VARIABLE} may be 0 when CMAKE_OSX_ARCHITECTURES
1894 has multiple architectures for building OS X universal binaries.
1895 This indicates that the type size varies across architectures.
1896 In this case ${VARIABLE}_CODE contains C preprocessor tests map‐
1897 ping from each architecture macro to the corresponding type
1898 size. The list of architecture macros is stored in ${VARI‐
1899 ABLE}_KEYS, and the value for each key is stored in ${VARI‐
1900 ABLE}-${KEY}.
1901 If the BUILTIN_TYPES_ONLY option is not given, the macro checks
1903 for headers <sys/types.h>, <stdint.h>, and <stddef.h>, and saves
1904 results in HAVE_SYS_TYPES_H, HAVE_STDINT_H, and HAVE_STDDEF_H.
1905 The type size check automatically includes the available head‐
1906 ers, thus supporting checks of types defined in the headers.
1907 If LANGUAGE is set, the specified compiler will be used to per‐
1909 form the check. Acceptable values are C and CXX.
1910 Despite the name of the macro you may use it to check the size of more
1912 complex expressions, too. To check e.g. for the size of a struct mem‐
1913 ber you can do something like this:
1914 check_type_size("((struct something*)0)->member" SIZEOF_MEMBER)
1916 The following variables may be set before calling this macro to modify
1918 the way the check is run:
1919 CMAKE_REQUIRED_FLAGS
1921 string of compile command line flags.
1922 CMAKE_REQUIRED_DEFINITIONS
1924 list of macros to define (-DFOO=bar).
1925 CMAKE_REQUIRED_INCLUDES
1927 list of include directories.
1928 CMAKE_REQUIRED_LINK_OPTIONS
1930 New in version 3.14: list of options to pass to link command.
1931 CMAKE_REQUIRED_LIBRARIES
1934 list of libraries to link.
1935 CMAKE_REQUIRED_QUIET
1937 New in version 3.1: execute quietly without messages.
1938 CMAKE_EXTRA_INCLUDE_FILES
1941 list of extra headers to include.
1942 CheckVariableExists
1944 Check if the variable exists.
1945 CHECK_VARIABLE_EXISTS
1947 CHECK_VARIABLE_EXISTS(VAR VARIABLE)
1949 VAR - the name of the variable
1951 VARIABLE - variable to store the result
1952 Will be created as an internal cache variable.
1953 This macro is only for C variables.
1955 The following variables may be set before calling this macro to modify
1957 the way the check is run:
1958 CMAKE_REQUIRED_FLAGS
1960 string of compile command line flags.
1961 CMAKE_REQUIRED_DEFINITIONS
1963 list of macros to define (-DFOO=bar).
1964 CMAKE_REQUIRED_LINK_OPTIONS
1966 New in version 3.14: list of options to pass to link command.
1967 CMAKE_REQUIRED_LIBRARIES
1970 list of libraries to link.
1971 CMAKE_REQUIRED_QUIET
1973 New in version 3.1: execute quietly without messages.
1974 CMakeAddFortranSubdirectory
1977 Add a fortran-only subdirectory, find a fortran compiler, and build.
1978 The cmake_add_fortran_subdirectory function adds a subdirectory to a
1980 project that contains a fortran-only subproject. The module will check
1981 the current compiler and see if it can support fortran. If no fortran
1982 compiler is found and the compiler is MSVC, then this module will find
1983 the MinGW gfortran. It will then use an external project to build with
1984 the MinGW tools. It will also create imported targets for the li‐
1985 braries created. This will only work if the fortran code is built into
1986 a dll, so BUILD_SHARED_LIBS is turned on in the project. In addition
1987 the CMAKE_GNUtoMS option is set to on, so that Microsoft .lib files are
1988 created. Usage is as follows:
1989 cmake_add_fortran_subdirectory(
1991 <subdir> # name of subdirectory
1992 PROJECT <project_name> # project name in subdir top CMakeLists.txt
1993 ARCHIVE_DIR <dir> # dir where project places .lib files
1994 RUNTIME_DIR <dir> # dir where project places .dll files
1995 LIBRARIES <lib>... # names of library targets to import
1996 LINK_LIBRARIES # link interface libraries for LIBRARIES
1997 [LINK_LIBS <lib> <dep>...]...
1998 CMAKE_COMMAND_LINE ... # extra command line flags to pass to cmake
1999 NO_EXTERNAL_INSTALL # skip installation of external project
2000 )
2001 Relative paths in ARCHIVE_DIR and RUNTIME_DIR are interpreted with re‐
2003 spect to the build directory corresponding to the source directory in
2004 which the function is invoked.
2005 Limitations:
2007 NO_EXTERNAL_INSTALL is required for forward compatibility with a future
2009 version that supports installation of the external project binaries
2010 during make install.
2011 CMakeBackwardCompatibilityCXX
2013 define a bunch of backwards compatibility variables
2014 CMAKE_ANSI_CXXFLAGS - flag for ansi c++
2016 CMAKE_HAS_ANSI_STRING_STREAM - has <strstream>
2017 include(TestForANSIStreamHeaders)
2018 include(CheckIncludeFileCXX)
2019 include(TestForSTDNamespace)
2020 include(TestForANSIForScope)
2021 CMakeDependentOption
2023 Macro to provide an option dependent on other options.
2024 This macro presents an option to the user only if a set of other condi‐
2026 tions are true.
2027 Usage:
2029 cmake_dependent_option(<option> "<help_text>" <value> <depends> <force>)
2031 Where <option> is available to the user if <depends> is true. When <op‐
2033 tion> is available, the given <help_text> and initial <value> are used.
2034 If the <depends> condition is not true, <option> will not be presented
2035 and will always have the value given by <force>. Any value set by the
2036 user is preserved for when the option is presented again. Each element
2037 in the fourth parameter is evaluated as an if-condition, so Condition
2038 Syntax can be used.
2039 Example invocation:
2041 cmake_dependent_option(USE_FOO "Use Foo" ON
2043 "USE_BAR;NOT USE_ZOT" OFF)
2044 If USE_BAR is true and USE_ZOT is false, this provides an option called
2046 USE_FOO that defaults to ON. Otherwise, it sets USE_FOO to OFF and
2047 hides the option from the user. If the status of USE_BAR or USE_ZOT
2048 ever changes, any value for the USE_FOO option is saved so that when
2049 the option is re-enabled it retains its old value.
2050 CMakeFindDependencyMacro
2052 find_dependency
2053 The find_dependency() macro wraps a find_package() call for a
2054 package dependency:
2055 find_dependency(<dep> [...])
2057 It is designed to be used in a Package Configuration File
2059 (<PackageName>Config.cmake). find_dependency forwards the cor‐
2060 rect parameters for QUIET and REQUIRED which were passed to the
2061 original find_package() call. Any additional arguments speci‐
2062 fied are forwarded to find_package().
2063 If the dependency could not be found it sets an informative di‐
2065 agnostic message and calls return() to end processing of the
2066 calling package configuration file and return to the find_pack‐
2067 age() command that loaded it.
2068 NOTE:
2070 The call to return() makes this macro unsuitable to call from
2071 Find Modules.
2072 CMakeFindFrameworks
2074 helper module to find OSX frameworks
2075 This module reads hints about search locations from variables:
2077 CMAKE_FIND_FRAMEWORK_EXTRA_LOCATIONS - Extra directories
2079 CMakeFindPackageMode
2081 This file is executed by cmake when invoked with --find-package. It
2082 expects that the following variables are set using -D:
2083 NAME name of the package
2085 COMPILER_ID
2087 the CMake compiler ID for which the result is, i.e. GNU/In‐
2088 tel/Clang/MSVC, etc.
2089 LANGUAGE
2091 language for which the result will be used, i.e. C/CXX/For‐
2092 tran/ASM
2093 MODE
2095 EXIST only check for existence of the given package
2097 COMPILE
2099 print the flags needed for compiling an object file which
2100 uses the given package
2101 LINK print the flags needed for linking when using the given
2103 package
2104 QUIET if TRUE, don't print anything
2106 CMakeGraphVizOptions
2108 The builtin Graphviz support of CMake.
2109 Generating Graphviz files
2111 CMake can generate Graphviz files showing the dependencies between the
2112 targets in a project, as well as external libraries which are linked
2113 against.
2114 When running CMake with the --graphviz=foo.dot option, it produces:
2116 • a foo.dot file, showing all dependencies in the project
2118 • a foo.dot.<target> file for each target, showing on which other tar‐
2120 gets it depends
2121 • a foo.dot.<target>.dependers file for each target, showing which
2123 other targets depend on it
2124 Those .dot files can be converted to images using the dot command from
2126 the Graphviz package:
2127 dot -Tpng -o foo.png foo.dot
2129 New in version 3.10: The different dependency types PUBLIC, INTERFACE
2131 and PRIVATE are represented as solid, dashed and dotted edges.
2132 Variables specific to the Graphviz support
2135 The resulting graphs can be huge. The look and content of the gener‐
2136 ated graphs can be controlled using the file CMakeGraphVizOp‐
2137 tions.cmake. This file is first searched in CMAKE_BINARY_DIR, and then
2138 in CMAKE_SOURCE_DIR. If found, the variables set in it are used to ad‐
2139 just options for the generated Graphviz files.
2140 GRAPHVIZ_GRAPH_NAME
2142 The graph name.
2143 • Mandatory: NO
2145 • Default: value of CMAKE_PROJECT_NAME
2147 GRAPHVIZ_GRAPH_HEADER
2149 The header written at the top of the Graphviz files.
2150 • Mandatory: NO
2152 • Default: "node [ fontsize = "12" ];"
2154 GRAPHVIZ_NODE_PREFIX
2156 The prefix for each node in the Graphviz files.
2157 • Mandatory: NO
2159 • Default: "node"
2161 GRAPHVIZ_EXECUTABLES
2163 Set to FALSE to exclude executables from the generated graphs.
2164 • Mandatory: NO
2166 • Default: TRUE
2168 GRAPHVIZ_STATIC_LIBS
2170 Set to FALSE to exclude static libraries from the generated
2171 graphs.
2172 • Mandatory: NO
2174 • Default: TRUE
2176 GRAPHVIZ_SHARED_LIBS
2178 Set to FALSE to exclude shared libraries from the generated
2179 graphs.
2180 • Mandatory: NO
2182 • Default: TRUE
2184 GRAPHVIZ_MODULE_LIBS
2186 Set to FALSE to exclude module libraries from the generated
2187 graphs.
2188 • Mandatory: NO
2190 • Default: TRUE
2192 GRAPHVIZ_INTERFACE_LIBS
2194 Set to FALSE to exclude interface libraries from the generated
2195 graphs.
2196 • Mandatory: NO
2198 • Default: TRUE
2200 GRAPHVIZ_OBJECT_LIBS
2202 Set to FALSE to exclude object libraries from the generated
2203 graphs.
2204 • Mandatory: NO
2206 • Default: TRUE
2208 GRAPHVIZ_UNKNOWN_LIBS
2210 Set to FALSE to exclude unknown libraries from the generated
2211 graphs.
2212 • Mandatory: NO
2214 • Default: TRUE
2216 GRAPHVIZ_EXTERNAL_LIBS
2218 Set to FALSE to exclude external libraries from the generated
2219 graphs.
2220 • Mandatory: NO
2222 • Default: TRUE
2224 GRAPHVIZ_CUSTOM_TARGETS
2226 Set to TRUE to include custom targets in the generated graphs.
2227 • Mandatory: NO
2229 • Default: FALSE
2231 GRAPHVIZ_IGNORE_TARGETS
2233 A list of regular expressions for names of targets to exclude
2234 from the generated graphs.
2235 • Mandatory: NO
2237 • Default: empty
2239 GRAPHVIZ_GENERATE_PER_TARGET
2241 Set to FALSE to not generate per-target graphs foo.dot.<target>.
2242 • Mandatory: NO
2244 • Default: TRUE
2246 GRAPHVIZ_GENERATE_DEPENDERS
2248 Set to FALSE to not generate depender graphs foo.dot.<tar‐
2249 get>.dependers.
2250 • Mandatory: NO
2252 • Default: TRUE
2254 CMakePackageConfigHelpers
2256 Helpers functions for creating config files that can be included by
2257 other projects to find and use a package.
2258 Adds the configure_package_config_file() and
2260 write_basic_package_version_file() commands.
2261 Generating a Package Configuration File
2263 configure_package_config_file
2264 Create a config file for a project:
2265 configure_package_config_file(<input> <output>
2267 INSTALL_DESTINATION <path>
2268 [PATH_VARS <var1> <var2> ... <varN>]
2269 [NO_SET_AND_CHECK_MACRO]
2270 [NO_CHECK_REQUIRED_COMPONENTS_MACRO]
2271 [INSTALL_PREFIX <path>]
2272 )
2273 configure_package_config_file() should be used instead of the plain
2275 configure_file() command when creating the <PackageName>Config.cmake or
2276 <PackageName>-config.cmake file for installing a project or library.
2277 It helps making the resulting package relocatable by avoiding hardcoded
2278 paths in the installed Config.cmake file.
2279 In a FooConfig.cmake file there may be code like this to make the in‐
2281 stall destinations know to the using project:
2282 set(FOO_INCLUDE_DIR "@CMAKE_INSTALL_FULL_INCLUDEDIR@" )
2284 set(FOO_DATA_DIR "@CMAKE_INSTALL_PREFIX@/@RELATIVE_DATA_INSTALL_DIR@" )
2285 set(FOO_ICONS_DIR "@CMAKE_INSTALL_PREFIX@/share/icons" )
2286 #...logic to determine installedPrefix from the own location...
2287 set(FOO_CONFIG_DIR "${installedPrefix}/@CONFIG_INSTALL_DIR@" )
2288 All 4 options shown above are not sufficient, since the first 3 hard‐
2290 code the absolute directory locations, and the 4th case works only if
2291 the logic to determine the installedPrefix is correct, and if CON‐
2292 FIG_INSTALL_DIR contains a relative path, which in general cannot be
2293 guaranteed. This has the effect that the resulting FooConfig.cmake
2294 file would work poorly under Windows and OSX, where users are used to
2295 choose the install location of a binary package at install time, inde‐
2296 pendent from how CMAKE_INSTALL_PREFIX was set at build/cmake time.
2297 Using configure_package_config_file helps. If used correctly, it makes
2299 the resulting FooConfig.cmake file relocatable. Usage:
2300 1. write a FooConfig.cmake.in file as you are used to
2302 2. insert a line containing only the string @PACKAGE_INIT@
2304 3. instead of set(FOO_DIR "@SOME_INSTALL_DIR@"), use set(FOO_DIR
2306 "@PACKAGE_SOME_INSTALL_DIR@") (this must be after the @PACKAGE_INIT@
2307 line)
2308 4. instead of using the normal configure_file(), use configure_pack‐
2310 age_config_file()
2311 The <input> and <output> arguments are the input and output file, the
2313 same way as in configure_file().
2314 The <path> given to INSTALL_DESTINATION must be the destination where
2316 the FooConfig.cmake file will be installed to. This path can either be
2317 absolute, or relative to the INSTALL_PREFIX path.
2318 The variables <var1> to <varN> given as PATH_VARS are the variables
2320 which contain install destinations. For each of them the macro will
2321 create a helper variable PACKAGE_<var...>. These helper variables must
2322 be used in the FooConfig.cmake.in file for setting the installed loca‐
2323 tion. They are calculated by configure_package_config_file so that
2324 they are always relative to the installed location of the package.
2325 This works both for relative and also for absolute locations. For ab‐
2326 solute locations it works only if the absolute location is a subdirec‐
2327 tory of INSTALL_PREFIX.
2328 New in version 3.1: If the INSTALL_PREFIX argument is passed, this is
2330 used as base path to calculate all the relative paths. The <path> ar‐
2331 gument must be an absolute path. If this argument is not passed, the
2332 CMAKE_INSTALL_PREFIX variable will be used instead. The default value
2333 is good when generating a FooConfig.cmake file to use your package from
2334 the install tree. When generating a FooConfig.cmake file to use your
2335 package from the build tree this option should be used.
2336 By default configure_package_config_file also generates two helper
2339 macros, set_and_check() and check_required_components() into the
2340 FooConfig.cmake file.
2341 set_and_check() should be used instead of the normal set() command for
2343 setting directories and file locations. Additionally to setting the
2344 variable it also checks that the referenced file or directory actually
2345 exists and fails with a FATAL_ERROR otherwise. This makes sure that
2346 the created FooConfig.cmake file does not contain wrong references.
2347 When using the NO_SET_AND_CHECK_MACRO, this macro is not generated into
2348 the FooConfig.cmake file.
2349 check_required_components(<PackageName>) should be called at the end of
2351 the FooConfig.cmake file. This macro checks whether all requested,
2352 non-optional components have been found, and if this is not the case,
2353 sets the Foo_FOUND variable to FALSE, so that the package is considered
2354 to be not found. It does that by testing the Foo_<Component>_FOUND
2355 variables for all requested required components. This macro should be
2356 called even if the package doesn't provide any components to make sure
2357 users are not specifying components erroneously. When using the
2358 NO_CHECK_REQUIRED_COMPONENTS_MACRO option, this macro is not generated
2359 into the FooConfig.cmake file.
2360 For an example see below the documentation for
2362 write_basic_package_version_file().
2363 Generating a Package Version File
2365 write_basic_package_version_file
2366 Create a version file for a project:
2367 write_basic_package_version_file(<filename>
2369 [VERSION <major.minor.patch>]
2370 COMPATIBILITY <AnyNewerVersion|SameMajorVersion|SameMinorVersion|ExactVersion>
2371 [ARCH_INDEPENDENT] )
2372 Writes a file for use as <PackageName>ConfigVersion.cmake file to
2374 <filename>. See the documentation of find_package() for details on
2375 this.
2376 <filename> is the output filename, it should be in the build tree.
2378 <major.minor.patch> is the version number of the project to be in‐
2379 stalled.
2380 If no VERSION is given, the PROJECT_VERSION variable is used. If this
2382 hasn't been set, it errors out.
2383 The COMPATIBILITY mode AnyNewerVersion means that the installed package
2385 version will be considered compatible if it is newer or exactly the
2386 same as the requested version. This mode should be used for packages
2387 which are fully backward compatible, also across major versions. If
2388 SameMajorVersion is used instead, then the behaviour differs from
2389 AnyNewerVersion in that the major version number must be the same as
2390 requested, e.g. version 2.0 will not be considered compatible if 1.0
2391 is requested. This mode should be used for packages which guarantee
2392 backward compatibility within the same major version. If SameMinorVer‐
2393 sion is used, the behaviour is the same as SameMajorVersion, but both
2394 major and minor version must be the same as requested, e.g version 0.2
2395 will not be compatible if 0.1 is requested. If ExactVersion is used,
2396 then the package is only considered compatible if the requested version
2397 matches exactly its own version number (not considering the tweak ver‐
2398 sion). For example, version 1.2.3 of a package is only considered com‐
2399 patible to requested version 1.2.3. This mode is for packages without
2400 compatibility guarantees. If your project has more elaborated version
2401 matching rules, you will need to write your own custom ConfigVer‐
2402 sion.cmake file instead of using this macro.
2403 New in version 3.11: The SameMinorVersion compatibility mode.
2405 New in version 3.14: If ARCH_INDEPENDENT is given, the installed pack‐
2408 age version will be considered compatible even if it was built for a
2409 different architecture than the requested architecture. Otherwise, an
2410 architecture check will be performed, and the package will be consid‐
2411 ered compatible only if the architecture matches exactly. For example,
2412 if the package is built for a 32-bit architecture, the package is only
2413 considered compatible if it is used on a 32-bit architecture, unless
2414 ARCH_INDEPENDENT is given, in which case the package is considered com‐
2415 patible on any architecture.
2416 NOTE:
2419 ARCH_INDEPENDENT is intended for header-only libraries or similar
2420 packages with no binaries.
2421 New in version 3.19: COMPATIBILITY_MODE AnyNewerVersion, SameMajorVer‐
2423 sion and SameMinorVersion handle the version range if any is specified
2424 (see find_package() command for the details). ExactVersion mode is in‐
2425 compatible with version ranges and will display an author warning if
2426 one is specified.
2427 Internally, this macro executes configure_file() to create the result‐
2430 ing version file. Depending on the COMPATIBILITY, the corresponding
2431 BasicConfigVersion-<COMPATIBILITY>.cmake.in file is used. Please note
2432 that these files are internal to CMake and you should not call config‐
2433 ure_file() on them yourself, but they can be used as starting point to
2434 create more sophisticted custom ConfigVersion.cmake files.
2435 Example Generating Package Files
2437 Example using both configure_package_config_file() and write_ba‐
2438 sic_package_version_file():
2439 CMakeLists.txt:
2441 set(INCLUDE_INSTALL_DIR include/ ... CACHE )
2443 set(LIB_INSTALL_DIR lib/ ... CACHE )
2444 set(SYSCONFIG_INSTALL_DIR etc/foo/ ... CACHE )
2445 #...
2446 include(CMakePackageConfigHelpers)
2447 configure_package_config_file(FooConfig.cmake.in
2448 ${CMAKE_CURRENT_BINARY_DIR}/FooConfig.cmake
2449 INSTALL_DESTINATION ${LIB_INSTALL_DIR}/Foo/cmake
2450 PATH_VARS INCLUDE_INSTALL_DIR SYSCONFIG_INSTALL_DIR)
2451 write_basic_package_version_file(
2452 ${CMAKE_CURRENT_BINARY_DIR}/FooConfigVersion.cmake
2453 VERSION 1.2.3
2454 COMPATIBILITY SameMajorVersion )
2455 install(FILES ${CMAKE_CURRENT_BINARY_DIR}/FooConfig.cmake
2456 ${CMAKE_CURRENT_BINARY_DIR}/FooConfigVersion.cmake
2457 DESTINATION ${LIB_INSTALL_DIR}/Foo/cmake )
2458 FooConfig.cmake.in:
2460 set(FOO_VERSION x.y.z)
2462 ...
2463 @PACKAGE_INIT@
2464 ...
2465 set_and_check(FOO_INCLUDE_DIR "@PACKAGE_INCLUDE_INSTALL_DIR@")
2466 set_and_check(FOO_SYSCONFIG_DIR "@PACKAGE_SYSCONFIG_INSTALL_DIR@")
2467 check_required_components(Foo)
2469 CMakePrintHelpers
2471 Convenience functions for printing properties and variables, useful
2472 e.g. for debugging.
2473 cmake_print_properties([TARGETS target1 .. targetN]
2475 [SOURCES source1 .. sourceN]
2476 [DIRECTORIES dir1 .. dirN]
2477 [TESTS test1 .. testN]
2478 [CACHE_ENTRIES entry1 .. entryN]
2479 PROPERTIES prop1 .. propN )
2480 This function prints the values of the properties of the given targets,
2482 source files, directories, tests or cache entries. Exactly one of the
2483 scope keywords must be used. Example:
2484 cmake_print_properties(TARGETS foo bar PROPERTIES
2486 LOCATION INTERFACE_INCLUDE_DIRECTORIES)
2487 This will print the LOCATION and INTERFACE_INCLUDE_DIRECTORIES proper‐
2489 ties for both targets foo and bar.
2490 cmake_print_variables(var1 var2 .. varN)
2492 This function will print the name of each variable followed by its
2494 value. Example:
2495 cmake_print_variables(CMAKE_C_COMPILER CMAKE_MAJOR_VERSION DOES_NOT_EXIST)
2497 Gives:
2499 -- CMAKE_C_COMPILER="/usr/bin/gcc" ; CMAKE_MAJOR_VERSION="2" ; DOES_NOT_EXIST=""
2501 CMakePrintSystemInformation
2503 Print system information.
2504 This module serves diagnostic purposes. Just include it in a project to
2506 see various internal CMake variables.
2507 CMakePushCheckState
2509 This module defines three macros: CMAKE_PUSH_CHECK_STATE()
2510 CMAKE_POP_CHECK_STATE() and CMAKE_RESET_CHECK_STATE() These macros can
2511 be used to save, restore and reset (i.e., clear contents) the state of
2512 the variables CMAKE_REQUIRED_FLAGS, CMAKE_REQUIRED_DEFINITIONS,
2513 CMAKE_REQUIRED_LINK_OPTIONS, CMAKE_REQUIRED_LIBRARIES, CMAKE_RE‐
2514 QUIRED_INCLUDES and CMAKE_EXTRA_INCLUDE_FILES used by the various
2515 Check-files coming with CMake, like e.g. check_function_exists() etc.
2516 The variable contents are pushed on a stack, pushing multiple times is
2517 supported. This is useful e.g. when executing such tests in a
2518 Find-module, where they have to be set, but after the Find-module has
2519 been executed they should have the same value as they had before.
2520 CMAKE_PUSH_CHECK_STATE() macro receives optional argument RESET.
2522 Whether it's specified, CMAKE_PUSH_CHECK_STATE() will set all CMAKE_RE‐
2523 QUIRED_* variables to empty values, same as CMAKE_RESET_CHECK_STATE()
2524 call will do.
2525 Usage:
2527 cmake_push_check_state(RESET)
2529 set(CMAKE_REQUIRED_DEFINITIONS -DSOME_MORE_DEF)
2530 check_function_exists(...)
2531 cmake_reset_check_state()
2532 set(CMAKE_REQUIRED_DEFINITIONS -DANOTHER_DEF)
2533 check_function_exists(...)
2534 cmake_pop_check_state()
2535 CMakeVerifyManifest
2537 CMakeVerifyManifest.cmake
2538 This script is used to verify that embedded manifests and side by side
2540 manifests for a project match. To run this script, cd to a directory
2541 and run the script with cmake -P. On the command line you can pass in
2542 versions that are OK even if not found in the .manifest files. For ex‐
2543 ample, cmake -Dallow_versions=8.0.50608.0 -PCmakeVerifyManifest.cmake
2544 could be used to allow an embedded manifest of 8.0.50608.0 to be used
2545 in a project even if that version was not found in the .manifest file.
2546 CPack
2548 Configure generators for binary installers and source packages.
2549 Introduction
2551 The CPack module generates the configuration files CPackConfig.cmake
2552 and CPackSourceConfig.cmake. They are intended for use in a subsequent
2553 run of the cpack program where they steer the generation of installers
2554 or/and source packages.
2555 Depending on the CMake generator, the CPack module may also add two new
2557 build targets, package and package_source. See the packaging targets
2558 section below for details.
2559 The generated binary installers will contain all files that have been
2561 installed via CMake's install() command (and the deprecated commands
2562 install_files(), install_programs(), and install_targets()). Note that
2563 the DESTINATION option of the install() command must be a relative
2564 path; otherwise installed files are ignored by CPack.
2565 Certain kinds of binary installers can be configured such that users
2567 can select individual application components to install. See the
2568 CPackComponent module for further details.
2569 Source packages (configured through CPackSourceConfig.cmake and gener‐
2571 ated by the CPack Archive Generator) will contain all source files in
2572 the project directory except those specified in
2573 CPACK_SOURCE_IGNORE_FILES.
2574 CPack Generators
2576 The CPACK_GENERATOR variable has different meanings in different con‐
2577 texts. In a CMakeLists.txt file, CPACK_GENERATOR is a list of genera‐
2578 tors: and when cpack is run with no other arguments, it will iterate
2579 over that list and produce one package for each generator. In a
2580 CPACK_PROJECT_CONFIG_FILE, CPACK_GENERATOR is a string naming a single
2581 generator. If you need per-cpack-generator logic to control other
2582 cpack settings, then you need a CPACK_PROJECT_CONFIG_FILE. If set, the
2583 CPACK_PROJECT_CONFIG_FILE is included automatically on a per-generator
2584 basis. It only need contain overrides.
2585 Here's how it works:
2587 • cpack runs
2589 • it includes CPackConfig.cmake
2591 • it iterates over the generators given by the -G command line option,
2593 or if no such option was specified, over the list of generators given
2594 by the CPACK_GENERATOR variable set in the CPackConfig.cmake input
2595 file.
2596 • foreach generator, it then
2598 • sets CPACK_GENERATOR to the one currently being iterated
2600 • includes the CPACK_PROJECT_CONFIG_FILE
2602 • produces the package for that generator
2604 This is the key: For each generator listed in CPACK_GENERATOR in CPack‐
2606 Config.cmake, cpack will reset CPACK_GENERATOR internally to the one
2607 currently being used and then include the CPACK_PROJECT_CONFIG_FILE.
2608 For a list of available generators, see cpack-generators(7).
2610 Targets package and package_source
2612 If CMake is run with the Makefile, Ninja, or Xcode generator, then in‐
2613 clude(CPack) generates a target package. This makes it possible to
2614 build a binary installer from CMake, Make, or Ninja: Instead of cpack,
2615 one may call cmake --build . --target package or make package or ninja
2616 package. The VS generator creates an uppercase target PACKAGE.
2617 If CMake is run with the Makefile or Ninja generator, then in‐
2619 clude(CPack) also generates a target package_source. To build a source
2620 package, instead of cpack -G TGZ --config CPackSourceConfig.cmake one
2621 may call cmake --build . --target package_source, make package_source,
2622 or ninja package_source.
2623 Variables common to all CPack Generators
2625 Before including this CPack module in your CMakeLists.txt file, there
2626 are a variety of variables that can be set to customize the resulting
2627 installers. The most commonly-used variables are:
2628 CPACK_PACKAGE_NAME
2630 The name of the package (or application). If not specified, it
2631 defaults to the project name.
2632 CPACK_PACKAGE_VENDOR
2634 The name of the package vendor. (e.g., "Kitware"). The default
2635 is "Humanity".
2636 CPACK_PACKAGE_DIRECTORY
2638 The directory in which CPack is doing its packaging. If it is
2639 not set then this will default (internally) to the build dir.
2640 This variable may be defined in a CPack config file or from the
2641 cpack command line option -B. If set, the command line option
2642 overrides the value found in the config file.
2643 CPACK_PACKAGE_VERSION_MAJOR
2645 Package major version. This variable will always be set, but
2646 its default value depends on whether or not version details were
2647 given to the project() command in the top level CMakeLists.txt
2648 file. If version details were given, the default value will be
2649 CMAKE_PROJECT_VERSION_MAJOR. If no version details were given,
2650 a default version of 0.1.1 will be assumed, leading to
2651 CPACK_PACKAGE_VERSION_MAJOR having a default value of 0.
2652 CPACK_PACKAGE_VERSION_MINOR
2654 Package minor version. The default value is determined based on
2655 whether or not version details were given to the project() com‐
2656 mand in the top level CMakeLists.txt file. If version details
2657 were given, the default value will be CMAKE_PROJECT_VERSION_MI‐
2658 NOR, but if no minor version component was specified then
2659 CPACK_PACKAGE_VERSION_MINOR will be left unset. If no project
2660 version was given at all, a default version of 0.1.1 will be as‐
2661 sumed, leading to CPACK_PACKAGE_VERSION_MINOR having a default
2662 value of 1.
2663 CPACK_PACKAGE_VERSION_PATCH
2665 Package patch version. The default value is determined based on
2666 whether or not version details were given to the project() com‐
2667 mand in the top level CMakeLists.txt file. If version details
2668 were given, the default value will be CMAKE_PROJECT_VER‐
2669 SION_PATCH, but if no patch version component was specified then
2670 CPACK_PACKAGE_VERSION_PATCH will be left unset. If no project
2671 version was given at all, a default version of 0.1.1 will be as‐
2672 sumed, leading to CPACK_PACKAGE_VERSION_PATCH having a default
2673 value of 1.
2674 CPACK_PACKAGE_DESCRIPTION
2676 A description of the project, used in places such as the intro‐
2677 duction screen of CPack-generated Windows installers. If not
2678 set, the value of this variable is populated from the file named
2679 by CPACK_PACKAGE_DESCRIPTION_FILE.
2680 CPACK_PACKAGE_DESCRIPTION_FILE
2682 A text file used to describe the project when
2683 CPACK_PACKAGE_DESCRIPTION is not explicitly set. The default
2684 value for CPACK_PACKAGE_DESCRIPTION_FILE points to a built-in
2685 template file Templates/CPack.GenericDescription.txt.
2686 CPACK_PACKAGE_DESCRIPTION_SUMMARY
2688 Short description of the project (only a few words). If the
2689 CMAKE_PROJECT_DESCRIPTION variable is set, it is used as the de‐
2690 fault value, otherwise the default will be a string generated by
2691 CMake based on CMAKE_PROJECT_NAME.
2692 CPACK_PACKAGE_HOMEPAGE_URL
2694 Project homepage URL. The default value is taken from the
2695 CMAKE_PROJECT_HOMEPAGE_URL variable, which is set by the top
2696 level project() command, or else the default will be empty if no
2697 URL was provided to project().
2698 CPACK_PACKAGE_FILE_NAME
2700 The name of the package file to generate, not including the ex‐
2701 tension. For example, cmake-2.6.1-Linux-i686. The default
2702 value is:
2703 ${CPACK_PACKAGE_NAME}-${CPACK_PACKAGE_VERSION}-${CPACK_SYSTEM_NAME}
2705 CPACK_PACKAGE_INSTALL_DIRECTORY
2707 Installation directory on the target system. This may be used by
2708 some CPack generators like NSIS to create an installation direc‐
2709 tory e.g., "CMake 2.5" below the installation prefix. All in‐
2710 stalled elements will be put inside this directory.
2711 CPACK_PACKAGE_ICON
2713 A branding image that will be displayed inside the installer
2714 (used by GUI installers).
2715 CPACK_PACKAGE_CHECKSUM
2717 New in version 3.7.
2718 An algorithm that will be used to generate an additional file
2721 with the checksum of the package. The output file name will be:
2722 ${CPACK_PACKAGE_FILE_NAME}.${CPACK_PACKAGE_CHECKSUM}
2724 Supported algorithms are those listed by the string(<HASH>) com‐
2726 mand.
2727 CPACK_PROJECT_CONFIG_FILE
2729 CPack-time project CPack configuration file. This file is in‐
2730 cluded at cpack time, once per generator after CPack has set
2731 CPACK_GENERATOR to the actual generator being used. It allows
2732 per-generator setting of CPACK_* variables at cpack time.
2733 CPACK_RESOURCE_FILE_LICENSE
2735 License to be embedded in the installer. It will typically be
2736 displayed to the user by the produced installer (often with an
2737 explicit "Accept" button, for graphical installers) prior to in‐
2738 stallation. This license file is NOT added to the installed
2739 files but is used by some CPack generators like NSIS. If you
2740 want to install a license file (may be the same as this one)
2741 along with your project, you must add an appropriate CMake in‐
2742 stall() command in your CMakeLists.txt.
2743 CPACK_RESOURCE_FILE_README
2745 ReadMe file to be embedded in the installer. It typically de‐
2746 scribes in some detail the purpose of the project during the in‐
2747 stallation. Not all CPack generators use this file.
2748 CPACK_RESOURCE_FILE_WELCOME
2750 Welcome file to be embedded in the installer. It welcomes users
2751 to this installer. Typically used in the graphical installers
2752 on Windows and Mac OS X.
2753 CPACK_MONOLITHIC_INSTALL
2755 Disables the component-based installation mechanism. When set,
2756 the component specification is ignored and all installed items
2757 are put in a single "MONOLITHIC" package. Some CPack generators
2758 do monolithic packaging by default and may be asked to do compo‐
2759 nent packaging by setting CPACK_<GENNAME>_COMPONENT_INSTALL to
2760 TRUE.
2761 CPACK_GENERATOR
2763 List of CPack generators to use. If not specified, CPack will
2764 create a set of options following the naming pattern
2765 CPACK_BINARY_<GENNAME> (e.g. CPACK_BINARY_NSIS) allowing the
2766 user to enable/disable individual generators. If the -G option
2767 is given on the cpack command line, it will override this vari‐
2768 able and any CPACK_BINARY_<GENNAME> options.
2769 CPACK_OUTPUT_CONFIG_FILE
2771 The name of the CPack binary configuration file. This file is
2772 the CPack configuration generated by the CPack module for binary
2773 installers. Defaults to CPackConfig.cmake.
2774 CPACK_PACKAGE_EXECUTABLES
2776 Lists each of the executables and associated text label to be
2777 used to create Start Menu shortcuts. For example, setting this
2778 to the list ccmake;CMake will create a shortcut named "CMake"
2779 that will execute the installed executable ccmake. Not all
2780 CPack generators use it (at least NSIS, WIX and OSXX11 do).
2781 CPACK_STRIP_FILES
2783 List of files to be stripped. Starting with CMake 2.6.0,
2784 CPACK_STRIP_FILES will be a boolean variable which enables
2785 stripping of all files (a list of files evaluates to TRUE in
2786 CMake, so this change is compatible).
2787 CPACK_VERBATIM_VARIABLES
2789 New in version 3.4.
2790 If set to TRUE, values of variables prefixed with CPACK_ will be
2793 escaped before being written to the configuration files, so that
2794 the cpack program receives them exactly as they were specified.
2795 If not, characters like quotes and backslashes can cause parsing
2796 errors or alter the value received by the cpack program. De‐
2797 faults to FALSE for backwards compatibility.
2798 CPACK_THREADS
2800 New in version 3.20.
2801 Number of threads to use when performing parallelized opera‐
2804 tions, such as compressing the installer package.
2805 Some compression methods used by CPack generators such as Debian
2807 or Archive may take advantage of multiple CPU cores to speed up
2808 compression. CPACK_THREADS can be set to positive integer to
2809 specify how many threads will be used for compression. If it is
2810 set to 0, CPack will set it so that all available CPU cores are
2811 used. By default CPACK_THREADS is set to 1.
2812 Currently only xz compression may take advantage of multiple
2814 cores. Other compression methods ignore this value and use only
2815 one thread.
2816 NOTE:
2818 Official CMake binaries available on cmake.org ship with a
2819 liblzma that does not support parallel compression.
2820 Variables for Source Package Generators
2822 The following CPack variables are specific to source packages, and will
2823 not affect binary packages:
2824 CPACK_SOURCE_PACKAGE_FILE_NAME
2826 The name of the source package. For example cmake-2.6.1.
2827 CPACK_SOURCE_STRIP_FILES
2829 List of files in the source tree that will be stripped. Start‐
2830 ing with CMake 2.6.0, CPACK_SOURCE_STRIP_FILES will be a boolean
2831 variable which enables stripping of all files (a list of files
2832 evaluates to TRUE in CMake, so this change is compatible).
2833 CPACK_SOURCE_GENERATOR
2835 List of generators used for the source packages. As with
2836 CPACK_GENERATOR, if this is not specified then CPack will create
2837 a set of options (e.g. CPACK_SOURCE_ZIP) allowing users to se‐
2838 lect which packages will be generated.
2839 CPACK_SOURCE_OUTPUT_CONFIG_FILE
2841 The name of the CPack source configuration file. This file is
2842 the CPack configuration generated by the CPack module for source
2843 installers. Defaults to CPackSourceConfig.cmake.
2844 CPACK_SOURCE_IGNORE_FILES
2846 Pattern of files in the source tree that won't be packaged when
2847 building a source package. This is a list of regular expression
2848 patterns (that must be properly escaped), e.g.,
2849 /CVS/;/\\.svn/;\\.swp$;\\.#;/#;.*~;cscope.*
2850 Variables for Advanced Use
2852 The following variables are for advanced uses of CPack:
2853 CPACK_CMAKE_GENERATOR
2855 What CMake generator should be used if the project is a CMake
2856 project. Defaults to the value of CMAKE_GENERATOR. Few users
2857 will want to change this setting.
2858 CPACK_INSTALL_CMAKE_PROJECTS
2860 List of four values that specify what project to install. The
2861 four values are: Build directory, Project Name, Project Compo‐
2862 nent, Directory. If omitted, CPack will build an installer that
2863 installs everything.
2864 CPACK_SYSTEM_NAME
2866 System name, defaults to the value of CMAKE_SYSTEM_NAME, except
2867 on Windows where it will be win32 or win64.
2868 CPACK_PACKAGE_VERSION
2870 Package full version, used internally. By default, this is
2871 built from CPACK_PACKAGE_VERSION_MAJOR,
2872 CPACK_PACKAGE_VERSION_MINOR, and CPACK_PACKAGE_VERSION_PATCH.
2873 CPACK_TOPLEVEL_TAG
2875 Directory for the installed files.
2876 CPACK_INSTALL_COMMANDS
2878 Extra commands to install components. The environment variable
2879 CMAKE_INSTALL_PREFIX is set to the temporary install directory
2880 during execution.
2881 CPACK_INSTALL_SCRIPTS
2883 New in version 3.16.
2884 Extra CMake scripts executed by CPack during its local staging
2887 installation. They are executed before installing the files to
2888 be packaged. The scripts are not called by a standalone install
2889 (e.g.: make install). For every script, the following variables
2890 will be set: CMAKE_CURRENT_SOURCE_DIR, CMAKE_CURRENT_BINARY_DIR
2891 and CMAKE_INSTALL_PREFIX (which is set to the staging install
2892 directory). The singular form CMAKE_INSTALL_SCRIPT is supported
2893 as an alternative variable for historical reasons, but its value
2894 is ignored if CMAKE_INSTALL_SCRIPTS is set and a warning will be
2895 issued.
2896 See also CPACK_PRE_BUILD_SCRIPTS and CPACK_POST_BUILD_SCRIPTS
2898 which can be used to specify scripts to be executed later in the
2899 packaging process.
2900 CPACK_PRE_BUILD_SCRIPTS
2902 New in version 3.19.
2903 List of CMake scripts to execute after CPack has installed the
2906 files to be packaged into a staging directory and before produc‐
2907 ing the package(s) from those files. See also
2908 CPACK_INSTALL_SCRIPTS and CPACK_POST_BUILD_SCRIPTS.
2909 CPACK_POST_BUILD_SCRIPTS
2911 New in version 3.19.
2912 List of CMake scripts to execute after CPack has produced the
2915 resultant packages and before copying them back to the build di‐
2916 rectory. See also CPACK_INSTALL_SCRIPTS,
2917 CPACK_PRE_BUILD_SCRIPTS and CPACK_PACKAGE_FILES.
2918 CPACK_PACKAGE_FILES
2920 New in version 3.19.
2921 List of package files created in the staging directory, with
2924 each file provided as a full absolute path. This variable is
2925 populated by CPack just before invoking the post-build scripts
2926 listed in CPACK_POST_BUILD_SCRIPTS. It is the preferred way for
2927 the post-build scripts to know the set of package files to oper‐
2928 ate on. Projects should not try to set this variable them‐
2929 selves.
2930 CPACK_INSTALLED_DIRECTORIES
2932 Extra directories to install.
2933 CPACK_PACKAGE_INSTALL_REGISTRY_KEY
2935 Registry key used when installing this project. This is only
2936 used by installers for Windows. The default value is based on
2937 the installation directory.
2938 CPACK_CREATE_DESKTOP_LINKS
2940 List of desktop links to create. Each desktop link requires a
2941 corresponding start menu shortcut as created by
2942 CPACK_PACKAGE_EXECUTABLES.
2943 CPACK_BINARY_<GENNAME>
2945 CPack generated options for binary generators. The CPack.cmake
2946 module generates (when CPACK_GENERATOR is not set) a set of
2947 CMake options (see CMake option() command) which may then be
2948 used to select the CPack generator(s) to be used when building
2949 the package target or when running cpack without the -G option.
2950 CPackComponent
2952 Configure components for binary installers and source packages.
2953 Introduction
2955 This module is automatically included by CPack.
2956 Certain binary installers (especially the graphical installers) gener‐
2958 ated by CPack allow users to select individual application components
2959 to install. This module allows developers to configure the packaging
2960 of such components.
2961 Contents is assigned to components by the COMPONENT argument of CMake's
2963 install() command. Components can be annotated with user-friendly
2964 names and descriptions, inter-component dependencies, etc., and grouped
2965 in various ways to customize the resulting installer, using the com‐
2966 mands described below.
2967 To specify different groupings for different CPack generators use a
2969 CPACK_PROJECT_CONFIG_FILE.
2970 Variables
2972 The following variables influence the component-specific packaging:
2973 CPACK_COMPONENTS_ALL
2975 The list of component to install.
2976 The default value of this variable is computed by CPack and con‐
2978 tains all components defined by the project. The user may set
2979 it to only include the specified components.
2980 Instead of specifying all the desired components, it is possible
2982 to obtain a list of all defined components and then remove the
2983 unwanted ones from the list. The get_cmake_property() command
2984 can be used to obtain the COMPONENTS property, then the list(RE‐
2985 MOVE_ITEM) command can be used to remove the unwanted ones. For
2986 example, to use all defined components except foo and bar:
2987 get_cmake_property(CPACK_COMPONENTS_ALL COMPONENTS)
2989 list(REMOVE_ITEM CPACK_COMPONENTS_ALL "foo" "bar")
2990 CPACK_<GENNAME>_COMPONENT_INSTALL
2992 Enable/Disable component install for CPack generator <GENNAME>.
2993 Each CPack Generator (RPM, DEB, ARCHIVE, NSIS, DMG, etc...) has
2995 a legacy default behavior. e.g. RPM builds monolithic whereas
2996 NSIS builds component. One can change the default behavior by
2997 setting this variable to 0/1 or OFF/ON.
2998 CPACK_COMPONENTS_GROUPING
3000 Specify how components are grouped for multi-package compo‐
3001 nent-aware CPack generators.
3002 Some generators like RPM or ARCHIVE (TGZ, ZIP, ...) may generate
3004 several packages files when there are components, depending on
3005 the value of this variable:
3006 • ONE_PER_GROUP (default): create one package per component
3008 group
3009 • IGNORE : create one package per component (ignore the groups)
3011 • ALL_COMPONENTS_IN_ONE : create a single package with all re‐
3013 quested components
3014 CPACK_COMPONENT_<compName>_DISPLAY_NAME
3016 The name to be displayed for a component.
3017 CPACK_COMPONENT_<compName>_DESCRIPTION
3019 The description of a component.
3020 CPACK_COMPONENT_<compName>_GROUP
3022 The group of a component.
3023 CPACK_COMPONENT_<compName>_DEPENDS
3025 The dependencies (list of components) on which this component
3026 depends.
3027 CPACK_COMPONENT_<compName>_HIDDEN
3029 True if this component is hidden from the user.
3030 CPACK_COMPONENT_<compName>_REQUIRED
3032 True if this component is required.
3033 CPACK_COMPONENT_<compName>_DISABLED
3035 True if this component is not selected to be installed by de‐
3036 fault.
3037 Commands
3039 Add component
3040 cpack_add_component
3041 Describe an installation component.
3043 cpack_add_component(compname
3045 [DISPLAY_NAME name]
3046 [DESCRIPTION description]
3047 [HIDDEN | REQUIRED | DISABLED ]
3048 [GROUP group]
3049 [DEPENDS comp1 comp2 ... ]
3050 [INSTALL_TYPES type1 type2 ... ]
3051 [DOWNLOADED]
3052 [ARCHIVE_FILE filename]
3053 [PLIST filename])
3054 compname is the name of an installation component, as defined by the
3056 COMPONENT argument of one or more CMake install() commands. With the
3057 cpack_add_component command one can set a name, a description, and
3058 other attributes of an installation component. One can also assign a
3059 component to a component group.
3060 DISPLAY_NAME is the displayed name of the component, used in graphical
3062 installers to display the component name. This value can be any
3063 string.
3064 DESCRIPTION is an extended description of the component, used in graph‐
3066 ical installers to give the user additional information about the com‐
3067 ponent. Descriptions can span multiple lines using \n as the line sep‐
3068 arator. Typically, these descriptions should be no more than a few
3069 lines long.
3070 HIDDEN indicates that this component will be hidden in the graphical
3072 installer, so that the user cannot directly change whether it is in‐
3073 stalled or not.
3074 REQUIRED indicates that this component is required, and therefore will
3076 always be installed. It will be visible in the graphical installer,
3077 but it cannot be unselected. (Typically, required components are shown
3078 greyed out).
3079 DISABLED indicates that this component should be disabled (unselected)
3081 by default. The user is free to select this component for installa‐
3082 tion, unless it is also HIDDEN.
3083 DEPENDS lists the components on which this component depends. If this
3085 component is selected, then each of the components listed must also be
3086 selected. The dependency information is encoded within the installer
3087 itself, so that users cannot install inconsistent sets of components.
3088 GROUP names the component group of which this component is a part. If
3090 not provided, the component will be a standalone component, not part of
3091 any component group. Component groups are described with the
3092 cpack_add_component_group command, detailed below.
3093 INSTALL_TYPES lists the installation types of which this component is a
3095 part. When one of these installations types is selected, this compo‐
3096 nent will automatically be selected. Installation types are described
3097 with the cpack_add_install_type command, detailed below.
3098 DOWNLOADED indicates that this component should be downloaded
3100 on-the-fly by the installer, rather than packaged in with the installer
3101 itself. For more information, see the cpack_configure_downloads com‐
3102 mand.
3103 ARCHIVE_FILE provides a name for the archive file created by CPack to
3105 be used for downloaded components. If not supplied, CPack will create
3106 a file with some name based on CPACK_PACKAGE_FILE_NAME and the name of
3107 the component. See cpack_configure_downloads for more information.
3108 PLIST gives a filename that is passed to pkgbuild with the --compo‐
3110 nent-plist argument when using the productbuild generator.
3111 Add component group
3113 cpack_add_component_group
3114 Describes a group of related CPack installation components.
3116 cpack_add_component_group(groupname
3118 [DISPLAY_NAME name]
3119 [DESCRIPTION description]
3120 [PARENT_GROUP parent]
3121 [EXPANDED]
3122 [BOLD_TITLE])
3123 The cpack_add_component_group describes a group of installation compo‐
3125 nents, which will be placed together within the listing of options.
3126 Typically, component groups allow the user to select/deselect all of
3127 the components within a single group via a single group-level option.
3128 Use component groups to reduce the complexity of installers with many
3129 options. groupname is an arbitrary name used to identify the group in
3130 the GROUP argument of the cpack_add_component command, which is used to
3131 place a component in a group. The name of the group must not conflict
3132 with the name of any component.
3133 DISPLAY_NAME is the displayed name of the component group, used in
3135 graphical installers to display the component group name. This value
3136 can be any string.
3137 DESCRIPTION is an extended description of the component group, used in
3139 graphical installers to give the user additional information about the
3140 components within that group. Descriptions can span multiple lines us‐
3141 ing \n as the line separator. Typically, these descriptions should be
3142 no more than a few lines long.
3143 PARENT_GROUP, if supplied, names the parent group of this group. Par‐
3145 ent groups are used to establish a hierarchy of groups, providing an
3146 arbitrary hierarchy of groups.
3147 EXPANDED indicates that, by default, the group should show up as "ex‐
3149 panded", so that the user immediately sees all of the components within
3150 the group. Otherwise, the group will initially show up as a single en‐
3151 try.
3152 BOLD_TITLE indicates that the group title should appear in bold, to
3154 call the user's attention to the group.
3155 Add installation type
3157 cpack_add_install_type
3158 Add a new installation type containing a set of predefined component
3160 selections to the graphical installer.
3161 cpack_add_install_type(typename
3163 [DISPLAY_NAME name])
3164 The cpack_add_install_type command identifies a set of preselected com‐
3166 ponents that represents a common use case for an application. For ex‐
3167 ample, a "Developer" install type might include an application along
3168 with its header and library files, while an "End user" install type
3169 might just include the application's executable. Each component iden‐
3170 tifies itself with one or more install types via the INSTALL_TYPES ar‐
3171 gument to cpack_add_component.
3172 DISPLAY_NAME is the displayed name of the install type, which will typ‐
3174 ically show up in a drop-down box within a graphical installer. This
3175 value can be any string.
3176 Configure downloads
3178 cpack_configure_downloads
3179 Configure CPack to download selected components on-the-fly as part of
3181 the installation process.
3182 cpack_configure_downloads(site
3184 [UPLOAD_DIRECTORY dirname]
3185 [ALL]
3186 [ADD_REMOVE|NO_ADD_REMOVE])
3187 The cpack_configure_downloads command configures installation-time
3189 downloads of selected components. For each downloadable component,
3190 CPack will create an archive containing the contents of that component,
3191 which should be uploaded to the given site. When the user selects that
3192 component for installation, the installer will download and extract the
3193 component in place. This feature is useful for creating small install‐
3194 ers that only download the requested components, saving bandwidth. Ad‐
3195 ditionally, the installers are small enough that they will be installed
3196 as part of the normal installation process, and the "Change" button in
3197 Windows Add/Remove Programs control panel will allow one to add or re‐
3198 move parts of the application after the original installation. On Win‐
3199 dows, the downloaded-components functionality requires the ZipDLL
3200 plug-in for NSIS, available at:
3201 http://nsis.sourceforge.net/ZipDLL_plug-in
3203 On macOS, installers that download components on-the-fly can only be
3205 built and installed on system using macOS 10.5 or later.
3206 The site argument is a URL where the archives for downloadable compo‐
3208 nents will reside, e.g., https://cmake.org/files/2.6.1/installer/ All
3209 of the archives produced by CPack should be uploaded to that location.
3210 UPLOAD_DIRECTORY is the local directory where CPack will create the
3212 various archives for each of the components. The contents of this di‐
3213 rectory should be uploaded to a location accessible by the URL given in
3214 the site argument. If omitted, CPack will use the directory CPackU‐
3215 ploads inside the CMake binary directory to store the generated ar‐
3216 chives.
3217 The ALL flag indicates that all components be downloaded. Otherwise,
3219 only those components explicitly marked as DOWNLOADED or that have a
3220 specified ARCHIVE_FILE will be downloaded. Additionally, the ALL op‐
3221 tion implies ADD_REMOVE (unless NO_ADD_REMOVE is specified).
3222 ADD_REMOVE indicates that CPack should install a copy of the installer
3224 that can be called from Windows' Add/Remove Programs dialog (via the
3225 "Modify" button) to change the set of installed components. NO_ADD_RE‐
3226 MOVE turns off this behavior. This option is ignored on Mac OS X.
3227 CPackIFW
3229 New in version 3.1.
3230 This module looks for the location of the command-line utilities sup‐
3233 plied with the Qt Installer Framework (QtIFW).
3234 The module also defines several commands to control the behavior of the
3236 CPack IFW Generator.
3237 Commands
3239 The module defines the following commands:
3240 cpack_ifw_configure_component
3242 Sets the arguments specific to the CPack IFW generator.
3243 cpack_ifw_configure_component(<compname> [COMMON] [ESSENTIAL] [VIRTUAL]
3245 [FORCED_INSTALLATION] [REQUIRES_ADMIN_RIGHTS]
3246 [NAME <name>]
3247 [DISPLAY_NAME <display_name>] # Note: Internationalization supported
3248 [DESCRIPTION <description>] # Note: Internationalization supported
3249 [UPDATE_TEXT <update_text>]
3250 [VERSION <version>]
3251 [RELEASE_DATE <release_date>]
3252 [SCRIPT <script>]
3253 [PRIORITY|SORTING_PRIORITY <sorting_priority>] # Note: PRIORITY is deprecated
3254 [DEPENDS|DEPENDENCIES <com_id> ...]
3255 [AUTO_DEPEND_ON <comp_id> ...]
3256 [LICENSES <display_name> <file_path> ...]
3257 [DEFAULT <value>]
3258 [USER_INTERFACES <file_path> <file_path> ...]
3259 [TRANSLATIONS <file_path> <file_path> ...]
3260 [REPLACES <comp_id> ...]
3261 [CHECKABLE <value>])
3262 This command should be called after cpack_add_component() com‐
3264 mand.
3265 COMMON if set, then the component will be packaged and installed
3267 as part of a group to which it belongs.
3268 ESSENTIAL
3270 New in version 3.6.
3271 if set, then the package manager stays disabled until
3274 that component is updated.
3275 VIRTUAL
3277 New in version 3.8.
3278 if set, then the component will be hidden from the in‐
3281 staller. It is a equivalent of the HIDDEN option from
3282 the cpack_add_component() command.
3283 FORCED_INSTALLATION
3285 New in version 3.8.
3286 if set, then the component must always be installed. It
3289 is a equivalent of the REQUIRED option from the
3290 cpack_add_component() command.
3291 REQUIRES_ADMIN_RIGHTS
3293 New in version 3.8.
3294 set it if the component needs to be installed with ele‐
3297 vated permissions.
3298 NAME is used to create domain-like identification for this
3300 component. By default used origin component name.
3301 DISPLAY_NAME
3303 New in version 3.8.
3304 set to rewrite original name configured by cpack_add_com‐
3307 ponent() command.
3308 DESCRIPTION
3310 New in version 3.8.
3311 set to rewrite original description configured by
3314 cpack_add_component() command.
3315 UPDATE_TEXT
3317 New in version 3.8.
3318 will be added to the component description if this is an
3321 update to the component.
3322 VERSION
3324 is version of component. By default used CPACK_PACK‐
3325 AGE_VERSION.
3326 RELEASE_DATE
3328 New in version 3.8.
3329 keep empty to auto generate.
3332 SCRIPT is a relative or absolute path to operations script for
3334 this component.
3335 SORTING_PRIORITY
3337 New in version 3.8.
3338 is priority of the component in the tree.
3341 PRIORITY
3343 Deprecated since version 3.8: Old name for SORTING_PRIOR‐
3344 ITY.
3345 DEPENDS, DEPENDENCIES
3348 New in version 3.8.
3349 list of dependency component or component group identi‐
3352 fiers in QtIFW style.
3353 AUTO_DEPEND_ON
3355 New in version 3.8.
3356 list of identifiers of component or component group in
3359 QtIFW style that this component has an automatic depen‐
3360 dency on.
3361 LICENSES
3363 pair of <display_name> and <file_path> of license text
3364 for this component. You can specify more then one li‐
3365 cense.
3366 DEFAULT
3368 New in version 3.8.
3369 Possible values are: TRUE, FALSE, and SCRIPT. Set to
3372 FALSE to disable the component in the installer or to
3373 SCRIPT to resolved during runtime (don't forget add the
3374 file of the script as a value of the SCRIPT option).
3375 USER_INTERFACES
3377 New in version 3.7.
3378 is a list of <file_path> ('.ui' files) representing pages
3381 to load.
3382 TRANSLATIONS
3384 New in version 3.8.
3385 is a list of <file_path> ('.qm' files) representing
3388 translations to load.
3389 REPLACES
3391 New in version 3.10.
3392 list of identifiers of component or component group to
3395 replace.
3396 CHECKABLE
3398 New in version 3.10.
3399 Possible values are: TRUE, FALSE. Set to FALSE if you
3402 want to hide the checkbox for an item. This is useful
3403 when only a few subcomponents should be selected instead
3404 of all.
3405 cpack_ifw_configure_component_group
3407 Sets the arguments specific to the CPack IFW generator.
3408 cpack_ifw_configure_component_group(<groupname> [VIRTUAL]
3410 [FORCED_INSTALLATION] [REQUIRES_ADMIN_RIGHTS]
3411 [NAME <name>]
3412 [DISPLAY_NAME <display_name>] # Note: Internationalization supported
3413 [DESCRIPTION <description>] # Note: Internationalization supported
3414 [UPDATE_TEXT <update_text>]
3415 [VERSION <version>]
3416 [RELEASE_DATE <release_date>]
3417 [SCRIPT <script>]
3418 [PRIORITY|SORTING_PRIORITY <sorting_priority>] # Note: PRIORITY is deprecated
3419 [DEPENDS|DEPENDENCIES <com_id> ...]
3420 [AUTO_DEPEND_ON <comp_id> ...]
3421 [LICENSES <display_name> <file_path> ...]
3422 [DEFAULT <value>]
3423 [USER_INTERFACES <file_path> <file_path> ...]
3424 [TRANSLATIONS <file_path> <file_path> ...]
3425 [REPLACES <comp_id> ...]
3426 [CHECKABLE <value>])
3427 This command should be called after cpack_add_component_group()
3429 command.
3430 VIRTUAL
3432 New in version 3.8.
3433 if set, then the group will be hidden from the installer.
3436 Note that setting this on a root component does not work.
3437 FORCED_INSTALLATION
3439 New in version 3.8.
3440 if set, then the group must always be installed.
3443 REQUIRES_ADMIN_RIGHTS
3445 New in version 3.8.
3446 set it if the component group needs to be installed with
3449 elevated permissions.
3450 NAME is used to create domain-like identification for this
3452 component group. By default used origin component group
3453 name.
3454 DISPLAY_NAME
3456 New in version 3.8.
3457 set to rewrite original name configured by cpack_add_com‐
3460 ponent_group() command.
3461 DESCRIPTION
3463 New in version 3.8.
3464 set to rewrite original description configured by
3467 cpack_add_component_group() command.
3468 UPDATE_TEXT
3470 New in version 3.8.
3471 will be added to the component group description if this
3474 is an update to the component group.
3475 VERSION
3477 is version of component group. By default used
3478 CPACK_PACKAGE_VERSION.
3479 RELEASE_DATE
3481 New in version 3.8.
3482 keep empty to auto generate.
3485 SCRIPT is a relative or absolute path to operations script for
3487 this component group.
3488 SORTING_PRIORITY
3490 is priority of the component group in the tree.
3491 PRIORITY
3493 Deprecated since version 3.8: Old name for SORTING_PRIOR‐
3494 ITY.
3495 DEPENDS, DEPENDENCIES
3498 New in version 3.8.
3499 list of dependency component or component group identi‐
3502 fiers in QtIFW style.
3503 AUTO_DEPEND_ON
3505 New in version 3.8.
3506 list of identifiers of component or component group in
3509 QtIFW style that this component group has an automatic
3510 dependency on.
3511 LICENSES
3513 pair of <display_name> and <file_path> of license text
3514 for this component group. You can specify more then one
3515 license.
3516 DEFAULT
3518 New in version 3.8.
3519 Possible values are: TRUE, FALSE, and SCRIPT. Set to
3522 TRUE to preselect the group in the installer (this takes
3523 effect only on groups that have no visible child compo‐
3524 nents) or to SCRIPT to resolved during runtime (don't
3525 forget add the file of the script as a value of the
3526 SCRIPT option).
3527 USER_INTERFACES
3529 New in version 3.7.
3530 is a list of <file_path> ('.ui' files) representing pages
3533 to load.
3534 TRANSLATIONS
3536 New in version 3.8.
3537 is a list of <file_path> ('.qm' files) representing
3540 translations to load.
3541 REPLACES
3543 New in version 3.10.
3544 list of identifiers of component or component group to
3547 replace.
3548 CHECKABLE
3550 New in version 3.10.
3551 Possible values are: TRUE, FALSE. Set to FALSE if you
3554 want to hide the checkbox for an item. This is useful
3555 when only a few subcomponents should be selected instead
3556 of all.
3557 cpack_ifw_add_repository
3559 Add QtIFW specific remote repository to binary installer.
3560 cpack_ifw_add_repository(<reponame> [DISABLED]
3562 URL <url>
3563 [USERNAME <username>]
3564 [PASSWORD <password>]
3565 [DISPLAY_NAME <display_name>])
3566 This command will also add the <reponame> repository to a vari‐
3568 able CPACK_IFW_REPOSITORIES_ALL.
3569 DISABLED
3571 if set, then the repository will be disabled by default.
3572 URL is points to a list of available components.
3574 USERNAME
3576 is used as user on a protected repository.
3577 PASSWORD
3579 is password to use on a protected repository.
3580 DISPLAY_NAME
3582 is string to display instead of the URL.
3583 cpack_ifw_update_repository
3585 New in version 3.6.
3586 Update QtIFW specific repository from remote repository.
3589 cpack_ifw_update_repository(<reponame>
3591 [[ADD|REMOVE] URL <url>]|
3592 [REPLACE OLD_URL <old_url> NEW_URL <new_url>]]
3593 [USERNAME <username>]
3594 [PASSWORD <password>]
3595 [DISPLAY_NAME <display_name>])
3596 This command will also add the <reponame> repository to a vari‐
3598 able CPACK_IFW_REPOSITORIES_ALL.
3599 URL is points to a list of available components.
3601 OLD_URL
3603 is points to a list that will replaced.
3604 NEW_URL
3606 is points to a list that will replace to.
3607 USERNAME
3609 is used as user on a protected repository.
3610 PASSWORD
3612 is password to use on a protected repository.
3613 DISPLAY_NAME
3615 is string to display instead of the URL.
3616 cpack_ifw_add_package_resources
3618 New in version 3.7.
3619 Add additional resources in the installer binary.
3622 cpack_ifw_add_package_resources(<file_path> <file_path> ...)
3624 This command will also add the specified files to a variable
3626 CPACK_IFW_PACKAGE_RESOURCES.
3627 CPackIFWConfigureFile
3629 New in version 3.8.
3630 The module defines configure_file() similar command to configure file
3633 templates prepared in QtIFW/SDK/Creator style.
3634 Commands
3636 The module defines the following commands:
3637 cpack_ifw_configure_file
3639 Copy a file to another location and modify its contents.
3640 cpack_ifw_configure_file(<input> <output>)
3642 Copies an <input> file to an <output> file and substitutes vari‐
3644 able values referenced as %{VAR} or %VAR% in the input file con‐
3645 tent. Each variable reference will be replaced with the current
3646 value of the variable, or the empty string if the variable is
3647 not defined.
3648 CSharpUtilities
3650 New in version 3.8.
3651 Functions to make configuration of CSharp/.NET targets easier.
3654 A collection of CMake utility functions useful for dealing with CSharp
3656 targets for Visual Studio generators from version 2010 and later.
3657 The following functions are provided by this module:
3659 Main functions
3661 • csharp_set_windows_forms_properties()
3663 • csharp_set_designer_cs_properties()
3665 • csharp_set_xaml_cs_properties()
3667 Helper functions
3669 • csharp_get_filename_keys()
3671 • csharp_get_filename_key_base()
3673 • csharp_get_dependentupon_name()
3675 Main functions provided by the module
3677 csharp_set_windows_forms_properties
3678 Sets source file properties for use of Windows Forms. Use this,
3679 if your CSharp target uses Windows Forms:
3680 csharp_set_windows_forms_properties([<file1> [<file2> [...]]])
3682 <fileN>
3684 List of all source files which are relevant for setting
3685 the VS_CSHARP_<tagname> properties (including .cs, .resx
3686 and .Designer.cs extensions).
3687 In the list of all given files for all files ending with .De‐
3689 signer.cs and .resx is searched. For every designer or resource
3690 file a file with the same base name but only .cs as extension is
3691 searched. If this is found, the VS_CSHARP_<tagname> properties
3692 are set as follows:
3693 for the .cs file:
3695 • VS_CSHARP_SubType "Form"
3697 for the .Designer.cs file (if it exists):
3699 • VS_CSHARP_DependentUpon <cs-filename>
3701 • VS_CSHARP_DesignTime "" (delete tag if previously de‐
3703 fined)
3704 • VS_CSHARP_AutoGen ""(delete tag if previously defined)
3706 for the .resx file (if it exists):
3708 • VS_RESOURCE_GENERATOR "" (delete tag if previously de‐
3710 fined)
3711 • VS_CSHARP_DependentUpon <cs-filename>
3713 • VS_CSHARP_SubType "Designer"
3715 csharp_set_designer_cs_properties
3717 Sets source file properties of .Designer.cs files depending on
3718 sibling filenames. Use this, if your CSharp target does not use
3719 Windows Forms (for Windows Forms use
3720 csharp_set_designer_cs_properties() instead):
3721 csharp_set_designer_cs_properties([<file1> [<file2> [...]]])
3723 <fileN>
3725 List of all source files which are relevant for setting
3726 the VS_CSHARP_<tagname> properties (including .cs, .resx,
3727 .settings and .Designer.cs extensions).
3728 In the list of all given files for all files ending with .De‐
3730 signer.cs is searched. For every designer file all files with
3731 the same base name but different extensions are searched. If a
3732 match is found, the source file properties of the designer file
3733 are set depending on the extension of the matched file:
3734 if match is .resx file:
3736 • VS_CSHARP_AutoGen "True"
3738 • VS_CSHARP_DesignTime "True"
3740 • VS_CSHARP_DependentUpon <resx-filename>
3742 if match is .cs file:
3744 • VS_CSHARP_DependentUpon <cs-filename>
3746 if match is .settings file:
3748 • VS_CSHARP_AutoGen "True"
3750 • VS_CSHARP_DesignTimeSharedInput "True"
3752 • VS_CSHARP_DependentUpon <settings-filename>
3754 NOTE:
3756 Because the source file properties of the .Designer.cs file are set
3757 according to the found matches and every match sets the
3758 VS_CSHARP_DependentUpon property, there should only be one match for
3759 each Designer.cs file.
3760 csharp_set_xaml_cs_properties
3762 Sets source file properties for use of Windows Presentation
3763 Foundation (WPF) and XAML. Use this, if your CSharp target uses
3764 WPF/XAML:
3765 csharp_set_xaml_cs_properties([<file1> [<file2> [...]]])
3767 <fileN>
3769 List of all source files which are relevant for setting
3770 the VS_CSHARP_<tagname> properties (including .cs, .xaml,
3771 and .xaml.cs extensions).
3772 In the list of all given files for all files ending with
3774 .xaml.cs is searched. For every xaml-cs file, a file with the
3775 same base name but extension .xaml is searched. If a match is
3776 found, the source file properties of the .xaml.cs file are set:
3777 • VS_CSHARP_DependentUpon <xaml-filename>
3779 Helper functions which are used by the above ones
3781 csharp_get_filename_keys
3782 Helper function which computes a list of key values to identify
3783 source files independently of relative/absolute paths given in
3784 cmake and eliminates case sensitivity:
3785 csharp_get_filename_keys(OUT [<file1> [<file2> [...]]])
3787 OUT Name of the variable in which the list of keys is stored
3789 <fileN>
3791 filename(s) as given to to CSharp target using add_li‐
3792 brary() or add_executable()
3793 In some way the function applies a canonicalization to the
3795 source names. This is necessary to find file matches if the
3796 files have been added to the target with different directory
3797 prefixes:
3798 add_library(lib
3800 myfile.cs
3801 ${CMAKE_CURRENT_SOURCE_DIR}/myfile.Designer.cs)
3802 set_source_files_properties(myfile.Designer.cs PROPERTIES
3804 VS_CSHARP_DependentUpon myfile.cs)
3805 # this will fail, because in cmake
3807 # - ${CMAKE_CURRENT_SOURCE_DIR}/myfile.Designer.cs
3808 # - myfile.Designer.cs
3809 # are not the same source file. The source file property is not set.
3810 csharp_get_filename_key_base
3812 Returns the full filepath and name without extension of a key.
3813 KEY is expected to be a key from csharp_get_filename_keys. In
3814 BASE the value of KEY without the file extension is returned:
3815 csharp_get_filename_key_base(BASE KEY)
3817 BASE Name of the variable with the computed "base" of KEY.
3819 KEY The key of which the base will be computed. Expected to
3821 be a upper case full filename.
3822 csharp_get_dependentupon_name
3824 Computes a string which can be used as value for the source file
3825 property VS_CSHARP_<tagname> with target being DependentUpon:
3826 csharp_get_dependentupon_name(NAME FILE)
3828 NAME Name of the variable with the result value
3830 FILE Filename to convert to <DependentUpon> value
3832 Actually this is only the filename without any path given at the
3834 moment.
3835 CTest
3837 Configure a project for testing with CTest/CDash
3838 Include this module in the top CMakeLists.txt file of a project to en‐
3840 able testing with CTest and dashboard submissions to CDash:
3841 project(MyProject)
3843 ...
3844 include(CTest)
3845 The module automatically creates a BUILD_TESTING option that selects
3847 whether to enable testing support (ON by default). After including the
3848 module, use code like:
3849 if(BUILD_TESTING)
3851 # ... CMake code to create tests ...
3852 endif()
3853 to creating tests when testing is enabled.
3855 To enable submissions to a CDash server, create a CTestConfig.cmake
3857 file at the top of the project with content such as:
3858 set(CTEST_NIGHTLY_START_TIME "01:00:00 UTC")
3860 set(CTEST_SUBMIT_URL "http://my.cdash.org/submit.php?project=MyProject")
3861 (the CDash server can provide the file to a project administrator who
3863 configures MyProject). Settings in the config file are shared by both
3864 this CTest module and the ctest(1) command-line Dashboard Client mode
3865 (ctest -S).
3866 While building a project for submission to CDash, CTest scans the build
3868 output for errors and warnings and reports them with surrounding con‐
3869 text from the build log. This generic approach works for all build
3870 tools, but does not give details about the command invocation that pro‐
3871 duced a given problem. One may get more detailed reports by setting
3872 the CTEST_USE_LAUNCHERS variable:
3873 set(CTEST_USE_LAUNCHERS 1)
3875 in the CTestConfig.cmake file.
3877 CTestCoverageCollectGCOV
3879 New in version 3.2.
3880 This module provides the ctest_coverage_collect_gcov function.
3883 This function runs gcov on all .gcda files found in the binary tree and
3885 packages the resulting .gcov files into a tar file. This tarball also
3886 contains the following:
3887 • data.json defines the source and build directories for use by CDash.
3889 • Labels.json indicates any LABELS that have been set on the source
3891 files.
3892 • The uncovered directory holds any uncovered files found by CTEST_EX‐
3894 TRA_COVERAGE_GLOB.
3895 After generating this tar file, it can be sent to CDash for display
3897 with the ctest_submit(CDASH_UPLOAD) command.
3898 ctest_coverage_collect_gcov
3900 ctest_coverage_collect_gcov(TARBALL <tarfile>
3902 [SOURCE <source_dir>][BUILD <build_dir>]
3903 [GCOV_COMMAND <gcov_command>]
3904 [GCOV_OPTIONS <options>...]
3905 )
3906 Run gcov and package a tar file for CDash. The options are:
3908 TARBALL <tarfile>
3910 Specify the location of the .tar file to be created for
3911 later upload to CDash. Relative paths will be inter‐
3912 preted with respect to the top-level build directory.
3913 TARBALL_COMPRESSION <option>
3915 New in version 3.18.
3916 Specify a compression algorithm for the TARBALL data
3919 file. Using this option reduces the size of the data
3920 file before it is submitted to CDash. <option> must be
3921 one of GZIP, BZIP2, XZ, ZSTD, FROM_EXT, or an expression
3922 that CMake evaluates as FALSE. The default value is
3923 BZIP2.
3924 If FROM_EXT is specified, the resulting file will be com‐
3926 pressed based on the file extension of the <tarfile>
3927 (i.e. .tar.gz will use GZIP compression). File extensions
3928 that will produce compressed output include .tar.gz,
3929 .tgz, .tar.bzip2, .tbz, .tar.xz, and .txz.
3930 SOURCE <source_dir>
3932 Specify the top-level source directory for the build.
3933 Default is the value of CTEST_SOURCE_DIRECTORY.
3934 BUILD <build_dir>
3936 Specify the top-level build directory for the build. De‐
3937 fault is the value of CTEST_BINARY_DIRECTORY.
3938 GCOV_COMMAND <gcov_command>
3940 Specify the full path to the gcov command on the machine.
3941 Default is the value of CTEST_COVERAGE_COMMAND.
3942 GCOV_OPTIONS <options>...
3944 Specify options to be passed to gcov. The gcov command
3945 is run as gcov <options>... -o <gcov-dir> <file>.gcda.
3946 If not specified, the default option is just -b -x.
3947 GLOB New in version 3.6.
3949 Recursively search for .gcda files in build_dir rather
3952 than determining search locations by reading TargetDirec‐
3953 tories.txt.
3954 DELETE New in version 3.6.
3956 Delete coverage files after they've been packaged into
3959 the .tar.
3960 QUIET Suppress non-error messages that otherwise would have
3962 been printed out by this function.
3963 New in version 3.3: Added support for the CTEST_CUSTOM_COVER‐
3965 AGE_EXCLUDE variable.
3966 CTestScriptMode
3969 This file is read by ctest in script mode (-S)
3970 CTestUseLaunchers
3972 Set the RULE_LAUNCH_* global properties when CTEST_USE_LAUNCHERS is on.
3973 CTestUseLaunchers is automatically included when you include(CTest).
3975 However, it is split out into its own module file so projects can use
3976 the CTEST_USE_LAUNCHERS functionality independently.
3977 To use launchers, set CTEST_USE_LAUNCHERS to ON in a ctest -S dashboard
3979 script, and then also set it in the cache of the configured project.
3980 Both cmake and ctest need to know the value of it for the launchers to
3981 work properly. CMake needs to know in order to generate proper build
3982 rules, and ctest, in order to produce the proper error and warning
3983 analysis.
3984 For convenience, you may set the ENV variable CTEST_USE_LAUNCHERS_DE‐
3986 FAULT in your ctest -S script, too. Then, as long as your CMakeLists
3987 uses include(CTest) or include(CTestUseLaunchers), it will use the
3988 value of the ENV variable to initialize a CTEST_USE_LAUNCHERS cache
3989 variable. This cache variable initialization only occurs if
3990 CTEST_USE_LAUNCHERS is not already defined.
3991 New in version 3.8: If CTEST_USE_LAUNCHERS is on in a ctest -S script
3993 the ctest_configure command will add -DCTEST_USE_LAUNCHERS:BOOL=TRUE to
3994 the cmake command used to configure the project.
3995 Dart
3998 Configure a project for testing with CTest or old Dart Tcl Client
3999 This file is the backwards-compatibility version of the CTest module.
4001 It supports using the old Dart 1 Tcl client for driving dashboard sub‐
4002 missions as well as testing with CTest. This module should be included
4003 in the CMakeLists.txt file at the top of a project. Typical usage:
4004 include(Dart)
4006 if(BUILD_TESTING)
4007 # ... testing related CMake code ...
4008 endif()
4009 The BUILD_TESTING option is created by the Dart module to determine
4011 whether testing support should be enabled. The default is ON.
4012 DeployQt4
4014 Functions to help assemble a standalone Qt4 executable.
4015 A collection of CMake utility functions useful for deploying Qt4 exe‐
4017 cutables.
4018 The following functions are provided by this module:
4020 write_qt4_conf
4022 resolve_qt4_paths
4023 fixup_qt4_executable
4024 install_qt4_plugin_path
4025 install_qt4_plugin
4026 install_qt4_executable
4027 Requires CMake 2.6 or greater because it uses function and PAR‐
4029 ENT_SCOPE. Also depends on BundleUtilities.cmake.
4030 write_qt4_conf(<qt_conf_dir> <qt_conf_contents>)
4032 Writes a qt.conf file with the <qt_conf_contents> into <qt_conf_dir>.
4034 resolve_qt4_paths(<paths_var> [<executable_path>])
4036 Loop through <paths_var> list and if any don't exist resolve them rela‐
4038 tive to the <executable_path> (if supplied) or the CMAKE_INSTALL_PRE‐
4039 FIX.
4040 fixup_qt4_executable(<executable>
4042 [<qtplugins> <libs> <dirs> <plugins_dir> <request_qt_conf>])
4043 Copies Qt plugins, writes a Qt configuration file (if needed) and fixes
4045 up a Qt4 executable using BundleUtilities so it is standalone and can
4046 be drag-and-drop copied to another machine as long as all of the system
4047 libraries are compatible.
4048 <executable> should point to the executable to be fixed-up.
4050 <qtplugins> should contain a list of the names or paths of any Qt plug‐
4052 ins to be installed.
4053 <libs> will be passed to BundleUtilities and should be a list of any
4055 already installed plugins, libraries or executables to also be
4056 fixed-up.
4057 <dirs> will be passed to BundleUtilities and should contain and direc‐
4059 tories to be searched to find library dependencies.
4060 <plugins_dir> allows an custom plugins directory to be used.
4062 <request_qt_conf> will force a qt.conf file to be written even if not
4064 needed.
4065 install_qt4_plugin_path(plugin executable copy installed_plugin_path_var
4067 <plugins_dir> <component> <configurations>)
4068 Install (or copy) a resolved <plugin> to the default plugins directory
4070 (or <plugins_dir>) relative to <executable> and store the result in
4071 <installed_plugin_path_var>.
4072 If <copy> is set to TRUE then the plugins will be copied rather than
4074 installed. This is to allow this module to be used at CMake time
4075 rather than install time.
4076 If <component> is set then anything installed will use this COMPONENT.
4078 install_qt4_plugin(plugin executable copy installed_plugin_path_var
4080 <plugins_dir> <component>)
4081 Install (or copy) an unresolved <plugin> to the default plugins direc‐
4083 tory (or <plugins_dir>) relative to <executable> and store the result
4084 in <installed_plugin_path_var>. See documentation of IN‐
4085 STALL_QT4_PLUGIN_PATH.
4086 install_qt4_executable(<executable>
4088 [<qtplugins> <libs> <dirs> <plugins_dir> <request_qt_conf> <component>])
4089 Installs Qt plugins, writes a Qt configuration file (if needed) and
4091 fixes up a Qt4 executable using BundleUtilities so it is standalone and
4092 can be drag-and-drop copied to another machine as long as all of the
4093 system libraries are compatible. The executable will be fixed-up at
4094 install time. <component> is the COMPONENT used for bundle fixup and
4095 plugin installation. See documentation of FIXUP_QT4_BUNDLE.
4096 ExternalData
4098 Manage data files stored outside source tree
4099 Introduction
4101 Use this module to unambiguously reference data files stored outside
4102 the source tree and fetch them at build time from arbitrary local and
4103 remote content-addressed locations. Functions provided by this module
4104 recognize arguments with the syntax DATA{<name>} as references to ex‐
4105 ternal data, replace them with full paths to local copies of those
4106 data, and create build rules to fetch and update the local copies.
4107 For example:
4109 include(ExternalData)
4111 set(ExternalData_URL_TEMPLATES "file:///local/%(algo)/%(hash)"
4112 "file:////host/share/%(algo)/%(hash)"
4113 "http://data.org/%(algo)/%(hash)")
4114 ExternalData_Add_Test(MyData
4115 NAME MyTest
4116 COMMAND MyExe DATA{MyInput.png}
4117 )
4118 ExternalData_Add_Target(MyData)
4119 When test MyTest runs the DATA{MyInput.png} argument will be replaced
4121 by the full path to a real instance of the data file MyInput.png on
4122 disk. If the source tree contains a content link such as MyIn‐
4123 put.png.md5 then the MyData target creates a real MyInput.png in the
4124 build tree.
4125 Module Functions
4127 ExternalData_Expand_Arguments
4128 The ExternalData_Expand_Arguments function evaluates DATA{} ref‐
4129 erences in its arguments and constructs a new list of arguments:
4130 ExternalData_Expand_Arguments(
4132 <target> # Name of data management target
4133 <outVar> # Output variable
4134 [args...] # Input arguments, DATA{} allowed
4135 )
4136 It replaces each DATA{} reference in an argument with the full
4138 path of a real data file on disk that will exist after the <tar‐
4139 get> builds.
4140 ExternalData_Add_Test
4142 The ExternalData_Add_Test function wraps around the CMake
4143 add_test() command but supports DATA{} references in its argu‐
4144 ments:
4145 ExternalData_Add_Test(
4147 <target> # Name of data management target
4148 ... # Arguments of add_test(), DATA{} allowed
4149 )
4150 It passes its arguments through ExternalData_Expand_Arguments
4152 and then invokes the add_test() command using the results.
4153 ExternalData_Add_Target
4155 The ExternalData_Add_Target function creates a custom target to
4156 manage local instances of data files stored externally:
4157 ExternalData_Add_Target(
4159 <target> # Name of data management target
4160 [SHOW_PROGRESS <ON|OFF>] # Show progress during the download
4161 )
4162 It creates custom commands in the target as necessary to make
4164 data files available for each DATA{} reference previously evalu‐
4165 ated by other functions provided by this module. Data files may
4166 be fetched from one of the URL templates specified in the Exter‐
4167 nalData_URL_TEMPLATES variable, or may be found locally in one
4168 of the paths specified in the ExternalData_OBJECT_STORES vari‐
4169 able.
4170 New in version 3.20: The SHOW_PROGRESS argument may be passed to
4172 suppress progress information during the download of objects. If
4173 not provided, it defaults to OFF for Ninja and Ninja Multi-Con‐
4174 fig generators and ON otherwise.
4175 Typically only one target is needed to manage all external data
4178 within a project. Call this function once at the end of config‐
4179 uration after all data references have been processed.
4180 Module Variables
4182 The following variables configure behavior. They should be set before
4183 calling any of the functions provided by this module.
4184 ExternalData_BINARY_ROOT
4186 The ExternalData_BINARY_ROOT variable may be set to the direc‐
4187 tory to hold the real data files named by expanded DATA{} refer‐
4188 ences. The default is CMAKE_BINARY_DIR. The directory layout
4189 will mirror that of content links under External‐
4190 Data_SOURCE_ROOT.
4191 ExternalData_CUSTOM_SCRIPT_<key>
4193 New in version 3.2.
4194 Specify a full path to a .cmake custom fetch script identified
4197 by <key> in entries of the ExternalData_URL_TEMPLATES list. See
4198 Custom Fetch Scripts.
4199 ExternalData_LINK_CONTENT
4201 The ExternalData_LINK_CONTENT variable may be set to the name of
4202 a supported hash algorithm to enable automatic conversion of
4203 real data files referenced by the DATA{} syntax into content
4204 links. For each such <file> a content link named <file><ext> is
4205 created. The original file is renamed to the form .External‐
4206 Data_<algo>_<hash> to stage it for future transmission to one of
4207 the locations in the list of URL templates (by means outside the
4208 scope of this module). The data fetch rule created for the con‐
4209 tent link will use the staged object if it cannot be found using
4210 any URL template.
4211 ExternalData_NO_SYMLINKS
4213 New in version 3.3.
4214 The real data files named by expanded DATA{} references may be
4217 made available under ExternalData_BINARY_ROOT using symbolic
4218 links on some platforms. The ExternalData_NO_SYMLINKS variable
4219 may be set to disable use of symbolic links and enable use of
4220 copies instead.
4221 ExternalData_OBJECT_STORES
4223 The ExternalData_OBJECT_STORES variable may be set to a list of
4224 local directories that store objects using the layout
4225 <dir>/%(algo)/%(hash). These directories will be searched first
4226 for a needed object. If the object is not available in any
4227 store then it will be fetched remotely using the URL templates
4228 and added to the first local store listed. If no stores are
4229 specified the default is a location inside the build tree.
4230 ExternalData_SERIES_PARSE
4232 ExternalData_SERIES_PARSE_PREFIX
4234 ExternalData_SERIES_PARSE_NUMBER
4236 ExternalData_SERIES_PARSE_SUFFIX
4238 ExternalData_SERIES_MATCH
4240 See Referencing File Series.
4241 ExternalData_SOURCE_ROOT
4243 The ExternalData_SOURCE_ROOT variable may be set to the highest
4244 source directory containing any path named by a DATA{} refer‐
4245 ence. The default is CMAKE_SOURCE_DIR. External‐
4246 Data_SOURCE_ROOT and CMAKE_SOURCE_DIR must refer to directories
4247 within a single source distribution (e.g. they come together in
4248 one tarball).
4249 ExternalData_TIMEOUT_ABSOLUTE
4251 The ExternalData_TIMEOUT_ABSOLUTE variable sets the download ab‐
4252 solute timeout, in seconds, with a default of 300 seconds. Set
4253 to 0 to disable enforcement.
4254 ExternalData_TIMEOUT_INACTIVITY
4256 The ExternalData_TIMEOUT_INACTIVITY variable sets the download
4257 inactivity timeout, in seconds, with a default of 60 seconds.
4258 Set to 0 to disable enforcement.
4259 ExternalData_URL_ALGO_<algo>_<key>
4261 New in version 3.3.
4262 Specify a custom URL component to be substituted for URL tem‐
4265 plate placeholders of the form %(algo:<key>), where <key> is a
4266 valid C identifier, when fetching an object referenced via hash
4267 algorithm <algo>. If not defined, the default URL component is
4268 just <algo> for any <key>.
4269 ExternalData_URL_TEMPLATES
4271 The ExternalData_URL_TEMPLATES may be set to provide a list of
4272 URL templates using the placeholders %(algo) and %(hash) in each
4273 template. Data fetch rules try each URL template in order by
4274 substituting the hash algorithm name for %(algo) and the hash
4275 value for %(hash). Alternatively one may use %(algo:<key>) with
4276 ExternalData_URL_ALGO_<algo>_<key> variables to gain more flexi‐
4277 bility in remote URLs.
4278 Referencing Files
4280 Referencing Single Files
4281 The DATA{} syntax is literal and the <name> is a full or relative path
4282 within the source tree. The source tree must contain either a real
4283 data file at <name> or a "content link" at <name><ext> containing a
4284 hash of the real file using a hash algorithm corresponding to <ext>.
4285 For example, the argument DATA{img.png} may be satisfied by either a
4286 real img.png file in the current source directory or a img.png.md5 file
4287 containing its MD5 sum.
4288 New in version 3.8: Multiple content links of the same name with dif‐
4290 ferent hash algorithms are supported (e.g. img.png.sha256 and
4291 img.png.sha1) so long as they all correspond to the same real file.
4292 This allows objects to be fetched from sources indexed by different
4293 hash algorithms.
4294 Referencing File Series
4297 The DATA{} syntax can be told to fetch a file series using the form
4298 DATA{<name>,:}, where the : is literal. If the source tree contains a
4299 group of files or content links named like a series then a reference to
4300 one member adds rules to fetch all of them. Although all members of a
4301 series are fetched, only the file originally named by the DATA{} argu‐
4302 ment is substituted for it. The default configuration recognizes file
4303 series names ending with #.ext, _#.ext, .#.ext, or -#.ext where # is a
4304 sequence of decimal digits and .ext is any single extension. Configure
4305 it with a regex that parses <number> and <suffix> parts from the end of
4306 <name>:
4307 ExternalData_SERIES_PARSE = regex of the form (<number>)(<suffix>)$
4309 For more complicated cases set:
4311 ExternalData_SERIES_PARSE = regex with at least two () groups
4313 ExternalData_SERIES_PARSE_PREFIX = <prefix> regex group number, if any
4314 ExternalData_SERIES_PARSE_NUMBER = <number> regex group number
4315 ExternalData_SERIES_PARSE_SUFFIX = <suffix> regex group number
4316 Configure series number matching with a regex that matches the <number>
4318 part of series members named <prefix><number><suffix>:
4319 ExternalData_SERIES_MATCH = regex matching <number> in all series members
4321 Note that the <suffix> of a series does not include a hash-algorithm
4323 extension.
4324 Referencing Associated Files
4326 The DATA{} syntax can alternatively match files associated with the
4327 named file and contained in the same directory. Associated files may
4328 be specified by options using the syntax
4329 DATA{<name>,<opt1>,<opt2>,...}. Each option may specify one file by
4330 name or specify a regular expression to match file names using the syn‐
4331 tax REGEX:<regex>. For example, the arguments:
4332 DATA{MyData/MyInput.mhd,MyInput.img} # File pair
4334 DATA{MyData/MyFrames00.png,REGEX:MyFrames[0-9]+\\.png} # Series
4335 will pass MyInput.mha and MyFrames00.png on the command line but ensure
4337 that the associated files are present next to them.
4338 Referencing Directories
4340 The DATA{} syntax may reference a directory using a trailing slash and
4341 a list of associated files. The form DATA{<name>/,<opt1>,<opt2>,...}
4342 adds rules to fetch any files in the directory that match one of the
4343 associated file options. For example, the argument DATA{My‐
4344 DataDir/,REGEX:.*} will pass the full path to a MyDataDir directory on
4345 the command line and ensure that the directory contains files corre‐
4346 sponding to every file or content link in the MyDataDir source direc‐
4347 tory.
4348 New in version 3.3: In order to match associated files in subdirecto‐
4350 ries, specify a RECURSE: option, e.g. DATA{MyDataDir/,RE‐
4351 CURSE:,REGEX:.*}.
4352 Hash Algorithms
4355 The following hash algorithms are supported:
4356 %(algo) <ext> Description
4358 ------- ----- -----------
4359 MD5 .md5 Message-Digest Algorithm 5, RFC 1321
4360 SHA1 .sha1 US Secure Hash Algorithm 1, RFC 3174
4361 SHA224 .sha224 US Secure Hash Algorithms, RFC 4634
4362 SHA256 .sha256 US Secure Hash Algorithms, RFC 4634
4363 SHA384 .sha384 US Secure Hash Algorithms, RFC 4634
4364 SHA512 .sha512 US Secure Hash Algorithms, RFC 4634
4365 SHA3_224 .sha3-224 Keccak SHA-3
4366 SHA3_256 .sha3-256 Keccak SHA-3
4367 SHA3_384 .sha3-384 Keccak SHA-3
4368 SHA3_512 .sha3-512 Keccak SHA-3
4369 New in version 3.8: Added the SHA3_* hash algorithms.
4371 Note that the hashes are used only for unique data identification and
4374 download verification.
4375 Custom Fetch Scripts
4377 New in version 3.2.
4378 When a data file must be fetched from one of the URL templates speci‐
4381 fied in the ExternalData_URL_TEMPLATES variable, it is normally down‐
4382 loaded using the file(DOWNLOAD) command. One may specify usage of a
4383 custom fetch script by using a URL template of the form ExternalData‐
4384 CustomScript://<key>/<loc>. The <key> must be a C identifier, and the
4385 <loc> must contain the %(algo) and %(hash) placeholders. A variable
4386 corresponding to the key, ExternalData_CUSTOM_SCRIPT_<key>, must be set
4387 to the full path to a .cmake script file. The script will be included
4388 to perform the actual fetch, and provided with the following variables:
4389 ExternalData_CUSTOM_LOCATION
4391 When a custom fetch script is loaded, this variable is set to
4392 the location part of the URL, which will contain the substituted
4393 hash algorithm name and content hash value.
4394 ExternalData_CUSTOM_FILE
4396 When a custom fetch script is loaded, this variable is set to
4397 the full path to a file in which the script must store the
4398 fetched content. The name of the file is unspecified and should
4399 not be interpreted in any way.
4400 The custom fetch script is expected to store fetched content in the
4402 file or set a variable:
4403 ExternalData_CUSTOM_ERROR
4405 When a custom fetch script fails to fetch the requested content,
4406 it must set this variable to a short one-line message describing
4407 the reason for failure.
4408 ExternalProject
4410 Commands
4411 External Project Definition
4412 ExternalProject_Add
4413 The ExternalProject_Add() function creates a custom target to
4414 drive download, update/patch, configure, build, install and test
4415 steps of an external project:
4416 ExternalProject_Add(<name> [<option>...])
4418 The individual steps within the process can be driven indepen‐
4420 dently if required (e.g. for CDash submission) and extra custom
4421 steps can be defined, along with the ability to control the step
4422 dependencies. The directory structure used for the management of
4423 the external project can also be customized. The function sup‐
4424 ports a large number of options which can be used to tailor the
4425 external project behavior.
4426 Directory Options:
4428 Most of the time, the default directory layout is suffi‐
4429 cient. It is largely an implementation detail that the
4430 main project usually doesn't need to change. In some cir‐
4431 cumstances, however, control over the directory layout
4432 can be useful or necessary. The directory options are po‐
4433 tentially more useful from the point of view that the
4434 main build can use the ExternalProject_Get_Property()
4435 command to retrieve their values, thereby allowing the
4436 main project to refer to build artifacts of the external
4437 project.
4438 PREFIX <dir>
4440 Root directory for the external project. Unless
4441 otherwise noted below, all other directories asso‐
4442 ciated with the external project will be created
4443 under here.
4444 TMP_DIR <dir>
4446 Directory in which to store temporary files.
4447 STAMP_DIR <dir>
4449 Directory in which to store the timestamps of each
4450 step. Log files from individual steps are also
4451 created in here unless overridden by LOG_DIR (see
4452 Logging Options below).
4453 LOG_DIR <dir>
4455 New in version 3.14.
4456 Directory in which to store the logs of each step.
4459 DOWNLOAD_DIR <dir>
4461 Directory in which to store downloaded files be‐
4462 fore unpacking them. This directory is only used
4463 by the URL download method, all other download
4464 methods use SOURCE_DIR directly instead.
4465 SOURCE_DIR <dir>
4467 Source directory into which downloaded contents
4468 will be unpacked, or for non-URL download methods,
4469 the directory in which the repository should be
4470 checked out, cloned, etc. If no download method is
4471 specified, this must point to an existing direc‐
4472 tory where the external project has already been
4473 unpacked or cloned/checked out.
4474 NOTE:
4476 If a download method is specified, any existing
4477 contents of the source directory may be
4478 deleted. Only the URL download method checks
4479 whether this directory is either missing or
4480 empty before initiating the download, stopping
4481 with an error if it is not empty. All other
4482 download methods silently discard any previous
4483 contents of the source directory.
4484 BINARY_DIR <dir>
4486 Specify the build directory location. This option
4487 is ignored if BUILD_IN_SOURCE is enabled.
4488 INSTALL_DIR <dir>
4490 Installation prefix to be placed in the <IN‐
4491 STALL_DIR> placeholder. This does not actually
4492 configure the external project to install to the
4493 given prefix. That must be done by passing appro‐
4494 priate arguments to the external project configu‐
4495 ration step, e.g. using <INSTALL_DIR>.
4496 If any of the above ..._DIR options are not specified,
4498 their defaults are computed as follows. If the PREFIX op‐
4499 tion is given or the EP_PREFIX directory property is set,
4500 then an external project is built and installed under the
4501 specified prefix:
4502 TMP_DIR = <prefix>/tmp
4504 STAMP_DIR = <prefix>/src/<name>-stamp
4505 DOWNLOAD_DIR = <prefix>/src
4506 SOURCE_DIR = <prefix>/src/<name>
4507 BINARY_DIR = <prefix>/src/<name>-build
4508 INSTALL_DIR = <prefix>
4509 LOG_DIR = <STAMP_DIR>
4510 Otherwise, if the EP_BASE directory property is set then
4512 components of an external project are stored under the
4513 specified base:
4514 TMP_DIR = <base>/tmp/<name>
4516 STAMP_DIR = <base>/Stamp/<name>
4517 DOWNLOAD_DIR = <base>/Download/<name>
4518 SOURCE_DIR = <base>/Source/<name>
4519 BINARY_DIR = <base>/Build/<name>
4520 INSTALL_DIR = <base>/Install/<name>
4521 LOG_DIR = <STAMP_DIR>
4522 If no PREFIX, EP_PREFIX, or EP_BASE is specified, then
4524 the default is to set PREFIX to <name>-prefix. Relative
4525 paths are interpreted with respect to CMAKE_CURRENT_BI‐
4526 NARY_DIR at the point where ExternalProject_Add() is
4527 called.
4528 Download Step Options:
4530 A download method can be omitted if the SOURCE_DIR option
4531 is used to point to an existing non-empty directory. Oth‐
4532 erwise, one of the download methods below must be speci‐
4533 fied (multiple download methods should not be given) or a
4534 custom DOWNLOAD_COMMAND provided.
4535 DOWNLOAD_COMMAND <cmd>...
4537 Overrides the command used for the download step
4538 (generator expressions are supported). If this op‐
4539 tion is specified, all other download options will
4540 be ignored. Providing an empty string for <cmd>
4541 effectively disables the download step.
4542 URL Download
4544 URL <url1> [<url2>...]
4546 List of paths and/or URL(s) of the external
4547 project's source. When more than one URL is
4548 given, they are tried in turn until one
4549 succeeds. A URL may be an ordinary path in
4550 the local file system (in which case it
4551 must be the only URL provided) or any down‐
4552 loadable URL supported by the file(DOWN‐
4553 LOAD) command. A local filesystem path may
4554 refer to either an existing directory or to
4555 an archive file, whereas a URL is expected
4556 to point to a file which can be treated as
4557 an archive. When an archive is used, it
4558 will be unpacked automatically unless the
4559 DOWNLOAD_NO_EXTRACT option is set to pre‐
4560 vent it. The archive type is determined by
4561 inspecting the actual content rather than
4562 using logic based on the file extension.
4563 Changed in version 3.7: Multiple URLs are
4565 allowed.
4566 URL_HASH <algo>=<hashValue>
4569 Hash of the archive file to be downloaded.
4570 The argument should be of the form
4571 <algo>=<hashValue> where algo can be any of
4572 the hashing algorithms supported by the
4573 file() command. Specifying this option is
4574 strongly recommended for URL downloads, as
4575 it ensures the integrity of the downloaded
4576 content. It is also used as a check for a
4577 previously downloaded file, allowing con‐
4578 nection to the remote location to be
4579 avoided altogether if the local directory
4580 already has a file from an earlier download
4581 that matches the specified hash.
4582 URL_MD5 <md5>
4584 Equivalent to URL_HASH MD5=<md5>.
4585 DOWNLOAD_NAME <fname>
4587 File name to use for the downloaded file.
4588 If not given, the end of the URL is used to
4589 determine the file name. This option is
4590 rarely needed, the default name is gener‐
4591 ally suitable and is not normally used out‐
4592 side of code internal to the ExternalPro‐
4593 ject module.
4594 DOWNLOAD_NO_EXTRACT <bool>
4596 New in version 3.6.
4597 Allows the extraction part of the download
4600 step to be disabled by passing a boolean
4601 true value for this option. If this option
4602 is not given, the downloaded contents will
4603 be unpacked automatically if required. If
4604 extraction has been disabled, the full path
4605 to the downloaded file is available as
4606 <DOWNLOADED_FILE> in subsequent steps or as
4607 the property DOWNLOADED_FILE with the
4608 ExternalProject_Get_Property() command.
4609 DOWNLOAD_NO_PROGRESS <bool>
4611 Can be used to disable logging the download
4612 progress. If this option is not given,
4613 download progress messages will be logged.
4614 TIMEOUT <seconds>
4616 Maximum time allowed for file download op‐
4617 erations.
4618 INACTIVITY_TIMEOUT <seconds>
4620 New in version 3.19.
4621 Terminate the operation after a period of
4624 inactivity.
4625 HTTP_USERNAME <username>
4627 New in version 3.7.
4628 Username for the download operation if au‐
4631 thentication is required.
4632 HTTP_PASSWORD <password>
4634 New in version 3.7.
4635 Password for the download operation if au‐
4638 thentication is required.
4639 HTTP_HEADER <header1> [<header2>...]
4641 New in version 3.7.
4642 Provides an arbitrary list of HTTP headers
4645 for the download operation. This can be
4646 useful for accessing content in systems
4647 like AWS, etc.
4648 TLS_VERIFY <bool>
4650 Specifies whether certificate verification
4651 should be performed for https URLs. If this
4652 option is not provided, the default behav‐
4653 ior is determined by the CMAKE_TLS_VERIFY
4654 variable (see file(DOWNLOAD)). If that is
4655 also not set, certificate verification will
4656 not be performed. In situations where
4657 URL_HASH cannot be provided, this option
4658 can be an alternative verification measure.
4659 Changed in version 3.6: This option also
4661 applies to git clone invocations.
4662 TLS_CAINFO <file>
4665 Specify a custom certificate authority file
4666 to use if TLS_VERIFY is enabled. If this
4667 option is not specified, the value of the
4668 CMAKE_TLS_CAINFO variable will be used in‐
4669 stead (see file(DOWNLOAD))
4670 NETRC <level>
4672 New in version 3.11.
4673 Specify whether the .netrc file is to be
4676 used for operation. If this option is not
4677 specified, the value of the CMAKE_NETRC
4678 variable will be used instead (see
4679 file(DOWNLOAD)) Valid levels are:
4680 IGNORED
4682 The .netrc file is ignored. This is
4683 the default.
4684 OPTIONAL
4686 The .netrc file is optional, and in‐
4687 formation in the URL is preferred.
4688 The file will be scanned to find
4689 which ever information is not speci‐
4690 fied in the URL.
4691 REQUIRED
4693 The .netrc file is required, and in‐
4694 formation in the URL is ignored.
4695 NETRC_FILE <file>
4697 New in version 3.11.
4698 Specify an alternative .netrc file to the
4701 one in your home directory if the NETRC
4702 level is OPTIONAL or REQUIRED. If this op‐
4703 tion is not specified, the value of the
4704 CMAKE_NETRC_FILE variable will be used in‐
4705 stead (see file(DOWNLOAD))
4706 New in version 3.1: Added support for tbz2,
4708 .tar.xz, .txz, and .7z extensions.
4709 Git NOTE: A git version of 1.6.5 or later is required
4712 if this download method is used.
4713 GIT_REPOSITORY <url>
4715 URL of the git repository. Any URL under‐
4716 stood by the git command may be used.
4717 GIT_TAG <tag>
4719 Git branch name, tag or commit hash. Note
4720 that branch names and tags should generally
4721 be specified as remote names (i.e. ori‐
4722 gin/myBranch rather than simply myBranch).
4723 This ensures that if the remote end has its
4724 tag moved or branch rebased or history
4725 rewritten, the local clone will still be
4726 updated correctly. In general, however,
4727 specifying a commit hash should be pre‐
4728 ferred for a number of reasons:
4729 • If the local clone already has the commit
4731 corresponding to the hash, no git fetch
4732 needs to be performed to check for
4733 changes each time CMake is re-run. This
4734 can result in a significant speed up if
4735 many external projects are being used.
4736 • Using a specific git hash ensures that
4738 the main project's own history is fully
4739 traceable to a specific point in the ex‐
4740 ternal project's evolution. If a branch
4741 or tag name is used instead, then check‐
4742 ing out a specific commit of the main
4743 project doesn't necessarily pin the whole
4744 build to a specific point in the life of
4745 the external project. The lack of such
4746 deterministic behavior makes the main
4747 project lose traceability and repeatabil‐
4748 ity.
4749 If GIT_SHALLOW is enabled then GIT_TAG
4751 works only with branch names and tags. A
4752 commit hash is not allowed.
4753 GIT_REMOTE_NAME <name>
4755 The optional name of the remote. If this
4756 option is not specified, it defaults to
4757 origin.
4758 GIT_SUBMODULES <module>...
4760 Specific git submodules that should also be
4761 updated. If this option is not provided,
4762 all git submodules will be updated.
4763 Changed in version 3.16: When CMP0097 is
4765 set to NEW, if this value is set to an
4766 empty string then no submodules are ini‐
4767 tialized or updated.
4768 GIT_SUBMODULES_RECURSE <bool>
4771 New in version 3.17.
4772 Specify whether git submodules (if any)
4775 should update recursively by passing the
4776 --recursive flag to git submodule update.
4777 If not specified, the default is on.
4778 GIT_SHALLOW <bool>
4780 New in version 3.6.
4781 When this option is enabled, the git clone
4784 operation will be given the --depth 1 op‐
4785 tion. This performs a shallow clone, which
4786 avoids downloading the whole history and
4787 instead retrieves just the commit denoted
4788 by the GIT_TAG option.
4789 GIT_PROGRESS <bool>
4791 New in version 3.8.
4792 When enabled, this option instructs the git
4795 clone operation to report its progress by
4796 passing it the --progress option. Without
4797 this option, the clone step for large
4798 projects may appear to make the build
4799 stall, since nothing will be logged until
4800 the clone operation finishes. While this
4801 option can be used to provide progress to
4802 prevent the appearance of the build having
4803 stalled, it may also make the build overly
4804 noisy if lots of external projects are
4805 used.
4806 GIT_CONFIG <option1> [<option2>...]
4808 New in version 3.8.
4809 Specify a list of config options to pass to
4812 git clone. Each option listed will be
4813 transformed into its own --config <option>
4814 on the git clone command line, with each
4815 option required to be in the form
4816 key=value.
4817 GIT_REMOTE_UPDATE_STRATEGY <strategy>
4819 New in version 3.18.
4820 When GIT_TAG refers to a remote branch,
4823 this option can be used to specify how the
4824 update step behaves. The <strategy> must
4825 be one of the following:
4826 CHECKOUT
4828 Ignore the local branch and always
4829 checkout the branch specified by
4830 GIT_TAG.
4831 REBASE Try to rebase the current branch to
4833 the one specified by GIT_TAG. If
4834 there are local uncommitted changes,
4835 they will be stashed first and
4836 popped again after rebasing. If re‐
4837 basing or popping stashed changes
4838 fail, abort the rebase and halt with
4839 an error. When GIT_REMOTE_UP‐
4840 DATE_STRATEGY is not present, this
4841 is the default strategy unless the
4842 default has been overridden with
4843 CMAKE_EP_GIT_REMOTE_UPDATE_STRATEGY
4844 (see below).
4845 REBASE_CHECKOUT
4847 Same as REBASE except if the rebase
4848 fails, an annotated tag will be cre‐
4849 ated at the original HEAD position
4850 from before the rebase and then
4851 checkout GIT_TAG just like the
4852 CHECKOUT strategy. The message
4853 stored on the annotated tag will
4854 give information about what was at‐
4855 tempted and the tag name will in‐
4856 clude a timestamp so that each
4857 failed run will add a new tag. This
4858 strategy ensures no changes will be
4859 lost, but updates should always suc‐
4860 ceed if GIT_TAG refers to a valid
4861 ref unless there are uncommitted
4862 changes that cannot be popped suc‐
4863 cessfully.
4864 The variable CMAKE_EP_GIT_REMOTE_UP‐
4866 DATE_STRATEGY can be set to override the
4867 default strategy. This variable should not
4868 be set by a project, it is intended for the
4869 user to set. It is primarily intended for
4870 use in continuous integration scripts to
4871 ensure that when history is rewritten on a
4872 remote branch, the build doesn't end up
4873 with unintended changes or failed builds
4874 resulting from conflicts during rebase op‐
4875 erations.
4876 Subversion
4878 SVN_REPOSITORY <url>
4880 URL of the Subversion repository.
4881 SVN_REVISION -r<rev>
4883 Revision to checkout from the Subversion
4884 repository.
4885 SVN_USERNAME <username>
4887 Username for the Subversion checkout and
4888 update.
4889 SVN_PASSWORD <password>
4891 Password for the Subversion checkout and
4892 update.
4893 SVN_TRUST_CERT <bool>
4895 Specifies whether to trust the Subversion
4896 server site certificate. If enabled, the
4897 --trust-server-cert option is passed to the
4898 svn checkout and update commands.
4899 Mercurial
4901 HG_REPOSITORY <url>
4903 URL of the mercurial repository.
4904 HG_TAG <tag>
4906 Mercurial branch name, tag or commit id.
4907 CVS
4909 CVS_REPOSITORY <cvsroot>
4911 CVSROOT of the CVS repository.
4912 CVS_MODULE <mod>
4914 Module to checkout from the CVS repository.
4915 CVS_TAG <tag>
4917 Tag to checkout from the CVS repository.
4918 Update/Patch Step Options:
4920 Whenever CMake is re-run, by default the external
4921 project's sources will be updated if the download method
4922 supports updates (e.g. a git repository would be checked
4923 if the GIT_TAG does not refer to a specific commit).
4924 UPDATE_COMMAND <cmd>...
4926 Overrides the download method's update step with a
4927 custom command. The command may use generator ex‐
4928 pressions.
4929 UPDATE_DISCONNECTED <bool>
4931 New in version 3.2.
4932 When enabled, this option causes the update step
4935 to be skipped. It does not, however, prevent the
4936 download step. The update step can still be added
4937 as a step target (see
4938 ExternalProject_Add_StepTargets()) and called man‐
4939 ually. This is useful if you want to allow devel‐
4940 opers to build the project when disconnected from
4941 the network (the network may still be needed for
4942 the download step though).
4943 When this option is present, it is generally ad‐
4945 visable to make the value a cache variable under
4946 the developer's control rather than hard-coding
4947 it. If this option is not present, the default
4948 value is taken from the EP_UPDATE_DISCONNECTED di‐
4949 rectory property. If that is also not defined, up‐
4950 dates are performed as normal. The EP_UPDATE_DIS‐
4951 CONNECTED directory property is intended as a con‐
4952 venience for controlling the UPDATE_DISCONNECTED
4953 behavior for an entire section of a project's di‐
4954 rectory hierarchy and may be a more convenient
4955 method of giving developers control over whether
4956 or not to perform updates (assuming the project
4957 also provides a cache variable or some other con‐
4958 venient method for setting the directory prop‐
4959 erty).
4960 This may cause a step target to be created auto‐
4962 matically for the download step. See policy
4963 CMP0114.
4964 PATCH_COMMAND <cmd>...
4966 Specifies a custom command to patch the sources
4967 after an update. By default, no patch command is
4968 defined. Note that it can be quite difficult to
4969 define an appropriate patch command that performs
4970 robustly, especially for download methods such as
4971 git where changing the GIT_TAG will not discard
4972 changes from a previous patch, but the patch com‐
4973 mand will be called again after updating to the
4974 new tag.
4975 Configure Step Options:
4977 The configure step is run after the download and update
4978 steps. By default, the external project is assumed to be
4979 a CMake project, but this can be overridden if required.
4980 CONFIGURE_COMMAND <cmd>...
4982 The default configure command runs CMake with op‐
4983 tions based on the main project. For non-CMake ex‐
4984 ternal projects, the CONFIGURE_COMMAND option must
4985 be used to override this behavior (generator ex‐
4986 pressions are supported). For projects that re‐
4987 quire no configure step, specify this option with
4988 an empty string as the command to execute.
4989 CMAKE_COMMAND /.../cmake
4991 Specify an alternative cmake executable for the
4992 configure step (use an absolute path). This is
4993 generally not recommended, since it is usually de‐
4994 sirable to use the same CMake version throughout
4995 the whole build. This option is ignored if a cus‐
4996 tom configure command has been specified with CON‐
4997 FIGURE_COMMAND.
4998 CMAKE_GENERATOR <gen>
5000 Override the CMake generator used for the config‐
5001 ure step. Without this option, the same generator
5002 as the main build will be used. This option is ig‐
5003 nored if a custom configure command has been spec‐
5004 ified with the CONFIGURE_COMMAND option.
5005 CMAKE_GENERATOR_PLATFORM <platform>
5007 New in version 3.1.
5008 Pass a generator-specific platform name to the
5011 CMake command (see CMAKE_GENERATOR_PLATFORM). It
5012 is an error to provide this option without the
5013 CMAKE_GENERATOR option.
5014 CMAKE_GENERATOR_TOOLSET <toolset>
5016 Pass a generator-specific toolset name to the
5017 CMake command (see CMAKE_GENERATOR_TOOLSET). It is
5018 an error to provide this option without the
5019 CMAKE_GENERATOR option.
5020 CMAKE_GENERATOR_INSTANCE <instance>
5022 New in version 3.11.
5023 Pass a generator-specific instance selection to
5026 the CMake command (see CMAKE_GENERATOR_INSTANCE).
5027 It is an error to provide this option without the
5028 CMAKE_GENERATOR option.
5029 CMAKE_ARGS <arg>...
5031 The specified arguments are passed to the cmake
5032 command line. They can be any argument the cmake
5033 command understands, not just cache values defined
5034 by -D... arguments (see also CMake Options).
5035 New in version 3.3: Arguments may use generator
5037 expressions.
5038 CMAKE_CACHE_ARGS <arg>...
5041 This is an alternate way of specifying cache vari‐
5042 ables where command line length issues may become
5043 a problem. The arguments are expected to be in the
5044 form -Dvar:STRING=value, which are then trans‐
5045 formed into CMake set() commands with the FORCE
5046 option used. These set() commands are written to a
5047 pre-load script which is then applied using the
5048 cmake -C command line option.
5049 New in version 3.3: Arguments may use generator
5051 expressions.
5052 CMAKE_CACHE_DEFAULT_ARGS <arg>...
5055 New in version 3.2.
5056 This is the same as the CMAKE_CACHE_ARGS option
5059 except the set() commands do not include the FORCE
5060 keyword. This means the values act as initial de‐
5061 faults only and will not override any variables
5062 already set from a previous run. Use this option
5063 with care, as it can lead to different behavior
5064 depending on whether the build starts from a fresh
5065 build directory or re-uses previous build con‐
5066 tents.
5067 New in version 3.15: If the CMake generator is the
5069 Green Hills MULTI and not overridden then the
5070 original project's settings for the GHS toolset
5071 and target system customization cache variables
5072 are propagated into the external project.
5073 SOURCE_SUBDIR <dir>
5076 New in version 3.7.
5077 When no CONFIGURE_COMMAND option is specified, the
5080 configure step assumes the external project has a
5081 CMakeLists.txt file at the top of its source tree
5082 (i.e. in SOURCE_DIR). The SOURCE_SUBDIR option can
5083 be used to point to an alternative directory
5084 within the source tree to use as the top of the
5085 CMake source tree instead. This must be a relative
5086 path and it will be interpreted as being relative
5087 to SOURCE_DIR.
5088 New in version 3.14: When BUILD_IN_SOURCE option
5090 is enabled, the BUILD_COMMAND is used to point to
5091 an alternative directory within the source tree.
5092 CONFIGURE_HANDLED_BY_BUILD <bool>
5095 New in version 3.20.
5096 Enabling this option relaxes the dependencies of
5099 the configure step on other external projects to
5100 order-only. This means the configure step will be
5101 executed after its external project dependencies
5102 are built but it will not be marked dirty when one
5103 of its external project dependencies is rebuilt.
5104 This option can be enabled when the build step is
5105 smart enough to figure out if the configure step
5106 needs to be rerun. CMake and Meson are examples of
5107 build systems whose build step is smart enough to
5108 know if the configure step needs to be rerun.
5109 Build Step Options:
5111 If the configure step assumed the external project uses
5112 CMake as its build system, the build step will also. Oth‐
5113 erwise, the build step will assume a Makefile-based build
5114 and simply run make with no arguments as the default
5115 build step. This can be overridden with custom build com‐
5116 mands if required.
5117 BUILD_COMMAND <cmd>...
5119 Overrides the default build command (generator ex‐
5120 pressions are supported). If this option is not
5121 given, the default build command will be chosen to
5122 integrate with the main build in the most appro‐
5123 priate way (e.g. using recursive make for Makefile
5124 generators or cmake --build if the project uses a
5125 CMake build). This option can be specified with an
5126 empty string as the command to make the build step
5127 do nothing.
5128 BUILD_IN_SOURCE <bool>
5130 When this option is enabled, the build will be
5131 done directly within the external project's source
5132 tree. This should generally be avoided, the use of
5133 a separate build directory is usually preferred,
5134 but it can be useful when the external project as‐
5135 sumes an in-source build. The BINARY_DIR option
5136 should not be specified if building in-source.
5137 BUILD_ALWAYS <bool>
5139 Enabling this option forces the build step to al‐
5140 ways be run. This can be the easiest way to ro‐
5141 bustly ensure that the external project's own
5142 build dependencies are evaluated rather than rely‐
5143 ing on the default success timestamp-based method.
5144 This option is not normally needed unless develop‐
5145 ers are expected to modify something the external
5146 project's build depends on in a way that is not
5147 detectable via the step target dependencies (e.g.
5148 SOURCE_DIR is used without a download method and
5149 developers might modify the sources in
5150 SOURCE_DIR).
5151 BUILD_BYPRODUCTS <file>...
5153 New in version 3.2.
5154 Specifies files that will be generated by the
5157 build command but which might or might not have
5158 their modification time updated by subsequent
5159 builds. These ultimately get passed through as
5160 BYPRODUCTS to the build step's own underlying call
5161 to add_custom_command().
5162 Install Step Options:
5164 If the configure step assumed the external project uses
5165 CMake as its build system, the install step will also.
5166 Otherwise, the install step will assume a Makefile-based
5167 build and simply run make install as the default build
5168 step. This can be overridden with custom install commands
5169 if required.
5170 INSTALL_COMMAND <cmd>...
5172 The external project's own install step is invoked
5173 as part of the main project's build. It is done
5174 after the external project's build step and may be
5175 before or after the external project's test step
5176 (see the TEST_BEFORE_INSTALL option below). The
5177 external project's install rules are not part of
5178 the main project's install rules, so if anything
5179 from the external project should be installed as
5180 part of the main build, these need to be specified
5181 in the main build as additional install() com‐
5182 mands. The default install step builds the install
5183 target of the external project, but this can be
5184 overridden with a custom command using this option
5185 (generator expressions are supported). Passing an
5186 empty string as the <cmd> makes the install step
5187 do nothing.
5188 Test Step Options:
5190 The test step is only defined if at least one of the fol‐
5191 lowing TEST_... options are provided.
5192 TEST_COMMAND <cmd>...
5194 Overrides the default test command (generator ex‐
5195 pressions are supported). If this option is not
5196 given, the default behavior of the test step is to
5197 build the external project's own test target. This
5198 option can be specified with <cmd> as an empty
5199 string, which allows the test step to still be de‐
5200 fined, but it will do nothing. Do not specify any
5201 of the other TEST_... options if providing an
5202 empty string as the test command, but prefer to
5203 omit all TEST_... options altogether if the test
5204 step target is not needed.
5205 TEST_BEFORE_INSTALL <bool>
5207 When this option is enabled, the test step will be
5208 executed before the install step. The default be‐
5209 havior is for the test step to run after the in‐
5210 stall step.
5211 TEST_AFTER_INSTALL <bool>
5213 This option is mainly useful as a way to indicate
5214 that the test step is desired but all default be‐
5215 havior is sufficient. Specifying this option with
5216 a boolean true value ensures the test step is de‐
5217 fined and that it comes after the install step. If
5218 both TEST_BEFORE_INSTALL and TEST_AFTER_INSTALL
5219 are enabled, the latter is silently ignored.
5220 TEST_EXCLUDE_FROM_MAIN <bool>
5222 New in version 3.2.
5223 If enabled, the main build's default ALL target
5226 will not depend on the test step. This can be a
5227 useful way of ensuring the test step is defined
5228 but only gets invoked when manually requested.
5229 This may cause a step target to be created auto‐
5230 matically for either the install or build step.
5231 See policy CMP0114.
5232 Output Logging Options:
5234 Each of the following LOG_... options can be used to wrap
5235 the relevant step in a script to capture its output to
5236 files. The log files will be created in LOG_DIR if sup‐
5237 plied or otherwise the STAMP_DIR directory with step-spe‐
5238 cific file names.
5239 LOG_DOWNLOAD <bool>
5241 When enabled, the output of the download step is
5242 logged to files.
5243 LOG_UPDATE <bool>
5245 When enabled, the output of the update step is
5246 logged to files.
5247 LOG_PATCH <bool>
5249 New in version 3.14.
5250 When enabled, the output of the patch step is
5253 logged to files.
5254 LOG_CONFIGURE <bool>
5256 When enabled, the output of the configure step is
5257 logged to files.
5258 LOG_BUILD <bool>
5260 When enabled, the output of the build step is
5261 logged to files.
5262 LOG_INSTALL <bool>
5264 When enabled, the output of the install step is
5265 logged to files.
5266 LOG_TEST <bool>
5268 When enabled, the output of the test step is
5269 logged to files.
5270 LOG_MERGED_STDOUTERR <bool>
5272 New in version 3.14.
5273 When enabled, stdout and stderr will be merged for
5276 any step whose output is being logged to files.
5277 LOG_OUTPUT_ON_FAILURE <bool>
5279 New in version 3.14.
5280 This option only has an effect if at least one of
5283 the other LOG_<step> options is enabled. If an
5284 error occurs for a step which has logging to file
5285 enabled, that step's output will be printed to the
5286 console if LOG_OUTPUT_ON_FAILURE is set to true.
5287 For cases where a large amount of output is
5288 recorded, just the end of that output may be
5289 printed to the console.
5290 Terminal Access Options:
5292 New in version 3.4.
5293 Steps can be given direct access to the terminal in some
5296 cases. Giving a step access to the terminal may allow it
5297 to receive terminal input if required, such as for au‐
5298 thentication details not provided by other options. With
5299 the Ninja generator, these options place the steps in the
5300 console job pool. Each step can be given access to the
5301 terminal individually via the following options:
5302 USES_TERMINAL_DOWNLOAD <bool>
5304 Give the download step access to the terminal.
5305 USES_TERMINAL_UPDATE <bool>
5307 Give the update step access to the terminal.
5308 USES_TERMINAL_CONFIGURE <bool>
5310 Give the configure step access to the terminal.
5311 USES_TERMINAL_BUILD <bool>
5313 Give the build step access to the terminal.
5314 USES_TERMINAL_INSTALL <bool>
5316 Give the install step access to the terminal.
5317 USES_TERMINAL_TEST <bool>
5319 Give the test step access to the terminal.
5320 Target Options:
5322 DEPENDS <targets>...
5324 Specify other targets on which the external
5325 project depends. The other targets will be brought
5326 up to date before any of the external project's
5327 steps are executed. Because the external project
5328 uses additional custom targets internally for each
5329 step, the DEPENDS option is the most convenient
5330 way to ensure all of those steps depend on the
5331 other targets. Simply doing add_dependen‐
5332 cies(<name> <targets>) will not make any of the
5333 steps dependent on <targets>.
5334 EXCLUDE_FROM_ALL <bool>
5336 When enabled, this option excludes the external
5337 project from the default ALL target of the main
5338 build.
5339 STEP_TARGETS <step-target>...
5341 Generate custom targets for the specified steps.
5342 This is required if the steps need to be triggered
5343 manually or if they need to be used as dependen‐
5344 cies of other targets. If this option is not spec‐
5345 ified, the default value is taken from the
5346 EP_STEP_TARGETS directory property. See
5347 ExternalProject_Add_StepTargets() below for fur‐
5348 ther discussion of the effects of this option.
5349 INDEPENDENT_STEP_TARGETS <step-target>...
5351 Deprecated since version 3.19: This is allowed
5352 only if policy CMP0114 is not set to NEW.
5353 Generates custom targets for the specified steps
5356 and prevent these targets from having the usual
5357 dependencies applied to them. If this option is
5358 not specified, the default value is taken from the
5359 EP_INDEPENDENT_STEP_TARGETS directory property.
5360 This option is mostly useful for allowing individ‐
5361 ual steps to be driven independently, such as for
5362 a CDash setup where each step should be initiated
5363 and reported individually rather than as one whole
5364 build. See ExternalProject_Add_StepTargets() below
5365 for further discussion of the effects of this op‐
5366 tion.
5367 Miscellaneous Options:
5369 LIST_SEPARATOR <sep>
5371 For any of the various ..._COMMAND options, re‐
5372 place ; with <sep> in the specified command lines.
5373 This can be useful where list variables may be
5374 given in commands where they should end up as
5375 space-separated arguments (<sep> would be a single
5376 space character string in this case).
5377 COMMAND <cmd>...
5379 Any of the other ..._COMMAND options can have ad‐
5380 ditional commands appended to them by following
5381 them with as many COMMAND ... options as needed
5382 (generator expressions are supported). For exam‐
5383 ple:
5384 ExternalProject_Add(example
5386 ... # Download options, etc.
5387 BUILD_COMMAND ${CMAKE_COMMAND} -E echo "Starting $<CONFIG> build"
5388 COMMAND ${CMAKE_COMMAND} --build <BINARY_DIR> --config $<CONFIG>
5389 COMMAND ${CMAKE_COMMAND} -E echo "$<CONFIG> build complete"
5390 )
5391 It should also be noted that each build step is created via a
5393 call to ExternalProject_Add_Step(). See that command's documen‐
5394 tation for the automatic substitutions that are supported for
5395 some options.
5396 Obtaining Project Properties
5398 ExternalProject_Get_Property
5399 The ExternalProject_Get_Property() function retrieves external
5400 project target properties:
5401 ExternalProject_Get_Property(<name> <prop1> [<prop2>...])
5403 The function stores property values in variables of the same
5405 name. Property names correspond to the keyword argument names of
5406 ExternalProject_Add(). For example, the source directory might
5407 be retrieved like so:
5408 ExternalProject_Get_property(myExtProj SOURCE_DIR)
5410 message("Source dir of myExtProj = ${SOURCE_DIR}")
5411 Explicit Step Management
5413 The ExternalProject_Add() function on its own is often sufficient for
5414 incorporating an external project into the main build. Certain scenar‐
5415 ios require additional work to implement desired behavior, such as
5416 adding in a custom step or making steps available as manually trigger‐
5417 able targets. The ExternalProject_Add_Step(), ExternalProject_Add_Step‐
5418 Targets() and ExternalProject_Add_StepDependencies functions provide
5419 the lower level control needed to implement such step-level capabili‐
5420 ties.
5421 ExternalProject_Add_Step
5423 The ExternalProject_Add_Step() function specifies an additional
5424 custom step for an external project defined by an earlier call
5425 to ExternalProject_Add():
5426 ExternalProject_Add_Step(<name> <step> [<option>...])
5428 <name> is the same as the name passed to the original call to
5430 ExternalProject_Add(). The specified <step> must not be one of
5431 the pre-defined steps (mkdir, download, update, patch, config‐
5432 ure, build, install or test). The supported options are:
5433 COMMAND <cmd>...
5435 The command line to be executed by this custom step (gen‐
5436 erator expressions are supported). This option can be re‐
5437 peated multiple times to specify multiple commands to be
5438 executed in order.
5439 COMMENT <text>...
5441 Text to be printed when the custom step executes.
5442 DEPENDEES <step>...
5444 Other steps (custom or pre-defined) on which this step
5445 depends.
5446 DEPENDERS <step>...
5448 Other steps (custom or pre-defined) that depend on this
5449 new custom step.
5450 DEPENDS <file>...
5452 Files on which this custom step depends.
5453 INDEPENDENT <bool>
5455 New in version 3.19.
5456 Specifies whether this step is independent of the exter‐
5459 nal dependencies specified by the ExternalProject_Add()'s
5460 DEPENDS option. The default is FALSE. Steps marked as
5461 independent may depend only on other steps marked inde‐
5462 pendent. See policy CMP0114.
5463 Note that this use of the term "independent" refers only
5465 to independence from external targets specified by the
5466 DEPENDS option and is orthogonal to a step's dependencies
5467 on other steps.
5468 If a step target is created for an independent step by
5470 the ExternalProject_Add() STEP_TARGETS option or by the
5471 ExternalProject_Add_StepTargets() function, it will not
5472 depend on the external targets, but may depend on targets
5473 for other steps.
5474 BYPRODUCTS <file>...
5476 New in version 3.2.
5477 Files that will be generated by this custom step but
5480 which might or might not have their modification time up‐
5481 dated by subsequent builds. This list of files will ulti‐
5482 mately be passed through as the BYPRODUCTS option to the
5483 add_custom_command() used to implement the custom step
5484 internally.
5485 ALWAYS <bool>
5487 When enabled, this option specifies that the custom step
5488 should always be run (i.e. that it is always considered
5489 out of date).
5490 EXCLUDE_FROM_MAIN <bool>
5492 When enabled, this option specifies that the external
5493 project's main target does not depend on the custom step.
5494 This may cause step targets to be created automatically
5495 for the steps on which this step depends. See policy
5496 CMP0114.
5497 WORKING_DIRECTORY <dir>
5499 Specifies the working directory to set before running the
5500 custom step's command. If this option is not specified,
5501 the directory will be the value of the CMAKE_CURRENT_BI‐
5502 NARY_DIR at the point where ExternalProject_Add_Step()
5503 was called.
5504 LOG <bool>
5506 If set, this causes the output from the custom step to be
5507 captured to files in the external project's LOG_DIR if
5508 supplied or STAMP_DIR.
5509 USES_TERMINAL <bool>
5511 If enabled, this gives the custom step direct access to
5512 the terminal if possible.
5513 The command line, comment, working directory and byproducts of
5515 every standard and custom step are processed to replace the to‐
5516 kens <SOURCE_DIR>, <SOURCE_SUBDIR>, <BINARY_DIR>, <INSTALL_DIR>
5517 <TMP_DIR>, <DOWNLOAD_DIR> and <DOWNLOADED_FILE> with their cor‐
5518 responding property values defined in the original call to
5519 ExternalProject_Add().
5520 New in version 3.3: Token replacement is extended to byproducts.
5522 New in version 3.11: The <DOWNLOAD_DIR> substitution token.
5525 ExternalProject_Add_StepTargets
5528 The ExternalProject_Add_StepTargets() function generates targets
5529 for the steps listed. The name of each created target will be of
5530 the form <name>-<step>:
5531 ExternalProject_Add_StepTargets(<name> <step1> [<step2>...])
5533 Creating a target for a step allows it to be used as a depen‐
5535 dency of another target or to be triggered manually. Having tar‐
5536 gets for specific steps also allows them to be driven indepen‐
5537 dently of each other by specifying targets on build command
5538 lines. For example, you may be submitting to a sub-project based
5539 dashboard where you want to drive the configure portion of the
5540 build, then submit to the dashboard, followed by the build por‐
5541 tion, followed by tests. If you invoke a custom target that de‐
5542 pends on a step halfway through the step dependency chain, then
5543 all the previous steps will also run to ensure everything is up
5544 to date.
5545 Internally, ExternalProject_Add() calls
5547 ExternalProject_Add_Step() to create each step. If any STEP_TAR‐
5548 GETS were specified, then ExternalProject_Add_StepTargets() will
5549 also be called after ExternalProject_Add_Step(). Even if a step
5550 is not mentioned in the STEP_TARGETS option, ExternalPro‐
5551 ject_Add_StepTargets() can still be called later to manually de‐
5552 fine a target for the step.
5553 The STEP_TARGETS option for ExternalProject_Add() is generally
5555 the easiest way to ensure targets are created for specific steps
5556 of interest. For custom steps, ExternalProject_Add_StepTar‐
5557 gets() must be called explicitly if a target should also be cre‐
5558 ated for that custom step. An alternative to these two options
5559 is to populate the EP_STEP_TARGETS directory property. It acts
5560 as a default for the step target options and can save having to
5561 repeatedly specify the same set of step targets when multiple
5562 external projects are being defined.
5563 New in version 3.19: If CMP0114 is set to NEW, step targets are
5565 fully responsible for holding the custom commands implementing
5566 their steps. The primary target created by ExternalProject_Add
5567 depends on the step targets, and the step targets depend on each
5568 other. The target-level dependencies match the file-level de‐
5569 pendencies used by the custom commands for each step. The tar‐
5570 gets for steps created with ExternalProject_Add_Step()'s INDE‐
5571 PENDENT option do not depend on the external targets specified
5572 by ExternalProject_Add()'s DEPENDS option. The predefined steps
5573 mkdir, download, update, and patch are independent.
5574 If CMP0114 is not NEW, the following deprecated behavior is
5577 available:
5578 • A deprecated NO_DEPENDS option may be specified immediately
5580 after the <name> and before the first step. If the NO_DEPENDS
5581 option is specified, the step target will not depend on the
5582 dependencies of the external project (i.e. on any dependencies
5583 of the <name> custom target created by ExternalProject_Add()).
5584 This is usually safe for the download, update and patch steps,
5585 since they do not typically require that the dependencies are
5586 updated and built. Using NO_DEPENDS for any of the other
5587 pre-defined steps, however, may break parallel builds. Only
5588 use NO_DEPENDS where it is certain that the named steps gen‐
5589 uinely do not have dependencies. For custom steps, consider
5590 whether or not the custom commands require the dependencies to
5591 be configured, built and installed.
5592 • The INDEPENDENT_STEP_TARGETS option for ExternalProject_Add(),
5594 or the EP_INDEPENDENT_STEP_TARGETS directory property, tells
5595 the function to call ExternalProject_Add_StepTargets() inter‐
5596 nally using the NO_DEPENDS option for the specified steps.
5597 ExternalProject_Add_StepDependencies
5599 New in version 3.2.
5600 The ExternalProject_Add_StepDependencies() function can be used
5603 to add dependencies to a step. The dependencies added must be
5604 targets CMake already knows about (these can be ordinary exe‐
5605 cutable or library targets, custom targets or even step targets
5606 of another external project):
5607 ExternalProject_Add_StepDependencies(<name> <step> <target1> [<target2>...])
5609 This function takes care to set both target and file level de‐
5611 pendencies and will ensure that parallel builds will not break.
5612 It should be used instead of add_dependencies() whenever adding
5613 a dependency for some of the step targets generated by the Ex‐
5614 ternalProject module.
5615 Examples
5617 The following example shows how to download and build a hypothetical
5618 project called FooBar from github:
5619 include(ExternalProject)
5621 ExternalProject_Add(foobar
5622 GIT_REPOSITORY git@github.com:FooCo/FooBar.git
5623 GIT_TAG origin/release/1.2.3
5624 )
5625 For the sake of the example, also define a second hypothetical external
5627 project called SecretSauce, which is downloaded from a web server. Two
5628 URLs are given to take advantage of a faster internal network if avail‐
5629 able, with a fallback to a slower external server. The project is a
5630 typical Makefile project with no configure step, so some of the default
5631 commands are overridden. The build is only required to build the sauce
5632 target:
5633 find_program(MAKE_EXE NAMES gmake nmake make)
5635 ExternalProject_Add(secretsauce
5636 URL http://intranet.somecompany.com/artifacts/sauce-2.7.tgz
5637 https://www.somecompany.com/downloads/sauce-2.7.zip
5638 URL_HASH MD5=d41d8cd98f00b204e9800998ecf8427e
5639 CONFIGURE_COMMAND ""
5640 BUILD_COMMAND ${MAKE_EXE} sauce
5641 )
5642 Suppose the build step of secretsauce requires that foobar must already
5644 be built. This could be enforced like so:
5645 ExternalProject_Add_StepDependencies(secretsauce build foobar)
5647 Another alternative would be to create a custom target for foobar's
5649 build step and make secretsauce depend on that rather than the whole
5650 foobar project. This would mean foobar only needs to be built, it
5651 doesn't need to run its install or test steps before secretsauce can be
5652 built. The dependency can also be defined along with the secretsauce
5653 project:
5654 ExternalProject_Add_StepTargets(foobar build)
5656 ExternalProject_Add(secretsauce
5657 URL http://intranet.somecompany.com/artifacts/sauce-2.7.tgz
5658 https://www.somecompany.com/downloads/sauce-2.7.zip
5659 URL_HASH MD5=d41d8cd98f00b204e9800998ecf8427e
5660 CONFIGURE_COMMAND ""
5661 BUILD_COMMAND ${MAKE_EXE} sauce
5662 DEPENDS foobar-build
5663 )
5664 Instead of calling ExternalProject_Add_StepTargets(), the target could
5666 be defined along with the foobar project itself:
5667 ExternalProject_Add(foobar
5669 GIT_REPOSITORY git@github.com:FooCo/FooBar.git
5670 GIT_TAG origin/release/1.2.3
5671 STEP_TARGETS build
5672 )
5673 If many external projects should have the same set of step targets,
5675 setting a directory property may be more convenient. The build step
5676 target could be created automatically by setting the EP_STEP_TARGETS
5677 directory property before creating the external projects with
5678 ExternalProject_Add():
5679 set_property(DIRECTORY PROPERTY EP_STEP_TARGETS build)
5681 Lastly, suppose that secretsauce provides a script called makedoc which
5683 can be used to generate its own documentation. Further suppose that the
5684 script expects the output directory to be provided as the only parame‐
5685 ter and that it should be run from the secretsauce source directory. A
5686 custom step and a custom target to trigger the script can be defined
5687 like so:
5688 ExternalProject_Add_Step(secretsauce docs
5690 COMMAND <SOURCE_DIR>/makedoc <BINARY_DIR>
5691 WORKING_DIRECTORY <SOURCE_DIR>
5692 COMMENT "Building secretsauce docs"
5693 ALWAYS TRUE
5694 EXCLUDE_FROM_MAIN TRUE
5695 )
5696 ExternalProject_Add_StepTargets(secretsauce docs)
5697 The custom step could then be triggered from the main build like so:
5699 cmake --build . --target secretsauce-docs
5701 FeatureSummary
5703 Functions for generating a summary of enabled/disabled features.
5704 These functions can be used to generate a summary of enabled and dis‐
5706 abled packages and/or feature for a build tree such as:
5707 -- The following OPTIONAL packages have been found:
5709 LibXml2 (required version >= 2.4), XML processing lib, <http://xmlsoft.org>
5710 * Enables HTML-import in MyWordProcessor
5711 * Enables odt-export in MyWordProcessor
5712 PNG, A PNG image library., <http://www.libpng.org/pub/png/>
5713 * Enables saving screenshots
5714 -- The following OPTIONAL packages have not been found:
5715 Lua51, The Lua scripting language., <http://www.lua.org>
5716 * Enables macros in MyWordProcessor
5717 Foo, Foo provides cool stuff.
5718 Global Properties
5720 FeatureSummary_PKG_TYPES
5721 The global property FeatureSummary_PKG_TYPES defines the type of pack‐
5723 ages used by FeatureSummary.
5724 The order in this list is important, the first package type in the list
5726 is the least important, the last is the most important. the of a pack‐
5727 age can only be changed to higher types.
5728 The default package types are , RUNTIME, OPTIONAL, RECOMMENDED and RE‐
5730 QUIRED, and their importance is RUNTIME < OPTIONAL < RECOMMENDED < RE‐
5731 QUIRED.
5732 FeatureSummary_REQUIRED_PKG_TYPES
5734 The global property FeatureSummary_REQUIRED_PKG_TYPES defines which
5736 package types are required.
5737 If one or more package in this categories has not been found, CMake
5739 will abort when calling feature_summary() with the 'FATAL_ON_MISS‐
5740 ING_REQUIRED_PACKAGES' option enabled.
5741 The default value for this global property is REQUIRED.
5743 FeatureSummary_DEFAULT_PKG_TYPE
5745 The global property FeatureSummary_DEFAULT_PKG_TYPE defines which pack‐
5747 age type is the default one. When calling feature_summary(), if the
5748 user did not set the package type explicitly, the package will be as‐
5749 signed to this category.
5750 This value must be one of the types defined in the
5752 FeatureSummary_PKG_TYPES global property unless the package type is set
5753 for all the packages.
5754 The default value for this global property is OPTIONAL.
5756 FeatureSummary_<TYPE>_DESCRIPTION
5758 New in version 3.9.
5760 The global property FeatureSummary_<TYPE>_DESCRIPTION can be defined
5763 for each type to replace the type name with the specified string when‐
5764 ever the package type is used in an output string.
5765 If not set, the string "<TYPE> packages" is used.
5767 Functions
5769 feature_summary
5770 feature_summary( [FILENAME <file>]
5772 [APPEND]
5773 [VAR <variable_name>]
5774 [INCLUDE_QUIET_PACKAGES]
5775 [FATAL_ON_MISSING_REQUIRED_PACKAGES]
5776 [DESCRIPTION "<description>" | DEFAULT_DESCRIPTION]
5777 [QUIET_ON_EMPTY]
5778 WHAT (ALL
5779 | PACKAGES_FOUND | PACKAGES_NOT_FOUND
5780 | <TYPE>_PACKAGES_FOUND | <TYPE>_PACKAGES_NOT_FOUND
5781 | ENABLED_FEATURES | DISABLED_FEATURES)
5782 )
5783 The feature_summary() macro can be used to print information
5785 about enabled or disabled packages or features of a project. By
5786 default, only the names of the features/packages will be printed
5787 and their required version when one was specified. Use
5788 set_package_properties() to add more useful information, like
5789 e.g. a download URL for the respective package or their purpose
5790 in the project.
5791 The WHAT option is the only mandatory option. Here you specify
5793 what information will be printed:
5794 ALL print everything
5796 ENABLED_FEATURES
5798 the list of all features which are enabled
5799 DISABLED_FEATURES
5801 the list of all features which are disabled
5802 PACKAGES_FOUND
5804 the list of all packages which have been found
5805 PACKAGES_NOT_FOUND
5807 the list of all packages which have not been found
5808 For each package type <TYPE> defined by the
5810 FeatureSummary_PKG_TYPES global property, the following informa‐
5811 tion can also be used:
5812 <TYPE>_PACKAGES_FOUND
5814 only those packages which have been found which have the
5815 type <TYPE>
5816 <TYPE>_PACKAGES_NOT_FOUND
5818 only those packages which have not been found which have
5819 the type <TYPE>
5820 Changed in version 3.1: With the exception of the ALL value,
5822 these values can be combined in order to customize the output.
5823 For example:
5824 feature_summary(WHAT ENABLED_FEATURES DISABLED_FEATURES)
5826 If a FILENAME is given, the information is printed into this
5829 file. If APPEND is used, it is appended to this file, otherwise
5830 the file is overwritten if it already existed. If the VAR op‐
5831 tion is used, the information is "printed" into the specified
5832 variable. If FILENAME is not used, the information is printed
5833 to the terminal. Using the DESCRIPTION option a description or
5834 headline can be set which will be printed above the actual con‐
5835 tent. If only one type of package was requested, no title is
5836 printed, unless it is explicitly set using either DESCRIPTION to
5837 use a custom string, or DEFAULT_DESCRIPTION to use a default ti‐
5838 tle for the requested type. If INCLUDE_QUIET_PACKAGES is given,
5839 packages which have been searched with find_package(... QUIET)
5840 will also be listed. By default they are skipped. If FA‐
5841 TAL_ON_MISSING_REQUIRED_PACKAGES is given, CMake will abort if a
5842 package which is marked as one of the package types listed in
5843 the FeatureSummary_REQUIRED_PKG_TYPES global property has not
5844 been found. The default value for the
5845 FeatureSummary_REQUIRED_PKG_TYPES global property is REQUIRED.
5846 New in version 3.9: The DEFAULT_DESCRIPTION option.
5848 The FeatureSummary_DEFAULT_PKG_TYPE global property can be modi‐
5851 fied to change the default package type assigned when not ex‐
5852 plicitly assigned by the user.
5853 New in version 3.8: If the QUIET_ON_EMPTY option is used, if
5855 only one type of package was requested, and no packages belong‐
5856 ing to that category were found, then no output (including the
5857 DESCRIPTION) is printed or added to the VAR variable.
5858 Example 1, append everything to a file:
5861 include(FeatureSummary)
5863 feature_summary(WHAT ALL
5864 FILENAME ${CMAKE_BINARY_DIR}/all.log APPEND)
5865 Example 2, print the enabled features into the variable enabled‐
5867 FeaturesText, including QUIET packages:
5868 include(FeatureSummary)
5870 feature_summary(WHAT ENABLED_FEATURES
5871 INCLUDE_QUIET_PACKAGES
5872 DESCRIPTION "Enabled Features:"
5873 VAR enabledFeaturesText)
5874 message(STATUS "${enabledFeaturesText}")
5875 Example 3, change default package types and print only the cate‐
5877 gories that are not empty:
5878 include(FeatureSummary)
5880 set_property(GLOBAL APPEND PROPERTY FeatureSummary_PKG_TYPES BUILD)
5881 find_package(FOO)
5882 set_package_properties(FOO PROPERTIES TYPE BUILD)
5883 feature_summary(WHAT BUILD_PACKAGES_FOUND
5884 Description "Build tools found:"
5885 QUIET_ON_EMPTY)
5886 feature_summary(WHAT BUILD_PACKAGES_NOT_FOUND
5887 Description "Build tools not found:"
5888 QUIET_ON_EMPTY)
5889 set_package_properties
5891 set_package_properties(<name> PROPERTIES
5893 [ URL <url> ]
5894 [ DESCRIPTION <description> ]
5895 [ TYPE (RUNTIME|OPTIONAL|RECOMMENDED|REQUIRED) ]
5896 [ PURPOSE <purpose> ]
5897 )
5898 Use this macro to set up information about the named package,
5900 which can then be displayed via FEATURE_SUMMARY(). This can be
5901 done either directly in the Find-module or in the project which
5902 uses the module after the find_package() call. The features for
5903 which information can be set are added automatically by the
5904 find_package() command.
5905 URL <url>
5907 This should be the homepage of the package, or something
5908 similar. Ideally this is set already directly in the
5909 Find-module.
5910 DESCRIPTION <description>
5912 A short description what that package is, at most one
5913 sentence. Ideally this is set already directly in the
5914 Find-module.
5915 TYPE <type>
5917 What type of dependency has the using project on that
5918 package. Default is OPTIONAL. In this case it is a
5919 package which can be used by the project when available
5920 at buildtime, but it also work without. RECOMMENDED is
5921 similar to OPTIONAL, i.e. the project will build if the
5922 package is not present, but the functionality of the re‐
5923 sulting binaries will be severely limited. If a REQUIRED
5924 package is not available at buildtime, the project may
5925 not even build. This can be combined with the FA‐
5926 TAL_ON_MISSING_REQUIRED_PACKAGES argument for fea‐
5927 ture_summary(). Last, a RUNTIME package is a package
5928 which is actually not used at all during the build, but
5929 which is required for actually running the resulting bi‐
5930 naries. So if such a package is missing, the project can
5931 still be built, but it may not work later on. If
5932 set_package_properties() is called multiple times for the
5933 same package with different TYPEs, the TYPE is only
5934 changed to higher TYPEs (RUNTIME < OPTIONAL < RECOMMENDED
5935 < REQUIRED), lower TYPEs are ignored. The TYPE property
5936 is project-specific, so it cannot be set by the Find-mod‐
5937 ule, but must be set in the project. Type accepted can
5938 be changed by setting the FeatureSummary_PKG_TYPES global
5939 property.
5940 PURPOSE <purpose>
5942 This describes which features this package enables in the
5943 project, i.e. it tells the user what functionality he
5944 gets in the resulting binaries. If set_package_proper‐
5945 ties() is called multiple times for a package, all PUR‐
5946 POSE properties are appended to a list of purposes of the
5947 package in the project. As the TYPE property, also the
5948 PURPOSE property is project-specific, so it cannot be set
5949 by the Find-module, but must be set in the project.
5950 Example for setting the info for a package:
5952 find_package(LibXml2)
5954 set_package_properties(LibXml2 PROPERTIES
5955 DESCRIPTION "A XML processing library."
5956 URL "http://xmlsoft.org/")
5957 # or
5958 set_package_properties(LibXml2 PROPERTIES
5959 TYPE RECOMMENDED
5960 PURPOSE "Enables HTML-import in MyWordProcessor")
5961 # or
5962 set_package_properties(LibXml2 PROPERTIES
5963 TYPE OPTIONAL
5964 PURPOSE "Enables odt-export in MyWordProcessor")
5965 find_package(DBUS)
5967 set_package_properties(DBUS PROPERTIES
5968 TYPE RUNTIME
5969 PURPOSE "Necessary to disable the screensaver during a presentation")
5970 add_feature_info
5972 add_feature_info(<name> <enabled> <description>)
5974 Use this macro to add information about a feature with the given
5976 <name>. <enabled> contains whether this feature is enabled or
5977 not. It can be a variable or a list of conditions. <descrip‐
5978 tion> is a text describing the feature. The information can be
5979 displayed using feature_summary() for ENABLED_FEATURES and DIS‐
5980 ABLED_FEATURES respectively.
5981 Changed in version 3.8: <enabled> can be a list of conditions.
5983 Example for setting the info for a feature:
5986 option(WITH_FOO "Help for foo" ON)
5988 add_feature_info(Foo WITH_FOO "The Foo feature provides very cool stuff.")
5989 Legacy Macros
5991 The following macros are provided for compatibility with previous CMake
5992 versions:
5993 set_package_info
5995 set_package_info(<name> <description> [ <url> [<purpose>] ])
5997 Use this macro to set up information about the named package,
5999 which can then be displayed via feature_summary(). This can be
6000 done either directly in the Find-module or in the project which
6001 uses the module after the find_package() call. The features for
6002 which information can be set are added automatically by the
6003 find_package() command.
6004 set_feature_info
6006 set_feature_info(<name> <description> [<url>])
6008 Does the same as:
6010 set_package_info(<name> <description> <url>)
6012 print_enabled_features
6014 print_enabled_features()
6016 Does the same as
6018 feature_summary(WHAT ENABLED_FEATURES DESCRIPTION "Enabled features:")
6020 print_disabled_features
6022 print_disabled_features()
6024 Does the same as
6026 feature_summary(WHAT DISABLED_FEATURES DESCRIPTION "Disabled features:")
6028 FetchContent
6030 New in version 3.11.
6031 Overview
6034 This module enables populating content at configure time via any method
6035 supported by the ExternalProject module. Whereas ExternalProject_Add()
6036 downloads at build time, the FetchContent module makes content avail‐
6037 able immediately, allowing the configure step to use the content in
6038 commands like add_subdirectory(), include() or file() operations.
6039 Content population details would normally be defined separately from
6041 the command that performs the actual population. This separation en‐
6042 sures that all of the dependency details are defined before anything
6043 may try to use those details to populate content. This is particularly
6044 important in more complex project hierarchies where dependencies may be
6045 shared between multiple projects.
6046 The following shows a typical example of declaring content details:
6048 FetchContent_Declare(
6050 googletest
6051 GIT_REPOSITORY https://github.com/google/googletest.git
6052 GIT_TAG release-1.8.0
6053 )
6054 For most typical cases, populating the content can then be done with a
6056 single command like so:
6057 FetchContent_MakeAvailable(googletest)
6059 The above command not only populates the content, it also adds it to
6061 the main build (if possible) so that the main build can use the popu‐
6062 lated project's targets, etc. In some cases, the main project may need
6063 to have more precise control over the population or may be required to
6064 explicitly define the population steps (e.g. if CMake versions earlier
6065 than 3.14 need to be supported). The typical pattern of such custom
6066 steps looks like this:
6067 FetchContent_GetProperties(googletest)
6069 if(NOT googletest_POPULATED)
6070 FetchContent_Populate(googletest)
6071 add_subdirectory(${googletest_SOURCE_DIR} ${googletest_BINARY_DIR})
6072 endif()
6073 Regardless of which population method is used, when using the de‐
6075 clare-populate pattern with a hierarchical project arrangement,
6076 projects at higher levels in the hierarchy are able to override the
6077 population details of content specified anywhere lower in the project
6078 hierarchy. The ability to detect whether content has already been pop‐
6079 ulated ensures that even if multiple child projects want certain con‐
6080 tent to be available, the first one to populate it wins. The other
6081 child project can simply make use of the already available content in‐
6082 stead of repeating the population for itself. See the Examples section
6083 which demonstrates this scenario.
6084 The FetchContent module also supports defining and populating content
6086 in a single call, with no check for whether the content has been popu‐
6087 lated elsewhere in the project already. This is a more low level oper‐
6088 ation and would not normally be the way the module is used, but it is
6089 sometimes useful as part of implementing some higher level feature or
6090 to populate some content in CMake's script mode.
6091 Changed in version 3.14: FetchContent commands can access the terminal.
6093 This is necessary for password prompts and real-time progress displays
6094 to work.
6095 Commands
6098 Declaring Content Details
6099 FetchContent_Declare
6100 FetchContent_Declare(<name> <contentOptions>...)
6102 The FetchContent_Declare() function records the options that de‐
6104 scribe how to populate the specified content, but if such de‐
6105 tails have already been recorded earlier in this project (re‐
6106 gardless of where in the project hierarchy), this and all later
6107 calls for the same content <name> are ignored. This "first to
6108 record, wins" approach is what allows hierarchical projects to
6109 have parent projects override content details of child projects.
6110 The content <name> can be any string without spaces, but good
6112 practice would be to use only letters, numbers and underscores.
6113 The name will be treated case-insensitively and it should be ob‐
6114 vious for the content it represents, often being the name of the
6115 child project or the value given to its top level project() com‐
6116 mand (if it is a CMake project). For well-known public
6117 projects, the name should generally be the official name of the
6118 project. Choosing an unusual name makes it unlikely that other
6119 projects needing that same content will use the same name, lead‐
6120 ing to the content being populated multiple times.
6121 The <contentOptions> can be any of the download or update/patch
6123 options that the ExternalProject_Add() command understands. The
6124 configure, build, install and test steps are explicitly disabled
6125 and therefore options related to them will be ignored. The
6126 SOURCE_SUBDIR option is an exception, see
6127 FetchContent_MakeAvailable() for details on how that affects be‐
6128 havior.
6129 In most cases, <contentOptions> will just be a couple of options
6131 defining the download method and method-specific details like a
6132 commit tag or archive hash. For example:
6133 FetchContent_Declare(
6135 googletest
6136 GIT_REPOSITORY https://github.com/google/googletest.git
6137 GIT_TAG release-1.8.0
6138 )
6139 FetchContent_Declare(
6141 myCompanyIcons
6142 URL https://intranet.mycompany.com/assets/iconset_1.12.tar.gz
6143 URL_HASH 5588a7b18261c20068beabfb4f530b87
6144 )
6145 FetchContent_Declare(
6147 myCompanyCertificates
6148 SVN_REPOSITORY svn+ssh://svn.mycompany.com/srv/svn/trunk/certs
6149 SVN_REVISION -r12345
6150 )
6151 Populating The Content
6153 For most common scenarios, population means making content available to
6154 the main build according to previously declared details for that depen‐
6155 dency. There are two main patterns for populating content, one based
6156 on calling FetchContent_GetProperties() and FetchContent_Populate() for
6157 more precise control and the other on calling
6158 FetchContent_MakeAvailable() for a simpler, more automated approach.
6159 The former generally follows this canonical pattern:
6160 # Check if population has already been performed
6162 FetchContent_GetProperties(<name>)
6163 string(TOLOWER "<name>" lcName)
6164 if(NOT ${lcName}_POPULATED)
6165 # Fetch the content using previously declared details
6166 FetchContent_Populate(<name>)
6167 # Set custom variables, policies, etc.
6169 # ...
6170 # Bring the populated content into the build
6172 add_subdirectory(${${lcName}_SOURCE_DIR} ${${lcName}_BINARY_DIR})
6173 endif()
6174 The above is such a common pattern that, where no custom steps are
6176 needed between the calls to FetchContent_Populate() and add_subdirec‐
6177 tory(), equivalent logic can be obtained by calling
6178 FetchContent_MakeAvailable() instead. Where it meets the needs of the
6179 project, FetchContent_MakeAvailable() should be preferred, as it is
6180 simpler and provides additional features over the pattern above.
6181 FetchContent_Populate
6183 FetchContent_Populate( <name> )
6185 In most cases, the only argument given to FetchContent_Popu‐
6187 late() is the <name>. When used this way, the command assumes
6188 the content details have been recorded by an earlier call to
6189 FetchContent_Declare(). The details are stored in a global
6190 property, so they are unaffected by things like variable or di‐
6191 rectory scope. Therefore, it doesn't matter where in the
6192 project the details were previously declared, as long as they
6193 have been declared before the call to FetchContent_Populate().
6194 Those saved details are then used to construct a call to Exter‐
6195 nalProject_Add() in a private sub-build to perform the content
6196 population immediately. The implementation of ExternalPro‐
6197 ject_Add() ensures that if the content has already been popu‐
6198 lated in a previous CMake run, that content will be reused
6199 rather than repopulating them again. For the common case where
6200 population involves downloading content, the cost of the down‐
6201 load is only paid once.
6202 An internal global property records when a particular content
6204 population request has been processed. If FetchContent_Popu‐
6205 late() is called more than once for the same content name within
6206 a configure run, the second call will halt with an error.
6207 Projects can and should check whether content population has al‐
6208 ready been processed with the FetchContent_GetProperties() com‐
6209 mand before calling FetchContent_Populate().
6210 FetchContent_Populate() will set three variables in the scope of
6212 the caller; <lcName>_POPULATED, <lcName>_SOURCE_DIR and <lc‐
6213 Name>_BINARY_DIR, where <lcName> is the lowercased <name>. <lc‐
6214 Name>_POPULATED will always be set to True by the call. <lc‐
6215 Name>_SOURCE_DIR is the location where the content can be found
6216 upon return (it will have already been populated), while <lc‐
6217 Name>_BINARY_DIR is a directory intended for use as a corre‐
6218 sponding build directory. The main use case for the two direc‐
6219 tory variables is to call add_subdirectory() immediately after
6220 population, i.e.:
6221 FetchContent_Populate(FooBar ...)
6223 add_subdirectory(${foobar_SOURCE_DIR} ${foobar_BINARY_DIR})
6224 The values of the three variables can also be retrieved from
6226 anywhere in the project hierarchy using the
6227 FetchContent_GetProperties() command.
6228 A number of cache variables influence the behavior of all con‐
6230 tent population performed using details saved from a
6231 FetchContent_Declare() call:
6232 FETCHCONTENT_BASE_DIR
6234 In most cases, the saved details do not specify any op‐
6235 tions relating to the directories to use for the internal
6236 sub-build, final source and build areas. It is generally
6237 best to leave these decisions up to the FetchContent mod‐
6238 ule to handle on the project's behalf. The FETCHCON‐
6239 TENT_BASE_DIR cache variable controls the point under
6240 which all content population directories are collected,
6241 but in most cases developers would not need to change
6242 this. The default location is ${CMAKE_BINARY_DIR}/_deps,
6243 but if developers change this value, they should aim to
6244 keep the path short and just below the top level of the
6245 build tree to avoid running into path length problems on
6246 Windows.
6247 FETCHCONTENT_QUIET
6249 The logging output during population can be quite ver‐
6250 bose, making the configure stage quite noisy. This cache
6251 option (ON by default) hides all population output unless
6252 an error is encountered. If experiencing problems with
6253 hung downloads, temporarily switching this option off may
6254 help diagnose which content population is causing the is‐
6255 sue.
6256 FETCHCONTENT_FULLY_DISCONNECTED
6258 When this option is enabled, no attempt is made to down‐
6259 load or update any content. It is assumed that all con‐
6260 tent has already been populated in a previous run or the
6261 source directories have been pointed at existing contents
6262 the developer has provided manually (using options de‐
6263 scribed further below). When the developer knows that no
6264 changes have been made to any content details, turning
6265 this option ON can significantly speed up the configure
6266 stage. It is OFF by default.
6267 FETCHCONTENT_UPDATES_DISCONNECTED
6269 This is a less severe download/update control compared to
6270 FETCHCONTENT_FULLY_DISCONNECTED. Instead of bypassing
6271 all download and update logic, the FETCHCONTENT_UP‐
6272 DATES_DISCONNECTED only disables the update stage.
6273 Therefore, if content has not been downloaded previously,
6274 it will still be downloaded when this option is enabled.
6275 This can speed up the configure stage, but not as much as
6276 FETCHCONTENT_FULLY_DISCONNECTED. It is OFF by default.
6277 In addition to the above cache variables, the following cache
6279 variables are also defined for each content name (<ucName> is
6280 the uppercased value of <name>):
6281 FETCHCONTENT_SOURCE_DIR_<ucName>
6283 If this is set, no download or update steps are performed
6284 for the specified content and the <lcName>_SOURCE_DIR
6285 variable returned to the caller is pointed at this loca‐
6286 tion. This gives developers a way to have a separate
6287 checkout of the content that they can modify freely with‐
6288 out interference from the build. The build simply uses
6289 that existing source, but it still defines <lcName>_BI‐
6290 NARY_DIR to point inside its own build area. Developers
6291 are strongly encouraged to use this mechanism rather than
6292 editing the sources populated in the default location, as
6293 changes to sources in the default location can be lost
6294 when content population details are changed by the
6295 project.
6296 FETCHCONTENT_UPDATES_DISCONNECTED_<ucName>
6298 This is the per-content equivalent of FETCHCONTENT_UP‐
6299 DATES_DISCONNECTED. If the global option or this option
6300 is ON, then updates will be disabled for the named con‐
6301 tent. Disabling updates for individual content can be
6302 useful for content whose details rarely change, while
6303 still leaving other frequently changing content with up‐
6304 dates enabled.
6305 The FetchContent_Populate() command also supports a syntax al‐
6307 lowing the content details to be specified directly rather than
6308 using any saved details. This is more low-level and use of this
6309 form is generally to be avoided in favour of using saved content
6310 details as outlined above. Nevertheless, in certain situations
6311 it can be useful to invoke the content population as an isolated
6312 operation (typically as part of implementing some other higher
6313 level feature or when using CMake in script mode):
6314 FetchContent_Populate( <name>
6316 [QUIET]
6317 [SUBBUILD_DIR <subBuildDir>]
6318 [SOURCE_DIR <srcDir>]
6319 [BINARY_DIR <binDir>]
6320 ...
6321 )
6322 This form has a number of key differences to that where only
6324 <name> is provided:
6325 • All required population details are assumed to have been pro‐
6327 vided directly in the call to FetchContent_Populate(). Any
6328 saved details for <name> are ignored.
6329 • No check is made for whether content for <name> has already
6331 been populated.
6332 • No global property is set to record that the population has
6334 occurred.
6335 • No global properties record the source or binary directories
6337 used for the populated content.
6338 • The FETCHCONTENT_FULLY_DISCONNECTED and FETCHCONTENT_UP‐
6340 DATES_DISCONNECTED cache variables are ignored.
6341 The <lcName>_SOURCE_DIR and <lcName>_BINARY_DIR variables are
6343 still returned to the caller, but since these locations are not
6344 stored as global properties when this form is used, they are
6345 only available to the calling scope and below rather than the
6346 entire project hierarchy. No <lcName>_POPULATED variable is set
6347 in the caller's scope with this form.
6348 The supported options for FetchContent_Populate() are the same
6350 as those for FetchContent_Declare(). Those few options shown
6351 just above are either specific to FetchContent_Populate() or
6352 their behavior is slightly modified from how ExternalPro‐
6353 ject_Add() treats them.
6354 QUIET The QUIET option can be given to hide the output associ‐
6356 ated with populating the specified content. If the popu‐
6357 lation fails, the output will be shown regardless of
6358 whether this option was given or not so that the cause of
6359 the failure can be diagnosed. The global FETCHCON‐
6360 TENT_QUIET cache variable has no effect on FetchCon‐
6361 tent_Populate() calls where the content details are pro‐
6362 vided directly.
6363 SUBBUILD_DIR
6365 The SUBBUILD_DIR argument can be provided to change the
6366 location of the sub-build created to perform the popula‐
6367 tion. The default value is ${CMAKE_CURRENT_BI‐
6368 NARY_DIR}/<lcName>-subbuild and it would be unusual to
6369 need to override this default. If a relative path is
6370 specified, it will be interpreted as relative to
6371 CMAKE_CURRENT_BINARY_DIR. This option should not be con‐
6372 fused with the SOURCE_SUBDIR option which only affects
6373 the FetchContent_MakeAvailable() command.
6374 SOURCE_DIR, BINARY_DIR
6376 The SOURCE_DIR and BINARY_DIR arguments are supported by
6377 ExternalProject_Add(), but different default values are
6378 used by FetchContent_Populate(). SOURCE_DIR defaults to
6379 ${CMAKE_CURRENT_BINARY_DIR}/<lcName>-src and BINARY_DIR
6380 defaults to ${CMAKE_CURRENT_BINARY_DIR}/<lcName>-build.
6381 If a relative path is specified, it will be interpreted
6382 as relative to CMAKE_CURRENT_BINARY_DIR.
6383 In addition to the above explicit options, any other unrecog‐
6385 nized options are passed through unmodified to ExternalPro‐
6386 ject_Add() to perform the download, patch and update steps. The
6387 following options are explicitly prohibited (they are disabled
6388 by the FetchContent_Populate() command):
6389 • CONFIGURE_COMMAND
6391 • BUILD_COMMAND
6393 • INSTALL_COMMAND
6395 • TEST_COMMAND
6397 If using FetchContent_Populate() within CMake's script mode, be
6399 aware that the implementation sets up a sub-build which there‐
6400 fore requires a CMake generator and build tool to be available.
6401 If these cannot be found by default, then the CMAKE_GENERATOR
6402 and/or CMAKE_MAKE_PROGRAM variables will need to be set appro‐
6403 priately on the command line invoking the script.
6404 New in version 3.18: Added support for DOWNLOAD_NO_EXTRACT and
6406 SOURCE_SUBDIR options.
6407 FetchContent_GetProperties
6410 When using saved content details, a call to
6411 FetchContent_Populate() records information in global properties
6412 which can be queried at any time. This information includes the
6413 source and binary directories associated with the content and
6414 also whether or not the content population has been processed
6415 during the current configure run.
6416 FetchContent_GetProperties( <name>
6418 [SOURCE_DIR <srcDirVar>]
6419 [BINARY_DIR <binDirVar>]
6420 [POPULATED <doneVar>]
6421 )
6422 The SOURCE_DIR, BINARY_DIR and POPULATED options can be used to
6424 specify which properties should be retrieved. Each option ac‐
6425 cepts a value which is the name of the variable in which to
6426 store that property. Most of the time though, only <name> is
6427 given, in which case the call will then set the same variables
6428 as a call to FetchContent_Populate(name). This allows the fol‐
6429 lowing canonical pattern to be used, which ensures that the rel‐
6430 evant variables will always be defined regardless of whether or
6431 not the population has been performed elsewhere in the project
6432 already:
6433 FetchContent_GetProperties(foobar)
6435 if(NOT foobar_POPULATED)
6436 FetchContent_Populate(foobar)
6437 ...
6438 endif()
6439 The above pattern allows other parts of the overall project hi‐
6441 erarchy to re-use the same content and ensure that it is only
6442 populated once.
6443 FetchContent_MakeAvailable
6445 FetchContent_MakeAvailable( <name1> [<name2>...] )
6447 New in version 3.14.
6449 This command implements the common pattern typically needed for
6452 most dependencies. It iterates over each of the named dependen‐
6453 cies in turn and for each one it loosely follows the canonical
6454 pattern as presented at the beginning of this section. An im‐
6455 portant difference is that add_subdirectory() will only be
6456 called on the populated content if there is a CMakeLists.txt
6457 file in its top level source directory. This allows the command
6458 to be used for dependencies that make downloaded content avail‐
6459 able at a known location but which do not need or support being
6460 added directly to the build.
6461 The SOURCE_SUBDIR option can be given in the declared details to
6463 instruct FetchContent_MakeAvailable() to look for a CMake‐
6464 Lists.txt file in a subdirectory below the top level (i.e. the
6465 same way that SOURCE_SUBDIR is used by the ExternalProject_Add()
6466 command). SOURCE_SUBDIR must always be a relative path. See
6467 the next section for an example of this option.
6468 Examples
6470 This first fairly straightforward example ensures that some popular
6471 testing frameworks are available to the main build:
6472 include(FetchContent)
6474 FetchContent_Declare(
6475 googletest
6476 GIT_REPOSITORY https://github.com/google/googletest.git
6477 GIT_TAG release-1.8.0
6478 )
6479 FetchContent_Declare(
6480 Catch2
6481 GIT_REPOSITORY https://github.com/catchorg/Catch2.git
6482 GIT_TAG v2.5.0
6483 )
6484 # After the following call, the CMake targets defined by googletest and
6486 # Catch2 will be defined and available to the rest of the build
6487 FetchContent_MakeAvailable(googletest Catch2)
6488 If the sub-project's CMakeLists.txt file is not at the top level of its
6490 source tree, the SOURCE_SUBDIR option can be used to tell FetchContent
6491 where to find it. The following example shows how to use that option
6492 and it also sets a variable which is meaningful to the subproject be‐
6493 fore pulling it into the main build:
6494 include(FetchContent)
6496 FetchContent_Declare(
6497 protobuf
6498 GIT_REPOSITORY https://github.com/protocolbuffers/protobuf.git
6499 GIT_TAG v3.12.0
6500 SOURCE_SUBDIR cmake
6501 )
6502 set(protobuf_BUILD_TESTS OFF)
6503 FetchContent_MakeAvailable(protobuf)
6504 In more complex project hierarchies, the dependency relationships can
6506 be more complicated. Consider a hierarchy where projA is the top level
6507 project and it depends directly on projects projB and projC. Both
6508 projB and projC can be built standalone and they also both depend on
6509 another project projD. projB additionally depends on projE. This ex‐
6510 ample assumes that all five projects are available on a company git
6511 server. The CMakeLists.txt of each project might have sections like
6512 the following:
6513 projA:
6515 include(FetchContent)
6517 FetchContent_Declare(
6518 projB
6519 GIT_REPOSITORY git@mycompany.com:git/projB.git
6520 GIT_TAG 4a89dc7e24ff212a7b5167bef7ab079d
6521 )
6522 FetchContent_Declare(
6523 projC
6524 GIT_REPOSITORY git@mycompany.com:git/projC.git
6525 GIT_TAG 4ad4016bd1d8d5412d135cf8ceea1bb9
6526 )
6527 FetchContent_Declare(
6528 projD
6529 GIT_REPOSITORY git@mycompany.com:git/projD.git
6530 GIT_TAG origin/integrationBranch
6531 )
6532 FetchContent_Declare(
6533 projE
6534 GIT_REPOSITORY git@mycompany.com:git/projE.git
6535 GIT_TAG origin/release/2.3-rc1
6536 )
6537 # Order is important, see notes in the discussion further below
6539 FetchContent_MakeAvailable(projD projB projC)
6540 projB:
6542 include(FetchContent)
6544 FetchContent_Declare(
6545 projD
6546 GIT_REPOSITORY git@mycompany.com:git/projD.git
6547 GIT_TAG 20b415f9034bbd2a2e8216e9a5c9e632
6548 )
6549 FetchContent_Declare(
6550 projE
6551 GIT_REPOSITORY git@mycompany.com:git/projE.git
6552 GIT_TAG 68e20f674a48be38d60e129f600faf7d
6553 )
6554 FetchContent_MakeAvailable(projD projE)
6556 projC:
6558 include(FetchContent)
6560 FetchContent_Declare(
6561 projD
6562 GIT_REPOSITORY git@mycompany.com:git/projD.git
6563 GIT_TAG 7d9a17ad2c962aa13e2fbb8043fb6b8a
6564 )
6565 # This particular version of projD requires workarounds
6567 FetchContent_GetProperties(projD)
6568 if(NOT projd_POPULATED)
6569 FetchContent_Populate(projD)
6570 # Copy an additional/replacement file into the populated source
6572 file(COPY someFile.c DESTINATION ${projd_SOURCE_DIR}/src)
6573 add_subdirectory(${projd_SOURCE_DIR} ${projd_BINARY_DIR})
6575 endif()
6576 A few key points should be noted in the above:
6578 • projB and projC define different content details for projD, but projA
6580 also defines a set of content details for projD. Because projA will
6581 define them first, the details from projB and projC will not be used.
6582 The override details defined by projA are not required to match ei‐
6583 ther of those from projB or projC, but it is up to the higher level
6584 project to ensure that the details it does define still make sense
6585 for the child projects.
6586 • In the projA call to FetchContent_MakeAvailable(), projD is listed
6588 ahead of projB and projC to ensure that projA is in control of how
6589 projD is populated.
6590 • While projA defines content details for projE, it does not need to
6592 explicitly call FetchContent_MakeAvailable(projE) or FetchCon‐
6593 tent_Populate(projD) itself. Instead, it leaves that to the child
6594 projB. For higher level projects, it is often enough to just define
6595 the override content details and leave the actual population to the
6596 child projects. This saves repeating the same thing at each level of
6597 the project hierarchy unnecessarily.
6598 Projects don't always need to add the populated content to the build.
6600 Sometimes the project just wants to make the downloaded content avail‐
6601 able at a predictable location. The next example ensures that a set of
6602 standard company toolchain files (and potentially even the toolchain
6603 binaries themselves) is available early enough to be used for that same
6604 build.
6605 cmake_minimum_required(VERSION 3.14)
6607 include(FetchContent)
6609 FetchContent_Declare(
6610 mycom_toolchains
6611 URL https://intranet.mycompany.com//toolchains_1.3.2.tar.gz
6612 )
6613 FetchContent_MakeAvailable(mycom_toolchains)
6614 project(CrossCompileExample)
6616 The project could be configured to use one of the downloaded toolchains
6618 like so:
6619 cmake -DCMAKE_TOOLCHAIN_FILE=_deps/mycom_toolchains-src/toolchain_arm.cmake /path/to/src
6621 When CMake processes the CMakeLists.txt file, it will download and un‐
6623 pack the tarball into _deps/mycompany_toolchains-src relative to the
6624 build directory. The CMAKE_TOOLCHAIN_FILE variable is not used until
6625 the project() command is reached, at which point CMake looks for the
6626 named toolchain file relative to the build directory. Because the tar‐
6627 ball has already been downloaded and unpacked by then, the toolchain
6628 file will be in place, even the very first time that cmake is run in
6629 the build directory.
6630 Lastly, the following example demonstrates how one might download and
6632 unpack a firmware tarball using CMake's script mode. The call to
6633 FetchContent_Populate() specifies all the content details and the un‐
6634 packed firmware will be placed in a firmware directory below the cur‐
6635 rent working directory.
6636 getFirmware.cmake:
6638 # NOTE: Intended to be run in script mode with cmake -P
6640 include(FetchContent)
6641 FetchContent_Populate(
6642 firmware
6643 URL https://mycompany.com/assets/firmware-1.23-arm.tar.gz
6644 URL_HASH MD5=68247684da89b608d466253762b0ff11
6645 SOURCE_DIR firmware
6646 )
6647 FindPackageHandleStandardArgs
6649 This module provides functions intended to be used in Find Modules im‐
6650 plementing find_package(<PackageName>) calls.
6651 find_package_handle_standard_args
6653 This command handles the REQUIRED, QUIET and version-related ar‐
6654 guments of find_package(). It also sets the <PackageName>_FOUND
6655 variable. The package is considered found if all variables
6656 listed contain valid results, e.g. valid filepaths.
6657 There are two signatures:
6659 find_package_handle_standard_args(<PackageName>
6661 (DEFAULT_MSG|<custom-failure-message>)
6662 <required-var>...
6663 )
6664 find_package_handle_standard_args(<PackageName>
6666 [FOUND_VAR <result-var>]
6667 [REQUIRED_VARS <required-var>...]
6668 [VERSION_VAR <version-var>]
6669 [HANDLE_VERSION_RANGE]
6670 [HANDLE_COMPONENTS]
6671 [CONFIG_MODE]
6672 [NAME_MISMATCHED]
6673 [REASON_FAILURE_MESSAGE <reason-failure-message>]
6674 [FAIL_MESSAGE <custom-failure-message>]
6675 )
6676 The <PackageName>_FOUND variable will be set to TRUE if all the
6678 variables <required-var>... are valid and any optional con‐
6679 straints are satisfied, and FALSE otherwise. A success or fail‐
6680 ure message may be displayed based on the results and on whether
6681 the REQUIRED and/or QUIET option was given to the find_package()
6682 call.
6683 The options are:
6685 (DEFAULT_MSG|<custom-failure-message>)
6687 In the simple signature this specifies the failure mes‐
6688 sage. Use DEFAULT_MSG to ask for a default message to be
6689 computed (recommended). Not valid in the full signature.
6690 FOUND_VAR <result-var>
6692 Deprecated since version 3.3.
6693 Specifies either <PackageName>_FOUND or <PACKAGE‐
6696 NAME>_FOUND as the result variable. This exists only for
6697 compatibility with older versions of CMake and is now ig‐
6698 nored. Result variables of both names are always set for
6699 compatibility.
6700 REQUIRED_VARS <required-var>...
6702 Specify the variables which are required for this pack‐
6703 age. These may be named in the generated failure message
6704 asking the user to set the missing variable values.
6705 Therefore these should typically be cache entries such as
6706 FOO_LIBRARY and not output variables like FOO_LIBRARIES.
6707 Changed in version 3.18: If HANDLE_COMPONENTS is speci‐
6709 fied, this option can be omitted.
6710 VERSION_VAR <version-var>
6713 Specify the name of a variable that holds the version of
6714 the package that has been found. This version will be
6715 checked against the (potentially) specified required ver‐
6716 sion given to the find_package() call, including its EX‐
6717 ACT option. The default messages include information
6718 about the required version and the version which has been
6719 actually found, both if the version is ok or not.
6720 HANDLE_VERSION_RANGE
6722 New in version 3.19.
6723 Enable handling of a version range, if one is specified.
6726 Without this option, a developer warning will be dis‐
6727 played if a version range is specified.
6728 HANDLE_COMPONENTS
6730 Enable handling of package components. In this case, the
6731 command will report which components have been found and
6732 which are missing, and the <PackageName>_FOUND variable
6733 will be set to FALSE if any of the required components
6734 (i.e. not the ones listed after the OPTIONAL_COMPONENTS
6735 option of find_package()) are missing.
6736 CONFIG_MODE
6738 Specify that the calling find module is a wrapper around
6739 a call to find_package(<PackageName> NO_MODULE). This
6740 implies a VERSION_VAR value of <PackageName>_VERSION.
6741 The command will automatically check whether the package
6742 configuration file was found.
6743 REASON_FAILURE_MESSAGE <reason-failure-message>
6745 New in version 3.16.
6746 Specify a custom message of the reason for the failure
6749 which will be appended to the default generated message.
6750 FAIL_MESSAGE <custom-failure-message>
6752 Specify a custom failure message instead of using the de‐
6753 fault generated message. Not recommended.
6754 NAME_MISMATCHED
6756 New in version 3.17.
6757 Indicate that the <PackageName> does not match
6760 ${CMAKE_FIND_PACKAGE_NAME}. This is usually a mistake and
6761 raises a warning, but it may be intentional for usage of
6762 the command for components of a larger package.
6763 Example for the simple signature:
6765 find_package_handle_standard_args(LibXml2 DEFAULT_MSG
6767 LIBXML2_LIBRARY LIBXML2_INCLUDE_DIR)
6768 The LibXml2 package is considered to be found if both LIBXML2_LIBRARY
6770 and LIBXML2_INCLUDE_DIR are valid. Then also LibXml2_FOUND is set to
6771 TRUE. If it is not found and REQUIRED was used, it fails with a mes‐
6772 sage(FATAL_ERROR), independent whether QUIET was used or not. If it is
6773 found, success will be reported, including the content of the first
6774 <required-var>. On repeated CMake runs, the same message will not be
6775 printed again.
6776 NOTE:
6778 If <PackageName> does not match CMAKE_FIND_PACKAGE_NAME for the
6779 calling module, a warning that there is a mismatch is given. The
6780 FPHSA_NAME_MISMATCHED variable may be set to bypass the warning if
6781 using the old signature and the NAME_MISMATCHED argument using the
6782 new signature. To avoid forcing the caller to require newer versions
6783 of CMake for usage, the variable's value will be used if defined
6784 when the NAME_MISMATCHED argument is not passed for the new signa‐
6785 ture (but using both is an error)..
6786 Example for the full signature:
6788 find_package_handle_standard_args(LibArchive
6790 REQUIRED_VARS LibArchive_LIBRARY LibArchive_INCLUDE_DIR
6791 VERSION_VAR LibArchive_VERSION)
6792 In this case, the LibArchive package is considered to be found if both
6794 LibArchive_LIBRARY and LibArchive_INCLUDE_DIR are valid. Also the ver‐
6795 sion of LibArchive will be checked by using the version contained in
6796 LibArchive_VERSION. Since no FAIL_MESSAGE is given, the default mes‐
6797 sages will be printed.
6798 Another example for the full signature:
6800 find_package(Automoc4 QUIET NO_MODULE HINTS /opt/automoc4)
6802 find_package_handle_standard_args(Automoc4 CONFIG_MODE)
6803 In this case, a FindAutmoc4.cmake module wraps a call to find_pack‐
6805 age(Automoc4 NO_MODULE) and adds an additional search directory for au‐
6806 tomoc4. Then the call to find_package_handle_standard_args produces a
6807 proper success/failure message.
6808 find_package_check_version
6810 New in version 3.19.
6811 Helper function which can be used to check if a <version> is
6814 valid against version-related arguments of find_package().
6815 find_package_check_version(<version> <result-var>
6817 [HANDLE_VERSION_RANGE]
6818 [RESULT_MESSAGE_VARIABLE <message-var>]
6819 )
6820 The <result-var> will hold a boolean value giving the result of
6822 the check.
6823 The options are:
6825 HANDLE_VERSION_RANGE
6827 Enable handling of a version range, if one is specified.
6828 Without this option, a developer warning will be dis‐
6829 played if a version range is specified.
6830 RESULT_MESSAGE_VARIABLE <message-var>
6832 Specify a variable to get back a message describing the
6833 result of the check.
6834 Example for the usage:
6836 find_package_check_version(1.2.3 result HANDLE_VERSION_RANGE
6838 RESULT_MESSAGE_VARIABLE reason)
6839 if (result)
6840 message (STATUS "${reason}")
6841 else()
6842 message (FATAL_ERROR "${reason}")
6843 endif()
6844 FindPackageMessage
6846 find_package_message(<name> "message for user" "find result details")
6847 This function is intended to be used in FindXXX.cmake modules files.
6849 It will print a message once for each unique find result. This is use‐
6850 ful for telling the user where a package was found. The first argument
6851 specifies the name (XXX) of the package. The second argument specifies
6852 the message to display. The third argument lists details about the
6853 find result so that if they change the message will be displayed again.
6854 The macro also obeys the QUIET argument to the find_package command.
6855 Example:
6857 if(X11_FOUND)
6859 find_package_message(X11 "Found X11: ${X11_X11_LIB}"
6860 "[${X11_X11_LIB}][${X11_INCLUDE_DIR}]")
6861 else()
6862 ...
6863 endif()
6864 FortranCInterface
6866 Fortran/C Interface Detection
6867 This module automatically detects the API by which C and Fortran lan‐
6869 guages interact.
6870 Module Variables
6872 Variables that indicate if the mangling is found:
6873 FortranCInterface_GLOBAL_FOUND
6875 Global subroutines and functions.
6876 FortranCInterface_MODULE_FOUND
6878 Module subroutines and functions (declared by "MODULE PROCE‐
6879 DURE").
6880 This module also provides the following variables to specify the de‐
6882 tected mangling, though a typical use case does not need to reference
6883 them and can use the Module Functions below.
6884 FortranCInterface_GLOBAL_PREFIX
6886 Prefix for a global symbol without an underscore.
6887 FortranCInterface_GLOBAL_SUFFIX
6889 Suffix for a global symbol without an underscore.
6890 FortranCInterface_GLOBAL_CASE
6892 The case for a global symbol without an underscore, either UPPER
6893 or LOWER.
6894 FortranCInterface_GLOBAL__PREFIX
6896 Prefix for a global symbol with an underscore.
6897 FortranCInterface_GLOBAL__SUFFIX
6899 Suffix for a global symbol with an underscore.
6900 FortranCInterface_GLOBAL__CASE
6902 The case for a global symbol with an underscore, either UPPER or
6903 LOWER.
6904 FortranCInterface_MODULE_PREFIX
6906 Prefix for a module symbol without an underscore.
6907 FortranCInterface_MODULE_MIDDLE
6909 Middle of a module symbol without an underscore that appears be‐
6910 tween the name of the module and the name of the symbol.
6911 FortranCInterface_MODULE_SUFFIX
6913 Suffix for a module symbol without an underscore.
6914 FortranCInterface_MODULE_CASE
6916 The case for a module symbol without an underscore, either UPPER
6917 or LOWER.
6918 FortranCInterface_MODULE__PREFIX
6920 Prefix for a module symbol with an underscore.
6921 FortranCInterface_MODULE__MIDDLE
6923 Middle of a module symbol with an underscore that appears be‐
6924 tween the name of the module and the name of the symbol.
6925 FortranCInterface_MODULE__SUFFIX
6927 Suffix for a module symbol with an underscore.
6928 FortranCInterface_MODULE__CASE
6930 The case for a module symbol with an underscore, either UPPER or
6931 LOWER.
6932 Module Functions
6934 FortranCInterface_HEADER
6935 The FortranCInterface_HEADER function is provided to generate a
6936 C header file containing macros to mangle symbol names:
6937 FortranCInterface_HEADER(<file>
6939 [MACRO_NAMESPACE <macro-ns>]
6940 [SYMBOL_NAMESPACE <ns>]
6941 [SYMBOLS [<module>:]<function> ...])
6942 It generates in <file> definitions of the following macros:
6944 #define FortranCInterface_GLOBAL (name,NAME) ...
6946 #define FortranCInterface_GLOBAL_(name,NAME) ...
6947 #define FortranCInterface_MODULE (mod,name, MOD,NAME) ...
6948 #define FortranCInterface_MODULE_(mod,name, MOD,NAME) ...
6949 These macros mangle four categories of Fortran symbols, respec‐
6951 tively:
6952 • Global symbols without '_': call mysub()
6954 • Global symbols with '_' : call my_sub()
6956 • Module symbols without '_': use mymod; call mysub()
6958 • Module symbols with '_' : use mymod; call my_sub()
6960 If mangling for a category is not known, its macro is left unde‐
6962 fined. All macros require raw names in both lower case and up‐
6963 per case.
6964 The options are:
6966 MACRO_NAMESPACE
6968 Replace the default FortranCInterface_ prefix with a
6969 given namespace <macro-ns>.
6970 SYMBOLS
6972 List symbols to mangle automatically with C preprocessor
6973 definitions:
6974 <function> ==> #define <ns><function> ...
6976 <module>:<function> ==> #define <ns><module>_<function> ...
6977 If the mangling for some symbol is not known then no pre‐
6979 processor definition is created, and a warning is dis‐
6980 played.
6981 SYMBOL_NAMESPACE
6983 Prefix all preprocessor definitions generated by the SYM‐
6984 BOLS option with a given namespace <ns>.
6985 FortranCInterface_VERIFY
6987 The FortranCInterface_VERIFY function is provided to verify that
6988 the Fortran and C/C++ compilers work together:
6989 FortranCInterface_VERIFY([CXX] [QUIET])
6991 It tests whether a simple test executable using Fortran and C
6993 (and C++ when the CXX option is given) compiles and links suc‐
6994 cessfully. The result is stored in the cache entry FortranCIn‐
6995 terface_VERIFIED_C (or FortranCInterface_VERIFIED_CXX if CXX is
6996 given) as a boolean. If the check fails and QUIET is not given
6997 the function terminates with a fatal error message describing
6998 the problem. The purpose of this check is to stop a build early
6999 for incompatible compiler combinations. The test is built in
7000 the Release configuration.
7001 Example Usage
7003 include(FortranCInterface)
7004 FortranCInterface_HEADER(FC.h MACRO_NAMESPACE "FC_")
7005 This creates a "FC.h" header that defines mangling macros FC_GLOBAL(),
7007 FC_GLOBAL_(), FC_MODULE(), and FC_MODULE_().
7008 include(FortranCInterface)
7010 FortranCInterface_HEADER(FCMangle.h
7011 MACRO_NAMESPACE "FC_"
7012 SYMBOL_NAMESPACE "FC_"
7013 SYMBOLS mysub mymod:my_sub)
7014 This creates a "FCMangle.h" header that defines the same FC_*() man‐
7016 gling macros as the previous example plus preprocessor symbols FC_mysub
7017 and FC_mymod_my_sub.
7018 Additional Manglings
7020 FortranCInterface is aware of possible GLOBAL and MODULE manglings for
7021 many Fortran compilers, but it also provides an interface to specify
7022 new possible manglings. Set the variables:
7023 FortranCInterface_GLOBAL_SYMBOLS
7025 FortranCInterface_MODULE_SYMBOLS
7026 before including FortranCInterface to specify manglings of the symbols
7028 MySub, My_Sub, MyModule:MySub, and My_Module:My_Sub. For example, the
7029 code:
7030 set(FortranCInterface_GLOBAL_SYMBOLS mysub_ my_sub__ MYSUB_)
7032 # ^^^^^ ^^^^^^ ^^^^^
7033 set(FortranCInterface_MODULE_SYMBOLS
7034 __mymodule_MOD_mysub __my_module_MOD_my_sub)
7035 # ^^^^^^^^ ^^^^^ ^^^^^^^^^ ^^^^^^
7036 include(FortranCInterface)
7037 tells FortranCInterface to try given GLOBAL and MODULE manglings. (The
7039 carets point at raw symbol names for clarity in this example but are
7040 not needed.)
7041 GenerateExportHeader
7043 Function for generation of export macros for libraries
7044 This module provides the function GENERATE_EXPORT_HEADER().
7046 New in version 3.12: Added support for C projects. Previous versions
7048 supported C++ project only.
7049 The GENERATE_EXPORT_HEADER function can be used to generate a file
7052 suitable for preprocessor inclusion which contains EXPORT macros to be
7053 used in library classes:
7054 GENERATE_EXPORT_HEADER( LIBRARY_TARGET
7056 [BASE_NAME <base_name>]
7057 [EXPORT_MACRO_NAME <export_macro_name>]
7058 [EXPORT_FILE_NAME <export_file_name>]
7059 [DEPRECATED_MACRO_NAME <deprecated_macro_name>]
7060 [NO_EXPORT_MACRO_NAME <no_export_macro_name>]
7061 [INCLUDE_GUARD_NAME <include_guard_name>]
7062 [STATIC_DEFINE <static_define>]
7063 [NO_DEPRECATED_MACRO_NAME <no_deprecated_macro_name>]
7064 [DEFINE_NO_DEPRECATED]
7065 [PREFIX_NAME <prefix_name>]
7066 [CUSTOM_CONTENT_FROM_VARIABLE <variable>]
7067 )
7068 The target properties CXX_VISIBILITY_PRESET and VISIBILITY_INLINES_HID‐
7070 DEN can be used to add the appropriate compile flags for targets. See
7071 the documentation of those target properties, and the convenience vari‐
7072 ables CMAKE_CXX_VISIBILITY_PRESET and CMAKE_VISIBILITY_INLINES_HIDDEN.
7073 By default GENERATE_EXPORT_HEADER() generates macro names in a file
7075 name determined by the name of the library. This means that in the
7076 simplest case, users of GenerateExportHeader will be equivalent to:
7077 set(CMAKE_CXX_VISIBILITY_PRESET hidden)
7079 set(CMAKE_VISIBILITY_INLINES_HIDDEN 1)
7080 add_library(somelib someclass.cpp)
7081 generate_export_header(somelib)
7082 install(TARGETS somelib DESTINATION ${LIBRARY_INSTALL_DIR})
7083 install(FILES
7084 someclass.h
7085 ${PROJECT_BINARY_DIR}/somelib_export.h DESTINATION ${INCLUDE_INSTALL_DIR}
7086 )
7087 And in the ABI header files:
7089 #include "somelib_export.h"
7091 class SOMELIB_EXPORT SomeClass {
7092 ...
7093 };
7094 The CMake fragment will generate a file in the ${CMAKE_CURRENT_BI‐
7096 NARY_DIR} called somelib_export.h containing the macros SOMELIB_EXPORT,
7097 SOMELIB_NO_EXPORT, SOMELIB_DEPRECATED, SOMELIB_DEPRECATED_EXPORT and
7098 SOMELIB_DEPRECATED_NO_EXPORT. They will be followed by content taken
7099 from the variable specified by the CUSTOM_CONTENT_FROM_VARIABLE option,
7100 if any. The resulting file should be installed with other headers in
7101 the library.
7102 The BASE_NAME argument can be used to override the file name and the
7104 names used for the macros:
7105 add_library(somelib someclass.cpp)
7107 generate_export_header(somelib
7108 BASE_NAME other_name
7109 )
7110 Generates a file called other_name_export.h containing the macros
7112 OTHER_NAME_EXPORT, OTHER_NAME_NO_EXPORT and OTHER_NAME_DEPRECATED etc.
7113 The BASE_NAME may be overridden by specifying other options in the
7115 function. For example:
7116 add_library(somelib someclass.cpp)
7118 generate_export_header(somelib
7119 EXPORT_MACRO_NAME OTHER_NAME_EXPORT
7120 )
7121 creates the macro OTHER_NAME_EXPORT instead of SOMELIB_EXPORT, but
7123 other macros and the generated file name is as default:
7124 add_library(somelib someclass.cpp)
7126 generate_export_header(somelib
7127 DEPRECATED_MACRO_NAME KDE_DEPRECATED
7128 )
7129 creates the macro KDE_DEPRECATED instead of SOMELIB_DEPRECATED.
7131 If LIBRARY_TARGET is a static library, macros are defined without val‐
7133 ues.
7134 If the same sources are used to create both a shared and a static li‐
7136 brary, the uppercased symbol ${BASE_NAME}_STATIC_DEFINE should be used
7137 when building the static library:
7138 add_library(shared_variant SHARED ${lib_SRCS})
7140 add_library(static_variant ${lib_SRCS})
7141 generate_export_header(shared_variant BASE_NAME libshared_and_static)
7142 set_target_properties(static_variant PROPERTIES
7143 COMPILE_FLAGS -DLIBSHARED_AND_STATIC_STATIC_DEFINE)
7144 This will cause the export macros to expand to nothing when building
7146 the static library.
7147 If DEFINE_NO_DEPRECATED is specified, then a macro ${BASE_NAME}_NO_DEP‐
7149 RECATED will be defined This macro can be used to remove deprecated
7150 code from preprocessor output:
7151 option(EXCLUDE_DEPRECATED "Exclude deprecated parts of the library" FALSE)
7153 if (EXCLUDE_DEPRECATED)
7154 set(NO_BUILD_DEPRECATED DEFINE_NO_DEPRECATED)
7155 endif()
7156 generate_export_header(somelib ${NO_BUILD_DEPRECATED})
7157 And then in somelib:
7159 class SOMELIB_EXPORT SomeClass
7161 {
7162 public:
7163 #ifndef SOMELIB_NO_DEPRECATED
7164 SOMELIB_DEPRECATED void oldMethod();
7165 #endif
7166 };
7167 #ifndef SOMELIB_NO_DEPRECATED
7169 void SomeClass::oldMethod() { }
7170 #endif
7171 If PREFIX_NAME is specified, the argument will be used as a prefix to
7173 all generated macros.
7174 For example:
7176 generate_export_header(somelib PREFIX_NAME VTK_)
7178 Generates the macros VTK_SOMELIB_EXPORT etc.
7180 New in version 3.1: Library target can be an OBJECT library.
7182 New in version 3.7: Added the CUSTOM_CONTENT_FROM_VARIABLE option.
7185 New in version 3.11: Added the INCLUDE_GUARD_NAME option.
7188 ADD_COMPILER_EXPORT_FLAGS( [<output_variable>] )
7191 Deprecated since version 3.0: Set the target properties CXX_VISIBIL‐
7193 ITY_PRESET and VISIBILITY_INLINES_HIDDEN instead.
7194 The ADD_COMPILER_EXPORT_FLAGS function adds -fvisibility=hidden to
7197 CMAKE_CXX_FLAGS if supported, and is a no-op on Windows which does not
7198 need extra compiler flags for exporting support. You may optionally
7199 pass a single argument to ADD_COMPILER_EXPORT_FLAGS that will be popu‐
7200 lated with the CXX_FLAGS required to enable visibility support for the
7201 compiler/architecture in use.
7202 GetPrerequisites
7204 Deprecated since version 3.16: Use file(GET_RUNTIME_DEPENDENCIES) in‐
7205 stead.
7206 Functions to analyze and list executable file prerequisites.
7209 This module provides functions to list the .dll, .dylib or .so files
7211 that an executable or shared library file depends on. (Its prerequi‐
7212 sites.)
7213 It uses various tools to obtain the list of required shared library
7215 files:
7216 dumpbin (Windows)
7218 objdump (MinGW on Windows)
7219 ldd (Linux/Unix)
7220 otool (Mac OSX)
7221 Changed in version 3.16: The tool specified by CMAKE_OBJDUMP will be
7223 used, if set.
7224 The following functions are provided by this module:
7227 get_prerequisites
7229 list_prerequisites
7230 list_prerequisites_by_glob
7231 gp_append_unique
7232 is_file_executable
7233 gp_item_default_embedded_path
7234 (projects can override with gp_item_default_embedded_path_override)
7235 gp_resolve_item
7236 (projects can override with gp_resolve_item_override)
7237 gp_resolved_file_type
7238 (projects can override with gp_resolved_file_type_override)
7239 gp_file_type
7240 GET_PREREQUISITES(<target> <prerequisites_var> <exclude_system> <recurse>
7242 <exepath> <dirs> [<rpaths>])
7243 Get the list of shared library files required by <target>. The list in
7245 the variable named <prerequisites_var> should be empty on first entry
7246 to this function. On exit, <prerequisites_var> will contain the list
7247 of required shared library files.
7248 <target> is the full path to an executable file. <prerequisites_var>
7250 is the name of a CMake variable to contain the results. <exclude_sys‐
7251 tem> must be 0 or 1 indicating whether to include or exclude "system"
7252 prerequisites. If <recurse> is set to 1 all prerequisites will be
7253 found recursively, if set to 0 only direct prerequisites are listed.
7254 <exepath> is the path to the top level executable used for @exe‐
7255 cutable_path replacement on the Mac. <dirs> is a list of paths where
7256 libraries might be found: these paths are searched first when a target
7257 without any path info is given. Then standard system locations are
7258 also searched: PATH, Framework locations, /usr/lib...
7259 New in version 3.14: The variable GET_PREREQUISITES_VERBOSE can be set
7261 to true to enable verbose output.
7262 LIST_PREREQUISITES(<target> [<recurse> [<exclude_system> [<verbose>]]])
7265 Print a message listing the prerequisites of <target>.
7267 <target> is the name of a shared library or executable target or the
7269 full path to a shared library or executable file. If <recurse> is set
7270 to 1 all prerequisites will be found recursively, if set to 0 only di‐
7271 rect prerequisites are listed. <exclude_system> must be 0 or 1 indi‐
7272 cating whether to include or exclude "system" prerequisites. With
7273 <verbose> set to 0 only the full path names of the prerequisites are
7274 printed, set to 1 extra informatin will be displayed.
7275 LIST_PREREQUISITES_BY_GLOB(<glob_arg> <glob_exp>)
7277 Print the prerequisites of shared library and executable files matching
7279 a globbing pattern. <glob_arg> is GLOB or GLOB_RECURSE and <glob_exp>
7280 is a globbing expression used with "file(GLOB" or "file(GLOB_RECURSE"
7281 to retrieve a list of matching files. If a matching file is exe‐
7282 cutable, its prerequisites are listed.
7283 Any additional (optional) arguments provided are passed along as the
7285 optional arguments to the list_prerequisites calls.
7286 GP_APPEND_UNIQUE(<list_var> <value>)
7288 Append <value> to the list variable <list_var> only if the value is not
7290 already in the list.
7291 IS_FILE_EXECUTABLE(<file> <result_var>)
7293 Return 1 in <result_var> if <file> is a binary executable, 0 otherwise.
7295 GP_ITEM_DEFAULT_EMBEDDED_PATH(<item> <default_embedded_path_var>)
7297 Return the path that others should refer to the item by when the item
7299 is embedded inside a bundle.
7300 Override on a per-project basis by providing a project-specific
7302 gp_item_default_embedded_path_override function.
7303 GP_RESOLVE_ITEM(<context> <item> <exepath> <dirs> <resolved_item_var>
7305 [<rpaths>])
7306 Resolve an item into an existing full path file.
7308 Override on a per-project basis by providing a project-specific gp_re‐
7310 solve_item_override function.
7311 GP_RESOLVED_FILE_TYPE(<original_file> <file> <exepath> <dirs> <type_var>
7313 [<rpaths>])
7314 Return the type of <file> with respect to <original_file>. String de‐
7316 scribing type of prerequisite is returned in variable named <type_var>.
7317 Use <exepath> and <dirs> if necessary to resolve non-absolute <file>
7319 values -- but only for non-embedded items.
7320 Possible types are:
7322 system
7324 local
7325 embedded
7326 other
7327 Override on a per-project basis by providing a project-specific gp_re‐
7329 solved_file_type_override function.
7330 GP_FILE_TYPE(<original_file> <file> <type_var>)
7332 Return the type of <file> with respect to <original_file>. String de‐
7334 scribing type of prerequisite is returned in variable named <type_var>.
7335 Possible types are:
7337 system
7339 local
7340 embedded
7341 other
7342 GNUInstallDirs
7344 Define GNU standard installation directories
7345 Provides install directory variables as defined by the GNU Coding Stan‐
7347 dards.
7348 Result Variables
7350 Inclusion of this module defines the following variables:
7351 CMAKE_INSTALL_<dir>
7353 Destination for files of a given type. This value may be passed to
7354 the DESTINATION options of install() commands for the corresponding
7355 file type. It should typically be a path relative to the installa‐
7356 tion prefix so that it can be converted to an absolute path in a re‐
7357 locatable way (see CMAKE_INSTALL_FULL_<dir>). However, an absolute
7358 path is also allowed.
7359 CMAKE_INSTALL_FULL_<dir>
7361 The absolute path generated from the corresponding CMAKE_IN‐
7362 STALL_<dir> value. If the value is not already an absolute path, an
7363 absolute path is constructed typically by prepending the value of
7364 the CMAKE_INSTALL_PREFIX variable. However, there are some special
7365 cases as documented below.
7366 where <dir> is one of:
7368 BINDIR user executables (bin)
7370 SBINDIR
7372 system admin executables (sbin)
7373 LIBEXECDIR
7375 program executables (libexec)
7376 SYSCONFDIR
7378 read-only single-machine data (etc)
7379 SHAREDSTATEDIR
7381 modifiable architecture-independent data (com)
7382 LOCALSTATEDIR
7384 modifiable single-machine data (var)
7385 RUNSTATEDIR
7387 New in version 3.9: run-time variable data (LOCALSTATEDIR/run)
7388 LIBDIR object code libraries (lib or lib64 or lib/<multiarch-tuple> on
7391 Debian)
7392 INCLUDEDIR
7394 C header files (include)
7395 OLDINCLUDEDIR
7397 C header files for non-gcc (/usr/include)
7398 DATAROOTDIR
7400 read-only architecture-independent data root (share)
7401 DATADIR
7403 read-only architecture-independent data (DATAROOTDIR)
7404 INFODIR
7406 info documentation (DATAROOTDIR/info)
7407 LOCALEDIR
7409 locale-dependent data (DATAROOTDIR/locale)
7410 MANDIR man documentation (DATAROOTDIR/man)
7412 DOCDIR documentation root (DATAROOTDIR/doc/PROJECT_NAME)
7414 If the includer does not define a value the above-shown default will be
7416 used and the value will appear in the cache for editing by the user.
7417 Special Cases
7419 New in version 3.4.
7420 The following values of CMAKE_INSTALL_PREFIX are special:
7423 /
7425 For <dir> other than the SYSCONFDIR, LOCALSTATEDIR and RUNSTATEDIR,
7426 the value of CMAKE_INSTALL_<dir> is prefixed with usr/ if it is not
7427 user-specified as an absolute path. For example, the INCLUDEDIR
7428 value include becomes usr/include. This is required by the GNU Cod‐
7429 ing Standards, which state:
7430 When building the complete GNU system, the prefix will be empty
7431 and /usr will be a symbolic link to /.
7432 /usr
7434 For <dir> equal to SYSCONFDIR, LOCALSTATEDIR or RUNSTATEDIR, the
7435 CMAKE_INSTALL_FULL_<dir> is computed by prepending just / to the
7436 value of CMAKE_INSTALL_<dir> if it is not user-specified as an abso‐
7437 lute path. For example, the SYSCONFDIR value etc becomes /etc.
7438 This is required by the GNU Coding Standards.
7439 /opt/...
7441 For <dir> equal to SYSCONFDIR, LOCALSTATEDIR or RUNSTATEDIR, the
7442 CMAKE_INSTALL_FULL_<dir> is computed by appending the prefix to the
7443 value of CMAKE_INSTALL_<dir> if it is not user-specified as an abso‐
7444 lute path. For example, the SYSCONFDIR value etc becomes
7445 /etc/opt/.... This is defined by the Filesystem Hierarchy Standard.
7446 Macros
7448 GNUInstallDirs_get_absolute_install_dir
7449 GNUInstallDirs_get_absolute_install_dir(absvar var dirname)
7451 New in version 3.7.
7453 Set the given variable absvar to the absolute path contained
7456 within the variable var. This is to allow the computation of an
7457 absolute path, accounting for all the special cases documented
7458 above. While this macro is used to compute the various
7459 CMAKE_INSTALL_FULL_<dir> variables, it is exposed publicly to
7460 allow users who create additional path variables to also compute
7461 absolute paths where necessary, using the same logic. dirname
7462 is the directory name to get, e.g. BINDIR.
7463 Changed in version 3.20: Added the <dirname> parameter. Previ‐
7465 ous versions of CMake passed this value through the variable
7466 ${dir}.
7467 GoogleTest
7470 New in version 3.9.
7471 This module defines functions to help use the Google Test infrastruc‐
7474 ture. Two mechanisms for adding tests are provided. gtest_add_tests()
7475 has been around for some time, originally via find_package(GTest).
7476 gtest_discover_tests() was introduced in CMake 3.10.
7477 The (older) gtest_add_tests() scans source files to identify tests.
7479 This is usually effective, with some caveats, including in cross-com‐
7480 piling environments, and makes setting additional properties on tests
7481 more convenient. However, its handling of parameterized tests is less
7482 comprehensive, and it requires re-running CMake to detect changes to
7483 the list of tests.
7484 The (newer) gtest_discover_tests() discovers tests by asking the com‐
7486 piled test executable to enumerate its tests. This is more robust and
7487 provides better handling of parameterized tests, and does not require
7488 CMake to be re-run when tests change. However, it may not work in a
7489 cross-compiling environment, and setting test properties is less conve‐
7490 nient.
7491 More details can be found in the documentation of the respective func‐
7493 tions.
7494 Both commands are intended to replace use of add_test() to register
7496 tests, and will create a separate CTest test for each Google Test test
7497 case. Note that this is in some cases less efficient, as common set-up
7498 and tear-down logic cannot be shared by multiple test cases executing
7499 in the same instance. However, it provides more fine-grained pass/fail
7500 information to CTest, which is usually considered as more beneficial.
7501 By default, the CTest test name is the same as the Google Test name
7502 (i.e. suite.testcase); see also TEST_PREFIX and TEST_SUFFIX.
7503 gtest_add_tests
7505 Automatically add tests with CTest by scanning source code for
7506 Google Test macros:
7507 gtest_add_tests(TARGET target
7509 [SOURCES src1...]
7510 [EXTRA_ARGS arg1...]
7511 [WORKING_DIRECTORY dir]
7512 [TEST_PREFIX prefix]
7513 [TEST_SUFFIX suffix]
7514 [SKIP_DEPENDENCY]
7515 [TEST_LIST outVar]
7516 )
7517 gtest_add_tests attempts to identify tests by scanning source
7519 files. Although this is generally effective, it uses only a ba‐
7520 sic regular expression match, which can be defeated by atypical
7521 test declarations, and is unable to fully "split" parameterized
7522 tests. Additionally, it requires that CMake be re-run to dis‐
7523 cover any newly added, removed or renamed tests (by default,
7524 this means that CMake is re-run when any test source file is
7525 changed, but see SKIP_DEPENDENCY). However, it has the advan‐
7526 tage of declaring tests at CMake time, which somewhat simplifies
7527 setting additional properties on tests, and always works in a
7528 cross-compiling environment.
7529 The options are:
7531 TARGET target
7533 Specifies the Google Test executable, which must be a
7534 known CMake executable target. CMake will substitute the
7535 location of the built executable when running the test.
7536 SOURCES src1...
7538 When provided, only the listed files will be scanned for
7539 test cases. If this option is not given, the SOURCES
7540 property of the specified target will be used to obtain
7541 the list of sources.
7542 EXTRA_ARGS arg1...
7544 Any extra arguments to pass on the command line to each
7545 test case.
7546 WORKING_DIRECTORY dir
7548 Specifies the directory in which to run the discovered
7549 test cases. If this option is not provided, the current
7550 binary directory is used.
7551 TEST_PREFIX prefix
7553 Specifies a prefix to be prepended to the name of each
7554 discovered test case. This can be useful when the same
7555 source files are being used in multiple calls to
7556 gtest_add_test() but with different EXTRA_ARGS.
7557 TEST_SUFFIX suffix
7559 Similar to TEST_PREFIX except the suffix is appended to
7560 the name of every discovered test case. Both TEST_PREFIX
7561 and TEST_SUFFIX may be specified.
7562 SKIP_DEPENDENCY
7564 Normally, the function creates a dependency which will
7565 cause CMake to be re-run if any of the sources being
7566 scanned are changed. This is to ensure that the list of
7567 discovered tests is updated. If this behavior is not de‐
7568 sired (as may be the case while actually writing the test
7569 cases), this option can be used to prevent the dependency
7570 from being added.
7571 TEST_LIST outVar
7573 The variable named by outVar will be populated in the
7574 calling scope with the list of discovered test cases.
7575 This allows the caller to do things like manipulate test
7576 properties of the discovered tests.
7577 Usage example:
7579 include(GoogleTest)
7581 add_executable(FooTest FooUnitTest.cxx)
7582 gtest_add_tests(TARGET FooTest
7583 TEST_SUFFIX .noArgs
7584 TEST_LIST noArgsTests
7585 )
7586 gtest_add_tests(TARGET FooTest
7587 EXTRA_ARGS --someArg someValue
7588 TEST_SUFFIX .withArgs
7589 TEST_LIST withArgsTests
7590 )
7591 set_tests_properties(${noArgsTests} PROPERTIES TIMEOUT 10)
7592 set_tests_properties(${withArgsTests} PROPERTIES TIMEOUT 20)
7593 For backward compatibility, the following form is also sup‐
7595 ported:
7596 gtest_add_tests(exe args files...)
7598 exe The path to the test executable or the name of a CMake
7600 target.
7601 args A ;-list of extra arguments to be passed to executable.
7603 The entire list must be passed as a single argument. En‐
7604 close it in quotes, or pass "" for no arguments.
7605 files...
7607 A list of source files to search for tests and test fix‐
7608 tures. Alternatively, use AUTO to specify that exe is
7609 the name of a CMake executable target whose sources
7610 should be scanned.
7611 include(GoogleTest)
7613 set(FooTestArgs --foo 1 --bar 2)
7614 add_executable(FooTest FooUnitTest.cxx)
7615 gtest_add_tests(FooTest "${FooTestArgs}" AUTO)
7616 gtest_discover_tests
7618 Automatically add tests with CTest by querying the compiled test
7619 executable for available tests:
7620 gtest_discover_tests(target
7622 [EXTRA_ARGS arg1...]
7623 [WORKING_DIRECTORY dir]
7624 [TEST_PREFIX prefix]
7625 [TEST_SUFFIX suffix]
7626 [NO_PRETTY_TYPES] [NO_PRETTY_VALUES]
7627 [PROPERTIES name1 value1...]
7628 [TEST_LIST var]
7629 [DISCOVERY_TIMEOUT seconds]
7630 [XML_OUTPUT_DIR dir]
7631 [DISCOVERY_MODE <POST_BUILD|PRE_TEST>]
7632 )
7633 New in version 3.10.
7635 gtest_discover_tests() sets up a post-build command on the test
7638 executable that generates the list of tests by parsing the out‐
7639 put from running the test with the --gtest_list_tests argument.
7640 Compared to the source parsing approach of gtest_add_tests(),
7641 this ensures that the full list of tests, including instantia‐
7642 tions of parameterized tests, is obtained. Since test discovery
7643 occurs at build time, it is not necessary to re-run CMake when
7644 the list of tests changes. However, it requires that CROSSCOM‐
7645 PILING_EMULATOR is properly set in order to function in a
7646 cross-compiling environment.
7647 Additionally, setting properties on tests is somewhat less con‐
7649 venient, since the tests are not available at CMake time. Addi‐
7650 tional test properties may be assigned to the set of tests as a
7651 whole using the PROPERTIES option. If more fine-grained test
7652 control is needed, custom content may be provided through an ex‐
7653 ternal CTest script using the TEST_INCLUDE_FILES directory prop‐
7654 erty. The set of discovered tests is made accessible to such a
7655 script via the <target>_TESTS variable.
7656 The options are:
7658 target Specifies the Google Test executable, which must be a
7660 known CMake executable target. CMake will substitute the
7661 location of the built executable when running the test.
7662 EXTRA_ARGS arg1...
7664 Any extra arguments to pass on the command line to each
7665 test case.
7666 WORKING_DIRECTORY dir
7668 Specifies the directory in which to run the discovered
7669 test cases. If this option is not provided, the current
7670 binary directory is used.
7671 TEST_PREFIX prefix
7673 Specifies a prefix to be prepended to the name of each
7674 discovered test case. This can be useful when the same
7675 test executable is being used in multiple calls to
7676 gtest_discover_tests() but with different EXTRA_ARGS.
7677 TEST_SUFFIX suffix
7679 Similar to TEST_PREFIX except the suffix is appended to
7680 the name of every discovered test case. Both TEST_PREFIX
7681 and TEST_SUFFIX may be specified.
7682 NO_PRETTY_TYPES
7684 By default, the type index of type-parameterized tests is
7685 replaced by the actual type name in the CTest test name.
7686 If this behavior is undesirable (e.g. because the type
7687 names are unwieldy), this option will suppress this be‐
7688 havior.
7689 NO_PRETTY_VALUES
7691 By default, the value index of value-parameterized tests
7692 is replaced by the actual value in the CTest test name.
7693 If this behavior is undesirable (e.g. because the value
7694 strings are unwieldy), this option will suppress this be‐
7695 havior.
7696 PROPERTIES name1 value1...
7698 Specifies additional properties to be set on all tests
7699 discovered by this invocation of gtest_discover_tests().
7700 TEST_LIST var
7702 Make the list of tests available in the variable var,
7703 rather than the default <target>_TESTS. This can be use‐
7704 ful when the same test executable is being used in multi‐
7705 ple calls to gtest_discover_tests(). Note that this
7706 variable is only available in CTest.
7707 DISCOVERY_TIMEOUT num
7709 New in version 3.10.3.
7710 Specifies how long (in seconds) CMake will wait for the
7713 test to enumerate available tests. If the test takes
7714 longer than this, discovery (and your build) will fail.
7715 Most test executables will enumerate their tests very
7716 quickly, but under some exceptional circumstances, a test
7717 may require a longer timeout. The default is 5. See
7718 also the TIMEOUT option of execute_process().
7719 NOTE:
7721 In CMake versions 3.10.1 and 3.10.2, this option was
7722 called TIMEOUT. This clashed with the TIMEOUT test
7723 property, which is one of the common properties that
7724 would be set with the PROPERTIES keyword, usually
7725 leading to legal but unintended behavior. The keyword
7726 was changed to DISCOVERY_TIMEOUT in CMake 3.10.3 to
7727 address this problem. The ambiguous behavior of the
7728 TIMEOUT keyword in 3.10.1 and 3.10.2 has not been pre‐
7729 served.
7730 XML_OUTPUT_DIR dir
7732 New in version 3.18.
7733 If specified, the parameter is passed along with
7736 --gtest_output=xml: to test executable. The actual file
7737 name is the same as the test target, including prefix and
7738 suffix. This should be used instead of EXTRA_ARGS
7739 --gtest_output=xml to avoid race conditions writing the
7740 XML result output when using parallel test execution.
7741 DISCOVERY_MODE
7743 New in version 3.18.
7744 Provides greater control over when gtest_discover_tests()
7747 performs test discovery. By default, POST_BUILD sets up a
7748 post-build command to perform test discovery at build
7749 time. In certain scenarios, like cross-compiling, this
7750 POST_BUILD behavior is not desirable. By contrast,
7751 PRE_TEST delays test discovery until just prior to test
7752 execution. This way test discovery occurs in the target
7753 environment where the test has a better chance at finding
7754 appropriate runtime dependencies.
7755 DISCOVERY_MODE defaults to the value of the
7757 CMAKE_GTEST_DISCOVER_TESTS_DISCOVERY_MODE variable if it
7758 is not passed when calling gtest_discover_tests(). This
7759 provides a mechanism for globally selecting a preferred
7760 test discovery behavior without having to modify each
7761 call site.
7762 InstallRequiredSystemLibraries
7764 Include this module to search for compiler-provided system runtime li‐
7765 braries and add install rules for them. Some optional variables may be
7766 set prior to including the module to adjust behavior:
7767 CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS
7769 Specify additional runtime libraries that may not be detected.
7770 After inclusion any detected libraries will be appended to this.
7771 CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS_SKIP
7773 Set to TRUE to skip calling the install(PROGRAMS) command to al‐
7774 low the includer to specify its own install rule, using the
7775 value of CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS to get the list of
7776 libraries.
7777 CMAKE_INSTALL_DEBUG_LIBRARIES
7779 Set to TRUE to install the debug runtime libraries when avail‐
7780 able with MSVC tools.
7781 CMAKE_INSTALL_DEBUG_LIBRARIES_ONLY
7783 Set to TRUE to install only the debug runtime libraries with
7784 MSVC tools even if the release runtime libraries are also avail‐
7785 able.
7786 CMAKE_INSTALL_UCRT_LIBRARIES
7788 New in version 3.6.
7789 Set to TRUE to install the Windows Universal CRT libraries for
7792 app-local deployment (e.g. to Windows XP). This is meaningful
7793 only with MSVC from Visual Studio 2015 or higher.
7794 New in version 3.9: One may set a CMAKE_WINDOWS_KITS_10_DIR en‐
7796 vironment variable to an absolute path to tell CMake to look for
7797 Windows 10 SDKs in a custom location. The specified directory
7798 is expected to contain Redist/ucrt/DLLs/* directories.
7799 CMAKE_INSTALL_MFC_LIBRARIES
7802 Set to TRUE to install the MSVC MFC runtime libraries.
7803 CMAKE_INSTALL_OPENMP_LIBRARIES
7805 Set to TRUE to install the MSVC OpenMP runtime libraries
7806 CMAKE_INSTALL_SYSTEM_RUNTIME_DESTINATION
7808 Specify the install(PROGRAMS) command DESTINATION option. If
7809 not specified, the default is bin on Windows and lib elsewhere.
7810 CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS_NO_WARNINGS
7812 Set to TRUE to disable warnings about required library files
7813 that do not exist. (For example, Visual Studio Express editions
7814 may not provide the redistributable files.)
7815 CMAKE_INSTALL_SYSTEM_RUNTIME_COMPONENT
7817 New in version 3.3.
7818 Specify the install(PROGRAMS) command COMPONENT option. If not
7821 specified, no such option will be used.
7822 New in version 3.10: Support for installing Intel compiler runtimes.
7824 ProcessorCount
7827 ProcessorCount(var)
7828 Determine the number of processors/cores and save value in ${var}
7830 Sets the variable named ${var} to the number of physical cores avail‐
7832 able on the machine if the information can be determined. Otherwise it
7833 is set to 0. Currently this functionality is implemented for AIX, cyg‐
7834 win, FreeBSD, HPUX, Linux, macOS, QNX, Sun and Windows.
7835 Changed in version 3.15: On Linux, returns the container CPU count in‐
7837 stead of the host CPU count.
7838 This function is guaranteed to return a positive integer (>=1) if it
7841 succeeds. It returns 0 if there's a problem determining the processor
7842 count.
7843 Example use, in a ctest -S dashboard script:
7845 include(ProcessorCount)
7847 ProcessorCount(N)
7848 if(NOT N EQUAL 0)
7849 set(CTEST_BUILD_FLAGS -j${N})
7850 set(ctest_test_args ${ctest_test_args} PARALLEL_LEVEL ${N})
7851 endif()
7852 This function is intended to offer an approximation of the value of the
7854 number of compute cores available on the current machine, such that you
7855 may use that value for parallel building and parallel testing. It is
7856 meant to help utilize as much of the machine as seems reasonable. Of
7857 course, knowledge of what else might be running on the machine simulta‐
7858 neously should be used when deciding whether to request a machine's
7859 full capacity all for yourself.
7860 SelectLibraryConfigurations
7862 select_library_configurations(basename)
7863 This macro takes a library base name as an argument, and will choose
7865 good values for the variables
7866 basename_LIBRARY
7868 basename_LIBRARIES
7869 basename_LIBRARY_DEBUG
7870 basename_LIBRARY_RELEASE
7871 depending on what has been found and set.
7873 If only basename_LIBRARY_RELEASE is defined, basename_LIBRARY will be
7875 set to the release value, and basename_LIBRARY_DEBUG will be set to
7876 basename_LIBRARY_DEBUG-NOTFOUND. If only basename_LIBRARY_DEBUG is de‐
7877 fined, then basename_LIBRARY will take the debug value, and base‐
7878 name_LIBRARY_RELEASE will be set to basename_LIBRARY_RELEASE-NOTFOUND.
7879 If the generator supports configuration types, then basename_LIBRARY
7881 and basename_LIBRARIES will be set with debug and optimized flags spec‐
7882 ifying the library to be used for the given configuration. If no build
7883 type has been set or the generator in use does not support configura‐
7884 tion types, then basename_LIBRARY and basename_LIBRARIES will take only
7885 the release value, or the debug value if the release one is not set.
7886 SquishTestScript
7888 This script launches a GUI test using Squish. You should not call the
7889 script directly; instead, you should access it via the SQUISH_ADD_TEST
7890 macro that is defined in FindSquish.cmake.
7891 This script starts the Squish server, launches the test on the client,
7893 and finally stops the squish server. If any of these steps fail (in‐
7894 cluding if the tests do not pass) then a fatal error is raised.
7895 TestBigEndian
7897 Deprecated since version 3.20: Supserseded by the CMAKE_<LANG>_BYTE_OR‐
7898 DER variable.
7899 Check if the target architecture is big endian or little endian.
7902 test_big_endian
7904 test_big_endian(<var>)
7906 Stores in variable <var> either 1 or 0 indicating whether the
7908 target architecture is big or little endian.
7909 TestForANSIForScope
7911 Check for ANSI for scope support
7912 Check if the compiler restricts the scope of variables declared in a
7914 for-init-statement to the loop body.
7915 CMAKE_NO_ANSI_FOR_SCOPE - holds result
7917 TestForANSIStreamHeaders
7919 Test for compiler support of ANSI stream headers iostream, etc.
7920 check if the compiler supports the standard ANSI iostream header (with‐
7922 out the .h)
7923 CMAKE_NO_ANSI_STREAM_HEADERS - defined by the results
7925 TestForSSTREAM
7927 Test for compiler support of ANSI sstream header
7928 check if the compiler supports the standard ANSI sstream header
7930 CMAKE_NO_ANSI_STRING_STREAM - defined by the results
7932 TestForSTDNamespace
7934 Test for std:: namespace support
7935 check if the compiler supports std:: on stl classes
7937 CMAKE_NO_STD_NAMESPACE - defined by the results
7939 UseEcos
7941 This module defines variables and macros required to build eCos appli‐
7942 cation.
7943 This file contains the following macros: ECOS_ADD_INCLUDE_DIRECTORIES()
7945 - add the eCos include dirs ECOS_ADD_EXECUTABLE(name source1 ...
7946 sourceN ) - create an eCos executable ECOS_ADJUST_DIRECTORY(VAR source1
7947 ... sourceN ) - adjusts the path of the source files and puts the re‐
7948 sult into VAR
7949 Macros for selecting the toolchain: ECOS_USE_ARM_ELF_TOOLS() - enable
7951 the ARM ELF toolchain for the directory where it is called
7952 ECOS_USE_I386_ELF_TOOLS() - enable the i386 ELF toolchain for the di‐
7953 rectory where it is called ECOS_USE_PPC_EABI_TOOLS() - enable the Pow‐
7954 erPC toolchain for the directory where it is called
7955 It contains the following variables: ECOS_DEFINITIONS ECOSCONFIG_EXE‐
7957 CUTABLE ECOS_CONFIG_FILE - defaults to ecos.ecc, if your eCos configu‐
7958 ration file has a different name, adjust this variable for internal use
7959 only:
7960 ECOS_ADD_TARGET_LIB
7962 UseJava
7964 Use Module for Java
7965 This file provides functions for Java. It is assumed that FindJava has
7967 already been loaded. See FindJava for information on how to load Java
7968 into your CMake project.
7969 Creating And Installing JARs
7971 add_jar(<target_name>
7972 [SOURCES] <source1> [<source2>...] [<resource1>...]
7973 [INCLUDE_JARS <jar1> [<jar2>...]]
7974 [ENTRY_POINT <entry>]
7975 [VERSION <version>]
7976 [OUTPUT_NAME <name>]
7977 [OUTPUT_DIR <dir>]
7978 [GENERATE_NATIVE_HEADERS <target>
7979 [DESTINATION (<dir>|INSTALL <dir> [BUILD <dir>])]]
7980 )
7981 This command creates a <target_name>.jar. It compiles the given
7983 <source> files and adds the given <resource> files to the jar file.
7984 Source files can be java files or listing files (prefixed by @). If
7985 only resource files are given then just a jar file is created. The
7986 list of INCLUDE_JARS are added to the classpath when compiling the java
7987 sources and also to the dependencies of the target. INCLUDE_JARS also
7988 accepts other target names created by add_jar(). For backwards compat‐
7989 ibility, jar files listed as sources are ignored (as they have been
7990 since the first version of this module).
7991 New in version 3.4: Support for response files (prefixed by @) in the
7993 SOURCES list.
7994 The default OUTPUT_DIR can also be changed by setting the variable
7997 CMAKE_JAVA_TARGET_OUTPUT_DIR.
7998 New in version 3.11: Optionally, using option GENERATE_NATIVE_HEADERS,
8000 native header files can be generated for methods declared as native.
8001 These files provide the connective glue that allow your Java and C code
8002 to interact. An INTERFACE target will be created for an easy usage of
8003 generated files. Sub-option DESTINATION can be used to specify the
8004 output directory for generated header files.
8005 GENERATE_NATIVE_HEADERS option requires, at least, version 1.8 of the
8007 JDK.
8008 New in version 3.20: DESTINATION sub-option now supports the possibil‐
8011 ity to specify different output directories for BUILD and INSTALL
8012 steps. This is required to export the interface target generated by
8013 GENERATE_NATIVE_HEADERS option. If BUILD directory is not specified, a
8014 default directory will be used.
8015 The add_jar() function sets the following target properties on <tar‐
8018 get_name>:
8019 INSTALL_FILES
8021 The files which should be installed. This is used by in‐
8022 stall_jar().
8023 JNI_SYMLINK
8025 The JNI symlink which should be installed. This is used by in‐
8026 stall_jni_symlink().
8027 JAR_FILE
8029 The location of the jar file so that you can include it.
8030 CLASSDIR
8032 The directory where the class files can be found. For example
8033 to use them with javah.
8034 New in version 3.20: The target generated by option GENERATE_NA‐
8036 TIVE_HEADERS has the property NATIVE_HEADERS_DIRECTORY which specify
8037 the directory holding the native headers.
8038 install_jar(<target_name> <destination>)
8041 install_jar(<target_name> DESTINATION <destination> [COMPONENT <component>])
8042 This command installs the <target_name> files to the given <destina‐
8044 tion>. It should be called in the same scope as add_jar() or it will
8045 fail.
8046 The install_jar() function sets the INSTALL_DESTINATION target property
8048 on jars so installed. This property holds the <destination> as de‐
8049 scribed above, and is used by install_jar_exports(). You can get this
8050 information with get_property() and the INSTALL_DESTINATION property
8051 key.
8052 New in version 3.4: The second signature with DESTINATION and COMPONENT
8054 options.
8055 install_jni_symlink(<target_name> <destination>)
8058 install_jni_symlink(<target_name> DESTINATION <destination> [COMPONENT <component>])
8059 This command installs the <target_name> JNI symlinks to the given <des‐
8061 tination>. It should be called in the same scope as add_jar() or it
8062 will fail.
8063 New in version 3.4: The second signature with DESTINATION and COMPONENT
8065 options.
8066 Exporting JAR Targets
8069 New in version 3.7.
8070 install_jar_exports(TARGETS <jars>...
8073 [NAMESPACE <namespace>]
8074 FILE <filename>
8075 DESTINATION <destination> [COMPONENT <component>])
8076 This command installs a target export file <filename> for the named jar
8078 targets to the given <destination> directory. Its function is similar
8079 to that of install(EXPORTS).
8080 New in version 3.9: The NAMESPACE option.
8082 export_jars(TARGETS <jars>...
8085 [NAMESPACE <namespace>]
8086 FILE <filename>)
8087 This command writes a target export file <filename> for the named
8089 <jars> targets. Its function is similar to that of export().
8090 New in version 3.9: The NAMESPACE option.
8092 Examples
8095 To add compile flags to the target you can set these flags with the
8096 following variable:
8097 set(CMAKE_JAVA_COMPILE_FLAGS -nowarn)
8099 To add a path or a jar file to the class path you can do this with the
8101 CMAKE_JAVA_INCLUDE_PATH variable.
8102 set(CMAKE_JAVA_INCLUDE_PATH /usr/share/java/shibboleet.jar)
8104 To use a different output name for the target you can set it with:
8106 add_jar(foobar foobar.java OUTPUT_NAME shibboleet.jar)
8108 To use a different output directory than CMAKE_CURRENT_BINARY_DIR you
8110 can set it with:
8111 add_jar(foobar foobar.java OUTPUT_DIR ${PROJECT_BINARY_DIR}/bin)
8113 To define an entry point in your jar you can set it with the EN‐
8115 TRY_POINT named argument:
8116 add_jar(example ENTRY_POINT com/examples/MyProject/Main)
8118 To define a custom manifest for the jar, you can set it with the MANI‐
8120 FEST named argument:
8121 add_jar(example MANIFEST /path/to/manifest)
8123 To add a version to the target output name you can set it using the
8125 VERSION named argument to add_jar(). The following example will create
8126 a jar file with the name shibboleet-1.0.0.jar and will create a symlink
8127 shibboleet.jar pointing to the jar with the version information.
8128 add_jar(shibboleet shibbotleet.java VERSION 1.2.0)
8130 If the target is a JNI library, utilize the following commands to cre‐
8132 ate a JNI symbolic link:
8133 set(CMAKE_JNI_TARGET TRUE)
8135 add_jar(shibboleet shibbotleet.java VERSION 1.2.0)
8136 install_jar(shibboleet ${LIB_INSTALL_DIR}/shibboleet)
8137 install_jni_symlink(shibboleet ${JAVA_LIB_INSTALL_DIR})
8138 If a single target needs to produce more than one jar from its java
8140 source code, to prevent the accumulation of duplicate class files in
8141 subsequent jars, set/reset CMAKE_JAR_CLASSES_PREFIX prior to calling
8142 the add_jar() function:
8143 set(CMAKE_JAR_CLASSES_PREFIX com/redhat/foo)
8145 add_jar(foo foo.java)
8146 set(CMAKE_JAR_CLASSES_PREFIX com/redhat/bar)
8148 add_jar(bar bar.java)
8149 For an optimum usage of option GENERATE_NATIVE_HEADERS, it is recom‐
8151 mended to include module JNI before any call to add_jar(). The produced
8152 target for native headers can then be used to compile C/C++ sources
8153 with the target_link_libraries() command.
8154 find_package(JNI)
8156 add_jar(foo foo.java GENERATE_NATIVE_HEADERS foo-native)
8157 add_library(bar bar.cpp)
8158 target_link_libraries(bar PRIVATE foo-native)
8159 New in version 3.20: It is now possible to export the target generated
8161 by GENERATE_NATIVE_HEADERS option.
8162 add_jar(foo foo.java GENERATE_NATIVE_HEADERS foo-native
8164 DESTINATION INSTALL include)
8165 install(TARGETS foo-native EXPORT native)
8166 install(DIRECTORY "$<TARGET_PROPERTY:foo-native,NATIVE_HEADERS_DIRECTORY>/"
8167 DESTINATION include)
8168 install(EXPORT native DESTINATION /to/export NAMESPACE foo)
8169 Finding JARs
8172 find_jar(<VAR>
8173 <name> | NAMES <name1> [<name2>...]
8174 [PATHS <path1> [<path2>... ENV <var>]]
8175 [VERSIONS <version1> [<version2>]]
8176 [DOC "cache documentation string"]
8177 )
8178 This command is used to find a full path to the named jar. A cache en‐
8180 try named by <VAR> is created to store the result of this command. If
8181 the full path to a jar is found the result is stored in the variable
8182 and the search will not repeated unless the variable is cleared. If
8183 nothing is found, the result will be <VAR>-NOTFOUND, and the search
8184 will be attempted again next time find_jar() is invoked with the same
8185 variable. The name of the full path to a file that is searched for is
8186 specified by the names listed after NAMES argument. Additional search
8187 locations can be specified after the PATHS argument. If you require
8188 special a version of a jar file you can specify it with the VERSIONS
8189 argument. The argument after DOC will be used for the documentation
8190 string in the cache.
8191 Javadoc
8193 The create_javadoc() command can be used to create java documentation
8194 based on files or packages. For more details please read the javadoc
8195 manpage.
8196 There are two main signatures for create_javadoc(). The first signa‐
8198 ture works with package names on a path with source files.
8199 create_javadoc(<VAR>
8201 PACKAGES <pkg1> [<pkg2>...]
8202 [SOURCEPATH <sourcepath>]
8203 [CLASSPATH <classpath>]
8204 [INSTALLPATH <install path>]
8205 [DOCTITLE "the documentation title"]
8206 [WINDOWTITLE "the title of the document"]
8207 [AUTHOR TRUE|FALSE]
8208 [USE TRUE|FALSE]
8209 [VERSION TRUE|FALSE]
8210 )
8211 For example:
8213 create_javadoc(my_example_doc
8215 PACKAGES com.example.foo com.example.bar
8216 SOURCEPATH "${CMAKE_CURRENT_SOURCE_DIR}"
8217 CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH}
8218 WINDOWTITLE "My example"
8219 DOCTITLE "<h1>My example</h1>"
8220 AUTHOR TRUE
8221 USE TRUE
8222 VERSION TRUE
8223 )
8224 The second signature for create_javadoc() works on a given list of
8226 files.
8227 create_javadoc(<VAR>
8229 FILES <file1> [<file2>...]
8230 [CLASSPATH <classpath>]
8231 [INSTALLPATH <install path>]
8232 [DOCTITLE "the documentation title"]
8233 [WINDOWTITLE "the title of the document"]
8234 [AUTHOR TRUE|FALSE]
8235 [USE TRUE|FALSE]
8236 [VERSION TRUE|FALSE]
8237 )
8238 For example:
8240 create_javadoc(my_example_doc
8242 FILES ${example_SRCS}
8243 CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH}
8244 WINDOWTITLE "My example"
8245 DOCTITLE "<h1>My example</h1>"
8246 AUTHOR TRUE
8247 USE TRUE
8248 VERSION TRUE
8249 )
8250 Both signatures share most of the options. These options are the same
8252 as what you can find in the javadoc manpage. Please look at the man‐
8253 page for CLASSPATH, DOCTITLE, WINDOWTITLE, AUTHOR, USE and VERSION.
8254 If you don't set the INSTALLPATH, then by default the documentation
8256 will be installed to :
8257 ${CMAKE_INSTALL_PREFIX}/share/javadoc/<VAR>
8259 Header Generation
8261 create_javah(TARGET <target> | GENERATED_FILES <VAR>
8262 CLASSES <class>...
8263 [CLASSPATH <classpath>...]
8264 [DEPENDS <depend>...]
8265 [OUTPUT_NAME <path>|OUTPUT_DIR <path>]
8266 )
8267 New in version 3.4.
8269 Deprecated since version 3.11: This command will no longer be supported
8272 starting with version 10 of the JDK due to the suppression of javah
8273 tool. The add_jar(GENERATE_NATIVE_HEADERS) command should be used in‐
8274 stead.
8275 Create C header files from java classes. These files provide the con‐
8278 nective glue that allow your Java and C code to interact.
8279 There are two main signatures for create_javah(). The first signature
8281 returns generated files through variable specified by the GENER‐
8282 ATED_FILES option. For example:
8283 create_javah(GENERATED_FILES files_headers
8285 CLASSES org.cmake.HelloWorld
8286 CLASSPATH hello.jar
8287 )
8288 The second signature for create_javah() creates a target which encapsu‐
8290 lates header files generation. E.g.
8291 create_javah(TARGET target_headers
8293 CLASSES org.cmake.HelloWorld
8294 CLASSPATH hello.jar
8295 )
8296 Both signatures share same options.
8298 CLASSES <class>...
8300 Specifies Java classes used to generate headers.
8301 CLASSPATH <classpath>...
8303 Specifies various paths to look up classes. Here .class files,
8304 jar files or targets created by command add_jar can be used.
8305 DEPENDS <depend>...
8307 Targets on which the javah target depends.
8308 OUTPUT_NAME <path>
8310 Concatenates the resulting header files for all the classes
8311 listed by option CLASSES into <path>. Same behavior as option
8312 -o of javah tool.
8313 OUTPUT_DIR <path>
8315 Sets the directory where the header files will be generated.
8316 Same behavior as option -d of javah tool. If not specified,
8317 CMAKE_CURRENT_BINARY_DIR is used as the output directory.
8318 UseSWIG
8320 This file provides support for SWIG. It is assumed that FindSWIG module
8321 has already been loaded.
8322 Defines the following command for use with SWIG:
8324 swig_add_library
8326 New in version 3.8.
8327 Define swig module with given name and specified language:
8330 swig_add_library(<name>
8332 [TYPE <SHARED|MODULE|STATIC|USE_BUILD_SHARED_LIBS>]
8333 LANGUAGE <language>
8334 [NO_PROXY]
8335 [OUTPUT_DIR <directory>]
8336 [OUTFILE_DIR <directory>]
8337 SOURCES <file>...
8338 )
8339 Targets created with the swig_add_library command have the same
8341 capabilities as targets created with the add_library() command,
8342 so those targets can be used with any command expecting a target
8343 (e.g. target_link_libraries()).
8344 Changed in version 3.13: This command creates a target with the
8346 specified <name> when policy CMP0078 is set to NEW. Otherwise,
8347 the legacy behavior will choose a different target name and
8348 store it in the SWIG_MODULE_<name>_REAL_NAME variable.
8349 Changed in version 3.15: Alternate library name (set with the
8352 OUTPUT_NAME property, for example) will be passed on to Python
8353 and CSharp wrapper libraries.
8354 NOTE:
8357 For multi-config generators, this module does not support
8358 configuration-specific files generated by SWIG. All build
8359 configurations must result in the same generated source file.
8360 NOTE:
8362 For Makefile Generators, if, for some sources, the
8363 USE_SWIG_DEPENDENCIES property is FALSE, swig_add_library
8364 does not track file dependencies, so depending on the
8365 <name>_swig_compilation custom target is required for targets
8366 which require the swig-generated files to exist. Other gener‐
8367 ators may depend on the source files that would be generated
8368 by SWIG.
8369 TYPE SHARED, MODULE and STATIC have the same semantic as for
8371 the add_library() command. If USE_BUILD_SHARED_LIBS is
8372 specified, the library type will be STATIC or SHARED
8373 based on whether the current value of the
8374 BUILD_SHARED_LIBS variable is ON. If no type is speci‐
8375 fied, MODULE will be used.
8376 LANGUAGE
8378 Specify the target language.
8379 New in version 3.1: Go and Lua language support.
8381 New in version 3.2: R language support.
8384 New in version 3.18: Fortran language support.
8387 NO_PROXY
8390 New in version 3.12.
8391 Prevent the generation of the wrapper layer (swig -no‐
8394 proxy option).
8395 OUTPUT_DIR
8397 New in version 3.12.
8398 Specify where to write the language specific files (swig
8401 -outdir option). If not given, the CMAKE_SWIG_OUTDIR
8402 variable will be used. If neither is specified, the de‐
8403 fault depends on the value of the UseSWIG_MODULE_VERSION
8404 variable as follows:
8405 • If UseSWIG_MODULE_VERSION is 1 or is undefined, output
8407 is written to the CMAKE_CURRENT_BINARY_DIR directory.
8408 • If UseSWIG_MODULE_VERSION is 2, a dedicated directory
8410 will be used. The path of this directory can be re‐
8411 trieved from the SWIG_SUPPORT_FILES_DIRECTORY target
8412 property.
8413 OUTFILE_DIR
8415 New in version 3.12.
8416 Specify an output directory name where the generated
8419 source file will be placed (swig -o option). If not spec‐
8420 ified, the SWIG_OUTFILE_DIR variable will be used. If
8421 neither is specified, OUTPUT_DIR or CMAKE_SWIG_OUTDIR is
8422 used instead.
8423 SOURCES
8425 List of sources for the library. Files with extension .i
8426 will be identified as sources for the SWIG tool. Other
8427 files will be handled in the standard way.
8428 New in version 3.14: This behavior can be overridden by
8430 specifying the variable SWIG_SOURCE_FILE_EXTENSIONS.
8431 NOTE:
8434 If UseSWIG_MODULE_VERSION is set to 2, it is strongly recom‐
8435 mended to use a dedicated directory unique to the target when
8436 either the OUTPUT_DIR option or the CMAKE_SWIG_OUTDIR vari‐
8437 able are specified. The output directory contents are erased
8438 as part of the target build, so to prevent interference be‐
8439 tween targets or losing other important files, each target
8440 should have its own dedicated output directory.
8441 swig_link_libraries
8443 Link libraries to swig module:
8444 swig_link_libraries(<name> <item>...)
8446 This command has same capabilities as target_link_libraries()
8448 command.
8449 NOTE:
8451 If variable UseSWIG_TARGET_NAME_PREFERENCE is set to STAN‐
8452 DARD, this command is deprecated and target_link_libraries()
8453 command must be used instead.
8454 Source file properties on module files must be set before the invoca‐
8456 tion of the swig_add_library command to specify special behavior of
8457 SWIG and ensure generated files will receive the required settings.
8458 CPLUSPLUS
8460 Call SWIG in c++ mode. For example:
8461 set_property(SOURCE mymod.i PROPERTY CPLUSPLUS ON)
8463 swig_add_library(mymod LANGUAGE python SOURCES mymod.i)
8464 SWIG_FLAGS
8466 Deprecated since version 3.12: Replaced with the fine-grained
8467 properties that follow.
8468 Pass custom flags to the SWIG executable.
8471 INCLUDE_DIRECTORIES, COMPILE_DEFINITIONS and COMPILE_OPTIONS
8473 New in version 3.12.
8474 Add custom flags to SWIG compiler and have same semantic as
8477 properties INCLUDE_DIRECTORIES, COMPILE_DEFINITIONS and COM‐
8478 PILE_OPTIONS.
8479 USE_TARGET_INCLUDE_DIRECTORIES
8481 New in version 3.13.
8482 If set to TRUE, contents of target property INCLUDE_DIRECTORIES
8485 will be forwarded to SWIG compiler. If set to FALSE target
8486 property INCLUDE_DIRECTORIES will be ignored. If not set, target
8487 property SWIG_USE_TARGET_INCLUDE_DIRECTORIES will be considered.
8488 GENERATED_INCLUDE_DIRECTORIES, GENERATED_COMPILE_DEFINITIONS and GENER‐
8490 ATED_COMPILE_OPTIONS
8491 New in version 3.12.
8492 Add custom flags to the C/C++ generated source. They will fill,
8495 respectively, properties INCLUDE_DIRECTORIES, COMPILE_DEFINI‐
8496 TIONS and COMPILE_OPTIONS of generated C/C++ file.
8497 DEPENDS
8499 New in version 3.12.
8500 Specify additional dependencies to the source file.
8503 USE_SWIG_DEPENDENCIES
8505 New in version 3.20.
8506 If set to TRUE, implicit dependencies are generated by the swig
8509 tool itself. This property is only meaningful for Makefile and
8510 Ninja generators. Default value is FALSE.
8511 SWIG_MODULE_NAME
8513 Specify the actual import name of the module in the target lan‐
8514 guage. This is required if it cannot be scanned automatically
8515 from source or different from the module file basename. For ex‐
8516 ample:
8517 set_property(SOURCE mymod.i PROPERTY SWIG_MODULE_NAME mymod_realname)
8519 Changed in version 3.14: If policy CMP0086 is set to NEW, -mod‐
8521 ule <module_name> is passed to SWIG compiler.
8522 OUTPUT_DIR
8525 New in version 3.19.
8526 Specify where to write the language specific files (swig -outdir
8529 option) for the considered source file. If not specified, the
8530 other ways to define the output directory applies (see OUT‐
8531 PUT_DIR option of swig_add_library() command).
8532 OUTFILE_DIR
8534 New in version 3.19.
8535 Specify an output directory where the generated source file will
8538 be placed (swig -o option) for the considered source file. If
8539 not specified, OUTPUT_DIR source property will be used. If nei‐
8540 ther are specified, the other ways to define output file direc‐
8541 tory applies (see OUTFILE_DIR option of swig_add_library() com‐
8542 mand).
8543 Target library properties can be set to apply same configuration to all
8545 SWIG input files.
8546 SWIG_INCLUDE_DIRECTORIES, SWIG_COMPILE_DEFINITIONS and SWIG_COMPILE_OP‐
8548 TIONS
8549 New in version 3.12.
8550 These properties will be applied to all SWIG input files and
8553 have same semantic as target properties INCLUDE_DIRECTORIES,
8554 COMPILE_DEFINITIONS and COMPILE_OPTIONS.
8555 set (UseSWIG_TARGET_NAME_PREFERENCE STANDARD)
8557 swig_add_library(mymod LANGUAGE python SOURCES mymod.i)
8558 set_property(TARGET mymod PROPERTY SWIG_COMPILE_DEFINITIONS MY_DEF1 MY_DEF2)
8559 set_property(TARGET mymod PROPERTY SWIG_COMPILE_OPTIONS -bla -blb)
8560 SWIG_USE_TARGET_INCLUDE_DIRECTORIES
8562 New in version 3.13.
8563 If set to TRUE, contents of target property INCLUDE_DIRECTORIES
8566 will be forwarded to SWIG compiler. If set to FALSE or not de‐
8567 fined, target property INCLUDE_DIRECTORIES will be ignored. This
8568 behavior can be overridden by specifying source property
8569 USE_TARGET_INCLUDE_DIRECTORIES.
8570 SWIG_GENERATED_INCLUDE_DIRECTORIES, SWIG_GENERATED_COMPILE_DEFINITIONS
8572 and SWIG_GENERATED_COMPILE_OPTIONS
8573 New in version 3.12.
8574 These properties will populate, respectively, properties IN‐
8577 CLUDE_DIRECTORIES, COMPILE_DEFINITIONS and COMPILE_FLAGS of all
8578 generated C/C++ files.
8579 SWIG_DEPENDS
8581 New in version 3.12.
8582 Add dependencies to all SWIG input files.
8585 The following target properties are output properties and can be used
8587 to get information about support files generated by SWIG interface com‐
8588 pilation.
8589 SWIG_SUPPORT_FILES
8591 New in version 3.12.
8592 This output property list of wrapper files generated during SWIG
8595 compilation.
8596 set (UseSWIG_TARGET_NAME_PREFERENCE STANDARD)
8598 swig_add_library(mymod LANGUAGE python SOURCES mymod.i)
8599 get_property(support_files TARGET mymod PROPERTY SWIG_SUPPORT_FILES)
8600 NOTE:
8602 Only most principal support files are listed. In case some
8603 advanced features of SWIG are used (for example %template),
8604 associated support files may not be listed. Prefer to use the
8605 SWIG_SUPPORT_FILES_DIRECTORY property to handle support
8606 files.
8607 SWIG_SUPPORT_FILES_DIRECTORY
8609 New in version 3.12.
8610 This output property specifies the directory where support files
8613 will be generated.
8614 NOTE:
8616 When source property OUTPUT_DIR is defined, multiple directo‐
8617 ries can be specified as part of SWIG_SUPPORT_FILES_DIREC‐
8618 TORY.
8619 Some variables can be set to customize the behavior of swig_add_library
8621 as well as SWIG:
8622 UseSWIG_MODULE_VERSION
8624 New in version 3.12.
8625 Specify different behaviors for UseSWIG module.
8628 • Set to 1 or undefined: Legacy behavior is applied.
8630 • Set to 2: A new strategy is applied regarding support files:
8632 the output directory of support files is erased before SWIG
8633 interface compilation.
8634 CMAKE_SWIG_FLAGS
8636 Add flags to all swig calls.
8637 CMAKE_SWIG_OUTDIR
8639 Specify where to write the language specific files (swig -outdir
8640 option).
8641 SWIG_OUTFILE_DIR
8643 New in version 3.8.
8644 Specify an output directory name where the generated source file
8647 will be placed. If not specified, CMAKE_SWIG_OUTDIR is used.
8648 SWIG_MODULE_<name>_EXTRA_DEPS
8650 Specify extra dependencies for the generated module for <name>.
8651 SWIG_SOURCE_FILE_EXTENSIONS
8653 New in version 3.14.
8654 Specify a list of source file extensions to override the default
8657 behavior of considering only .i files as sources for the SWIG
8658 tool. For example:
8659 set(SWIG_SOURCE_FILE_EXTENSIONS ".i" ".swg")
8661 SWIG_USE_SWIG_DEPENDENCIES
8663 New in version 3.20.
8664 If set to TRUE, implicit dependencies are generated by the swig
8667 tool itself. This property is only meaningful for Makefile and
8668 Ninja generators. Default value is FALSE.
8669 Source file property USE_SWIG_DEPENDENCIES, if not defined, will
8671 be initialized with the value of this variable.
8672 UsewxWidgets
8674 Convenience include for using wxWidgets library.
8675 Determines if wxWidgets was FOUND and sets the appropriate libs, in‐
8677 cdirs, flags, etc. INCLUDE_DIRECTORIES and LINK_DIRECTORIES are
8678 called.
8679 USAGE
8681 # Note that for MinGW users the order of libs is important!
8683 find_package(wxWidgets REQUIRED net gl core base)
8684 include(${wxWidgets_USE_FILE})
8685 # and for each of your dependent executable/library targets:
8686 target_link_libraries(<YourTarget> ${wxWidgets_LIBRARIES})
8687 DEPRECATED
8689 LINK_LIBRARIES is not called in favor of adding dependencies per target.
8691 AUTHOR
8693 Jan Woetzel <jw -at- mip.informatik.uni-kiel.de>
8695
8697 These modules search for third-party software. They are normally
8698 called through the find_package() command.
8699 FindALSA
8701 Find Advanced Linux Sound Architecture (ALSA)
8702 Find the alsa libraries (asound)
8704 IMPORTED Targets
8706 New in version 3.12.
8707 This module defines IMPORTED target ALSA::ALSA, if ALSA has been found.
8710 Result Variables
8712 This module defines the following variables:
8713 ALSA_FOUND
8715 True if ALSA_INCLUDE_DIR & ALSA_LIBRARY are found
8716 ALSA_LIBRARIES
8718 List of libraries when using ALSA.
8719 ALSA_INCLUDE_DIRS
8721 Where to find the ALSA headers.
8722 Cache variables
8724 The following cache variables may also be set:
8725 ALSA_INCLUDE_DIR
8727 the ALSA include directory
8728 ALSA_LIBRARY
8730 the absolute path of the asound library
8731 FindArmadillo
8733 Find the Armadillo C++ library. Armadillo is a library for linear al‐
8734 gebra & scientific computing.
8735 New in version 3.18: Support for linking wrapped libraries directly
8737 (ARMA_DONT_USE_WRAPPER).
8738 Using Armadillo:
8741 find_package(Armadillo REQUIRED)
8743 include_directories(${ARMADILLO_INCLUDE_DIRS})
8744 add_executable(foo foo.cc)
8745 target_link_libraries(foo ${ARMADILLO_LIBRARIES})
8746 This module sets the following variables:
8748 ARMADILLO_FOUND - set to true if the library is found
8750 ARMADILLO_INCLUDE_DIRS - list of required include directories
8751 ARMADILLO_LIBRARIES - list of libraries to be linked
8752 ARMADILLO_VERSION_MAJOR - major version number
8753 ARMADILLO_VERSION_MINOR - minor version number
8754 ARMADILLO_VERSION_PATCH - patch version number
8755 ARMADILLO_VERSION_STRING - version number as a string (ex: "1.0.4")
8756 ARMADILLO_VERSION_NAME - name of the version (ex: "Antipodean Antileech")
8757 FindASPELL
8759 Try to find ASPELL
8760 Once done this will define
8762 ASPELL_FOUND - system has ASPELL
8764 ASPELL_EXECUTABLE - the ASPELL executable
8765 ASPELL_INCLUDE_DIR - the ASPELL include directory
8766 ASPELL_LIBRARIES - The libraries needed to use ASPELL
8767 ASPELL_DEFINITIONS - Compiler switches required for using ASPELL
8768 FindAVIFile
8770 Locate AVIFILE library and include paths
8771 AVIFILE (http://avifile.sourceforge.net/) is a set of libraries for
8773 i386 machines to use various AVI codecs. Support is limited beyond
8774 Linux. Windows provides native AVI support, and so doesn't need this
8775 library. This module defines
8776 AVIFILE_INCLUDE_DIR, where to find avifile.h , etc.
8778 AVIFILE_LIBRARIES, the libraries to link against
8779 AVIFILE_DEFINITIONS, definitions to use when compiling
8780 AVIFILE_FOUND, If false, don't try to use AVIFILE
8781 FindBacktrace
8783 Find provider for backtrace(3).
8784 Checks if OS supports backtrace(3) via either libc or custom library.
8786 This module defines the following variables:
8787 Backtrace_HEADER
8789 The header file needed for backtrace(3). Cached. Could be
8790 forcibly set by user.
8791 Backtrace_INCLUDE_DIRS
8793 The include directories needed to use backtrace(3) header.
8794 Backtrace_LIBRARIES
8796 The libraries (linker flags) needed to use backtrace(3), if any.
8797 Backtrace_FOUND
8799 Is set if and only if backtrace(3) support detected.
8800 The following cache variables are also available to set or use:
8802 Backtrace_LIBRARY
8804 The external library providing backtrace, if any.
8805 Backtrace_INCLUDE_DIR
8807 The directory holding the backtrace(3) header.
8808 Typical usage is to generate of header file using configure_file() with
8810 the contents like the following:
8811 #cmakedefine01 Backtrace_FOUND
8813 #if Backtrace_FOUND
8814 # include <${Backtrace_HEADER}>
8815 #endif
8816 And then reference that generated header file in actual source.
8818 FindBISON
8820 Find bison executable and provide a macro to generate custom build
8821 rules.
8822 The module defines the following variables:
8824 BISON_EXECUTABLE
8826 path to the bison program
8827 BISON_VERSION
8829 version of bison
8830 BISON_FOUND
8832 "True" if the program was found
8833 The minimum required version of bison can be specified using the stan‐
8835 dard CMake syntax, e.g. find_package(BISON 2.1.3).
8836 If bison is found, the module defines the macro:
8838 BISON_TARGET(<Name> <YaccInput> <CodeOutput>
8840 [COMPILE_FLAGS <flags>]
8841 [DEFINES_FILE <file>]
8842 [VERBOSE [<file>]]
8843 [REPORT_FILE <file>]
8844 )
8845 which will create a custom rule to generate a parser. <YaccInput> is
8847 the path to a yacc file. <CodeOutput> is the name of the source file
8848 generated by bison. A header file is also be generated, and contains
8849 the token list.
8850 Changed in version 3.14: When CMP0088 is set to NEW, bison runs in the
8852 CMAKE_CURRENT_BINARY_DIR directory.
8853 The options are:
8856 COMPILE_FLAGS <flags>
8858 Specify flags to be added to the bison command line.
8859 DEFINES_FILE <file>
8861 New in version 3.4.
8862 Specify a non-default header <file> to be generated by bison.
8865 VERBOSE [<file>]
8867 Tell bison to write a report file of the grammar and parser.
8868 Deprecated since version 3.7: If <file> is given, it specifies
8870 path the report file is copied to. [<file>] is left for back‐
8871 ward compatibility of this module. Use VERBOSE REPORT_FILE
8872 <file>.
8873 REPORT_FILE <file>
8876 New in version 3.7.
8877 Specify a non-default report <file>, if generated.
8880 The macro defines the following variables:
8882 BISON_<Name>_DEFINED
8884 True is the macro ran successfully
8885 BISON_<Name>_INPUT
8887 The input source file, an alias for <YaccInput>
8888 BISON_<Name>_OUTPUT_SOURCE
8890 The source file generated by bison
8891 BISON_<Name>_OUTPUT_HEADER
8893 The header file generated by bison
8894 BISON_<Name>_OUTPUTS
8896 All files generated by bison including the source, the header
8897 and the report
8898 BISON_<Name>_COMPILE_FLAGS
8900 Options used in the bison command line
8901 Example usage:
8903 find_package(BISON)
8905 BISON_TARGET(MyParser parser.y ${CMAKE_CURRENT_BINARY_DIR}/parser.cpp
8906 DEFINES_FILE ${CMAKE_CURRENT_BINARY_DIR}/parser.h)
8907 add_executable(Foo main.cpp ${BISON_MyParser_OUTPUTS})
8908 FindBLAS
8910 Find Basic Linear Algebra Subprograms (BLAS) library
8911 This module finds an installed Fortran library that implements the BLAS
8913 linear-algebra interface (see http://www.netlib.org/blas/).
8914 The approach follows that taken for the autoconf macro file,
8916 acx_blas.m4 (distributed at
8917 http://ac-archive.sourceforge.net/ac-archive/acx_blas.html).
8918 Input Variables
8920 The following variables may be set to influence this module's behavior:
8921 BLA_STATIC
8923 if ON use static linkage
8924 BLA_VENDOR
8926 If set, checks only the specified vendor, if not set checks all
8927 the possibilities. List of vendors valid in this module:
8928 • Goto
8930 • FlexiBLAS
8932 • OpenBLAS
8934 • FLAME
8936 • ATLAS PhiPACK
8938 • CXML
8940 • DXML
8942 • SunPerf
8944 • SCSL
8946 • SGIMATH
8948 • IBMESSL
8950 • Intel10_32 (intel mkl v10 32 bit, threaded code)
8952 • Intel10_64lp (intel mkl v10+ 64 bit, threaded code, lp64
8954 model)
8955 • Intel10_64lp_seq (intel mkl v10+ 64 bit, sequential code, lp64
8957 model)
8958 • Intel10_64ilp (intel mkl v10+ 64 bit, threaded code, ilp64
8960 model)
8961 • Intel10_64ilp_seq (intel mkl v10+ 64 bit, sequential code,
8963 ilp64 model)
8964 • Intel10_64_dyn (intel mkl v10+ 64 bit, single dynamic library)
8966 • Intel (obsolete versions of mkl 32 and 64 bit)
8968 • ACML
8970 • ACML_MP
8972 • ACML_GPU
8974 • Apple
8976 • NAS
8978 • Arm
8980 • Arm_mp
8982 • Arm_ilp64
8984 • Arm_ilp64_mp
8986 • EML
8988 • EML_mt
8990 • Generic
8992 New in version 3.6: OpenBLAS support.
8994 New in version 3.11: FLAME support.
8997 New in version 3.13: Added ILP64 MKL variants (Intel10_64ilp,
9000 Intel10_64ilp_seq).
9001 New in version 3.17: Added single dynamic library MKL variant
9004 (Intel10_64_dyn).
9005 New in version 3.18: Arm Performance Libraries support (Arm,
9008 Arm_mp, Arm_ilp64, Arm_ilp64_mp).
9009 New in version 3.19: FlexiBLAS support.
9012 New in version 3.20: Elbrus Math Library support (EML, EML_mt).
9015 BLA_F95
9018 if ON tries to find the BLAS95 interfaces
9019 BLA_PREFER_PKGCONFIG
9021 New in version 3.11.
9022 if set pkg-config will be used to search for a BLAS library
9025 first and if one is found that is preferred
9026 Imported targets
9028 New in version 3.18.
9029 This module defines the following IMPORTED target:
9032 BLAS::BLAS
9034 The libraries to use for BLAS, if found.
9035 Result Variables
9037 This module defines the following variables:
9038 BLAS_FOUND
9040 library implementing the BLAS interface is found
9041 BLAS_LINKER_FLAGS
9043 uncached list of required linker flags (excluding -l and -L).
9044 BLAS_LIBRARIES
9046 uncached list of libraries (using full path name) to link
9047 against to use BLAS (may be empty if compiler implicitly links
9048 BLAS)
9049 BLAS95_LIBRARIES
9051 uncached list of libraries (using full path name) to link
9052 against to use BLAS95 interface
9053 BLAS95_FOUND
9055 library implementing the BLAS95 interface is found
9056 NOTE:
9058 C, CXX or Fortran must be enabled to detect a BLAS library. C or
9059 CXX must be enabled to use Intel Math Kernel Library (MKL).
9060 For example, to use Intel MKL libraries and/or Intel compiler:
9062 set(BLA_VENDOR Intel10_64lp)
9064 find_package(BLAS)
9065 Hints
9067 MKLROOT
9068 New in version 3.15.
9069 Set this environment variable to a directory that contains an
9072 MKL installation, or add the directory to the dynamic library
9073 loader environment variable for your platform (LIB, DYLD_LI‐
9074 BRARY_PATH or LD_LIBRARY_PATH).
9075 FindBoost
9077 Find Boost include dirs and libraries
9078 Use this module by invoking find_package() with the form:
9080 find_package(Boost
9082 [version] [EXACT] # Minimum or EXACT version e.g. 1.67.0
9083 [REQUIRED] # Fail with error if Boost is not found
9084 [COMPONENTS <libs>...] # Boost libraries by their canonical name
9085 # e.g. "date_time" for "libboost_date_time"
9086 [OPTIONAL_COMPONENTS <libs>...]
9087 # Optional Boost libraries by their canonical name)
9088 ) # e.g. "date_time" for "libboost_date_time"
9089 This module finds headers and requested component libraries OR a CMake
9091 package configuration file provided by a "Boost CMake" build. For the
9092 latter case skip to the Boost CMake section below.
9093 New in version 3.7: bzip2 and zlib components (Windows only).
9095 New in version 3.11: The OPTIONAL_COMPONENTS option.
9098 New in version 3.13: stacktrace_* components.
9101 New in version 3.19: bzip2 and zlib components on all platforms.
9104 Result Variables
9107 This module defines the following variables:
9108 Boost_FOUND
9110 True if headers and requested libraries were found.
9111 Boost_INCLUDE_DIRS
9113 Boost include directories.
9114 Boost_LIBRARY_DIRS
9116 Link directories for Boost libraries.
9117 Boost_LIBRARIES
9119 Boost component libraries to be linked.
9120 Boost_<COMPONENT>_FOUND
9122 True if component <COMPONENT> was found (<COMPONENT> name is up‐
9123 per-case).
9124 Boost_<COMPONENT>_LIBRARY
9126 Libraries to link for component <COMPONENT> (may include tar‐
9127 get_link_libraries() debug/optimized keywords).
9128 Boost_VERSION_MACRO
9130 BOOST_VERSION value from boost/version.hpp.
9131 Boost_VERSION_STRING
9133 Boost version number in X.Y.Z format.
9134 Boost_VERSION
9136 Boost version number in X.Y.Z format (same as Boost_VER‐
9137 SION_STRING).
9138 Changed in version 3.15: In previous CMake versions, this vari‐
9140 able used the raw version string from the Boost header (same as
9141 Boost_VERSION_MACRO). See policy CMP0093.
9142 Boost_LIB_VERSION
9145 Version string appended to library filenames.
9146 Boost_VERSION_MAJOR, Boost_MAJOR_VERSION
9148 Boost major version number (X in X.Y.Z).
9149 Boost_VERSION_MINOR, Boost_MINOR_VERSION
9151 Boost minor version number (Y in X.Y.Z).
9152 Boost_VERSION_PATCH, Boost_SUBMINOR_VERSION
9154 Boost subminor version number (Z in X.Y.Z).
9155 Boost_VERSION_COUNT
9157 Amount of version components (3).
9158 Boost_LIB_DIAGNOSTIC_DEFINITIONS (Windows-specific)
9160 Pass to add_definitions() to have diagnostic information about
9161 Boost's automatic linking displayed during compilation
9162 New in version 3.15: The Boost_VERSION_<PART> variables.
9164 Cache variables
9167 Search results are saved persistently in CMake cache entries:
9168 Boost_INCLUDE_DIR
9170 Directory containing Boost headers.
9171 Boost_LIBRARY_DIR_RELEASE
9173 Directory containing release Boost libraries.
9174 Boost_LIBRARY_DIR_DEBUG
9176 Directory containing debug Boost libraries.
9177 Boost_<COMPONENT>_LIBRARY_DEBUG
9179 Component <COMPONENT> library debug variant.
9180 Boost_<COMPONENT>_LIBRARY_RELEASE
9182 Component <COMPONENT> library release variant.
9183 New in version 3.3: Per-configuration variables Boost_LIBRARY_DIR_RE‐
9185 LEASE and Boost_LIBRARY_DIR_DEBUG.
9186 Hints
9189 This module reads hints about search locations from variables:
9190 BOOST_ROOT, BOOSTROOT
9192 Preferred installation prefix.
9193 BOOST_INCLUDEDIR
9195 Preferred include directory e.g. <prefix>/include.
9196 BOOST_LIBRARYDIR
9198 Preferred library directory e.g. <prefix>/lib.
9199 Boost_NO_SYSTEM_PATHS
9201 Set to ON to disable searching in locations not specified by
9202 these hint variables. Default is OFF.
9203 Boost_ADDITIONAL_VERSIONS
9205 List of Boost versions not known to this module. (Boost install
9206 locations may contain the version).
9207 Users may set these hints or results as CACHE entries. Projects should
9209 not read these entries directly but instead use the above result vari‐
9210 ables. Note that some hint names start in upper-case BOOST. One may
9211 specify these as environment variables if they are not specified as
9212 CMake variables or cache entries.
9213 This module first searches for the Boost header files using the above
9215 hint variables (excluding BOOST_LIBRARYDIR) and saves the result in
9216 Boost_INCLUDE_DIR. Then it searches for requested component libraries
9217 using the above hints (excluding BOOST_INCLUDEDIR and Boost_ADDI‐
9218 TIONAL_VERSIONS), "lib" directories near Boost_INCLUDE_DIR, and the li‐
9219 brary name configuration settings below. It saves the library directo‐
9220 ries in Boost_LIBRARY_DIR_DEBUG and Boost_LIBRARY_DIR_RELEASE and indi‐
9221 vidual library locations in Boost_<COMPONENT>_LIBRARY_DEBUG and
9222 Boost_<COMPONENT>_LIBRARY_RELEASE. When one changes settings used by
9223 previous searches in the same build tree (excluding environment vari‐
9224 ables) this module discards previous search results affected by the
9225 changes and searches again.
9226 Imported Targets
9228 New in version 3.5.
9229 This module defines the following IMPORTED targets:
9232 Boost::boost
9234 Target for header-only dependencies. (Boost include directory).
9235 Boost::headers
9237 New in version 3.15: Alias for Boost::boost.
9238 Boost::<component>
9241 Target for specific component dependency (shared or static li‐
9242 brary); <component> name is lower-case.
9243 Boost::diagnostic_definitions
9245 Interface target to enable diagnostic information about Boost's
9246 automatic linking during compilation (adds -DBOOST_LIB_DIAGNOS‐
9247 TIC).
9248 Boost::disable_autolinking
9250 Interface target to disable automatic linking with MSVC (adds
9251 -DBOOST_ALL_NO_LIB).
9252 Boost::dynamic_linking
9254 Interface target to enable dynamic linking linking with MSVC
9255 (adds -DBOOST_ALL_DYN_LINK).
9256 Implicit dependencies such as Boost::filesystem requiring Boost::system
9258 will be automatically detected and satisfied, even if system is not
9259 specified when using find_package() and if Boost::system is not added
9260 to target_link_libraries(). If using Boost::thread, then
9261 Threads::Threads will also be added automatically.
9262 It is important to note that the imported targets behave differently
9264 than variables created by this module: multiple calls to find_pack‐
9265 age(Boost) in the same directory or sub-directories with different op‐
9266 tions (e.g. static or shared) will not override the values of the tar‐
9267 gets created by the first call.
9268 Other Variables
9270 Boost libraries come in many variants encoded in their file name.
9271 Users or projects may tell this module which variant to find by setting
9272 variables:
9273 Boost_USE_DEBUG_LIBS
9275 New in version 3.10.
9276 Set to ON or OFF to specify whether to search and use the debug
9279 libraries. Default is ON.
9280 Boost_USE_RELEASE_LIBS
9282 New in version 3.10.
9283 Set to ON or OFF to specify whether to search and use the re‐
9286 lease libraries. Default is ON.
9287 Boost_USE_MULTITHREADED
9289 Set to OFF to use the non-multithreaded libraries ("mt" tag).
9290 Default is ON.
9291 Boost_USE_STATIC_LIBS
9293 Set to ON to force the use of the static libraries. Default is
9294 OFF.
9295 Boost_USE_STATIC_RUNTIME
9297 Set to ON or OFF to specify whether to use libraries linked
9298 statically to the C++ runtime ("s" tag). Default is platform
9299 dependent.
9300 Boost_USE_DEBUG_RUNTIME
9302 Set to ON or OFF to specify whether to use libraries linked to
9303 the MS debug C++ runtime ("g" tag). Default is ON.
9304 Boost_USE_DEBUG_PYTHON
9306 Set to ON to use libraries compiled with a debug Python build
9307 ("y" tag). Default is OFF.
9308 Boost_USE_STLPORT
9310 Set to ON to use libraries compiled with STLPort ("p" tag). De‐
9311 fault is OFF.
9312 Boost_USE_STLPORT_DEPRECATED_NATIVE_IOSTREAMS
9314 Set to ON to use libraries compiled with STLPort deprecated "na‐
9315 tive iostreams" ("n" tag). Default is OFF.
9316 Boost_COMPILER
9318 Set to the compiler-specific library suffix (e.g. -gcc43). De‐
9319 fault is auto-computed for the C++ compiler in use.
9320 Changed in version 3.9: A list may be used if multiple compati‐
9322 ble suffixes should be tested for, in decreasing order of pref‐
9323 erence.
9324 Boost_LIB_PREFIX
9327 New in version 3.18.
9328 Set to the platform-specific library name prefix (e.g. lib) used
9331 by Boost static libs. This is needed only on platforms where
9332 CMake does not know the prefix by default.
9333 Boost_ARCHITECTURE
9335 New in version 3.13.
9336 Set to the architecture-specific library suffix (e.g. -x64).
9339 Default is auto-computed for the C++ compiler in use.
9340 Boost_THREADAPI
9342 Suffix for thread component library name, such as pthread or
9343 win32. Names with and without this suffix will both be tried.
9344 Boost_NAMESPACE
9346 Alternate namespace used to build boost with e.g. if set to my‐
9347 boost, will search for myboost_thread instead of boost_thread.
9348 Other variables one may set to control this module are:
9350 Boost_DEBUG
9352 Set to ON to enable debug output from FindBoost. Please enable
9353 this before filing any bug report.
9354 Boost_REALPATH
9356 Set to ON to resolve symlinks for discovered libraries to assist
9357 with packaging. For example, the "system" component library may
9358 be resolved to /usr/lib/libboost_system.so.1.67.0 instead of
9359 /usr/lib/libboost_system.so. This does not affect linking and
9360 should not be enabled unless the user needs this information.
9361 Boost_LIBRARY_DIR
9363 Default value for Boost_LIBRARY_DIR_RELEASE and Boost_LI‐
9364 BRARY_DIR_DEBUG.
9365 Boost_NO_WARN_NEW_VERSIONS
9367 New in version 3.20.
9368 Set to ON to suppress the warning about unknown dependencies for
9371 new Boost versions.
9372 On Visual Studio and Borland compilers Boost headers request automatic
9374 linking to corresponding libraries. This requires matching libraries
9375 to be linked explicitly or available in the link library search path.
9376 In this case setting Boost_USE_STATIC_LIBS to OFF may not achieve dy‐
9377 namic linking. Boost automatic linking typically requests static li‐
9378 braries with a few exceptions (such as Boost.Python). Use:
9379 add_definitions(${Boost_LIB_DIAGNOSTIC_DEFINITIONS})
9381 to ask Boost to report information about automatic linking requests.
9383 Examples
9385 Find Boost headers only:
9386 find_package(Boost 1.36.0)
9388 if(Boost_FOUND)
9389 include_directories(${Boost_INCLUDE_DIRS})
9390 add_executable(foo foo.cc)
9391 endif()
9392 Find Boost libraries and use imported targets:
9394 find_package(Boost 1.56 REQUIRED COMPONENTS
9396 date_time filesystem iostreams)
9397 add_executable(foo foo.cc)
9398 target_link_libraries(foo Boost::date_time Boost::filesystem
9399 Boost::iostreams)
9400 Find Boost Python 3.6 libraries and use imported targets:
9402 find_package(Boost 1.67 REQUIRED COMPONENTS
9404 python36 numpy36)
9405 add_executable(foo foo.cc)
9406 target_link_libraries(foo Boost::python36 Boost::numpy36)
9407 Find Boost headers and some static (release only) libraries:
9409 set(Boost_USE_STATIC_LIBS ON) # only find static libs
9411 set(Boost_USE_DEBUG_LIBS OFF) # ignore debug libs and
9412 set(Boost_USE_RELEASE_LIBS ON) # only find release libs
9413 set(Boost_USE_MULTITHREADED ON)
9414 set(Boost_USE_STATIC_RUNTIME OFF)
9415 find_package(Boost 1.66.0 COMPONENTS date_time filesystem system ...)
9416 if(Boost_FOUND)
9417 include_directories(${Boost_INCLUDE_DIRS})
9418 add_executable(foo foo.cc)
9419 target_link_libraries(foo ${Boost_LIBRARIES})
9420 endif()
9421 Boost CMake
9423 If Boost was built using the boost-cmake project or from Boost 1.70.0
9424 on it provides a package configuration file for use with find_package's
9425 config mode. This module looks for the package configuration file
9426 called BoostConfig.cmake or boost-config.cmake and stores the result in
9427 CACHE entry Boost_DIR. If found, the package configuration file is
9428 loaded and this module returns with no further action. See documenta‐
9429 tion of the Boost CMake package configuration for details on what it
9430 provides.
9431 Set Boost_NO_BOOST_CMAKE to ON, to disable the search for boost-cmake.
9433 FindBullet
9435 Try to find the Bullet physics engine
9436 This module defines the following variables
9438 BULLET_FOUND - Was bullet found
9440 BULLET_INCLUDE_DIRS - the Bullet include directories
9441 BULLET_LIBRARIES - Link to this, by default it includes
9442 all bullet components (Dynamics,
9443 Collision, LinearMath, & SoftBody)
9444 This module accepts the following variables
9446 BULLET_ROOT - Can be set to bullet install path or Windows build path
9448 FindBZip2
9450 Try to find BZip2
9451 IMPORTED Targets
9453 New in version 3.12.
9454 This module defines IMPORTED target BZip2::BZip2, if BZip2 has been
9457 found.
9458 Result Variables
9460 This module defines the following variables:
9461 BZIP2_FOUND
9463 system has BZip2
9464 BZIP2_INCLUDE_DIRS
9466 New in version 3.12: the BZip2 include directories
9467 BZIP2_LIBRARIES
9470 Link these to use BZip2
9471 BZIP2_NEED_PREFIX
9473 this is set if the functions are prefixed with BZ2_
9474 BZIP2_VERSION_STRING
9476 the version of BZip2 found
9477 Cache variables
9479 The following cache variables may also be set:
9480 BZIP2_INCLUDE_DIR
9482 the BZip2 include directory
9483 FindCABLE
9485 Find CABLE
9486 This module finds if CABLE is installed and determines where the in‐
9488 clude files and libraries are. This code sets the following variables:
9489 CABLE the path to the cable executable
9491 CABLE_TCL_LIBRARY the path to the Tcl wrapper library
9492 CABLE_INCLUDE_DIR the path to the include directory
9493 To build Tcl wrappers, you should add shared library and link it to
9495 ${CABLE_TCL_LIBRARY}. You should also add ${CABLE_INCLUDE_DIR} as an
9496 include directory.
9497 FindCoin3D
9499 Find Coin3D (Open Inventor)
9500 Coin3D is an implementation of the Open Inventor API. It provides data
9502 structures and algorithms for 3D visualization.
9503 This module defines the following variables
9505 COIN3D_FOUND - system has Coin3D - Open Inventor
9507 COIN3D_INCLUDE_DIRS - where the Inventor include directory can be found
9508 COIN3D_LIBRARIES - Link to this to use Coin3D
9509 FindCUDAToolkit
9511 New in version 3.17.
9512 This script locates the NVIDIA CUDA toolkit and the associated li‐
9515 braries, but does not require the CUDA language be enabled for a given
9516 project. This module does not search for the NVIDIA CUDA Samples.
9517 New in version 3.19: QNX support.
9519 Search Behavior
9522 The CUDA Toolkit search behavior uses the following order:
9523 1. If the CUDA language has been enabled we will use the directory con‐
9525 taining the compiler as the first search location for nvcc.
9526 2. If the CUDAToolkit_ROOT cmake configuration variable (e.g., -DCUDA‐
9528 Toolkit_ROOT=/some/path) or environment variable is defined, it will
9529 be searched. If both an environment variable and a configuration
9530 variable are specified, the configuration variable takes precedence.
9531 The directory specified here must be such that the executable nvcc
9533 or the appropriate version.txt file can be found underneath the
9534 specified directory.
9535 3. If the CUDA_PATH environment variable is defined, it will be
9537 searched for nvcc.
9538 4. The user's path is searched for nvcc using find_program(). If this
9540 is found, no subsequent search attempts are performed. Users are
9541 responsible for ensuring that the first nvcc to show up in the path
9542 is the desired path in the event that multiple CUDA Toolkits are in‐
9543 stalled.
9544 5. On Unix systems, if the symbolic link /usr/local/cuda exists, this
9546 is used. No subsequent search attempts are performed. No default
9547 symbolic link location exists for the Windows platform.
9548 6. The platform specific default install locations are searched. If
9550 exactly one candidate is found, this is used. The default CUDA
9551 Toolkit install locations searched are:
9552 ┌───────────┬────────────────────────────┐
9554 │Platform │ Search Pattern │
9555 ├───────────┼────────────────────────────┤
9556 │macOS │ /Developer/NVIDIA/CUDA-X.Y │
9557 ├───────────┼────────────────────────────┤
9558 │Other Unix │ /usr/local/cuda-X.Y │
9559 ├───────────┼────────────────────────────┤
9560 │Windows │ C:\Program Files\NVIDIA │
9561 │ │ GPU Computing Tool‐ │
9562 │ │ kit\CUDA\vX.Y │
9563 └───────────┴────────────────────────────┘
9564 Where X.Y would be a specific version of the CUDA Toolkit, such as
9566 /usr/local/cuda-9.0 or C:\Program Files\NVIDIA GPU Computing Tool‐
9567 kit\CUDA\v9.0
9568 NOTE:
9570 When multiple CUDA Toolkits are installed in the default location
9571 of a system (e.g., both /usr/local/cuda-9.0 and /usr/lo‐
9572 cal/cuda-10.0 exist but the /usr/local/cuda symbolic link does
9573 not exist), this package is marked as not found.
9574 There are too many factors involved in making an automatic deci‐
9576 sion in the presence of multiple CUDA Toolkits being installed.
9577 In this situation, users are encouraged to either (1) set CUDA‐
9578 Toolkit_ROOT [22mor (2) ensure that the correct nvcc executable shows
9579 up in $PATH for find_program() to find.
9580 Options
9582 VERSION
9583 If specified, describes the version of the CUDA Toolkit to
9584 search for.
9585 REQUIRED
9587 If specified, configuration will error if a suitable CUDA Tool‐
9588 kit is not found.
9589 QUIET If specified, the search for a suitable CUDA Toolkit will not
9591 produce any messages.
9592 EXACT If specified, the CUDA Toolkit is considered found only if the
9594 exact VERSION specified is recovered.
9595 Imported targets
9597 An imported target named CUDA::toolkit is provided.
9598 This module defines IMPORTED targets for each of the following li‐
9600 braries that are part of the CUDAToolkit:
9601 • CUDA Runtime Library
9603 • CUDA Driver Library
9605 • cuBLAS
9607 • cuFFT
9609 • cuRAND
9611 • cuSOLVER
9613 • cuSPARSE
9615 • cuPTI
9617 • NPP
9619 • nvBLAS
9621 • nvGRAPH
9623 • nvJPEG
9625 • nvidia-ML
9627 • nvRTC
9629 • nvToolsExt
9631 • OpenCL
9633 • cuLIBOS
9635 CUDA Runtime Library
9637 The CUDA Runtime library (cudart) are what most applications will typi‐
9638 cally need to link against to make any calls such as cudaMalloc, and
9639 cudaFree.
9640 Targets Created:
9642 • CUDA::cudart
9644 • CUDA::cudart_static
9646 CUDA Driver Library
9648 The CUDA Driver library (cuda) are used by applications that use calls
9649 such as cuMemAlloc, and cuMemFree. This is generally used by advanced
9650 Targets Created:
9652 • CUDA::cuda_driver
9654 • CUDA::cuda_driver
9656 cuBLAS
9658 The cuBLAS library.
9659 Targets Created:
9661 • CUDA::cublas
9663 • CUDA::cublas_static
9665 • CUDA::cublasLt starting in CUDA 10.1
9667 • CUDA::cublasLt_static starting in CUDA 10.1
9669 cuFFT
9671 The cuFFT library.
9672 Targets Created:
9674 • CUDA::cufft
9676 • CUDA::cufftw
9678 • CUDA::cufft_static
9680 • CUDA::cufftw_static
9682 cuRAND
9684 The cuRAND library.
9685 Targets Created:
9687 • CUDA::curand
9689 • CUDA::curand_static
9691 cuSOLVER
9693 The cuSOLVER library.
9694 Targets Created:
9696 • CUDA::cusolver
9698 • CUDA::cusolver_static
9700 cuSPARSE
9702 The cuSPARSE library.
9703 Targets Created:
9705 • CUDA::cusparse
9707 • CUDA::cusparse_static
9709 cupti
9711 The NVIDIA CUDA Profiling Tools Interface.
9712 Targets Created:
9714 • CUDA::cupti
9716 • CUDA::cupti_static
9718 NPP
9720 The NPP libraries.
9721 Targets Created:
9723 • nppc:
9725 • CUDA::nppc
9727 • CUDA::nppc_static
9729 • nppial: Arithmetic and logical operation functions in nppi_arith‐
9731 metic_and_logical_operations.h
9732 • CUDA::nppial
9734 • CUDA::nppial_static
9736 • nppicc: Color conversion and sampling functions in nppi_color_conver‐
9738 sion.h
9739 • CUDA::nppicc
9741 • CUDA::nppicc_static
9743 • nppicom: JPEG compression and decompression functions in nppi_com‐
9745 pression_functions.h Removed starting in CUDA 11.0, use nvJPEG in‐
9746 stead.
9747 • CUDA::nppicom
9749 • CUDA::nppicom_static
9751 • nppidei: Data exchange and initialization functions in nppi_data_ex‐
9753 change_and_initialization.h
9754 • CUDA::nppidei
9756 • CUDA::nppidei_static
9758 • nppif: Filtering and computer vision functions in nppi_filter_func‐
9760 tions.h
9761 • CUDA::nppif
9763 • CUDA::nppif_static
9765 • nppig: Geometry transformation functions found in nppi_geome‐
9767 try_transforms.h
9768 • CUDA::nppig
9770 • CUDA::nppig_static
9772 • nppim: Morphological operation functions found in nppi_morphologi‐
9774 cal_operations.h
9775 • CUDA::nppim
9777 • CUDA::nppim_static
9779 • nppist: Statistics and linear transform in nppi_statistics_func‐
9781 tions.h and nppi_linear_transforms.h
9782 • CUDA::nppist
9784 • CUDA::nppist_static
9786 • nppisu: Memory support functions in nppi_support_functions.h
9788 • CUDA::nppisu
9790 • CUDA::nppisu_static
9792 • nppitc: Threshold and compare operation functions in nppi_thresh‐
9794 old_and_compare_operations.h
9795 • CUDA::nppitc
9797 • CUDA::nppitc_static
9799 • npps:
9801 • CUDA::npps
9803 • CUDA::npps_static
9805 nvBLAS
9807 The nvBLAS libraries. This is a shared library only.
9808 Targets Created:
9810 • CUDA::nvblas
9812 nvGRAPH
9814 The nvGRAPH library. Removed starting in CUDA 11.0
9815 Targets Created:
9817 • CUDA::nvgraph
9819 • CUDA::nvgraph_static
9821 nvJPEG
9823 The nvJPEG library. Introduced in CUDA 10.
9824 Targets Created:
9826 • CUDA::nvjpeg
9828 • CUDA::nvjpeg_static
9830 nvRTC
9832 The nvRTC (Runtime Compilation) library. This is a shared library
9833 only.
9834 Targets Created:
9836 • CUDA::nvrtc
9838 nvidia-ML
9840 The NVIDIA Management Library. This is a shared library only.
9841 Targets Created:
9843 • CUDA::nvml
9845 nvToolsExt
9847 The NVIDIA Tools Extension. This is a shared library only.
9848 Targets Created:
9850 • CUDA::nvToolsExt
9852 OpenCL
9854 The NVIDIA OpenCL Library. This is a shared library only.
9855 Targets Created:
9857 • CUDA::OpenCL
9859 cuLIBOS
9861 The cuLIBOS library is a backend thread abstraction layer library which
9862 is static only. The CUDA::cublas_static, CUDA::cusparse_static,
9863 CUDA::cufft_static, CUDA::curand_static, and (when implemented) NPP li‐
9864 braries all automatically have this dependency linked.
9865 Target Created:
9867 • CUDA::culibos
9869 Note: direct usage of this target by consumers should not be necessary.
9871 Result variables
9873 CUDAToolkit_FOUND
9874 A boolean specifying whether or not the CUDA Toolkit was found.
9875 CUDAToolkit_VERSION
9877 The exact version of the CUDA Toolkit found (as reported by nvcc
9878 --version or version.txt).
9879 CUDAToolkit_VERSION_MAJOR
9881 The major version of the CUDA Toolkit.
9882 CUDAToolkit_VERSION_MAJOR
9884 The minor version of the CUDA Toolkit.
9885 CUDAToolkit_VERSION_PATCH
9887 The patch version of the CUDA Toolkit.
9888 CUDAToolkit_BIN_DIR
9890 The path to the CUDA Toolkit library directory that contains the
9891 CUDA executable nvcc.
9892 CUDAToolkit_INCLUDE_DIRS
9894 The path to the CUDA Toolkit include folder containing the
9895 header files required to compile a project linking against CUDA.
9896 CUDAToolkit_LIBRARY_DIR
9898 The path to the CUDA Toolkit library directory that contains the
9899 CUDA Runtime library cudart.
9900 CUDAToolkit_LIBRARY_ROOT
9902 New in version 3.18.
9903 The path to the CUDA Toolkit directory containing the nvvm di‐
9906 rectory and version.txt.
9907 CUDAToolkit_TARGET_DIR
9909 The path to the CUDA Toolkit directory including the target ar‐
9910 chitecture when cross-compiling. When not cross-compiling this
9911 will be equivalent to the parent directory of CUDA‐
9912 Toolkit_BIN_DIR.
9913 CUDAToolkit_NVCC_EXECUTABLE
9915 The path to the NVIDIA CUDA compiler nvcc. Note that this path
9916 may not be the same as CMAKE_CUDA_COMPILER. nvcc must be found
9917 to determine the CUDA Toolkit version as well as determining
9918 other features of the Toolkit. This variable is set for the
9919 convenience of modules that depend on this one.
9920 FindCups
9922 Find the Common UNIX Printing System (CUPS).
9923 Set CUPS_REQUIRE_IPP_DELETE_ATTRIBUTE to TRUE if you need a version
9925 which features this function (i.e. at least 1.1.19)
9926 Imported targets
9928 New in version 3.15.
9929 This module defines IMPORTED target Cups::Cups, if Cups has been found.
9932 Result variables
9934 This module will set the following variables in your project:
9935 CUPS_FOUND
9937 true if CUPS headers and libraries were found
9938 CUPS_INCLUDE_DIRS
9940 the directory containing the Cups headers
9941 CUPS_LIBRARIES
9943 the libraries to link against to use CUPS.
9944 CUPS_VERSION_STRING
9946 the version of CUPS found (since CMake 2.8.8)
9947 Cache variables
9949 The following cache variables may also be set:
9950 CUPS_INCLUDE_DIR
9952 the directory containing the Cups headers
9953 FindCURL
9955 Find the native CURL headers and libraries.
9956 New in version 3.14: This module accept optional COMPONENTS to check
9958 supported features and protocols:
9959 PROTOCOLS: ICT FILE FTP FTPS GOPHER HTTP HTTPS IMAP IMAPS LDAP LDAPS POP3
9962 POP3S RTMP RTSP SCP SFTP SMB SMBS SMTP SMTPS TELNET TFTP
9963 FEATURES: SSL IPv6 UnixSockets libz AsynchDNS IDN GSS-API PSL SPNEGO
9964 Kerberos NTLM NTLM_WB TLS-SRP HTTP2 HTTPS-proxy
9965 IMPORTED Targets
9967 New in version 3.12.
9968 This module defines IMPORTED target CURL::libcurl, if curl has been
9971 found.
9972 Result Variables
9974 This module defines the following variables:
9975 CURL_FOUND
9977 "True" if curl found.
9978 CURL_INCLUDE_DIRS
9980 where to find curl/curl.h, etc.
9981 CURL_LIBRARIES
9983 List of libraries when using curl.
9984 CURL_VERSION_STRING
9986 The version of curl found.
9987 New in version 3.13: Debug and Release variants are found separately.
9989 CURL CMake
9992 New in version 3.17.
9993 If CURL was built using the CMake buildsystem then it provides its own
9996 CURLConfig.cmake file for use with the find_package() command's config
9997 mode. This module looks for this file and, if found, returns its re‐
9998 sults with no further action.
9999 Set CURL_NO_CURL_CMAKE to ON to disable this search.
10001 FindCurses
10003 Find the curses or ncurses include file and library.
10004 Result Variables
10006 This module defines the following variables:
10007 CURSES_FOUND
10009 True if Curses is found.
10010 CURSES_INCLUDE_DIRS
10012 The include directories needed to use Curses.
10013 CURSES_LIBRARIES
10015 The libraries needed to use Curses.
10016 CURSES_CFLAGS
10018 New in version 3.16.
10019 Parameters which ought be given to C/C++ compilers when using
10022 Curses.
10023 CURSES_HAVE_CURSES_H
10025 True if curses.h is available.
10026 CURSES_HAVE_NCURSES_H
10028 True if ncurses.h is available.
10029 CURSES_HAVE_NCURSES_NCURSES_H
10031 True if ncurses/ncurses.h is available.
10032 CURSES_HAVE_NCURSES_CURSES_H
10034 True if ncurses/curses.h is available.
10035 Set CURSES_NEED_NCURSES to TRUE before the find_package(Curses) call if
10037 NCurses functionality is required.
10038 New in version 3.10: Set CURSES_NEED_WIDE to TRUE before the find_pack‐
10040 age(Curses) call if unicode functionality is required.
10041 Backward Compatibility
10044 The following variable are provided for backward compatibility:
10045 CURSES_INCLUDE_DIR
10047 Path to Curses include. Use CURSES_INCLUDE_DIRS instead.
10048 CURSES_LIBRARY
10050 Path to Curses library. Use CURSES_LIBRARIES instead.
10051 FindCVS
10053 Find the Concurrent Versions System (CVS).
10054 The module defines the following variables:
10056 CVS_EXECUTABLE - path to cvs command line client
10058 CVS_FOUND - true if the command line client was found
10059 Example usage:
10061 find_package(CVS)
10063 if(CVS_FOUND)
10064 message("CVS found: ${CVS_EXECUTABLE}")
10065 endif()
10066 FindCxxTest
10068 Find CxxTest unit testing framework.
10069 Find the CxxTest suite and declare a helper macro for creating unit
10071 tests and integrating them with CTest. For more details on CxxTest see
10072 http://cxxtest.tigris.org
10073 INPUT Variables
10075 CXXTEST_USE_PYTHON [deprecated since 1.3]
10077 Only used in the case both Python & Perl
10078 are detected on the system to control
10079 which CxxTest code generator is used.
10080 Valid only for CxxTest version 3.
10081 NOTE: In older versions of this Find Module,
10083 this variable controlled if the Python test
10084 generator was used instead of the Perl one,
10085 regardless of which scripting language the
10086 user had installed.
10087 CXXTEST_TESTGEN_ARGS (since CMake 2.8.3)
10089 Specify a list of options to pass to the CxxTest code
10090 generator. If not defined, --error-printer is
10091 passed.
10092 OUTPUT Variables
10094 CXXTEST_FOUND
10096 True if the CxxTest framework was found
10097 CXXTEST_INCLUDE_DIRS
10098 Where to find the CxxTest include directory
10099 CXXTEST_PERL_TESTGEN_EXECUTABLE
10100 The perl-based test generator
10101 CXXTEST_PYTHON_TESTGEN_EXECUTABLE
10102 The python-based test generator
10103 CXXTEST_TESTGEN_EXECUTABLE (since CMake 2.8.3)
10104 The test generator that is actually used (chosen using user preferences
10105 and interpreters found in the system)
10106 CXXTEST_TESTGEN_INTERPRETER (since CMake 2.8.3)
10107 The full path to the Perl or Python executable on the system, on
10108 platforms where the script cannot be executed using its shebang line.
10109 MACROS for optional use by CMake users:
10111 CXXTEST_ADD_TEST(<test_name> <gen_source_file> <input_files_to_testgen...>)
10113 Creates a CxxTest runner and adds it to the CTest testing suite
10114 Parameters:
10115 test_name The name of the test
10116 gen_source_file The generated source filename to be
10117 generated by CxxTest
10118 input_files_to_testgen The list of header files containing the
10119 CxxTest::TestSuite's to be included in
10120 this runner
10121 #==============
10123 Example Usage:
10124 find_package(CxxTest)
10126 if(CXXTEST_FOUND)
10127 include_directories(${CXXTEST_INCLUDE_DIR})
10128 enable_testing()
10129 CXXTEST_ADD_TEST(unittest_foo foo_test.cc
10131 ${CMAKE_CURRENT_SOURCE_DIR}/foo_test.h)
10132 target_link_libraries(unittest_foo foo) # as needed
10133 endif()
10134 This will (if CxxTest is found):
10136 1. Invoke the testgen executable to autogenerate foo_test.cc in the
10137 binary tree from "foo_test.h" in the current source directory.
10138 2. Create an executable and test called unittest_foo.
10139 #=============
10141 Example foo_test.h:
10142 #include <cxxtest/TestSuite.h>
10144 class MyTestSuite : public CxxTest::TestSuite
10146 {
10147 public:
10148 void testAddition( void )
10149 {
10150 TS_ASSERT( 1 + 1 > 1 );
10151 TS_ASSERT_EQUALS( 1 + 1, 2 );
10152 }
10153 };
10154 FindCygwin
10156 Find Cygwin, a POSIX-compatible environment that runs natively on Mi‐
10157 crosoft Windows
10158 FindDart
10160 Find DART
10161 This module looks for the dart testing software and sets DART_ROOT to
10163 point to where it found it.
10164 FindDCMTK
10166 Find DICOM ToolKit (DCMTK) libraries and applications
10167 The module defines the following variables:
10169 DCMTK_INCLUDE_DIRS - Directories to include to use DCMTK
10171 DCMTK_LIBRARIES - Files to link against to use DCMTK
10172 DCMTK_FOUND - If false, don't try to use DCMTK
10173 DCMTK_DIR - (optional) Source directory for DCMTK
10174 Compatibility
10176 This module is able to find a version of DCMTK that does or does not
10177 export a DCMTKConfig.cmake file. It applies a two step process:
10178 • Step 1: Attempt to find DCMTK version providing a DCMTKConfig.cmake
10180 file.
10181 • Step 2: If step 1 failed, rely on FindDCMTK.cmake to set DCMTK_*
10183 variables details below.
10184 Recent DCMTK provides a DCMTKConfig.cmake package configuration file.
10186 To exclusively use the package configuration file (recommended when
10187 possible), pass the NO_MODULE option to find_package(). For example,
10188 find_package(DCMTK NO_MODULE). This requires official DCMTK snapshot
10189 3.6.1_20140617 or newer.
10190 Until all clients update to the more recent DCMTK, build systems will
10192 need to support different versions of DCMTK.
10193 On any given system, the following combinations of DCMTK versions could
10195 be considered:
10196 ┌───────┬─────────────────┬─────────────────┬─────────────┐
10198 │ │ SYSTEM DCMTK │ LOCAL DCMTK │ Supported ? │
10199 ├───────┼─────────────────┼─────────────────┼─────────────┤
10200 │Case A │ NA │ [ ] DCMTKConfig │ YES │
10201 ├───────┼─────────────────┼─────────────────┼─────────────┤
10202 │Case B │ NA │ [X] DCMTKConfig │ YES │
10203 ├───────┼─────────────────┼─────────────────┼─────────────┤
10204 │Case C │ [ ] DCMTKConfig │ NA │ YES │
10205 ├───────┼─────────────────┼─────────────────┼─────────────┤
10206 │Case D │ [X] DCMTKConfig │ NA │ YES │
10207 ├───────┼─────────────────┼─────────────────┼─────────────┤
10208 │Case E │ [ ] DCMTKConfig │ [ ] DCMTKConfig │ YES (*) │
10209 ├───────┼─────────────────┼─────────────────┼─────────────┤
10210 │Case F │ [X] DCMTKConfig │ [ ] DCMTKConfig │ NO │
10211 ├───────┼─────────────────┼─────────────────┼─────────────┤
10212 │Case G │ [ ] DCMTKConfig │ [X] DCMTKConfig │ YES │
10213 ├───────┼─────────────────┼─────────────────┼─────────────┤
10214 │Case H │ [X] DCMTKConfig │ [X] DCMTKConfig │ YES │
10215 └───────┴─────────────────┴─────────────────┴─────────────┘
10216 (*) See Troubleshooting section.
10217 Legend:
10219 NA ...............: Means that no System or Local DCMTK is available
10220 [ ] DCMTKConfig ..: Means that the version of DCMTK does NOT export
10222 a DCMTKConfig.cmake file.
10223 [X] DCMTKConfig ..: Means that the version of DCMTK exports a DCMTK‐
10225 Config.cmake file.
10226 Troubleshooting
10228 What to do if my project finds a different version of DCMTK?
10229 Remove DCMTK entry from the CMake cache per find_package() documenta‐
10231 tion.
10232 FindDevIL
10234 This module locates the developer's image library.
10235 http://openil.sourceforge.net/
10236 This module sets:
10238 IL_LIBRARIES - the name of the IL library. These include the full path to
10240 the core DevIL library. This one has to be linked into the
10241 application.
10242 ILU_LIBRARIES - the name of the ILU library. Again, the full path. This
10243 library is for filters and effects, not actual loading. It
10244 doesn't have to be linked if the functionality it provides
10245 is not used.
10246 ILUT_LIBRARIES - the name of the ILUT library. Full path. This part of the
10247 library interfaces with OpenGL. It is not strictly needed
10248 in applications.
10249 IL_INCLUDE_DIR - where to find the il.h, ilu.h and ilut.h files.
10250 DevIL_FOUND - this is set to TRUE if all the above variables were set.
10251 This will be set to false if ILU or ILUT are not found,
10252 even if they are not needed. In most systems, if one
10253 library is found all the others are as well. That's the
10254 way the DevIL developers release it.
10255 FindDoxygen
10257 Doxygen is a documentation generation tool (see
10258 http://www.doxygen.org). This module looks for Doxygen and some op‐
10259 tional tools it supports:
10260 dot Graphviz dot utility used to render various graphs.
10262 mscgen Message Chart Generator utility used by Doxygen's \msc and \msc‐
10264 file commands.
10265 dia Dia the diagram editor used by Doxygen's \diafile command.
10267 New in version 3.9: These tools are available as components in the
10269 find_package() command. For example:
10270 # Require dot, treat the other components as optional
10273 find_package(Doxygen
10274 REQUIRED dot
10275 OPTIONAL_COMPONENTS mscgen dia)
10276 The following variables are defined by this module:
10278 DOXYGEN_FOUND
10280 True if the doxygen executable was found.
10281 DOXYGEN_VERSION
10283 The version reported by doxygen --version.
10284 New in version 3.9: The module defines IMPORTED targets for Doxygen and
10286 each component found. These can be used as part of custom commands,
10287 etc. and should be preferred over old-style (and now deprecated) vari‐
10288 ables like DOXYGEN_EXECUTABLE. The following import targets are defined
10289 if their corresponding executable could be found (the component import
10290 targets will only be defined if that component was requested):
10291 Doxygen::doxygen
10294 Doxygen::dot
10295 Doxygen::mscgen
10296 Doxygen::dia
10297 Functions
10299 doxygen_add_docs
10300 New in version 3.9.
10301 This function is intended as a convenience for adding a target
10304 for generating documentation with Doxygen. It aims to provide
10305 sensible defaults so that projects can generally just provide
10306 the input files and directories and that will be sufficient to
10307 give sensible results. The function supports the ability to cus‐
10308 tomize the Doxygen configuration used to build the documenta‐
10309 tion.
10310 doxygen_add_docs(targetName
10312 [filesOrDirs...]
10313 [ALL]
10314 [USE_STAMP_FILE]
10315 [WORKING_DIRECTORY dir]
10316 [COMMENT comment])
10317 The function constructs a Doxyfile and defines a custom target
10319 that runs Doxygen on that generated file. The listed files and
10320 directories are used as the INPUT of the generated Doxyfile and
10321 they can contain wildcards. Any files that are listed explic‐
10322 itly will also be added as SOURCES of the custom target so they
10323 will show up in an IDE project's source list.
10324 So that relative input paths work as expected, by default the
10326 working directory of the Doxygen command will be the current
10327 source directory (i.e. CMAKE_CURRENT_SOURCE_DIR). This can be
10328 overridden with the WORKING_DIRECTORY option to change the di‐
10329 rectory used as the relative base point. Note also that Doxy‐
10330 gen's default behavior is to strip the working directory from
10331 relative paths in the generated documentation (see the
10332 STRIP_FROM_PATH Doxygen config option for details).
10333 If provided, the optional comment will be passed as the COMMENT
10335 for the add_custom_target() command used to create the custom
10336 target internally.
10337 New in version 3.12: If ALL is set, the target will be added to
10339 the default build target.
10340 New in version 3.16: If USE_STAMP_FILE is set, the custom com‐
10343 mand defined by this function will create a stamp file with the
10344 name <targetName>.stamp in the current binary directory whenever
10345 doxygen is re-run. With this option present, all items in
10346 <filesOrDirs> must be files (i.e. no directories, symlinks or
10347 wildcards) and each of the files must exist at the time doxy‐
10348 gen_add_docs() is called. An error will be raised if any of the
10349 items listed is missing or is not a file when USE_STAMP_FILE is
10350 given. A dependency will be created on each of the files so
10351 that doxygen will only be re-run if one of the files is updated.
10352 Without the USE_STAMP_FILE option, doxygen will always be re-run
10353 if the <targetName> target is built regardless of whether any‐
10354 thing listed in <filesOrDirs> has changed.
10355 The contents of the generated Doxyfile can be customized by set‐
10358 ting CMake variables before calling doxygen_add_docs(). Any
10359 variable with a name of the form DOXYGEN_<tag> will have its
10360 value substituted for the corresponding <tag> configuration op‐
10361 tion in the Doxyfile. See the Doxygen documentation for the full
10362 list of supported configuration options.
10363 Some of Doxygen's defaults are overridden to provide more appro‐
10365 priate behavior for a CMake project. Each of the following will
10366 be explicitly set unless the variable already has a value before
10367 doxygen_add_docs() is called (with some exceptions noted):
10368 DOXYGEN_HAVE_DOT
10370 Set to YES if the dot component was requested and it was
10371 found, NO otherwise. Any existing value of DOXY‐
10372 GEN_HAVE_DOT is ignored.
10373 DOXYGEN_DOT_MULTI_TARGETS
10375 Set to YES by this module (note that this requires a dot
10376 version newer than 1.8.10). This option is only meaning‐
10377 ful if DOXYGEN_HAVE_DOT is also set to YES.
10378 DOXYGEN_GENERATE_LATEX
10380 Set to NO by this module.
10381 DOXYGEN_WARN_FORMAT
10383 For Visual Studio based generators, this is set to the
10384 form recognized by the Visual Studio IDE: $file($line) :
10385 $text. For all other generators, Doxygen's default value
10386 is not overridden.
10387 DOXYGEN_PROJECT_NAME
10389 Populated with the name of the current project (i.e.
10390 PROJECT_NAME).
10391 DOXYGEN_PROJECT_NUMBER
10393 Populated with the version of the current project (i.e.
10394 PROJECT_VERSION).
10395 DOXYGEN_PROJECT_BRIEF
10397 Populated with the description of the current project
10398 (i.e. PROJECT_DESCRIPTION).
10399 DOXYGEN_INPUT
10401 Projects should not set this variable. It will be popu‐
10402 lated with the set of files and directories passed to
10403 doxygen_add_docs(), thereby providing consistent behavior
10404 with the other built-in commands like add_executable(),
10405 add_library() and add_custom_target(). If a variable
10406 named DOXYGEN_INPUT is set by the project, it will be ig‐
10407 nored and a warning will be issued.
10408 DOXYGEN_RECURSIVE
10410 Set to YES by this module.
10411 DOXYGEN_EXCLUDE_PATTERNS
10413 If the set of inputs includes directories, this variable
10414 will specify patterns used to exclude files from them.
10415 The following patterns are added by doxygen_add_docs() to
10416 ensure CMake-specific files and directories are not in‐
10417 cluded in the input. If the project sets DOXYGEN_EX‐
10418 CLUDE_PATTERNS, those contents are merged with these ad‐
10419 ditional patterns rather than replacing them:
10420 */.git/*
10422 */.svn/*
10423 */.hg/*
10424 */CMakeFiles/*
10425 */_CPack_Packages/*
10426 DartConfiguration.tcl
10427 CMakeLists.txt
10428 CMakeCache.txt
10429 DOXYGEN_OUTPUT_DIRECTORY
10431 Set to CMAKE_CURRENT_BINARY_DIR by this module. Note that
10432 if the project provides its own value for this and it is
10433 a relative path, it will be converted to an absolute path
10434 relative to the current binary directory. This is neces‐
10435 sary because doxygen will normally be run from a direc‐
10436 tory within the source tree so that relative source paths
10437 work as expected. If this directory does not exist, it
10438 will be recursively created prior to executing the doxy‐
10439 gen commands.
10440 To change any of these defaults or override any other Doxygen config
10442 option, set relevant variables before calling doxygen_add_docs(). For
10443 example:
10444 set(DOXYGEN_GENERATE_HTML NO)
10446 set(DOXYGEN_GENERATE_MAN YES)
10447 doxygen_add_docs(
10449 doxygen
10450 ${PROJECT_SOURCE_DIR}
10451 COMMENT "Generate man pages"
10452 )
10453 A number of Doxygen config options accept lists of values, but Doxygen
10455 requires them to be separated by whitespace. CMake variables hold lists
10456 as a string with items separated by semi-colons, so a conversion needs
10457 to be performed. The doxygen_add_docs() command specifically checks the
10458 following Doxygen config options and will convert their associated
10459 CMake variable's contents into the required form if set.
10460 ABBREVIATE_BRIEF
10462 ALIASES
10463 CITE_BIB_FILES
10464 DIAFILE_DIRS
10465 DOTFILE_DIRS
10466 DOT_FONTPATH
10467 ENABLED_SECTIONS
10468 EXAMPLE_PATH
10469 EXAMPLE_PATTERNS
10470 EXCLUDE
10471 EXCLUDE_PATTERNS
10472 EXCLUDE_SYMBOLS
10473 EXPAND_AS_DEFINED
10474 EXTENSION_MAPPING
10475 EXTRA_PACKAGES
10476 EXTRA_SEARCH_MAPPINGS
10477 FILE_PATTERNS
10478 FILTER_PATTERNS
10479 FILTER_SOURCE_PATTERNS
10480 HTML_EXTRA_FILES
10481 HTML_EXTRA_STYLESHEET
10482 IGNORE_PREFIX
10483 IMAGE_PATH
10484 INCLUDE_FILE_PATTERNS
10485 INCLUDE_PATH
10486 INPUT
10487 LATEX_EXTRA_FILES
10488 LATEX_EXTRA_STYLESHEET
10489 MATHJAX_EXTENSIONS
10490 MSCFILE_DIRS
10491 PLANTUML_INCLUDE_PATH
10492 PREDEFINED
10493 QHP_CUST_FILTER_ATTRS
10494 QHP_SECT_FILTER_ATTRS
10495 STRIP_FROM_INC_PATH
10496 STRIP_FROM_PATH
10497 TAGFILES
10498 TCL_SUBST
10499 The following single value Doxygen options will be quoted automatically
10501 if they contain at least one space:
10502 CHM_FILE
10504 DIA_PATH
10505 DOCBOOK_OUTPUT
10506 DOCSET_FEEDNAME
10507 DOCSET_PUBLISHER_NAME
10508 DOT_FONTNAME
10509 DOT_PATH
10510 EXTERNAL_SEARCH_ID
10511 FILE_VERSION_FILTER
10512 GENERATE_TAGFILE
10513 HHC_LOCATION
10514 HTML_FOOTER
10515 HTML_HEADER
10516 HTML_OUTPUT
10517 HTML_STYLESHEET
10518 INPUT_FILTER
10519 LATEX_FOOTER
10520 LATEX_HEADER
10521 LATEX_OUTPUT
10522 LAYOUT_FILE
10523 MAN_OUTPUT
10524 MAN_SUBDIR
10525 MATHJAX_CODEFILE
10526 MSCGEN_PATH
10527 OUTPUT_DIRECTORY
10528 PERL_PATH
10529 PLANTUML_JAR_PATH
10530 PROJECT_BRIEF
10531 PROJECT_LOGO
10532 PROJECT_NAME
10533 QCH_FILE
10534 QHG_LOCATION
10535 QHP_CUST_FILTER_NAME
10536 QHP_VIRTUAL_FOLDER
10537 RTF_EXTENSIONS_FILE
10538 RTF_OUTPUT
10539 RTF_STYLESHEET_FILE
10540 SEARCHDATA_FILE
10541 USE_MDFILE_AS_MAINPAGE
10542 WARN_FORMAT
10543 WARN_LOGFILE
10544 XML_OUTPUT
10545 New in version 3.11: There are situations where it may be undesirable
10547 for a particular config option to be automatically quoted by doxy‐
10548 gen_add_docs(), such as ALIASES which may need to include its own em‐
10549 bedded quoting. The DOXYGEN_VERBATIM_VARS variable can be used to
10550 specify a list of Doxygen variables (including the leading DOXYGEN_
10551 prefix) which should not be quoted. The project is then responsible
10552 for ensuring that those variables' values make sense when placed di‐
10553 rectly in the Doxygen input file. In the case of list variables, list
10554 items are still separated by spaces, it is only the automatic quoting
10555 that is skipped. For example, the following allows doxygen_add_docs()
10556 to apply quoting to DOXYGEN_PROJECT_BRIEF, but not each item in the
10557 DOXYGEN_ALIASES list (bracket syntax can also be used to make working
10558 with embedded quotes easier):
10559 set(DOXYGEN_PROJECT_BRIEF "String with spaces")
10562 set(DOXYGEN_ALIASES
10563 [[somealias="@some_command param"]]
10564 "anotherAlias=@foobar"
10565 )
10566 set(DOXYGEN_VERBATIM_VARS DOXYGEN_ALIASES)
10567 The resultant Doxyfile will contain the following lines:
10569 PROJECT_BRIEF = "String with spaces"
10571 ALIASES = somealias="@some_command param" anotherAlias=@foobar
10572 Deprecated Result Variables
10574 Deprecated since version 3.9.
10575 For compatibility with previous versions of CMake, the following vari‐
10578 ables are also defined but they are deprecated and should no longer be
10579 used:
10580 DOXYGEN_EXECUTABLE
10582 The path to the doxygen command. If projects need to refer to
10583 the doxygen executable directly, they should use the Doxy‐
10584 gen::doxygen import target instead.
10585 DOXYGEN_DOT_FOUND
10587 True if the dot executable was found.
10588 DOXYGEN_DOT_EXECUTABLE
10590 The path to the dot command. If projects need to refer to the
10591 dot executable directly, they should use the Doxygen::dot import
10592 target instead.
10593 DOXYGEN_DOT_PATH
10595 The path to the directory containing the dot executable as re‐
10596 ported in DOXYGEN_DOT_EXECUTABLE. The path may have forward
10597 slashes even on Windows and is not suitable for direct substitu‐
10598 tion into a Doxyfile.in template. If you need this value, get
10599 the IMPORTED_LOCATION property of the Doxygen::dot target and
10600 use get_filename_component() to extract the directory part of
10601 that path. You may also want to consider using file(TO_NA‐
10602 TIVE_PATH) to prepare the path for a Doxygen configuration file.
10603 Deprecated Hint Variables
10605 Deprecated since version 3.9.
10606 DOXYGEN_SKIP_DOT
10609 This variable has no effect for the component form of find_pack‐
10610 age. In backward compatibility mode (i.e. without components
10611 list) it prevents the finder module from searching for
10612 Graphviz's dot utility.
10613 FindEnvModules
10615 New in version 3.15.
10616 Locate an environment module implementation and make commands available
10619 to CMake scripts to use them. This is compatible with both Lua-based
10620 Lmod and TCL-based EnvironmentModules.
10621 This module is intended for the use case of setting up the compiler and
10623 library environment within a CTest Script (ctest -S). It can also be
10624 used in a CMake Script (cmake -P).
10625 NOTE:
10627 The loaded environment will not survive past the end of the calling
10628 process. Do not use this module in project code (CMakeLists.txt
10629 files) to load a compiler environment; it will not be available dur‐
10630 ing the build. Instead load the environment manually before running
10631 CMake or using the generated build system.
10632 Example Usage
10634 set(CTEST_BUILD_NAME "CrayLinux-CrayPE-Cray-dynamic")
10635 set(CTEST_BUILD_CONFIGURATION Release)
10636 set(CTEST_BUILD_FLAGS "-k -j8")
10637 set(CTEST_CMAKE_GENERATOR "Unix Makefiles")
10638 ...
10640 find_package(EnvModules REQUIRED)
10642 env_module(purge)
10644 env_module(load modules)
10645 env_module(load craype)
10646 env_module(load PrgEnv-cray)
10647 env_module(load craype-knl)
10648 env_module(load cray-mpich)
10649 env_module(load cray-libsci)
10650 set(ENV{CRAYPE_LINK_TYPE} dynamic)
10652 ...
10654 Result Variables
10656 This module will set the following variables in your project:
10657 EnvModules_FOUND
10659 True if a compatible environment modules framework was found.
10660 Cache Variables
10662 The following cache variable will be set:
10663 EnvModules_COMMAND
10665 The low level module command to use. Currently supported imple‐
10666 mentations are the Lua based Lmod and TCL based EnvironmentMod‐
10667 ules.
10668 Environment Variables
10670 ENV{MODULESHOME}
10671 Usually set by the module environment implementation, used as a
10672 hint to locate the module command to execute.
10673 Provided Functions
10675 This defines the following CMake functions for interacting with envi‐
10676 ronment modules:
10677 env_module
10679 Execute an aribitrary module command:
10680 env_module(cmd arg1 ... argN)
10682 env_module(
10683 COMMAND cmd arg1 ... argN
10684 [OUTPUT_VARIABLE <out-var>]
10685 [RESULT_VARIABLE <ret-var>]
10686 )
10687 The options are:
10689 cmd arg1 ... argN
10691 The module sub-command and arguments to execute as if
10692 they were passed directly to the module command in your
10693 shell environment.
10694 OUTPUT_VARIABLE <out-var>
10696 The standard output from executing the module command.
10697 RESULT_VARIABLE <ret-var>
10699 The return code from executing the module command.
10700 env_module_swap
10702 Swap one module for another:
10703 env_module_swap(out_mod in_mod
10705 [OUTPUT_VARIABLE <out-var>]
10706 [RESULT_VARIABLE <ret-var>]
10707 )
10708 This is functionally equivalent to the module swap out_mod
10710 in_mod shell command. The options are:
10711 OUTPUT_VARIABLE <out-var>
10713 The standard output from executing the module command.
10714 RESULT_VARIABLE <ret-var>
10716 The return code from executing the module command.
10717 env_module_list
10719 Retrieve the list of currently loaded modules:
10720 env_module_list(<out-var>)
10722 This is functionally equivalent to the module list shell com‐
10724 mand. The result is stored in <out-var> as a properly formatted
10725 CMake semicolon-separated list variable.
10726 env_module_avail
10728 Retrieve the list of available modules:
10729 env_module_avail([<mod-prefix>] <out-var>)
10731 This is functionally equivalent to the module avail <mod-prefix>
10733 shell command. The result is stored in <out-var> as a properly
10734 formatted CMake semicolon-separated list variable.
10735 FindEXPAT
10737 Find the native Expat headers and library. Expat is a stream-oriented
10738 XML parser library written in C.
10739 Imported Targets
10741 New in version 3.10.
10742 This module defines the following IMPORTED targets:
10745 EXPAT::EXPAT
10747 The Expat expat library, if found.
10748 Result Variables
10750 This module will set the following variables in your project:
10751 EXPAT_INCLUDE_DIRS
10753 where to find expat.h, etc.
10754 EXPAT_LIBRARIES
10756 the libraries to link against to use Expat.
10757 EXPAT_FOUND
10759 true if the Expat headers and libraries were found.
10760 FindFLEX
10762 Find Fast Lexical Analyzer (Flex) executable and provides a macro to
10763 generate custom build rules
10764 The module defines the following variables:
10766 FLEX_FOUND - True is flex executable is found
10768 FLEX_EXECUTABLE - the path to the flex executable
10769 FLEX_VERSION - the version of flex
10770 FLEX_LIBRARIES - The flex libraries
10771 FLEX_INCLUDE_DIRS - The path to the flex headers
10772 The minimum required version of flex can be specified using the stan‐
10774 dard syntax, e.g. find_package(FLEX 2.5.13)
10775 If flex is found on the system, the module provides the macro:
10777 FLEX_TARGET(Name FlexInput FlexOutput
10779 [COMPILE_FLAGS <string>]
10780 [DEFINES_FILE <string>]
10781 )
10782 which creates a custom command to generate the FlexOutput file from the
10784 FlexInput file. Name is an alias used to get details of this custom
10785 command. If COMPILE_FLAGS option is specified, the next parameter is
10786 added to the flex command line.
10787 New in version 3.5: If flex is configured to output a header file, the
10789 DEFINES_FILE option may be used to specify its name.
10790 Changed in version 3.17: When CMP0098 is set to NEW, flex runs in the
10793 CMAKE_CURRENT_BINARY_DIR directory.
10794 The macro defines the following variables:
10797 FLEX_${Name}_DEFINED - true is the macro ran successfully
10799 FLEX_${Name}_OUTPUTS - the source file generated by the custom rule, an
10800 alias for FlexOutput
10801 FLEX_${Name}_INPUT - the flex source file, an alias for ${FlexInput}
10802 FLEX_${Name}_OUTPUT_HEADER - the header flex output, if any.
10803 Flex scanners often use tokens defined by Bison: the code generated by
10805 Flex depends of the header generated by Bison. This module also de‐
10806 fines a macro:
10807 ADD_FLEX_BISON_DEPENDENCY(FlexTarget BisonTarget)
10809 which adds the required dependency between a scanner and a parser where
10811 FlexTarget and BisonTarget are the first parameters of respectively
10812 FLEX_TARGET and BISON_TARGET macros.
10813 ====================================================================
10815 Example:
10816 find_package(BISON)
10818 find_package(FLEX)
10819 BISON_TARGET(MyParser parser.y ${CMAKE_CURRENT_BINARY_DIR}/parser.cpp)
10821 FLEX_TARGET(MyScanner lexer.l ${CMAKE_CURRENT_BINARY_DIR}/lexer.cpp)
10822 ADD_FLEX_BISON_DEPENDENCY(MyScanner MyParser)
10823 include_directories(${CMAKE_CURRENT_BINARY_DIR})
10825 add_executable(Foo
10826 Foo.cc
10827 ${BISON_MyParser_OUTPUTS}
10828 ${FLEX_MyScanner_OUTPUTS}
10829 )
10830 target_link_libraries(Foo ${FLEX_LIBRARIES})
10831 ====================================================================
10832 FindFLTK
10834 Find the Fast Light Toolkit (FLTK) library
10835 Input Variables
10837 By default this module will search for all of the FLTK components and
10838 add them to the FLTK_LIBRARIES variable. You can limit the components
10839 which get placed in FLTK_LIBRARIES by defining one or more of the fol‐
10840 lowing three options:
10841 FLTK_SKIP_OPENGL
10843 Set to true to disable searching for the FLTK GL library
10844 FLTK_SKIP_FORMS
10846 Set to true to disable searching for the FLTK Forms library
10847 FLTK_SKIP_IMAGES
10849 Set to true to disable searching for the FLTK Images library
10850 FLTK is composed also by a binary tool. You can set the following op‐
10852 tion:
10853 FLTK_SKIP_FLUID
10855 Set to true to not look for the FLUID binary
10856 Result Variables
10858 The following variables will be defined:
10859 FLTK_FOUND
10861 True if all components not skipped were found
10862 FLTK_INCLUDE_DIR
10864 Path to the include directory for FLTK header files
10865 FLTK_LIBRARIES
10867 List of the FLTK libraries found
10868 FLTK_FLUID_EXECUTABLE
10870 Path to the FLUID binary tool
10871 FLTK_WRAP_UI
10873 True if FLUID is found, used to enable the FLTK_WRAP_UI command
10874 Cache Variables
10876 The following cache variables are also available to set or use:
10877 FLTK_BASE_LIBRARY_RELEASE
10879 The FLTK base library (optimized)
10880 FLTK_BASE_LIBRARY_DEBUG
10882 The FLTK base library (debug)
10883 FLTK_GL_LIBRARY_RELEASE
10885 The FLTK GL library (optimized)
10886 FLTK_GL_LIBRARY_DEBUG
10888 The FLTK GL library (debug)
10889 FLTK_FORMS_LIBRARY_RELEASE
10891 The FLTK Forms library (optimized)
10892 FLTK_FORMS_LIBRARY_DEBUG
10894 The FLTK Forms library (debug)
10895 FLTK_IMAGES_LIBRARY_RELEASE
10897 The FLTK Images protobuf library (optimized)
10898 FLTK_IMAGES_LIBRARY_DEBUG
10900 The FLTK Images library (debug)
10901 New in version 3.11: Debug and Release variants are found separately
10903 and use per-configuration variables.
10904 FindFLTK2
10907 Find the native FLTK 2.0 includes and library
10908 The following settings are defined
10910 FLTK2_FLUID_EXECUTABLE, where to find the Fluid tool
10912 FLTK2_WRAP_UI, This enables the FLTK2_WRAP_UI command
10913 FLTK2_INCLUDE_DIR, where to find include files
10914 FLTK2_LIBRARIES, list of fltk2 libraries
10915 FLTK2_FOUND, Don't use FLTK2 if false.
10916 The following settings should not be used in general.
10918 FLTK2_BASE_LIBRARY = the full path to fltk2.lib
10920 FLTK2_GL_LIBRARY = the full path to fltk2_gl.lib
10921 FLTK2_IMAGES_LIBRARY = the full path to fltk2_images.lib
10922 FindFontconfig
10924 New in version 3.14.
10925 Find Fontconfig headers and library.
10928 Imported Targets
10930 Fontconfig::Fontconfig
10931 The Fontconfig library, if found.
10932 Result Variables
10934 This will define the following variables in your project:
10935 Fontconfig_FOUND
10937 true if (the requested version of) Fontconfig is available.
10938 Fontconfig_VERSION
10940 the version of Fontconfig.
10941 Fontconfig_LIBRARIES
10943 the libraries to link against to use Fontconfig.
10944 Fontconfig_INCLUDE_DIRS
10946 where to find the Fontconfig headers.
10947 Fontconfig_COMPILE_OPTIONS
10949 this should be passed to target_compile_options(), if the target
10950 is not used for linking
10951 FindFreetype
10953 Find the FreeType font renderer includes and library.
10954 Imported Targets
10956 New in version 3.10.
10957 This module defines the following IMPORTED target:
10960 Freetype::Freetype
10962 The Freetype freetype library, if found
10963 Result Variables
10965 This module will set the following variables in your project:
10966 FREETYPE_FOUND
10968 true if the Freetype headers and libraries were found
10969 FREETYPE_INCLUDE_DIRS
10971 directories containing the Freetype headers. This is the con‐
10972 catenation of the variables:
10973 FREETYPE_INCLUDE_DIR_ft2build
10975 directory holding the main Freetype API configuration
10976 header
10977 FREETYPE_INCLUDE_DIR_freetype2
10979 directory holding Freetype public headers
10980 FREETYPE_LIBRARIES
10982 the library to link against
10983 FREETYPE_VERSION_STRING
10985 the version of freetype found
10986 New in version 3.7: Debug and Release variants are found separately.
10988 Hints
10991 The user may set the environment variable FREETYPE_DIR to the root di‐
10992 rectory of a Freetype installation.
10993 FindGCCXML
10995 Find the GCC-XML front-end executable.
10996 This module will define the following variables:
10998 GCCXML - the GCC-XML front-end executable.
11000 FindGDAL
11002 Find Geospatial Data Abstraction Library (GDAL).
11003 IMPORTED Targets
11005 New in version 3.14.
11006 This module defines IMPORTED target GDAL::GDAL if GDAL has been found.
11009 Result Variables
11011 This module will set the following variables in your project:
11012 GDAL_FOUND
11014 True if GDAL is found.
11015 GDAL_INCLUDE_DIRS
11017 Include directories for GDAL headers.
11018 GDAL_LIBRARIES
11020 Libraries to link to GDAL.
11021 GDAL_VERSION
11023 New in version 3.14: The version of GDAL found.
11024 Cache variables
11027 The following cache variables may also be set:
11028 GDAL_LIBRARY
11030 The libgdal library file.
11031 GDAL_INCLUDE_DIR
11033 The directory containing gdal.h.
11034 Hints
11036 Set GDAL_DIR or GDAL_ROOT in the environment to specify the GDAL in‐
11037 stallation prefix.
11038 The following variables may be set to modify the search strategy:
11040 FindGDAL_SKIP_GDAL_CONFIG
11042 If set, gdal-config will not be used. This can be useful if
11043 there are GDAL libraries built with autotools (which provide the
11044 tool) and CMake (which do not) in the same environment.
11045 GDAL_ADDITIONAL_LIBRARY_VERSIONS
11047 Extra versions of library names to search for.
11048 FindGettext
11050 Find GNU gettext tools
11051 This module looks for the GNU gettext tools. This module defines the
11053 following values:
11054 GETTEXT_MSGMERGE_EXECUTABLE: the full path to the msgmerge tool.
11056 GETTEXT_MSGFMT_EXECUTABLE: the full path to the msgfmt tool.
11057 GETTEXT_FOUND: True if gettext has been found.
11058 GETTEXT_VERSION_STRING: the version of gettext found (since CMake 2.8.8)
11059 Additionally it provides the following macros:
11061 GETTEXT_CREATE_TRANSLATIONS ( outputFile [ALL] file1 ... fileN )
11063 This will create a target "translations" which will convert the
11065 given input po files into the binary output mo file. If the
11066 ALL option is used, the translations will also be created when
11067 building the default target.
11068 GETTEXT_PROCESS_POT_FILE( <potfile> [ALL] [INSTALL_DESTINATION <dest‐
11070 dir>] LANGUAGES <lang1> <lang2> ... )
11071 Process the given pot file to mo files.
11073 If INSTALL_DESTINATION is given then automatically install rules will
11074 be created, the language subdirectory will be taken into account
11075 (by default use share/locale/).
11076 If ALL is specified, the pot file is processed when building the all traget.
11077 It creates a custom target "potfile".
11078 GETTEXT_PROCESS_PO_FILES( <lang> [ALL] [INSTALL_DESTINATION <dir>]
11080 PO_FILES <po1> <po2> ... )
11081 Process the given po files to mo files for the given language.
11083 If INSTALL_DESTINATION is given then automatically install rules will
11084 be created, the language subdirectory will be taken into account
11085 (by default use share/locale/).
11086 If ALL is specified, the po files are processed when building the all traget.
11087 It creates a custom target "pofiles".
11088 New in version 3.2: If you wish to use the Gettext library (libintl),
11090 use FindIntl.
11091 FindGIF
11094 This finds the Graphics Interchange Format (GIF) library (giflib)
11095 Imported targets
11097 This module defines the following IMPORTED target:
11098 GIF::GIF
11100 The giflib library, if found.
11101 Result variables
11103 This module will set the following variables in your project:
11104 GIF_FOUND
11106 If false, do not try to use GIF.
11107 GIF_INCLUDE_DIRS
11109 where to find gif_lib.h, etc.
11110 GIF_LIBRARIES
11112 the libraries needed to use GIF.
11113 GIF_VERSION
11115 3, 4 or a full version string (eg 5.1.4) for versions >= 4.1.6.
11116 Cache variables
11118 The following cache variables may also be set:
11119 GIF_INCLUDE_DIR
11121 where to find the GIF headers.
11122 GIF_LIBRARY
11124 where to find the GIF library.
11125 Hints
11127 GIF_DIR is an environment variable that would correspond to the ./con‐
11128 figure --prefix=$GIF_DIR.
11129 FindGit
11131 The module defines the following variables:
11132 GIT_EXECUTABLE
11134 Path to Git command-line client.
11135 Git_FOUND, GIT_FOUND
11137 True if the Git command-line client was found.
11138 GIT_VERSION_STRING
11140 The version of Git found.
11141 New in version 3.14: The module defines the following IMPORTED targets
11143 (when CMAKE_ROLE is PROJECT):
11144 Git::Git
11147 Executable of the Git command-line client.
11148 Example usage:
11150 find_package(Git)
11152 if(Git_FOUND)
11153 message("Git found: ${GIT_EXECUTABLE}")
11154 endif()
11155 FindGLEW
11157 Find the OpenGL Extension Wrangler Library (GLEW)
11158 Input Variables
11160 The following variables may be set to influence this module's behavior:
11161 GLEW_USE_STATIC_LIBS
11163 to find and create IMPORTED target for static linkage.
11164 GLEW_VERBOSE
11166 to output a detailed log of this module.
11167 Imported Targets
11169 New in version 3.1.
11170 This module defines the following Imported Targets:
11173 GLEW::glew
11175 The GLEW shared library.
11176 GLEW::glew_s
11178 The GLEW static library, if GLEW_USE_STATIC_LIBS is set to TRUE.
11179 GLEW::GLEW
11181 Duplicates either GLEW::glew or GLEW::glew_s based on availabil‐
11182 ity.
11183 Result Variables
11185 This module defines the following variables:
11186 GLEW_INCLUDE_DIRS
11188 include directories for GLEW
11189 GLEW_LIBRARIES
11191 libraries to link against GLEW
11192 GLEW_SHARED_LIBRARIES
11194 libraries to link against shared GLEW
11195 GLEW_STATIC_LIBRARIES
11197 libraries to link against static GLEW
11198 GLEW_FOUND
11200 true if GLEW has been found and can be used
11201 GLEW_VERSION
11203 GLEW version
11204 GLEW_VERSION_MAJOR
11206 GLEW major version
11207 GLEW_VERSION_MINOR
11209 GLEW minor version
11210 GLEW_VERSION_MICRO
11212 GLEW micro version
11213 New in version 3.7: Debug and Release variants are found separately.
11215 FindGLUT
11218 Find OpenGL Utility Toolkit (GLUT) library and include files.
11219 IMPORTED Targets
11221 New in version 3.1.
11222 This module defines the IMPORTED targets:
11225 GLUT::GLUT
11227 Defined if the system has GLUT.
11228 Result Variables
11230 This module sets the following variables:
11231 GLUT_INCLUDE_DIR, where to find GL/glut.h, etc.
11233 GLUT_LIBRARIES, the libraries to link against
11234 GLUT_FOUND, If false, do not try to use GLUT.
11235 Also defined, but not for general use are:
11237 GLUT_glut_LIBRARY = the full path to the glut library.
11239 GLUT_Xmu_LIBRARY = the full path to the Xmu library.
11240 GLUT_Xi_LIBRARY = the full path to the Xi Library.
11241 New in version 3.13: Debug and Release variants are found separately.
11243 FindGnuplot
11246 this module looks for gnuplot
11247 Once done this will define
11249 GNUPLOT_FOUND - system has Gnuplot
11251 GNUPLOT_EXECUTABLE - the Gnuplot executable
11252 GNUPLOT_VERSION_STRING - the version of Gnuplot found (since CMake 2.8.8)
11253 GNUPLOT_VERSION_STRING will not work for old versions like 3.7.1.
11255 FindGnuTLS
11257 Find the GNU Transport Layer Security library (gnutls)
11258 IMPORTED Targets
11260 New in version 3.16.
11261 This module defines IMPORTED target GnuTLS::GnuTLS, if gnutls has been
11264 found.
11265 Result Variables
11267 GNUTLS_FOUND
11268 System has gnutls
11269 GNUTLS_INCLUDE_DIR
11271 The gnutls include directory
11272 GNUTLS_LIBRARIES
11274 The libraries needed to use gnutls
11275 GNUTLS_DEFINITIONS
11277 Compiler switches required for using gnutls
11278 GNUTLS_VERSION
11280 version of gnutls.
11281 FindGSL
11283 New in version 3.2.
11284 Find the native GNU Scientific Library (GSL) includes and libraries.
11287 The GNU Scientific Library (GSL) is a numerical library for C and C++
11289 programmers. It is free software under the GNU General Public License.
11290 Imported Targets
11292 If GSL is found, this module defines the following IMPORTED targets:
11293 GSL::gsl - The main GSL library.
11295 GSL::gslcblas - The CBLAS support library used by GSL.
11296 Result Variables
11298 This module will set the following variables in your project:
11299 GSL_FOUND - True if GSL found on the local system
11301 GSL_INCLUDE_DIRS - Location of GSL header files.
11302 GSL_LIBRARIES - The GSL libraries.
11303 GSL_VERSION - The version of the discovered GSL install.
11304 Hints
11306 Set GSL_ROOT_DIR to a directory that contains a GSL installation.
11307 This script expects to find libraries at $GSL_ROOT_DIR/lib and the GSL
11309 headers at $GSL_ROOT_DIR/include/gsl. The library directory may op‐
11310 tionally provide Release and Debug folders. If available, the libraries
11311 named gsld, gslblasd or cblasd are recognized as debug libraries. For
11312 Unix-like systems, this script will use $GSL_ROOT_DIR/bin/gsl-config
11313 (if found) to aid in the discovery of GSL.
11314 Cache Variables
11316 This module may set the following variables depending on platform and
11317 type of GSL installation discovered. These variables may optionally be
11318 set to help this module find the correct files:
11319 GSL_CBLAS_LIBRARY - Location of the GSL CBLAS library.
11321 GSL_CBLAS_LIBRARY_DEBUG - Location of the debug GSL CBLAS library (if any).
11322 GSL_CONFIG_EXECUTABLE - Location of the ``gsl-config`` script (if any).
11323 GSL_LIBRARY - Location of the GSL library.
11324 GSL_LIBRARY_DEBUG - Location of the debug GSL library (if any).
11325 FindGTest
11327 Locate the Google C++ Testing Framework.
11328 New in version 3.20: Upstream GTestConfig.cmake is used if possible.
11330 Imported targets
11333 New in version 3.20: This module defines the following IMPORTED tar‐
11334 gets:
11335 GTest::gtest
11338 The Google Test gtest library, if found; adds Thread::Thread au‐
11339 tomatically
11340 GTest::gtest_main
11342 The Google Test gtest_main library, if found
11343 Deprecated since version 3.20: For backwards compatibility, this module
11345 defines additionally the following deprecated IMPORTED targets (avail‐
11346 able since 3.5):
11347 GTest::GTest
11350 The Google Test gtest library, if found; adds Thread::Thread au‐
11351 tomatically
11352 GTest::Main
11354 The Google Test gtest_main library, if found
11355 Result variables
11357 This module will set the following variables in your project:
11358 GTest_FOUND
11360 Found the Google Testing framework
11361 GTEST_INCLUDE_DIRS
11363 the directory containing the Google Test headers
11364 The library variables below are set as normal variables. These contain
11366 debug/optimized keywords when a debugging library is found.
11367 GTEST_LIBRARIES
11369 The Google Test gtest library; note it also requires linking
11370 with an appropriate thread library
11371 GTEST_MAIN_LIBRARIES
11373 The Google Test gtest_main library
11374 GTEST_BOTH_LIBRARIES
11376 Both gtest and gtest_main
11377 Cache variables
11379 The following cache variables may also be set:
11380 GTEST_ROOT
11382 The root directory of the Google Test installation (may also be
11383 set as an environment variable)
11384 GTEST_MSVC_SEARCH
11386 If compiling with MSVC, this variable can be set to MT or MD
11387 (the default) to enable searching a GTest build tree
11388 Example usage
11390 enable_testing()
11391 find_package(GTest REQUIRED)
11392 add_executable(foo foo.cc)
11394 target_link_libraries(foo GTest::gtest GTest::gtest_main)
11395 add_test(AllTestsInFoo foo)
11397 Deeper integration with CTest
11399 See GoogleTest for information on the gtest_add_tests() and gtest_dis‐
11400 cover_tests() commands.
11401 Changed in version 3.9: Previous CMake versions defined
11403 gtest_add_tests() macro in this module.
11404 FindGTK
11407 Find GTK, glib and GTKGLArea
11408 GTK_INCLUDE_DIR - Directories to include to use GTK
11410 GTK_LIBRARIES - Files to link against to use GTK
11411 GTK_FOUND - GTK was found
11412 GTK_GL_FOUND - GTK's GL features were found
11413 FindGTK2
11415 Find the GTK2 widget libraries and several of its other optional compo‐
11416 nents like gtkmm, glade, and glademm.
11417 Specify one or more of the following components as you call this find
11419 module. See example below.
11420 • gtk
11422 • gtkmm
11424 • glade
11426 • glademm
11428 Imported Targets
11430 This module defines the following IMPORTED targets (subject to compo‐
11431 nent selection):
11432 GTK2::atk, GTK2::atkmm, GTK2::cairo, GTK2::cairomm, GTK2::gdk_pixbuf,
11434 GTK2::gdk, GTK2::gdkmm, GTK2::gio, GTK2::giomm, GTK2::glade,
11435 GTK2::glademm, GTK2::glib, GTK2::glibmm, GTK2::gmodule, GTK2::gobject,
11436 GTK2::gthread, GTK2::gtk, GTK2::gtkmm, GTK2::harfbuzz, GTK2::pango,
11437 GTK2::pangocairo, GTK2::pangoft2, GTK2::pangomm, GTK2::pangoxft,
11438 GTK2::sigc.
11439 New in version 3.16.7: Added the GTK2::harfbuzz target.
11441 Result Variables
11444 The following variables will be defined for your use
11445 GTK2_FOUND
11447 Were all of your specified components found?
11448 GTK2_INCLUDE_DIRS
11450 All include directories
11451 GTK2_LIBRARIES
11453 All libraries
11454 GTK2_TARGETS
11456 New in version 3.5: All imported targets
11457 GTK2_DEFINITIONS
11460 Additional compiler flags
11461 GTK2_VERSION
11463 The version of GTK2 found (x.y.z)
11464 GTK2_MAJOR_VERSION
11466 The major version of GTK2
11467 GTK2_MINOR_VERSION
11469 The minor version of GTK2
11470 GTK2_PATCH_VERSION
11472 The patch version of GTK2
11473 New in version 3.5: When GTK2_USE_IMPORTED_TARGETS is set to TRUE,
11475 GTK2_LIBRARIES will list imported targets instead of library paths.
11476 Input Variables
11479 Optional variables you can define prior to calling this module:
11480 GTK2_DEBUG
11482 Enables verbose debugging of the module
11483 GTK2_ADDITIONAL_SUFFIXES
11485 Allows defining additional directories to search for include
11486 files
11487 Example Usage
11489 Call find_package() once. Here are some examples to pick from:
11490 Require GTK 2.6 or later:
11492 find_package(GTK2 2.6 REQUIRED gtk)
11494 Require GTK 2.10 or later and Glade:
11496 find_package(GTK2 2.10 REQUIRED gtk glade)
11498 Search for GTK/GTKMM 2.8 or later:
11500 find_package(GTK2 2.8 COMPONENTS gtk gtkmm)
11502 Use the results:
11504 if(GTK2_FOUND)
11506 include_directories(${GTK2_INCLUDE_DIRS})
11507 add_executable(mygui mygui.cc)
11508 target_link_libraries(mygui ${GTK2_LIBRARIES})
11509 endif()
11510 FindHDF5
11512 Find Hierarchical Data Format (HDF5), a library for reading and writing
11513 self describing array data.
11514 This module invokes the HDF5 wrapper compiler that should be installed
11516 alongside HDF5. Depending upon the HDF5 Configuration, the wrapper
11517 compiler is called either h5cc or h5pcc. If this succeeds, the module
11518 will then call the compiler with the show argument to see what flags
11519 are used when compiling an HDF5 client application.
11520 The module will optionally accept the COMPONENTS argument. If no COM‐
11522 PONENTS are specified, then the find module will default to finding
11523 only the HDF5 C library. If one or more COMPONENTS are specified, the
11524 module will attempt to find the language bindings for the specified
11525 components. The valid components are C, CXX, Fortran, HL. HL refers
11526 to the "high-level" HDF5 functions for C and Fortran. If the COMPO‐
11527 NENTS argument is not given, the module will attempt to find only the C
11528 bindings. For example, to use Fortran HDF5 and HDF5-HL functions, do:
11529 find_package(HDF5 COMPONENTS Fortran HL).
11530 This module will read the variable HDF5_USE_STATIC_LIBRARIES to deter‐
11532 mine whether or not to prefer a static link to a dynamic link for HDF5
11533 and all of it's dependencies. To use this feature, make sure that the
11534 HDF5_USE_STATIC_LIBRARIES variable is set before the call to find_pack‐
11535 age.
11536 New in version 3.10: Support for HDF5_USE_STATIC_LIBRARIES on Windows.
11538 Both the serial and parallel HDF5 wrappers are considered and the first
11541 directory to contain either one will be used. In the event that both
11542 appear in the same directory the serial version is preferentially se‐
11543 lected. This behavior can be reversed by setting the variable HDF5_PRE‐
11544 FER_PARALLEL to TRUE.
11545 In addition to finding the includes and libraries required to compile
11547 an HDF5 client application, this module also makes an effort to find
11548 tools that come with the HDF5 distribution that may be useful for re‐
11549 gression testing.
11550 Result Variables
11552 This module will set the following variables in your project:
11553 HDF5_FOUND
11555 HDF5 was found on the system
11556 HDF5_VERSION
11558 New in version 3.3: HDF5 library version
11559 HDF5_INCLUDE_DIRS
11562 Location of the HDF5 header files
11563 HDF5_DEFINITIONS
11565 Required compiler definitions for HDF5
11566 HDF5_LIBRARIES
11568 Required libraries for all requested bindings
11569 HDF5_HL_LIBRARIES
11571 Required libraries for the HDF5 high level API for all bindings,
11572 if the HL component is enabled
11573 Available components are: C CXX Fortran and HL. For each enabled lan‐
11575 guage binding, a corresponding HDF5_${LANG}_LIBRARIES variable, and po‐
11576 tentially HDF5_${LANG}_DEFINITIONS, will be defined. If the HL compo‐
11577 nent is enabled, then an HDF5_${LANG}_HL_LIBRARIES will also be de‐
11578 fined. With all components enabled, the following variables will be
11579 defined:
11580 HDF5_C_DEFINITIONS
11582 Required compiler definitions for HDF5 C bindings
11583 HDF5_CXX_DEFINITIONS
11585 Required compiler definitions for HDF5 C++ bindings
11586 HDF5_Fortran_DEFINITIONS
11588 Required compiler definitions for HDF5 Fortran bindings
11589 HDF5_C_INCLUDE_DIRS
11591 Required include directories for HDF5 C bindings
11592 HDF5_CXX_INCLUDE_DIRS
11594 Required include directories for HDF5 C++ bindings
11595 HDF5_Fortran_INCLUDE_DIRS
11597 Required include directories for HDF5 Fortran bindings
11598 HDF5_C_LIBRARIES
11600 Required libraries for the HDF5 C bindings
11601 HDF5_CXX_LIBRARIES
11603 Required libraries for the HDF5 C++ bindings
11604 HDF5_Fortran_LIBRARIES
11606 Required libraries for the HDF5 Fortran bindings
11607 HDF5_C_HL_LIBRARIES
11609 Required libraries for the high level C bindings
11610 HDF5_CXX_HL_LIBRARIES
11612 Required libraries for the high level C++ bindings
11613 HDF5_Fortran_HL_LIBRARIES
11615 Required libraries for the high level Fortran bindings.
11616 HDF5_IS_PARALLEL
11618 HDF5 library has parallel IO support
11619 HDF5_C_COMPILER_EXECUTABLE
11621 path to the HDF5 C wrapper compiler
11622 HDF5_CXX_COMPILER_EXECUTABLE
11624 path to the HDF5 C++ wrapper compiler
11625 HDF5_Fortran_COMPILER_EXECUTABLE
11627 path to the HDF5 Fortran wrapper compiler
11628 HDF5_C_COMPILER_EXECUTABLE_NO_INTERROGATE
11630 path to the primary C compiler which is also the HDF5 wrapper
11631 HDF5_CXX_COMPILER_EXECUTABLE_NO_INTERROGATE
11633 path to the primary C++ compiler which is also the HDF5 wrapper
11634 HDF5_Fortran_COMPILER_EXECUTABLE_NO_INTERROGATE
11636 path to the primary Fortran compiler which is also the HDF5
11637 wrapper
11638 HDF5_DIFF_EXECUTABLE
11640 path to the HDF5 dataset comparison tool
11641 With all components enabled, the following targets will be defined:
11643 HDF5::HDF5
11645 All detected HDF5_LIBRARIES.
11646 hdf5::hdf5
11648 C library.
11649 hdf5::hdf5_cpp
11651 C++ library.
11652 hdf5::hdf5_fortran
11654 Fortran library.
11655 hdf5::hdf5_hl
11657 High-level C library.
11658 hdf5::hdf5_hl_cpp
11660 High-level C++ library.
11661 hdf5::hdf5_hl_fortran
11663 High-level Fortran library.
11664 hdf5::h5diff
11666 h5diff executable.
11667 Hints
11669 The following variables can be set to guide the search for HDF5 li‐
11670 braries and includes:
11671 HDF5_PREFER_PARALLEL
11673 New in version 3.4.
11674 set true to prefer parallel HDF5 (by default, serial is pre‐
11677 ferred)
11678 HDF5_FIND_DEBUG
11680 New in version 3.9.
11681 Set true to get extra debugging output.
11684 HDF5_NO_FIND_PACKAGE_CONFIG_FILE
11686 New in version 3.8.
11687 Set true to skip trying to find hdf5-config.cmake.
11690 FindHg
11692 Extract information from a mercurial working copy.
11693 The module defines the following variables:
11695 HG_EXECUTABLE - path to mercurial command line client (hg)
11697 HG_FOUND - true if the command line client was found
11698 HG_VERSION_STRING - the version of mercurial found
11699 New in version 3.1: If the command line client executable is found the
11701 following macro is defined:
11702 HG_WC_INFO(<dir> <var-prefix>)
11705 Hg_WC_INFO extracts information of a mercurial working copy at a given
11707 location. This macro defines the following variables:
11708 <var-prefix>_WC_CHANGESET - current changeset
11710 <var-prefix>_WC_REVISION - current revision
11711 Example usage:
11713 find_package(Hg)
11715 if(HG_FOUND)
11716 message("hg found: ${HG_EXECUTABLE}")
11717 HG_WC_INFO(${PROJECT_SOURCE_DIR} Project)
11718 message("Current revision is ${Project_WC_REVISION}")
11719 message("Current changeset is ${Project_WC_CHANGESET}")
11720 endif()
11721 FindHSPELL
11723 Try to find Hebrew spell-checker (Hspell) and morphology engine.
11724 Once done this will define
11726 HSPELL_FOUND - system has Hspell
11728 HSPELL_INCLUDE_DIR - the Hspell include directory
11729 HSPELL_LIBRARIES - The libraries needed to use Hspell
11730 HSPELL_DEFINITIONS - Compiler switches required for using Hspell
11731 HSPELL_VERSION_STRING - The version of Hspell found (x.y)
11733 HSPELL_MAJOR_VERSION - the major version of Hspell
11734 HSPELL_MINOR_VERSION - The minor version of Hspell
11735 FindHTMLHelp
11737 This module looks for Microsoft HTML Help Compiler
11738 It defines:
11740 HTML_HELP_COMPILER : full path to the Compiler (hhc.exe)
11742 HTML_HELP_INCLUDE_PATH : include path to the API (htmlhelp.h)
11743 HTML_HELP_LIBRARY : full path to the library (htmlhelp.lib)
11744 FindIce
11746 New in version 3.1.
11747 Find the ZeroC Internet Communication Engine (ICE) programs, libraries
11750 and datafiles.
11751 This module supports multiple components. Components can include any
11753 of: Freeze, Glacier2, Ice, IceBox, IceDB, IceDiscovery, IceGrid, IceLo‐
11754 catorDiscovery, IcePatch, IceSSL, IceStorm, IceUtil, IceXML, or Slice.
11755 Ice 3.7 and later also include C++11-specific components: Glacier2++11,
11757 Ice++11, IceBox++11, IceDiscovery++11 IceGrid, IceLocatorDiscovery++11,
11758 IceSSL++11, IceStorm++11
11759 Note that the set of supported components is Ice version-specific.
11761 New in version 3.4: Imported targets for components and most EXECUTABLE
11763 variables.
11764 New in version 3.7: Debug and Release variants are found separately.
11767 New in version 3.10: Ice 3.7 support, including new components, pro‐
11770 grams and the Nuget package.
11771 This module reports information about the Ice installation in several
11774 variables. General variables:
11775 Ice_VERSION - Ice release version
11777 Ice_FOUND - true if the main programs and libraries were found
11778 Ice_LIBRARIES - component libraries to be linked
11779 Ice_INCLUDE_DIRS - the directories containing the Ice headers
11780 Ice_SLICE_DIRS - the directories containing the Ice slice interface
11781 definitions
11782 Imported targets:
11784 Ice::<C>
11786 Where <C> is the name of an Ice component, for example Ice::Glacier2 or
11788 Ice++11.
11789 Ice slice programs are reported in:
11791 Ice_SLICE2CONFLUENCE_EXECUTABLE - path to slice2confluence executable
11793 Ice_SLICE2CPP_EXECUTABLE - path to slice2cpp executable
11794 Ice_SLICE2CS_EXECUTABLE - path to slice2cs executable
11795 Ice_SLICE2FREEZEJ_EXECUTABLE - path to slice2freezej executable
11796 Ice_SLICE2FREEZE_EXECUTABLE - path to slice2freeze executable
11797 Ice_SLICE2HTML_EXECUTABLE - path to slice2html executable
11798 Ice_SLICE2JAVA_EXECUTABLE - path to slice2java executable
11799 Ice_SLICE2JS_EXECUTABLE - path to slice2js executable
11800 Ice_SLICE2MATLAB_EXECUTABLE - path to slice2matlab executable
11801 Ice_SLICE2OBJC_EXECUTABLE - path to slice2objc executable
11802 Ice_SLICE2PHP_EXECUTABLE - path to slice2php executable
11803 Ice_SLICE2PY_EXECUTABLE - path to slice2py executable
11804 Ice_SLICE2RB_EXECUTABLE - path to slice2rb executable
11805 New in version 3.14: Variables for slice2confluence and slice2matlab.
11807 Ice programs are reported in:
11810 Ice_GLACIER2ROUTER_EXECUTABLE - path to glacier2router executable
11812 Ice_ICEBOX_EXECUTABLE - path to icebox executable
11813 Ice_ICEBOXXX11_EXECUTABLE - path to icebox++11 executable
11814 Ice_ICEBOXADMIN_EXECUTABLE - path to iceboxadmin executable
11815 Ice_ICEBOXD_EXECUTABLE - path to iceboxd executable
11816 Ice_ICEBOXNET_EXECUTABLE - path to iceboxnet executable
11817 Ice_ICEBRIDGE_EXECUTABLE - path to icebridge executable
11818 Ice_ICEGRIDADMIN_EXECUTABLE - path to icegridadmin executable
11819 Ice_ICEGRIDDB_EXECUTABLE - path to icegriddb executable
11820 Ice_ICEGRIDNODE_EXECUTABLE - path to icegridnode executable
11821 Ice_ICEGRIDNODED_EXECUTABLE - path to icegridnoded executable
11822 Ice_ICEGRIDREGISTRY_EXECUTABLE - path to icegridregistry executable
11823 Ice_ICEGRIDREGISTRYD_EXECUTABLE - path to icegridregistryd executable
11824 Ice_ICEPATCH2CALC_EXECUTABLE - path to icepatch2calc executable
11825 Ice_ICEPATCH2CLIENT_EXECUTABLE - path to icepatch2client executable
11826 Ice_ICEPATCH2SERVER_EXECUTABLE - path to icepatch2server executable
11827 Ice_ICESERVICEINSTALL_EXECUTABLE - path to iceserviceinstall executable
11828 Ice_ICESTORMADMIN_EXECUTABLE - path to icestormadmin executable
11829 Ice_ICESTORMDB_EXECUTABLE - path to icestormdb executable
11830 Ice_ICESTORMMIGRATE_EXECUTABLE - path to icestormmigrate executable
11831 Ice db programs (Windows only; standard system versions on all other
11833 platforms) are reported in:
11834 Ice_DB_ARCHIVE_EXECUTABLE - path to db_archive executable
11836 Ice_DB_CHECKPOINT_EXECUTABLE - path to db_checkpoint executable
11837 Ice_DB_DEADLOCK_EXECUTABLE - path to db_deadlock executable
11838 Ice_DB_DUMP_EXECUTABLE - path to db_dump executable
11839 Ice_DB_HOTBACKUP_EXECUTABLE - path to db_hotbackup executable
11840 Ice_DB_LOAD_EXECUTABLE - path to db_load executable
11841 Ice_DB_LOG_VERIFY_EXECUTABLE - path to db_log_verify executable
11842 Ice_DB_PRINTLOG_EXECUTABLE - path to db_printlog executable
11843 Ice_DB_RECOVER_EXECUTABLE - path to db_recover executable
11844 Ice_DB_STAT_EXECUTABLE - path to db_stat executable
11845 Ice_DB_TUNER_EXECUTABLE - path to db_tuner executable
11846 Ice_DB_UPGRADE_EXECUTABLE - path to db_upgrade executable
11847 Ice_DB_VERIFY_EXECUTABLE - path to db_verify executable
11848 Ice_DUMPDB_EXECUTABLE - path to dumpdb executable
11849 Ice_TRANSFORMDB_EXECUTABLE - path to transformdb executable
11850 Ice component libraries are reported in:
11852 Ice_<C>_FOUND - ON if component was found
11854 Ice_<C>_LIBRARIES - libraries for component
11855 Note that <C> is the uppercased name of the component.
11857 This module reads hints about search results from:
11859 Ice_HOME - the root of the Ice installation
11861 The environment variable ICE_HOME may also be used; the Ice_HOME vari‐
11863 able takes precedence.
11864 NOTE:
11866 On Windows, Ice 3.7.0 and later provide libraries via the NuGet
11867 package manager. Appropriate NuGet packages will be searched for
11868 using CMAKE_PREFIX_PATH, or alternatively Ice_HOME may be set to the
11869 location of a specific NuGet package to restrict the search.
11870 The following cache variables may also be set:
11872 Ice_<P>_EXECUTABLE - the path to executable <P>
11874 Ice_INCLUDE_DIR - the directory containing the Ice headers
11875 Ice_SLICE_DIR - the directory containing the Ice slice interface
11876 definitions
11877 Ice_<C>_LIBRARY - the library for component <C>
11878 NOTE:
11880 In most cases none of the above variables will require setting, un‐
11881 less multiple Ice versions are available and a specific version is
11882 required. On Windows, the most recent version of Ice will be found
11883 through the registry. On Unix, the programs, headers and libraries
11884 will usually be in standard locations, but Ice_SLICE_DIRS might not
11885 be automatically detected (commonly known locations are searched).
11886 All the other variables are defaulted using Ice_HOME, if set. It's
11887 possible to set Ice_HOME and selectively specify alternative loca‐
11888 tions for the other components; this might be required for e.g.
11889 newer versions of Visual Studio if the heuristics are not sufficient
11890 to identify the correct programs and libraries for the specific Vis‐
11891 ual Studio version.
11892 Other variables one may set to control this module are:
11894 Ice_DEBUG - Set to ON to enable debug output from FindIce.
11896 FindIconv
11898 New in version 3.11.
11899 This module finds the iconv() POSIX.1 functions on the system. These
11902 functions might be provided in the regular C library or externally in
11903 the form of an additional library.
11904 The following variables are provided to indicate iconv support:
11906 Iconv_FOUND
11908 Variable indicating if the iconv support was found.
11909 Iconv_INCLUDE_DIRS
11911 The directories containing the iconv headers.
11912 Iconv_LIBRARIES
11914 The iconv libraries to be linked.
11915 Iconv_IS_BUILT_IN
11917 A variable indicating whether iconv support is stemming from the
11918 C library or not. Even if the C library provides iconv(), the
11919 presence of an external libiconv implementation might lead to
11920 this being false.
11921 Additionally, the following IMPORTED target is being provided:
11923 Iconv::Iconv
11925 Imported target for using iconv.
11926 The following cache variables may also be set:
11928 Iconv_INCLUDE_DIR
11930 The directory containing the iconv headers.
11931 Iconv_LIBRARY
11933 The iconv library (if not implicitly given in the C library).
11934 NOTE:
11936 On POSIX platforms, iconv might be part of the C library and the
11937 cache variables Iconv_INCLUDE_DIR and Iconv_LIBRARY might be empty.
11938 FindIcotool
11940 Find icotool
11941 This module looks for icotool. Convert and create Win32 icon and cursor
11943 files. This module defines the following values:
11944 ICOTOOL_EXECUTABLE: the full path to the icotool tool.
11946 ICOTOOL_FOUND: True if icotool has been found.
11947 ICOTOOL_VERSION_STRING: the version of icotool found.
11948 FindICU
11950 New in version 3.7.
11951 Find the International Components for Unicode (ICU) libraries and pro‐
11954 grams.
11955 This module supports multiple components. Components can include any
11957 of: data, i18n, io, le, lx, test, tu and uc.
11958 Note that on Windows data is named dt and i18n is named in; any of the
11960 names may be used, and the appropriate platform-specific library name
11961 will be automatically selected.
11962 New in version 3.11: Added support for static libraries on Windows.
11964 This module reports information about the ICU installation in several
11967 variables. General variables:
11968 ICU_VERSION - ICU release version
11970 ICU_FOUND - true if the main programs and libraries were found
11971 ICU_LIBRARIES - component libraries to be linked
11972 ICU_INCLUDE_DIRS - the directories containing the ICU headers
11973 Imported targets:
11975 ICU::<C>
11977 Where <C> is the name of an ICU component, for example ICU::i18n; <C>
11979 is lower-case.
11980 ICU programs are reported in:
11982 ICU_GENCNVAL_EXECUTABLE - path to gencnval executable
11984 ICU_ICUINFO_EXECUTABLE - path to icuinfo executable
11985 ICU_GENBRK_EXECUTABLE - path to genbrk executable
11986 ICU_ICU-CONFIG_EXECUTABLE - path to icu-config executable
11987 ICU_GENRB_EXECUTABLE - path to genrb executable
11988 ICU_GENDICT_EXECUTABLE - path to gendict executable
11989 ICU_DERB_EXECUTABLE - path to derb executable
11990 ICU_PKGDATA_EXECUTABLE - path to pkgdata executable
11991 ICU_UCONV_EXECUTABLE - path to uconv executable
11992 ICU_GENCFU_EXECUTABLE - path to gencfu executable
11993 ICU_MAKECONV_EXECUTABLE - path to makeconv executable
11994 ICU_GENNORM2_EXECUTABLE - path to gennorm2 executable
11995 ICU_GENCCODE_EXECUTABLE - path to genccode executable
11996 ICU_GENSPREP_EXECUTABLE - path to gensprep executable
11997 ICU_ICUPKG_EXECUTABLE - path to icupkg executable
11998 ICU_GENCMN_EXECUTABLE - path to gencmn executable
11999 ICU component libraries are reported in:
12001 ICU_<C>_FOUND - ON if component was found; ``<C>`` is upper-case.
12003 ICU_<C>_LIBRARIES - libraries for component; ``<C>`` is upper-case.
12004 ICU datafiles are reported in:
12006 ICU_MAKEFILE_INC - Makefile.inc
12008 ICU_PKGDATA_INC - pkgdata.inc
12009 This module reads hints about search results from:
12011 ICU_ROOT - the root of the ICU installation
12013 The environment variable ICU_ROOT may also be used; the ICU_ROOT vari‐
12015 able takes precedence.
12016 The following cache variables may also be set:
12018 ICU_<P>_EXECUTABLE - the path to executable <P>; ``<P>`` is upper-case.
12020 ICU_INCLUDE_DIR - the directory containing the ICU headers
12021 ICU_<C>_LIBRARY - the library for component <C>; ``<C>`` is upper-case.
12022 NOTE:
12024 In most cases none of the above variables will require setting, un‐
12025 less multiple ICU versions are available and a specific version is
12026 required.
12027 Other variables one may set to control this module are:
12029 ICU_DEBUG - Set to ON to enable debug output from FindICU.
12031 FindImageMagick
12033 Find ImageMagick binary suite.
12034 New in version 3.9: Added support for ImageMagick 7.
12036 This module will search for a set of ImageMagick tools specified as
12039 components in the find_package() call. Typical components include, but
12040 are not limited to (future versions of ImageMagick might have addi‐
12041 tional components not listed here):
12042 animate
12044 compare
12045 composite
12046 conjure
12047 convert
12048 display
12049 identify
12050 import
12051 mogrify
12052 montage
12053 stream
12054 If no component is specified in the find_package() call, then it only
12056 searches for the ImageMagick executable directory. This code defines
12057 the following variables:
12058 ImageMagick_FOUND - TRUE if all components are found.
12060 ImageMagick_EXECUTABLE_DIR - Full path to executables directory.
12061 ImageMagick_<component>_FOUND - TRUE if <component> is found.
12062 ImageMagick_<component>_EXECUTABLE - Full path to <component> executable.
12063 ImageMagick_VERSION_STRING - the version of ImageMagick found
12064 (since CMake 2.8.8)
12065 ImageMagick_VERSION_STRING will not work for old versions like 5.2.3.
12067 There are also components for the following ImageMagick APIs:
12069 Magick++
12071 MagickWand
12072 MagickCore
12073 For these components the following variables are set:
12075 ImageMagick_FOUND - TRUE if all components are found.
12077 ImageMagick_INCLUDE_DIRS - Full paths to all include dirs.
12078 ImageMagick_LIBRARIES - Full paths to all libraries.
12079 ImageMagick_<component>_FOUND - TRUE if <component> is found.
12080 ImageMagick_<component>_INCLUDE_DIRS - Full path to <component> include dirs.
12081 ImageMagick_<component>_LIBRARIES - Full path to <component> libraries.
12082 Example Usages:
12084 find_package(ImageMagick)
12086 find_package(ImageMagick COMPONENTS convert)
12087 find_package(ImageMagick COMPONENTS convert mogrify display)
12088 find_package(ImageMagick COMPONENTS Magick++)
12089 find_package(ImageMagick COMPONENTS Magick++ convert)
12090 Note that the standard find_package() features are supported (i.e.,
12092 QUIET, REQUIRED, etc.).
12093 FindIntl
12095 New in version 3.2.
12096 Find the Gettext libintl headers and libraries.
12099 This module reports information about the Gettext libintl installation
12101 in several variables.
12102 Intl_FOUND
12104 True if libintl is found.
12105 Intl_INCLUDE_DIRS
12107 The directory containing the libintl headers.
12108 Intl_LIBRARIES
12110 The intl libraries to be linked.
12111 New in version 3.20: This module defines IMPORTED target Intl::Intl.
12113 The following cache variables may also be set:
12116 Intl_INCLUDE_DIR
12118 The directory containing the libintl headers
12119 Intl_LIBRARY
12121 The libintl library (if any)
12122 Intl_IS_BUILT_IN
12124 New in version 3.20.
12125 whether intl is a part of the C library.
12128 NOTE:
12130 On some platforms, such as Linux with GNU libc, the gettext func‐
12131 tions are present in the C standard library and libintl is not re‐
12132 quired. Intl_LIBRARIES will be empty in this case.
12133 NOTE:
12135 If you wish to use the Gettext tools (msgmerge, msgfmt, etc.), use
12136 FindGettext.
12137 FindITK
12139 This module no longer exists.
12140 This module existed in versions of CMake prior to 3.1, but became only
12142 a thin wrapper around find_package(ITK NO_MODULE) to provide compati‐
12143 bility for projects using long-outdated conventions. Now find_pack‐
12144 age(ITK) will search for ITKConfig.cmake directly.
12145 FindJasper
12147 Try to find the Jasper JPEG2000 library
12148 Once done this will define
12150 JASPER_FOUND - system has Jasper
12152 JASPER_INCLUDE_DIR - the Jasper include directory
12153 JASPER_LIBRARIES - the libraries needed to use Jasper
12154 JASPER_VERSION_STRING - the version of Jasper found (since CMake 2.8.8)
12155 FindJava
12157 Find Java
12158 This module finds if Java is installed and determines where the include
12160 files and libraries are. The caller may set variable JAVA_HOME to
12161 specify a Java installation prefix explicitly.
12162 See also the FindJNI module to find Java Native Interface (JNI).
12164 New in version 3.10: Added support for Java 9+ version parsing.
12166 Specify one or more of the following components as you call this find
12169 module. See example below.
12170 Runtime = Java Runtime Environment used to execute Java byte-compiled applications
12172 Development = Development tools (java, javac, javah, jar and javadoc), includes Runtime component
12173 IdlJ = Interface Description Language (IDL) to Java compiler
12174 JarSigner = Signer and verifier tool for Java Archive (JAR) files
12175 This module sets the following result variables:
12177 Java_JAVA_EXECUTABLE = the full path to the Java runtime
12179 Java_JAVAC_EXECUTABLE = the full path to the Java compiler
12180 Java_JAVAH_EXECUTABLE = the full path to the Java header generator
12181 Java_JAVADOC_EXECUTABLE = the full path to the Java documentation generator
12182 Java_IDLJ_EXECUTABLE = the full path to the Java idl compiler
12183 Java_JAR_EXECUTABLE = the full path to the Java archiver
12184 Java_JARSIGNER_EXECUTABLE = the full path to the Java jar signer
12185 Java_VERSION_STRING = Version of java found, eg. 1.6.0_12
12186 Java_VERSION_MAJOR = The major version of the package found.
12187 Java_VERSION_MINOR = The minor version of the package found.
12188 Java_VERSION_PATCH = The patch version of the package found.
12189 Java_VERSION_TWEAK = The tweak version of the package found (after '_')
12190 Java_VERSION = This is set to: $major[.$minor[.$patch[.$tweak]]]
12191 New in version 3.4: Added the Java_IDLJ_EXECUTABLE and Java_JAR‐
12193 SIGNER_EXECUTABLE variables.
12194 The minimum required version of Java can be specified using the
12197 find_package() syntax, e.g.
12198 find_package(Java 1.8)
12200 NOTE: ${Java_VERSION} and ${Java_VERSION_STRING} are not guaranteed to
12202 be identical. For example some java version may return: Java_VER‐
12203 SION_STRING = 1.8.0_17 and Java_VERSION = 1.8.0.17
12204 another example is the Java OEM, with: Java_VERSION_STRING = 1.8.0-oem
12206 and Java_VERSION = 1.8.0
12207 For these components the following variables are set:
12209 Java_FOUND - TRUE if all components are found.
12211 Java_<component>_FOUND - TRUE if <component> is found.
12212 Example Usages:
12214 find_package(Java)
12216 find_package(Java 1.8 REQUIRED)
12217 find_package(Java COMPONENTS Runtime)
12218 find_package(Java COMPONENTS Development)
12219 FindJNI
12221 Find Java Native Interface (JNI) libraries.
12222 JNI enables Java code running in a Java Virtual Machine (JVM) to call
12224 and be called by native applications and libraries written in other
12225 languages such as C, C++.
12226 This module finds if Java is installed and determines where the include
12228 files and libraries are. It also determines what the name of the li‐
12229 brary is. The caller may set variable JAVA_HOME to specify a Java in‐
12230 stallation prefix explicitly.
12231 Result Variables
12233 This module sets the following result variables:
12234 JNI_INCLUDE_DIRS
12236 the include dirs to use
12237 JNI_LIBRARIES
12239 the libraries to use (JAWT and JVM)
12240 JNI_FOUND
12242 TRUE if JNI headers and libraries were found.
12243 Cache Variables
12245 The following cache variables are also available to set or use:
12246 JAVA_AWT_LIBRARY
12248 the path to the Java AWT Native Interface (JAWT) library
12249 JAVA_JVM_LIBRARY
12251 the path to the Java Virtual Machine (JVM) library
12252 JAVA_INCLUDE_PATH
12254 the include path to jni.h
12255 JAVA_INCLUDE_PATH2
12257 the include path to jni_md.h and jniport.h
12258 JAVA_AWT_INCLUDE_PATH
12260 the include path to jawt.h
12261 FindJPEG
12263 Find the Joint Photographic Experts Group (JPEG) library (libjpeg)
12264 Imported targets
12266 New in version 3.12.
12267 This module defines the following IMPORTED targets:
12270 JPEG::JPEG
12272 The JPEG library, if found.
12273 Result variables
12275 This module will set the following variables in your project:
12276 JPEG_FOUND
12278 If false, do not try to use JPEG.
12279 JPEG_INCLUDE_DIRS
12281 where to find jpeglib.h, etc.
12282 JPEG_LIBRARIES
12284 the libraries needed to use JPEG.
12285 JPEG_VERSION
12287 New in version 3.12: the version of the JPEG library found
12288 Cache variables
12291 The following cache variables may also be set:
12292 JPEG_INCLUDE_DIRS
12294 where to find jpeglib.h, etc.
12295 JPEG_LIBRARY_RELEASE
12297 where to find the JPEG library (optimized).
12298 JPEG_LIBRARY_DEBUG
12300 where to find the JPEG library (debug).
12301 New in version 3.12: Debug and Release variand are found separately.
12303 Obsolete variables
12306 JPEG_INCLUDE_DIR
12307 where to find jpeglib.h, etc. (same as JPEG_INCLUDE_DIRS)
12308 JPEG_LIBRARY
12310 where to find the JPEG library.
12311 FindKDE3
12313 Find the KDE3 include and library dirs, KDE preprocessors and define a
12314 some macros
12315 This module defines the following variables:
12317 KDE3_DEFINITIONS
12319 compiler definitions required for compiling KDE software
12320 KDE3_INCLUDE_DIR
12322 the KDE include directory
12323 KDE3_INCLUDE_DIRS
12325 the KDE and the Qt include directory, for use with include_di‐
12326 rectories()
12327 KDE3_LIB_DIR
12329 the directory where the KDE libraries are installed, for use
12330 with link_directories()
12331 QT_AND_KDECORE_LIBS
12333 this contains both the Qt and the kdecore library
12334 KDE3_DCOPIDL_EXECUTABLE
12336 the dcopidl executable
12337 KDE3_DCOPIDL2CPP_EXECUTABLE
12339 the dcopidl2cpp executable
12340 KDE3_KCFGC_EXECUTABLE
12342 the kconfig_compiler executable
12343 KDE3_FOUND
12345 set to TRUE if all of the above has been found
12346 The following user adjustable options are provided:
12348 KDE3_BUILD_TESTS
12350 enable this to build KDE testcases
12351 It also adds the following macros (from KDE3Macros.cmake) SRCS_VAR is
12353 always the variable which contains the list of source files for your
12354 application or library.
12355 KDE3_AUTOMOC(file1 ... fileN)
12357 Call this if you want to have automatic moc file handling.
12359 This means if you include "foo.moc" in the source file foo.cpp
12360 a moc file for the header foo.h will be created automatically.
12361 You can set the property SKIP_AUTOMAKE using set_source_files_properties()
12362 to exclude some files in the list from being processed.
12363 KDE3_ADD_MOC_FILES(SRCS_VAR file1 ... fileN )
12365 If you don't use the KDE3_AUTOMOC() macro, for the files
12367 listed here moc files will be created (named "foo.moc.cpp")
12368 KDE3_ADD_DCOP_SKELS(SRCS_VAR header1.h ... headerN.h )
12370 Use this to generate DCOP skeletions from the listed headers.
12372 KDE3_ADD_DCOP_STUBS(SRCS_VAR header1.h ... headerN.h )
12374 Use this to generate DCOP stubs from the listed headers.
12376 KDE3_ADD_UI_FILES(SRCS_VAR file1.ui ... fileN.ui )
12378 Use this to add the Qt designer ui files to your application/library.
12380 KDE3_ADD_KCFG_FILES(SRCS_VAR file1.kcfgc ... fileN.kcfgc )
12382 Use this to add KDE kconfig compiler files to your application/library.
12384 KDE3_INSTALL_LIBTOOL_FILE(target)
12386 This will create and install a simple libtool file for the given target.
12388 KDE3_ADD_EXECUTABLE(name file1 ... fileN )
12390 Currently identical to add_executable(), may provide some advanced
12392 features in the future.
12393 KDE3_ADD_KPART(name [WITH_PREFIX] file1 ... fileN )
12395 Create a KDE plugin (KPart, kioslave, etc.) from the given source files.
12397 If WITH_PREFIX is given, the resulting plugin will have the prefix "lib",
12398 otherwise it won't.
12399 It creates and installs an appropriate libtool la-file.
12400 KDE3_ADD_KDEINIT_EXECUTABLE(name file1 ... fileN )
12402 Create a KDE application in the form of a module loadable via kdeinit.
12404 A library named kdeinit_<name> will be created and a small executable
12405 which links to it.
12406 The option KDE3_ENABLE_FINAL to enable all-in-one compilation is no
12408 longer supported.
12409 Author: Alexander Neundorf <neundorf@kde.org>
12411 FindKDE4
12413 Find KDE4 and provide all necessary variables and macros to compile
12414 software for it. It looks for KDE 4 in the following directories in
12415 the given order:
12416 CMAKE_INSTALL_PREFIX
12418 KDEDIRS
12419 /opt/kde4
12420 Please look in FindKDE4Internal.cmake and KDE4Macros.cmake for more in‐
12422 formation. They are installed with the KDE 4 libraries in
12423 $KDEDIRS/share/apps/cmake/modules/.
12424 Author: Alexander Neundorf <neundorf@kde.org>
12426 FindLAPACK
12428 Find Linear Algebra PACKage (LAPACK) library
12429 This module finds an installed Fortran library that implements the LA‐
12431 PACK linear-algebra interface (see http://www.netlib.org/lapack/).
12432 The approach follows that taken for the autoconf macro file, acx_la‐
12434 pack.m4 (distributed at
12435 http://ac-archive.sourceforge.net/ac-archive/acx_lapack.html).
12436 Input Variables
12438 The following variables may be set to influence this module's behavior:
12439 BLA_STATIC
12441 if ON use static linkage
12442 BLA_VENDOR
12444 If set, checks only the specified vendor, if not set checks all
12445 the possibilities. List of vendors valid in this module:
12446 • FlexiBLAS
12448 • OpenBLAS
12450 • FLAME
12452 • Intel10_32 (intel mkl v10 32 bit, threaded code)
12454 • Intel10_64lp (intel mkl v10+ 64 bit, threaded code, lp64
12456 model)
12457 • Intel10_64lp_seq (intel mkl v10+ 64 bit, sequential code, lp64
12459 model)
12460 • Intel10_64ilp (intel mkl v10+ 64 bit, threaded code, ilp64
12462 model)
12463 • Intel10_64ilp_seq (intel mkl v10+ 64 bit, sequential code,
12465 ilp64 model)
12466 • Intel10_64_dyn (intel mkl v10+ 64 bit, single dynamic library)
12468 • Intel (obsolete versions of mkl 32 and 64 bit)
12470 • ACML
12472 • Apple
12474 • NAS
12476 • Arm
12478 • Arm_mp
12480 • Arm_ilp64
12482 • Arm_ilp64_mp
12484 • EML
12486 • EML_mt
12488 • Generic
12490 New in version 3.6: OpenBLAS support.
12492 New in version 3.11: FLAME support.
12495 New in version 3.13: Added ILP64 MKL variants (Intel10_64ilp,
12497 Intel10_64ilp_seq).
12498 New in version 3.17: Added single dynamic library MKL variant
12502 (Intel10_64_dyn).
12503 New in version 3.18: Arm Performance Libraries support (Arm,
12506 Arm_mp, Arm_ilp64, Arm_ilp64_mp).
12507 New in version 3.19: FlexiBLAS support.
12510 New in version 3.20: Elbrus Math Library support (EML, EML_mt).
12513 BLA_F95
12516 if ON tries to find the BLAS95/LAPACK95 interfaces
12517 BLA_PREFER_PKGCONFIG
12519 New in version 3.20.
12520 if set pkg-config will be used to search for a LAPACK library
12523 first and if one is found that is preferred
12524 Imported targets
12526 New in version 3.18.
12527 This module defines the following IMPORTED target:
12530 LAPACK::LAPACK
12532 The libraries to use for LAPACK, if found.
12533 Result Variables
12535 This module defines the following variables:
12536 LAPACK_FOUND
12538 library implementing the LAPACK interface is found
12539 LAPACK_LINKER_FLAGS
12541 uncached list of required linker flags (excluding -l and -L).
12542 LAPACK_LIBRARIES
12544 uncached list of libraries (using full path name) to link
12545 against to use LAPACK
12546 LAPACK95_LIBRARIES
12548 uncached list of libraries (using full path name) to link
12549 against to use LAPACK95
12550 LAPACK95_FOUND
12552 library implementing the LAPACK95 interface is found
12553 NOTE:
12555 C, CXX or Fortran must be enabled to detect a BLAS/LAPACK library.
12556 C or CXX must be enabled to use Intel Math Kernel Library (MKL).
12557 For example, to use Intel MKL libraries and/or Intel compiler:
12559 set(BLA_VENDOR Intel10_64lp)
12561 find_package(LAPACK)
12562 FindLATEX
12564 Find LaTeX
12565 This module finds an installed LaTeX and determines the location of the
12567 compiler. Additionally the module looks for Latex-related software
12568 like BibTeX.
12569 New in version 3.2: Component processing; support for htlatex, pdftops,
12571 Biber, xindy, XeLaTeX, LuaLaTeX.
12572 This module sets the following result variables:
12575 LATEX_FOUND: whether found Latex and requested components
12577 LATEX_<component>_FOUND: whether found <component>
12578 LATEX_COMPILER: path to the LaTeX compiler
12579 PDFLATEX_COMPILER: path to the PdfLaTeX compiler
12580 XELATEX_COMPILER: path to the XeLaTeX compiler
12581 LUALATEX_COMPILER: path to the LuaLaTeX compiler
12582 BIBTEX_COMPILER: path to the BibTeX compiler
12583 BIBER_COMPILER: path to the Biber compiler
12584 MAKEINDEX_COMPILER: path to the MakeIndex compiler
12585 XINDY_COMPILER: path to the xindy compiler
12586 DVIPS_CONVERTER: path to the DVIPS converter
12587 DVIPDF_CONVERTER: path to the DVIPDF converter
12588 PS2PDF_CONVERTER: path to the PS2PDF converter
12589 PDFTOPS_CONVERTER: path to the pdftops converter
12590 LATEX2HTML_CONVERTER: path to the LaTeX2Html converter
12591 HTLATEX_COMPILER: path to the htlatex compiler
12592 Possible components are:
12594 PDFLATEX
12596 XELATEX
12597 LUALATEX
12598 BIBTEX
12599 BIBER
12600 MAKEINDEX
12601 XINDY
12602 DVIPS
12603 DVIPDF
12604 PS2PDF
12605 PDFTOPS
12606 LATEX2HTML
12607 HTLATEX
12608 Example Usages:
12610 find_package(LATEX)
12612 find_package(LATEX COMPONENTS PDFLATEX)
12613 find_package(LATEX COMPONENTS BIBTEX PS2PDF)
12614 FindLibArchive
12616 Find libarchive library and headers. Libarchive is multi-format ar‐
12617 chive and compression library.
12618 The module defines the following variables:
12620 LibArchive_FOUND - true if libarchive was found
12622 LibArchive_INCLUDE_DIRS - include search path
12623 LibArchive_LIBRARIES - libraries to link
12624 LibArchive_VERSION - libarchive 3-component version number
12625 The module defines the following IMPORTED targets:
12627 LibArchive::LibArchive - target for linking against libarchive
12629 New in version 3.6: Support for new libarchive 3.2 version string for‐
12631 mat.
12632 FindLibinput
12635 New in version 3.14.
12636 Find libinput headers and library.
12639 Imported Targets
12641 Libinput::Libinput
12642 The libinput library, if found.
12643 Result Variables
12645 This will define the following variables in your project:
12646 Libinput_FOUND
12648 true if (the requested version of) libinput is available.
12649 Libinput_VERSION
12651 the version of libinput.
12652 Libinput_LIBRARIES
12654 the libraries to link against to use libinput.
12655 Libinput_INCLUDE_DIRS
12657 where to find the libinput headers.
12658 Libinput_COMPILE_OPTIONS
12660 this should be passed to target_compile_options(), if the target
12661 is not used for linking
12662 FindLibLZMA
12664 Find LZMA compression algorithm headers and library.
12665 Imported Targets
12667 New in version 3.14.
12668 This module defines IMPORTED target LibLZMA::LibLZMA, if liblzma has
12671 been found.
12672 Result variables
12674 This module will set the following variables in your project:
12675 LIBLZMA_FOUND
12677 True if liblzma headers and library were found.
12678 LIBLZMA_INCLUDE_DIRS
12680 Directory where liblzma headers are located.
12681 LIBLZMA_LIBRARIES
12683 Lzma libraries to link against.
12684 LIBLZMA_HAS_AUTO_DECODER
12686 True if lzma_auto_decoder() is found (required).
12687 LIBLZMA_HAS_EASY_ENCODER
12689 True if lzma_easy_encoder() is found (required).
12690 LIBLZMA_HAS_LZMA_PRESET
12692 True if lzma_lzma_preset() is found (required).
12693 LIBLZMA_VERSION_MAJOR
12695 The major version of lzma
12696 LIBLZMA_VERSION_MINOR
12698 The minor version of lzma
12699 LIBLZMA_VERSION_PATCH
12701 The patch version of lzma
12702 LIBLZMA_VERSION_STRING
12704 version number as a string (ex: "5.0.3")
12705 FindLibXml2
12707 Find the XML processing library (libxml2).
12708 IMPORTED Targets
12710 New in version 3.12.
12711 The following IMPORTED targets may be defined:
12714 LibXml2::LibXml2
12716 libxml2 library.
12717 LibXml2::xmllint
12719 New in version 3.17.
12720 xmllint command-line executable.
12723 Result variables
12725 This module will set the following variables in your project:
12726 LibXml2_FOUND
12728 true if libxml2 headers and libraries were found
12729 LIBXML2_INCLUDE_DIR
12731 the directory containing LibXml2 headers
12732 LIBXML2_INCLUDE_DIRS
12734 list of the include directories needed to use LibXml2
12735 LIBXML2_LIBRARIES
12737 LibXml2 libraries to be linked
12738 LIBXML2_DEFINITIONS
12740 the compiler switches required for using LibXml2
12741 LIBXML2_XMLLINT_EXECUTABLE
12743 path to the XML checking tool xmllint coming with LibXml2
12744 LIBXML2_VERSION_STRING
12746 the version of LibXml2 found (since CMake 2.8.8)
12747 Cache variables
12749 The following cache variables may also be set:
12750 LIBXML2_INCLUDE_DIR
12752 the directory containing LibXml2 headers
12753 LIBXML2_LIBRARY
12755 path to the LibXml2 library
12756 FindLibXslt
12758 Find the XSL Transformations, Extensible Stylesheet Language Transfor‐
12759 mations (XSLT) library (LibXslt)
12760 IMPORTED Targets
12762 New in version 3.18.
12763 The following IMPORTED targets may be defined:
12766 LibXslt::LibXslt
12768 If the libxslt library has been found
12769 LibXslt::LibExslt
12771 If the libexslt library has been found
12772 LibXslt::xsltproc
12774 If the xsltproc command-line executable has been found
12775 Result variables
12777 This module will set the following variables in your project:
12778 LIBXSLT_FOUND - system has LibXslt LIBXSLT_INCLUDE_DIR - the LibXslt
12779 include directory LIBXSLT_LIBRARIES - Link these to LibXslt
12780 LIBXSLT_DEFINITIONS - Compiler switches required for using LibXslt
12781 LIBXSLT_VERSION_STRING - version of LibXslt found (since CMake
12782 2.8.8)
12783 Additionally, the following two variables are set (but not required for
12785 using xslt):
12786 LIBXSLT_EXSLT_INCLUDE_DIR
12788 New in version 3.18: The include directory for exslt.
12789 LIBXSLT_EXSLT_LIBRARIES
12792 Link to these if you need to link against the exslt library.
12793 LIBXSLT_XSLTPROC_EXECUTABLE
12795 Contains the full path to the xsltproc executable if found.
12796 FindLTTngUST
12798 New in version 3.6.
12799 Find Linux Trace Toolkit Next Generation (LTTng-UST) library.
12802 Imported target
12804 This module defines the following IMPORTED target:
12805 LTTng::UST
12807 The LTTng-UST library, if found
12808 Result variables
12810 This module sets the following
12811 LTTNGUST_FOUND
12813 TRUE if system has LTTng-UST
12814 LTTNGUST_INCLUDE_DIRS
12816 The LTTng-UST include directories
12817 LTTNGUST_LIBRARIES
12819 The libraries needed to use LTTng-UST
12820 LTTNGUST_VERSION_STRING
12822 The LTTng-UST version
12823 LTTNGUST_HAS_TRACEF
12825 TRUE if the tracef() API is available in the system's LTTng-UST
12826 LTTNGUST_HAS_TRACELOG
12828 TRUE if the tracelog() API is available in the system's LT‐
12829 Tng-UST
12830 FindLua
12832 Locate Lua library.
12833 New in version 3.18: Support for Lua 5.4.
12835 This module defines:
12838 ::
12840 LUA_FOUND - if false, do not try to link to Lua LUA_LI‐
12841 BRARIES - both lua and lualib LUA_INCLUDE_DIR - where to
12842 find lua.h LUA_VERSION_STRING - the version of Lua found LUA_VER‐
12843 SION_MAJOR - the major version of Lua LUA_VERSION_MINOR - the mi‐
12844 nor version of Lua LUA_VERSION_PATCH - the patch version of Lua
12845 Note that the expected include convention is
12847 #include "lua.h"
12849 and not
12851 #include <lua/lua.h>
12853 This is because, the lua location is not standardized and may exist in
12855 locations other than lua/
12856 FindLua50
12858 Locate Lua library. This module defines:
12859 ::
12861 LUA50_FOUND, if false, do not try to link to Lua LUA_LIBRARIES, both
12862 lua and lualib LUA_INCLUDE_DIR, where to find lua.h and lualib.h
12863 (and probably lauxlib.h)
12864 Note that the expected include convention is
12866 #include "lua.h"
12868 and not
12870 #include <lua/lua.h>
12872 This is because, the lua location is not standardized and may exist in
12874 locations other than lua/
12875 FindLua51
12877 Locate Lua library. This module defines:
12878 ::
12880 LUA51_FOUND, if false, do not try to link to Lua LUA_LIBRARIES
12881 LUA_INCLUDE_DIR, where to find lua.h LUA_VERSION_STRING, the version
12882 of Lua found (since CMake 2.8.8)
12883 Note that the expected include convention is
12885 #include "lua.h"
12887 and not
12889 #include <lua/lua.h>
12891 This is because, the lua location is not standardized and may exist in
12893 locations other than lua/
12894 FindMatlab
12896 Finds Matlab or Matlab Compiler Runtime (MCR) and provides Matlab
12897 tools, libraries and compilers to CMake.
12898 This package primary purpose is to find the libraries associated with
12900 Matlab or the MCR in order to be able to build Matlab extensions (mex
12901 files). It can also be used:
12902 • to run specific commands in Matlab in case Matlab is available
12904 • for declaring Matlab unit test
12906 • to retrieve various information from Matlab (mex extensions, versions
12908 and release queries, ...)
12909 New in version 3.12: Added Matlab Compiler Runtime (MCR) support.
12911 The module supports the following components:
12914 • ENG_LIBRARY and MAT_LIBRARY: respectively the ENG and MAT libraries
12916 of Matlab
12917 • MAIN_PROGRAM the Matlab binary program. Note that this component is
12919 not available on the MCR version, and will yield an error if the MCR
12920 is found instead of the regular Matlab installation.
12921 • MEX_COMPILER the MEX compiler.
12923 • MCC_COMPILER the MCC compiler, included with the Matlab Compiler
12925 add-on.
12926 • SIMULINK the Simulink environment.
12928 New in version 3.7: Added the MAT_LIBRARY component.
12930 New in version 3.13: Added the ENGINE_LIBRARY, DATAARRAY_LIBRARY and
12933 MCC_COMPILER components.
12934 Changed in version 3.14: Removed the MX_LIBRARY, ENGINE_LIBRARY and
12937 DATAARRAY_LIBRARY components. These libraries are found uncondition‐
12938 ally.
12939 NOTE:
12942 The version given to the find_package() directive is the Matlab ver‐
12943 sion, which should not be confused with the Matlab release name (eg.
12944 R2014). The matlab_get_version_from_release_name() and
12945 matlab_get_release_name_from_version() provide a mapping between the
12946 release name and the version.
12947 The variable Matlab_ROOT_DIR may be specified in order to give the path
12949 of the desired Matlab version. Otherwise, the behaviour is platform
12950 specific:
12951 • Windows: The installed versions of Matlab/MCR are retrieved from the
12953 Windows registry
12954 • OS X: The installed versions of Matlab/MCR are given by the MATLAB
12956 default installation paths in /Application. If no such application is
12957 found, it falls back to the one that might be accessible from the
12958 PATH.
12959 • Unix: The desired Matlab should be accessible from the PATH. This
12961 does not work for MCR installation and Matlab_ROOT_DIR should be
12962 specified on this platform.
12963 Additional information is provided when MATLAB_FIND_DEBUG is set. When
12965 a Matlab/MCR installation is found automatically and the MATLAB_VERSION
12966 is not given, the version is queried from Matlab directly (on Windows
12967 this may pop up a Matlab window) or from the MCR installation.
12968 The mapping of the release names and the version of Matlab is performed
12970 by defining pairs (name, version). The variable
12971 MATLAB_ADDITIONAL_VERSIONS may be provided before the call to the
12972 find_package() in order to handle additional versions.
12973 A Matlab scripts can be added to the set of tests using the
12975 matlab_add_unit_test(). By default, the Matlab unit test framework will
12976 be used (>= 2013a) to run this script, but regular .m files returning
12977 an exit code can be used as well (0 indicating a success).
12978 Module Input Variables
12980 Users or projects may set the following variables to configure the mod‐
12981 ule behaviour:
12982 Matlab_ROOT_DIR
12984 the root of the Matlab installation.
12985 MATLAB_FIND_DEBUG
12987 outputs debug information
12988 MATLAB_ADDITIONAL_VERSIONS
12990 additional versions of Matlab for the automatic retrieval of the
12991 installed versions.
12992 Variables defined by the module
12994 Result variables
12995 Matlab_FOUND
12996 TRUE if the Matlab installation is found, FALSE otherwise. All
12997 variable below are defined if Matlab is found.
12998 Matlab_ROOT_DIR
13000 the final root of the Matlab installation determined by the
13001 FindMatlab module.
13002 Matlab_MAIN_PROGRAM
13004 the Matlab binary program. Available only if the component
13005 MAIN_PROGRAM is given in the find_package() directive.
13006 Matlab_INCLUDE_DIRS
13008 the path of the Matlab libraries headers
13009 Matlab_MEX_LIBRARY
13011 library for mex, always available.
13012 Matlab_MX_LIBRARY
13014 mx library of Matlab (arrays), always available.
13015 Matlab_ENG_LIBRARY
13017 Matlab engine library. Available only if the component ENG_LI‐
13018 BRARY is requested.
13019 Matlab_MAT_LIBRARY
13021 Matlab matrix library. Available only if the component MAT_LI‐
13022 BRARY is requested.
13023 Matlab_ENGINE_LIBRARY
13025 New in version 3.13.
13026 Matlab C++ engine library, always available for R2018a and
13029 newer.
13030 Matlab_DATAARRAY_LIBRARY
13032 New in version 3.13.
13033 Matlab C++ data array library, always available for R2018a and
13036 newer.
13037 Matlab_LIBRARIES
13039 the whole set of libraries of Matlab
13040 Matlab_MEX_COMPILER
13042 the mex compiler of Matlab. Currently not used. Available only
13043 if the component MEX_COMPILER is requested.
13044 Matlab_MCC_COMPILER
13046 New in version 3.13.
13047 the mcc compiler of Matlab. Included with the Matlab Compiler
13050 add-on. Available only if the component MCC_COMPILER is re‐
13051 quested.
13052 Cached variables
13054 Matlab_MEX_EXTENSION
13055 the extension of the mex files for the current platform (given
13056 by Matlab).
13057 Matlab_ROOT_DIR
13059 the location of the root of the Matlab installation found. If
13060 this value is changed by the user, the result variables are re‐
13061 computed.
13062 Provided macros
13064 matlab_get_version_from_release_name()
13065 returns the version from the release name
13066 matlab_get_release_name_from_version()
13068 returns the release name from the Matlab version
13069 Provided functions
13071 matlab_add_mex()
13072 adds a target compiling a MEX file.
13073 matlab_add_unit_test()
13075 adds a Matlab unit test file as a test to the project.
13076 matlab_extract_all_installed_versions_from_registry()
13078 parses the registry for all Matlab versions. Available on Win‐
13079 dows only. The part of the registry parsed is dependent on the
13080 host processor
13081 matlab_get_all_valid_matlab_roots_from_registry()
13083 returns all the possible Matlab or MCR paths, according to a
13084 previously given list. Only the existing/accessible paths are
13085 kept. This is mainly useful for the searching all possible Mat‐
13086 lab installation.
13087 matlab_get_mex_suffix()
13089 returns the suffix to be used for the mex files (platform/archi‐
13090 tecture dependent)
13091 matlab_get_version_from_matlab_run()
13093 returns the version of Matlab/MCR, given the full directory of
13094 the Matlab/MCR installation path.
13095 Known issues
13097 Symbol clash in a MEX target
13098 By default, every symbols inside a MEX file defined with the
13099 command matlab_add_mex() have hidden visibility, except for the
13100 entry point. This is the default behaviour of the MEX compiler,
13101 which lowers the risk of symbol collision between the libraries
13102 shipped with Matlab, and the libraries to which the MEX file is
13103 linking to. This is also the default on Windows platforms.
13104 However, this is not sufficient in certain case, where for in‐
13106 stance your MEX file is linking against libraries that are al‐
13107 ready loaded by Matlab, even if those libraries have different
13108 SONAMES. A possible solution is to hide the symbols of the li‐
13109 braries to which the MEX target is linking to. This can be
13110 achieved in GNU GCC compilers with the linker option -Wl,--ex‐
13111 clude-libs,ALL.
13112 Tests using GPU resources
13114 in case your MEX file is using the GPU and in order to be able
13115 to run unit tests on this MEX file, the GPU resources should be
13116 properly released by Matlab. A possible solution is to make Mat‐
13117 lab aware of the use of the GPU resources in the session, which
13118 can be performed by a command such as D = gpuDevice() at the be‐
13119 ginning of the test script (or via a fixture).
13120 Reference
13122 Matlab_ROOT_DIR
13123 The root folder of the Matlab installation. If set before the
13124 call to find_package(), the module will look for the components
13125 in that path. If not set, then an automatic search of Matlab
13126 will be performed. If set, it should point to a valid version of
13127 Matlab.
13128 MATLAB_FIND_DEBUG
13130 If set, the lookup of Matlab and the intermediate configuration
13131 steps are outputted to the console.
13132 MATLAB_ADDITIONAL_VERSIONS
13134 If set, specifies additional versions of Matlab that may be
13135 looked for. The variable should be a list of strings, organised
13136 by pairs of release name and versions, such as follows:
13137 set(MATLAB_ADDITIONAL_VERSIONS
13139 "release_name1=corresponding_version1"
13140 "release_name2=corresponding_version2"
13141 ...
13142 )
13143 Example:
13145 set(MATLAB_ADDITIONAL_VERSIONS
13147 "R2013b=8.2"
13148 "R2013a=8.1"
13149 "R2012b=8.0")
13150 The order of entries in this list matters when several versions
13152 of Matlab are installed. The priority is set according to the
13153 ordering in this list.
13154 matlab_get_version_from_release_name
13156 Returns the version of Matlab (17.58) from a release name
13157 (R2017k)
13158 matlab_get_release_name_from_version
13160 Returns the release name (R2017k) from the version of Matlab
13161 (17.58)
13162 matlab_extract_all_installed_versions_from_registry
13164 This function parses the registry and founds the Matlab versions
13165 that are installed. The found versions are returned in mat‐
13166 lab_versions. Set win64 to TRUE if the 64 bit version of Matlab
13167 should be looked for The returned list contains all versions un‐
13168 der HKLM\\SOFTWARE\\Mathworks\\MATLAB and HKLM\\SOFTWARE\\Math‐
13169 works\\MATLAB Runtime or an empty list in case an error occurred
13170 (or nothing found).
13171 NOTE:
13173 Only the versions are provided. No check is made over the ex‐
13174 istence of the installation referenced in the registry,
13175 matlab_get_all_valid_matlab_roots_from_registry
13177 Populates the Matlab root with valid versions of Matlab or Mat‐
13178 lab Runtime (MCR). The returned matlab_roots is organized in
13179 triplets (type,version_number,matlab_root_path), where type in‐
13180 dicates either MATLAB or MCR.
13181 matlab_get_all_valid_matlab_roots_from_registry(
13183 matlab_versions
13184 matlab_roots)
13185 matlab_versions
13187 the versions of each of the Matlab or MCR installations
13188 matlab_roots
13190 the location of each of the Matlab or MCR installations
13191 matlab_get_mex_suffix
13193 Returns the extension of the mex files (the suffixes). This
13194 function should not be called before the appropriate Matlab root
13195 has been found.
13196 matlab_get_mex_suffix(
13198 matlab_root
13199 mex_suffix)
13200 matlab_root
13202 the root of the Matlab/MCR installation
13203 mex_suffix
13205 the variable name in which the suffix will be returned.
13206 matlab_get_version_from_matlab_run
13208 This function runs Matlab program specified on arguments and ex‐
13209 tracts its version. If the path provided for the Matlab instal‐
13210 lation points to an MCR installation, the version is extracted
13211 from the installed files.
13212 matlab_get_version_from_matlab_run(
13214 matlab_binary_path
13215 matlab_list_versions)
13216 matlab_binary_path
13218 the location of the matlab binary executable
13219 matlab_list_versions
13221 the version extracted from Matlab
13222 matlab_add_unit_test
13224 Adds a Matlab unit test to the test set of cmake/ctest. This
13225 command requires the component MAIN_PROGRAM and hence is not
13226 available for an MCR installation.
13227 The unit test uses the Matlab unittest framework (default,
13229 available starting Matlab 2013b+) except if the option
13230 NO_UNITTEST_FRAMEWORK is given.
13231 The function expects one Matlab test script file to be given.
13233 In the case NO_UNITTEST_FRAMEWORK is given, the unittest script
13234 file should contain the script to be run, plus an exit command
13235 with the exit value. This exit value will be passed to the ctest
13236 framework (0 success, non 0 failure). Additional arguments ac‐
13237 cepted by add_test() can be passed through TEST_ARGS (eg. CON‐
13238 FIGURATION <config> ...).
13239 matlab_add_unit_test(
13241 NAME <name>
13242 UNITTEST_FILE matlab_file_containing_unittest.m
13243 [CUSTOM_TEST_COMMAND matlab_command_to_run_as_test]
13244 [UNITTEST_PRECOMMAND matlab_command_to_run]
13245 [TIMEOUT timeout]
13246 [ADDITIONAL_PATH path1 [path2 ...]]
13247 [MATLAB_ADDITIONAL_STARTUP_OPTIONS option1 [option2 ...]]
13248 [TEST_ARGS arg1 [arg2 ...]]
13249 [NO_UNITTEST_FRAMEWORK]
13250 )
13251 The function arguments are:
13253 NAME name of the unittest in ctest.
13255 UNITTEST_FILE
13257 the matlab unittest file. Its path will be automatically
13258 added to the Matlab path.
13259 CUSTOM_TEST_COMMAND
13261 Matlab script command to run as the test. If this is not
13262 set, then the following is run: runtests('mat‐
13263 lab_file_name'), exit(max([ans(1,:).Failed])) where mat‐
13264 lab_file_name is the UNITTEST_FILE without the extension.
13265 UNITTEST_PRECOMMAND
13267 Matlab script command to be ran before the file contain‐
13268 ing the test (eg. GPU device initialisation based on
13269 CMake variables).
13270 TIMEOUT
13272 the test timeout in seconds. Defaults to 180 seconds as
13273 the Matlab unit test may hang.
13274 ADDITIONAL_PATH
13276 a list of paths to add to the Matlab path prior to run‐
13277 ning the unit test.
13278 MATLAB_ADDITIONAL_STARTUP_OPTIONS
13280 a list of additional option in order to run Matlab from
13281 the command line. -nosplash -nodesktop -nodisplay are
13282 always added.
13283 TEST_ARGS
13285 Additional options provided to the add_test command.
13286 These options are added to the default options (eg. "CON‐
13287 FIGURATIONS Release")
13288 NO_UNITTEST_FRAMEWORK
13290 when set, indicates that the test should not use the
13291 unittest framework of Matlab (available for versions >=
13292 R2013a).
13293 WORKING_DIRECTORY
13295 This will be the working directory for the test. If spec‐
13296 ified it will also be the output directory used for the
13297 log file of the test run. If not specified the temporary
13298 directory ${CMAKE_BINARY_DIR}/Matlab will be used as the
13299 working directory and the log location.
13300 matlab_add_mex
13302 Adds a Matlab MEX target. This commands compiles the given
13303 sources with the current tool-chain in order to produce a MEX
13304 file. The final name of the produced output may be specified, as
13305 well as additional link libraries, and a documentation entry for
13306 the MEX file. Remaining arguments of the call are passed to the
13307 add_library() or add_executable() command.
13308 matlab_add_mex(
13310 NAME <name>
13311 [EXECUTABLE | MODULE | SHARED]
13312 SRC src1 [src2 ...]
13313 [OUTPUT_NAME output_name]
13314 [DOCUMENTATION file.txt]
13315 [LINK_TO target1 target2 ...]
13316 [R2017b | R2018a]
13317 [EXCLUDE_FROM_ALL]
13318 [...]
13319 )
13320 NAME name of the target.
13322 SRC list of source files.
13324 LINK_TO
13326 a list of additional link dependencies. The target links
13327 to libmex and libmx by default.
13328 OUTPUT_NAME
13330 if given, overrides the default name. The default name is
13331 the name of the target without any prefix and with Mat‐
13332 lab_MEX_EXTENSION suffix.
13333 DOCUMENTATION
13335 if given, the file file.txt will be considered as being
13336 the documentation file for the MEX file. This file is
13337 copied into the same folder without any processing, with
13338 the same name as the final mex file, and with extension
13339 .m. In that case, typing help <name> in Matlab prints the
13340 documentation contained in this file.
13341 R2017b or R2018a
13343 New in version 3.14.
13344 May be given to specify the version of the C API to use:
13347 R2017b specifies the traditional (separate complex) C
13348 API, and corresponds to the -R2017b flag for the mex com‐
13349 mand. R2018a specifies the new interleaved complex C API,
13350 and corresponds to the -R2018a flag for the mex command.
13351 Ignored if MATLAB version prior to R2018a. Defaults to
13352 R2017b.
13353 MODULE or SHARED
13355 New in version 3.7.
13356 May be given to specify the type of library to be cre‐
13359 ated.
13360 EXECUTABLE
13362 New in version 3.7.
13363 May be given to create an executable instead of a li‐
13366 brary. If no type is given explicitly, the type is
13367 SHARED.
13368 EXCLUDE_FROM_ALL
13370 This option has the same meaning as for EXCLUDE_FROM_ALL
13371 and is forwarded to add_library() or add_executable()
13372 commands.
13373 The documentation file is not processed and should be in the
13375 following format:
13376 % This is the documentation
13378 function ret = mex_target_output_name(input1)
13379 FindMFC
13381 Find Microsoft Foundation Class Library (MFC) on Windows
13382 Find the native MFC - i.e. decide if an application can link to the
13384 MFC libraries.
13385 MFC_FOUND - Was MFC support found
13387 You don't need to include anything or link anything to use it.
13389 FindMotif
13391 Try to find Motif (or lesstif)
13392 Once done this will define:
13394 MOTIF_FOUND - system has MOTIF
13396 MOTIF_INCLUDE_DIR - include paths to use Motif
13397 MOTIF_LIBRARIES - Link these to use Motif
13398 FindMPEG
13400 Find the native MPEG includes and library
13401 This module defines
13403 MPEG_INCLUDE_DIR, where to find MPEG.h, etc.
13405 MPEG_LIBRARIES, the libraries required to use MPEG.
13406 MPEG_FOUND, If false, do not try to use MPEG.
13407 also defined, but not for general use are
13409 MPEG_mpeg2_LIBRARY, where to find the MPEG library.
13411 MPEG_vo_LIBRARY, where to find the vo library.
13412 FindMPEG2
13414 Find the native MPEG2 includes and library
13415 This module defines
13417 MPEG2_INCLUDE_DIR, path to mpeg2dec/mpeg2.h, etc.
13419 MPEG2_LIBRARIES, the libraries required to use MPEG2.
13420 MPEG2_FOUND, If false, do not try to use MPEG2.
13421 also defined, but not for general use are
13423 MPEG2_mpeg2_LIBRARY, where to find the MPEG2 library.
13425 MPEG2_vo_LIBRARY, where to find the vo library.
13426 FindMPI
13428 Find a Message Passing Interface (MPI) implementation.
13429 The Message Passing Interface (MPI) is a library used to write
13431 high-performance distributed-memory parallel applications, and is typi‐
13432 cally deployed on a cluster. MPI is a standard interface (defined by
13433 the MPI forum) for which many implementations are available.
13434 New in version 3.10: Major overhaul of the module: many new variables,
13436 per-language components, support for a wider variety of runtimes.
13437 Variables for using MPI
13440 The module exposes the components C, CXX, MPICXX and Fortran. Each of
13441 these controls the various MPI languages to search for. The difference
13442 between CXX and MPICXX is that CXX refers to the MPI C API being usable
13443 from C++, whereas MPICXX refers to the MPI-2 C++ API that was removed
13444 again in MPI-3.
13445 Depending on the enabled components the following variables will be
13447 set:
13448 MPI_FOUND
13450 Variable indicating that MPI settings for all requested lan‐
13451 guages have been found. If no components are specified, this is
13452 true if MPI settings for all enabled languages were detected.
13453 Note that the MPICXX component does not affect this variable.
13454 MPI_VERSION
13456 Minimal version of MPI detected among the requested languages,
13457 or all enabled languages if no components were specified.
13458 This module will set the following variables per language in your
13460 project, where <lang> is one of C, CXX, or Fortran:
13461 MPI_<lang>_FOUND
13463 Variable indicating the MPI settings for <lang> were found and
13464 that simple MPI test programs compile with the provided set‐
13465 tings.
13466 MPI_<lang>_COMPILER
13468 MPI compiler for <lang> if such a program exists.
13469 MPI_<lang>_COMPILE_OPTIONS
13471 Compilation options for MPI programs in <lang>, given as a
13472 ;-list.
13473 MPI_<lang>_COMPILE_DEFINITIONS
13475 Compilation definitions for MPI programs in <lang>, given as a
13476 ;-list.
13477 MPI_<lang>_INCLUDE_DIRS
13479 Include path(s) for MPI header.
13480 MPI_<lang>_LINK_FLAGS
13482 Linker flags for MPI programs.
13483 MPI_<lang>_LIBRARIES
13485 All libraries to link MPI programs against.
13486 New in version 3.9: Additionally, the following IMPORTED targets are
13488 defined:
13489 MPI::MPI_<lang>
13492 Target for using MPI from <lang>.
13493 The following variables indicating which bindings are present will be
13495 defined:
13496 MPI_MPICXX_FOUND
13498 Variable indicating whether the MPI-2 C++ bindings are present
13499 (introduced in MPI-2, removed with MPI-3).
13500 MPI_Fortran_HAVE_F77_HEADER
13502 True if the Fortran 77 header mpif.h is available.
13503 MPI_Fortran_HAVE_F90_MODULE
13505 True if the Fortran 90 module mpi can be used for accessing MPI
13506 (MPI-2 and higher only).
13507 MPI_Fortran_HAVE_F08_MODULE
13509 True if the Fortran 2008 mpi_f08 is available to MPI programs
13510 (MPI-3 and higher only).
13511 If possible, the MPI version will be determined by this module. The fa‐
13513 cilities to detect the MPI version were introduced with MPI-1.2, and
13514 therefore cannot be found for older MPI versions.
13515 MPI_<lang>_VERSION_MAJOR
13517 Major version of MPI implemented for <lang> by the MPI distribu‐
13518 tion.
13519 MPI_<lang>_VERSION_MINOR
13521 Minor version of MPI implemented for <lang> by the MPI distribu‐
13522 tion.
13523 MPI_<lang>_VERSION
13525 MPI version implemented for <lang> by the MPI distribution.
13526 Note that there's no variable for the C bindings being accessible
13528 through mpi.h, since the MPI standards always have required this bind‐
13529 ing to work in both C and C++ code.
13530 For running MPI programs, the module sets the following variables
13532 MPIEXEC_EXECUTABLE
13534 Executable for running MPI programs, if such exists.
13535 MPIEXEC_NUMPROC_FLAG
13537 Flag to pass to mpiexec before giving it the number of proces‐
13538 sors to run on.
13539 MPIEXEC_MAX_NUMPROCS
13541 Number of MPI processors to utilize. Defaults to the number of
13542 processors detected on the host system.
13543 MPIEXEC_PREFLAGS
13545 Flags to pass to mpiexec directly before the executable to run.
13546 MPIEXEC_POSTFLAGS
13548 Flags to pass to mpiexec after other flags.
13549 Variables for locating MPI
13551 This module performs a four step search for an MPI implementation:
13552 1. Search for MPIEXEC_EXECUTABLE and, if found, use its base directory.
13554 2. Check if the compiler has MPI support built-in. This is the case if
13556 the user passed a compiler wrapper as CMAKE_<LANG>_COMPILER or if
13557 they're on a Cray system.
13558 3. Attempt to find an MPI compiler wrapper and determine the compiler
13560 information from it.
13561 4. Try to find an MPI implementation that does not ship such a wrapper
13563 by guessing settings. Currently, only Microsoft MPI and MPICH2 on
13564 Windows are supported.
13565 For controlling the MPIEXEC_EXECUTABLE step, the following variables
13567 may be set:
13568 MPIEXEC_EXECUTABLE
13570 Manually specify the location of mpiexec.
13571 MPI_HOME
13573 Specify the base directory of the MPI installation.
13574 ENV{MPI_HOME}
13576 Environment variable to specify the base directory of the MPI
13577 installation.
13578 ENV{I_MPI_ROOT}
13580 Environment variable to specify the base directory of the MPI
13581 installation.
13582 For controlling the compiler wrapper step, the following variables may
13584 be set:
13585 MPI_<lang>_COMPILER
13587 Search for the specified compiler wrapper and use it.
13588 MPI_<lang>_COMPILER_FLAGS
13590 Flags to pass to the MPI compiler wrapper during interrogation.
13591 Some compiler wrappers support linking debug or tracing li‐
13592 braries if a specific flag is passed and this variable may be
13593 used to obtain them.
13594 MPI_COMPILER_FLAGS
13596 Used to initialize MPI_<lang>_COMPILER_FLAGS if no language spe‐
13597 cific flag has been given. Empty by default.
13598 MPI_EXECUTABLE_SUFFIX
13600 A suffix which is appended to all names that are being looked
13601 for. For instance you may set this to .mpich or .openmpi to pre‐
13602 fer the one or the other on Debian and its derivatives.
13603 In order to control the guessing step, the following variable may be
13605 set:
13606 MPI_GUESS_LIBRARY_NAME
13608 Valid values are MSMPI and MPICH2. If set, only the given li‐
13609 brary will be searched for. By default, MSMPI will be preferred
13610 over MPICH2 if both are available. This also sets MPI_SKIP_COM‐
13611 PILER_WRAPPER to true, which may be overridden.
13612 Each of the search steps may be skipped with the following control
13614 variables:
13615 MPI_ASSUME_NO_BUILTIN_MPI
13617 If true, the module assumes that the compiler itself does not
13618 provide an MPI implementation and skips to step 2.
13619 MPI_SKIP_COMPILER_WRAPPER
13621 If true, no compiler wrapper will be searched for.
13622 MPI_SKIP_GUESSING
13624 If true, the guessing step will be skipped.
13625 Additionally, the following control variable is available to change
13627 search behavior:
13628 MPI_CXX_SKIP_MPICXX
13630 Add some definitions that will disable the MPI-2 C++ bindings.
13631 Currently supported are MPICH, Open MPI, Platform MPI and deriv‐
13632 atives thereof, for example MVAPICH or Intel MPI.
13633 If the find procedure fails for a variable MPI_<lang>_WORKS, then the
13635 settings detected by or passed to the module did not work and even a
13636 simple MPI test program failed to compile.
13637 If all of these parameters were not sufficient to find the right MPI
13639 implementation, a user may disable the entire autodetection process by
13640 specifying both a list of libraries in MPI_<lang>_LIBRARIES and a list
13641 of include directories in MPI_<lang>_ADDITIONAL_INCLUDE_DIRS. Any
13642 other variable may be set in addition to these two. The module will
13643 then validate the MPI settings and store the settings in the cache.
13644 Cache variables for MPI
13646 The variable MPI_<lang>_INCLUDE_DIRS will be assembled from the follow‐
13647 ing variables. For C and CXX:
13648 MPI_<lang>_HEADER_DIR
13650 Location of the mpi.h header on disk.
13651 For Fortran:
13653 MPI_Fortran_F77_HEADER_DIR
13655 Location of the Fortran 77 header mpif.h, if it exists.
13656 MPI_Fortran_MODULE_DIR
13658 Location of the mpi or mpi_f08 modules, if available.
13659 For all languages the following variables are additionally considered:
13661 MPI_<lang>_ADDITIONAL_INCLUDE_DIRS
13663 A ;-list of paths needed in addition to the normal include di‐
13664 rectories.
13665 MPI_<include_name>_INCLUDE_DIR
13667 Path variables for include folders referred to by <in‐
13668 clude_name>.
13669 MPI_<lang>_ADDITIONAL_INCLUDE_VARS
13671 A ;-list of <include_name> that will be added to the include lo‐
13672 cations of <lang>.
13673 The variable MPI_<lang>_LIBRARIES will be assembled from the following
13675 variables:
13676 MPI_<lib_name>_LIBRARY
13678 The location of a library called <lib_name> for use with MPI.
13679 MPI_<lang>_LIB_NAMES
13681 A ;-list of <lib_name> that will be added to the include loca‐
13682 tions of <lang>.
13683 Usage of mpiexec
13685 When using MPIEXEC_EXECUTABLE to execute MPI applications, you should
13686 typically use all of the MPIEXEC_EXECUTABLE flags as follows:
13687 ${MPIEXEC_EXECUTABLE} ${MPIEXEC_NUMPROC_FLAG} ${MPIEXEC_MAX_NUMPROCS}
13689 ${MPIEXEC_PREFLAGS} EXECUTABLE ${MPIEXEC_POSTFLAGS} ARGS
13690 where EXECUTABLE is the MPI program, and ARGS are the arguments to pass
13692 to the MPI program.
13693 Advanced variables for using MPI
13695 The module can perform some advanced feature detections upon explicit
13696 request.
13697 Important notice: The following checks cannot be performed without exe‐
13699 cuting an MPI test program. Consider the special considerations for
13700 the behavior of try_run() during cross compilation. Moreover, running
13701 an MPI program can cause additional issues, like a firewall notifica‐
13702 tion on some systems. You should only enable these detections if you
13703 absolutely need the information.
13704 If the following variables are set to true, the respective search will
13706 be performed:
13707 MPI_DETERMINE_Fortran_CAPABILITIES
13709 Determine for all available Fortran bindings what the values of
13710 MPI_SUBARRAYS_SUPPORTED and MPI_ASYNC_PROTECTS_NONBLOCKING are
13711 and make their values available as MPI_Fortran_<binding>_SUBAR‐
13712 RAYS and MPI_Fortran_<binding>_ASYNCPROT, where <binding> is one
13713 of F77_HEADER, F90_MODULE and F08_MODULE.
13714 MPI_DETERMINE_LIBRARY_VERSION
13716 For each language, find the output of MPI_Get_library_version
13717 and make it available as MPI_<lang>_LIBRARY_VERSION_STRING.
13718 This information is usually tied to the runtime component of an
13719 MPI implementation and might differ depending on <lang>. Note
13720 that the return value is entirely implementation defined. This
13721 information might be used to identify the MPI vendor and for ex‐
13722 ample pick the correct one of multiple third party binaries that
13723 matches the MPI vendor.
13724 Backward Compatibility
13726 Deprecated since version 3.10.
13727 For backward compatibility with older versions of FindMPI, these vari‐
13730 ables are set:
13731 MPI_COMPILER MPI_LIBRARY MPI_EXTRA_LIBRARY
13733 MPI_COMPILE_FLAGS MPI_INCLUDE_PATH MPI_LINK_FLAGS
13734 MPI_LIBRARIES
13735 In new projects, please use the MPI_<lang>_XXX equivalents. Addition‐
13737 ally, the following variables are deprecated:
13738 MPI_<lang>_COMPILE_FLAGS
13740 Use MPI_<lang>_COMPILE_OPTIONS and MPI_<lang>_COMPILE_DEFINI‐
13741 TIONS instead.
13742 MPI_<lang>_INCLUDE_PATH
13744 For consumption use MPI_<lang>_INCLUDE_DIRS and for specifying
13745 folders use MPI_<lang>_ADDITIONAL_INCLUDE_DIRS instead.
13746 MPIEXEC
13748 Use MPIEXEC_EXECUTABLE instead.
13749 FindODBC
13751 New in version 3.12.
13752 Find an Open Database Connectivity (ODBC) include directory and li‐
13755 brary.
13756 On Windows, when building with Visual Studio, this module assumes the
13758 ODBC library is provided by the available Windows SDK.
13759 On Unix, this module allows to search for ODBC library provided by
13761 unixODBC or iODBC implementations of ODBC API. This module reads hint
13762 about location of the config program:
13763 ODBC_CONFIG
13765 Location of odbc_config or iodbc-config program
13766 Otherwise, this module tries to find the config program, first from
13768 unixODBC, then from iODBC. If no config program found, this module
13769 searches for ODBC header and library in list of known locations.
13770 Imported targets
13772 This module defines the following IMPORTED targets:
13773 ODBC::ODBC
13775 Imported target for using the ODBC library, if found.
13776 Result variables
13778 ODBC_FOUND
13779 Set to true if ODBC library found, otherwise false or undefined.
13780 ODBC_INCLUDE_DIRS
13782 Paths to include directories listed in one variable for use by
13783 ODBC client. May be empty on Windows, where the include direc‐
13784 tory corresponding to the expected Windows SDK is already avail‐
13785 able in the compilation environment.
13786 ODBC_LIBRARIES
13788 Paths to libraries to linked against to use ODBC. May just a
13789 library name on Windows, where the library directory correspond‐
13790 ing to the expected Windows SDK is already available in the com‐
13791 pilation environment.
13792 ODBC_CONFIG
13794 Path to unixODBC or iODBC config program, if found or specified.
13795 Cache variables
13797 For users who wish to edit and control the module behavior, this module
13798 reads hints about search locations from the following variables:
13799 ODBC_INCLUDE_DIR
13801 Path to ODBC include directory with sql.h header.
13802 ODBC_LIBRARY
13804 Path to ODBC library to be linked.
13805 These variables should not be used directly by project code.
13807 Limitations
13809 On Windows, this module does not search for iODBC. On Unix, there is
13810 no way to prefer unixODBC over iODBC, or vice versa, other than provid‐
13811 ing the config program location using the ODBC_CONFIG. This module
13812 does not allow to search for a specific ODBC driver.
13813 FindOpenACC
13815 New in version 3.10.
13816 Detect OpenACC support by the compiler.
13819 This module can be used to detect OpenACC support in a compiler. If
13821 the compiler supports OpenACC, the flags required to compile with Ope‐
13822 nACC support are returned in variables for the different languages.
13823 Currently, only NVHPC, PGI, GNU and Cray compilers are supported.
13824 Imported Targets
13826 New in version 3.16.
13827 The module provides IMPORTED targets:
13830 OpenACC::OpenACC_<lang>
13832 Target for using OpenACC from <lang>.
13833 Variables
13835 This module will set the following variables per language in your
13836 project, where <lang> is one of C, CXX, or Fortran:
13837 OpenACC_<lang>_FOUND
13839 Variable indicating if OpenACC support for <lang> was detected.
13840 OpenACC_<lang>_FLAGS
13842 OpenACC compiler flags for <lang>, separated by spaces.
13843 OpenACC_<lang>_OPTIONS
13845 New in version 3.16.
13846 OpenACC compiler flags for <lang>, as a list. Suitable for usage
13849 with target_compile_options or target_link_options.
13850 The module will also try to provide the OpenACC version variables:
13852 OpenACC_<lang>_SPEC_DATE
13854 Date of the OpenACC specification implemented by the <lang> com‐
13855 piler.
13856 OpenACC_<lang>_VERSION_MAJOR
13858 Major version of OpenACC implemented by the <lang> compiler.
13859 OpenACC_<lang>_VERSION_MINOR
13861 Minor version of OpenACC implemented by the <lang> compiler.
13862 OpenACC_<lang>_VERSION
13864 OpenACC version implemented by the <lang> compiler.
13865 The specification date is formatted as given in the OpenACC standard:
13867 yyyymm where yyyy and mm represents the year and month of the OpenACC
13868 specification implemented by the <lang> compiler.
13869 Input Variables
13871 OpenACC_ACCEL_TARGET=<target> If set, will the correct target accelera‐
13872 tor flag set to the <target> will be returned with Ope‐
13873 nACC_<lang>_FLAGS.
13874 FindOpenAL
13876 Finds Open Audio Library (OpenAL).
13877 Projects using this module should use #include "al.h" to include the
13879 OpenAL header file, not #include <AL/al.h>. The reason for this is
13880 that the latter is not entirely portable. Windows/Creative Labs does
13881 not by default put their headers in AL/ and macOS uses the convention
13882 <OpenAL/al.h>.
13883 Hints
13885 Environment variable $OPENALDIR can be used to set the prefix of OpenAL
13886 installation to be found.
13887 By default on macOS, system framework is search first. In other words,
13889 OpenAL is searched in the following order:
13890 1. System framework: /System/Library/Frameworks, whose priority can be
13892 changed via setting the CMAKE_FIND_FRAMEWORK variable.
13893 2. Environment variable $OPENALDIR.
13895 3. System paths.
13897 4. User-compiled framework: ~/Library/Frameworks.
13899 5. Manually compiled framework: /Library/Frameworks.
13901 6. Add-on package: /opt.
13903 Result Variables
13905 This module defines the following variables:
13906 OPENAL_FOUND
13908 If false, do not try to link to OpenAL
13909 OPENAL_INCLUDE_DIR
13911 OpenAL include directory
13912 OPENAL_LIBRARY
13914 Path to the OpenAL library
13915 OPENAL_VERSION_STRING
13917 Human-readable string containing the version of OpenAL
13918 FindOpenCL
13920 New in version 3.1.
13921 Finds Open Computing Language (OpenCL)
13924 New in version 3.10: Detection of OpenCL 2.1 and 2.2.
13926 IMPORTED Targets
13929 New in version 3.7.
13930 This module defines IMPORTED target OpenCL::OpenCL, if OpenCL has been
13933 found.
13934 Result Variables
13936 This module defines the following variables:
13937 OpenCL_FOUND - True if OpenCL was found
13939 OpenCL_INCLUDE_DIRS - include directories for OpenCL
13940 OpenCL_LIBRARIES - link against this library to use OpenCL
13941 OpenCL_VERSION_STRING - Highest supported OpenCL version (eg. 1.2)
13942 OpenCL_VERSION_MAJOR - The major version of the OpenCL implementation
13943 OpenCL_VERSION_MINOR - The minor version of the OpenCL implementation
13944 The module will also define two cache variables:
13946 OpenCL_INCLUDE_DIR - the OpenCL include directory
13948 OpenCL_LIBRARY - the path to the OpenCL library
13949 FindOpenGL
13951 FindModule for OpenGL and OpenGL Utility Library (GLU).
13952 Changed in version 3.2: X11 is no longer added as a dependency on
13954 Unix/Linux systems.
13955 New in version 3.10: GLVND support on Linux. See the Linux-specific
13958 section below.
13959 Optional COMPONENTS
13962 New in version 3.10.
13963 This module respects several optional COMPONENTS: EGL, GLX, and OpenGL.
13966 There are corresponding import targets for each of these flags.
13967 IMPORTED Targets
13969 New in version 3.8.
13970 This module defines the IMPORTED targets:
13973 OpenGL::GL
13975 Defined to the platform-specific OpenGL libraries if the system
13976 has OpenGL.
13977 OpenGL::GLU
13979 Defined if the system has OpenGL Utility Library (GLU).
13980 New in version 3.10: Additionally, the following GLVND-specific library
13982 targets are defined:
13983 OpenGL::OpenGL
13986 Defined to libOpenGL if the system is GLVND-based.
13987 OpenGL::GLX
13989 Defined if the system has OpenGL Extension to the X Window Sys‐
13990 tem (GLX).
13991 OpenGL::EGL
13993 Defined if the system has EGL.
13994 Result Variables
13996 This module sets the following variables:
13997 OPENGL_FOUND
13999 True, if the system has OpenGL and all components are found.
14000 OPENGL_XMESA_FOUND
14002 True, if the system has XMESA.
14003 OPENGL_GLU_FOUND
14005 True, if the system has GLU.
14006 OpenGL_OpenGL_FOUND
14008 True, if the system has an OpenGL library.
14009 OpenGL_GLX_FOUND
14011 True, if the system has GLX.
14012 OpenGL_EGL_FOUND
14014 True, if the system has EGL.
14015 OPENGL_INCLUDE_DIR
14017 Path to the OpenGL include directory.
14018 OPENGL_EGL_INCLUDE_DIRS
14020 Path to the EGL include directory.
14021 OPENGL_LIBRARIES
14023 Paths to the OpenGL library, windowing system libraries, and GLU
14024 libraries. On Linux, this assumes GLX and is never correct for
14025 EGL-based targets. Clients are encouraged to use the OpenGL::*
14026 import targets instead.
14027 New in version 3.10: Variables for GLVND-specific libraries OpenGL, EGL
14029 and GLX.
14030 Cache variables
14033 The following cache variables may also be set:
14034 OPENGL_egl_LIBRARY
14036 Path to the EGL library.
14037 OPENGL_glu_LIBRARY
14039 Path to the GLU library.
14040 OPENGL_glx_LIBRARY
14042 Path to the GLVND 'GLX' library.
14043 OPENGL_opengl_LIBRARY
14045 Path to the GLVND 'OpenGL' library
14046 OPENGL_gl_LIBRARY
14048 Path to the OpenGL library. New code should prefer the
14049 OpenGL::* import targets.
14050 New in version 3.10: Variables for GLVND-specific libraries OpenGL, EGL
14052 and GLX.
14053 Linux-specific
14056 Some Linux systems utilize GLVND as a new ABI for OpenGL. GLVND sepa‐
14057 rates context libraries from OpenGL itself; OpenGL lives in "li‐
14058 bOpenGL", and contexts are defined in "libGLX" or "libEGL". GLVND is
14059 currently the only way to get OpenGL 3+ functionality via EGL in a man‐
14060 ner portable across vendors. Projects may use GLVND explicitly with
14061 target OpenGL::OpenGL and either OpenGL::GLX or OpenGL::EGL.
14062 Projects may use the OpenGL::GL target (or OPENGL_LIBRARIES variable)
14064 to use legacy GL interfaces. These will use the legacy GL library lo‐
14065 cated by OPENGL_gl_LIBRARY, if available. If OPENGL_gl_LIBRARY is
14066 empty or not found and GLVND is available, the OpenGL::GL target will
14067 use GLVND OpenGL::OpenGL and OpenGL::GLX (and the OPENGL_LIBRARIES
14068 variable will use the corresponding libraries). Thus, for
14069 non-EGL-based Linux targets, the OpenGL::GL target is most portable.
14070 A OpenGL_GL_PREFERENCE variable may be set to specify the preferred way
14072 to provide legacy GL interfaces in case multiple choices are available.
14073 The value may be one of:
14074 GLVND If the GLVND OpenGL and GLX libraries are available, prefer
14076 them. This forces OPENGL_gl_LIBRARY to be empty.
14077 Changed in version 3.11: This is the default, unless policy
14079 CMP0072 is set to OLD and no components are requeted (since com‐
14080 ponents correspond to GLVND libraries).
14081 LEGACY Prefer to use the legacy libGL library, if available.
14084 For EGL targets the client must rely on GLVND support on the user's
14086 system. Linking should use the OpenGL::OpenGL OpenGL::EGL targets.
14087 Using GLES* libraries is theoretically possible in place of
14088 OpenGL::OpenGL, but this module does not currently support that; con‐
14089 tributions welcome.
14090 OPENGL_egl_LIBRARY and OPENGL_EGL_INCLUDE_DIRS are defined in the case
14092 of GLVND. For non-GLVND Linux and other systems these are left unde‐
14093 fined.
14094 macOS-Specific
14096 On OSX FindOpenGL defaults to using the framework version of OpenGL.
14097 People will have to change the cache values of OPENGL_glu_LIBRARY and
14098 OPENGL_gl_LIBRARY to use OpenGL with X11 on OSX.
14099 FindOpenMP
14101 Finds Open Multi-Processing (OpenMP) support.
14102 This module can be used to detect OpenMP support in a compiler. If the
14104 compiler supports OpenMP, the flags required to compile with OpenMP
14105 support are returned in variables for the different languages. The
14106 variables may be empty if the compiler does not need a special flag to
14107 support OpenMP.
14108 New in version 3.5: Clang support.
14110 Variables
14113 New in version 3.10: The module exposes the components C, CXX, and For‐
14114 tran. Each of these controls the various languages to search OpenMP
14115 support for.
14116 Depending on the enabled components the following variables will be
14119 set:
14120 OpenMP_FOUND
14122 Variable indicating that OpenMP flags for all requested lan‐
14123 guages have been found. If no components are specified, this is
14124 true if OpenMP settings for all enabled languages were detected.
14125 OpenMP_VERSION
14127 Minimal version of the OpenMP standard detected among the re‐
14128 quested languages, or all enabled languages if no components
14129 were specified.
14130 This module will set the following variables per language in your
14132 project, where <lang> is one of C, CXX, or Fortran:
14133 OpenMP_<lang>_FOUND
14135 Variable indicating if OpenMP support for <lang> was detected.
14136 OpenMP_<lang>_FLAGS
14138 OpenMP compiler flags for <lang>, separated by spaces.
14139 OpenMP_<lang>_INCLUDE_DIRS
14141 Directories that must be added to the header search path for
14142 <lang> when using OpenMP.
14143 For linking with OpenMP code written in <lang>, the following variables
14145 are provided:
14146 OpenMP_<lang>_LIB_NAMES
14148 ;-list of libraries for OpenMP programs for <lang>.
14149 OpenMP_<libname>_LIBRARY
14151 Location of the individual libraries needed for OpenMP support
14152 in <lang>.
14153 OpenMP_<lang>_LIBRARIES
14155 A list of libraries needed to link with OpenMP code written in
14156 <lang>.
14157 Additionally, the module provides IMPORTED targets:
14159 OpenMP::OpenMP_<lang>
14161 Target for using OpenMP from <lang>.
14162 Specifically for Fortran, the module sets the following variables:
14164 OpenMP_Fortran_HAVE_OMPLIB_HEADER
14166 Boolean indicating if OpenMP is accessible through omp_lib.h.
14167 OpenMP_Fortran_HAVE_OMPLIB_MODULE
14169 Boolean indicating if OpenMP is accessible through the omp_lib
14170 Fortran module.
14171 The module will also try to provide the OpenMP version variables:
14173 OpenMP_<lang>_SPEC_DATE
14175 New in version 3.7.
14176 Date of the OpenMP specification implemented by the <lang> com‐
14179 piler.
14180 OpenMP_<lang>_VERSION_MAJOR
14182 Major version of OpenMP implemented by the <lang> compiler.
14183 OpenMP_<lang>_VERSION_MINOR
14185 Minor version of OpenMP implemented by the <lang> compiler.
14186 OpenMP_<lang>_VERSION
14188 OpenMP version implemented by the <lang> compiler.
14189 The specification date is formatted as given in the OpenMP standard:
14191 yyyymm where yyyy and mm represents the year and month of the OpenMP
14192 specification implemented by the <lang> compiler.
14193 For some compilers, it may be necessary to add a header search path to
14195 find the relevant OpenMP headers. This location may be language-spe‐
14196 cific. Where this is needed, the module may attempt to find the loca‐
14197 tion, but it can be provided directly by setting the OpenMP_<lang>_IN‐
14198 CLUDE_DIR cache variable. Note that this variable is an _input_ con‐
14199 trol to the module. Project code should use the OpenMP_<lang>_IN‐
14200 CLUDE_DIRS _output_ variable if it needs to know what include directo‐
14201 ries are needed.
14202 FindOpenSceneGraph
14204 Find OpenSceneGraph (3D graphics application programming interface)
14205 This module searches for the OpenSceneGraph core "osg" library as well
14207 as FindOpenThreads, and whatever additional COMPONENTS (nodekits) that
14208 you specify.
14209 See http://www.openscenegraph.org
14211 NOTE: To use this module effectively you must either require CMake >=
14213 2.6.3 with cmake_minimum_required(VERSION 2.6.3) or download and place
14214 FindOpenThreads, Findosg functions, Findosg and Find<etc>.cmake files
14215 into your CMAKE_MODULE_PATH.
14216 ----
14219 This module accepts the following variables (note mixed case)
14223 OpenSceneGraph_DEBUG - Enable debugging output
14225 OpenSceneGraph_MARK_AS_ADVANCED - Mark cache variables as advanced
14227 automatically
14228 The following environment variables are also respected for finding the
14230 OSG and it's various components. CMAKE_PREFIX_PATH can also be used
14231 for this (see find_library() CMake documentation).
14232 <MODULE>_DIR
14234 (where MODULE is of the form "OSGVOLUME" and there is a Findos‐
14235 gVolume.cmake` file)
14236 OSG_DIR
14238 OSGDIR
14240 OSG_ROOT
14242 [CMake 2.8.10]: The CMake variable OSG_DIR can now be used as well to
14244 influence detection, instead of needing to specify an environment vari‐
14245 able.
14246 This module defines the following output variables:
14248 OPENSCENEGRAPH_FOUND - Was the OSG and all of the specified components found?
14250 OPENSCENEGRAPH_VERSION - The version of the OSG which was found
14252 OPENSCENEGRAPH_INCLUDE_DIRS - Where to find the headers
14254 OPENSCENEGRAPH_LIBRARIES - The OSG libraries
14256 ================================== Example Usage:
14258 find_package(OpenSceneGraph 2.0.0 REQUIRED osgDB osgUtil)
14260 # libOpenThreads & libosg automatically searched
14261 include_directories(${OPENSCENEGRAPH_INCLUDE_DIRS})
14262 add_executable(foo foo.cc)
14264 target_link_libraries(foo ${OPENSCENEGRAPH_LIBRARIES})
14265 FindOpenSSL
14267 Find the OpenSSL encryption library.
14268 This module finds an installed OpenSSL library and determines its ver‐
14270 sion.
14271 New in version 3.19: When a version is requested, it can be specified
14273 as a simple value or as a range. For a detailed description of version
14274 range usage and capabilities, refer to the find_package() command.
14275 New in version 3.18: Support for OpenSSL 3.0.
14278 Optional COMPONENTS
14281 New in version 3.12.
14282 This module supports two optional COMPONENTS: Crypto and SSL. Both
14285 components have associated imported targets, as described below.
14286 Imported Targets
14288 New in version 3.4.
14289 This module defines the following IMPORTED targets:
14292 OpenSSL::SSL
14294 The OpenSSL ssl library, if found.
14295 OpenSSL::Crypto
14297 The OpenSSL crypto library, if found.
14298 OpenSSL::applink
14300 New in version 3.18.
14301 The OpenSSL applink components that might be need to be compiled
14304 into projects under MSVC. This target is available only if found
14305 OpenSSL version is not less than 0.9.8. By linking this target
14306 the above OpenSSL targets can be linked even if the project has
14307 different MSVC runtime configurations with the above OpenSSL
14308 targets. This target has no effect on platforms other than MSVC.
14309 NOTE: Due to how INTERFACE_SOURCES are consumed by the consuming tar‐
14311 get, unless you certainly know what you are doing, it is always pre‐
14312 ferred to link OpenSSL::applink target as PRIVATE and to make sure that
14313 this target is linked at most once for the whole dependency graph of
14314 any library or executable:
14315 target_link_libraries(myTarget PRIVATE OpenSSL::applink)
14317 Otherwise you would probably encounter unexpected random problems when
14319 building and linking, as both the ISO C and the ISO C++ standard claims
14320 almost nothing about what a link process should be.
14321 Result Variables
14323 This module will set the following variables in your project:
14324 OPENSSL_FOUND
14326 System has the OpenSSL library. If no components are requested
14327 it only requires the crypto library.
14328 OPENSSL_INCLUDE_DIR
14330 The OpenSSL include directory.
14331 OPENSSL_CRYPTO_LIBRARY
14333 The OpenSSL crypto library.
14334 OPENSSL_CRYPTO_LIBRARIES
14336 The OpenSSL crypto library and its dependencies.
14337 OPENSSL_SSL_LIBRARY
14339 The OpenSSL SSL library.
14340 OPENSSL_SSL_LIBRARIES
14342 The OpenSSL SSL library and its dependencies.
14343 OPENSSL_LIBRARIES
14345 All OpenSSL libraries and their dependencies.
14346 OPENSSL_VERSION
14348 This is set to $major.$minor.$revision$patch (e.g. 0.9.8s).
14349 OPENSSL_APPLINK_SOURCE
14351 The sources in the target OpenSSL::applink that is mentioned
14352 above. This variable shall always be undefined if found openssl
14353 version is less than 0.9.8 or if platform is not MSVC.
14354 Hints
14356 Set OPENSSL_ROOT_DIR to the root directory of an OpenSSL installation.
14357 New in version 3.4: Set OPENSSL_USE_STATIC_LIBS to TRUE to look for
14359 static libraries.
14360 New in version 3.5: Set OPENSSL_MSVC_STATIC_RT set TRUE to choose the
14363 MT version of the lib.
14364 FindOpenThreads
14367 OpenThreads is a C++ based threading library. Its largest userbase
14368 seems to OpenSceneGraph so you might notice I accept OSGDIR as an envi‐
14369 ronment path. I consider this part of the Findosg* suite used to find
14370 OpenSceneGraph components. Each component is separate and you must opt
14371 in to each module.
14372 Locate OpenThreads This module defines OPENTHREADS_LIBRARY
14374 OPENTHREADS_FOUND, if false, do not try to link to OpenThreads
14375 OPENTHREADS_INCLUDE_DIR, where to find the headers
14376 $OPENTHREADS_DIR is an environment variable that would correspond to
14378 the ./configure --prefix=$OPENTHREADS_DIR used in building osg.
14379 [CMake 2.8.10]: The CMake variables OPENTHREADS_DIR or OSG_DIR can now
14381 be used as well to influence detection, instead of needing to specify
14382 an environment variable.
14383 Created by Eric Wing.
14385 Findosg
14387 NOTE: It is highly recommended that you use the new FindOpenScene‐
14388 Graph.cmake introduced in CMake 2.6.3 and not use this Find module di‐
14389 rectly.
14390 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
14392 nents. Each component is separate and you must opt in to each module.
14393 You must also opt into OpenGL and OpenThreads (and Producer if needed)
14394 as these modules won't do it for you. This is to allow you control
14395 over your own system piece by piece in case you need to opt out of cer‐
14396 tain components or change the Find behavior for a particular module
14397 (perhaps because the default FindOpenGL.cmake module doesn't work with
14398 your system as an example). If you want to use a more convenient mod‐
14399 ule that includes everything, use the FindOpenSceneGraph.cmake instead
14400 of the Findosg*.cmake modules.
14401 Locate osg This module defines
14403 OSG_FOUND - Was the Osg found? OSG_INCLUDE_DIR - Where to find the
14405 headers OSG_LIBRARIES - The libraries to link against for the OSG (use
14406 this)
14407 OSG_LIBRARY - The OSG library OSG_LIBRARY_DEBUG - The OSG debug library
14409 $OSGDIR is an environment variable that would correspond to the ./con‐
14411 figure --prefix=$OSGDIR used in building osg.
14412 Created by Eric Wing.
14414 Findosg_functions
14416 This CMake file contains two macros to assist with searching for OSG
14417 libraries and nodekits. Please see FindOpenSceneGraph.cmake for full
14418 documentation.
14419 FindosgAnimation
14421 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
14422 nents. Each component is separate and you must opt in to each module.
14423 You must also opt into OpenGL and OpenThreads (and Producer if needed)
14424 as these modules won't do it for you. This is to allow you control
14425 over your own system piece by piece in case you need to opt out of cer‐
14426 tain components or change the Find behavior for a particular module
14427 (perhaps because the default FindOpenGL.cmake module doesn't work with
14428 your system as an example). If you want to use a more convenient mod‐
14429 ule that includes everything, use the FindOpenSceneGraph.cmake instead
14430 of the Findosg*.cmake modules.
14431 Locate osgAnimation This module defines
14433 OSGANIMATION_FOUND - Was osgAnimation found? OSGANIMATION_INCLUDE_DIR -
14435 Where to find the headers OSGANIMATION_LIBRARIES - The libraries to
14436 link against for the OSG (use this)
14437 OSGANIMATION_LIBRARY - The OSG library OSGANIMATION_LIBRARY_DEBUG - The
14439 OSG debug library
14440 $OSGDIR is an environment variable that would correspond to the ./con‐
14442 figure --prefix=$OSGDIR used in building osg.
14443 Created by Eric Wing.
14445 FindosgDB
14447 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
14448 nents. Each component is separate and you must opt in to each module.
14449 You must also opt into OpenGL and OpenThreads (and Producer if needed)
14450 as these modules won't do it for you. This is to allow you control
14451 over your own system piece by piece in case you need to opt out of cer‐
14452 tain components or change the Find behavior for a particular module
14453 (perhaps because the default FindOpenGL module doesn't work with your
14454 system as an example). If you want to use a more convenient module
14455 that includes everything, use the FindOpenSceneGraph instead of the
14456 Findosg*.cmake modules.
14457 Locate osgDB This module defines:
14459 OSGDB_FOUND
14461 Was osgDB found?
14462 OSGDB_INCLUDE_DIR
14464 Where to find the headers
14465 OSGDB_LIBRARIES
14467 The libraries to link against for the osgDB
14468 OSGDB_LIBRARY
14470 The osgDB library
14471 OSGDB_LIBRARY_DEBUG
14473 The osgDB debug library
14474 $OSGDIR is an environment variable that would correspond to:
14476 ./configure --prefix=$OSGDIR used in building osg.
14478 FindosgFX
14480 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
14481 nents. Each component is separate and you must opt in to each module.
14482 You must also opt into OpenGL and OpenThreads (and Producer if needed)
14483 as these modules won't do it for you. This is to allow you control
14484 over your own system piece by piece in case you need to opt out of cer‐
14485 tain components or change the Find behavior for a particular module
14486 (perhaps because the default FindOpenGL.cmake module doesn't work with
14487 your system as an example). If you want to use a more convenient mod‐
14488 ule that includes everything, use the FindOpenSceneGraph.cmake instead
14489 of the Findosg*.cmake modules.
14490 Locate osgFX This module defines
14492 OSGFX_FOUND - Was osgFX found? OSGFX_INCLUDE_DIR - Where to find the
14494 headers OSGFX_LIBRARIES - The libraries to link against for the osgFX
14495 (use this)
14496 OSGFX_LIBRARY - The osgFX library OSGFX_LIBRARY_DEBUG - The osgFX debug
14498 library
14499 $OSGDIR is an environment variable that would correspond to the ./con‐
14501 figure --prefix=$OSGDIR used in building osg.
14502 Created by Eric Wing.
14504 FindosgGA
14506 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
14507 nents. Each component is separate and you must opt in to each module.
14508 You must also opt into OpenGL and OpenThreads (and Producer if needed)
14509 as these modules won't do it for you. This is to allow you control
14510 over your own system piece by piece in case you need to opt out of cer‐
14511 tain components or change the Find behavior for a particular module
14512 (perhaps because the default FindOpenGL.cmake module doesn't work with
14513 your system as an example). If you want to use a more convenient mod‐
14514 ule that includes everything, use the FindOpenSceneGraph.cmake instead
14515 of the Findosg*.cmake modules.
14516 Locate osgGA This module defines
14518 OSGGA_FOUND - Was osgGA found? OSGGA_INCLUDE_DIR - Where to find the
14520 headers OSGGA_LIBRARIES - The libraries to link against for the osgGA
14521 (use this)
14522 OSGGA_LIBRARY - The osgGA library OSGGA_LIBRARY_DEBUG - The osgGA debug
14524 library
14525 $OSGDIR is an environment variable that would correspond to the ./con‐
14527 figure --prefix=$OSGDIR used in building osg.
14528 Created by Eric Wing.
14530 FindosgIntrospection
14532 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
14533 nents. Each component is separate and you must opt in to each module.
14534 You must also opt into OpenGL and OpenThreads (and Producer if needed)
14535 as these modules won't do it for you. This is to allow you control
14536 over your own system piece by piece in case you need to opt out of cer‐
14537 tain components or change the Find behavior for a particular module
14538 (perhaps because the default FindOpenGL.cmake module doesn't work with
14539 your system as an example). If you want to use a more convenient mod‐
14540 ule that includes everything, use the FindOpenSceneGraph.cmake instead
14541 of the Findosg*.cmake modules.
14542 Locate osgINTROSPECTION This module defines
14544 OSGINTROSPECTION_FOUND - Was osgIntrospection found? OSGINTROSPEC‐
14546 TION_INCLUDE_DIR - Where to find the headers OSGINTROSPECTION_LIBRARIES
14547 - The libraries to link for osgIntrospection (use this)
14548 OSGINTROSPECTION_LIBRARY - The osgIntrospection library OSGINTROSPEC‐
14550 TION_LIBRARY_DEBUG - The osgIntrospection debug library
14551 $OSGDIR is an environment variable that would correspond to the ./con‐
14553 figure --prefix=$OSGDIR used in building osg.
14554 Created by Eric Wing.
14556 FindosgManipulator
14558 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
14559 nents. Each component is separate and you must opt in to each module.
14560 You must also opt into OpenGL and OpenThreads (and Producer if needed)
14561 as these modules won't do it for you. This is to allow you control
14562 over your own system piece by piece in case you need to opt out of cer‐
14563 tain components or change the Find behavior for a particular module
14564 (perhaps because the default FindOpenGL.cmake module doesn't work with
14565 your system as an example). If you want to use a more convenient mod‐
14566 ule that includes everything, use the FindOpenSceneGraph.cmake instead
14567 of the Findosg*.cmake modules.
14568 Locate osgManipulator This module defines
14570 OSGMANIPULATOR_FOUND - Was osgManipulator found? OSGMANIPULATOR_IN‐
14572 CLUDE_DIR - Where to find the headers OSGMANIPULATOR_LIBRARIES - The
14573 libraries to link for osgManipulator (use this)
14574 OSGMANIPULATOR_LIBRARY - The osgManipulator library OSGMANIPULATOR_LI‐
14576 BRARY_DEBUG - The osgManipulator debug library
14577 $OSGDIR is an environment variable that would correspond to the ./con‐
14579 figure --prefix=$OSGDIR used in building osg.
14580 Created by Eric Wing.
14582 FindosgParticle
14584 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
14585 nents. Each component is separate and you must opt in to each module.
14586 You must also opt into OpenGL and OpenThreads (and Producer if needed)
14587 as these modules won't do it for you. This is to allow you control
14588 over your own system piece by piece in case you need to opt out of cer‐
14589 tain components or change the Find behavior for a particular module
14590 (perhaps because the default FindOpenGL.cmake module doesn't work with
14591 your system as an example). If you want to use a more convenient mod‐
14592 ule that includes everything, use the FindOpenSceneGraph.cmake instead
14593 of the Findosg*.cmake modules.
14594 Locate osgParticle This module defines
14596 OSGPARTICLE_FOUND - Was osgParticle found? OSGPARTICLE_INCLUDE_DIR -
14598 Where to find the headers OSGPARTICLE_LIBRARIES - The libraries to link
14599 for osgParticle (use this)
14600 OSGPARTICLE_LIBRARY - The osgParticle library OSGPARTICLE_LIBRARY_DEBUG
14602 - The osgParticle debug library
14603 $OSGDIR is an environment variable that would correspond to the ./con‐
14605 figure --prefix=$OSGDIR used in building osg.
14606 Created by Eric Wing.
14608 FindosgPresentation
14610 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
14611 nents. Each component is separate and you must opt in to each module.
14612 You must also opt into OpenGL and OpenThreads (and Producer if needed)
14613 as these modules won't do it for you. This is to allow you control
14614 over your own system piece by piece in case you need to opt out of cer‐
14615 tain components or change the Find behavior for a particular module
14616 (perhaps because the default FindOpenGL.cmake module doesn't work with
14617 your system as an example). If you want to use a more convenient mod‐
14618 ule that includes everything, use the FindOpenSceneGraph.cmake instead
14619 of the Findosg*.cmake modules.
14620 Locate osgPresentation This module defines
14622 OSGPRESENTATION_FOUND - Was osgPresentation found? OSGPRESENTATION_IN‐
14624 CLUDE_DIR - Where to find the headers OSGPRESENTATION_LIBRARIES - The
14625 libraries to link for osgPresentation (use this)
14626 OSGPRESENTATION_LIBRARY - The osgPresentation library OSGPRESENTA‐
14628 TION_LIBRARY_DEBUG - The osgPresentation debug library
14629 $OSGDIR is an environment variable that would correspond to the ./con‐
14631 figure --prefix=$OSGDIR used in building osg.
14632 Created by Eric Wing. Modified to work with osgPresentation by Robert
14634 Osfield, January 2012.
14635 FindosgProducer
14637 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
14638 nents. Each component is separate and you must opt in to each module.
14639 You must also opt into OpenGL and OpenThreads (and Producer if needed)
14640 as these modules won't do it for you. This is to allow you control
14641 over your own system piece by piece in case you need to opt out of cer‐
14642 tain components or change the Find behavior for a particular module
14643 (perhaps because the default FindOpenGL.cmake module doesn't work with
14644 your system as an example). If you want to use a more convenient mod‐
14645 ule that includes everything, use the FindOpenSceneGraph.cmake instead
14646 of the Findosg*.cmake modules.
14647 Locate osgProducer This module defines
14649 OSGPRODUCER_FOUND - Was osgProducer found? OSGPRODUCER_INCLUDE_DIR -
14651 Where to find the headers OSGPRODUCER_LIBRARIES - The libraries to link
14652 for osgProducer (use this)
14653 OSGPRODUCER_LIBRARY - The osgProducer library OSGPRODUCER_LIBRARY_DEBUG
14655 - The osgProducer debug library
14656 $OSGDIR is an environment variable that would correspond to the ./con‐
14658 figure --prefix=$OSGDIR used in building osg.
14659 Created by Eric Wing.
14661 FindosgQt
14663 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
14664 nents. Each component is separate and you must opt in to each module.
14665 You must also opt into OpenGL and OpenThreads (and Producer if needed)
14666 as these modules won't do it for you. This is to allow you control
14667 over your own system piece by piece in case you need to opt out of cer‐
14668 tain components or change the Find behavior for a particular module
14669 (perhaps because the default FindOpenGL.cmake module doesn't work with
14670 your system as an example). If you want to use a more convenient mod‐
14671 ule that includes everything, use the FindOpenSceneGraph.cmake instead
14672 of the Findosg*.cmake modules.
14673 Locate osgQt This module defines
14675 OSGQT_FOUND - Was osgQt found? OSGQT_INCLUDE_DIR - Where to find the
14677 headers OSGQT_LIBRARIES - The libraries to link for osgQt (use this)
14678 OSGQT_LIBRARY - The osgQt library OSGQT_LIBRARY_DEBUG - The osgQt debug
14680 library
14681 $OSGDIR is an environment variable that would correspond to the ./con‐
14683 figure --prefix=$OSGDIR used in building osg.
14684 Created by Eric Wing. Modified to work with osgQt by Robert Osfield,
14686 January 2012.
14687 FindosgShadow
14689 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
14690 nents. Each component is separate and you must opt in to each module.
14691 You must also opt into OpenGL and OpenThreads (and Producer if needed)
14692 as these modules won't do it for you. This is to allow you control
14693 over your own system piece by piece in case you need to opt out of cer‐
14694 tain components or change the Find behavior for a particular module
14695 (perhaps because the default FindOpenGL.cmake module doesn't work with
14696 your system as an example). If you want to use a more convenient mod‐
14697 ule that includes everything, use the FindOpenSceneGraph.cmake instead
14698 of the Findosg*.cmake modules.
14699 Locate osgShadow This module defines
14701 OSGSHADOW_FOUND - Was osgShadow found? OSGSHADOW_INCLUDE_DIR - Where to
14703 find the headers OSGSHADOW_LIBRARIES - The libraries to link for os‐
14704 gShadow (use this)
14705 OSGSHADOW_LIBRARY - The osgShadow library OSGSHADOW_LIBRARY_DEBUG - The
14707 osgShadow debug library
14708 $OSGDIR is an environment variable that would correspond to the ./con‐
14710 figure --prefix=$OSGDIR used in building osg.
14711 Created by Eric Wing.
14713 FindosgSim
14715 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
14716 nents. Each component is separate and you must opt in to each module.
14717 You must also opt into OpenGL and OpenThreads (and Producer if needed)
14718 as these modules won't do it for you. This is to allow you control
14719 over your own system piece by piece in case you need to opt out of cer‐
14720 tain components or change the Find behavior for a particular module
14721 (perhaps because the default FindOpenGL.cmake module doesn't work with
14722 your system as an example). If you want to use a more convenient mod‐
14723 ule that includes everything, use the FindOpenSceneGraph.cmake instead
14724 of the Findosg*.cmake modules.
14725 Locate osgSim This module defines
14727 OSGSIM_FOUND - Was osgSim found? OSGSIM_INCLUDE_DIR - Where to find the
14729 headers OSGSIM_LIBRARIES - The libraries to link for osgSim (use this)
14730 OSGSIM_LIBRARY - The osgSim library OSGSIM_LIBRARY_DEBUG - The osgSim
14732 debug library
14733 $OSGDIR is an environment variable that would correspond to the ./con‐
14735 figure --prefix=$OSGDIR used in building osg.
14736 Created by Eric Wing.
14738 FindosgTerrain
14740 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
14741 nents. Each component is separate and you must opt in to each module.
14742 You must also opt into OpenGL and OpenThreads (and Producer if needed)
14743 as these modules won't do it for you. This is to allow you control
14744 over your own system piece by piece in case you need to opt out of cer‐
14745 tain components or change the Find behavior for a particular module
14746 (perhaps because the default FindOpenGL.cmake module doesn't work with
14747 your system as an example). If you want to use a more convenient mod‐
14748 ule that includes everything, use the FindOpenSceneGraph.cmake instead
14749 of the Findosg*.cmake modules.
14750 Locate osgTerrain This module defines
14752 OSGTERRAIN_FOUND - Was osgTerrain found? OSGTERRAIN_INCLUDE_DIR - Where
14754 to find the headers OSGTERRAIN_LIBRARIES - The libraries to link for
14755 osgTerrain (use this)
14756 OSGTERRAIN_LIBRARY - The osgTerrain library OSGTERRAIN_LIBRARY_DEBUG -
14758 The osgTerrain debug library
14759 $OSGDIR is an environment variable that would correspond to the ./con‐
14761 figure --prefix=$OSGDIR used in building osg.
14762 Created by Eric Wing.
14764 FindosgText
14766 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
14767 nents. Each component is separate and you must opt in to each module.
14768 You must also opt into OpenGL and OpenThreads (and Producer if needed)
14769 as these modules won't do it for you. This is to allow you control
14770 over your own system piece by piece in case you need to opt out of cer‐
14771 tain components or change the Find behavior for a particular module
14772 (perhaps because the default FindOpenGL.cmake module doesn't work with
14773 your system as an example). If you want to use a more convenient mod‐
14774 ule that includes everything, use the FindOpenSceneGraph.cmake instead
14775 of the Findosg*.cmake modules.
14776 Locate osgText This module defines
14778 OSGTEXT_FOUND - Was osgText found? OSGTEXT_INCLUDE_DIR - Where to find
14780 the headers OSGTEXT_LIBRARIES - The libraries to link for osgText (use
14781 this)
14782 OSGTEXT_LIBRARY - The osgText library OSGTEXT_LIBRARY_DEBUG - The osg‐
14784 Text debug library
14785 $OSGDIR is an environment variable that would correspond to the ./con‐
14787 figure --prefix=$OSGDIR used in building osg.
14788 Created by Eric Wing.
14790 FindosgUtil
14792 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
14793 nents. Each component is separate and you must opt in to each module.
14794 You must also opt into OpenGL and OpenThreads (and Producer if needed)
14795 as these modules won't do it for you. This is to allow you control
14796 over your own system piece by piece in case you need to opt out of cer‐
14797 tain components or change the Find behavior for a particular module
14798 (perhaps because the default FindOpenGL.cmake module doesn't work with
14799 your system as an example). If you want to use a more convenient mod‐
14800 ule that includes everything, use the FindOpenSceneGraph.cmake instead
14801 of the Findosg*.cmake modules.
14802 Locate osgUtil This module defines
14804 OSGUTIL_FOUND - Was osgUtil found? OSGUTIL_INCLUDE_DIR - Where to find
14806 the headers OSGUTIL_LIBRARIES - The libraries to link for osgUtil (use
14807 this)
14808 OSGUTIL_LIBRARY - The osgUtil library OSGUTIL_LIBRARY_DEBUG - The
14810 osgUtil debug library
14811 $OSGDIR is an environment variable that would correspond to the ./con‐
14813 figure --prefix=$OSGDIR used in building osg.
14814 Created by Eric Wing.
14816 FindosgViewer
14818 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
14819 nents. Each component is separate and you must opt in to each module.
14820 You must also opt into OpenGL and OpenThreads (and Producer if needed)
14821 as these modules won't do it for you. This is to allow you control
14822 over your own system piece by piece in case you need to opt out of cer‐
14823 tain components or change the Find behavior for a particular module
14824 (perhaps because the default FindOpenGL.cmake module doesn't work with
14825 your system as an example). If you want to use a more convenient mod‐
14826 ule that includes everything, use the FindOpenSceneGraph.cmake instead
14827 of the Findosg*.cmake modules.
14828 Locate osgViewer This module defines
14830 OSGVIEWER_FOUND - Was osgViewer found? OSGVIEWER_INCLUDE_DIR - Where to
14832 find the headers OSGVIEWER_LIBRARIES - The libraries to link for os‐
14833 gViewer (use this)
14834 OSGVIEWER_LIBRARY - The osgViewer library OSGVIEWER_LIBRARY_DEBUG - The
14836 osgViewer debug library
14837 $OSGDIR is an environment variable that would correspond to the ./con‐
14839 figure --prefix=$OSGDIR used in building osg.
14840 Created by Eric Wing.
14842 FindosgVolume
14844 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
14845 nents. Each component is separate and you must opt in to each module.
14846 You must also opt into OpenGL and OpenThreads (and Producer if needed)
14847 as these modules won't do it for you. This is to allow you control
14848 over your own system piece by piece in case you need to opt out of cer‐
14849 tain components or change the Find behavior for a particular module
14850 (perhaps because the default FindOpenGL.cmake module doesn't work with
14851 your system as an example). If you want to use a more convenient mod‐
14852 ule that includes everything, use the FindOpenSceneGraph.cmake instead
14853 of the Findosg*.cmake modules.
14854 Locate osgVolume This module defines
14856 OSGVOLUME_FOUND - Was osgVolume found? OSGVOLUME_INCLUDE_DIR - Where to
14858 find the headers OSGVOLUME_LIBRARIES - The libraries to link for os‐
14859 gVolume (use this)
14860 OSGVOLUME_LIBRARY - The osgVolume library OSGVOLUME_LIBRARY_DEBUG - The
14862 osgVolume debug library
14863 $OSGDIR is an environment variable that would correspond to the ./con‐
14865 figure --prefix=$OSGDIR used in building osg.
14866 Created by Eric Wing.
14868 FindosgWidget
14870 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
14871 nents. Each component is separate and you must opt in to each module.
14872 You must also opt into OpenGL and OpenThreads (and Producer if needed)
14873 as these modules won't do it for you. This is to allow you control
14874 over your own system piece by piece in case you need to opt out of cer‐
14875 tain components or change the Find behavior for a particular module
14876 (perhaps because the default FindOpenGL.cmake module doesn't work with
14877 your system as an example). If you want to use a more convenient mod‐
14878 ule that includes everything, use the FindOpenSceneGraph.cmake instead
14879 of the Findosg*.cmake modules.
14880 Locate osgWidget This module defines
14882 OSGWIDGET_FOUND - Was osgWidget found? OSGWIDGET_INCLUDE_DIR - Where to
14884 find the headers OSGWIDGET_LIBRARIES - The libraries to link for osg‐
14885 Widget (use this)
14886 OSGWIDGET_LIBRARY - The osgWidget library OSGWIDGET_LIBRARY_DEBUG - The
14888 osgWidget debug library
14889 $OSGDIR is an environment variable that would correspond to the ./con‐
14891 figure --prefix=$OSGDIR used in building osg.
14892 FindosgWidget.cmake tweaked from Findosg* suite as created by Eric
14894 Wing.
14895 FindPatch
14897 New in version 3.10.
14898 The module defines the following variables:
14901 Patch_EXECUTABLE
14903 Path to patch command-line executable.
14904 Patch_FOUND
14906 True if the patch command-line executable was found.
14907 The following IMPORTED targets are also defined:
14909 Patch::patch
14911 The command-line executable.
14912 Example usage:
14914 find_package(Patch)
14916 if(Patch_FOUND)
14917 message("Patch found: ${Patch_EXECUTABLE}")
14918 endif()
14919 FindPerl
14921 Find perl
14922 this module looks for Perl
14924 PERL_EXECUTABLE - the full path to perl
14926 PERL_FOUND - If false, don't attempt to use perl.
14927 PERL_VERSION_STRING - version of perl found (since CMake 2.8.8)
14928 FindPerlLibs
14930 Find Perl libraries
14931 This module finds if PERL is installed and determines where the include
14933 files and libraries are. It also determines what the name of the li‐
14934 brary is. This code sets the following variables:
14935 PERLLIBS_FOUND = True if perl.h & libperl were found
14937 PERL_INCLUDE_PATH = path to where perl.h is found
14938 PERL_LIBRARY = path to libperl
14939 PERL_EXECUTABLE = full path to the perl binary
14940 The minimum required version of Perl can be specified using the stan‐
14942 dard syntax, e.g. find_package(PerlLibs 6.0)
14943 The following variables are also available if needed
14945 (introduced after CMake 2.6.4)
14946 PERL_SITESEARCH = path to the sitesearch install dir (-V:installsitesearch)
14948 PERL_SITEARCH = path to the sitelib install directory (-V:installsitearch)
14949 PERL_SITELIB = path to the sitelib install directory (-V:installsitelib)
14950 PERL_VENDORARCH = path to the vendor arch install directory (-V:installvendorarch)
14951 PERL_VENDORLIB = path to the vendor lib install directory (-V:installvendorlib)
14952 PERL_ARCHLIB = path to the core arch lib install directory (-V:archlib)
14953 PERL_PRIVLIB = path to the core priv lib install directory (-V:privlib)
14954 PERL_UPDATE_ARCHLIB = path to the update arch lib install directory (-V:installarchlib)
14955 PERL_UPDATE_PRIVLIB = path to the update priv lib install directory (-V:installprivlib)
14956 PERL_EXTRA_C_FLAGS = Compilation flags used to build perl
14957 FindPHP4
14959 Find PHP4
14960 This module finds if PHP4 is installed and determines where the include
14962 files and libraries are. It also determines what the name of the li‐
14963 brary is. This code sets the following variables:
14964 PHP4_INCLUDE_PATH = path to where php.h can be found
14966 PHP4_EXECUTABLE = full path to the php4 binary
14967 FindPhysFS
14969 Locate PhysFS library This module defines PHYSFS_LIBRARY, the name of
14970 the library to link against PHYSFS_FOUND, if false, do not try to link
14971 to PHYSFS PHYSFS_INCLUDE_DIR, where to find physfs.h
14972 $PHYSFSDIR is an environment variable that would correspond to the
14974 ./configure --prefix=$PHYSFSDIR used in building PHYSFS.
14975 Created by Eric Wing.
14977 FindPike
14979 Find Pike
14980 This module finds if PIKE is installed and determines where the include
14982 files and libraries are. It also determines what the name of the li‐
14983 brary is. This code sets the following variables:
14984 PIKE_INCLUDE_PATH = path to where program.h is found
14986 PIKE_EXECUTABLE = full path to the pike binary
14987 FindPkgConfig
14989 A pkg-config module for CMake.
14990 Finds the pkg-config executable and adds the pkg_get_variable(),
14992 pkg_check_modules() and pkg_search_module() commands. The following
14993 variables will also be set:
14994 PKG_CONFIG_FOUND
14996 if pkg-config executable was found
14997 PKG_CONFIG_EXECUTABLE
14999 pathname of the pkg-config program
15000 PKG_CONFIG_VERSION_STRING
15002 version of pkg-config (since CMake 2.8.8)
15003 pkg_check_modules
15005 Checks for all the given modules, setting a variety of result
15006 variables in the calling scope.
15007 pkg_check_modules(<prefix>
15009 [REQUIRED] [QUIET]
15010 [NO_CMAKE_PATH]
15011 [NO_CMAKE_ENVIRONMENT_PATH]
15012 [IMPORTED_TARGET [GLOBAL]]
15013 <moduleSpec> [<moduleSpec>...])
15014 When the REQUIRED argument is given, the command will fail with
15016 an error if module(s) could not be found.
15017 When the QUIET argument is given, no status messages will be
15019 printed.
15020 New in version 3.1: The CMAKE_PREFIX_PATH, CMAKE_FRAMEWORK_PATH,
15022 and CMAKE_APPBUNDLE_PATH cache and environment variables will be
15023 added to the pkg-config search path. The NO_CMAKE_PATH and
15024 NO_CMAKE_ENVIRONMENT_PATH arguments disable this behavior for
15025 the cache variables and environment variables respectively. The
15026 PKG_CONFIG_USE_CMAKE_PREFIX_PATH variable set to FALSE disables
15027 this behavior globally.
15028 New in version 3.6: The IMPORTED_TARGET argument will create an
15031 imported target named PkgConfig::<prefix> that can be passed di‐
15032 rectly as an argument to target_link_libraries().
15033 New in version 3.13: The GLOBAL argument will make the imported
15036 target available in global scope.
15037 New in version 3.15: Non-library linker options reported by
15040 pkg-config are stored in the INTERFACE_LINK_OPTIONS target prop‐
15041 erty.
15042 Changed in version 3.18: Include directories specified with
15045 -isystem are stored in the INTERFACE_INCLUDE_DIRECTORIES target
15046 property. Previous versions of CMake left them in the INTER‐
15047 FACE_COMPILE_OPTIONS property.
15048 Each <moduleSpec> can be either a bare module name or it can be
15051 a module name with a version constraint (operators =, <, >, <=
15052 and >= are supported). The following are examples for a module
15053 named foo with various constraints:
15054 • foo matches any version.
15056 • foo<2 only matches versions before 2.
15058 • foo>=3.1 matches any version from 3.1 or later.
15060 • foo=1.2.3 requires that foo must be exactly version 1.2.3.
15062 The following variables may be set upon return. Two sets of
15064 values exist: One for the common case (<XXX> = <prefix>) and an‐
15065 other for the information pkg-config provides when called with
15066 the --static option (<XXX> = <prefix>_STATIC).
15067 <XXX>_FOUND
15069 set to 1 if module(s) exist
15070 <XXX>_LIBRARIES
15072 only the libraries (without the '-l')
15073 <XXX>_LINK_LIBRARIES
15075 the libraries and their absolute paths
15076 <XXX>_LIBRARY_DIRS
15078 the paths of the libraries (without the '-L')
15079 <XXX>_LDFLAGS
15081 all required linker flags
15082 <XXX>_LDFLAGS_OTHER
15084 all other linker flags
15085 <XXX>_INCLUDE_DIRS
15087 the '-I' preprocessor flags (without the '-I')
15088 <XXX>_CFLAGS
15090 all required cflags
15091 <XXX>_CFLAGS_OTHER
15093 the other compiler flags
15094 All but <XXX>_FOUND may be a ;-list if the associated variable
15096 returned from pkg-config has multiple values.
15097 Changed in version 3.18: Include directories specified with
15099 -isystem are stored in the <XXX>_INCLUDE_DIRS variable. Previ‐
15100 ous versions of CMake left them in <XXX>_CFLAGS_OTHER.
15101 There are some special variables whose prefix depends on the
15104 number of <moduleSpec> given. When there is only one <module‐
15105 Spec>, <YYY> will simply be <prefix>, but if two or more <mod‐
15106 uleSpec> items are given, <YYY> will be <prefix>_<moduleName>.
15107 <YYY>_VERSION
15109 version of the module
15110 <YYY>_PREFIX
15112 prefix directory of the module
15113 <YYY>_INCLUDEDIR
15115 include directory of the module
15116 <YYY>_LIBDIR
15118 lib directory of the module
15119 Changed in version 3.8: For any given <prefix>, pkg_check_mod‐
15121 ules() can be called multiple times with different parameters.
15122 Previous versions of CMake cached and returned the first suc‐
15123 cessful result.
15124 Changed in version 3.16: If a full path to the found library
15127 can't be determined, but it's still visible to the linker, pass
15128 it through as -l<name>. Previous versions of CMake failed in
15129 this case.
15130 Examples:
15133 pkg_check_modules (GLIB2 glib-2.0)
15135 Looks for any version of glib2. If found, the output variable
15137 GLIB2_VERSION will hold the actual version found.
15138 pkg_check_modules (GLIB2 glib-2.0>=2.10)
15140 Looks for at least version 2.10 of glib2. If found, the output
15142 variable GLIB2_VERSION will hold the actual version found.
15143 pkg_check_modules (FOO glib-2.0>=2.10 gtk+-2.0)
15145 Looks for both glib2-2.0 (at least version 2.10) and any version
15147 of gtk2+-2.0. Only if both are found will FOO be considered
15148 found. The FOO_glib-2.0_VERSION and FOO_gtk+-2.0_VERSION vari‐
15149 ables will be set to their respective found module versions.
15150 pkg_check_modules (XRENDER REQUIRED xrender)
15152 Requires any version of xrender. Example output variables set
15154 by a successful call:
15155 XRENDER_LIBRARIES=Xrender;X11
15157 XRENDER_STATIC_LIBRARIES=Xrender;X11;pthread;Xau;Xdmcp
15158 pkg_search_module
15160 The behavior of this command is the same as pkg_check_modules(),
15161 except that rather than checking for all the specified modules,
15162 it searches for just the first successful match.
15163 pkg_search_module(<prefix>
15165 [REQUIRED] [QUIET]
15166 [NO_CMAKE_PATH]
15167 [NO_CMAKE_ENVIRONMENT_PATH]
15168 [IMPORTED_TARGET [GLOBAL]]
15169 <moduleSpec> [<moduleSpec>...])
15170 New in version 3.16: If a module is found, the <prefix>_MOD‐
15172 ULE_NAME variable will contain the name of the matching module.
15173 This variable can be used if you need to run pkg_get_variable().
15174 Example:
15177 pkg_search_module (BAR libxml-2.0 libxml2 libxml>=2)
15179 pkg_get_variable
15181 New in version 3.4.
15182 Retrieves the value of a pkg-config variable varName and stores
15185 it in the result variable resultVar in the calling scope.
15186 pkg_get_variable(<resultVar> <moduleName> <varName>)
15188 If pkg-config returns multiple values for the specified vari‐
15190 able, resultVar will contain a ;-list.
15191 For example:
15193 pkg_get_variable(GI_GIRDIR gobject-introspection-1.0 girdir)
15195 Variables Affecting Behavior
15197 PKG_CONFIG_EXECUTABLE
15198 This can be set to the path of the pkg-config executable. If
15199 not provided, it will be set by the module as a result of call‐
15200 ing find_program() internally.
15201 New in version 3.1: The PKG_CONFIG environment variable can be
15203 used as a hint.
15204 PKG_CONFIG_USE_CMAKE_PREFIX_PATH
15207 New in version 3.1.
15208 Specifies whether pkg_check_modules() and pkg_search_module()
15211 should add the paths in the CMAKE_PREFIX_PATH, CMAKE_FRAME‐
15212 WORK_PATH and CMAKE_APPBUNDLE_PATH cache and environment vari‐
15213 ables to the pkg-config search path.
15214 If this variable is not set, this behavior is enabled by default
15216 if CMAKE_MINIMUM_REQUIRED_VERSION is 3.1 or later, disabled oth‐
15217 erwise.
15218 FindPNG
15220 Find libpng, the official reference library for the PNG image format.
15221 Imported targets
15223 New in version 3.5.
15224 This module defines the following IMPORTED target:
15227 PNG::PNG
15229 The libpng library, if found.
15230 Result variables
15232 This module will set the following variables in your project:
15233 PNG_INCLUDE_DIRS
15235 where to find png.h, etc.
15236 PNG_LIBRARIES
15238 the libraries to link against to use PNG.
15239 PNG_DEFINITIONS
15241 You should add_definitions(${PNG_DEFINITIONS}) before compiling
15242 code that includes png library files.
15243 PNG_FOUND
15245 If false, do not try to use PNG.
15246 PNG_VERSION_STRING
15248 the version of the PNG library found (since CMake 2.8.8)
15249 Obsolete variables
15251 The following variables may also be set, for backwards compatibility:
15252 PNG_LIBRARY
15254 where to find the PNG library.
15255 PNG_INCLUDE_DIR
15257 where to find the PNG headers (same as PNG_INCLUDE_DIRS)
15258 Since PNG depends on the ZLib compression library, none of the above
15260 will be defined unless ZLib can be found.
15261 FindPostgreSQL
15263 Find the PostgreSQL installation.
15264 IMPORTED Targets
15266 New in version 3.14.
15267 This module defines IMPORTED target PostgreSQL::PostgreSQL if Post‐
15270 greSQL has been found.
15271 Result Variables
15273 This module will set the following variables in your project:
15274 PostgreSQL_FOUND
15276 True if PostgreSQL is found.
15277 PostgreSQL_LIBRARIES
15279 the PostgreSQL libraries needed for linking
15280 PostgreSQL_INCLUDE_DIRS
15282 the directories of the PostgreSQL headers
15283 PostgreSQL_LIBRARY_DIRS
15285 the link directories for PostgreSQL libraries
15286 PostgreSQL_VERSION_STRING
15288 the version of PostgreSQL found
15289 PostgreSQL_TYPE_INCLUDE_DIR
15291 the directories of the PostgreSQL server headers
15292 Components
15294 This module contains additional Server component, that forcibly checks
15295 for the presence of server headers. Note that PostgreSQL_TYPE_IN‐
15296 CLUDE_DIR is set regardless of the presence of the Server component in
15297 find_package call.
15298 FindProducer
15300 Though Producer isn't directly part of OpenSceneGraph, its primary user
15301 is OSG so I consider this part of the Findosg* suite used to find Open‐
15302 SceneGraph components. You'll notice that I accept OSGDIR as an envi‐
15303 ronment path.
15304 Each component is separate and you must opt in to each module. You
15306 must also opt into OpenGL (and OpenThreads?) as these modules won't do
15307 it for you. This is to allow you control over your own system piece by
15308 piece in case you need to opt out of certain components or change the
15309 Find behavior for a particular module (perhaps because the default
15310 FindOpenGL.cmake module doesn't work with your system as an example).
15311 If you want to use a more convenient module that includes everything,
15312 use the FindOpenSceneGraph.cmake instead of the Findosg*.cmake modules.
15313 Locate Producer This module defines PRODUCER_LIBRARY PRODUCER_FOUND, if
15315 false, do not try to link to Producer PRODUCER_INCLUDE_DIR, where to
15316 find the headers
15317 $PRODUCER_DIR is an environment variable that would correspond to the
15319 ./configure --prefix=$PRODUCER_DIR used in building osg.
15320 Created by Eric Wing.
15322 FindProtobuf
15324 Locate and configure the Google Protocol Buffers library.
15325 New in version 3.6: Support for find_package() version checks.
15327 Changed in version 3.6: All input and output variables use the Proto‐
15330 buf_ prefix. Variables with PROTOBUF_ prefix are still supported for
15331 compatibility.
15332 The following variables can be set and are optional:
15335 Protobuf_SRC_ROOT_FOLDER
15337 When compiling with MSVC, if this cache variable is set the pro‐
15338 tobuf-default VS project build locations (vsprojects/Debug and
15339 vsprojects/Release or vsprojects/x64/Debug and vspro‐
15340 jects/x64/Release) will be searched for libraries and binaries.
15341 Protobuf_IMPORT_DIRS
15343 List of additional directories to be searched for imported
15344 .proto files.
15345 Protobuf_DEBUG
15347 New in version 3.6.
15348 Show debug messages.
15351 Protobuf_USE_STATIC_LIBS
15353 New in version 3.9.
15354 Set to ON to force the use of the static libraries. Default is
15357 OFF.
15358 Defines the following variables:
15360 Protobuf_FOUND
15362 Found the Google Protocol Buffers library (libprotobuf & header
15363 files)
15364 Protobuf_VERSION
15366 New in version 3.6.
15367 Version of package found.
15370 Protobuf_INCLUDE_DIRS
15372 Include directories for Google Protocol Buffers
15373 Protobuf_LIBRARIES
15375 The protobuf libraries
15376 Protobuf_PROTOC_LIBRARIES
15378 The protoc libraries
15379 Protobuf_LITE_LIBRARIES
15381 The protobuf-lite libraries
15382 New in version 3.9: The following IMPORTED targets are also defined:
15384 protobuf::libprotobuf
15387 The protobuf library.
15388 protobuf::libprotobuf-lite
15390 The protobuf lite library.
15391 protobuf::libprotoc
15393 The protoc library.
15394 protobuf::protoc
15396 New in version 3.10: The protoc compiler.
15397 The following cache variables are also available to set or use:
15400 Protobuf_LIBRARY
15402 The protobuf library
15403 Protobuf_PROTOC_LIBRARY
15405 The protoc library
15406 Protobuf_INCLUDE_DIR
15408 The include directory for protocol buffers
15409 Protobuf_PROTOC_EXECUTABLE
15411 The protoc compiler
15412 Protobuf_LIBRARY_DEBUG
15414 The protobuf library (debug)
15415 Protobuf_PROTOC_LIBRARY_DEBUG
15417 The protoc library (debug)
15418 Protobuf_LITE_LIBRARY
15420 The protobuf lite library
15421 Protobuf_LITE_LIBRARY_DEBUG
15423 The protobuf lite library (debug)
15424 Example:
15426 find_package(Protobuf REQUIRED)
15428 include_directories(${Protobuf_INCLUDE_DIRS})
15429 include_directories(${CMAKE_CURRENT_BINARY_DIR})
15430 protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS foo.proto)
15431 protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS EXPORT_MACRO DLL_EXPORT foo.proto)
15432 protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS DESCRIPTORS PROTO_DESCS foo.proto)
15433 protobuf_generate_python(PROTO_PY foo.proto)
15434 add_executable(bar bar.cc ${PROTO_SRCS} ${PROTO_HDRS})
15435 target_link_libraries(bar ${Protobuf_LIBRARIES})
15436 NOTE:
15438 The protobuf_generate_cpp and protobuf_generate_python functions and
15439 add_executable() or add_library() calls only work properly within
15440 the same directory.
15441 protobuf_generate_cpp
15443 Add custom commands to process .proto files to C++:
15444 protobuf_generate_cpp (<SRCS> <HDRS>
15446 [DESCRIPTORS <DESC>] [EXPORT_MACRO <MACRO>] [<ARGN>...])
15447 SRCS Variable to define with autogenerated source files
15449 HDRS Variable to define with autogenerated header files
15451 DESCRIPTORS
15453 New in version 3.10: Variable to define with autogener‐
15454 ated descriptor files, if requested.
15455 EXPORT_MACRO
15458 is a macro which should expand to __declspec(dllexport)
15459 or __declspec(dllimport) depending on what is being com‐
15460 piled.
15461 ARGN .proto files
15463 protobuf_generate_python
15465 New in version 3.4.
15466 Add custom commands to process .proto files to Python:
15469 protobuf_generate_python (<PY> [<ARGN>...])
15471 PY Variable to define with autogenerated Python files
15473 ARGN .proto files
15475 FindPython
15477 New in version 3.12.
15478 Find Python interpreter, compiler and development environment (include
15481 directories and libraries).
15482 New in version 3.19: When a version is requested, it can be specified
15484 as a simple value or as a range. For a detailed description of version
15485 range usage and capabilities, refer to the find_package() command.
15486 The following components are supported:
15489 • Interpreter: search for Python interpreter.
15491 • Compiler: search for Python compiler. Only offered by IronPython.
15493 • Development: search for development artifacts (include directories
15495 and libraries).
15496 New in version 3.18: This component includes two sub-components which
15498 can be specified independently:
15499 • Development.Module: search for artifacts for Python module develop‐
15501 ments.
15502 • Development.Embed: search for artifacts for Python embedding devel‐
15504 opments.
15505 • NumPy: search for NumPy include directories.
15508 New in version 3.14: Added the NumPy component.
15510 If no COMPONENTS are specified, Interpreter is assumed.
15513 If component Development is specified, it implies sub-components Devel‐
15515 opment.Module and Development.Embed.
15516 To ensure consistent versions between components Interpreter, Compiler,
15518 Development (or one of its sub-components) and NumPy, specify all com‐
15519 ponents at the same time:
15520 find_package (Python COMPONENTS Interpreter Development)
15522 This module looks preferably for version 3 of Python. If not found,
15524 version 2 is searched. To manage concurrent versions 3 and 2 of
15525 Python, use FindPython3 and FindPython2 modules rather than this one.
15526 NOTE:
15528 If components Interpreter and Development (or one of its sub-compo‐
15529 nents) are both specified, this module search only for interpreter
15530 with same platform architecture as the one defined by CMake configu‐
15531 ration. This constraint does not apply if only Interpreter component
15532 is specified.
15533 Imported Targets
15535 This module defines the following Imported Targets:
15536 Changed in version 3.14: Imported Targets are only created when
15538 CMAKE_ROLE is PROJECT.
15539 Python::Interpreter
15542 Python interpreter. Target defined if component Interpreter is
15543 found.
15544 Python::Compiler
15546 Python compiler. Target defined if component Compiler is found.
15547 Python::Module
15549 New in version 3.15.
15550 Python library for Python module. Target defined if component
15553 Development.Module is found.
15554 Python::Python
15556 Python library for Python embedding. Target defined if component
15557 Development.Embed is found.
15558 Python::NumPy
15560 New in version 3.14.
15561 NumPy Python library. Target defined if component NumPy is
15564 found.
15565 Result Variables
15567 This module will set the following variables in your project (see Stan‐
15568 dard Variable Names):
15569 Python_FOUND
15571 System has the Python requested components.
15572 Python_Interpreter_FOUND
15574 System has the Python interpreter.
15575 Python_EXECUTABLE
15577 Path to the Python interpreter.
15578 Python_INTERPRETER_ID
15580 A short string unique to the interpreter. Possible values in‐
15582 clude:
15583 • Python
15585 • ActivePython
15587 • Anaconda
15589 • Canopy
15591 • IronPython
15593 • PyPy
15595 Python_STDLIB
15597 Standard platform independent installation directory.
15598 Information returned by distutils.syscon‐
15600 fig.get_python_lib(plat_specific=False,standard_lib=True) or
15601 else sysconfig.get_path('stdlib').
15602 Python_STDARCH
15604 Standard platform dependent installation directory.
15605 Information returned by distutils.syscon‐
15607 fig.get_python_lib(plat_specific=True,standard_lib=True) or else
15608 sysconfig.get_path('platstdlib').
15609 Python_SITELIB
15611 Third-party platform independent installation directory.
15612 Information returned by distutils.syscon‐
15614 fig.get_python_lib(plat_specific=False,standard_lib=False) or
15615 else sysconfig.get_path('purelib').
15616 Python_SITEARCH
15618 Third-party platform dependent installation directory.
15619 Information returned by distutils.syscon‐
15621 fig.get_python_lib(plat_specific=True,standard_lib=False) or
15622 else sysconfig.get_path('platlib').
15623 Python_SOABI
15625 New in version 3.17.
15626 Extension suffix for modules.
15629 Information returned by distutils.sysconfig.get_con‐
15631 fig_var('SOABI') or computed from distutils.sysconfig.get_con‐
15632 fig_var('EXT_SUFFIX') or python-config --extension-suffix. If
15633 package distutils.sysconfig is not available, sysconfig.get_con‐
15634 fig_var('SOABI') or sysconfig.get_config_var('EXT_SUFFIX') are
15635 used.
15636 Python_Compiler_FOUND
15638 System has the Python compiler.
15639 Python_COMPILER
15641 Path to the Python compiler. Only offered by IronPython.
15642 Python_COMPILER_ID
15644 A short string unique to the compiler. Possible values include:
15646 • IronPython
15648 Python_DOTNET_LAUNCHER
15650 New in version 3.18.
15651 The .Net interpreter. Only used by IronPython implementation.
15654 Python_Development_FOUND
15656 System has the Python development artifacts.
15657 Python_Development.Module_FOUND
15659 New in version 3.18.
15660 System has the Python development artifacts for Python module.
15663 Python_Development.Embed_FOUND
15665 New in version 3.18.
15666 System has the Python development artifacts for Python embed‐
15669 ding.
15670 Python_INCLUDE_DIRS
15672 The Python include directories.
15673 Python_LINK_OPTIONS
15675 New in version 3.19.
15676 The Python link options. Some configurations require specific
15679 link options for a correct build and execution.
15680 Python_LIBRARIES
15682 The Python libraries.
15683 Python_LIBRARY_DIRS
15685 The Python library directories.
15686 Python_RUNTIME_LIBRARY_DIRS
15688 The Python runtime library directories.
15689 Python_VERSION
15691 Python version.
15692 Python_VERSION_MAJOR
15694 Python major version.
15695 Python_VERSION_MINOR
15697 Python minor version.
15698 Python_VERSION_PATCH
15700 Python patch version.
15701 Python_PyPy_VERSION
15703 New in version 3.18.
15704 Python PyPy version.
15707 Python_NumPy_FOUND
15709 New in version 3.14.
15710 System has the NumPy.
15713 Python_NumPy_INCLUDE_DIRS
15715 New in version 3.14.
15716 The NumPy include directories.
15719 Python_NumPy_VERSION
15721 New in version 3.14.
15722 The NumPy version.
15725 Hints
15727 Python_ROOT_DIR
15728 Define the root directory of a Python installation.
15729 Python_USE_STATIC_LIBS
15731 • If not defined, search for shared libraries and static li‐
15733 braries in that order.
15734 • If set to TRUE, search only for static libraries.
15736 • If set to FALSE, search only for shared libraries.
15738 Python_FIND_ABI
15740 New in version 3.16.
15741 This variable defines which ABIs, as defined in PEP 3149, should
15744 be searched.
15745 NOTE:
15747 This hint will be honored only when searched for Python ver‐
15748 sion 3.
15749 NOTE:
15751 If Python_FIND_ABI is not defined, any ABI will be searched.
15752 The Python_FIND_ABI variable is a 3-tuple specifying, in that
15754 order, pydebug (d), pymalloc (m) and unicode (u) flags. Each
15755 element can be set to one of the following:
15756 • ON: Corresponding flag is selected.
15758 • OFF: Corresponding flag is not selected.
15760 • ANY: The two possibilities (ON and OFF) will be searched.
15762 From this 3-tuple, various ABIs will be searched starting from
15764 the most specialized to the most general. Moreover, debug ver‐
15765 sions will be searched after non-debug ones.
15766 For example, if we have:
15768 set (Python_FIND_ABI "ON" "ANY" "ANY")
15770 The following flags combinations will be appended, in that or‐
15772 der, to the artifact names: dmu, dm, du, and d.
15773 And to search any possible ABIs:
15775 set (Python_FIND_ABI "ANY" "ANY" "ANY")
15777 The following combinations, in that order, will be used: mu, m,
15779 u, <empty>, dmu, dm, du and d.
15780 NOTE:
15782 This hint is useful only on POSIX systems. So, on Windows
15783 systems, when Python_FIND_ABI is defined, Python distribu‐
15784 tions from python.org will be found only if value for each
15785 flag is OFF or ANY.
15786 Python_FIND_STRATEGY
15788 New in version 3.15.
15789 This variable defines how lookup will be done. The
15792 Python_FIND_STRATEGY variable can be set to one of the follow‐
15793 ing:
15794 • VERSION: Try to find the most recent version in all specified
15796 locations. This is the default if policy CMP0094 is undefined
15797 or set to OLD.
15798 • LOCATION: Stops lookup as soon as a version satisfying version
15800 constraints is founded. This is the default if policy CMP0094
15801 is set to NEW.
15802 Python_FIND_REGISTRY
15804 New in version 3.13.
15805 On Windows the Python_FIND_REGISTRY variable determine the order
15808 of preference between registry and environment variables. the
15809 Python_FIND_REGISTRY variable can be set to one of the follow‐
15810 ing:
15811 • FIRST: Try to use registry before environment variables. This
15813 is the default.
15814 • LAST: Try to use registry after environment variables.
15816 • NEVER: Never try to use registry.
15818 Python_FIND_FRAMEWORK
15820 New in version 3.15.
15821 On macOS the Python_FIND_FRAMEWORK variable determine the order
15824 of preference between Apple-style and unix-style package compo‐
15825 nents. This variable can take same values as CMAKE_FIND_FRAME‐
15826 WORK variable.
15827 NOTE:
15829 Value ONLY is not supported so FIRST will be used instead.
15830 If Python_FIND_FRAMEWORK is not defined, CMAKE_FIND_FRAMEWORK
15832 variable will be used, if any.
15833 Python_FIND_VIRTUALENV
15835 New in version 3.15.
15836 This variable defines the handling of virtual environments man‐
15839 aged by virtualenv or conda. It is meaningful only when a vir‐
15840 tual environment is active (i.e. the activate script has been
15841 evaluated). In this case, it takes precedence over
15842 Python_FIND_REGISTRY and CMAKE_FIND_FRAMEWORK variables. The
15843 Python_FIND_VIRTUALENV variable can be set to one of the follow‐
15844 ing:
15845 • FIRST: The virtual environment is used before any other stan‐
15847 dard paths to look-up for the interpreter. This is the de‐
15848 fault.
15849 • ONLY: Only the virtual environment is used to look-up for the
15851 interpreter.
15852 • STANDARD: The virtual environment is not used to look-up for
15854 the interpreter but environment variable PATH is always con‐
15855 sidered. In this case, variable Python_FIND_REGISTRY (Win‐
15856 dows) or CMAKE_FIND_FRAMEWORK (macOS) can be set with value
15857 LAST or NEVER to select preferably the interpreter from the
15858 virtual environment.
15859 New in version 3.17: Added support for conda environments.
15861 NOTE:
15864 If the component Development is requested, it is strongly
15865 recommended to also include the component Interpreter to get
15866 expected result.
15867 Python_FIND_IMPLEMENTATIONS
15869 New in version 3.18.
15870 This variable defines, in an ordered list, the different imple‐
15873 mentations which will be searched. The Python_FIND_IMPLEMENTA‐
15874 TIONS variable can hold the following values:
15875 • CPython: this is the standard implementation. Various prod‐
15877 ucts, like Anaconda or ActivePython, rely on this implementa‐
15878 tion.
15879 • IronPython: This implementation use the CSharp language for
15881 .NET Framework on top of the Dynamic Language Runtime (DLR).
15882 See IronPython.
15883 • PyPy: This implementation use RPython language and RPython
15885 translation toolchain to produce the python interpreter. See
15886 PyPy.
15887 The default value is:
15889 • Windows platform: CPython, IronPython
15891 • Other platforms: CPython
15893 NOTE:
15895 This hint has the lowest priority of all hints, so even if,
15896 for example, you specify IronPython first and CPython in sec‐
15897 ond, a python product based on CPython can be selected be‐
15898 cause, for example with Python_FIND_STRATEGY=LOCATION, each
15899 location will be search first for IronPython and second for
15900 CPython.
15901 NOTE:
15903 When IronPython is specified, on platforms other than Win‐
15904 dows, the .Net interpreter (i.e. mono command) is expected to
15905 be available through the PATH variable.
15906 Python_FIND_UNVERSIONED_NAMES
15908 New in version 3.20.
15909 This variable defines how the generic names will be searched.
15912 Currently, it only applies to the generic names of the inter‐
15913 preter, namely, python3 or python2 and python. The
15914 Python_FIND_UNVERSIONED_NAMES variable can be set to one of the
15915 following values:
15916 • FIRST: The generic names are searched before the more special‐
15918 ized ones (such as python2.5 for example).
15919 • LAST: The generic names are searched after the more special‐
15921 ized ones. This is the default.
15922 • NEVER: The generic name are not searched at all.
15924 Artifacts Specification
15926 New in version 3.16.
15927 To solve special cases, it is possible to specify directly the arti‐
15930 facts by setting the following variables:
15931 Python_EXECUTABLE
15933 The path to the interpreter.
15934 Python_COMPILER
15936 The path to the compiler.
15937 Python_DOTNET_LAUNCHER
15939 New in version 3.18.
15940 The .Net interpreter. Only used by IronPython implementation.
15943 Python_LIBRARY
15945 The path to the library. It will be used to compute the vari‐
15946 ables Python_LIBRARIES, Python_LIBRARY_DIRS and Python_RUN‐
15947 TIME_LIBRARY_DIRS.
15948 Python_INCLUDE_DIR
15950 The path to the directory of the Python headers. It will be used
15951 to compute the variable Python_INCLUDE_DIRS.
15952 Python_NumPy_INCLUDE_DIR
15954 The path to the directory of the NumPy headers. It will be used
15955 to compute the variable Python_NumPy_INCLUDE_DIRS.
15956 NOTE:
15958 All paths must be absolute. Any artifact specified with a relative
15959 path will be ignored.
15960 NOTE:
15962 When an artifact is specified, all HINTS will be ignored and no
15963 search will be performed for this artifact.
15964 If more than one artifact is specified, it is the user's responsi‐
15966 bility to ensure the consistency of the various artifacts.
15967 By default, this module supports multiple calls in different directo‐
15969 ries of a project with different version/component requirements while
15970 providing correct and consistent results for each call. To support this
15971 behavior, CMake cache is not used in the traditional way which can be
15972 problematic for interactive specification. So, to enable also interac‐
15973 tive specification, module behavior can be controlled with the follow‐
15974 ing variable:
15975 Python_ARTIFACTS_INTERACTIVE
15977 New in version 3.18.
15978 Selects the behavior of the module. This is a boolean variable:
15981 • If set to TRUE: Create CMake cache entries for the above arti‐
15983 fact specification variables so that users can edit them in‐
15984 teractively. This disables support for multiple version/com‐
15985 ponent requirements.
15986 • If set to FALSE or undefined: Enable multiple version/compo‐
15988 nent requirements.
15989 Commands
15991 This module defines the command Python_add_library (when CMAKE_ROLE is
15992 PROJECT), which has the same semantics as add_library() and adds a de‐
15993 pendency to target Python::Python or, when library type is MODULE, to
15994 target Python::Module and takes care of Python module naming rules:
15995 Python_add_library (<name> [STATIC | SHARED | MODULE [WITH_SOABI]]
15997 <source1> [<source2> ...])
15998 If the library type is not specified, MODULE is assumed.
16000 New in version 3.17: For MODULE library type, if option WITH_SOABI is
16002 specified, the module suffix will include the Python_SOABI value, if
16003 any.
16004 FindPython2
16007 New in version 3.12.
16008 Find Python 2 interpreter, compiler and development environment (in‐
16011 clude directories and libraries).
16012 New in version 3.19: When a version is requested, it can be specified
16014 as a simple value or as a range. For a detailed description of version
16015 range usage and capabilities, refer to the find_package() command.
16016 The following components are supported:
16019 • Interpreter: search for Python 2 interpreter
16021 • Compiler: search for Python 2 compiler. Only offered by IronPython.
16023 • Development: search for development artifacts (include directories
16025 and libraries).
16026 New in version 3.18: This component includes two sub-components which
16028 can be specified independently:
16029 • Development.Module: search for artifacts for Python 2 module devel‐
16031 opments.
16032 • Development.Embed: search for artifacts for Python 2 embedding de‐
16034 velopments.
16035 • NumPy: search for NumPy include directories.
16038 New in version 3.14: Added the NumPy component.
16040 If no COMPONENTS are specified, Interpreter is assumed.
16043 If component Development is specified, it implies sub-components Devel‐
16045 opment.Module and Development.Embed.
16046 To ensure consistent versions between components Interpreter, Compiler,
16048 Development (or one of its sub-components) and NumPy, specify all com‐
16049 ponents at the same time:
16050 find_package (Python2 COMPONENTS Interpreter Development)
16052 This module looks only for version 2 of Python. This module can be used
16054 concurrently with FindPython3 module to use both Python versions.
16055 The FindPython module can be used if Python version does not matter for
16057 you.
16058 NOTE:
16060 If components Interpreter and Development (or one of its sub-compo‐
16061 nents) are both specified, this module search only for interpreter
16062 with same platform architecture as the one defined by CMake configu‐
16063 ration. This constraint does not apply if only Interpreter component
16064 is specified.
16065 Imported Targets
16067 This module defines the following Imported Targets:
16068 Changed in version 3.14: Imported Targets are only created when
16070 CMAKE_ROLE is PROJECT.
16071 Python2::Interpreter
16074 Python 2 interpreter. Target defined if component Interpreter is
16075 found.
16076 Python2::Compiler
16078 Python 2 compiler. Target defined if component Compiler is
16079 found.
16080 Python2::Module
16082 New in version 3.15.
16083 Python 2 library for Python module. Target defined if component
16086 Development.Module is found.
16087 Python2::Python
16089 Python 2 library for Python embedding. Target defined if compo‐
16090 nent Development.Embed is found.
16091 Python2::NumPy
16093 New in version 3.14.
16094 NumPy library for Python 2. Target defined if component NumPy is
16097 found.
16098 Result Variables
16100 This module will set the following variables in your project (see Stan‐
16101 dard Variable Names):
16102 Python2_FOUND
16104 System has the Python 2 requested components.
16105 Python2_Interpreter_FOUND
16107 System has the Python 2 interpreter.
16108 Python2_EXECUTABLE
16110 Path to the Python 2 interpreter.
16111 Python2_INTERPRETER_ID
16113 A short string unique to the interpreter. Possible values in‐
16115 clude:
16116 • Python
16118 • ActivePython
16120 • Anaconda
16122 • Canopy
16124 • IronPython
16126 • PyPy
16128 Python2_STDLIB
16130 Standard platform independent installation directory.
16131 Information returned by distutils.syscon‐
16133 fig.get_python_lib(plat_specific=False,standard_lib=True) or
16134 else sysconfig.get_path('stdlib').
16135 Python2_STDARCH
16137 Standard platform dependent installation directory.
16138 Information returned by distutils.syscon‐
16140 fig.get_python_lib(plat_specific=True,standard_lib=True) or else
16141 sysconfig.get_path('platstdlib').
16142 Python2_SITELIB
16144 Third-party platform independent installation directory.
16145 Information returned by distutils.syscon‐
16147 fig.get_python_lib(plat_specific=False,standard_lib=False) or
16148 else sysconfig.get_path('purelib').
16149 Python2_SITEARCH
16151 Third-party platform dependent installation directory.
16152 Information returned by distutils.syscon‐
16154 fig.get_python_lib(plat_specific=True,standard_lib=False) or
16155 else sysconfig.get_path('platlib').
16156 Python2_Compiler_FOUND
16158 System has the Python 2 compiler.
16159 Python2_COMPILER
16161 Path to the Python 2 compiler. Only offered by IronPython.
16162 Python2_COMPILER_ID
16164 A short string unique to the compiler. Possible values include:
16166 • IronPython
16168 Python2_DOTNET_LAUNCHER
16170 New in version 3.18.
16171 The .Net interpreter. Only used by IronPython implementation.
16174 Python2_Development_FOUND
16176 System has the Python 2 development artifacts.
16177 Python2_Development.Module_FOUND
16179 New in version 3.18.
16180 System has the Python 2 development artifacts for Python module.
16183 Python2_Development.Embed_FOUND
16185 New in version 3.18.
16186 System has the Python 2 development artifacts for Python embed‐
16189 ding.
16190 Python2_INCLUDE_DIRS
16192 The Python 2 include directories.
16193 Python2_LINK_OPTIONS
16195 New in version 3.19.
16196 The Python 2 link options. Some configurations require specific
16199 link options for a correct build and execution.
16200 Python2_LIBRARIES
16202 The Python 2 libraries.
16203 Python2_LIBRARY_DIRS
16205 The Python 2 library directories.
16206 Python2_RUNTIME_LIBRARY_DIRS
16208 The Python 2 runtime library directories.
16209 Python2_VERSION
16211 Python 2 version.
16212 Python2_VERSION_MAJOR
16214 Python 2 major version.
16215 Python2_VERSION_MINOR
16217 Python 2 minor version.
16218 Python2_VERSION_PATCH
16220 Python 2 patch version.
16221 Python2_PyPy_VERSION
16223 New in version 3.18.
16224 Python 2 PyPy version.
16227 Python2_NumPy_FOUND
16229 New in version 3.14.
16230 System has the NumPy.
16233 Python2_NumPy_INCLUDE_DIRS
16235 New in version 3.14.
16236 The NumPy include directories.
16239 Python2_NumPy_VERSION
16241 New in version 3.14.
16242 The NumPy version.
16245 Hints
16247 Python2_ROOT_DIR
16248 Define the root directory of a Python 2 installation.
16249 Python2_USE_STATIC_LIBS
16251 • If not defined, search for shared libraries and static li‐
16253 braries in that order.
16254 • If set to TRUE, search only for static libraries.
16256 • If set to FALSE, search only for shared libraries.
16258 Python2_FIND_STRATEGY
16260 New in version 3.15.
16261 This variable defines how lookup will be done. The
16264 Python2_FIND_STRATEGY variable can be set to one of the follow‐
16265 ing:
16266 • VERSION: Try to find the most recent version in all specified
16268 locations. This is the default if policy CMP0094 is undefined
16269 or set to OLD.
16270 • LOCATION: Stops lookup as soon as a version satisfying version
16272 constraints is founded. This is the default if policy CMP0094
16273 is set to NEW.
16274 Python2_FIND_REGISTRY
16276 New in version 3.13.
16277 On Windows the Python2_FIND_REGISTRY variable determine the or‐
16280 der of preference between registry and environment variables.
16281 the Python2_FIND_REGISTRY variable can be set to one of the fol‐
16282 lowing:
16283 • FIRST: Try to use registry before environment variables. This
16285 is the default.
16286 • LAST: Try to use registry after environment variables.
16288 • NEVER: Never try to use registry.
16290 Python2_FIND_FRAMEWORK
16292 New in version 3.15.
16293 On macOS the Python2_FIND_FRAMEWORK variable determine the order
16296 of preference between Apple-style and unix-style package compo‐
16297 nents. This variable can take same values as CMAKE_FIND_FRAME‐
16298 WORK variable.
16299 NOTE:
16301 Value ONLY is not supported so FIRST will be used instead.
16302 If Python2_FIND_FRAMEWORK is not defined, CMAKE_FIND_FRAMEWORK
16304 variable will be used, if any.
16305 Python2_FIND_VIRTUALENV
16307 New in version 3.15.
16308 This variable defines the handling of virtual environments man‐
16311 aged by virtualenv or conda. It is meaningful only when a vir‐
16312 tual environment is active (i.e. the activate script has been
16313 evaluated). In this case, it takes precedence over
16314 Python2_FIND_REGISTRY and CMAKE_FIND_FRAMEWORK variables. The
16315 Python2_FIND_VIRTUALENV variable can be set to one of the fol‐
16316 lowing:
16317 • FIRST: The virtual environment is used before any other stan‐
16319 dard paths to look-up for the interpreter. This is the de‐
16320 fault.
16321 • ONLY: Only the virtual environment is used to look-up for the
16323 interpreter.
16324 • STANDARD: The virtual environment is not used to look-up for
16326 the interpreter but environment variable PATH is always con‐
16327 sidered. In this case, variable Python2_FIND_REGISTRY (Win‐
16328 dows) or CMAKE_FIND_FRAMEWORK (macOS) can be set with value
16329 LAST or NEVER to select preferably the interpreter from the
16330 virtual environment.
16331 New in version 3.17: Added support for conda environments.
16333 NOTE:
16336 If the component Development is requested, it is strongly
16337 recommended to also include the component Interpreter to get
16338 expected result.
16339 Python2_FIND_IMPLEMENTATIONS
16341 New in version 3.18.
16342 This variable defines, in an ordered list, the different imple‐
16345 mentations which will be searched. The Python2_FIND_IMPLEMENTA‐
16346 TIONS variable can hold the following values:
16347 • CPython: this is the standard implementation. Various prod‐
16349 ucts, like Anaconda or ActivePython, rely on this implementa‐
16350 tion.
16351 • IronPython: This implementation use the CSharp language for
16353 .NET Framework on top of the Dynamic Language Runtime (DLR).
16354 See IronPython.
16355 • PyPy: This implementation use RPython language and RPython
16357 translation toolchain to produce the python interpreter. See
16358 PyPy.
16359 The default value is:
16361 • Windows platform: CPython, IronPython
16363 • Other platforms: CPython
16365 NOTE:
16367 This hint has the lowest priority of all hints, so even if,
16368 for example, you specify IronPython first and CPython in sec‐
16369 ond, a python product based on CPython can be selected be‐
16370 cause, for example with Python2_FIND_STRATEGY=LOCATION, each
16371 location will be search first for IronPython and second for
16372 CPython.
16373 NOTE:
16375 When IronPython is specified, on platforms other than Win‐
16376 dows, the .Net interpreter (i.e. mono command) is expected to
16377 be available through the PATH variable.
16378 Python2_FIND_UNVERSIONED_NAMES
16380 New in version 3.20.
16381 This variable defines how the generic names will be searched.
16384 Currently, it only applies to the generic names of the inter‐
16385 preter, namely, python2 and python. The Python2_FIND_UNVER‐
16386 SIONED_NAMES variable can be set to one of the following values:
16387 • FIRST: The generic names are searched before the more special‐
16389 ized ones (such as python2.5 for example).
16390 • LAST: The generic names are searched after the more special‐
16392 ized ones. This is the default.
16393 • NEVER: The generic name are not searched at all.
16395 Artifacts Specification
16397 New in version 3.16.
16398 To solve special cases, it is possible to specify directly the arti‐
16401 facts by setting the following variables:
16402 Python2_EXECUTABLE
16404 The path to the interpreter.
16405 Python2_COMPILER
16407 The path to the compiler.
16408 Python2_DOTNET_LAUNCHER
16410 New in version 3.18.
16411 The .Net interpreter. Only used by IronPython implementation.
16414 Python2_LIBRARY
16416 The path to the library. It will be used to compute the vari‐
16417 ables Python2_LIBRARIES, Python2_LIBRARY_DIRS and Python2_RUN‐
16418 TIME_LIBRARY_DIRS.
16419 Python2_INCLUDE_DIR
16421 The path to the directory of the Python headers. It will be used
16422 to compute the variable Python2_INCLUDE_DIRS.
16423 Python2_NumPy_INCLUDE_DIR
16425 The path to the directory of the NumPy headers. It will be used
16426 to compute the variable Python2_NumPy_INCLUDE_DIRS.
16427 NOTE:
16429 All paths must be absolute. Any artifact specified with a relative
16430 path will be ignored.
16431 NOTE:
16433 When an artifact is specified, all HINTS will be ignored and no
16434 search will be performed for this artifact.
16435 If more than one artifact is specified, it is the user's responsi‐
16437 bility to ensure the consistency of the various artifacts.
16438 By default, this module supports multiple calls in different directo‐
16440 ries of a project with different version/component requirements while
16441 providing correct and consistent results for each call. To support this
16442 behavior, CMake cache is not used in the traditional way which can be
16443 problematic for interactive specification. So, to enable also interac‐
16444 tive specification, module behavior can be controlled with the follow‐
16445 ing variable:
16446 Python2_ARTIFACTS_INTERACTIVE
16448 New in version 3.18.
16449 Selects the behavior of the module. This is a boolean variable:
16452 • If set to TRUE: Create CMake cache entries for the above arti‐
16454 fact specification variables so that users can edit them in‐
16455 teractively. This disables support for multiple version/com‐
16456 ponent requirements.
16457 • If set to FALSE or undefined: Enable multiple version/compo‐
16459 nent requirements.
16460 Commands
16462 This module defines the command Python2_add_library (when CMAKE_ROLE is
16463 PROJECT), which has the same semantics as add_library() and adds a de‐
16464 pendency to target Python2::Python or, when library type is MODULE, to
16465 target Python2::Module and takes care of Python module naming rules:
16466 Python2_add_library (<name> [STATIC | SHARED | MODULE]
16468 <source1> [<source2> ...])
16469 If library type is not specified, MODULE is assumed.
16471 FindPython3
16473 New in version 3.12.
16474 Find Python 3 interpreter, compiler and development environment (in‐
16477 clude directories and libraries).
16478 New in version 3.19: When a version is requested, it can be specified
16480 as a simple value or as a range. For a detailed description of version
16481 range usage and capabilities, refer to the find_package() command.
16482 The following components are supported:
16485 • Interpreter: search for Python 3 interpreter
16487 • Compiler: search for Python 3 compiler. Only offered by IronPython.
16489 • Development: search for development artifacts (include directories
16491 and libraries).
16492 New in version 3.18: This component includes two sub-components which
16494 can be specified independently:
16495 • Development.Module: search for artifacts for Python 3 module devel‐
16497 opments.
16498 • Development.Embed: search for artifacts for Python 3 embedding de‐
16500 velopments.
16501 • NumPy: search for NumPy include directories.
16504 New in version 3.14: Added the NumPy component.
16506 If no COMPONENTS are specified, Interpreter is assumed.
16509 If component Development is specified, it implies sub-components Devel‐
16511 opment.Module and Development.Embed.
16512 To ensure consistent versions between components Interpreter, Compiler,
16514 Development (or one of its sub-components) and NumPy, specify all com‐
16515 ponents at the same time:
16516 find_package (Python3 COMPONENTS Interpreter Development)
16518 This module looks only for version 3 of Python. This module can be used
16520 concurrently with FindPython2 module to use both Python versions.
16521 The FindPython module can be used if Python version does not matter for
16523 you.
16524 NOTE:
16526 If components Interpreter and Development (or one of its sub-compo‐
16527 nents) are both specified, this module search only for interpreter
16528 with same platform architecture as the one defined by CMake configu‐
16529 ration. This constraint does not apply if only Interpreter component
16530 is specified.
16531 Imported Targets
16533 This module defines the following Imported Targets:
16534 Changed in version 3.14: Imported Targets are only created when
16536 CMAKE_ROLE is PROJECT.
16537 Python3::Interpreter
16540 Python 3 interpreter. Target defined if component Interpreter is
16541 found.
16542 Python3::Compiler
16544 Python 3 compiler. Target defined if component Compiler is
16545 found.
16546 Python3::Module
16548 New in version 3.15.
16549 Python 3 library for Python module. Target defined if component
16552 Development.Module is found.
16553 Python3::Python
16555 Python 3 library for Python embedding. Target defined if compo‐
16556 nent Development.Embed is found.
16557 Python3::NumPy
16559 New in version 3.14.
16560 NumPy library for Python 3. Target defined if component NumPy is
16563 found.
16564 Result Variables
16566 This module will set the following variables in your project (see Stan‐
16567 dard Variable Names):
16568 Python3_FOUND
16570 System has the Python 3 requested components.
16571 Python3_Interpreter_FOUND
16573 System has the Python 3 interpreter.
16574 Python3_EXECUTABLE
16576 Path to the Python 3 interpreter.
16577 Python3_INTERPRETER_ID
16579 A short string unique to the interpreter. Possible values in‐
16581 clude:
16582 • Python
16584 • ActivePython
16586 • Anaconda
16588 • Canopy
16590 • IronPython
16592 • PyPy
16594 Python3_STDLIB
16596 Standard platform independent installation directory.
16597 Information returned by distutils.syscon‐
16599 fig.get_python_lib(plat_specific=False,standard_lib=True) or
16600 else sysconfig.get_path('stdlib').
16601 Python3_STDARCH
16603 Standard platform dependent installation directory.
16604 Information returned by distutils.syscon‐
16606 fig.get_python_lib(plat_specific=True,standard_lib=True) or else
16607 sysconfig.get_path('platstdlib').
16608 Python3_SITELIB
16610 Third-party platform independent installation directory.
16611 Information returned by distutils.syscon‐
16613 fig.get_python_lib(plat_specific=False,standard_lib=False) or
16614 else sysconfig.get_path('purelib').
16615 Python3_SITEARCH
16617 Third-party platform dependent installation directory.
16618 Information returned by distutils.syscon‐
16620 fig.get_python_lib(plat_specific=True,standard_lib=False) or
16621 else sysconfig.get_path('platlib').
16622 Python3_SOABI
16624 New in version 3.17.
16625 Extension suffix for modules.
16628 Information returned by distutils.sysconfig.get_con‐
16630 fig_var('SOABI') or computed from distutils.sysconfig.get_con‐
16631 fig_var('EXT_SUFFIX') or python3-config --extension-suffix. If
16632 package distutils.sysconfig is not available, sysconfig.get_con‐
16633 fig_var('SOABI') or sysconfig.get_config_var('EXT_SUFFIX') are
16634 used.
16635 Python3_Compiler_FOUND
16637 System has the Python 3 compiler.
16638 Python3_COMPILER
16640 Path to the Python 3 compiler. Only offered by IronPython.
16641 Python3_COMPILER_ID
16643 A short string unique to the compiler. Possible values include:
16645 • IronPython
16647 Python3_DOTNET_LAUNCHER
16649 New in version 3.18.
16650 The .Net interpreter. Only used by IronPython implementation.
16653 Python3_Development_FOUND
16655 System has the Python 3 development artifacts.
16656 Python3_Development.Module_FOUND
16658 New in version 3.18.
16659 System has the Python 3 development artifacts for Python module.
16662 Python3_Development.Embed_FOUND
16664 New in version 3.18.
16665 System has the Python 3 development artifacts for Python embed‐
16668 ding.
16669 Python3_INCLUDE_DIRS
16671 The Python 3 include directories.
16672 Python3_LINK_OPTIONS
16674 New in version 3.19.
16675 The Python 3 link options. Some configurations require specific
16678 link options for a correct build and execution.
16679 Python3_LIBRARIES
16681 The Python 3 libraries.
16682 Python3_LIBRARY_DIRS
16684 The Python 3 library directories.
16685 Python3_RUNTIME_LIBRARY_DIRS
16687 The Python 3 runtime library directories.
16688 Python3_VERSION
16690 Python 3 version.
16691 Python3_VERSION_MAJOR
16693 Python 3 major version.
16694 Python3_VERSION_MINOR
16696 Python 3 minor version.
16697 Python3_VERSION_PATCH
16699 Python 3 patch version.
16700 Python3_PyPy_VERSION
16702 New in version 3.18.
16703 Python 3 PyPy version.
16706 Python3_NumPy_FOUND
16708 New in version 3.14.
16709 System has the NumPy.
16712 Python3_NumPy_INCLUDE_DIRS
16714 New in version 3.14.
16715 The NumPy include directories.
16718 Python3_NumPy_VERSION
16720 New in version 3.14.
16721 The NumPy version.
16724 Hints
16726 Python3_ROOT_DIR
16727 Define the root directory of a Python 3 installation.
16728 Python3_USE_STATIC_LIBS
16730 • If not defined, search for shared libraries and static li‐
16732 braries in that order.
16733 • If set to TRUE, search only for static libraries.
16735 • If set to FALSE, search only for shared libraries.
16737 Python3_FIND_ABI
16739 New in version 3.16.
16740 This variable defines which ABIs, as defined in PEP 3149, should
16743 be searched.
16744 NOTE:
16746 If Python3_FIND_ABI is not defined, any ABI will be searched.
16747 The Python3_FIND_ABI variable is a 3-tuple specifying, in that
16749 order, pydebug (d), pymalloc (m) and unicode (u) flags. Each
16750 element can be set to one of the following:
16751 • ON: Corresponding flag is selected.
16753 • OFF: Corresponding flag is not selected.
16755 • ANY: The two possibilities (ON and OFF) will be searched.
16757 From this 3-tuple, various ABIs will be searched starting from
16759 the most specialized to the most general. Moreover, debug ver‐
16760 sions will be searched after non-debug ones.
16761 For example, if we have:
16763 set (Python3_FIND_ABI "ON" "ANY" "ANY")
16765 The following flags combinations will be appended, in that or‐
16767 der, to the artifact names: dmu, dm, du, and d.
16768 And to search any possible ABIs:
16770 set (Python3_FIND_ABI "ANY" "ANY" "ANY")
16772 The following combinations, in that order, will be used: mu, m,
16774 u, <empty>, dmu, dm, du and d.
16775 NOTE:
16777 This hint is useful only on POSIX systems. So, on Windows
16778 systems, when Python3_FIND_ABI is defined, Python distribu‐
16779 tions from python.org will be found only if value for each
16780 flag is OFF or ANY.
16781 Python3_FIND_STRATEGY
16783 New in version 3.15.
16784 This variable defines how lookup will be done. The
16787 Python3_FIND_STRATEGY variable can be set to one of the follow‐
16788 ing:
16789 • VERSION: Try to find the most recent version in all specified
16791 locations. This is the default if policy CMP0094 is undefined
16792 or set to OLD.
16793 • LOCATION: Stops lookup as soon as a version satisfying version
16795 constraints is founded. This is the default if policy CMP0094
16796 is set to NEW.
16797 Python3_FIND_REGISTRY
16799 New in version 3.13.
16800 On Windows the Python3_FIND_REGISTRY variable determine the or‐
16803 der of preference between registry and environment variables.
16804 The Python3_FIND_REGISTRY variable can be set to one of the fol‐
16805 lowing:
16806 • FIRST: Try to use registry before environment variables. This
16808 is the default.
16809 • LAST: Try to use registry after environment variables.
16811 • NEVER: Never try to use registry.
16813 Python3_FIND_FRAMEWORK
16815 New in version 3.15.
16816 On macOS the Python3_FIND_FRAMEWORK variable determine the order
16819 of preference between Apple-style and unix-style package compo‐
16820 nents. This variable can take same values as CMAKE_FIND_FRAME‐
16821 WORK variable.
16822 NOTE:
16824 Value ONLY is not supported so FIRST will be used instead.
16825 If Python3_FIND_FRAMEWORK is not defined, CMAKE_FIND_FRAMEWORK
16827 variable will be used, if any.
16828 Python3_FIND_VIRTUALENV
16830 New in version 3.15.
16831 This variable defines the handling of virtual environments man‐
16834 aged by virtualenv or conda. It is meaningful only when a vir‐
16835 tual environment is active (i.e. the activate script has been
16836 evaluated). In this case, it takes precedence over
16837 Python3_FIND_REGISTRY and CMAKE_FIND_FRAMEWORK variables. The
16838 Python3_FIND_VIRTUALENV variable can be set to one of the fol‐
16839 lowing:
16840 • FIRST: The virtual environment is used before any other stan‐
16842 dard paths to look-up for the interpreter. This is the de‐
16843 fault.
16844 • ONLY: Only the virtual environment is used to look-up for the
16846 interpreter.
16847 • STANDARD: The virtual environment is not used to look-up for
16849 the interpreter but environment variable PATH is always con‐
16850 sidered. In this case, variable Python3_FIND_REGISTRY (Win‐
16851 dows) or CMAKE_FIND_FRAMEWORK (macOS) can be set with value
16852 LAST or NEVER to select preferably the interpreter from the
16853 virtual environment.
16854 New in version 3.17: Added support for conda environments.
16856 NOTE:
16859 If the component Development is requested, it is strongly
16860 recommended to also include the component Interpreter to get
16861 expected result.
16862 Python3_FIND_IMPLEMENTATIONS
16864 New in version 3.18.
16865 This variable defines, in an ordered list, the different imple‐
16868 mentations which will be searched. The Python3_FIND_IMPLEMENTA‐
16869 TIONS variable can hold the following values:
16870 • CPython: this is the standard implementation. Various prod‐
16872 ucts, like Anaconda or ActivePython, rely on this implementa‐
16873 tion.
16874 • IronPython: This implementation use the CSharp language for
16876 .NET Framework on top of the Dynamic Language Runtime (DLR).
16877 See IronPython.
16878 • PyPy: This implementation use RPython language and RPython
16880 translation toolchain to produce the python interpreter. See
16881 PyPy.
16882 The default value is:
16884 • Windows platform: CPython, IronPython
16886 • Other platforms: CPython
16888 NOTE:
16890 This hint has the lowest priority of all hints, so even if,
16891 for example, you specify IronPython first and CPython in sec‐
16892 ond, a python product based on CPython can be selected be‐
16893 cause, for example with Python3_FIND_STRATEGY=LOCATION, each
16894 location will be search first for IronPython and second for
16895 CPython.
16896 NOTE:
16898 When IronPython is specified, on platforms other than Win‐
16899 dows, the .Net interpreter (i.e. mono command) is expected to
16900 be available through the PATH variable.
16901 Python3_FIND_UNVERSIONED_NAMES
16903 New in version 3.20.
16904 This variable defines how the generic names will be searched.
16907 Currently, it only applies to the generic names of the inter‐
16908 preter, namely, python3 and python. The Python3_FIND_UNVER‐
16909 SIONED_NAMES variable can be set to one of the following values:
16910 • FIRST: The generic names are searched before the more special‐
16912 ized ones (such as python3.5 for example).
16913 • LAST: The generic names are searched after the more special‐
16915 ized ones. This is the default.
16916 • NEVER: The generic name are not searched at all.
16918 Artifacts Specification
16920 New in version 3.16.
16921 To solve special cases, it is possible to specify directly the arti‐
16924 facts by setting the following variables:
16925 Python3_EXECUTABLE
16927 The path to the interpreter.
16928 Python3_COMPILER
16930 The path to the compiler.
16931 Python3_DOTNET_LAUNCHER
16933 New in version 3.18.
16934 The .Net interpreter. Only used by IronPython implementation.
16937 Python3_LIBRARY
16939 The path to the library. It will be used to compute the vari‐
16940 ables Python3_LIBRARIES, Python3_LIBRARY_DIRS and Python3_RUN‐
16941 TIME_LIBRARY_DIRS.
16942 Python3_INCLUDE_DIR
16944 The path to the directory of the Python headers. It will be used
16945 to compute the variable Python3_INCLUDE_DIRS.
16946 Python3_NumPy_INCLUDE_DIR
16948 The path to the directory of the NumPy headers. It will be used
16949 to compute the variable Python3_NumPy_INCLUDE_DIRS.
16950 NOTE:
16952 All paths must be absolute. Any artifact specified with a relative
16953 path will be ignored.
16954 NOTE:
16956 When an artifact is specified, all HINTS will be ignored and no
16957 search will be performed for this artifact.
16958 If more than one artifact is specified, it is the user's responsi‐
16960 bility to ensure the consistency of the various artifacts.
16961 By default, this module supports multiple calls in different directo‐
16963 ries of a project with different version/component requirements while
16964 providing correct and consistent results for each call. To support this
16965 behavior, CMake cache is not used in the traditional way which can be
16966 problematic for interactive specification. So, to enable also interac‐
16967 tive specification, module behavior can be controlled with the follow‐
16968 ing variable:
16969 Python3_ARTIFACTS_INTERACTIVE
16971 New in version 3.18.
16972 Selects the behavior of the module. This is a boolean variable:
16975 • If set to TRUE: Create CMake cache entries for the above arti‐
16977 fact specification variables so that users can edit them in‐
16978 teractively. This disables support for multiple version/com‐
16979 ponent requirements.
16980 • If set to FALSE or undefined: Enable multiple version/compo‐
16982 nent requirements.
16983 Commands
16985 This module defines the command Python3_add_library (when CMAKE_ROLE is
16986 PROJECT), which has the same semantics as add_library() and adds a de‐
16987 pendency to target Python3::Python or, when library type is MODULE, to
16988 target Python3::Module and takes care of Python module naming rules:
16989 Python3_add_library (<name> [STATIC | SHARED | MODULE [WITH_SOABI]]
16991 <source1> [<source2> ...])
16992 If the library type is not specified, MODULE is assumed.
16994 New in version 3.17: For MODULE library type, if option WITH_SOABI is
16996 specified, the module suffix will include the Python3_SOABI value, if
16997 any.
16998 FindQt3
17001 Locate Qt include paths and libraries
17002 This module defines:
17004 QT_INCLUDE_DIR - where to find qt.h, etc.
17006 QT_LIBRARIES - the libraries to link against to use Qt.
17007 QT_DEFINITIONS - definitions to use when
17008 compiling code that uses Qt.
17009 QT_FOUND - If false, don't try to use Qt.
17010 QT_VERSION_STRING - the version of Qt found
17011 If you need the multithreaded version of Qt, set QT_MT_REQUIRED to TRUE
17013 Also defined, but not for general use are:
17015 QT_MOC_EXECUTABLE, where to find the moc tool.
17017 QT_UIC_EXECUTABLE, where to find the uic tool.
17018 QT_QT_LIBRARY, where to find the Qt library.
17019 QT_QTMAIN_LIBRARY, where to find the qtmain
17020 library. This is only required by Qt3 on Windows.
17021 FindQt4
17023 Finding and Using Qt4
17024 This module can be used to find Qt4. The most important issue is that
17025 the Qt4 qmake is available via the system path. This qmake is then
17026 used to detect basically everything else. This module defines a number
17027 of IMPORTED targets, macros and variables.
17028 Typical usage could be something like:
17030 set(CMAKE_AUTOMOC ON)
17032 set(CMAKE_INCLUDE_CURRENT_DIR ON)
17033 find_package(Qt4 4.4.3 REQUIRED QtGui QtXml)
17034 add_executable(myexe main.cpp)
17035 target_link_libraries(myexe Qt4::QtGui Qt4::QtXml)
17036 NOTE:
17038 When using IMPORTED targets, the qtmain.lib static library is auto‐
17039 matically linked on Windows for WIN32 executables. To disable that
17040 globally, set the QT4_NO_LINK_QTMAIN variable before finding Qt4. To
17041 disable that for a particular executable, set the QT4_NO_LINK_QTMAIN
17042 target property to TRUE on the executable.
17043 Qt Build Tools
17045 Qt relies on some bundled tools for code generation, such as moc for
17046 meta-object code generation,``uic`` for widget layout and population,
17047 and rcc for virtual filesystem content generation. These tools may be
17048 automatically invoked by cmake(1) if the appropriate conditions are
17049 met. See cmake-qt(7) for more.
17050 Qt Macros
17052 In some cases it can be necessary or useful to invoke the Qt build
17053 tools in a more-manual way. Several macros are available to add targets
17054 for such uses.
17055 macro QT4_WRAP_CPP(outfiles inputfile ... [TARGET tgt] OPTIONS ...)
17057 create moc code from a list of files containing Qt class with
17058 the Q_OBJECT declaration. Per-directory preprocessor definitions
17059 are also added. If the <tgt> is specified, the
17060 INTERFACE_INCLUDE_DIRECTORIES and INTERFACE_COMPILE_DEFINITIONS from
17061 the <tgt> are passed to moc. Options may be given to moc, such as
17062 those found when executing "moc -help".
17063 macro QT4_WRAP_UI(outfiles inputfile ... OPTIONS ...)
17065 create code from a list of Qt designer ui files.
17066 Options may be given to uic, such as those found
17067 when executing "uic -help"
17068 macro QT4_ADD_RESOURCES(outfiles inputfile ... OPTIONS ...)
17070 create code from a list of Qt resource files.
17071 Options may be given to rcc, such as those found
17072 when executing "rcc -help"
17073 macro QT4_GENERATE_MOC(inputfile outputfile [TARGET tgt])
17075 creates a rule to run moc on infile and create outfile.
17076 Use this if for some reason QT4_WRAP_CPP() isn't appropriate, e.g.
17077 because you need a custom filename for the moc file or something
17078 similar. If the <tgt> is specified, the
17079 INTERFACE_INCLUDE_DIRECTORIES and INTERFACE_COMPILE_DEFINITIONS from
17080 the <tgt> are passed to moc.
17081 macro QT4_ADD_DBUS_INTERFACE(outfiles interface basename)
17083 Create the interface header and implementation files with the
17084 given basename from the given interface xml file and add it to
17085 the list of sources.
17086 You can pass additional parameters to the qdbusxml2cpp call by setting
17088 properties on the input file:
17089 INCLUDE the given file will be included in the generate interface header
17091 CLASSNAME the generated class is named accordingly
17093 NO_NAMESPACE the generated class is not wrapped in a namespace
17095 macro QT4_ADD_DBUS_INTERFACES(outfiles inputfile ... )
17097 Create the interface header and implementation files
17098 for all listed interface xml files.
17099 The basename will be automatically determined from the name
17100 of the xml file.
17101 The source file properties described for
17103 QT4_ADD_DBUS_INTERFACE also apply here.
17104 macro QT4_ADD_DBUS_ADAPTOR(outfiles xmlfile parentheader parentclassname
17106 [basename] [classname])
17107 create a dbus adaptor (header and implementation file) from the xml file
17108 describing the interface, and add it to the list of sources. The adaptor
17109 forwards the calls to a parent class, defined in parentheader and named
17110 parentclassname. The name of the generated files will be
17111 <basename>adaptor.{cpp,h} where basename defaults to the basename of the
17112 xml file.
17113 If <classname> is provided, then it will be used as the classname of the
17114 adaptor itself.
17115 macro QT4_GENERATE_DBUS_INTERFACE( header [interfacename] OPTIONS ...)
17117 generate the xml interface file from the given header.
17118 If the optional argument interfacename is omitted, the name of the
17119 interface file is constructed from the basename of the header with
17120 the suffix .xml appended.
17121 Options may be given to qdbuscpp2xml, such as those found when
17122 executing "qdbuscpp2xml --help"
17123 macro QT4_CREATE_TRANSLATION( qm_files directories ... sources ...
17125 ts_files ... OPTIONS ...)
17126 out: qm_files
17127 in: directories sources ts_files
17128 options: flags to pass to lupdate, such as -extensions to specify
17129 extensions for a directory scan.
17130 generates commands to create .ts (via lupdate) and .qm
17131 (via lrelease) - files from directories and/or sources. The ts files are
17132 created and/or updated in the source tree (unless given with full paths).
17133 The qm files are generated in the build tree.
17134 Updating the translations can be done by adding the qm_files
17135 to the source list of your library/executable, so they are
17136 always updated, or by adding a custom target to control when
17137 they get updated/generated.
17138 macro QT4_ADD_TRANSLATION( qm_files ts_files ... )
17140 out: qm_files
17141 in: ts_files
17142 generates commands to create .qm from .ts - files. The generated
17143 filenames can be found in qm_files. The ts_files
17144 must exist and are not updated in any way.
17145 macro QT4_AUTOMOC(sourcefile1 sourcefile2 ... [TARGET tgt])
17147 The qt4_automoc macro is obsolete. Use the CMAKE_AUTOMOC feature instead.
17148 This macro is still experimental.
17149 It can be used to have moc automatically handled.
17150 So if you have the files foo.h and foo.cpp, and in foo.h a
17151 a class uses the Q_OBJECT macro, moc has to run on it. If you don't
17152 want to use QT4_WRAP_CPP() (which is reliable and mature), you can insert
17153 #include "foo.moc"
17154 in foo.cpp and then give foo.cpp as argument to QT4_AUTOMOC(). This will
17155 scan all listed files at cmake-time for such included moc files and if it
17156 finds them cause a rule to be generated to run moc at build time on the
17157 accompanying header file foo.h.
17158 If a source file has the SKIP_AUTOMOC property set it will be ignored by
17159 this macro.
17160 If the <tgt> is specified, the INTERFACE_INCLUDE_DIRECTORIES and
17161 INTERFACE_COMPILE_DEFINITIONS from the <tgt> are passed to moc.
17162 function QT4_USE_MODULES( target [link_type] modules...)
17164 This function is obsolete. Use target_link_libraries with IMPORTED targets
17165 instead.
17166 Make <target> use the <modules> from Qt. Using a Qt module means
17167 to link to the library, add the relevant include directories for the
17168 module, and add the relevant compiler defines for using the module.
17169 Modules are roughly equivalent to components of Qt4, so usage would be
17170 something like:
17171 qt4_use_modules(myexe Core Gui Declarative)
17172 to use QtCore, QtGui and QtDeclarative. The optional <link_type> argument
17173 can be specified as either LINK_PUBLIC or LINK_PRIVATE to specify the
17174 same argument to the target_link_libraries call.
17175 IMPORTED Targets
17177 A particular Qt library may be used by using the corresponding IMPORTED
17178 target with the target_link_libraries() command:
17179 target_link_libraries(myexe Qt4::QtGui Qt4::QtXml)
17181 Using a target in this way causes :cmake(1)` to use the appropriate in‐
17183 clude directories and compile definitions for the target when compiling
17184 myexe.
17185 Targets are aware of their dependencies, so for example it is not nec‐
17187 essary to list Qt4::QtCore if another Qt library is listed, and it is
17188 not necessary to list Qt4::QtGui if Qt4::QtDeclarative is listed. Tar‐
17189 gets may be tested for existence in the usual way with the if(TARGET)
17190 command.
17191 The Qt toolkit may contain both debug and release libraries. cmake(1)
17193 will choose the appropriate version based on the build configuration.
17194 Qt4::QtCore
17196 The QtCore target
17197 Qt4::QtGui
17199 The QtGui target
17200 Qt4::Qt3Support
17202 The Qt3Support target
17203 Qt4::QtAssistant
17205 The QtAssistant target
17206 Qt4::QtAssistantClient
17208 The QtAssistantClient target
17209 Qt4::QAxContainer
17211 The QAxContainer target (Windows only)
17212 Qt4::QAxServer
17214 The QAxServer target (Windows only)
17215 Qt4::QtDBus
17217 The QtDBus target
17218 Qt4::QtDeclarative
17220 The QtDeclarative target
17221 Qt4::QtDesigner
17223 The QtDesigner target
17224 Qt4::QtDesignerComponents
17226 The QtDesignerComponents target
17227 Qt4::QtHelp
17229 The QtHelp target
17230 Qt4::QtMotif
17232 The QtMotif target
17233 Qt4::QtMultimedia
17235 The QtMultimedia target
17236 Qt4::QtNetwork
17238 The QtNetwork target
17239 Qt4::QtNsPLugin
17241 The QtNsPLugin target
17242 Qt4::QtOpenGL
17244 The QtOpenGL target
17245 Qt4::QtScript
17247 The QtScript target
17248 Qt4::QtScriptTools
17250 The QtScriptTools target
17251 Qt4::QtSql
17253 The QtSql target
17254 Qt4::QtSvg
17256 The QtSvg target
17257 Qt4::QtTest
17259 The QtTest target
17260 Qt4::QtUiTools
17262 The QtUiTools target
17263 Qt4::QtWebKit
17265 The QtWebKit target
17266 Qt4::QtXml
17268 The QtXml target
17269 Qt4::QtXmlPatterns
17271 The QtXmlPatterns target
17272 Qt4::phonon
17274 The phonon target
17275 Result Variables
17277 Below is a detailed list of variables that FindQt4.cmake sets.
17278 Qt4_FOUND
17280 If false, don't try to use Qt 4.
17281 QT_FOUND
17283 If false, don't try to use Qt. This variable is for compatibil‐
17284 ity only.
17285 QT4_FOUND
17287 If false, don't try to use Qt 4. This variable is for compati‐
17288 bility only.
17289 QT_VERSION_MAJOR
17291 The major version of Qt found.
17292 QT_VERSION_MINOR
17294 The minor version of Qt found.
17295 QT_VERSION_PATCH
17297 The patch version of Qt found.
17298 FindQuickTime
17300 Locate QuickTime This module defines QUICKTIME_LIBRARY QUICKTIME_FOUND,
17301 if false, do not try to link to gdal QUICKTIME_INCLUDE_DIR, where to
17302 find the headers
17303 $QUICKTIME_DIR is an environment variable that would correspond to the
17305 ./configure --prefix=$QUICKTIME_DIR
17306 Created by Eric Wing.
17308 FindRTI
17310 Try to find M&S HLA RTI libraries
17311 This module finds if any HLA RTI is installed and locates the standard
17313 RTI include files and libraries.
17314 RTI is a simulation infrastructure standardized by IEEE and SISO. It
17316 has a well defined C++ API that assures that simulation applications
17317 are independent on a particular RTI implementation.
17318 http://en.wikipedia.org/wiki/Run-Time_Infrastructure_(simulation)
17320 This code sets the following variables:
17322 RTI_INCLUDE_DIR = the directory where RTI includes file are found
17324 RTI_LIBRARIES = The libraries to link against to use RTI
17325 RTI_DEFINITIONS = -DRTI_USES_STD_FSTREAM
17326 RTI_FOUND = Set to FALSE if any HLA RTI was not found
17327 Report problems to <certi-devel@nongnu.org>
17329 FindRuby
17331 Find Ruby
17332 This module finds if Ruby is installed and determines where the include
17334 files and libraries are. Ruby 1.8 through 2.7 are supported.
17335 The minimum required version of Ruby can be specified using the stan‐
17337 dard syntax, e.g.
17338 find_package(Ruby 2.5.1 EXACT REQUIRED)
17340 # OR
17341 find_package(Ruby 2.4)
17342 It also determines what the name of the library is.
17344 Virtual environments such as RVM are handled as well, by passing the
17346 argument Ruby_FIND_VIRTUALENV
17347 Result Variables
17349 This module will set the following variables in your project:
17350 Ruby_FOUND
17352 set to true if ruby was found successfully
17353 Ruby_EXECUTABLE
17355 full path to the ruby binary
17356 Ruby_INCLUDE_DIRS
17358 include dirs to be used when using the ruby library
17359 Ruby_LIBRARIES
17361 New in version 3.18: libraries needed to use ruby from C.
17362 Ruby_VERSION
17365 the version of ruby which was found, e.g. "1.8.7"
17366 Ruby_VERSION_MAJOR
17368 Ruby major version.
17369 Ruby_VERSION_MINOR
17371 Ruby minor version.
17372 Ruby_VERSION_PATCH
17374 Ruby patch version.
17375 Changed in version 3.18: Previous versions of CMake used the RUBY_ pre‐
17377 fix for all variables. The following variables are provided for com‐
17378 patibility reasons, don't use them in new code:
17379 RUBY_EXECUTABLE
17382 same as Ruby_EXECUTABLE.
17383 RUBY_INCLUDE_DIRS
17385 same as Ruby_INCLUDE_DIRS.
17386 RUBY_INCLUDE_PATH
17388 same as Ruby_INCLUDE_DIRS.
17389 RUBY_LIBRARY
17391 same as Ruby_LIBRARY.
17392 RUBY_VERSION
17394 same as Ruby_VERSION.
17395 RUBY_FOUND
17397 same as Ruby_FOUND.
17398 Hints
17400 New in version 3.18.
17401 Ruby_ROOT_DIR
17404 Define the root directory of a Ruby installation.
17405 Ruby_FIND_VIRTUALENV
17407 This variable defines the handling of virtual environments man‐
17408 aged by rvm. It is meaningful only when a virtual environment is
17409 active (i.e. the rvm script has been evaluated or at least the
17410 MY_RUBY_HOME environment variable is set). The Ruby_FIND_VIR‐
17411 TUALENV variable can be set to empty or one of the following:
17412 • FIRST: The virtual environment is used before any other stan‐
17414 dard paths to look-up for the interpreter. This is the de‐
17415 fault.
17416 • ONLY: Only the virtual environment is used to look-up for the
17418 interpreter.
17419 • STANDARD: The virtual environment is not used to look-up for
17421 the interpreter (assuming it isn't still in the PATH...)
17422 FindSDL
17424 Locate the SDL library
17425 Imported targets
17427 New in version 3.19.
17428 This module defines the following IMPORTED target:
17431 SDL::SDL
17433 The SDL library, if found
17434 Result variables
17436 This module will set the following variables in your project:
17437 SDL_INCLUDE_DIRS
17439 where to find SDL.h
17440 SDL_LIBRARIES
17442 the name of the library to link against
17443 SDL_FOUND
17445 if false, do not try to link to SDL
17446 SDL_VERSION
17448 the human-readable string containing the version of SDL if found
17449 SDL_VERSION_MAJOR
17451 SDL major version
17452 SDL_VERSION_MINOR
17454 SDL minor version
17455 SDL_VERSION_PATCH
17457 SDL patch version
17458 New in version 3.19: Added the SDL_INCLUDE_DIRS, SDL_LIBRARIES and
17460 SDL_VERSION[_<PART>] variables.
17461 Cache variables
17464 These variables may optionally be set to help this module find the cor‐
17465 rect files:
17466 SDL_INCLUDE_DIR
17468 where to find SDL.h
17469 SDL_LIBRARY
17471 the name of the library to link against
17472 Variables for locating SDL
17474 This module responds to the flag:
17475 SDL_BUILDING_LIBRARY
17477 If this is defined, then no SDL_main will be linked in because
17478 only applications need main(). Otherwise, it is assumed you are
17479 building an application and this module will attempt to locate
17480 and set the proper link flags as part of the returned SDL_LI‐
17481 BRARY variable.
17482 Obsolete variables
17484 Deprecated since version 3.19.
17485 These variables are obsolete and provided for backwards compatibility:
17488 SDL_VERSION_STRING
17490 the human-readable string containing the version of SDL if
17491 found. Identical to SDL_VERSION
17492 Don't forget to include SDLmain.h and SDLmain.m your project for the OS
17494 X framework based version. (Other versions link to -lSDLmain which
17495 this module will try to find on your behalf.) Also for OS X, this mod‐
17496 ule will automatically add the -framework Cocoa on your behalf.
17497 Additional Note: If you see an empty SDL_LIBRARY_TEMP in your configu‐
17499 ration and no SDL_LIBRARY, it means CMake did not find your SDL library
17500 (SDL.dll, libsdl.so, SDL.framework, etc). Set SDL_LIBRARY_TEMP to
17501 point to your SDL library, and configure again. Similarly, if you see
17502 an empty SDLMAIN_LIBRARY, you should set this value as appropriate.
17503 These values are used to generate the final SDL_LIBRARY variable, but
17504 when these values are unset, SDL_LIBRARY does not get created.
17505 $SDLDIR is an environment variable that would correspond to the ./con‐
17507 figure --prefix=$SDLDIR used in building SDL. l.e.galup 9-20-02
17508 On OSX, this will prefer the Framework version (if found) over others.
17510 People will have to manually change the cache values of SDL_LIBRARY to
17511 override this selection or set the CMake environment CMAKE_INCLUDE_PATH
17512 to modify the search paths.
17513 Note that the header path has changed from SDL/SDL.h to just SDL.h This
17515 needed to change because "proper" SDL convention is #include "SDL.h",
17516 not <SDL/SDL.h>. This is done for portability reasons because not all
17517 systems place things in SDL/ (see FreeBSD).
17518 FindSDL_image
17520 Locate SDL_image library
17521 This module defines:
17523 SDL_IMAGE_LIBRARIES, the name of the library to link against
17525 SDL_IMAGE_INCLUDE_DIRS, where to find the headers
17526 SDL_IMAGE_FOUND, if false, do not try to link against
17527 SDL_IMAGE_VERSION_STRING - human-readable string containing the
17528 version of SDL_image
17529 For backward compatibility the following variables are also set:
17531 SDLIMAGE_LIBRARY (same value as SDL_IMAGE_LIBRARIES)
17533 SDLIMAGE_INCLUDE_DIR (same value as SDL_IMAGE_INCLUDE_DIRS)
17534 SDLIMAGE_FOUND (same value as SDL_IMAGE_FOUND)
17535 $SDLDIR is an environment variable that would correspond to the ./con‐
17537 figure --prefix=$SDLDIR used in building SDL.
17538 Created by Eric Wing. This was influenced by the FindSDL.cmake module,
17540 but with modifications to recognize OS X frameworks and additional Unix
17541 paths (FreeBSD, etc).
17542 FindSDL_mixer
17544 Locate SDL_mixer library
17545 This module defines:
17547 SDL_MIXER_LIBRARIES, the name of the library to link against
17549 SDL_MIXER_INCLUDE_DIRS, where to find the headers
17550 SDL_MIXER_FOUND, if false, do not try to link against
17551 SDL_MIXER_VERSION_STRING - human-readable string containing the
17552 version of SDL_mixer
17553 For backward compatibility the following variables are also set:
17555 SDLMIXER_LIBRARY (same value as SDL_MIXER_LIBRARIES)
17557 SDLMIXER_INCLUDE_DIR (same value as SDL_MIXER_INCLUDE_DIRS)
17558 SDLMIXER_FOUND (same value as SDL_MIXER_FOUND)
17559 $SDLDIR is an environment variable that would correspond to the ./con‐
17561 figure --prefix=$SDLDIR used in building SDL.
17562 Created by Eric Wing. This was influenced by the FindSDL.cmake module,
17564 but with modifications to recognize OS X frameworks and additional Unix
17565 paths (FreeBSD, etc).
17566 FindSDL_net
17568 Locate SDL_net library
17569 This module defines:
17571 SDL_NET_LIBRARIES, the name of the library to link against
17573 SDL_NET_INCLUDE_DIRS, where to find the headers
17574 SDL_NET_FOUND, if false, do not try to link against
17575 SDL_NET_VERSION_STRING - human-readable string containing the version of SDL_net
17576 For backward compatibility the following variables are also set:
17578 SDLNET_LIBRARY (same value as SDL_NET_LIBRARIES)
17580 SDLNET_INCLUDE_DIR (same value as SDL_NET_INCLUDE_DIRS)
17581 SDLNET_FOUND (same value as SDL_NET_FOUND)
17582 $SDLDIR is an environment variable that would correspond to the ./con‐
17584 figure --prefix=$SDLDIR used in building SDL.
17585 Created by Eric Wing. This was influenced by the FindSDL.cmake module,
17587 but with modifications to recognize OS X frameworks and additional Unix
17588 paths (FreeBSD, etc).
17589 FindSDL_sound
17591 Locates the SDL_sound library
17592 This module depends on SDL being found and must be called AFTER Find‐
17594 SDL.cmake is called.
17595 This module defines
17597 SDL_SOUND_INCLUDE_DIR, where to find SDL_sound.h
17599 SDL_SOUND_FOUND, if false, do not try to link to SDL_sound
17600 SDL_SOUND_LIBRARIES, this contains the list of libraries that you need
17601 to link against.
17602 SDL_SOUND_EXTRAS, this is an optional variable for you to add your own
17603 flags to SDL_SOUND_LIBRARIES. This is prepended to SDL_SOUND_LIBRARIES.
17604 This is available mostly for cases this module failed to anticipate for
17605 and you must add additional flags. This is marked as ADVANCED.
17606 SDL_SOUND_VERSION_STRING, human-readable string containing the
17607 version of SDL_sound
17608 This module also defines (but you shouldn't need to use directly)
17610 SDL_SOUND_LIBRARY, the name of just the SDL_sound library you would link
17612 against. Use SDL_SOUND_LIBRARIES for you link instructions and not this one.
17613 And might define the following as needed
17615 MIKMOD_LIBRARY
17617 MODPLUG_LIBRARY
17618 OGG_LIBRARY
17619 VORBIS_LIBRARY
17620 SMPEG_LIBRARY
17621 FLAC_LIBRARY
17622 SPEEX_LIBRARY
17623 Typically, you should not use these variables directly, and you should
17625 use SDL_SOUND_LIBRARIES which contains SDL_SOUND_LIBRARY and the other
17626 audio libraries (if needed) to successfully compile on your system.
17627 Created by Eric Wing. This module is a bit more complicated than the
17629 other FindSDL* family modules. The reason is that SDL_sound can be
17630 compiled in a large variety of different ways which are independent of
17631 platform. SDL_sound may dynamically link against other 3rd party li‐
17632 braries to get additional codec support, such as Ogg Vorbis, SMPEG,
17633 ModPlug, MikMod, FLAC, Speex, and potentially others. Under some cir‐
17634 cumstances which I don't fully understand, there seems to be a require‐
17635 ment that dependent libraries of libraries you use must also be explic‐
17636 itly linked against in order to successfully compile. SDL_sound does
17637 not currently have any system in place to know how it was compiled. So
17638 this CMake module does the hard work in trying to discover which 3rd
17639 party libraries are required for building (if any). This module uses a
17640 brute force approach to create a test program that uses SDL_sound, and
17641 then tries to build it. If the build fails, it parses the error output
17642 for known symbol names to figure out which libraries are needed.
17643 Responds to the $SDLDIR and $SDLSOUNDDIR environmental variable that
17645 would correspond to the ./configure --prefix=$SDLDIR used in building
17646 SDL.
17647 On OSX, this will prefer the Framework version (if found) over others.
17649 People will have to manually change the cache values of SDL_LIBRARY to
17650 override this selectionor set the CMake environment CMAKE_INCLUDE_PATH
17651 to modify the search paths.
17652 FindSDL_ttf
17654 Locate SDL_ttf library
17655 This module defines:
17657 SDL_TTF_LIBRARIES, the name of the library to link against
17659 SDL_TTF_INCLUDE_DIRS, where to find the headers
17660 SDL_TTF_FOUND, if false, do not try to link against
17661 SDL_TTF_VERSION_STRING - human-readable string containing the version of SDL_ttf
17662 For backward compatibility the following variables are also set:
17664 SDLTTF_LIBRARY (same value as SDL_TTF_LIBRARIES)
17666 SDLTTF_INCLUDE_DIR (same value as SDL_TTF_INCLUDE_DIRS)
17667 SDLTTF_FOUND (same value as SDL_TTF_FOUND)
17668 $SDLDIR is an environment variable that would correspond to the ./con‐
17670 figure --prefix=$SDLDIR used in building SDL.
17671 Created by Eric Wing. This was influenced by the FindSDL.cmake module,
17673 but with modifications to recognize OS X frameworks and additional Unix
17674 paths (FreeBSD, etc).
17675 FindSelfPackers
17677 Find upx
17678 This module looks for some executable packers (i.e. software that com‐
17680 press executables or shared libs into on-the-fly self-extracting exe‐
17681 cutables or shared libs. Examples:
17682 UPX: http://wildsau.idv.uni-linz.ac.at/mfx/upx.html
17684 FindSquish
17686 -- Typical Use
17687 This module can be used to find Squish.
17689 SQUISH_FOUND If false, don't try to use Squish
17691 SQUISH_VERSION The full version of Squish found
17692 SQUISH_VERSION_MAJOR The major version of Squish found
17693 SQUISH_VERSION_MINOR The minor version of Squish found
17694 SQUISH_VERSION_PATCH The patch version of Squish found
17695 SQUISH_INSTALL_DIR The Squish installation directory
17697 (containing bin, lib, etc)
17698 SQUISH_SERVER_EXECUTABLE The squishserver executable
17699 SQUISH_CLIENT_EXECUTABLE The squishrunner executable
17700 SQUISH_INSTALL_DIR_FOUND Was the install directory found?
17702 SQUISH_SERVER_EXECUTABLE_FOUND Was the server executable found?
17703 SQUISH_CLIENT_EXECUTABLE_FOUND Was the client executable found?
17704 It provides the function squish_add_test() for adding a squish test to
17706 cmake using Squish >= 4.x:
17707 squish_add_test(cmakeTestName
17709 AUT targetName SUITE suiteName TEST squishTestName
17710 [SETTINGSGROUP group] [PRE_COMMAND command] [POST_COMMAND command] )
17711 Changed in version 3.18: In previous CMake versions, this function was
17713 named squish_v4_add_test.
17714 The arguments have the following meaning:
17717 cmakeTestName
17719 this will be used as the first argument for add_test()
17720 AUT targetName
17722 the name of the cmake target which will be used as AUT, i.e. the
17723 executable which will be tested.
17724 SUITE suiteName
17726 this is either the full path to the squish suite, or just the
17727 last directory of the suite, i.e. the suite name. In this case
17728 the CMakeLists.txt which calls squish_add_test() must be located
17729 in the parent directory of the suite directory.
17730 TEST squishTestName
17732 the name of the squish test, i.e. the name of the subdirectory
17733 of the test inside the suite directory.
17734 SETTINGSGROUP group
17736 deprecated, this argument will be ignored.
17737 PRE_COMMAND command
17739 if specified, the given command will be executed before starting
17740 the squish test.
17741 POST_COMMAND command
17743 same as PRE_COMMAND, but after the squish test has been exe‐
17744 cuted.
17745 enable_testing()
17747 find_package(Squish 6.5)
17748 if (SQUISH_FOUND)
17749 squish_add_test(myTestName
17750 AUT myApp
17751 SUITE ${CMAKE_SOURCE_DIR}/tests/mySuite
17752 TEST someSquishTest
17753 )
17754 endif ()
17755 For users of Squish version 3.x the macro squish_v3_add_test() is pro‐
17757 vided:
17758 squish_v3_add_test(testName applicationUnderTest testCase envVars testWrapper)
17760 Use this macro to add a test using Squish 3.x.
17761 enable_testing()
17763 find_package(Squish 3.0)
17764 if (SQUISH_FOUND)
17765 squish_v3_add_test(myTestName myApplication testCase envVars testWrapper)
17766 endif ()
17767 FindSQLite3
17769 New in version 3.14.
17770 Find the SQLite libraries, v3
17773 IMPORTED targets
17775 This module defines the following IMPORTED target:
17776 SQLite::SQLite3
17778 Result variables
17780 This module will set the following variables if found:
17781 SQLite3_INCLUDE_DIRS
17783 where to find sqlite3.h, etc.
17784 SQLite3_LIBRARIES
17786 the libraries to link against to use SQLite3.
17787 SQLite3_VERSION
17789 version of the SQLite3 library found
17790 SQLite3_FOUND
17792 TRUE if found
17793 FindSubversion
17795 Extract information from a subversion working copy
17796 The module defines the following variables:
17798 Subversion_SVN_EXECUTABLE - path to svn command line client
17800 Subversion_VERSION_SVN - version of svn command line client
17801 Subversion_FOUND - true if the command line client was found
17802 SUBVERSION_FOUND - same as Subversion_FOUND, set for compatibility reasons
17803 The minimum required version of Subversion can be specified using the
17805 standard syntax, e.g. find_package(Subversion 1.4).
17806 If the command line client executable is found two macros are defined:
17808 Subversion_WC_INFO(<dir> <var-prefix> [IGNORE_SVN_FAILURE])
17810 Subversion_WC_LOG(<dir> <var-prefix>)
17811 Subversion_WC_INFO extracts information of a subversion working copy at
17813 a given location. This macro defines the following variables if run‐
17814 ning Subversion's info command on <dir> succeeds; otherwise a SEND_ER‐
17815 ROR message is generated.
17816 New in version 3.13: The error can be ignored by providing the IG‐
17818 NORE_SVN_FAILURE option, which causes these variables to remain unde‐
17819 fined.
17820 <var-prefix>_WC_URL - url of the repository (at <dir>)
17823 <var-prefix>_WC_ROOT - root url of the repository
17824 <var-prefix>_WC_REVISION - current revision
17825 <var-prefix>_WC_LAST_CHANGED_AUTHOR - author of last commit
17826 <var-prefix>_WC_LAST_CHANGED_DATE - date of last commit
17827 <var-prefix>_WC_LAST_CHANGED_REV - revision of last commit
17828 <var-prefix>_WC_INFO - output of command `svn info <dir>'
17829 Subversion_WC_LOG retrieves the log message of the base revision of a
17831 subversion working copy at a given location. This macro defines the
17832 variable:
17833 <var-prefix>_LAST_CHANGED_LOG - last log of base revision
17835 Example usage:
17837 find_package(Subversion)
17839 if(SUBVERSION_FOUND)
17840 Subversion_WC_INFO(${PROJECT_SOURCE_DIR} Project)
17841 message("Current revision is ${Project_WC_REVISION}")
17842 Subversion_WC_LOG(${PROJECT_SOURCE_DIR} Project)
17843 message("Last changed log is ${Project_LAST_CHANGED_LOG}")
17844 endif()
17845 FindSWIG
17847 Find the Simplified Wrapper and Interface Generator (SWIG) executable.
17848 This module finds an installed SWIG and determines its version.
17850 New in version 3.18: If a COMPONENTS or OPTIONAL_COMPONENTS argument is
17852 given to the find_package() command, it will also determine supported
17853 target languages.
17854 New in version 3.19: When a version is requested, it can be specified
17857 as a simple value or as a range. For a detailed description of version
17858 range usage and capabilities, refer to the find_package() command.
17859 The module defines the following variables:
17862 SWIG_FOUND
17864 Whether SWIG and any required components were found on the sys‐
17865 tem.
17866 SWIG_EXECUTABLE
17868 Path to the SWIG executable.
17869 SWIG_DIR
17871 Path to the installed SWIG Lib directory (result of swig
17872 -swiglib).
17873 SWIG_VERSION
17875 SWIG executable version (result of swig -version).
17876 SWIG_<lang>_FOUND
17878 If COMPONENTS or OPTIONAL_COMPONENTS are requested, each avail‐
17879 able target language <lang> (lowercase) will be set to TRUE.
17880 Any COMPONENTS given to find_package should be the names of supported
17882 target languages as provided to the LANGUAGE argument of swig_add_li‐
17883 brary, such as python or perl5. Language names must be lowercase.
17884 All information is collected from the SWIG_EXECUTABLE, so the version
17886 to be found can be changed from the command line by means of setting
17887 SWIG_EXECUTABLE.
17888 Example usage requiring SWIG 4.0 or higher and Python language support,
17890 with optional Fortran support:
17891 find_package(SWIG 4.0 COMPONENTS python OPTIONAL_COMPONENTS fortran)
17893 if(SWIG_FOUND)
17894 message("SWIG found: ${SWIG_EXECUTABLE}")
17895 if(NOT SWIG_fortran_FOUND)
17896 message(WARNING "SWIG Fortran bindings cannot be generated")
17897 endif()
17898 endif()
17899 FindTCL
17901 TK_INTERNAL_PATH was removed.
17902 This module finds if Tcl is installed and determines where the include
17904 files and libraries are. It also determines what the name of the li‐
17905 brary is. This code sets the following variables:
17906 TCL_FOUND = Tcl was found
17908 TK_FOUND = Tk was found
17909 TCLTK_FOUND = Tcl and Tk were found
17910 TCL_LIBRARY = path to Tcl library (tcl tcl80)
17911 TCL_INCLUDE_PATH = path to where tcl.h can be found
17912 TCL_TCLSH = path to tclsh binary (tcl tcl80)
17913 TK_LIBRARY = path to Tk library (tk tk80 etc)
17914 TK_INCLUDE_PATH = path to where tk.h can be found
17915 TK_WISH = full path to the wish executable
17916 In an effort to remove some clutter and clear up some issues for people
17918 who are not necessarily Tcl/Tk gurus/developers, some variables were
17919 moved or removed. Changes compared to CMake 2.4 are:
17920 => they were only useful for people writing Tcl/Tk extensions.
17922 => these libs are not packaged by default with Tcl/Tk distributions.
17923 Even when Tcl/Tk is built from source, several flavors of debug libs
17924 are created and there is no real reason to pick a single one
17925 specifically (say, amongst tcl84g, tcl84gs, or tcl84sgx).
17926 Let's leave that choice to the user by allowing him to assign
17927 TCL_LIBRARY to any Tcl library, debug or not.
17928 => this ended up being only a Win32 variable, and there is a lot of
17929 confusion regarding the location of this file in an installed Tcl/Tk
17930 tree anyway (see 8.5 for example). If you need the internal path at
17931 this point it is safer you ask directly where the *source* tree is
17932 and dig from there.
17933 FindTclsh
17935 Find tclsh
17936 This module finds if TCL is installed and determines where the include
17938 files and libraries are. It also determines what the name of the li‐
17939 brary is. This code sets the following variables:
17940 TCLSH_FOUND = TRUE if tclsh has been found
17942 TCL_TCLSH = the path to the tclsh executable
17943 FindTclStub
17945 TCL_STUB_LIBRARY_DEBUG and TK_STUB_LIBRARY_DEBUG were removed.
17946 This module finds Tcl stub libraries. It first finds Tcl include files
17948 and libraries by calling FindTCL.cmake. How to Use the Tcl Stubs Li‐
17949 brary:
17950 http://tcl.activestate.com/doc/howto/stubs.html
17952 Using Stub Libraries:
17954 http://safari.oreilly.com/0130385603/ch48lev1sec3
17956 This code sets the following variables:
17958 TCL_STUB_LIBRARY = path to Tcl stub library
17960 TK_STUB_LIBRARY = path to Tk stub library
17961 TTK_STUB_LIBRARY = path to ttk stub library
17962 In an effort to remove some clutter and clear up some issues for people
17964 who are not necessarily Tcl/Tk gurus/developers, some variables were
17965 moved or removed. Changes compared to CMake 2.4 are:
17966 => these libs are not packaged by default with Tcl/Tk distributions.
17968 Even when Tcl/Tk is built from source, several flavors of debug libs
17969 are created and there is no real reason to pick a single one
17970 specifically (say, amongst tclstub84g, tclstub84gs, or tclstub84sgx).
17971 Let's leave that choice to the user by allowing him to assign
17972 TCL_STUB_LIBRARY to any Tcl library, debug or not.
17973 FindThreads
17975 This module determines the thread library of the system.
17976 Imported Targets
17978 New in version 3.1.
17979 This module defines the following IMPORTED target:
17982 Threads::Threads
17984 The thread library, if found.
17985 Result Variables
17987 The following variables are set:
17988 Threads_FOUND
17990 If a supported thread library was found.
17991 CMAKE_THREAD_LIBS_INIT
17993 The thread library to use. This may be empty if the thread func‐
17994 tions are provided by the system libraries and no special flags
17995 are needed to use them.
17996 CMAKE_USE_WIN32_THREADS_INIT
17998 If the found thread library is the win32 one.
17999 CMAKE_USE_PTHREADS_INIT
18001 If the found thread library is pthread compatible.
18002 CMAKE_HP_PTHREADS_INIT
18004 If the found thread library is the HP thread library.
18005 Variables Affecting Behavior
18007 THREADS_PREFER_PTHREAD_FLAG
18008 New in version 3.1.
18009 If the use of the -pthread compiler and linker flag is preferred
18012 then the caller can set this variable to TRUE. The compiler flag
18013 can only be used with the imported target. Use of both the im‐
18014 ported target as well as this switch is highly recommended for
18015 new code.
18016 This variable has no effect if the system libraries provide the
18018 thread functions, i.e. when CMAKE_THREAD_LIBS_INIT will be
18019 empty.
18020 FindTIFF
18022 Find the TIFF library (libtiff, https://libtiff.gitlab.io/libtiff/).
18023 Optional COMPONENTS
18025 This module supports the optional component CXX, for use with the COM‐
18026 PONENTS argument of the find_package() command. This component has an
18027 associated imported target, as described below.
18028 Imported targets
18030 New in version 3.5.
18031 This module defines the following IMPORTED targets:
18034 TIFF::TIFF
18036 The TIFF library, if found.
18037 TIFF::CXX
18039 New in version 3.19.
18040 The C++ wrapper libtiffxx, if requested by the COMPONENTS CXX
18043 option, if the compiler is not MSVC (which includes the C++
18044 wrapper in libtiff), and if found.
18045 Result variables
18047 This module will set the following variables in your project:
18048 TIFF_FOUND
18050 true if the TIFF headers and libraries were found
18051 TIFF_INCLUDE_DIR
18053 the directory containing the TIFF headers
18054 TIFF_INCLUDE_DIRS
18056 the directory containing the TIFF headers
18057 TIFF_LIBRARIES
18059 TIFF libraries to be linked
18060 Cache variables
18062 The following cache variables may also be set:
18063 TIFF_INCLUDE_DIR
18065 the directory containing the TIFF headers
18066 TIFF_LIBRARY_RELEASE
18068 the path to the TIFF library for release configurations
18069 TIFF_LIBRARY_DEBUG
18071 the path to the TIFF library for debug configurations
18072 TIFFXX_LIBRARY_RELEASE
18074 the path to the TIFFXX library for release configurations
18075 TIFFXX_LIBRARY_DEBUG
18077 the path to the TIFFXX library for debug configurations
18078 New in version 3.4: Debug and Release variants are found separately.
18080 FindUnixCommands
18083 Find Unix commands, including the ones from Cygwin
18084 This module looks for the Unix commands bash, cp, gzip, mv, rm, and tar
18086 and stores the result in the variables BASH, CP, GZIP, MV, RM, and TAR.
18087 FindVTK
18089 This module no longer exists.
18090 This module existed in versions of CMake prior to 3.1, but became only
18092 a thin wrapper around find_package(VTK NO_MODULE) to provide compati‐
18093 bility for projects using long-outdated conventions. Now find_pack‐
18094 age(VTK) will search for VTKConfig.cmake directly.
18095 FindVulkan
18097 New in version 3.7.
18098 Find Vulkan, which is a low-overhead, cross-platform 3D graphics and
18101 computing API.
18102 IMPORTED Targets
18104 This module defines IMPORTED target Vulkan::Vulkan, if Vulkan has been
18105 found.
18106 New in version 3.19: This module defines IMPORTED target Vulkan::glslc,
18108 if Vulkan and the GLSLC SPIR-V compiler has been found.
18109 Result Variables
18112 This module defines the following variables:
18113 Vulkan_FOUND - "True" if Vulkan was found
18115 Vulkan_INCLUDE_DIRS - include directories for Vulkan
18116 Vulkan_LIBRARIES - link against this library to use Vulkan
18117 The module will also define three cache variables:
18119 Vulkan_INCLUDE_DIR - the Vulkan include directory
18121 Vulkan_LIBRARY - the path to the Vulkan library
18122 Vulkan_GLSLC_EXECUTABLE - the path to the GLSL SPIR-V compiler
18123 Hints
18125 New in version 3.18.
18126 The VULKAN_SDK environment variable optionally specifies the location
18129 of the Vulkan SDK root directory for the given architecture. It is typ‐
18130 ically set by sourcing the toplevel setup-env.sh script of the Vulkan
18131 SDK directory into the shell environment.
18132 FindWget
18134 Find wget
18135 This module looks for wget. This module defines the following values:
18137 WGET_EXECUTABLE: the full path to the wget tool.
18139 WGET_FOUND: True if wget has been found.
18140 FindWish
18142 Find wish installation
18143 This module finds if TCL is installed and determines where the include
18145 files and libraries are. It also determines what the name of the li‐
18146 brary is. This code sets the following variables:
18147 TK_WISH = the path to the wish executable
18149 if UNIX is defined, then it will look for the cygwin version first
18151 FindwxWidgets
18153 Find a wxWidgets (a.k.a., wxWindows) installation.
18154 This module finds if wxWidgets is installed and selects a default con‐
18156 figuration to use. wxWidgets is a modular library. To specify the
18157 modules that you will use, you need to name them as components to the
18158 package:
18159 find_package(wxWidgets COMPONENTS core base ... OPTIONAL_COMPONENTS net
18161 ...)
18162 New in version 3.4: Support for find_package() version argument; web‐
18164 view component.
18165 New in version 3.14: OPTIONAL_COMPONENTS support.
18168 There are two search branches: a windows style and a unix style. For
18171 windows, the following variables are searched for and set to defaults
18172 in case of multiple choices. Change them if the defaults are not de‐
18173 sired (i.e., these are the only variables you should change to select a
18174 configuration):
18175 wxWidgets_ROOT_DIR - Base wxWidgets directory
18177 (e.g., C:/wxWidgets-2.6.3).
18178 wxWidgets_LIB_DIR - Path to wxWidgets libraries
18179 (e.g., C:/wxWidgets-2.6.3/lib/vc_lib).
18180 wxWidgets_CONFIGURATION - Configuration to use
18181 (e.g., msw, mswd, mswu, mswunivud, etc.)
18182 wxWidgets_EXCLUDE_COMMON_LIBRARIES
18183 - Set to TRUE to exclude linking of
18184 commonly required libs (e.g., png tiff
18185 jpeg zlib regex expat).
18186 For unix style it uses the wx-config utility. You can select between
18188 debug/release, unicode/ansi, universal/non-universal, and static/shared
18189 in the QtDialog or ccmake interfaces by turning ON/OFF the following
18190 variables:
18191 wxWidgets_USE_DEBUG
18193 wxWidgets_USE_UNICODE
18194 wxWidgets_USE_UNIVERSAL
18195 wxWidgets_USE_STATIC
18196 There is also a wxWidgets_CONFIG_OPTIONS variable for all other options
18198 that need to be passed to the wx-config utility. For example, to use
18199 the base toolkit found in the /usr/local path, set the variable (before
18200 calling the FIND_PACKAGE command) as such:
18201 set(wxWidgets_CONFIG_OPTIONS --toolkit=base --prefix=/usr)
18203 The following are set after the configuration is done for both windows
18205 and unix style:
18206 wxWidgets_FOUND - Set to TRUE if wxWidgets was found.
18208 wxWidgets_INCLUDE_DIRS - Include directories for WIN32
18209 i.e., where to find "wx/wx.h" and
18210 "wx/setup.h"; possibly empty for unices.
18211 wxWidgets_LIBRARIES - Path to the wxWidgets libraries.
18212 wxWidgets_LIBRARY_DIRS - compile time link dirs, useful for
18213 rpath on UNIX. Typically an empty string
18214 in WIN32 environment.
18215 wxWidgets_DEFINITIONS - Contains defines required to compile/link
18216 against WX, e.g. WXUSINGDLL
18217 wxWidgets_DEFINITIONS_DEBUG- Contains defines required to compile/link
18218 against WX debug builds, e.g. __WXDEBUG__
18219 wxWidgets_CXX_FLAGS - Include dirs and compiler flags for
18220 unices, empty on WIN32. Essentially
18221 "`wx-config --cxxflags`".
18222 wxWidgets_USE_FILE - Convenience include file.
18223 New in version 3.11: The following environment variables can be used as
18225 hints: WX_CONFIG, WXRC_CMD.
18226 Sample usage:
18229 # Note that for MinGW users the order of libs is important!
18231 find_package(wxWidgets COMPONENTS gl core base OPTIONAL_COMPONENTS net)
18232 if(wxWidgets_FOUND)
18233 include(${wxWidgets_USE_FILE})
18234 # and for each of your dependent executable/library targets:
18235 target_link_libraries(<YourTarget> ${wxWidgets_LIBRARIES})
18236 endif()
18237 If wxWidgets is required (i.e., not an optional part):
18239 find_package(wxWidgets REQUIRED gl core base OPTIONAL_COMPONENTS net)
18241 include(${wxWidgets_USE_FILE})
18242 # and for each of your dependent executable/library targets:
18243 target_link_libraries(<YourTarget> ${wxWidgets_LIBRARIES})
18244 FindX11
18246 Find X11 installation
18247 Try to find X11 on UNIX systems. The following values are defined
18249 X11_FOUND - True if X11 is available
18251 X11_INCLUDE_DIR - include directories to use X11
18252 X11_LIBRARIES - link against these to use X11
18253 and also the following more fine grained variables and targets:
18255 New in version 3.14: Imported targets.
18257 X11_ICE_INCLUDE_PATH, X11_ICE_LIB, X11_ICE_FOUND, X11::ICE
18260 X11_SM_INCLUDE_PATH, X11_SM_LIB, X11_SM_FOUND, X11::SM
18261 X11_X11_INCLUDE_PATH, X11_X11_LIB, X11::X11
18262 X11_Xaccessrules_INCLUDE_PATH,
18263 X11_Xaccessstr_INCLUDE_PATH, X11_Xaccess_FOUND
18264 X11_Xau_INCLUDE_PATH, X11_Xau_LIB, X11_Xau_FOUND, X11::Xau
18265 X11_xcb_INCLUDE_PATH, X11_xcb_LIB, X11_xcb_FOUND, X11::xcb
18266 X11_X11_xcb_INCLUDE_PATH, X11_X11_xcb_LIB, X11_X11_xcb_FOUND, X11::X11_xcb
18267 X11_xcb_icccm_INCLUDE_PATH, X11_xcb_icccm_LIB, X11_xcb_icccm_FOUND, X11::xcb_icccm
18268 X11_xcb_util_INCLUDE_PATH, X11_xcb_util_LIB, X11_xcb_util_FOUND, X11::xcb_util
18269 X11_xcb_xfixes_INCLUDE_PATH, X11_xcb_xfixes_LIB, X11_xcb_xfixes_FOUND, X11::xcb_xfixes
18270 X11_xcb_xkb_INCLUDE_PATH, X11_xcb_xkb_LIB, X11_xcb_xkb_FOUND, X11::xcb_xkb
18271 X11_Xcomposite_INCLUDE_PATH, X11_Xcomposite_LIB, X11_Xcomposite_FOUND, X11::Xcomposite
18272 X11_Xcursor_INCLUDE_PATH, X11_Xcursor_LIB, X11_Xcursor_FOUND, X11::Xcursor
18273 X11_Xdamage_INCLUDE_PATH, X11_Xdamage_LIB, X11_Xdamage_FOUND, X11::Xdamage
18274 X11_Xdmcp_INCLUDE_PATH, X11_Xdmcp_LIB, X11_Xdmcp_FOUND, X11::Xdmcp
18275 X11_Xext_INCLUDE_PATH, X11_Xext_LIB, X11_Xext_FOUND, X11::Xext
18276 X11_Xxf86misc_INCLUDE_PATH, X11_Xxf86misc_LIB, X11_Xxf86misc_FOUND, X11::Xxf86misc
18277 X11_Xxf86vm_INCLUDE_PATH, X11_Xxf86vm_LIB X11_Xxf86vm_FOUND, X11::Xxf86vm
18278 X11_Xfixes_INCLUDE_PATH, X11_Xfixes_LIB, X11_Xfixes_FOUND, X11::Xfixes
18279 X11_Xft_INCLUDE_PATH, X11_Xft_LIB, X11_Xft_FOUND, X11::Xft
18280 X11_Xi_INCLUDE_PATH, X11_Xi_LIB, X11_Xi_FOUND, X11::Xi
18281 X11_Xinerama_INCLUDE_PATH, X11_Xinerama_LIB, X11_Xinerama_FOUND, X11::Xinerama
18282 X11_Xkb_INCLUDE_PATH,
18283 X11_Xkblib_INCLUDE_PATH, X11_Xkb_FOUND, X11::Xkb
18284 X11_xkbcommon_INCLUDE_PATH, X11_xkbcommon_LIB, X11_xkbcommon_FOUND, X11::xkbcommon
18285 X11_xkbcommon_X11_INCLUDE_PATH,X11_xkbcommon_X11_LIB,X11_xkbcommon_X11_FOUND,X11::xkbcommon_X11
18286 X11_xkbfile_INCLUDE_PATH, X11_xkbfile_LIB, X11_xkbfile_FOUND, X11::xkbfile
18287 X11_Xmu_INCLUDE_PATH, X11_Xmu_LIB, X11_Xmu_FOUND, X11::Xmu
18288 X11_Xpm_INCLUDE_PATH, X11_Xpm_LIB, X11_Xpm_FOUND, X11::Xpm
18289 X11_Xtst_INCLUDE_PATH, X11_Xtst_LIB, X11_Xtst_FOUND, X11::Xtst
18290 X11_Xrandr_INCLUDE_PATH, X11_Xrandr_LIB, X11_Xrandr_FOUND, X11::Xrandr
18291 X11_Xrender_INCLUDE_PATH, X11_Xrender_LIB, X11_Xrender_FOUND, X11::Xrender
18292 X11_XRes_INCLUDE_PATH, X11_XRes_LIB, X11_XRes_FOUND, X11::XRes
18293 X11_Xss_INCLUDE_PATH, X11_Xss_LIB, X11_Xss_FOUND, X11::Xss
18294 X11_Xt_INCLUDE_PATH, X11_Xt_LIB, X11_Xt_FOUND, X11::Xt
18295 X11_Xutil_INCLUDE_PATH, X11_Xutil_FOUND, X11::Xutil
18296 X11_Xv_INCLUDE_PATH, X11_Xv_LIB, X11_Xv_FOUND, X11::Xv
18297 X11_dpms_INCLUDE_PATH, (in X11_Xext_LIB), X11_dpms_FOUND
18298 X11_XShm_INCLUDE_PATH, (in X11_Xext_LIB), X11_XShm_FOUND
18299 X11_Xshape_INCLUDE_PATH, (in X11_Xext_LIB), X11_Xshape_FOUND
18300 X11_XSync_INCLUDE_PATH, (in X11_Xext_LIB), X11_XSync_FOUND
18301 X11_Xaw_INCLUDE_PATH, X11_Xaw_LIB X11_Xaw_FOUND X11::Xaw
18302 New in version 3.14: Renamed Xxf86misc, X11_Xxf86misc, X11_Xxf86vm,
18304 X11_xkbfile, X11_Xtst, and X11_Xss libraries to match their file names.
18305 Deprecated the X11_Xinput library. Old names are still available for
18306 compatibility.
18307 New in version 3.14: Added the X11_Xext_INCLUDE_PATH variable.
18310 New in version 3.18: Added the xcb, X11-xcb, xcb-icccm, xcb-xkb, xkb‐
18313 common, and xkbcommon-X11 libraries.
18314 New in version 3.19: Added the Xaw, xcb_util, and xcb_xfixes libraries.
18317 FindXalanC
18320 New in version 3.5.
18321 Find the Apache Xalan-C++ XSL transform processor headers and li‐
18324 braries.
18325 Imported targets
18327 This module defines the following IMPORTED targets:
18328 XalanC::XalanC
18330 The Xalan-C++ xalan-c library, if found.
18331 Result variables
18333 This module will set the following variables in your project:
18334 XalanC_FOUND
18336 true if the Xalan headers and libraries were found
18337 XalanC_VERSION
18339 Xalan release version
18340 XalanC_INCLUDE_DIRS
18342 the directory containing the Xalan headers; note XercesC_IN‐
18343 CLUDE_DIRS is also required
18344 XalanC_LIBRARIES
18346 Xalan libraries to be linked; note XercesC_LIBRARIES is also re‐
18347 quired
18348 Cache variables
18350 The following cache variables may also be set:
18351 XalanC_INCLUDE_DIR
18353 the directory containing the Xalan headers
18354 XalanC_LIBRARY
18356 the Xalan library
18357 FindXCTest
18359 New in version 3.3.
18360 Functions to help creating and executing XCTest bundles.
18363 An XCTest bundle is a CFBundle with a special product-type and bundle
18365 extension. The Mac Developer Library provides more information in the
18366 Testing with Xcode document.
18367 Module Functions
18369 xctest_add_bundle
18370 The xctest_add_bundle function creates a XCTest bundle named
18371 <target> which will test the target <testee>. Supported target
18372 types for testee are Frameworks and App Bundles:
18373 xctest_add_bundle(
18375 <target> # Name of the XCTest bundle
18376 <testee> # Target name of the testee
18377 )
18378 xctest_add_test
18380 The xctest_add_test function adds an XCTest bundle to the
18381 project to be run by ctest(1). The test will be named <name> and
18382 tests <bundle>:
18383 xctest_add_test(
18385 <name> # Test name
18386 <bundle> # Target name of XCTest bundle
18387 )
18388 Module Variables
18390 The following variables are set by including this module:
18391 XCTest_FOUND
18393 True if the XCTest Framework and executable were found.
18394 XCTest_EXECUTABLE
18396 The path to the xctest command line tool used to execute XCTest
18397 bundles.
18398 XCTest_INCLUDE_DIRS
18400 The directory containing the XCTest Framework headers.
18401 XCTest_LIBRARIES
18403 The location of the XCTest Framework.
18404 FindXercesC
18406 New in version 3.1.
18407 Find the Apache Xerces-C++ validating XML parser headers and libraries.
18410 Imported targets
18412 New in version 3.5.
18413 This module defines the following IMPORTED targets:
18416 XercesC::XercesC
18418 The Xerces-C++ xerces-c library, if found.
18419 Result variables
18421 This module will set the following variables in your project:
18422 XercesC_FOUND
18424 true if the Xerces headers and libraries were found
18425 XercesC_VERSION
18427 Xerces release version
18428 XercesC_INCLUDE_DIRS
18430 the directory containing the Xerces headers
18431 XercesC_LIBRARIES
18433 Xerces libraries to be linked
18434 Cache variables
18436 The following cache variables may also be set:
18437 XercesC_INCLUDE_DIR
18439 the directory containing the Xerces headers
18440 XercesC_LIBRARY
18442 the Xerces library
18443 New in version 3.4: Debug and Release variants are found separately.
18445 FindXMLRPC
18448 Find xmlrpc
18449 Find the native XMLRPC headers and libraries.
18451 XMLRPC_INCLUDE_DIRS - where to find xmlrpc.h, etc.
18453 XMLRPC_LIBRARIES - List of libraries when using xmlrpc.
18454 XMLRPC_FOUND - True if xmlrpc found.
18455 XMLRPC modules may be specified as components for this find module.
18457 Modules may be listed by running "xmlrpc-c-config". Modules include:
18458 c++ C++ wrapper code
18460 libwww-client libwww-based client
18461 cgi-server CGI-based server
18462 abyss-server ABYSS-based server
18463 Typical usage:
18465 find_package(XMLRPC REQUIRED libwww-client)
18467 FindZLIB
18469 Find the native ZLIB includes and library.
18470 IMPORTED Targets
18472 New in version 3.1.
18473 This module defines IMPORTED target ZLIB::ZLIB, if ZLIB has been found.
18476 Result Variables
18478 This module defines the following variables:
18479 ZLIB_INCLUDE_DIRS - where to find zlib.h, etc.
18481 ZLIB_LIBRARIES - List of libraries when using zlib.
18482 ZLIB_FOUND - True if zlib found.
18483 ZLIB_VERSION_STRING - The version of zlib found (x.y.z)
18485 ZLIB_VERSION_MAJOR - The major version of zlib
18486 ZLIB_VERSION_MINOR - The minor version of zlib
18487 ZLIB_VERSION_PATCH - The patch version of zlib
18488 ZLIB_VERSION_TWEAK - The tweak version of zlib
18489 New in version 3.4: Debug and Release variants are found separately.
18491 Backward Compatibility
18494 The following variable are provided for backward compatibility
18495 ZLIB_MAJOR_VERSION - The major version of zlib
18497 ZLIB_MINOR_VERSION - The minor version of zlib
18498 ZLIB_PATCH_VERSION - The patch version of zlib
18499 Hints
18501 A user may set ZLIB_ROOT to a zlib installation root to tell this mod‐
18502 ule where to look.
18503
18505 Deprecated Utility Modules
18506 AddFileDependencies
18507 Deprecated since version 3.20.
18508 Add dependencies to a source file.
18511 add_file_dependencies(<source> <files>...)
18513 Adds the given <files> to the dependencies of file <source>.
18515 Do not use this command in new code. It is just a wrapper around:
18517 set_property(SOURCE <source> APPEND PROPERTY OBJECT_DEPENDS <files>...)
18519 Instead use the set_property() command to append to the OBJECT_DEPENDS
18521 source file property directly.
18522 CMakeDetermineVSServicePack
18524 Deprecated since version 3.0: Do not use.
18525 The functionality of this module has been superseded by the
18528 CMAKE_<LANG>_COMPILER_VERSION variable that contains the compiler ver‐
18529 sion number.
18530 Determine the Visual Studio service pack of the 'cl' in use.
18532 Usage:
18534 if(MSVC)
18536 include(CMakeDetermineVSServicePack)
18537 DetermineVSServicePack( my_service_pack )
18538 if( my_service_pack )
18539 message(STATUS "Detected: ${my_service_pack}")
18540 endif()
18541 endif()
18542 Function DetermineVSServicePack sets the given variable to one of the
18544 following values or an empty string if unknown:
18545 vc80, vc80sp1
18547 vc90, vc90sp1
18548 vc100, vc100sp1
18549 vc110, vc110sp1, vc110sp2, vc110sp3, vc110sp4
18550 CMakeExpandImportedTargets
18552 Deprecated since version 3.4: Do not use.
18553 This module was once needed to expand imported targets to the underly‐
18556 ing libraries they reference on disk for use with the try_compile() and
18557 try_run() commands. These commands now support imported libraries in
18558 their LINK_LIBRARIES options (since CMake 2.8.11 for try_compile() and
18559 since CMake 3.2 for try_run()).
18560 This module does not support the policy CMP0022 NEW behavior or use of
18562 the INTERFACE_LINK_LIBRARIES property because generator expressions
18563 cannot be evaluated during configuration.
18564 CMAKE_EXPAND_IMPORTED_TARGETS(<var> LIBRARIES lib1 lib2...libN
18566 [CONFIGURATION <config>])
18567 CMAKE_EXPAND_IMPORTED_TARGETS() takes a list of libraries and replaces
18569 all imported targets contained in this list with their actual file
18570 paths of the referenced libraries on disk, including the libraries from
18571 their link interfaces. If a CONFIGURATION is given, it uses the re‐
18572 spective configuration of the imported targets if it exists. If no
18573 CONFIGURATION is given, it uses the first configuration from
18574 ${CMAKE_CONFIGURATION_TYPES} if set, otherwise ${CMAKE_BUILD_TYPE}.
18575 cmake_expand_imported_targets(expandedLibs
18577 LIBRARIES ${CMAKE_REQUIRED_LIBRARIES}
18578 CONFIGURATION "${CMAKE_TRY_COMPILE_CONFIGURATION}" )
18579 CMakeForceCompiler
18581 Deprecated since version 3.6: Do not use.
18582 The macros provided by this module were once intended for use by
18585 cross-compiling toolchain files when CMake was not able to automati‐
18586 cally detect the compiler identification. Since the introduction of
18587 this module, CMake's compiler identification capabilities have improved
18588 and can now be taught to recognize any compiler. Furthermore, the
18589 suite of information CMake detects from a compiler is now too extensive
18590 to be provided by toolchain files using these macros.
18591 One common use case for this module was to skip CMake's checks for a
18593 working compiler when using a cross-compiler that cannot link binaries
18594 without special flags or custom linker scripts. This case is now sup‐
18595 ported by setting the CMAKE_TRY_COMPILE_TARGET_TYPE variable in the
18596 toolchain file instead.
18597 ----
18600 Macro CMAKE_FORCE_C_COMPILER has the following signature:
18604 CMAKE_FORCE_C_COMPILER(<compiler> <compiler-id>)
18606 It sets CMAKE_C_COMPILER to the given compiler and the cmake internal
18608 variable CMAKE_C_COMPILER_ID to the given compiler-id. It also by‐
18609 passes the check for working compiler and basic compiler information
18610 tests.
18611 Macro CMAKE_FORCE_CXX_COMPILER has the following signature:
18613 CMAKE_FORCE_CXX_COMPILER(<compiler> <compiler-id>)
18615 It sets CMAKE_CXX_COMPILER to the given compiler and the cmake internal
18617 variable CMAKE_CXX_COMPILER_ID to the given compiler-id. It also by‐
18618 passes the check for working compiler and basic compiler information
18619 tests.
18620 Macro CMAKE_FORCE_Fortran_COMPILER has the following signature:
18622 CMAKE_FORCE_Fortran_COMPILER(<compiler> <compiler-id>)
18624 It sets CMAKE_Fortran_COMPILER to the given compiler and the cmake in‐
18626 ternal variable CMAKE_Fortran_COMPILER_ID to the given compiler-id. It
18627 also bypasses the check for working compiler and basic compiler infor‐
18628 mation tests.
18629 So a simple toolchain file could look like this:
18631 include (CMakeForceCompiler)
18633 set(CMAKE_SYSTEM_NAME Generic)
18634 CMAKE_FORCE_C_COMPILER (chc12 MetrowerksHicross)
18635 CMAKE_FORCE_CXX_COMPILER (chc12 MetrowerksHicross)
18636 CMakeParseArguments
18638 This module once implemented the cmake_parse_arguments() command that
18639 is now implemented natively by CMake. It is now an empty placeholder
18640 for compatibility with projects that include it to get the command from
18641 CMake 3.4 and lower.
18642 Documentation
18644 Deprecated since version 3.18: This module does nothing, unless policy
18645 CMP0106 is set to OLD.
18646 This module provides support for the VTK documentation framework. It
18649 relies on several tools (Doxygen, Perl, etc).
18650 MacroAddFileDependencies
18652 Deprecated since version 3.14.
18653 MACRO_ADD_FILE_DEPENDENCIES(<source> <files>...)
18656 Do not use this command in new code. It is just a wrapper around:
18658 set_property(SOURCE <source> APPEND PROPERTY OBJECT_DEPENDS <files>...)
18660 Instead use the set_property() command to append to the OBJECT_DEPENDS
18662 source file property directly.
18663 TestCXXAcceptsFlag
18665 Deprecated since version 3.0: See CheckCXXCompilerFlag.
18666 Check if the CXX compiler accepts a flag.
18669 CHECK_CXX_ACCEPTS_FLAG(<flags> <variable>)
18671 <flags>
18673 the flags to try
18674 <variable>
18676 variable to store the result
18677 UseJavaClassFilelist
18679 Changed in version 3.20: This module was previously documented by mis‐
18680 take and was never meant for direct inclusion by project code. See the
18681 UseJava module.
18682 UseJavaSymlinks
18685 Changed in version 3.20: This module was previously documented by mis‐
18686 take and was never meant for direct inclusion by project code. See the
18687 UseJava module.
18688 UsePkgConfig
18691 Obsolete pkg-config module for CMake, use FindPkgConfig instead.
18692 This module defines the following macro:
18694 PKGCONFIG(package includedir libdir linkflags cflags)
18696 Calling PKGCONFIG will fill the desired information into the 4 given
18698 arguments, e.g. PKGCONFIG(libart-2.0 LIBART_INCLUDE_DIR
18699 LIBART_LINK_DIR LIBART_LINK_FLAGS LIBART_CFLAGS) if pkg-config was NOT
18700 found or the specified software package doesn't exist, the variable
18701 will be empty when the function returns, otherwise they will contain
18702 the respective information
18703 Use_wxWindows
18705 Deprecated since version 2.8.10: Use find_package(wxWidgets) and in‐
18706 clude(${wxWidgets_USE_FILE}) instead.
18707 This convenience include finds if wxWindows is installed and set the
18710 appropriate libs, incdirs, flags etc. author Jan Woetzel <jw -at-
18711 mip.informatik.uni-kiel.de> (07/2003)
18712 USAGE:
18714 just include Use_wxWindows.cmake
18716 in your projects CMakeLists.txt
18717 include( ${CMAKE_MODULE_PATH}/Use_wxWindows.cmake)
18719 if you are sure you need GL then
18721 set(WXWINDOWS_USE_GL 1)
18723 *before* you include this file.
18725 WriteBasicConfigVersionFile
18727 Deprecated since version 3.0: Use the identical command write_ba‐
18728 sic_package_version_file() from module CMakePackageConfigHelpers.
18729 WRITE_BASIC_CONFIG_VERSION_FILE( filename
18732 [VERSION major.minor.patch]
18733 COMPATIBILITY (AnyNewerVersion|SameMajorVersion|SameMinorVersion|ExactVersion)
18734 [ARCH_INDEPENDENT]
18735 )
18736 WriteCompilerDetectionHeader
18738 Deprecated since version 3.20: This module is available only if policy
18739 CMP0120 is not set to NEW. Do not use it in new code.
18740 New in version 3.1.
18743 This module provides the function write_compiler_detection_header().
18746 This function can be used to generate a file suitable for preprocessor
18748 inclusion which contains macros to be used in source code:
18749 write_compiler_detection_header(
18751 FILE <file>
18752 PREFIX <prefix>
18753 [OUTPUT_FILES_VAR <output_files_var> OUTPUT_DIR <output_dir>]
18754 COMPILERS <compiler> [...]
18755 FEATURES <feature> [...]
18756 [BARE_FEATURES <feature> [...]]
18757 [VERSION <version>]
18758 [PROLOG <prolog>]
18759 [EPILOG <epilog>]
18760 [ALLOW_UNKNOWN_COMPILERS]
18761 [ALLOW_UNKNOWN_COMPILER_VERSIONS]
18762 )
18763 This generates the file <file> with macros which all have the prefix
18765 <prefix>.
18766 By default, all content is written directly to the <file>. The OUT‐
18768 PUT_FILES_VAR may be specified to cause the compiler-specific content
18769 to be written to separate files. The separate files are then available
18770 in the <output_files_var> and may be consumed by the caller for instal‐
18771 lation for example. The OUTPUT_DIR specifies a relative path from the
18772 main <file> to the compiler-specific files. For example:
18773 write_compiler_detection_header(
18775 FILE climbingstats_compiler_detection.h
18776 PREFIX ClimbingStats
18777 OUTPUT_FILES_VAR support_files
18778 OUTPUT_DIR compilers
18779 COMPILERS GNU Clang MSVC Intel
18780 FEATURES cxx_variadic_templates
18781 )
18782 install(FILES
18783 ${CMAKE_CURRENT_BINARY_DIR}/climbingstats_compiler_detection.h
18784 DESTINATION include
18785 )
18786 install(FILES
18787 ${support_files}
18788 DESTINATION include/compilers
18789 )
18790 VERSION may be used to specify the API version to be generated. Future
18792 versions of CMake may introduce alternative APIs. A given API is se‐
18793 lected by any <version> value greater than or equal to the version of
18794 CMake that introduced the given API and less than the version of CMake
18795 that introduced its succeeding API. The value of the CMAKE_MINIMUM_RE‐
18796 QUIRED_VERSION variable is used if no explicit version is specified.
18797 (As of CMake version 3.20.3 there is only one API version.)
18798 PROLOG may be specified as text content to write at the start of the
18800 header. EPILOG may be specified as text content to write at the end of
18801 the header
18802 At least one <compiler> and one <feature> must be listed. Compilers
18804 which are known to CMake, but not specified are detected and a pre‐
18805 processor #error is generated for them. A preprocessor macro matching
18806 <PREFIX>_COMPILER_IS_<compiler> is generated for each compiler known to
18807 CMake to contain the value 0 or 1.
18808 Possible compiler identifiers are documented with the CMAKE_<LANG>_COM‐
18810 PILER_ID variable. Available features in this version of CMake are
18811 listed in the CMAKE_C_KNOWN_FEATURES and CMAKE_CXX_KNOWN_FEATURES
18812 global properties. See the cmake-compile-features(7) manual for infor‐
18813 mation on compile features.
18814 New in version 3.2: Added MSVC and AppleClang compiler support.
18816 New in version 3.6: Added Intel compiler support.
18819 Changed in version 3.8: The {c,cxx}_std_* meta-features are ignored if
18822 requested.
18823 New in version 3.8: ALLOW_UNKNOWN_COMPILERS and ALLOW_UNKNOWN_COM‐
18826 PILER_VERSIONS cause the module to generate conditions that treat un‐
18827 known compilers as simply lacking all features. Without these options
18828 the default behavior is to generate a #error for unknown compilers and
18829 versions.
18830 New in version 3.12: BARE_FEATURES will define the compatibility macros
18833 with the name used in newer versions of the language standard, so the
18834 code can use the new feature name unconditionally.
18835 Feature Test Macros
18838 For each compiler, a preprocessor macro is generated matching <PRE‐
18839 FIX>_COMPILER_IS_<compiler> which has the content either 0 or 1, de‐
18840 pending on the compiler in use. Preprocessor macros for compiler ver‐
18841 sion components are generated matching <PREFIX>_COMPILER_VERSION_MAJOR
18842 <PREFIX>_COMPILER_VERSION_MINOR and <PREFIX>_COMPILER_VERSION_PATCH
18843 containing decimal values for the corresponding compiler version compo‐
18844 nents, if defined.
18845 A preprocessor test is generated based on the compiler version denoting
18847 whether each feature is enabled. A preprocessor macro matching <PRE‐
18848 FIX>_COMPILER_<FEATURE>, where <FEATURE> is the upper-case <feature>
18849 name, is generated to contain the value 0 or 1 depending on whether the
18850 compiler in use supports the feature:
18851 write_compiler_detection_header(
18853 FILE climbingstats_compiler_detection.h
18854 PREFIX ClimbingStats
18855 COMPILERS GNU Clang AppleClang MSVC Intel
18856 FEATURES cxx_variadic_templates
18857 )
18858 #if ClimbingStats_COMPILER_CXX_VARIADIC_TEMPLATES
18860 template<typename... T>
18861 void someInterface(T t...) { /* ... */ }
18862 #else
18863 // Compatibility versions
18864 template<typename T1>
18865 void someInterface(T1 t1) { /* ... */ }
18866 template<typename T1, typename T2>
18867 void someInterface(T1 t1, T2 t2) { /* ... */ }
18868 template<typename T1, typename T2, typename T3>
18869 void someInterface(T1 t1, T2 t2, T3 t3) { /* ... */ }
18870 #endif
18871 Symbol Macros
18873 Some additional symbol-defines are created for particular features for
18874 use as symbols which may be conditionally defined empty:
18875 class MyClass ClimbingStats_FINAL
18877 {
18878 ClimbingStats_CONSTEXPR int someInterface() { return 42; }
18879 };
18880 The ClimbingStats_FINAL macro will expand to final if the compiler (and
18882 its flags) support the cxx_final feature, and the ClimbingStats_CONST‐
18883 EXPR macro will expand to constexpr if cxx_constexpr is supported.
18884 If BARE_FEATURES cxx_final was given as argument the final keyword will
18886 be defined for old compilers, too.
18887 The following features generate corresponding symbol defines and if
18889 they are available as BARE_FEATURES:
18890 ┌──────────────────┬────────────────────┬─────────────┬──────┐
18892 │Feature │ Define │ Symbol │ bare │
18893 ├──────────────────┼────────────────────┼─────────────┼──────┤
18894 │c_restrict │ <PREFIX>_RE‐ │ restrict │ yes │
18895 │ │ STRICT │ │ │
18896 ├──────────────────┼────────────────────┼─────────────┼──────┤
18897 │cxx_constexpr │ <PREFIX>_CONST‐ │ constexpr │ yes │
18898 │ │ EXPR │ │ │
18899 ├──────────────────┼────────────────────┼─────────────┼──────┤
18900 │cxx_deleted_func‐ │ <PRE‐ │ = delete │ │
18901 │tions │ FIX>_DELETED_FUNC‐ │ │ │
18902 │ │ TION │ │ │
18903 ├──────────────────┼────────────────────┼─────────────┼──────┤
18904 │cxx_extern_tem‐ │ <PREFIX>_EX‐ │ extern │ │
18905 │plates │ TERN_TEMPLATE │ │ │
18906 ├──────────────────┼────────────────────┼─────────────┼──────┤
18907 │cxx_final │ <PREFIX>_FINAL │ final │ yes │
18908 ├──────────────────┼────────────────────┼─────────────┼──────┤
18909 │cxx_noexcept │ <PREFIX>_NOEXCEPT │ noexcept │ yes │
18910 ├──────────────────┼────────────────────┼─────────────┼──────┤
18911 │cxx_noexcept │ <PREFIX>_NOEX‐ │ noexcept(X) │ │
18912 │ │ CEPT_EXPR(X) │ │ │
18913 ├──────────────────┼────────────────────┼─────────────┼──────┤
18914 │cxx_override │ <PREFIX>_OVERRIDE │ override │ yes │
18915 └──────────────────┴────────────────────┴─────────────┴──────┘
18916 Compatibility Implementation Macros
18918 Some features are suitable for wrapping in a macro with a backward com‐
18919 patibility implementation if the compiler does not support the feature.
18920 When the cxx_static_assert feature is not provided by the compiler, a
18922 compatibility implementation is available via the <PREFIX>_STATIC_AS‐
18923 SERT(COND) and <PREFIX>_STATIC_ASSERT_MSG(COND, MSG) function-like
18924 macros. The macros expand to static_assert where that compiler feature
18925 is available, and to a compatibility implementation otherwise. In the
18926 first form, the condition is stringified in the message field of
18927 static_assert. In the second form, the message MSG is passed to the
18928 message field of static_assert, or ignored if using the backward com‐
18929 patibility implementation.
18930 The cxx_attribute_deprecated feature provides a macro definition <PRE‐
18932 FIX>_DEPRECATED, which expands to either the standard [[deprecated]]
18933 attribute or a compiler-specific decorator such as __attri‐
18934 bute__((__deprecated__)) used by GNU compilers.
18935 The cxx_alignas feature provides a macro definition <PREFIX>_ALIGNAS
18937 which expands to either the standard alignas decorator or a com‐
18938 piler-specific decorator such as __attribute__ ((__aligned__)) used by
18939 GNU compilers.
18940 The cxx_alignof feature provides a macro definition <PREFIX>_ALIGNOF
18942 which expands to either the standard alignof decorator or a com‐
18943 piler-specific decorator such as __alignof__ used by GNU compilers.
18944 ┌─────────────────┬──────────────────┬────────────────┬──────┐
18946 │Feature │ Define │ Symbol │ bare │
18947 ├─────────────────┼──────────────────┼────────────────┼──────┤
18948 │cxx_alignas │ <PREFIX>_ALIGNAS │ alignas │ │
18949 ├─────────────────┼──────────────────┼────────────────┼──────┤
18950 │cxx_alignof │ <PREFIX>_ALIGNOF │ alignof │ │
18951 ├─────────────────┼──────────────────┼────────────────┼──────┤
18952 │cxx_nullptr │ <PREFIX>_NULLPTR │ nullptr │ yes │
18953 ├─────────────────┼──────────────────┼────────────────┼──────┤
18954 │cxx_static_as‐ │ <PRE‐ │ static_assert │ │
18955 │sert │ FIX>_STATIC_AS‐ │ │ │
18956 │ │ SERT │ │ │
18957 ├─────────────────┼──────────────────┼────────────────┼──────┤
18958 │cxx_static_as‐ │ <PRE‐ │ static_assert │ │
18959 │sert │ FIX>_STATIC_AS‐ │ │ │
18960 │ │ SERT_MSG │ │ │
18961 ├─────────────────┼──────────────────┼────────────────┼──────┤
18962 │cxx_attri‐ │ <PREFIX>_DEPRE‐ │ [[deprecated]] │ │
18963 │bute_deprecated │ CATED │ │ │
18964 ├─────────────────┼──────────────────┼────────────────┼──────┤
18965 │cxx_attri‐ │ <PREFIX>_DEPRE‐ │ [[deprecated]] │ │
18966 │bute_deprecated │ CATED_MSG │ │ │
18967 ├─────────────────┼──────────────────┼────────────────┼──────┤
18968 │cxx_thread_local │ <PRE‐ │ thread_local │ │
18969 │ │ FIX>_THREAD_LO‐ │ │ │
18970 │ │ CAL │ │ │
18971 └─────────────────┴──────────────────┴────────────────┴──────┘
18972 A use-case which arises with such deprecation macros is the deprecation
18974 of an entire library. In that case, all public API in the library may
18975 be decorated with the <PREFIX>_DEPRECATED macro. This results in very
18976 noisy build output when building the library itself, so the macro may
18977 be may be defined to empty in that case when building the deprecated
18978 library:
18979 add_library(compat_support ${srcs})
18981 target_compile_definitions(compat_support
18982 PRIVATE
18983 CompatSupport_DEPRECATED=
18984 )
18985 Example Usage
18987 NOTE:
18988 This section was migrated from the cmake-compile-features(7) manual
18989 since it relies on the WriteCompilerDetectionHeader module which is
18990 removed by policy CMP0120.
18991 Compile features may be preferred if available, without creating a hard
18993 requirement. For example, a library may provide alternative implemen‐
18994 tations depending on whether the cxx_variadic_templates feature is
18995 available:
18996 #if Foo_COMPILER_CXX_VARIADIC_TEMPLATES
18998 template<int I, int... Is>
18999 struct Interface;
19000 template<int I>
19002 struct Interface<I>
19003 {
19004 static int accumulate()
19005 {
19006 return I;
19007 }
19008 };
19009 template<int I, int... Is>
19011 struct Interface
19012 {
19013 static int accumulate()
19014 {
19015 return I + Interface<Is...>::accumulate();
19016 }
19017 };
19018 #else
19019 template<int I1, int I2 = 0, int I3 = 0, int I4 = 0>
19020 struct Interface
19021 {
19022 static int accumulate() { return I1 + I2 + I3 + I4; }
19023 };
19024 #endif
19025 Such an interface depends on using the correct preprocessor defines for
19027 the compiler features. CMake can generate a header file containing
19028 such defines using the WriteCompilerDetectionHeader module. The module
19029 contains the write_compiler_detection_header function which accepts pa‐
19030 rameters to control the content of the generated header file:
19031 write_compiler_detection_header(
19033 FILE "${CMAKE_CURRENT_BINARY_DIR}/foo_compiler_detection.h"
19034 PREFIX Foo
19035 COMPILERS GNU
19036 FEATURES
19037 cxx_variadic_templates
19038 )
19039 Such a header file may be used internally in the source code of a
19041 project, and it may be installed and used in the interface of library
19042 code.
19043 For each feature listed in FEATURES, a preprocessor definition is cre‐
19045 ated in the header file, and defined to either 1 or 0.
19046 Additionally, some features call for additional defines, such as the
19048 cxx_final and cxx_override features. Rather than being used in #ifdef
19049 code, the final keyword is abstracted by a symbol which is defined to
19050 either final, a compiler-specific equivalent, or to empty. That way,
19051 C++ code can be written to unconditionally use the symbol, and compiler
19052 support determines what it is expanded to:
19053 struct Interface {
19055 virtual void Execute() = 0;
19056 };
19057 struct Concrete Foo_FINAL {
19059 void Execute() Foo_OVERRIDE;
19060 };
19061 In this case, Foo_FINAL will expand to final if the compiler supports
19063 the keyword, or to empty otherwise.
19064 In this use-case, the project code may wish to enable a particular lan‐
19066 guage standard if available from the compiler. The CXX_STANDARD target
19067 property may be set to the desired language standard for a particular
19068 target, and the CMAKE_CXX_STANDARD variable may be set to influence all
19069 following targets:
19070 write_compiler_detection_header(
19072 FILE "${CMAKE_CURRENT_BINARY_DIR}/foo_compiler_detection.h"
19073 PREFIX Foo
19074 COMPILERS GNU
19075 FEATURES
19076 cxx_final cxx_override
19077 )
19078 # Includes foo_compiler_detection.h and uses the Foo_FINAL symbol
19080 # which will expand to 'final' if the compiler supports the requested
19081 # CXX_STANDARD.
19082 add_library(foo foo.cpp)
19083 set_property(TARGET foo PROPERTY CXX_STANDARD 11)
19084 # Includes foo_compiler_detection.h and uses the Foo_FINAL symbol
19086 # which will expand to 'final' if the compiler supports the feature,
19087 # even though CXX_STANDARD is not set explicitly. The requirement of
19088 # cxx_constexpr causes CMake to set CXX_STANDARD internally, which
19089 # affects the compile flags.
19090 add_library(foo_impl foo_impl.cpp)
19091 target_compile_features(foo_impl PRIVATE cxx_constexpr)
19092 The write_compiler_detection_header function also creates compatibility
19094 code for other features which have standard equivalents. For example,
19095 the cxx_static_assert feature is emulated with a template and ab‐
19096 stracted via the <PREFIX>_STATIC_ASSERT and <PREFIX>_STATIC_ASSERT_MSG
19097 function-macros.
19098 Deprecated Find Modules
19100 FindCUDA
19101 Deprecated since version 3.10.
19102 It is no longer necessary to use this module or call find_package(CUDA)
19105 for compiling CUDA code. Instead, list CUDA among the languages named
19106 in the top-level call to the project() command, or call the enable_lan‐
19107 guage() command with CUDA. Then one can add CUDA (.cu) sources to pro‐
19108 grams directly in calls to add_library() and add_executable().
19109 New in version 3.17: To find and use the CUDA toolkit libraries the
19111 FindCUDAToolkit module has superseded this module. It works whether or
19112 not the CUDA language is enabled.
19113 Documentation of Deprecated Usage
19116 Tools for building CUDA C files: libraries and build dependencies.
19117 This script locates the NVIDIA CUDA C tools. It should work on Linux,
19119 Windows, and macOS and should be reasonably up to date with CUDA C re‐
19120 leases.
19121 New in version 3.19: QNX support.
19123 This script makes use of the standard find_package() arguments of <VER‐
19126 SION>, REQUIRED and QUIET. CUDA_FOUND will report if an acceptable
19127 version of CUDA was found.
19128 The script will prompt the user to specify CUDA_TOOLKIT_ROOT_DIR if the
19130 prefix cannot be determined by the location of nvcc in the system path
19131 and REQUIRED is specified to find_package(). To use a different in‐
19132 stalled version of the toolkit set the environment variable
19133 CUDA_BIN_PATH before running cmake (e.g. CUDA_BIN_PATH=/usr/lo‐
19134 cal/cuda1.0 instead of the default /usr/local/cuda) or set CUDA_TOOL‐
19135 KIT_ROOT_DIR after configuring. If you change the value of CUDA_TOOL‐
19136 KIT_ROOT_DIR, various components that depend on the path will be relo‐
19137 cated.
19138 It might be necessary to set CUDA_TOOLKIT_ROOT_DIR manually on certain
19140 platforms, or to use a CUDA runtime not installed in the default loca‐
19141 tion. In newer versions of the toolkit the CUDA library is included
19142 with the graphics driver -- be sure that the driver version matches
19143 what is needed by the CUDA runtime version.
19144 Input Variables
19146 The following variables affect the behavior of the macros in the script
19147 (in alphabetical order). Note that any of these flags can be changed
19148 multiple times in the same directory before calling cuda_add_exe‐
19149 cutable(), cuda_add_library(), cuda_compile(), cuda_compile_ptx(),
19150 cuda_compile_fatbin(), cuda_compile_cubin() or cuda_wrap_srcs():
19151 CUDA_64_BIT_DEVICE_CODE (Default: host bit size)
19153 Set to ON to compile for 64 bit device code, OFF for 32 bit de‐
19154 vice code. Note that making this different from the host code
19155 when generating object or C files from CUDA code just won't
19156 work, because size_t gets defined by nvcc in the generated
19157 source. If you compile to PTX and then load the file yourself,
19158 you can mix bit sizes between device and host.
19159 CUDA_ATTACH_VS_BUILD_RULE_TO_CUDA_FILE (Default: ON)
19161 Set to ON if you want the custom build rule to be attached to
19162 the source file in Visual Studio. Turn OFF if you add the same
19163 cuda file to multiple targets.
19164 This allows the user to build the target from the CUDA file;
19166 however, bad things can happen if the CUDA source file is added
19167 to multiple targets. When performing parallel builds it is pos‐
19168 sible for the custom build command to be run more than once and
19169 in parallel causing cryptic build errors. VS runs the rules for
19170 every source file in the target, and a source can have only one
19171 rule no matter how many projects it is added to. When the rule
19172 is run from multiple targets race conditions can occur on the
19173 generated file. Eventually everything will get built, but if
19174 the user is unaware of this behavior, there may be confusion.
19175 It would be nice if this script could detect the reuse of source
19176 files across multiple targets and turn the option off for the
19177 user, but no good solution could be found.
19178 CUDA_BUILD_CUBIN (Default: OFF)
19180 Set to ON to enable and extra compilation pass with the -cubin
19181 option in Device mode. The output is parsed and register, shared
19182 memory usage is printed during build.
19183 CUDA_BUILD_EMULATION (Default: OFF for device mode)
19185 Set to ON for Emulation mode. -D_DEVICEEMU is defined for CUDA C
19186 files when CUDA_BUILD_EMULATION is TRUE.
19187 CUDA_LINK_LIBRARIES_KEYWORD (Default: "")
19189 New in version 3.9.
19190 The <PRIVATE|PUBLIC|INTERFACE> keyword to use for internal tar‐
19193 get_link_libraries() calls. The default is to use no keyword
19194 which uses the old "plain" form of target_link_libraries(). Note
19195 that is matters because whatever is used inside the FindCUDA
19196 module must also be used outside - the two forms of tar‐
19197 get_link_libraries() cannot be mixed.
19198 CUDA_GENERATED_OUTPUT_DIR (Default: CMAKE_CURRENT_BINARY_DIR)
19200 Set to the path you wish to have the generated files placed. If
19201 it is blank output files will be placed in CMAKE_CURRENT_BI‐
19202 NARY_DIR. Intermediate files will always be placed in
19203 CMAKE_CURRENT_BINARY_DIR/CMakeFiles.
19204 CUDA_HOST_COMPILATION_CPP (Default: ON)
19206 Set to OFF for C compilation of host code.
19207 CUDA_HOST_COMPILER (Default: CMAKE_C_COMPILER)
19209 Set the host compiler to be used by nvcc. Ignored if -ccbin or
19210 --compiler-bindir is already present in the CUDA_NVCC_FLAGS or
19211 CUDA_NVCC_FLAGS_<CONFIG> variables. For Visual Studio targets,
19212 the host compiler is constructed with one or more visual studio
19213 macros such as $(VCInstallDir), that expands out to the path
19214 when the command is run from within VS.
19215 New in version 3.13: If the CUDAHOSTCXX environment variable is
19217 set it will be used as the default.
19218 CUDA_NVCC_FLAGS, CUDA_NVCC_FLAGS_<CONFIG>
19221 Additional NVCC command line arguments. NOTE: multiple argu‐
19222 ments must be semi-colon delimited (e.g. --compiler-op‐
19223 tions;-Wall)
19224 New in version 3.6: Contents of these variables may use genera‐
19226 tor expressions.
19227 CUDA_PROPAGATE_HOST_FLAGS (Default: ON)
19230 Set to ON to propagate CMAKE_{C,CXX}_FLAGS and their configura‐
19231 tion dependent counterparts (e.g. CMAKE_C_FLAGS_DEBUG) automati‐
19232 cally to the host compiler through nvcc's -Xcompiler flag. This
19233 helps make the generated host code match the rest of the system
19234 better. Sometimes certain flags give nvcc problems, and this
19235 will help you turn the flag propagation off. This does not af‐
19236 fect the flags supplied directly to nvcc via CUDA_NVCC_FLAGS or
19237 through the OPTION flags specified through cuda_add_library(),
19238 cuda_add_executable(), or cuda_wrap_srcs(). Flags used for
19239 shared library compilation are not affected by this flag.
19240 CUDA_SEPARABLE_COMPILATION (Default: OFF)
19242 If set this will enable separable compilation for all CUDA run‐
19243 time object files. If used outside of cuda_add_executable() and
19244 cuda_add_library() (e.g. calling cuda_wrap_srcs() directly),
19245 cuda_compute_separable_compilation_object_file_name() and
19246 cuda_link_separable_compilation_objects() should be called.
19247 CUDA_SOURCE_PROPERTY_FORMAT
19249 New in version 3.3.
19250 If this source file property is set, it can override the format
19253 specified to cuda_wrap_srcs() (OBJ, PTX, CUBIN, or FATBIN). If
19254 an input source file is not a .cu file, setting this file will
19255 cause it to be treated as a .cu file. See documentation for
19256 set_source_files_properties on how to set this property.
19257 CUDA_USE_STATIC_CUDA_RUNTIME (Default: ON)
19259 New in version 3.3.
19260 When enabled the static version of the CUDA runtime library will
19263 be used in CUDA_LIBRARIES. If the version of CUDA configured
19264 doesn't support this option, then it will be silently disabled.
19265 CUDA_VERBOSE_BUILD (Default: OFF)
19267 Set to ON to see all the commands used when building the CUDA
19268 file. When using a Makefile generator the value defaults to
19269 VERBOSE (run make VERBOSE=1 to see output), although setting
19270 CUDA_VERBOSE_BUILD to ON will always print the output.
19271 Commands
19273 The script creates the following functions and macros (in alphabetical
19274 order):
19275 cuda_add_cufft_to_target(<cuda_target>)
19277 Adds the cufft library to the target (can be any target). Handles
19279 whether you are in emulation mode or not.
19280 cuda_add_cublas_to_target(<cuda_target>)
19282 Adds the cublas library to the target (can be any target). Handles
19284 whether you are in emulation mode or not.
19285 cuda_add_executable(<cuda_target> <file>...
19287 [WIN32] [MACOSX_BUNDLE] [EXCLUDE_FROM_ALL] [OPTIONS ...])
19288 Creates an executable <cuda_target> which is made up of the files spec‐
19290 ified. All of the non CUDA C files are compiled using the standard
19291 build rules specified by CMake and the CUDA files are compiled to ob‐
19292 ject files using nvcc and the host compiler. In addition CUDA_IN‐
19293 CLUDE_DIRS is added automatically to include_directories(). Some stan‐
19294 dard CMake target calls can be used on the target after calling this
19295 macro (e.g. set_target_properties() and target_link_libraries()), but
19296 setting properties that adjust compilation flags will not affect code
19297 compiled by nvcc. Such flags should be modified before calling
19298 cuda_add_executable(), cuda_add_library() or cuda_wrap_srcs().
19299 cuda_add_library(<cuda_target> <file>...
19301 [STATIC | SHARED | MODULE] [EXCLUDE_FROM_ALL] [OPTIONS ...])
19302 Same as cuda_add_executable() except that a library is created.
19304 cuda_build_clean_target()
19306 Creates a convenience target that deletes all the dependency files gen‐
19308 erated. You should make clean after running this target to ensure the
19309 dependency files get regenerated.
19310 cuda_compile(<generated_files> <file>... [STATIC | SHARED | MODULE]
19312 [OPTIONS ...])
19313 Returns a list of generated files from the input source files to be
19315 used with add_library() or add_executable().
19316 cuda_compile_ptx(<generated_files> <file>... [OPTIONS ...])
19318 Returns a list of PTX files generated from the input source files.
19320 cuda_compile_fatbin(<generated_files> <file>... [OPTIONS ...])
19322 New in version 3.1.
19324 Returns a list of FATBIN files generated from the input source files.
19327 cuda_compile_cubin(<generated_files> <file>... [OPTIONS ...])
19329 New in version 3.1.
19331 Returns a list of CUBIN files generated from the input source files.
19334 cuda_compute_separable_compilation_object_file_name(<output_file_var>
19336 <cuda_target>
19337 <object_files>)
19338 Compute the name of the intermediate link file used for separable com‐
19340 pilation. This file name is typically passed into CUDA_LINK_SEPARA‐
19341 BLE_COMPILATION_OBJECTS. output_file_var is produced based on
19342 cuda_target the list of objects files that need separable compilation
19343 as specified by <object_files>. If the <object_files> list is empty,
19344 then <output_file_var> will be empty. This function is called automat‐
19345 ically for cuda_add_library() and cuda_add_executable(). Note that
19346 this is a function and not a macro.
19347 cuda_include_directories(path0 path1 ...)
19349 Sets the directories that should be passed to nvcc (e.g. nvcc -Ipath0
19351 -Ipath1 ...). These paths usually contain other .cu files.
19352 cuda_link_separable_compilation_objects(<output_file_var> <cuda_target>
19354 <nvcc_flags> <object_files>)
19355 Generates the link object required by separable compilation from the
19357 given object files. This is called automatically for cuda_add_exe‐
19358 cutable() and cuda_add_library(), but can be called manually when using
19359 cuda_wrap_srcs() directly. When called from cuda_add_library() or
19360 cuda_add_executable() the <nvcc_flags> passed in are the same as the
19361 flags passed in via the OPTIONS argument. The only nvcc flag added au‐
19362 tomatically is the bitness flag as specified by CUDA_64_BIT_DE‐
19363 VICE_CODE. Note that this is a function instead of a macro.
19364 cuda_select_nvcc_arch_flags(<out_variable> [<target_CUDA_architecture> ...])
19366 Selects GPU arch flags for nvcc based on target_CUDA_architecture.
19368 Values for target_CUDA_architecture:
19370 • Auto: detects local machine GPU compute arch at runtime.
19372 • Common and All: cover common and entire subsets of architectures.
19374 • <name>: one of Fermi, Kepler, Maxwell, Kepler+Tegra, Kepler+Tesla,
19376 Maxwell+Tegra, Pascal.
19377 • <ver>, <ver>(<ver>), <ver>+PTX, where <ver> is one of 2.0, 2.1, 3.0,
19379 3.2, 3.5, 3.7, 5.0, 5.2, 5.3, 6.0, 6.2.
19380 Returns list of flags to be added to CUDA_NVCC_FLAGS in <out_variable>.
19382 Additionally, sets <out_variable>_readable to the resulting numeric
19383 list.
19384 Example:
19386 cuda_select_nvcc_arch_flags(ARCH_FLAGS 3.0 3.5+PTX 5.2(5.0) Maxwell)
19388 list(APPEND CUDA_NVCC_FLAGS ${ARCH_FLAGS})
19389 More info on CUDA architectures: https://en.wikipedia.org/wiki/CUDA.
19391 Note that this is a function instead of a macro.
19392 cuda_wrap_srcs(<cuda_target> <format> <generated_files> <file>...
19394 [STATIC | SHARED | MODULE] [OPTIONS ...])
19395 This is where all the magic happens. cuda_add_executable(),
19397 cuda_add_library(), cuda_compile(), and cuda_compile_ptx() all call
19398 this function under the hood.
19399 Given the list of files <file>... this macro generates custom commands
19401 that generate either PTX or linkable objects (use PTX or OBJ for the
19402 <format> argument to switch). Files that don't end with .cu or have
19403 the HEADER_FILE_ONLY property are ignored.
19404 The arguments passed in after OPTIONS are extra command line options to
19406 give to nvcc. You can also specify per configuration options by speci‐
19407 fying the name of the configuration followed by the options. General
19408 options must precede configuration specific options. Not all configu‐
19409 rations need to be specified, only the ones provided will be used. For
19410 example:
19411 cuda_add_executable(...
19413 OPTIONS -DFLAG=2 "-DFLAG_OTHER=space in flag"
19414 DEBUG -g
19415 RELEASE --use_fast_math
19416 RELWITHDEBINFO --use_fast_math;-g
19417 MINSIZEREL --use_fast_math)
19418 For certain configurations (namely VS generating object files with
19420 CUDA_ATTACH_VS_BUILD_RULE_TO_CUDA_FILE set to ON), no generated file
19421 will be produced for the given cuda file. This is because when you add
19422 the cuda file to Visual Studio it knows that this file produces an ob‐
19423 ject file and will link in the resulting object file automatically.
19424 This script will also generate a separate cmake script that is used at
19426 build time to invoke nvcc. This is for several reasons:
19427 • nvcc can return negative numbers as return values which confuses Vis‐
19429 ual Studio into thinking that the command succeeded. The script now
19430 checks the error codes and produces errors when there was a problem.
19431 • nvcc has been known to not delete incomplete results when it encoun‐
19433 ters problems. This confuses build systems into thinking the target
19434 was generated when in fact an unusable file exists. The script now
19435 deletes the output files if there was an error.
19436 • By putting all the options that affect the build into a file and then
19438 make the build rule dependent on the file, the output files will be
19439 regenerated when the options change.
19440 This script also looks at optional arguments STATIC, SHARED, or MODULE
19442 to determine when to target the object compilation for a shared li‐
19443 brary. BUILD_SHARED_LIBS is ignored in cuda_wrap_srcs(), but it is re‐
19444 spected in cuda_add_library(). On some systems special flags are added
19445 for building objects intended for shared libraries. A preprocessor
19446 macro, <target_name>_EXPORTS is defined when a shared library compila‐
19447 tion is detected.
19448 Flags passed into add_definitions with -D or /D are passed along to
19450 nvcc.
19451 Result Variables
19453 The script defines the following variables:
19454 CUDA_VERSION_MAJOR
19456 The major version of cuda as reported by nvcc.
19457 CUDA_VERSION_MINOR
19459 The minor version.
19460 CUDA_VERSION, CUDA_VERSION_STRING
19462 Full version in the X.Y format.
19463 CUDA_HAS_FP16
19465 New in version 3.6: Whether a short float (float16, fp16) is
19466 supported.
19467 CUDA_TOOLKIT_ROOT_DIR
19470 Path to the CUDA Toolkit (defined if not set).
19471 CUDA_SDK_ROOT_DIR
19473 Path to the CUDA SDK. Use this to find files in the SDK. This
19474 script will not directly support finding specific libraries or
19475 headers, as that isn't supported by NVIDIA. If you want to
19476 change libraries when the path changes see the FindCUDA.cmake
19477 script for an example of how to clear these variables. There
19478 are also examples of how to use the CUDA_SDK_ROOT_DIR to locate
19479 headers or libraries, if you so choose (at your own risk).
19480 CUDA_INCLUDE_DIRS
19482 Include directory for cuda headers. Added automatically for
19483 cuda_add_executable() and cuda_add_library().
19484 CUDA_LIBRARIES
19486 Cuda RT library.
19487 CUDA_CUFFT_LIBRARIES
19489 Device or emulation library for the Cuda FFT implementation (al‐
19490 ternative to cuda_add_cufft_to_target() macro)
19491 CUDA_CUBLAS_LIBRARIES
19493 Device or emulation library for the Cuda BLAS implementation
19494 (alternative to cuda_add_cublas_to_target() macro).
19495 CUDA_cudart_static_LIBRARY
19497 Statically linkable cuda runtime library. Only available for
19498 CUDA version 5.5+.
19499 CUDA_cudadevrt_LIBRARY
19501 New in version 3.7: Device runtime library. Required for sepa‐
19502 rable compilation.
19503 CUDA_cupti_LIBRARY
19506 CUDA Profiling Tools Interface library. Only available for CUDA
19507 version 4.0+.
19508 CUDA_curand_LIBRARY
19510 CUDA Random Number Generation library. Only available for CUDA
19511 version 3.2+.
19512 CUDA_cusolver_LIBRARY
19514 New in version 3.2: CUDA Direct Solver library. Only available
19515 for CUDA version 7.0+.
19516 CUDA_cusparse_LIBRARY
19519 CUDA Sparse Matrix library. Only available for CUDA version
19520 3.2+.
19521 CUDA_npp_LIBRARY
19523 NVIDIA Performance Primitives lib. Only available for CUDA ver‐
19524 sion 4.0+.
19525 CUDA_nppc_LIBRARY
19527 NVIDIA Performance Primitives lib (core). Only available for
19528 CUDA version 5.5+.
19529 CUDA_nppi_LIBRARY
19531 NVIDIA Performance Primitives lib (image processing). Only
19532 available for CUDA version 5.5 - 8.0.
19533 CUDA_nppial_LIBRARY
19535 NVIDIA Performance Primitives lib (image processing). Only
19536 available for CUDA version 9.0.
19537 CUDA_nppicc_LIBRARY
19539 NVIDIA Performance Primitives lib (image processing). Only
19540 available for CUDA version 9.0.
19541 CUDA_nppicom_LIBRARY
19543 NVIDIA Performance Primitives lib (image processing). Only
19544 available for CUDA version 9.0 - 10.2. Replaced by nvjpeg.
19545 CUDA_nppidei_LIBRARY
19547 NVIDIA Performance Primitives lib (image processing). Only
19548 available for CUDA version 9.0.
19549 CUDA_nppif_LIBRARY
19551 NVIDIA Performance Primitives lib (image processing). Only
19552 available for CUDA version 9.0.
19553 CUDA_nppig_LIBRARY
19555 NVIDIA Performance Primitives lib (image processing). Only
19556 available for CUDA version 9.0.
19557 CUDA_nppim_LIBRARY
19559 NVIDIA Performance Primitives lib (image processing). Only
19560 available for CUDA version 9.0.
19561 CUDA_nppist_LIBRARY
19563 NVIDIA Performance Primitives lib (image processing). Only
19564 available for CUDA version 9.0.
19565 CUDA_nppisu_LIBRARY
19567 NVIDIA Performance Primitives lib (image processing). Only
19568 available for CUDA version 9.0.
19569 CUDA_nppitc_LIBRARY
19571 NVIDIA Performance Primitives lib (image processing). Only
19572 available for CUDA version 9.0.
19573 CUDA_npps_LIBRARY
19575 NVIDIA Performance Primitives lib (signal processing). Only
19576 available for CUDA version 5.5+.
19577 CUDA_nvcuvenc_LIBRARY
19579 CUDA Video Encoder library. Only available for CUDA version
19580 3.2+. Windows only.
19581 CUDA_nvcuvid_LIBRARY
19583 CUDA Video Decoder library. Only available for CUDA version
19584 3.2+. Windows only.
19585 CUDA_nvToolsExt_LIBRARY
19587 New in version 3.16: NVIDA CUDA Tools Extension library. Avail‐
19588 able for CUDA version 5+.
19589 CUDA_OpenCL_LIBRARY
19592 New in version 3.16: NVIDA CUDA OpenCL library. Available for
19593 CUDA version 5+.
19594 FindPythonInterp
19597 Deprecated since version 3.12: Use FindPython3, FindPython2 or Find‐
19598 Python instead.
19599 Find python interpreter
19602 This module finds if Python interpreter is installed and determines
19604 where the executables are. This code sets the following variables:
19605 PYTHONINTERP_FOUND - Was the Python executable found
19607 PYTHON_EXECUTABLE - path to the Python interpreter
19608 PYTHON_VERSION_STRING - Python version found e.g. 2.5.2
19610 PYTHON_VERSION_MAJOR - Python major version found e.g. 2
19611 PYTHON_VERSION_MINOR - Python minor version found e.g. 5
19612 PYTHON_VERSION_PATCH - Python patch version found e.g. 2
19613 The Python_ADDITIONAL_VERSIONS variable can be used to specify a list
19615 of version numbers that should be taken into account when searching for
19616 Python. You need to set this variable before calling find_pack‐
19617 age(PythonInterp).
19618 If calling both find_package(PythonInterp) and find_package(Python‐
19620 Libs), call find_package(PythonInterp) first to get the currently ac‐
19621 tive Python version by default with a consistent version of PYTHON_LI‐
19622 BRARIES.
19623 NOTE:
19625 A call to find_package(PythonInterp ${V}) for python version V may
19626 find a python executable with no version suffix. In this case no
19627 attempt is made to avoid python executables from other versions.
19628 Use FindPython3, FindPython2 or FindPython instead.
19629 FindPythonLibs
19631 Deprecated since version 3.12: Use FindPython3, FindPython2 or Find‐
19632 Python instead.
19633 Find python libraries
19636 This module finds if Python is installed and determines where the in‐
19638 clude files and libraries are. It also determines what the name of the
19639 library is. This code sets the following variables:
19640 PYTHONLIBS_FOUND - have the Python libs been found
19642 PYTHON_LIBRARIES - path to the python library
19643 PYTHON_INCLUDE_PATH - path to where Python.h is found (deprecated)
19644 PYTHON_INCLUDE_DIRS - path to where Python.h is found
19645 PYTHON_DEBUG_LIBRARIES - path to the debug library (deprecated)
19646 PYTHONLIBS_VERSION_STRING - version of the Python libs found (since CMake 2.8.8)
19647 The Python_ADDITIONAL_VERSIONS variable can be used to specify a list
19649 of version numbers that should be taken into account when searching for
19650 Python. You need to set this variable before calling find_pack‐
19651 age(PythonLibs).
19652 If you'd like to specify the installation of Python to use, you should
19654 modify the following cache variables:
19655 PYTHON_LIBRARY - path to the python library
19657 PYTHON_INCLUDE_DIR - path to where Python.h is found
19658 If calling both find_package(PythonInterp) and find_package(Python‐
19660 Libs), call find_package(PythonInterp) first to get the currently ac‐
19661 tive Python version by default with a consistent version of PYTHON_LI‐
19662 BRARIES.
19663 FindQt
19665 Deprecated since version 3.14: This module is available only if policy
19666 CMP0084 is not set to NEW.
19667 Searches for all installed versions of Qt3 or Qt4.
19670 This module cannot handle Qt5 or any later versions. For those, see
19672 cmake-qt(7).
19673 This module should only be used if your project can work with multiple
19675 versions of Qt. If not, you should just directly use FindQt4 or
19676 FindQt3. If multiple versions of Qt are found on the machine, then The
19677 user must set the option DESIRED_QT_VERSION to the version they want to
19678 use. If only one version of qt is found on the machine, then the DE‐
19679 SIRED_QT_VERSION is set to that version and the matching FindQt3 or
19680 FindQt4 module is included. Once the user sets DESIRED_QT_VERSION,
19681 then the FindQt3 or FindQt4 module is included.
19682 QT_REQUIRED if this is set to TRUE then if CMake can
19684 not find Qt4 or Qt3 an error is raised
19685 and a message is sent to the user.
19686 DESIRED_QT_VERSION OPTION is created
19688 QT4_INSTALLED is set to TRUE if qt4 is found.
19689 QT3_INSTALLED is set to TRUE if qt3 is found.
19690 FindwxWindows
19692 Deprecated since version 3.0: Replaced by FindwxWidgets.
19693 Find wxWindows (wxWidgets) installation
19696 This module finds if wxWindows/wxWidgets is installed and determines
19698 where the include files and libraries are. It also determines what the
19699 name of the library is. This code sets the following variables:
19700 WXWINDOWS_FOUND = system has WxWindows
19702 WXWINDOWS_LIBRARIES = path to the wxWindows libraries
19703 on Unix/Linux with additional
19704 linker flags from
19705 "wx-config --libs"
19706 CMAKE_WXWINDOWS_CXX_FLAGS = Compiler flags for wxWindows,
19707 essentially "`wx-config --cxxflags`"
19708 on Linux
19709 WXWINDOWS_INCLUDE_DIR = where to find "wx/wx.h" and "wx/setup.h"
19710 WXWINDOWS_LINK_DIRECTORIES = link directories, useful for rpath on
19711 Unix
19712 WXWINDOWS_DEFINITIONS = extra defines
19713 OPTIONS If you need OpenGL support please
19715 set(WXWINDOWS_USE_GL 1)
19717 in your CMakeLists.txt before you include this file.
19719 HAVE_ISYSTEM - true required to replace -I by -isystem on g++
19721 For convenience include Use_wxWindows.cmake in your project's CMake‐
19723 Lists.txt using include(${CMAKE_CURRENT_LIST_DIR}/Use_wxWindows.cmake).
19724 USAGE
19726 set(WXWINDOWS_USE_GL 1)
19728 find_package(wxWindows)
19729 NOTES wxWidgets 2.6.x is supported for monolithic builds e.g. compiled
19731 in wx/build/msw dir as:
19732 nmake -f makefile.vc BUILD=debug SHARED=0 USE_OPENGL=1 MONOLITHIC=1
19734 DEPRECATED
19736 CMAKE_WX_CAN_COMPILE
19738 WXWINDOWS_LIBRARY
19739 CMAKE_WX_CXX_FLAGS
19740 WXWINDOWS_INCLUDE_PATH
19741 AUTHOR Jan Woetzel <http://www.mip.informatik.uni-kiel.de/~jw>
19743 (07/2003-01/2006)
19744 Legacy CPack Modules
19746 These modules used to be mistakenly exposed to the user, and have been
19747 moved out of user visibility. They are for CPack internal use, and
19748 should never be used directly.
19749 CPackArchive
19751 New in version 3.9.
19752 The documentation for the CPack Archive generator has moved here: CPack
19755 Archive Generator
19756 CPackBundle
19758 The documentation for the CPack Bundle generator has moved here: CPack
19759 Bundle Generator
19760 CPackCygwin
19762 The documentation for the CPack Cygwin generator has moved here: CPack
19763 Cygwin Generator
19764 CPackDeb
19766 The documentation for the CPack DEB generator has moved here: CPack DEB
19767 Generator
19768 CPackDMG
19770 The documentation for the CPack DragNDrop generator has moved here:
19771 CPack DragNDrop Generator
19772 CPackFreeBSD
19774 New in version 3.10.
19775 The documentation for the CPack FreeBSD generator has moved here: CPack
19778 FreeBSD Generator
19779 CPackNSIS
19781 The documentation for the CPack NSIS generator has moved here: CPack
19782 NSIS Generator
19783 CPackNuGet
19785 New in version 3.12.
19786 The documentation for the CPack NuGet generator has moved here: CPack
19789 NuGet Generator
19790 CPackPackageMaker
19792 The documentation for the CPack PackageMaker generator has moved here:
19793 CPack PackageMaker Generator
19794 CPackProductBuild
19796 New in version 3.7.
19797 The documentation for the CPack productbuild generator has moved here:
19800 CPack productbuild Generator
19801 CPackRPM
19803 The documentation for the CPack RPM generator has moved here: CPack RPM
19804 Generator
19805 CPackWIX
19807 The documentation for the CPack WIX generator has moved here: CPack WIX
19808 Generator
19809
19811 2000-2021 Kitware, Inc. and Contributors
198123.20.3 May 30, 2021 CMAKE-MODULES(7)