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 AddFileDependencies
16 Add dependencies to a source file.
17 ADD_FILE_DEPENDENCIES(<source> <files>)
19 Adds the given <files> to the dependencies of file <source>.
21 AndroidTestUtilities
23 New in version 3.7.
24 Create a test that automatically loads specified data onto an Android
27 device.
28 Introduction
30 Use this module to push data needed for testing an Android device
31 behavior onto a connected Android device. The module will accept files
32 and libraries as well as separate destinations for each. It will create
33 a test that loads the files into a device object store and link to them
34 from the specified destination. The files are only uploaded if they are
35 not already in the object store.
36 For example:
38 include(AndroidTestUtilities)
40 android_add_test_data(
41 example_setup_test
42 FILES <files>...
43 LIBS <libs>...
44 DEVICE_TEST_DIR "/data/local/tests/example"
45 DEVICE_OBJECT_STORE "/sdcard/.ExternalData/SHA"
46 )
47 At build time a test named “example_setup_test” will be created. Run
49 this test on the command line with ctest(1) to load the data onto the
50 Android device.
51 Module Functions
53 android_add_test_data
54 android_add_test_data(<test-name>
56 [FILES <files>...] [FILES_DEST <device-dir>]
57 [LIBS <libs>...] [LIBS_DEST <device-dir>]
58 [DEVICE_OBJECT_STORE <device-dir>]
59 [DEVICE_TEST_DIR <device-dir>]
60 [NO_LINK_REGEX <strings>...]
61 )
62 The android_add_test_data function is used to copy files and
64 libraries needed to run project-specific tests. On the host
65 operating system, this is done at build time. For on-device
66 testing, the files are loaded onto the device by the manufac‐
67 tured test at run time.
68 This function accepts the following named parameters:
70 FILES <files>...
72 zero or more files needed for testing
73 LIBS <libs>...
75 zero or more libraries needed for testing
76 FILES_DEST <device-dir>
78 absolute path where the data files are expected to be
79 LIBS_DEST <device-dir>
81 absolute path where the libraries are expected to be
82 DEVICE_OBJECT_STORE <device-dir>
84 absolute path to the location where the data is stored
85 on-device
86 DEVICE_TEST_DIR <device-dir>
88 absolute path to the root directory of the on-device test
89 location
90 NO_LINK_REGEX <strings>...
92 list of regex strings matching the names of files that
93 should be copied from the object store to the testing
94 directory
95 BundleUtilities
97 Functions to help assemble a standalone bundle application.
98 A collection of CMake utility functions useful for dealing with .app
100 bundles on the Mac and bundle-like directories on any OS.
101 The following functions are provided by this module:
103 fixup_bundle
105 copy_and_fixup_bundle
106 verify_app
107 get_bundle_main_executable
108 get_dotapp_dir
109 get_bundle_and_executable
110 get_bundle_all_executables
111 get_item_key
112 get_item_rpaths
113 clear_bundle_keys
114 set_bundle_key_values
115 get_bundle_keys
116 copy_resolved_item_into_bundle
117 copy_resolved_framework_into_bundle
118 fixup_bundle_item
119 verify_bundle_prerequisites
120 verify_bundle_symlinks
121 Requires CMake 2.6 or greater because it uses function, break and PAR‐
123 ENT_SCOPE. Also depends on GetPrerequisites.cmake.
124 DO NOT USE THESE FUNCTIONS AT CONFIGURE TIME (from CMakeLists.txt)!
126 Instead, invoke them from an install(CODE) or install(SCRIPT) rule.
127 fixup_bundle(<app> <libs> <dirs>)
129 Fix up <app> bundle in-place and make it standalone, such that it can
131 be drag-n-drop copied to another machine and run on that machine as
132 long as all of the system libraries are compatible.
133 If you pass plugins to fixup_bundle as the libs parameter, you should
135 install them or copy them into the bundle before calling fixup_bundle.
136 The <libs> parameter is a list of libraries that must be fixed up, but
137 that cannot be determined by otool output analysis (i.e. plugins).
138 Gather all the keys for all the executables and libraries in a bundle,
140 and then, for each key, copy each prerequisite into the bundle. Then
141 fix each one up according to its own list of prerequisites.
142 Then clear all the keys and call verify_app on the final bundle to
144 ensure that it is truly standalone.
145 As an optional parameter (IGNORE_ITEM) a list of file names can be
147 passed, which are then ignored (e.g. IGNORE_ITEM "vcre‐
148 dist_x86.exe;vcredist_x64.exe").
149 copy_and_fixup_bundle(<src> <dst> <libs> <dirs>)
151 Makes a copy of the bundle <src> at location <dst> and then fixes up
153 the new copied bundle in-place at <dst>.
154 verify_app(<app>)
156 Verifies that an application <app> appears valid based on running anal‐
158 ysis tools on it. Calls message(FATAL_ERROR) if the application is not
159 verified.
160 As an optional parameter (IGNORE_ITEM) a list of file names can be
162 passed, which are then ignored (e.g. IGNORE_ITEM "vcre‐
163 dist_x86.exe;vcredist_x64.exe")
164 get_bundle_main_executable(<bundle> <result_var>)
166 The result will be the full path name of the bundle’s main executable
168 file or an error: prefixed string if it could not be determined.
169 get_dotapp_dir(<exe> <dotapp_dir_var>)
171 Returns the nearest parent dir whose name ends with .app given the full
173 path to an executable. If there is no such parent dir, then simply
174 return the dir containing the executable.
175 The returned directory may or may not exist.
177 get_bundle_and_executable(<app> <bundle_var> <executable_var> <valid_var>)
179 Takes either a .app directory name or the name of an executable nested
181 inside a .app directory and returns the path to the .app directory in
182 <bundle_var> and the path to its main executable in <executable_var>.
183 get_bundle_all_executables(<bundle> <exes_var>)
185 Scans <bundle> bundle recursively for all <exes_var> executable files
187 and accumulates them into a variable.
188 get_item_key(<item> <key_var>)
190 Given <item> file name, generate <key_var> key that should be unique
192 considering the set of libraries that need copying or fixing up to make
193 a bundle standalone. This is essentially the file name including
194 extension with . replaced by _
195 This key is used as a prefix for CMake variables so that we can asso‐
197 ciate a set of variables with a given item based on its key.
198 clear_bundle_keys(<keys_var>)
200 Loop over the <keys_var> list of keys, clearing all the variables asso‐
202 ciated with each key. After the loop, clear the list of keys itself.
203 Caller of get_bundle_keys should call clear_bundle_keys when done with
205 list of keys.
206 set_bundle_key_values(<keys_var> <context> <item> <exepath> <dirs>
208 <copyflag> [<rpaths>])
209 Add <keys_var> key to the list (if necessary) for the given item. If
211 added, also set all the variables associated with that key.
212 get_bundle_keys(<app> <libs> <dirs> <keys_var>)
214 Loop over all the executable and library files within <app> bundle (and
216 given as extra <libs>) and accumulate a list of keys representing them.
217 Set values associated with each key such that we can loop over all of
218 them and copy prerequisite libs into the bundle and then do appropriate
219 install_name_tool fixups.
220 As an optional parameter (IGNORE_ITEM) a list of file names can be
222 passed, which are then ignored (e.g. IGNORE_ITEM "vcre‐
223 dist_x86.exe;vcredist_x64.exe")
224 copy_resolved_item_into_bundle(<resolved_item> <resolved_embedded_item>)
226 Copy a resolved item into the bundle if necessary. Copy is not neces‐
228 sary, if the <resolved_item> is “the same as” the <resolved_embed‐
229 ded_item>.
230 copy_resolved_framework_into_bundle(<resolved_item> <resolved_embedded_item>)
232 Copy a resolved framework into the bundle if necessary. Copy is not
234 necessary, if the <resolved_item> is “the same as” the <resolved_embed‐
235 ded_item>.
236 By default, BU_COPY_FULL_FRAMEWORK_CONTENTS is not set. If you want
238 full frameworks embedded in your bundles, set BU_COPY_FULL_FRAME‐
239 WORK_CONTENTS to ON before calling fixup_bundle. By default,
240 COPY_RESOLVED_FRAMEWORK_INTO_BUNDLE copies the framework dylib itself
241 plus the framework Resources directory.
242 fixup_bundle_item(<resolved_embedded_item> <exepath> <dirs>)
244 Get the direct/non-system prerequisites of the <resolved_embed‐
246 ded_item>. For each prerequisite, change the way it is referenced to
247 the value of the _EMBEDDED_ITEM keyed variable for that prerequisite.
248 (Most likely changing to an @executable_path style reference.)
249 This function requires that the <resolved_embedded_item> be inside the
251 bundle already. In other words, if you pass plugins to fixup_bundle as
252 the libs parameter, you should install them or copy them into the bun‐
253 dle before calling fixup_bundle. The libs parameter is a list of
254 libraries that must be fixed up, but that cannot be determined by otool
255 output analysis. (i.e., plugins)
256 Also, change the id of the item being fixed up to its own _EMBED‐
258 DED_ITEM value.
259 Accumulate changes in a local variable and make one call to
261 install_name_tool at the end of the function with all the changes at
262 once.
263 If the BU_CHMOD_BUNDLE_ITEMS variable is set then bundle items will be
265 marked writable before install_name_tool tries to change them.
266 verify_bundle_prerequisites(<bundle> <result_var> <info_var>)
268 Verifies that the sum of all prerequisites of all files inside the bun‐
270 dle are contained within the bundle or are system libraries, presumed
271 to exist everywhere.
272 As an optional parameter (IGNORE_ITEM) a list of file names can be
274 passed, which are then ignored (e.g. IGNORE_ITEM "vcre‐
275 dist_x86.exe;vcredist_x64.exe")
276 verify_bundle_symlinks(<bundle> <result_var> <info_var>)
278 Verifies that any symlinks found in the <bundle> bundle point to other
280 files that are already also in the bundle… Anything that points to an
281 external file causes this function to fail the verification.
282 CheckCCompilerFlag
284 Check whether the C compiler supports a given flag.
285 check_c_compiler_flag
287 check_c_compiler_flag(<flag> <var>)
289 Check that the <flag> is accepted by the compiler without a
291 diagnostic. Stores the result in an internal cache entry named
292 <var>.
293 This command temporarily sets the CMAKE_REQUIRED_DEFINITIONS variable
295 and calls the check_c_source_compiles macro from the CheckCSourceCom‐
296 piles module. See documentation of that module for a listing of vari‐
297 ables that can otherwise modify the build.
298 A positive result from this check indicates only that the compiler did
300 not issue a diagnostic message when given the flag. Whether the flag
301 has any effect or even a specific one is beyond the scope of this mod‐
302 ule.
303 NOTE:
305 Since the try_compile() command forwards flags from variables like
306 CMAKE_C_FLAGS, unknown flags in such variables may cause a false
307 negative for this check.
308 CheckCompilerFlag
310 New in version 3.19.
311 Check whether the compiler supports a given flag.
314 check_compiler_flag
316 check_compiler_flag(<lang> <flag> <var>)
318 Check that the <flag> is accepted by the compiler without a diagnostic.
320 Stores the result in an internal cache entry named <var>.
321 This command temporarily sets the CMAKE_REQUIRED_DEFINITIONS variable
323 and calls the check_source_compiles(<LANG>) function from the Check‐
324 SourceCompiles module. See documentation of that module for a listing
325 of variables that can otherwise modify the build.
326 A positive result from this check indicates only that the compiler did
328 not issue a diagnostic message when given the flag. Whether the flag
329 has any effect or even a specific one is beyond the scope of this mod‐
330 ule.
331 NOTE:
333 Since the try_compile() command forwards flags from variables like
334 CMAKE_<LANG>_FLAGS, unknown flags in such variables may cause a
335 false negative for this check.
336 CheckCSourceCompiles
338 Check if given C source compiles and links into an executable.
339 check_c_source_compiles
341 check_c_source_compiles(<code> <resultVar>
343 [FAIL_REGEX <regex1> [<regex2>...]])
344 Check that the source supplied in <code> can be compiled as a C
346 source file and linked as an executable (so it must contain at
347 least a main() function). The result will be stored in the
348 internal cache variable specified by <resultVar>, with a boolean
349 true value for success and boolean false for failure. If
350 FAIL_REGEX is provided, then failure is determined by checking
351 if anything in the output matches any of the specified regular
352 expressions.
353 The underlying check is performed by the try_compile() command.
355 The compile and link commands can be influenced by setting any
356 of the following variables prior to calling check_c_source_com‐
357 piles():
358 CMAKE_REQUIRED_FLAGS
360 Additional flags to pass to the compiler. Note that the
361 contents of CMAKE_C_FLAGS and its associated configura‐
362 tion-specific variable are automatically added to the
363 compiler command before the contents of
364 CMAKE_REQUIRED_FLAGS.
365 CMAKE_REQUIRED_DEFINITIONS
367 A ;-list of compiler definitions of the form -DFOO or
368 -DFOO=bar. A definition for the name specified by
369 <resultVar> will also be added automatically.
370 CMAKE_REQUIRED_INCLUDES
372 A ;-list of header search paths to pass to the compiler.
373 These will be the only header search paths used by
374 try_compile(), i.e. the contents of the INCLUDE_DIRECTO‐
375 RIES directory property will be ignored.
376 CMAKE_REQUIRED_LINK_OPTIONS
378 A ;-list of options to add to the link command (see
379 try_compile() for further details).
380 CMAKE_REQUIRED_LIBRARIES
382 A ;-list of libraries to add to the link command. These
383 can be the name of system libraries or they can be
384 Imported Targets (see try_compile() for further details).
385 CMAKE_REQUIRED_QUIET
387 If this variable evaluates to a boolean true value, all
388 status messages associated with the check will be sup‐
389 pressed.
390 The check is only performed once, with the result cached in the
392 variable named by <resultVar>. Every subsequent CMake run will
393 re-use this cached value rather than performing the check again,
394 even if the <code> changes. In order to force the check to be
395 re-evaluated, the variable named by <resultVar> must be manually
396 removed from the cache.
397 CheckCSourceRuns
399 Check if given C source compiles and links into an executable and can
400 subsequently be run.
401 check_c_source_runs
403 check_c_source_runs(<code> <resultVar>)
405 Check that the source supplied in <code> can be compiled as a C
407 source file, linked as an executable and then run. The <code>
408 must contain at least a main() function. If the <code> could be
409 built and run successfully, the internal cache variable speci‐
410 fied by <resultVar> will be set to 1, otherwise it will be set
411 to an value that evaluates to boolean false (e.g. an empty
412 string or an error message).
413 The underlying check is performed by the try_run() command. The
415 compile and link commands can be influenced by setting any of
416 the following variables prior to calling check_c_source_runs():
417 CMAKE_REQUIRED_FLAGS
419 Additional flags to pass to the compiler. Note that the
420 contents of CMAKE_C_FLAGS and its associated configura‐
421 tion-specific variable are automatically added to the
422 compiler command before the contents of
423 CMAKE_REQUIRED_FLAGS.
424 CMAKE_REQUIRED_DEFINITIONS
426 A ;-list of compiler definitions of the form -DFOO or
427 -DFOO=bar. A definition for the name specified by
428 <resultVar> will also be added automatically.
429 CMAKE_REQUIRED_INCLUDES
431 A ;-list of header search paths to pass to the compiler.
432 These will be the only header search paths used by
433 try_run(), i.e. the contents of the INCLUDE_DIRECTORIES
434 directory property will be ignored.
435 CMAKE_REQUIRED_LINK_OPTIONS
437 A ;-list of options to add to the link command (see
438 try_run() for further details).
439 CMAKE_REQUIRED_LIBRARIES
441 A ;-list of libraries to add to the link command. These
442 can be the name of system libraries or they can be
443 Imported Targets (see try_run() for further details).
444 CMAKE_REQUIRED_QUIET
446 If this variable evaluates to a boolean true value, all
447 status messages associated with the check will be sup‐
448 pressed.
449 The check is only performed once, with the result cached in the
451 variable named by <resultVar>. Every subsequent CMake run will
452 re-use this cached value rather than performing the check again,
453 even if the <code> changes. In order to force the check to be
454 re-evaluated, the variable named by <resultVar> must be manually
455 removed from the cache.
456 CheckCXXCompilerFlag
458 Check whether the CXX compiler supports a given flag.
459 check_cxx_compiler_flag
461 check_cxx_compiler_flag(<flag> <var>)
463 Check that the <flag> is accepted by the compiler without a
465 diagnostic. Stores the result in an internal cache entry named
466 <var>.
467 This command temporarily sets the CMAKE_REQUIRED_DEFINITIONS variable
469 and calls the check_cxx_source_compiles macro from the CheckCXXSource‐
470 Compiles module. See documentation of that module for a listing of
471 variables that can otherwise modify the build.
472 A positive result from this check indicates only that the compiler did
474 not issue a diagnostic message when given the flag. Whether the flag
475 has any effect or even a specific one is beyond the scope of this mod‐
476 ule.
477 NOTE:
479 Since the try_compile() command forwards flags from variables like
480 CMAKE_CXX_FLAGS, unknown flags in such variables may cause a false
481 negative for this check.
482 CheckCXXSourceCompiles
484 Check if given C++ source compiles and links into an executable.
485 check_cxx_source_compiles
487 check_cxx_source_compiles(<code> <resultVar>
489 [FAIL_REGEX <regex1> [<regex2>...]])
490 Check that the source supplied in <code> can be compiled as a
492 C++ source file and linked as an executable (so it must contain
493 at least a main() function). The result will be stored in the
494 internal cache variable specified by <resultVar>, with a boolean
495 true value for success and boolean false for failure. If
496 FAIL_REGEX is provided, then failure is determined by checking
497 if anything in the output matches any of the specified regular
498 expressions.
499 The underlying check is performed by the try_compile() command.
501 The compile and link commands can be influenced by setting any
502 of the following variables prior to calling
503 check_cxx_source_compiles():
504 CMAKE_REQUIRED_FLAGS
506 Additional flags to pass to the compiler. Note that the
507 contents of CMAKE_CXX_FLAGS and its associated configura‐
508 tion-specific variable are automatically added to the
509 compiler command before the contents of
510 CMAKE_REQUIRED_FLAGS.
511 CMAKE_REQUIRED_DEFINITIONS
513 A ;-list of compiler definitions of the form -DFOO or
514 -DFOO=bar. A definition for the name specified by
515 <resultVar> will also be added automatically.
516 CMAKE_REQUIRED_INCLUDES
518 A ;-list of header search paths to pass to the compiler.
519 These will be the only header search paths used by
520 try_compile(), i.e. the contents of the INCLUDE_DIRECTO‐
521 RIES directory property will be ignored.
522 CMAKE_REQUIRED_LINK_OPTIONS
524 A ;-list of options to add to the link command (see
525 try_compile() for further details).
526 CMAKE_REQUIRED_LIBRARIES
528 A ;-list of libraries to add to the link command. These
529 can be the name of system libraries or they can be
530 Imported Targets (see try_compile() for further details).
531 CMAKE_REQUIRED_QUIET
533 If this variable evaluates to a boolean true value, all
534 status messages associated with the check will be sup‐
535 pressed.
536 The check is only performed once, with the result cached in the
538 variable named by <resultVar>. Every subsequent CMake run will
539 re-use this cached value rather than performing the check again,
540 even if the <code> changes. In order to force the check to be
541 re-evaluated, the variable named by <resultVar> must be manually
542 removed from the cache.
543 CheckCXXSourceRuns
545 Check if given C++ source compiles and links into an executable and can
546 subsequently be run.
547 check_cxx_source_runs
549 check_cxx_source_runs(<code> <resultVar>)
551 Check that the source supplied in <code> can be compiled as a
553 C++ source file, linked as an executable and then run. The
554 <code> must contain at least a main() function. If the <code>
555 could be built and run successfully, the internal cache variable
556 specified by <resultVar> will be set to 1, otherwise it will be
557 set to an value that evaluates to boolean false (e.g. an empty
558 string or an error message).
559 The underlying check is performed by the try_run() command. The
561 compile and link commands can be influenced by setting any of
562 the following variables prior to calling
563 check_cxx_source_runs():
564 CMAKE_REQUIRED_FLAGS
566 Additional flags to pass to the compiler. Note that the
567 contents of CMAKE_CXX_FLAGS and its associated configura‐
568 tion-specific variable are automatically added to the
569 compiler command before the contents of
570 CMAKE_REQUIRED_FLAGS.
571 CMAKE_REQUIRED_DEFINITIONS
573 A ;-list of compiler definitions of the form -DFOO or
574 -DFOO=bar. A definition for the name specified by
575 <resultVar> will also be added automatically.
576 CMAKE_REQUIRED_INCLUDES
578 A ;-list of header search paths to pass to the compiler.
579 These will be the only header search paths used by
580 try_run(), i.e. the contents of the INCLUDE_DIRECTORIES
581 directory property will be ignored.
582 CMAKE_REQUIRED_LINK_OPTIONS
584 A ;-list of options to add to the link command (see
585 try_run() for further details).
586 CMAKE_REQUIRED_LIBRARIES
588 A ;-list of libraries to add to the link command. These
589 can be the name of system libraries or they can be
590 Imported Targets (see try_run() for further details).
591 CMAKE_REQUIRED_QUIET
593 If this variable evaluates to a boolean true value, all
594 status messages associated with the check will be sup‐
595 pressed.
596 The check is only performed once, with the result cached in the
598 variable named by <resultVar>. Every subsequent CMake run will
599 re-use this cached value rather than performing the check again,
600 even if the <code> changes. In order to force the check to be
601 re-evaluated, the variable named by <resultVar> must be manually
602 removed from the cache.
603 CheckCXXSymbolExists
605 Check if a symbol exists as a function, variable, or macro in C++.
606 check_cxx_symbol_exists
608 check_cxx_symbol_exists(<symbol> <files> <variable>)
610 Check that the <symbol> is available after including given
612 header <files> and store the result in a <variable>. Specify
613 the list of files in one argument as a semicolon-separated list.
614 check_cxx_symbol_exists() can be used to check for symbols as
615 seen by the C++ compiler, as opposed to check_symbol_exists(),
616 which always uses the C compiler.
617 If the header files define the symbol as a macro it is consid‐
619 ered available and assumed to work. If the header files declare
620 the symbol as a function or variable then the symbol must also
621 be available for linking. If the symbol is a type, enum value,
622 or C++ template it will not be recognized: consider using the
623 CheckTypeSize or CheckCXXSourceCompiles module instead.
624 NOTE:
626 This command is unreliable when <symbol> is (potentially) an over‐
627 loaded function. Since there is no reliable way to predict whether a
628 given function in the system environment may be defined as an over‐
629 loaded function or may be an overloaded function on other systems or
630 will become so in the future, it is generally advised to use the
631 CheckCXXSourceCompiles module for checking any function symbol
632 (unless somehow you surely know the checked function is not over‐
633 loaded on other systems or will not be so in the future).
634 The following variables may be set before calling this macro to modify
636 the way the check is run:
637 CMAKE_REQUIRED_FLAGS
639 string of compile command line flags.
640 CMAKE_REQUIRED_DEFINITIONS
642 a ;-list of macros to define (-DFOO=bar).
643 CMAKE_REQUIRED_INCLUDES
645 a ;-list of header search paths to pass to the compiler.
646 CMAKE_REQUIRED_LINK_OPTIONS
648 a ;-list of options to add to the link command.
649 CMAKE_REQUIRED_LIBRARIES
651 a ;-list of libraries to add to the link command. See policy
652 CMP0075.
653 CMAKE_REQUIRED_QUIET
655 execute quietly without messages.
656 For example:
658 include(CheckCXXSymbolExists)
660 # Check for macro SEEK_SET
662 check_cxx_symbol_exists(SEEK_SET "cstdio" HAVE_SEEK_SET)
663 # Check for function std::fopen
664 check_cxx_symbol_exists(std::fopen "cstdio" HAVE_STD_FOPEN)
665 CheckFortranCompilerFlag
667 New in version 3.3.
668 Check whether the Fortran compiler supports a given flag.
671 check_fortran_compiler_flag
673 check_fortran_compiler_flag(<flag> <var>)
675 Check that the <flag> is accepted by the compiler without a
677 diagnostic. Stores the result in an internal cache entry named
678 <var>.
679 This command temporarily sets the CMAKE_REQUIRED_DEFINITIONS variable
681 and calls the check_fortran_source_compiles macro from the CheckFor‐
682 tranSourceCompiles module. See documentation of that module for a
683 listing of variables that can otherwise modify the build.
684 A positive result from this check indicates only that the compiler did
686 not issue a diagnostic message when given the flag. Whether the flag
687 has any effect or even a specific one is beyond the scope of this mod‐
688 ule.
689 NOTE:
691 Since the try_compile() command forwards flags from variables like
692 CMAKE_Fortran_FLAGS, unknown flags in such variables may cause a
693 false negative for this check.
694 CheckFortranFunctionExists
696 Check if a Fortran function exists.
697 CHECK_FORTRAN_FUNCTION_EXISTS
699 CHECK_FORTRAN_FUNCTION_EXISTS(<function> <result>)
701 where
703 <function>
705 the name of the Fortran function
706 <result>
708 variable to store the result; will be created as an
709 internal cache variable.
710 The following variables may be set before calling this macro to modify
712 the way the check is run:
713 CMAKE_REQUIRED_LINK_OPTIONS
715 A ;-list of options to add to the link command (see try_com‐
716 pile() for further details).
717 CMAKE_REQUIRED_LIBRARIES
719 A ;-list of libraries to add to the link command. These can be
720 the name of system libraries or they can be Imported Targets
721 (see try_compile() for further details).
722 CheckFortranSourceCompiles
724 New in version 3.1.
725 Check if given Fortran source compiles and links into an executable.
728 check_fortran_source_compiles
730 check_fortran_source_compiles(<code> <resultVar>
732 [FAIL_REGEX <regex>...]
733 [SRC_EXT <extension>]
734 )
735 Checks that the source supplied in <code> can be compiled as a
737 Fortran source file and linked as an executable. The <code> must
738 be a Fortran program containing at least an end statement–for
739 example:
740 check_fortran_source_compiles("character :: b; error stop b; end" F2018ESTOPOK SRC_EXT F90)
742 This command can help avoid costly build processes when a com‐
744 piler lacks support for a necessary feature, or a particular
745 vendor library is not compatible with the Fortran compiler ver‐
746 sion being used. This generate-time check may advise the user of
747 such before the main build process. See also the check_for‐
748 tran_source_runs() command to actually run the compiled code.
749 The result will be stored in the internal cache variable
751 <resultVar>, with a boolean true value for success and boolean
752 false for failure.
753 If FAIL_REGEX is provided, then failure is determined by check‐
755 ing if anything in the output matches any of the specified regu‐
756 lar expressions.
757 By default, the test source file will be given a .F file exten‐
759 sion. The SRC_EXT option can be used to override this with
760 .<extension> instead– .F90 is a typical choice.
761 The underlying check is performed by the try_compile() command.
763 The compile and link commands can be influenced by setting any
764 of the following variables prior to calling check_for‐
765 tran_source_compiles():
766 CMAKE_REQUIRED_FLAGS
768 Additional flags to pass to the compiler. Note that the
769 contents of CMAKE_Fortran_FLAGS and its associated con‐
770 figuration-specific variable are automatically added to
771 the compiler command before the contents of
772 CMAKE_REQUIRED_FLAGS.
773 CMAKE_REQUIRED_DEFINITIONS
775 A ;-list of compiler definitions of the form -DFOO or
776 -DFOO=bar. A definition for the name specified by
777 <resultVar> will also be added automatically.
778 CMAKE_REQUIRED_INCLUDES
780 A ;-list of header search paths to pass to the compiler.
781 These will be the only header search paths used by
782 try_compile(), i.e. the contents of the INCLUDE_DIRECTO‐
783 RIES directory property will be ignored.
784 CMAKE_REQUIRED_LINK_OPTIONS
786 A ;-list of options to add to the link command (see
787 try_compile() for further details).
788 CMAKE_REQUIRED_LIBRARIES
790 A ;-list of libraries to add to the link command. These
791 can be the name of system libraries or they can be
792 Imported Targets (see try_compile() for further details).
793 CMAKE_REQUIRED_QUIET
795 If this variable evaluates to a boolean true value, all
796 status messages associated with the check will be sup‐
797 pressed.
798 The check is only performed once, with the result cached in the
800 variable named by <resultVar>. Every subsequent CMake run will
801 re-use this cached value rather than performing the check again,
802 even if the <code> changes. In order to force the check to be
803 re-evaluated, the variable named by <resultVar> must be manually
804 removed from the cache.
805 CheckFortranSourceRuns
807 New in version 3.14.
808 Check if given Fortran source compiles and links into an executable and
811 can subsequently be run.
812 check_fortran_source_runs
814 check_fortran_source_runs(<code> <resultVar>
816 [SRC_EXT <extension>])
817 Check that the source supplied in <code> can be compiled as a
819 Fortran source file, linked as an executable and then run. The
820 <code> must be a Fortran program containing at least an end
821 statement–for example:
822 check_fortran_source_runs("real :: x[*]; call co_sum(x); end" F2018coarrayOK)
824 This command can help avoid costly build processes when a com‐
826 piler lacks support for a necessary feature, or a particular
827 vendor library is not compatible with the Fortran compiler ver‐
828 sion being used. Some of these failures only occur at runtime
829 instead of linktime, and a trivial runtime example can catch the
830 issue before the main build process.
831 If the <code> could be built and run successfully, the internal
833 cache variable specified by <resultVar> will be set to 1, other‐
834 wise it will be set to an value that evaluates to boolean false
835 (e.g. an empty string or an error message).
836 By default, the test source file will be given a .F90 file
838 extension. The SRC_EXT option can be used to override this with
839 .<extension> instead.
840 The underlying check is performed by the try_run() command. The
842 compile and link commands can be influenced by setting any of
843 the following variables prior to calling check_for‐
844 tran_source_runs():
845 CMAKE_REQUIRED_FLAGS
847 Additional flags to pass to the compiler. Note that the
848 contents of CMAKE_Fortran_FLAGS and its associated con‐
849 figuration-specific variable are automatically added to
850 the compiler command before the contents of
851 CMAKE_REQUIRED_FLAGS.
852 CMAKE_REQUIRED_DEFINITIONS
854 A ;-list of compiler definitions of the form -DFOO or
855 -DFOO=bar. A definition for the name specified by
856 <resultVar> will also be added automatically.
857 CMAKE_REQUIRED_INCLUDES
859 A ;-list of header search paths to pass to the compiler.
860 These will be the only header search paths used by
861 try_run(), i.e. the contents of the INCLUDE_DIRECTORIES
862 directory property will be ignored.
863 CMAKE_REQUIRED_LINK_OPTIONS
865 A ;-list of options to add to the link command (see
866 try_run() for further details).
867 CMAKE_REQUIRED_LIBRARIES
869 A ;-list of libraries to add to the link command. These
870 can be the name of system libraries or they can be
871 Imported Targets (see try_run() for further details).
872 CMAKE_REQUIRED_QUIET
874 If this variable evaluates to a boolean true value, all
875 status messages associated with the check will be sup‐
876 pressed.
877 The check is only performed once, with the result cached in the
879 variable named by <resultVar>. Every subsequent CMake run will
880 re-use this cached value rather than performing the check again,
881 even if the <code> changes. In order to force the check to be
882 re-evaluated, the variable named by <resultVar> must be manually
883 removed from the cache.
884 CheckFunctionExists
886 Check if a C function can be linked
887 check_function_exists
889 check_function_exists(<function> <variable>)
891 Checks that the <function> is provided by libraries on the sys‐
893 tem and store the result in a <variable>, which will be created
894 as an internal cache variable.
895 The following variables may be set before calling this macro to modify
897 the way the check is run:
898 CMAKE_REQUIRED_FLAGS
900 string of compile command line flags.
901 CMAKE_REQUIRED_DEFINITIONS
903 a ;-list of macros to define (-DFOO=bar).
904 CMAKE_REQUIRED_INCLUDES
906 a ;-list of header search paths to pass to the compiler.
907 CMAKE_REQUIRED_LINK_OPTIONS
909 a ;-list of options to add to the link command.
910 CMAKE_REQUIRED_LIBRARIES
912 a ;-list of libraries to add to the link command. See policy
913 CMP0075.
914 CMAKE_REQUIRED_QUIET
916 execute quietly without messages.
917 NOTE:
919 Prefer using CheckSymbolExists instead of this module, for the fol‐
920 lowing reasons:
921 · check_function_exists() can’t detect functions that are inlined in
923 headers or specified as a macro.
924 · check_function_exists() can’t detect anything in the 32-bit ver‐
926 sions of the Win32 API, because of a mismatch in calling conven‐
927 tions.
928 · check_function_exists() only verifies linking, it does not verify
930 that the function is declared in system headers.
931 CheckIncludeFileCXX
933 Provides a macro to check if a header file can be included in CXX.
934 CHECK_INCLUDE_FILE_CXX
936 CHECK_INCLUDE_FILE_CXX(<include> <variable> [<flags>])
938 Check if the given <include> file may be included in a CXX
940 source file and store the result in an internal cache entry
941 named <variable>. The optional third argument may be used to
942 add compilation flags to the check (or use CMAKE_REQUIRED_FLAGS
943 below).
944 The following variables may be set before calling this macro to modify
946 the way the check is run:
947 CMAKE_REQUIRED_FLAGS
949 string of compile command line flags.
950 CMAKE_REQUIRED_DEFINITIONS
952 a ;-list of macros to define (-DFOO=bar).
953 CMAKE_REQUIRED_INCLUDES
955 a ;-list of header search paths to pass to the compiler.
956 CMAKE_REQUIRED_LINK_OPTIONS
958 a ;-list of options to add to the link command.
959 CMAKE_REQUIRED_LIBRARIES
961 a ;-list of libraries to add to the link command. See policy
962 CMP0075.
963 CMAKE_REQUIRED_QUIET
965 execute quietly without messages.
966 See modules CheckIncludeFile and CheckIncludeFiles to check for one or
968 more C headers.
969 CheckIncludeFile
971 Provides a macro to check if a header file can be included in C.
972 CHECK_INCLUDE_FILE
974 CHECK_INCLUDE_FILE(<include> <variable> [<flags>])
976 Check if the given <include> file may be included in a C source
978 file and store the result in an internal cache entry named
979 <variable>. The optional third argument may be used to add com‐
980 pilation flags to the check (or use CMAKE_REQUIRED_FLAGS below).
981 The following variables may be set before calling this macro to modify
983 the way the check is run:
984 CMAKE_REQUIRED_FLAGS
986 string of compile command line flags.
987 CMAKE_REQUIRED_DEFINITIONS
989 a ;-list of macros to define (-DFOO=bar).
990 CMAKE_REQUIRED_INCLUDES
992 a ;-list of header search paths to pass to the compiler.
993 CMAKE_REQUIRED_LINK_OPTIONS
995 a ;-list of options to add to the link command.
996 CMAKE_REQUIRED_LIBRARIES
998 a ;-list of libraries to add to the link command. See policy
999 CMP0075.
1000 CMAKE_REQUIRED_QUIET
1002 execute quietly without messages.
1003 See the CheckIncludeFiles module to check for multiple headers at once.
1005 See the CheckIncludeFileCXX module to check for headers using the CXX
1006 language.
1007 CheckIncludeFiles
1009 Provides a macro to check if a list of one or more header files can be
1010 included together.
1011 CHECK_INCLUDE_FILES
1013 CHECK_INCLUDE_FILES("<includes>" <variable> [LANGUAGE <language>])
1015 Check if the given <includes> list may be included together in a
1017 source file and store the result in an internal cache entry
1018 named <variable>. Specify the <includes> argument as a ;-list
1019 of header file names.
1020 If LANGUAGE is set, the specified compiler will be used to per‐
1022 form the check. Acceptable values are C and CXX. If not set, the
1023 C compiler will be used if enabled. If the C compiler is not
1024 enabled, the C++ compiler will be used if enabled.
1025 The following variables may be set before calling this macro to modify
1027 the way the check is run:
1028 CMAKE_REQUIRED_FLAGS
1030 string of compile command line flags.
1031 CMAKE_REQUIRED_DEFINITIONS
1033 a ;-list of macros to define (-DFOO=bar).
1034 CMAKE_REQUIRED_INCLUDES
1036 a ;-list of header search paths to pass to the compiler.
1037 CMAKE_REQUIRED_LINK_OPTIONS
1039 a ;-list of options to add to the link command.
1040 CMAKE_REQUIRED_LIBRARIES
1042 a ;-list of libraries to add to the link command. See policy
1043 CMP0075.
1044 CMAKE_REQUIRED_QUIET
1046 execute quietly without messages.
1047 See modules CheckIncludeFile and CheckIncludeFileCXX to check for a
1049 single header file in C or CXX languages.
1050 CheckIPOSupported
1052 New in version 3.9.
1053 Check whether the compiler supports an interprocedural optimization
1056 (IPO/LTO). Use this before enabling the INTERPROCEDURAL_OPTIMIZATION
1057 target property.
1058 check_ipo_supported
1060 check_ipo_supported([RESULT <result>] [OUTPUT <output>]
1062 [LANGUAGES <lang>...])
1063 Options are:
1065 RESULT <result>
1067 Set <result> variable to YES if IPO is supported by the
1068 compiler and NO otherwise. If this option is not given
1069 then the command will issue a fatal error if IPO is not
1070 supported.
1071 OUTPUT <output>
1073 Set <output> variable with details about any error.
1074 LANGUAGES <lang>...
1076 Specify languages whose compilers to check. Languages C,
1077 CXX, and Fortran are supported.
1078 It makes no sense to use this module when CMP0069 is set to OLD so mod‐
1080 ule will return error in this case. See policy CMP0069 for details.
1081 Examples
1083 check_ipo_supported() # fatal error if IPO is not supported
1084 set_property(TARGET foo PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
1085 # Optional IPO. Do not use IPO if it's not supported by compiler.
1087 check_ipo_supported(RESULT result OUTPUT output)
1088 if(result)
1089 set_property(TARGET foo PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
1090 else()
1091 message(WARNING "IPO is not supported: ${output}")
1092 endif()
1093 CheckLanguage
1095 Check if a language can be enabled
1096 Usage:
1098 check_language(<lang>)
1100 where <lang> is a language that may be passed to enable_language() such
1102 as Fortran. If CMAKE_<LANG>_COMPILER is already defined the check does
1103 nothing. Otherwise it tries enabling the language in a test project.
1104 The result is cached in CMAKE_<LANG>_COMPILER as the compiler that was
1105 found, or NOTFOUND if the language cannot be enabled. For CUDA which
1106 can have an explicit host compiler, the cache CMAKE_CUDA_HOST_COMPILER
1107 variable will be set if it was required for compilation (and cleared if
1108 it was not).
1109 Example:
1111 check_language(Fortran)
1113 if(CMAKE_Fortran_COMPILER)
1114 enable_language(Fortran)
1115 else()
1116 message(STATUS "No Fortran support")
1117 endif()
1118 CheckLibraryExists
1120 Check if the function exists.
1121 CHECK_LIBRARY_EXISTS
1123 CHECK_LIBRARY_EXISTS(LIBRARY FUNCTION LOCATION VARIABLE)
1125 LIBRARY - the name of the library you are looking for
1127 FUNCTION - the name of the function
1128 LOCATION - location where the library should be found
1129 VARIABLE - variable to store the result
1130 Will be created as an internal cache variable.
1131 The following variables may be set before calling this macro to modify
1133 the way the check is run:
1134 CMAKE_REQUIRED_FLAGS = string of compile command line flags
1136 CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
1137 CMAKE_REQUIRED_LINK_OPTIONS = list of options to pass to link command
1138 CMAKE_REQUIRED_LIBRARIES = list of libraries to link
1139 CMAKE_REQUIRED_QUIET = execute quietly without messages
1140 CheckLinkerFlag
1142 New in version 3.18.
1143 Check whether the compiler supports a given link flag.
1146 check_linker_flag
1148 check_linker_flag(<lang> <flag> <var>)
1150 Check that the link <flag> is accepted by the <lang> compiler without a
1152 diagnostic. Stores the result in an internal cache entry named <var>.
1153 This command temporarily sets the CMAKE_REQUIRED_LINK_OPTIONS variable
1155 and calls the check_source_compiles() command from the CheckSourceCom‐
1156 piles module. See that module’s documentation for a listing of vari‐
1157 ables that can otherwise modify the build.
1158 The underlying implementation relies on the LINK_OPTIONS property to
1160 check the specified flag. The LINKER: prefix, as described in the tar‐
1161 get_link_options() command, can be used as well.
1162 A positive result from this check indicates only that the compiler did
1164 not issue a diagnostic message when given the link flag. Whether the
1165 flag has any effect or even a specific one is beyond the scope of this
1166 module.
1167 NOTE:
1169 Since the try_compile() command forwards flags from variables like
1170 CMAKE_<LANG>_FLAGS, unknown flags in such variables may cause a
1171 false negative for this check.
1172 CheckOBJCCompilerFlag
1174 New in version 3.16.
1175 Check whether the Objective-C compiler supports a given flag.
1178 check_objc_compiler_flag
1180 check_objc_compiler_flag(<flag> <var>)
1182 Check that the <flag> is accepted by the compiler without a
1184 diagnostic. Stores the result in an internal cache entry named
1185 <var>.
1186 This command temporarily sets the CMAKE_REQUIRED_DEFINITIONS variable
1188 and calls the check_objc_source_compiles macro from the CheckOBJC‐
1189 SourceCompiles module. See documentation of that module for a listing
1190 of variables that can otherwise modify the build.
1191 A positive result from this check indicates only that the compiler did
1193 not issue a diagnostic message when given the flag. Whether the flag
1194 has any effect or even a specific one is beyond the scope of this mod‐
1195 ule.
1196 NOTE:
1198 Since the try_compile() command forwards flags from variables like
1199 CMAKE_OBJC_FLAGS, unknown flags in such variables may cause a false
1200 negative for this check.
1201 CheckOBJCSourceCompiles
1203 New in version 3.16.
1204 Check if given Objective-C source compiles and links into an exe‐
1207 cutable.
1208 check_objc_source_compiles
1210 check_objc_source_compiles(<code> <resultVar>
1212 [FAIL_REGEX <regex1> [<regex2>...]])
1213 Check that the source supplied in <code> can be compiled as a
1215 Objectie-C source file and linked as an executable (so it must
1216 contain at least a main() function). The result will be stored
1217 in the internal cache variable specified by <resultVar>, with a
1218 boolean true value for success and boolean false for failure. If
1219 FAIL_REGEX is provided, then failure is determined by checking
1220 if anything in the output matches any of the specified regular
1221 expressions.
1222 The underlying check is performed by the try_compile() command.
1224 The compile and link commands can be influenced by setting any
1225 of the following variables prior to calling
1226 check_objc_source_compiles():
1227 CMAKE_REQUIRED_FLAGS
1229 Additional flags to pass to the compiler. Note that the
1230 contents of CMAKE_OBJC_FLAGS and its associated configu‐
1231 ration-specific variable are automatically added to the
1232 compiler command before the contents of
1233 CMAKE_REQUIRED_FLAGS.
1234 CMAKE_REQUIRED_DEFINITIONS
1236 A ;-list of compiler definitions of the form -DFOO or
1237 -DFOO=bar. A definition for the name specified by
1238 <resultVar> will also be added automatically.
1239 CMAKE_REQUIRED_INCLUDES
1241 A ;-list of header search paths to pass to the compiler.
1242 These will be the only header search paths used by
1243 try_compile(), i.e. the contents of the INCLUDE_DIRECTO‐
1244 RIES directory property will be ignored.
1245 CMAKE_REQUIRED_LINK_OPTIONS
1247 A ;-list of options to add to the link command (see
1248 try_compile() for further details).
1249 CMAKE_REQUIRED_LIBRARIES
1251 A ;-list of libraries to add to the link command. These
1252 can be the name of system libraries or they can be
1253 Imported Targets (see try_compile() for further details).
1254 CMAKE_REQUIRED_QUIET
1256 If this variable evaluates to a boolean true value, all
1257 status messages associated with the check will be sup‐
1258 pressed.
1259 The check is only performed once, with the result cached in the
1261 variable named by <resultVar>. Every subsequent CMake run will
1262 re-use this cached value rather than performing the check again,
1263 even if the <code> changes. In order to force the check to be
1264 re-evaluated, the variable named by <resultVar> must be manually
1265 removed from the cache.
1266 CheckOBJCSourceRuns
1268 New in version 3.16.
1269 Check if given Objective-C source compiles and links into an executable
1272 and can subsequently be run.
1273 check_objc_source_runs
1275 check_objc_source_runs(<code> <resultVar>)
1277 Check that the source supplied in <code> can be compiled as a
1279 Objective-C source file, linked as an executable and then run.
1280 The <code> must contain at least a main() function. If the
1281 <code> could be built and run successfully, the internal cache
1282 variable specified by <resultVar> will be set to 1, otherwise it
1283 will be set to an value that evaluates to boolean false (e.g. an
1284 empty string or an error message).
1285 The underlying check is performed by the try_run() command. The
1287 compile and link commands can be influenced by setting any of
1288 the following variables prior to calling
1289 check_objc_source_runs():
1290 CMAKE_REQUIRED_FLAGS
1292 Additional flags to pass to the compiler. Note that the
1293 contents of CMAKE_OBJC_FLAGS and its associated configu‐
1294 ration-specific variable are automatically added to the
1295 compiler command before the contents of
1296 CMAKE_REQUIRED_FLAGS.
1297 CMAKE_REQUIRED_DEFINITIONS
1299 A ;-list of compiler definitions of the form -DFOO or
1300 -DFOO=bar. A definition for the name specified by
1301 <resultVar> will also be added automatically.
1302 CMAKE_REQUIRED_INCLUDES
1304 A ;-list of header search paths to pass to the compiler.
1305 These will be the only header search paths used by
1306 try_run(), i.e. the contents of the INCLUDE_DIRECTORIES
1307 directory property will be ignored.
1308 CMAKE_REQUIRED_LINK_OPTIONS
1310 A ;-list of options to add to the link command (see
1311 try_run() for further details).
1312 CMAKE_REQUIRED_LIBRARIES
1314 A ;-list of libraries to add to the link command. These
1315 can be the name of system libraries or they can be
1316 Imported Targets (see try_run() for further details).
1317 CMAKE_REQUIRED_QUIET
1319 If this variable evaluates to a boolean true value, all
1320 status messages associated with the check will be sup‐
1321 pressed.
1322 The check is only performed once, with the result cached in the
1324 variable named by <resultVar>. Every subsequent CMake run will
1325 re-use this cached value rather than performing the check again,
1326 even if the <code> changes. In order to force the check to be
1327 re-evaluated, the variable named by <resultVar> must be manually
1328 removed from the cache.
1329 CheckOBJCXXCompilerFlag
1331 New in version 3.16.
1332 Check whether the Objective-C++ compiler supports a given flag.
1335 check_objcxx_compiler_flag
1337 check_objcxx_compiler_flag(<flag> <var>)
1339 Check that the <flag> is accepted by the compiler without a
1341 diagnostic. Stores the result in an internal cache entry named
1342 <var>.
1343 This command temporarily sets the CMAKE_REQUIRED_DEFINITIONS variable
1345 and calls the check_objcxx_source_compiles macro from the CheckOB‐
1346 JCXXSourceCompiles module. See documentation of that module for a
1347 listing of variables that can otherwise modify the build.
1348 A positive result from this check indicates only that the compiler did
1350 not issue a diagnostic message when given the flag. Whether the flag
1351 has any effect or even a specific one is beyond the scope of this mod‐
1352 ule.
1353 NOTE:
1355 Since the try_compile() command forwards flags from variables like
1356 CMAKE_OBJCXX_FLAGS, unknown flags in such variables may cause a
1357 false negative for this check.
1358 CheckOBJCXXSourceCompiles
1360 New in version 3.16.
1361 Check if given Objective-C++ source compiles and links into an exe‐
1364 cutable.
1365 check_objcxx_source_compiles
1367 check_objcxx_source_compiles(<code> <resultVar>
1369 [FAIL_REGEX <regex1> [<regex2>...]])
1370 Check that the source supplied in <code> can be compiled as a
1372 Objective-C++ source file and linked as an executable (so it
1373 must contain at least a main() function). The result will be
1374 stored in the internal cache variable specified by <resultVar>,
1375 with a boolean true value for success and boolean false for
1376 failure. If FAIL_REGEX is provided, then failure is determined
1377 by checking if anything in the output matches any of the speci‐
1378 fied regular expressions.
1379 The underlying check is performed by the try_compile() command.
1381 The compile and link commands can be influenced by setting any
1382 of the following variables prior to calling
1383 check_objcxx_source_compiles():
1384 CMAKE_REQUIRED_FLAGS
1386 Additional flags to pass to the compiler. Note that the
1387 contents of CMAKE_OBJCXX_FLAGS and its associated config‐
1388 uration-specific variable are automatically added to the
1389 compiler command before the contents of
1390 CMAKE_REQUIRED_FLAGS.
1391 CMAKE_REQUIRED_DEFINITIONS
1393 A ;-list of compiler definitions of the form -DFOO or
1394 -DFOO=bar. A definition for the name specified by
1395 <resultVar> will also be added automatically.
1396 CMAKE_REQUIRED_INCLUDES
1398 A ;-list of header search paths to pass to the compiler.
1399 These will be the only header search paths used by
1400 try_compile(), i.e. the contents of the INCLUDE_DIRECTO‐
1401 RIES directory property will be ignored.
1402 CMAKE_REQUIRED_LINK_OPTIONS
1404 A ;-list of options to add to the link command (see
1405 try_compile() for further details).
1406 CMAKE_REQUIRED_LIBRARIES
1408 A ;-list of libraries to add to the link command. These
1409 can be the name of system libraries or they can be
1410 Imported Targets (see try_compile() for further details).
1411 CMAKE_REQUIRED_QUIET
1413 If this variable evaluates to a boolean true value, all
1414 status messages associated with the check will be sup‐
1415 pressed.
1416 The check is only performed once, with the result cached in the
1418 variable named by <resultVar>. Every subsequent CMake run will
1419 re-use this cached value rather than performing the check again,
1420 even if the <code> changes. In order to force the check to be
1421 re-evaluated, the variable named by <resultVar> must be manually
1422 removed from the cache.
1423 CheckOBJCXXSourceRuns
1425 New in version 3.16.
1426 Check if given Objective-C++ source compiles and links into an exe‐
1429 cutable and can subsequently be run.
1430 check_objcxx_source_runs
1432 check_objcxx_source_runs(<code> <resultVar>)
1434 Check that the source supplied in <code> can be compiled as a
1436 Objective-C++ source file, linked as an executable and then run.
1437 The <code> must contain at least a main() function. If the
1438 <code> could be built and run successfully, the internal cache
1439 variable specified by <resultVar> will be set to 1, otherwise it
1440 will be set to an value that evaluates to boolean false (e.g. an
1441 empty string or an error message).
1442 The underlying check is performed by the try_run() command. The
1444 compile and link commands can be influenced by setting any of
1445 the following variables prior to calling
1446 check_objcxx_source_runs():
1447 CMAKE_REQUIRED_FLAGS
1449 Additional flags to pass to the compiler. Note that the
1450 contents of CMAKE_OBJCXX_FLAGS and its associated config‐
1451 uration-specific variable are automatically added to the
1452 compiler command before the contents of
1453 CMAKE_REQUIRED_FLAGS.
1454 CMAKE_REQUIRED_DEFINITIONS
1456 A ;-list of compiler definitions of the form -DFOO or
1457 -DFOO=bar. A definition for the name specified by
1458 <resultVar> will also be added automatically.
1459 CMAKE_REQUIRED_INCLUDES
1461 A ;-list of header search paths to pass to the compiler.
1462 These will be the only header search paths used by
1463 try_run(), i.e. the contents of the INCLUDE_DIRECTORIES
1464 directory property will be ignored.
1465 CMAKE_REQUIRED_LINK_OPTIONS
1467 A ;-list of options to add to the link command (see
1468 try_run() for further details).
1469 CMAKE_REQUIRED_LIBRARIES
1471 A ;-list of libraries to add to the link command. These
1472 can be the name of system libraries or they can be
1473 Imported Targets (see try_run() for further details).
1474 CMAKE_REQUIRED_QUIET
1476 If this variable evaluates to a boolean true value, all
1477 status messages associated with the check will be sup‐
1478 pressed.
1479 The check is only performed once, with the result cached in the
1481 variable named by <resultVar>. Every subsequent CMake run will
1482 re-use this cached value rather than performing the check again,
1483 even if the <code> changes. In order to force the check to be
1484 re-evaluated, the variable named by <resultVar> must be manually
1485 removed from the cache.
1486 CheckPIESupported
1488 New in version 3.14.
1489 Check whether the linker supports Position Independent Code (PIE) or No
1492 Position Independent Code (NO_PIE) for executables. Use this to ensure
1493 that the POSITION_INDEPENDENT_CODE target property for executables will
1494 be honored at link time.
1495 check_pie_supported
1497 check_pie_supported([OUTPUT_VARIABLE <output>]
1499 [LANGUAGES <lang>...])
1500 Options are:
1502 OUTPUT_VARIABLE <output>
1504 Set <output> variable with details about any error.
1505 LANGUAGES <lang>...
1507 Check the linkers used for each of the specified lan‐
1508 guages. Supported languages are C, CXX, and Fortran.
1509 It makes no sense to use this module when CMP0083 is set to OLD, so the
1511 command will return an error in this case. See policy CMP0083 for
1512 details.
1513 Variables
1515 For each language checked, two boolean cache variables are defined.
1516 CMAKE_<lang>_LINK_PIE_SUPPORTED
1518 Set to YES if PIE is supported by the linker and NO other‐
1519 wise.
1520 CMAKE_<lang>_LINK_NO_PIE_SUPPORTED
1522 Set to YES if NO_PIE is supported by the linker and NO other‐
1523 wise.
1524 Examples
1526 check_pie_supported()
1527 set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE)
1528 # Retrieve any error message.
1530 check_pie_supported(OUTPUT_VARIABLE output LANGUAGES C)
1531 set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE)
1532 if(NOT CMAKE_C_LINK_PIE_SUPPORTED)
1533 message(WARNING "PIE is not supported at link time: ${output}.\n"
1534 "PIE link options will not be passed to linker.")
1535 endif()
1536 CheckPrototypeDefinition
1538 Check if the prototype we expect is correct.
1539 check_prototype_definition
1541 check_prototype_definition(FUNCTION PROTOTYPE RETURN HEADER VARIABLE)
1543 FUNCTION - The name of the function (used to check if prototype exists)
1545 PROTOTYPE- The prototype to check.
1546 RETURN - The return value of the function.
1547 HEADER - The header files required.
1548 VARIABLE - The variable to store the result.
1549 Will be created as an internal cache variable.
1550 Example:
1552 check_prototype_definition(getpwent_r
1554 "struct passwd *getpwent_r(struct passwd *src, char *buf, int buflen)"
1555 "NULL"
1556 "unistd.h;pwd.h"
1557 SOLARIS_GETPWENT_R)
1558 The following variables may be set before calling this function to mod‐
1560 ify the way the check is run:
1561 CMAKE_REQUIRED_FLAGS = string of compile command line flags
1563 CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
1564 CMAKE_REQUIRED_INCLUDES = list of include directories
1565 CMAKE_REQUIRED_LINK_OPTIONS = list of options to pass to link command
1566 CMAKE_REQUIRED_LIBRARIES = list of libraries to link
1567 CMAKE_REQUIRED_QUIET = execute quietly without messages
1568 CheckSourceCompiles
1570 New in version 3.19.
1571 Check if given source compiles and links into an executable.
1574 check_source_compiles
1576 check_source_compiles(<lang> <code> <resultVar>
1578 [FAIL_REGEX <regex1> [<regex2>...]]
1579 [SRC_EXT <extension>])
1580 Check that the source supplied in <code> can be compiled as a
1582 source file for the requested language and linked as an exe‐
1583 cutable (so it must contain at least a main() function). The
1584 result will be stored in the internal cache variable specified
1585 by <resultVar>, with a boolean true value for success and bool‐
1586 ean false for failure. If FAIL_REGEX is provided, then failure
1587 is determined by checking if anything in the output matches any
1588 of the specified regular expressions.
1589 By default, the test source file will be given a file extension
1591 that matches the requested language. The SRC_EXT option can be
1592 used to override this with .<extension> instead.
1593 The underlying check is performed by the try_compile() command.
1595 The compile and link commands can be influenced by setting any
1596 of the following variables prior to calling check_source_com‐
1597 piles():
1598 CMAKE_REQUIRED_FLAGS
1600 Additional flags to pass to the compiler. Note that the
1601 contents of CMAKE_<LANG>_FLAGS and its associated config‐
1602 uration-specific variable are automatically added to the
1603 compiler command before the contents of
1604 CMAKE_REQUIRED_FLAGS.
1605 CMAKE_REQUIRED_DEFINITIONS
1607 A ;-list of compiler definitions of the form -DFOO or
1608 -DFOO=bar. A definition for the name specified by
1609 <resultVar> will also be added automatically.
1610 CMAKE_REQUIRED_INCLUDES
1612 A ;-list of header search paths to pass to the compiler.
1613 These will be the only header search paths used by
1614 try_compile(), i.e. the contents of the INCLUDE_DIRECTO‐
1615 RIES directory property will be ignored.
1616 CMAKE_REQUIRED_LINK_OPTIONS
1618 A ;-list of options to add to the link command (see
1619 try_compile() for further details).
1620 CMAKE_REQUIRED_LIBRARIES
1622 A ;-list of libraries to add to the link command. These
1623 can be the name of system libraries or they can be
1624 Imported Targets (see try_compile() for further details).
1625 CMAKE_REQUIRED_QUIET
1627 If this variable evaluates to a boolean true value, all
1628 status messages associated with the check will be sup‐
1629 pressed.
1630 The check is only performed once, with the result cached in the
1632 variable named by <resultVar>. Every subsequent CMake run will
1633 re-use this cached value rather than performing the check again,
1634 even if the <code> changes. In order to force the check to be
1635 re-evaluated, the variable named by <resultVar> must be manually
1636 removed from the cache.
1637 CheckSourceRuns
1639 New in version 3.19.
1640 Check if given source compiles and links into an executable and can
1643 subsequently be run.
1644 check_source_runs
1646 check_source_runs(<lang> <code> <resultVar>
1648 [SRC_EXT <extension>])
1649 Check that the source supplied in <code> can be compiled as a
1651 source file for the requested language, linked as an executable
1652 and then run. The <code> must contain at least a main() func‐
1653 tion. If the <code> could be built and run successfully, the
1654 internal cache variable specified by <resultVar> will be set to
1655 1, otherwise it will be set to an value that evaluates to bool‐
1656 ean false (e.g. an empty string or an error message).
1657 By default, the test source file will be given a file extension
1659 that matches the requested language. The SRC_EXT option can be
1660 used to override this with .<extension> instead.
1661 The underlying check is performed by the try_run() command. The
1663 compile and link commands can be influenced by setting any of
1664 the following variables prior to calling
1665 check_objc_source_runs():
1666 CMAKE_REQUIRED_FLAGS
1668 Additional flags to pass to the compiler. Note that the
1669 contents of CMAKE_OBJC_FLAGS and its associated configu‐
1670 ration-specific variable are automatically added to the
1671 compiler command before the contents of
1672 CMAKE_REQUIRED_FLAGS.
1673 CMAKE_REQUIRED_DEFINITIONS
1675 A ;-list of compiler definitions of the form -DFOO or
1676 -DFOO=bar. A definition for the name specified by
1677 <resultVar> will also be added automatically.
1678 CMAKE_REQUIRED_INCLUDES
1680 A ;-list of header search paths to pass to the compiler.
1681 These will be the only header search paths used by
1682 try_run(), i.e. the contents of the INCLUDE_DIRECTORIES
1683 directory property will be ignored.
1684 CMAKE_REQUIRED_LINK_OPTIONS
1686 A ;-list of options to add to the link command (see
1687 try_run() for further details).
1688 CMAKE_REQUIRED_LIBRARIES
1690 A ;-list of libraries to add to the link command. These
1691 can be the name of system libraries or they can be
1692 Imported Targets (see try_run() for further details).
1693 CMAKE_REQUIRED_QUIET
1695 If this variable evaluates to a boolean true value, all
1696 status messages associated with the check will be sup‐
1697 pressed.
1698 The check is only performed once, with the result cached in the
1700 variable named by <resultVar>. Every subsequent CMake run will
1701 re-use this cached value rather than performing the check again,
1702 even if the <code> changes. In order to force the check to be
1703 re-evaluated, the variable named by <resultVar> must be manually
1704 removed from the cache.
1705 CheckStructHasMember
1707 Check if the given struct or class has the specified member variable
1708 CHECK_STRUCT_HAS_MEMBER
1710 CHECK_STRUCT_HAS_MEMBER(<struct> <member> <header> <variable>
1712 [LANGUAGE <language>])
1713 <struct> - the name of the struct or class you are interested in
1715 <member> - the member which existence you want to check
1716 <header> - the header(s) where the prototype should be declared
1717 <variable> - variable to store the result
1718 <language> - the compiler to use (C or CXX)
1719 The following variables may be set before calling this macro to modify
1721 the way the check is run:
1722 CMAKE_REQUIRED_FLAGS = string of compile command line flags
1724 CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
1725 CMAKE_REQUIRED_INCLUDES = list of include directories
1726 CMAKE_REQUIRED_LINK_OPTIONS = list of options to pass to link command
1727 CMAKE_REQUIRED_LIBRARIES = list of libraries to link
1728 CMAKE_REQUIRED_QUIET = execute quietly without messages
1729 Example:
1731 CHECK_STRUCT_HAS_MEMBER("struct timeval" tv_sec sys/select.h
1733 HAVE_TIMEVAL_TV_SEC LANGUAGE C)
1734 CheckSymbolExists
1736 Provides a macro to check if a symbol exists as a function, variable,
1737 or macro in C.
1738 check_symbol_exists
1740 check_symbol_exists(<symbol> <files> <variable>)
1742 Check that the <symbol> is available after including given
1744 header <files> and store the result in a <variable>. Specify
1745 the list of files in one argument as a semicolon-separated list.
1746 <variable> will be created as an internal cache variable.
1747 If the header files define the symbol as a macro it is considered
1749 available and assumed to work. If the header files declare the symbol
1750 as a function or variable then the symbol must also be available for
1751 linking (so intrinsics may not be detected). If the symbol is a type,
1752 enum value, or intrinsic it will not be recognized (consider using
1753 CheckTypeSize or CheckCSourceCompiles). If the check needs to be done
1754 in C++, consider using CheckCXXSymbolExists instead.
1755 The following variables may be set before calling this macro to modify
1757 the way the check is run:
1758 CMAKE_REQUIRED_FLAGS
1760 string of compile command line flags.
1761 CMAKE_REQUIRED_DEFINITIONS
1763 a ;-list of macros to define (-DFOO=bar).
1764 CMAKE_REQUIRED_INCLUDES
1766 a ;-list of header search paths to pass to the compiler.
1767 CMAKE_REQUIRED_LINK_OPTIONS
1769 a ;-list of options to add to the link command.
1770 CMAKE_REQUIRED_LIBRARIES
1772 a ;-list of libraries to add to the link command. See policy
1773 CMP0075.
1774 CMAKE_REQUIRED_QUIET
1776 execute quietly without messages.
1777 For example:
1779 include(CheckSymbolExists)
1781 # Check for macro SEEK_SET
1783 check_symbol_exists(SEEK_SET "stdio.h" HAVE_SEEK_SET)
1784 # Check for function fopen
1785 check_symbol_exists(fopen "stdio.h" HAVE_FOPEN)
1786 CheckTypeSize
1788 Check sizeof a type
1789 CHECK_TYPE_SIZE
1791 CHECK_TYPE_SIZE(TYPE VARIABLE [BUILTIN_TYPES_ONLY]
1793 [LANGUAGE <language>])
1794 Check if the type exists and determine its size. On return,
1796 HAVE_${VARIABLE} holds the existence of the type, and ${VARI‐
1797 ABLE} holds one of the following:
1798 <size> = type has non-zero size <size>
1800 "0" = type has arch-dependent size (see below)
1801 "" = type does not exist
1802 Both HAVE_${VARIABLE} and ${VARIABLE} will be created as inter‐
1804 nal cache variables.
1805 Furthermore, the variable ${VARIABLE}_CODE holds C preprocessor
1807 code to define the macro ${VARIABLE} to the size of the type, or
1808 leave the macro undefined if the type does not exist.
1809 The variable ${VARIABLE} may be 0 when CMAKE_OSX_ARCHITECTURES
1811 has multiple architectures for building OS X universal binaries.
1812 This indicates that the type size varies across architectures.
1813 In this case ${VARIABLE}_CODE contains C preprocessor tests map‐
1814 ping from each architecture macro to the corresponding type
1815 size. The list of architecture macros is stored in ${VARI‐
1816 ABLE}_KEYS, and the value for each key is stored in ${VARI‐
1817 ABLE}-${KEY}.
1818 If the BUILTIN_TYPES_ONLY option is not given, the macro checks
1820 for headers <sys/types.h>, <stdint.h>, and <stddef.h>, and saves
1821 results in HAVE_SYS_TYPES_H, HAVE_STDINT_H, and HAVE_STDDEF_H.
1822 The type size check automatically includes the available head‐
1823 ers, thus supporting checks of types defined in the headers.
1824 If LANGUAGE is set, the specified compiler will be used to per‐
1826 form the check. Acceptable values are C and CXX.
1827 Despite the name of the macro you may use it to check the size of more
1829 complex expressions, too. To check e.g. for the size of a struct mem‐
1830 ber you can do something like this:
1831 check_type_size("((struct something*)0)->member" SIZEOF_MEMBER)
1833 The following variables may be set before calling this macro to modify
1835 the way the check is run:
1836 CMAKE_REQUIRED_FLAGS = string of compile command line flags
1838 CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
1839 CMAKE_REQUIRED_INCLUDES = list of include directories
1840 CMAKE_REQUIRED_LINK_OPTIONS = list of options to pass to link command
1841 CMAKE_REQUIRED_LIBRARIES = list of libraries to link
1842 CMAKE_REQUIRED_QUIET = execute quietly without messages
1843 CMAKE_EXTRA_INCLUDE_FILES = list of extra headers to include
1844 CheckVariableExists
1846 Check if the variable exists.
1847 CHECK_VARIABLE_EXISTS
1849 CHECK_VARIABLE_EXISTS(VAR VARIABLE)
1851 VAR - the name of the variable
1853 VARIABLE - variable to store the result
1854 Will be created as an internal cache variable.
1855 This macro is only for C variables.
1857 The following variables may be set before calling this macro to modify
1859 the way the check is run:
1860 CMAKE_REQUIRED_FLAGS = string of compile command line flags
1862 CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
1863 CMAKE_REQUIRED_LINK_OPTIONS = list of options to pass to link command
1864 CMAKE_REQUIRED_LIBRARIES = list of libraries to link
1865 CMAKE_REQUIRED_QUIET = execute quietly without messages
1866 CMakeAddFortranSubdirectory
1868 Add a fortran-only subdirectory, find a fortran compiler, and build.
1869 The cmake_add_fortran_subdirectory function adds a subdirectory to a
1871 project that contains a fortran-only subproject. The module will check
1872 the current compiler and see if it can support fortran. If no fortran
1873 compiler is found and the compiler is MSVC, then this module will find
1874 the MinGW gfortran. It will then use an external project to build with
1875 the MinGW tools. It will also create imported targets for the
1876 libraries created. This will only work if the fortran code is built
1877 into a dll, so BUILD_SHARED_LIBS is turned on in the project. In addi‐
1878 tion the CMAKE_GNUtoMS option is set to on, so that Microsoft .lib
1879 files are created. Usage is as follows:
1880 cmake_add_fortran_subdirectory(
1882 <subdir> # name of subdirectory
1883 PROJECT <project_name> # project name in subdir top CMakeLists.txt
1884 ARCHIVE_DIR <dir> # dir where project places .lib files
1885 RUNTIME_DIR <dir> # dir where project places .dll files
1886 LIBRARIES <lib>... # names of library targets to import
1887 LINK_LIBRARIES # link interface libraries for LIBRARIES
1888 [LINK_LIBS <lib> <dep>...]...
1889 CMAKE_COMMAND_LINE ... # extra command line flags to pass to cmake
1890 NO_EXTERNAL_INSTALL # skip installation of external project
1891 )
1892 Relative paths in ARCHIVE_DIR and RUNTIME_DIR are interpreted with
1894 respect to the build directory corresponding to the source directory in
1895 which the function is invoked.
1896 Limitations:
1898 NO_EXTERNAL_INSTALL is required for forward compatibility with a future
1900 version that supports installation of the external project binaries
1901 during make install.
1902 CMakeBackwardCompatibilityCXX
1904 define a bunch of backwards compatibility variables
1905 CMAKE_ANSI_CXXFLAGS - flag for ansi c++
1907 CMAKE_HAS_ANSI_STRING_STREAM - has <strstream>
1908 include(TestForANSIStreamHeaders)
1909 include(CheckIncludeFileCXX)
1910 include(TestForSTDNamespace)
1911 include(TestForANSIForScope)
1912 CMakeDependentOption
1914 Macro to provide an option dependent on other options.
1915 This macro presents an option to the user only if a set of other condi‐
1917 tions are true.
1918 Usage:
1920 cmake_dependent_option(<option> "<help_text>" <value> <depends> <force>)
1922 Where <option> is available to the user if <depends> is true. When
1924 <option> is available, the given <help_text> and initial <value> are
1925 used. If the <depends> condition is not true, <option> will not be pre‐
1926 sented and will always have the value given by <force>. Any value set
1927 by the user is preserved for when the option is presented again. Each
1928 element in the fourth parameter is evaluated as an if-condition, so
1929 Condition Syntax can be used.
1930 Example invocation:
1932 cmake_dependent_option(USE_FOO "Use Foo" ON
1934 "USE_BAR;NOT USE_ZOT" OFF)
1935 If USE_BAR is true and USE_ZOT is false, this provides an option called
1937 USE_FOO that defaults to ON. Otherwise, it sets USE_FOO to OFF and
1938 hides the option from the user. If the status of USE_BAR or USE_ZOT
1939 ever changes, any value for the USE_FOO option is saved so that when
1940 the option is re-enabled it retains its old value.
1941 CMakeFindDependencyMacro
1943 find_dependency
1944 The find_dependency() macro wraps a find_package() call for a
1945 package dependency:
1946 find_dependency(<dep> [...])
1948 It is designed to be used in a Package Configuration File
1950 (<PackageName>Config.cmake). find_dependency forwards the cor‐
1951 rect parameters for QUIET and REQUIRED which were passed to the
1952 original find_package() call. Any additional arguments speci‐
1953 fied are forwarded to find_package().
1954 If the dependency could not be found it sets an informative
1956 diagnostic message and calls return() to end processing of the
1957 calling package configuration file and return to the find_pack‐
1958 age() command that loaded it.
1959 NOTE:
1961 The call to return() makes this macro unsuitable to call from
1962 Find Modules.
1963 CMakeFindFrameworks
1965 helper module to find OSX frameworks
1966 This module reads hints about search locations from variables:
1968 CMAKE_FIND_FRAMEWORK_EXTRA_LOCATIONS - Extra directories
1970 CMakeFindPackageMode
1972 This file is executed by cmake when invoked with –find-package. It
1973 expects that the following variables are set using -D:
1974 NAME name of the package
1976 COMPILER_ID
1978 the CMake compiler ID for which the result is, i.e.
1979 GNU/Intel/Clang/MSVC, etc.
1980 LANGUAGE
1982 language for which the result will be used, i.e. C/CXX/For‐
1983 tran/ASM
1984 MODE
1986 EXIST only check for existence of the given package
1988 COMPILE
1990 print the flags needed for compiling an object file which
1991 uses the given package
1992 LINK print the flags needed for linking when using the given
1994 package
1995 QUIET if TRUE, don’t print anything
1997 CMakeGraphVizOptions
1999 The builtin Graphviz support of CMake.
2000 Generating Graphviz files
2002 CMake can generate Graphviz files showing the dependencies between the
2003 targets in a project, as well as external libraries which are linked
2004 against.
2005 When running CMake with the --graphviz=foo.dot option, it produces:
2007 · a foo.dot file, showing all dependencies in the project
2009 · a foo.dot.<target> file for each target, showing on which other tar‐
2011 gets it depends
2012 · a foo.dot.<target>.dependers file for each target, showing which
2014 other targets depend on it
2015 Those .dot files can be converted to images using the dot command from
2017 the Graphviz package:
2018 dot -Tpng -o foo.png foo.dot
2020 The different dependency types PUBLIC, INTERFACE and PRIVATE are repre‐
2022 sented as solid, dashed and dotted edges.
2023 Variables specific to the Graphviz support
2025 The resulting graphs can be huge. The look and content of the gener‐
2026 ated graphs can be controlled using the file CMakeGraphVizOp‐
2027 tions.cmake. This file is first searched in CMAKE_BINARY_DIR, and then
2028 in CMAKE_SOURCE_DIR. If found, the variables set in it are used to
2029 adjust options for the generated Graphviz files.
2030 GRAPHVIZ_GRAPH_NAME
2032 The graph name.
2033 · Mandatory: NO
2035 · Default: value of CMAKE_PROJECT_NAME
2037 GRAPHVIZ_GRAPH_HEADER
2039 The header written at the top of the Graphviz files.
2040 · Mandatory: NO
2042 · Default: “node [ fontsize = “12” ];”
2044 GRAPHVIZ_NODE_PREFIX
2046 The prefix for each node in the Graphviz files.
2047 · Mandatory: NO
2049 · Default: “node”
2051 GRAPHVIZ_EXECUTABLES
2053 Set to FALSE to exclude executables from the generated graphs.
2054 · Mandatory: NO
2056 · Default: TRUE
2058 GRAPHVIZ_STATIC_LIBS
2060 Set to FALSE to exclude static libraries from the generated
2061 graphs.
2062 · Mandatory: NO
2064 · Default: TRUE
2066 GRAPHVIZ_SHARED_LIBS
2068 Set to FALSE to exclude shared libraries from the generated
2069 graphs.
2070 · Mandatory: NO
2072 · Default: TRUE
2074 GRAPHVIZ_MODULE_LIBS
2076 Set to FALSE to exclude module libraries from the generated
2077 graphs.
2078 · Mandatory: NO
2080 · Default: TRUE
2082 GRAPHVIZ_INTERFACE_LIBS
2084 Set to FALSE to exclude interface libraries from the generated
2085 graphs.
2086 · Mandatory: NO
2088 · Default: TRUE
2090 GRAPHVIZ_OBJECT_LIBS
2092 Set to FALSE to exclude object libraries from the generated
2093 graphs.
2094 · Mandatory: NO
2096 · Default: TRUE
2098 GRAPHVIZ_UNKNOWN_LIBS
2100 Set to FALSE to exclude unknown libraries from the generated
2101 graphs.
2102 · Mandatory: NO
2104 · Default: TRUE
2106 GRAPHVIZ_EXTERNAL_LIBS
2108 Set to FALSE to exclude external libraries from the generated
2109 graphs.
2110 · Mandatory: NO
2112 · Default: TRUE
2114 GRAPHVIZ_CUSTOM_TARGETS
2116 Set to TRUE to include custom targets in the generated graphs.
2117 · Mandatory: NO
2119 · Default: FALSE
2121 GRAPHVIZ_IGNORE_TARGETS
2123 A list of regular expressions for names of targets to exclude
2124 from the generated graphs.
2125 · Mandatory: NO
2127 · Default: empty
2129 GRAPHVIZ_GENERATE_PER_TARGET
2131 Set to FALSE to not generate per-target graphs foo.dot.<target>.
2132 · Mandatory: NO
2134 · Default: TRUE
2136 GRAPHVIZ_GENERATE_DEPENDERS
2138 Set to FALSE to not generate depender graphs foo.dot.<tar‐
2139 get>.dependers.
2140 · Mandatory: NO
2142 · Default: TRUE
2144 CMakePackageConfigHelpers
2146 Helpers functions for creating config files that can be included by
2147 other projects to find and use a package.
2148 Adds the configure_package_config_file() and
2150 write_basic_package_version_file() commands.
2151 Generating a Package Configuration File
2153 configure_package_config_file
2154 Create a config file for a project:
2155 configure_package_config_file(<input> <output>
2157 INSTALL_DESTINATION <path>
2158 [PATH_VARS <var1> <var2> ... <varN>]
2159 [NO_SET_AND_CHECK_MACRO]
2160 [NO_CHECK_REQUIRED_COMPONENTS_MACRO]
2161 [INSTALL_PREFIX <path>]
2162 )
2163 configure_package_config_file() should be used instead of the plain
2165 configure_file() command when creating the <PackageName>Config.cmake or
2166 <PackageName>-config.cmake file for installing a project or library.
2167 It helps making the resulting package relocatable by avoiding hardcoded
2168 paths in the installed Config.cmake file.
2169 In a FooConfig.cmake file there may be code like this to make the
2171 install destinations know to the using project:
2172 set(FOO_INCLUDE_DIR "@CMAKE_INSTALL_FULL_INCLUDEDIR@" )
2174 set(FOO_DATA_DIR "@CMAKE_INSTALL_PREFIX@/@RELATIVE_DATA_INSTALL_DIR@" )
2175 set(FOO_ICONS_DIR "@CMAKE_INSTALL_PREFIX@/share/icons" )
2176 #...logic to determine installedPrefix from the own location...
2177 set(FOO_CONFIG_DIR "${installedPrefix}/@CONFIG_INSTALL_DIR@" )
2178 All 4 options shown above are not sufficient, since the first 3 hard‐
2180 code the absolute directory locations, and the 4th case works only if
2181 the logic to determine the installedPrefix is correct, and if CON‐
2182 FIG_INSTALL_DIR contains a relative path, which in general cannot be
2183 guaranteed. This has the effect that the resulting FooConfig.cmake
2184 file would work poorly under Windows and OSX, where users are used to
2185 choose the install location of a binary package at install time, inde‐
2186 pendent from how CMAKE_INSTALL_PREFIX was set at build/cmake time.
2187 Using configure_package_config_file helps. If used correctly, it makes
2189 the resulting FooConfig.cmake file relocatable. Usage:
2190 1. write a FooConfig.cmake.in file as you are used to
2192 2. insert a line containing only the string @PACKAGE_INIT@
2194 3. instead of set(FOO_DIR "@SOME_INSTALL_DIR@"), use set(FOO_DIR
2196 "@PACKAGE_SOME_INSTALL_DIR@") (this must be after the @PACKAGE_INIT@
2197 line)
2198 4. instead of using the normal configure_file(), use configure_pack‐
2200 age_config_file()
2201 The <input> and <output> arguments are the input and output file, the
2203 same way as in configure_file().
2204 The <path> given to INSTALL_DESTINATION must be the destination where
2206 the FooConfig.cmake file will be installed to. This path can either be
2207 absolute, or relative to the INSTALL_PREFIX path.
2208 The variables <var1> to <varN> given as PATH_VARS are the variables
2210 which contain install destinations. For each of them the macro will
2211 create a helper variable PACKAGE_<var...>. These helper variables must
2212 be used in the FooConfig.cmake.in file for setting the installed loca‐
2213 tion. They are calculated by configure_package_config_file so that
2214 they are always relative to the installed location of the package.
2215 This works both for relative and also for absolute locations. For
2216 absolute locations it works only if the absolute location is a subdi‐
2217 rectory of INSTALL_PREFIX.
2218 If the INSTALL_PREFIX argument is passed, this is used as base path to
2220 calculate all the relative paths. The <path> argument must be an abso‐
2221 lute path. If this argument is not passed, the CMAKE_INSTALL_PREFIX
2222 variable will be used instead. The default value is good when generat‐
2223 ing a FooConfig.cmake file to use your package from the install tree.
2224 When generating a FooConfig.cmake file to use your package from the
2225 build tree this option should be used.
2226 By default configure_package_config_file also generates two helper
2228 macros, set_and_check() and check_required_components() into the
2229 FooConfig.cmake file.
2230 set_and_check() should be used instead of the normal set() command for
2232 setting directories and file locations. Additionally to setting the
2233 variable it also checks that the referenced file or directory actually
2234 exists and fails with a FATAL_ERROR otherwise. This makes sure that
2235 the created FooConfig.cmake file does not contain wrong references.
2236 When using the NO_SET_AND_CHECK_MACRO, this macro is not generated into
2237 the FooConfig.cmake file.
2238 check_required_components(<PackageName>) should be called at the end of
2240 the FooConfig.cmake file. This macro checks whether all requested,
2241 non-optional components have been found, and if this is not the case,
2242 sets the Foo_FOUND variable to FALSE, so that the package is considered
2243 to be not found. It does that by testing the Foo_<Component>_FOUND
2244 variables for all requested required components. This macro should be
2245 called even if the package doesn’t provide any components to make sure
2246 users are not specifying components erroneously. When using the
2247 NO_CHECK_REQUIRED_COMPONENTS_MACRO option, this macro is not generated
2248 into the FooConfig.cmake file.
2249 For an example see below the documentation for
2251 write_basic_package_version_file().
2252 Generating a Package Version File
2254 write_basic_package_version_file
2255 Create a version file for a project:
2256 write_basic_package_version_file(<filename>
2258 [VERSION <major.minor.patch>]
2259 COMPATIBILITY <AnyNewerVersion|SameMajorVersion|SameMinorVersion|ExactVersion>
2260 [ARCH_INDEPENDENT] )
2261 Writes a file for use as <PackageName>ConfigVersion.cmake file to
2263 <filename>. See the documentation of find_package() for details on
2264 this.
2265 <filename> is the output filename, it should be in the build tree.
2267 <major.minor.patch> is the version number of the project to be
2268 installed.
2269 If no VERSION is given, the PROJECT_VERSION variable is used. If this
2271 hasn’t been set, it errors out.
2272 The COMPATIBILITY mode AnyNewerVersion means that the installed package
2274 version will be considered compatible if it is newer or exactly the
2275 same as the requested version. This mode should be used for packages
2276 which are fully backward compatible, also across major versions. If
2277 SameMajorVersion is used instead, then the behaviour differs from
2278 AnyNewerVersion in that the major version number must be the same as
2279 requested, e.g. version 2.0 will not be considered compatible if 1.0
2280 is requested. This mode should be used for packages which guarantee
2281 backward compatibility within the same major version. If SameMinorVer‐
2282 sion is used, the behaviour is the same as SameMajorVersion, but both
2283 major and minor version must be the same as requested, e.g version 0.2
2284 will not be compatible if 0.1 is requested. If ExactVersion is used,
2285 then the package is only considered compatible if the requested version
2286 matches exactly its own version number (not considering the tweak ver‐
2287 sion). For example, version 1.2.3 of a package is only considered com‐
2288 patible to requested version 1.2.3. This mode is for packages without
2289 compatibility guarantees. If your project has more elaborated version
2290 matching rules, you will need to write your own custom ConfigVer‐
2291 sion.cmake file instead of using this macro.
2292 NOTE:
2294 COMPATIBILITY_MODE AnyNewerVersion, SameMajorVersion and SameMi‐
2295 norVersion handle the version range if any is specified (see
2296 find_package() command for the details). ExactVersion is incompati‐
2297 ble with version ranges and will display an author warning if one is
2298 specified.
2299 If ARCH_INDEPENDENT is given, the installed package version will be
2301 considered compatible even if it was built for a different architecture
2302 than the requested architecture. Otherwise, an architecture check will
2303 be performed, and the package will be considered compatible only if the
2304 architecture matches exactly. For example, if the package is built for
2305 a 32-bit architecture, the package is only considered compatible if it
2306 is used on a 32-bit architecture, unless ARCH_INDEPENDENT is given, in
2307 which case the package is considered compatible on any architecture.
2308 NOTE:
2310 ARCH_INDEPENDENT is intended for header-only libraries or similar
2311 packages with no binaries.
2312 Internally, this macro executes configure_file() to create the result‐
2314 ing version file. Depending on the COMPATIBILITY, the corresponding
2315 BasicConfigVersion-<COMPATIBILITY>.cmake.in file is used. Please note
2316 that these files are internal to CMake and you should not call config‐
2317 ure_file() on them yourself, but they can be used as starting point to
2318 create more sophisticted custom ConfigVersion.cmake files.
2319 Example Generating Package Files
2321 Example using both configure_package_config_file() and
2322 write_basic_package_version_file():
2323 CMakeLists.txt:
2325 set(INCLUDE_INSTALL_DIR include/ ... CACHE )
2327 set(LIB_INSTALL_DIR lib/ ... CACHE )
2328 set(SYSCONFIG_INSTALL_DIR etc/foo/ ... CACHE )
2329 #...
2330 include(CMakePackageConfigHelpers)
2331 configure_package_config_file(FooConfig.cmake.in
2332 ${CMAKE_CURRENT_BINARY_DIR}/FooConfig.cmake
2333 INSTALL_DESTINATION ${LIB_INSTALL_DIR}/Foo/cmake
2334 PATH_VARS INCLUDE_INSTALL_DIR SYSCONFIG_INSTALL_DIR)
2335 write_basic_package_version_file(
2336 ${CMAKE_CURRENT_BINARY_DIR}/FooConfigVersion.cmake
2337 VERSION 1.2.3
2338 COMPATIBILITY SameMajorVersion )
2339 install(FILES ${CMAKE_CURRENT_BINARY_DIR}/FooConfig.cmake
2340 ${CMAKE_CURRENT_BINARY_DIR}/FooConfigVersion.cmake
2341 DESTINATION ${LIB_INSTALL_DIR}/Foo/cmake )
2342 FooConfig.cmake.in:
2344 set(FOO_VERSION x.y.z)
2346 ...
2347 @PACKAGE_INIT@
2348 ...
2349 set_and_check(FOO_INCLUDE_DIR "@PACKAGE_INCLUDE_INSTALL_DIR@")
2350 set_and_check(FOO_SYSCONFIG_DIR "@PACKAGE_SYSCONFIG_INSTALL_DIR@")
2351 check_required_components(Foo)
2353 CMakePrintHelpers
2355 Convenience functions for printing properties and variables, useful
2356 e.g. for debugging.
2357 cmake_print_properties([TARGETS target1 .. targetN]
2359 [SOURCES source1 .. sourceN]
2360 [DIRECTORIES dir1 .. dirN]
2361 [TESTS test1 .. testN]
2362 [CACHE_ENTRIES entry1 .. entryN]
2363 PROPERTIES prop1 .. propN )
2364 This function prints the values of the properties of the given targets,
2366 source files, directories, tests or cache entries. Exactly one of the
2367 scope keywords must be used. Example:
2368 cmake_print_properties(TARGETS foo bar PROPERTIES
2370 LOCATION INTERFACE_INCLUDE_DIRECTORIES)
2371 This will print the LOCATION and INTERFACE_INCLUDE_DIRECTORIES proper‐
2373 ties for both targets foo and bar.
2374 cmake_print_variables(var1 var2 .. varN)
2376 This function will print the name of each variable followed by its
2378 value. Example:
2379 cmake_print_variables(CMAKE_C_COMPILER CMAKE_MAJOR_VERSION DOES_NOT_EXIST)
2381 Gives:
2383 -- CMAKE_C_COMPILER="/usr/bin/gcc" ; CMAKE_MAJOR_VERSION="2" ; DOES_NOT_EXIST=""
2385 CMakePrintSystemInformation
2387 Print system information.
2388 This module serves diagnostic purposes. Just include it in a project to
2390 see various internal CMake variables.
2391 CMakePushCheckState
2393 This module defines three macros: CMAKE_PUSH_CHECK_STATE()
2394 CMAKE_POP_CHECK_STATE() and CMAKE_RESET_CHECK_STATE() These macros can
2395 be used to save, restore and reset (i.e., clear contents) the state of
2396 the variables CMAKE_REQUIRED_FLAGS, CMAKE_REQUIRED_DEFINITIONS,
2397 CMAKE_REQUIRED_LINK_OPTIONS, CMAKE_REQUIRED_LIBRARIES,
2398 CMAKE_REQUIRED_INCLUDES and CMAKE_EXTRA_INCLUDE_FILES used by the vari‐
2399 ous Check-files coming with CMake, like e.g. check_function_exists()
2400 etc. The variable contents are pushed on a stack, pushing multiple
2401 times is supported. This is useful e.g. when executing such tests in
2402 a Find-module, where they have to be set, but after the Find-module has
2403 been executed they should have the same value as they had before.
2404 CMAKE_PUSH_CHECK_STATE() macro receives optional argument RESET.
2406 Whether it’s specified, CMAKE_PUSH_CHECK_STATE() will set all
2407 CMAKE_REQUIRED_* variables to empty values, same as
2408 CMAKE_RESET_CHECK_STATE() call will do.
2409 Usage:
2411 cmake_push_check_state(RESET)
2413 set(CMAKE_REQUIRED_DEFINITIONS -DSOME_MORE_DEF)
2414 check_function_exists(...)
2415 cmake_reset_check_state()
2416 set(CMAKE_REQUIRED_DEFINITIONS -DANOTHER_DEF)
2417 check_function_exists(...)
2418 cmake_pop_check_state()
2419 CMakeVerifyManifest
2421 CMakeVerifyManifest.cmake
2422 This script is used to verify that embedded manifests and side by side
2424 manifests for a project match. To run this script, cd to a directory
2425 and run the script with cmake -P. On the command line you can pass in
2426 versions that are OK even if not found in the .manifest files. For
2427 example, cmake -Dallow_versions=8.0.50608.0 -PCmakeVerifyManifest.cmake
2428 could be used to allow an embedded manifest of 8.0.50608.0 to be used
2429 in a project even if that version was not found in the .manifest file.
2430 CPack
2432 Configure generators for binary installers and source packages.
2433 Introduction
2435 The CPack module generates the configuration files CPackConfig.cmake
2436 and CPackSourceConfig.cmake. They are intended for use in a subsequent
2437 run of the cpack program where they steer the generation of installers
2438 or/and source packages.
2439 Depending on the CMake generator, the CPack module may also add two new
2441 build targets, package and package_source. See the packaging targets
2442 section below for details.
2443 The generated binary installers will contain all files that have been
2445 installed via CMake’s install() command (and the deprecated commands
2446 install_files(), install_programs(), and install_targets()). Note that
2447 the DESTINATION option of the install() command must be a relative
2448 path; otherwise installed files are ignored by CPack.
2449 Certain kinds of binary installers can be configured such that users
2451 can select individual application components to install. See the
2452 CPackComponent module for further details.
2453 Source packages (configured through CPackSourceConfig.cmake and gener‐
2455 ated by the CPack Archive Generator) will contain all source files in
2456 the project directory except those specified in
2457 CPACK_SOURCE_IGNORE_FILES.
2458 CPack Generators
2460 The CPACK_GENERATOR variable has different meanings in different con‐
2461 texts. In a CMakeLists.txt file, CPACK_GENERATOR is a list of genera‐
2462 tors: and when cpack is run with no other arguments, it will iterate
2463 over that list and produce one package for each generator. In a
2464 CPACK_PROJECT_CONFIG_FILE, CPACK_GENERATOR is a string naming a single
2465 generator. If you need per-cpack-generator logic to control other
2466 cpack settings, then you need a CPACK_PROJECT_CONFIG_FILE. If set, the
2467 CPACK_PROJECT_CONFIG_FILE is included automatically on a per-generator
2468 basis. It only need contain overrides.
2469 Here’s how it works:
2471 · cpack runs
2473 · it includes CPackConfig.cmake
2475 · it iterates over the generators given by the -G command line option,
2477 or if no such option was specified, over the list of generators given
2478 by the CPACK_GENERATOR variable set in the CPackConfig.cmake input
2479 file.
2480 · foreach generator, it then
2482 · sets CPACK_GENERATOR to the one currently being iterated
2484 · includes the CPACK_PROJECT_CONFIG_FILE
2486 · produces the package for that generator
2488 This is the key: For each generator listed in CPACK_GENERATOR in CPack‐
2490 Config.cmake, cpack will reset CPACK_GENERATOR internally to the one
2491 currently being used and then include the CPACK_PROJECT_CONFIG_FILE.
2492 For a list of available generators, see cpack-generators(7).
2494 Targets package and package_source
2496 If CMake is run with the Makefile, Ninja, or Xcode generator, then
2497 include(CPack) generates a target package. This makes it possible to
2498 build a binary installer from CMake, Make, or Ninja: Instead of cpack,
2499 one may call cmake --build . --target package or make package or ninja
2500 package. The VS generator creates an uppercase target PACKAGE.
2501 If CMake is run with the Makefile or Ninja generator, then
2503 include(CPack) also generates a target package_source. To build a
2504 source package, instead of cpack -G TGZ --config CPackSourceCon‐
2505 fig.cmake one may call cmake --build . --target package_source, make
2506 package_source, or ninja package_source.
2507 Variables common to all CPack Generators
2509 Before including this CPack module in your CMakeLists.txt file, there
2510 are a variety of variables that can be set to customize the resulting
2511 installers. The most commonly-used variables are:
2512 CPACK_PACKAGE_NAME
2514 The name of the package (or application). If not specified, it
2515 defaults to the project name.
2516 CPACK_PACKAGE_VENDOR
2518 The name of the package vendor. (e.g., “Kitware”). The default
2519 is “Humanity”.
2520 CPACK_PACKAGE_DIRECTORY
2522 The directory in which CPack is doing its packaging. If it is
2523 not set then this will default (internally) to the build dir.
2524 This variable may be defined in a CPack config file or from the
2525 cpack command line option -B. If set, the command line option
2526 overrides the value found in the config file.
2527 CPACK_PACKAGE_VERSION_MAJOR
2529 Package major version. This variable will always be set, but
2530 its default value depends on whether or not version details were
2531 given to the project() command in the top level CMakeLists.txt
2532 file. If version details were given, the default value will be
2533 CMAKE_PROJECT_VERSION_MAJOR. If no version details were given,
2534 a default version of 0.1.1 will be assumed, leading to
2535 CPACK_PACKAGE_VERSION_MAJOR having a default value of 0.
2536 CPACK_PACKAGE_VERSION_MINOR
2538 Package minor version. The default value is determined based on
2539 whether or not version details were given to the project() com‐
2540 mand in the top level CMakeLists.txt file. If version details
2541 were given, the default value will be CMAKE_PROJECT_VER‐
2542 SION_MINOR, but if no minor version component was specified then
2543 CPACK_PACKAGE_VERSION_MINOR will be left unset. If no project
2544 version was given at all, a default version of 0.1.1 will be
2545 assumed, leading to CPACK_PACKAGE_VERSION_MINOR having a default
2546 value of 1.
2547 CPACK_PACKAGE_VERSION_PATCH
2549 Package patch version. The default value is determined based on
2550 whether or not version details were given to the project() com‐
2551 mand in the top level CMakeLists.txt file. If version details
2552 were given, the default value will be CMAKE_PROJECT_VER‐
2553 SION_PATCH, but if no patch version component was specified then
2554 CPACK_PACKAGE_VERSION_PATCH will be left unset. If no project
2555 version was given at all, a default version of 0.1.1 will be
2556 assumed, leading to CPACK_PACKAGE_VERSION_PATCH having a default
2557 value of 1.
2558 CPACK_PACKAGE_DESCRIPTION
2560 A description of the project, used in places such as the intro‐
2561 duction screen of CPack-generated Windows installers. If not
2562 set, the value of this variable is populated from the file named
2563 by CPACK_PACKAGE_DESCRIPTION_FILE.
2564 CPACK_PACKAGE_DESCRIPTION_FILE
2566 A text file used to describe the project when
2567 CPACK_PACKAGE_DESCRIPTION is not explicitly set. The default
2568 value for CPACK_PACKAGE_DESCRIPTION_FILE points to a built-in
2569 template file Templates/CPack.GenericDescription.txt.
2570 CPACK_PACKAGE_DESCRIPTION_SUMMARY
2572 Short description of the project (only a few words). If the
2573 CMAKE_PROJECT_DESCRIPTION variable is set, it is used as the
2574 default value, otherwise the default will be a string generated
2575 by CMake based on CMAKE_PROJECT_NAME.
2576 CPACK_PACKAGE_HOMEPAGE_URL
2578 Project homepage URL. The default value is taken from the
2579 CMAKE_PROJECT_HOMEPAGE_URL variable, which is set by the top
2580 level project() command, or else the default will be empty if no
2581 URL was provided to project().
2582 CPACK_PACKAGE_FILE_NAME
2584 The name of the package file to generate, not including the
2585 extension. For example, cmake-2.6.1-Linux-i686. The default
2586 value is:
2587 ${CPACK_PACKAGE_NAME}-${CPACK_PACKAGE_VERSION}-${CPACK_SYSTEM_NAME}
2589 CPACK_PACKAGE_INSTALL_DIRECTORY
2591 Installation directory on the target system. This may be used by
2592 some CPack generators like NSIS to create an installation direc‐
2593 tory e.g., “CMake 2.5” below the installation prefix. All
2594 installed elements will be put inside this directory.
2595 CPACK_PACKAGE_ICON
2597 A branding image that will be displayed inside the installer
2598 (used by GUI installers).
2599 CPACK_PACKAGE_CHECKSUM
2601 An algorithm that will be used to generate an additional file
2602 with the checksum of the package. The output file name will be:
2603 ${CPACK_PACKAGE_FILE_NAME}.${CPACK_PACKAGE_CHECKSUM}
2605 Supported algorithms are those listed by the string(<HASH>) com‐
2607 mand.
2608 CPACK_PROJECT_CONFIG_FILE
2610 CPack-time project CPack configuration file. This file is
2611 included at cpack time, once per generator after CPack has set
2612 CPACK_GENERATOR to the actual generator being used. It allows
2613 per-generator setting of CPACK_* variables at cpack time.
2614 CPACK_RESOURCE_FILE_LICENSE
2616 License to be embedded in the installer. It will typically be
2617 displayed to the user by the produced installer (often with an
2618 explicit “Accept” button, for graphical installers) prior to
2619 installation. This license file is NOT added to the installed
2620 files but is used by some CPack generators like NSIS. If you
2621 want to install a license file (may be the same as this one)
2622 along with your project, you must add an appropriate CMake
2623 install() command in your CMakeLists.txt.
2624 CPACK_RESOURCE_FILE_README
2626 ReadMe file to be embedded in the installer. It typically
2627 describes in some detail the purpose of the project during the
2628 installation. Not all CPack generators use this file.
2629 CPACK_RESOURCE_FILE_WELCOME
2631 Welcome file to be embedded in the installer. It welcomes users
2632 to this installer. Typically used in the graphical installers
2633 on Windows and Mac OS X.
2634 CPACK_MONOLITHIC_INSTALL
2636 Disables the component-based installation mechanism. When set,
2637 the component specification is ignored and all installed items
2638 are put in a single “MONOLITHIC” package. Some CPack generators
2639 do monolithic packaging by default and may be asked to do compo‐
2640 nent packaging by setting CPACK_<GENNAME>_COMPONENT_INSTALL to
2641 TRUE.
2642 CPACK_GENERATOR
2644 List of CPack generators to use. If not specified, CPack will
2645 create a set of options following the naming pattern
2646 CPACK_BINARY_<GENNAME> (e.g. CPACK_BINARY_NSIS) allowing the
2647 user to enable/disable individual generators. If the -G option
2648 is given on the cpack command line, it will override this vari‐
2649 able and any CPACK_BINARY_<GENNAME> options.
2650 CPACK_OUTPUT_CONFIG_FILE
2652 The name of the CPack binary configuration file. This file is
2653 the CPack configuration generated by the CPack module for binary
2654 installers. Defaults to CPackConfig.cmake.
2655 CPACK_PACKAGE_EXECUTABLES
2657 Lists each of the executables and associated text label to be
2658 used to create Start Menu shortcuts. For example, setting this
2659 to the list ccmake;CMake will create a shortcut named “CMake”
2660 that will execute the installed executable ccmake. Not all
2661 CPack generators use it (at least NSIS, WIX and OSXX11 do).
2662 CPACK_STRIP_FILES
2664 List of files to be stripped. Starting with CMake 2.6.0,
2665 CPACK_STRIP_FILES will be a boolean variable which enables
2666 stripping of all files (a list of files evaluates to TRUE in
2667 CMake, so this change is compatible).
2668 CPACK_VERBATIM_VARIABLES
2670 If set to TRUE, values of variables prefixed with CPACK_ will be
2671 escaped before being written to the configuration files, so that
2672 the cpack program receives them exactly as they were specified.
2673 If not, characters like quotes and backslashes can cause parsing
2674 errors or alter the value received by the cpack program.
2675 Defaults to FALSE for backwards compatibility.
2676 Variables for Source Package Generators
2678 The following CPack variables are specific to source packages, and will
2679 not affect binary packages:
2680 CPACK_SOURCE_PACKAGE_FILE_NAME
2682 The name of the source package. For example cmake-2.6.1.
2683 CPACK_SOURCE_STRIP_FILES
2685 List of files in the source tree that will be stripped. Start‐
2686 ing with CMake 2.6.0, CPACK_SOURCE_STRIP_FILES will be a boolean
2687 variable which enables stripping of all files (a list of files
2688 evaluates to TRUE in CMake, so this change is compatible).
2689 CPACK_SOURCE_GENERATOR
2691 List of generators used for the source packages. As with
2692 CPACK_GENERATOR, if this is not specified then CPack will create
2693 a set of options (e.g. CPACK_SOURCE_ZIP) allowing users to
2694 select which packages will be generated.
2695 CPACK_SOURCE_OUTPUT_CONFIG_FILE
2697 The name of the CPack source configuration file. This file is
2698 the CPack configuration generated by the CPack module for source
2699 installers. Defaults to CPackSourceConfig.cmake.
2700 CPACK_SOURCE_IGNORE_FILES
2702 Pattern of files in the source tree that won’t be packaged when
2703 building a source package. This is a list of regular expression
2704 patterns (that must be properly escaped), e.g.,
2705 /CVS/;/\\.svn/;\\.swp$;\\.#;/#;.*~;cscope.*
2706 Variables for Advanced Use
2708 The following variables are for advanced uses of CPack:
2709 CPACK_CMAKE_GENERATOR
2711 What CMake generator should be used if the project is a CMake
2712 project. Defaults to the value of CMAKE_GENERATOR. Few users
2713 will want to change this setting.
2714 CPACK_INSTALL_CMAKE_PROJECTS
2716 List of four values that specify what project to install. The
2717 four values are: Build directory, Project Name, Project Compo‐
2718 nent, Directory. If omitted, CPack will build an installer that
2719 installs everything.
2720 CPACK_SYSTEM_NAME
2722 System name, defaults to the value of CMAKE_SYSTEM_NAME, except
2723 on Windows where it will be win32 or win64.
2724 CPACK_PACKAGE_VERSION
2726 Package full version, used internally. By default, this is
2727 built from CPACK_PACKAGE_VERSION_MAJOR,
2728 CPACK_PACKAGE_VERSION_MINOR, and CPACK_PACKAGE_VERSION_PATCH.
2729 CPACK_TOPLEVEL_TAG
2731 Directory for the installed files.
2732 CPACK_INSTALL_COMMANDS
2734 Extra commands to install components. The environment variable
2735 CMAKE_INSTALL_PREFIX is set to the temporary install directory
2736 during execution.
2737 CPACK_INSTALL_SCRIPTS
2739 Extra CMake scripts executed by CPack during its local staging
2740 installation. They are executed before installing the files to
2741 be packaged. The scripts are not called by a standalone install
2742 (e.g.: make install). For every script, the following variables
2743 will be set: CMAKE_CURRENT_SOURCE_DIR, CMAKE_CURRENT_BINARY_DIR
2744 and CMAKE_INSTALL_PREFIX (which is set to the staging install
2745 directory). The singular form CMAKE_INSTALL_SCRIPT is supported
2746 as an alternative variable for historical reasons, but its value
2747 is ignored if CMAKE_INSTALL_SCRIPTS is set and a warning will be
2748 issued.
2749 See also CPACK_PRE_BUILD_SCRIPTS and CPACK_POST_BUILD_SCRIPTS
2751 which can be used to specify scripts to be executed later in the
2752 packaging process.
2753 CPACK_PRE_BUILD_SCRIPTS
2755 List of CMake scripts to execute after CPack has installed the
2756 files to be packaged into a staging directory and before produc‐
2757 ing the package(s) from those files. See also
2758 CPACK_INSTALL_SCRIPTS and CPACK_POST_BUILD_SCRIPTS.
2759 CPACK_POST_BUILD_SCRIPTS
2761 List of CMake scripts to execute after CPack has produced the
2762 resultant packages and before copying them back to the build
2763 directory. See also CPACK_INSTALL_SCRIPTS,
2764 CPACK_PRE_BUILD_SCRIPTS and CPACK_PACKAGE_FILES.
2765 CPACK_PACKAGE_FILES
2767 List of package files created in the staging directory, with
2768 each file provided as a full absolute path. This variable is
2769 populated by CPack just before invoking the post-build scripts
2770 listed in CPACK_POST_BUILD_SCRIPTS. It is the preferred way for
2771 the post-build scripts to know the set of package files to oper‐
2772 ate on. Projects should not try to set this variable them‐
2773 selves.
2774 CPACK_INSTALLED_DIRECTORIES
2776 Extra directories to install.
2777 CPACK_PACKAGE_INSTALL_REGISTRY_KEY
2779 Registry key used when installing this project. This is only
2780 used by installers for Windows. The default value is based on
2781 the installation directory.
2782 CPACK_CREATE_DESKTOP_LINKS
2784 List of desktop links to create. Each desktop link requires a
2785 corresponding start menu shortcut as created by
2786 CPACK_PACKAGE_EXECUTABLES.
2787 CPACK_BINARY_<GENNAME>
2789 CPack generated options for binary generators. The CPack.cmake
2790 module generates (when CPACK_GENERATOR is not set) a set of
2791 CMake options (see CMake option() command) which may then be
2792 used to select the CPack generator(s) to be used when building
2793 the package target or when running cpack without the -G option.
2794 CPackComponent
2796 Configure components for binary installers and source packages.
2797 Introduction
2799 This module is automatically included by CPack.
2800 Certain binary installers (especially the graphical installers) gener‐
2802 ated by CPack allow users to select individual application components
2803 to install. This module allows developers to configure the packaging
2804 of such components.
2805 Contents is assigned to components by the COMPONENT argument of CMake’s
2807 install() command. Components can be annotated with user-friendly
2808 names and descriptions, inter-component dependencies, etc., and grouped
2809 in various ways to customize the resulting installer, using the com‐
2810 mands described below.
2811 To specify different groupings for different CPack generators use a
2813 CPACK_PROJECT_CONFIG_FILE.
2814 Variables
2816 The following variables influence the component-specific packaging:
2817 CPACK_COMPONENTS_ALL
2819 The list of component to install.
2820 The default value of this variable is computed by CPack and con‐
2822 tains all components defined by the project. The user may set
2823 it to only include the specified components.
2824 Instead of specifying all the desired components, it is possible
2826 to obtain a list of all defined components and then remove the
2827 unwanted ones from the list. The get_cmake_property() command
2828 can be used to obtain the COMPONENTS property, then the
2829 list(REMOVE_ITEM) command can be used to remove the unwanted
2830 ones. For example, to use all defined components except foo and
2831 bar:
2832 get_cmake_property(CPACK_COMPONENTS_ALL COMPONENTS)
2834 list(REMOVE_ITEM CPACK_COMPONENTS_ALL "foo" "bar")
2835 CPACK_<GENNAME>_COMPONENT_INSTALL
2837 Enable/Disable component install for CPack generator <GENNAME>.
2838 Each CPack Generator (RPM, DEB, ARCHIVE, NSIS, DMG, etc…) has a
2840 legacy default behavior. e.g. RPM builds monolithic whereas
2841 NSIS builds component. One can change the default behavior by
2842 setting this variable to 0/1 or OFF/ON.
2843 CPACK_COMPONENTS_GROUPING
2845 Specify how components are grouped for multi-package compo‐
2846 nent-aware CPack generators.
2847 Some generators like RPM or ARCHIVE (TGZ, ZIP, …) may generate
2849 several packages files when there are components, depending on
2850 the value of this variable:
2851 · ONE_PER_GROUP (default): create one package per component
2853 group
2854 · IGNORE : create one package per component (ignore the groups)
2856 · ALL_COMPONENTS_IN_ONE : create a single package with all
2858 requested components
2859 CPACK_COMPONENT_<compName>_DISPLAY_NAME
2861 The name to be displayed for a component.
2862 CPACK_COMPONENT_<compName>_DESCRIPTION
2864 The description of a component.
2865 CPACK_COMPONENT_<compName>_GROUP
2867 The group of a component.
2868 CPACK_COMPONENT_<compName>_DEPENDS
2870 The dependencies (list of components) on which this component
2871 depends.
2872 CPACK_COMPONENT_<compName>_HIDDEN
2874 True if this component is hidden from the user.
2875 CPACK_COMPONENT_<compName>_REQUIRED
2877 True if this component is required.
2878 CPACK_COMPONENT_<compName>_DISABLED
2880 True if this component is not selected to be installed by
2881 default.
2882 Commands
2884 Add component
2885 cpack_add_component
2886 Describe an installation component.
2888 cpack_add_component(compname
2890 [DISPLAY_NAME name]
2891 [DESCRIPTION description]
2892 [HIDDEN | REQUIRED | DISABLED ]
2893 [GROUP group]
2894 [DEPENDS comp1 comp2 ... ]
2895 [INSTALL_TYPES type1 type2 ... ]
2896 [DOWNLOADED]
2897 [ARCHIVE_FILE filename]
2898 [PLIST filename])
2899 compname is the name of an installation component, as defined by the
2901 COMPONENT argument of one or more CMake install() commands. With the
2902 cpack_add_component command one can set a name, a description, and
2903 other attributes of an installation component. One can also assign a
2904 component to a component group.
2905 DISPLAY_NAME is the displayed name of the component, used in graphical
2907 installers to display the component name. This value can be any
2908 string.
2909 DESCRIPTION is an extended description of the component, used in graph‐
2911 ical installers to give the user additional information about the com‐
2912 ponent. Descriptions can span multiple lines using \n as the line sep‐
2913 arator. Typically, these descriptions should be no more than a few
2914 lines long.
2915 HIDDEN indicates that this component will be hidden in the graphical
2917 installer, so that the user cannot directly change whether it is
2918 installed or not.
2919 REQUIRED indicates that this component is required, and therefore will
2921 always be installed. It will be visible in the graphical installer,
2922 but it cannot be unselected. (Typically, required components are shown
2923 greyed out).
2924 DISABLED indicates that this component should be disabled (unselected)
2926 by default. The user is free to select this component for installa‐
2927 tion, unless it is also HIDDEN.
2928 DEPENDS lists the components on which this component depends. If this
2930 component is selected, then each of the components listed must also be
2931 selected. The dependency information is encoded within the installer
2932 itself, so that users cannot install inconsistent sets of components.
2933 GROUP names the component group of which this component is a part. If
2935 not provided, the component will be a standalone component, not part of
2936 any component group. Component groups are described with the
2937 cpack_add_component_group command, detailed below.
2938 INSTALL_TYPES lists the installation types of which this component is a
2940 part. When one of these installations types is selected, this compo‐
2941 nent will automatically be selected. Installation types are described
2942 with the cpack_add_install_type command, detailed below.
2943 DOWNLOADED indicates that this component should be downloaded
2945 on-the-fly by the installer, rather than packaged in with the installer
2946 itself. For more information, see the cpack_configure_downloads com‐
2947 mand.
2948 ARCHIVE_FILE provides a name for the archive file created by CPack to
2950 be used for downloaded components. If not supplied, CPack will create
2951 a file with some name based on CPACK_PACKAGE_FILE_NAME and the name of
2952 the component. See cpack_configure_downloads for more information.
2953 PLIST gives a filename that is passed to pkgbuild with the --compo‐
2955 nent-plist argument when using the productbuild generator.
2956 Add component group
2958 cpack_add_component_group
2959 Describes a group of related CPack installation components.
2961 cpack_add_component_group(groupname
2963 [DISPLAY_NAME name]
2964 [DESCRIPTION description]
2965 [PARENT_GROUP parent]
2966 [EXPANDED]
2967 [BOLD_TITLE])
2968 The cpack_add_component_group describes a group of installation compo‐
2970 nents, which will be placed together within the listing of options.
2971 Typically, component groups allow the user to select/deselect all of
2972 the components within a single group via a single group-level option.
2973 Use component groups to reduce the complexity of installers with many
2974 options. groupname is an arbitrary name used to identify the group in
2975 the GROUP argument of the cpack_add_component command, which is used to
2976 place a component in a group. The name of the group must not conflict
2977 with the name of any component.
2978 DISPLAY_NAME is the displayed name of the component group, used in
2980 graphical installers to display the component group name. This value
2981 can be any string.
2982 DESCRIPTION is an extended description of the component group, used in
2984 graphical installers to give the user additional information about the
2985 components within that group. Descriptions can span multiple lines
2986 using \n as the line separator. Typically, these descriptions should
2987 be no more than a few lines long.
2988 PARENT_GROUP, if supplied, names the parent group of this group. Par‐
2990 ent groups are used to establish a hierarchy of groups, providing an
2991 arbitrary hierarchy of groups.
2992 EXPANDED indicates that, by default, the group should show up as
2994 “expanded”, so that the user immediately sees all of the components
2995 within the group. Otherwise, the group will initially show up as a
2996 single entry.
2997 BOLD_TITLE indicates that the group title should appear in bold, to
2999 call the user’s attention to the group.
3000 Add installation type
3002 cpack_add_install_type
3003 Add a new installation type containing a set of predefined component
3005 selections to the graphical installer.
3006 cpack_add_install_type(typename
3008 [DISPLAY_NAME name])
3009 The cpack_add_install_type command identifies a set of preselected com‐
3011 ponents that represents a common use case for an application. For
3012 example, a “Developer” install type might include an application along
3013 with its header and library files, while an “End user” install type
3014 might just include the application’s executable. Each component iden‐
3015 tifies itself with one or more install types via the INSTALL_TYPES
3016 argument to cpack_add_component.
3017 DISPLAY_NAME is the displayed name of the install type, which will typ‐
3019 ically show up in a drop-down box within a graphical installer. This
3020 value can be any string.
3021 Configure downloads
3023 cpack_configure_downloads
3024 Configure CPack to download selected components on-the-fly as part of
3026 the installation process.
3027 cpack_configure_downloads(site
3029 [UPLOAD_DIRECTORY dirname]
3030 [ALL]
3031 [ADD_REMOVE|NO_ADD_REMOVE])
3032 The cpack_configure_downloads command configures installation-time
3034 downloads of selected components. For each downloadable component,
3035 CPack will create an archive containing the contents of that component,
3036 which should be uploaded to the given site. When the user selects that
3037 component for installation, the installer will download and extract the
3038 component in place. This feature is useful for creating small install‐
3039 ers that only download the requested components, saving bandwidth.
3040 Additionally, the installers are small enough that they will be
3041 installed as part of the normal installation process, and the “Change”
3042 button in Windows Add/Remove Programs control panel will allow one to
3043 add or remove parts of the application after the original installation.
3044 On Windows, the downloaded-components functionality requires the ZipDLL
3045 plug-in for NSIS, available at:
3046 http://nsis.sourceforge.net/ZipDLL_plug-in
3048 On macOS, installers that download components on-the-fly can only be
3050 built and installed on system using macOS 10.5 or later.
3051 The site argument is a URL where the archives for downloadable compo‐
3053 nents will reside, e.g., https://cmake.org/files/2.6.1/installer/ All
3054 of the archives produced by CPack should be uploaded to that location.
3055 UPLOAD_DIRECTORY is the local directory where CPack will create the
3057 various archives for each of the components. The contents of this
3058 directory should be uploaded to a location accessible by the URL given
3059 in the site argument. If omitted, CPack will use the directory CPackU‐
3060 ploads inside the CMake binary directory to store the generated ar‐
3061 chives.
3062 The ALL flag indicates that all components be downloaded. Otherwise,
3064 only those components explicitly marked as DOWNLOADED or that have a
3065 specified ARCHIVE_FILE will be downloaded. Additionally, the ALL
3066 option implies ADD_REMOVE (unless NO_ADD_REMOVE is specified).
3067 ADD_REMOVE indicates that CPack should install a copy of the installer
3069 that can be called from Windows’ Add/Remove Programs dialog (via the
3070 “Modify” button) to change the set of installed components.
3071 NO_ADD_REMOVE turns off this behavior. This option is ignored on Mac
3072 OS X.
3073 CPackIFW
3075 New in version 3.1.
3076 This module looks for the location of the command-line utilities sup‐
3079 plied with the Qt Installer Framework (QtIFW).
3080 The module also defines several commands to control the behavior of the
3082 CPack IFW Generator.
3083 Commands
3085 The module defines the following commands:
3086 cpack_ifw_configure_component
3088 Sets the arguments specific to the CPack IFW generator.
3089 cpack_ifw_configure_component(<compname> [COMMON] [ESSENTIAL] [VIRTUAL]
3091 [FORCED_INSTALLATION] [REQUIRES_ADMIN_RIGHTS]
3092 [NAME <name>]
3093 [DISPLAY_NAME <display_name>] # Note: Internationalization supported
3094 [DESCRIPTION <description>] # Note: Internationalization supported
3095 [UPDATE_TEXT <update_text>]
3096 [VERSION <version>]
3097 [RELEASE_DATE <release_date>]
3098 [SCRIPT <script>]
3099 [PRIORITY|SORTING_PRIORITY <sorting_priority>] # Note: PRIORITY is deprecated
3100 [DEPENDS|DEPENDENCIES <com_id> ...]
3101 [AUTO_DEPEND_ON <comp_id> ...]
3102 [LICENSES <display_name> <file_path> ...]
3103 [DEFAULT <value>]
3104 [USER_INTERFACES <file_path> <file_path> ...]
3105 [TRANSLATIONS <file_path> <file_path> ...]
3106 [REPLACES <comp_id> ...]
3107 [CHECKABLE <value>])
3108 This command should be called after cpack_add_component() com‐
3110 mand.
3111 COMMON if set, then the component will be packaged and installed
3113 as part of a group to which it belongs.
3114 ESSENTIAL
3116 if set, then the package manager stays disabled until
3117 that component is updated.
3118 VIRTUAL
3120 if set, then the component will be hidden from the in‐
3121 staller. It is a equivalent of the HIDDEN option from
3122 the cpack_add_component() command.
3123 FORCED_INSTALLATION
3125 if set, then the component must always be installed. It
3126 is a equivalent of the REQUIRED option from the
3127 cpack_add_component() command.
3128 REQUIRES_ADMIN_RIGHTS
3130 set it if the component needs to be installed with ele‐
3131 vated permissions.
3132 NAME is used to create domain-like identification for this
3134 component. By default used origin component name.
3135 DISPLAY_NAME
3137 set to rewrite original name configured by cpack_add_com‐
3138 ponent() command.
3139 DESCRIPTION
3141 set to rewrite original description configured by
3142 cpack_add_component() command.
3143 UPDATE_TEXT
3145 will be added to the component description if this is an
3146 update to the component.
3147 VERSION
3149 is version of component. By default used CPACK_PACK‐
3150 AGE_VERSION.
3151 RELEASE_DATE
3153 keep empty to auto generate.
3154 SCRIPT is a relative or absolute path to operations script for
3156 this component.
3157 PRIORITY | SORTING_PRIORITY
3159 is priority of the component in the tree. The PRIORITY
3160 option is deprecated and will be removed in a future ver‐
3161 sion of CMake. Please use SORTING_PRIORITY option
3162 instead.
3163 DEPENDS | DEPENDENCIES
3165 list of dependency component or component group identi‐
3166 fiers in QtIFW style.
3167 AUTO_DEPEND_ON
3169 list of identifiers of component or component group in
3170 QtIFW style that this component has an automatic depen‐
3171 dency on.
3172 LICENSES
3174 pair of <display_name> and <file_path> of license text
3175 for this component. You can specify more then one
3176 license.
3177 DEFAULT
3179 Possible values are: TRUE, FALSE, and SCRIPT. Set to
3180 FALSE to disable the component in the installer or to
3181 SCRIPT to resolved during runtime (don’t forget add the
3182 file of the script as a value of the SCRIPT option).
3183 USER_INTERFACES
3185 is a list of <file_path> (‘.ui’ files) representing pages
3186 to load.
3187 TRANSLATIONS
3189 is a list of <file_path> (‘.qm’ files) representing
3190 translations to load.
3191 REPLACES
3193 list of identifiers of component or component group to
3194 replace.
3195 CHECKABLE
3197 Possible values are: TRUE, FALSE. Set to FALSE if you
3198 want to hide the checkbox for an item. This is useful
3199 when only a few subcomponents should be selected instead
3200 of all.
3201 cpack_ifw_configure_component_group
3203 Sets the arguments specific to the CPack IFW generator.
3204 cpack_ifw_configure_component_group(<groupname> [VIRTUAL]
3206 [FORCED_INSTALLATION] [REQUIRES_ADMIN_RIGHTS]
3207 [NAME <name>]
3208 [DISPLAY_NAME <display_name>] # Note: Internationalization supported
3209 [DESCRIPTION <description>] # Note: Internationalization supported
3210 [UPDATE_TEXT <update_text>]
3211 [VERSION <version>]
3212 [RELEASE_DATE <release_date>]
3213 [SCRIPT <script>]
3214 [PRIORITY|SORTING_PRIORITY <sorting_priority>] # Note: PRIORITY is deprecated
3215 [DEPENDS|DEPENDENCIES <com_id> ...]
3216 [AUTO_DEPEND_ON <comp_id> ...]
3217 [LICENSES <display_name> <file_path> ...]
3218 [DEFAULT <value>]
3219 [USER_INTERFACES <file_path> <file_path> ...]
3220 [TRANSLATIONS <file_path> <file_path> ...]
3221 [REPLACES <comp_id> ...]
3222 [CHECKABLE <value>])
3223 This command should be called after cpack_add_component_group()
3225 command.
3226 VIRTUAL
3228 if set, then the group will be hidden from the installer.
3229 Note that setting this on a root component does not work.
3230 FORCED_INSTALLATION
3232 if set, then the group must always be installed.
3233 REQUIRES_ADMIN_RIGHTS
3235 set it if the component group needs to be installed with
3236 elevated permissions.
3237 NAME is used to create domain-like identification for this
3239 component group. By default used origin component group
3240 name.
3241 DISPLAY_NAME
3243 set to rewrite original name configured by cpack_add_com‐
3244 ponent_group() command.
3245 DESCRIPTION
3247 set to rewrite original description configured by
3248 cpack_add_component_group() command.
3249 UPDATE_TEXT
3251 will be added to the component group description if this
3252 is an update to the component group.
3253 VERSION
3255 is version of component group. By default used
3256 CPACK_PACKAGE_VERSION.
3257 RELEASE_DATE
3259 keep empty to auto generate.
3260 SCRIPT is a relative or absolute path to operations script for
3262 this component group.
3263 PRIORITY | SORTING_PRIORITY
3265 is priority of the component group in the tree. The PRI‐
3266 ORITY option is deprecated and will be removed in a
3267 future version of CMake. Please use SORTING_PRIORITY
3268 option instead.
3269 DEPENDS | DEPENDENCIES
3271 list of dependency component or component group identi‐
3272 fiers in QtIFW style.
3273 AUTO_DEPEND_ON
3275 list of identifiers of component or component group in
3276 QtIFW style that this component group has an automatic
3277 dependency on.
3278 LICENSES
3280 pair of <display_name> and <file_path> of license text
3281 for this component group. You can specify more then one
3282 license.
3283 DEFAULT
3285 Possible values are: TRUE, FALSE, and SCRIPT. Set to
3286 TRUE to preselect the group in the installer (this takes
3287 effect only on groups that have no visible child compo‐
3288 nents) or to SCRIPT to resolved during runtime (don’t
3289 forget add the file of the script as a value of the
3290 SCRIPT option).
3291 USER_INTERFACES
3293 is a list of <file_path> (‘.ui’ files) representing pages
3294 to load.
3295 TRANSLATIONS
3297 is a list of <file_path> (‘.qm’ files) representing
3298 translations to load.
3299 REPLACES
3301 list of identifiers of component or component group to
3302 replace.
3303 CHECKABLE
3305 Possible values are: TRUE, FALSE. Set to FALSE if you
3306 want to hide the checkbox for an item. This is useful
3307 when only a few subcomponents should be selected instead
3308 of all.
3309 cpack_ifw_add_repository
3311 Add QtIFW specific remote repository to binary installer.
3312 cpack_ifw_add_repository(<reponame> [DISABLED]
3314 URL <url>
3315 [USERNAME <username>]
3316 [PASSWORD <password>]
3317 [DISPLAY_NAME <display_name>])
3318 This command will also add the <reponame> repository to a vari‐
3320 able CPACK_IFW_REPOSITORIES_ALL.
3321 DISABLED
3323 if set, then the repository will be disabled by default.
3324 URL is points to a list of available components.
3326 USERNAME
3328 is used as user on a protected repository.
3329 PASSWORD
3331 is password to use on a protected repository.
3332 DISPLAY_NAME
3334 is string to display instead of the URL.
3335 cpack_ifw_update_repository
3337 Update QtIFW specific repository from remote repository.
3338 cpack_ifw_update_repository(<reponame>
3340 [[ADD|REMOVE] URL <url>]|
3341 [REPLACE OLD_URL <old_url> NEW_URL <new_url>]]
3342 [USERNAME <username>]
3343 [PASSWORD <password>]
3344 [DISPLAY_NAME <display_name>])
3345 This command will also add the <reponame> repository to a vari‐
3347 able CPACK_IFW_REPOSITORIES_ALL.
3348 URL is points to a list of available components.
3350 OLD_URL
3352 is points to a list that will replaced.
3353 NEW_URL
3355 is points to a list that will replace to.
3356 USERNAME
3358 is used as user on a protected repository.
3359 PASSWORD
3361 is password to use on a protected repository.
3362 DISPLAY_NAME
3364 is string to display instead of the URL.
3365 cpack_ifw_add_package_resources
3367 Add additional resources in the installer binary.
3368 cpack_ifw_add_package_resources(<file_path> <file_path> ...)
3370 This command will also add the specified files to a variable
3372 CPACK_IFW_PACKAGE_RESOURCES.
3373 CPackIFWConfigureFile
3375 New in version 3.8.
3376 The module defines configure_file() similar command to configure file
3379 templates prepared in QtIFW/SDK/Creator style.
3380 Commands
3382 The module defines the following commands:
3383 cpack_ifw_configure_file
3385 Copy a file to another location and modify its contents.
3386 cpack_ifw_configure_file(<input> <output>)
3388 Copies an <input> file to an <output> file and substitutes vari‐
3390 able values referenced as %{VAR} or %VAR% in the input file con‐
3391 tent. Each variable reference will be replaced with the current
3392 value of the variable, or the empty string if the variable is
3393 not defined.
3394 CSharpUtilities
3396 New in version 3.8.
3397 Functions to make configuration of CSharp/.NET targets easier.
3400 A collection of CMake utility functions useful for dealing with CSharp
3402 targets for Visual Studio generators from version 2010 and later.
3403 The following functions are provided by this module:
3405 Main functions
3407 · csharp_set_windows_forms_properties()
3409 · csharp_set_designer_cs_properties()
3411 · csharp_set_xaml_cs_properties()
3413 Helper functions
3415 · csharp_get_filename_keys()
3417 · csharp_get_filename_key_base()
3419 · csharp_get_dependentupon_name()
3421 Main functions provided by the module
3423 csharp_set_windows_forms_properties
3424 Sets source file properties for use of Windows Forms. Use this,
3425 if your CSharp target uses Windows Forms:
3426 csharp_set_windows_forms_properties([<file1> [<file2> [...]]])
3428 <fileN>
3430 List of all source files which are relevant for setting
3431 the VS_CSHARP_<tagname> properties (including .cs, .resx
3432 and .Designer.cs extensions).
3433 In the list of all given files for all files ending with
3435 .Designer.cs and .resx is searched. For every designer or
3436 resource file a file with the same base name but only .cs as
3437 extension is searched. If this is found, the VS_CSHARP_<tag‐
3438 name> properties are set as follows:
3439 for the .cs file:
3441 · VS_CSHARP_SubType “Form”
3443 for the .Designer.cs file (if it exists):
3445 · VS_CSHARP_DependentUpon <cs-filename>
3447 · VS_CSHARP_DesignTime “” (delete tag if previously
3449 defined)
3450 · VS_CSHARP_AutoGen “”(delete tag if previously defined)
3452 for the .resx file (if it exists):
3454 · VS_RESOURCE_GENERATOR “” (delete tag if previously
3456 defined)
3457 · VS_CSHARP_DependentUpon <cs-filename>
3459 · VS_CSHARP_SubType “Designer”
3461 csharp_set_designer_cs_properties
3463 Sets source file properties of .Designer.cs files depending on
3464 sibling filenames. Use this, if your CSharp target does not use
3465 Windows Forms (for Windows Forms use
3466 csharp_set_designer_cs_properties() instead):
3467 csharp_set_designer_cs_properties([<file1> [<file2> [...]]])
3469 <fileN>
3471 List of all source files which are relevant for setting
3472 the VS_CSHARP_<tagname> properties (including .cs, .resx,
3473 .settings and .Designer.cs extensions).
3474 In the list of all given files for all files ending with
3476 .Designer.cs is searched. For every designer file all files with
3477 the same base name but different extensions are searched. If a
3478 match is found, the source file properties of the designer file
3479 are set depending on the extension of the matched file:
3480 if match is .resx file:
3482 · VS_CSHARP_AutoGen “True”
3484 · VS_CSHARP_DesignTime “True”
3486 · VS_CSHARP_DependentUpon <resx-filename>
3488 if match is .cs file:
3490 · VS_CSHARP_DependentUpon <cs-filename>
3492 if match is .settings file:
3494 · VS_CSHARP_AutoGen “True”
3496 · VS_CSHARP_DesignTimeSharedInput “True”
3498 · VS_CSHARP_DependentUpon <settings-filename>
3500 NOTE:
3502 Because the source file properties of the .Designer.cs file are set
3503 according to the found matches and every match sets the
3504 VS_CSHARP_DependentUpon property, there should only be one match for
3505 each Designer.cs file.
3506 csharp_set_xaml_cs_properties
3508 Sets source file properties for use of Windows Presentation
3509 Foundation (WPF) and XAML. Use this, if your CSharp target uses
3510 WPF/XAML:
3511 csharp_set_xaml_cs_properties([<file1> [<file2> [...]]])
3513 <fileN>
3515 List of all source files which are relevant for setting
3516 the VS_CSHARP_<tagname> properties (including .cs, .xaml,
3517 and .xaml.cs extensions).
3518 In the list of all given files for all files ending with
3520 .xaml.cs is searched. For every xaml-cs file, a file with the
3521 same base name but extension .xaml is searched. If a match is
3522 found, the source file properties of the .xaml.cs file are set:
3523 · VS_CSHARP_DependentUpon <xaml-filename>
3525 Helper functions which are used by the above ones
3527 csharp_get_filename_keys
3528 Helper function which computes a list of key values to identify
3529 source files independently of relative/absolute paths given in
3530 cmake and eliminates case sensitivity:
3531 csharp_get_filename_keys(OUT [<file1> [<file2> [...]]])
3533 OUT Name of the variable in which the list of keys is stored
3535 <fileN>
3537 filename(s) as given to to CSharp target using
3538 add_library() or add_executable()
3539 In some way the function applies a canonicalization to the
3541 source names. This is necessary to find file matches if the
3542 files have been added to the target with different directory
3543 prefixes:
3544 add_library(lib
3546 myfile.cs
3547 ${CMAKE_CURRENT_SOURCE_DIR}/myfile.Designer.cs)
3548 set_source_files_properties(myfile.Designer.cs PROPERTIES
3550 VS_CSHARP_DependentUpon myfile.cs)
3551 # this will fail, because in cmake
3553 # - ${CMAKE_CURRENT_SOURCE_DIR}/myfile.Designer.cs
3554 # - myfile.Designer.cs
3555 # are not the same source file. The source file property is not set.
3556 csharp_get_filename_key_base
3558 Returns the full filepath and name without extension of a key.
3559 KEY is expected to be a key from csharp_get_filename_keys. In
3560 BASE the value of KEY without the file extension is returned:
3561 csharp_get_filename_key_base(BASE KEY)
3563 BASE Name of the variable with the computed “base” of KEY.
3565 KEY The key of which the base will be computed. Expected to
3567 be a upper case full filename.
3568 csharp_get_dependentupon_name
3570 Computes a string which can be used as value for the source file
3571 property VS_CSHARP_<tagname> with target being DependentUpon:
3572 csharp_get_dependentupon_name(NAME FILE)
3574 NAME Name of the variable with the result value
3576 FILE Filename to convert to <DependentUpon> value
3578 Actually this is only the filename without any path given at the
3580 moment.
3581 CTest
3583 Configure a project for testing with CTest/CDash
3584 Include this module in the top CMakeLists.txt file of a project to
3586 enable testing with CTest and dashboard submissions to CDash:
3587 project(MyProject)
3589 ...
3590 include(CTest)
3591 The module automatically creates a BUILD_TESTING option that selects
3593 whether to enable testing support (ON by default). After including the
3594 module, use code like:
3595 if(BUILD_TESTING)
3597 # ... CMake code to create tests ...
3598 endif()
3599 to creating tests when testing is enabled.
3601 To enable submissions to a CDash server, create a CTestConfig.cmake
3603 file at the top of the project with content such as:
3604 set(CTEST_NIGHTLY_START_TIME "01:00:00 UTC")
3606 set(CTEST_SUBMIT_URL "http://my.cdash.org/submit.php?project=MyProject")
3607 (the CDash server can provide the file to a project administrator who
3609 configures MyProject). Settings in the config file are shared by both
3610 this CTest module and the ctest(1) command-line Dashboard Client mode
3611 (ctest -S).
3612 While building a project for submission to CDash, CTest scans the build
3614 output for errors and warnings and reports them with surrounding con‐
3615 text from the build log. This generic approach works for all build
3616 tools, but does not give details about the command invocation that pro‐
3617 duced a given problem. One may get more detailed reports by setting
3618 the CTEST_USE_LAUNCHERS variable:
3619 set(CTEST_USE_LAUNCHERS 1)
3621 in the CTestConfig.cmake file.
3623 CTestCoverageCollectGCOV
3625 New in version 3.2.
3626 This module provides the ctest_coverage_collect_gcov function.
3629 This function runs gcov on all .gcda files found in the binary tree and
3631 packages the resulting .gcov files into a tar file. This tarball also
3632 contains the following:
3633 · data.json defines the source and build directories for use by CDash.
3635 · Labels.json indicates any LABELS that have been set on the source
3637 files.
3638 · The uncovered directory holds any uncovered files found by
3640 CTEST_EXTRA_COVERAGE_GLOB.
3641 After generating this tar file, it can be sent to CDash for display
3643 with the ctest_submit(CDASH_UPLOAD) command.
3644 ctest_coverage_collect_gcov
3646 ctest_coverage_collect_gcov(TARBALL <tarfile>
3648 [SOURCE <source_dir>][BUILD <build_dir>]
3649 [GCOV_COMMAND <gcov_command>]
3650 [GCOV_OPTIONS <options>...]
3651 )
3652 Run gcov and package a tar file for CDash. The options are:
3654 TARBALL <tarfile>
3656 Specify the location of the .tar file to be created for
3657 later upload to CDash. Relative paths will be inter‐
3658 preted with respect to the top-level build directory.
3659 TARBALL_COMPRESSION <option> Specify a compression algorithm for
3661 the
3662 TARBALL data file. Using this option reduces the size of
3663 the data file before it is submitted to CDash. <option>
3664 must be one of GZIP, BZIP2, XZ, ZSTD, FROM_EXT, or an
3665 expression that CMake evaluates as FALSE. The default
3666 value is BZIP2.
3667 If FROM_EXT is specified, the resulting file will be com‐
3669 pressed based on the file extension of the <tarfile>
3670 (i.e. .tar.gz will use GZIP compression). File extensions
3671 that will produce compressed output include .tar.gz,
3672 .tgz, .tar.bzip2, .tbz, .tar.xz, and .txz.
3673 SOURCE <source_dir>
3675 Specify the top-level source directory for the build.
3676 Default is the value of CTEST_SOURCE_DIRECTORY.
3677 BUILD <build_dir>
3679 Specify the top-level build directory for the build.
3680 Default is the value of CTEST_BINARY_DIRECTORY.
3681 GCOV_COMMAND <gcov_command>
3683 Specify the full path to the gcov command on the machine.
3684 Default is the value of CTEST_COVERAGE_COMMAND.
3685 GCOV_OPTIONS <options>...
3687 Specify options to be passed to gcov. The gcov command
3688 is run as gcov <options>... -o <gcov-dir> <file>.gcda.
3689 If not specified, the default option is just -b -x.
3690 GLOB Recursively search for .gcda files in build_dir rather
3692 than determining search locations by reading TargetDirec‐
3693 tories.txt.
3694 DELETE Delete coverage files after they’ve been packaged into
3696 the .tar.
3697 QUIET Suppress non-error messages that otherwise would have
3699 been printed out by this function.
3700 CTestScriptMode
3702 This file is read by ctest in script mode (-S)
3703 CTestUseLaunchers
3705 Set the RULE_LAUNCH_* global properties when CTEST_USE_LAUNCHERS is on.
3706 CTestUseLaunchers is automatically included when you include(CTest).
3708 However, it is split out into its own module file so projects can use
3709 the CTEST_USE_LAUNCHERS functionality independently.
3710 To use launchers, set CTEST_USE_LAUNCHERS to ON in a ctest -S dashboard
3712 script, and then also set it in the cache of the configured project.
3713 Both cmake and ctest need to know the value of it for the launchers to
3714 work properly. CMake needs to know in order to generate proper build
3715 rules, and ctest, in order to produce the proper error and warning
3716 analysis.
3717 For convenience, you may set the ENV variable CTEST_USE_LAUNCH‐
3719 ERS_DEFAULT in your ctest -S script, too. Then, as long as your CMake‐
3720 Lists uses include(CTest) or include(CTestUseLaunchers), it will use
3721 the value of the ENV variable to initialize a CTEST_USE_LAUNCHERS cache
3722 variable. This cache variable initialization only occurs if
3723 CTEST_USE_LAUNCHERS is not already defined. If CTEST_USE_LAUNCHERS is
3724 on in a ctest -S script the ctest_configure command will add
3725 -DCTEST_USE_LAUNCHERS:BOOL=TRUE to the cmake command used to configure
3726 the project.
3727 Dart
3729 Configure a project for testing with CTest or old Dart Tcl Client
3730 This file is the backwards-compatibility version of the CTest module.
3732 It supports using the old Dart 1 Tcl client for driving dashboard sub‐
3733 missions as well as testing with CTest. This module should be included
3734 in the CMakeLists.txt file at the top of a project. Typical usage:
3735 include(Dart)
3737 if(BUILD_TESTING)
3738 # ... testing related CMake code ...
3739 endif()
3740 The BUILD_TESTING option is created by the Dart module to determine
3742 whether testing support should be enabled. The default is ON.
3743 DeployQt4
3745 Functions to help assemble a standalone Qt4 executable.
3746 A collection of CMake utility functions useful for deploying Qt4 exe‐
3748 cutables.
3749 The following functions are provided by this module:
3751 write_qt4_conf
3753 resolve_qt4_paths
3754 fixup_qt4_executable
3755 install_qt4_plugin_path
3756 install_qt4_plugin
3757 install_qt4_executable
3758 Requires CMake 2.6 or greater because it uses function and PAR‐
3760 ENT_SCOPE. Also depends on BundleUtilities.cmake.
3761 write_qt4_conf(<qt_conf_dir> <qt_conf_contents>)
3763 Writes a qt.conf file with the <qt_conf_contents> into <qt_conf_dir>.
3765 resolve_qt4_paths(<paths_var> [<executable_path>])
3767 Loop through <paths_var> list and if any don’t exist resolve them rela‐
3769 tive to the <executable_path> (if supplied) or the CMAKE_INSTALL_PRE‐
3770 FIX.
3771 fixup_qt4_executable(<executable>
3773 [<qtplugins> <libs> <dirs> <plugins_dir> <request_qt_conf>])
3774 Copies Qt plugins, writes a Qt configuration file (if needed) and fixes
3776 up a Qt4 executable using BundleUtilities so it is standalone and can
3777 be drag-and-drop copied to another machine as long as all of the system
3778 libraries are compatible.
3779 <executable> should point to the executable to be fixed-up.
3781 <qtplugins> should contain a list of the names or paths of any Qt plug‐
3783 ins to be installed.
3784 <libs> will be passed to BundleUtilities and should be a list of any
3786 already installed plugins, libraries or executables to also be
3787 fixed-up.
3788 <dirs> will be passed to BundleUtilities and should contain and direc‐
3790 tories to be searched to find library dependencies.
3791 <plugins_dir> allows an custom plugins directory to be used.
3793 <request_qt_conf> will force a qt.conf file to be written even if not
3795 needed.
3796 install_qt4_plugin_path(plugin executable copy installed_plugin_path_var
3798 <plugins_dir> <component> <configurations>)
3799 Install (or copy) a resolved <plugin> to the default plugins directory
3801 (or <plugins_dir>) relative to <executable> and store the result in
3802 <installed_plugin_path_var>.
3803 If <copy> is set to TRUE then the plugins will be copied rather than
3805 installed. This is to allow this module to be used at CMake time
3806 rather than install time.
3807 If <component> is set then anything installed will use this COMPONENT.
3809 install_qt4_plugin(plugin executable copy installed_plugin_path_var
3811 <plugins_dir> <component>)
3812 Install (or copy) an unresolved <plugin> to the default plugins direc‐
3814 tory (or <plugins_dir>) relative to <executable> and store the result
3815 in <installed_plugin_path_var>. See documentation of INSTALL_QT4_PLUG‐
3816 IN_PATH.
3817 install_qt4_executable(<executable>
3819 [<qtplugins> <libs> <dirs> <plugins_dir> <request_qt_conf> <component>])
3820 Installs Qt plugins, writes a Qt configuration file (if needed) and
3822 fixes up a Qt4 executable using BundleUtilities so it is standalone and
3823 can be drag-and-drop copied to another machine as long as all of the
3824 system libraries are compatible. The executable will be fixed-up at
3825 install time. <component> is the COMPONENT used for bundle fixup and
3826 plugin installation. See documentation of FIXUP_QT4_BUNDLE.
3827 Documentation
3829 This module provides support for the VTK documentation framework. It
3830 relies on several tools (Doxygen, Perl, etc).
3831 ExternalData
3833 Manage data files stored outside source tree
3834 Introduction
3836 Use this module to unambiguously reference data files stored outside
3837 the source tree and fetch them at build time from arbitrary local and
3838 remote content-addressed locations. Functions provided by this module
3839 recognize arguments with the syntax DATA{<name>} as references to
3840 external data, replace them with full paths to local copies of those
3841 data, and create build rules to fetch and update the local copies.
3842 For example:
3844 include(ExternalData)
3846 set(ExternalData_URL_TEMPLATES "file:///local/%(algo)/%(hash)"
3847 "file:////host/share/%(algo)/%(hash)"
3848 "http://data.org/%(algo)/%(hash)")
3849 ExternalData_Add_Test(MyData
3850 NAME MyTest
3851 COMMAND MyExe DATA{MyInput.png}
3852 )
3853 ExternalData_Add_Target(MyData)
3854 When test MyTest runs the DATA{MyInput.png} argument will be replaced
3856 by the full path to a real instance of the data file MyInput.png on
3857 disk. If the source tree contains a content link such as MyIn‐
3858 put.png.md5 then the MyData target creates a real MyInput.png in the
3859 build tree.
3860 Module Functions
3862 ExternalData_Expand_Arguments
3863 The ExternalData_Expand_Arguments function evaluates DATA{} ref‐
3864 erences in its arguments and constructs a new list of arguments:
3865 ExternalData_Expand_Arguments(
3867 <target> # Name of data management target
3868 <outVar> # Output variable
3869 [args...] # Input arguments, DATA{} allowed
3870 )
3871 It replaces each DATA{} reference in an argument with the full
3873 path of a real data file on disk that will exist after the <tar‐
3874 get> builds.
3875 ExternalData_Add_Test
3877 The ExternalData_Add_Test function wraps around the CMake
3878 add_test() command but supports DATA{} references in its argu‐
3879 ments:
3880 ExternalData_Add_Test(
3882 <target> # Name of data management target
3883 ... # Arguments of add_test(), DATA{} allowed
3884 )
3885 It passes its arguments through ExternalData_Expand_Arguments
3887 and then invokes the add_test() command using the results.
3888 ExternalData_Add_Target
3890 The ExternalData_Add_Target function creates a custom target to
3891 manage local instances of data files stored externally:
3892 ExternalData_Add_Target(
3894 <target> # Name of data management target
3895 )
3896 It creates custom commands in the target as necessary to make
3898 data files available for each DATA{} reference previously evalu‐
3899 ated by other functions provided by this module. Data files may
3900 be fetched from one of the URL templates specified in the Exter‐
3901 nalData_URL_TEMPLATES variable, or may be found locally in one
3902 of the paths specified in the ExternalData_OBJECT_STORES vari‐
3903 able.
3904 Typically only one target is needed to manage all external data
3906 within a project. Call this function once at the end of config‐
3907 uration after all data references have been processed.
3908 Module Variables
3910 The following variables configure behavior. They should be set before
3911 calling any of the functions provided by this module.
3912 ExternalData_BINARY_ROOT
3914 The ExternalData_BINARY_ROOT variable may be set to the direc‐
3915 tory to hold the real data files named by expanded DATA{} refer‐
3916 ences. The default is CMAKE_BINARY_DIR. The directory layout
3917 will mirror that of content links under External‐
3918 Data_SOURCE_ROOT.
3919 ExternalData_CUSTOM_SCRIPT_<key>
3921 Specify a full path to a .cmake custom fetch script identified
3922 by <key> in entries of the ExternalData_URL_TEMPLATES list. See
3923 Custom Fetch Scripts.
3924 ExternalData_LINK_CONTENT
3926 The ExternalData_LINK_CONTENT variable may be set to the name of
3927 a supported hash algorithm to enable automatic conversion of
3928 real data files referenced by the DATA{} syntax into content
3929 links. For each such <file> a content link named <file><ext> is
3930 created. The original file is renamed to the form .External‐
3931 Data_<algo>_<hash> to stage it for future transmission to one of
3932 the locations in the list of URL templates (by means outside the
3933 scope of this module). The data fetch rule created for the con‐
3934 tent link will use the staged object if it cannot be found using
3935 any URL template.
3936 ExternalData_NO_SYMLINKS
3938 The real data files named by expanded DATA{} references may be
3939 made available under ExternalData_BINARY_ROOT using symbolic
3940 links on some platforms. The ExternalData_NO_SYMLINKS variable
3941 may be set to disable use of symbolic links and enable use of
3942 copies instead.
3943 ExternalData_OBJECT_STORES
3945 The ExternalData_OBJECT_STORES variable may be set to a list of
3946 local directories that store objects using the layout
3947 <dir>/%(algo)/%(hash). These directories will be searched first
3948 for a needed object. If the object is not available in any
3949 store then it will be fetched remotely using the URL templates
3950 and added to the first local store listed. If no stores are
3951 specified the default is a location inside the build tree.
3952 ExternalData_SERIES_PARSE
3954 ExternalData_SERIES_PARSE_PREFIX
3956 ExternalData_SERIES_PARSE_NUMBER
3958 ExternalData_SERIES_PARSE_SUFFIX
3960 ExternalData_SERIES_MATCH
3962 See Referencing File Series.
3963 ExternalData_SOURCE_ROOT
3965 The ExternalData_SOURCE_ROOT variable may be set to the highest
3966 source directory containing any path named by a DATA{} refer‐
3967 ence. The default is CMAKE_SOURCE_DIR. External‐
3968 Data_SOURCE_ROOT and CMAKE_SOURCE_DIR must refer to directories
3969 within a single source distribution (e.g. they come together in
3970 one tarball).
3971 ExternalData_TIMEOUT_ABSOLUTE
3973 The ExternalData_TIMEOUT_ABSOLUTE variable sets the download
3974 absolute timeout, in seconds, with a default of 300 seconds.
3975 Set to 0 to disable enforcement.
3976 ExternalData_TIMEOUT_INACTIVITY
3978 The ExternalData_TIMEOUT_INACTIVITY variable sets the download
3979 inactivity timeout, in seconds, with a default of 60 seconds.
3980 Set to 0 to disable enforcement.
3981 ExternalData_URL_ALGO_<algo>_<key>
3983 Specify a custom URL component to be substituted for URL tem‐
3984 plate placeholders of the form %(algo:<key>), where <key> is a
3985 valid C identifier, when fetching an object referenced via hash
3986 algorithm <algo>. If not defined, the default URL component is
3987 just <algo> for any <key>.
3988 ExternalData_URL_TEMPLATES
3990 The ExternalData_URL_TEMPLATES may be set to provide a list of
3991 URL templates using the placeholders %(algo) and %(hash) in each
3992 template. Data fetch rules try each URL template in order by
3993 substituting the hash algorithm name for %(algo) and the hash
3994 value for %(hash). Alternatively one may use %(algo:<key>) with
3995 ExternalData_URL_ALGO_<algo>_<key> variables to gain more flexi‐
3996 bility in remote URLs.
3997 Referencing Files
3999 Referencing Single Files
4000 The DATA{} syntax is literal and the <name> is a full or relative path
4001 within the source tree. The source tree must contain either a real
4002 data file at <name> or a “content link” at <name><ext> containing a
4003 hash of the real file using a hash algorithm corresponding to <ext>.
4004 For example, the argument DATA{img.png} may be satisfied by either a
4005 real img.png file in the current source directory or a img.png.md5 file
4006 containing its MD5 sum.
4007 Multiple content links of the same name with different hash algorithms
4009 are supported (e.g. img.png.sha256 and img.png.sha1) so long as they
4010 all correspond to the same real file. This allows objects to be
4011 fetched from sources indexed by different hash algorithms.
4012 Referencing File Series
4014 The DATA{} syntax can be told to fetch a file series using the form
4015 DATA{<name>,:}, where the : is literal. If the source tree contains a
4016 group of files or content links named like a series then a reference to
4017 one member adds rules to fetch all of them. Although all members of a
4018 series are fetched, only the file originally named by the DATA{} argu‐
4019 ment is substituted for it. The default configuration recognizes file
4020 series names ending with #.ext, _#.ext, .#.ext, or -#.ext where # is a
4021 sequence of decimal digits and .ext is any single extension. Configure
4022 it with a regex that parses <number> and <suffix> parts from the end of
4023 <name>:
4024 ExternalData_SERIES_PARSE = regex of the form (<number>)(<suffix>)$
4026 For more complicated cases set:
4028 ExternalData_SERIES_PARSE = regex with at least two () groups
4030 ExternalData_SERIES_PARSE_PREFIX = <prefix> regex group number, if any
4031 ExternalData_SERIES_PARSE_NUMBER = <number> regex group number
4032 ExternalData_SERIES_PARSE_SUFFIX = <suffix> regex group number
4033 Configure series number matching with a regex that matches the <number>
4035 part of series members named <prefix><number><suffix>:
4036 ExternalData_SERIES_MATCH = regex matching <number> in all series members
4038 Note that the <suffix> of a series does not include a hash-algorithm
4040 extension.
4041 Referencing Associated Files
4043 The DATA{} syntax can alternatively match files associated with the
4044 named file and contained in the same directory. Associated files may
4045 be specified by options using the syntax
4046 DATA{<name>,<opt1>,<opt2>,...}. Each option may specify one file by
4047 name or specify a regular expression to match file names using the syn‐
4048 tax REGEX:<regex>. For example, the arguments:
4049 DATA{MyData/MyInput.mhd,MyInput.img} # File pair
4051 DATA{MyData/MyFrames00.png,REGEX:MyFrames[0-9]+\\.png} # Series
4052 will pass MyInput.mha and MyFrames00.png on the command line but ensure
4054 that the associated files are present next to them.
4055 Referencing Directories
4057 The DATA{} syntax may reference a directory using a trailing slash and
4058 a list of associated files. The form DATA{<name>/,<opt1>,<opt2>,...}
4059 adds rules to fetch any files in the directory that match one of the
4060 associated file options. For example, the argument
4061 DATA{MyDataDir/,REGEX:.*} will pass the full path to a MyDataDir direc‐
4062 tory on the command line and ensure that the directory contains files
4063 corresponding to every file or content link in the MyDataDir source
4064 directory. In order to match associated files in subdirectories, spec‐
4065 ify a RECURSE: option, e.g. DATA{MyDataDir/,RECURSE:,REGEX:.*}.
4066 Hash Algorithms
4068 The following hash algorithms are supported:
4069 %(algo) <ext> Description
4071 ------- ----- -----------
4072 MD5 .md5 Message-Digest Algorithm 5, RFC 1321
4073 SHA1 .sha1 US Secure Hash Algorithm 1, RFC 3174
4074 SHA224 .sha224 US Secure Hash Algorithms, RFC 4634
4075 SHA256 .sha256 US Secure Hash Algorithms, RFC 4634
4076 SHA384 .sha384 US Secure Hash Algorithms, RFC 4634
4077 SHA512 .sha512 US Secure Hash Algorithms, RFC 4634
4078 SHA3_224 .sha3-224 Keccak SHA-3
4079 SHA3_256 .sha3-256 Keccak SHA-3
4080 SHA3_384 .sha3-384 Keccak SHA-3
4081 SHA3_512 .sha3-512 Keccak SHA-3
4082 Note that the hashes are used only for unique data identification and
4084 download verification.
4085 Custom Fetch Scripts
4087 When a data file must be fetched from one of the URL templates speci‐
4088 fied in the ExternalData_URL_TEMPLATES variable, it is normally down‐
4089 loaded using the file(DOWNLOAD) command. One may specify usage of a
4090 custom fetch script by using a URL template of the form ExternalData‐
4091 CustomScript://<key>/<loc>. The <key> must be a C identifier, and the
4092 <loc> must contain the %(algo) and %(hash) placeholders. A variable
4093 corresponding to the key, ExternalData_CUSTOM_SCRIPT_<key>, must be set
4094 to the full path to a .cmake script file. The script will be included
4095 to perform the actual fetch, and provided with the following variables:
4096 ExternalData_CUSTOM_LOCATION
4098 When a custom fetch script is loaded, this variable is set to
4099 the location part of the URL, which will contain the substituted
4100 hash algorithm name and content hash value.
4101 ExternalData_CUSTOM_FILE
4103 When a custom fetch script is loaded, this variable is set to
4104 the full path to a file in which the script must store the
4105 fetched content. The name of the file is unspecified and should
4106 not be interpreted in any way.
4107 The custom fetch script is expected to store fetched content in the
4109 file or set a variable:
4110 ExternalData_CUSTOM_ERROR
4112 When a custom fetch script fails to fetch the requested content,
4113 it must set this variable to a short one-line message describing
4114 the reason for failure.
4115 ExternalProject
4117 Commands
4118 External Project Definition
4119 ExternalProject_Add
4120 The ExternalProject_Add() function creates a custom target to
4121 drive download, update/patch, configure, build, install and test
4122 steps of an external project:
4123 ExternalProject_Add(<name> [<option>...])
4125 The individual steps within the process can be driven indepen‐
4127 dently if required (e.g. for CDash submission) and extra custom
4128 steps can be defined, along with the ability to control the step
4129 dependencies. The directory structure used for the management of
4130 the external project can also be customized. The function sup‐
4131 ports a large number of options which can be used to tailor the
4132 external project behavior.
4133 Directory Options:
4135 Most of the time, the default directory layout is suffi‐
4136 cient. It is largely an implementation detail that the
4137 main project usually doesn’t need to change. In some cir‐
4138 cumstances, however, control over the directory layout
4139 can be useful or necessary. The directory options are
4140 potentially more useful from the point of view that the
4141 main build can use the ExternalProject_Get_Property()
4142 command to retrieve their values, thereby allowing the
4143 main project to refer to build artifacts of the external
4144 project.
4145 PREFIX <dir>
4147 Root directory for the external project. Unless
4148 otherwise noted below, all other directories asso‐
4149 ciated with the external project will be created
4150 under here.
4151 TMP_DIR <dir>
4153 Directory in which to store temporary files.
4154 STAMP_DIR <dir>
4156 Directory in which to store the timestamps of each
4157 step. Log files from individual steps are also
4158 created in here unless overridden by LOG_DIR (see
4159 Logging Options below).
4160 LOG_DIR <dir>
4162 Directory in which to store the logs of each step.
4163 DOWNLOAD_DIR <dir>
4165 Directory in which to store downloaded files
4166 before unpacking them. This directory is only used
4167 by the URL download method, all other download
4168 methods use SOURCE_DIR directly instead.
4169 SOURCE_DIR <dir>
4171 Source directory into which downloaded contents
4172 will be unpacked, or for non-URL download methods,
4173 the directory in which the repository should be
4174 checked out, cloned, etc. If no download method is
4175 specified, this must point to an existing direc‐
4176 tory where the external project has already been
4177 unpacked or cloned/checked out.
4178 NOTE:
4180 If a download method is specified, any existing
4181 contents of the source directory may be
4182 deleted. Only the URL download method checks
4183 whether this directory is either missing or
4184 empty before initiating the download, stopping
4185 with an error if it is not empty. All other
4186 download methods silently discard any previous
4187 contents of the source directory.
4188 BINARY_DIR <dir>
4190 Specify the build directory location. This option
4191 is ignored if BUILD_IN_SOURCE is enabled.
4192 INSTALL_DIR <dir>
4194 Installation prefix to be placed in the
4195 <INSTALL_DIR> placeholder. This does not actually
4196 configure the external project to install to the
4197 given prefix. That must be done by passing appro‐
4198 priate arguments to the external project configu‐
4199 ration step, e.g. using <INSTALL_DIR>.
4200 If any of the above ..._DIR options are not specified,
4202 their defaults are computed as follows. If the PREFIX
4203 option is given or the EP_PREFIX directory property is
4204 set, then an external project is built and installed
4205 under the specified prefix:
4206 TMP_DIR = <prefix>/tmp
4208 STAMP_DIR = <prefix>/src/<name>-stamp
4209 DOWNLOAD_DIR = <prefix>/src
4210 SOURCE_DIR = <prefix>/src/<name>
4211 BINARY_DIR = <prefix>/src/<name>-build
4212 INSTALL_DIR = <prefix>
4213 LOG_DIR = <STAMP_DIR>
4214 Otherwise, if the EP_BASE directory property is set then
4216 components of an external project are stored under the
4217 specified base:
4218 TMP_DIR = <base>/tmp/<name>
4220 STAMP_DIR = <base>/Stamp/<name>
4221 DOWNLOAD_DIR = <base>/Download/<name>
4222 SOURCE_DIR = <base>/Source/<name>
4223 BINARY_DIR = <base>/Build/<name>
4224 INSTALL_DIR = <base>/Install/<name>
4225 LOG_DIR = <STAMP_DIR>
4226 If no PREFIX, EP_PREFIX, or EP_BASE is specified, then
4228 the default is to set PREFIX to <name>-prefix. Relative
4229 paths are interpreted with respect to CMAKE_CUR‐
4230 RENT_BINARY_DIR at the point where ExternalProject_Add()
4231 is called.
4232 Download Step Options:
4234 A download method can be omitted if the SOURCE_DIR option
4235 is used to point to an existing non-empty directory. Oth‐
4236 erwise, one of the download methods below must be speci‐
4237 fied (multiple download methods should not be given) or a
4238 custom DOWNLOAD_COMMAND provided.
4239 DOWNLOAD_COMMAND <cmd>...
4241 Overrides the command used for the download step
4242 (generator expressions are supported). If this
4243 option is specified, all other download options
4244 will be ignored. Providing an empty string for
4245 <cmd> effectively disables the download step.
4246 URL Download
4248 URL <url1> [<url2>...]
4250 List of paths and/or URL(s) of the external
4251 project’s source. When more than one URL is
4252 given, they are tried in turn until one
4253 succeeds. A URL may be an ordinary path in
4254 the local file system (in which case it
4255 must be the only URL provided) or any down‐
4256 loadable URL supported by the file(DOWN‐
4257 LOAD) command. A local filesystem path may
4258 refer to either an existing directory or to
4259 an archive file, whereas a URL is expected
4260 to point to a file which can be treated as
4261 an archive. When an archive is used, it
4262 will be unpacked automatically unless the
4263 DOWNLOAD_NO_EXTRACT option is set to pre‐
4264 vent it. The archive type is determined by
4265 inspecting the actual content rather than
4266 using logic based on the file extension.
4267 URL_HASH <algo>=<hashValue>
4269 Hash of the archive file to be downloaded.
4270 The argument should be of the form
4271 <algo>=<hashValue> where algo can be any of
4272 the hashing algorithms supported by the
4273 file() command. Specifying this option is
4274 strongly recommended for URL downloads, as
4275 it ensures the integrity of the downloaded
4276 content. It is also used as a check for a
4277 previously downloaded file, allowing con‐
4278 nection to the remote location to be
4279 avoided altogether if the local directory
4280 already has a file from an earlier download
4281 that matches the specified hash.
4282 URL_MD5 <md5>
4284 Equivalent to URL_HASH MD5=<md5>.
4285 DOWNLOAD_NAME <fname>
4287 File name to use for the downloaded file.
4288 If not given, the end of the URL is used to
4289 determine the file name. This option is
4290 rarely needed, the default name is gener‐
4291 ally suitable and is not normally used out‐
4292 side of code internal to the ExternalPro‐
4293 ject module.
4294 DOWNLOAD_NO_EXTRACT <bool>
4296 Allows the extraction part of the download
4297 step to be disabled by passing a boolean
4298 true value for this option. If this option
4299 is not given, the downloaded contents will
4300 be unpacked automatically if required. If
4301 extraction has been disabled, the full path
4302 to the downloaded file is available as
4303 <DOWNLOADED_FILE> in subsequent steps or as
4304 the property DOWNLOADED_FILE with the
4305 ExternalProject_Get_Property() command.
4306 DOWNLOAD_NO_PROGRESS <bool>
4308 Can be used to disable logging the download
4309 progress. If this option is not given,
4310 download progress messages will be logged.
4311 TIMEOUT <seconds>
4313 Maximum time allowed for file download
4314 operations.
4315 INACTIVITY_TIMEOUT <seconds>
4317 Terminate the operation after a period of
4318 inactivity.
4319 HTTP_USERNAME <username>
4321 Username for the download operation if
4322 authentication is required.
4323 HTTP_PASSWORD <password>
4325 Password for the download operation if
4326 authentication is required.
4327 HTTP_HEADER <header1> [<header2>...]
4329 Provides an arbitrary list of HTTP headers
4330 for the download operation. This can be
4331 useful for accessing content in systems
4332 like AWS, etc.
4333 TLS_VERIFY <bool>
4335 Specifies whether certificate verification
4336 should be performed for https URLs. If this
4337 option is not provided, the default behav‐
4338 ior is determined by the CMAKE_TLS_VERIFY
4339 variable (see file(DOWNLOAD)). If that is
4340 also not set, certificate verification will
4341 not be performed. In situations where
4342 URL_HASH cannot be provided, this option
4343 can be an alternative verification measure.
4344 TLS_CAINFO <file>
4346 Specify a custom certificate authority file
4347 to use if TLS_VERIFY is enabled. If this
4348 option is not specified, the value of the
4349 CMAKE_TLS_CAINFO variable will be used
4350 instead (see file(DOWNLOAD))
4351 NETRC <level>
4353 Specify whether the .netrc file is to be
4354 used for operation. If this option is not
4355 specified, the value of the CMAKE_NETRC
4356 variable will be used instead (see
4357 file(DOWNLOAD)) Valid levels are:
4358 IGNORED
4360 The .netrc file is ignored. This is
4361 the default.
4362 OPTIONAL
4364 The .netrc file is optional, and
4365 information in the URL is preferred.
4366 The file will be scanned to find
4367 which ever information is not speci‐
4368 fied in the URL.
4369 REQUIRED
4371 The .netrc file is required, and
4372 information in the URL is ignored.
4373 NETRC_FILE <file>
4375 Specify an alternative .netrc file to the
4376 one in your home directory if the NETRC
4377 level is OPTIONAL or REQUIRED. If this
4378 option is not specified, the value of the
4379 CMAKE_NETRC_FILE variable will be used
4380 instead (see file(DOWNLOAD))
4381 Git NOTE: A git version of 1.6.5 or later is required
4383 if this download method is used.
4384 GIT_REPOSITORY <url>
4386 URL of the git repository. Any URL under‐
4387 stood by the git command may be used.
4388 GIT_TAG <tag>
4390 Git branch name, tag or commit hash. Note
4391 that branch names and tags should generally
4392 be specified as remote names (i.e. ori‐
4393 gin/myBranch rather than simply myBranch).
4394 This ensures that if the remote end has its
4395 tag moved or branch rebased or history
4396 rewritten, the local clone will still be
4397 updated correctly. In general, however,
4398 specifying a commit hash should be pre‐
4399 ferred for a number of reasons:
4400 · If the local clone already has the commit
4402 corresponding to the hash, no git fetch
4403 needs to be performed to check for
4404 changes each time CMake is re-run. This
4405 can result in a significant speed up if
4406 many external projects are being used.
4407 · Using a specific git hash ensures that
4409 the main project’s own history is fully
4410 traceable to a specific point in the
4411 external project’s evolution. If a branch
4412 or tag name is used instead, then check‐
4413 ing out a specific commit of the main
4414 project doesn’t necessarily pin the whole
4415 build to a specific point in the life of
4416 the external project. The lack of such
4417 deterministic behavior makes the main
4418 project lose traceability and repeatabil‐
4419 ity.
4420 If GIT_SHALLOW is enabled then GIT_TAG
4422 works only with branch names and tags. A
4423 commit hash is not allowed.
4424 GIT_REMOTE_NAME <name>
4426 The optional name of the remote. If this
4427 option is not specified, it defaults to
4428 origin.
4429 GIT_SUBMODULES <module>...
4431 Specific git submodules that should also be
4432 updated. If this option is not provided,
4433 all git submodules will be updated. When
4434 CMP0097 is set to NEW if this value is set
4435 to an empty string then no submodules are
4436 initialized or updated.
4437 GIT_SUBMODULES_RECURSE <bool>
4439 Specify whether git submodules (if any)
4440 should update recursively by passing the
4441 --recursive flag to git submodule update.
4442 If not specified, the default is on.
4443 GIT_SHALLOW <bool>
4445 When this option is enabled, the git clone
4446 operation will be given the --depth 1
4447 option. This performs a shallow clone,
4448 which avoids downloading the whole history
4449 and instead retrieves just the commit
4450 denoted by the GIT_TAG option.
4451 GIT_PROGRESS <bool>
4453 When enabled, this option instructs the git
4454 clone operation to report its progress by
4455 passing it the --progress option. Without
4456 this option, the clone step for large
4457 projects may appear to make the build
4458 stall, since nothing will be logged until
4459 the clone operation finishes. While this
4460 option can be used to provide progress to
4461 prevent the appearance of the build having
4462 stalled, it may also make the build overly
4463 noisy if lots of external projects are
4464 used.
4465 GIT_CONFIG <option1> [<option2>...]
4467 Specify a list of config options to pass to
4468 git clone. Each option listed will be
4469 transformed into its own --config <option>
4470 on the git clone command line, with each
4471 option required to be in the form
4472 key=value.
4473 GIT_REMOTE_UPDATE_STRATEGY <strategy>
4475 When GIT_TAG refers to a remote branch,
4476 this option can be used to specify how the
4477 update step behaves. The <strategy> must
4478 be one of the following:
4479 CHECKOUT
4481 Ignore the local branch and always
4482 checkout the branch specified by
4483 GIT_TAG.
4484 REBASE Try to rebase the current branch to
4486 the one specified by GIT_TAG. If
4487 there are local uncommitted changes,
4488 they will be stashed first and
4489 popped again after rebasing. If
4490 rebasing or popping stashed changes
4491 fail, abort the rebase and halt with
4492 an error. When
4493 GIT_REMOTE_UPDATE_STRATEGY is not
4494 present, this is the default strat‐
4495 egy unless the default has been
4496 overridden with
4497 CMAKE_EP_GIT_REMOTE_UPDATE_STRATEGY
4498 (see below).
4499 REBASE_CHECKOUT
4501 Same as REBASE except if the rebase
4502 fails, an annotated tag will be cre‐
4503 ated at the original HEAD position
4504 from before the rebase and then
4505 checkout GIT_TAG just like the
4506 CHECKOUT strategy. The message
4507 stored on the annotated tag will
4508 give information about what was
4509 attempted and the tag name will
4510 include a timestamp so that each
4511 failed run will add a new tag. This
4512 strategy ensures no changes will be
4513 lost, but updates should always suc‐
4514 ceed if GIT_TAG refers to a valid
4515 ref unless there are uncommitted
4516 changes that cannot be popped suc‐
4517 cessfully.
4518 The variable
4520 CMAKE_EP_GIT_REMOTE_UPDATE_STRATEGY can be
4521 set to override the default strategy. This
4522 variable should not be set by a project, it
4523 is intended for the user to set. It is
4524 primarily intended for use in continuous
4525 integration scripts to ensure that when
4526 history is rewritten on a remote branch,
4527 the build doesn’t end up with unintended
4528 changes or failed builds resulting from
4529 conflicts during rebase operations.
4530 Subversion
4532 SVN_REPOSITORY <url>
4534 URL of the Subversion repository.
4535 SVN_REVISION -r<rev>
4537 Revision to checkout from the Subversion
4538 repository.
4539 SVN_USERNAME <username>
4541 Username for the Subversion checkout and
4542 update.
4543 SVN_PASSWORD <password>
4545 Password for the Subversion checkout and
4546 update.
4547 SVN_TRUST_CERT <bool>
4549 Specifies whether to trust the Subversion
4550 server site certificate. If enabled, the
4551 --trust-server-cert option is passed to the
4552 svn checkout and update commands.
4553 Mercurial
4555 HG_REPOSITORY <url>
4557 URL of the mercurial repository.
4558 HG_TAG <tag>
4560 Mercurial branch name, tag or commit id.
4561 CVS
4563 CVS_REPOSITORY <cvsroot>
4565 CVSROOT of the CVS repository.
4566 CVS_MODULE <mod>
4568 Module to checkout from the CVS repository.
4569 CVS_TAG <tag>
4571 Tag to checkout from the CVS repository.
4572 Update/Patch Step Options:
4574 Whenever CMake is re-run, by default the external
4575 project’s sources will be updated if the download method
4576 supports updates (e.g. a git repository would be checked
4577 if the GIT_TAG does not refer to a specific commit).
4578 UPDATE_COMMAND <cmd>...
4580 Overrides the download method’s update step with a
4581 custom command. The command may use generator
4582 expressions.
4583 UPDATE_DISCONNECTED <bool>
4585 When enabled, this option causes the update step
4586 to be skipped. It does not, however, prevent the
4587 download step. The update step can still be added
4588 as a step target (see
4589 ExternalProject_Add_StepTargets()) and called man‐
4590 ually. This is useful if you want to allow devel‐
4591 opers to build the project when disconnected from
4592 the network (the network may still be needed for
4593 the download step though).
4594 When this option is present, it is generally
4596 advisable to make the value a cache variable under
4597 the developer’s control rather than hard-coding
4598 it. If this option is not present, the default
4599 value is taken from the EP_UPDATE_DISCONNECTED
4600 directory property. If that is also not defined,
4601 updates are performed as normal. The
4602 EP_UPDATE_DISCONNECTED directory property is
4603 intended as a convenience for controlling the
4604 UPDATE_DISCONNECTED behavior for an entire section
4605 of a project’s directory hierarchy and may be a
4606 more convenient method of giving developers con‐
4607 trol over whether or not to perform updates
4608 (assuming the project also provides a cache vari‐
4609 able or some other convenient method for setting
4610 the directory property).
4611 This may cause a step target to be created auto‐
4613 matically for the download step. See policy
4614 CMP0114.
4615 PATCH_COMMAND <cmd>...
4617 Specifies a custom command to patch the sources
4618 after an update. By default, no patch command is
4619 defined. Note that it can be quite difficult to
4620 define an appropriate patch command that performs
4621 robustly, especially for download methods such as
4622 git where changing the GIT_TAG will not discard
4623 changes from a previous patch, but the patch com‐
4624 mand will be called again after updating to the
4625 new tag.
4626 Configure Step Options:
4628 The configure step is run after the download and update
4629 steps. By default, the external project is assumed to be
4630 a CMake project, but this can be overridden if required.
4631 CONFIGURE_COMMAND <cmd>...
4633 The default configure command runs CMake with
4634 options based on the main project. For non-CMake
4635 external projects, the CONFIGURE_COMMAND option
4636 must be used to override this behavior (generator
4637 expressions are supported). For projects that
4638 require no configure step, specify this option
4639 with an empty string as the command to execute.
4640 CMAKE_COMMAND /.../cmake
4642 Specify an alternative cmake executable for the
4643 configure step (use an absolute path). This is
4644 generally not recommended, since it is usually
4645 desirable to use the same CMake version throughout
4646 the whole build. This option is ignored if a cus‐
4647 tom configure command has been specified with CON‐
4648 FIGURE_COMMAND.
4649 CMAKE_GENERATOR <gen>
4651 Override the CMake generator used for the config‐
4652 ure step. Without this option, the same generator
4653 as the main build will be used. This option is
4654 ignored if a custom configure command has been
4655 specified with the CONFIGURE_COMMAND option.
4656 CMAKE_GENERATOR_PLATFORM <platform>
4658 Pass a generator-specific platform name to the
4659 CMake command (see CMAKE_GENERATOR_PLATFORM). It
4660 is an error to provide this option without the
4661 CMAKE_GENERATOR option.
4662 CMAKE_GENERATOR_TOOLSET <toolset>
4664 Pass a generator-specific toolset name to the
4665 CMake command (see CMAKE_GENERATOR_TOOLSET). It is
4666 an error to provide this option without the
4667 CMAKE_GENERATOR option.
4668 CMAKE_GENERATOR_INSTANCE <instance>
4670 Pass a generator-specific instance selection to
4671 the CMake command (see CMAKE_GENERATOR_INSTANCE).
4672 It is an error to provide this option without the
4673 CMAKE_GENERATOR option.
4674 CMAKE_ARGS <arg>...
4676 The specified arguments are passed to the cmake
4677 command line. They can be any argument the cmake
4678 command understands, not just cache values defined
4679 by -D... arguments (see also CMake Options). In
4680 addition, arguments may use generator expressions.
4681 CMAKE_CACHE_ARGS <arg>...
4683 This is an alternate way of specifying cache vari‐
4684 ables where command line length issues may become
4685 a problem. The arguments are expected to be in the
4686 form -Dvar:STRING=value, which are then trans‐
4687 formed into CMake set() commands with the FORCE
4688 option used. These set() commands are written to a
4689 pre-load script which is then applied using the
4690 cmake -C command line option. Arguments may use
4691 generator expressions.
4692 CMAKE_CACHE_DEFAULT_ARGS <arg>...
4694 This is the same as the CMAKE_CACHE_ARGS option
4695 except the set() commands do not include the FORCE
4696 keyword. This means the values act as initial
4697 defaults only and will not override any variables
4698 already set from a previous run. Use this option
4699 with care, as it can lead to different behavior
4700 depending on whether the build starts from a fresh
4701 build directory or re-uses previous build con‐
4702 tents.
4703 If the CMake generator is the Green Hills MULTI
4705 and not overridden then the original project’s
4706 settings for the GHS toolset and target system
4707 customization cache variables are propagated into
4708 the external project.
4709 SOURCE_SUBDIR <dir>
4711 When no CONFIGURE_COMMAND option is specified, the
4712 configure step assumes the external project has a
4713 CMakeLists.txt file at the top of its source tree
4714 (i.e. in SOURCE_DIR). The SOURCE_SUBDIR option can
4715 be used to point to an alternative directory
4716 within the source tree to use as the top of the
4717 CMake source tree instead. This must be a relative
4718 path and it will be interpreted as being relative
4719 to SOURCE_DIR. When BUILD_IN_SOURCE 1 is speci‐
4720 fied, the BUILD_COMMAND is used to point to an
4721 alternative directory within the source tree.
4722 Build Step Options:
4724 If the configure step assumed the external project uses
4725 CMake as its build system, the build step will also. Oth‐
4726 erwise, the build step will assume a Makefile-based build
4727 and simply run make with no arguments as the default
4728 build step. This can be overridden with custom build com‐
4729 mands if required.
4730 BUILD_COMMAND <cmd>...
4732 Overrides the default build command (generator
4733 expressions are supported). If this option is not
4734 given, the default build command will be chosen to
4735 integrate with the main build in the most appro‐
4736 priate way (e.g. using recursive make for Makefile
4737 generators or cmake --build if the project uses a
4738 CMake build). This option can be specified with an
4739 empty string as the command to make the build step
4740 do nothing.
4741 BUILD_IN_SOURCE <bool>
4743 When this option is enabled, the build will be
4744 done directly within the external project’s source
4745 tree. This should generally be avoided, the use of
4746 a separate build directory is usually preferred,
4747 but it can be useful when the external project
4748 assumes an in-source build. The BINARY_DIR option
4749 should not be specified if building in-source.
4750 BUILD_ALWAYS <bool>
4752 Enabling this option forces the build step to
4753 always be run. This can be the easiest way to
4754 robustly ensure that the external project’s own
4755 build dependencies are evaluated rather than rely‐
4756 ing on the default success timestamp-based method.
4757 This option is not normally needed unless develop‐
4758 ers are expected to modify something the external
4759 project’s build depends on in a way that is not
4760 detectable via the step target dependencies (e.g.
4761 SOURCE_DIR is used without a download method and
4762 developers might modify the sources in
4763 SOURCE_DIR).
4764 BUILD_BYPRODUCTS <file>...
4766 Specifies files that will be generated by the
4767 build command but which might or might not have
4768 their modification time updated by subsequent
4769 builds. These ultimately get passed through as
4770 BYPRODUCTS to the build step’s own underlying call
4771 to add_custom_command().
4772 Install Step Options:
4774 If the configure step assumed the external project uses
4775 CMake as its build system, the install step will also.
4776 Otherwise, the install step will assume a Makefile-based
4777 build and simply run make install as the default build
4778 step. This can be overridden with custom install commands
4779 if required.
4780 INSTALL_COMMAND <cmd>...
4782 The external project’s own install step is invoked
4783 as part of the main project’s build. It is done
4784 after the external project’s build step and may be
4785 before or after the external project’s test step
4786 (see the TEST_BEFORE_INSTALL option below). The
4787 external project’s install rules are not part of
4788 the main project’s install rules, so if anything
4789 from the external project should be installed as
4790 part of the main build, these need to be specified
4791 in the main build as additional install() com‐
4792 mands. The default install step builds the install
4793 target of the external project, but this can be
4794 overridden with a custom command using this option
4795 (generator expressions are supported). Passing an
4796 empty string as the <cmd> makes the install step
4797 do nothing.
4798 Test Step Options:
4800 The test step is only defined if at least one of the fol‐
4801 lowing TEST_... options are provided.
4802 TEST_COMMAND <cmd>...
4804 Overrides the default test command (generator
4805 expressions are supported). If this option is not
4806 given, the default behavior of the test step is to
4807 build the external project’s own test target. This
4808 option can be specified with <cmd> as an empty
4809 string, which allows the test step to still be
4810 defined, but it will do nothing. Do not specify
4811 any of the other TEST_... options if providing an
4812 empty string as the test command, but prefer to
4813 omit all TEST_... options altogether if the test
4814 step target is not needed.
4815 TEST_BEFORE_INSTALL <bool>
4817 When this option is enabled, the test step will be
4818 executed before the install step. The default
4819 behavior is for the test step to run after the
4820 install step.
4821 TEST_AFTER_INSTALL <bool>
4823 This option is mainly useful as a way to indicate
4824 that the test step is desired but all default
4825 behavior is sufficient. Specifying this option
4826 with a boolean true value ensures the test step is
4827 defined and that it comes after the install step.
4828 If both TEST_BEFORE_INSTALL and TEST_AFTER_INSTALL
4829 are enabled, the latter is silently ignored.
4830 TEST_EXCLUDE_FROM_MAIN <bool>
4832 If enabled, the main build’s default ALL target
4833 will not depend on the test step. This can be a
4834 useful way of ensuring the test step is defined
4835 but only gets invoked when manually requested.
4836 This may cause a step target to be created auto‐
4837 matically for either the install or build step.
4838 See policy CMP0114.
4839 Output Logging Options:
4841 Each of the following LOG_... options can be used to wrap
4842 the relevant step in a script to capture its output to
4843 files. The log files will be created in LOG_DIR if sup‐
4844 plied or otherwise the STAMP_DIR directory with step-spe‐
4845 cific file names.
4846 LOG_DOWNLOAD <bool>
4848 When enabled, the output of the download step is
4849 logged to files.
4850 LOG_UPDATE <bool>
4852 When enabled, the output of the update step is
4853 logged to files.
4854 LOG_PATCH <bool>
4856 When enabled, the output of the patch step is
4857 logged to files.
4858 LOG_CONFIGURE <bool>
4860 When enabled, the output of the configure step is
4861 logged to files.
4862 LOG_BUILD <bool>
4864 When enabled, the output of the build step is
4865 logged to files.
4866 LOG_INSTALL <bool>
4868 When enabled, the output of the install step is
4869 logged to files.
4870 LOG_TEST <bool>
4872 When enabled, the output of the test step is
4873 logged to files.
4874 LOG_MERGED_STDOUTERR <bool>
4876 When enabled, stdout and stderr will be merged for
4877 any step whose output is being logged to files.
4878 LOG_OUTPUT_ON_FAILURE <bool>
4880 This option only has an effect if at least one of
4881 the other LOG_<step> options is enabled. If an
4882 error occurs for a step which has logging to file
4883 enabled, that step’s output will be printed to the
4884 console if LOG_OUTPUT_ON_FAILURE is set to true.
4885 For cases where a large amount of output is
4886 recorded, just the end of that output may be
4887 printed to the console.
4888 Terminal Access Options:
4890 Steps can be given direct access to the terminal in some
4891 cases. Giving a step access to the terminal may allow it
4892 to receive terminal input if required, such as for
4893 authentication details not provided by other options.
4894 With the Ninja generator, these options place the steps
4895 in the console job pool. Each step can be given access to
4896 the terminal individually via the following options:
4897 USES_TERMINAL_DOWNLOAD <bool>
4899 Give the download step access to the terminal.
4900 USES_TERMINAL_UPDATE <bool>
4902 Give the update step access to the terminal.
4903 USES_TERMINAL_CONFIGURE <bool>
4905 Give the configure step access to the terminal.
4906 USES_TERMINAL_BUILD <bool>
4908 Give the build step access to the terminal.
4909 USES_TERMINAL_INSTALL <bool>
4911 Give the install step access to the terminal.
4912 USES_TERMINAL_TEST <bool>
4914 Give the test step access to the terminal.
4915 Target Options:
4917 DEPENDS <targets>...
4919 Specify other targets on which the external
4920 project depends. The other targets will be brought
4921 up to date before any of the external project’s
4922 steps are executed. Because the external project
4923 uses additional custom targets internally for each
4924 step, the DEPENDS option is the most convenient
4925 way to ensure all of those steps depend on the
4926 other targets. Simply doing add_dependen‐
4927 cies(<name> <targets>) will not make any of the
4928 steps dependent on <targets>.
4929 EXCLUDE_FROM_ALL <bool>
4931 When enabled, this option excludes the external
4932 project from the default ALL target of the main
4933 build.
4934 STEP_TARGETS <step-target>...
4936 Generate custom targets for the specified steps.
4937 This is required if the steps need to be triggered
4938 manually or if they need to be used as dependen‐
4939 cies of other targets. If this option is not spec‐
4940 ified, the default value is taken from the
4941 EP_STEP_TARGETS directory property. See
4942 ExternalProject_Add_StepTargets() below for fur‐
4943 ther discussion of the effects of this option.
4944 INDEPENDENT_STEP_TARGETS <step-target>...
4946 Deprecated. This is allowed only if policy
4947 CMP0114 is not set to NEW. Generates custom tar‐
4948 gets for the specified steps and prevent these
4949 targets from having the usual dependencies applied
4950 to them. If this option is not specified, the
4951 default value is taken from the EP_INDEPEN‐
4952 DENT_STEP_TARGETS directory property. This option
4953 is mostly useful for allowing individual steps to
4954 be driven independently, such as for a CDash setup
4955 where each step should be initiated and reported
4956 individually rather than as one whole build. See
4957 ExternalProject_Add_StepTargets() below for fur‐
4958 ther discussion of the effects of this option.
4959 Miscellaneous Options:
4961 LIST_SEPARATOR <sep>
4963 For any of the various ..._COMMAND options,
4964 replace ; with <sep> in the specified command
4965 lines. This can be useful where list variables may
4966 be given in commands where they should end up as
4967 space-separated arguments (<sep> would be a single
4968 space character string in this case).
4969 COMMAND <cmd>...
4971 Any of the other ..._COMMAND options can have
4972 additional commands appended to them by following
4973 them with as many COMMAND ... options as needed
4974 (generator expressions are supported). For exam‐
4975 ple:
4976 ExternalProject_Add(example
4978 ... # Download options, etc.
4979 BUILD_COMMAND ${CMAKE_COMMAND} -E echo "Starting $<CONFIG> build"
4980 COMMAND ${CMAKE_COMMAND} --build <BINARY_DIR> --config $<CONFIG>
4981 COMMAND ${CMAKE_COMMAND} -E echo "$<CONFIG> build complete"
4982 )
4983 It should also be noted that each build step is created via a
4985 call to ExternalProject_Add_Step(). See that command’s documen‐
4986 tation for the automatic substitutions that are supported for
4987 some options.
4988 Obtaining Project Properties
4990 ExternalProject_Get_Property
4991 The ExternalProject_Get_Property() function retrieves external
4992 project target properties:
4993 ExternalProject_Get_Property(<name> <prop1> [<prop2>...])
4995 The function stores property values in variables of the same
4997 name. Property names correspond to the keyword argument names of
4998 ExternalProject_Add(). For example, the source directory might
4999 be retrieved like so:
5000 ExternalProject_Get_property(myExtProj SOURCE_DIR)
5002 message("Source dir of myExtProj = ${SOURCE_DIR}")
5003 Explicit Step Management
5005 The ExternalProject_Add() function on its own is often sufficient for
5006 incorporating an external project into the main build. Certain scenar‐
5007 ios require additional work to implement desired behavior, such as
5008 adding in a custom step or making steps available as manually trigger‐
5009 able targets. The ExternalProject_Add_Step(), ExternalProject_Add_Step‐
5010 Targets() and ExternalProject_Add_StepDependencies functions provide
5011 the lower level control needed to implement such step-level capabili‐
5012 ties.
5013 ExternalProject_Add_Step
5015 The ExternalProject_Add_Step() function specifies an additional
5016 custom step for an external project defined by an earlier call
5017 to ExternalProject_Add():
5018 ExternalProject_Add_Step(<name> <step> [<option>...])
5020 <name> is the same as the name passed to the original call to
5022 ExternalProject_Add(). The specified <step> must not be one of
5023 the pre-defined steps (mkdir, download, update, patch, config‐
5024 ure, build, install or test). The supported options are:
5025 COMMAND <cmd>...
5027 The command line to be executed by this custom step (gen‐
5028 erator expressions are supported). This option can be
5029 repeated multiple times to specify multiple commands to
5030 be executed in order.
5031 COMMENT <text>...
5033 Text to be printed when the custom step executes.
5034 DEPENDEES <step>...
5036 Other steps (custom or pre-defined) on which this step
5037 depends.
5038 DEPENDERS <step>...
5040 Other steps (custom or pre-defined) that depend on this
5041 new custom step.
5042 DEPENDS <file>...
5044 Files on which this custom step depends.
5045 INDEPENDENT <bool>
5047 Specifies whether this step is independent of the exter‐
5048 nal dependencies specified by the ExternalProject_Add()’s
5049 DEPENDS option. The default is FALSE. Steps marked as
5050 independent may depend only on other steps marked inde‐
5051 pendent. See policy CMP0114.
5052 Note that this use of the term “independent” refers only
5054 to independence from external targets specified by the
5055 DEPENDS option and is orthogonal to a step’s dependencies
5056 on other steps.
5057 If a step target is created for an independent step by
5059 the ExternalProject_Add() STEP_TARGETS option or by the
5060 ExternalProject_Add_StepTargets() function, it will not
5061 depend on the external targets, but may depend on targets
5062 for other steps.
5063 BYPRODUCTS <file>...
5065 Files that will be generated by this custom step but
5066 which might or might not have their modification time
5067 updated by subsequent builds. This list of files will
5068 ultimately be passed through as the BYPRODUCTS option to
5069 the add_custom_command() used to implement the custom
5070 step internally.
5071 ALWAYS <bool>
5073 When enabled, this option specifies that the custom step
5074 should always be run (i.e. that it is always considered
5075 out of date).
5076 EXCLUDE_FROM_MAIN <bool>
5078 When enabled, this option specifies that the external
5079 project’s main target does not depend on the custom step.
5080 This may cause step targets to be created automatically
5081 for the steps on which this step depends. See policy
5082 CMP0114.
5083 WORKING_DIRECTORY <dir>
5085 Specifies the working directory to set before running the
5086 custom step’s command. If this option is not specified,
5087 the directory will be the value of the CMAKE_CUR‐
5088 RENT_BINARY_DIR at the point where ExternalPro‐
5089 ject_Add_Step() was called.
5090 LOG <bool>
5092 If set, this causes the output from the custom step to be
5093 captured to files in the external project’s LOG_DIR if
5094 supplied or STAMP_DIR.
5095 USES_TERMINAL <bool>
5097 If enabled, this gives the custom step direct access to
5098 the terminal if possible.
5099 The command line, comment, working directory and byproducts of
5101 every standard and custom step are processed to replace the
5102 tokens <SOURCE_DIR>, <SOURCE_SUBDIR>, <BINARY_DIR>,
5103 <INSTALL_DIR> <TMP_DIR>, <DOWNLOAD_DIR> and <DOWNLOADED_FILE>
5104 with their corresponding property values defined in the original
5105 call to ExternalProject_Add().
5106 ExternalProject_Add_StepTargets
5108 The ExternalProject_Add_StepTargets() function generates targets
5109 for the steps listed. The name of each created target will be of
5110 the form <name>-<step>:
5111 ExternalProject_Add_StepTargets(<name> <step1> [<step2>...])
5113 Creating a target for a step allows it to be used as a depen‐
5115 dency of another target or to be triggered manually. Having tar‐
5116 gets for specific steps also allows them to be driven indepen‐
5117 dently of each other by specifying targets on build command
5118 lines. For example, you may be submitting to a sub-project based
5119 dashboard where you want to drive the configure portion of the
5120 build, then submit to the dashboard, followed by the build por‐
5121 tion, followed by tests. If you invoke a custom target that
5122 depends on a step halfway through the step dependency chain,
5123 then all the previous steps will also run to ensure everything
5124 is up to date.
5125 Internally, ExternalProject_Add() calls
5127 ExternalProject_Add_Step() to create each step. If any STEP_TAR‐
5128 GETS were specified, then ExternalProject_Add_StepTargets() will
5129 also be called after ExternalProject_Add_Step(). Even if a step
5130 is not mentioned in the STEP_TARGETS option, ExternalPro‐
5131 ject_Add_StepTargets() can still be called later to manually
5132 define a target for the step.
5133 The STEP_TARGETS option for ExternalProject_Add() is generally
5135 the easiest way to ensure targets are created for specific steps
5136 of interest. For custom steps, ExternalProject_Add_StepTar‐
5137 gets() must be called explicitly if a target should also be cre‐
5138 ated for that custom step. An alternative to these two options
5139 is to populate the EP_STEP_TARGETS directory property. It acts
5140 as a default for the step target options and can save having to
5141 repeatedly specify the same set of step targets when multiple
5142 external projects are being defined.
5143 If CMP0114 is set to NEW, step targets are fully responsible for
5145 holding the custom commands implementing their steps. The pri‐
5146 mary target created by ExternalProject_Add depends on the step
5147 targets, and the step targets depend on each other. The tar‐
5148 get-level dependencies match the file-level dependencies used by
5149 the custom commands for each step. The targets for steps cre‐
5150 ated with ExternalProject_Add_Step()’s INDEPENDENT option do not
5151 depend on the external targets specified by
5152 ExternalProject_Add()’s DEPENDS option. The predefined steps
5153 mkdir, download, update, and patch are independent.
5154 If CMP0114 is not NEW, the following deprecated behavior is
5156 available:
5157 · A deprecated NO_DEPENDS option may be specified immediately
5159 after the <name> and before the first step. If the NO_DEPENDS
5160 option is specified, the step target will not depend on the
5161 dependencies of the external project (i.e. on any dependencies
5162 of the <name> custom target created by ExternalProject_Add()).
5163 This is usually safe for the download, update and patch steps,
5164 since they do not typically require that the dependencies are
5165 updated and built. Using NO_DEPENDS for any of the other
5166 pre-defined steps, however, may break parallel builds. Only
5167 use NO_DEPENDS where it is certain that the named steps gen‐
5168 uinely do not have dependencies. For custom steps, consider
5169 whether or not the custom commands require the dependencies to
5170 be configured, built and installed.
5171 · The INDEPENDENT_STEP_TARGETS option for ExternalProject_Add(),
5173 or the EP_INDEPENDENT_STEP_TARGETS directory property, tells
5174 the function to call ExternalProject_Add_StepTargets() inter‐
5175 nally using the NO_DEPENDS option for the specified steps.
5176 ExternalProject_Add_StepDependencies
5178 The ExternalProject_Add_StepDependencies() function can be used
5179 to add dependencies to a step. The dependencies added must be
5180 targets CMake already knows about (these can be ordinary exe‐
5181 cutable or library targets, custom targets or even step targets
5182 of another external project):
5183 ExternalProject_Add_StepDependencies(<name> <step> <target1> [<target2>...])
5185 This function takes care to set both target and file level
5187 dependencies and will ensure that parallel builds will not
5188 break. It should be used instead of add_dependencies() whenever
5189 adding a dependency for some of the step targets generated by
5190 the ExternalProject module.
5191 Examples
5193 The following example shows how to download and build a hypothetical
5194 project called FooBar from github:
5195 include(ExternalProject)
5197 ExternalProject_Add(foobar
5198 GIT_REPOSITORY git@github.com:FooCo/FooBar.git
5199 GIT_TAG origin/release/1.2.3
5200 )
5201 For the sake of the example, also define a second hypothetical external
5203 project called SecretSauce, which is downloaded from a web server. Two
5204 URLs are given to take advantage of a faster internal network if avail‐
5205 able, with a fallback to a slower external server. The project is a
5206 typical Makefile project with no configure step, so some of the default
5207 commands are overridden. The build is only required to build the sauce
5208 target:
5209 find_program(MAKE_EXE NAMES gmake nmake make)
5211 ExternalProject_Add(secretsauce
5212 URL http://intranet.somecompany.com/artifacts/sauce-2.7.tgz
5213 https://www.somecompany.com/downloads/sauce-2.7.zip
5214 URL_HASH MD5=d41d8cd98f00b204e9800998ecf8427e
5215 CONFIGURE_COMMAND ""
5216 BUILD_COMMAND ${MAKE_EXE} sauce
5217 )
5218 Suppose the build step of secretsauce requires that foobar must already
5220 be built. This could be enforced like so:
5221 ExternalProject_Add_StepDependencies(secretsauce build foobar)
5223 Another alternative would be to create a custom target for foobar’s
5225 build step and make secretsauce depend on that rather than the whole
5226 foobar project. This would mean foobar only needs to be built, it
5227 doesn’t need to run its install or test steps before secretsauce can be
5228 built. The dependency can also be defined along with the secretsauce
5229 project:
5230 ExternalProject_Add_StepTargets(foobar build)
5232 ExternalProject_Add(secretsauce
5233 URL http://intranet.somecompany.com/artifacts/sauce-2.7.tgz
5234 https://www.somecompany.com/downloads/sauce-2.7.zip
5235 URL_HASH MD5=d41d8cd98f00b204e9800998ecf8427e
5236 CONFIGURE_COMMAND ""
5237 BUILD_COMMAND ${MAKE_EXE} sauce
5238 DEPENDS foobar-build
5239 )
5240 Instead of calling ExternalProject_Add_StepTargets(), the target could
5242 be defined along with the foobar project itself:
5243 ExternalProject_Add(foobar
5245 GIT_REPOSITORY git@github.com:FooCo/FooBar.git
5246 GIT_TAG origin/release/1.2.3
5247 STEP_TARGETS build
5248 )
5249 If many external projects should have the same set of step targets,
5251 setting a directory property may be more convenient. The build step
5252 target could be created automatically by setting the EP_STEP_TARGETS
5253 directory property before creating the external projects with
5254 ExternalProject_Add():
5255 set_property(DIRECTORY PROPERTY EP_STEP_TARGETS build)
5257 Lastly, suppose that secretsauce provides a script called makedoc which
5259 can be used to generate its own documentation. Further suppose that the
5260 script expects the output directory to be provided as the only parame‐
5261 ter and that it should be run from the secretsauce source directory. A
5262 custom step and a custom target to trigger the script can be defined
5263 like so:
5264 ExternalProject_Add_Step(secretsauce docs
5266 COMMAND <SOURCE_DIR>/makedoc <BINARY_DIR>
5267 WORKING_DIRECTORY <SOURCE_DIR>
5268 COMMENT "Building secretsauce docs"
5269 ALWAYS TRUE
5270 EXCLUDE_FROM_MAIN TRUE
5271 )
5272 ExternalProject_Add_StepTargets(secretsauce docs)
5273 The custom step could then be triggered from the main build like so:
5275 cmake --build . --target secretsauce-docs
5277 FeatureSummary
5279 Functions for generating a summary of enabled/disabled features.
5280 These functions can be used to generate a summary of enabled and dis‐
5282 abled packages and/or feature for a build tree such as:
5283 -- The following OPTIONAL packages have been found:
5285 LibXml2 (required version >= 2.4), XML processing lib, <http://xmlsoft.org>
5286 * Enables HTML-import in MyWordProcessor
5287 * Enables odt-export in MyWordProcessor
5288 PNG, A PNG image library., <http://www.libpng.org/pub/png/>
5289 * Enables saving screenshots
5290 -- The following OPTIONAL packages have not been found:
5291 Lua51, The Lua scripting language., <http://www.lua.org>
5292 * Enables macros in MyWordProcessor
5293 Foo, Foo provides cool stuff.
5294 Global Properties
5296 FeatureSummary_PKG_TYPES
5297 The global property FeatureSummary_PKG_TYPES defines the type of pack‐
5299 ages used by FeatureSummary.
5300 The order in this list is important, the first package type in the list
5302 is the least important, the last is the most important. the of a pack‐
5303 age can only be changed to higher types.
5304 The default package types are , RUNTIME, OPTIONAL, RECOMMENDED and
5306 REQUIRED, and their importance is RUNTIME < OPTIONAL < RECOMMENDED <
5307 REQUIRED.
5308 FeatureSummary_REQUIRED_PKG_TYPES
5310 The global property FeatureSummary_REQUIRED_PKG_TYPES defines which
5312 package types are required.
5313 If one or more package in this categories has not been found, CMake
5315 will abort when calling feature_summary() with the ‘FATAL_ON_MISS‐
5316 ING_REQUIRED_PACKAGES’ option enabled.
5317 The default value for this global property is REQUIRED.
5319 FeatureSummary_DEFAULT_PKG_TYPE
5321 The global property FeatureSummary_DEFAULT_PKG_TYPE defines which pack‐
5323 age type is the default one. When calling feature_summary(), if the
5324 user did not set the package type explicitly, the package will be
5325 assigned to this category.
5326 This value must be one of the types defined in the
5328 FeatureSummary_PKG_TYPES global property unless the package type is set
5329 for all the packages.
5330 The default value for this global property is OPTIONAL.
5332 FeatureSummary_<TYPE>_DESCRIPTION
5334 The global property FeatureSummary_<TYPE>_DESCRIPTION can be defined
5336 for each type to replace the type name with the specified string when‐
5337 ever the package type is used in an output string.
5338 If not set, the string “<TYPE> packages” is used.
5340 Functions
5342 feature_summary
5343 feature_summary( [FILENAME <file>]
5345 [APPEND]
5346 [VAR <variable_name>]
5347 [INCLUDE_QUIET_PACKAGES]
5348 [FATAL_ON_MISSING_REQUIRED_PACKAGES]
5349 [DESCRIPTION "<description>" | DEFAULT_DESCRIPTION]
5350 [QUIET_ON_EMPTY]
5351 WHAT (ALL
5352 | PACKAGES_FOUND | PACKAGES_NOT_FOUND
5353 | <TYPE>_PACKAGES_FOUND | <TYPE>_PACKAGES_NOT_FOUND
5354 | ENABLED_FEATURES | DISABLED_FEATURES)
5355 )
5356 The feature_summary() macro can be used to print information
5358 about enabled or disabled packages or features of a project. By
5359 default, only the names of the features/packages will be printed
5360 and their required version when one was specified. Use
5361 set_package_properties() to add more useful information, like
5362 e.g. a download URL for the respective package or their purpose
5363 in the project.
5364 The WHAT option is the only mandatory option. Here you specify
5366 what information will be printed:
5367 ALL print everything
5369 ENABLED_FEATURES
5371 the list of all features which are enabled
5372 DISABLED_FEATURES
5374 the list of all features which are disabled
5375 PACKAGES_FOUND
5377 the list of all packages which have been found
5378 PACKAGES_NOT_FOUND
5380 the list of all packages which have not been found
5381 For each package type <TYPE> defined by the
5383 FeatureSummary_PKG_TYPES global property, the following informa‐
5384 tion can also be used:
5385 <TYPE>_PACKAGES_FOUND
5387 only those packages which have been found which have the
5388 type <TYPE>
5389 <TYPE>_PACKAGES_NOT_FOUND
5391 only those packages which have not been found which have
5392 the type <TYPE>
5393 With the exception of the ALL value, these values can be com‐
5395 bined in order to customize the output. For example:
5396 feature_summary(WHAT ENABLED_FEATURES DISABLED_FEATURES)
5398 If a FILENAME is given, the information is printed into this
5400 file. If APPEND is used, it is appended to this file, otherwise
5401 the file is overwritten if it already existed. If the VAR
5402 option is used, the information is “printed” into the specified
5403 variable. If FILENAME is not used, the information is printed
5404 to the terminal. Using the DESCRIPTION option a description or
5405 headline can be set which will be printed above the actual con‐
5406 tent. If only one type of package was requested, no title is
5407 printed, unless it is explicitly set using either DESCRIPTION to
5408 use a custom string, or DEFAULT_DESCRIPTION to use a default
5409 title for the requested type. If INCLUDE_QUIET_PACKAGES is
5410 given, packages which have been searched with find_package(...
5411 QUIET) will also be listed. By default they are skipped. If
5412 FATAL_ON_MISSING_REQUIRED_PACKAGES is given, CMake will abort if
5413 a package which is marked as one of the package types listed in
5414 the FeatureSummary_REQUIRED_PKG_TYPES global property has not
5415 been found. The default value for the
5416 FeatureSummary_REQUIRED_PKG_TYPES global property is REQUIRED.
5417 The FeatureSummary_DEFAULT_PKG_TYPE global property can be modi‐
5419 fied to change the default package type assigned when not
5420 explicitly assigned by the user.
5421 If the QUIET_ON_EMPTY option is used, if only one type of pack‐
5423 age was requested, and no packages belonging to that category
5424 were found, then no output (including the DESCRIPTION) is
5425 printed or added to the VAR variable.
5426 Example 1, append everything to a file:
5428 include(FeatureSummary)
5430 feature_summary(WHAT ALL
5431 FILENAME ${CMAKE_BINARY_DIR}/all.log APPEND)
5432 Example 2, print the enabled features into the variable enabled‐
5434 FeaturesText, including QUIET packages:
5435 include(FeatureSummary)
5437 feature_summary(WHAT ENABLED_FEATURES
5438 INCLUDE_QUIET_PACKAGES
5439 DESCRIPTION "Enabled Features:"
5440 VAR enabledFeaturesText)
5441 message(STATUS "${enabledFeaturesText}")
5442 Example 3, change default package types and print only the cate‐
5444 gories that are not empty:
5445 include(FeatureSummary)
5447 set_property(GLOBAL APPEND PROPERTY FeatureSummary_PKG_TYPES BUILD)
5448 find_package(FOO)
5449 set_package_properties(FOO PROPERTIES TYPE BUILD)
5450 feature_summary(WHAT BUILD_PACKAGES_FOUND
5451 Description "Build tools found:"
5452 QUIET_ON_EMPTY)
5453 feature_summary(WHAT BUILD_PACKAGES_NOT_FOUND
5454 Description "Build tools not found:"
5455 QUIET_ON_EMPTY)
5456 set_package_properties
5458 set_package_properties(<name> PROPERTIES
5460 [ URL <url> ]
5461 [ DESCRIPTION <description> ]
5462 [ TYPE (RUNTIME|OPTIONAL|RECOMMENDED|REQUIRED) ]
5463 [ PURPOSE <purpose> ]
5464 )
5465 Use this macro to set up information about the named package,
5467 which can then be displayed via FEATURE_SUMMARY(). This can be
5468 done either directly in the Find-module or in the project which
5469 uses the module after the find_package() call. The features for
5470 which information can be set are added automatically by the
5471 find_package() command.
5472 URL <url>
5474 This should be the homepage of the package, or something
5475 similar. Ideally this is set already directly in the
5476 Find-module.
5477 DESCRIPTION <description>
5479 A short description what that package is, at most one
5480 sentence. Ideally this is set already directly in the
5481 Find-module.
5482 TYPE <type>
5484 What type of dependency has the using project on that
5485 package. Default is OPTIONAL. In this case it is a
5486 package which can be used by the project when available
5487 at buildtime, but it also work without. RECOMMENDED is
5488 similar to OPTIONAL, i.e. the project will build if the
5489 package is not present, but the functionality of the
5490 resulting binaries will be severely limited. If a
5491 REQUIRED package is not available at buildtime, the
5492 project may not even build. This can be combined with
5493 the FATAL_ON_MISSING_REQUIRED_PACKAGES argument for fea‐
5494 ture_summary(). Last, a RUNTIME package is a package
5495 which is actually not used at all during the build, but
5496 which is required for actually running the resulting
5497 binaries. So if such a package is missing, the project
5498 can still be built, but it may not work later on. If
5499 set_package_properties() is called multiple times for the
5500 same package with different TYPEs, the TYPE is only
5501 changed to higher TYPEs (RUNTIME < OPTIONAL < RECOMMENDED
5502 < REQUIRED), lower TYPEs are ignored. The TYPE property
5503 is project-specific, so it cannot be set by the Find-mod‐
5504 ule, but must be set in the project. Type accepted can
5505 be changed by setting the FeatureSummary_PKG_TYPES global
5506 property.
5507 PURPOSE <purpose>
5509 This describes which features this package enables in the
5510 project, i.e. it tells the user what functionality he
5511 gets in the resulting binaries. If set_package_proper‐
5512 ties() is called multiple times for a package, all PUR‐
5513 POSE properties are appended to a list of purposes of the
5514 package in the project. As the TYPE property, also the
5515 PURPOSE property is project-specific, so it cannot be set
5516 by the Find-module, but must be set in the project.
5517 Example for setting the info for a package:
5519 find_package(LibXml2)
5521 set_package_properties(LibXml2 PROPERTIES
5522 DESCRIPTION "A XML processing library."
5523 URL "http://xmlsoft.org/")
5524 # or
5525 set_package_properties(LibXml2 PROPERTIES
5526 TYPE RECOMMENDED
5527 PURPOSE "Enables HTML-import in MyWordProcessor")
5528 # or
5529 set_package_properties(LibXml2 PROPERTIES
5530 TYPE OPTIONAL
5531 PURPOSE "Enables odt-export in MyWordProcessor")
5532 find_package(DBUS)
5534 set_package_properties(DBUS PROPERTIES
5535 TYPE RUNTIME
5536 PURPOSE "Necessary to disable the screensaver during a presentation")
5537 add_feature_info
5539 add_feature_info(<name> <enabled> <description>)
5541 Use this macro to add information about a feature with the given
5543 <name>. <enabled> contains whether this feature is enabled or
5544 not. It can be a variable or a list of conditions. <descrip‐
5545 tion> is a text describing the feature. The information can be
5546 displayed using feature_summary() for ENABLED_FEATURES and DIS‐
5547 ABLED_FEATURES respectively.
5548 Example for setting the info for a feature:
5550 option(WITH_FOO "Help for foo" ON)
5552 add_feature_info(Foo WITH_FOO "The Foo feature provides very cool stuff.")
5553 Legacy Macros
5555 The following macros are provided for compatibility with previous CMake
5556 versions:
5557 set_package_info
5559 set_package_info(<name> <description> [ <url> [<purpose>] ])
5561 Use this macro to set up information about the named package,
5563 which can then be displayed via feature_summary(). This can be
5564 done either directly in the Find-module or in the project which
5565 uses the module after the find_package() call. The features for
5566 which information can be set are added automatically by the
5567 find_package() command.
5568 set_feature_info
5570 set_feature_info(<name> <description> [<url>])
5572 Does the same as:
5574 set_package_info(<name> <description> <url>)
5576 print_enabled_features
5578 print_enabled_features()
5580 Does the same as
5582 feature_summary(WHAT ENABLED_FEATURES DESCRIPTION "Enabled features:")
5584 print_disabled_features
5586 print_disabled_features()
5588 Does the same as
5590 feature_summary(WHAT DISABLED_FEATURES DESCRIPTION "Disabled features:")
5592 FetchContent
5594 New in version 3.11.
5595 Overview
5598 This module enables populating content at configure time via any method
5599 supported by the ExternalProject module. Whereas ExternalProject_Add()
5600 downloads at build time, the FetchContent module makes content avail‐
5601 able immediately, allowing the configure step to use the content in
5602 commands like add_subdirectory(), include() or file() operations.
5603 Content population details would normally be defined separately from
5605 the command that performs the actual population. This separation
5606 ensures that all of the dependency details are defined before anything
5607 may try to use those details to populate content. This is particularly
5608 important in more complex project hierarchies where dependencies may be
5609 shared between multiple projects.
5610 The following shows a typical example of declaring content details:
5612 FetchContent_Declare(
5614 googletest
5615 GIT_REPOSITORY https://github.com/google/googletest.git
5616 GIT_TAG release-1.8.0
5617 )
5618 For most typical cases, populating the content can then be done with a
5620 single command like so:
5621 FetchContent_MakeAvailable(googletest)
5623 The above command not only populates the content, it also adds it to
5625 the main build (if possible) so that the main build can use the popu‐
5626 lated project’s targets, etc. In some cases, the main project may need
5627 to have more precise control over the population or may be required to
5628 explicitly define the population steps (e.g. if CMake versions earlier
5629 than 3.14 need to be supported). The typical pattern of such custom
5630 steps looks like this:
5631 FetchContent_GetProperties(googletest)
5633 if(NOT googletest_POPULATED)
5634 FetchContent_Populate(googletest)
5635 add_subdirectory(${googletest_SOURCE_DIR} ${googletest_BINARY_DIR})
5636 endif()
5637 Regardless of which population method is used, when using the
5639 declare-populate pattern with a hierarchical project arrangement,
5640 projects at higher levels in the hierarchy are able to override the
5641 population details of content specified anywhere lower in the project
5642 hierarchy. The ability to detect whether content has already been pop‐
5643 ulated ensures that even if multiple child projects want certain con‐
5644 tent to be available, the first one to populate it wins. The other
5645 child project can simply make use of the already available content
5646 instead of repeating the population for itself. See the Examples sec‐
5647 tion which demonstrates this scenario.
5648 The FetchContent module also supports defining and populating content
5650 in a single call, with no check for whether the content has been popu‐
5651 lated elsewhere in the project already. This is a more low level oper‐
5652 ation and would not normally be the way the module is used, but it is
5653 sometimes useful as part of implementing some higher level feature or
5654 to populate some content in CMake’s script mode.
5655 Commands
5657 Declaring Content Details
5658 FetchContent_Declare
5659 FetchContent_Declare(<name> <contentOptions>...)
5661 The FetchContent_Declare() function records the options that
5663 describe how to populate the specified content, but if such
5664 details have already been recorded earlier in this project
5665 (regardless of where in the project hierarchy), this and all
5666 later calls for the same content <name> are ignored. This
5667 “first to record, wins” approach is what allows hierarchical
5668 projects to have parent projects override content details of
5669 child projects.
5670 The content <name> can be any string without spaces, but good
5672 practice would be to use only letters, numbers and underscores.
5673 The name will be treated case-insensitively and it should be
5674 obvious for the content it represents, often being the name of
5675 the child project or the value given to its top level project()
5676 command (if it is a CMake project). For well-known public
5677 projects, the name should generally be the official name of the
5678 project. Choosing an unusual name makes it unlikely that other
5679 projects needing that same content will use the same name, lead‐
5680 ing to the content being populated multiple times.
5681 The <contentOptions> can be any of the download or update/patch
5683 options that the ExternalProject_Add() command understands. The
5684 configure, build, install and test steps are explicitly disabled
5685 and therefore options related to them will be ignored. The
5686 SOURCE_SUBDIR option is an exception, see
5687 FetchContent_MakeAvailable() for details on how that affects
5688 behavior.
5689 In most cases, <contentOptions> will just be a couple of options
5691 defining the download method and method-specific details like a
5692 commit tag or archive hash. For example:
5693 FetchContent_Declare(
5695 googletest
5696 GIT_REPOSITORY https://github.com/google/googletest.git
5697 GIT_TAG release-1.8.0
5698 )
5699 FetchContent_Declare(
5701 myCompanyIcons
5702 URL https://intranet.mycompany.com/assets/iconset_1.12.tar.gz
5703 URL_HASH 5588a7b18261c20068beabfb4f530b87
5704 )
5705 FetchContent_Declare(
5707 myCompanyCertificates
5708 SVN_REPOSITORY svn+ssh://svn.mycompany.com/srv/svn/trunk/certs
5709 SVN_REVISION -r12345
5710 )
5711 Populating The Content
5713 For most common scenarios, population means making content available to
5714 the main build according to previously declared details for that depen‐
5715 dency. There are two main patterns for populating content, one based
5716 on calling FetchContent_GetProperties() and FetchContent_Populate() for
5717 more precise control and the other on calling
5718 FetchContent_MakeAvailable() for a simpler, more automated approach.
5719 The former generally follows this canonical pattern:
5720 # Check if population has already been performed
5722 FetchContent_GetProperties(<name>)
5723 string(TOLOWER "<name>" lcName)
5724 if(NOT ${lcName}_POPULATED)
5725 # Fetch the content using previously declared details
5726 FetchContent_Populate(<name>)
5727 # Set custom variables, policies, etc.
5729 # ...
5730 # Bring the populated content into the build
5732 add_subdirectory(${${lcName}_SOURCE_DIR} ${${lcName}_BINARY_DIR})
5733 endif()
5734 The above is such a common pattern that, where no custom steps are
5736 needed between the calls to FetchContent_Populate() and add_subdirec‐
5737 tory(), equivalent logic can be obtained by calling
5738 FetchContent_MakeAvailable() instead. Where it meets the needs of the
5739 project, FetchContent_MakeAvailable() should be preferred, as it is
5740 simpler and provides additional features over the pattern above.
5741 FetchContent_Populate
5743 FetchContent_Populate( <name> )
5745 In most cases, the only argument given to FetchContent_Popu‐
5747 late() is the <name>. When used this way, the command assumes
5748 the content details have been recorded by an earlier call to
5749 FetchContent_Declare(). The details are stored in a global
5750 property, so they are unaffected by things like variable or
5751 directory scope. Therefore, it doesn’t matter where in the
5752 project the details were previously declared, as long as they
5753 have been declared before the call to FetchContent_Populate().
5754 Those saved details are then used to construct a call to Exter‐
5755 nalProject_Add() in a private sub-build to perform the content
5756 population immediately. The implementation of ExternalPro‐
5757 ject_Add() ensures that if the content has already been popu‐
5758 lated in a previous CMake run, that content will be reused
5759 rather than repopulating them again. For the common case where
5760 population involves downloading content, the cost of the down‐
5761 load is only paid once.
5762 An internal global property records when a particular content
5764 population request has been processed. If FetchContent_Popu‐
5765 late() is called more than once for the same content name within
5766 a configure run, the second call will halt with an error.
5767 Projects can and should check whether content population has
5768 already been processed with the FetchContent_GetProperties()
5769 command before calling FetchContent_Populate().
5770 FetchContent_Populate() will set three variables in the scope of
5772 the caller; <lcName>_POPULATED, <lcName>_SOURCE_DIR and
5773 <lcName>_BINARY_DIR, where <lcName> is the lowercased <name>.
5774 <lcName>_POPULATED will always be set to True by the call.
5775 <lcName>_SOURCE_DIR is the location where the content can be
5776 found upon return (it will have already been populated), while
5777 <lcName>_BINARY_DIR is a directory intended for use as a corre‐
5778 sponding build directory. The main use case for the two direc‐
5779 tory variables is to call add_subdirectory() immediately after
5780 population, i.e.:
5781 FetchContent_Populate(FooBar ...)
5783 add_subdirectory(${foobar_SOURCE_DIR} ${foobar_BINARY_DIR})
5784 The values of the three variables can also be retrieved from
5786 anywhere in the project hierarchy using the
5787 FetchContent_GetProperties() command.
5788 A number of cache variables influence the behavior of all con‐
5790 tent population performed using details saved from a
5791 FetchContent_Declare() call:
5792 FETCHCONTENT_BASE_DIR
5794 In most cases, the saved details do not specify any
5795 options relating to the directories to use for the inter‐
5796 nal sub-build, final source and build areas. It is gen‐
5797 erally best to leave these decisions up to the FetchCon‐
5798 tent module to handle on the project’s behalf. The
5799 FETCHCONTENT_BASE_DIR cache variable controls the point
5800 under which all content population directories are col‐
5801 lected, but in most cases developers would not need to
5802 change this. The default location is
5803 ${CMAKE_BINARY_DIR}/_deps, but if developers change this
5804 value, they should aim to keep the path short and just
5805 below the top level of the build tree to avoid running
5806 into path length problems on Windows.
5807 FETCHCONTENT_QUIET
5809 The logging output during population can be quite ver‐
5810 bose, making the configure stage quite noisy. This cache
5811 option (ON by default) hides all population output unless
5812 an error is encountered. If experiencing problems with
5813 hung downloads, temporarily switching this option off may
5814 help diagnose which content population is causing the
5815 issue.
5816 FETCHCONTENT_FULLY_DISCONNECTED
5818 When this option is enabled, no attempt is made to down‐
5819 load or update any content. It is assumed that all con‐
5820 tent has already been populated in a previous run or the
5821 source directories have been pointed at existing contents
5822 the developer has provided manually (using options
5823 described further below). When the developer knows that
5824 no changes have been made to any content details, turning
5825 this option ON can significantly speed up the configure
5826 stage. It is OFF by default.
5827 FETCHCONTENT_UPDATES_DISCONNECTED
5829 This is a less severe download/update control compared to
5830 FETCHCONTENT_FULLY_DISCONNECTED. Instead of bypassing
5831 all download and update logic, the FETCHCON‐
5832 TENT_UPDATES_DISCONNECTED only disables the update stage.
5833 Therefore, if content has not been downloaded previously,
5834 it will still be downloaded when this option is enabled.
5835 This can speed up the configure stage, but not as much as
5836 FETCHCONTENT_FULLY_DISCONNECTED. It is OFF by default.
5837 In addition to the above cache variables, the following cache
5839 variables are also defined for each content name (<ucName> is
5840 the uppercased value of <name>):
5841 FETCHCONTENT_SOURCE_DIR_<ucName>
5843 If this is set, no download or update steps are performed
5844 for the specified content and the <lcName>_SOURCE_DIR
5845 variable returned to the caller is pointed at this loca‐
5846 tion. This gives developers a way to have a separate
5847 checkout of the content that they can modify freely with‐
5848 out interference from the build. The build simply uses
5849 that existing source, but it still defines
5850 <lcName>_BINARY_DIR to point inside its own build area.
5851 Developers are strongly encouraged to use this mechanism
5852 rather than editing the sources populated in the default
5853 location, as changes to sources in the default location
5854 can be lost when content population details are changed
5855 by the project.
5856 FETCHCONTENT_UPDATES_DISCONNECTED_<ucName>
5858 This is the per-content equivalent of FETCHCON‐
5859 TENT_UPDATES_DISCONNECTED. If the global option or this
5860 option is ON, then updates will be disabled for the named
5861 content. Disabling updates for individual content can be
5862 useful for content whose details rarely change, while
5863 still leaving other frequently changing content with
5864 updates enabled.
5865 The FetchContent_Populate() command also supports a syntax
5867 allowing the content details to be specified directly rather
5868 than using any saved details. This is more low-level and use of
5869 this form is generally to be avoided in favour of using saved
5870 content details as outlined above. Nevertheless, in certain
5871 situations it can be useful to invoke the content population as
5872 an isolated operation (typically as part of implementing some
5873 other higher level feature or when using CMake in script mode):
5874 FetchContent_Populate( <name>
5876 [QUIET]
5877 [SUBBUILD_DIR <subBuildDir>]
5878 [SOURCE_DIR <srcDir>]
5879 [BINARY_DIR <binDir>]
5880 ...
5881 )
5882 This form has a number of key differences to that where only
5884 <name> is provided:
5885 · All required population details are assumed to have been pro‐
5887 vided directly in the call to FetchContent_Populate(). Any
5888 saved details for <name> are ignored.
5889 · No check is made for whether content for <name> has already
5891 been populated.
5892 · No global property is set to record that the population has
5894 occurred.
5895 · No global properties record the source or binary directories
5897 used for the populated content.
5898 · The FETCHCONTENT_FULLY_DISCONNECTED and FETCHCON‐
5900 TENT_UPDATES_DISCONNECTED cache variables are ignored.
5901 The <lcName>_SOURCE_DIR and <lcName>_BINARY_DIR variables are
5903 still returned to the caller, but since these locations are not
5904 stored as global properties when this form is used, they are
5905 only available to the calling scope and below rather than the
5906 entire project hierarchy. No <lcName>_POPULATED variable is set
5907 in the caller’s scope with this form.
5908 The supported options for FetchContent_Populate() are the same
5910 as those for FetchContent_Declare(). Those few options shown
5911 just above are either specific to FetchContent_Populate() or
5912 their behavior is slightly modified from how ExternalPro‐
5913 ject_Add() treats them.
5914 QUIET The QUIET option can be given to hide the output associ‐
5916 ated with populating the specified content. If the popu‐
5917 lation fails, the output will be shown regardless of
5918 whether this option was given or not so that the cause of
5919 the failure can be diagnosed. The global FETCHCON‐
5920 TENT_QUIET cache variable has no effect on FetchCon‐
5921 tent_Populate() calls where the content details are pro‐
5922 vided directly.
5923 SUBBUILD_DIR
5925 The SUBBUILD_DIR argument can be provided to change the
5926 location of the sub-build created to perform the popula‐
5927 tion. The default value is ${CMAKE_CUR‐
5928 RENT_BINARY_DIR}/<lcName>-subbuild and it would be
5929 unusual to need to override this default. If a relative
5930 path is specified, it will be interpreted as relative to
5931 CMAKE_CURRENT_BINARY_DIR. This option should not be con‐
5932 fused with the SOURCE_SUBDIR option which only affects
5933 the FetchContent_MakeAvailable() command.
5934 SOURCE_DIR, BINARY_DIR
5936 The SOURCE_DIR and BINARY_DIR arguments are supported by
5937 ExternalProject_Add(), but different default values are
5938 used by FetchContent_Populate(). SOURCE_DIR defaults to
5939 ${CMAKE_CURRENT_BINARY_DIR}/<lcName>-src and BINARY_DIR
5940 defaults to ${CMAKE_CURRENT_BINARY_DIR}/<lcName>-build.
5941 If a relative path is specified, it will be interpreted
5942 as relative to CMAKE_CURRENT_BINARY_DIR.
5943 In addition to the above explicit options, any other unrecog‐
5945 nized options are passed through unmodified to ExternalPro‐
5946 ject_Add() to perform the download, patch and update steps. The
5947 following options are explicitly prohibited (they are disabled
5948 by the FetchContent_Populate() command):
5949 · CONFIGURE_COMMAND
5951 · BUILD_COMMAND
5953 · INSTALL_COMMAND
5955 · TEST_COMMAND
5957 If using FetchContent_Populate() within CMake’s script mode, be
5959 aware that the implementation sets up a sub-build which there‐
5960 fore requires a CMake generator and build tool to be available.
5961 If these cannot be found by default, then the CMAKE_GENERATOR
5962 and/or CMAKE_MAKE_PROGRAM variables will need to be set appro‐
5963 priately on the command line invoking the script.
5964 FetchContent_GetProperties
5966 When using saved content details, a call to
5967 FetchContent_Populate() records information in global properties
5968 which can be queried at any time. This information includes the
5969 source and binary directories associated with the content and
5970 also whether or not the content population has been processed
5971 during the current configure run.
5972 FetchContent_GetProperties( <name>
5974 [SOURCE_DIR <srcDirVar>]
5975 [BINARY_DIR <binDirVar>]
5976 [POPULATED <doneVar>]
5977 )
5978 The SOURCE_DIR, BINARY_DIR and POPULATED options can be used to
5980 specify which properties should be retrieved. Each option
5981 accepts a value which is the name of the variable in which to
5982 store that property. Most of the time though, only <name> is
5983 given, in which case the call will then set the same variables
5984 as a call to FetchContent_Populate(name). This allows the fol‐
5985 lowing canonical pattern to be used, which ensures that the rel‐
5986 evant variables will always be defined regardless of whether or
5987 not the population has been performed elsewhere in the project
5988 already:
5989 FetchContent_GetProperties(foobar)
5991 if(NOT foobar_POPULATED)
5992 FetchContent_Populate(foobar)
5993 ...
5994 endif()
5995 The above pattern allows other parts of the overall project
5997 hierarchy to re-use the same content and ensure that it is only
5998 populated once.
5999 FetchContent_MakeAvailable
6001 FetchContent_MakeAvailable( <name1> [<name2>...] )
6003 This command implements the common pattern typically needed for
6005 most dependencies. It iterates over each of the named dependen‐
6006 cies in turn and for each one it loosely follows the canonical
6007 pattern as presented at the beginning of this section. An
6008 important difference is that add_subdirectory() will only be
6009 called on the populated content if there is a CMakeLists.txt
6010 file in its top level source directory. This allows the command
6011 to be used for dependencies that make downloaded content avail‐
6012 able at a known location but which do not need or support being
6013 added directly to the build.
6014 The SOURCE_SUBDIR option can be given in the declared details to
6016 instruct FetchContent_MakeAvailable() to look for a CMake‐
6017 Lists.txt file in a subdirectory below the top level (i.e. the
6018 same way that SOURCE_SUBDIR is used by the ExternalProject_Add()
6019 command). SOURCE_SUBDIR must always be a relative path. See
6020 the next section for an example of this option.
6021 Examples
6023 This first fairly straightforward example ensures that some popular
6024 testing frameworks are available to the main build:
6025 include(FetchContent)
6027 FetchContent_Declare(
6028 googletest
6029 GIT_REPOSITORY https://github.com/google/googletest.git
6030 GIT_TAG release-1.8.0
6031 )
6032 FetchContent_Declare(
6033 Catch2
6034 GIT_REPOSITORY https://github.com/catchorg/Catch2.git
6035 GIT_TAG v2.5.0
6036 )
6037 # After the following call, the CMake targets defined by googletest and
6039 # Catch2 will be defined and available to the rest of the build
6040 FetchContent_MakeAvailable(googletest Catch2)
6041 If the sub-project’s CMakeLists.txt file is not at the top level of its
6043 source tree, the SOURCE_SUBDIR option can be used to tell FetchContent
6044 where to find it. The following example shows how to use that option
6045 and it also sets a variable which is meaningful to the subproject
6046 before pulling it into the main build:
6047 include(FetchContent)
6049 FetchContent_Declare(
6050 protobuf
6051 GIT_REPOSITORY https://github.com/protocolbuffers/protobuf.git
6052 GIT_TAG v3.12.0
6053 SOURCE_SUBDIR cmake
6054 )
6055 set(protobuf_BUILD_TESTS OFF)
6056 FetchContent_MakeAvailable(protobuf)
6057 In more complex project hierarchies, the dependency relationships can
6059 be more complicated. Consider a hierarchy where projA is the top level
6060 project and it depends directly on projects projB and projC. Both
6061 projB and projC can be built standalone and they also both depend on
6062 another project projD. projB additionally depends on projE. This
6063 example assumes that all five projects are available on a company git
6064 server. The CMakeLists.txt of each project might have sections like
6065 the following:
6066 projA:
6068 include(FetchContent)
6070 FetchContent_Declare(
6071 projB
6072 GIT_REPOSITORY git@mycompany.com:git/projB.git
6073 GIT_TAG 4a89dc7e24ff212a7b5167bef7ab079d
6074 )
6075 FetchContent_Declare(
6076 projC
6077 GIT_REPOSITORY git@mycompany.com:git/projC.git
6078 GIT_TAG 4ad4016bd1d8d5412d135cf8ceea1bb9
6079 )
6080 FetchContent_Declare(
6081 projD
6082 GIT_REPOSITORY git@mycompany.com:git/projD.git
6083 GIT_TAG origin/integrationBranch
6084 )
6085 FetchContent_Declare(
6086 projE
6087 GIT_REPOSITORY git@mycompany.com:git/projE.git
6088 GIT_TAG origin/release/2.3-rc1
6089 )
6090 # Order is important, see notes in the discussion further below
6092 FetchContent_MakeAvailable(projD projB projC)
6093 projB:
6095 include(FetchContent)
6097 FetchContent_Declare(
6098 projD
6099 GIT_REPOSITORY git@mycompany.com:git/projD.git
6100 GIT_TAG 20b415f9034bbd2a2e8216e9a5c9e632
6101 )
6102 FetchContent_Declare(
6103 projE
6104 GIT_REPOSITORY git@mycompany.com:git/projE.git
6105 GIT_TAG 68e20f674a48be38d60e129f600faf7d
6106 )
6107 FetchContent_MakeAvailable(projD projE)
6109 projC:
6111 include(FetchContent)
6113 FetchContent_Declare(
6114 projD
6115 GIT_REPOSITORY git@mycompany.com:git/projD.git
6116 GIT_TAG 7d9a17ad2c962aa13e2fbb8043fb6b8a
6117 )
6118 # This particular version of projD requires workarounds
6120 FetchContent_GetProperties(projD)
6121 if(NOT projd_POPULATED)
6122 FetchContent_Populate(projD)
6123 # Copy an additional/replacement file into the populated source
6125 file(COPY someFile.c DESTINATION ${projd_SOURCE_DIR}/src)
6126 add_subdirectory(${projd_SOURCE_DIR} ${projd_BINARY_DIR})
6128 endif()
6129 A few key points should be noted in the above:
6131 · projB and projC define different content details for projD, but projA
6133 also defines a set of content details for projD. Because projA will
6134 define them first, the details from projB and projC will not be used.
6135 The override details defined by projA are not required to match
6136 either of those from projB or projC, but it is up to the higher level
6137 project to ensure that the details it does define still make sense
6138 for the child projects.
6139 · In the projA call to FetchContent_MakeAvailable(), projD is listed
6141 ahead of projB and projC to ensure that projA is in control of how
6142 projD is populated.
6143 · While projA defines content details for projE, it does not need to
6145 explicitly call FetchContent_MakeAvailable(projE) or FetchCon‐
6146 tent_Populate(projD) itself. Instead, it leaves that to the child
6147 projB. For higher level projects, it is often enough to just define
6148 the override content details and leave the actual population to the
6149 child projects. This saves repeating the same thing at each level of
6150 the project hierarchy unnecessarily.
6151 Projects don’t always need to add the populated content to the build.
6153 Sometimes the project just wants to make the downloaded content avail‐
6154 able at a predictable location. The next example ensures that a set of
6155 standard company toolchain files (and potentially even the toolchain
6156 binaries themselves) is available early enough to be used for that same
6157 build.
6158 cmake_minimum_required(VERSION 3.14)
6160 include(FetchContent)
6162 FetchContent_Declare(
6163 mycom_toolchains
6164 URL https://intranet.mycompany.com//toolchains_1.3.2.tar.gz
6165 )
6166 FetchContent_MakeAvailable(mycom_toolchains)
6167 project(CrossCompileExample)
6169 The project could be configured to use one of the downloaded toolchains
6171 like so:
6172 cmake -DCMAKE_TOOLCHAIN_FILE=_deps/mycom_toolchains-src/toolchain_arm.cmake /path/to/src
6174 When CMake processes the CMakeLists.txt file, it will download and
6176 unpack the tarball into _deps/mycompany_toolchains-src relative to the
6177 build directory. The CMAKE_TOOLCHAIN_FILE variable is not used until
6178 the project() command is reached, at which point CMake looks for the
6179 named toolchain file relative to the build directory. Because the tar‐
6180 ball has already been downloaded and unpacked by then, the toolchain
6181 file will be in place, even the very first time that cmake is run in
6182 the build directory.
6183 Lastly, the following example demonstrates how one might download and
6185 unpack a firmware tarball using CMake’s script mode. The call to
6186 FetchContent_Populate() specifies all the content details and the
6187 unpacked firmware will be placed in a firmware directory below the cur‐
6188 rent working directory.
6189 getFirmware.cmake:
6191 # NOTE: Intended to be run in script mode with cmake -P
6193 include(FetchContent)
6194 FetchContent_Populate(
6195 firmware
6196 URL https://mycompany.com/assets/firmware-1.23-arm.tar.gz
6197 URL_HASH MD5=68247684da89b608d466253762b0ff11
6198 SOURCE_DIR firmware
6199 )
6200 FindPackageHandleStandardArgs
6202 This module provides functions intended to be used in Find Modules
6203 implementing find_package(<PackageName>) calls.
6204 find_package_handle_standard_args
6206 This command handles the REQUIRED, QUIET and version-related
6207 arguments of find_package(). It also sets the <Package‐
6208 Name>_FOUND variable. The package is considered found if all
6209 variables listed contain valid results, e.g. valid filepaths.
6210 There are two signatures:
6212 find_package_handle_standard_args(<PackageName>
6214 (DEFAULT_MSG|<custom-failure-message>)
6215 <required-var>...
6216 )
6217 find_package_handle_standard_args(<PackageName>
6219 [FOUND_VAR <result-var>]
6220 [REQUIRED_VARS <required-var>...]
6221 [VERSION_VAR <version-var>]
6222 [HANDLE_VERSION_RANGE]
6223 [HANDLE_COMPONENTS]
6224 [CONFIG_MODE]
6225 [NAME_MISMATCHED]
6226 [REASON_FAILURE_MESSAGE <reason-failure-message>]
6227 [FAIL_MESSAGE <custom-failure-message>]
6228 )
6229 The <PackageName>_FOUND variable will be set to TRUE if all the
6231 variables <required-var>... are valid and any optional con‐
6232 straints are satisfied, and FALSE otherwise. A success or fail‐
6233 ure message may be displayed based on the results and on whether
6234 the REQUIRED and/or QUIET option was given to the find_package()
6235 call.
6236 The options are:
6238 (DEFAULT_MSG|<custom-failure-message>)
6240 In the simple signature this specifies the failure mes‐
6241 sage. Use DEFAULT_MSG to ask for a default message to be
6242 computed (recommended). Not valid in the full signature.
6243 FOUND_VAR <result-var>
6245 Obsolete. Specifies either <PackageName>_FOUND or <PACK‐
6246 AGENAME>_FOUND as the result variable. This exists only
6247 for compatibility with older versions of CMake and is now
6248 ignored. Result variables of both names are always set
6249 for compatibility.
6250 REQUIRED_VARS <required-var>...
6252 Specify the variables which are required for this pack‐
6253 age. These may be named in the generated failure message
6254 asking the user to set the missing variable values.
6255 Therefore these should typically be cache entries such as
6256 FOO_LIBRARY and not output variables like FOO_LIBRARIES.
6257 This option is mandatory if HANDLE_COMPONENTS is not
6258 specified.
6259 VERSION_VAR <version-var>
6261 Specify the name of a variable that holds the version of
6262 the package that has been found. This version will be
6263 checked against the (potentially) specified required ver‐
6264 sion given to the find_package() call, including its
6265 EXACT option. The default messages include information
6266 about the required version and the version which has been
6267 actually found, both if the version is ok or not.
6268 HANDLE_VERSION_RANGE
6270 Enable handling of a version range, if one is specified.
6271 Without this option, a developer warning will be dis‐
6272 played if a version range is specified.
6273 HANDLE_COMPONENTS
6275 Enable handling of package components. In this case, the
6276 command will report which components have been found and
6277 which are missing, and the <PackageName>_FOUND variable
6278 will be set to FALSE if any of the required components
6279 (i.e. not the ones listed after the OPTIONAL_COMPONENTS
6280 option of find_package()) are missing.
6281 CONFIG_MODE
6283 Specify that the calling find module is a wrapper around
6284 a call to find_package(<PackageName> NO_MODULE). This
6285 implies a VERSION_VAR value of <PackageName>_VERSION.
6286 The command will automatically check whether the package
6287 configuration file was found.
6288 REASON_FAILURE_MESSAGE <reason-failure-message>
6290 Specify a custom message of the reason for the failure
6291 which will be appended to the default generated message.
6292 FAIL_MESSAGE <custom-failure-message>
6294 Specify a custom failure message instead of using the
6295 default generated message. Not recommended.
6296 NAME_MISMATCHED
6298 Indicate that the <PackageName> does not match
6299 ${CMAKE_FIND_PACKAGE_NAME}. This is usually a mistake and
6300 raises a warning, but it may be intentional for usage of
6301 the command for components of a larger package.
6302 Example for the simple signature:
6304 find_package_handle_standard_args(LibXml2 DEFAULT_MSG
6306 LIBXML2_LIBRARY LIBXML2_INCLUDE_DIR)
6307 The LibXml2 package is considered to be found if both LIBXML2_LIBRARY
6309 and LIBXML2_INCLUDE_DIR are valid. Then also LibXml2_FOUND is set to
6310 TRUE. If it is not found and REQUIRED was used, it fails with a mes‐
6311 sage(FATAL_ERROR), independent whether QUIET was used or not. If it is
6312 found, success will be reported, including the content of the first
6313 <required-var>. On repeated CMake runs, the same message will not be
6314 printed again.
6315 NOTE:
6317 If <PackageName> does not match CMAKE_FIND_PACKAGE_NAME for the
6318 calling module, a warning that there is a mismatch is given. The
6319 FPHSA_NAME_MISMATCHED variable may be set to bypass the warning if
6320 using the old signature and the NAME_MISMATCHED argument using the
6321 new signature. To avoid forcing the caller to require newer versions
6322 of CMake for usage, the variable’s value will be used if defined
6323 when the NAME_MISMATCHED argument is not passed for the new signa‐
6324 ture (but using both is an error)..
6325 Example for the full signature:
6327 find_package_handle_standard_args(LibArchive
6329 REQUIRED_VARS LibArchive_LIBRARY LibArchive_INCLUDE_DIR
6330 VERSION_VAR LibArchive_VERSION)
6331 In this case, the LibArchive package is considered to be found if both
6333 LibArchive_LIBRARY and LibArchive_INCLUDE_DIR are valid. Also the ver‐
6334 sion of LibArchive will be checked by using the version contained in
6335 LibArchive_VERSION. Since no FAIL_MESSAGE is given, the default mes‐
6336 sages will be printed.
6337 Another example for the full signature:
6339 find_package(Automoc4 QUIET NO_MODULE HINTS /opt/automoc4)
6341 find_package_handle_standard_args(Automoc4 CONFIG_MODE)
6342 In this case, a FindAutmoc4.cmake module wraps a call to find_pack‐
6344 age(Automoc4 NO_MODULE) and adds an additional search directory for
6345 automoc4. Then the call to find_package_handle_standard_args produces
6346 a proper success/failure message.
6347 find_package_check_version
6349 Helper function which can be used to check if a <version> is
6350 valid against version-related arguments of find_package().
6351 find_package_check_version(<version> <result-var>
6353 [HANDLE_VERSION_RANGE]
6354 [RESULT_MESSAGE_VARIABLE <message-var>]
6355 )
6356 The <result-var> will hold a boolean value giving the result of
6358 the check.
6359 The options are:
6361 HANDLE_VERSION_RANGE
6363 Enable handling of a version range, if one is specified.
6364 Without this option, a developer warning will be dis‐
6365 played if a version range is specified.
6366 RESULT_MESSAGE_VARIABLE <message-var>
6368 Specify a variable to get back a message describing the
6369 result of the check.
6370 Example for the usage:
6372 find_package_check_version(1.2.3 result HANDLE_VERSION_RANGE
6374 RESULT_MESSAGE_VARIABLE reason)
6375 if (result)
6376 message (STATUS "${reason}")
6377 else()
6378 message (FATAL_ERROR "${reason}")
6379 endif()
6380 FindPackageMessage
6382 find_package_message(<name> "message for user" "find result details")
6383 This function is intended to be used in FindXXX.cmake modules files.
6385 It will print a message once for each unique find result. This is use‐
6386 ful for telling the user where a package was found. The first argument
6387 specifies the name (XXX) of the package. The second argument specifies
6388 the message to display. The third argument lists details about the
6389 find result so that if they change the message will be displayed again.
6390 The macro also obeys the QUIET argument to the find_package command.
6391 Example:
6393 if(X11_FOUND)
6395 find_package_message(X11 "Found X11: ${X11_X11_LIB}"
6396 "[${X11_X11_LIB}][${X11_INCLUDE_DIR}]")
6397 else()
6398 ...
6399 endif()
6400 FortranCInterface
6402 Fortran/C Interface Detection
6403 This module automatically detects the API by which C and Fortran lan‐
6405 guages interact.
6406 Module Variables
6408 Variables that indicate if the mangling is found:
6409 FortranCInterface_GLOBAL_FOUND
6411 Global subroutines and functions.
6412 FortranCInterface_MODULE_FOUND
6414 Module subroutines and functions (declared by “MODULE PROCE‐
6415 DURE”).
6416 This module also provides the following variables to specify the
6418 detected mangling, though a typical use case does not need to reference
6419 them and can use the Module Functions below.
6420 FortranCInterface_GLOBAL_PREFIX
6422 Prefix for a global symbol without an underscore.
6423 FortranCInterface_GLOBAL_SUFFIX
6425 Suffix for a global symbol without an underscore.
6426 FortranCInterface_GLOBAL_CASE
6428 The case for a global symbol without an underscore, either UPPER
6429 or LOWER.
6430 FortranCInterface_GLOBAL__PREFIX
6432 Prefix for a global symbol with an underscore.
6433 FortranCInterface_GLOBAL__SUFFIX
6435 Suffix for a global symbol with an underscore.
6436 FortranCInterface_GLOBAL__CASE
6438 The case for a global symbol with an underscore, either UPPER or
6439 LOWER.
6440 FortranCInterface_MODULE_PREFIX
6442 Prefix for a module symbol without an underscore.
6443 FortranCInterface_MODULE_MIDDLE
6445 Middle of a module symbol without an underscore that appears
6446 between the name of the module and the name of the symbol.
6447 FortranCInterface_MODULE_SUFFIX
6449 Suffix for a module symbol without an underscore.
6450 FortranCInterface_MODULE_CASE
6452 The case for a module symbol without an underscore, either UPPER
6453 or LOWER.
6454 FortranCInterface_MODULE__PREFIX
6456 Prefix for a module symbol with an underscore.
6457 FortranCInterface_MODULE__MIDDLE
6459 Middle of a module symbol with an underscore that appears
6460 between the name of the module and the name of the symbol.
6461 FortranCInterface_MODULE__SUFFIX
6463 Suffix for a module symbol with an underscore.
6464 FortranCInterface_MODULE__CASE
6466 The case for a module symbol with an underscore, either UPPER or
6467 LOWER.
6468 Module Functions
6470 FortranCInterface_HEADER
6471 The FortranCInterface_HEADER function is provided to generate a
6472 C header file containing macros to mangle symbol names:
6473 FortranCInterface_HEADER(<file>
6475 [MACRO_NAMESPACE <macro-ns>]
6476 [SYMBOL_NAMESPACE <ns>]
6477 [SYMBOLS [<module>:]<function> ...])
6478 It generates in <file> definitions of the following macros:
6480 #define FortranCInterface_GLOBAL (name,NAME) ...
6482 #define FortranCInterface_GLOBAL_(name,NAME) ...
6483 #define FortranCInterface_MODULE (mod,name, MOD,NAME) ...
6484 #define FortranCInterface_MODULE_(mod,name, MOD,NAME) ...
6485 These macros mangle four categories of Fortran symbols, respec‐
6487 tively:
6488 · Global symbols without ‘_’: call mysub()
6490 · Global symbols with ‘_’ : call my_sub()
6492 · Module symbols without ‘_’: use mymod; call mysub()
6494 · Module symbols with ‘_’ : use mymod; call my_sub()
6496 If mangling for a category is not known, its macro is left unde‐
6498 fined. All macros require raw names in both lower case and
6499 upper case.
6500 The options are:
6502 MACRO_NAMESPACE
6504 Replace the default FortranCInterface_ prefix with a
6505 given namespace <macro-ns>.
6506 SYMBOLS
6508 List symbols to mangle automatically with C preprocessor
6509 definitions:
6510 <function> ==> #define <ns><function> ...
6512 <module>:<function> ==> #define <ns><module>_<function> ...
6513 If the mangling for some symbol is not known then no pre‐
6515 processor definition is created, and a warning is dis‐
6516 played.
6517 SYMBOL_NAMESPACE
6519 Prefix all preprocessor definitions generated by the SYM‐
6520 BOLS option with a given namespace <ns>.
6521 FortranCInterface_VERIFY
6523 The FortranCInterface_VERIFY function is provided to verify that
6524 the Fortran and C/C++ compilers work together:
6525 FortranCInterface_VERIFY([CXX] [QUIET])
6527 It tests whether a simple test executable using Fortran and C
6529 (and C++ when the CXX option is given) compiles and links suc‐
6530 cessfully. The result is stored in the cache entry FortranCIn‐
6531 terface_VERIFIED_C (or FortranCInterface_VERIFIED_CXX if CXX is
6532 given) as a boolean. If the check fails and QUIET is not given
6533 the function terminates with a fatal error message describing
6534 the problem. The purpose of this check is to stop a build early
6535 for incompatible compiler combinations. The test is built in
6536 the Release configuration.
6537 Example Usage
6539 include(FortranCInterface)
6540 FortranCInterface_HEADER(FC.h MACRO_NAMESPACE "FC_")
6541 This creates a “FC.h” header that defines mangling macros FC_GLOBAL(),
6543 FC_GLOBAL_(), FC_MODULE(), and FC_MODULE_().
6544 include(FortranCInterface)
6546 FortranCInterface_HEADER(FCMangle.h
6547 MACRO_NAMESPACE "FC_"
6548 SYMBOL_NAMESPACE "FC_"
6549 SYMBOLS mysub mymod:my_sub)
6550 This creates a “FCMangle.h” header that defines the same FC_*() man‐
6552 gling macros as the previous example plus preprocessor symbols FC_mysub
6553 and FC_mymod_my_sub.
6554 Additional Manglings
6556 FortranCInterface is aware of possible GLOBAL and MODULE manglings for
6557 many Fortran compilers, but it also provides an interface to specify
6558 new possible manglings. Set the variables:
6559 FortranCInterface_GLOBAL_SYMBOLS
6561 FortranCInterface_MODULE_SYMBOLS
6562 before including FortranCInterface to specify manglings of the symbols
6564 MySub, My_Sub, MyModule:MySub, and My_Module:My_Sub. For example, the
6565 code:
6566 set(FortranCInterface_GLOBAL_SYMBOLS mysub_ my_sub__ MYSUB_)
6568 # ^^^^^ ^^^^^^ ^^^^^
6569 set(FortranCInterface_MODULE_SYMBOLS
6570 __mymodule_MOD_mysub __my_module_MOD_my_sub)
6571 # ^^^^^^^^ ^^^^^ ^^^^^^^^^ ^^^^^^
6572 include(FortranCInterface)
6573 tells FortranCInterface to try given GLOBAL and MODULE manglings. (The
6575 carets point at raw symbol names for clarity in this example but are
6576 not needed.)
6577 GenerateExportHeader
6579 Function for generation of export macros for libraries
6580 This module provides the function GENERATE_EXPORT_HEADER().
6582 The GENERATE_EXPORT_HEADER function can be used to generate a file
6584 suitable for preprocessor inclusion which contains EXPORT macros to be
6585 used in library classes:
6586 GENERATE_EXPORT_HEADER( LIBRARY_TARGET
6588 [BASE_NAME <base_name>]
6589 [EXPORT_MACRO_NAME <export_macro_name>]
6590 [EXPORT_FILE_NAME <export_file_name>]
6591 [DEPRECATED_MACRO_NAME <deprecated_macro_name>]
6592 [NO_EXPORT_MACRO_NAME <no_export_macro_name>]
6593 [INCLUDE_GUARD_NAME <include_guard_name>]
6594 [STATIC_DEFINE <static_define>]
6595 [NO_DEPRECATED_MACRO_NAME <no_deprecated_macro_name>]
6596 [DEFINE_NO_DEPRECATED]
6597 [PREFIX_NAME <prefix_name>]
6598 [CUSTOM_CONTENT_FROM_VARIABLE <variable>]
6599 )
6600 The target properties CXX_VISIBILITY_PRESET and VISIBILITY_INLINES_HID‐
6602 DEN can be used to add the appropriate compile flags for targets. See
6603 the documentation of those target properties, and the convenience vari‐
6604 ables CMAKE_CXX_VISIBILITY_PRESET and CMAKE_VISIBILITY_INLINES_HIDDEN.
6605 By default GENERATE_EXPORT_HEADER() generates macro names in a file
6607 name determined by the name of the library. This means that in the
6608 simplest case, users of GenerateExportHeader will be equivalent to:
6609 set(CMAKE_CXX_VISIBILITY_PRESET hidden)
6611 set(CMAKE_VISIBILITY_INLINES_HIDDEN 1)
6612 add_library(somelib someclass.cpp)
6613 generate_export_header(somelib)
6614 install(TARGETS somelib DESTINATION ${LIBRARY_INSTALL_DIR})
6615 install(FILES
6616 someclass.h
6617 ${PROJECT_BINARY_DIR}/somelib_export.h DESTINATION ${INCLUDE_INSTALL_DIR}
6618 )
6619 And in the ABI header files:
6621 #include "somelib_export.h"
6623 class SOMELIB_EXPORT SomeClass {
6624 ...
6625 };
6626 The CMake fragment will generate a file in the ${CMAKE_CUR‐
6628 RENT_BINARY_DIR} called somelib_export.h containing the macros
6629 SOMELIB_EXPORT, SOMELIB_NO_EXPORT, SOMELIB_DEPRECATED, SOMELIB_DEPRE‐
6630 CATED_EXPORT and SOMELIB_DEPRECATED_NO_EXPORT. They will be followed
6631 by content taken from the variable specified by the CUSTOM_CON‐
6632 TENT_FROM_VARIABLE option, if any. The resulting file should be
6633 installed with other headers in the library.
6634 The BASE_NAME argument can be used to override the file name and the
6636 names used for the macros:
6637 add_library(somelib someclass.cpp)
6639 generate_export_header(somelib
6640 BASE_NAME other_name
6641 )
6642 Generates a file called other_name_export.h containing the macros
6644 OTHER_NAME_EXPORT, OTHER_NAME_NO_EXPORT and OTHER_NAME_DEPRECATED etc.
6645 The BASE_NAME may be overridden by specifying other options in the
6647 function. For example:
6648 add_library(somelib someclass.cpp)
6650 generate_export_header(somelib
6651 EXPORT_MACRO_NAME OTHER_NAME_EXPORT
6652 )
6653 creates the macro OTHER_NAME_EXPORT instead of SOMELIB_EXPORT, but
6655 other macros and the generated file name is as default:
6656 add_library(somelib someclass.cpp)
6658 generate_export_header(somelib
6659 DEPRECATED_MACRO_NAME KDE_DEPRECATED
6660 )
6661 creates the macro KDE_DEPRECATED instead of SOMELIB_DEPRECATED.
6663 If LIBRARY_TARGET is a static library, macros are defined without val‐
6665 ues.
6666 If the same sources are used to create both a shared and a static
6668 library, the uppercased symbol ${BASE_NAME}_STATIC_DEFINE should be
6669 used when building the static library:
6670 add_library(shared_variant SHARED ${lib_SRCS})
6672 add_library(static_variant ${lib_SRCS})
6673 generate_export_header(shared_variant BASE_NAME libshared_and_static)
6674 set_target_properties(static_variant PROPERTIES
6675 COMPILE_FLAGS -DLIBSHARED_AND_STATIC_STATIC_DEFINE)
6676 This will cause the export macros to expand to nothing when building
6678 the static library.
6679 If DEFINE_NO_DEPRECATED is specified, then a macro ${BASE_NAME}_NO_DEP‐
6681 RECATED will be defined This macro can be used to remove deprecated
6682 code from preprocessor output:
6683 option(EXCLUDE_DEPRECATED "Exclude deprecated parts of the library" FALSE)
6685 if (EXCLUDE_DEPRECATED)
6686 set(NO_BUILD_DEPRECATED DEFINE_NO_DEPRECATED)
6687 endif()
6688 generate_export_header(somelib ${NO_BUILD_DEPRECATED})
6689 And then in somelib:
6691 class SOMELIB_EXPORT SomeClass
6693 {
6694 public:
6695 #ifndef SOMELIB_NO_DEPRECATED
6696 SOMELIB_DEPRECATED void oldMethod();
6697 #endif
6698 };
6699 #ifndef SOMELIB_NO_DEPRECATED
6701 void SomeClass::oldMethod() { }
6702 #endif
6703 If PREFIX_NAME is specified, the argument will be used as a prefix to
6705 all generated macros.
6706 For example:
6708 generate_export_header(somelib PREFIX_NAME VTK_)
6710 Generates the macros VTK_SOMELIB_EXPORT etc.
6712 ADD_COMPILER_EXPORT_FLAGS( [<output_variable>] )
6714 The ADD_COMPILER_EXPORT_FLAGS function adds -fvisibility=hidden to
6716 CMAKE_CXX_FLAGS if supported, and is a no-op on Windows which does not
6717 need extra compiler flags for exporting support. You may optionally
6718 pass a single argument to ADD_COMPILER_EXPORT_FLAGS that will be popu‐
6719 lated with the CXX_FLAGS required to enable visibility support for the
6720 compiler/architecture in use.
6721 This function is deprecated. Set the target properties CXX_VISIBIL‐
6723 ITY_PRESET and VISIBILITY_INLINES_HIDDEN instead.
6724 GetPrerequisites
6726 Deprecated since version 3.16: Use file(GET_RUNTIME_DEPENDENCIES)
6727 instead.
6728 Functions to analyze and list executable file prerequisites.
6731 This module provides functions to list the .dll, .dylib or .so files
6733 that an executable or shared library file depends on. (Its prerequi‐
6734 sites.)
6735 It uses various tools to obtain the list of required shared library
6737 files:
6738 dumpbin (Windows)
6740 objdump (MinGW on Windows)
6741 ldd (Linux/Unix)
6742 otool (Mac OSX)
6743 The following functions are provided by this module:
6745 get_prerequisites
6747 list_prerequisites
6748 list_prerequisites_by_glob
6749 gp_append_unique
6750 is_file_executable
6751 gp_item_default_embedded_path
6752 (projects can override with gp_item_default_embedded_path_override)
6753 gp_resolve_item
6754 (projects can override with gp_resolve_item_override)
6755 gp_resolved_file_type
6756 (projects can override with gp_resolved_file_type_override)
6757 gp_file_type
6758 Requires CMake 2.6 or greater because it uses function, break, return
6760 and PARENT_SCOPE.
6761 GET_PREREQUISITES(<target> <prerequisites_var> <exclude_system> <recurse>
6763 <exepath> <dirs> [<rpaths>])
6764 Get the list of shared library files required by <target>. The list in
6766 the variable named <prerequisites_var> should be empty on first entry
6767 to this function. On exit, <prerequisites_var> will contain the list
6768 of required shared library files.
6769 <target> is the full path to an executable file. <prerequisites_var>
6771 is the name of a CMake variable to contain the results. <exclude_sys‐
6772 tem> must be 0 or 1 indicating whether to include or exclude “system”
6773 prerequisites. If <recurse> is set to 1 all prerequisites will be
6774 found recursively, if set to 0 only direct prerequisites are listed.
6775 <exepath> is the path to the top level executable used for @exe‐
6776 cutable_path replacement on the Mac. <dirs> is a list of paths where
6777 libraries might be found: these paths are searched first when a target
6778 without any path info is given. Then standard system locations are
6779 also searched: PATH, Framework locations, /usr/lib…
6780 The variable GET_PREREQUISITES_VERBOSE can be set to true to enable
6782 verbose output.
6783 LIST_PREREQUISITES(<target> [<recurse> [<exclude_system> [<verbose>]]])
6785 Print a message listing the prerequisites of <target>.
6787 <target> is the name of a shared library or executable target or the
6789 full path to a shared library or executable file. If <recurse> is set
6790 to 1 all prerequisites will be found recursively, if set to 0 only
6791 direct prerequisites are listed. <exclude_system> must be 0 or 1 indi‐
6792 cating whether to include or exclude “system” prerequisites. With
6793 <verbose> set to 0 only the full path names of the prerequisites are
6794 printed, set to 1 extra informatin will be displayed.
6795 LIST_PREREQUISITES_BY_GLOB(<glob_arg> <glob_exp>)
6797 Print the prerequisites of shared library and executable files matching
6799 a globbing pattern. <glob_arg> is GLOB or GLOB_RECURSE and <glob_exp>
6800 is a globbing expression used with “file(GLOB” or “file(GLOB_RECURSE”
6801 to retrieve a list of matching files. If a matching file is exe‐
6802 cutable, its prerequisites are listed.
6803 Any additional (optional) arguments provided are passed along as the
6805 optional arguments to the list_prerequisites calls.
6806 GP_APPEND_UNIQUE(<list_var> <value>)
6808 Append <value> to the list variable <list_var> only if the value is not
6810 already in the list.
6811 IS_FILE_EXECUTABLE(<file> <result_var>)
6813 Return 1 in <result_var> if <file> is a binary executable, 0 otherwise.
6815 GP_ITEM_DEFAULT_EMBEDDED_PATH(<item> <default_embedded_path_var>)
6817 Return the path that others should refer to the item by when the item
6819 is embedded inside a bundle.
6820 Override on a per-project basis by providing a project-specific
6822 gp_item_default_embedded_path_override function.
6823 GP_RESOLVE_ITEM(<context> <item> <exepath> <dirs> <resolved_item_var>
6825 [<rpaths>])
6826 Resolve an item into an existing full path file.
6828 Override on a per-project basis by providing a project-specific
6830 gp_resolve_item_override function.
6831 GP_RESOLVED_FILE_TYPE(<original_file> <file> <exepath> <dirs> <type_var>
6833 [<rpaths>])
6834 Return the type of <file> with respect to <original_file>. String
6836 describing type of prerequisite is returned in variable named
6837 <type_var>.
6838 Use <exepath> and <dirs> if necessary to resolve non-absolute <file>
6840 values – but only for non-embedded items.
6841 Possible types are:
6843 system
6845 local
6846 embedded
6847 other
6848 Override on a per-project basis by providing a project-specific
6850 gp_resolved_file_type_override function.
6851 GP_FILE_TYPE(<original_file> <file> <type_var>)
6853 Return the type of <file> with respect to <original_file>. String
6855 describing type of prerequisite is returned in variable named
6856 <type_var>.
6857 Possible types are:
6859 system
6861 local
6862 embedded
6863 other
6864 GNUInstallDirs
6866 Define GNU standard installation directories
6867 Provides install directory variables as defined by the GNU Coding Stan‐
6869 dards.
6870 Result Variables
6872 Inclusion of this module defines the following variables:
6873 CMAKE_INSTALL_<dir>
6875 Destination for files of a given type. This value may be passed to
6876 the DESTINATION options of install() commands for the corresponding
6877 file type.
6878 CMAKE_INSTALL_FULL_<dir>
6880 The absolute path generated from the corresponding
6881 CMAKE_INSTALL_<dir> value. If the value is not already an absolute
6882 path, an absolute path is constructed typically by prepending the
6883 value of the CMAKE_INSTALL_PREFIX variable. However, there are some
6884 special cases as documented below.
6885 where <dir> is one of:
6887 BINDIR user executables (bin)
6889 SBINDIR
6891 system admin executables (sbin)
6892 LIBEXECDIR
6894 program executables (libexec)
6895 SYSCONFDIR
6897 read-only single-machine data (etc)
6898 SHAREDSTATEDIR
6900 modifiable architecture-independent data (com)
6901 LOCALSTATEDIR
6903 modifiable single-machine data (var)
6904 RUNSTATEDIR
6906 run-time variable data (LOCALSTATEDIR/run)
6907 LIBDIR object code libraries (lib or lib64 or lib/<multiarch-tuple> on
6909 Debian)
6910 INCLUDEDIR
6912 C header files (include)
6913 OLDINCLUDEDIR
6915 C header files for non-gcc (/usr/include)
6916 DATAROOTDIR
6918 read-only architecture-independent data root (share)
6919 DATADIR
6921 read-only architecture-independent data (DATAROOTDIR)
6922 INFODIR
6924 info documentation (DATAROOTDIR/info)
6925 LOCALEDIR
6927 locale-dependent data (DATAROOTDIR/locale)
6928 MANDIR man documentation (DATAROOTDIR/man)
6930 DOCDIR documentation root (DATAROOTDIR/doc/PROJECT_NAME)
6932 If the includer does not define a value the above-shown default will be
6934 used and the value will appear in the cache for editing by the user.
6935 Special Cases
6937 The following values of CMAKE_INSTALL_PREFIX are special:
6938 /
6940 For <dir> other than the SYSCONFDIR, LOCALSTATEDIR and RUNSTATEDIR,
6941 the value of CMAKE_INSTALL_<dir> is prefixed with usr/ if it is not
6942 user-specified as an absolute path. For example, the INCLUDEDIR
6943 value include becomes usr/include. This is required by the GNU Cod‐
6944 ing Standards, which state:
6945 When building the complete GNU system, the prefix will be empty
6946 and /usr will be a symbolic link to /.
6947 /usr
6949 For <dir> equal to SYSCONFDIR, LOCALSTATEDIR or RUNSTATEDIR, the
6950 CMAKE_INSTALL_FULL_<dir> is computed by prepending just / to the
6951 value of CMAKE_INSTALL_<dir> if it is not user-specified as an abso‐
6952 lute path. For example, the SYSCONFDIR value etc becomes /etc.
6953 This is required by the GNU Coding Standards.
6954 /opt/...
6956 For <dir> equal to SYSCONFDIR, LOCALSTATEDIR or RUNSTATEDIR, the
6957 CMAKE_INSTALL_FULL_<dir> is computed by appending the prefix to the
6958 value of CMAKE_INSTALL_<dir> if it is not user-specified as an abso‐
6959 lute path. For example, the SYSCONFDIR value etc becomes
6960 /etc/opt/.... This is defined by the Filesystem Hierarchy Standard.
6961 Macros
6963 GNUInstallDirs_get_absolute_install_dir
6964 GNUInstallDirs_get_absolute_install_dir(absvar var)
6966 Set the given variable absvar to the absolute path contained
6968 within the variable var. This is to allow the computation of an
6969 absolute path, accounting for all the special cases documented
6970 above. While this macro is used to compute the various
6971 CMAKE_INSTALL_FULL_<dir> variables, it is exposed publicly to
6972 allow users who create additional path variables to also compute
6973 absolute paths where necessary, using the same logic.
6974 GoogleTest
6976 New in version 3.9.
6977 This module defines functions to help use the Google Test infrastruc‐
6980 ture. Two mechanisms for adding tests are provided. gtest_add_tests()
6981 has been around for some time, originally via find_package(GTest).
6982 gtest_discover_tests() was introduced in CMake 3.10.
6983 The (older) gtest_add_tests() scans source files to identify tests.
6985 This is usually effective, with some caveats, including in cross-com‐
6986 piling environments, and makes setting additional properties on tests
6987 more convenient. However, its handling of parameterized tests is less
6988 comprehensive, and it requires re-running CMake to detect changes to
6989 the list of tests.
6990 The (newer) gtest_discover_tests() discovers tests by asking the com‐
6992 piled test executable to enumerate its tests. This is more robust and
6993 provides better handling of parameterized tests, and does not require
6994 CMake to be re-run when tests change. However, it may not work in a
6995 cross-compiling environment, and setting test properties is less conve‐
6996 nient.
6997 More details can be found in the documentation of the respective func‐
6999 tions.
7000 Both commands are intended to replace use of add_test() to register
7002 tests, and will create a separate CTest test for each Google Test test
7003 case. Note that this is in some cases less efficient, as common set-up
7004 and tear-down logic cannot be shared by multiple test cases executing
7005 in the same instance. However, it provides more fine-grained pass/fail
7006 information to CTest, which is usually considered as more beneficial.
7007 By default, the CTest test name is the same as the Google Test name
7008 (i.e. suite.testcase); see also TEST_PREFIX and TEST_SUFFIX.
7009 gtest_add_tests
7011 Automatically add tests with CTest by scanning source code for
7012 Google Test macros:
7013 gtest_add_tests(TARGET target
7015 [SOURCES src1...]
7016 [EXTRA_ARGS arg1...]
7017 [WORKING_DIRECTORY dir]
7018 [TEST_PREFIX prefix]
7019 [TEST_SUFFIX suffix]
7020 [SKIP_DEPENDENCY]
7021 [TEST_LIST outVar]
7022 )
7023 gtest_add_tests attempts to identify tests by scanning source
7025 files. Although this is generally effective, it uses only a
7026 basic regular expression match, which can be defeated by atypi‐
7027 cal test declarations, and is unable to fully “split” parameter‐
7028 ized tests. Additionally, it requires that CMake be re-run to
7029 discover any newly added, removed or renamed tests (by default,
7030 this means that CMake is re-run when any test source file is
7031 changed, but see SKIP_DEPENDENCY). However, it has the advan‐
7032 tage of declaring tests at CMake time, which somewhat simplifies
7033 setting additional properties on tests, and always works in a
7034 cross-compiling environment.
7035 The options are:
7037 TARGET target
7039 Specifies the Google Test executable, which must be a
7040 known CMake executable target. CMake will substitute the
7041 location of the built executable when running the test.
7042 SOURCES src1...
7044 When provided, only the listed files will be scanned for
7045 test cases. If this option is not given, the SOURCES
7046 property of the specified target will be used to obtain
7047 the list of sources.
7048 EXTRA_ARGS arg1...
7050 Any extra arguments to pass on the command line to each
7051 test case.
7052 WORKING_DIRECTORY dir
7054 Specifies the directory in which to run the discovered
7055 test cases. If this option is not provided, the current
7056 binary directory is used.
7057 TEST_PREFIX prefix
7059 Specifies a prefix to be prepended to the name of each
7060 discovered test case. This can be useful when the same
7061 source files are being used in multiple calls to
7062 gtest_add_test() but with different EXTRA_ARGS.
7063 TEST_SUFFIX suffix
7065 Similar to TEST_PREFIX except the suffix is appended to
7066 the name of every discovered test case. Both TEST_PREFIX
7067 and TEST_SUFFIX may be specified.
7068 SKIP_DEPENDENCY
7070 Normally, the function creates a dependency which will
7071 cause CMake to be re-run if any of the sources being
7072 scanned are changed. This is to ensure that the list of
7073 discovered tests is updated. If this behavior is not
7074 desired (as may be the case while actually writing the
7075 test cases), this option can be used to prevent the
7076 dependency from being added.
7077 TEST_LIST outVar
7079 The variable named by outVar will be populated in the
7080 calling scope with the list of discovered test cases.
7081 This allows the caller to do things like manipulate test
7082 properties of the discovered tests.
7083 include(GoogleTest)
7085 add_executable(FooTest FooUnitTest.cxx)
7086 gtest_add_tests(TARGET FooTest
7087 TEST_SUFFIX .noArgs
7088 TEST_LIST noArgsTests
7089 )
7090 gtest_add_tests(TARGET FooTest
7091 EXTRA_ARGS --someArg someValue
7092 TEST_SUFFIX .withArgs
7093 TEST_LIST withArgsTests
7094 )
7095 set_tests_properties(${noArgsTests} PROPERTIES TIMEOUT 10)
7096 set_tests_properties(${withArgsTests} PROPERTIES TIMEOUT 20)
7097 For backward compatibility, the following form is also sup‐
7099 ported:
7100 gtest_add_tests(exe args files...)
7102 exe The path to the test executable or the name of a CMake
7104 target.
7105 args A ;-list of extra arguments to be passed to executable.
7107 The entire list must be passed as a single argument.
7108 Enclose it in quotes, or pass "" for no arguments.
7109 files...
7111 A list of source files to search for tests and test fix‐
7112 tures. Alternatively, use AUTO to specify that exe is
7113 the name of a CMake executable target whose sources
7114 should be scanned.
7115 include(GoogleTest)
7117 set(FooTestArgs --foo 1 --bar 2)
7118 add_executable(FooTest FooUnitTest.cxx)
7119 gtest_add_tests(FooTest "${FooTestArgs}" AUTO)
7120 gtest_discover_tests
7122 Automatically add tests with CTest by querying the compiled test
7123 executable for available tests:
7124 gtest_discover_tests(target
7126 [EXTRA_ARGS arg1...]
7127 [WORKING_DIRECTORY dir]
7128 [TEST_PREFIX prefix]
7129 [TEST_SUFFIX suffix]
7130 [NO_PRETTY_TYPES] [NO_PRETTY_VALUES]
7131 [PROPERTIES name1 value1...]
7132 [TEST_LIST var]
7133 [DISCOVERY_TIMEOUT seconds]
7134 [XML_OUTPUT_DIR dir]
7135 [DISCOVERY_MODE <POST_BUILD|PRE_TEST>]
7136 )
7137 gtest_discover_tests() sets up a post-build command on the test
7139 executable that generates the list of tests by parsing the out‐
7140 put from running the test with the --gtest_list_tests argument.
7141 Compared to the source parsing approach of gtest_add_tests(),
7142 this ensures that the full list of tests, including instantia‐
7143 tions of parameterized tests, is obtained. Since test discovery
7144 occurs at build time, it is not necessary to re-run CMake when
7145 the list of tests changes. However, it requires that CROSSCOM‐
7146 PILING_EMULATOR is properly set in order to function in a
7147 cross-compiling environment.
7148 Additionally, setting properties on tests is somewhat less con‐
7150 venient, since the tests are not available at CMake time. Addi‐
7151 tional test properties may be assigned to the set of tests as a
7152 whole using the PROPERTIES option. If more fine-grained test
7153 control is needed, custom content may be provided through an
7154 external CTest script using the TEST_INCLUDE_FILES directory
7155 property. The set of discovered tests is made accessible to
7156 such a script via the <target>_TESTS variable.
7157 The options are:
7159 target Specifies the Google Test executable, which must be a
7161 known CMake executable target. CMake will substitute the
7162 location of the built executable when running the test.
7163 EXTRA_ARGS arg1...
7165 Any extra arguments to pass on the command line to each
7166 test case.
7167 WORKING_DIRECTORY dir
7169 Specifies the directory in which to run the discovered
7170 test cases. If this option is not provided, the current
7171 binary directory is used.
7172 TEST_PREFIX prefix
7174 Specifies a prefix to be prepended to the name of each
7175 discovered test case. This can be useful when the same
7176 test executable is being used in multiple calls to
7177 gtest_discover_tests() but with different EXTRA_ARGS.
7178 TEST_SUFFIX suffix
7180 Similar to TEST_PREFIX except the suffix is appended to
7181 the name of every discovered test case. Both TEST_PREFIX
7182 and TEST_SUFFIX may be specified.
7183 NO_PRETTY_TYPES
7185 By default, the type index of type-parameterized tests is
7186 replaced by the actual type name in the CTest test name.
7187 If this behavior is undesirable (e.g. because the type
7188 names are unwieldy), this option will suppress this
7189 behavior.
7190 NO_PRETTY_VALUES
7192 By default, the value index of value-parameterized tests
7193 is replaced by the actual value in the CTest test name.
7194 If this behavior is undesirable (e.g. because the value
7195 strings are unwieldy), this option will suppress this
7196 behavior.
7197 PROPERTIES name1 value1...
7199 Specifies additional properties to be set on all tests
7200 discovered by this invocation of gtest_discover_tests().
7201 TEST_LIST var
7203 Make the list of tests available in the variable var,
7204 rather than the default <target>_TESTS. This can be use‐
7205 ful when the same test executable is being used in multi‐
7206 ple calls to gtest_discover_tests(). Note that this
7207 variable is only available in CTest.
7208 DISCOVERY_TIMEOUT num
7210 Specifies how long (in seconds) CMake will wait for the
7211 test to enumerate available tests. If the test takes
7212 longer than this, discovery (and your build) will fail.
7213 Most test executables will enumerate their tests very
7214 quickly, but under some exceptional circumstances, a test
7215 may require a longer timeout. The default is 5. See
7216 also the TIMEOUT option of execute_process().
7217 NOTE:
7219 In CMake versions 3.10.1 and 3.10.2, this option was
7220 called TIMEOUT. This clashed with the TIMEOUT test
7221 property, which is one of the common properties that
7222 would be set with the PROPERTIES keyword, usually
7223 leading to legal but unintended behavior. The keyword
7224 was changed to DISCOVERY_TIMEOUT in CMake 3.10.3 to
7225 address this problem. The ambiguous behavior of the
7226 TIMEOUT keyword in 3.10.1 and 3.10.2 has not been pre‐
7227 served.
7228 XML_OUTPUT_DIR dir
7230 If specified, the parameter is passed along with
7231 --gtest_output=xml: to test executable. The actual file
7232 name is the same as the test target, including prefix and
7233 suffix. This should be used instead of EXTRA_ARGS
7234 --gtest_output=xml to avoid race conditions writing the
7235 XML result output when using parallel test execution.
7236 DISCOVERY_MODE
7238 Provides greater control over when gtest_discover_tests()
7239 performs test discovery. By default, POST_BUILD sets up a
7240 post-build command to perform test discovery at build
7241 time. In certain scenarios, like cross-compiling, this
7242 POST_BUILD behavior is not desirable. By contrast,
7243 PRE_TEST delays test discovery until just prior to test
7244 execution. This way test discovery occurs in the target
7245 environment where the test has a better chance at finding
7246 appropriate runtime dependencies.
7247 DISCOVERY_MODE defaults to the value of the
7249 CMAKE_GTEST_DISCOVER_TESTS_DISCOVERY_MODE variable if it
7250 is not passed when calling gtest_discover_tests(). This
7251 provides a mechanism for globally selecting a preferred
7252 test discovery behavior without having to modify each
7253 call site.
7254 InstallRequiredSystemLibraries
7256 Include this module to search for compiler-provided system runtime
7257 libraries and add install rules for them. Some optional variables may
7258 be set prior to including the module to adjust behavior:
7259 CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS
7261 Specify additional runtime libraries that may not be detected.
7262 After inclusion any detected libraries will be appended to this.
7263 CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS_SKIP
7265 Set to TRUE to skip calling the install(PROGRAMS) command to
7266 allow the includer to specify its own install rule, using the
7267 value of CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS to get the list of
7268 libraries.
7269 CMAKE_INSTALL_DEBUG_LIBRARIES
7271 Set to TRUE to install the debug runtime libraries when avail‐
7272 able with MSVC tools.
7273 CMAKE_INSTALL_DEBUG_LIBRARIES_ONLY
7275 Set to TRUE to install only the debug runtime libraries with
7276 MSVC tools even if the release runtime libraries are also avail‐
7277 able.
7278 CMAKE_INSTALL_UCRT_LIBRARIES
7280 Set to TRUE to install the Windows Universal CRT libraries for
7281 app-local deployment (e.g. to Windows XP). This is meaningful
7282 only with MSVC from Visual Studio 2015 or higher.
7283 One may set a CMAKE_WINDOWS_KITS_10_DIR environment variable to
7285 an absolute path to tell CMake to look for Windows 10 SDKs in a
7286 custom location. The specified directory is expected to contain
7287 Redist/ucrt/DLLs/* directories.
7288 CMAKE_INSTALL_MFC_LIBRARIES
7290 Set to TRUE to install the MSVC MFC runtime libraries.
7291 CMAKE_INSTALL_OPENMP_LIBRARIES
7293 Set to TRUE to install the MSVC OpenMP runtime libraries
7294 CMAKE_INSTALL_SYSTEM_RUNTIME_DESTINATION
7296 Specify the install(PROGRAMS) command DESTINATION option. If
7297 not specified, the default is bin on Windows and lib elsewhere.
7298 CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS_NO_WARNINGS
7300 Set to TRUE to disable warnings about required library files
7301 that do not exist. (For example, Visual Studio Express editions
7302 may not provide the redistributable files.)
7303 CMAKE_INSTALL_SYSTEM_RUNTIME_COMPONENT
7305 Specify the install(PROGRAMS) command COMPONENT option. If not
7306 specified, no such option will be used.
7307 ProcessorCount
7309 ProcessorCount(var)
7310 Determine the number of processors/cores and save value in ${var}
7312 Sets the variable named ${var} to the number of physical cores avail‐
7314 able on the machine if the information can be determined. Otherwise it
7315 is set to 0. Currently this functionality is implemented for AIX, cyg‐
7316 win, FreeBSD, HPUX, Linux, macOS, QNX, Sun and Windows.
7317 This function is guaranteed to return a positive integer (>=1) if it
7319 succeeds. It returns 0 if there’s a problem determining the processor
7320 count.
7321 Example use, in a ctest -S dashboard script:
7323 include(ProcessorCount)
7325 ProcessorCount(N)
7326 if(NOT N EQUAL 0)
7327 set(CTEST_BUILD_FLAGS -j${N})
7328 set(ctest_test_args ${ctest_test_args} PARALLEL_LEVEL ${N})
7329 endif()
7330 This function is intended to offer an approximation of the value of the
7332 number of compute cores available on the current machine, such that you
7333 may use that value for parallel building and parallel testing. It is
7334 meant to help utilize as much of the machine as seems reasonable. Of
7335 course, knowledge of what else might be running on the machine simulta‐
7336 neously should be used when deciding whether to request a machine’s
7337 full capacity all for yourself.
7338 SelectLibraryConfigurations
7340 select_library_configurations(basename)
7341 This macro takes a library base name as an argument, and will choose
7343 good values for the variables
7344 basename_LIBRARY
7346 basename_LIBRARIES
7347 basename_LIBRARY_DEBUG
7348 basename_LIBRARY_RELEASE
7349 depending on what has been found and set.
7351 If only basename_LIBRARY_RELEASE is defined, basename_LIBRARY will be
7353 set to the release value, and basename_LIBRARY_DEBUG will be set to
7354 basename_LIBRARY_DEBUG-NOTFOUND. If only basename_LIBRARY_DEBUG is
7355 defined, then basename_LIBRARY will take the debug value, and base‐
7356 name_LIBRARY_RELEASE will be set to basename_LIBRARY_RELEASE-NOTFOUND.
7357 If the generator supports configuration types, then basename_LIBRARY
7359 and basename_LIBRARIES will be set with debug and optimized flags spec‐
7360 ifying the library to be used for the given configuration. If no build
7361 type has been set or the generator in use does not support configura‐
7362 tion types, then basename_LIBRARY and basename_LIBRARIES will take only
7363 the release value, or the debug value if the release one is not set.
7364 SquishTestScript
7366 This script launches a GUI test using Squish. You should not call the
7367 script directly; instead, you should access it via the SQUISH_ADD_TEST
7368 macro that is defined in FindSquish.cmake.
7369 This script starts the Squish server, launches the test on the client,
7371 and finally stops the squish server. If any of these steps fail
7372 (including if the tests do not pass) then a fatal error is raised.
7373 TestBigEndian
7375 Define macro to determine endian type
7376 Check if the system is big endian or little endian
7378 TEST_BIG_ENDIAN(VARIABLE)
7380 VARIABLE - variable to store the result to
7381 TestForANSIForScope
7383 Check for ANSI for scope support
7384 Check if the compiler restricts the scope of variables declared in a
7386 for-init-statement to the loop body.
7387 CMAKE_NO_ANSI_FOR_SCOPE - holds result
7389 TestForANSIStreamHeaders
7391 Test for compiler support of ANSI stream headers iostream, etc.
7392 check if the compiler supports the standard ANSI iostream header (with‐
7394 out the .h)
7395 CMAKE_NO_ANSI_STREAM_HEADERS - defined by the results
7397 TestForSSTREAM
7399 Test for compiler support of ANSI sstream header
7400 check if the compiler supports the standard ANSI sstream header
7402 CMAKE_NO_ANSI_STRING_STREAM - defined by the results
7404 TestForSTDNamespace
7406 Test for std:: namespace support
7407 check if the compiler supports std:: on stl classes
7409 CMAKE_NO_STD_NAMESPACE - defined by the results
7411 UseEcos
7413 This module defines variables and macros required to build eCos appli‐
7414 cation.
7415 This file contains the following macros: ECOS_ADD_INCLUDE_DIRECTORIES()
7417 - add the eCos include dirs ECOS_ADD_EXECUTABLE(name source1 … sourceN
7418 ) - create an eCos executable ECOS_ADJUST_DIRECTORY(VAR source1 …
7419 sourceN ) - adjusts the path of the source files and puts the result
7420 into VAR
7421 Macros for selecting the toolchain: ECOS_USE_ARM_ELF_TOOLS() - enable
7423 the ARM ELF toolchain for the directory where it is called
7424 ECOS_USE_I386_ELF_TOOLS() - enable the i386 ELF toolchain for the
7425 directory where it is called ECOS_USE_PPC_EABI_TOOLS() - enable the
7426 PowerPC toolchain for the directory where it is called
7427 It contains the following variables: ECOS_DEFINITIONS ECOSCONFIG_EXE‐
7429 CUTABLE ECOS_CONFIG_FILE - defaults to ecos.ecc, if your eCos configu‐
7430 ration file has a different name, adjust this variable for internal use
7431 only:
7432 ECOS_ADD_TARGET_LIB
7434 UseJava
7436 Use Module for Java
7437 This file provides functions for Java. It is assumed that FindJava has
7439 already been loaded. See FindJava for information on how to load Java
7440 into your CMake project.
7441 Creating And Installing JARs
7443 add_jar(<target_name>
7444 [SOURCES] <source1> [<source2>...] [<resource1>...]
7445 [INCLUDE_JARS <jar1> [<jar2>...]]
7446 [ENTRY_POINT <entry>]
7447 [VERSION <version>]
7448 [OUTPUT_NAME <name>]
7449 [OUTPUT_DIR <dir>]
7450 [GENERATE_NATIVE_HEADERS <target> [DESTINATION <dir>]]
7451 )
7452 This command creates a <target_name>.jar. It compiles the given
7454 <source> files and adds the given <resource> files to the jar file.
7455 Source files can be java files or listing files (prefixed by @). If
7456 only resource files are given then just a jar file is created. The
7457 list of INCLUDE_JARS are added to the classpath when compiling the java
7458 sources and also to the dependencies of the target. INCLUDE_JARS also
7459 accepts other target names created by add_jar(). For backwards compat‐
7460 ibility, jar files listed as sources are ignored (as they have been
7461 since the first version of this module).
7462 The default OUTPUT_DIR can also be changed by setting the variable
7464 CMAKE_JAVA_TARGET_OUTPUT_DIR.
7465 Optionally, using option GENERATE_NATIVE_HEADERS, native header files
7467 can be generated for methods declared as native. These files provide
7468 the connective glue that allow your Java and C code to interact. An
7469 INTERFACE target will be created for an easy usage of generated files.
7470 Sub-option DESTINATION can be used to specify the output directory for
7471 generated header files.
7472 GENERATE_NATIVE_HEADERS option requires, at least, version 1.8 of the
7474 JDK.
7475 The add_jar() function sets the following target properties on <tar‐
7477 get_name>:
7478 INSTALL_FILES
7480 The files which should be installed. This is used by
7481 install_jar().
7482 JNI_SYMLINK
7484 The JNI symlink which should be installed. This is used by
7485 install_jni_symlink().
7486 JAR_FILE
7488 The location of the jar file so that you can include it.
7489 CLASSDIR
7491 The directory where the class files can be found. For example
7492 to use them with javah.
7493 install_jar(<target_name> <destination>)
7495 install_jar(<target_name> DESTINATION <destination> [COMPONENT <component>])
7496 This command installs the <target_name> files to the given <destina‐
7498 tion>. It should be called in the same scope as add_jar() or it will
7499 fail.
7500 The install_jar() function sets the INSTALL_DESTINATION target property
7502 on jars so installed. This property holds the <destination> as
7503 described above, and is used by install_jar_exports(). You can get
7504 this information with get_property() and the INSTALL_DESTINATION prop‐
7505 erty key.
7506 install_jni_symlink(<target_name> <destination>)
7508 install_jni_symlink(<target_name> DESTINATION <destination> [COMPONENT <component>])
7509 This command installs the <target_name> JNI symlinks to the given <des‐
7511 tination>. It should be called in the same scope as add_jar() or it
7512 will fail.
7513 install_jar_exports(TARGETS <jars>...
7515 [NAMESPACE <namespace>]
7516 FILE <filename>
7517 DESTINATION <destination> [COMPONENT <component>])
7518 This command installs a target export file <filename> for the named jar
7520 targets to the given <destination> directory. Its function is similar
7521 to that of install(EXPORTS).
7522 export_jars(TARGETS <jars>...
7524 [NAMESPACE <namespace>]
7525 FILE <filename>)
7526 This command writes a target export file <filename> for the named
7528 <jars> targets. Its function is similar to that of export().
7529 Examples
7531 To add compile flags to the target you can set these flags with the
7532 following variable:
7533 set(CMAKE_JAVA_COMPILE_FLAGS -nowarn)
7535 To add a path or a jar file to the class path you can do this with the
7537 CMAKE_JAVA_INCLUDE_PATH variable.
7538 set(CMAKE_JAVA_INCLUDE_PATH /usr/share/java/shibboleet.jar)
7540 To use a different output name for the target you can set it with:
7542 add_jar(foobar foobar.java OUTPUT_NAME shibboleet.jar)
7544 To use a different output directory than CMAKE_CURRENT_BINARY_DIR you
7546 can set it with:
7547 add_jar(foobar foobar.java OUTPUT_DIR ${PROJECT_BINARY_DIR}/bin)
7549 To define an entry point in your jar you can set it with the
7551 ENTRY_POINT named argument:
7552 add_jar(example ENTRY_POINT com/examples/MyProject/Main)
7554 To define a custom manifest for the jar, you can set it with the MANI‐
7556 FEST named argument:
7557 add_jar(example MANIFEST /path/to/manifest)
7559 To add a version to the target output name you can set it using the
7561 VERSION named argument to add_jar(). The following example will create
7562 a jar file with the name shibboleet-1.0.0.jar and will create a symlink
7563 shibboleet.jar pointing to the jar with the version information.
7564 add_jar(shibboleet shibbotleet.java VERSION 1.2.0)
7566 If the target is a JNI library, utilize the following commands to cre‐
7568 ate a JNI symbolic link:
7569 set(CMAKE_JNI_TARGET TRUE)
7571 add_jar(shibboleet shibbotleet.java VERSION 1.2.0)
7572 install_jar(shibboleet ${LIB_INSTALL_DIR}/shibboleet)
7573 install_jni_symlink(shibboleet ${JAVA_LIB_INSTALL_DIR})
7574 If a single target needs to produce more than one jar from its java
7576 source code, to prevent the accumulation of duplicate class files in
7577 subsequent jars, set/reset CMAKE_JAR_CLASSES_PREFIX prior to calling
7578 the add_jar() function:
7579 set(CMAKE_JAR_CLASSES_PREFIX com/redhat/foo)
7581 add_jar(foo foo.java)
7582 set(CMAKE_JAR_CLASSES_PREFIX com/redhat/bar)
7584 add_jar(bar bar.java)
7585 For an optimum usage of option GENERATE_NATIVE_HEADERS, it is recom‐
7587 mended to include module JNI before any call to add_jar(). The produced
7588 target for native headers can then be used to compile C/C++ sources
7589 with the target_link_libraries() command.
7590 find_package(JNI)
7592 add_jar(foo foo.java GENERATE_NATIVE_HEADERS foo-native)
7593 add_library(bar bar.cpp)
7594 target_link_libraries(bar PRIVATE foo-native)
7595 Finding JARs
7597 find_jar(<VAR>
7598 <name> | NAMES <name1> [<name2>...]
7599 [PATHS <path1> [<path2>... ENV <var>]]
7600 [VERSIONS <version1> [<version2>]]
7601 [DOC "cache documentation string"]
7602 )
7603 This command is used to find a full path to the named jar. A cache
7605 entry named by <VAR> is created to store the result of this command.
7606 If the full path to a jar is found the result is stored in the variable
7607 and the search will not repeated unless the variable is cleared. If
7608 nothing is found, the result will be <VAR>-NOTFOUND, and the search
7609 will be attempted again next time find_jar() is invoked with the same
7610 variable. The name of the full path to a file that is searched for is
7611 specified by the names listed after NAMES argument. Additional search
7612 locations can be specified after the PATHS argument. If you require
7613 special a version of a jar file you can specify it with the VERSIONS
7614 argument. The argument after DOC will be used for the documentation
7615 string in the cache.
7616 Javadoc
7618 The create_javadoc() command can be used to create java documentation
7619 based on files or packages. For more details please read the javadoc
7620 manpage.
7621 There are two main signatures for create_javadoc(). The first signa‐
7623 ture works with package names on a path with source files.
7624 create_javadoc(<VAR>
7626 PACKAGES <pkg1> [<pkg2>...]
7627 [SOURCEPATH <sourcepath>]
7628 [CLASSPATH <classpath>]
7629 [INSTALLPATH <install path>]
7630 [DOCTITLE "the documentation title"]
7631 [WINDOWTITLE "the title of the document"]
7632 [AUTHOR TRUE|FALSE]
7633 [USE TRUE|FALSE]
7634 [VERSION TRUE|FALSE]
7635 )
7636 For example:
7638 create_javadoc(my_example_doc
7640 PACKAGES com.example.foo com.example.bar
7641 SOURCEPATH "${CMAKE_CURRENT_SOURCE_DIR}"
7642 CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH}
7643 WINDOWTITLE "My example"
7644 DOCTITLE "<h1>My example</h1>"
7645 AUTHOR TRUE
7646 USE TRUE
7647 VERSION TRUE
7648 )
7649 The second signature for create_javadoc() works on a given list of
7651 files.
7652 create_javadoc(<VAR>
7654 FILES <file1> [<file2>...]
7655 [CLASSPATH <classpath>]
7656 [INSTALLPATH <install path>]
7657 [DOCTITLE "the documentation title"]
7658 [WINDOWTITLE "the title of the document"]
7659 [AUTHOR TRUE|FALSE]
7660 [USE TRUE|FALSE]
7661 [VERSION TRUE|FALSE]
7662 )
7663 For example:
7665 create_javadoc(my_example_doc
7667 FILES ${example_SRCS}
7668 CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH}
7669 WINDOWTITLE "My example"
7670 DOCTITLE "<h1>My example</h1>"
7671 AUTHOR TRUE
7672 USE TRUE
7673 VERSION TRUE
7674 )
7675 Both signatures share most of the options. These options are the same
7677 as what you can find in the javadoc manpage. Please look at the man‐
7678 page for CLASSPATH, DOCTITLE, WINDOWTITLE, AUTHOR, USE and VERSION.
7679 If you don’t set the INSTALLPATH, then by default the documentation
7681 will be installed to :
7682 ${CMAKE_INSTALL_PREFIX}/share/javadoc/<VAR>
7684 Header Generation
7686 create_javah(TARGET <target> | GENERATED_FILES <VAR>
7687 CLASSES <class>...
7688 [CLASSPATH <classpath>...]
7689 [DEPENDS <depend>...]
7690 [OUTPUT_NAME <path>|OUTPUT_DIR <path>]
7691 )
7692 Create C header files from java classes. These files provide the con‐
7694 nective glue that allow your Java and C code to interact.
7695 Deprecated since version 3.11.
7697 NOTE:
7700 This command will no longer be supported starting with version 10 of
7701 the JDK due to the suppression of javah tool. The add_jar(GENER‐
7702 ATE_NATIVE_HEADERS) command should be used instead.
7703 There are two main signatures for create_javah(). The first signature
7705 returns generated files through variable specified by the GENER‐
7706 ATED_FILES option. For example:
7707 create_javah(GENERATED_FILES files_headers
7709 CLASSES org.cmake.HelloWorld
7710 CLASSPATH hello.jar
7711 )
7712 The second signature for create_javah() creates a target which encapsu‐
7714 lates header files generation. E.g.
7715 create_javah(TARGET target_headers
7717 CLASSES org.cmake.HelloWorld
7718 CLASSPATH hello.jar
7719 )
7720 Both signatures share same options.
7722 CLASSES <class>...
7724 Specifies Java classes used to generate headers.
7725 CLASSPATH <classpath>...
7727 Specifies various paths to look up classes. Here .class files,
7728 jar files or targets created by command add_jar can be used.
7729 DEPENDS <depend>...
7731 Targets on which the javah target depends.
7732 OUTPUT_NAME <path>
7734 Concatenates the resulting header files for all the classes
7735 listed by option CLASSES into <path>. Same behavior as option
7736 -o of javah tool.
7737 OUTPUT_DIR <path>
7739 Sets the directory where the header files will be generated.
7740 Same behavior as option -d of javah tool. If not specified,
7741 CMAKE_CURRENT_BINARY_DIR is used as the output directory.
7742 UseJavaClassFilelist
7744 This script create a list of compiled Java class files to be added to a
7745 jar file. This avoids including cmake files which get created in the
7746 binary directory.
7747 UseJavaSymlinks
7749 Helper script for UseJava.cmake
7750 UseSWIG
7752 This file provides support for SWIG. It is assumed that FindSWIG module
7753 has already been loaded.
7754 Defines the following command for use with SWIG:
7756 swig_add_library
7758 Define swig module with given name and specified language:
7759 swig_add_library(<name>
7761 [TYPE <SHARED|MODULE|STATIC|USE_BUILD_SHARED_LIBS>]
7762 LANGUAGE <language>
7763 [NO_PROXY]
7764 [OUTPUT_DIR <directory>]
7765 [OUTFILE_DIR <directory>]
7766 SOURCES <file>...
7767 )
7768 Targets created with the swig_add_library command have the same
7770 capabilities as targets created with the add_library() command,
7771 so those targets can be used with any command expecting a target
7772 (e.g. target_link_libraries()).
7773 NOTE:
7775 This command creates a target with the specified <name> when
7776 policy CMP0078 is set to NEW. Otherwise, the legacy behavior
7777 will choose a different target name and store it in the
7778 SWIG_MODULE_<name>_REAL_NAME variable.
7779 NOTE:
7781 For multi-config generators, this module does not support
7782 configuration-specific files generated by SWIG. All build
7783 configurations must result in the same generated source file.
7784 NOTE:
7786 For Make-based generators, swig_add_library does not track
7787 file dependencies, so depending on the <name>_swig_compila‐
7788 tion custom target is required for targets which require the
7789 swig-generated files to exist. Other generators may depend on
7790 the source files that would be generated by SWIG.
7791 TYPE SHARED, MODULE and STATIC have the same semantic as for
7793 the add_library() command. If USE_BUILD_SHARED_LIBS is
7794 specified, the library type will be STATIC or SHARED
7795 based on whether the current value of the
7796 BUILD_SHARED_LIBS variable is ON. If no type is speci‐
7797 fied, MODULE will be used.
7798 LANGUAGE
7800 Specify the target language.
7801 NO_PROXY
7803 Prevent the generation of the wrapper layer (swig
7804 -noproxy option).
7805 OUTPUT_DIR
7807 Specify where to write the language specific files (swig
7808 -outdir option). If not given, the CMAKE_SWIG_OUTDIR
7809 variable will be used. If neither is specified, the
7810 default depends on the value of the UseSWIG_MODULE_VER‐
7811 SION variable as follows:
7812 · If UseSWIG_MODULE_VERSION is 1 or is undefined, output
7814 is written to the CMAKE_CURRENT_BINARY_DIR directory.
7815 · If UseSWIG_MODULE_VERSION is 2, a dedicated directory
7817 will be used. The path of this directory can be
7818 retrieved from the SWIG_SUPPORT_FILES_DIRECTORY target
7819 property.
7820 OUTFILE_DIR
7822 Specify an output directory name where the generated
7823 source file will be placed (swig -o option). If not spec‐
7824 ified, the SWIG_OUTFILE_DIR variable will be used. If
7825 neither is specified, OUTPUT_DIR or CMAKE_SWIG_OUTDIR is
7826 used instead.
7827 SOURCES
7829 List of sources for the library. Files with extension .i
7830 will be identified as sources for the SWIG tool. Other
7831 files will be handled in the standard way. This behavior
7832 can be overridden by specifying the variable
7833 SWIG_SOURCE_FILE_EXTENSIONS.
7834 NOTE:
7836 If UseSWIG_MODULE_VERSION is set to 2, it is strongly recom‐
7837 mended to use a dedicated directory unique to the target when
7838 either the OUTPUT_DIR option or the CMAKE_SWIG_OUTDIR vari‐
7839 able are specified. The output directory contents are erased
7840 as part of the target build, so to prevent interference
7841 between targets or losing other important files, each target
7842 should have its own dedicated output directory.
7843 swig_link_libraries
7845 Link libraries to swig module:
7846 swig_link_libraries(<name> <item>...)
7848 This command has same capabilities as target_link_libraries()
7850 command.
7851 NOTE:
7853 If variable UseSWIG_TARGET_NAME_PREFERENCE is set to STAN‐
7854 DARD, this command is deprecated and target_link_libraries()
7855 command must be used instead.
7856 Source file properties on module files must be set before the invoca‐
7858 tion of the swig_add_library command to specify special behavior of
7859 SWIG and ensure generated files will receive the required settings.
7860 CPLUSPLUS
7862 Call SWIG in c++ mode. For example:
7863 set_property(SOURCE mymod.i PROPERTY CPLUSPLUS ON)
7865 swig_add_library(mymod LANGUAGE python SOURCES mymod.i)
7866 INCLUDE_DIRECTORIES, COMPILE_DEFINITIONS and COMPILE_OPTIONS
7868 Add custom flags to SWIG compiler and have same semantic as
7869 properties INCLUDE_DIRECTORIES, COMPILE_DEFINITIONS and COM‐
7870 PILE_OPTIONS.
7871 USE_TARGET_INCLUDE_DIRECTORIES
7873 If set to TRUE, contents of target property INCLUDE_DIRECTORIES
7874 will be forwarded to SWIG compiler. If set to FALSE target
7875 property INCLUDE_DIRECTORIES will be ignored. If not set, target
7876 property SWIG_USE_TARGET_INCLUDE_DIRECTORIES will be considered.
7877 GENERATED_INCLUDE_DIRECTORIES, GENERATED_COMPILE_DEFINITIONS and GENER‐
7879 ATED_COMPILE_OPTIONS
7880 Add custom flags to the C/C++ generated source. They will fill,
7881 respectively, properties INCLUDE_DIRECTORIES, COMPILE_DEFINI‐
7882 TIONS and COMPILE_OPTIONS of generated C/C++ file.
7883 DEPENDS
7885 Specify additional dependencies to the source file.
7886 SWIG_MODULE_NAME
7888 Specify the actual import name of the module in the target lan‐
7889 guage. This is required if it cannot be scanned automatically
7890 from source or different from the module file basename. For
7891 example:
7892 set_property(SOURCE mymod.i PROPERTY SWIG_MODULE_NAME mymod_realname)
7894 NOTE:
7896 If policy CMP0086 is set to NEW, -module <module_name> is
7897 passed to SWIG compiler.
7898 OUTPUT_DIR
7900 Specify where to write the language specific files (swig -outdir
7901 option) for the considered source file. If not specified, the
7902 other ways to define the output directory applies (see OUT‐
7903 PUT_DIR option of swig_add_library() command).
7904 OUTFILE_DIR
7906 Specify an output directory where the generated source file will
7907 be placed (swig -o option) for the considered source file. If
7908 not specified, OUTPUT_DIR source property will be used. If nei‐
7909 ther are specified, the other ways to define output file direc‐
7910 tory applies (see OUTFILE_DIR option of swig_add_library() com‐
7911 mand).
7912 Target library properties can be set to apply same configuration to all
7914 SWIG input files.
7915 SWIG_INCLUDE_DIRECTORIES, SWIG_COMPILE_DEFINITIONS and SWIG_COM‐
7917 PILE_OPTIONS
7918 These properties will be applied to all SWIG input files and
7919 have same semantic as target properties INCLUDE_DIRECTORIES,
7920 COMPILE_DEFINITIONS and COMPILE_OPTIONS.
7921 set (UseSWIG_TARGET_NAME_PREFERENCE STANDARD)
7923 swig_add_library(mymod LANGUAGE python SOURCES mymod.i)
7924 set_property(TARGET mymod PROPERTY SWIG_COMPILE_DEFINITIONS MY_DEF1 MY_DEF2)
7925 set_property(TARGET mymod PROPERTY SWIG_COMPILE_OPTIONS -bla -blb)
7926 SWIG_USE_TARGET_INCLUDE_DIRECTORIES
7928 If set to TRUE, contents of target property INCLUDE_DIRECTORIES
7929 will be forwarded to SWIG compiler. If set to FALSE or not
7930 defined, target property INCLUDE_DIRECTORIES will be ignored.
7931 This behavior can be overridden by specifying source property
7932 USE_TARGET_INCLUDE_DIRECTORIES.
7933 SWIG_GENERATED_INCLUDE_DIRECTORIES, SWIG_GENERATED_COMPILE_DEFINITIONS
7935 and SWIG_GENERATED_COMPILE_OPTIONS
7936 These properties will populate, respectively, properties
7937 INCLUDE_DIRECTORIES, COMPILE_DEFINITIONS and COMPILE_FLAGS of
7938 all generated C/C++ files.
7939 SWIG_DEPENDS
7941 Add dependencies to all SWIG input files.
7942 The following target properties are output properties and can be used
7944 to get information about support files generated by SWIG interface com‐
7945 pilation.
7946 SWIG_SUPPORT_FILES
7948 This output property list of wrapper files generated during SWIG
7949 compilation.
7950 set (UseSWIG_TARGET_NAME_PREFERENCE STANDARD)
7952 swig_add_library(mymod LANGUAGE python SOURCES mymod.i)
7953 get_property(support_files TARGET mymod PROPERTY SWIG_SUPPORT_FILES)
7954 NOTE:
7956 Only most principal support files are listed. In case some
7957 advanced features of SWIG are used (for example %template),
7958 associated support files may not be listed. Prefer to use the
7959 SWIG_SUPPORT_FILES_DIRECTORY property to handle support
7960 files.
7961 SWIG_SUPPORT_FILES_DIRECTORY
7963 This output property specifies the directory where support files
7964 will be generated.
7965 NOTE:
7967 When source property OUTPUT_DIR is defined, multiple directo‐
7968 ries can be specified as part of SWIG_SUPPORT_FILES_DIREC‐
7969 TORY.
7970 Some variables can be set to customize the behavior of swig_add_library
7972 as well as SWIG:
7973 UseSWIG_MODULE_VERSION
7975 Specify different behaviors for UseSWIG module.
7976 · Set to 1 or undefined: Legacy behavior is applied.
7978 · Set to 2: A new strategy is applied regarding support files:
7980 the output directory of support files is erased before SWIG
7981 interface compilation.
7982 CMAKE_SWIG_FLAGS
7984 Add flags to all swig calls.
7985 CMAKE_SWIG_OUTDIR
7987 Specify where to write the language specific files (swig -outdir
7988 option).
7989 SWIG_OUTFILE_DIR
7991 Specify an output directory name where the generated source file
7992 will be placed. If not specified, CMAKE_SWIG_OUTDIR is used.
7993 SWIG_MODULE_<name>_EXTRA_DEPS
7995 Specify extra dependencies for the generated module for <name>.
7996 SWIG_SOURCE_FILE_EXTENSIONS
7998 Specify a list of source file extensions to override the default
7999 behavior of considering only .i files as sources for the SWIG
8000 tool. For example:
8001 set(SWIG_SOURCE_FILE_EXTENSIONS ".i" ".swg")
8003 UsewxWidgets
8005 Convenience include for using wxWidgets library.
8006 Determines if wxWidgets was FOUND and sets the appropriate libs,
8008 incdirs, flags, etc. INCLUDE_DIRECTORIES and LINK_DIRECTORIES are
8009 called.
8010 USAGE
8012 # Note that for MinGW users the order of libs is important!
8014 find_package(wxWidgets REQUIRED net gl core base)
8015 include(${wxWidgets_USE_FILE})
8016 # and for each of your dependent executable/library targets:
8017 target_link_libraries(<YourTarget> ${wxWidgets_LIBRARIES})
8018 DEPRECATED
8020 LINK_LIBRARIES is not called in favor of adding dependencies per target.
8022 AUTHOR
8024 Jan Woetzel <jw -at- mip.informatik.uni-kiel.de>
8026 WriteCompilerDetectionHeader
8028 New in version 3.1.
8029 This module provides the function write_compiler_detection_header().
8032 This function can be used to generate a file suitable for preprocessor
8034 inclusion which contains macros to be used in source code:
8035 write_compiler_detection_header(
8037 FILE <file>
8038 PREFIX <prefix>
8039 [OUTPUT_FILES_VAR <output_files_var> OUTPUT_DIR <output_dir>]
8040 COMPILERS <compiler> [...]
8041 FEATURES <feature> [...]
8042 [BARE_FEATURES <feature> [...]]
8043 [VERSION <version>]
8044 [PROLOG <prolog>]
8045 [EPILOG <epilog>]
8046 [ALLOW_UNKNOWN_COMPILERS]
8047 [ALLOW_UNKNOWN_COMPILER_VERSIONS]
8048 )
8049 This generates the file <file> with macros which all have the prefix
8051 <prefix>.
8052 By default, all content is written directly to the <file>. The OUT‐
8054 PUT_FILES_VAR may be specified to cause the compiler-specific content
8055 to be written to separate files. The separate files are then available
8056 in the <output_files_var> and may be consumed by the caller for instal‐
8057 lation for example. The OUTPUT_DIR specifies a relative path from the
8058 main <file> to the compiler-specific files. For example:
8059 write_compiler_detection_header(
8061 FILE climbingstats_compiler_detection.h
8062 PREFIX ClimbingStats
8063 OUTPUT_FILES_VAR support_files
8064 OUTPUT_DIR compilers
8065 COMPILERS GNU Clang MSVC Intel
8066 FEATURES cxx_variadic_templates
8067 )
8068 install(FILES
8069 ${CMAKE_CURRENT_BINARY_DIR}/climbingstats_compiler_detection.h
8070 DESTINATION include
8071 )
8072 install(FILES
8073 ${support_files}
8074 DESTINATION include/compilers
8075 )
8076 VERSION may be used to specify the API version to be generated. Future
8078 versions of CMake may introduce alternative APIs. A given API is
8079 selected by any <version> value greater than or equal to the version of
8080 CMake that introduced the given API and less than the version of CMake
8081 that introduced its succeeding API. The value of the CMAKE_MINI‐
8082 MUM_REQUIRED_VERSION variable is used if no explicit version is speci‐
8083 fied. (As of CMake version 3.19.7 there is only one API version.)
8084 PROLOG may be specified as text content to write at the start of the
8086 header. EPILOG may be specified as text content to write at the end of
8087 the header
8088 At least one <compiler> and one <feature> must be listed. Compilers
8090 which are known to CMake, but not specified are detected and a pre‐
8091 processor #error is generated for them. A preprocessor macro matching
8092 <PREFIX>_COMPILER_IS_<compiler> is generated for each compiler known to
8093 CMake to contain the value 0 or 1.
8094 Possible compiler identifiers are documented with the CMAKE_<LANG>_COM‐
8096 PILER_ID variable. Available features in this version of CMake are
8097 listed in the CMAKE_C_KNOWN_FEATURES and CMAKE_CXX_KNOWN_FEATURES
8098 global properties. The {c,cxx}_std_* meta-features are ignored if
8099 requested.
8100 See the cmake-compile-features(7) manual for information on compile
8102 features.
8103 BARE_FEATURES will define the compatibility macros with the name used
8105 in newer versions of the language standard, so the code can use the new
8106 feature name unconditionally.
8107 ALLOW_UNKNOWN_COMPILERS and ALLOW_UNKNOWN_COMPILER_VERSIONS cause the
8109 module to generate conditions that treat unknown compilers as simply
8110 lacking all features. Without these options the default behavior is to
8111 generate a #error for unknown compilers and versions.
8112 Feature Test Macros
8114 For each compiler, a preprocessor macro is generated matching <PRE‐
8115 FIX>_COMPILER_IS_<compiler> which has the content either 0 or 1,
8116 depending on the compiler in use. Preprocessor macros for compiler ver‐
8117 sion components are generated matching <PREFIX>_COMPILER_VERSION_MAJOR
8118 <PREFIX>_COMPILER_VERSION_MINOR and <PREFIX>_COMPILER_VERSION_PATCH
8119 containing decimal values for the corresponding compiler version compo‐
8120 nents, if defined.
8121 A preprocessor test is generated based on the compiler version denoting
8123 whether each feature is enabled. A preprocessor macro matching <PRE‐
8124 FIX>_COMPILER_<FEATURE>, where <FEATURE> is the upper-case <feature>
8125 name, is generated to contain the value 0 or 1 depending on whether the
8126 compiler in use supports the feature:
8127 write_compiler_detection_header(
8129 FILE climbingstats_compiler_detection.h
8130 PREFIX ClimbingStats
8131 COMPILERS GNU Clang AppleClang MSVC Intel
8132 FEATURES cxx_variadic_templates
8133 )
8134 #if ClimbingStats_COMPILER_CXX_VARIADIC_TEMPLATES
8136 template<typename... T>
8137 void someInterface(T t...) { /* ... */ }
8138 #else
8139 // Compatibility versions
8140 template<typename T1>
8141 void someInterface(T1 t1) { /* ... */ }
8142 template<typename T1, typename T2>
8143 void someInterface(T1 t1, T2 t2) { /* ... */ }
8144 template<typename T1, typename T2, typename T3>
8145 void someInterface(T1 t1, T2 t2, T3 t3) { /* ... */ }
8146 #endif
8147 Symbol Macros
8149 Some additional symbol-defines are created for particular features for
8150 use as symbols which may be conditionally defined empty:
8151 class MyClass ClimbingStats_FINAL
8153 {
8154 ClimbingStats_CONSTEXPR int someInterface() { return 42; }
8155 };
8156 The ClimbingStats_FINAL macro will expand to final if the compiler (and
8158 its flags) support the cxx_final feature, and the ClimbingStats_CONST‐
8159 EXPR macro will expand to constexpr if cxx_constexpr is supported.
8160 If BARE_FEATURES cxx_final was given as argument the final keyword will
8162 be defined for old compilers, too.
8163 The following features generate corresponding symbol defines and if
8165 they are available as BARE_FEATURES:
8166 ┌──────────────────┬────────────────────┬─────────────┬──────┐
8168 │Feature │ Define │ Symbol │ bare │
8169 ├──────────────────┼────────────────────┼─────────────┼──────┤
8170 │c_restrict │ <PRE‐ │ restrict │ yes │
8171 │ │ FIX>_RESTRICT │ │ │
8172 ├──────────────────┼────────────────────┼─────────────┼──────┤
8173 │cxx_constexpr │ <PREFIX>_CONST‐ │ constexpr │ yes │
8174 │ │ EXPR │ │ │
8175 ├──────────────────┼────────────────────┼─────────────┼──────┤
8176 │cxx_deleted_func‐ │ <PRE‐ │ = delete │ │
8177 │tions │ FIX>_DELETED_FUNC‐ │ │ │
8178 │ │ TION │ │ │
8179 ├──────────────────┼────────────────────┼─────────────┼──────┤
8180 │cxx_extern_tem‐ │ <PRE‐ │ extern │ │
8181 │plates │ FIX>_EXTERN_TEM‐ │ │ │
8182 │ │ PLATE │ │ │
8183 ├──────────────────┼────────────────────┼─────────────┼──────┤
8184 │cxx_final │ <PREFIX>_FINAL │ final │ yes │
8185 ├──────────────────┼────────────────────┼─────────────┼──────┤
8186 │cxx_noexcept │ <PREFIX>_NOEXCEPT │ noexcept │ yes │
8187 ├──────────────────┼────────────────────┼─────────────┼──────┤
8188 │cxx_noexcept │ <PREFIX>_NOEX‐ │ noexcept(X) │ │
8189 │ │ CEPT_EXPR(X) │ │ │
8190 ├──────────────────┼────────────────────┼─────────────┼──────┤
8191 │cxx_override │ <PREFIX>_OVERRIDE │ override │ yes │
8192 └──────────────────┴────────────────────┴─────────────┴──────┘
8193 Compatibility Implementation Macros
8195 Some features are suitable for wrapping in a macro with a backward com‐
8196 patibility implementation if the compiler does not support the feature.
8197 When the cxx_static_assert feature is not provided by the compiler, a
8199 compatibility implementation is available via the <PRE‐
8200 FIX>_STATIC_ASSERT(COND) and <PREFIX>_STATIC_ASSERT_MSG(COND, MSG)
8201 function-like macros. The macros expand to static_assert where that
8202 compiler feature is available, and to a compatibility implementation
8203 otherwise. In the first form, the condition is stringified in the mes‐
8204 sage field of static_assert. In the second form, the message MSG is
8205 passed to the message field of static_assert, or ignored if using the
8206 backward compatibility implementation.
8207 The cxx_attribute_deprecated feature provides a macro definition <PRE‐
8209 FIX>_DEPRECATED, which expands to either the standard [[deprecated]]
8210 attribute or a compiler-specific decorator such as
8211 __attribute__((__deprecated__)) used by GNU compilers.
8212 The cxx_alignas feature provides a macro definition <PREFIX>_ALIGNAS
8214 which expands to either the standard alignas decorator or a com‐
8215 piler-specific decorator such as __attribute__ ((__aligned__)) used by
8216 GNU compilers.
8217 The cxx_alignof feature provides a macro definition <PREFIX>_ALIGNOF
8219 which expands to either the standard alignof decorator or a com‐
8220 piler-specific decorator such as __alignof__ used by GNU compilers.
8221 ┌───────────────────┬────────────────────────┬────────────────┬──────┐
8223 │Feature │ Define │ Symbol │ bare │
8224 ├───────────────────┼────────────────────────┼────────────────┼──────┤
8225 │cxx_alignas │ <PREFIX>_ALIGNAS │ alignas │ │
8226 ├───────────────────┼────────────────────────┼────────────────┼──────┤
8227 │cxx_alignof │ <PREFIX>_ALIGNOF │ alignof │ │
8228 ├───────────────────┼────────────────────────┼────────────────┼──────┤
8229 │cxx_nullptr │ <PREFIX>_NULLPTR │ nullptr │ yes │
8230 └───────────────────┴────────────────────────┴────────────────┴──────┘
8231 │cxx_static_assert │ <PRE‐ │ static_assert │ │
8235 │ │ FIX>_STATIC_ASSERT │ │ │
8236 ├───────────────────┼────────────────────────┼────────────────┼──────┤
8237 │cxx_static_assert │ <PRE‐ │ static_assert │ │
8238 │ │ FIX>_STATIC_ASSERT_MSG │ │ │
8239 ├───────────────────┼────────────────────────┼────────────────┼──────┤
8240 │cxx_attribute_dep‐ │ <PREFIX>_DEPRECATED │ [[deprecated]] │ │
8241 │recated │ │ │ │
8242 ├───────────────────┼────────────────────────┼────────────────┼──────┤
8243 │cxx_attribute_dep‐ │ <PREFIX>_DEPRE‐ │ [[deprecated]] │ │
8244 │recated │ CATED_MSG │ │ │
8245 ├───────────────────┼────────────────────────┼────────────────┼──────┤
8246 │cxx_thread_local │ <PREFIX>_THREAD_LOCAL │ thread_local │ │
8247 └───────────────────┴────────────────────────┴────────────────┴──────┘
8248 A use-case which arises with such deprecation macros is the deprecation
8250 of an entire library. In that case, all public API in the library may
8251 be decorated with the <PREFIX>_DEPRECATED macro. This results in very
8252 noisy build output when building the library itself, so the macro may
8253 be may be defined to empty in that case when building the deprecated
8254 library:
8255 add_library(compat_support ${srcs})
8257 target_compile_definitions(compat_support
8258 PRIVATE
8259 CompatSupport_DEPRECATED=
8260 )
8261
8263 These modules search for third-party software. They are normally
8264 called through the find_package() command.
8265 FindALSA
8267 Find Advanced Linux Sound Architecture (ALSA)
8268 Find the alsa libraries (asound)
8270 IMPORTED Targets
8272 This module defines IMPORTED target ALSA::ALSA, if ALSA has been found.
8273 Result Variables
8275 This module defines the following variables:
8276 ALSA_FOUND
8278 True if ALSA_INCLUDE_DIR & ALSA_LIBRARY are found
8279 ALSA_LIBRARIES
8281 List of libraries when using ALSA.
8282 ALSA_INCLUDE_DIRS
8284 Where to find the ALSA headers.
8285 Cache variables
8287 The following cache variables may also be set:
8288 ALSA_INCLUDE_DIR
8290 the ALSA include directory
8291 ALSA_LIBRARY
8293 the absolute path of the asound library
8294 FindArmadillo
8296 Find the Armadillo C++ library. Armadillo is a library for linear
8297 algebra & scientific computing.
8298 Using Armadillo:
8300 find_package(Armadillo REQUIRED)
8302 include_directories(${ARMADILLO_INCLUDE_DIRS})
8303 add_executable(foo foo.cc)
8304 target_link_libraries(foo ${ARMADILLO_LIBRARIES})
8305 This module sets the following variables:
8307 ARMADILLO_FOUND - set to true if the library is found
8309 ARMADILLO_INCLUDE_DIRS - list of required include directories
8310 ARMADILLO_LIBRARIES - list of libraries to be linked
8311 ARMADILLO_VERSION_MAJOR - major version number
8312 ARMADILLO_VERSION_MINOR - minor version number
8313 ARMADILLO_VERSION_PATCH - patch version number
8314 ARMADILLO_VERSION_STRING - version number as a string (ex: "1.0.4")
8315 ARMADILLO_VERSION_NAME - name of the version (ex: "Antipodean Antileech")
8316 FindASPELL
8318 Try to find ASPELL
8319 Once done this will define
8321 ASPELL_FOUND - system has ASPELL
8323 ASPELL_EXECUTABLE - the ASPELL executable
8324 ASPELL_INCLUDE_DIR - the ASPELL include directory
8325 ASPELL_LIBRARIES - The libraries needed to use ASPELL
8326 ASPELL_DEFINITIONS - Compiler switches required for using ASPELL
8327 FindAVIFile
8329 Locate AVIFILE library and include paths
8330 AVIFILE (http://avifile.sourceforge.net/) is a set of libraries for
8332 i386 machines to use various AVI codecs. Support is limited beyond
8333 Linux. Windows provides native AVI support, and so doesn’t need this
8334 library. This module defines
8335 AVIFILE_INCLUDE_DIR, where to find avifile.h , etc.
8337 AVIFILE_LIBRARIES, the libraries to link against
8338 AVIFILE_DEFINITIONS, definitions to use when compiling
8339 AVIFILE_FOUND, If false, don't try to use AVIFILE
8340 FindBacktrace
8342 Find provider for backtrace(3).
8343 Checks if OS supports backtrace(3) via either libc or custom library.
8345 This module defines the following variables:
8346 Backtrace_HEADER
8348 The header file needed for backtrace(3). Cached. Could be
8349 forcibly set by user.
8350 Backtrace_INCLUDE_DIRS
8352 The include directories needed to use backtrace(3) header.
8353 Backtrace_LIBRARIES
8355 The libraries (linker flags) needed to use backtrace(3), if any.
8356 Backtrace_FOUND
8358 Is set if and only if backtrace(3) support detected.
8359 The following cache variables are also available to set or use:
8361 Backtrace_LIBRARY
8363 The external library providing backtrace, if any.
8364 Backtrace_INCLUDE_DIR
8366 The directory holding the backtrace(3) header.
8367 Typical usage is to generate of header file using configure_file() with
8369 the contents like the following:
8370 #cmakedefine01 Backtrace_FOUND
8372 #if Backtrace_FOUND
8373 # include <${Backtrace_HEADER}>
8374 #endif
8375 And then reference that generated header file in actual source.
8377 FindBISON
8379 Find bison executable and provide a macro to generate custom build
8380 rules.
8381 The module defines the following variables:
8383 BISON_EXECUTABLE
8385 path to the bison program
8386 BISON_VERSION
8388 version of bison
8389 BISON_FOUND
8391 “True” if the program was found
8392 The minimum required version of bison can be specified using the stan‐
8394 dard CMake syntax, e.g. find_package(BISON 2.1.3).
8395 If bison is found, the module defines the macro:
8397 BISON_TARGET(<Name> <YaccInput> <CodeOutput>
8399 [COMPILE_FLAGS <flags>]
8400 [DEFINES_FILE <file>]
8401 [VERBOSE [<file>]]
8402 [REPORT_FILE <file>]
8403 )
8404 which will create a custom rule to generate a parser. <YaccInput> is
8406 the path to a yacc file. <CodeOutput> is the name of the source file
8407 generated by bison. A header file is also be generated, and contains
8408 the token list.
8409 The options are:
8411 COMPILE_FLAGS <flags>
8413 Specify flags to be added to the bison command line.
8414 DEFINES_FILE <file>
8416 Specify a non-default header <file> to be generated by bison.
8417 VERBOSE [<file>]
8419 Tell bison to write a report file of the grammar and parser. If
8420 <file> is given, it specifies path the report file is copied to.
8421 [<file>] is left for backward compatibility of this module. Use
8422 VERBOSE REPORT_FILE <file>.
8423 REPORT_FILE <file>
8425 Specify a non-default report <file>, if generated.
8426 The macro defines the following variables:
8428 BISON_<Name>_DEFINED
8430 True is the macro ran successfully
8431 BISON_<Name>_INPUT
8433 The input source file, an alias for <YaccInput>
8434 BISON_<Name>_OUTPUT_SOURCE
8436 The source file generated by bison
8437 BISON_<Name>_OUTPUT_HEADER
8439 The header file generated by bison
8440 BISON_<Name>_OUTPUTS
8442 All files generated by bison including the source, the header
8443 and the report
8444 BISON_<Name>_COMPILE_FLAGS
8446 Options used in the bison command line
8447 Example usage:
8449 find_package(BISON)
8451 BISON_TARGET(MyParser parser.y ${CMAKE_CURRENT_BINARY_DIR}/parser.cpp
8452 DEFINES_FILE ${CMAKE_CURRENT_BINARY_DIR}/parser.h)
8453 add_executable(Foo main.cpp ${BISON_MyParser_OUTPUTS})
8454 FindBLAS
8456 Find Basic Linear Algebra Subprograms (BLAS) library
8457 This module finds an installed Fortran library that implements the BLAS
8459 linear-algebra interface (see http://www.netlib.org/blas/).
8460 The approach follows that taken for the autoconf macro file,
8462 acx_blas.m4 (distributed at
8463 http://ac-archive.sourceforge.net/ac-archive/acx_blas.html).
8464 Input Variables
8466 The following variables may be set to influence this module’s behavior:
8467 BLA_STATIC
8469 if ON use static linkage
8470 BLA_VENDOR
8472 If set, checks only the specified vendor, if not set checks all
8473 the possibilities. List of vendors valid in this module:
8474 · Goto
8476 · FlexiBLAS
8478 · OpenBLAS
8480 · FLAME
8482 · ATLAS PhiPACK
8484 · CXML
8486 · DXML
8488 · SunPerf
8490 · SCSL
8492 · SGIMATH
8494 · IBMESSL
8496 · Intel10_32 (intel mkl v10 32 bit, threaded code)
8498 · Intel10_64lp (intel mkl v10+ 64 bit, threaded code, lp64
8500 model)
8501 · Intel10_64lp_seq (intel mkl v10+ 64 bit, sequential code, lp64
8503 model)
8504 · Intel10_64ilp (intel mkl v10+ 64 bit, threaded code, ilp64
8506 model)
8507 · Intel10_64ilp_seq (intel mkl v10+ 64 bit, sequential code,
8509 ilp64 model)
8510 · Intel10_64_dyn (intel mkl v10+ 64 bit, single dynamic library)
8512 · Intel (obsolete versions of mkl 32 and 64 bit)
8514 · ACML
8516 · ACML_MP
8518 · ACML_GPU
8520 · Apple
8522 · NAS
8524 · Arm
8526 · Arm_mp
8528 · Arm_ilp64
8530 · Arm_ilp64_mp
8532 · Generic
8534 BLA_F95
8536 if ON tries to find the BLAS95 interfaces
8537 BLA_PREFER_PKGCONFIG
8539 if set pkg-config will be used to search for a BLAS library
8540 first and if one is found that is preferred
8541 Imported targets
8543 This module defines the following IMPORTED target:
8544 BLAS::BLAS
8546 The libraries to use for BLAS, if found.
8547 Result Variables
8549 This module defines the following variables:
8550 BLAS_FOUND
8552 library implementing the BLAS interface is found
8553 BLAS_LINKER_FLAGS
8555 uncached list of required linker flags (excluding -l and -L).
8556 BLAS_LIBRARIES
8558 uncached list of libraries (using full path name) to link
8559 against to use BLAS (may be empty if compiler implicitly links
8560 BLAS)
8561 BLAS95_LIBRARIES
8563 uncached list of libraries (using full path name) to link
8564 against to use BLAS95 interface
8565 BLAS95_FOUND
8567 library implementing the BLAS95 interface is found
8568 NOTE:
8570 C, CXX or Fortran must be enabled to detect a BLAS library. C or
8571 CXX must be enabled to use Intel Math Kernel Library (MKL).
8572 For example, to use Intel MKL libraries and/or Intel compiler:
8574 set(BLA_VENDOR Intel10_64lp)
8576 find_package(BLAS)
8577 Hints
8579 Set the MKLROOT environment variable to a directory that contains an
8580 MKL installation, or add the directory to the dynamic library loader
8581 environment variable for your platform (LIB, DYLD_LIBRARY_PATH or
8582 LD_LIBRARY_PATH).
8583 FindBoost
8585 Find Boost include dirs and libraries
8586 Use this module by invoking find_package with the form:
8588 find_package(Boost
8590 [version] [EXACT] # Minimum or EXACT version e.g. 1.67.0
8591 [REQUIRED] # Fail with error if Boost is not found
8592 [COMPONENTS <libs>...] # Boost libraries by their canonical name
8593 # e.g. "date_time" for "libboost_date_time"
8594 [OPTIONAL_COMPONENTS <libs>...]
8595 # Optional Boost libraries by their canonical name)
8596 ) # e.g. "date_time" for "libboost_date_time"
8597 This module finds headers and requested component libraries OR a CMake
8599 package configuration file provided by a “Boost CMake” build. For the
8600 latter case skip to the “Boost CMake” section below. For the former
8601 case results are reported in variables:
8602 Boost_FOUND - True if headers and requested libraries were found
8604 Boost_INCLUDE_DIRS - Boost include directories
8605 Boost_LIBRARY_DIRS - Link directories for Boost libraries
8606 Boost_LIBRARIES - Boost component libraries to be linked
8607 Boost_<C>_FOUND - True if component <C> was found (<C> is upper-case)
8608 Boost_<C>_LIBRARY - Libraries to link for component <C> (may include
8609 target_link_libraries debug/optimized keywords)
8610 Boost_VERSION_MACRO - BOOST_VERSION value from boost/version.hpp
8611 Boost_VERSION_STRING - Boost version number in x.y.z format
8612 Boost_VERSION - if CMP0093 NEW => same as Boost_VERSION_STRING
8613 if CMP0093 OLD or unset => same as Boost_VERSION_MACRO
8614 Boost_LIB_VERSION - Version string appended to library filenames
8615 Boost_VERSION_MAJOR - Boost major version number (X in X.y.z)
8616 alias: Boost_MAJOR_VERSION
8617 Boost_VERSION_MINOR - Boost minor version number (Y in x.Y.z)
8618 alias: Boost_MINOR_VERSION
8619 Boost_VERSION_PATCH - Boost subminor version number (Z in x.y.Z)
8620 alias: Boost_SUBMINOR_VERSION
8621 Boost_VERSION_COUNT - Amount of version components (3)
8622 Boost_LIB_DIAGNOSTIC_DEFINITIONS (Windows)
8623 - Pass to add_definitions() to have diagnostic
8624 information about Boost's automatic linking
8625 displayed during compilation
8626 Note that Boost Python components require a Python version suffix
8628 (Boost 1.67 and later), e.g. python36 or python27 for the versions
8629 built against Python 3.6 and 2.7, respectively. This also applies to
8630 additional components using Python including mpi_python and numpy.
8631 Earlier Boost releases may use distribution-specific suffixes such as
8632 2, 3 or 2.7. These may also be used as suffixes, but note that they
8633 are not portable.
8634 This module reads hints about search locations from variables:
8636 BOOST_ROOT - Preferred installation prefix
8638 (or BOOSTROOT)
8639 BOOST_INCLUDEDIR - Preferred include directory e.g. <prefix>/include
8640 BOOST_LIBRARYDIR - Preferred library directory e.g. <prefix>/lib
8641 Boost_NO_SYSTEM_PATHS - Set to ON to disable searching in locations not
8642 specified by these hint variables. Default is OFF.
8643 Boost_ADDITIONAL_VERSIONS
8644 - List of Boost versions not known to this module
8645 (Boost install locations may contain the version)
8646 and saves search results persistently in CMake cache entries:
8648 Boost_INCLUDE_DIR - Directory containing Boost headers
8650 Boost_LIBRARY_DIR_RELEASE - Directory containing release Boost libraries
8651 Boost_LIBRARY_DIR_DEBUG - Directory containing debug Boost libraries
8652 Boost_<C>_LIBRARY_DEBUG - Component <C> library debug variant
8653 Boost_<C>_LIBRARY_RELEASE - Component <C> library release variant
8654 The following IMPORTED targets are also defined:
8656 Boost::headers - Target for header-only dependencies
8658 (Boost include directory)
8659 alias: Boost::boost
8660 Boost::<C> - Target for specific component dependency
8661 (shared or static library); <C> is lower-
8662 case
8663 Boost::diagnostic_definitions - interface target to enable diagnostic
8664 information about Boost's automatic linking
8665 during compilation (adds BOOST_LIB_DIAGNOSTIC)
8666 Boost::disable_autolinking - interface target to disable automatic
8667 linking with MSVC (adds BOOST_ALL_NO_LIB)
8668 Boost::dynamic_linking - interface target to enable dynamic linking
8669 linking with MSVC (adds BOOST_ALL_DYN_LINK)
8670 Implicit dependencies such as Boost::filesystem requiring Boost::system
8672 will be automatically detected and satisfied, even if system is not
8673 specified when using find_package() and if Boost::system is not added
8674 to target_link_libraries(). If using Boost::thread, then
8675 Threads::Threads will also be added automatically.
8676 It is important to note that the imported targets behave differently
8678 than variables created by this module: multiple calls to find_pack‐
8679 age(Boost) in the same directory or sub-directories with different
8680 options (e.g. static or shared) will not override the values of the
8681 targets created by the first call.
8682 Users may set these hints or results as CACHE entries. Projects should
8684 not read these entries directly but instead use the above result vari‐
8685 ables. Note that some hint names start in upper-case “BOOST”. One may
8686 specify these as environment variables if they are not specified as
8687 CMake variables or cache entries.
8688 This module first searches for the Boost header files using the above
8690 hint variables (excluding BOOST_LIBRARYDIR) and saves the result in
8691 Boost_INCLUDE_DIR. Then it searches for requested component libraries
8692 using the above hints (excluding BOOST_INCLUDEDIR and Boost_ADDI‐
8693 TIONAL_VERSIONS), “lib” directories near Boost_INCLUDE_DIR, and the
8694 library name configuration settings below. It saves the library direc‐
8695 tories in Boost_LIBRARY_DIR_DEBUG and Boost_LIBRARY_DIR_RELEASE and
8696 individual library locations in Boost_<C>_LIBRARY_DEBUG and
8697 Boost_<C>_LIBRARY_RELEASE. When one changes settings used by previous
8698 searches in the same build tree (excluding environment variables) this
8699 module discards previous search results affected by the changes and
8700 searches again.
8701 Boost libraries come in many variants encoded in their file name.
8703 Users or projects may tell this module which variant to find by setting
8704 variables:
8705 Boost_USE_DEBUG_LIBS - Set to ON or OFF to specify whether to search
8707 and use the debug libraries. Default is ON.
8708 Boost_USE_RELEASE_LIBS - Set to ON or OFF to specify whether to search
8709 and use the release libraries. Default is ON.
8710 Boost_USE_MULTITHREADED - Set to OFF to use the non-multithreaded
8711 libraries ('mt' tag). Default is ON.
8712 Boost_USE_STATIC_LIBS - Set to ON to force the use of the static
8713 libraries. Default is OFF.
8714 Boost_USE_STATIC_RUNTIME - Set to ON or OFF to specify whether to use
8715 libraries linked statically to the C++ runtime
8716 ('s' tag). Default is platform dependent.
8717 Boost_USE_DEBUG_RUNTIME - Set to ON or OFF to specify whether to use
8718 libraries linked to the MS debug C++ runtime
8719 ('g' tag). Default is ON.
8720 Boost_USE_DEBUG_PYTHON - Set to ON to use libraries compiled with a
8721 debug Python build ('y' tag). Default is OFF.
8722 Boost_USE_STLPORT - Set to ON to use libraries compiled with
8723 STLPort ('p' tag). Default is OFF.
8724 Boost_USE_STLPORT_DEPRECATED_NATIVE_IOSTREAMS
8725 - Set to ON to use libraries compiled with
8726 STLPort deprecated "native iostreams"
8727 ('n' tag). Default is OFF.
8728 Boost_COMPILER - Set to the compiler-specific library suffix
8729 (e.g. "-gcc43"). Default is auto-computed
8730 for the C++ compiler in use. A list may be
8731 used if multiple compatible suffixes should
8732 be tested for, in decreasing order of
8733 preference.
8734 Boost_LIB_PREFIX - Set to the platform-specific library name
8735 prefix (e.g. "lib") used by Boost static libs.
8736 This is needed only on platforms where CMake
8737 does not know the prefix by default.
8738 Boost_ARCHITECTURE - Set to the architecture-specific library suffix
8739 (e.g. "-x64"). Default is auto-computed for the
8740 C++ compiler in use.
8741 Boost_THREADAPI - Suffix for "thread" component library name,
8742 such as "pthread" or "win32". Names with
8743 and without this suffix will both be tried.
8744 Boost_NAMESPACE - Alternate namespace used to build boost with
8745 e.g. if set to "myboost", will search for
8746 myboost_thread instead of boost_thread.
8747 Other variables one may set to control this module are:
8749 Boost_DEBUG - Set to ON to enable debug output from FindBoost.
8751 Please enable this before filing any bug report.
8752 Boost_REALPATH - Set to ON to resolve symlinks for discovered
8753 libraries to assist with packaging. For example,
8754 the "system" component library may be resolved to
8755 "/usr/lib/libboost_system.so.1.67.0" instead of
8756 "/usr/lib/libboost_system.so". This does not
8757 affect linking and should not be enabled unless
8758 the user needs this information.
8759 Boost_LIBRARY_DIR - Default value for Boost_LIBRARY_DIR_RELEASE and
8760 Boost_LIBRARY_DIR_DEBUG.
8761 On Visual Studio and Borland compilers Boost headers request automatic
8763 linking to corresponding libraries. This requires matching libraries
8764 to be linked explicitly or available in the link library search path.
8765 In this case setting Boost_USE_STATIC_LIBS to OFF may not achieve
8766 dynamic linking. Boost automatic linking typically requests static
8767 libraries with a few exceptions (such as Boost.Python). Use:
8768 add_definitions(${Boost_LIB_DIAGNOSTIC_DEFINITIONS})
8770 to ask Boost to report information about automatic linking requests.
8772 Example to find Boost headers only:
8774 find_package(Boost 1.36.0)
8776 if(Boost_FOUND)
8777 include_directories(${Boost_INCLUDE_DIRS})
8778 add_executable(foo foo.cc)
8779 endif()
8780 Example to find Boost libraries and use imported targets:
8782 find_package(Boost 1.56 REQUIRED COMPONENTS
8784 date_time filesystem iostreams)
8785 add_executable(foo foo.cc)
8786 target_link_libraries(foo Boost::date_time Boost::filesystem
8787 Boost::iostreams)
8788 Example to find Boost Python 3.6 libraries and use imported targets:
8790 find_package(Boost 1.67 REQUIRED COMPONENTS
8792 python36 numpy36)
8793 add_executable(foo foo.cc)
8794 target_link_libraries(foo Boost::python36 Boost::numpy36)
8795 Example to find Boost headers and some static (release only) libraries:
8797 set(Boost_USE_STATIC_LIBS ON) # only find static libs
8799 set(Boost_USE_DEBUG_LIBS OFF) # ignore debug libs and
8800 set(Boost_USE_RELEASE_LIBS ON) # only find release libs
8801 set(Boost_USE_MULTITHREADED ON)
8802 set(Boost_USE_STATIC_RUNTIME OFF)
8803 find_package(Boost 1.66.0 COMPONENTS date_time filesystem system ...)
8804 if(Boost_FOUND)
8805 include_directories(${Boost_INCLUDE_DIRS})
8806 add_executable(foo foo.cc)
8807 target_link_libraries(foo ${Boost_LIBRARIES})
8808 endif()
8809 Boost CMake
8811 If Boost was built using the boost-cmake project or from Boost 1.70.0
8812 on it provides a package configuration file for use with find_package’s
8813 config mode. This module looks for the package configuration file
8814 called BoostConfig.cmake or boost-config.cmake and stores the result in
8815 CACHE entry “Boost_DIR”. If found, the package configuration file is
8816 loaded and this module returns with no further action. See documenta‐
8817 tion of the Boost CMake package configuration for details on what it
8818 provides.
8819 Set Boost_NO_BOOST_CMAKE to ON, to disable the search for boost-cmake.
8821 FindBullet
8823 Try to find the Bullet physics engine
8824 This module defines the following variables
8826 BULLET_FOUND - Was bullet found
8828 BULLET_INCLUDE_DIRS - the Bullet include directories
8829 BULLET_LIBRARIES - Link to this, by default it includes
8830 all bullet components (Dynamics,
8831 Collision, LinearMath, & SoftBody)
8832 This module accepts the following variables
8834 BULLET_ROOT - Can be set to bullet install path or Windows build path
8836 FindBZip2
8838 Try to find BZip2
8839 IMPORTED Targets
8841 This module defines IMPORTED target BZip2::BZip2, if BZip2 has been
8842 found.
8843 Result Variables
8845 This module defines the following variables:
8846 BZIP2_FOUND
8848 system has BZip2
8849 BZIP2_INCLUDE_DIRS
8851 the BZip2 include directories
8852 BZIP2_LIBRARIES
8854 Link these to use BZip2
8855 BZIP2_NEED_PREFIX
8857 this is set if the functions are prefixed with BZ2_
8858 BZIP2_VERSION_STRING
8860 the version of BZip2 found
8861 Cache variables
8863 The following cache variables may also be set:
8864 BZIP2_INCLUDE_DIR
8866 the BZip2 include directory
8867 FindCABLE
8869 Find CABLE
8870 This module finds if CABLE is installed and determines where the
8872 include files and libraries are. This code sets the following vari‐
8873 ables:
8874 CABLE the path to the cable executable
8876 CABLE_TCL_LIBRARY the path to the Tcl wrapper library
8877 CABLE_INCLUDE_DIR the path to the include directory
8878 To build Tcl wrappers, you should add shared library and link it to
8880 ${CABLE_TCL_LIBRARY}. You should also add ${CABLE_INCLUDE_DIR} as an
8881 include directory.
8882 FindCoin3D
8884 Find Coin3D (Open Inventor)
8885 Coin3D is an implementation of the Open Inventor API. It provides data
8887 structures and algorithms for 3D visualization.
8888 This module defines the following variables
8890 COIN3D_FOUND - system has Coin3D - Open Inventor
8892 COIN3D_INCLUDE_DIRS - where the Inventor include directory can be found
8893 COIN3D_LIBRARIES - Link to this to use Coin3D
8894 FindCUDAToolkit
8896 New in version 3.17.
8897 This script locates the NVIDIA CUDA toolkit and the associated
8900 libraries, but does not require the CUDA language be enabled for a
8901 given project. This module does not search for the NVIDIA CUDA Samples.
8902 Search Behavior
8904 The CUDA Toolkit search behavior uses the following order:
8905 1. If the CUDA language has been enabled we will use the directory con‐
8907 taining the compiler as the first search location for nvcc.
8908 2. If the CUDAToolkit_ROOT cmake configuration variable (e.g., -DCUDA‐
8910 Toolkit_ROOT=/some/path) or environment variable is defined, it will
8911 be searched. If both an environment variable and a configuration
8912 variable are specified, the configuration variable takes precedence.
8913 The directory specified here must be such that the executable nvcc
8915 or the appropriate version.txt file can be found underneath the
8916 specified directory.
8917 3. If the CUDA_PATH environment variable is defined, it will be
8919 searched for nvcc.
8920 4. The user’s path is searched for nvcc using find_program(). If this
8922 is found, no subsequent search attempts are performed. Users are
8923 responsible for ensuring that the first nvcc to show up in the path
8924 is the desired path in the event that multiple CUDA Toolkits are
8925 installed.
8926 5. On Unix systems, if the symbolic link /usr/local/cuda exists, this
8928 is used. No subsequent search attempts are performed. No default
8929 symbolic link location exists for the Windows platform.
8930 6. The platform specific default install locations are searched. If
8932 exactly one candidate is found, this is used. The default CUDA
8933 Toolkit install locations searched are:
8934 ┌───────────┬────────────────────────────┐
8936 │Platform │ Search Pattern │
8937 ├───────────┼────────────────────────────┤
8938 │macOS │ /Developer/NVIDIA/CUDA-X.Y │
8939 ├───────────┼────────────────────────────┤
8940 │Other Unix │ /usr/local/cuda-X.Y │
8941 ├───────────┼────────────────────────────┤
8942 │Windows │ C:\Program Files\NVIDIA │
8943 │ │ GPU Computing Tool‐ │
8944 │ │ kit\CUDA\vX.Y │
8945 └───────────┴────────────────────────────┘
8946 Where X.Y would be a specific version of the CUDA Toolkit, such as
8948 /usr/local/cuda-9.0 or C:\Program Files\NVIDIA GPU Computing Tool‐
8949 kit\CUDA\v9.0
8950 NOTE:
8952 When multiple CUDA Toolkits are installed in the default location
8953 of a system (e.g., both /usr/local/cuda-9.0 and
8954 /usr/local/cuda-10.0 exist but the /usr/local/cuda symbolic link
8955 does not exist), this package is marked as not found.
8956 There are too many factors involved in making an automatic deci‐
8958 sion in the presence of multiple CUDA Toolkits being installed.
8959 In this situation, users are encouraged to either (1) set CUDA‐
8960 Toolkit_ROOT [22mor (2) ensure that the correct nvcc executable shows
8961 up in $PATH for find_program() to find.
8962 Options
8964 VERSION
8965 If specified, describes the version of the CUDA Toolkit to
8966 search for.
8967 REQUIRED
8969 If specified, configuration will error if a suitable CUDA Tool‐
8970 kit is not found.
8971 QUIET If specified, the search for a suitable CUDA Toolkit will not
8973 produce any messages.
8974 EXACT If specified, the CUDA Toolkit is considered found only if the
8976 exact VERSION specified is recovered.
8977 Imported targets
8979 An imported target named CUDA::toolkit is provided.
8980 This module defines IMPORTED targets for each of the following
8982 libraries that are part of the CUDAToolkit:
8983 · CUDA Runtime Library
8985 · CUDA Driver Library
8987 · cuBLAS
8989 · cuFFT
8991 · cuRAND
8993 · cuSOLVER
8995 · cuSPARSE
8997 · cuPTI
8999 · NPP
9001 · nvBLAS
9003 · nvGRAPH
9005 · nvJPEG
9007 · nvidia-ML
9009 · nvRTC
9011 · nvToolsExt
9013 · OpenCL
9015 · cuLIBOS
9017 CUDA Runtime Library
9019 The CUDA Runtime library (cudart) are what most applications will typi‐
9020 cally need to link against to make any calls such as cudaMalloc, and
9021 cudaFree.
9022 Targets Created:
9024 · CUDA::cudart
9026 · CUDA::cudart_static
9028 CUDA Driver Library
9030 The CUDA Driver library (cuda) are used by applications that use calls
9031 such as cuMemAlloc, and cuMemFree. This is generally used by advanced
9032 Targets Created:
9034 · CUDA::cuda_driver
9036 · CUDA::cuda_driver
9038 cuBLAS
9040 The cuBLAS library.
9041 Targets Created:
9043 · CUDA::cublas
9045 · CUDA::cublas_static
9047 · CUDA::cublasLt starting in CUDA 10.1
9049 · CUDA::cublasLt_static starting in CUDA 10.1
9051 cuFFT
9053 The cuFFT library.
9054 Targets Created:
9056 · CUDA::cufft
9058 · CUDA::cufftw
9060 · CUDA::cufft_static
9062 · CUDA::cufftw_static
9064 cuRAND
9066 The cuRAND library.
9067 Targets Created:
9069 · CUDA::curand
9071 · CUDA::curand_static
9073 cuSOLVER
9075 The cuSOLVER library.
9076 Targets Created:
9078 · CUDA::cusolver
9080 · CUDA::cusolver_static
9082 cuSPARSE
9084 The cuSPARSE library.
9085 Targets Created:
9087 · CUDA::cusparse
9089 · CUDA::cusparse_static
9091 cupti
9093 The NVIDIA CUDA Profiling Tools Interface.
9094 Targets Created:
9096 · CUDA::cupti
9098 · CUDA::cupti_static
9100 NPP
9102 The NPP libraries.
9103 Targets Created:
9105 · nppc:
9107 · CUDA::nppc
9109 · CUDA::nppc_static
9111 · nppial: Arithmetic and logical operation functions in nppi_arith‐
9113 metic_and_logical_operations.h
9114 · CUDA::nppial
9116 · CUDA::nppial_static
9118 · nppicc: Color conversion and sampling functions in nppi_color_conver‐
9120 sion.h
9121 · CUDA::nppicc
9123 · CUDA::nppicc_static
9125 · nppicom: JPEG compression and decompression functions in nppi_com‐
9127 pression_functions.h Removed starting in CUDA 11.0, use nvJPEG
9128 instead.
9129 · CUDA::nppicom
9131 · CUDA::nppicom_static
9133 · nppidei: Data exchange and initialization functions in
9135 nppi_data_exchange_and_initialization.h
9136 · CUDA::nppidei
9138 · CUDA::nppidei_static
9140 · nppif: Filtering and computer vision functions in nppi_filter_func‐
9142 tions.h
9143 · CUDA::nppif
9145 · CUDA::nppif_static
9147 · nppig: Geometry transformation functions found in nppi_geome‐
9149 try_transforms.h
9150 · CUDA::nppig
9152 · CUDA::nppig_static
9154 · nppim: Morphological operation functions found in nppi_morphologi‐
9156 cal_operations.h
9157 · CUDA::nppim
9159 · CUDA::nppim_static
9161 · nppist: Statistics and linear transform in nppi_statistics_func‐
9163 tions.h and nppi_linear_transforms.h
9164 · CUDA::nppist
9166 · CUDA::nppist_static
9168 · nppisu: Memory support functions in nppi_support_functions.h
9170 · CUDA::nppisu
9172 · CUDA::nppisu_static
9174 · nppitc: Threshold and compare operation functions in nppi_thresh‐
9176 old_and_compare_operations.h
9177 · CUDA::nppitc
9179 · CUDA::nppitc_static
9181 · npps:
9183 · CUDA::npps
9185 · CUDA::npps_static
9187 nvBLAS
9189 The nvBLAS libraries. This is a shared library only.
9190 Targets Created:
9192 · CUDA::nvblas
9194 nvGRAPH
9196 The nvGRAPH library. Removed starting in CUDA 11.0
9197 Targets Created:
9199 · CUDA::nvgraph
9201 · CUDA::nvgraph_static
9203 nvJPEG
9205 The nvJPEG library. Introduced in CUDA 10.
9206 Targets Created:
9208 · CUDA::nvjpeg
9210 · CUDA::nvjpeg_static
9212 nvRTC
9214 The nvRTC (Runtime Compilation) library. This is a shared library
9215 only.
9216 Targets Created:
9218 · CUDA::nvrtc
9220 nvidia-ML
9222 The NVIDIA Management Library. This is a shared library only.
9223 Targets Created:
9225 · CUDA::nvml
9227 nvToolsExt
9229 The NVIDIA Tools Extension. This is a shared library only.
9230 Targets Created:
9232 · CUDA::nvToolsExt
9234 OpenCL
9236 The NVIDIA OpenCL Library. This is a shared library only.
9237 Targets Created:
9239 · CUDA::OpenCL
9241 cuLIBOS
9243 The cuLIBOS library is a backend thread abstraction layer library which
9244 is static only. The CUDA::cublas_static, CUDA::cusparse_static,
9245 CUDA::cufft_static, CUDA::curand_static, and (when implemented) NPP
9246 libraries all automatically have this dependency linked.
9247 Target Created:
9249 · CUDA::culibos
9251 Note: direct usage of this target by consumers should not be necessary.
9253 Result variables
9255 CUDAToolkit_FOUND
9256 A boolean specifying whether or not the CUDA Toolkit was found.
9257 CUDAToolkit_VERSION
9259 The exact version of the CUDA Toolkit found (as reported by nvcc
9260 --version or version.txt).
9261 CUDAToolkit_VERSION_MAJOR
9263 The major version of the CUDA Toolkit.
9264 CUDAToolkit_VERSION_MAJOR
9266 The minor version of the CUDA Toolkit.
9267 CUDAToolkit_VERSION_PATCH
9269 The patch version of the CUDA Toolkit.
9270 CUDAToolkit_BIN_DIR
9272 The path to the CUDA Toolkit library directory that contains the
9273 CUDA executable nvcc.
9274 CUDAToolkit_INCLUDE_DIRS
9276 The path to the CUDA Toolkit include folder containing the
9277 header files required to compile a project linking against CUDA.
9278 CUDAToolkit_LIBRARY_DIR
9280 The path to the CUDA Toolkit library directory that contains the
9281 CUDA Runtime library cudart.
9282 CUDAToolkit_LIBRARY_ROOT
9284 The path to the CUDA Toolkit directory containing the nvvm
9285 directory and version.txt.
9286 CUDAToolkit_TARGET_DIR
9288 The path to the CUDA Toolkit directory including the target
9289 architecture when cross-compiling. When not cross-compiling this
9290 will be equivalent to the parent directory of CUDA‐
9291 Toolkit_BIN_DIR.
9292 CUDAToolkit_NVCC_EXECUTABLE
9294 The path to the NVIDIA CUDA compiler nvcc. Note that this path
9295 may not be the same as CMAKE_CUDA_COMPILER. nvcc must be found
9296 to determine the CUDA Toolkit version as well as determining
9297 other features of the Toolkit. This variable is set for the
9298 convenience of modules that depend on this one.
9299 FindCups
9301 Find the Common UNIX Printing System (CUPS).
9302 Set CUPS_REQUIRE_IPP_DELETE_ATTRIBUTE to TRUE if you need a version
9304 which features this function (i.e. at least 1.1.19)
9305 Imported targets
9307 This module defines IMPORTED target Cups::Cups, if Cups has been found.
9308 Result variables
9310 This module will set the following variables in your project:
9311 CUPS_FOUND
9313 true if CUPS headers and libraries were found
9314 CUPS_INCLUDE_DIRS
9316 the directory containing the Cups headers
9317 CUPS_LIBRARIES
9319 the libraries to link against to use CUPS.
9320 CUPS_VERSION_STRING
9322 the version of CUPS found (since CMake 2.8.8)
9323 Cache variables
9325 The following cache variables may also be set:
9326 CUPS_INCLUDE_DIR
9328 the directory containing the Cups headers
9329 FindCURL
9331 Find the native CURL headers and libraries.
9332 This module accept optional COMPONENTS to check supported features and
9334 protocols:
9335 PROTOCOLS: ICT FILE FTP FTPS GOPHER HTTP HTTPS IMAP IMAPS LDAP LDAPS POP3
9337 POP3S RTMP RTSP SCP SFTP SMB SMBS SMTP SMTPS TELNET TFTP
9338 FEATURES: SSL IPv6 UnixSockets libz AsynchDNS IDN GSS-API PSL SPNEGO
9339 Kerberos NTLM NTLM_WB TLS-SRP HTTP2 HTTPS-proxy
9340 IMPORTED Targets
9342 This module defines IMPORTED target CURL::libcurl, if curl has been
9343 found.
9344 Result Variables
9346 This module defines the following variables:
9347 CURL_FOUND
9349 “True” if curl found.
9350 CURL_INCLUDE_DIRS
9352 where to find curl/curl.h, etc.
9353 CURL_LIBRARIES
9355 List of libraries when using curl.
9356 CURL_VERSION_STRING
9358 The version of curl found.
9359 CURL CMake
9361 If CURL was built using the CMake buildsystem then it provides its own
9362 CURLConfig.cmake file for use with the find_package() command’s config
9363 mode. This module looks for this file and, if found, returns its
9364 results with no further action.
9365 Set CURL_NO_CURL_CMAKE to ON to disable this search.
9367 FindCurses
9369 Find the curses or ncurses include file and library.
9370 Result Variables
9372 This module defines the following variables:
9373 CURSES_FOUND
9375 True if Curses is found.
9376 CURSES_INCLUDE_DIRS
9378 The include directories needed to use Curses.
9379 CURSES_LIBRARIES
9381 The libraries needed to use Curses.
9382 CURSES_CFLAGS
9384 Parameters which ought be given to C/C++ compilers when using
9385 Curses.
9386 CURSES_HAVE_CURSES_H
9388 True if curses.h is available.
9389 CURSES_HAVE_NCURSES_H
9391 True if ncurses.h is available.
9392 CURSES_HAVE_NCURSES_NCURSES_H
9394 True if ncurses/ncurses.h is available.
9395 CURSES_HAVE_NCURSES_CURSES_H
9397 True if ncurses/curses.h is available.
9398 Set CURSES_NEED_NCURSES to TRUE before the find_package(Curses) call if
9400 NCurses functionality is required. Set CURSES_NEED_WIDE to TRUE before
9401 the find_package(Curses) call if unicode functionality is required.
9402 Backward Compatibility
9404 The following variable are provided for backward compatibility:
9405 CURSES_INCLUDE_DIR
9407 Path to Curses include. Use CURSES_INCLUDE_DIRS instead.
9408 CURSES_LIBRARY
9410 Path to Curses library. Use CURSES_LIBRARIES instead.
9411 FindCVS
9413 Find the Concurrent Versions System (CVS).
9414 The module defines the following variables:
9416 CVS_EXECUTABLE - path to cvs command line client
9418 CVS_FOUND - true if the command line client was found
9419 Example usage:
9421 find_package(CVS)
9423 if(CVS_FOUND)
9424 message("CVS found: ${CVS_EXECUTABLE}")
9425 endif()
9426 FindCxxTest
9428 Find CxxTest unit testing framework.
9429 Find the CxxTest suite and declare a helper macro for creating unit
9431 tests and integrating them with CTest. For more details on CxxTest see
9432 http://cxxtest.tigris.org
9433 INPUT Variables
9435 CXXTEST_USE_PYTHON [deprecated since 1.3]
9437 Only used in the case both Python & Perl
9438 are detected on the system to control
9439 which CxxTest code generator is used.
9440 Valid only for CxxTest version 3.
9441 NOTE: In older versions of this Find Module,
9443 this variable controlled if the Python test
9444 generator was used instead of the Perl one,
9445 regardless of which scripting language the
9446 user had installed.
9447 CXXTEST_TESTGEN_ARGS (since CMake 2.8.3)
9449 Specify a list of options to pass to the CxxTest code
9450 generator. If not defined, --error-printer is
9451 passed.
9452 OUTPUT Variables
9454 CXXTEST_FOUND
9456 True if the CxxTest framework was found
9457 CXXTEST_INCLUDE_DIRS
9458 Where to find the CxxTest include directory
9459 CXXTEST_PERL_TESTGEN_EXECUTABLE
9460 The perl-based test generator
9461 CXXTEST_PYTHON_TESTGEN_EXECUTABLE
9462 The python-based test generator
9463 CXXTEST_TESTGEN_EXECUTABLE (since CMake 2.8.3)
9464 The test generator that is actually used (chosen using user preferences
9465 and interpreters found in the system)
9466 CXXTEST_TESTGEN_INTERPRETER (since CMake 2.8.3)
9467 The full path to the Perl or Python executable on the system, on
9468 platforms where the script cannot be executed using its shebang line.
9469 MACROS for optional use by CMake users:
9471 CXXTEST_ADD_TEST(<test_name> <gen_source_file> <input_files_to_testgen...>)
9473 Creates a CxxTest runner and adds it to the CTest testing suite
9474 Parameters:
9475 test_name The name of the test
9476 gen_source_file The generated source filename to be
9477 generated by CxxTest
9478 input_files_to_testgen The list of header files containing the
9479 CxxTest::TestSuite's to be included in
9480 this runner
9481 #==============
9483 Example Usage:
9484 find_package(CxxTest)
9486 if(CXXTEST_FOUND)
9487 include_directories(${CXXTEST_INCLUDE_DIR})
9488 enable_testing()
9489 CXXTEST_ADD_TEST(unittest_foo foo_test.cc
9491 ${CMAKE_CURRENT_SOURCE_DIR}/foo_test.h)
9492 target_link_libraries(unittest_foo foo) # as needed
9493 endif()
9494 This will (if CxxTest is found):
9496 1. Invoke the testgen executable to autogenerate foo_test.cc in the
9497 binary tree from "foo_test.h" in the current source directory.
9498 2. Create an executable and test called unittest_foo.
9499 #=============
9501 Example foo_test.h:
9502 #include <cxxtest/TestSuite.h>
9504 class MyTestSuite : public CxxTest::TestSuite
9506 {
9507 public:
9508 void testAddition( void )
9509 {
9510 TS_ASSERT( 1 + 1 > 1 );
9511 TS_ASSERT_EQUALS( 1 + 1, 2 );
9512 }
9513 };
9514 FindCygwin
9516 Find Cygwin, a POSIX-compatible environment that runs natively on Mi‐
9517 crosoft Windows
9518 FindDart
9520 Find DART
9521 This module looks for the dart testing software and sets DART_ROOT to
9523 point to where it found it.
9524 FindDCMTK
9526 Find DICOM ToolKit (DCMTK) libraries and applications
9527 The module defines the following variables:
9529 DCMTK_INCLUDE_DIRS - Directories to include to use DCMTK
9531 DCMTK_LIBRARIES - Files to link against to use DCMTK
9532 DCMTK_FOUND - If false, don't try to use DCMTK
9533 DCMTK_DIR - (optional) Source directory for DCMTK
9534 Compatibility
9536 This module is able to find a version of DCMTK that does or does not
9537 export a DCMTKConfig.cmake file. It applies a two step process:
9538 · Step 1: Attempt to find DCMTK version providing a DCMTKConfig.cmake
9540 file.
9541 · Step 2: If step 1 failed, rely on FindDCMTK.cmake to set DCMTK_*
9543 variables details below.
9544 Recent DCMTK provides a DCMTKConfig.cmake package configuration file.
9546 To exclusively use the package configuration file (recommended when
9547 possible), pass the NO_MODULE option to find_package(). For example,
9548 find_package(DCMTK NO_MODULE). This requires official DCMTK snapshot
9549 3.6.1_20140617 or newer.
9550 Until all clients update to the more recent DCMTK, build systems will
9552 need to support different versions of DCMTK.
9553 On any given system, the following combinations of DCMTK versions could
9555 be considered:
9556 ┌───────┬─────────────────┬─────────────────┬─────────────┐
9558 │ │ SYSTEM DCMTK │ LOCAL DCMTK │ Supported ? │
9559 ├───────┼─────────────────┼─────────────────┼─────────────┤
9560 │Case A │ NA │ [ ] DCMTKConfig │ YES │
9561 ├───────┼─────────────────┼─────────────────┼─────────────┤
9562 │Case B │ NA │ [X] DCMTKConfig │ YES │
9563 ├───────┼─────────────────┼─────────────────┼─────────────┤
9564 │Case C │ [ ] DCMTKConfig │ NA │ YES │
9565 ├───────┼─────────────────┼─────────────────┼─────────────┤
9566 │Case D │ [X] DCMTKConfig │ NA │ YES │
9567 ├───────┼─────────────────┼─────────────────┼─────────────┤
9568 │Case E │ [ ] DCMTKConfig │ [ ] DCMTKConfig │ YES (*) │
9569 ├───────┼─────────────────┼─────────────────┼─────────────┤
9570 │Case F │ [X] DCMTKConfig │ [ ] DCMTKConfig │ NO │
9571 ├───────┼─────────────────┼─────────────────┼─────────────┤
9572 │Case G │ [ ] DCMTKConfig │ [X] DCMTKConfig │ YES │
9573 └───────┴─────────────────┴─────────────────┴─────────────┘
9574 │Case H │ [X] DCMTKConfig │ [X] DCMTKConfig │ YES │
9577 └───────┴─────────────────┴─────────────────┴─────────────┘
9578 (*) See Troubleshooting section.
9579 Legend:
9581 NA ……………: Means that no System or Local DCMTK is available
9582 [ ] DCMTKConfig ..: Means that the version of DCMTK does NOT export
9584 a DCMTKConfig.cmake file.
9585 [X] DCMTKConfig ..: Means that the version of DCMTK exports a DCMTK‐
9587 Config.cmake file.
9588 Troubleshooting
9590 What to do if my project finds a different version of DCMTK?
9591 Remove DCMTK entry from the CMake cache per find_package() documenta‐
9593 tion.
9594 FindDevIL
9596 This module locates the developer’s image library.
9597 http://openil.sourceforge.net/
9598 This module sets:
9600 IL_LIBRARIES - the name of the IL library. These include the full path to
9602 the core DevIL library. This one has to be linked into the
9603 application.
9604 ILU_LIBRARIES - the name of the ILU library. Again, the full path. This
9605 library is for filters and effects, not actual loading. It
9606 doesn't have to be linked if the functionality it provides
9607 is not used.
9608 ILUT_LIBRARIES - the name of the ILUT library. Full path. This part of the
9609 library interfaces with OpenGL. It is not strictly needed
9610 in applications.
9611 IL_INCLUDE_DIR - where to find the il.h, ilu.h and ilut.h files.
9612 DevIL_FOUND - this is set to TRUE if all the above variables were set.
9613 This will be set to false if ILU or ILUT are not found,
9614 even if they are not needed. In most systems, if one
9615 library is found all the others are as well. That's the
9616 way the DevIL developers release it.
9617 FindDoxygen
9619 Doxygen is a documentation generation tool (see
9620 http://www.doxygen.org). This module looks for Doxygen and some
9621 optional tools it supports. These tools are enabled as components in
9622 the find_package() command:
9623 dot Graphviz dot utility used to render various graphs.
9625 mscgen Message Chart Generator utility used by Doxygen’s \msc and \msc‐
9627 file commands.
9628 dia Dia the diagram editor used by Doxygen’s \diafile command.
9630 Examples:
9632 # Require dot, treat the other components as optional
9634 find_package(Doxygen
9635 REQUIRED dot
9636 OPTIONAL_COMPONENTS mscgen dia)
9637 The following variables are defined by this module:
9639 DOXYGEN_FOUND
9641 True if the doxygen executable was found.
9642 DOXYGEN_VERSION
9644 The version reported by doxygen --version.
9645 The module defines IMPORTED targets for Doxygen and each component
9647 found. These can be used as part of custom commands, etc. and should
9648 be preferred over old-style (and now deprecated) variables like DOXY‐
9649 GEN_EXECUTABLE. The following import targets are defined if their cor‐
9650 responding executable could be found (the component import targets will
9651 only be defined if that component was requested):
9652 Doxygen::doxygen
9654 Doxygen::dot
9655 Doxygen::mscgen
9656 Doxygen::dia
9657 Functions
9659 doxygen_add_docs
9660 This function is intended as a convenience for adding a target
9661 for generating documentation with Doxygen. It aims to provide
9662 sensible defaults so that projects can generally just provide
9663 the input files and directories and that will be sufficient to
9664 give sensible results. The function supports the ability to cus‐
9665 tomize the Doxygen configuration used to build the documenta‐
9666 tion.
9667 doxygen_add_docs(targetName
9669 [filesOrDirs...]
9670 [ALL]
9671 [USE_STAMP_FILE]
9672 [WORKING_DIRECTORY dir]
9673 [COMMENT comment])
9674 The function constructs a Doxyfile and defines a custom target
9676 that runs Doxygen on that generated file. The listed files and
9677 directories are used as the INPUT of the generated Doxyfile and
9678 they can contain wildcards. Any files that are listed explic‐
9679 itly will also be added as SOURCES of the custom target so they
9680 will show up in an IDE project’s source list.
9681 So that relative input paths work as expected, by default the
9683 working directory of the Doxygen command will be the current
9684 source directory (i.e. CMAKE_CURRENT_SOURCE_DIR). This can be
9685 overridden with the WORKING_DIRECTORY option to change the
9686 directory used as the relative base point. Note also that Doxy‐
9687 gen’s default behavior is to strip the working directory from
9688 relative paths in the generated documentation (see the
9689 STRIP_FROM_PATH Doxygen config option for details).
9690 If provided, the optional comment will be passed as the COMMENT
9692 for the add_custom_target() command used to create the custom
9693 target internally.
9694 If ALL is set, the target will be added to the default build
9696 target.
9697 If USE_STAMP_FILE is set, the custom command defined by this
9699 function will create a stamp file with the name <target‐
9700 Name>.stamp in the current binary directory whenever doxygen is
9701 re-run. With this option present, all items in <filesOrDirs>
9702 must be files (i.e. no directories, symlinks or wildcards) and
9703 each of the files must exist at the time doxygen_add_docs() is
9704 called. An error will be raised if any of the items listed is
9705 missing or is not a file when USE_STAMP_FILE is given. A depen‐
9706 dency will be created on each of the files so that doxygen will
9707 only be re-run if one of the files is updated. Without the
9708 USE_STAMP_FILE option, doxygen will always be re-run if the
9709 <targetName> target is built regardless of whether anything
9710 listed in <filesOrDirs> has changed.
9711 The contents of the generated Doxyfile can be customized by set‐
9713 ting CMake variables before calling doxygen_add_docs(). Any
9714 variable with a name of the form DOXYGEN_<tag> will have its
9715 value substituted for the corresponding <tag> configuration
9716 option in the Doxyfile. See the Doxygen documentation for the
9717 full list of supported configuration options.
9718 Some of Doxygen’s defaults are overridden to provide more appro‐
9720 priate behavior for a CMake project. Each of the following will
9721 be explicitly set unless the variable already has a value before
9722 doxygen_add_docs() is called (with some exceptions noted):
9723 DOXYGEN_HAVE_DOT
9725 Set to YES if the dot component was requested and it was
9726 found, NO otherwise. Any existing value of DOXY‐
9727 GEN_HAVE_DOT is ignored.
9728 DOXYGEN_DOT_MULTI_TARGETS
9730 Set to YES by this module (note that this requires a dot
9731 version newer than 1.8.10). This option is only meaning‐
9732 ful if DOXYGEN_HAVE_DOT is also set to YES.
9733 DOXYGEN_GENERATE_LATEX
9735 Set to NO by this module.
9736 DOXYGEN_WARN_FORMAT
9738 For Visual Studio based generators, this is set to the
9739 form recognized by the Visual Studio IDE: $file($line) :
9740 $text. For all other generators, Doxygen’s default value
9741 is not overridden.
9742 DOXYGEN_PROJECT_NAME
9744 Populated with the name of the current project (i.e.
9745 PROJECT_NAME).
9746 DOXYGEN_PROJECT_NUMBER
9748 Populated with the version of the current project (i.e.
9749 PROJECT_VERSION).
9750 DOXYGEN_PROJECT_BRIEF
9752 Populated with the description of the current project
9753 (i.e. PROJECT_DESCRIPTION).
9754 DOXYGEN_INPUT
9756 Projects should not set this variable. It will be popu‐
9757 lated with the set of files and directories passed to
9758 doxygen_add_docs(), thereby providing consistent behavior
9759 with the other built-in commands like add_executable(),
9760 add_library() and add_custom_target(). If a variable
9761 named DOXYGEN_INPUT is set by the project, it will be
9762 ignored and a warning will be issued.
9763 DOXYGEN_RECURSIVE
9765 Set to YES by this module.
9766 DOXYGEN_EXCLUDE_PATTERNS
9768 If the set of inputs includes directories, this variable
9769 will specify patterns used to exclude files from them.
9770 The following patterns are added by doxygen_add_docs() to
9771 ensure CMake-specific files and directories are not
9772 included in the input. If the project sets DOXY‐
9773 GEN_EXCLUDE_PATTERNS, those contents are merged with
9774 these additional patterns rather than replacing them:
9775 */.git/*
9777 */.svn/*
9778 */.hg/*
9779 */CMakeFiles/*
9780 */_CPack_Packages/*
9781 DartConfiguration.tcl
9782 CMakeLists.txt
9783 CMakeCache.txt
9784 DOXYGEN_OUTPUT_DIRECTORY
9786 Set to CMAKE_CURRENT_BINARY_DIR by this module. Note that
9787 if the project provides its own value for this and it is
9788 a relative path, it will be converted to an absolute path
9789 relative to the current binary directory. This is neces‐
9790 sary because doxygen will normally be run from a direc‐
9791 tory within the source tree so that relative source paths
9792 work as expected. If this directory does not exist, it
9793 will be recursively created prior to executing the doxy‐
9794 gen commands.
9795 To change any of these defaults or override any other Doxygen config
9797 option, set relevant variables before calling doxygen_add_docs(). For
9798 example:
9799 set(DOXYGEN_GENERATE_HTML NO)
9801 set(DOXYGEN_GENERATE_MAN YES)
9802 doxygen_add_docs(
9804 doxygen
9805 ${PROJECT_SOURCE_DIR}
9806 COMMENT "Generate man pages"
9807 )
9808 A number of Doxygen config options accept lists of values, but Doxygen
9810 requires them to be separated by whitespace. CMake variables hold lists
9811 as a string with items separated by semi-colons, so a conversion needs
9812 to be performed. The doxygen_add_docs() command specifically checks the
9813 following Doxygen config options and will convert their associated
9814 CMake variable’s contents into the required form if set.
9815 ABBREVIATE_BRIEF
9817 ALIASES
9818 CITE_BIB_FILES
9819 DIAFILE_DIRS
9820 DOTFILE_DIRS
9821 DOT_FONTPATH
9822 ENABLED_SECTIONS
9823 EXAMPLE_PATH
9824 EXAMPLE_PATTERNS
9825 EXCLUDE
9826 EXCLUDE_PATTERNS
9827 EXCLUDE_SYMBOLS
9828 EXPAND_AS_DEFINED
9829 EXTENSION_MAPPING
9830 EXTRA_PACKAGES
9831 EXTRA_SEARCH_MAPPINGS
9832 FILE_PATTERNS
9833 FILTER_PATTERNS
9834 FILTER_SOURCE_PATTERNS
9835 HTML_EXTRA_FILES
9836 HTML_EXTRA_STYLESHEET
9837 IGNORE_PREFIX
9838 IMAGE_PATH
9839 INCLUDE_FILE_PATTERNS
9840 INCLUDE_PATH
9841 INPUT
9842 LATEX_EXTRA_FILES
9843 LATEX_EXTRA_STYLESHEET
9844 MATHJAX_EXTENSIONS
9845 MSCFILE_DIRS
9846 PLANTUML_INCLUDE_PATH
9847 PREDEFINED
9848 QHP_CUST_FILTER_ATTRS
9849 QHP_SECT_FILTER_ATTRS
9850 STRIP_FROM_INC_PATH
9851 STRIP_FROM_PATH
9852 TAGFILES
9853 TCL_SUBST
9854 The following single value Doxygen options will be quoted automatically
9856 if they contain at least one space:
9857 CHM_FILE
9859 DIA_PATH
9860 DOCBOOK_OUTPUT
9861 DOCSET_FEEDNAME
9862 DOCSET_PUBLISHER_NAME
9863 DOT_FONTNAME
9864 DOT_PATH
9865 EXTERNAL_SEARCH_ID
9866 FILE_VERSION_FILTER
9867 GENERATE_TAGFILE
9868 HHC_LOCATION
9869 HTML_FOOTER
9870 HTML_HEADER
9871 HTML_OUTPUT
9872 HTML_STYLESHEET
9873 INPUT_FILTER
9874 LATEX_FOOTER
9875 LATEX_HEADER
9876 LATEX_OUTPUT
9877 LAYOUT_FILE
9878 MAN_OUTPUT
9879 MAN_SUBDIR
9880 MATHJAX_CODEFILE
9881 MSCGEN_PATH
9882 OUTPUT_DIRECTORY
9883 PERL_PATH
9884 PLANTUML_JAR_PATH
9885 PROJECT_BRIEF
9886 PROJECT_LOGO
9887 PROJECT_NAME
9888 QCH_FILE
9889 QHG_LOCATION
9890 QHP_CUST_FILTER_NAME
9891 QHP_VIRTUAL_FOLDER
9892 RTF_EXTENSIONS_FILE
9893 RTF_OUTPUT
9894 RTF_STYLESHEET_FILE
9895 SEARCHDATA_FILE
9896 USE_MDFILE_AS_MAINPAGE
9897 WARN_FORMAT
9898 WARN_LOGFILE
9899 XML_OUTPUT
9900 There are situations where it may be undesirable for a particular con‐
9902 fig option to be automatically quoted by doxygen_add_docs(), such as
9903 ALIASES which may need to include its own embedded quoting. The DOXY‐
9904 GEN_VERBATIM_VARS variable can be used to specify a list of Doxygen
9905 variables (including the leading DOXYGEN_ prefix) which should not be
9906 quoted. The project is then responsible for ensuring that those vari‐
9907 ables’ values make sense when placed directly in the Doxygen input
9908 file. In the case of list variables, list items are still separated by
9909 spaces, it is only the automatic quoting that is skipped. For example,
9910 the following allows doxygen_add_docs() to apply quoting to DOXY‐
9911 GEN_PROJECT_BRIEF, but not each item in the DOXYGEN_ALIASES list
9912 (bracket syntax can also be used to make working with embedded quotes
9913 easier):
9914 set(DOXYGEN_PROJECT_BRIEF "String with spaces")
9916 set(DOXYGEN_ALIASES
9917 [[somealias="@some_command param"]]
9918 "anotherAlias=@foobar"
9919 )
9920 set(DOXYGEN_VERBATIM_VARS DOXYGEN_ALIASES)
9921 The resultant Doxyfile will contain the following lines:
9923 PROJECT_BRIEF = "String with spaces"
9925 ALIASES = somealias="@some_command param" anotherAlias=@foobar
9926 Deprecated Result Variables
9928 For compatibility with previous versions of CMake, the following vari‐
9929 ables are also defined but they are deprecated and should no longer be
9930 used:
9931 DOXYGEN_EXECUTABLE
9933 The path to the doxygen command. If projects need to refer to
9934 the doxygen executable directly, they should use the Doxy‐
9935 gen::doxygen import target instead.
9936 DOXYGEN_DOT_FOUND
9938 True if the dot executable was found.
9939 DOXYGEN_DOT_EXECUTABLE
9941 The path to the dot command. If projects need to refer to the
9942 dot executable directly, they should use the Doxygen::dot import
9943 target instead.
9944 DOXYGEN_DOT_PATH
9946 The path to the directory containing the dot executable as
9947 reported in DOXYGEN_DOT_EXECUTABLE. The path may have forward
9948 slashes even on Windows and is not suitable for direct substitu‐
9949 tion into a Doxyfile.in template. If you need this value, get
9950 the IMPORTED_LOCATION property of the Doxygen::dot target and
9951 use get_filename_component() to extract the directory part of
9952 that path. You may also want to consider using
9953 file(TO_NATIVE_PATH) to prepare the path for a Doxygen configu‐
9954 ration file.
9955 Deprecated Hint Variables
9957 DOXYGEN_SKIP_DOT
9958 This variable has no effect for the component form of find_pack‐
9959 age. In backward compatibility mode (i.e. without components
9960 list) it prevents the finder module from searching for
9961 Graphviz’s dot utility.
9962 FindEnvModules
9964 New in version 3.15.
9965 Locate an environment module implementation and make commands available
9968 to CMake scripts to use them. This is compatible with both Lua-based
9969 Lmod and TCL-based EnvironmentModules.
9970 This module is intended for the use case of setting up the compiler and
9972 library environment within a CTest Script (ctest -S). It can also be
9973 used in a CMake Script (cmake -P).
9974 NOTE:
9976 The loaded environment will not survive past the end of the calling
9977 process. Do not use this module in project code (CMakeLists.txt
9978 files) to load a compiler environment; it will not be available dur‐
9979 ing the build. Instead load the environment manually before running
9980 CMake or using the generated build system.
9981 Example Usage
9983 set(CTEST_BUILD_NAME "CrayLinux-CrayPE-Cray-dynamic")
9984 set(CTEST_BUILD_CONFIGURATION Release)
9985 set(CTEST_BUILD_FLAGS "-k -j8")
9986 set(CTEST_CMAKE_GENERATOR "Unix Makefiles")
9987 ...
9989 find_package(EnvModules REQUIRED)
9991 env_module(purge)
9993 env_module(load modules)
9994 env_module(load craype)
9995 env_module(load PrgEnv-cray)
9996 env_module(load craype-knl)
9997 env_module(load cray-mpich)
9998 env_module(load cray-libsci)
9999 set(ENV{CRAYPE_LINK_TYPE} dynamic)
10001 ...
10003 Result Variables
10005 This module will set the following variables in your project:
10006 EnvModules_FOUND
10008 True if a compatible environment modules framework was found.
10009 Cache Variables
10011 The following cache variable will be set:
10012 EnvModules_COMMAND
10014 The low level module command to use. Currently supported imple‐
10015 mentations are the Lua based Lmod and TCL based EnvironmentMod‐
10016 ules.
10017 Environment Variables
10019 ENV{MODULESHOME}
10020 Usually set by the module environment implementation, used as a
10021 hint to locate the module command to execute.
10022 Provided Functions
10024 This defines the following CMake functions for interacting with envi‐
10025 ronment modules:
10026 env_module
10028 Execute an aribitrary module command:
10029 env_module(cmd arg1 ... argN)
10031 env_module(
10032 COMMAND cmd arg1 ... argN
10033 [OUTPUT_VARIABLE <out-var>]
10034 [RESULT_VARIABLE <ret-var>]
10035 )
10036 The options are:
10038 cmd arg1 ... argN
10040 The module sub-command and arguments to execute as if
10041 they were passed directly to the module command in your
10042 shell environment.
10043 OUTPUT_VARIABLE <out-var>
10045 The standard output from executing the module command.
10046 RESULT_VARIABLE <ret-var>
10048 The return code from executing the module command.
10049 env_module_swap
10051 Swap one module for another:
10052 env_module_swap(out_mod in_mod
10054 [OUTPUT_VARIABLE <out-var>]
10055 [RESULT_VARIABLE <ret-var>]
10056 )
10057 This is functionally equivalent to the module swap out_mod
10059 in_mod shell command. The options are:
10060 OUTPUT_VARIABLE <out-var>
10062 The standard output from executing the module command.
10063 RESULT_VARIABLE <ret-var>
10065 The return code from executing the module command.
10066 env_module_list
10068 Retrieve the list of currently loaded modules:
10069 env_module_list(<out-var>)
10071 This is functionally equivalent to the module list shell com‐
10073 mand. The result is stored in <out-var> as a properly formatted
10074 CMake semicolon-separated list variable.
10075 env_module_avail
10077 Retrieve the list of available modules:
10078 env_module_avail([<mod-prefix>] <out-var>)
10080 This is functionally equivalent to the module avail <mod-prefix>
10082 shell command. The result is stored in <out-var> as a properly
10083 formatted CMake semicolon-separated list variable.
10084 FindEXPAT
10086 Find the native Expat headers and library. Expat is a stream-oriented
10087 XML parser library written in C.
10088 Imported Targets
10090 This module defines the following IMPORTED targets:
10091 EXPAT::EXPAT
10093 The Expat expat library, if found.
10094 Result Variables
10096 This module will set the following variables in your project:
10097 EXPAT_INCLUDE_DIRS
10099 where to find expat.h, etc.
10100 EXPAT_LIBRARIES
10102 the libraries to link against to use Expat.
10103 EXPAT_FOUND
10105 true if the Expat headers and libraries were found.
10106 FindFLEX
10108 Find Fast Lexical Analyzer (Flex) executable and provides a macro to
10109 generate custom build rules
10110 The module defines the following variables:
10112 FLEX_FOUND - True is flex executable is found
10114 FLEX_EXECUTABLE - the path to the flex executable
10115 FLEX_VERSION - the version of flex
10116 FLEX_LIBRARIES - The flex libraries
10117 FLEX_INCLUDE_DIRS - The path to the flex headers
10118 The minimum required version of flex can be specified using the stan‐
10120 dard syntax, e.g. find_package(FLEX 2.5.13)
10121 If flex is found on the system, the module provides the macro:
10123 FLEX_TARGET(Name FlexInput FlexOutput
10125 [COMPILE_FLAGS <string>]
10126 [DEFINES_FILE <string>]
10127 )
10128 which creates a custom command to generate the FlexOutput file from the
10130 FlexInput file. If COMPILE_FLAGS option is specified, the next parame‐
10131 ter is added to the flex command line. If flex is configured to output
10132 a header file, the DEFINES_FILE option may be used to specify its name.
10133 Name is an alias used to get details of this custom command. Indeed
10134 the macro defines the following variables:
10135 FLEX_${Name}_DEFINED - true is the macro ran successfully
10137 FLEX_${Name}_OUTPUTS - the source file generated by the custom rule, an
10138 alias for FlexOutput
10139 FLEX_${Name}_INPUT - the flex source file, an alias for ${FlexInput}
10140 FLEX_${Name}_OUTPUT_HEADER - the header flex output, if any.
10141 Flex scanners often use tokens defined by Bison: the code generated by
10143 Flex depends of the header generated by Bison. This module also
10144 defines a macro:
10145 ADD_FLEX_BISON_DEPENDENCY(FlexTarget BisonTarget)
10147 which adds the required dependency between a scanner and a parser where
10149 FlexTarget and BisonTarget are the first parameters of respectively
10150 FLEX_TARGET and BISON_TARGET macros.
10151 ====================================================================
10153 Example:
10154 find_package(BISON)
10156 find_package(FLEX)
10157 BISON_TARGET(MyParser parser.y ${CMAKE_CURRENT_BINARY_DIR}/parser.cpp)
10159 FLEX_TARGET(MyScanner lexer.l ${CMAKE_CURRENT_BINARY_DIR}/lexer.cpp)
10160 ADD_FLEX_BISON_DEPENDENCY(MyScanner MyParser)
10161 include_directories(${CMAKE_CURRENT_BINARY_DIR})
10163 add_executable(Foo
10164 Foo.cc
10165 ${BISON_MyParser_OUTPUTS}
10166 ${FLEX_MyScanner_OUTPUTS}
10167 )
10168 target_link_libraries(Foo ${FLEX_LIBRARIES})
10169 ====================================================================
10170 FindFLTK
10172 Find the Fast Light Toolkit (FLTK) library
10173 Input Variables
10175 By default this module will search for all of the FLTK components and
10176 add them to the FLTK_LIBRARIES variable. You can limit the components
10177 which get placed in FLTK_LIBRARIES by defining one or more of the fol‐
10178 lowing three options:
10179 FLTK_SKIP_OPENGL
10181 Set to true to disable searching for the FLTK GL library
10182 FLTK_SKIP_FORMS
10184 Set to true to disable searching for the FLTK Forms library
10185 FLTK_SKIP_IMAGES
10187 Set to true to disable searching for the FLTK Images library
10188 FLTK is composed also by a binary tool. You can set the following
10190 option:
10191 FLTK_SKIP_FLUID
10193 Set to true to not look for the FLUID binary
10194 Result Variables
10196 The following variables will be defined:
10197 FLTK_FOUND
10199 True if all components not skipped were found
10200 FLTK_INCLUDE_DIR
10202 Path to the include directory for FLTK header files
10203 FLTK_LIBRARIES
10205 List of the FLTK libraries found
10206 FLTK_FLUID_EXECUTABLE
10208 Path to the FLUID binary tool
10209 FLTK_WRAP_UI
10211 True if FLUID is found, used to enable the FLTK_WRAP_UI command
10212 Cache Variables
10214 The following cache variables are also available to set or use:
10215 FLTK_BASE_LIBRARY_RELEASE
10217 The FLTK base library (optimized)
10218 FLTK_BASE_LIBRARY_DEBUG
10220 The FLTK base library (debug)
10221 FLTK_GL_LIBRARY_RELEASE
10223 The FLTK GL library (optimized)
10224 FLTK_GL_LIBRARY_DEBUG
10226 The FLTK GL library (debug)
10227 FLTK_FORMS_LIBRARY_RELEASE
10229 The FLTK Forms library (optimized)
10230 FLTK_FORMS_LIBRARY_DEBUG
10232 The FLTK Forms library (debug)
10233 FLTK_IMAGES_LIBRARY_RELEASE
10235 The FLTK Images protobuf library (optimized)
10236 FLTK_IMAGES_LIBRARY_DEBUG
10238 The FLTK Images library (debug)
10239 FindFLTK2
10241 Find the native FLTK 2.0 includes and library
10242 The following settings are defined
10244 FLTK2_FLUID_EXECUTABLE, where to find the Fluid tool
10246 FLTK2_WRAP_UI, This enables the FLTK2_WRAP_UI command
10247 FLTK2_INCLUDE_DIR, where to find include files
10248 FLTK2_LIBRARIES, list of fltk2 libraries
10249 FLTK2_FOUND, Don't use FLTK2 if false.
10250 The following settings should not be used in general.
10252 FLTK2_BASE_LIBRARY = the full path to fltk2.lib
10254 FLTK2_GL_LIBRARY = the full path to fltk2_gl.lib
10255 FLTK2_IMAGES_LIBRARY = the full path to fltk2_images.lib
10256 FindFontconfig
10258 New in version 3.14.
10259 Find Fontconfig headers and library.
10262 Imported Targets
10264 Fontconfig::Fontconfig
10265 The Fontconfig library, if found.
10266 Result Variables
10268 This will define the following variables in your project:
10269 Fontconfig_FOUND
10271 true if (the requested version of) Fontconfig is available.
10272 Fontconfig_VERSION
10274 the version of Fontconfig.
10275 Fontconfig_LIBRARIES
10277 the libraries to link against to use Fontconfig.
10278 Fontconfig_INCLUDE_DIRS
10280 where to find the Fontconfig headers.
10281 Fontconfig_COMPILE_OPTIONS
10283 this should be passed to target_compile_options(), if the target
10284 is not used for linking
10285 FindFreetype
10287 Find the FreeType font renderer includes and library.
10288 Imported Targets
10290 This module defines the following IMPORTED target:
10291 Freetype::Freetype
10293 The Freetype freetype library, if found
10294 Result Variables
10296 This module will set the following variables in your project:
10297 FREETYPE_FOUND
10299 true if the Freetype headers and libraries were found
10300 FREETYPE_INCLUDE_DIRS
10302 directories containing the Freetype headers. This is the con‐
10303 catenation of the variables:
10304 FREETYPE_INCLUDE_DIR_ft2build
10306 directory holding the main Freetype API configuration
10307 header
10308 FREETYPE_INCLUDE_DIR_freetype2
10310 directory holding Freetype public headers
10311 FREETYPE_LIBRARIES
10313 the library to link against
10314 FREETYPE_VERSION_STRING
10316 the version of freetype found (since CMake 2.8.8)
10317 Hints
10319 The user may set the environment variable FREETYPE_DIR to the root
10320 directory of a Freetype installation.
10321 FindGCCXML
10323 Find the GCC-XML front-end executable.
10324 This module will define the following variables:
10326 GCCXML - the GCC-XML front-end executable.
10328 FindGDAL
10330 Find Geospatial Data Abstraction Library (GDAL).
10331 IMPORTED Targets
10333 This module defines IMPORTED target GDAL::GDAL if GDAL has been found.
10334 Result Variables
10336 This module will set the following variables in your project:
10337 GDAL_FOUND
10339 True if GDAL is found.
10340 GDAL_INCLUDE_DIRS
10342 Include directories for GDAL headers.
10343 GDAL_LIBRARIES
10345 Libraries to link to GDAL.
10346 GDAL_VERSION
10348 The version of GDAL found.
10349 Cache variables
10351 The following cache variables may also be set:
10352 GDAL_LIBRARY
10354 The libgdal library file.
10355 GDAL_INCLUDE_DIR
10357 The directory containing gdal.h.
10358 Hints
10360 Set GDAL_DIR or GDAL_ROOT in the environment to specify the GDAL
10361 installation prefix.
10362 FindGettext
10364 Find GNU gettext tools
10365 This module looks for the GNU gettext tools. This module defines the
10367 following values:
10368 GETTEXT_MSGMERGE_EXECUTABLE: the full path to the msgmerge tool.
10370 GETTEXT_MSGFMT_EXECUTABLE: the full path to the msgfmt tool.
10371 GETTEXT_FOUND: True if gettext has been found.
10372 GETTEXT_VERSION_STRING: the version of gettext found (since CMake 2.8.8)
10373 Additionally it provides the following macros:
10375 GETTEXT_CREATE_TRANSLATIONS ( outputFile [ALL] file1 … fileN )
10377 This will create a target "translations" which will convert the
10379 given input po files into the binary output mo file. If the
10380 ALL option is used, the translations will also be created when
10381 building the default target.
10382 GETTEXT_PROCESS_POT_FILE( <potfile> [ALL] [INSTALL_DESTINATION <dest‐
10384 dir>] LANGUAGES <lang1> <lang2> … )
10385 Process the given pot file to mo files.
10387 If INSTALL_DESTINATION is given then automatically install rules will
10388 be created, the language subdirectory will be taken into account
10389 (by default use share/locale/).
10390 If ALL is specified, the pot file is processed when building the all traget.
10391 It creates a custom target "potfile".
10392 GETTEXT_PROCESS_PO_FILES( <lang> [ALL] [INSTALL_DESTINATION <dir>]
10394 PO_FILES <po1> <po2> … )
10395 Process the given po files to mo files for the given language.
10397 If INSTALL_DESTINATION is given then automatically install rules will
10398 be created, the language subdirectory will be taken into account
10399 (by default use share/locale/).
10400 If ALL is specified, the po files are processed when building the all traget.
10401 It creates a custom target "pofiles".
10402 NOTE:
10404 If you wish to use the Gettext library (libintl), use FindIntl.
10405 FindGIF
10407 This finds the Graphics Interchange Format (GIF) library (giflib)
10408 Imported targets
10410 This module defines the following IMPORTED target:
10411 GIF::GIF
10413 The giflib library, if found.
10414 Result variables
10416 This module will set the following variables in your project:
10417 GIF_FOUND
10419 If false, do not try to use GIF.
10420 GIF_INCLUDE_DIRS
10422 where to find gif_lib.h, etc.
10423 GIF_LIBRARIES
10425 the libraries needed to use GIF.
10426 GIF_VERSION
10428 3, 4 or a full version string (eg 5.1.4) for versions >= 4.1.6.
10429 Cache variables
10431 The following cache variables may also be set:
10432 GIF_INCLUDE_DIR
10434 where to find the GIF headers.
10435 GIF_LIBRARY
10437 where to find the GIF library.
10438 Hints
10440 GIF_DIR is an environment variable that would correspond to the ./con‐
10441 figure --prefix=$GIF_DIR.
10442 FindGit
10444 The module defines the following IMPORTED targets (when CMAKE_ROLE is
10445 PROJECT):
10446 Git::Git
10448 Executable of the Git command-line client.
10449 The module defines the following variables:
10451 GIT_EXECUTABLE
10453 Path to Git command-line client.
10454 Git_FOUND, GIT_FOUND
10456 True if the Git command-line client was found.
10457 GIT_VERSION_STRING
10459 The version of Git found.
10460 Example usage:
10462 find_package(Git)
10464 if(Git_FOUND)
10465 message("Git found: ${GIT_EXECUTABLE}")
10466 endif()
10467 FindGLEW
10469 Find the OpenGL Extension Wrangler Library (GLEW)
10470 Input Variables
10472 The following variables may be set to influence this module’s behavior:
10473 GLEW_USE_STATIC_LIBS
10475 to find and create IMPORTED target for static linkage.
10476 GLEW_VERBOSE
10478 to output a detailed log of this module.
10479 Imported Targets
10481 This module defines the following Imported Targets:
10482 GLEW::glew
10484 The GLEW shared library.
10485 GLEW::glew_s
10487 The GLEW static library, if GLEW_USE_STATIC_LIBS is set to TRUE.
10488 GLEW::GLEW
10490 Duplicates either GLEW::glew or GLEW::glew_s based on availabil‐
10491 ity.
10492 Result Variables
10494 This module defines the following variables:
10495 GLEW_INCLUDE_DIRS
10497 include directories for GLEW
10498 GLEW_LIBRARIES
10500 libraries to link against GLEW
10501 GLEW_SHARED_LIBRARIES
10503 libraries to link against shared GLEW
10504 GLEW_STATIC_LIBRARIES
10506 libraries to link against static GLEW
10507 GLEW_FOUND
10509 true if GLEW has been found and can be used
10510 GLEW_VERSION
10512 GLEW version
10513 GLEW_VERSION_MAJOR
10515 GLEW major version
10516 GLEW_VERSION_MINOR
10518 GLEW minor version
10519 GLEW_VERSION_MICRO
10521 GLEW micro version
10522 FindGLUT
10524 Find OpenGL Utility Toolkit (GLUT) library and include files.
10525 IMPORTED Targets
10527 This module defines the IMPORTED targets:
10528 GLUT::GLUT
10530 Defined if the system has GLUT.
10531 Result Variables
10533 This module sets the following variables:
10534 GLUT_INCLUDE_DIR, where to find GL/glut.h, etc.
10536 GLUT_LIBRARIES, the libraries to link against
10537 GLUT_FOUND, If false, do not try to use GLUT.
10538 Also defined, but not for general use are:
10540 GLUT_glut_LIBRARY = the full path to the glut library.
10542 GLUT_Xmu_LIBRARY = the full path to the Xmu library.
10543 GLUT_Xi_LIBRARY = the full path to the Xi Library.
10544 FindGnuplot
10546 this module looks for gnuplot
10547 Once done this will define
10549 GNUPLOT_FOUND - system has Gnuplot
10551 GNUPLOT_EXECUTABLE - the Gnuplot executable
10552 GNUPLOT_VERSION_STRING - the version of Gnuplot found (since CMake 2.8.8)
10553 GNUPLOT_VERSION_STRING will not work for old versions like 3.7.1.
10555 FindGnuTLS
10557 Find the GNU Transport Layer Security library (gnutls)
10558 IMPORTED Targets
10560 This module defines IMPORTED target GnuTLS::GnuTLS, if gnutls has been
10561 found.
10562 Result Variables
10564 GNUTLS_FOUND
10565 System has gnutls
10566 GNUTLS_INCLUDE_DIR
10568 The gnutls include directory
10569 GNUTLS_LIBRARIES
10571 The libraries needed to use gnutls
10572 GNUTLS_DEFINITIONS
10574 Compiler switches required for using gnutls
10575 GNUTLS_VERSION
10577 version of gnutls.
10578 FindGSL
10580 New in version 3.2.
10581 Find the native GNU Scientific Library (GSL) includes and libraries.
10584 The GNU Scientific Library (GSL) is a numerical library for C and C++
10586 programmers. It is free software under the GNU General Public License.
10587 Imported Targets
10589 If GSL is found, this module defines the following IMPORTED targets:
10590 GSL::gsl - The main GSL library.
10592 GSL::gslcblas - The CBLAS support library used by GSL.
10593 Result Variables
10595 This module will set the following variables in your project:
10596 GSL_FOUND - True if GSL found on the local system
10598 GSL_INCLUDE_DIRS - Location of GSL header files.
10599 GSL_LIBRARIES - The GSL libraries.
10600 GSL_VERSION - The version of the discovered GSL install.
10601 Hints
10603 Set GSL_ROOT_DIR to a directory that contains a GSL installation.
10604 This script expects to find libraries at $GSL_ROOT_DIR/lib and the GSL
10606 headers at $GSL_ROOT_DIR/include/gsl. The library directory may
10607 optionally provide Release and Debug folders. If available, the
10608 libraries named gsld, gslblasd or cblasd are recognized as debug
10609 libraries. For Unix-like systems, this script will use
10610 $GSL_ROOT_DIR/bin/gsl-config (if found) to aid in the discovery of GSL.
10611 Cache Variables
10613 This module may set the following variables depending on platform and
10614 type of GSL installation discovered. These variables may optionally be
10615 set to help this module find the correct files:
10616 GSL_CBLAS_LIBRARY - Location of the GSL CBLAS library.
10618 GSL_CBLAS_LIBRARY_DEBUG - Location of the debug GSL CBLAS library (if any).
10619 GSL_CONFIG_EXECUTABLE - Location of the ``gsl-config`` script (if any).
10620 GSL_LIBRARY - Location of the GSL library.
10621 GSL_LIBRARY_DEBUG - Location of the debug GSL library (if any).
10622 FindGTest
10624 Locate the Google C++ Testing Framework.
10625 Imported targets
10627 This module defines the following IMPORTED targets:
10628 GTest::GTest
10630 The Google Test gtest library, if found; adds Thread::Thread
10631 automatically
10632 GTest::Main
10634 The Google Test gtest_main library, if found
10635 Result variables
10637 This module will set the following variables in your project:
10638 GTEST_FOUND
10640 Found the Google Testing framework
10641 GTEST_INCLUDE_DIRS
10643 the directory containing the Google Test headers
10644 The library variables below are set as normal variables. These contain
10646 debug/optimized keywords when a debugging library is found.
10647 GTEST_LIBRARIES
10649 The Google Test gtest library; note it also requires linking
10650 with an appropriate thread library
10651 GTEST_MAIN_LIBRARIES
10653 The Google Test gtest_main library
10654 GTEST_BOTH_LIBRARIES
10656 Both gtest and gtest_main
10657 Cache variables
10659 The following cache variables may also be set:
10660 GTEST_ROOT
10662 The root directory of the Google Test installation (may also be
10663 set as an environment variable)
10664 GTEST_MSVC_SEARCH
10666 If compiling with MSVC, this variable can be set to MT or MD
10667 (the default) to enable searching a GTest build tree
10668 Example usage
10670 enable_testing()
10671 find_package(GTest REQUIRED)
10672 add_executable(foo foo.cc)
10674 target_link_libraries(foo GTest::GTest GTest::Main)
10675 add_test(AllTestsInFoo foo)
10677 Deeper integration with CTest
10679 See GoogleTest for information on the gtest_add_tests() and gtest_dis‐
10680 cover_tests() commands.
10681 FindGTK
10683 Find GTK, glib and GTKGLArea
10684 GTK_INCLUDE_DIR - Directories to include to use GTK
10686 GTK_LIBRARIES - Files to link against to use GTK
10687 GTK_FOUND - GTK was found
10688 GTK_GL_FOUND - GTK's GL features were found
10689 FindGTK2
10691 Find the GTK2 widget libraries and several of its other optional compo‐
10692 nents like gtkmm, glade, and glademm.
10693 Specify one or more of the following components as you call this find
10695 module. See example below.
10696 · gtk
10698 · gtkmm
10700 · glade
10702 · glademm
10704 Result Variables
10706 The following variables will be defined for your use
10707 GTK2_FOUND
10709 Were all of your specified components found?
10710 GTK2_INCLUDE_DIRS
10712 All include directories
10713 GTK2_LIBRARIES
10715 All libraries
10716 GTK2_TARGETS
10718 All imported targets
10719 GTK2_DEFINITIONS
10721 Additional compiler flags
10722 GTK2_VERSION
10724 The version of GTK2 found (x.y.z)
10725 GTK2_MAJOR_VERSION
10727 The major version of GTK2
10728 GTK2_MINOR_VERSION
10730 The minor version of GTK2
10731 GTK2_PATCH_VERSION
10733 The patch version of GTK2
10734 Input Variables
10736 Optional variables you can define prior to calling this module:
10737 GTK2_DEBUG
10739 Enables verbose debugging of the module
10740 GTK2_ADDITIONAL_SUFFIXES
10742 Allows defining additional directories to search for include
10743 files
10744 Example Usage
10746 Call find_package() once. Here are some examples to pick from:
10747 Require GTK 2.6 or later:
10749 find_package(GTK2 2.6 REQUIRED gtk)
10751 Require GTK 2.10 or later and Glade:
10753 find_package(GTK2 2.10 REQUIRED gtk glade)
10755 Search for GTK/GTKMM 2.8 or later:
10757 find_package(GTK2 2.8 COMPONENTS gtk gtkmm)
10759 Use the results:
10761 if(GTK2_FOUND)
10763 include_directories(${GTK2_INCLUDE_DIRS})
10764 add_executable(mygui mygui.cc)
10765 target_link_libraries(mygui ${GTK2_LIBRARIES})
10766 endif()
10767 FindHDF5
10769 Find Hierarchical Data Format (HDF5), a library for reading and writing
10770 self describing array data.
10771 This module invokes the HDF5 wrapper compiler that should be installed
10773 alongside HDF5. Depending upon the HDF5 Configuration, the wrapper
10774 compiler is called either h5cc or h5pcc. If this succeeds, the module
10775 will then call the compiler with the show argument to see what flags
10776 are used when compiling an HDF5 client application.
10777 The module will optionally accept the COMPONENTS argument. If no COM‐
10779 PONENTS are specified, then the find module will default to finding
10780 only the HDF5 C library. If one or more COMPONENTS are specified, the
10781 module will attempt to find the language bindings for the specified
10782 components. The valid components are C, CXX, Fortran, HL. HL refers
10783 to the “high-level” HDF5 functions for C and Fortran. If the COMPO‐
10784 NENTS argument is not given, the module will attempt to find only the C
10785 bindings. For example, to use Fortran HDF5 and HDF5-HL functions, do:
10786 find_package(HDF5 COMPONENTS Fortran HL).
10787 This module will read the variable HDF5_USE_STATIC_LIBRARIES to deter‐
10789 mine whether or not to prefer a static link to a dynamic link for HDF5
10790 and all of it’s dependencies. To use this feature, make sure that the
10791 HDF5_USE_STATIC_LIBRARIES variable is set before the call to find_pack‐
10792 age.
10793 Both the serial and parallel HDF5 wrappers are considered and the first
10795 directory to contain either one will be used. In the event that both
10796 appear in the same directory the serial version is preferentially
10797 selected. This behavior can be reversed by setting the variable
10798 HDF5_PREFER_PARALLEL to TRUE.
10799 In addition to finding the includes and libraries required to compile
10801 an HDF5 client application, this module also makes an effort to find
10802 tools that come with the HDF5 distribution that may be useful for
10803 regression testing.
10804 Result Variables
10806 This module will set the following variables in your project:
10807 HDF5_FOUND
10809 HDF5 was found on the system
10810 HDF5_VERSION
10812 HDF5 library version
10813 HDF5_INCLUDE_DIRS
10815 Location of the HDF5 header files
10816 HDF5_DEFINITIONS
10818 Required compiler definitions for HDF5
10819 HDF5_LIBRARIES
10821 Required libraries for all requested bindings
10822 HDF5_HL_LIBRARIES
10824 Required libraries for the HDF5 high level API for all bindings,
10825 if the HL component is enabled
10826 Available components are: C CXX Fortran and HL. For each enabled lan‐
10828 guage binding, a corresponding HDF5_${LANG}_LIBRARIES variable, and
10829 potentially HDF5_${LANG}_DEFINITIONS, will be defined. If the HL com‐
10830 ponent is enabled, then an HDF5_${LANG}_HL_LIBRARIES will also be
10831 defined. With all components enabled, the following variables will be
10832 defined:
10833 HDF5_C_DEFINITIONS
10835 Required compiler definitions for HDF5 C bindings
10836 HDF5_CXX_DEFINITIONS
10838 Required compiler definitions for HDF5 C++ bindings
10839 HDF5_Fortran_DEFINITIONS
10841 Required compiler definitions for HDF5 Fortran bindings
10842 HDF5_C_INCLUDE_DIRS
10844 Required include directories for HDF5 C bindings
10845 HDF5_CXX_INCLUDE_DIRS
10847 Required include directories for HDF5 C++ bindings
10848 HDF5_Fortran_INCLUDE_DIRS
10850 Required include directories for HDF5 Fortran bindings
10851 HDF5_C_LIBRARIES
10853 Required libraries for the HDF5 C bindings
10854 HDF5_CXX_LIBRARIES
10856 Required libraries for the HDF5 C++ bindings
10857 HDF5_Fortran_LIBRARIES
10859 Required libraries for the HDF5 Fortran bindings
10860 HDF5_C_HL_LIBRARIES
10862 Required libraries for the high level C bindings
10863 HDF5_CXX_HL_LIBRARIES
10865 Required libraries for the high level C++ bindings
10866 HDF5_Fortran_HL_LIBRARIES
10868 Required libraries for the high level Fortran bindings.
10869 HDF5_IS_PARALLEL
10871 HDF5 library has parallel IO support
10872 HDF5_C_COMPILER_EXECUTABLE
10874 path to the HDF5 C wrapper compiler
10875 HDF5_CXX_COMPILER_EXECUTABLE
10877 path to the HDF5 C++ wrapper compiler
10878 HDF5_Fortran_COMPILER_EXECUTABLE
10880 path to the HDF5 Fortran wrapper compiler
10881 HDF5_C_COMPILER_EXECUTABLE_NO_INTERROGATE
10883 path to the primary C compiler which is also the HDF5 wrapper
10884 HDF5_CXX_COMPILER_EXECUTABLE_NO_INTERROGATE
10886 path to the primary C++ compiler which is also the HDF5 wrapper
10887 HDF5_Fortran_COMPILER_EXECUTABLE_NO_INTERROGATE
10889 path to the primary Fortran compiler which is also the HDF5
10890 wrapper
10891 HDF5_DIFF_EXECUTABLE
10893 path to the HDF5 dataset comparison tool
10894 With all components enabled, the following targets will be defined:
10896 ``hdf5::hdf5``
10898 ``hdf5::hdf5_hl_cpp``
10899 ``hdf5::hdf5_fortran``
10900 ``hdf5::hdf5_hl``
10901 ``hdf5::hdf5_hl_cpp``
10902 ``hdf5::hdf5_hl_fortran``
10903 ``hdf5::h5diff``
10904 Hints
10906 The following variables can be set to guide the search for HDF5
10907 libraries and includes:
10908 HDF5_PREFER_PARALLEL
10910 set true to prefer parallel HDF5 (by default, serial is pre‐
10911 ferred)
10912 HDF5_FIND_DEBUG
10914 Set true to get extra debugging output.
10915 HDF5_NO_FIND_PACKAGE_CONFIG_FILE
10917 Set true to skip trying to find hdf5-config.cmake.
10918 FindHg
10920 Extract information from a mercurial working copy.
10921 The module defines the following variables:
10923 HG_EXECUTABLE - path to mercurial command line client (hg)
10925 HG_FOUND - true if the command line client was found
10926 HG_VERSION_STRING - the version of mercurial found
10927 If the command line client executable is found the following macro is
10929 defined:
10930 HG_WC_INFO(<dir> <var-prefix>)
10932 Hg_WC_INFO extracts information of a mercurial working copy at a given
10934 location. This macro defines the following variables:
10935 <var-prefix>_WC_CHANGESET - current changeset
10937 <var-prefix>_WC_REVISION - current revision
10938 Example usage:
10940 find_package(Hg)
10942 if(HG_FOUND)
10943 message("hg found: ${HG_EXECUTABLE}")
10944 HG_WC_INFO(${PROJECT_SOURCE_DIR} Project)
10945 message("Current revision is ${Project_WC_REVISION}")
10946 message("Current changeset is ${Project_WC_CHANGESET}")
10947 endif()
10948 FindHSPELL
10950 Try to find Hebrew spell-checker (Hspell) and morphology engine.
10951 Once done this will define
10953 HSPELL_FOUND - system has Hspell
10955 HSPELL_INCLUDE_DIR - the Hspell include directory
10956 HSPELL_LIBRARIES - The libraries needed to use Hspell
10957 HSPELL_DEFINITIONS - Compiler switches required for using Hspell
10958 HSPELL_VERSION_STRING - The version of Hspell found (x.y)
10960 HSPELL_MAJOR_VERSION - the major version of Hspell
10961 HSPELL_MINOR_VERSION - The minor version of Hspell
10962 FindHTMLHelp
10964 This module looks for Microsoft HTML Help Compiler
10965 It defines:
10967 HTML_HELP_COMPILER : full path to the Compiler (hhc.exe)
10969 HTML_HELP_INCLUDE_PATH : include path to the API (htmlhelp.h)
10970 HTML_HELP_LIBRARY : full path to the library (htmlhelp.lib)
10971 FindIce
10973 New in version 3.1.
10974 Find the ZeroC Internet Communication Engine (ICE) programs, libraries
10977 and datafiles.
10978 This module supports multiple components. Components can include any
10980 of: Freeze, Glacier2, Ice, IceBox, IceDB, IceDiscovery, IceGrid, IceLo‐
10981 catorDiscovery, IcePatch, IceSSL, IceStorm, IceUtil, IceXML, or Slice.
10982 Ice 3.7 and later also include C++11-specific components: Glacier2++11,
10984 Ice++11, IceBox++11, IceDiscovery++11 IceGrid, IceLocatorDiscovery++11,
10985 IceSSL++11, IceStorm++11
10986 Note that the set of supported components is Ice version-specific.
10988 This module reports information about the Ice installation in several
10990 variables. General variables:
10991 Ice_VERSION - Ice release version
10993 Ice_FOUND - true if the main programs and libraries were found
10994 Ice_LIBRARIES - component libraries to be linked
10995 Ice_INCLUDE_DIRS - the directories containing the Ice headers
10996 Ice_SLICE_DIRS - the directories containing the Ice slice interface
10997 definitions
10998 Imported targets:
11000 Ice::<C>
11002 Where <C> is the name of an Ice component, for example Ice::Glacier2 or
11004 Ice++11.
11005 Ice slice programs are reported in:
11007 Ice_SLICE2CONFLUENCE_EXECUTABLE - path to slice2confluence executable
11009 Ice_SLICE2CPP_EXECUTABLE - path to slice2cpp executable
11010 Ice_SLICE2CS_EXECUTABLE - path to slice2cs executable
11011 Ice_SLICE2FREEZEJ_EXECUTABLE - path to slice2freezej executable
11012 Ice_SLICE2FREEZE_EXECUTABLE - path to slice2freeze executable
11013 Ice_SLICE2HTML_EXECUTABLE - path to slice2html executable
11014 Ice_SLICE2JAVA_EXECUTABLE - path to slice2java executable
11015 Ice_SLICE2JS_EXECUTABLE - path to slice2js executable
11016 Ice_SLICE2MATLAB_EXECUTABLE - path to slice2matlab executable
11017 Ice_SLICE2OBJC_EXECUTABLE - path to slice2objc executable
11018 Ice_SLICE2PHP_EXECUTABLE - path to slice2php executable
11019 Ice_SLICE2PY_EXECUTABLE - path to slice2py executable
11020 Ice_SLICE2RB_EXECUTABLE - path to slice2rb executable
11021 Ice programs are reported in:
11023 Ice_GLACIER2ROUTER_EXECUTABLE - path to glacier2router executable
11025 Ice_ICEBOX_EXECUTABLE - path to icebox executable
11026 Ice_ICEBOXXX11_EXECUTABLE - path to icebox++11 executable
11027 Ice_ICEBOXADMIN_EXECUTABLE - path to iceboxadmin executable
11028 Ice_ICEBOXD_EXECUTABLE - path to iceboxd executable
11029 Ice_ICEBOXNET_EXECUTABLE - path to iceboxnet executable
11030 Ice_ICEBRIDGE_EXECUTABLE - path to icebridge executable
11031 Ice_ICEGRIDADMIN_EXECUTABLE - path to icegridadmin executable
11032 Ice_ICEGRIDDB_EXECUTABLE - path to icegriddb executable
11033 Ice_ICEGRIDNODE_EXECUTABLE - path to icegridnode executable
11034 Ice_ICEGRIDNODED_EXECUTABLE - path to icegridnoded executable
11035 Ice_ICEGRIDREGISTRY_EXECUTABLE - path to icegridregistry executable
11036 Ice_ICEGRIDREGISTRYD_EXECUTABLE - path to icegridregistryd executable
11037 Ice_ICEPATCH2CALC_EXECUTABLE - path to icepatch2calc executable
11038 Ice_ICEPATCH2CLIENT_EXECUTABLE - path to icepatch2client executable
11039 Ice_ICEPATCH2SERVER_EXECUTABLE - path to icepatch2server executable
11040 Ice_ICESERVICEINSTALL_EXECUTABLE - path to iceserviceinstall executable
11041 Ice_ICESTORMADMIN_EXECUTABLE - path to icestormadmin executable
11042 Ice_ICESTORMDB_EXECUTABLE - path to icestormdb executable
11043 Ice_ICESTORMMIGRATE_EXECUTABLE - path to icestormmigrate executable
11044 Ice db programs (Windows only; standard system versions on all other
11046 platforms) are reported in:
11047 Ice_DB_ARCHIVE_EXECUTABLE - path to db_archive executable
11049 Ice_DB_CHECKPOINT_EXECUTABLE - path to db_checkpoint executable
11050 Ice_DB_DEADLOCK_EXECUTABLE - path to db_deadlock executable
11051 Ice_DB_DUMP_EXECUTABLE - path to db_dump executable
11052 Ice_DB_HOTBACKUP_EXECUTABLE - path to db_hotbackup executable
11053 Ice_DB_LOAD_EXECUTABLE - path to db_load executable
11054 Ice_DB_LOG_VERIFY_EXECUTABLE - path to db_log_verify executable
11055 Ice_DB_PRINTLOG_EXECUTABLE - path to db_printlog executable
11056 Ice_DB_RECOVER_EXECUTABLE - path to db_recover executable
11057 Ice_DB_STAT_EXECUTABLE - path to db_stat executable
11058 Ice_DB_TUNER_EXECUTABLE - path to db_tuner executable
11059 Ice_DB_UPGRADE_EXECUTABLE - path to db_upgrade executable
11060 Ice_DB_VERIFY_EXECUTABLE - path to db_verify executable
11061 Ice_DUMPDB_EXECUTABLE - path to dumpdb executable
11062 Ice_TRANSFORMDB_EXECUTABLE - path to transformdb executable
11063 Ice component libraries are reported in:
11065 Ice_<C>_FOUND - ON if component was found
11067 Ice_<C>_LIBRARIES - libraries for component
11068 Note that <C> is the uppercased name of the component.
11070 This module reads hints about search results from:
11072 Ice_HOME - the root of the Ice installation
11074 The environment variable ICE_HOME may also be used; the Ice_HOME vari‐
11076 able takes precedence.
11077 NOTE:
11079 On Windows, Ice 3.7.0 and later provide libraries via the NuGet
11080 package manager. Appropriate NuGet packages will be searched for
11081 using CMAKE_PREFIX_PATH, or alternatively Ice_HOME may be set to the
11082 location of a specific NuGet package to restrict the search.
11083 The following cache variables may also be set:
11085 Ice_<P>_EXECUTABLE - the path to executable <P>
11087 Ice_INCLUDE_DIR - the directory containing the Ice headers
11088 Ice_SLICE_DIR - the directory containing the Ice slice interface
11089 definitions
11090 Ice_<C>_LIBRARY - the library for component <C>
11091 NOTE:
11093 In most cases none of the above variables will require setting,
11094 unless multiple Ice versions are available and a specific version is
11095 required. On Windows, the most recent version of Ice will be found
11096 through the registry. On Unix, the programs, headers and libraries
11097 will usually be in standard locations, but Ice_SLICE_DIRS might not
11098 be automatically detected (commonly known locations are searched).
11099 All the other variables are defaulted using Ice_HOME, if set. It’s
11100 possible to set Ice_HOME and selectively specify alternative loca‐
11101 tions for the other components; this might be required for e.g.
11102 newer versions of Visual Studio if the heuristics are not sufficient
11103 to identify the correct programs and libraries for the specific Vis‐
11104 ual Studio version.
11105 Other variables one may set to control this module are:
11107 Ice_DEBUG - Set to ON to enable debug output from FindIce.
11109 FindIconv
11111 New in version 3.11.
11112 This module finds the iconv() POSIX.1 functions on the system. These
11115 functions might be provided in the regular C library or externally in
11116 the form of an additional library.
11117 The following variables are provided to indicate iconv support:
11119 Iconv_FOUND
11121 Variable indicating if the iconv support was found.
11122 Iconv_INCLUDE_DIRS
11124 The directories containing the iconv headers.
11125 Iconv_LIBRARIES
11127 The iconv libraries to be linked.
11128 Iconv_IS_BUILT_IN
11130 A variable indicating whether iconv support is stemming from the
11131 C library or not. Even if the C library provides iconv(), the
11132 presence of an external libiconv implementation might lead to
11133 this being false.
11134 Additionally, the following IMPORTED target is being provided:
11136 Iconv::Iconv
11138 Imported target for using iconv.
11139 The following cache variables may also be set:
11141 Iconv_INCLUDE_DIR
11143 The directory containing the iconv headers.
11144 Iconv_LIBRARY
11146 The iconv library (if not implicitly given in the C library).
11147 NOTE:
11149 On POSIX platforms, iconv might be part of the C library and the
11150 cache variables Iconv_INCLUDE_DIR and Iconv_LIBRARY might be empty.
11151 FindIcotool
11153 Find icotool
11154 This module looks for icotool. Convert and create Win32 icon and cursor
11156 files. This module defines the following values:
11157 ICOTOOL_EXECUTABLE: the full path to the icotool tool.
11159 ICOTOOL_FOUND: True if icotool has been found.
11160 ICOTOOL_VERSION_STRING: the version of icotool found.
11161 FindICU
11163 New in version 3.7.
11164 Find the International Components for Unicode (ICU) libraries and pro‐
11167 grams.
11168 This module supports multiple components. Components can include any
11170 of: data, i18n, io, le, lx, test, tu and uc.
11171 Note that on Windows data is named dt and i18n is named in; any of the
11173 names may be used, and the appropriate platform-specific library name
11174 will be automatically selected.
11175 This module reports information about the ICU installation in several
11177 variables. General variables:
11178 ICU_VERSION - ICU release version
11180 ICU_FOUND - true if the main programs and libraries were found
11181 ICU_LIBRARIES - component libraries to be linked
11182 ICU_INCLUDE_DIRS - the directories containing the ICU headers
11183 Imported targets:
11185 ICU::<C>
11187 Where <C> is the name of an ICU component, for example ICU::i18n.
11189 ICU programs are reported in:
11191 ICU_GENCNVAL_EXECUTABLE - path to gencnval executable
11193 ICU_ICUINFO_EXECUTABLE - path to icuinfo executable
11194 ICU_GENBRK_EXECUTABLE - path to genbrk executable
11195 ICU_ICU-CONFIG_EXECUTABLE - path to icu-config executable
11196 ICU_GENRB_EXECUTABLE - path to genrb executable
11197 ICU_GENDICT_EXECUTABLE - path to gendict executable
11198 ICU_DERB_EXECUTABLE - path to derb executable
11199 ICU_PKGDATA_EXECUTABLE - path to pkgdata executable
11200 ICU_UCONV_EXECUTABLE - path to uconv executable
11201 ICU_GENCFU_EXECUTABLE - path to gencfu executable
11202 ICU_MAKECONV_EXECUTABLE - path to makeconv executable
11203 ICU_GENNORM2_EXECUTABLE - path to gennorm2 executable
11204 ICU_GENCCODE_EXECUTABLE - path to genccode executable
11205 ICU_GENSPREP_EXECUTABLE - path to gensprep executable
11206 ICU_ICUPKG_EXECUTABLE - path to icupkg executable
11207 ICU_GENCMN_EXECUTABLE - path to gencmn executable
11208 ICU component libraries are reported in:
11210 ICU_<C>_FOUND - ON if component was found
11212 ICU_<C>_LIBRARIES - libraries for component
11213 ICU datafiles are reported in:
11215 ICU_MAKEFILE_INC - Makefile.inc
11217 ICU_PKGDATA_INC - pkgdata.inc
11218 Note that <C> is the uppercased name of the component.
11220 This module reads hints about search results from:
11222 ICU_ROOT - the root of the ICU installation
11224 The environment variable ICU_ROOT may also be used; the ICU_ROOT vari‐
11226 able takes precedence.
11227 The following cache variables may also be set:
11229 ICU_<P>_EXECUTABLE - the path to executable <P>
11231 ICU_INCLUDE_DIR - the directory containing the ICU headers
11232 ICU_<C>_LIBRARY - the library for component <C>
11233 NOTE:
11235 In most cases none of the above variables will require setting,
11236 unless multiple ICU versions are available and a specific version is
11237 required.
11238 Other variables one may set to control this module are:
11240 ICU_DEBUG - Set to ON to enable debug output from FindICU.
11242 FindImageMagick
11244 Find ImageMagick binary suite.
11245 This module will search for a set of ImageMagick tools specified as
11247 components in the find_package() call. Typical components include, but
11248 are not limited to (future versions of ImageMagick might have addi‐
11249 tional components not listed here):
11250 animate
11252 compare
11253 composite
11254 conjure
11255 convert
11256 display
11257 identify
11258 import
11259 mogrify
11260 montage
11261 stream
11262 If no component is specified in the find_package() call, then it only
11264 searches for the ImageMagick executable directory. This code defines
11265 the following variables:
11266 ImageMagick_FOUND - TRUE if all components are found.
11268 ImageMagick_EXECUTABLE_DIR - Full path to executables directory.
11269 ImageMagick_<component>_FOUND - TRUE if <component> is found.
11270 ImageMagick_<component>_EXECUTABLE - Full path to <component> executable.
11271 ImageMagick_VERSION_STRING - the version of ImageMagick found
11272 (since CMake 2.8.8)
11273 ImageMagick_VERSION_STRING will not work for old versions like 5.2.3.
11275 There are also components for the following ImageMagick APIs:
11277 Magick++
11279 MagickWand
11280 MagickCore
11281 For these components the following variables are set:
11283 ImageMagick_FOUND - TRUE if all components are found.
11285 ImageMagick_INCLUDE_DIRS - Full paths to all include dirs.
11286 ImageMagick_LIBRARIES - Full paths to all libraries.
11287 ImageMagick_<component>_FOUND - TRUE if <component> is found.
11288 ImageMagick_<component>_INCLUDE_DIRS - Full path to <component> include dirs.
11289 ImageMagick_<component>_LIBRARIES - Full path to <component> libraries.
11290 Example Usages:
11292 find_package(ImageMagick)
11294 find_package(ImageMagick COMPONENTS convert)
11295 find_package(ImageMagick COMPONENTS convert mogrify display)
11296 find_package(ImageMagick COMPONENTS Magick++)
11297 find_package(ImageMagick COMPONENTS Magick++ convert)
11298 Note that the standard find_package() features are supported (i.e.,
11300 QUIET, REQUIRED, etc.).
11301 FindIntl
11303 New in version 3.2.
11304 Find the Gettext libintl headers and libraries.
11307 This module reports information about the Gettext libintl installation
11309 in several variables. General variables:
11310 Intl_FOUND - true if the libintl headers and libraries were found
11312 Intl_INCLUDE_DIRS - the directory containing the libintl headers
11313 Intl_LIBRARIES - libintl libraries to be linked
11314 The following cache variables may also be set:
11316 Intl_INCLUDE_DIR - the directory containing the libintl headers
11318 Intl_LIBRARY - the libintl library (if any)
11319 NOTE:
11321 On some platforms, such as Linux with GNU libc, the gettext func‐
11322 tions are present in the C standard library and libintl is not
11323 required. Intl_LIBRARIES will be empty in this case.
11324 NOTE:
11326 If you wish to use the Gettext tools (msgmerge, msgfmt, etc.), use
11327 FindGettext.
11328 FindITK
11330 This module no longer exists.
11331 This module existed in versions of CMake prior to 3.1, but became only
11333 a thin wrapper around find_package(ITK NO_MODULE) to provide compati‐
11334 bility for projects using long-outdated conventions. Now find_pack‐
11335 age(ITK) will search for ITKConfig.cmake directly.
11336 FindJasper
11338 Try to find the Jasper JPEG2000 library
11339 Once done this will define
11341 JASPER_FOUND - system has Jasper
11343 JASPER_INCLUDE_DIR - the Jasper include directory
11344 JASPER_LIBRARIES - the libraries needed to use Jasper
11345 JASPER_VERSION_STRING - the version of Jasper found (since CMake 2.8.8)
11346 FindJava
11348 Find Java
11349 This module finds if Java is installed and determines where the include
11351 files and libraries are. The caller may set variable JAVA_HOME to
11352 specify a Java installation prefix explicitly.
11353 See also the FindJNI module to find Java Native Interface (JNI).
11355 Specify one or more of the following components as you call this find
11357 module. See example below.
11358 Runtime = Java Runtime Environment used to execute Java byte-compiled applications
11360 Development = Development tools (java, javac, javah, jar and javadoc), includes Runtime component
11361 IdlJ = Interface Description Language (IDL) to Java compiler
11362 JarSigner = Signer and verifier tool for Java Archive (JAR) files
11363 This module sets the following result variables:
11365 Java_JAVA_EXECUTABLE = the full path to the Java runtime
11367 Java_JAVAC_EXECUTABLE = the full path to the Java compiler
11368 Java_JAVAH_EXECUTABLE = the full path to the Java header generator
11369 Java_JAVADOC_EXECUTABLE = the full path to the Java documentation generator
11370 Java_IDLJ_EXECUTABLE = the full path to the Java idl compiler
11371 Java_JAR_EXECUTABLE = the full path to the Java archiver
11372 Java_JARSIGNER_EXECUTABLE = the full path to the Java jar signer
11373 Java_VERSION_STRING = Version of java found, eg. 1.6.0_12
11374 Java_VERSION_MAJOR = The major version of the package found.
11375 Java_VERSION_MINOR = The minor version of the package found.
11376 Java_VERSION_PATCH = The patch version of the package found.
11377 Java_VERSION_TWEAK = The tweak version of the package found (after '_')
11378 Java_VERSION = This is set to: $major[.$minor[.$patch[.$tweak]]]
11379 The minimum required version of Java can be specified using the
11381 find_package() syntax, e.g.
11382 find_package(Java 1.8)
11384 NOTE: ${Java_VERSION} and ${Java_VERSION_STRING} are not guaranteed to
11386 be identical. For example some java version may return: Java_VER‐
11387 SION_STRING = 1.8.0_17 and Java_VERSION = 1.8.0.17
11388 another example is the Java OEM, with: Java_VERSION_STRING = 1.8.0-oem
11390 and Java_VERSION = 1.8.0
11391 For these components the following variables are set:
11393 Java_FOUND - TRUE if all components are found.
11395 Java_<component>_FOUND - TRUE if <component> is found.
11396 Example Usages:
11398 find_package(Java)
11400 find_package(Java 1.8 REQUIRED)
11401 find_package(Java COMPONENTS Runtime)
11402 find_package(Java COMPONENTS Development)
11403 FindJNI
11405 Find Java Native Interface (JNI) libraries.
11406 JNI enables Java code running in a Java Virtual Machine (JVM) to call
11408 and be called by native applications and libraries written in other
11409 languages such as C, C++.
11410 This module finds if Java is installed and determines where the include
11412 files and libraries are. It also determines what the name of the
11413 library is. The caller may set variable JAVA_HOME to specify a Java
11414 installation prefix explicitly.
11415 Result Variables
11417 This module sets the following result variables:
11418 JNI_INCLUDE_DIRS
11420 the include dirs to use
11421 JNI_LIBRARIES
11423 the libraries to use (JAWT and JVM)
11424 JNI_FOUND
11426 TRUE if JNI headers and libraries were found.
11427 Cache Variables
11429 The following cache variables are also available to set or use:
11430 JAVA_AWT_LIBRARY
11432 the path to the Java AWT Native Interface (JAWT) library
11433 JAVA_JVM_LIBRARY
11435 the path to the Java Virtual Machine (JVM) library
11436 JAVA_INCLUDE_PATH
11438 the include path to jni.h
11439 JAVA_INCLUDE_PATH2
11441 the include path to jni_md.h and jniport.h
11442 JAVA_AWT_INCLUDE_PATH
11444 the include path to jawt.h
11445 FindJPEG
11447 Find the Joint Photographic Experts Group (JPEG) library (libjpeg)
11448 Imported targets
11450 This module defines the following IMPORTED targets:
11451 JPEG::JPEG
11453 The JPEG library, if found.
11454 Result variables
11456 This module will set the following variables in your project:
11457 JPEG_FOUND
11459 If false, do not try to use JPEG.
11460 JPEG_INCLUDE_DIRS
11462 where to find jpeglib.h, etc.
11463 JPEG_LIBRARIES
11465 the libraries needed to use JPEG.
11466 JPEG_VERSION
11468 the version of the JPEG library found
11469 Cache variables
11471 The following cache variables may also be set:
11472 JPEG_INCLUDE_DIRS
11474 where to find jpeglib.h, etc.
11475 JPEG_LIBRARY_RELEASE
11477 where to find the JPEG library (optimized).
11478 JPEG_LIBRARY_DEBUG
11480 where to find the JPEG library (debug).
11481 Obsolete variables
11483 JPEG_INCLUDE_DIR
11484 where to find jpeglib.h, etc. (same as JPEG_INCLUDE_DIRS)
11485 JPEG_LIBRARY
11487 where to find the JPEG library.
11488 FindKDE3
11490 Find the KDE3 include and library dirs, KDE preprocessors and define a
11491 some macros
11492 This module defines the following variables:
11494 KDE3_DEFINITIONS
11496 compiler definitions required for compiling KDE software
11497 KDE3_INCLUDE_DIR
11499 the KDE include directory
11500 KDE3_INCLUDE_DIRS
11502 the KDE and the Qt include directory, for use with
11503 include_directories()
11504 KDE3_LIB_DIR
11506 the directory where the KDE libraries are installed, for use
11507 with link_directories()
11508 QT_AND_KDECORE_LIBS
11510 this contains both the Qt and the kdecore library
11511 KDE3_DCOPIDL_EXECUTABLE
11513 the dcopidl executable
11514 KDE3_DCOPIDL2CPP_EXECUTABLE
11516 the dcopidl2cpp executable
11517 KDE3_KCFGC_EXECUTABLE
11519 the kconfig_compiler executable
11520 KDE3_FOUND
11522 set to TRUE if all of the above has been found
11523 The following user adjustable options are provided:
11525 KDE3_BUILD_TESTS
11527 enable this to build KDE testcases
11528 It also adds the following macros (from KDE3Macros.cmake) SRCS_VAR is
11530 always the variable which contains the list of source files for your
11531 application or library.
11532 KDE3_AUTOMOC(file1 … fileN)
11534 Call this if you want to have automatic moc file handling.
11536 This means if you include "foo.moc" in the source file foo.cpp
11537 a moc file for the header foo.h will be created automatically.
11538 You can set the property SKIP_AUTOMAKE using set_source_files_properties()
11539 to exclude some files in the list from being processed.
11540 KDE3_ADD_MOC_FILES(SRCS_VAR file1 … fileN )
11542 If you don't use the KDE3_AUTOMOC() macro, for the files
11544 listed here moc files will be created (named "foo.moc.cpp")
11545 KDE3_ADD_DCOP_SKELS(SRCS_VAR header1.h … headerN.h )
11547 Use this to generate DCOP skeletions from the listed headers.
11549 KDE3_ADD_DCOP_STUBS(SRCS_VAR header1.h … headerN.h )
11551 Use this to generate DCOP stubs from the listed headers.
11553 KDE3_ADD_UI_FILES(SRCS_VAR file1.ui … fileN.ui )
11555 Use this to add the Qt designer ui files to your application/library.
11557 KDE3_ADD_KCFG_FILES(SRCS_VAR file1.kcfgc … fileN.kcfgc )
11559 Use this to add KDE kconfig compiler files to your application/library.
11561 KDE3_INSTALL_LIBTOOL_FILE(target)
11563 This will create and install a simple libtool file for the given target.
11565 KDE3_ADD_EXECUTABLE(name file1 … fileN )
11567 Currently identical to add_executable(), may provide some advanced
11569 features in the future.
11570 KDE3_ADD_KPART(name [WITH_PREFIX] file1 … fileN )
11572 Create a KDE plugin (KPart, kioslave, etc.) from the given source files.
11574 If WITH_PREFIX is given, the resulting plugin will have the prefix "lib",
11575 otherwise it won't.
11576 It creates and installs an appropriate libtool la-file.
11577 KDE3_ADD_KDEINIT_EXECUTABLE(name file1 … fileN )
11579 Create a KDE application in the form of a module loadable via kdeinit.
11581 A library named kdeinit_<name> will be created and a small executable
11582 which links to it.
11583 The option KDE3_ENABLE_FINAL to enable all-in-one compilation is no
11585 longer supported.
11586 Author: Alexander Neundorf <neundorf@kde.org>
11588 FindKDE4
11590 Find KDE4 and provide all necessary variables and macros to compile
11591 software for it. It looks for KDE 4 in the following directories in
11592 the given order:
11593 CMAKE_INSTALL_PREFIX
11595 KDEDIRS
11596 /opt/kde4
11597 Please look in FindKDE4Internal.cmake and KDE4Macros.cmake for more
11599 information. They are installed with the KDE 4 libraries in
11600 $KDEDIRS/share/apps/cmake/modules/.
11601 Author: Alexander Neundorf <neundorf@kde.org>
11603 FindLAPACK
11605 Find Linear Algebra PACKage (LAPACK) library
11606 This module finds an installed Fortran library that implements the
11608 LAPACK linear-algebra interface (see http://www.netlib.org/lapack/).
11609 The approach follows that taken for the autoconf macro file,
11611 acx_lapack.m4 (distributed at
11612 http://ac-archive.sourceforge.net/ac-archive/acx_lapack.html).
11613 Input Variables
11615 The following variables may be set to influence this module’s behavior:
11616 BLA_STATIC
11618 if ON use static linkage
11619 BLA_VENDOR
11621 If set, checks only the specified vendor, if not set checks all
11622 the possibilities. List of vendors valid in this module:
11623 · FlexiBLAS
11625 · OpenBLAS
11627 · FLAME
11629 · Intel10_32 (intel mkl v10 32 bit, threaded code)
11631 · Intel10_64lp (intel mkl v10+ 64 bit, threaded code, lp64
11633 model)
11634 · Intel10_64lp_seq (intel mkl v10+ 64 bit, sequential code, lp64
11636 model)
11637 · Intel10_64ilp (intel mkl v10+ 64 bit, threaded code, ilp64
11639 model)
11640 · Intel10_64ilp_seq (intel mkl v10+ 64 bit, sequential code,
11642 ilp64 model)
11643 · Intel10_64_dyn (intel mkl v10+ 64 bit, single dynamic library)
11645 · Intel (obsolete versions of mkl 32 and 64 bit)
11647 · ACML
11649 · Apple
11651 · NAS
11653 · Arm
11655 · Arm_mp
11657 · Arm_ilp64
11659 · Arm_ilp64_mp
11661 · Generic
11663 BLA_F95
11665 if ON tries to find the BLAS95/LAPACK95 interfaces
11666 Imported targets
11668 This module defines the following IMPORTED target:
11669 LAPACK::LAPACK
11671 The libraries to use for LAPACK, if found.
11672 Result Variables
11674 This module defines the following variables:
11675 LAPACK_FOUND
11677 library implementing the LAPACK interface is found
11678 LAPACK_LINKER_FLAGS
11680 uncached list of required linker flags (excluding -l and -L).
11681 LAPACK_LIBRARIES
11683 uncached list of libraries (using full path name) to link
11684 against to use LAPACK
11685 LAPACK95_LIBRARIES
11687 uncached list of libraries (using full path name) to link
11688 against to use LAPACK95
11689 LAPACK95_FOUND
11691 library implementing the LAPACK95 interface is found
11692 NOTE:
11694 C, CXX or Fortran must be enabled to detect a BLAS/LAPACK library.
11695 C or CXX must be enabled to use Intel Math Kernel Library (MKL).
11696 For example, to use Intel MKL libraries and/or Intel compiler:
11698 set(BLA_VENDOR Intel10_64lp)
11700 find_package(LAPACK)
11701 FindLATEX
11703 Find LaTeX
11704 This module finds an installed LaTeX and determines the location of the
11706 compiler. Additionally the module looks for Latex-related software
11707 like BibTeX.
11708 This module sets the following result variables:
11710 LATEX_FOUND: whether found Latex and requested components
11712 LATEX_<component>_FOUND: whether found <component>
11713 LATEX_COMPILER: path to the LaTeX compiler
11714 PDFLATEX_COMPILER: path to the PdfLaTeX compiler
11715 XELATEX_COMPILER: path to the XeLaTeX compiler
11716 LUALATEX_COMPILER: path to the LuaLaTeX compiler
11717 BIBTEX_COMPILER: path to the BibTeX compiler
11718 BIBER_COMPILER: path to the Biber compiler
11719 MAKEINDEX_COMPILER: path to the MakeIndex compiler
11720 XINDY_COMPILER: path to the xindy compiler
11721 DVIPS_CONVERTER: path to the DVIPS converter
11722 DVIPDF_CONVERTER: path to the DVIPDF converter
11723 PS2PDF_CONVERTER: path to the PS2PDF converter
11724 PDFTOPS_CONVERTER: path to the pdftops converter
11725 LATEX2HTML_CONVERTER: path to the LaTeX2Html converter
11726 HTLATEX_COMPILER: path to the htlatex compiler
11727 Possible components are:
11729 PDFLATEX
11731 XELATEX
11732 LUALATEX
11733 BIBTEX
11734 BIBER
11735 MAKEINDEX
11736 XINDY
11737 DVIPS
11738 DVIPDF
11739 PS2PDF
11740 PDFTOPS
11741 LATEX2HTML
11742 HTLATEX
11743 Example Usages:
11745 find_package(LATEX)
11747 find_package(LATEX COMPONENTS PDFLATEX)
11748 find_package(LATEX COMPONENTS BIBTEX PS2PDF)
11749 FindLibArchive
11751 Find libarchive library and headers. Libarchive is multi-format ar‐
11752 chive and compression library.
11753 The module defines the following variables:
11755 LibArchive_FOUND - true if libarchive was found
11757 LibArchive_INCLUDE_DIRS - include search path
11758 LibArchive_LIBRARIES - libraries to link
11759 LibArchive_VERSION - libarchive 3-component version number
11760 The module defines the following IMPORTED targets:
11762 LibArchive::LibArchive - target for linking against libarchive
11764 FindLibinput
11766 New in version 3.14.
11767 Find libinput headers and library.
11770 Imported Targets
11772 Libinput::Libinput
11773 The libinput library, if found.
11774 Result Variables
11776 This will define the following variables in your project:
11777 Libinput_FOUND
11779 true if (the requested version of) libinput is available.
11780 Libinput_VERSION
11782 the version of libinput.
11783 Libinput_LIBRARIES
11785 the libraries to link against to use libinput.
11786 Libinput_INCLUDE_DIRS
11788 where to find the libinput headers.
11789 Libinput_COMPILE_OPTIONS
11791 this should be passed to target_compile_options(), if the target
11792 is not used for linking
11793 FindLibLZMA
11795 Find LZMA compression algorithm headers and library.
11796 Imported Targets
11798 This module defines IMPORTED target LibLZMA::LibLZMA, if liblzma has
11799 been found.
11800 Result variables
11802 This module will set the following variables in your project:
11803 LIBLZMA_FOUND
11805 True if liblzma headers and library were found.
11806 LIBLZMA_INCLUDE_DIRS
11808 Directory where liblzma headers are located.
11809 LIBLZMA_LIBRARIES
11811 Lzma libraries to link against.
11812 LIBLZMA_HAS_AUTO_DECODER
11814 True if lzma_auto_decoder() is found (required).
11815 LIBLZMA_HAS_EASY_ENCODER
11817 True if lzma_easy_encoder() is found (required).
11818 LIBLZMA_HAS_LZMA_PRESET
11820 True if lzma_lzma_preset() is found (required).
11821 LIBLZMA_VERSION_MAJOR
11823 The major version of lzma
11824 LIBLZMA_VERSION_MINOR
11826 The minor version of lzma
11827 LIBLZMA_VERSION_PATCH
11829 The patch version of lzma
11830 LIBLZMA_VERSION_STRING
11832 version number as a string (ex: “5.0.3”)
11833 FindLibXml2
11835 Find the XML processing library (libxml2).
11836 IMPORTED Targets
11838 The following IMPORTED targets may be defined:
11839 LibXml2::LibXml2
11841 If the libxml2 library has been found
11842 LibXml2::xmllint
11844 If the xmllint command-line executable has been found
11845 Result variables
11847 This module will set the following variables in your project:
11848 LibXml2_FOUND
11850 true if libxml2 headers and libraries were found
11851 LIBXML2_INCLUDE_DIR
11853 the directory containing LibXml2 headers
11854 LIBXML2_INCLUDE_DIRS
11856 list of the include directories needed to use LibXml2
11857 LIBXML2_LIBRARIES
11859 LibXml2 libraries to be linked
11860 LIBXML2_DEFINITIONS
11862 the compiler switches required for using LibXml2
11863 LIBXML2_XMLLINT_EXECUTABLE
11865 path to the XML checking tool xmllint coming with LibXml2
11866 LIBXML2_VERSION_STRING
11868 the version of LibXml2 found (since CMake 2.8.8)
11869 Cache variables
11871 The following cache variables may also be set:
11872 LIBXML2_INCLUDE_DIR
11874 the directory containing LibXml2 headers
11875 LIBXML2_LIBRARY
11877 path to the LibXml2 library
11878 FindLibXslt
11880 Find the XSL Transformations, Extensible Stylesheet Language Transfor‐
11881 mations (XSLT) library (LibXslt)
11882 IMPORTED Targets
11884 The following IMPORTED targets may be defined:
11885 LibXslt::LibXslt
11887 If the libxslt library has been found
11888 LibXslt::LibExslt
11890 If the libexslt library has been found
11891 LibXslt::xsltproc
11893 If the xsltproc command-line executable has been found
11894 Result variables
11896 This module will set the following variables in your project:
11897 LIBXSLT_FOUND - system has LibXslt LIBXSLT_INCLUDE_DIR - the LibXslt
11898 include directory LIBXSLT_LIBRARIES - Link these to LibXslt
11899 LIBXSLT_DEFINITIONS - Compiler switches required for using LibXslt
11900 LIBXSLT_VERSION_STRING - version of LibXslt found (since CMake
11901 2.8.8)
11902 Additionally, the following two variables are set (but not required for
11904 using xslt):
11905 LIBXSLT_EXSLT_INCLUDE_DIR
11907 The include directory for exslt.
11908 LIBXSLT_EXSLT_LIBRARIES
11910 Link to these if you need to link against the exslt library.
11911 LIBXSLT_XSLTPROC_EXECUTABLE
11913 Contains the full path to the xsltproc executable if found.
11914 FindLTTngUST
11916 New in version 3.6.
11917 Find Linux Trace Toolkit Next Generation (LTTng-UST) library.
11920 Imported target
11922 This module defines the following IMPORTED target:
11923 LTTng::UST
11925 The LTTng-UST library, if found
11926 Result variables
11928 This module sets the following
11929 LTTNGUST_FOUND
11931 TRUE if system has LTTng-UST
11932 LTTNGUST_INCLUDE_DIRS
11934 The LTTng-UST include directories
11935 LTTNGUST_LIBRARIES
11937 The libraries needed to use LTTng-UST
11938 LTTNGUST_VERSION_STRING
11940 The LTTng-UST version
11941 LTTNGUST_HAS_TRACEF
11943 TRUE if the tracef() API is available in the system’s LTTng-UST
11944 LTTNGUST_HAS_TRACELOG
11946 TRUE if the tracelog() API is available in the system’s
11947 LTTng-UST
11948 FindLua
11950 Locate Lua library.
11951 This module defines:
11953 ::
11955 LUA_FOUND - if false, do not try to link to Lua
11956 LUA_LIBRARIES - both lua and lualib LUA_INCLUDE_DIR - where
11957 to find lua.h LUA_VERSION_STRING - the version of Lua found LUA_VER‐
11958 SION_MAJOR - the major version of Lua LUA_VERSION_MINOR - the
11959 minor version of Lua LUA_VERSION_PATCH - the patch version of Lua
11960 Note that the expected include convention is
11962 #include "lua.h"
11964 and not
11966 #include <lua/lua.h>
11968 This is because, the lua location is not standardized and may exist in
11970 locations other than lua/
11971 FindLua50
11973 Locate Lua library. This module defines:
11974 ::
11976 LUA50_FOUND, if false, do not try to link to Lua LUA_LIBRARIES, both
11977 lua and lualib LUA_INCLUDE_DIR, where to find lua.h and lualib.h
11978 (and probably lauxlib.h)
11979 Note that the expected include convention is
11981 #include "lua.h"
11983 and not
11985 #include <lua/lua.h>
11987 This is because, the lua location is not standardized and may exist in
11989 locations other than lua/
11990 FindLua51
11992 Locate Lua library. This module defines:
11993 ::
11995 LUA51_FOUND, if false, do not try to link to Lua LUA_LIBRARIES
11996 LUA_INCLUDE_DIR, where to find lua.h LUA_VERSION_STRING, the version
11997 of Lua found (since CMake 2.8.8)
11998 Note that the expected include convention is
12000 #include "lua.h"
12002 and not
12004 #include <lua/lua.h>
12006 This is because, the lua location is not standardized and may exist in
12008 locations other than lua/
12009 FindMatlab
12011 Finds Matlab or Matlab Compiler Runtime (MCR) and provides Matlab
12012 tools, libraries and compilers to CMake.
12013 This package primary purpose is to find the libraries associated with
12015 Matlab or the MCR in order to be able to build Matlab extensions (mex
12016 files). It can also be used:
12017 · to run specific commands in Matlab in case Matlab is available
12019 · for declaring Matlab unit test
12021 · to retrieve various information from Matlab (mex extensions, versions
12023 and release queries, …)
12024 The module supports the following components:
12026 · ENG_LIBRARY and MAT_LIBRARY: respectively the ENG and MAT libraries
12028 of Matlab
12029 · MAIN_PROGRAM the Matlab binary program. Note that this component is
12031 not available on the MCR version, and will yield an error if the MCR
12032 is found instead of the regular Matlab installation.
12033 · MEX_COMPILER the MEX compiler.
12035 · MCC_COMPILER the MCC compiler, included with the Matlab Compiler
12037 add-on.
12038 · SIMULINK the Simulink environment.
12040 NOTE:
12042 The version given to the find_package() directive is the Matlab ver‐
12043 sion, which should not be confused with the Matlab release name (eg.
12044 R2014). The matlab_get_version_from_release_name() and
12045 matlab_get_release_name_from_version() provide a mapping between the
12046 release name and the version.
12047 The variable Matlab_ROOT_DIR may be specified in order to give the path
12049 of the desired Matlab version. Otherwise, the behaviour is platform
12050 specific:
12051 · Windows: The installed versions of Matlab/MCR are retrieved from the
12053 Windows registry
12054 · OS X: The installed versions of Matlab/MCR are given by the MATLAB
12056 default installation paths in /Application. If no such application is
12057 found, it falls back to the one that might be accessible from the
12058 PATH.
12059 · Unix: The desired Matlab should be accessible from the PATH. This
12061 does not work for MCR installation and Matlab_ROOT_DIR should be
12062 specified on this platform.
12063 Additional information is provided when MATLAB_FIND_DEBUG is set. When
12065 a Matlab/MCR installation is found automatically and the MATLAB_VERSION
12066 is not given, the version is queried from Matlab directly (on Windows
12067 this may pop up a Matlab window) or from the MCR installation.
12068 The mapping of the release names and the version of Matlab is performed
12070 by defining pairs (name, version). The variable
12071 MATLAB_ADDITIONAL_VERSIONS may be provided before the call to the
12072 find_package() in order to handle additional versions.
12073 A Matlab scripts can be added to the set of tests using the
12075 matlab_add_unit_test(). By default, the Matlab unit test framework will
12076 be used (>= 2013a) to run this script, but regular .m files returning
12077 an exit code can be used as well (0 indicating a success).
12078 Module Input Variables
12080 Users or projects may set the following variables to configure the mod‐
12081 ule behaviour:
12082 Matlab_ROOT_DIR
12084 the root of the Matlab installation.
12085 MATLAB_FIND_DEBUG
12087 outputs debug information
12088 MATLAB_ADDITIONAL_VERSIONS
12090 additional versions of Matlab for the automatic retrieval of the
12091 installed versions.
12092 Variables defined by the module
12094 Result variables
12095 Matlab_FOUND
12096 TRUE if the Matlab installation is found, FALSE otherwise. All
12097 variable below are defined if Matlab is found.
12098 Matlab_ROOT_DIR
12100 the final root of the Matlab installation determined by the
12101 FindMatlab module.
12102 Matlab_MAIN_PROGRAM
12104 the Matlab binary program. Available only if the component
12105 MAIN_PROGRAM is given in the find_package() directive.
12106 Matlab_INCLUDE_DIRS
12108 the path of the Matlab libraries headers
12109 Matlab_MEX_LIBRARY
12111 library for mex, always available.
12112 Matlab_MX_LIBRARY
12114 mx library of Matlab (arrays), always available.
12115 Matlab_ENG_LIBRARY
12117 Matlab engine library. Available only if the component
12118 ENG_LIBRARY is requested.
12119 Matlab_MAT_LIBRARY
12121 Matlab matrix library. Available only if the component
12122 MAT_LIBRARY is requested.
12123 Matlab_ENGINE_LIBRARY
12125 Matlab C++ engine library, always available for R2018a and
12126 newer.
12127 Matlab_DATAARRAY_LIBRARY
12129 Matlab C++ data array library, always available for R2018a and
12130 newer.
12131 Matlab_LIBRARIES
12133 the whole set of libraries of Matlab
12134 Matlab_MEX_COMPILER
12136 the mex compiler of Matlab. Currently not used. Available only
12137 if the component MEX_COMPILER is requested.
12138 Matlab_MCC_COMPILER
12140 the mcc compiler of Matlab. Included with the Matlab Compiler
12141 add-on. Available only if the component MCC_COMPILER is
12142 requested.
12143 Cached variables
12145 Matlab_MEX_EXTENSION
12146 the extension of the mex files for the current platform (given
12147 by Matlab).
12148 Matlab_ROOT_DIR
12150 the location of the root of the Matlab installation found. If
12151 this value is changed by the user, the result variables are
12152 recomputed.
12153 Provided macros
12155 matlab_get_version_from_release_name()
12156 returns the version from the release name
12157 matlab_get_release_name_from_version()
12159 returns the release name from the Matlab version
12160 Provided functions
12162 matlab_add_mex()
12163 adds a target compiling a MEX file.
12164 matlab_add_unit_test()
12166 adds a Matlab unit test file as a test to the project.
12167 matlab_extract_all_installed_versions_from_registry()
12169 parses the registry for all Matlab versions. Available on Win‐
12170 dows only. The part of the registry parsed is dependent on the
12171 host processor
12172 matlab_get_all_valid_matlab_roots_from_registry()
12174 returns all the possible Matlab or MCR paths, according to a
12175 previously given list. Only the existing/accessible paths are
12176 kept. This is mainly useful for the searching all possible Mat‐
12177 lab installation.
12178 matlab_get_mex_suffix()
12180 returns the suffix to be used for the mex files (platform/archi‐
12181 tecture dependent)
12182 matlab_get_version_from_matlab_run()
12184 returns the version of Matlab/MCR, given the full directory of
12185 the Matlab/MCR installation path.
12186 Known issues
12188 Symbol clash in a MEX target
12189 By default, every symbols inside a MEX file defined with the
12190 command matlab_add_mex() have hidden visibility, except for the
12191 entry point. This is the default behaviour of the MEX compiler,
12192 which lowers the risk of symbol collision between the libraries
12193 shipped with Matlab, and the libraries to which the MEX file is
12194 linking to. This is also the default on Windows platforms.
12195 However, this is not sufficient in certain case, where for
12197 instance your MEX file is linking against libraries that are
12198 already loaded by Matlab, even if those libraries have different
12199 SONAMES. A possible solution is to hide the symbols of the
12200 libraries to which the MEX target is linking to. This can be
12201 achieved in GNU GCC compilers with the linker option
12202 -Wl,--exclude-libs,ALL.
12203 Tests using GPU resources
12205 in case your MEX file is using the GPU and in order to be able
12206 to run unit tests on this MEX file, the GPU resources should be
12207 properly released by Matlab. A possible solution is to make Mat‐
12208 lab aware of the use of the GPU resources in the session, which
12209 can be performed by a command such as D = gpuDevice() at the
12210 beginning of the test script (or via a fixture).
12211 Reference
12213 Matlab_ROOT_DIR
12214 The root folder of the Matlab installation. If set before the
12215 call to find_package(), the module will look for the components
12216 in that path. If not set, then an automatic search of Matlab
12217 will be performed. If set, it should point to a valid version of
12218 Matlab.
12219 MATLAB_FIND_DEBUG
12221 If set, the lookup of Matlab and the intermediate configuration
12222 steps are outputted to the console.
12223 MATLAB_ADDITIONAL_VERSIONS
12225 If set, specifies additional versions of Matlab that may be
12226 looked for. The variable should be a list of strings, organised
12227 by pairs of release name and versions, such as follows:
12228 set(MATLAB_ADDITIONAL_VERSIONS
12230 "release_name1=corresponding_version1"
12231 "release_name2=corresponding_version2"
12232 ...
12233 )
12234 Example:
12236 set(MATLAB_ADDITIONAL_VERSIONS
12238 "R2013b=8.2"
12239 "R2013a=8.1"
12240 "R2012b=8.0")
12241 The order of entries in this list matters when several versions
12243 of Matlab are installed. The priority is set according to the
12244 ordering in this list.
12245 matlab_get_version_from_release_name
12247 Returns the version of Matlab (17.58) from a release name
12248 (R2017k)
12249 matlab_get_release_name_from_version
12251 Returns the release name (R2017k) from the version of Matlab
12252 (17.58)
12253 matlab_extract_all_installed_versions_from_registry
12255 This function parses the registry and founds the Matlab versions
12256 that are installed. The found versions are returned in mat‐
12257 lab_versions. Set win64 to TRUE if the 64 bit version of Matlab
12258 should be looked for The returned list contains all versions
12259 under HKLM\\SOFTWARE\\Mathworks\\MATLAB and HKLM\\SOFT‐
12260 WARE\\Mathworks\\MATLAB Runtime or an empty list in case an
12261 error occurred (or nothing found).
12262 NOTE:
12264 Only the versions are provided. No check is made over the
12265 existence of the installation referenced in the registry,
12266 matlab_get_all_valid_matlab_roots_from_registry
12268 Populates the Matlab root with valid versions of Matlab or Mat‐
12269 lab Runtime (MCR). The returned matlab_roots is organized in
12270 triplets (type,version_number,matlab_root_path), where type
12271 indicates either MATLAB or MCR.
12272 matlab_get_all_valid_matlab_roots_from_registry(
12274 matlab_versions
12275 matlab_roots)
12276 matlab_versions
12278 the versions of each of the Matlab or MCR installations
12279 matlab_roots
12281 the location of each of the Matlab or MCR installations
12282 matlab_get_mex_suffix
12284 Returns the extension of the mex files (the suffixes). This
12285 function should not be called before the appropriate Matlab root
12286 has been found.
12287 matlab_get_mex_suffix(
12289 matlab_root
12290 mex_suffix)
12291 matlab_root
12293 the root of the Matlab/MCR installation
12294 mex_suffix
12296 the variable name in which the suffix will be returned.
12297 matlab_get_version_from_matlab_run
12299 This function runs Matlab program specified on arguments and
12300 extracts its version. If the path provided for the Matlab
12301 installation points to an MCR installation, the version is
12302 extracted from the installed files.
12303 matlab_get_version_from_matlab_run(
12305 matlab_binary_path
12306 matlab_list_versions)
12307 matlab_binary_path
12309 the location of the matlab binary executable
12310 matlab_list_versions
12312 the version extracted from Matlab
12313 matlab_add_unit_test
12315 Adds a Matlab unit test to the test set of cmake/ctest. This
12316 command requires the component MAIN_PROGRAM and hence is not
12317 available for an MCR installation.
12318 The unit test uses the Matlab unittest framework (default,
12320 available starting Matlab 2013b+) except if the option
12321 NO_UNITTEST_FRAMEWORK is given.
12322 The function expects one Matlab test script file to be given.
12324 In the case NO_UNITTEST_FRAMEWORK is given, the unittest script
12325 file should contain the script to be run, plus an exit command
12326 with the exit value. This exit value will be passed to the ctest
12327 framework (0 success, non 0 failure). Additional arguments
12328 accepted by add_test() can be passed through TEST_ARGS (eg. CON‐
12329 FIGURATION <config> ...).
12330 matlab_add_unit_test(
12332 NAME <name>
12333 UNITTEST_FILE matlab_file_containing_unittest.m
12334 [CUSTOM_TEST_COMMAND matlab_command_to_run_as_test]
12335 [UNITTEST_PRECOMMAND matlab_command_to_run]
12336 [TIMEOUT timeout]
12337 [ADDITIONAL_PATH path1 [path2 ...]]
12338 [MATLAB_ADDITIONAL_STARTUP_OPTIONS option1 [option2 ...]]
12339 [TEST_ARGS arg1 [arg2 ...]]
12340 [NO_UNITTEST_FRAMEWORK]
12341 )
12342 The function arguments are:
12344 NAME name of the unittest in ctest.
12346 UNITTEST_FILE
12348 the matlab unittest file. Its path will be automatically
12349 added to the Matlab path.
12350 CUSTOM_TEST_COMMAND
12352 Matlab script command to run as the test. If this is not
12353 set, then the following is run: runtests('mat‐
12354 lab_file_name'), exit(max([ans(1,:).Failed])) where mat‐
12355 lab_file_name is the UNITTEST_FILE without the extension.
12356 UNITTEST_PRECOMMAND
12358 Matlab script command to be ran before the file contain‐
12359 ing the test (eg. GPU device initialisation based on
12360 CMake variables).
12361 TIMEOUT
12363 the test timeout in seconds. Defaults to 180 seconds as
12364 the Matlab unit test may hang.
12365 ADDITIONAL_PATH
12367 a list of paths to add to the Matlab path prior to run‐
12368 ning the unit test.
12369 MATLAB_ADDITIONAL_STARTUP_OPTIONS
12371 a list of additional option in order to run Matlab from
12372 the command line. -nosplash -nodesktop -nodisplay are
12373 always added.
12374 TEST_ARGS
12376 Additional options provided to the add_test command.
12377 These options are added to the default options (eg. “CON‐
12378 FIGURATIONS Release”)
12379 NO_UNITTEST_FRAMEWORK
12381 when set, indicates that the test should not use the
12382 unittest framework of Matlab (available for versions >=
12383 R2013a).
12384 WORKING_DIRECTORY
12386 This will be the working directory for the test. If spec‐
12387 ified it will also be the output directory used for the
12388 log file of the test run. If not specified the temporary
12389 directory ${CMAKE_BINARY_DIR}/Matlab will be used as the
12390 working directory and the log location.
12391 matlab_add_mex
12393 Adds a Matlab MEX target. This commands compiles the given
12394 sources with the current tool-chain in order to produce a MEX
12395 file. The final name of the produced output may be specified, as
12396 well as additional link libraries, and a documentation entry for
12397 the MEX file. Remaining arguments of the call are passed to the
12398 add_library() or add_executable() command.
12399 matlab_add_mex(
12401 NAME <name>
12402 [EXECUTABLE | MODULE | SHARED]
12403 SRC src1 [src2 ...]
12404 [OUTPUT_NAME output_name]
12405 [DOCUMENTATION file.txt]
12406 [LINK_TO target1 target2 ...]
12407 [R2017b | R2018a]
12408 [EXCLUDE_FROM_ALL]
12409 [...]
12410 )
12411 NAME name of the target.
12413 SRC list of source files.
12415 LINK_TO
12417 a list of additional link dependencies. The target links
12418 to libmex and libmx by default.
12419 OUTPUT_NAME
12421 if given, overrides the default name. The default name is
12422 the name of the target without any prefix and with Mat‐
12423 lab_MEX_EXTENSION suffix.
12424 DOCUMENTATION
12426 if given, the file file.txt will be considered as being
12427 the documentation file for the MEX file. This file is
12428 copied into the same folder without any processing, with
12429 the same name as the final mex file, and with extension
12430 .m. In that case, typing help <name> in Matlab prints the
12431 documentation contained in this file.
12432 R2017b or R2018a may be given to specify the version of the C
12434 API
12435 to use: R2017b specifies the traditional (separate com‐
12436 plex) C API, and corresponds to the -R2017b flag for the
12437 mex command. R2018a specifies the new interleaved complex
12438 C API, and corresponds to the -R2018a flag for the mex
12439 command. Ignored if MATLAB version prior to R2018a.
12440 Defaults to R2017b.
12441 MODULE or SHARED may be given to specify the type of library to
12443 be
12444 created. EXECUTABLE may be given to create an executable
12445 instead of a library. If no type is given explicitly, the
12446 type is SHARED.
12447 EXCLUDE_FROM_ALL
12449 This option has the same meaning as for EXCLUDE_FROM_ALL
12450 and is forwarded to add_library() or add_executable()
12451 commands.
12452 The documentation file is not processed and should be in the
12454 following format:
12455 % This is the documentation
12457 function ret = mex_target_output_name(input1)
12458 FindMFC
12460 Find Microsoft Foundation Class Library (MFC) on Windows
12461 Find the native MFC - i.e. decide if an application can link to the
12463 MFC libraries.
12464 MFC_FOUND - Was MFC support found
12466 You don’t need to include anything or link anything to use it.
12468 FindMotif
12470 Try to find Motif (or lesstif)
12471 Once done this will define:
12473 MOTIF_FOUND - system has MOTIF
12475 MOTIF_INCLUDE_DIR - include paths to use Motif
12476 MOTIF_LIBRARIES - Link these to use Motif
12477 FindMPEG
12479 Find the native MPEG includes and library
12480 This module defines
12482 MPEG_INCLUDE_DIR, where to find MPEG.h, etc.
12484 MPEG_LIBRARIES, the libraries required to use MPEG.
12485 MPEG_FOUND, If false, do not try to use MPEG.
12486 also defined, but not for general use are
12488 MPEG_mpeg2_LIBRARY, where to find the MPEG library.
12490 MPEG_vo_LIBRARY, where to find the vo library.
12491 FindMPEG2
12493 Find the native MPEG2 includes and library
12494 This module defines
12496 MPEG2_INCLUDE_DIR, path to mpeg2dec/mpeg2.h, etc.
12498 MPEG2_LIBRARIES, the libraries required to use MPEG2.
12499 MPEG2_FOUND, If false, do not try to use MPEG2.
12500 also defined, but not for general use are
12502 MPEG2_mpeg2_LIBRARY, where to find the MPEG2 library.
12504 MPEG2_vo_LIBRARY, where to find the vo library.
12505 FindMPI
12507 Find a Message Passing Interface (MPI) implementation.
12508 The Message Passing Interface (MPI) is a library used to write
12510 high-performance distributed-memory parallel applications, and is typi‐
12511 cally deployed on a cluster. MPI is a standard interface (defined by
12512 the MPI forum) for which many implementations are available.
12513 Variables for using MPI
12515 The module exposes the components C, CXX, MPICXX and Fortran. Each of
12516 these controls the various MPI languages to search for. The difference
12517 between CXX and MPICXX is that CXX refers to the MPI C API being usable
12518 from C++, whereas MPICXX refers to the MPI-2 C++ API that was removed
12519 again in MPI-3.
12520 Depending on the enabled components the following variables will be
12522 set:
12523 MPI_FOUND
12525 Variable indicating that MPI settings for all requested lan‐
12526 guages have been found. If no components are specified, this is
12527 true if MPI settings for all enabled languages were detected.
12528 Note that the MPICXX component does not affect this variable.
12529 MPI_VERSION
12531 Minimal version of MPI detected among the requested languages,
12532 or all enabled languages if no components were specified.
12533 This module will set the following variables per language in your
12535 project, where <lang> is one of C, CXX, or Fortran:
12536 MPI_<lang>_FOUND
12538 Variable indicating the MPI settings for <lang> were found and
12539 that simple MPI test programs compile with the provided set‐
12540 tings.
12541 MPI_<lang>_COMPILER
12543 MPI compiler for <lang> if such a program exists.
12544 MPI_<lang>_COMPILE_OPTIONS
12546 Compilation options for MPI programs in <lang>, given as a
12547 ;-list.
12548 MPI_<lang>_COMPILE_DEFINITIONS
12550 Compilation definitions for MPI programs in <lang>, given as a
12551 ;-list.
12552 MPI_<lang>_INCLUDE_DIRS
12554 Include path(s) for MPI header.
12555 MPI_<lang>_LINK_FLAGS
12557 Linker flags for MPI programs.
12558 MPI_<lang>_LIBRARIES
12560 All libraries to link MPI programs against.
12561 Additionally, the following IMPORTED targets are defined:
12563 MPI::MPI_<lang>
12565 Target for using MPI from <lang>.
12566 The following variables indicating which bindings are present will be
12568 defined:
12569 MPI_MPICXX_FOUND
12571 Variable indicating whether the MPI-2 C++ bindings are present
12572 (introduced in MPI-2, removed with MPI-3).
12573 MPI_Fortran_HAVE_F77_HEADER
12575 True if the Fortran 77 header mpif.h is available.
12576 MPI_Fortran_HAVE_F90_MODULE
12578 True if the Fortran 90 module mpi can be used for accessing MPI
12579 (MPI-2 and higher only).
12580 MPI_Fortran_HAVE_F08_MODULE
12582 True if the Fortran 2008 mpi_f08 is available to MPI programs
12583 (MPI-3 and higher only).
12584 If possible, the MPI version will be determined by this module. The
12586 facilities to detect the MPI version were introduced with MPI-1.2, and
12587 therefore cannot be found for older MPI versions.
12588 MPI_<lang>_VERSION_MAJOR
12590 Major version of MPI implemented for <lang> by the MPI distribu‐
12591 tion.
12592 MPI_<lang>_VERSION_MINOR
12594 Minor version of MPI implemented for <lang> by the MPI distribu‐
12595 tion.
12596 MPI_<lang>_VERSION
12598 MPI version implemented for <lang> by the MPI distribution.
12599 Note that there’s no variable for the C bindings being accessible
12601 through mpi.h, since the MPI standards always have required this bind‐
12602 ing to work in both C and C++ code.
12603 For running MPI programs, the module sets the following variables
12605 MPIEXEC_EXECUTABLE
12607 Executable for running MPI programs, if such exists.
12608 MPIEXEC_NUMPROC_FLAG
12610 Flag to pass to mpiexec before giving it the number of proces‐
12611 sors to run on.
12612 MPIEXEC_MAX_NUMPROCS
12614 Number of MPI processors to utilize. Defaults to the number of
12615 processors detected on the host system.
12616 MPIEXEC_PREFLAGS
12618 Flags to pass to mpiexec directly before the executable to run.
12619 MPIEXEC_POSTFLAGS
12621 Flags to pass to mpiexec after other flags.
12622 Variables for locating MPI
12624 This module performs a four step search for an MPI implementation:
12625 1. Search for MPIEXEC_EXECUTABLE and, if found, use its base directory.
12627 2. Check if the compiler has MPI support built-in. This is the case if
12629 the user passed a compiler wrapper as CMAKE_<LANG>_COMPILER or if
12630 they’re on a Cray system.
12631 3. Attempt to find an MPI compiler wrapper and determine the compiler
12633 information from it.
12634 4. Try to find an MPI implementation that does not ship such a wrapper
12636 by guessing settings. Currently, only Microsoft MPI and MPICH2 on
12637 Windows are supported.
12638 For controlling the MPIEXEC_EXECUTABLE step, the following variables
12640 may be set:
12641 MPIEXEC_EXECUTABLE
12643 Manually specify the location of mpiexec.
12644 MPI_HOME
12646 Specify the base directory of the MPI installation.
12647 ENV{MPI_HOME}
12649 Environment variable to specify the base directory of the MPI
12650 installation.
12651 ENV{I_MPI_ROOT}
12653 Environment variable to specify the base directory of the MPI
12654 installation.
12655 For controlling the compiler wrapper step, the following variables may
12657 be set:
12658 MPI_<lang>_COMPILER
12660 Search for the specified compiler wrapper and use it.
12661 MPI_<lang>_COMPILER_FLAGS
12663 Flags to pass to the MPI compiler wrapper during interrogation.
12664 Some compiler wrappers support linking debug or tracing
12665 libraries if a specific flag is passed and this variable may be
12666 used to obtain them.
12667 MPI_COMPILER_FLAGS
12669 Used to initialize MPI_<lang>_COMPILER_FLAGS if no language spe‐
12670 cific flag has been given. Empty by default.
12671 MPI_EXECUTABLE_SUFFIX
12673 A suffix which is appended to all names that are being looked
12674 for. For instance you may set this to .mpich or .openmpi to pre‐
12675 fer the one or the other on Debian and its derivatives.
12676 In order to control the guessing step, the following variable may be
12678 set:
12679 MPI_GUESS_LIBRARY_NAME
12681 Valid values are MSMPI and MPICH2. If set, only the given
12682 library will be searched for. By default, MSMPI will be pre‐
12683 ferred over MPICH2 if both are available. This also sets
12684 MPI_SKIP_COMPILER_WRAPPER to true, which may be overridden.
12685 Each of the search steps may be skipped with the following control
12687 variables:
12688 MPI_ASSUME_NO_BUILTIN_MPI
12690 If true, the module assumes that the compiler itself does not
12691 provide an MPI implementation and skips to step 2.
12692 MPI_SKIP_COMPILER_WRAPPER
12694 If true, no compiler wrapper will be searched for.
12695 MPI_SKIP_GUESSING
12697 If true, the guessing step will be skipped.
12698 Additionally, the following control variable is available to change
12700 search behavior:
12701 MPI_CXX_SKIP_MPICXX
12703 Add some definitions that will disable the MPI-2 C++ bindings.
12704 Currently supported are MPICH, Open MPI, Platform MPI and deriv‐
12705 atives thereof, for example MVAPICH or Intel MPI.
12706 If the find procedure fails for a variable MPI_<lang>_WORKS, then the
12708 settings detected by or passed to the module did not work and even a
12709 simple MPI test program failed to compile.
12710 If all of these parameters were not sufficient to find the right MPI
12712 implementation, a user may disable the entire autodetection process by
12713 specifying both a list of libraries in MPI_<lang>_LIBRARIES and a list
12714 of include directories in MPI_<lang>_ADDITIONAL_INCLUDE_DIRS. Any
12715 other variable may be set in addition to these two. The module will
12716 then validate the MPI settings and store the settings in the cache.
12717 Cache variables for MPI
12719 The variable MPI_<lang>_INCLUDE_DIRS will be assembled from the follow‐
12720 ing variables. For C and CXX:
12721 MPI_<lang>_HEADER_DIR
12723 Location of the mpi.h header on disk.
12724 For Fortran:
12726 MPI_Fortran_F77_HEADER_DIR
12728 Location of the Fortran 77 header mpif.h, if it exists.
12729 MPI_Fortran_MODULE_DIR
12731 Location of the mpi or mpi_f08 modules, if available.
12732 For all languages the following variables are additionally considered:
12734 MPI_<lang>_ADDITIONAL_INCLUDE_DIRS
12736 A ;-list of paths needed in addition to the normal include
12737 directories.
12738 MPI_<include_name>_INCLUDE_DIR
12740 Path variables for include folders referred to by
12741 <include_name>.
12742 MPI_<lang>_ADDITIONAL_INCLUDE_VARS
12744 A ;-list of <include_name> that will be added to the include
12745 locations of <lang>.
12746 The variable MPI_<lang>_LIBRARIES will be assembled from the following
12748 variables:
12749 MPI_<lib_name>_LIBRARY
12751 The location of a library called <lib_name> for use with MPI.
12752 MPI_<lang>_LIB_NAMES
12754 A ;-list of <lib_name> that will be added to the include loca‐
12755 tions of <lang>.
12756 Usage of mpiexec
12758 When using MPIEXEC_EXECUTABLE to execute MPI applications, you should
12759 typically use all of the MPIEXEC_EXECUTABLE flags as follows:
12760 ${MPIEXEC_EXECUTABLE} ${MPIEXEC_NUMPROC_FLAG} ${MPIEXEC_MAX_NUMPROCS}
12762 ${MPIEXEC_PREFLAGS} EXECUTABLE ${MPIEXEC_POSTFLAGS} ARGS
12763 where EXECUTABLE is the MPI program, and ARGS are the arguments to pass
12765 to the MPI program.
12766 Advanced variables for using MPI
12768 The module can perform some advanced feature detections upon explicit
12769 request.
12770 Important notice: The following checks cannot be performed without exe‐
12772 cuting an MPI test program. Consider the special considerations for
12773 the behavior of try_run() during cross compilation. Moreover, running
12774 an MPI program can cause additional issues, like a firewall notifica‐
12775 tion on some systems. You should only enable these detections if you
12776 absolutely need the information.
12777 If the following variables are set to true, the respective search will
12779 be performed:
12780 MPI_DETERMINE_Fortran_CAPABILITIES
12782 Determine for all available Fortran bindings what the values of
12783 MPI_SUBARRAYS_SUPPORTED and MPI_ASYNC_PROTECTS_NONBLOCKING are
12784 and make their values available as MPI_Fortran_<binding>_SUBAR‐
12785 RAYS and MPI_Fortran_<binding>_ASYNCPROT, where <binding> is one
12786 of F77_HEADER, F90_MODULE and F08_MODULE.
12787 MPI_DETERMINE_LIBRARY_VERSION
12789 For each language, find the output of MPI_Get_library_version
12790 and make it available as MPI_<lang>_LIBRARY_VERSION_STRING.
12791 This information is usually tied to the runtime component of an
12792 MPI implementation and might differ depending on <lang>. Note
12793 that the return value is entirely implementation defined. This
12794 information might be used to identify the MPI vendor and for
12795 example pick the correct one of multiple third party binaries
12796 that matches the MPI vendor.
12797 Backward Compatibility
12799 For backward compatibility with older versions of FindMPI, these vari‐
12800 ables are set, but deprecated:
12801 MPI_COMPILER MPI_LIBRARY MPI_EXTRA_LIBRARY
12803 MPI_COMPILE_FLAGS MPI_INCLUDE_PATH MPI_LINK_FLAGS
12804 MPI_LIBRARIES
12805 In new projects, please use the MPI_<lang>_XXX equivalents. Addition‐
12807 ally, the following variables are deprecated:
12808 MPI_<lang>_COMPILE_FLAGS
12810 Use MPI_<lang>_COMPILE_OPTIONS and MPI_<lang>_COMPILE_DEFINI‐
12811 TIONS instead.
12812 MPI_<lang>_INCLUDE_PATH
12814 For consumption use MPI_<lang>_INCLUDE_DIRS and for specifying
12815 folders use MPI_<lang>_ADDITIONAL_INCLUDE_DIRS instead.
12816 MPIEXEC
12818 Use MPIEXEC_EXECUTABLE instead.
12819 FindODBC
12821 New in version 3.12.
12822 Find an Open Database Connectivity (ODBC) include directory and
12825 library.
12826 On Windows, when building with Visual Studio, this module assumes the
12828 ODBC library is provided by the available Windows SDK.
12829 On Unix, this module allows to search for ODBC library provided by
12831 unixODBC or iODBC implementations of ODBC API. This module reads hint
12832 about location of the config program:
12833 ODBC_CONFIG
12835 Location of odbc_config or iodbc-config program
12836 Otherwise, this module tries to find the config program, first from
12838 unixODBC, then from iODBC. If no config program found, this module
12839 searches for ODBC header and library in list of known locations.
12840 Imported targets
12842 This module defines the following IMPORTED targets:
12843 ODBC::ODBC
12845 Imported target for using the ODBC library, if found.
12846 Result variables
12848 ODBC_FOUND
12849 Set to true if ODBC library found, otherwise false or undefined.
12850 ODBC_INCLUDE_DIRS
12852 Paths to include directories listed in one variable for use by
12853 ODBC client. May be empty on Windows, where the include direc‐
12854 tory corresponding to the expected Windows SDK is already avail‐
12855 able in the compilation environment.
12856 ODBC_LIBRARIES
12858 Paths to libraries to linked against to use ODBC. May just a
12859 library name on Windows, where the library directory correspond‐
12860 ing to the expected Windows SDK is already available in the com‐
12861 pilation environment.
12862 ODBC_CONFIG
12864 Path to unixODBC or iODBC config program, if found or specified.
12865 Cache variables
12867 For users who wish to edit and control the module behavior, this module
12868 reads hints about search locations from the following variables:
12869 ODBC_INCLUDE_DIR
12871 Path to ODBC include directory with sql.h header.
12872 ODBC_LIBRARY
12874 Path to ODBC library to be linked.
12875 These variables should not be used directly by project code.
12877 Limitations
12879 On Windows, this module does not search for iODBC. On Unix, there is
12880 no way to prefer unixODBC over iODBC, or vice versa, other than provid‐
12881 ing the config program location using the ODBC_CONFIG. This module
12882 does not allow to search for a specific ODBC driver.
12883 FindOpenACC
12885 New in version 3.10.
12886 Detect OpenACC support by the compiler.
12889 This module can be used to detect OpenACC support in a compiler. If
12891 the compiler supports OpenACC, the flags required to compile with Ope‐
12892 nACC support are returned in variables for the different languages.
12893 Currently, only PGI, GNU and Cray compilers are supported.
12894 Variables
12896 This module will set the following variables per language in your
12897 project, where <lang> is one of C, CXX, or Fortran:
12898 OpenACC_<lang>_FOUND
12900 Variable indicating if OpenACC support for <lang> was detected.
12901 OpenACC_<lang>_FLAGS
12903 OpenACC compiler flags for <lang>, separated by spaces.
12904 OpenACC_<lang>_OPTIONS
12906 OpenACC compiler flags for <lang>, as a list. Suitable for usage
12907 with target_compile_options or target_link_options.
12908 Additionally, the module provides IMPORTED targets:
12910 OpenACC::OpenACC_<lang>
12912 Target for using OpenACC from <lang>.
12913 The module will also try to provide the OpenACC version variables:
12915 OpenACC_<lang>_SPEC_DATE
12917 Date of the OpenACC specification implemented by the <lang> com‐
12918 piler.
12919 OpenACC_<lang>_VERSION_MAJOR
12921 Major version of OpenACC implemented by the <lang> compiler.
12922 OpenACC_<lang>_VERSION_MINOR
12924 Minor version of OpenACC implemented by the <lang> compiler.
12925 OpenACC_<lang>_VERSION
12927 OpenACC version implemented by the <lang> compiler.
12928 The specification date is formatted as given in the OpenACC standard:
12930 yyyymm where yyyy and mm represents the year and month of the OpenACC
12931 specification implemented by the <lang> compiler.
12932 Input Variables
12934 OpenACC_ACCEL_TARGET=<target> If set, will the correct target accelera‐
12935 tor flag set to the <target> will be returned with Ope‐
12936 nACC_<lang>_FLAGS.
12937 FindOpenAL
12939 Finds Open Audio Library (OpenAL).
12940 Projects using this module should use #include "al.h" to include the
12942 OpenAL header file, not #include <AL/al.h>. The reason for this is
12943 that the latter is not entirely portable. Windows/Creative Labs does
12944 not by default put their headers in AL/ and macOS uses the convention
12945 <OpenAL/al.h>.
12946 Hints
12948 Environment variable $OPENALDIR can be used to set the prefix of OpenAL
12949 installation to be found.
12950 By default on macOS, system framework is search first. In other words,
12952 OpenAL is searched in the following order:
12953 1. System framework: /System/Library/Frameworks, whose priority can be
12955 changed via setting the CMAKE_FIND_FRAMEWORK variable.
12956 2. Environment variable $OPENALDIR.
12958 3. System paths.
12960 4. User-compiled framework: ~/Library/Frameworks.
12962 5. Manually compiled framework: /Library/Frameworks.
12964 6. Add-on package: /opt.
12966 Result Variables
12968 This module defines the following variables:
12969 OPENAL_FOUND
12971 If false, do not try to link to OpenAL
12972 OPENAL_INCLUDE_DIR
12974 OpenAL include directory
12975 OPENAL_LIBRARY
12977 Path to the OpenAL library
12978 OPENAL_VERSION_STRING
12980 Human-readable string containing the version of OpenAL
12981 FindOpenCL
12983 New in version 3.1.
12984 Finds Open Computing Language (OpenCL)
12987 IMPORTED Targets
12989 This module defines IMPORTED target OpenCL::OpenCL, if OpenCL has been
12990 found.
12991 Result Variables
12993 This module defines the following variables:
12994 OpenCL_FOUND - True if OpenCL was found
12996 OpenCL_INCLUDE_DIRS - include directories for OpenCL
12997 OpenCL_LIBRARIES - link against this library to use OpenCL
12998 OpenCL_VERSION_STRING - Highest supported OpenCL version (eg. 1.2)
12999 OpenCL_VERSION_MAJOR - The major version of the OpenCL implementation
13000 OpenCL_VERSION_MINOR - The minor version of the OpenCL implementation
13001 The module will also define two cache variables:
13003 OpenCL_INCLUDE_DIR - the OpenCL include directory
13005 OpenCL_LIBRARY - the path to the OpenCL library
13006 FindOpenGL
13008 FindModule for OpenGL and OpenGL Utility Library (GLU).
13009 Optional COMPONENTS
13011 This module respects several optional COMPONENTS: EGL, GLX, and OpenGL.
13012 There are corresponding import targets for each of these flags.
13013 IMPORTED Targets
13015 This module defines the IMPORTED targets:
13016 OpenGL::GL
13018 Defined to the platform-specific OpenGL libraries if the system
13019 has OpenGL.
13020 OpenGL::OpenGL
13022 Defined to libOpenGL if the system is GLVND-based.
13023 OpenGL::GLU
13025 Defined if the system has OpenGL Utility Library (GLU).
13026 OpenGL::GLX
13028 Defined if the system has OpenGL Extension to the X Window Sys‐
13029 tem (GLX).
13030 OpenGL::EGL
13032 Defined if the system has EGL.
13033 Result Variables
13035 This module sets the following variables:
13036 OPENGL_FOUND
13038 True, if the system has OpenGL and all components are found.
13039 OPENGL_XMESA_FOUND
13041 True, if the system has XMESA.
13042 OPENGL_GLU_FOUND
13044 True, if the system has GLU.
13045 OpenGL_OpenGL_FOUND
13047 True, if the system has an OpenGL library.
13048 OpenGL_GLX_FOUND
13050 True, if the system has GLX.
13051 OpenGL_EGL_FOUND
13053 True, if the system has EGL.
13054 OPENGL_INCLUDE_DIR
13056 Path to the OpenGL include directory.
13057 OPENGL_EGL_INCLUDE_DIRS
13059 Path to the EGL include directory.
13060 OPENGL_LIBRARIES
13062 Paths to the OpenGL library, windowing system libraries, and GLU
13063 libraries. On Linux, this assumes GLX and is never correct for
13064 EGL-based targets. Clients are encouraged to use the OpenGL::*
13065 import targets instead.
13066 Cache variables
13068 The following cache variables may also be set:
13069 OPENGL_egl_LIBRARY
13071 Path to the EGL library.
13072 OPENGL_glu_LIBRARY
13074 Path to the GLU library.
13075 OPENGL_glx_LIBRARY
13077 Path to the GLVND ‘GLX’ library.
13078 OPENGL_opengl_LIBRARY
13080 Path to the GLVND ‘OpenGL’ library
13081 OPENGL_gl_LIBRARY
13083 Path to the OpenGL library. New code should prefer the
13084 OpenGL::* import targets.
13085 Linux-specific
13087 Some Linux systems utilize GLVND as a new ABI for OpenGL. GLVND sepa‐
13088 rates context libraries from OpenGL itself; OpenGL lives in
13089 “libOpenGL”, and contexts are defined in “libGLX” or “libEGL”. GLVND
13090 is currently the only way to get OpenGL 3+ functionality via EGL in a
13091 manner portable across vendors. Projects may use GLVND explicitly with
13092 target OpenGL::OpenGL and either OpenGL::GLX or OpenGL::EGL.
13093 Projects may use the OpenGL::GL target (or OPENGL_LIBRARIES variable)
13095 to use legacy GL interfaces. These will use the legacy GL library
13096 located by OPENGL_gl_LIBRARY, if available. If OPENGL_gl_LIBRARY is
13097 empty or not found and GLVND is available, the OpenGL::GL target will
13098 use GLVND OpenGL::OpenGL and OpenGL::GLX (and the OPENGL_LIBRARIES
13099 variable will use the corresponding libraries). Thus, for
13100 non-EGL-based Linux targets, the OpenGL::GL target is most portable.
13101 A OpenGL_GL_PREFERENCE variable may be set to specify the preferred way
13103 to provide legacy GL interfaces in case multiple choices are available.
13104 The value may be one of:
13105 GLVND If the GLVND OpenGL and GLX libraries are available, prefer
13107 them. This forces OPENGL_gl_LIBRARY to be empty. This is the
13108 default if components were requested (since components corre‐
13109 spond to GLVND libraries) or if policy CMP0072 is set to NEW.
13110 LEGACY Prefer to use the legacy libGL library, if available. This is
13112 the default if no components were requested and policy CMP0072
13113 is not set to NEW.
13114 For EGL targets the client must rely on GLVND support on the user’s
13116 system. Linking should use the OpenGL::OpenGL OpenGL::EGL targets.
13117 Using GLES* libraries is theoretically possible in place of
13118 OpenGL::OpenGL, but this module does not currently support that; con‐
13119 tributions welcome.
13120 OPENGL_egl_LIBRARY and OPENGL_EGL_INCLUDE_DIRS are defined in the case
13122 of GLVND. For non-GLVND Linux and other systems these are left unde‐
13123 fined.
13124 macOS-Specific
13126 On OSX FindOpenGL defaults to using the framework version of OpenGL.
13127 People will have to change the cache values of OPENGL_glu_LIBRARY and
13128 OPENGL_gl_LIBRARY to use OpenGL with X11 on OSX.
13129 FindOpenMP
13131 Finds Open Multi-Processing (OpenMP) support.
13132 This module can be used to detect OpenMP support in a compiler. If the
13134 compiler supports OpenMP, the flags required to compile with OpenMP
13135 support are returned in variables for the different languages. The
13136 variables may be empty if the compiler does not need a special flag to
13137 support OpenMP.
13138 Variables
13140 The module exposes the components C, CXX, and Fortran. Each of these
13141 controls the various languages to search OpenMP support for.
13142 Depending on the enabled components the following variables will be
13144 set:
13145 OpenMP_FOUND
13147 Variable indicating that OpenMP flags for all requested lan‐
13148 guages have been found. If no components are specified, this is
13149 true if OpenMP settings for all enabled languages were detected.
13150 OpenMP_VERSION
13152 Minimal version of the OpenMP standard detected among the
13153 requested languages, or all enabled languages if no components
13154 were specified.
13155 This module will set the following variables per language in your
13157 project, where <lang> is one of C, CXX, or Fortran:
13158 OpenMP_<lang>_FOUND
13160 Variable indicating if OpenMP support for <lang> was detected.
13161 OpenMP_<lang>_FLAGS
13163 OpenMP compiler flags for <lang>, separated by spaces.
13164 OpenMP_<lang>_INCLUDE_DIRS
13166 Directories that must be added to the header search path for
13167 <lang> when using OpenMP.
13168 For linking with OpenMP code written in <lang>, the following variables
13170 are provided:
13171 OpenMP_<lang>_LIB_NAMES
13173 ;-list of libraries for OpenMP programs for <lang>.
13174 OpenMP_<libname>_LIBRARY
13176 Location of the individual libraries needed for OpenMP support
13177 in <lang>.
13178 OpenMP_<lang>_LIBRARIES
13180 A list of libraries needed to link with OpenMP code written in
13181 <lang>.
13182 Additionally, the module provides IMPORTED targets:
13184 OpenMP::OpenMP_<lang>
13186 Target for using OpenMP from <lang>.
13187 Specifically for Fortran, the module sets the following variables:
13189 OpenMP_Fortran_HAVE_OMPLIB_HEADER
13191 Boolean indicating if OpenMP is accessible through omp_lib.h.
13192 OpenMP_Fortran_HAVE_OMPLIB_MODULE
13194 Boolean indicating if OpenMP is accessible through the omp_lib
13195 Fortran module.
13196 The module will also try to provide the OpenMP version variables:
13198 OpenMP_<lang>_SPEC_DATE
13200 Date of the OpenMP specification implemented by the <lang> com‐
13201 piler.
13202 OpenMP_<lang>_VERSION_MAJOR
13204 Major version of OpenMP implemented by the <lang> compiler.
13205 OpenMP_<lang>_VERSION_MINOR
13207 Minor version of OpenMP implemented by the <lang> compiler.
13208 OpenMP_<lang>_VERSION
13210 OpenMP version implemented by the <lang> compiler.
13211 The specification date is formatted as given in the OpenMP standard:
13213 yyyymm where yyyy and mm represents the year and month of the OpenMP
13214 specification implemented by the <lang> compiler.
13215 For some compilers, it may be necessary to add a header search path to
13217 find the relevant OpenMP headers. This location may be language-spe‐
13218 cific. Where this is needed, the module may attempt to find the loca‐
13219 tion, but it can be provided directly by setting the
13220 OpenMP_<lang>_INCLUDE_DIR cache variable. Note that this variable is
13221 an _input_ control to the module. Project code should use the
13222 OpenMP_<lang>_INCLUDE_DIRS _output_ variable if it needs to know what
13223 include directories are needed.
13224 FindOpenSceneGraph
13226 Find OpenSceneGraph (3D graphics application programming interface)
13227 This module searches for the OpenSceneGraph core “osg” library as well
13229 as FindOpenThreads, and whatever additional COMPONENTS (nodekits) that
13230 you specify.
13231 See http://www.openscenegraph.org
13233 NOTE: To use this module effectively you must either require CMake >=
13235 2.6.3 with cmake_minimum_required(VERSION 2.6.3) or download and place
13236 FindOpenThreads, Findosg functions, Findosg and Find<etc>.cmake files
13237 into your CMAKE_MODULE_PATH.
13238 ----
13241 This module accepts the following variables (note mixed case)
13245 OpenSceneGraph_DEBUG - Enable debugging output
13247 OpenSceneGraph_MARK_AS_ADVANCED - Mark cache variables as advanced
13249 automatically
13250 The following environment variables are also respected for finding the
13252 OSG and it’s various components. CMAKE_PREFIX_PATH can also be used
13253 for this (see find_library() CMake documentation).
13254 <MODULE>_DIR
13256 (where MODULE is of the form “OSGVOLUME” and there is a Findos‐
13257 gVolume.cmake` file)
13258 OSG_DIR
13260 OSGDIR
13262 OSG_ROOT
13264 [CMake 2.8.10]: The CMake variable OSG_DIR can now be used as well to
13266 influence detection, instead of needing to specify an environment vari‐
13267 able.
13268 This module defines the following output variables:
13270 OPENSCENEGRAPH_FOUND - Was the OSG and all of the specified components found?
13272 OPENSCENEGRAPH_VERSION - The version of the OSG which was found
13274 OPENSCENEGRAPH_INCLUDE_DIRS - Where to find the headers
13276 OPENSCENEGRAPH_LIBRARIES - The OSG libraries
13278 ================================== Example Usage:
13280 find_package(OpenSceneGraph 2.0.0 REQUIRED osgDB osgUtil)
13282 # libOpenThreads & libosg automatically searched
13283 include_directories(${OPENSCENEGRAPH_INCLUDE_DIRS})
13284 add_executable(foo foo.cc)
13286 target_link_libraries(foo ${OPENSCENEGRAPH_LIBRARIES})
13287 FindOpenSSL
13289 Find the OpenSSL encryption library.
13290 Optional COMPONENTS
13292 This module supports two optional COMPONENTS: Crypto and SSL. Both
13293 components have associated imported targets, as described below.
13294 Imported Targets
13296 This module defines the following IMPORTED targets:
13297 OpenSSL::SSL
13299 The OpenSSL ssl library, if found.
13300 OpenSSL::Crypto
13302 The OpenSSL crypto library, if found.
13303 OpenSSL::applink
13305 The OpenSSL applink components that might be need to be compiled
13306 into projects under MSVC. This target is available only if found
13307 OpenSSL version is not less than 0.9.8. By linking this target
13308 the above OpenSSL targets can be linked even if the project has
13309 different MSVC runtime configurations with the above OpenSSL
13310 targets. This target has no effect on platforms other than MSVC.
13311 NOTE: Due to how INTERFACE_SOURCES are consumed by the consuming tar‐
13313 get, unless you certainly know what you are doing, it is always pre‐
13314 ferred to link OpenSSL::applink target as PRIVATE and to make sure that
13315 this target is linked at most once for the whole dependency graph of
13316 any library or executable:
13317 target_link_libraries(myTarget PRIVATE OpenSSL::applink)
13319 Otherwise you would probably encounter unexpected random problems when
13321 building and linking, as both the ISO C and the ISO C++ standard claims
13322 almost nothing about what a link process should be.
13323 Result Variables
13325 This module will set the following variables in your project:
13326 OPENSSL_FOUND
13328 System has the OpenSSL library. If no components are requested
13329 it only requires the crypto library.
13330 OPENSSL_INCLUDE_DIR
13332 The OpenSSL include directory.
13333 OPENSSL_CRYPTO_LIBRARY
13335 The OpenSSL crypto library.
13336 OPENSSL_CRYPTO_LIBRARIES
13338 The OpenSSL crypto library and its dependencies.
13339 OPENSSL_SSL_LIBRARY
13341 The OpenSSL SSL library.
13342 OPENSSL_SSL_LIBRARIES
13344 The OpenSSL SSL library and its dependencies.
13345 OPENSSL_LIBRARIES
13347 All OpenSSL libraries and their dependencies.
13348 OPENSSL_VERSION
13350 This is set to $major.$minor.$revision$patch (e.g. 0.9.8s).
13351 OPENSSL_APPLINK_SOURCE
13353 The sources in the target OpenSSL::applink that is mentioned
13354 above. This variable shall always be undefined if found openssl
13355 version is less than 0.9.8 or if platform is not MSVC.
13356 Hints
13358 Set OPENSSL_ROOT_DIR to the root directory of an OpenSSL installation.
13359 Set OPENSSL_USE_STATIC_LIBS to TRUE to look for static libraries. Set
13360 OPENSSL_MSVC_STATIC_RT set TRUE to choose the MT version of the lib.
13361 FindOpenThreads
13363 OpenThreads is a C++ based threading library. Its largest userbase
13364 seems to OpenSceneGraph so you might notice I accept OSGDIR as an envi‐
13365 ronment path. I consider this part of the Findosg* suite used to find
13366 OpenSceneGraph components. Each component is separate and you must opt
13367 in to each module.
13368 Locate OpenThreads This module defines OPENTHREADS_LIBRARY
13370 OPENTHREADS_FOUND, if false, do not try to link to OpenThreads
13371 OPENTHREADS_INCLUDE_DIR, where to find the headers
13372 $OPENTHREADS_DIR is an environment variable that would correspond to
13374 the ./configure –prefix=$OPENTHREADS_DIR used in building osg.
13375 [CMake 2.8.10]: The CMake variables OPENTHREADS_DIR or OSG_DIR can now
13377 be used as well to influence detection, instead of needing to specify
13378 an environment variable.
13379 Created by Eric Wing.
13381 Findosg
13383 NOTE: It is highly recommended that you use the new FindOpenScene‐
13384 Graph.cmake introduced in CMake 2.6.3 and not use this Find module
13385 directly.
13386 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
13388 nents. Each component is separate and you must opt in to each module.
13389 You must also opt into OpenGL and OpenThreads (and Producer if needed)
13390 as these modules won’t do it for you. This is to allow you control
13391 over your own system piece by piece in case you need to opt out of cer‐
13392 tain components or change the Find behavior for a particular module
13393 (perhaps because the default FindOpenGL.cmake module doesn’t work with
13394 your system as an example). If you want to use a more convenient mod‐
13395 ule that includes everything, use the FindOpenSceneGraph.cmake instead
13396 of the Findosg*.cmake modules.
13397 Locate osg This module defines
13399 OSG_FOUND - Was the Osg found? OSG_INCLUDE_DIR - Where to find the
13401 headers OSG_LIBRARIES - The libraries to link against for the OSG (use
13402 this)
13403 OSG_LIBRARY - The OSG library OSG_LIBRARY_DEBUG - The OSG debug library
13405 $OSGDIR is an environment variable that would correspond to the ./con‐
13407 figure –prefix=$OSGDIR used in building osg.
13408 Created by Eric Wing.
13410 Findosg_functions
13412 This CMake file contains two macros to assist with searching for OSG
13413 libraries and nodekits. Please see FindOpenSceneGraph.cmake for full
13414 documentation.
13415 FindosgAnimation
13417 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
13418 nents. Each component is separate and you must opt in to each module.
13419 You must also opt into OpenGL and OpenThreads (and Producer if needed)
13420 as these modules won’t do it for you. This is to allow you control
13421 over your own system piece by piece in case you need to opt out of cer‐
13422 tain components or change the Find behavior for a particular module
13423 (perhaps because the default FindOpenGL.cmake module doesn’t work with
13424 your system as an example). If you want to use a more convenient mod‐
13425 ule that includes everything, use the FindOpenSceneGraph.cmake instead
13426 of the Findosg*.cmake modules.
13427 Locate osgAnimation This module defines
13429 OSGANIMATION_FOUND - Was osgAnimation found? OSGANIMATION_INCLUDE_DIR -
13431 Where to find the headers OSGANIMATION_LIBRARIES - The libraries to
13432 link against for the OSG (use this)
13433 OSGANIMATION_LIBRARY - The OSG library OSGANIMATION_LIBRARY_DEBUG - The
13435 OSG debug library
13436 $OSGDIR is an environment variable that would correspond to the ./con‐
13438 figure –prefix=$OSGDIR used in building osg.
13439 Created by Eric Wing.
13441 FindosgDB
13443 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
13444 nents. Each component is separate and you must opt in to each module.
13445 You must also opt into OpenGL and OpenThreads (and Producer if needed)
13446 as these modules won’t do it for you. This is to allow you control
13447 over your own system piece by piece in case you need to opt out of cer‐
13448 tain components or change the Find behavior for a particular module
13449 (perhaps because the default FindOpenGL module doesn’t work with your
13450 system as an example). If you want to use a more convenient module
13451 that includes everything, use the FindOpenSceneGraph instead of the
13452 Findosg*.cmake modules.
13453 Locate osgDB This module defines:
13455 OSGDB_FOUND
13457 Was osgDB found?
13458 OSGDB_INCLUDE_DIR
13460 Where to find the headers
13461 OSGDB_LIBRARIES
13463 The libraries to link against for the osgDB
13464 OSGDB_LIBRARY
13466 The osgDB library
13467 OSGDB_LIBRARY_DEBUG
13469 The osgDB debug library
13470 $OSGDIR is an environment variable that would correspond to:
13472 ./configure --prefix=$OSGDIR used in building osg.
13474 FindosgFX
13476 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
13477 nents. Each component is separate and you must opt in to each module.
13478 You must also opt into OpenGL and OpenThreads (and Producer if needed)
13479 as these modules won’t do it for you. This is to allow you control
13480 over your own system piece by piece in case you need to opt out of cer‐
13481 tain components or change the Find behavior for a particular module
13482 (perhaps because the default FindOpenGL.cmake module doesn’t work with
13483 your system as an example). If you want to use a more convenient mod‐
13484 ule that includes everything, use the FindOpenSceneGraph.cmake instead
13485 of the Findosg*.cmake modules.
13486 Locate osgFX This module defines
13488 OSGFX_FOUND - Was osgFX found? OSGFX_INCLUDE_DIR - Where to find the
13490 headers OSGFX_LIBRARIES - The libraries to link against for the osgFX
13491 (use this)
13492 OSGFX_LIBRARY - The osgFX library OSGFX_LIBRARY_DEBUG - The osgFX debug
13494 library
13495 $OSGDIR is an environment variable that would correspond to the ./con‐
13497 figure –prefix=$OSGDIR used in building osg.
13498 Created by Eric Wing.
13500 FindosgGA
13502 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
13503 nents. Each component is separate and you must opt in to each module.
13504 You must also opt into OpenGL and OpenThreads (and Producer if needed)
13505 as these modules won’t do it for you. This is to allow you control
13506 over your own system piece by piece in case you need to opt out of cer‐
13507 tain components or change the Find behavior for a particular module
13508 (perhaps because the default FindOpenGL.cmake module doesn’t work with
13509 your system as an example). If you want to use a more convenient mod‐
13510 ule that includes everything, use the FindOpenSceneGraph.cmake instead
13511 of the Findosg*.cmake modules.
13512 Locate osgGA This module defines
13514 OSGGA_FOUND - Was osgGA found? OSGGA_INCLUDE_DIR - Where to find the
13516 headers OSGGA_LIBRARIES - The libraries to link against for the osgGA
13517 (use this)
13518 OSGGA_LIBRARY - The osgGA library OSGGA_LIBRARY_DEBUG - The osgGA debug
13520 library
13521 $OSGDIR is an environment variable that would correspond to the ./con‐
13523 figure –prefix=$OSGDIR used in building osg.
13524 Created by Eric Wing.
13526 FindosgIntrospection
13528 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
13529 nents. Each component is separate and you must opt in to each module.
13530 You must also opt into OpenGL and OpenThreads (and Producer if needed)
13531 as these modules won’t do it for you. This is to allow you control
13532 over your own system piece by piece in case you need to opt out of cer‐
13533 tain components or change the Find behavior for a particular module
13534 (perhaps because the default FindOpenGL.cmake module doesn’t work with
13535 your system as an example). If you want to use a more convenient mod‐
13536 ule that includes everything, use the FindOpenSceneGraph.cmake instead
13537 of the Findosg*.cmake modules.
13538 Locate osgINTROSPECTION This module defines
13540 OSGINTROSPECTION_FOUND - Was osgIntrospection found? OSGINTROSPEC‐
13542 TION_INCLUDE_DIR - Where to find the headers OSGINTROSPECTION_LIBRARIES
13543 - The libraries to link for osgIntrospection (use this)
13544 OSGINTROSPECTION_LIBRARY - The osgIntrospection library OSGINTROSPEC‐
13546 TION_LIBRARY_DEBUG - The osgIntrospection debug library
13547 $OSGDIR is an environment variable that would correspond to the ./con‐
13549 figure –prefix=$OSGDIR used in building osg.
13550 Created by Eric Wing.
13552 FindosgManipulator
13554 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
13555 nents. Each component is separate and you must opt in to each module.
13556 You must also opt into OpenGL and OpenThreads (and Producer if needed)
13557 as these modules won’t do it for you. This is to allow you control
13558 over your own system piece by piece in case you need to opt out of cer‐
13559 tain components or change the Find behavior for a particular module
13560 (perhaps because the default FindOpenGL.cmake module doesn’t work with
13561 your system as an example). If you want to use a more convenient mod‐
13562 ule that includes everything, use the FindOpenSceneGraph.cmake instead
13563 of the Findosg*.cmake modules.
13564 Locate osgManipulator This module defines
13566 OSGMANIPULATOR_FOUND - Was osgManipulator found? OSGMANIPULA‐
13568 TOR_INCLUDE_DIR - Where to find the headers OSGMANIPULATOR_LIBRARIES -
13569 The libraries to link for osgManipulator (use this)
13570 OSGMANIPULATOR_LIBRARY - The osgManipulator library OSGMANIPULA‐
13572 TOR_LIBRARY_DEBUG - The osgManipulator debug library
13573 $OSGDIR is an environment variable that would correspond to the ./con‐
13575 figure –prefix=$OSGDIR used in building osg.
13576 Created by Eric Wing.
13578 FindosgParticle
13580 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
13581 nents. Each component is separate and you must opt in to each module.
13582 You must also opt into OpenGL and OpenThreads (and Producer if needed)
13583 as these modules won’t do it for you. This is to allow you control
13584 over your own system piece by piece in case you need to opt out of cer‐
13585 tain components or change the Find behavior for a particular module
13586 (perhaps because the default FindOpenGL.cmake module doesn’t work with
13587 your system as an example). If you want to use a more convenient mod‐
13588 ule that includes everything, use the FindOpenSceneGraph.cmake instead
13589 of the Findosg*.cmake modules.
13590 Locate osgParticle This module defines
13592 OSGPARTICLE_FOUND - Was osgParticle found? OSGPARTICLE_INCLUDE_DIR -
13594 Where to find the headers OSGPARTICLE_LIBRARIES - The libraries to link
13595 for osgParticle (use this)
13596 OSGPARTICLE_LIBRARY - The osgParticle library OSGPARTICLE_LIBRARY_DEBUG
13598 - The osgParticle debug library
13599 $OSGDIR is an environment variable that would correspond to the ./con‐
13601 figure –prefix=$OSGDIR used in building osg.
13602 Created by Eric Wing.
13604 FindosgPresentation
13606 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
13607 nents. Each component is separate and you must opt in to each module.
13608 You must also opt into OpenGL and OpenThreads (and Producer if needed)
13609 as these modules won’t do it for you. This is to allow you control
13610 over your own system piece by piece in case you need to opt out of cer‐
13611 tain components or change the Find behavior for a particular module
13612 (perhaps because the default FindOpenGL.cmake module doesn’t work with
13613 your system as an example). If you want to use a more convenient mod‐
13614 ule that includes everything, use the FindOpenSceneGraph.cmake instead
13615 of the Findosg*.cmake modules.
13616 Locate osgPresentation This module defines
13618 OSGPRESENTATION_FOUND - Was osgPresentation found? OSGPRESENTA‐
13620 TION_INCLUDE_DIR - Where to find the headers OSGPRESENTATION_LIBRARIES
13621 - The libraries to link for osgPresentation (use this)
13622 OSGPRESENTATION_LIBRARY - The osgPresentation library OSGPRESENTA‐
13624 TION_LIBRARY_DEBUG - The osgPresentation debug library
13625 $OSGDIR is an environment variable that would correspond to the ./con‐
13627 figure –prefix=$OSGDIR used in building osg.
13628 Created by Eric Wing. Modified to work with osgPresentation by Robert
13630 Osfield, January 2012.
13631 FindosgProducer
13633 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
13634 nents. Each component is separate and you must opt in to each module.
13635 You must also opt into OpenGL and OpenThreads (and Producer if needed)
13636 as these modules won’t do it for you. This is to allow you control
13637 over your own system piece by piece in case you need to opt out of cer‐
13638 tain components or change the Find behavior for a particular module
13639 (perhaps because the default FindOpenGL.cmake module doesn’t work with
13640 your system as an example). If you want to use a more convenient mod‐
13641 ule that includes everything, use the FindOpenSceneGraph.cmake instead
13642 of the Findosg*.cmake modules.
13643 Locate osgProducer This module defines
13645 OSGPRODUCER_FOUND - Was osgProducer found? OSGPRODUCER_INCLUDE_DIR -
13647 Where to find the headers OSGPRODUCER_LIBRARIES - The libraries to link
13648 for osgProducer (use this)
13649 OSGPRODUCER_LIBRARY - The osgProducer library OSGPRODUCER_LIBRARY_DEBUG
13651 - The osgProducer debug library
13652 $OSGDIR is an environment variable that would correspond to the ./con‐
13654 figure –prefix=$OSGDIR used in building osg.
13655 Created by Eric Wing.
13657 FindosgQt
13659 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
13660 nents. Each component is separate and you must opt in to each module.
13661 You must also opt into OpenGL and OpenThreads (and Producer if needed)
13662 as these modules won’t do it for you. This is to allow you control
13663 over your own system piece by piece in case you need to opt out of cer‐
13664 tain components or change the Find behavior for a particular module
13665 (perhaps because the default FindOpenGL.cmake module doesn’t work with
13666 your system as an example). If you want to use a more convenient mod‐
13667 ule that includes everything, use the FindOpenSceneGraph.cmake instead
13668 of the Findosg*.cmake modules.
13669 Locate osgQt This module defines
13671 OSGQT_FOUND - Was osgQt found? OSGQT_INCLUDE_DIR - Where to find the
13673 headers OSGQT_LIBRARIES - The libraries to link for osgQt (use this)
13674 OSGQT_LIBRARY - The osgQt library OSGQT_LIBRARY_DEBUG - The osgQt debug
13676 library
13677 $OSGDIR is an environment variable that would correspond to the ./con‐
13679 figure –prefix=$OSGDIR used in building osg.
13680 Created by Eric Wing. Modified to work with osgQt by Robert Osfield,
13682 January 2012.
13683 FindosgShadow
13685 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
13686 nents. Each component is separate and you must opt in to each module.
13687 You must also opt into OpenGL and OpenThreads (and Producer if needed)
13688 as these modules won’t do it for you. This is to allow you control
13689 over your own system piece by piece in case you need to opt out of cer‐
13690 tain components or change the Find behavior for a particular module
13691 (perhaps because the default FindOpenGL.cmake module doesn’t work with
13692 your system as an example). If you want to use a more convenient mod‐
13693 ule that includes everything, use the FindOpenSceneGraph.cmake instead
13694 of the Findosg*.cmake modules.
13695 Locate osgShadow This module defines
13697 OSGSHADOW_FOUND - Was osgShadow found? OSGSHADOW_INCLUDE_DIR - Where to
13699 find the headers OSGSHADOW_LIBRARIES - The libraries to link for
13700 osgShadow (use this)
13701 OSGSHADOW_LIBRARY - The osgShadow library OSGSHADOW_LIBRARY_DEBUG - The
13703 osgShadow debug library
13704 $OSGDIR is an environment variable that would correspond to the ./con‐
13706 figure –prefix=$OSGDIR used in building osg.
13707 Created by Eric Wing.
13709 FindosgSim
13711 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
13712 nents. Each component is separate and you must opt in to each module.
13713 You must also opt into OpenGL and OpenThreads (and Producer if needed)
13714 as these modules won’t do it for you. This is to allow you control
13715 over your own system piece by piece in case you need to opt out of cer‐
13716 tain components or change the Find behavior for a particular module
13717 (perhaps because the default FindOpenGL.cmake module doesn’t work with
13718 your system as an example). If you want to use a more convenient mod‐
13719 ule that includes everything, use the FindOpenSceneGraph.cmake instead
13720 of the Findosg*.cmake modules.
13721 Locate osgSim This module defines
13723 OSGSIM_FOUND - Was osgSim found? OSGSIM_INCLUDE_DIR - Where to find the
13725 headers OSGSIM_LIBRARIES - The libraries to link for osgSim (use this)
13726 OSGSIM_LIBRARY - The osgSim library OSGSIM_LIBRARY_DEBUG - The osgSim
13728 debug library
13729 $OSGDIR is an environment variable that would correspond to the ./con‐
13731 figure –prefix=$OSGDIR used in building osg.
13732 Created by Eric Wing.
13734 FindosgTerrain
13736 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
13737 nents. Each component is separate and you must opt in to each module.
13738 You must also opt into OpenGL and OpenThreads (and Producer if needed)
13739 as these modules won’t do it for you. This is to allow you control
13740 over your own system piece by piece in case you need to opt out of cer‐
13741 tain components or change the Find behavior for a particular module
13742 (perhaps because the default FindOpenGL.cmake module doesn’t work with
13743 your system as an example). If you want to use a more convenient mod‐
13744 ule that includes everything, use the FindOpenSceneGraph.cmake instead
13745 of the Findosg*.cmake modules.
13746 Locate osgTerrain This module defines
13748 OSGTERRAIN_FOUND - Was osgTerrain found? OSGTERRAIN_INCLUDE_DIR - Where
13750 to find the headers OSGTERRAIN_LIBRARIES - The libraries to link for
13751 osgTerrain (use this)
13752 OSGTERRAIN_LIBRARY - The osgTerrain library OSGTERRAIN_LIBRARY_DEBUG -
13754 The osgTerrain debug library
13755 $OSGDIR is an environment variable that would correspond to the ./con‐
13757 figure –prefix=$OSGDIR used in building osg.
13758 Created by Eric Wing.
13760 FindosgText
13762 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
13763 nents. Each component is separate and you must opt in to each module.
13764 You must also opt into OpenGL and OpenThreads (and Producer if needed)
13765 as these modules won’t do it for you. This is to allow you control
13766 over your own system piece by piece in case you need to opt out of cer‐
13767 tain components or change the Find behavior for a particular module
13768 (perhaps because the default FindOpenGL.cmake module doesn’t work with
13769 your system as an example). If you want to use a more convenient mod‐
13770 ule that includes everything, use the FindOpenSceneGraph.cmake instead
13771 of the Findosg*.cmake modules.
13772 Locate osgText This module defines
13774 OSGTEXT_FOUND - Was osgText found? OSGTEXT_INCLUDE_DIR - Where to find
13776 the headers OSGTEXT_LIBRARIES - The libraries to link for osgText (use
13777 this)
13778 OSGTEXT_LIBRARY - The osgText library OSGTEXT_LIBRARY_DEBUG - The osg‐
13780 Text debug library
13781 $OSGDIR is an environment variable that would correspond to the ./con‐
13783 figure –prefix=$OSGDIR used in building osg.
13784 Created by Eric Wing.
13786 FindosgUtil
13788 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
13789 nents. Each component is separate and you must opt in to each module.
13790 You must also opt into OpenGL and OpenThreads (and Producer if needed)
13791 as these modules won’t do it for you. This is to allow you control
13792 over your own system piece by piece in case you need to opt out of cer‐
13793 tain components or change the Find behavior for a particular module
13794 (perhaps because the default FindOpenGL.cmake module doesn’t work with
13795 your system as an example). If you want to use a more convenient mod‐
13796 ule that includes everything, use the FindOpenSceneGraph.cmake instead
13797 of the Findosg*.cmake modules.
13798 Locate osgUtil This module defines
13800 OSGUTIL_FOUND - Was osgUtil found? OSGUTIL_INCLUDE_DIR - Where to find
13802 the headers OSGUTIL_LIBRARIES - The libraries to link for osgUtil (use
13803 this)
13804 OSGUTIL_LIBRARY - The osgUtil library OSGUTIL_LIBRARY_DEBUG - The
13806 osgUtil debug library
13807 $OSGDIR is an environment variable that would correspond to the ./con‐
13809 figure –prefix=$OSGDIR used in building osg.
13810 Created by Eric Wing.
13812 FindosgViewer
13814 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
13815 nents. Each component is separate and you must opt in to each module.
13816 You must also opt into OpenGL and OpenThreads (and Producer if needed)
13817 as these modules won’t do it for you. This is to allow you control
13818 over your own system piece by piece in case you need to opt out of cer‐
13819 tain components or change the Find behavior for a particular module
13820 (perhaps because the default FindOpenGL.cmake module doesn’t work with
13821 your system as an example). If you want to use a more convenient mod‐
13822 ule that includes everything, use the FindOpenSceneGraph.cmake instead
13823 of the Findosg*.cmake modules.
13824 Locate osgViewer This module defines
13826 OSGVIEWER_FOUND - Was osgViewer found? OSGVIEWER_INCLUDE_DIR - Where to
13828 find the headers OSGVIEWER_LIBRARIES - The libraries to link for
13829 osgViewer (use this)
13830 OSGVIEWER_LIBRARY - The osgViewer library OSGVIEWER_LIBRARY_DEBUG - The
13832 osgViewer debug library
13833 $OSGDIR is an environment variable that would correspond to the ./con‐
13835 figure –prefix=$OSGDIR used in building osg.
13836 Created by Eric Wing.
13838 FindosgVolume
13840 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
13841 nents. Each component is separate and you must opt in to each module.
13842 You must also opt into OpenGL and OpenThreads (and Producer if needed)
13843 as these modules won’t do it for you. This is to allow you control
13844 over your own system piece by piece in case you need to opt out of cer‐
13845 tain components or change the Find behavior for a particular module
13846 (perhaps because the default FindOpenGL.cmake module doesn’t work with
13847 your system as an example). If you want to use a more convenient mod‐
13848 ule that includes everything, use the FindOpenSceneGraph.cmake instead
13849 of the Findosg*.cmake modules.
13850 Locate osgVolume This module defines
13852 OSGVOLUME_FOUND - Was osgVolume found? OSGVOLUME_INCLUDE_DIR - Where to
13854 find the headers OSGVOLUME_LIBRARIES - The libraries to link for
13855 osgVolume (use this)
13856 OSGVOLUME_LIBRARY - The osgVolume library OSGVOLUME_LIBRARY_DEBUG - The
13858 osgVolume debug library
13859 $OSGDIR is an environment variable that would correspond to the ./con‐
13861 figure –prefix=$OSGDIR used in building osg.
13862 Created by Eric Wing.
13864 FindosgWidget
13866 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
13867 nents. Each component is separate and you must opt in to each module.
13868 You must also opt into OpenGL and OpenThreads (and Producer if needed)
13869 as these modules won’t do it for you. This is to allow you control
13870 over your own system piece by piece in case you need to opt out of cer‐
13871 tain components or change the Find behavior for a particular module
13872 (perhaps because the default FindOpenGL.cmake module doesn’t work with
13873 your system as an example). If you want to use a more convenient mod‐
13874 ule that includes everything, use the FindOpenSceneGraph.cmake instead
13875 of the Findosg*.cmake modules.
13876 Locate osgWidget This module defines
13878 OSGWIDGET_FOUND - Was osgWidget found? OSGWIDGET_INCLUDE_DIR - Where to
13880 find the headers OSGWIDGET_LIBRARIES - The libraries to link for osg‐
13881 Widget (use this)
13882 OSGWIDGET_LIBRARY - The osgWidget library OSGWIDGET_LIBRARY_DEBUG - The
13884 osgWidget debug library
13885 $OSGDIR is an environment variable that would correspond to the ./con‐
13887 figure –prefix=$OSGDIR used in building osg.
13888 FindosgWidget.cmake tweaked from Findosg* suite as created by Eric
13890 Wing.
13891 FindPatch
13893 New in version 3.10.
13894 The module defines the following variables:
13897 Patch_EXECUTABLE
13899 Path to patch command-line executable.
13900 Patch_FOUND
13902 True if the patch command-line executable was found.
13903 The following IMPORTED targets are also defined:
13905 Patch::patch
13907 The command-line executable.
13908 Example usage:
13910 find_package(Patch)
13912 if(Patch_FOUND)
13913 message("Patch found: ${Patch_EXECUTABLE}")
13914 endif()
13915 FindPerl
13917 Find perl
13918 this module looks for Perl
13920 PERL_EXECUTABLE - the full path to perl
13922 PERL_FOUND - If false, don't attempt to use perl.
13923 PERL_VERSION_STRING - version of perl found (since CMake 2.8.8)
13924 FindPerlLibs
13926 Find Perl libraries
13927 This module finds if PERL is installed and determines where the include
13929 files and libraries are. It also determines what the name of the
13930 library is. This code sets the following variables:
13931 PERLLIBS_FOUND = True if perl.h & libperl were found
13933 PERL_INCLUDE_PATH = path to where perl.h is found
13934 PERL_LIBRARY = path to libperl
13935 PERL_EXECUTABLE = full path to the perl binary
13936 The minimum required version of Perl can be specified using the stan‐
13938 dard syntax, e.g. find_package(PerlLibs 6.0)
13939 The following variables are also available if needed
13941 (introduced after CMake 2.6.4)
13942 PERL_SITESEARCH = path to the sitesearch install dir (-V:installsitesearch)
13944 PERL_SITEARCH = path to the sitelib install directory (-V:installsitearch)
13945 PERL_SITELIB = path to the sitelib install directory (-V:installsitelib)
13946 PERL_VENDORARCH = path to the vendor arch install directory (-V:installvendorarch)
13947 PERL_VENDORLIB = path to the vendor lib install directory (-V:installvendorlib)
13948 PERL_ARCHLIB = path to the core arch lib install directory (-V:archlib)
13949 PERL_PRIVLIB = path to the core priv lib install directory (-V:privlib)
13950 PERL_UPDATE_ARCHLIB = path to the update arch lib install directory (-V:installarchlib)
13951 PERL_UPDATE_PRIVLIB = path to the update priv lib install directory (-V:installprivlib)
13952 PERL_EXTRA_C_FLAGS = Compilation flags used to build perl
13953 FindPHP4
13955 Find PHP4
13956 This module finds if PHP4 is installed and determines where the include
13958 files and libraries are. It also determines what the name of the
13959 library is. This code sets the following variables:
13960 PHP4_INCLUDE_PATH = path to where php.h can be found
13962 PHP4_EXECUTABLE = full path to the php4 binary
13963 FindPhysFS
13965 Locate PhysFS library This module defines PHYSFS_LIBRARY, the name of
13966 the library to link against PHYSFS_FOUND, if false, do not try to link
13967 to PHYSFS PHYSFS_INCLUDE_DIR, where to find physfs.h
13968 $PHYSFSDIR is an environment variable that would correspond to the
13970 ./configure –prefix=$PHYSFSDIR used in building PHYSFS.
13971 Created by Eric Wing.
13973 FindPike
13975 Find Pike
13976 This module finds if PIKE is installed and determines where the include
13978 files and libraries are. It also determines what the name of the
13979 library is. This code sets the following variables:
13980 PIKE_INCLUDE_PATH = path to where program.h is found
13982 PIKE_EXECUTABLE = full path to the pike binary
13983 FindPkgConfig
13985 A pkg-config module for CMake.
13986 Finds the pkg-config executable and adds the pkg_get_variable(),
13988 pkg_check_modules() and pkg_search_module() commands. The following
13989 variables will also be set:
13990 PKG_CONFIG_FOUND
13992 if pkg-config executable was found
13993 PKG_CONFIG_EXECUTABLE
13995 pathname of the pkg-config program
13996 PKG_CONFIG_VERSION_STRING
13998 version of pkg-config (since CMake 2.8.8)
13999 pkg_check_modules
14001 Checks for all the given modules, setting a variety of result
14002 variables in the calling scope.
14003 pkg_check_modules(<prefix>
14005 [REQUIRED] [QUIET]
14006 [NO_CMAKE_PATH]
14007 [NO_CMAKE_ENVIRONMENT_PATH]
14008 [IMPORTED_TARGET [GLOBAL]]
14009 <moduleSpec> [<moduleSpec>...])
14010 When the REQUIRED argument is given, the command will fail with
14012 an error if module(s) could not be found.
14013 When the QUIET argument is given, no status messages will be
14015 printed.
14016 By default, if CMAKE_MINIMUM_REQUIRED_VERSION is 3.1 or later,
14018 or if PKG_CONFIG_USE_CMAKE_PREFIX_PATH is set to a boolean True
14019 value, then the CMAKE_PREFIX_PATH, CMAKE_FRAMEWORK_PATH, and
14020 CMAKE_APPBUNDLE_PATH cache and environment variables will be
14021 added to the pkg-config search path. The NO_CMAKE_PATH and
14022 NO_CMAKE_ENVIRONMENT_PATH arguments disable this behavior for
14023 the cache variables and environment variables respectively.
14024 The IMPORTED_TARGET argument will create an imported target
14026 named PkgConfig::<prefix> that can be passed directly as an
14027 argument to target_link_libraries(). The GLOBAL argument will
14028 make the imported target available in global scope.
14029 Each <moduleSpec> can be either a bare module name or it can be
14031 a module name with a version constraint (operators =, <, >, <=
14032 and >= are supported). The following are examples for a module
14033 named foo with various constraints:
14034 · foo matches any version.
14036 · foo<2 only matches versions before 2.
14038 · foo>=3.1 matches any version from 3.1 or later.
14040 · foo=1.2.3 requires that foo must be exactly version 1.2.3.
14042 The following variables may be set upon return. Two sets of
14044 values exist: One for the common case (<XXX> = <prefix>) and
14045 another for the information pkg-config provides when called with
14046 the --static option (<XXX> = <prefix>_STATIC).
14047 <XXX>_FOUND
14049 set to 1 if module(s) exist
14050 <XXX>_LIBRARIES
14052 only the libraries (without the ‘-l’)
14053 <XXX>_LINK_LIBRARIES
14055 the libraries and their absolute paths
14056 <XXX>_LIBRARY_DIRS
14058 the paths of the libraries (without the ‘-L’)
14059 <XXX>_LDFLAGS
14061 all required linker flags
14062 <XXX>_LDFLAGS_OTHER
14064 all other linker flags
14065 <XXX>_INCLUDE_DIRS
14067 the ‘-I’ preprocessor flags (without the ‘-I’)
14068 <XXX>_CFLAGS
14070 all required cflags
14071 <XXX>_CFLAGS_OTHER
14073 the other compiler flags
14074 All but <XXX>_FOUND may be a ;-list if the associated variable
14076 returned from pkg-config has multiple values.
14077 There are some special variables whose prefix depends on the
14079 number of <moduleSpec> given. When there is only one <module‐
14080 Spec>, <YYY> will simply be <prefix>, but if two or more <mod‐
14081 uleSpec> items are given, <YYY> will be <prefix>_<moduleName>.
14082 <YYY>_VERSION
14084 version of the module
14085 <YYY>_PREFIX
14087 prefix directory of the module
14088 <YYY>_INCLUDEDIR
14090 include directory of the module
14091 <YYY>_LIBDIR
14093 lib directory of the module
14094 Examples:
14096 pkg_check_modules (GLIB2 glib-2.0)
14098 Looks for any version of glib2. If found, the output variable
14100 GLIB2_VERSION will hold the actual version found.
14101 pkg_check_modules (GLIB2 glib-2.0>=2.10)
14103 Looks for at least version 2.10 of glib2. If found, the output
14105 variable GLIB2_VERSION will hold the actual version found.
14106 pkg_check_modules (FOO glib-2.0>=2.10 gtk+-2.0)
14108 Looks for both glib2-2.0 (at least version 2.10) and any version
14110 of gtk2+-2.0. Only if both are found will FOO be considered
14111 found. The FOO_glib-2.0_VERSION and FOO_gtk+-2.0_VERSION vari‐
14112 ables will be set to their respective found module versions.
14113 pkg_check_modules (XRENDER REQUIRED xrender)
14115 Requires any version of xrender. Example output variables set
14117 by a successful call:
14118 XRENDER_LIBRARIES=Xrender;X11
14120 XRENDER_STATIC_LIBRARIES=Xrender;X11;pthread;Xau;Xdmcp
14121 pkg_search_module
14123 The behavior of this command is the same as pkg_check_modules(),
14124 except that rather than checking for all the specified modules,
14125 it searches for just the first successful match.
14126 pkg_search_module(<prefix>
14128 [REQUIRED] [QUIET]
14129 [NO_CMAKE_PATH]
14130 [NO_CMAKE_ENVIRONMENT_PATH]
14131 [IMPORTED_TARGET [GLOBAL]]
14132 <moduleSpec> [<moduleSpec>...])
14133 If a module is found, the <prefix>_MODULE_NAME variable will
14135 contain the name of the matching module. This variable can be
14136 used if you need to run pkg_get_variable().
14137 Example:
14139 pkg_search_module (BAR libxml-2.0 libxml2 libxml>=2)
14141 pkg_get_variable
14143 Retrieves the value of a pkg-config variable varName and stores
14144 it in the result variable resultVar in the calling scope.
14145 pkg_get_variable(<resultVar> <moduleName> <varName>)
14147 If pkg-config returns multiple values for the specified vari‐
14149 able, resultVar will contain a ;-list.
14150 For example:
14152 pkg_get_variable(GI_GIRDIR gobject-introspection-1.0 girdir)
14154 Variables Affecting Behavior
14156 PKG_CONFIG_EXECUTABLE
14157 This can be set to the path of the pkg-config executable. If
14158 not provided, it will be set by the module as a result of call‐
14159 ing find_program() internally. The PKG_CONFIG environment vari‐
14160 able can be used as a hint.
14161 PKG_CONFIG_USE_CMAKE_PREFIX_PATH
14163 Specifies whether pkg_check_modules() and pkg_search_module()
14164 should add the paths in the CMAKE_PREFIX_PATH, CMAKE_FRAME‐
14165 WORK_PATH and CMAKE_APPBUNDLE_PATH cache and environment vari‐
14166 ables to the pkg-config search path.
14167 If this variable is not set, this behavior is enabled by default
14169 if CMAKE_MINIMUM_REQUIRED_VERSION is 3.1 or later, disabled oth‐
14170 erwise.
14171 FindPNG
14173 Find libpng, the official reference library for the PNG image format.
14174 Imported targets
14176 This module defines the following IMPORTED target:
14177 PNG::PNG
14179 The libpng library, if found.
14180 Result variables
14182 This module will set the following variables in your project:
14183 PNG_INCLUDE_DIRS
14185 where to find png.h, etc.
14186 PNG_LIBRARIES
14188 the libraries to link against to use PNG.
14189 PNG_DEFINITIONS
14191 You should add_definitions(${PNG_DEFINITIONS}) before compiling
14192 code that includes png library files.
14193 PNG_FOUND
14195 If false, do not try to use PNG.
14196 PNG_VERSION_STRING
14198 the version of the PNG library found (since CMake 2.8.8)
14199 Obsolete variables
14201 The following variables may also be set, for backwards compatibility:
14202 PNG_LIBRARY
14204 where to find the PNG library.
14205 PNG_INCLUDE_DIR
14207 where to find the PNG headers (same as PNG_INCLUDE_DIRS)
14208 Since PNG depends on the ZLib compression library, none of the above
14210 will be defined unless ZLib can be found.
14211 FindPostgreSQL
14213 Find the PostgreSQL installation.
14214 IMPORTED Targets
14216 This module defines IMPORTED target PostgreSQL::PostgreSQL if Post‐
14217 greSQL has been found.
14218 Result Variables
14220 This module will set the following variables in your project:
14221 PostgreSQL_FOUND
14223 True if PostgreSQL is found.
14224 PostgreSQL_LIBRARIES
14226 the PostgreSQL libraries needed for linking
14227 PostgreSQL_INCLUDE_DIRS
14229 the directories of the PostgreSQL headers
14230 PostgreSQL_LIBRARY_DIRS
14232 the link directories for PostgreSQL libraries
14233 PostgreSQL_VERSION_STRING
14235 the version of PostgreSQL found
14236 FindProducer
14238 Though Producer isn’t directly part of OpenSceneGraph, its primary user
14239 is OSG so I consider this part of the Findosg* suite used to find Open‐
14240 SceneGraph components. You’ll notice that I accept OSGDIR as an envi‐
14241 ronment path.
14242 Each component is separate and you must opt in to each module. You
14244 must also opt into OpenGL (and OpenThreads?) as these modules won’t do
14245 it for you. This is to allow you control over your own system piece by
14246 piece in case you need to opt out of certain components or change the
14247 Find behavior for a particular module (perhaps because the default
14248 FindOpenGL.cmake module doesn’t work with your system as an example).
14249 If you want to use a more convenient module that includes everything,
14250 use the FindOpenSceneGraph.cmake instead of the Findosg*.cmake modules.
14251 Locate Producer This module defines PRODUCER_LIBRARY PRODUCER_FOUND, if
14253 false, do not try to link to Producer PRODUCER_INCLUDE_DIR, where to
14254 find the headers
14255 $PRODUCER_DIR is an environment variable that would correspond to the
14257 ./configure –prefix=$PRODUCER_DIR used in building osg.
14258 Created by Eric Wing.
14260 FindProtobuf
14262 Locate and configure the Google Protocol Buffers library.
14263 The following variables can be set and are optional:
14265 Protobuf_SRC_ROOT_FOLDER
14267 When compiling with MSVC, if this cache variable is set the pro‐
14268 tobuf-default VS project build locations (vsprojects/Debug and
14269 vsprojects/Release or vsprojects/x64/Debug and vspro‐
14270 jects/x64/Release) will be searched for libraries and binaries.
14271 Protobuf_IMPORT_DIRS
14273 List of additional directories to be searched for imported
14274 .proto files.
14275 Protobuf_DEBUG
14277 Show debug messages.
14278 Protobuf_USE_STATIC_LIBS
14280 Set to ON to force the use of the static libraries. Default is
14281 OFF.
14282 Defines the following variables:
14284 Protobuf_FOUND
14286 Found the Google Protocol Buffers library (libprotobuf & header
14287 files)
14288 Protobuf_VERSION
14290 Version of package found.
14291 Protobuf_INCLUDE_DIRS
14293 Include directories for Google Protocol Buffers
14294 Protobuf_LIBRARIES
14296 The protobuf libraries
14297 Protobuf_PROTOC_LIBRARIES
14299 The protoc libraries
14300 Protobuf_LITE_LIBRARIES
14302 The protobuf-lite libraries
14303 The following IMPORTED targets are also defined:
14305 protobuf::libprotobuf
14307 The protobuf library.
14308 protobuf::libprotobuf-lite
14310 The protobuf lite library.
14311 protobuf::libprotoc
14313 The protoc library.
14314 protobuf::protoc
14316 The protoc compiler.
14317 The following cache variables are also available to set or use:
14319 Protobuf_LIBRARY
14321 The protobuf library
14322 Protobuf_PROTOC_LIBRARY
14324 The protoc library
14325 Protobuf_INCLUDE_DIR
14327 The include directory for protocol buffers
14328 Protobuf_PROTOC_EXECUTABLE
14330 The protoc compiler
14331 Protobuf_LIBRARY_DEBUG
14333 The protobuf library (debug)
14334 Protobuf_PROTOC_LIBRARY_DEBUG
14336 The protoc library (debug)
14337 Protobuf_LITE_LIBRARY
14339 The protobuf lite library
14340 Protobuf_LITE_LIBRARY_DEBUG
14342 The protobuf lite library (debug)
14343 Example:
14345 find_package(Protobuf REQUIRED)
14347 include_directories(${Protobuf_INCLUDE_DIRS})
14348 include_directories(${CMAKE_CURRENT_BINARY_DIR})
14349 protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS foo.proto)
14350 protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS EXPORT_MACRO DLL_EXPORT foo.proto)
14351 protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS DESCRIPTORS PROTO_DESCS foo.proto)
14352 protobuf_generate_python(PROTO_PY foo.proto)
14353 add_executable(bar bar.cc ${PROTO_SRCS} ${PROTO_HDRS})
14354 target_link_libraries(bar ${Protobuf_LIBRARIES})
14355 NOTE:
14357 The protobuf_generate_cpp and protobuf_generate_python functions and
14358 add_executable() or add_library() calls only work properly within
14359 the same directory.
14360 protobuf_generate_cpp
14362 Add custom commands to process .proto files to C++:
14363 protobuf_generate_cpp (<SRCS> <HDRS>
14365 [DESCRIPTORS <DESC>] [EXPORT_MACRO <MACRO>] [<ARGN>...])
14366 SRCS Variable to define with autogenerated source files
14368 HDRS Variable to define with autogenerated header files
14370 DESCRIPTORS
14372 Variable to define with autogenerated descriptor files,
14373 if requested.
14374 EXPORT_MACRO
14376 is a macro which should expand to __declspec(dllexport)
14377 or __declspec(dllimport) depending on what is being com‐
14378 piled.
14379 ARGN .proto files
14381 protobuf_generate_python
14383 Add custom commands to process .proto files to Python:
14384 protobuf_generate_python (<PY> [<ARGN>...])
14386 PY Variable to define with autogenerated Python files
14388 ARGN .proto files
14390 FindPython
14392 New in version 3.12.
14393 Find Python interpreter, compiler and development environment (include
14396 directories and libraries).
14397 When a version is requested, it can be specified as a simple value or
14399 as a range. For a detailed description of version range usage and capa‐
14400 bilities, refer to the find_package() command.
14401 The following components are supported:
14403 · Interpreter: search for Python interpreter.
14405 · Compiler: search for Python compiler. Only offered by IronPython.
14407 · Development: search for development artifacts (include directories
14409 and libraries). This component includes two sub-components which can
14410 be specified independently:
14411 · Development.Module: search for artifacts for Python module develop‐
14413 ments.
14414 · Development.Embed: search for artifacts for Python embedding devel‐
14416 opments.
14417 · NumPy: search for NumPy include directories.
14419 If no COMPONENTS are specified, Interpreter is assumed.
14421 If component Development is specified, it implies sub-components Devel‐
14423 opment.Module and Development.Embed.
14424 To ensure consistent versions between components Interpreter, Compiler,
14426 Development (or one of its sub-components) and NumPy, specify all com‐
14427 ponents at the same time:
14428 find_package (Python COMPONENTS Interpreter Development)
14430 This module looks preferably for version 3 of Python. If not found,
14432 version 2 is searched. To manage concurrent versions 3 and 2 of
14433 Python, use FindPython3 and FindPython2 modules rather than this one.
14434 NOTE:
14436 If components Interpreter and Development (or one of its sub-compo‐
14437 nents) are both specified, this module search only for interpreter
14438 with same platform architecture as the one defined by CMake configu‐
14439 ration. This constraint does not apply if only Interpreter component
14440 is specified.
14441 Imported Targets
14443 This module defines the following Imported Targets (when CMAKE_ROLE is
14444 PROJECT):
14445 Python::Interpreter
14447 Python interpreter. Target defined if component Interpreter is
14448 found.
14449 Python::Compiler
14451 Python compiler. Target defined if component Compiler is found.
14452 Python::Module
14454 Python library for Python module. Target defined if component
14455 Development.Module is found.
14456 Python::Python
14458 Python library for Python embedding. Target defined if component
14459 Development.Embed is found.
14460 Python::NumPy
14462 NumPy Python library. Target defined if component NumPy is
14463 found.
14464 Result Variables
14466 This module will set the following variables in your project (see Stan‐
14467 dard Variable Names):
14468 Python_FOUND
14470 System has the Python requested components.
14471 Python_Interpreter_FOUND
14473 System has the Python interpreter.
14474 Python_EXECUTABLE
14476 Path to the Python interpreter.
14477 Python_INTERPRETER_ID
14479 A short string unique to the interpreter. Possible values
14481 include:
14482 · Python
14484 · ActivePython
14486 · Anaconda
14488 · Canopy
14490 · IronPython
14492 · PyPy
14494 Python_STDLIB
14496 Standard platform independent installation directory.
14497 Information returned by distutils.syscon‐
14499 fig.get_python_lib(plat_specific=False,standard_lib=True) or
14500 else sysconfig.get_path('stdlib').
14501 Python_STDARCH
14503 Standard platform dependent installation directory.
14504 Information returned by distutils.syscon‐
14506 fig.get_python_lib(plat_specific=True,standard_lib=True) or else
14507 sysconfig.get_path('platstdlib').
14508 Python_SITELIB
14510 Third-party platform independent installation directory.
14511 Information returned by distutils.syscon‐
14513 fig.get_python_lib(plat_specific=False,standard_lib=False) or
14514 else sysconfig.get_path('purelib').
14515 Python_SITEARCH
14517 Third-party platform dependent installation directory.
14518 Information returned by distutils.syscon‐
14520 fig.get_python_lib(plat_specific=True,standard_lib=False) or
14521 else sysconfig.get_path('platlib').
14522 Python_SOABI
14524 Extension suffix for modules.
14525 Information returned by distutils.sysconfig.get_con‐
14527 fig_var('SOABI') or computed from distutils.sysconfig.get_con‐
14528 fig_var('EXT_SUFFIX') or python-config --extension-suffix. If
14529 package distutils.sysconfig is not available, sysconfig.get_con‐
14530 fig_var('SOABI') or sysconfig.get_config_var('EXT_SUFFIX') are
14531 used.
14532 Python_Compiler_FOUND
14534 System has the Python compiler.
14535 Python_COMPILER
14537 Path to the Python compiler. Only offered by IronPython.
14538 Python_COMPILER_ID
14540 A short string unique to the compiler. Possible values include:
14542 · IronPython
14544 Python_DOTNET_LAUNCHER
14546 The .Net interpreter. Only used by IronPython implementation.
14547 Python_Development_FOUND
14549 System has the Python development artifacts.
14550 Python_Development.Module_FOUND
14552 System has the Python development artifacts for Python module.
14553 Python_Development.Embed_FOUND
14555 System has the Python development artifacts for Python embed‐
14556 ding.
14557 Python_INCLUDE_DIRS
14559 The Python include directories.
14560 Python_LINK_OPTIONS
14562 The Python link options. Some configurations require specific
14563 link options for a correct build and execution.
14564 Python_LIBRARIES
14566 The Python libraries.
14567 Python_LIBRARY_DIRS
14569 The Python library directories.
14570 Python_RUNTIME_LIBRARY_DIRS
14572 The Python runtime library directories.
14573 Python_VERSION
14575 Python version.
14576 Python_VERSION_MAJOR
14578 Python major version.
14579 Python_VERSION_MINOR
14581 Python minor version.
14582 Python_VERSION_PATCH
14584 Python patch version.
14585 Python_PyPy_VERSION
14587 Python PyPy version.
14588 Python_NumPy_FOUND
14590 System has the NumPy.
14591 Python_NumPy_INCLUDE_DIRS
14593 The NumPy include directories.
14594 Python_NumPy_VERSION
14596 The NumPy version.
14597 Hints
14599 Python_ROOT_DIR
14600 Define the root directory of a Python installation.
14601 Python_USE_STATIC_LIBS
14603 · If not defined, search for shared libraries and static
14605 libraries in that order.
14606 · If set to TRUE, search only for static libraries.
14608 · If set to FALSE, search only for shared libraries.
14610 Python_FIND_ABI
14612 This variable defines which ABIs, as defined in PEP 3149, should
14613 be searched.
14614 NOTE:
14616 This hint will be honored only when searched for Python ver‐
14617 sion 3.
14618 NOTE:
14620 If Python_FIND_ABI is not defined, any ABI will be searched.
14621 The Python_FIND_ABI variable is a 3-tuple specifying, in that
14623 order, pydebug (d), pymalloc (m) and unicode (u) flags. Each
14624 element can be set to one of the following:
14625 · ON: Corresponding flag is selected.
14627 · OFF: Corresponding flag is not selected.
14629 · ANY: The two possibilities (ON and OFF) will be searched.
14631 From this 3-tuple, various ABIs will be searched starting from
14633 the most specialized to the most general. Moreover, debug ver‐
14634 sions will be searched after non-debug ones.
14635 For example, if we have:
14637 set (Python_FIND_ABI "ON" "ANY" "ANY")
14639 The following flags combinations will be appended, in that
14641 order, to the artifact names: dmu, dm, du, and d.
14642 And to search any possible ABIs:
14644 set (Python_FIND_ABI "ANY" "ANY" "ANY")
14646 The following combinations, in that order, will be used: mu, m,
14648 u, <empty>, dmu, dm, du and d.
14649 NOTE:
14651 This hint is useful only on POSIX systems. So, on Windows
14652 systems, when Python_FIND_ABI is defined, Python distribu‐
14653 tions from python.org will be found only if value for each
14654 flag is OFF or ANY.
14655 Python_FIND_STRATEGY
14657 This variable defines how lookup will be done. The
14658 Python_FIND_STRATEGY variable can be set to one of the follow‐
14659 ing:
14660 · VERSION: Try to find the most recent version in all specified
14662 locations. This is the default if policy CMP0094 is undefined
14663 or set to OLD.
14664 · LOCATION: Stops lookup as soon as a version satisfying version
14666 constraints is founded. This is the default if policy CMP0094
14667 is set to NEW.
14668 Python_FIND_REGISTRY
14670 On Windows the Python_FIND_REGISTRY variable determine the order
14671 of preference between registry and environment variables. the
14672 Python_FIND_REGISTRY variable can be set to one of the follow‐
14673 ing:
14674 · FIRST: Try to use registry before environment variables. This
14676 is the default.
14677 · LAST: Try to use registry after environment variables.
14679 · NEVER: Never try to use registry.
14681 Python_FIND_FRAMEWORK
14683 On macOS the Python_FIND_FRAMEWORK variable determine the order
14684 of preference between Apple-style and unix-style package compo‐
14685 nents. This variable can take same values as CMAKE_FIND_FRAME‐
14686 WORK variable.
14687 NOTE:
14689 Value ONLY is not supported so FIRST will be used instead.
14690 If Python_FIND_FRAMEWORK is not defined, CMAKE_FIND_FRAMEWORK
14692 variable will be used, if any.
14693 Python_FIND_VIRTUALENV
14695 This variable defines the handling of virtual environments man‐
14696 aged by virtualenv or conda. It is meaningful only when a vir‐
14697 tual environment is active (i.e. the activate script has been
14698 evaluated). In this case, it takes precedence over
14699 Python_FIND_REGISTRY and CMAKE_FIND_FRAMEWORK variables. The
14700 Python_FIND_VIRTUALENV variable can be set to one of the follow‐
14701 ing:
14702 · FIRST: The virtual environment is used before any other stan‐
14704 dard paths to look-up for the interpreter. This is the
14705 default.
14706 · ONLY: Only the virtual environment is used to look-up for the
14708 interpreter.
14709 · STANDARD: The virtual environment is not used to look-up for
14711 the interpreter but environment variable PATH is always con‐
14712 sidered. In this case, variable Python_FIND_REGISTRY (Win‐
14713 dows) or CMAKE_FIND_FRAMEWORK (macOS) can be set with value
14714 LAST or NEVER to select preferably the interpreter from the
14715 virtual environment.
14716 NOTE:
14718 If the component Development is requested, it is strongly
14719 recommended to also include the component Interpreter to get
14720 expected result.
14721 Python_FIND_IMPLEMENTATIONS
14723 This variable defines, in an ordered list, the different imple‐
14724 mentations which will be searched. The Python_FIND_IMPLEMENTA‐
14725 TIONS variable can hold the following values:
14726 · CPython: this is the standard implementation. Various prod‐
14728 ucts, like Anaconda or ActivePython, rely on this implementa‐
14729 tion.
14730 · IronPython: This implementation use the CSharp language for
14732 .NET Framework on top of the Dynamic Language Runtime (DLR).
14733 See IronPython.
14734 · PyPy: This implementation use RPython language and RPython
14736 translation toolchain to produce the python interpreter. See
14737 PyPy.
14738 The default value is:
14740 · Windows platform: CPython, IronPython
14742 · Other platforms: CPython
14744 NOTE:
14746 This hint has the lowest priority of all hints, so even if,
14747 for example, you specify IronPython first and CPython in sec‐
14748 ond, a python product based on CPython can be selected
14749 because, for example with Python_FIND_STRATEGY=LOCATION, each
14750 location will be search first for IronPython and second for
14751 CPython.
14752 NOTE:
14754 When IronPython is specified, on platforms other than Win‐
14755 dows, the .Net interpreter (i.e. mono command) is expected to
14756 be available through the PATH variable.
14757 Artifacts Specification
14759 To solve special cases, it is possible to specify directly the arti‐
14760 facts by setting the following variables:
14761 Python_EXECUTABLE
14763 The path to the interpreter.
14764 Python_COMPILER
14766 The path to the compiler.
14767 Python_DOTNET_LAUNCHER
14769 The .Net interpreter. Only used by IronPython implementation.
14770 Python_LIBRARY
14772 The path to the library. It will be used to compute the vari‐
14773 ables Python_LIBRARIES, Python_LIBRARY_DIRS and Python_RUN‐
14774 TIME_LIBRARY_DIRS.
14775 Python_INCLUDE_DIR
14777 The path to the directory of the Python headers. It will be used
14778 to compute the variable Python_INCLUDE_DIRS.
14779 Python_NumPy_INCLUDE_DIR
14781 The path to the directory of the NumPy headers. It will be used
14782 to compute the variable Python_NumPy_INCLUDE_DIRS.
14783 NOTE:
14785 All paths must be absolute. Any artifact specified with a relative
14786 path will be ignored.
14787 NOTE:
14789 When an artifact is specified, all HINTS will be ignored and no
14790 search will be performed for this artifact.
14791 If more than one artifact is specified, it is the user’s responsi‐
14793 bility to ensure the consistency of the various artifacts.
14794 By default, this module supports multiple calls in different directo‐
14796 ries of a project with different version/component requirements while
14797 providing correct and consistent results for each call. To support this
14798 behavior, CMake cache is not used in the traditional way which can be
14799 problematic for interactive specification. So, to enable also interac‐
14800 tive specification, module behavior can be controlled with the follow‐
14801 ing variable:
14802 Python_ARTIFACTS_INTERACTIVE
14804 Selects the behavior of the module. This is a boolean variable:
14805 · If set to TRUE: Create CMake cache entries for the above arti‐
14807 fact specification variables so that users can edit them
14808 interactively. This disables support for multiple ver‐
14809 sion/component requirements.
14810 · If set to FALSE or undefined: Enable multiple version/compo‐
14812 nent requirements.
14813 Commands
14815 This module defines the command Python_add_library (when CMAKE_ROLE is
14816 PROJECT), which has the same semantics as add_library() and adds a
14817 dependency to target Python::Python or, when library type is MODULE, to
14818 target Python::Module and takes care of Python module naming rules:
14819 Python_add_library (<name> [STATIC | SHARED | MODULE [WITH_SOABI]]
14821 <source1> [<source2> ...])
14822 If the library type is not specified, MODULE is assumed.
14824 For MODULE library type, if option WITH_SOABI is specified, the module
14826 suffix will include the Python_SOABI value, if any.
14827 FindPython2
14829 New in version 3.12.
14830 Find Python 2 interpreter, compiler and development environment
14833 (include directories and libraries).
14834 When a version is requested, it can be specified as a simple value or
14836 as a range. For a detailed description of version range usage and capa‐
14837 bilities, refer to the find_package() command.
14838 The following components are supported:
14840 · Interpreter: search for Python 2 interpreter
14842 · Compiler: search for Python 2 compiler. Only offered by IronPython.
14844 · Development: search for development artifacts (include directories
14846 and libraries). This component includes two sub-components which can
14847 be specified independently:
14848 · Development.Module: search for artifacts for Python 2 module devel‐
14850 opments.
14851 · Development.Embed: search for artifacts for Python 2 embedding
14853 developments.
14854 · NumPy: search for NumPy include directories.
14856 If no COMPONENTS are specified, Interpreter is assumed.
14858 If component Development is specified, it implies sub-components Devel‐
14860 opment.Module and Development.Embed.
14861 To ensure consistent versions between components Interpreter, Compiler,
14863 Development (or one of its sub-components) and NumPy, specify all com‐
14864 ponents at the same time:
14865 find_package (Python2 COMPONENTS Interpreter Development)
14867 This module looks only for version 2 of Python. This module can be used
14869 concurrently with FindPython3 module to use both Python versions.
14870 The FindPython module can be used if Python version does not matter for
14872 you.
14873 NOTE:
14875 If components Interpreter and Development (or one of its sub-compo‐
14876 nents) are both specified, this module search only for interpreter
14877 with same platform architecture as the one defined by CMake configu‐
14878 ration. This constraint does not apply if only Interpreter component
14879 is specified.
14880 Imported Targets
14882 This module defines the following Imported Targets (when CMAKE_ROLE is
14883 PROJECT):
14884 Python2::Interpreter
14886 Python 2 interpreter. Target defined if component Interpreter is
14887 found.
14888 Python2::Compiler
14890 Python 2 compiler. Target defined if component Compiler is
14891 found.
14892 Python2::Module
14894 Python 2 library for Python module. Target defined if component
14895 Development.Module is found.
14896 Python2::Python
14898 Python 2 library for Python embedding. Target defined if compo‐
14899 nent Development.Embed is found.
14900 Python2::NumPy
14902 NumPy library for Python 2. Target defined if component NumPy is
14903 found.
14904 Result Variables
14906 This module will set the following variables in your project (see Stan‐
14907 dard Variable Names):
14908 Python2_FOUND
14910 System has the Python 2 requested components.
14911 Python2_Interpreter_FOUND
14913 System has the Python 2 interpreter.
14914 Python2_EXECUTABLE
14916 Path to the Python 2 interpreter.
14917 Python2_INTERPRETER_ID
14919 A short string unique to the interpreter. Possible values
14921 include:
14922 · Python
14924 · ActivePython
14926 · Anaconda
14928 · Canopy
14930 · IronPython
14932 · PyPy
14934 Python2_STDLIB
14936 Standard platform independent installation directory.
14937 Information returned by distutils.syscon‐
14939 fig.get_python_lib(plat_specific=False,standard_lib=True) or
14940 else sysconfig.get_path('stdlib').
14941 Python2_STDARCH
14943 Standard platform dependent installation directory.
14944 Information returned by distutils.syscon‐
14946 fig.get_python_lib(plat_specific=True,standard_lib=True) or else
14947 sysconfig.get_path('platstdlib').
14948 Python2_SITELIB
14950 Third-party platform independent installation directory.
14951 Information returned by distutils.syscon‐
14953 fig.get_python_lib(plat_specific=False,standard_lib=False) or
14954 else sysconfig.get_path('purelib').
14955 Python2_SITEARCH
14957 Third-party platform dependent installation directory.
14958 Information returned by distutils.syscon‐
14960 fig.get_python_lib(plat_specific=True,standard_lib=False) or
14961 else sysconfig.get_path('platlib').
14962 Python2_Compiler_FOUND
14964 System has the Python 2 compiler.
14965 Python2_COMPILER
14967 Path to the Python 2 compiler. Only offered by IronPython.
14968 Python2_COMPILER_ID
14970 A short string unique to the compiler. Possible values include:
14972 · IronPython
14974 Python2_DOTNET_LAUNCHER
14976 The .Net interpreter. Only used by IronPython implementation.
14977 Python2_Development_FOUND
14979 System has the Python 2 development artifacts.
14980 Python2_Development.Module_FOUND
14982 System has the Python 2 development artifacts for Python module.
14983 Python2_Development.Embed_FOUND
14985 System has the Python 2 development artifacts for Python embed‐
14986 ding.
14987 Python2_INCLUDE_DIRS
14989 The Python 2 include directories.
14990 Python2_LINK_OPTIONS
14992 The Python 2 link options. Some configurations require specific
14993 link options for a correct build and execution.
14994 Python2_LIBRARIES
14996 The Python 2 libraries.
14997 Python2_LIBRARY_DIRS
14999 The Python 2 library directories.
15000 Python2_RUNTIME_LIBRARY_DIRS
15002 The Python 2 runtime library directories.
15003 Python2_VERSION
15005 Python 2 version.
15006 Python2_VERSION_MAJOR
15008 Python 2 major version.
15009 Python2_VERSION_MINOR
15011 Python 2 minor version.
15012 Python2_VERSION_PATCH
15014 Python 2 patch version.
15015 Python2_PyPy_VERSION
15017 Python 2 PyPy version.
15018 Python2_NumPy_FOUND
15020 System has the NumPy.
15021 Python2_NumPy_INCLUDE_DIRS
15023 The NumPy include directories.
15024 Python2_NumPy_VERSION
15026 The NumPy version.
15027 Hints
15029 Python2_ROOT_DIR
15030 Define the root directory of a Python 2 installation.
15031 Python2_USE_STATIC_LIBS
15033 · If not defined, search for shared libraries and static
15035 libraries in that order.
15036 · If set to TRUE, search only for static libraries.
15038 · If set to FALSE, search only for shared libraries.
15040 Python2_FIND_STRATEGY
15042 This variable defines how lookup will be done. The
15043 Python2_FIND_STRATEGY variable can be set to one of the follow‐
15044 ing:
15045 · VERSION: Try to find the most recent version in all specified
15047 locations. This is the default if policy CMP0094 is undefined
15048 or set to OLD.
15049 · LOCATION: Stops lookup as soon as a version satisfying version
15051 constraints is founded. This is the default if policy CMP0094
15052 is set to NEW.
15053 Python2_FIND_REGISTRY
15055 On Windows the Python2_FIND_REGISTRY variable determine the
15056 order of preference between registry and environment variables.
15057 the Python2_FIND_REGISTRY variable can be set to one of the fol‐
15058 lowing:
15059 · FIRST: Try to use registry before environment variables. This
15061 is the default.
15062 · LAST: Try to use registry after environment variables.
15064 · NEVER: Never try to use registry.
15066 Python2_FIND_FRAMEWORK
15068 On macOS the Python2_FIND_FRAMEWORK variable determine the order
15069 of preference between Apple-style and unix-style package compo‐
15070 nents. This variable can take same values as CMAKE_FIND_FRAME‐
15071 WORK variable.
15072 NOTE:
15074 Value ONLY is not supported so FIRST will be used instead.
15075 If Python2_FIND_FRAMEWORK is not defined, CMAKE_FIND_FRAMEWORK
15077 variable will be used, if any.
15078 Python2_FIND_VIRTUALENV
15080 This variable defines the handling of virtual environments man‐
15081 aged by virtualenv or conda. It is meaningful only when a vir‐
15082 tual environment is active (i.e. the activate script has been
15083 evaluated). In this case, it takes precedence over
15084 Python2_FIND_REGISTRY and CMAKE_FIND_FRAMEWORK variables. The
15085 Python2_FIND_VIRTUALENV variable can be set to one of the fol‐
15086 lowing:
15087 · FIRST: The virtual environment is used before any other stan‐
15089 dard paths to look-up for the interpreter. This is the
15090 default.
15091 · ONLY: Only the virtual environment is used to look-up for the
15093 interpreter.
15094 · STANDARD: The virtual environment is not used to look-up for
15096 the interpreter but environment variable PATH is always con‐
15097 sidered. In this case, variable Python2_FIND_REGISTRY (Win‐
15098 dows) or CMAKE_FIND_FRAMEWORK (macOS) can be set with value
15099 LAST or NEVER to select preferably the interpreter from the
15100 virtual environment.
15101 NOTE:
15103 If the component Development is requested, it is strongly
15104 recommended to also include the component Interpreter to get
15105 expected result.
15106 Python2_FIND_IMPLEMENTATIONS
15108 This variable defines, in an ordered list, the different imple‐
15109 mentations which will be searched. The Python2_FIND_IMPLEMENTA‐
15110 TIONS variable can hold the following values:
15111 · CPython: this is the standard implementation. Various prod‐
15113 ucts, like Anaconda or ActivePython, rely on this implementa‐
15114 tion.
15115 · IronPython: This implementation use the CSharp language for
15117 .NET Framework on top of the Dynamic Language Runtime (DLR).
15118 See IronPython.
15119 · PyPy: This implementation use RPython language and RPython
15121 translation toolchain to produce the python interpreter. See
15122 PyPy.
15123 The default value is:
15125 · Windows platform: CPython, IronPython
15127 · Other platforms: CPython
15129 NOTE:
15131 This hint has the lowest priority of all hints, so even if,
15132 for example, you specify IronPython first and CPython in sec‐
15133 ond, a python product based on CPython can be selected
15134 because, for example with Python2_FIND_STRATEGY=LOCATION,
15135 each location will be search first for IronPython and second
15136 for CPython.
15137 NOTE:
15139 When IronPython is specified, on platforms other than Win‐
15140 dows, the .Net interpreter (i.e. mono command) is expected to
15141 be available through the PATH variable.
15142 Artifacts Specification
15144 To solve special cases, it is possible to specify directly the arti‐
15145 facts by setting the following variables:
15146 Python2_EXECUTABLE
15148 The path to the interpreter.
15149 Python2_COMPILER
15151 The path to the compiler.
15152 Python2_DOTNET_LAUNCHER
15154 The .Net interpreter. Only used by IronPython implementation.
15155 Python2_LIBRARY
15157 The path to the library. It will be used to compute the vari‐
15158 ables Python2_LIBRARIES, Python2_LIBRARY_DIRS and Python2_RUN‐
15159 TIME_LIBRARY_DIRS.
15160 Python2_INCLUDE_DIR
15162 The path to the directory of the Python headers. It will be used
15163 to compute the variable Python2_INCLUDE_DIRS.
15164 Python2_NumPy_INCLUDE_DIR
15166 The path to the directory of the NumPy headers. It will be used
15167 to compute the variable Python2_NumPy_INCLUDE_DIRS.
15168 NOTE:
15170 All paths must be absolute. Any artifact specified with a relative
15171 path will be ignored.
15172 NOTE:
15174 When an artifact is specified, all HINTS will be ignored and no
15175 search will be performed for this artifact.
15176 If more than one artifact is specified, it is the user’s responsi‐
15178 bility to ensure the consistency of the various artifacts.
15179 By default, this module supports multiple calls in different directo‐
15181 ries of a project with different version/component requirements while
15182 providing correct and consistent results for each call. To support this
15183 behavior, CMake cache is not used in the traditional way which can be
15184 problematic for interactive specification. So, to enable also interac‐
15185 tive specification, module behavior can be controlled with the follow‐
15186 ing variable:
15187 Python2_ARTIFACTS_INTERACTIVE
15189 Selects the behavior of the module. This is a boolean variable:
15190 · If set to TRUE: Create CMake cache entries for the above arti‐
15192 fact specification variables so that users can edit them
15193 interactively. This disables support for multiple ver‐
15194 sion/component requirements.
15195 · If set to FALSE or undefined: Enable multiple version/compo‐
15197 nent requirements.
15198 Commands
15200 This module defines the command Python2_add_library (when CMAKE_ROLE is
15201 PROJECT), which has the same semantics as add_library() and adds a
15202 dependency to target Python2::Python or, when library type is MODULE,
15203 to target Python2::Module and takes care of Python module naming rules:
15204 Python2_add_library (<name> [STATIC | SHARED | MODULE]
15206 <source1> [<source2> ...])
15207 If library type is not specified, MODULE is assumed.
15209 FindPython3
15211 New in version 3.12.
15212 Find Python 3 interpreter, compiler and development environment
15215 (include directories and libraries).
15216 When a version is requested, it can be specified as a simple value or
15218 as a range. For a detailed description of version range usage and capa‐
15219 bilities, refer to the find_package() command.
15220 The following components are supported:
15222 · Interpreter: search for Python 3 interpreter
15224 · Compiler: search for Python 3 compiler. Only offered by IronPython.
15226 · Development: search for development artifacts (include directories
15228 and libraries). This component includes two sub-components which can
15229 be specified independently:
15230 · Development.Module: search for artifacts for Python 3 module devel‐
15232 opments.
15233 · Development.Embed: search for artifacts for Python 3 embedding
15235 developments.
15236 · NumPy: search for NumPy include directories.
15238 If no COMPONENTS are specified, Interpreter is assumed.
15240 If component Development is specified, it implies sub-components Devel‐
15242 opment.Module and Development.Embed.
15243 To ensure consistent versions between components Interpreter, Compiler,
15245 Development (or one of its sub-components) and NumPy, specify all com‐
15246 ponents at the same time:
15247 find_package (Python3 COMPONENTS Interpreter Development)
15249 This module looks only for version 3 of Python. This module can be used
15251 concurrently with FindPython2 module to use both Python versions.
15252 The FindPython module can be used if Python version does not matter for
15254 you.
15255 NOTE:
15257 If components Interpreter and Development (or one of its sub-compo‐
15258 nents) are both specified, this module search only for interpreter
15259 with same platform architecture as the one defined by CMake configu‐
15260 ration. This constraint does not apply if only Interpreter component
15261 is specified.
15262 Imported Targets
15264 This module defines the following Imported Targets (when CMAKE_ROLE is
15265 PROJECT):
15266 Python3::Interpreter
15268 Python 3 interpreter. Target defined if component Interpreter is
15269 found.
15270 Python3::Compiler
15272 Python 3 compiler. Target defined if component Compiler is
15273 found.
15274 Python3::Module
15276 Python 3 library for Python module. Target defined if component
15277 Development.Module is found.
15278 Python3::Python
15280 Python 3 library for Python embedding. Target defined if compo‐
15281 nent Development.Embed is found.
15282 Python3::NumPy
15284 NumPy library for Python 3. Target defined if component NumPy is
15285 found.
15286 Result Variables
15288 This module will set the following variables in your project (see Stan‐
15289 dard Variable Names):
15290 Python3_FOUND
15292 System has the Python 3 requested components.
15293 Python3_Interpreter_FOUND
15295 System has the Python 3 interpreter.
15296 Python3_EXECUTABLE
15298 Path to the Python 3 interpreter.
15299 Python3_INTERPRETER_ID
15301 A short string unique to the interpreter. Possible values
15303 include:
15304 · Python
15306 · ActivePython
15308 · Anaconda
15310 · Canopy
15312 · IronPython
15314 · PyPy
15316 Python3_STDLIB
15318 Standard platform independent installation directory.
15319 Information returned by distutils.syscon‐
15321 fig.get_python_lib(plat_specific=False,standard_lib=True) or
15322 else sysconfig.get_path('stdlib').
15323 Python3_STDARCH
15325 Standard platform dependent installation directory.
15326 Information returned by distutils.syscon‐
15328 fig.get_python_lib(plat_specific=True,standard_lib=True) or else
15329 sysconfig.get_path('platstdlib').
15330 Python3_SITELIB
15332 Third-party platform independent installation directory.
15333 Information returned by distutils.syscon‐
15335 fig.get_python_lib(plat_specific=False,standard_lib=False) or
15336 else sysconfig.get_path('purelib').
15337 Python3_SITEARCH
15339 Third-party platform dependent installation directory.
15340 Information returned by distutils.syscon‐
15342 fig.get_python_lib(plat_specific=True,standard_lib=False) or
15343 else sysconfig.get_path('platlib').
15344 Python3_SOABI
15346 Extension suffix for modules.
15347 Information returned by distutils.sysconfig.get_con‐
15349 fig_var('SOABI') or computed from distutils.sysconfig.get_con‐
15350 fig_var('EXT_SUFFIX') or python3-config --extension-suffix. If
15351 package distutils.sysconfig is not available, sysconfig.get_con‐
15352 fig_var('SOABI') or sysconfig.get_config_var('EXT_SUFFIX') are
15353 used.
15354 Python3_Compiler_FOUND
15356 System has the Python 3 compiler.
15357 Python3_COMPILER
15359 Path to the Python 3 compiler. Only offered by IronPython.
15360 Python3_COMPILER_ID
15362 A short string unique to the compiler. Possible values include:
15364 · IronPython
15366 Python3_DOTNET_LAUNCHER
15368 The .Net interpreter. Only used by IronPython implementation.
15369 Python3_Development_FOUND
15371 System has the Python 3 development artifacts.
15372 Python3_Development.Module_FOUND
15374 System has the Python 3 development artifacts for Python module.
15375 Python3_Development.Embed_FOUND
15377 System has the Python 3 development artifacts for Python embed‐
15378 ding.
15379 Python3_INCLUDE_DIRS
15381 The Python 3 include directories.
15382 Python3_LINK_OPTIONS
15384 The Python 3 link options. Some configurations require specific
15385 link options for a correct build and execution.
15386 Python3_LIBRARIES
15388 The Python 3 libraries.
15389 Python3_LIBRARY_DIRS
15391 The Python 3 library directories.
15392 Python3_RUNTIME_LIBRARY_DIRS
15394 The Python 3 runtime library directories.
15395 Python3_VERSION
15397 Python 3 version.
15398 Python3_VERSION_MAJOR
15400 Python 3 major version.
15401 Python3_VERSION_MINOR
15403 Python 3 minor version.
15404 Python3_VERSION_PATCH
15406 Python 3 patch version.
15407 Python3_PyPy_VERSION
15409 Python 3 PyPy version.
15410 Python3_NumPy_FOUND
15412 System has the NumPy.
15413 Python3_NumPy_INCLUDE_DIRS
15415 The NumPy include directories.
15416 Python3_NumPy_VERSION
15418 The NumPy version.
15419 Hints
15421 Python3_ROOT_DIR
15422 Define the root directory of a Python 3 installation.
15423 Python3_USE_STATIC_LIBS
15425 · If not defined, search for shared libraries and static
15427 libraries in that order.
15428 · If set to TRUE, search only for static libraries.
15430 · If set to FALSE, search only for shared libraries.
15432 Python3_FIND_ABI
15434 This variable defines which ABIs, as defined in PEP 3149, should
15435 be searched.
15436 NOTE:
15438 If Python3_FIND_ABI is not defined, any ABI will be searched.
15439 The Python3_FIND_ABI variable is a 3-tuple specifying, in that
15441 order, pydebug (d), pymalloc (m) and unicode (u) flags. Each
15442 element can be set to one of the following:
15443 · ON: Corresponding flag is selected.
15445 · OFF: Corresponding flag is not selected.
15447 · ANY: The two possibilities (ON and OFF) will be searched.
15449 From this 3-tuple, various ABIs will be searched starting from
15451 the most specialized to the most general. Moreover, debug ver‐
15452 sions will be searched after non-debug ones.
15453 For example, if we have:
15455 set (Python3_FIND_ABI "ON" "ANY" "ANY")
15457 The following flags combinations will be appended, in that
15459 order, to the artifact names: dmu, dm, du, and d.
15460 And to search any possible ABIs:
15462 set (Python3_FIND_ABI "ANY" "ANY" "ANY")
15464 The following combinations, in that order, will be used: mu, m,
15466 u, <empty>, dmu, dm, du and d.
15467 NOTE:
15469 This hint is useful only on POSIX systems. So, on Windows
15470 systems, when Python3_FIND_ABI is defined, Python distribu‐
15471 tions from python.org will be found only if value for each
15472 flag is OFF or ANY.
15473 Python3_FIND_STRATEGY
15475 This variable defines how lookup will be done. The
15476 Python3_FIND_STRATEGY variable can be set to one of the follow‐
15477 ing:
15478 · VERSION: Try to find the most recent version in all specified
15480 locations. This is the default if policy CMP0094 is undefined
15481 or set to OLD.
15482 · LOCATION: Stops lookup as soon as a version satisfying version
15484 constraints is founded. This is the default if policy CMP0094
15485 is set to NEW.
15486 Python3_FIND_REGISTRY
15488 On Windows the Python3_FIND_REGISTRY variable determine the
15489 order of preference between registry and environment variables.
15490 The Python3_FIND_REGISTRY variable can be set to one of the fol‐
15491 lowing:
15492 · FIRST: Try to use registry before environment variables. This
15494 is the default.
15495 · LAST: Try to use registry after environment variables.
15497 · NEVER: Never try to use registry.
15499 Python3_FIND_FRAMEWORK
15501 On macOS the Python3_FIND_FRAMEWORK variable determine the order
15502 of preference between Apple-style and unix-style package compo‐
15503 nents. This variable can take same values as CMAKE_FIND_FRAME‐
15504 WORK variable.
15505 NOTE:
15507 Value ONLY is not supported so FIRST will be used instead.
15508 If Python3_FIND_FRAMEWORK is not defined, CMAKE_FIND_FRAMEWORK
15510 variable will be used, if any.
15511 Python3_FIND_VIRTUALENV
15513 This variable defines the handling of virtual environments man‐
15514 aged by virtualenv or conda. It is meaningful only when a vir‐
15515 tual environment is active (i.e. the activate script has been
15516 evaluated). In this case, it takes precedence over
15517 Python3_FIND_REGISTRY and CMAKE_FIND_FRAMEWORK variables. The
15518 Python3_FIND_VIRTUALENV variable can be set to one of the fol‐
15519 lowing:
15520 · FIRST: The virtual environment is used before any other stan‐
15522 dard paths to look-up for the interpreter. This is the
15523 default.
15524 · ONLY: Only the virtual environment is used to look-up for the
15526 interpreter.
15527 · STANDARD: The virtual environment is not used to look-up for
15529 the interpreter but environment variable PATH is always con‐
15530 sidered. In this case, variable Python3_FIND_REGISTRY (Win‐
15531 dows) or CMAKE_FIND_FRAMEWORK (macOS) can be set with value
15532 LAST or NEVER to select preferably the interpreter from the
15533 virtual environment.
15534 NOTE:
15536 If the component Development is requested, it is strongly
15537 recommended to also include the component Interpreter to get
15538 expected result.
15539 Python3_FIND_IMPLEMENTATIONS
15541 This variable defines, in an ordered list, the different imple‐
15542 mentations which will be searched. The Python3_FIND_IMPLEMENTA‐
15543 TIONS variable can hold the following values:
15544 · CPython: this is the standard implementation. Various prod‐
15546 ucts, like Anaconda or ActivePython, rely on this implementa‐
15547 tion.
15548 · IronPython: This implementation use the CSharp language for
15550 .NET Framework on top of the Dynamic Language Runtime (DLR).
15551 See IronPython.
15552 · PyPy: This implementation use RPython language and RPython
15554 translation toolchain to produce the python interpreter. See
15555 PyPy.
15556 The default value is:
15558 · Windows platform: CPython, IronPython
15560 · Other platforms: CPython
15562 NOTE:
15564 This hint has the lowest priority of all hints, so even if,
15565 for example, you specify IronPython first and CPython in sec‐
15566 ond, a python product based on CPython can be selected
15567 because, for example with Python3_FIND_STRATEGY=LOCATION,
15568 each location will be search first for IronPython and second
15569 for CPython.
15570 NOTE:
15572 When IronPython is specified, on platforms other than Win‐
15573 dows, the .Net interpreter (i.e. mono command) is expected to
15574 be available through the PATH variable.
15575 Artifacts Specification
15577 To solve special cases, it is possible to specify directly the arti‐
15578 facts by setting the following variables:
15579 Python3_EXECUTABLE
15581 The path to the interpreter.
15582 Python3_COMPILER
15584 The path to the compiler.
15585 Python3_DOTNET_LAUNCHER
15587 The .Net interpreter. Only used by IronPython implementation.
15588 Python3_LIBRARY
15590 The path to the library. It will be used to compute the vari‐
15591 ables Python3_LIBRARIES, Python3_LIBRARY_DIRS and Python3_RUN‐
15592 TIME_LIBRARY_DIRS.
15593 Python3_INCLUDE_DIR
15595 The path to the directory of the Python headers. It will be used
15596 to compute the variable Python3_INCLUDE_DIRS.
15597 Python3_NumPy_INCLUDE_DIR
15599 The path to the directory of the NumPy headers. It will be used
15600 to compute the variable Python3_NumPy_INCLUDE_DIRS.
15601 NOTE:
15603 All paths must be absolute. Any artifact specified with a relative
15604 path will be ignored.
15605 NOTE:
15607 When an artifact is specified, all HINTS will be ignored and no
15608 search will be performed for this artifact.
15609 If more than one artifact is specified, it is the user’s responsi‐
15611 bility to ensure the consistency of the various artifacts.
15612 By default, this module supports multiple calls in different directo‐
15614 ries of a project with different version/component requirements while
15615 providing correct and consistent results for each call. To support this
15616 behavior, CMake cache is not used in the traditional way which can be
15617 problematic for interactive specification. So, to enable also interac‐
15618 tive specification, module behavior can be controlled with the follow‐
15619 ing variable:
15620 Python3_ARTIFACTS_INTERACTIVE
15622 Selects the behavior of the module. This is a boolean variable:
15623 · If set to TRUE: Create CMake cache entries for the above arti‐
15625 fact specification variables so that users can edit them
15626 interactively. This disables support for multiple ver‐
15627 sion/component requirements.
15628 · If set to FALSE or undefined: Enable multiple version/compo‐
15630 nent requirements.
15631 Commands
15633 This module defines the command Python3_add_library (when CMAKE_ROLE is
15634 PROJECT), which has the same semantics as add_library() and adds a
15635 dependency to target Python3::Python or, when library type is MODULE,
15636 to target Python3::Module and takes care of Python module naming rules:
15637 Python3_add_library (<name> [STATIC | SHARED | MODULE [WITH_SOABI]]
15639 <source1> [<source2> ...])
15640 If the library type is not specified, MODULE is assumed.
15642 For MODULE library type, if option WITH_SOABI is specified, the module
15644 suffix will include the Python3_SOABI value, if any.
15645 FindQt3
15647 Locate Qt include paths and libraries
15648 This module defines:
15650 QT_INCLUDE_DIR - where to find qt.h, etc.
15652 QT_LIBRARIES - the libraries to link against to use Qt.
15653 QT_DEFINITIONS - definitions to use when
15654 compiling code that uses Qt.
15655 QT_FOUND - If false, don't try to use Qt.
15656 QT_VERSION_STRING - the version of Qt found
15657 If you need the multithreaded version of Qt, set QT_MT_REQUIRED to TRUE
15659 Also defined, but not for general use are:
15661 QT_MOC_EXECUTABLE, where to find the moc tool.
15663 QT_UIC_EXECUTABLE, where to find the uic tool.
15664 QT_QT_LIBRARY, where to find the Qt library.
15665 QT_QTMAIN_LIBRARY, where to find the qtmain
15666 library. This is only required by Qt3 on Windows.
15667 FindQt4
15669 Finding and Using Qt4
15670 This module can be used to find Qt4. The most important issue is that
15671 the Qt4 qmake is available via the system path. This qmake is then
15672 used to detect basically everything else. This module defines a number
15673 of IMPORTED targets, macros and variables.
15674 Typical usage could be something like:
15676 set(CMAKE_AUTOMOC ON)
15678 set(CMAKE_INCLUDE_CURRENT_DIR ON)
15679 find_package(Qt4 4.4.3 REQUIRED QtGui QtXml)
15680 add_executable(myexe main.cpp)
15681 target_link_libraries(myexe Qt4::QtGui Qt4::QtXml)
15682 NOTE:
15684 When using IMPORTED targets, the qtmain.lib static library is auto‐
15685 matically linked on Windows for WIN32 executables. To disable that
15686 globally, set the QT4_NO_LINK_QTMAIN variable before finding Qt4. To
15687 disable that for a particular executable, set the QT4_NO_LINK_QTMAIN
15688 target property to TRUE on the executable.
15689 Qt Build Tools
15691 Qt relies on some bundled tools for code generation, such as moc for
15692 meta-object code generation,``uic`` for widget layout and population,
15693 and rcc for virtual filesystem content generation. These tools may be
15694 automatically invoked by cmake(1) if the appropriate conditions are
15695 met. See cmake-qt(7) for more.
15696 Qt Macros
15698 In some cases it can be necessary or useful to invoke the Qt build
15699 tools in a more-manual way. Several macros are available to add targets
15700 for such uses.
15701 macro QT4_WRAP_CPP(outfiles inputfile ... [TARGET tgt] OPTIONS ...)
15703 create moc code from a list of files containing Qt class with
15704 the Q_OBJECT declaration. Per-directory preprocessor definitions
15705 are also added. If the <tgt> is specified, the
15706 INTERFACE_INCLUDE_DIRECTORIES and INTERFACE_COMPILE_DEFINITIONS from
15707 the <tgt> are passed to moc. Options may be given to moc, such as
15708 those found when executing "moc -help".
15709 macro QT4_WRAP_UI(outfiles inputfile ... OPTIONS ...)
15711 create code from a list of Qt designer ui files.
15712 Options may be given to uic, such as those found
15713 when executing "uic -help"
15714 macro QT4_ADD_RESOURCES(outfiles inputfile ... OPTIONS ...)
15716 create code from a list of Qt resource files.
15717 Options may be given to rcc, such as those found
15718 when executing "rcc -help"
15719 macro QT4_GENERATE_MOC(inputfile outputfile [TARGET tgt])
15721 creates a rule to run moc on infile and create outfile.
15722 Use this if for some reason QT4_WRAP_CPP() isn't appropriate, e.g.
15723 because you need a custom filename for the moc file or something
15724 similar. If the <tgt> is specified, the
15725 INTERFACE_INCLUDE_DIRECTORIES and INTERFACE_COMPILE_DEFINITIONS from
15726 the <tgt> are passed to moc.
15727 macro QT4_ADD_DBUS_INTERFACE(outfiles interface basename)
15729 Create the interface header and implementation files with the
15730 given basename from the given interface xml file and add it to
15731 the list of sources.
15732 You can pass additional parameters to the qdbusxml2cpp call by setting
15734 properties on the input file:
15735 INCLUDE the given file will be included in the generate interface header
15737 CLASSNAME the generated class is named accordingly
15739 NO_NAMESPACE the generated class is not wrapped in a namespace
15741 macro QT4_ADD_DBUS_INTERFACES(outfiles inputfile ... )
15743 Create the interface header and implementation files
15744 for all listed interface xml files.
15745 The basename will be automatically determined from the name
15746 of the xml file.
15747 The source file properties described for
15749 QT4_ADD_DBUS_INTERFACE also apply here.
15750 macro QT4_ADD_DBUS_ADAPTOR(outfiles xmlfile parentheader parentclassname
15752 [basename] [classname])
15753 create a dbus adaptor (header and implementation file) from the xml file
15754 describing the interface, and add it to the list of sources. The adaptor
15755 forwards the calls to a parent class, defined in parentheader and named
15756 parentclassname. The name of the generated files will be
15757 <basename>adaptor.{cpp,h} where basename defaults to the basename of the
15758 xml file.
15759 If <classname> is provided, then it will be used as the classname of the
15760 adaptor itself.
15761 macro QT4_GENERATE_DBUS_INTERFACE( header [interfacename] OPTIONS ...)
15763 generate the xml interface file from the given header.
15764 If the optional argument interfacename is omitted, the name of the
15765 interface file is constructed from the basename of the header with
15766 the suffix .xml appended.
15767 Options may be given to qdbuscpp2xml, such as those found when
15768 executing "qdbuscpp2xml --help"
15769 macro QT4_CREATE_TRANSLATION( qm_files directories ... sources ...
15771 ts_files ... OPTIONS ...)
15772 out: qm_files
15773 in: directories sources ts_files
15774 options: flags to pass to lupdate, such as -extensions to specify
15775 extensions for a directory scan.
15776 generates commands to create .ts (via lupdate) and .qm
15777 (via lrelease) - files from directories and/or sources. The ts files are
15778 created and/or updated in the source tree (unless given with full paths).
15779 The qm files are generated in the build tree.
15780 Updating the translations can be done by adding the qm_files
15781 to the source list of your library/executable, so they are
15782 always updated, or by adding a custom target to control when
15783 they get updated/generated.
15784 macro QT4_ADD_TRANSLATION( qm_files ts_files ... )
15786 out: qm_files
15787 in: ts_files
15788 generates commands to create .qm from .ts - files. The generated
15789 filenames can be found in qm_files. The ts_files
15790 must exist and are not updated in any way.
15791 macro QT4_AUTOMOC(sourcefile1 sourcefile2 ... [TARGET tgt])
15793 The qt4_automoc macro is obsolete. Use the CMAKE_AUTOMOC feature instead.
15794 This macro is still experimental.
15795 It can be used to have moc automatically handled.
15796 So if you have the files foo.h and foo.cpp, and in foo.h a
15797 a class uses the Q_OBJECT macro, moc has to run on it. If you don't
15798 want to use QT4_WRAP_CPP() (which is reliable and mature), you can insert
15799 #include "foo.moc"
15800 in foo.cpp and then give foo.cpp as argument to QT4_AUTOMOC(). This will
15801 scan all listed files at cmake-time for such included moc files and if it
15802 finds them cause a rule to be generated to run moc at build time on the
15803 accompanying header file foo.h.
15804 If a source file has the SKIP_AUTOMOC property set it will be ignored by
15805 this macro.
15806 If the <tgt> is specified, the INTERFACE_INCLUDE_DIRECTORIES and
15807 INTERFACE_COMPILE_DEFINITIONS from the <tgt> are passed to moc.
15808 function QT4_USE_MODULES( target [link_type] modules...)
15810 This function is obsolete. Use target_link_libraries with IMPORTED targets
15811 instead.
15812 Make <target> use the <modules> from Qt. Using a Qt module means
15813 to link to the library, add the relevant include directories for the
15814 module, and add the relevant compiler defines for using the module.
15815 Modules are roughly equivalent to components of Qt4, so usage would be
15816 something like:
15817 qt4_use_modules(myexe Core Gui Declarative)
15818 to use QtCore, QtGui and QtDeclarative. The optional <link_type> argument
15819 can be specified as either LINK_PUBLIC or LINK_PRIVATE to specify the
15820 same argument to the target_link_libraries call.
15821 IMPORTED Targets
15823 A particular Qt library may be used by using the corresponding IMPORTED
15824 target with the target_link_libraries() command:
15825 target_link_libraries(myexe Qt4::QtGui Qt4::QtXml)
15827 Using a target in this way causes :cmake(1)` to use the appropriate
15829 include directories and compile definitions for the target when compil‐
15830 ing myexe.
15831 Targets are aware of their dependencies, so for example it is not nec‐
15833 essary to list Qt4::QtCore if another Qt library is listed, and it is
15834 not necessary to list Qt4::QtGui if Qt4::QtDeclarative is listed. Tar‐
15835 gets may be tested for existence in the usual way with the if(TARGET)
15836 command.
15837 The Qt toolkit may contain both debug and release libraries. cmake(1)
15839 will choose the appropriate version based on the build configuration.
15840 Qt4::QtCore
15842 The QtCore target
15843 Qt4::QtGui
15845 The QtGui target
15846 Qt4::Qt3Support
15848 The Qt3Support target
15849 Qt4::QtAssistant
15851 The QtAssistant target
15852 Qt4::QtAssistantClient
15854 The QtAssistantClient target
15855 Qt4::QAxContainer
15857 The QAxContainer target (Windows only)
15858 Qt4::QAxServer
15860 The QAxServer target (Windows only)
15861 Qt4::QtDBus
15863 The QtDBus target
15864 Qt4::QtDeclarative
15866 The QtDeclarative target
15867 Qt4::QtDesigner
15869 The QtDesigner target
15870 Qt4::QtDesignerComponents
15872 The QtDesignerComponents target
15873 Qt4::QtHelp
15875 The QtHelp target
15876 Qt4::QtMotif
15878 The QtMotif target
15879 Qt4::QtMultimedia
15881 The QtMultimedia target
15882 Qt4::QtNetwork
15884 The QtNetwork target
15885 Qt4::QtNsPLugin
15887 The QtNsPLugin target
15888 Qt4::QtOpenGL
15890 The QtOpenGL target
15891 Qt4::QtScript
15893 The QtScript target
15894 Qt4::QtScriptTools
15896 The QtScriptTools target
15897 Qt4::QtSql
15899 The QtSql target
15900 Qt4::QtSvg
15902 The QtSvg target
15903 Qt4::QtTest
15905 The QtTest target
15906 Qt4::QtUiTools
15908 The QtUiTools target
15909 Qt4::QtWebKit
15911 The QtWebKit target
15912 Qt4::QtXml
15914 The QtXml target
15915 Qt4::QtXmlPatterns
15917 The QtXmlPatterns target
15918 Qt4::phonon
15920 The phonon target
15921 Result Variables
15923 Below is a detailed list of variables that FindQt4.cmake sets.
15924 Qt4_FOUND
15926 If false, don’t try to use Qt 4.
15927 QT_FOUND
15929 If false, don’t try to use Qt. This variable is for compatibil‐
15930 ity only.
15931 QT4_FOUND
15933 If false, don’t try to use Qt 4. This variable is for compati‐
15934 bility only.
15935 QT_VERSION_MAJOR
15937 The major version of Qt found.
15938 QT_VERSION_MINOR
15940 The minor version of Qt found.
15941 QT_VERSION_PATCH
15943 The patch version of Qt found.
15944 FindQuickTime
15946 Locate QuickTime This module defines QUICKTIME_LIBRARY QUICKTIME_FOUND,
15947 if false, do not try to link to gdal QUICKTIME_INCLUDE_DIR, where to
15948 find the headers
15949 $QUICKTIME_DIR is an environment variable that would correspond to the
15951 ./configure –prefix=$QUICKTIME_DIR
15952 Created by Eric Wing.
15954 FindRTI
15956 Try to find M&S HLA RTI libraries
15957 This module finds if any HLA RTI is installed and locates the standard
15959 RTI include files and libraries.
15960 RTI is a simulation infrastructure standardized by IEEE and SISO. It
15962 has a well defined C++ API that assures that simulation applications
15963 are independent on a particular RTI implementation.
15964 http://en.wikipedia.org/wiki/Run-Time_Infrastructure_(simulation)
15966 This code sets the following variables:
15968 RTI_INCLUDE_DIR = the directory where RTI includes file are found
15970 RTI_LIBRARIES = The libraries to link against to use RTI
15971 RTI_DEFINITIONS = -DRTI_USES_STD_FSTREAM
15972 RTI_FOUND = Set to FALSE if any HLA RTI was not found
15973 Report problems to <certi-devel@nongnu.org>
15975 FindRuby
15977 Find Ruby
15978 This module finds if Ruby is installed and determines where the include
15980 files and libraries are. Ruby 1.8 through 2.7 are supported.
15981 The minimum required version of Ruby can be specified using the stan‐
15983 dard syntax, e.g.
15984 find_package(Ruby 2.5.1 EXACT REQUIRED)
15986 # OR
15987 find_package(Ruby 2.4)
15988 It also determines what the name of the library is.
15990 Virtual environments such as RVM are handled as well, by passing the
15992 argument Ruby_FIND_VIRTUALENV
15993 Result Variables
15995 This module will set the following variables in your project:
15996 Ruby_FOUND
15998 set to true if ruby was found successfully
15999 Ruby_EXECUTABLE
16001 full path to the ruby binary
16002 Ruby_INCLUDE_DIRS
16004 include dirs to be used when using the ruby library
16005 Ruby_LIBRARIES
16007 libraries needed to use ruby from C.
16008 Ruby_VERSION
16010 the version of ruby which was found, e.g. “1.8.7”
16011 Ruby_VERSION_MAJOR
16013 Ruby major version.
16014 Ruby_VERSION_MINOR
16016 Ruby minor version.
16017 Ruby_VERSION_PATCH
16019 Ruby patch version.
16020 The following variables are also provided for compatibility reasons,
16022 don’t use them in new code:
16023 RUBY_EXECUTABLE
16025 same as Ruby_EXECUTABLE.
16026 RUBY_INCLUDE_DIRS
16028 same as Ruby_INCLUDE_DIRS.
16029 RUBY_INCLUDE_PATH
16031 same as Ruby_INCLUDE_DIRS.
16032 RUBY_LIBRARY
16034 same as Ruby_LIBRARY.
16035 RUBY_VERSION
16037 same as Ruby_VERSION.
16038 RUBY_FOUND
16040 same as Ruby_FOUND.
16041 Hints
16043 Ruby_ROOT_DIR
16044 Define the root directory of a Ruby installation.
16045 Ruby_FIND_VIRTUALENV
16047 This variable defines the handling of virtual environments man‐
16048 aged by rvm. It is meaningful only when a virtual environment is
16049 active (i.e. the rvm script has been evaluated or at least the
16050 MY_RUBY_HOME environment variable is set). The Ruby_FIND_VIR‐
16051 TUALENV variable can be set to empty or one of the following:
16052 · FIRST: The virtual environment is used before any other stan‐
16054 dard paths to look-up for the interpreter. This is the
16055 default.
16056 · ONLY: Only the virtual environment is used to look-up for the
16058 interpreter.
16059 · STANDARD: The virtual environment is not used to look-up for
16061 the interpreter (assuming it isn’t still in the PATH…)
16062 FindSDL
16064 Locate the SDL library
16065 Imported targets
16067 This module defines the following IMPORTED target:
16068 SDL::SDL
16070 The SDL library, if found
16071 Result variables
16073 This module will set the following variables in your project:
16074 SDL_INCLUDE_DIRS
16076 where to find SDL.h
16077 SDL_LIBRARIES
16079 the name of the library to link against
16080 SDL_FOUND
16082 if false, do not try to link to SDL
16083 SDL_VERSION
16085 the human-readable string containing the version of SDL if found
16086 SDL_VERSION_MAJOR
16088 SDL major version
16089 SDL_VERSION_MINOR
16091 SDL minor version
16092 SDL_VERSION_PATCH
16094 SDL patch version
16095 Cache variables
16097 These variables may optionally be set to help this module find the cor‐
16098 rect files:
16099 SDL_INCLUDE_DIR
16101 where to find SDL.h
16102 SDL_LIBRARY
16104 the name of the library to link against
16105 Variables for locating SDL
16107 This module responds to the flag:
16108 SDL_BUILDING_LIBRARY
16110 If this is defined, then no SDL_main will be linked in because
16111 only applications need main(). Otherwise, it is assumed you are
16112 building an application and this module will attempt to locate
16113 and set the proper link flags as part of the returned
16114 SDL_LIBRARY variable.
16115 Obsolete variables
16117 These variables are obsolete and provided for backwards compatibility:
16118 SDL_VERSION_STRING
16120 the human-readable string containing the version of SDL if
16121 found. Identical to SDL_VERSION
16122 Don’t forget to include SDLmain.h and SDLmain.m your project for the OS
16124 X framework based version. (Other versions link to -lSDLmain which
16125 this module will try to find on your behalf.) Also for OS X, this mod‐
16126 ule will automatically add the -framework Cocoa on your behalf.
16127 Additional Note: If you see an empty SDL_LIBRARY_TEMP in your configu‐
16129 ration and no SDL_LIBRARY, it means CMake did not find your SDL library
16130 (SDL.dll, libsdl.so, SDL.framework, etc). Set SDL_LIBRARY_TEMP to
16131 point to your SDL library, and configure again. Similarly, if you see
16132 an empty SDLMAIN_LIBRARY, you should set this value as appropriate.
16133 These values are used to generate the final SDL_LIBRARY variable, but
16134 when these values are unset, SDL_LIBRARY does not get created.
16135 $SDLDIR is an environment variable that would correspond to the ./con‐
16137 figure –prefix=$SDLDIR used in building SDL. l.e.galup 9-20-02
16138 On OSX, this will prefer the Framework version (if found) over others.
16140 People will have to manually change the cache values of SDL_LIBRARY to
16141 override this selection or set the CMake environment CMAKE_INCLUDE_PATH
16142 to modify the search paths.
16143 Note that the header path has changed from SDL/SDL.h to just SDL.h This
16145 needed to change because “proper” SDL convention is #include “SDL.h”,
16146 not <SDL/SDL.h>. This is done for portability reasons because not all
16147 systems place things in SDL/ (see FreeBSD).
16148 FindSDL_image
16150 Locate SDL_image library
16151 This module defines:
16153 SDL_IMAGE_LIBRARIES, the name of the library to link against
16155 SDL_IMAGE_INCLUDE_DIRS, where to find the headers
16156 SDL_IMAGE_FOUND, if false, do not try to link against
16157 SDL_IMAGE_VERSION_STRING - human-readable string containing the
16158 version of SDL_image
16159 For backward compatibility the following variables are also set:
16161 SDLIMAGE_LIBRARY (same value as SDL_IMAGE_LIBRARIES)
16163 SDLIMAGE_INCLUDE_DIR (same value as SDL_IMAGE_INCLUDE_DIRS)
16164 SDLIMAGE_FOUND (same value as SDL_IMAGE_FOUND)
16165 $SDLDIR is an environment variable that would correspond to the ./con‐
16167 figure –prefix=$SDLDIR used in building SDL.
16168 Created by Eric Wing. This was influenced by the FindSDL.cmake module,
16170 but with modifications to recognize OS X frameworks and additional Unix
16171 paths (FreeBSD, etc).
16172 FindSDL_mixer
16174 Locate SDL_mixer library
16175 This module defines:
16177 SDL_MIXER_LIBRARIES, the name of the library to link against
16179 SDL_MIXER_INCLUDE_DIRS, where to find the headers
16180 SDL_MIXER_FOUND, if false, do not try to link against
16181 SDL_MIXER_VERSION_STRING - human-readable string containing the
16182 version of SDL_mixer
16183 For backward compatibility the following variables are also set:
16185 SDLMIXER_LIBRARY (same value as SDL_MIXER_LIBRARIES)
16187 SDLMIXER_INCLUDE_DIR (same value as SDL_MIXER_INCLUDE_DIRS)
16188 SDLMIXER_FOUND (same value as SDL_MIXER_FOUND)
16189 $SDLDIR is an environment variable that would correspond to the ./con‐
16191 figure –prefix=$SDLDIR used in building SDL.
16192 Created by Eric Wing. This was influenced by the FindSDL.cmake module,
16194 but with modifications to recognize OS X frameworks and additional Unix
16195 paths (FreeBSD, etc).
16196 FindSDL_net
16198 Locate SDL_net library
16199 This module defines:
16201 SDL_NET_LIBRARIES, the name of the library to link against
16203 SDL_NET_INCLUDE_DIRS, where to find the headers
16204 SDL_NET_FOUND, if false, do not try to link against
16205 SDL_NET_VERSION_STRING - human-readable string containing the version of SDL_net
16206 For backward compatibility the following variables are also set:
16208 SDLNET_LIBRARY (same value as SDL_NET_LIBRARIES)
16210 SDLNET_INCLUDE_DIR (same value as SDL_NET_INCLUDE_DIRS)
16211 SDLNET_FOUND (same value as SDL_NET_FOUND)
16212 $SDLDIR is an environment variable that would correspond to the ./con‐
16214 figure –prefix=$SDLDIR used in building SDL.
16215 Created by Eric Wing. This was influenced by the FindSDL.cmake module,
16217 but with modifications to recognize OS X frameworks and additional Unix
16218 paths (FreeBSD, etc).
16219 FindSDL_sound
16221 Locates the SDL_sound library
16222 This module depends on SDL being found and must be called AFTER Find‐
16224 SDL.cmake is called.
16225 This module defines
16227 SDL_SOUND_INCLUDE_DIR, where to find SDL_sound.h
16229 SDL_SOUND_FOUND, if false, do not try to link to SDL_sound
16230 SDL_SOUND_LIBRARIES, this contains the list of libraries that you need
16231 to link against.
16232 SDL_SOUND_EXTRAS, this is an optional variable for you to add your own
16233 flags to SDL_SOUND_LIBRARIES. This is prepended to SDL_SOUND_LIBRARIES.
16234 This is available mostly for cases this module failed to anticipate for
16235 and you must add additional flags. This is marked as ADVANCED.
16236 SDL_SOUND_VERSION_STRING, human-readable string containing the
16237 version of SDL_sound
16238 This module also defines (but you shouldn’t need to use directly)
16240 SDL_SOUND_LIBRARY, the name of just the SDL_sound library you would link
16242 against. Use SDL_SOUND_LIBRARIES for you link instructions and not this one.
16243 And might define the following as needed
16245 MIKMOD_LIBRARY
16247 MODPLUG_LIBRARY
16248 OGG_LIBRARY
16249 VORBIS_LIBRARY
16250 SMPEG_LIBRARY
16251 FLAC_LIBRARY
16252 SPEEX_LIBRARY
16253 Typically, you should not use these variables directly, and you should
16255 use SDL_SOUND_LIBRARIES which contains SDL_SOUND_LIBRARY and the other
16256 audio libraries (if needed) to successfully compile on your system.
16257 Created by Eric Wing. This module is a bit more complicated than the
16259 other FindSDL* family modules. The reason is that SDL_sound can be
16260 compiled in a large variety of different ways which are independent of
16261 platform. SDL_sound may dynamically link against other 3rd party
16262 libraries to get additional codec support, such as Ogg Vorbis, SMPEG,
16263 ModPlug, MikMod, FLAC, Speex, and potentially others. Under some cir‐
16264 cumstances which I don’t fully understand, there seems to be a require‐
16265 ment that dependent libraries of libraries you use must also be explic‐
16266 itly linked against in order to successfully compile. SDL_sound does
16267 not currently have any system in place to know how it was compiled. So
16268 this CMake module does the hard work in trying to discover which 3rd
16269 party libraries are required for building (if any). This module uses a
16270 brute force approach to create a test program that uses SDL_sound, and
16271 then tries to build it. If the build fails, it parses the error output
16272 for known symbol names to figure out which libraries are needed.
16273 Responds to the $SDLDIR and $SDLSOUNDDIR environmental variable that
16275 would correspond to the ./configure –prefix=$SDLDIR used in building
16276 SDL.
16277 On OSX, this will prefer the Framework version (if found) over others.
16279 People will have to manually change the cache values of SDL_LIBRARY to
16280 override this selectionor set the CMake environment CMAKE_INCLUDE_PATH
16281 to modify the search paths.
16282 FindSDL_ttf
16284 Locate SDL_ttf library
16285 This module defines:
16287 SDL_TTF_LIBRARIES, the name of the library to link against
16289 SDL_TTF_INCLUDE_DIRS, where to find the headers
16290 SDL_TTF_FOUND, if false, do not try to link against
16291 SDL_TTF_VERSION_STRING - human-readable string containing the version of SDL_ttf
16292 For backward compatibility the following variables are also set:
16294 SDLTTF_LIBRARY (same value as SDL_TTF_LIBRARIES)
16296 SDLTTF_INCLUDE_DIR (same value as SDL_TTF_INCLUDE_DIRS)
16297 SDLTTF_FOUND (same value as SDL_TTF_FOUND)
16298 $SDLDIR is an environment variable that would correspond to the ./con‐
16300 figure –prefix=$SDLDIR used in building SDL.
16301 Created by Eric Wing. This was influenced by the FindSDL.cmake module,
16303 but with modifications to recognize OS X frameworks and additional Unix
16304 paths (FreeBSD, etc).
16305 FindSelfPackers
16307 Find upx
16308 This module looks for some executable packers (i.e. software that com‐
16310 press executables or shared libs into on-the-fly self-extracting exe‐
16311 cutables or shared libs. Examples:
16312 UPX: http://wildsau.idv.uni-linz.ac.at/mfx/upx.html
16314 FindSquish
16316 – Typical Use
16317 This module can be used to find Squish.
16319 SQUISH_FOUND If false, don't try to use Squish
16321 SQUISH_VERSION The full version of Squish found
16322 SQUISH_VERSION_MAJOR The major version of Squish found
16323 SQUISH_VERSION_MINOR The minor version of Squish found
16324 SQUISH_VERSION_PATCH The patch version of Squish found
16325 SQUISH_INSTALL_DIR The Squish installation directory
16327 (containing bin, lib, etc)
16328 SQUISH_SERVER_EXECUTABLE The squishserver executable
16329 SQUISH_CLIENT_EXECUTABLE The squishrunner executable
16330 SQUISH_INSTALL_DIR_FOUND Was the install directory found?
16332 SQUISH_SERVER_EXECUTABLE_FOUND Was the server executable found?
16333 SQUISH_CLIENT_EXECUTABLE_FOUND Was the client executable found?
16334 It provides the function squish_add_test() for adding a squish test to
16336 cmake using Squish >= 4.x:
16337 squish_add_test(cmakeTestName
16339 AUT targetName SUITE suiteName TEST squishTestName
16340 [SETTINGSGROUP group] [PRE_COMMAND command] [POST_COMMAND command] )
16341 The arguments have the following meaning:
16343 cmakeTestName
16345 this will be used as the first argument for add_test()
16346 AUT targetName
16348 the name of the cmake target which will be used as AUT, i.e. the
16349 executable which will be tested.
16350 SUITE suiteName
16352 this is either the full path to the squish suite, or just the
16353 last directory of the suite, i.e. the suite name. In this case
16354 the CMakeLists.txt which calls squish_add_test() must be located
16355 in the parent directory of the suite directory.
16356 TEST squishTestName
16358 the name of the squish test, i.e. the name of the subdirectory
16359 of the test inside the suite directory.
16360 SETTINGSGROUP group
16362 deprecated, this argument will be ignored.
16363 PRE_COMMAND command
16365 if specified, the given command will be executed before starting
16366 the squish test.
16367 POST_COMMAND command
16369 same as PRE_COMMAND, but after the squish test has been exe‐
16370 cuted.
16371 enable_testing()
16373 find_package(Squish 6.5)
16374 if (SQUISH_FOUND)
16375 squish_add_test(myTestName
16376 AUT myApp
16377 SUITE ${CMAKE_SOURCE_DIR}/tests/mySuite
16378 TEST someSquishTest
16379 )
16380 endif ()
16381 For users of Squish version 3.x the macro squish_v3_add_test() is pro‐
16383 vided:
16384 squish_v3_add_test(testName applicationUnderTest testCase envVars testWrapper)
16386 Use this macro to add a test using Squish 3.x.
16387 enable_testing()
16389 find_package(Squish 3.0)
16390 if (SQUISH_FOUND)
16391 squish_v3_add_test(myTestName myApplication testCase envVars testWrapper)
16392 endif ()
16393 FindSQLite3
16395 New in version 3.14.
16396 Find the SQLite libraries, v3
16399 IMPORTED targets
16401 This module defines the following IMPORTED target:
16402 SQLite::SQLite3
16404 Result variables
16406 This module will set the following variables if found:
16407 SQLite3_INCLUDE_DIRS
16409 where to find sqlite3.h, etc.
16410 SQLite3_LIBRARIES
16412 the libraries to link against to use SQLite3.
16413 SQLite3_VERSION
16415 version of the SQLite3 library found
16416 SQLite3_FOUND
16418 TRUE if found
16419 FindSubversion
16421 Extract information from a subversion working copy
16422 The module defines the following variables:
16424 Subversion_SVN_EXECUTABLE - path to svn command line client
16426 Subversion_VERSION_SVN - version of svn command line client
16427 Subversion_FOUND - true if the command line client was found
16428 SUBVERSION_FOUND - same as Subversion_FOUND, set for compatibility reasons
16429 The minimum required version of Subversion can be specified using the
16431 standard syntax, e.g. find_package(Subversion 1.4).
16432 If the command line client executable is found two macros are defined:
16434 Subversion_WC_INFO(<dir> <var-prefix> [IGNORE_SVN_FAILURE])
16436 Subversion_WC_LOG(<dir> <var-prefix>)
16437 Subversion_WC_INFO extracts information of a subversion working copy at
16439 a given location. This macro defines the following variables if run‐
16440 ning Subversion’s info command on <dir> succeeds; otherwise a
16441 SEND_ERROR message is generated. The error can be ignored by providing
16442 the IGNORE_SVN_FAILURE option, which causes these variables to remain
16443 undefined.
16444 <var-prefix>_WC_URL - url of the repository (at <dir>)
16446 <var-prefix>_WC_ROOT - root url of the repository
16447 <var-prefix>_WC_REVISION - current revision
16448 <var-prefix>_WC_LAST_CHANGED_AUTHOR - author of last commit
16449 <var-prefix>_WC_LAST_CHANGED_DATE - date of last commit
16450 <var-prefix>_WC_LAST_CHANGED_REV - revision of last commit
16451 <var-prefix>_WC_INFO - output of command `svn info <dir>'
16452 Subversion_WC_LOG retrieves the log message of the base revision of a
16454 subversion working copy at a given location. This macro defines the
16455 variable:
16456 <var-prefix>_LAST_CHANGED_LOG - last log of base revision
16458 Example usage:
16460 find_package(Subversion)
16462 if(SUBVERSION_FOUND)
16463 Subversion_WC_INFO(${PROJECT_SOURCE_DIR} Project)
16464 message("Current revision is ${Project_WC_REVISION}")
16465 Subversion_WC_LOG(${PROJECT_SOURCE_DIR} Project)
16466 message("Last changed log is ${Project_LAST_CHANGED_LOG}")
16467 endif()
16468 FindSWIG
16470 Find the Simplified Wrapper and Interface Generator (SWIG) executable.
16471 This module finds an installed SWIG and determines its version. If a
16473 COMPONENTS or OPTIONAL_COMPONENTS argument is given to the find_pack‐
16474 age() command, it will also determine supported target languages.
16475 When a version is requested, it can be specified as a simple value or
16477 as a range. For a detailed description of version range usage and capa‐
16478 bilities, refer to the find_package() command.
16479 The module defines the following variables:
16481 SWIG_FOUND
16483 Whether SWIG and any required components were found on the sys‐
16484 tem.
16485 SWIG_EXECUTABLE
16487 Path to the SWIG executable.
16488 SWIG_DIR
16490 Path to the installed SWIG Lib directory (result of swig
16491 -swiglib).
16492 SWIG_VERSION
16494 SWIG executable version (result of swig -version).
16495 SWIG_<lang>_FOUND
16497 If COMPONENTS or OPTIONAL_COMPONENTS are requested, each avail‐
16498 able target language <lang> (lowercase) will be set to TRUE.
16499 Any COMPONENTS given to find_package should be the names of supported
16501 target languages as provided to the LANGUAGE argument of
16502 swig_add_library, such as python or perl5. Language names must be low‐
16503 ercase.
16504 All information is collected from the SWIG_EXECUTABLE, so the version
16506 to be found can be changed from the command line by means of setting
16507 SWIG_EXECUTABLE.
16508 Example usage requiring SWIG 4.0 or higher and Python language support,
16510 with optional Fortran support:
16511 find_package(SWIG 4.0 COMPONENTS python OPTIONAL_COMPONENTS fortran)
16513 if(SWIG_FOUND)
16514 message("SWIG found: ${SWIG_EXECUTABLE}")
16515 if(NOT SWIG_fortran_FOUND)
16516 message(WARNING "SWIG Fortran bindings cannot be generated")
16517 endif()
16518 endif()
16519 FindTCL
16521 TK_INTERNAL_PATH was removed.
16522 This module finds if Tcl is installed and determines where the include
16524 files and libraries are. It also determines what the name of the
16525 library is. This code sets the following variables:
16526 TCL_FOUND = Tcl was found
16528 TK_FOUND = Tk was found
16529 TCLTK_FOUND = Tcl and Tk were found
16530 TCL_LIBRARY = path to Tcl library (tcl tcl80)
16531 TCL_INCLUDE_PATH = path to where tcl.h can be found
16532 TCL_TCLSH = path to tclsh binary (tcl tcl80)
16533 TK_LIBRARY = path to Tk library (tk tk80 etc)
16534 TK_INCLUDE_PATH = path to where tk.h can be found
16535 TK_WISH = full path to the wish executable
16536 In an effort to remove some clutter and clear up some issues for people
16538 who are not necessarily Tcl/Tk gurus/developers, some variables were
16539 moved or removed. Changes compared to CMake 2.4 are:
16540 => they were only useful for people writing Tcl/Tk extensions.
16542 => these libs are not packaged by default with Tcl/Tk distributions.
16543 Even when Tcl/Tk is built from source, several flavors of debug libs
16544 are created and there is no real reason to pick a single one
16545 specifically (say, amongst tcl84g, tcl84gs, or tcl84sgx).
16546 Let's leave that choice to the user by allowing him to assign
16547 TCL_LIBRARY to any Tcl library, debug or not.
16548 => this ended up being only a Win32 variable, and there is a lot of
16549 confusion regarding the location of this file in an installed Tcl/Tk
16550 tree anyway (see 8.5 for example). If you need the internal path at
16551 this point it is safer you ask directly where the *source* tree is
16552 and dig from there.
16553 FindTclsh
16555 Find tclsh
16556 This module finds if TCL is installed and determines where the include
16558 files and libraries are. It also determines what the name of the
16559 library is. This code sets the following variables:
16560 TCLSH_FOUND = TRUE if tclsh has been found
16562 TCL_TCLSH = the path to the tclsh executable
16563 FindTclStub
16565 TCL_STUB_LIBRARY_DEBUG and TK_STUB_LIBRARY_DEBUG were removed.
16566 This module finds Tcl stub libraries. It first finds Tcl include files
16568 and libraries by calling FindTCL.cmake. How to Use the Tcl Stubs
16569 Library:
16570 http://tcl.activestate.com/doc/howto/stubs.html
16572 Using Stub Libraries:
16574 http://safari.oreilly.com/0130385603/ch48lev1sec3
16576 This code sets the following variables:
16578 TCL_STUB_LIBRARY = path to Tcl stub library
16580 TK_STUB_LIBRARY = path to Tk stub library
16581 TTK_STUB_LIBRARY = path to ttk stub library
16582 In an effort to remove some clutter and clear up some issues for people
16584 who are not necessarily Tcl/Tk gurus/developers, some variables were
16585 moved or removed. Changes compared to CMake 2.4 are:
16586 => these libs are not packaged by default with Tcl/Tk distributions.
16588 Even when Tcl/Tk is built from source, several flavors of debug libs
16589 are created and there is no real reason to pick a single one
16590 specifically (say, amongst tclstub84g, tclstub84gs, or tclstub84sgx).
16591 Let's leave that choice to the user by allowing him to assign
16592 TCL_STUB_LIBRARY to any Tcl library, debug or not.
16593 FindThreads
16595 This module determines the thread library of the system.
16596 Imported Targets
16598 This module defines the following IMPORTED target:
16599 Threads::Threads
16601 The thread library, if found.
16602 Result Variables
16604 The following variables are set:
16605 Threads_FOUND
16607 If a supported thread library was found.
16608 CMAKE_THREAD_LIBS_INIT
16610 The thread library to use. This may be empty if the thread func‐
16611 tions are provided by the system libraries and no special flags
16612 are needed to use them.
16613 CMAKE_USE_WIN32_THREADS_INIT
16615 If the found thread library is the win32 one.
16616 CMAKE_USE_PTHREADS_INIT
16618 If the found thread library is pthread compatible.
16619 CMAKE_HP_PTHREADS_INIT
16621 If the found thread library is the HP thread library.
16622 Variables Affecting Behavior
16624 THREADS_PREFER_PTHREAD_FLAG
16625 If the use of the -pthread compiler and linker flag is preferred
16626 then the caller can set this variable to TRUE. The compiler flag
16627 can only be used with the imported target. Use of both the
16628 imported target as well as this switch is highly recommended for
16629 new code.
16630 This variable has no effect if the system libraries provide the
16632 thread functions, i.e. when CMAKE_THREAD_LIBS_INIT will be
16633 empty.
16634 FindTIFF
16636 Find the TIFF library (libtiff, https://libtiff.gitlab.io/libtiff/).
16637 Optional COMPONENTS
16639 This module supports the optional component CXX, for use with the COM‐
16640 PONENTS argument of the find_package() command. This component has an
16641 associated imported target, as described below.
16642 Imported targets
16644 This module defines the following IMPORTED targets:
16645 TIFF::TIFF
16647 The TIFF library, if found.
16648 TIFF::CXX
16650 The C++ wrapper libtiffxx, if requested by the COMPONENTS CXX
16651 option, if the compiler is not MSVC (which includes the C++
16652 wrapper in libtiff), and if found.
16653 Result variables
16655 This module will set the following variables in your project:
16656 TIFF_FOUND
16658 true if the TIFF headers and libraries were found
16659 TIFF_INCLUDE_DIR
16661 the directory containing the TIFF headers
16662 TIFF_INCLUDE_DIRS
16664 the directory containing the TIFF headers
16665 TIFF_LIBRARIES
16667 TIFF libraries to be linked
16668 Cache variables
16670 The following cache variables may also be set:
16671 TIFF_INCLUDE_DIR
16673 the directory containing the TIFF headers
16674 TIFF_LIBRARY_RELEASE
16676 the path to the TIFF library for release configurations
16677 TIFF_LIBRARY_DEBUG
16679 the path to the TIFF library for debug configurations
16680 TIFFXX_LIBRARY_RELEASE
16682 the path to the TIFFXX library for release configurations
16683 TIFFXX_LIBRARY_DEBUG
16685 the path to the TIFFXX library for debug configurations
16686 FindUnixCommands
16688 Find Unix commands, including the ones from Cygwin
16689 This module looks for the Unix commands bash, cp, gzip, mv, rm, and tar
16691 and stores the result in the variables BASH, CP, GZIP, MV, RM, and TAR.
16692 FindVTK
16694 This module no longer exists.
16695 This module existed in versions of CMake prior to 3.1, but became only
16697 a thin wrapper around find_package(VTK NO_MODULE) to provide compati‐
16698 bility for projects using long-outdated conventions. Now find_pack‐
16699 age(VTK) will search for VTKConfig.cmake directly.
16700 FindVulkan
16702 New in version 3.7.
16703 Find Vulkan, which is a low-overhead, cross-platform 3D graphics and
16706 computing API.
16707 IMPORTED Targets
16709 This module defines IMPORTED target Vulkan::Vulkan, if Vulkan has been
16710 found.
16711 This module defines IMPORTED target Vulkan::glslc, if Vulkan and the
16713 GLSLC SPIR-V compiler has been found.
16714 Result Variables
16716 This module defines the following variables:
16717 Vulkan_FOUND - "True" if Vulkan was found
16719 Vulkan_INCLUDE_DIRS - include directories for Vulkan
16720 Vulkan_LIBRARIES - link against this library to use Vulkan
16721 The module will also define three cache variables:
16723 Vulkan_INCLUDE_DIR - the Vulkan include directory
16725 Vulkan_LIBRARY - the path to the Vulkan library
16726 Vulkan_GLSLC_EXECUTABLE - the path to the GLSL SPIR-V compiler
16727 Hints
16729 The VULKAN_SDK environment variable optionally specifies the location
16730 of the Vulkan SDK root directory for the given architecture. It is typ‐
16731 ically set by sourcing the toplevel setup-env.sh script of the Vulkan
16732 SDK directory into the shell environment.
16733 FindWget
16735 Find wget
16736 This module looks for wget. This module defines the following values:
16738 WGET_EXECUTABLE: the full path to the wget tool.
16740 WGET_FOUND: True if wget has been found.
16741 FindWish
16743 Find wish installation
16744 This module finds if TCL is installed and determines where the include
16746 files and libraries are. It also determines what the name of the
16747 library is. This code sets the following variables:
16748 TK_WISH = the path to the wish executable
16750 if UNIX is defined, then it will look for the cygwin version first
16752 FindwxWidgets
16754 Find a wxWidgets (a.k.a., wxWindows) installation.
16755 This module finds if wxWidgets is installed and selects a default con‐
16757 figuration to use. wxWidgets is a modular library. To specify the
16758 modules that you will use, you need to name them as components to the
16759 package:
16760 find_package(wxWidgets COMPONENTS core base … OPTIONAL_COMPONENTS net
16762 …)
16763 There are two search branches: a windows style and a unix style. For
16765 windows, the following variables are searched for and set to defaults
16766 in case of multiple choices. Change them if the defaults are not
16767 desired (i.e., these are the only variables you should change to select
16768 a configuration):
16769 wxWidgets_ROOT_DIR - Base wxWidgets directory
16771 (e.g., C:/wxWidgets-2.6.3).
16772 wxWidgets_LIB_DIR - Path to wxWidgets libraries
16773 (e.g., C:/wxWidgets-2.6.3/lib/vc_lib).
16774 wxWidgets_CONFIGURATION - Configuration to use
16775 (e.g., msw, mswd, mswu, mswunivud, etc.)
16776 wxWidgets_EXCLUDE_COMMON_LIBRARIES
16777 - Set to TRUE to exclude linking of
16778 commonly required libs (e.g., png tiff
16779 jpeg zlib regex expat).
16780 For unix style it uses the wx-config utility. You can select between
16782 debug/release, unicode/ansi, universal/non-universal, and static/shared
16783 in the QtDialog or ccmake interfaces by turning ON/OFF the following
16784 variables:
16785 wxWidgets_USE_DEBUG
16787 wxWidgets_USE_UNICODE
16788 wxWidgets_USE_UNIVERSAL
16789 wxWidgets_USE_STATIC
16790 There is also a wxWidgets_CONFIG_OPTIONS variable for all other options
16792 that need to be passed to the wx-config utility. For example, to use
16793 the base toolkit found in the /usr/local path, set the variable (before
16794 calling the FIND_PACKAGE command) as such:
16795 set(wxWidgets_CONFIG_OPTIONS --toolkit=base --prefix=/usr)
16797 The following are set after the configuration is done for both windows
16799 and unix style:
16800 wxWidgets_FOUND - Set to TRUE if wxWidgets was found.
16802 wxWidgets_INCLUDE_DIRS - Include directories for WIN32
16803 i.e., where to find "wx/wx.h" and
16804 "wx/setup.h"; possibly empty for unices.
16805 wxWidgets_LIBRARIES - Path to the wxWidgets libraries.
16806 wxWidgets_LIBRARY_DIRS - compile time link dirs, useful for
16807 rpath on UNIX. Typically an empty string
16808 in WIN32 environment.
16809 wxWidgets_DEFINITIONS - Contains defines required to compile/link
16810 against WX, e.g. WXUSINGDLL
16811 wxWidgets_DEFINITIONS_DEBUG- Contains defines required to compile/link
16812 against WX debug builds, e.g. __WXDEBUG__
16813 wxWidgets_CXX_FLAGS - Include dirs and compiler flags for
16814 unices, empty on WIN32. Essentially
16815 "`wx-config --cxxflags`".
16816 wxWidgets_USE_FILE - Convenience include file.
16817 Sample usage:
16819 # Note that for MinGW users the order of libs is important!
16821 find_package(wxWidgets COMPONENTS gl core base OPTIONAL_COMPONENTS net)
16822 if(wxWidgets_FOUND)
16823 include(${wxWidgets_USE_FILE})
16824 # and for each of your dependent executable/library targets:
16825 target_link_libraries(<YourTarget> ${wxWidgets_LIBRARIES})
16826 endif()
16827 If wxWidgets is required (i.e., not an optional part):
16829 find_package(wxWidgets REQUIRED gl core base OPTIONAL_COMPONENTS net)
16831 include(${wxWidgets_USE_FILE})
16832 # and for each of your dependent executable/library targets:
16833 target_link_libraries(<YourTarget> ${wxWidgets_LIBRARIES})
16834 FindX11
16836 Find X11 installation
16837 Try to find X11 on UNIX systems. The following values are defined
16839 X11_FOUND - True if X11 is available
16841 X11_INCLUDE_DIR - include directories to use X11
16842 X11_LIBRARIES - link against these to use X11
16843 and also the following more fine grained variables and targets:
16845 X11_ICE_INCLUDE_PATH, X11_ICE_LIB, X11_ICE_FOUND, X11::ICE
16847 X11_SM_INCLUDE_PATH, X11_SM_LIB, X11_SM_FOUND, X11::SM
16848 X11_X11_INCLUDE_PATH, X11_X11_LIB, X11::X11
16849 X11_Xaccessrules_INCLUDE_PATH,
16850 X11_Xaccessstr_INCLUDE_PATH, X11_Xaccess_FOUND
16851 X11_Xau_INCLUDE_PATH, X11_Xau_LIB, X11_Xau_FOUND, X11::Xau
16852 X11_xcb_INCLUDE_PATH, X11_xcb_LIB, X11_xcb_FOUND, X11::xcb
16853 X11_X11_xcb_INCLUDE_PATH, X11_X11_xcb_LIB, X11_X11_xcb_FOUND, X11::X11_xcb
16854 X11_xcb_icccm_INCLUDE_PATH, X11_xcb_icccm_LIB, X11_xcb_icccm_FOUND, X11::xcb_icccm
16855 X11_xcb_util_INCLUDE_PATH, X11_xcb_util_LIB, X11_xcb_util_FOUND, X11::xcb_util
16856 X11_xcb_xfixes_INCLUDE_PATH, X11_xcb_xfixes_LIB, X11_xcb_xfixes_FOUND, X11::xcb_xfixes
16857 X11_xcb_xkb_INCLUDE_PATH, X11_xcb_xkb_LIB, X11_xcb_xkb_FOUND, X11::xcb_xkb
16858 X11_Xcomposite_INCLUDE_PATH, X11_Xcomposite_LIB, X11_Xcomposite_FOUND, X11::Xcomposite
16859 X11_Xcursor_INCLUDE_PATH, X11_Xcursor_LIB, X11_Xcursor_FOUND, X11::Xcursor
16860 X11_Xdamage_INCLUDE_PATH, X11_Xdamage_LIB, X11_Xdamage_FOUND, X11::Xdamage
16861 X11_Xdmcp_INCLUDE_PATH, X11_Xdmcp_LIB, X11_Xdmcp_FOUND, X11::Xdmcp
16862 X11_Xext_INCLUDE_PATH, X11_Xext_LIB, X11_Xext_FOUND, X11::Xext
16863 X11_Xxf86misc_INCLUDE_PATH, X11_Xxf86misc_LIB, X11_Xxf86misc_FOUND, X11::Xxf86misc
16864 X11_Xxf86vm_INCLUDE_PATH, X11_Xxf86vm_LIB X11_Xxf86vm_FOUND, X11::Xxf86vm
16865 X11_Xfixes_INCLUDE_PATH, X11_Xfixes_LIB, X11_Xfixes_FOUND, X11::Xfixes
16866 X11_Xft_INCLUDE_PATH, X11_Xft_LIB, X11_Xft_FOUND, X11::Xft
16867 X11_Xi_INCLUDE_PATH, X11_Xi_LIB, X11_Xi_FOUND, X11::Xi
16868 X11_Xinerama_INCLUDE_PATH, X11_Xinerama_LIB, X11_Xinerama_FOUND, X11::Xinerama
16869 X11_Xkb_INCLUDE_PATH,
16870 X11_Xkblib_INCLUDE_PATH, X11_Xkb_FOUND, X11::Xkb
16871 X11_xkbcommon_INCLUDE_PATH, X11_xkbcommon_LIB, X11_xkbcommon_FOUND, X11::xkbcommon
16872 X11_xkbcommon_X11_INCLUDE_PATH,X11_xkbcommon_X11_LIB,X11_xkbcommon_X11_FOUND,X11::xkbcommon_X11
16873 X11_xkbfile_INCLUDE_PATH, X11_xkbfile_LIB, X11_xkbfile_FOUND, X11::xkbfile
16874 X11_Xmu_INCLUDE_PATH, X11_Xmu_LIB, X11_Xmu_FOUND, X11::Xmu
16875 X11_Xpm_INCLUDE_PATH, X11_Xpm_LIB, X11_Xpm_FOUND, X11::Xpm
16876 X11_Xtst_INCLUDE_PATH, X11_Xtst_LIB, X11_Xtst_FOUND, X11::Xtst
16877 X11_Xrandr_INCLUDE_PATH, X11_Xrandr_LIB, X11_Xrandr_FOUND, X11::Xrandr
16878 X11_Xrender_INCLUDE_PATH, X11_Xrender_LIB, X11_Xrender_FOUND, X11::Xrender
16879 X11_XRes_INCLUDE_PATH, X11_XRes_LIB, X11_XRes_FOUND, X11::XRes
16880 X11_Xss_INCLUDE_PATH, X11_Xss_LIB, X11_Xss_FOUND, X11::Xss
16881 X11_Xt_INCLUDE_PATH, X11_Xt_LIB, X11_Xt_FOUND, X11::Xt
16882 X11_Xutil_INCLUDE_PATH, X11_Xutil_FOUND, X11::Xutil
16883 X11_Xv_INCLUDE_PATH, X11_Xv_LIB, X11_Xv_FOUND, X11::Xv
16884 X11_dpms_INCLUDE_PATH, (in X11_Xext_LIB), X11_dpms_FOUND
16885 X11_XShm_INCLUDE_PATH, (in X11_Xext_LIB), X11_XShm_FOUND
16886 X11_Xshape_INCLUDE_PATH, (in X11_Xext_LIB), X11_Xshape_FOUND
16887 X11_XSync_INCLUDE_PATH, (in X11_Xext_LIB), X11_XSync_FOUND
16888 X11_Xaw_INCLUDE_PATH, X11_Xaw_LIB X11_Xaw_FOUND X11::Xaw
16889 FindXalanC
16891 New in version 3.5.
16892 Find the Apache Xalan-C++ XSL transform processor headers and
16895 libraries.
16896 Imported targets
16898 This module defines the following IMPORTED targets:
16899 XalanC::XalanC
16901 The Xalan-C++ xalan-c library, if found.
16902 Result variables
16904 This module will set the following variables in your project:
16905 XalanC_FOUND
16907 true if the Xalan headers and libraries were found
16908 XalanC_VERSION
16910 Xalan release version
16911 XalanC_INCLUDE_DIRS
16913 the directory containing the Xalan headers; note
16914 XercesC_INCLUDE_DIRS is also required
16915 XalanC_LIBRARIES
16917 Xalan libraries to be linked; note XercesC_LIBRARIES is also
16918 required
16919 Cache variables
16921 The following cache variables may also be set:
16922 XalanC_INCLUDE_DIR
16924 the directory containing the Xalan headers
16925 XalanC_LIBRARY
16927 the Xalan library
16928 FindXCTest
16930 New in version 3.3.
16931 Functions to help creating and executing XCTest bundles.
16934 An XCTest bundle is a CFBundle with a special product-type and bundle
16936 extension. The Mac Developer Library provides more information in the
16937 Testing with Xcode document.
16938 Module Functions
16940 xctest_add_bundle
16941 The xctest_add_bundle function creates a XCTest bundle named
16942 <target> which will test the target <testee>. Supported target
16943 types for testee are Frameworks and App Bundles:
16944 xctest_add_bundle(
16946 <target> # Name of the XCTest bundle
16947 <testee> # Target name of the testee
16948 )
16949 xctest_add_test
16951 The xctest_add_test function adds an XCTest bundle to the
16952 project to be run by ctest(1). The test will be named <name> and
16953 tests <bundle>:
16954 xctest_add_test(
16956 <name> # Test name
16957 <bundle> # Target name of XCTest bundle
16958 )
16959 Module Variables
16961 The following variables are set by including this module:
16962 XCTest_FOUND
16964 True if the XCTest Framework and executable were found.
16965 XCTest_EXECUTABLE
16967 The path to the xctest command line tool used to execute XCTest
16968 bundles.
16969 XCTest_INCLUDE_DIRS
16971 The directory containing the XCTest Framework headers.
16972 XCTest_LIBRARIES
16974 The location of the XCTest Framework.
16975 FindXercesC
16977 New in version 3.1.
16978 Find the Apache Xerces-C++ validating XML parser headers and libraries.
16981 Imported targets
16983 This module defines the following IMPORTED targets:
16984 XercesC::XercesC
16986 The Xerces-C++ xerces-c library, if found.
16987 Result variables
16989 This module will set the following variables in your project:
16990 XercesC_FOUND
16992 true if the Xerces headers and libraries were found
16993 XercesC_VERSION
16995 Xerces release version
16996 XercesC_INCLUDE_DIRS
16998 the directory containing the Xerces headers
16999 XercesC_LIBRARIES
17001 Xerces libraries to be linked
17002 Cache variables
17004 The following cache variables may also be set:
17005 XercesC_INCLUDE_DIR
17007 the directory containing the Xerces headers
17008 XercesC_LIBRARY
17010 the Xerces library
17011 FindXMLRPC
17013 Find xmlrpc
17014 Find the native XMLRPC headers and libraries.
17016 XMLRPC_INCLUDE_DIRS - where to find xmlrpc.h, etc.
17018 XMLRPC_LIBRARIES - List of libraries when using xmlrpc.
17019 XMLRPC_FOUND - True if xmlrpc found.
17020 XMLRPC modules may be specified as components for this find module.
17022 Modules may be listed by running “xmlrpc-c-config”. Modules include:
17023 c++ C++ wrapper code
17025 libwww-client libwww-based client
17026 cgi-server CGI-based server
17027 abyss-server ABYSS-based server
17028 Typical usage:
17030 find_package(XMLRPC REQUIRED libwww-client)
17032 FindZLIB
17034 Find the native ZLIB includes and library.
17035 IMPORTED Targets
17037 This module defines IMPORTED target ZLIB::ZLIB, if ZLIB has been found.
17038 Result Variables
17040 This module defines the following variables:
17041 ZLIB_INCLUDE_DIRS - where to find zlib.h, etc.
17043 ZLIB_LIBRARIES - List of libraries when using zlib.
17044 ZLIB_FOUND - True if zlib found.
17045 ZLIB_VERSION_STRING - The version of zlib found (x.y.z)
17047 ZLIB_VERSION_MAJOR - The major version of zlib
17048 ZLIB_VERSION_MINOR - The minor version of zlib
17049 ZLIB_VERSION_PATCH - The patch version of zlib
17050 ZLIB_VERSION_TWEAK - The tweak version of zlib
17051 Backward Compatibility
17053 The following variable are provided for backward compatibility
17054 ZLIB_MAJOR_VERSION - The major version of zlib
17056 ZLIB_MINOR_VERSION - The minor version of zlib
17057 ZLIB_PATCH_VERSION - The patch version of zlib
17058 Hints
17060 A user may set ZLIB_ROOT to a zlib installation root to tell this mod‐
17061 ule where to look.
17062
17064 Deprecated Utility Modules
17065 CMakeDetermineVSServicePack
17066 Deprecated since version 3.0: Do not use.
17067 The functionality of this module has been superseded by the
17070 CMAKE_<LANG>_COMPILER_VERSION variable that contains the compiler ver‐
17071 sion number.
17072 Determine the Visual Studio service pack of the ‘cl’ in use.
17074 Usage:
17076 if(MSVC)
17078 include(CMakeDetermineVSServicePack)
17079 DetermineVSServicePack( my_service_pack )
17080 if( my_service_pack )
17081 message(STATUS "Detected: ${my_service_pack}")
17082 endif()
17083 endif()
17084 Function DetermineVSServicePack sets the given variable to one of the
17086 following values or an empty string if unknown:
17087 vc80, vc80sp1
17089 vc90, vc90sp1
17090 vc100, vc100sp1
17091 vc110, vc110sp1, vc110sp2, vc110sp3, vc110sp4
17092 CMakeExpandImportedTargets
17094 Deprecated since version 3.4: Do not use.
17095 This module was once needed to expand imported targets to the underly‐
17098 ing libraries they reference on disk for use with the try_compile() and
17099 try_run() commands. These commands now support imported libraries in
17100 their LINK_LIBRARIES options (since CMake 2.8.11 for try_compile() and
17101 since CMake 3.2 for try_run()).
17102 This module does not support the policy CMP0022 NEW behavior or use of
17104 the INTERFACE_LINK_LIBRARIES property because generator expressions
17105 cannot be evaluated during configuration.
17106 CMAKE_EXPAND_IMPORTED_TARGETS(<var> LIBRARIES lib1 lib2...libN
17108 [CONFIGURATION <config>])
17109 CMAKE_EXPAND_IMPORTED_TARGETS() takes a list of libraries and replaces
17111 all imported targets contained in this list with their actual file
17112 paths of the referenced libraries on disk, including the libraries from
17113 their link interfaces. If a CONFIGURATION is given, it uses the
17114 respective configuration of the imported targets if it exists. If no
17115 CONFIGURATION is given, it uses the first configuration from
17116 ${CMAKE_CONFIGURATION_TYPES} if set, otherwise ${CMAKE_BUILD_TYPE}.
17117 cmake_expand_imported_targets(expandedLibs
17119 LIBRARIES ${CMAKE_REQUIRED_LIBRARIES}
17120 CONFIGURATION "${CMAKE_TRY_COMPILE_CONFIGURATION}" )
17121 CMakeForceCompiler
17123 Deprecated since version 3.6: Do not use.
17124 The macros provided by this module were once intended for use by
17127 cross-compiling toolchain files when CMake was not able to automati‐
17128 cally detect the compiler identification. Since the introduction of
17129 this module, CMake’s compiler identification capabilities have improved
17130 and can now be taught to recognize any compiler. Furthermore, the
17131 suite of information CMake detects from a compiler is now too extensive
17132 to be provided by toolchain files using these macros.
17133 One common use case for this module was to skip CMake’s checks for a
17135 working compiler when using a cross-compiler that cannot link binaries
17136 without special flags or custom linker scripts. This case is now sup‐
17137 ported by setting the CMAKE_TRY_COMPILE_TARGET_TYPE variable in the
17138 toolchain file instead.
17139 ----
17142 Macro CMAKE_FORCE_C_COMPILER has the following signature:
17146 CMAKE_FORCE_C_COMPILER(<compiler> <compiler-id>)
17148 It sets CMAKE_C_COMPILER to the given compiler and the cmake internal
17150 variable CMAKE_C_COMPILER_ID to the given compiler-id. It also
17151 bypasses the check for working compiler and basic compiler information
17152 tests.
17153 Macro CMAKE_FORCE_CXX_COMPILER has the following signature:
17155 CMAKE_FORCE_CXX_COMPILER(<compiler> <compiler-id>)
17157 It sets CMAKE_CXX_COMPILER to the given compiler and the cmake internal
17159 variable CMAKE_CXX_COMPILER_ID to the given compiler-id. It also
17160 bypasses the check for working compiler and basic compiler information
17161 tests.
17162 Macro CMAKE_FORCE_Fortran_COMPILER has the following signature:
17164 CMAKE_FORCE_Fortran_COMPILER(<compiler> <compiler-id>)
17166 It sets CMAKE_Fortran_COMPILER to the given compiler and the cmake
17168 internal variable CMAKE_Fortran_COMPILER_ID to the given compiler-id.
17169 It also bypasses the check for working compiler and basic compiler
17170 information tests.
17171 So a simple toolchain file could look like this:
17173 include (CMakeForceCompiler)
17175 set(CMAKE_SYSTEM_NAME Generic)
17176 CMAKE_FORCE_C_COMPILER (chc12 MetrowerksHicross)
17177 CMAKE_FORCE_CXX_COMPILER (chc12 MetrowerksHicross)
17178 CMakeParseArguments
17180 This module once implemented the cmake_parse_arguments() command that
17181 is now implemented natively by CMake. It is now an empty placeholder
17182 for compatibility with projects that include it to get the command from
17183 CMake 3.4 and lower.
17184 MacroAddFileDependencies
17186 MACRO_ADD_FILE_DEPENDENCIES(<_file> depend_files…)
17187 Using the macro MACRO_ADD_FILE_DEPENDENCIES() is discouraged. There
17189 are usually better ways to specify the correct dependencies.
17190 MACRO_ADD_FILE_DEPENDENCIES(<_file> depend_files…) is just a conve‐
17192 nience wrapper around the OBJECT_DEPENDS source file property. You can
17193 just use set_property(SOURCE <file> APPEND PROPERTY OBJECT_DEPENDS
17194 depend_files) instead.
17195 TestCXXAcceptsFlag
17197 Deprecated since version 3.0: See CheckCXXCompilerFlag.
17198 Check if the CXX compiler accepts a flag.
17201 CHECK_CXX_ACCEPTS_FLAG(<flags> <variable>)
17203 <flags>
17205 the flags to try
17206 <variable>
17208 variable to store the result
17209 UsePkgConfig
17211 Obsolete pkg-config module for CMake, use FindPkgConfig instead.
17212 This module defines the following macro:
17214 PKGCONFIG(package includedir libdir linkflags cflags)
17216 Calling PKGCONFIG will fill the desired information into the 4 given
17218 arguments, e.g. PKGCONFIG(libart-2.0 LIBART_INCLUDE_DIR
17219 LIBART_LINK_DIR LIBART_LINK_FLAGS LIBART_CFLAGS) if pkg-config was NOT
17220 found or the specified software package doesn’t exist, the variable
17221 will be empty when the function returns, otherwise they will contain
17222 the respective information
17223 Use_wxWindows
17225 Deprecated since version 2.8.10: Use find_package(wxWidgets) and
17226 include(${wxWidgets_USE_FILE}) instead.
17227 This convenience include finds if wxWindows is installed and set the
17230 appropriate libs, incdirs, flags etc. author Jan Woetzel <jw -at-
17231 mip.informatik.uni-kiel.de> (07/2003)
17232 USAGE:
17234 just include Use_wxWindows.cmake
17236 in your projects CMakeLists.txt
17237 include( ${CMAKE_MODULE_PATH}/Use_wxWindows.cmake)
17239 if you are sure you need GL then
17241 set(WXWINDOWS_USE_GL 1)
17243 *before* you include this file.
17245 WriteBasicConfigVersionFile
17247 Deprecated since version 3.0: Use the identical command
17248 write_basic_package_version_file() from module CMakePackageCon‐
17249 figHelpers.
17250 WRITE_BASIC_CONFIG_VERSION_FILE( filename
17253 [VERSION major.minor.patch]
17254 COMPATIBILITY (AnyNewerVersion|SameMajorVersion|SameMinorVersion|ExactVersion)
17255 [ARCH_INDEPENDENT]
17256 )
17257 Deprecated Find Modules
17259 FindCUDA
17260 Deprecated since version 3.10: Superseded by first-class support for
17261 the CUDA language in CMake. Superseded by the FindCUDAToolkit for CUDA
17262 toolkit libraries.
17263 Replacement
17266 It is no longer necessary to use this module or call find_package(CUDA)
17267 for compiling CUDA code. Instead, list CUDA among the languages named
17268 in the top-level call to the project() command, or call the enable_lan‐
17269 guage() command with CUDA. Then one can add CUDA (.cu) sources to pro‐
17270 grams directly in calls to add_library() and add_executable().
17271 To find and use the CUDA toolkit libraries the FindCUDAToolkit module
17273 has superseded this module. It works whether or not the CUDA language
17274 is enabled.
17275 Documentation of Deprecated Usage
17277 Tools for building CUDA C files: libraries and build dependencies.
17278 This script locates the NVIDIA CUDA C tools. It should work on Linux,
17280 Windows, and macOS and should be reasonably up to date with CUDA C
17281 releases.
17282 This script makes use of the standard find_package() arguments of <VER‐
17284 SION>, REQUIRED and QUIET. CUDA_FOUND will report if an acceptable
17285 version of CUDA was found.
17286 The script will prompt the user to specify CUDA_TOOLKIT_ROOT_DIR if the
17288 prefix cannot be determined by the location of nvcc in the system path
17289 and REQUIRED is specified to find_package(). To use a different
17290 installed version of the toolkit set the environment variable
17291 CUDA_BIN_PATH before running cmake (e.g.
17292 CUDA_BIN_PATH=/usr/local/cuda1.0 instead of the default
17293 /usr/local/cuda) or set CUDA_TOOLKIT_ROOT_DIR after configuring. If
17294 you change the value of CUDA_TOOLKIT_ROOT_DIR, various components that
17295 depend on the path will be relocated.
17296 It might be necessary to set CUDA_TOOLKIT_ROOT_DIR manually on certain
17298 platforms, or to use a CUDA runtime not installed in the default loca‐
17299 tion. In newer versions of the toolkit the CUDA library is included
17300 with the graphics driver – be sure that the driver version matches what
17301 is needed by the CUDA runtime version.
17302 The following variables affect the behavior of the macros in the script
17304 (in alphabetical order). Note that any of these flags can be changed
17305 multiple times in the same directory before calling CUDA_ADD_EXE‐
17306 CUTABLE, CUDA_ADD_LIBRARY, CUDA_COMPILE, CUDA_COMPILE_PTX, CUDA_COM‐
17307 PILE_FATBIN, CUDA_COMPILE_CUBIN or CUDA_WRAP_SRCS:
17308 CUDA_64_BIT_DEVICE_CODE (Default matches host bit size)
17310 -- Set to ON to compile for 64 bit device code, OFF for 32 bit device code.
17311 Note that making this different from the host code when generating object
17312 or C files from CUDA code just won't work, because size_t gets defined by
17313 nvcc in the generated source. If you compile to PTX and then load the
17314 file yourself, you can mix bit sizes between device and host.
17315 CUDA_ATTACH_VS_BUILD_RULE_TO_CUDA_FILE (Default ON)
17317 -- Set to ON if you want the custom build rule to be attached to the source
17318 file in Visual Studio. Turn OFF if you add the same cuda file to multiple
17319 targets.
17320 This allows the user to build the target from the CUDA file; however, bad
17322 things can happen if the CUDA source file is added to multiple targets.
17323 When performing parallel builds it is possible for the custom build
17324 command to be run more than once and in parallel causing cryptic build
17325 errors. VS runs the rules for every source file in the target, and a
17326 source can have only one rule no matter how many projects it is added to.
17327 When the rule is run from multiple targets race conditions can occur on
17328 the generated file. Eventually everything will get built, but if the user
17329 is unaware of this behavior, there may be confusion. It would be nice if
17330 this script could detect the reuse of source files across multiple targets
17331 and turn the option off for the user, but no good solution could be found.
17332 CUDA_BUILD_CUBIN (Default OFF)
17334 -- Set to ON to enable and extra compilation pass with the -cubin option in
17335 Device mode. The output is parsed and register, shared memory usage is
17336 printed during build.
17337 CUDA_BUILD_EMULATION (Default OFF for device mode)
17339 -- Set to ON for Emulation mode. -D_DEVICEEMU is defined for CUDA C files
17340 when CUDA_BUILD_EMULATION is TRUE.
17341 CUDA_LINK_LIBRARIES_KEYWORD (Default "")
17343 -- The <PRIVATE|PUBLIC|INTERFACE> keyword to use for internal
17344 target_link_libraries calls. The default is to use no keyword which
17345 uses the old "plain" form of target_link_libraries. Note that is matters
17346 because whatever is used inside the FindCUDA module must also be used
17347 outside - the two forms of target_link_libraries cannot be mixed.
17348 CUDA_GENERATED_OUTPUT_DIR (Default CMAKE_CURRENT_BINARY_DIR)
17350 -- Set to the path you wish to have the generated files placed. If it is
17351 blank output files will be placed in CMAKE_CURRENT_BINARY_DIR.
17352 Intermediate files will always be placed in
17353 CMAKE_CURRENT_BINARY_DIR/CMakeFiles.
17354 CUDA_HOST_COMPILATION_CPP (Default ON)
17356 -- Set to OFF for C compilation of host code.
17357 CUDA_HOST_COMPILER (Default CMAKE_C_COMPILER)
17359 -- Set the host compiler to be used by nvcc. Ignored if -ccbin or
17360 --compiler-bindir is already present in the CUDA_NVCC_FLAGS or
17361 CUDA_NVCC_FLAGS_<CONFIG> variables. For Visual Studio targets,
17362 the host compiler is constructed with one or more visual studio macros
17363 such as $(VCInstallDir), that expands out to the path when
17364 the command is run from within VS.
17365 If the CUDAHOSTCXX environment variable is set it will
17366 be used as the default.
17367 CUDA_NVCC_FLAGS
17369 CUDA_NVCC_FLAGS_<CONFIG>
17370 -- Additional NVCC command line arguments. NOTE: multiple arguments must be
17371 semi-colon delimited (e.g. --compiler-options;-Wall)
17372 CUDA_PROPAGATE_HOST_FLAGS (Default ON)
17374 -- Set to ON to propagate CMAKE_{C,CXX}_FLAGS and their configuration
17375 dependent counterparts (e.g. CMAKE_C_FLAGS_DEBUG) automatically to the
17376 host compiler through nvcc's -Xcompiler flag. This helps make the
17377 generated host code match the rest of the system better. Sometimes
17378 certain flags give nvcc problems, and this will help you turn the flag
17379 propagation off. This does not affect the flags supplied directly to nvcc
17380 via CUDA_NVCC_FLAGS or through the OPTION flags specified through
17381 CUDA_ADD_LIBRARY, CUDA_ADD_EXECUTABLE, or CUDA_WRAP_SRCS. Flags used for
17382 shared library compilation are not affected by this flag.
17383 CUDA_SEPARABLE_COMPILATION (Default OFF)
17385 -- If set this will enable separable compilation for all CUDA runtime object
17386 files. If used outside of CUDA_ADD_EXECUTABLE and CUDA_ADD_LIBRARY
17387 (e.g. calling CUDA_WRAP_SRCS directly),
17388 CUDA_COMPUTE_SEPARABLE_COMPILATION_OBJECT_FILE_NAME and
17389 CUDA_LINK_SEPARABLE_COMPILATION_OBJECTS should be called.
17390 CUDA_SOURCE_PROPERTY_FORMAT
17392 -- If this source file property is set, it can override the format specified
17393 to CUDA_WRAP_SRCS (OBJ, PTX, CUBIN, or FATBIN). If an input source file
17394 is not a .cu file, setting this file will cause it to be treated as a .cu
17395 file. See documentation for set_source_files_properties on how to set
17396 this property.
17397 CUDA_USE_STATIC_CUDA_RUNTIME (Default ON)
17399 -- When enabled the static version of the CUDA runtime library will be used
17400 in CUDA_LIBRARIES. If the version of CUDA configured doesn't support
17401 this option, then it will be silently disabled.
17402 CUDA_VERBOSE_BUILD (Default OFF)
17404 -- Set to ON to see all the commands used when building the CUDA file. When
17405 using a Makefile generator the value defaults to VERBOSE (run make
17406 VERBOSE=1 to see output), although setting CUDA_VERBOSE_BUILD to ON will
17407 always print the output.
17408 The script creates the following macros (in alphabetical order):
17410 CUDA_ADD_CUFFT_TO_TARGET( cuda_target )
17412 -- Adds the cufft library to the target (can be any target). Handles whether
17413 you are in emulation mode or not.
17414 CUDA_ADD_CUBLAS_TO_TARGET( cuda_target )
17416 -- Adds the cublas library to the target (can be any target). Handles
17417 whether you are in emulation mode or not.
17418 CUDA_ADD_EXECUTABLE( cuda_target file0 file1 ...
17420 [WIN32] [MACOSX_BUNDLE] [EXCLUDE_FROM_ALL] [OPTIONS ...] )
17421 -- Creates an executable "cuda_target" which is made up of the files
17422 specified. All of the non CUDA C files are compiled using the standard
17423 build rules specified by CMAKE and the cuda files are compiled to object
17424 files using nvcc and the host compiler. In addition CUDA_INCLUDE_DIRS is
17425 added automatically to include_directories(). Some standard CMake target
17426 calls can be used on the target after calling this macro
17427 (e.g. set_target_properties and target_link_libraries), but setting
17428 properties that adjust compilation flags will not affect code compiled by
17429 nvcc. Such flags should be modified before calling CUDA_ADD_EXECUTABLE,
17430 CUDA_ADD_LIBRARY or CUDA_WRAP_SRCS.
17431 CUDA_ADD_LIBRARY( cuda_target file0 file1 ...
17433 [STATIC | SHARED | MODULE] [EXCLUDE_FROM_ALL] [OPTIONS ...] )
17434 -- Same as CUDA_ADD_EXECUTABLE except that a library is created.
17435 CUDA_BUILD_CLEAN_TARGET()
17437 -- Creates a convenience target that deletes all the dependency files
17438 generated. You should make clean after running this target to ensure the
17439 dependency files get regenerated.
17440 CUDA_COMPILE( generated_files file0 file1 ... [STATIC | SHARED | MODULE]
17442 [OPTIONS ...] )
17443 -- Returns a list of generated files from the input source files to be used
17444 with ADD_LIBRARY or ADD_EXECUTABLE.
17445 CUDA_COMPILE_PTX( generated_files file0 file1 ... [OPTIONS ...] )
17447 -- Returns a list of PTX files generated from the input source files.
17448 CUDA_COMPILE_FATBIN( generated_files file0 file1 ... [OPTIONS ...] )
17450 -- Returns a list of FATBIN files generated from the input source files.
17451 CUDA_COMPILE_CUBIN( generated_files file0 file1 ... [OPTIONS ...] )
17453 -- Returns a list of CUBIN files generated from the input source files.
17454 CUDA_COMPUTE_SEPARABLE_COMPILATION_OBJECT_FILE_NAME( output_file_var
17456 cuda_target
17457 object_files )
17458 -- Compute the name of the intermediate link file used for separable
17459 compilation. This file name is typically passed into
17460 CUDA_LINK_SEPARABLE_COMPILATION_OBJECTS. output_file_var is produced
17461 based on cuda_target the list of objects files that need separable
17462 compilation as specified by object_files. If the object_files list is
17463 empty, then output_file_var will be empty. This function is called
17464 automatically for CUDA_ADD_LIBRARY and CUDA_ADD_EXECUTABLE. Note that
17465 this is a function and not a macro.
17466 CUDA_INCLUDE_DIRECTORIES( path0 path1 ... )
17468 -- Sets the directories that should be passed to nvcc
17469 (e.g. nvcc -Ipath0 -Ipath1 ... ). These paths usually contain other .cu
17470 files.
17471 CUDA_LINK_SEPARABLE_COMPILATION_OBJECTS( output_file_var cuda_target
17474 nvcc_flags object_files)
17475 -- Generates the link object required by separable compilation from the given
17476 object files. This is called automatically for CUDA_ADD_EXECUTABLE and
17477 CUDA_ADD_LIBRARY, but can be called manually when using CUDA_WRAP_SRCS
17478 directly. When called from CUDA_ADD_LIBRARY or CUDA_ADD_EXECUTABLE the
17479 nvcc_flags passed in are the same as the flags passed in via the OPTIONS
17480 argument. The only nvcc flag added automatically is the bitness flag as
17481 specified by CUDA_64_BIT_DEVICE_CODE. Note that this is a function
17482 instead of a macro.
17483 CUDA_SELECT_NVCC_ARCH_FLAGS(out_variable [target_CUDA_architectures])
17485 -- Selects GPU arch flags for nvcc based on target_CUDA_architectures
17486 target_CUDA_architectures : Auto | Common | All | LIST(ARCH_AND_PTX ...)
17487 - "Auto" detects local machine GPU compute arch at runtime.
17488 - "Common" and "All" cover common and entire subsets of architectures
17489 ARCH_AND_PTX : NAME | NUM.NUM | NUM.NUM(NUM.NUM) | NUM.NUM+PTX
17490 NAME: Fermi Kepler Maxwell Kepler+Tegra Kepler+Tesla Maxwell+Tegra Pascal
17491 NUM: Any number. Only those pairs are currently accepted by NVCC though:
17492 2.0 2.1 3.0 3.2 3.5 3.7 5.0 5.2 5.3 6.0 6.2
17493 Returns LIST of flags to be added to CUDA_NVCC_FLAGS in ${out_variable}
17494 Additionally, sets ${out_variable}_readable to the resulting numeric list
17495 Example:
17496 CUDA_SELECT_NVCC_ARCH_FLAGS(ARCH_FLAGS 3.0 3.5+PTX 5.2(5.0) Maxwell)
17497 LIST(APPEND CUDA_NVCC_FLAGS ${ARCH_FLAGS})
17498 More info on CUDA architectures: https://en.wikipedia.org/wiki/CUDA
17500 Note that this is a function instead of a macro.
17501 CUDA_WRAP_SRCS ( cuda_target format generated_files file0 file1 ...
17503 [STATIC | SHARED | MODULE] [OPTIONS ...] )
17504 -- This is where all the magic happens. CUDA_ADD_EXECUTABLE,
17505 CUDA_ADD_LIBRARY, CUDA_COMPILE, and CUDA_COMPILE_PTX all call this
17506 function under the hood.
17507 Given the list of files (file0 file1 ... fileN) this macro generates
17509 custom commands that generate either PTX or linkable objects (use "PTX" or
17510 "OBJ" for the format argument to switch). Files that don't end with .cu
17511 or have the HEADER_FILE_ONLY property are ignored.
17512 The arguments passed in after OPTIONS are extra command line options to
17514 give to nvcc. You can also specify per configuration options by
17515 specifying the name of the configuration followed by the options. General
17516 options must precede configuration specific options. Not all
17517 configurations need to be specified, only the ones provided will be used.
17518 OPTIONS -DFLAG=2 "-DFLAG_OTHER=space in flag"
17520 DEBUG -g
17521 RELEASE --use_fast_math
17522 RELWITHDEBINFO --use_fast_math;-g
17523 MINSIZEREL --use_fast_math
17524 For certain configurations (namely VS generating object files with
17526 CUDA_ATTACH_VS_BUILD_RULE_TO_CUDA_FILE set to ON), no generated file will
17527 be produced for the given cuda file. This is because when you add the
17528 cuda file to Visual Studio it knows that this file produces an object file
17529 and will link in the resulting object file automatically.
17530 This script will also generate a separate cmake script that is used at
17532 build time to invoke nvcc. This is for several reasons.
17533 1. nvcc can return negative numbers as return values which confuses
17535 Visual Studio into thinking that the command succeeded. The script now
17536 checks the error codes and produces errors when there was a problem.
17537 2. nvcc has been known to not delete incomplete results when it
17539 encounters problems. This confuses build systems into thinking the
17540 target was generated when in fact an unusable file exists. The script
17541 now deletes the output files if there was an error.
17542 3. By putting all the options that affect the build into a file and then
17544 make the build rule dependent on the file, the output files will be
17545 regenerated when the options change.
17546 This script also looks at optional arguments STATIC, SHARED, or MODULE to
17548 determine when to target the object compilation for a shared library.
17549 BUILD_SHARED_LIBS is ignored in CUDA_WRAP_SRCS, but it is respected in
17550 CUDA_ADD_LIBRARY. On some systems special flags are added for building
17551 objects intended for shared libraries. A preprocessor macro,
17552 <target_name>_EXPORTS is defined when a shared library compilation is
17553 detected.
17554 Flags passed into add_definitions with -D or /D are passed along to nvcc.
17556 The script defines the following variables:
17558 CUDA_VERSION_MAJOR -- The major version of cuda as reported by nvcc.
17560 CUDA_VERSION_MINOR -- The minor version.
17561 CUDA_VERSION
17562 CUDA_VERSION_STRING -- CUDA_VERSION_MAJOR.CUDA_VERSION_MINOR
17563 CUDA_HAS_FP16 -- Whether a short float (float16,fp16) is supported.
17564 CUDA_TOOLKIT_ROOT_DIR -- Path to the CUDA Toolkit (defined if not set).
17566 CUDA_SDK_ROOT_DIR -- Path to the CUDA SDK. Use this to find files in the
17567 SDK. This script will not directly support finding
17568 specific libraries or headers, as that isn't
17569 supported by NVIDIA. If you want to change
17570 libraries when the path changes see the
17571 FindCUDA.cmake script for an example of how to clear
17572 these variables. There are also examples of how to
17573 use the CUDA_SDK_ROOT_DIR to locate headers or
17574 libraries, if you so choose (at your own risk).
17575 CUDA_INCLUDE_DIRS -- Include directory for cuda headers. Added automatically
17576 for CUDA_ADD_EXECUTABLE and CUDA_ADD_LIBRARY.
17577 CUDA_LIBRARIES -- Cuda RT library.
17578 CUDA_CUFFT_LIBRARIES -- Device or emulation library for the Cuda FFT
17579 implementation (alternative to:
17580 CUDA_ADD_CUFFT_TO_TARGET macro)
17581 CUDA_CUBLAS_LIBRARIES -- Device or emulation library for the Cuda BLAS
17582 implementation (alternative to:
17583 CUDA_ADD_CUBLAS_TO_TARGET macro).
17584 CUDA_cudart_static_LIBRARY -- Statically linkable cuda runtime library.
17585 Only available for CUDA version 5.5+
17586 CUDA_cudadevrt_LIBRARY -- Device runtime library.
17587 Required for separable compilation.
17588 CUDA_cupti_LIBRARY -- CUDA Profiling Tools Interface library.
17589 Only available for CUDA version 4.0+.
17590 CUDA_curand_LIBRARY -- CUDA Random Number Generation library.
17591 Only available for CUDA version 3.2+.
17592 CUDA_cusolver_LIBRARY -- CUDA Direct Solver library.
17593 Only available for CUDA version 7.0+.
17594 CUDA_cusparse_LIBRARY -- CUDA Sparse Matrix library.
17595 Only available for CUDA version 3.2+.
17596 CUDA_npp_LIBRARY -- NVIDIA Performance Primitives lib.
17597 Only available for CUDA version 4.0+.
17598 CUDA_nppc_LIBRARY -- NVIDIA Performance Primitives lib (core).
17599 Only available for CUDA version 5.5+.
17600 CUDA_nppi_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
17601 Only available for CUDA version 5.5 - 8.0.
17602 CUDA_nppial_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
17603 Only available for CUDA version 9.0.
17604 CUDA_nppicc_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
17605 Only available for CUDA version 9.0.
17606 CUDA_nppicom_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
17607 Only available for CUDA version 9.0 - 10.2.
17608 Replaced by nvjpeg.
17609 CUDA_nppidei_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
17610 Only available for CUDA version 9.0.
17611 CUDA_nppif_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
17612 Only available for CUDA version 9.0.
17613 CUDA_nppig_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
17614 Only available for CUDA version 9.0.
17615 CUDA_nppim_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
17616 Only available for CUDA version 9.0.
17617 CUDA_nppist_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
17618 Only available for CUDA version 9.0.
17619 CUDA_nppisu_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
17620 Only available for CUDA version 9.0.
17621 CUDA_nppitc_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
17622 Only available for CUDA version 9.0.
17623 CUDA_npps_LIBRARY -- NVIDIA Performance Primitives lib (signal processing).
17624 Only available for CUDA version 5.5+.
17625 CUDA_nvcuvenc_LIBRARY -- CUDA Video Encoder library.
17626 Only available for CUDA version 3.2+.
17627 Windows only.
17628 CUDA_nvcuvid_LIBRARY -- CUDA Video Decoder library.
17629 Only available for CUDA version 3.2+.
17630 Windows only.
17631 CUDA_nvToolsExt_LIBRARY
17632 -- NVIDA CUDA Tools Extension library.
17633 Available for CUDA version 5+.
17634 CUDA_OpenCL_LIBRARY -- NVIDA CUDA OpenCL library.
17635 Available for CUDA version 5+.
17636 FindPythonInterp
17638 Deprecated since version 3.12: Use FindPython3, FindPython2 or Find‐
17639 Python instead.
17640 Find python interpreter
17643 This module finds if Python interpreter is installed and determines
17645 where the executables are. This code sets the following variables:
17646 PYTHONINTERP_FOUND - Was the Python executable found
17648 PYTHON_EXECUTABLE - path to the Python interpreter
17649 PYTHON_VERSION_STRING - Python version found e.g. 2.5.2
17651 PYTHON_VERSION_MAJOR - Python major version found e.g. 2
17652 PYTHON_VERSION_MINOR - Python minor version found e.g. 5
17653 PYTHON_VERSION_PATCH - Python patch version found e.g. 2
17654 The Python_ADDITIONAL_VERSIONS variable can be used to specify a list
17656 of version numbers that should be taken into account when searching for
17657 Python. You need to set this variable before calling find_pack‐
17658 age(PythonInterp).
17659 If calling both find_package(PythonInterp) and find_package(Python‐
17661 Libs), call find_package(PythonInterp) first to get the currently
17662 active Python version by default with a consistent version of
17663 PYTHON_LIBRARIES.
17664 NOTE:
17666 A call to find_package(PythonInterp ${V}) for python version V may
17667 find a python executable with no version suffix. In this case no
17668 attempt is made to avoid python executables from other versions.
17669 Use FindPython3, FindPython2 or FindPython instead.
17670 FindPythonLibs
17672 Deprecated since version 3.12: Use FindPython3, FindPython2 or Find‐
17673 Python instead.
17674 Find python libraries
17677 This module finds if Python is installed and determines where the
17679 include files and libraries are. It also determines what the name of
17680 the library is. This code sets the following variables:
17681 PYTHONLIBS_FOUND - have the Python libs been found
17683 PYTHON_LIBRARIES - path to the python library
17684 PYTHON_INCLUDE_PATH - path to where Python.h is found (deprecated)
17685 PYTHON_INCLUDE_DIRS - path to where Python.h is found
17686 PYTHON_DEBUG_LIBRARIES - path to the debug library (deprecated)
17687 PYTHONLIBS_VERSION_STRING - version of the Python libs found (since CMake 2.8.8)
17688 The Python_ADDITIONAL_VERSIONS variable can be used to specify a list
17690 of version numbers that should be taken into account when searching for
17691 Python. You need to set this variable before calling find_pack‐
17692 age(PythonLibs).
17693 If you’d like to specify the installation of Python to use, you should
17695 modify the following cache variables:
17696 PYTHON_LIBRARY - path to the python library
17698 PYTHON_INCLUDE_DIR - path to where Python.h is found
17699 If calling both find_package(PythonInterp) and find_package(Python‐
17701 Libs), call find_package(PythonInterp) first to get the currently
17702 active Python version by default with a consistent version of
17703 PYTHON_LIBRARIES.
17704 FindQt
17706 Searches for all installed versions of Qt3 or Qt4.
17707 This module cannot handle Qt5 or any later versions. For those, see
17709 cmake-qt(7).
17710 This module exists for the find_package() command only if policy
17712 CMP0084 is not set to NEW.
17713 This module should only be used if your project can work with multiple
17715 versions of Qt. If not, you should just directly use FindQt4 or
17716 FindQt3. If multiple versions of Qt are found on the machine, then The
17717 user must set the option DESIRED_QT_VERSION to the version they want to
17718 use. If only one version of qt is found on the machine, then the
17719 DESIRED_QT_VERSION is set to that version and the matching FindQt3 or
17720 FindQt4 module is included. Once the user sets DESIRED_QT_VERSION,
17721 then the FindQt3 or FindQt4 module is included.
17722 QT_REQUIRED if this is set to TRUE then if CMake can
17724 not find Qt4 or Qt3 an error is raised
17725 and a message is sent to the user.
17726 DESIRED_QT_VERSION OPTION is created
17728 QT4_INSTALLED is set to TRUE if qt4 is found.
17729 QT3_INSTALLED is set to TRUE if qt3 is found.
17730 FindwxWindows
17732 Deprecated since version 3.0: Replaced by FindwxWidgets.
17733 Find wxWindows (wxWidgets) installation
17736 This module finds if wxWindows/wxWidgets is installed and determines
17738 where the include files and libraries are. It also determines what the
17739 name of the library is. This code sets the following variables:
17740 WXWINDOWS_FOUND = system has WxWindows
17742 WXWINDOWS_LIBRARIES = path to the wxWindows libraries
17743 on Unix/Linux with additional
17744 linker flags from
17745 "wx-config --libs"
17746 CMAKE_WXWINDOWS_CXX_FLAGS = Compiler flags for wxWindows,
17747 essentially "`wx-config --cxxflags`"
17748 on Linux
17749 WXWINDOWS_INCLUDE_DIR = where to find "wx/wx.h" and "wx/setup.h"
17750 WXWINDOWS_LINK_DIRECTORIES = link directories, useful for rpath on
17751 Unix
17752 WXWINDOWS_DEFINITIONS = extra defines
17753 OPTIONS If you need OpenGL support please
17755 set(WXWINDOWS_USE_GL 1)
17757 in your CMakeLists.txt before you include this file.
17759 HAVE_ISYSTEM - true required to replace -I by -isystem on g++
17761 For convenience include Use_wxWindows.cmake in your project’s CMake‐
17763 Lists.txt using include(${CMAKE_CURRENT_LIST_DIR}/Use_wxWindows.cmake).
17764 USAGE
17766 set(WXWINDOWS_USE_GL 1)
17768 find_package(wxWindows)
17769 NOTES wxWidgets 2.6.x is supported for monolithic builds e.g. compiled
17771 in wx/build/msw dir as:
17772 nmake -f makefile.vc BUILD=debug SHARED=0 USE_OPENGL=1 MONOLITHIC=1
17774 DEPRECATED
17776 CMAKE_WX_CAN_COMPILE
17778 WXWINDOWS_LIBRARY
17779 CMAKE_WX_CXX_FLAGS
17780 WXWINDOWS_INCLUDE_PATH
17781 AUTHOR Jan Woetzel <http://www.mip.informatik.uni-kiel.de/~jw>
17783 (07/2003-01/2006)
17784 Legacy CPack Modules
17786 These modules used to be mistakenly exposed to the user, and have been
17787 moved out of user visibility. They are for CPack internal use, and
17788 should never be used directly.
17789 CPackArchive
17791 New in version 3.9.
17792 The documentation for the CPack Archive generator has moved here: CPack
17795 Archive Generator
17796 CPackBundle
17798 The documentation for the CPack Bundle generator has moved here: CPack
17799 Bundle Generator
17800 CPackCygwin
17802 The documentation for the CPack Cygwin generator has moved here: CPack
17803 Cygwin Generator
17804 CPackDeb
17806 The documentation for the CPack DEB generator has moved here: CPack DEB
17807 Generator
17808 CPackDMG
17810 The documentation for the CPack DragNDrop generator has moved here:
17811 CPack DragNDrop Generator
17812 CPackFreeBSD
17814 New in version 3.10.
17815 The documentation for the CPack FreeBSD generator has moved here: CPack
17818 FreeBSD Generator
17819 CPackNSIS
17821 The documentation for the CPack NSIS generator has moved here: CPack
17822 NSIS Generator
17823 CPackNuGet
17825 New in version 3.12.
17826 The documentation for the CPack NuGet generator has moved here: CPack
17829 NuGet Generator
17830 CPackPackageMaker
17832 The documentation for the CPack PackageMaker generator has moved here:
17833 CPack PackageMaker Generator
17834 CPackProductBuild
17836 New in version 3.7.
17837 The documentation for the CPack productbuild generator has moved here:
17840 CPack productbuild Generator
17841 CPackRPM
17843 The documentation for the CPack RPM generator has moved here: CPack RPM
17844 Generator
17845 CPackWIX
17847 The documentation for the CPack WIX generator has moved here: CPack WIX
17848 Generator
17849
17851 2000-2021 Kitware, Inc. and Contributors
178523.19.7 Mar 15, 2021 CMAKE-MODULES(7)