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 Create a test that automatically loads specified data onto an Android
24 device.
25 Introduction
27 Use this module to push data needed for testing an Android device
28 behavior onto a connected Android device. The module will accept files
29 and libraries as well as separate destinations for each. It will create
30 a test that loads the files into a device object store and link to them
31 from the specified destination. The files are only uploaded if they are
32 not already in the object store.
33 For example:
35 include(AndroidTestUtilities)
37 android_add_test_data(
38 example_setup_test
39 FILES <files>...
40 LIBS <libs>...
41 DEVICE_TEST_DIR "/data/local/tests/example"
42 DEVICE_OBJECT_STORE "/sdcard/.ExternalData/SHA"
43 )
44 At build time a test named “example_setup_test” will be created. Run
46 this test on the command line with ctest(1) to load the data onto the
47 Android device.
48 Module Functions
50 android_add_test_data
51 android_add_test_data(<test-name>
53 [FILES <files>...] [FILES_DEST <device-dir>]
54 [LIBS <libs>...] [LIBS_DEST <device-dir>]
55 [DEVICE_OBJECT_STORE <device-dir>]
56 [DEVICE_TEST_DIR <device-dir>]
57 [NO_LINK_REGEX <strings>...]
58 )
59 The android_add_test_data function is used to copy files and
61 libraries needed to run project-specific tests. On the host
62 operating system, this is done at build time. For on-device
63 testing, the files are loaded onto the device by the manufac‐
64 tured test at run time.
65 This function accepts the following named parameters:
67 FILES <files>...
69 zero or more files needed for testing
70 LIBS <libs>...
72 zero or more libraries needed for testing
73 FILES_DEST <device-dir>
75 absolute path where the data files are expected to be
76 LIBS_DEST <device-dir>
78 absolute path where the libraries are expected to be
79 DEVICE_OBJECT_STORE <device-dir>
81 absolute path to the location where the data is stored
82 on-device
83 DEVICE_TEST_DIR <device-dir>
85 absolute path to the root directory of the on-device test
86 location
87 NO_LINK_REGEX <strings>...
89 list of regex strings matching the names of files that
90 should be copied from the object store to the testing
91 directory
92 BundleUtilities
94 Functions to help assemble a standalone bundle application.
95 A collection of CMake utility functions useful for dealing with .app
97 bundles on the Mac and bundle-like directories on any OS.
98 The following functions are provided by this module:
100 fixup_bundle
102 copy_and_fixup_bundle
103 verify_app
104 get_bundle_main_executable
105 get_dotapp_dir
106 get_bundle_and_executable
107 get_bundle_all_executables
108 get_item_key
109 get_item_rpaths
110 clear_bundle_keys
111 set_bundle_key_values
112 get_bundle_keys
113 copy_resolved_item_into_bundle
114 copy_resolved_framework_into_bundle
115 fixup_bundle_item
116 verify_bundle_prerequisites
117 verify_bundle_symlinks
118 Requires CMake 2.6 or greater because it uses function, break and PAR‐
120 ENT_SCOPE. Also depends on GetPrerequisites.cmake.
121 DO NOT USE THESE FUNCTIONS AT CONFIGURE TIME (from CMakeLists.txt)!
123 Instead, invoke them from an install(CODE) or install(SCRIPT) rule.
124 fixup_bundle(<app> <libs> <dirs>)
126 Fix up <app> bundle in-place and make it standalone, such that it can
128 be drag-n-drop copied to another machine and run on that machine as
129 long as all of the system libraries are compatible.
130 If you pass plugins to fixup_bundle as the libs parameter, you should
132 install them or copy them into the bundle before calling fixup_bundle.
133 The <libs> parameter is a list of libraries that must be fixed up, but
134 that cannot be determined by otool output analysis (i.e. plugins).
135 Gather all the keys for all the executables and libraries in a bundle,
137 and then, for each key, copy each prerequisite into the bundle. Then
138 fix each one up according to its own list of prerequisites.
139 Then clear all the keys and call verify_app on the final bundle to
141 ensure that it is truly standalone.
142 As an optional parameter (IGNORE_ITEM) a list of file names can be
144 passed, which are then ignored (e.g. IGNORE_ITEM "vcre‐
145 dist_x86.exe;vcredist_x64.exe").
146 copy_and_fixup_bundle(<src> <dst> <libs> <dirs>)
148 Makes a copy of the bundle <src> at location <dst> and then fixes up
150 the new copied bundle in-place at <dst>.
151 verify_app(<app>)
153 Verifies that an application <app> appears valid based on running anal‐
155 ysis tools on it. Calls message(FATAL_ERROR) if the application is not
156 verified.
157 As an optional parameter (IGNORE_ITEM) a list of file names can be
159 passed, which are then ignored (e.g. IGNORE_ITEM "vcre‐
160 dist_x86.exe;vcredist_x64.exe")
161 get_bundle_main_executable(<bundle> <result_var>)
163 The result will be the full path name of the bundle’s main executable
165 file or an error: prefixed string if it could not be determined.
166 get_dotapp_dir(<exe> <dotapp_dir_var>)
168 Returns the nearest parent dir whose name ends with .app given the full
170 path to an executable. If there is no such parent dir, then simply
171 return the dir containing the executable.
172 The returned directory may or may not exist.
174 get_bundle_and_executable(<app> <bundle_var> <executable_var> <valid_var>)
176 Takes either a .app directory name or the name of an executable nested
178 inside a .app directory and returns the path to the .app directory in
179 <bundle_var> and the path to its main executable in <executable_var>.
180 get_bundle_all_executables(<bundle> <exes_var>)
182 Scans <bundle> bundle recursively for all <exes_var> executable files
184 and accumulates them into a variable.
185 get_item_key(<item> <key_var>)
187 Given <item> file name, generate <key_var> key that should be unique
189 considering the set of libraries that need copying or fixing up to make
190 a bundle standalone. This is essentially the file name including
191 extension with . replaced by _
192 This key is used as a prefix for CMake variables so that we can asso‐
194 ciate a set of variables with a given item based on its key.
195 clear_bundle_keys(<keys_var>)
197 Loop over the <keys_var> list of keys, clearing all the variables asso‐
199 ciated with each key. After the loop, clear the list of keys itself.
200 Caller of get_bundle_keys should call clear_bundle_keys when done with
202 list of keys.
203 set_bundle_key_values(<keys_var> <context> <item> <exepath> <dirs>
205 <copyflag> [<rpaths>])
206 Add <keys_var> key to the list (if necessary) for the given item. If
208 added, also set all the variables associated with that key.
209 get_bundle_keys(<app> <libs> <dirs> <keys_var>)
211 Loop over all the executable and library files within <app> bundle (and
213 given as extra <libs>) and accumulate a list of keys representing them.
214 Set values associated with each key such that we can loop over all of
215 them and copy prerequisite libs into the bundle and then do appropriate
216 install_name_tool fixups.
217 As an optional parameter (IGNORE_ITEM) a list of file names can be
219 passed, which are then ignored (e.g. IGNORE_ITEM "vcre‐
220 dist_x86.exe;vcredist_x64.exe")
221 copy_resolved_item_into_bundle(<resolved_item> <resolved_embedded_item>)
223 Copy a resolved item into the bundle if necessary. Copy is not neces‐
225 sary, if the <resolved_item> is “the same as” the <resolved_embed‐
226 ded_item>.
227 copy_resolved_framework_into_bundle(<resolved_item> <resolved_embedded_item>)
229 Copy a resolved framework into the bundle if necessary. Copy is not
231 necessary, if the <resolved_item> is “the same as” the <resolved_embed‐
232 ded_item>.
233 By default, BU_COPY_FULL_FRAMEWORK_CONTENTS is not set. If you want
235 full frameworks embedded in your bundles, set BU_COPY_FULL_FRAME‐
236 WORK_CONTENTS to ON before calling fixup_bundle. By default,
237 COPY_RESOLVED_FRAMEWORK_INTO_BUNDLE copies the framework dylib itself
238 plus the framework Resources directory.
239 fixup_bundle_item(<resolved_embedded_item> <exepath> <dirs>)
241 Get the direct/non-system prerequisites of the <resolved_embed‐
243 ded_item>. For each prerequisite, change the way it is referenced to
244 the value of the _EMBEDDED_ITEM keyed variable for that prerequisite.
245 (Most likely changing to an @executable_path style reference.)
246 This function requires that the <resolved_embedded_item> be inside the
248 bundle already. In other words, if you pass plugins to fixup_bundle as
249 the libs parameter, you should install them or copy them into the bun‐
250 dle before calling fixup_bundle. The libs parameter is a list of
251 libraries that must be fixed up, but that cannot be determined by otool
252 output analysis. (i.e., plugins)
253 Also, change the id of the item being fixed up to its own _EMBED‐
255 DED_ITEM value.
256 Accumulate changes in a local variable and make one call to
258 install_name_tool at the end of the function with all the changes at
259 once.
260 If the BU_CHMOD_BUNDLE_ITEMS variable is set then bundle items will be
262 marked writable before install_name_tool tries to change them.
263 verify_bundle_prerequisites(<bundle> <result_var> <info_var>)
265 Verifies that the sum of all prerequisites of all files inside the bun‐
267 dle are contained within the bundle or are system libraries, presumed
268 to exist everywhere.
269 As an optional parameter (IGNORE_ITEM) a list of file names can be
271 passed, which are then ignored (e.g. IGNORE_ITEM "vcre‐
272 dist_x86.exe;vcredist_x64.exe")
273 verify_bundle_symlinks(<bundle> <result_var> <info_var>)
275 Verifies that any symlinks found in the <bundle> bundle point to other
277 files that are already also in the bundle… Anything that points to an
278 external file causes this function to fail the verification.
279 CheckCCompilerFlag
281 Check whether the C compiler supports a given flag.
282 check_c_compiler_flag
284 check_c_compiler_flag(<flag> <var>)
286 Check that the <flag> is accepted by the compiler without a
288 diagnostic. Stores the result in an internal cache entry named
289 <var>.
290 This command temporarily sets the CMAKE_REQUIRED_DEFINITIONS variable
292 and calls the check_c_source_compiles macro from the CheckCSourceCom‐
293 piles module. See documentation of that module for a listing of vari‐
294 ables that can otherwise modify the build.
295 A positive result from this check indicates only that the compiler did
297 not issue a diagnostic message when given the flag. Whether the flag
298 has any effect or even a specific one is beyond the scope of this mod‐
299 ule.
300 NOTE:
302 Since the try_compile() command forwards flags from variables like
303 CMAKE_C_FLAGS, unknown flags in such variables may cause a false
304 negative for this check.
305 CheckCSourceCompiles
307 Check if given C source compiles and links into an executable.
308 check_c_source_compiles
310 check_c_source_compiles(<code> <resultVar>
312 [FAIL_REGEX <regex1> [<regex2>...]])
313 Check that the source supplied in <code> can be compiled as a C
315 source file and linked as an executable (so it must contain at
316 least a main() function). The result will be stored in the
317 internal cache variable specified by <resultVar>, with a boolean
318 true value for success and boolean false for failure. If
319 FAIL_REGEX is provided, then failure is determined by checking
320 if anything in the output matches any of the specified regular
321 expressions.
322 The underlying check is performed by the try_compile() command.
324 The compile and link commands can be influenced by setting any
325 of the following variables prior to calling check_c_source_com‐
326 piles():
327 CMAKE_REQUIRED_FLAGS
329 Additional flags to pass to the compiler. Note that the
330 contents of CMAKE_C_FLAGS and its associated configura‐
331 tion-specific variable are automatically added to the
332 compiler command before the contents of
333 CMAKE_REQUIRED_FLAGS.
334 CMAKE_REQUIRED_DEFINITIONS
336 A ;-list of compiler definitions of the form -DFOO or
337 -DFOO=bar. A definition for the name specified by
338 <resultVar> will also be added automatically.
339 CMAKE_REQUIRED_INCLUDES
341 A ;-list of header search paths to pass to the compiler.
342 These will be the only header search paths used by
343 try_compile(), i.e. the contents of the INCLUDE_DIRECTO‐
344 RIES directory property will be ignored.
345 CMAKE_REQUIRED_LINK_OPTIONS
347 A ;-list of options to add to the link command (see
348 try_compile() for further details).
349 CMAKE_REQUIRED_LIBRARIES
351 A ;-list of libraries to add to the link command. These
352 can be the name of system libraries or they can be
353 Imported Targets (see try_compile() for further details).
354 CMAKE_REQUIRED_QUIET
356 If this variable evaluates to a boolean true value, all
357 status messages associated with the check will be sup‐
358 pressed.
359 The check is only performed once, with the result cached in the
361 variable named by <resultVar>. Every subsequent CMake run will
362 re-use this cached value rather than performing the check again,
363 even if the <code> changes. In order to force the check to be
364 re-evaluated, the variable named by <resultVar> must be manually
365 removed from the cache.
366 CheckCSourceRuns
368 Check if given C source compiles and links into an executable and can
369 subsequently be run.
370 check_c_source_runs
372 check_c_source_runs(<code> <resultVar>)
374 Check that the source supplied in <code> can be compiled as a C
376 source file, linked as an executable and then run. The <code>
377 must contain at least a main() function. If the <code> could be
378 built and run successfully, the internal cache variable speci‐
379 fied by <resultVar> will be set to 1, otherwise it will be set
380 to an value that evaluates to boolean false (e.g. an empty
381 string or an error message).
382 The underlying check is performed by the try_run() command. The
384 compile and link commands can be influenced by setting any of
385 the following variables prior to calling check_c_source_runs():
386 CMAKE_REQUIRED_FLAGS
388 Additional flags to pass to the compiler. Note that the
389 contents of CMAKE_C_FLAGS and its associated configura‐
390 tion-specific variable are automatically added to the
391 compiler command before the contents of
392 CMAKE_REQUIRED_FLAGS.
393 CMAKE_REQUIRED_DEFINITIONS
395 A ;-list of compiler definitions of the form -DFOO or
396 -DFOO=bar. A definition for the name specified by
397 <resultVar> will also be added automatically.
398 CMAKE_REQUIRED_INCLUDES
400 A ;-list of header search paths to pass to the compiler.
401 These will be the only header search paths used by
402 try_run(), i.e. the contents of the INCLUDE_DIRECTORIES
403 directory property will be ignored.
404 CMAKE_REQUIRED_LINK_OPTIONS
406 A ;-list of options to add to the link command (see
407 try_run() for further details).
408 CMAKE_REQUIRED_LIBRARIES
410 A ;-list of libraries to add to the link command. These
411 can be the name of system libraries or they can be
412 Imported Targets (see try_run() for further details).
413 CMAKE_REQUIRED_QUIET
415 If this variable evaluates to a boolean true value, all
416 status messages associated with the check will be sup‐
417 pressed.
418 The check is only performed once, with the result cached in the
420 variable named by <resultVar>. Every subsequent CMake run will
421 re-use this cached value rather than performing the check again,
422 even if the <code> changes. In order to force the check to be
423 re-evaluated, the variable named by <resultVar> must be manually
424 removed from the cache.
425 CheckCXXCompilerFlag
427 Check whether the CXX compiler supports a given flag.
428 check_cxx_compiler_flag
430 check_cxx_compiler_flag(<flag> <var>)
432 Check that the <flag> is accepted by the compiler without a
434 diagnostic. Stores the result in an internal cache entry named
435 <var>.
436 This command temporarily sets the CMAKE_REQUIRED_DEFINITIONS variable
438 and calls the check_cxx_source_compiles macro from the CheckCXXSource‐
439 Compiles module. See documentation of that module for a listing of
440 variables that can otherwise modify the build.
441 A positive result from this check indicates only that the compiler did
443 not issue a diagnostic message when given the flag. Whether the flag
444 has any effect or even a specific one is beyond the scope of this mod‐
445 ule.
446 NOTE:
448 Since the try_compile() command forwards flags from variables like
449 CMAKE_CXX_FLAGS, unknown flags in such variables may cause a false
450 negative for this check.
451 CheckCXXSourceCompiles
453 Check if given C++ source compiles and links into an executable.
454 check_cxx_source_compiles
456 check_cxx_source_compiles(<code> <resultVar>
458 [FAIL_REGEX <regex1> [<regex2>...]])
459 Check that the source supplied in <code> can be compiled as a
461 C++ source file and linked as an executable (so it must contain
462 at least a main() function). The result will be stored in the
463 internal cache variable specified by <resultVar>, with a boolean
464 true value for success and boolean false for failure. If
465 FAIL_REGEX is provided, then failure is determined by checking
466 if anything in the output matches any of the specified regular
467 expressions.
468 The underlying check is performed by the try_compile() command.
470 The compile and link commands can be influenced by setting any
471 of the following variables prior to calling
472 check_cxx_source_compiles():
473 CMAKE_REQUIRED_FLAGS
475 Additional flags to pass to the compiler. Note that the
476 contents of CMAKE_CXX_FLAGS and its associated configura‐
477 tion-specific variable are automatically added to the
478 compiler command before the contents of
479 CMAKE_REQUIRED_FLAGS.
480 CMAKE_REQUIRED_DEFINITIONS
482 A ;-list of compiler definitions of the form -DFOO or
483 -DFOO=bar. A definition for the name specified by
484 <resultVar> will also be added automatically.
485 CMAKE_REQUIRED_INCLUDES
487 A ;-list of header search paths to pass to the compiler.
488 These will be the only header search paths used by
489 try_compile(), i.e. the contents of the INCLUDE_DIRECTO‐
490 RIES directory property will be ignored.
491 CMAKE_REQUIRED_LINK_OPTIONS
493 A ;-list of options to add to the link command (see
494 try_compile() for further details).
495 CMAKE_REQUIRED_LIBRARIES
497 A ;-list of libraries to add to the link command. These
498 can be the name of system libraries or they can be
499 Imported Targets (see try_compile() for further details).
500 CMAKE_REQUIRED_QUIET
502 If this variable evaluates to a boolean true value, all
503 status messages associated with the check will be sup‐
504 pressed.
505 The check is only performed once, with the result cached in the
507 variable named by <resultVar>. Every subsequent CMake run will
508 re-use this cached value rather than performing the check again,
509 even if the <code> changes. In order to force the check to be
510 re-evaluated, the variable named by <resultVar> must be manually
511 removed from the cache.
512 CheckCXXSourceRuns
514 Check if given C++ source compiles and links into an executable and can
515 subsequently be run.
516 check_cxx_source_runs
518 check_cxx_source_runs(<code> <resultVar>)
520 Check that the source supplied in <code> can be compiled as a
522 C++ source file, linked as an executable and then run. The
523 <code> must contain at least a main() function. If the <code>
524 could be built and run successfully, the internal cache variable
525 specified by <resultVar> will be set to 1, otherwise it will be
526 set to an value that evaluates to boolean false (e.g. an empty
527 string or an error message).
528 The underlying check is performed by the try_run() command. The
530 compile and link commands can be influenced by setting any of
531 the following variables prior to calling
532 check_cxx_source_runs():
533 CMAKE_REQUIRED_FLAGS
535 Additional flags to pass to the compiler. Note that the
536 contents of CMAKE_CXX_FLAGS and its associated configura‐
537 tion-specific variable are automatically added to the
538 compiler command before the contents of
539 CMAKE_REQUIRED_FLAGS.
540 CMAKE_REQUIRED_DEFINITIONS
542 A ;-list of compiler definitions of the form -DFOO or
543 -DFOO=bar. A definition for the name specified by
544 <resultVar> will also be added automatically.
545 CMAKE_REQUIRED_INCLUDES
547 A ;-list of header search paths to pass to the compiler.
548 These will be the only header search paths used by
549 try_run(), i.e. the contents of the INCLUDE_DIRECTORIES
550 directory property will be ignored.
551 CMAKE_REQUIRED_LINK_OPTIONS
553 A ;-list of options to add to the link command (see
554 try_run() for further details).
555 CMAKE_REQUIRED_LIBRARIES
557 A ;-list of libraries to add to the link command. These
558 can be the name of system libraries or they can be
559 Imported Targets (see try_run() for further details).
560 CMAKE_REQUIRED_QUIET
562 If this variable evaluates to a boolean true value, all
563 status messages associated with the check will be sup‐
564 pressed.
565 The check is only performed once, with the result cached in the
567 variable named by <resultVar>. Every subsequent CMake run will
568 re-use this cached value rather than performing the check again,
569 even if the <code> changes. In order to force the check to be
570 re-evaluated, the variable named by <resultVar> must be manually
571 removed from the cache.
572 CheckCXXSymbolExists
574 Check if a symbol exists as a function, variable, or macro in C++.
575 check_cxx_symbol_exists
577 check_cxx_symbol_exists(<symbol> <files> <variable>)
579 Check that the <symbol> is available after including given
581 header <files> and store the result in a <variable>. Specify
582 the list of files in one argument as a semicolon-separated list.
583 check_cxx_symbol_exists() can be used to check for symbols as
584 seen by the C++ compiler, as opposed to check_symbol_exists(),
585 which always uses the C compiler.
586 If the header files define the symbol as a macro it is consid‐
588 ered available and assumed to work. If the header files declare
589 the symbol as a function or variable then the symbol must also
590 be available for linking. If the symbol is a type, enum value,
591 or C++ template it will not be recognized: consider using the
592 CheckTypeSize or CheckCXXSourceCompiles module instead.
593 NOTE:
595 This command is unreliable when <symbol> is (potentially) an over‐
596 loaded function. Since there is no reliable way to predict whether a
597 given function in the system environment may be defined as an over‐
598 loaded function or may be an overloaded function on other systems or
599 will become so in the future, it is generally advised to use the
600 CheckCXXSourceCompiles module for checking any function symbol
601 (unless somehow you surely know the checked function is not over‐
602 loaded on other systems or will not be so in the future).
603 The following variables may be set before calling this macro to modify
605 the way the check is run:
606 CMAKE_REQUIRED_FLAGS
608 string of compile command line flags.
609 CMAKE_REQUIRED_DEFINITIONS
611 a ;-list of macros to define (-DFOO=bar).
612 CMAKE_REQUIRED_INCLUDES
614 a ;-list of header search paths to pass to the compiler.
615 CMAKE_REQUIRED_LINK_OPTIONS
617 a ;-list of options to add to the link command.
618 CMAKE_REQUIRED_LIBRARIES
620 a ;-list of libraries to add to the link command. See policy
621 CMP0075.
622 CMAKE_REQUIRED_QUIET
624 execute quietly without messages.
625 For example:
627 include(CheckCXXSymbolExists)
629 # Check for macro SEEK_SET
631 check_cxx_symbol_exists(SEEK_SET "cstdio" HAVE_SEEK_SET)
632 # Check for function std::fopen
633 check_cxx_symbol_exists(std::fopen "cstdio" HAVE_STD_FOPEN)
634 CheckFortranCompilerFlag
636 Check whether the Fortran compiler supports a given flag.
637 check_fortran_compiler_flag
639 check_fortran_compiler_flag(<flag> <var>)
641 Check that the <flag> is accepted by the compiler without a
643 diagnostic. Stores the result in an internal cache entry named
644 <var>.
645 This command temporarily sets the CMAKE_REQUIRED_DEFINITIONS variable
647 and calls the check_fortran_source_compiles macro from the CheckFor‐
648 tranSourceCompiles module. See documentation of that module for a
649 listing of variables that can otherwise modify the build.
650 A positive result from this check indicates only that the compiler did
652 not issue a diagnostic message when given the flag. Whether the flag
653 has any effect or even a specific one is beyond the scope of this mod‐
654 ule.
655 NOTE:
657 Since the try_compile() command forwards flags from variables like
658 CMAKE_Fortran_FLAGS, unknown flags in such variables may cause a
659 false negative for this check.
660 CheckFortranFunctionExists
662 Check if a Fortran function exists.
663 CHECK_FORTRAN_FUNCTION_EXISTS
665 CHECK_FORTRAN_FUNCTION_EXISTS(<function> <result>)
667 where
669 <function>
671 the name of the Fortran function
672 <result>
674 variable to store the result; will be created as an
675 internal cache variable.
676 The following variables may be set before calling this macro to modify
678 the way the check is run:
679 CMAKE_REQUIRED_LINK_OPTIONS
681 A ;-list of options to add to the link command (see try_com‐
682 pile() for further details).
683 CMAKE_REQUIRED_LIBRARIES
685 A ;-list of libraries to add to the link command. These can be
686 the name of system libraries or they can be Imported Targets
687 (see try_compile() for further details).
688 CheckFortranSourceCompiles
690 Check if given Fortran source compiles and links into an executable.
691 check_fortran_source_compiles
693 check_fortran_source_compiles(<code> <resultVar>
695 [FAIL_REGEX <regex>...]
696 [SRC_EXT <extension>]
697 )
698 Checks that the source supplied in <code> can be compiled as a
700 Fortran source file and linked as an executable. The <code> must
701 be a Fortran program containing at least an end statement–for
702 example:
703 check_fortran_source_compiles("character :: b; error stop b; end" F2018ESTOPOK SRC_EXT F90)
705 This command can help avoid costly build processes when a com‐
707 piler lacks support for a necessary feature, or a particular
708 vendor library is not compatible with the Fortran compiler ver‐
709 sion being used. This generate-time check may advise the user of
710 such before the main build process. See also the check_for‐
711 tran_source_runs() command to actually run the compiled code.
712 The result will be stored in the internal cache variable
714 <resultVar>, with a boolean true value for success and boolean
715 false for failure.
716 If FAIL_REGEX is provided, then failure is determined by check‐
718 ing if anything in the output matches any of the specified regu‐
719 lar expressions.
720 By default, the test source file will be given a .F file exten‐
722 sion. The SRC_EXT option can be used to override this with
723 .<extension> instead– .F90 is a typical choice.
724 The underlying check is performed by the try_compile() command.
726 The compile and link commands can be influenced by setting any
727 of the following variables prior to calling check_for‐
728 tran_source_compiles():
729 CMAKE_REQUIRED_FLAGS
731 Additional flags to pass to the compiler. Note that the
732 contents of CMAKE_Fortran_FLAGS and its associated con‐
733 figuration-specific variable are automatically added to
734 the compiler command before the contents of
735 CMAKE_REQUIRED_FLAGS.
736 CMAKE_REQUIRED_DEFINITIONS
738 A ;-list of compiler definitions of the form -DFOO or
739 -DFOO=bar. A definition for the name specified by
740 <resultVar> will also be added automatically.
741 CMAKE_REQUIRED_INCLUDES
743 A ;-list of header search paths to pass to the compiler.
744 These will be the only header search paths used by
745 try_compile(), i.e. the contents of the INCLUDE_DIRECTO‐
746 RIES directory property will be ignored.
747 CMAKE_REQUIRED_LINK_OPTIONS
749 A ;-list of options to add to the link command (see
750 try_compile() for further details).
751 CMAKE_REQUIRED_LIBRARIES
753 A ;-list of libraries to add to the link command. These
754 can be the name of system libraries or they can be
755 Imported Targets (see try_compile() for further details).
756 CMAKE_REQUIRED_QUIET
758 If this variable evaluates to a boolean true value, all
759 status messages associated with the check will be sup‐
760 pressed.
761 The check is only performed once, with the result cached in the
763 variable named by <resultVar>. Every subsequent CMake run will
764 re-use this cached value rather than performing the check again,
765 even if the <code> changes. In order to force the check to be
766 re-evaluated, the variable named by <resultVar> must be manually
767 removed from the cache.
768 CheckFortranSourceRuns
770 Check if given Fortran source compiles and links into an executable and
771 can subsequently be run.
772 check_fortran_source_runs
774 check_fortran_source_runs(<code> <resultVar>
776 [SRC_EXT <extension>])
777 Check that the source supplied in <code> can be compiled as a
779 Fortran source file, linked as an executable and then run. The
780 <code> must be a Fortran program containing at least an end
781 statement–for example:
782 check_fortran_source_runs("real :: x[*]; call co_sum(x); end" F2018coarrayOK)
784 This command can help avoid costly build processes when a com‐
786 piler lacks support for a necessary feature, or a particular
787 vendor library is not compatible with the Fortran compiler ver‐
788 sion being used. Some of these failures only occur at runtime
789 instead of linktime, and a trivial runtime example can catch the
790 issue before the main build process.
791 If the <code> could be built and run successfully, the internal
793 cache variable specified by <resultVar> will be set to 1, other‐
794 wise it will be set to an value that evaluates to boolean false
795 (e.g. an empty string or an error message).
796 By default, the test source file will be given a .F90 file
798 extension. The SRC_EXT option can be used to override this with
799 .<extension> instead.
800 The underlying check is performed by the try_run() command. The
802 compile and link commands can be influenced by setting any of
803 the following variables prior to calling check_for‐
804 tran_source_runs():
805 CMAKE_REQUIRED_FLAGS
807 Additional flags to pass to the compiler. Note that the
808 contents of CMAKE_Fortran_FLAGS and its associated con‐
809 figuration-specific variable are automatically added to
810 the compiler command before the contents of
811 CMAKE_REQUIRED_FLAGS.
812 CMAKE_REQUIRED_DEFINITIONS
814 A ;-list of compiler definitions of the form -DFOO or
815 -DFOO=bar. A definition for the name specified by
816 <resultVar> will also be added automatically.
817 CMAKE_REQUIRED_INCLUDES
819 A ;-list of header search paths to pass to the compiler.
820 These will be the only header search paths used by
821 try_run(), i.e. the contents of the INCLUDE_DIRECTORIES
822 directory property will be ignored.
823 CMAKE_REQUIRED_LINK_OPTIONS
825 A ;-list of options to add to the link command (see
826 try_run() for further details).
827 CMAKE_REQUIRED_LIBRARIES
829 A ;-list of libraries to add to the link command. These
830 can be the name of system libraries or they can be
831 Imported Targets (see try_run() for further details).
832 CMAKE_REQUIRED_QUIET
834 If this variable evaluates to a boolean true value, all
835 status messages associated with the check will be sup‐
836 pressed.
837 The check is only performed once, with the result cached in the
839 variable named by <resultVar>. Every subsequent CMake run will
840 re-use this cached value rather than performing the check again,
841 even if the <code> changes. In order to force the check to be
842 re-evaluated, the variable named by <resultVar> must be manually
843 removed from the cache.
844 CheckFunctionExists
846 Check if a C function can be linked
847 check_function_exists
849 check_function_exists(<function> <variable>)
851 Checks that the <function> is provided by libraries on the sys‐
853 tem and store the result in a <variable>, which will be created
854 as an internal cache variable.
855 The following variables may be set before calling this macro to modify
857 the way the check is run:
858 CMAKE_REQUIRED_FLAGS
860 string of compile command line flags.
861 CMAKE_REQUIRED_DEFINITIONS
863 a ;-list of macros to define (-DFOO=bar).
864 CMAKE_REQUIRED_INCLUDES
866 a ;-list of header search paths to pass to the compiler.
867 CMAKE_REQUIRED_LINK_OPTIONS
869 a ;-list of options to add to the link command.
870 CMAKE_REQUIRED_LIBRARIES
872 a ;-list of libraries to add to the link command. See policy
873 CMP0075.
874 CMAKE_REQUIRED_QUIET
876 execute quietly without messages.
877 NOTE:
879 Prefer using CheckSymbolExists instead of this module, for the fol‐
880 lowing reasons:
881 · check_function_exists() can’t detect functions that are inlined in
883 headers or specified as a macro.
884 · check_function_exists() can’t detect anything in the 32-bit ver‐
886 sions of the Win32 API, because of a mismatch in calling conven‐
887 tions.
888 · check_function_exists() only verifies linking, it does not verify
890 that the function is declared in system headers.
891 CheckIPOSupported
893 Check whether the compiler supports an interprocedural optimization
894 (IPO/LTO). Use this before enabling the INTERPROCEDURAL_OPTIMIZATION
895 target property.
896 check_ipo_supported
898 check_ipo_supported([RESULT <result>] [OUTPUT <output>]
900 [LANGUAGES <lang>...])
901 Options are:
903 RESULT <result>
905 Set <result> variable to YES if IPO is supported by the
906 compiler and NO otherwise. If this option is not given
907 then the command will issue a fatal error if IPO is not
908 supported.
909 OUTPUT <output>
911 Set <output> variable with details about any error.
912 LANGUAGES <lang>...
914 Specify languages whose compilers to check. Languages C,
915 CXX, and Fortran are supported.
916 It makes no sense to use this module when CMP0069 is set to OLD so mod‐
918 ule will return error in this case. See policy CMP0069 for details.
919 Examples
921 check_ipo_supported() # fatal error if IPO is not supported
922 set_property(TARGET foo PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
923 # Optional IPO. Do not use IPO if it's not supported by compiler.
925 check_ipo_supported(RESULT result OUTPUT output)
926 if(result)
927 set_property(TARGET foo PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
928 else()
929 message(WARNING "IPO is not supported: ${output}")
930 endif()
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 CheckLanguage
1052 Check if a language can be enabled
1053 Usage:
1055 check_language(<lang>)
1057 where <lang> is a language that may be passed to enable_language() such
1059 as Fortran. If CMAKE_<LANG>_COMPILER is already defined the check does
1060 nothing. Otherwise it tries enabling the language in a test project.
1061 The result is cached in CMAKE_<LANG>_COMPILER as the compiler that was
1062 found, or NOTFOUND if the language cannot be enabled. For CUDA which
1063 can have an explicit host compiler, the cache CMAKE_CUDA_HOST_COMPILER
1064 variable will be set if it was required for compilation.
1065 Example:
1067 check_language(Fortran)
1069 if(CMAKE_Fortran_COMPILER)
1070 enable_language(Fortran)
1071 else()
1072 message(STATUS "No Fortran support")
1073 endif()
1074 CheckLibraryExists
1076 Check if the function exists.
1077 CHECK_LIBRARY_EXISTS
1079 CHECK_LIBRARY_EXISTS(LIBRARY FUNCTION LOCATION VARIABLE)
1081 LIBRARY - the name of the library you are looking for
1083 FUNCTION - the name of the function
1084 LOCATION - location where the library should be found
1085 VARIABLE - variable to store the result
1086 Will be created as an internal cache variable.
1087 The following variables may be set before calling this macro to modify
1089 the way the check is run:
1090 CMAKE_REQUIRED_FLAGS = string of compile command line flags
1092 CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
1093 CMAKE_REQUIRED_LINK_OPTIONS = list of options to pass to link command
1094 CMAKE_REQUIRED_LIBRARIES = list of libraries to link
1095 CMAKE_REQUIRED_QUIET = execute quietly without messages
1096 CheckOBJCCompilerFlag
1098 Check whether the Objective-C compiler supports a given flag.
1099 check_objc_compiler_flag
1101 check_objc_compiler_flag(<flag> <var>)
1103 Check that the <flag> is accepted by the compiler without a
1105 diagnostic. Stores the result in an internal cache entry named
1106 <var>.
1107 This command temporarily sets the CMAKE_REQUIRED_DEFINITIONS variable
1109 and calls the check_objc_source_compiles macro from the CheckOBJC‐
1110 SourceCompiles module. See documentation of that module for a listing
1111 of variables that can otherwise modify the build.
1112 A positive result from this check indicates only that the compiler did
1114 not issue a diagnostic message when given the flag. Whether the flag
1115 has any effect or even a specific one is beyond the scope of this mod‐
1116 ule.
1117 NOTE:
1119 Since the try_compile() command forwards flags from variables like
1120 CMAKE_OBJC_FLAGS, unknown flags in such variables may cause a false
1121 negative for this check.
1122 CheckOBJCSourceCompiles
1124 Check if given Objective-C source compiles and links into an exe‐
1125 cutable.
1126 check_objc_source_compiles
1128 check_objc_source_compiles(<code> <resultVar>
1130 [FAIL_REGEX <regex1> [<regex2>...]])
1131 Check that the source supplied in <code> can be compiled as a
1133 Objectie-C source file and linked as an executable (so it must
1134 contain at least a main() function). The result will be stored
1135 in the internal cache variable specified by <resultVar>, with a
1136 boolean true value for success and boolean false for failure. If
1137 FAIL_REGEX is provided, then failure is determined by checking
1138 if anything in the output matches any of the specified regular
1139 expressions.
1140 The underlying check is performed by the try_compile() command.
1142 The compile and link commands can be influenced by setting any
1143 of the following variables prior to calling
1144 check_objc_source_compiles():
1145 CMAKE_REQUIRED_FLAGS
1147 Additional flags to pass to the compiler. Note that the
1148 contents of CMAKE_OBJC_FLAGS and its associated configu‐
1149 ration-specific variable are automatically added to the
1150 compiler command before the contents of
1151 CMAKE_REQUIRED_FLAGS.
1152 CMAKE_REQUIRED_DEFINITIONS
1154 A ;-list of compiler definitions of the form -DFOO or
1155 -DFOO=bar. A definition for the name specified by
1156 <resultVar> will also be added automatically.
1157 CMAKE_REQUIRED_INCLUDES
1159 A ;-list of header search paths to pass to the compiler.
1160 These will be the only header search paths used by
1161 try_compile(), i.e. the contents of the INCLUDE_DIRECTO‐
1162 RIES directory property will be ignored.
1163 CMAKE_REQUIRED_LINK_OPTIONS
1165 A ;-list of options to add to the link command (see
1166 try_compile() for further details).
1167 CMAKE_REQUIRED_LIBRARIES
1169 A ;-list of libraries to add to the link command. These
1170 can be the name of system libraries or they can be
1171 Imported Targets (see try_compile() for further details).
1172 CMAKE_REQUIRED_QUIET
1174 If this variable evaluates to a boolean true value, all
1175 status messages associated with the check will be sup‐
1176 pressed.
1177 The check is only performed once, with the result cached in the
1179 variable named by <resultVar>. Every subsequent CMake run will
1180 re-use this cached value rather than performing the check again,
1181 even if the <code> changes. In order to force the check to be
1182 re-evaluated, the variable named by <resultVar> must be manually
1183 removed from the cache.
1184 CheckOBJCSourceRuns
1186 Check if given Objective-C source compiles and links into an executable
1187 and can subsequently be run.
1188 check_objc_source_runs
1190 check_objc_source_runs(<code> <resultVar>)
1192 Check that the source supplied in <code> can be compiled as a
1194 Objective-C source file, linked as an executable and then run.
1195 The <code> must contain at least a main() function. If the
1196 <code> could be built and run successfully, the internal cache
1197 variable specified by <resultVar> will be set to 1, otherwise it
1198 will be set to an value that evaluates to boolean false (e.g. an
1199 empty string or an error message).
1200 The underlying check is performed by the try_run() command. The
1202 compile and link commands can be influenced by setting any of
1203 the following variables prior to calling
1204 check_objc_source_runs():
1205 CMAKE_REQUIRED_FLAGS
1207 Additional flags to pass to the compiler. Note that the
1208 contents of CMAKE_OBJC_FLAGS and its associated configu‐
1209 ration-specific variable are automatically added to the
1210 compiler command before the contents of
1211 CMAKE_REQUIRED_FLAGS.
1212 CMAKE_REQUIRED_DEFINITIONS
1214 A ;-list of compiler definitions of the form -DFOO or
1215 -DFOO=bar. A definition for the name specified by
1216 <resultVar> will also be added automatically.
1217 CMAKE_REQUIRED_INCLUDES
1219 A ;-list of header search paths to pass to the compiler.
1220 These will be the only header search paths used by
1221 try_run(), i.e. the contents of the INCLUDE_DIRECTORIES
1222 directory property will be ignored.
1223 CMAKE_REQUIRED_LINK_OPTIONS
1225 A ;-list of options to add to the link command (see
1226 try_run() for further details).
1227 CMAKE_REQUIRED_LIBRARIES
1229 A ;-list of libraries to add to the link command. These
1230 can be the name of system libraries or they can be
1231 Imported Targets (see try_run() for further details).
1232 CMAKE_REQUIRED_QUIET
1234 If this variable evaluates to a boolean true value, all
1235 status messages associated with the check will be sup‐
1236 pressed.
1237 The check is only performed once, with the result cached in the
1239 variable named by <resultVar>. Every subsequent CMake run will
1240 re-use this cached value rather than performing the check again,
1241 even if the <code> changes. In order to force the check to be
1242 re-evaluated, the variable named by <resultVar> must be manually
1243 removed from the cache.
1244 CheckOBJCXXCompilerFlag
1246 Check whether the Objective-C++ compiler supports a given flag.
1247 check_objcxx_compiler_flag
1249 check_objcxx_compiler_flag(<flag> <var>)
1251 Check that the <flag> is accepted by the compiler without a
1253 diagnostic. Stores the result in an internal cache entry named
1254 <var>.
1255 This command temporarily sets the CMAKE_REQUIRED_DEFINITIONS variable
1257 and calls the check_objcxx_source_compiles macro from the CheckOB‐
1258 JCXXSourceCompiles module. See documentation of that module for a
1259 listing of variables that can otherwise modify the build.
1260 A positive result from this check indicates only that the compiler did
1262 not issue a diagnostic message when given the flag. Whether the flag
1263 has any effect or even a specific one is beyond the scope of this mod‐
1264 ule.
1265 NOTE:
1267 Since the try_compile() command forwards flags from variables like
1268 CMAKE_OBJCXX_FLAGS, unknown flags in such variables may cause a
1269 false negative for this check.
1270 CheckOBJCXXSourceCompiles
1272 Check if given Objective-C++ source compiles and links into an exe‐
1273 cutable.
1274 check_objcxx_source_compiles
1276 check_objcxx_source_compiles(<code> <resultVar>
1278 [FAIL_REGEX <regex1> [<regex2>...]])
1279 Check that the source supplied in <code> can be compiled as a
1281 Objective-C++ source file and linked as an executable (so it
1282 must contain at least a main() function). The result will be
1283 stored in the internal cache variable specified by <resultVar>,
1284 with a boolean true value for success and boolean false for
1285 failure. If FAIL_REGEX is provided, then failure is determined
1286 by checking if anything in the output matches any of the speci‐
1287 fied regular expressions.
1288 The underlying check is performed by the try_compile() command.
1290 The compile and link commands can be influenced by setting any
1291 of the following variables prior to calling
1292 check_objcxx_source_compiles():
1293 CMAKE_REQUIRED_FLAGS
1295 Additional flags to pass to the compiler. Note that the
1296 contents of CMAKE_OBJCXX_FLAGS and its associated config‐
1297 uration-specific variable are automatically added to the
1298 compiler command before the contents of
1299 CMAKE_REQUIRED_FLAGS.
1300 CMAKE_REQUIRED_DEFINITIONS
1302 A ;-list of compiler definitions of the form -DFOO or
1303 -DFOO=bar. A definition for the name specified by
1304 <resultVar> will also be added automatically.
1305 CMAKE_REQUIRED_INCLUDES
1307 A ;-list of header search paths to pass to the compiler.
1308 These will be the only header search paths used by
1309 try_compile(), i.e. the contents of the INCLUDE_DIRECTO‐
1310 RIES directory property will be ignored.
1311 CMAKE_REQUIRED_LINK_OPTIONS
1313 A ;-list of options to add to the link command (see
1314 try_compile() for further details).
1315 CMAKE_REQUIRED_LIBRARIES
1317 A ;-list of libraries to add to the link command. These
1318 can be the name of system libraries or they can be
1319 Imported Targets (see try_compile() for further details).
1320 CMAKE_REQUIRED_QUIET
1322 If this variable evaluates to a boolean true value, all
1323 status messages associated with the check will be sup‐
1324 pressed.
1325 The check is only performed once, with the result cached in the
1327 variable named by <resultVar>. Every subsequent CMake run will
1328 re-use this cached value rather than performing the check again,
1329 even if the <code> changes. In order to force the check to be
1330 re-evaluated, the variable named by <resultVar> must be manually
1331 removed from the cache.
1332 CheckOBJCXXSourceRuns
1334 Check if given Objective-C++ source compiles and links into an exe‐
1335 cutable and can subsequently be run.
1336 check_objcxx_source_runs
1338 check_objcxx_source_runs(<code> <resultVar>)
1340 Check that the source supplied in <code> can be compiled as a
1342 Objective-C++ source file, linked as an executable and then run.
1343 The <code> must contain at least a main() function. If the
1344 <code> could be built and run successfully, the internal cache
1345 variable specified by <resultVar> will be set to 1, otherwise it
1346 will be set to an value that evaluates to boolean false (e.g. an
1347 empty string or an error message).
1348 The underlying check is performed by the try_run() command. The
1350 compile and link commands can be influenced by setting any of
1351 the following variables prior to calling
1352 check_objcxx_source_runs():
1353 CMAKE_REQUIRED_FLAGS
1355 Additional flags to pass to the compiler. Note that the
1356 contents of CMAKE_OBJCXX_FLAGS and its associated config‐
1357 uration-specific variable are automatically added to the
1358 compiler command before the contents of
1359 CMAKE_REQUIRED_FLAGS.
1360 CMAKE_REQUIRED_DEFINITIONS
1362 A ;-list of compiler definitions of the form -DFOO or
1363 -DFOO=bar. A definition for the name specified by
1364 <resultVar> will also be added automatically.
1365 CMAKE_REQUIRED_INCLUDES
1367 A ;-list of header search paths to pass to the compiler.
1368 These will be the only header search paths used by
1369 try_run(), i.e. the contents of the INCLUDE_DIRECTORIES
1370 directory property will be ignored.
1371 CMAKE_REQUIRED_LINK_OPTIONS
1373 A ;-list of options to add to the link command (see
1374 try_run() for further details).
1375 CMAKE_REQUIRED_LIBRARIES
1377 A ;-list of libraries to add to the link command. These
1378 can be the name of system libraries or they can be
1379 Imported Targets (see try_run() for further details).
1380 CMAKE_REQUIRED_QUIET
1382 If this variable evaluates to a boolean true value, all
1383 status messages associated with the check will be sup‐
1384 pressed.
1385 The check is only performed once, with the result cached in the
1387 variable named by <resultVar>. Every subsequent CMake run will
1388 re-use this cached value rather than performing the check again,
1389 even if the <code> changes. In order to force the check to be
1390 re-evaluated, the variable named by <resultVar> must be manually
1391 removed from the cache.
1392 CheckPIESupported
1394 Check whether the linker supports Position Independent Code (PIE) or No
1395 Position Independent Code (NO_PIE) for executables. Use this to ensure
1396 that the POSITION_INDEPENDENT_CODE target property for executables will
1397 be honored at link time.
1398 check_pie_supported
1400 check_pie_supported([OUTPUT_VARIABLE <output>]
1402 [LANGUAGES <lang>...])
1403 Options are:
1405 OUTPUT_VARIABLE <output>
1407 Set <output> variable with details about any error.
1408 LANGUAGES <lang>...
1410 Check the linkers used for each of the specified lan‐
1411 guages. Supported languages are C, CXX, and Fortran.
1412 It makes no sense to use this module when CMP0083 is set to OLD, so the
1414 command will return an error in this case. See policy CMP0083 for
1415 details.
1416 Variables
1418 For each language checked, two boolean cache variables are defined.
1419 CMAKE_<lang>_LINK_PIE_SUPPORTED
1421 Set to YES if PIE is supported by the linker and NO other‐
1422 wise.
1423 CMAKE_<lang>_LINK_NO_PIE_SUPPORTED
1425 Set to YES if NO_PIE is supported by the linker and NO other‐
1426 wise.
1427 Examples
1429 check_pie_supported()
1430 set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE)
1431 # Retrieve any error message.
1433 check_pie_supported(OUTPUT_VARIABLE output LANGUAGES C)
1434 set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE)
1435 if(NOT CMAKE_C_LINK_PIE_SUPPORTED)
1436 message(WARNING "PIE is not supported at link time: ${output}.\n"
1437 "PIE link options will not be passed to linker.")
1438 endif()
1439 CheckPrototypeDefinition
1441 Check if the prototype we expect is correct.
1442 check_prototype_definition
1444 check_prototype_definition(FUNCTION PROTOTYPE RETURN HEADER VARIABLE)
1446 FUNCTION - The name of the function (used to check if prototype exists)
1448 PROTOTYPE- The prototype to check.
1449 RETURN - The return value of the function.
1450 HEADER - The header files required.
1451 VARIABLE - The variable to store the result.
1452 Will be created as an internal cache variable.
1453 Example:
1455 check_prototype_definition(getpwent_r
1457 "struct passwd *getpwent_r(struct passwd *src, char *buf, int buflen)"
1458 "NULL"
1459 "unistd.h;pwd.h"
1460 SOLARIS_GETPWENT_R)
1461 The following variables may be set before calling this function to mod‐
1463 ify the way the check is run:
1464 CMAKE_REQUIRED_FLAGS = string of compile command line flags
1466 CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
1467 CMAKE_REQUIRED_INCLUDES = list of include directories
1468 CMAKE_REQUIRED_LINK_OPTIONS = list of options to pass to link command
1469 CMAKE_REQUIRED_LIBRARIES = list of libraries to link
1470 CMAKE_REQUIRED_QUIET = execute quietly without messages
1471 CheckStructHasMember
1473 Check if the given struct or class has the specified member variable
1474 CHECK_STRUCT_HAS_MEMBER
1476 CHECK_STRUCT_HAS_MEMBER(<struct> <member> <header> <variable>
1478 [LANGUAGE <language>])
1479 <struct> - the name of the struct or class you are interested in
1481 <member> - the member which existence you want to check
1482 <header> - the header(s) where the prototype should be declared
1483 <variable> - variable to store the result
1484 <language> - the compiler to use (C or CXX)
1485 The following variables may be set before calling this macro to modify
1487 the way the check is run:
1488 CMAKE_REQUIRED_FLAGS = string of compile command line flags
1490 CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
1491 CMAKE_REQUIRED_INCLUDES = list of include directories
1492 CMAKE_REQUIRED_LINK_OPTIONS = list of options to pass to link command
1493 CMAKE_REQUIRED_LIBRARIES = list of libraries to link
1494 CMAKE_REQUIRED_QUIET = execute quietly without messages
1495 Example:
1497 CHECK_STRUCT_HAS_MEMBER("struct timeval" tv_sec sys/select.h
1499 HAVE_TIMEVAL_TV_SEC LANGUAGE C)
1500 CheckSymbolExists
1502 Provides a macro to check if a symbol exists as a function, variable,
1503 or macro in C.
1504 check_symbol_exists
1506 check_symbol_exists(<symbol> <files> <variable>)
1508 Check that the <symbol> is available after including given
1510 header <files> and store the result in a <variable>. Specify
1511 the list of files in one argument as a semicolon-separated list.
1512 <variable> will be created as an internal cache variable.
1513 If the header files define the symbol as a macro it is considered
1515 available and assumed to work. If the header files declare the symbol
1516 as a function or variable then the symbol must also be available for
1517 linking (so intrinsics may not be detected). If the symbol is a type,
1518 enum value, or intrinsic it will not be recognized (consider using
1519 CheckTypeSize or CheckCSourceCompiles). If the check needs to be done
1520 in C++, consider using CheckCXXSymbolExists instead.
1521 The following variables may be set before calling this macro to modify
1523 the way the check is run:
1524 CMAKE_REQUIRED_FLAGS
1526 string of compile command line flags.
1527 CMAKE_REQUIRED_DEFINITIONS
1529 a ;-list of macros to define (-DFOO=bar).
1530 CMAKE_REQUIRED_INCLUDES
1532 a ;-list of header search paths to pass to the compiler.
1533 CMAKE_REQUIRED_LINK_OPTIONS
1535 a ;-list of options to add to the link command.
1536 CMAKE_REQUIRED_LIBRARIES
1538 a ;-list of libraries to add to the link command. See policy
1539 CMP0075.
1540 CMAKE_REQUIRED_QUIET
1542 execute quietly without messages.
1543 For example:
1545 include(CheckSymbolExists)
1547 # Check for macro SEEK_SET
1549 check_symbol_exists(SEEK_SET "stdio.h" HAVE_SEEK_SET)
1550 # Check for function fopen
1551 check_symbol_exists(fopen "stdio.h" HAVE_FOPEN)
1552 CheckTypeSize
1554 Check sizeof a type
1555 CHECK_TYPE_SIZE
1557 CHECK_TYPE_SIZE(TYPE VARIABLE [BUILTIN_TYPES_ONLY]
1559 [LANGUAGE <language>])
1560 Check if the type exists and determine its size. On return,
1562 HAVE_${VARIABLE} holds the existence of the type, and ${VARI‐
1563 ABLE} holds one of the following:
1564 <size> = type has non-zero size <size>
1566 "0" = type has arch-dependent size (see below)
1567 "" = type does not exist
1568 Both HAVE_${VARIABLE} and ${VARIABLE} will be created as inter‐
1570 nal cache variables.
1571 Furthermore, the variable ${VARIABLE}_CODE holds C preprocessor
1573 code to define the macro ${VARIABLE} to the size of the type, or
1574 leave the macro undefined if the type does not exist.
1575 The variable ${VARIABLE} may be 0 when CMAKE_OSX_ARCHITECTURES
1577 has multiple architectures for building OS X universal binaries.
1578 This indicates that the type size varies across architectures.
1579 In this case ${VARIABLE}_CODE contains C preprocessor tests map‐
1580 ping from each architecture macro to the corresponding type
1581 size. The list of architecture macros is stored in ${VARI‐
1582 ABLE}_KEYS, and the value for each key is stored in ${VARI‐
1583 ABLE}-${KEY}.
1584 If the BUILTIN_TYPES_ONLY option is not given, the macro checks
1586 for headers <sys/types.h>, <stdint.h>, and <stddef.h>, and saves
1587 results in HAVE_SYS_TYPES_H, HAVE_STDINT_H, and HAVE_STDDEF_H.
1588 The type size check automatically includes the available head‐
1589 ers, thus supporting checks of types defined in the headers.
1590 If LANGUAGE is set, the specified compiler will be used to per‐
1592 form the check. Acceptable values are C and CXX.
1593 Despite the name of the macro you may use it to check the size of more
1595 complex expressions, too. To check e.g. for the size of a struct mem‐
1596 ber you can do something like this:
1597 check_type_size("((struct something*)0)->member" SIZEOF_MEMBER)
1599 The following variables may be set before calling this macro to modify
1601 the way the check is run:
1602 CMAKE_REQUIRED_FLAGS = string of compile command line flags
1604 CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
1605 CMAKE_REQUIRED_INCLUDES = list of include directories
1606 CMAKE_REQUIRED_LINK_OPTIONS = list of options to pass to link command
1607 CMAKE_REQUIRED_LIBRARIES = list of libraries to link
1608 CMAKE_REQUIRED_QUIET = execute quietly without messages
1609 CMAKE_EXTRA_INCLUDE_FILES = list of extra headers to include
1610 CheckVariableExists
1612 Check if the variable exists.
1613 CHECK_VARIABLE_EXISTS
1615 CHECK_VARIABLE_EXISTS(VAR VARIABLE)
1617 VAR - the name of the variable
1619 VARIABLE - variable to store the result
1620 Will be created as an internal cache variable.
1621 This macro is only for C variables.
1623 The following variables may be set before calling this macro to modify
1625 the way the check is run:
1626 CMAKE_REQUIRED_FLAGS = string of compile command line flags
1628 CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
1629 CMAKE_REQUIRED_LINK_OPTIONS = list of options to pass to link command
1630 CMAKE_REQUIRED_LIBRARIES = list of libraries to link
1631 CMAKE_REQUIRED_QUIET = execute quietly without messages
1632 CMakeAddFortranSubdirectory
1634 Add a fortran-only subdirectory, find a fortran compiler, and build.
1635 The cmake_add_fortran_subdirectory function adds a subdirectory to a
1637 project that contains a fortran-only subproject. The module will check
1638 the current compiler and see if it can support fortran. If no fortran
1639 compiler is found and the compiler is MSVC, then this module will find
1640 the MinGW gfortran. It will then use an external project to build with
1641 the MinGW tools. It will also create imported targets for the
1642 libraries created. This will only work if the fortran code is built
1643 into a dll, so BUILD_SHARED_LIBS is turned on in the project. In addi‐
1644 tion the CMAKE_GNUtoMS option is set to on, so that Microsoft .lib
1645 files are created. Usage is as follows:
1646 cmake_add_fortran_subdirectory(
1648 <subdir> # name of subdirectory
1649 PROJECT <project_name> # project name in subdir top CMakeLists.txt
1650 ARCHIVE_DIR <dir> # dir where project places .lib files
1651 RUNTIME_DIR <dir> # dir where project places .dll files
1652 LIBRARIES <lib>... # names of library targets to import
1653 LINK_LIBRARIES # link interface libraries for LIBRARIES
1654 [LINK_LIBS <lib> <dep>...]...
1655 CMAKE_COMMAND_LINE ... # extra command line flags to pass to cmake
1656 NO_EXTERNAL_INSTALL # skip installation of external project
1657 )
1658 Relative paths in ARCHIVE_DIR and RUNTIME_DIR are interpreted with
1660 respect to the build directory corresponding to the source directory in
1661 which the function is invoked.
1662 Limitations:
1664 NO_EXTERNAL_INSTALL is required for forward compatibility with a future
1666 version that supports installation of the external project binaries
1667 during make install.
1668 CMakeBackwardCompatibilityCXX
1670 define a bunch of backwards compatibility variables
1671 CMAKE_ANSI_CXXFLAGS - flag for ansi c++
1673 CMAKE_HAS_ANSI_STRING_STREAM - has <strstream>
1674 include(TestForANSIStreamHeaders)
1675 include(CheckIncludeFileCXX)
1676 include(TestForSTDNamespace)
1677 include(TestForANSIForScope)
1678 CMakeDependentOption
1680 Macro to provide an option dependent on other options.
1681 This macro presents an option to the user only if a set of other condi‐
1683 tions are true. When the option is not presented a default value is
1684 used, but any value set by the user is preserved for when the option is
1685 presented again. Example invocation:
1686 CMAKE_DEPENDENT_OPTION(USE_FOO "Use Foo" ON
1688 "USE_BAR;NOT USE_ZOT" OFF)
1689 If USE_BAR is true and USE_ZOT is false, this provides an option called
1691 USE_FOO that defaults to ON. Otherwise, it sets USE_FOO to OFF. If
1692 the status of USE_BAR or USE_ZOT ever changes, any value for the
1693 USE_FOO option is saved so that when the option is re-enabled it
1694 retains its old value. Each element in the fourth parameter is evalu‐
1695 ated as an if-condition, so Condition Syntax can be used.
1696 CMakeFindDependencyMacro
1698 find_dependency
1699 The find_dependency() macro wraps a find_package() call for a
1700 package dependency:
1701 find_dependency(<dep> [...])
1703 It is designed to be used in a Package Configuration File
1705 (<PackageName>Config.cmake). find_dependency forwards the cor‐
1706 rect parameters for QUIET and REQUIRED which were passed to the
1707 original find_package() call. Any additional arguments speci‐
1708 fied are forwarded to find_package().
1709 If the dependency could not be found it sets an informative
1711 diagnostic message and calls return() to end processing of the
1712 calling package configuration file and return to the find_pack‐
1713 age() command that loaded it.
1714 NOTE:
1716 The call to return() makes this macro unsuitable to call from
1717 Find Modules.
1718 CMakeFindFrameworks
1720 helper module to find OSX frameworks
1721 This module reads hints about search locations from variables:
1723 CMAKE_FIND_FRAMEWORK_EXTRA_LOCATIONS - Extra directories
1725 CMakeFindPackageMode
1727 This file is executed by cmake when invoked with –find-package. It
1728 expects that the following variables are set using -D:
1729 NAME name of the package
1731 COMPILER_ID
1733 the CMake compiler ID for which the result is, i.e.
1734 GNU/Intel/Clang/MSVC, etc.
1735 LANGUAGE
1737 language for which the result will be used, i.e. C/CXX/For‐
1738 tran/ASM
1739 MODE
1741 EXIST only check for existence of the given package
1743 COMPILE
1745 print the flags needed for compiling an object file which
1746 uses the given package
1747 LINK print the flags needed for linking when using the given
1749 package
1750 QUIET if TRUE, don’t print anything
1752 CMakeGraphVizOptions
1754 The builtin graphviz support of CMake.
1755 Variables specific to the graphviz support
1757 CMake can generate graphviz files, showing the dependencies between the
1758 targets in a project and also external libraries which are linked
1759 against. When CMake is run with the --graphviz=foo.dot option, it will
1760 produce:
1761 · a foo.dot file showing all dependencies in the project
1763 · a foo.dot.<target> file for each target, file showing on which other
1765 targets the respective target depends
1766 · a foo.dot.<target>.dependers file, showing which other targets depend
1768 on the respective target
1769 The different dependency types PUBLIC, PRIVATE and INTERFACE are repre‐
1771 sented as solid, dashed and dotted edges.
1772 This can result in huge graphs. Using the file CMakeGraphVizOp‐
1774 tions.cmake the look and content of the generated graphs can be influ‐
1775 enced. This file is searched first in CMAKE_BINARY_DIR and then in
1776 CMAKE_SOURCE_DIR. If found, it is read and the variables set in it are
1777 used to adjust options for the generated graphviz files.
1778 GRAPHVIZ_GRAPH_TYPE
1780 The graph type.
1781 · Mandatory : NO
1783 · Default : “digraph”
1785 Valid graph types are:
1787 · “graph” : Nodes are joined with lines
1789 · “digraph” : Nodes are joined with arrows showing direction
1791 · “strict graph” : Like “graph” but max one line between each
1793 node
1794 · “strict digraph” : Like “graph” but max one line between each
1796 node in each direction
1797 GRAPHVIZ_GRAPH_NAME
1799 The graph name.
1800 · Mandatory : NO
1802 · Default : “GG”
1804 GRAPHVIZ_GRAPH_HEADER
1806 The header written at the top of the graphviz file.
1807 · Mandatory : NO
1809 · Default : “node [n fontsize = “12”];”
1811 GRAPHVIZ_NODE_PREFIX
1813 The prefix for each node in the graphviz file.
1814 · Mandatory : NO
1816 · Default : “node”
1818 GRAPHVIZ_EXECUTABLES
1820 Set this to FALSE to exclude executables from the generated
1821 graphs.
1822 · Mandatory : NO
1824 · Default : TRUE
1826 GRAPHVIZ_STATIC_LIBS
1828 Set this to FALSE to exclude static libraries from the generated
1829 graphs.
1830 · Mandatory : NO
1832 · Default : TRUE
1834 GRAPHVIZ_SHARED_LIBS
1836 Set this to FALSE to exclude shared libraries from the generated
1837 graphs.
1838 · Mandatory : NO
1840 · Default : TRUE
1842 GRAPHVIZ_MODULE_LIBS
1844 Set this to FALSE to exclude module libraries from the generated
1845 graphs.
1846 · Mandatory : NO
1848 · Default : TRUE
1850 GRAPHVIZ_EXTERNAL_LIBS
1852 Set this to FALSE to exclude external libraries from the gener‐
1853 ated graphs.
1854 · Mandatory : NO
1856 · Default : TRUE
1858 GRAPHVIZ_IGNORE_TARGETS
1860 A list of regular expressions for ignoring targets.
1861 · Mandatory : NO
1863 · Default : empty
1865 GRAPHVIZ_GENERATE_PER_TARGET
1867 Set this to FALSE to exclude per target graphs foo.dot.<target>.
1868 · Mandatory : NO
1870 · Default : TRUE
1872 GRAPHVIZ_GENERATE_DEPENDERS
1874 Set this to FALSE to exclude depender graphs foo.dot.<tar‐
1875 get>.dependers.
1876 · Mandatory : NO
1878 · Default : TRUE
1880 CMakePackageConfigHelpers
1882 Helpers functions for creating config files that can be included by
1883 other projects to find and use a package.
1884 Adds the configure_package_config_file() and
1886 write_basic_package_version_file() commands.
1887 Generating a Package Configuration File
1889 configure_package_config_file
1890 Create a config file for a project:
1891 configure_package_config_file(<input> <output>
1893 INSTALL_DESTINATION <path>
1894 [PATH_VARS <var1> <var2> ... <varN>]
1895 [NO_SET_AND_CHECK_MACRO]
1896 [NO_CHECK_REQUIRED_COMPONENTS_MACRO]
1897 [INSTALL_PREFIX <path>]
1898 )
1899 configure_package_config_file() should be used instead of the plain
1901 configure_file() command when creating the <PackageName>Config.cmake or
1902 <PackageName>-config.cmake file for installing a project or library.
1903 It helps making the resulting package relocatable by avoiding hardcoded
1904 paths in the installed Config.cmake file.
1905 In a FooConfig.cmake file there may be code like this to make the
1907 install destinations know to the using project:
1908 set(FOO_INCLUDE_DIR "@CMAKE_INSTALL_FULL_INCLUDEDIR@" )
1910 set(FOO_DATA_DIR "@CMAKE_INSTALL_PREFIX@/@RELATIVE_DATA_INSTALL_DIR@" )
1911 set(FOO_ICONS_DIR "@CMAKE_INSTALL_PREFIX@/share/icons" )
1912 #...logic to determine installedPrefix from the own location...
1913 set(FOO_CONFIG_DIR "${installedPrefix}/@CONFIG_INSTALL_DIR@" )
1914 All 4 options shown above are not sufficient, since the first 3 hard‐
1916 code the absolute directory locations, and the 4th case works only if
1917 the logic to determine the installedPrefix is correct, and if CON‐
1918 FIG_INSTALL_DIR contains a relative path, which in general cannot be
1919 guaranteed. This has the effect that the resulting FooConfig.cmake
1920 file would work poorly under Windows and OSX, where users are used to
1921 choose the install location of a binary package at install time, inde‐
1922 pendent from how CMAKE_INSTALL_PREFIX was set at build/cmake time.
1923 Using configure_package_config_file helps. If used correctly, it makes
1925 the resulting FooConfig.cmake file relocatable. Usage:
1926 1. write a FooConfig.cmake.in file as you are used to
1928 2. insert a line containing only the string @PACKAGE_INIT@
1930 3. instead of set(FOO_DIR "@SOME_INSTALL_DIR@"), use set(FOO_DIR
1932 "@PACKAGE_SOME_INSTALL_DIR@") (this must be after the @PACKAGE_INIT@
1933 line)
1934 4. instead of using the normal configure_file(), use configure_pack‐
1936 age_config_file()
1937 The <input> and <output> arguments are the input and output file, the
1939 same way as in configure_file().
1940 The <path> given to INSTALL_DESTINATION must be the destination where
1942 the FooConfig.cmake file will be installed to. This path can either be
1943 absolute, or relative to the INSTALL_PREFIX path.
1944 The variables <var1> to <varN> given as PATH_VARS are the variables
1946 which contain install destinations. For each of them the macro will
1947 create a helper variable PACKAGE_<var...>. These helper variables must
1948 be used in the FooConfig.cmake.in file for setting the installed loca‐
1949 tion. They are calculated by configure_package_config_file so that
1950 they are always relative to the installed location of the package.
1951 This works both for relative and also for absolute locations. For
1952 absolute locations it works only if the absolute location is a subdi‐
1953 rectory of INSTALL_PREFIX.
1954 If the INSTALL_PREFIX argument is passed, this is used as base path to
1956 calculate all the relative paths. The <path> argument must be an abso‐
1957 lute path. If this argument is not passed, the CMAKE_INSTALL_PREFIX
1958 variable will be used instead. The default value is good when generat‐
1959 ing a FooConfig.cmake file to use your package from the install tree.
1960 When generating a FooConfig.cmake file to use your package from the
1961 build tree this option should be used.
1962 By default configure_package_config_file also generates two helper
1964 macros, set_and_check() and check_required_components() into the
1965 FooConfig.cmake file.
1966 set_and_check() should be used instead of the normal set() command for
1968 setting directories and file locations. Additionally to setting the
1969 variable it also checks that the referenced file or directory actually
1970 exists and fails with a FATAL_ERROR otherwise. This makes sure that
1971 the created FooConfig.cmake file does not contain wrong references.
1972 When using the NO_SET_AND_CHECK_MACRO, this macro is not generated into
1973 the FooConfig.cmake file.
1974 check_required_components(<PackageName>) should be called at the end of
1976 the FooConfig.cmake file. This macro checks whether all requested,
1977 non-optional components have been found, and if this is not the case,
1978 sets the Foo_FOUND variable to FALSE, so that the package is considered
1979 to be not found. It does that by testing the Foo_<Component>_FOUND
1980 variables for all requested required components. This macro should be
1981 called even if the package doesn’t provide any components to make sure
1982 users are not specifying components erroneously. When using the
1983 NO_CHECK_REQUIRED_COMPONENTS_MACRO option, this macro is not generated
1984 into the FooConfig.cmake file.
1985 For an example see below the documentation for
1987 write_basic_package_version_file().
1988 Generating a Package Version File
1990 write_basic_package_version_file
1991 Create a version file for a project:
1992 write_basic_package_version_file(<filename>
1994 [VERSION <major.minor.patch>]
1995 COMPATIBILITY <AnyNewerVersion|SameMajorVersion|SameMinorVersion|ExactVersion>
1996 [ARCH_INDEPENDENT] )
1997 Writes a file for use as <PackageName>ConfigVersion.cmake file to
1999 <filename>. See the documentation of find_package() for details on
2000 this.
2001 <filename> is the output filename, it should be in the build tree.
2003 <major.minor.patch> is the version number of the project to be
2004 installed.
2005 If no VERSION is given, the PROJECT_VERSION variable is used. If this
2007 hasn’t been set, it errors out.
2008 The COMPATIBILITY mode AnyNewerVersion means that the installed package
2010 version will be considered compatible if it is newer or exactly the
2011 same as the requested version. This mode should be used for packages
2012 which are fully backward compatible, also across major versions. If
2013 SameMajorVersion is used instead, then the behaviour differs from
2014 AnyNewerVersion in that the major version number must be the same as
2015 requested, e.g. version 2.0 will not be considered compatible if 1.0
2016 is requested. This mode should be used for packages which guarantee
2017 backward compatibility within the same major version. If SameMinorVer‐
2018 sion is used, the behaviour is the same as SameMajorVersion, but both
2019 major and minor version must be the same as requested, e.g version 0.2
2020 will not be compatible if 0.1 is requested. If ExactVersion is used,
2021 then the package is only considered compatible if the requested version
2022 matches exactly its own version number (not considering the tweak ver‐
2023 sion). For example, version 1.2.3 of a package is only considered com‐
2024 patible to requested version 1.2.3. This mode is for packages without
2025 compatibility guarantees. If your project has more elaborated version
2026 matching rules, you will need to write your own custom ConfigVer‐
2027 sion.cmake file instead of using this macro.
2028 If ARCH_INDEPENDENT is given, the installed package version will be
2030 considered compatible even if it was built for a different architecture
2031 than the requested architecture. Otherwise, an architecture check will
2032 be performed, and the package will be considered compatible only if the
2033 architecture matches exactly. For example, if the package is built for
2034 a 32-bit architecture, the package is only considered compatible if it
2035 is used on a 32-bit architecture, unless ARCH_INDEPENDENT is given, in
2036 which case the package is considered compatible on any architecture.
2037 NOTE:
2039 ARCH_INDEPENDENT is intended for header-only libraries or similar
2040 packages with no binaries.
2041 Internally, this macro executes configure_file() to create the result‐
2043 ing version file. Depending on the COMPATIBILITY, the corresponding
2044 BasicConfigVersion-<COMPATIBILITY>.cmake.in file is used. Please note
2045 that these files are internal to CMake and you should not call config‐
2046 ure_file() on them yourself, but they can be used as starting point to
2047 create more sophisticted custom ConfigVersion.cmake files.
2048 Example Generating Package Files
2050 Example using both configure_package_config_file() and
2051 write_basic_package_version_file():
2052 CMakeLists.txt:
2054 set(INCLUDE_INSTALL_DIR include/ ... CACHE )
2056 set(LIB_INSTALL_DIR lib/ ... CACHE )
2057 set(SYSCONFIG_INSTALL_DIR etc/foo/ ... CACHE )
2058 #...
2059 include(CMakePackageConfigHelpers)
2060 configure_package_config_file(FooConfig.cmake.in
2061 ${CMAKE_CURRENT_BINARY_DIR}/FooConfig.cmake
2062 INSTALL_DESTINATION ${LIB_INSTALL_DIR}/Foo/cmake
2063 PATH_VARS INCLUDE_INSTALL_DIR SYSCONFIG_INSTALL_DIR)
2064 write_basic_package_version_file(
2065 ${CMAKE_CURRENT_BINARY_DIR}/FooConfigVersion.cmake
2066 VERSION 1.2.3
2067 COMPATIBILITY SameMajorVersion )
2068 install(FILES ${CMAKE_CURRENT_BINARY_DIR}/FooConfig.cmake
2069 ${CMAKE_CURRENT_BINARY_DIR}/FooConfigVersion.cmake
2070 DESTINATION ${LIB_INSTALL_DIR}/Foo/cmake )
2071 FooConfig.cmake.in:
2073 set(FOO_VERSION x.y.z)
2075 ...
2076 @PACKAGE_INIT@
2077 ...
2078 set_and_check(FOO_INCLUDE_DIR "@PACKAGE_INCLUDE_INSTALL_DIR@")
2079 set_and_check(FOO_SYSCONFIG_DIR "@PACKAGE_SYSCONFIG_INSTALL_DIR@")
2080 check_required_components(Foo)
2082 CMakePrintHelpers
2084 Convenience functions for printing properties and variables, useful
2085 e.g. for debugging.
2086 cmake_print_properties([TARGETS target1 .. targetN]
2088 [SOURCES source1 .. sourceN]
2089 [DIRECTORIES dir1 .. dirN]
2090 [TESTS test1 .. testN]
2091 [CACHE_ENTRIES entry1 .. entryN]
2092 PROPERTIES prop1 .. propN )
2093 This function prints the values of the properties of the given targets,
2095 source files, directories, tests or cache entries. Exactly one of the
2096 scope keywords must be used. Example:
2097 cmake_print_properties(TARGETS foo bar PROPERTIES
2099 LOCATION INTERFACE_INCLUDE_DIRECTORIES)
2100 This will print the LOCATION and INTERFACE_INCLUDE_DIRECTORIES proper‐
2102 ties for both targets foo and bar.
2103 cmake_print_variables(var1 var2 .. varN)
2105 This function will print the name of each variable followed by its
2107 value. Example:
2108 cmake_print_variables(CMAKE_C_COMPILER CMAKE_MAJOR_VERSION DOES_NOT_EXIST)
2110 Gives:
2112 -- CMAKE_C_COMPILER="/usr/bin/gcc" ; CMAKE_MAJOR_VERSION="2" ; DOES_NOT_EXIST=""
2114 CMakePrintSystemInformation
2116 print system information
2117 This file can be used for diagnostic purposes just include it in a
2119 project to see various internal CMake variables.
2120 CMakePushCheckState
2122 This module defines three macros: CMAKE_PUSH_CHECK_STATE()
2123 CMAKE_POP_CHECK_STATE() and CMAKE_RESET_CHECK_STATE() These macros can
2124 be used to save, restore and reset (i.e., clear contents) the state of
2125 the variables CMAKE_REQUIRED_FLAGS, CMAKE_REQUIRED_DEFINITIONS,
2126 CMAKE_REQUIRED_LINK_OPTIONS, CMAKE_REQUIRED_LIBRARIES,
2127 CMAKE_REQUIRED_INCLUDES and CMAKE_EXTRA_INCLUDE_FILES used by the vari‐
2128 ous Check-files coming with CMake, like e.g. check_function_exists()
2129 etc. The variable contents are pushed on a stack, pushing multiple
2130 times is supported. This is useful e.g. when executing such tests in
2131 a Find-module, where they have to be set, but after the Find-module has
2132 been executed they should have the same value as they had before.
2133 CMAKE_PUSH_CHECK_STATE() macro receives optional argument RESET.
2135 Whether it’s specified, CMAKE_PUSH_CHECK_STATE() will set all
2136 CMAKE_REQUIRED_* variables to empty values, same as
2137 CMAKE_RESET_CHECK_STATE() call will do.
2138 Usage:
2140 cmake_push_check_state(RESET)
2142 set(CMAKE_REQUIRED_DEFINITIONS -DSOME_MORE_DEF)
2143 check_function_exists(...)
2144 cmake_reset_check_state()
2145 set(CMAKE_REQUIRED_DEFINITIONS -DANOTHER_DEF)
2146 check_function_exists(...)
2147 cmake_pop_check_state()
2148 CMakeVerifyManifest
2150 CMakeVerifyManifest.cmake
2151 This script is used to verify that embedded manifests and side by side
2153 manifests for a project match. To run this script, cd to a directory
2154 and run the script with cmake -P. On the command line you can pass in
2155 versions that are OK even if not found in the .manifest files. For
2156 example, cmake -Dallow_versions=8.0.50608.0 -PCmakeVerifyManifest.cmake
2157 could be used to allow an embedded manifest of 8.0.50608.0 to be used
2158 in a project even if that version was not found in the .manifest file.
2159 CPackComponent
2161 Build binary and source package installers
2162 Variables concerning CPack Components
2164 The CPackComponent module is the module which handles the component
2165 part of CPack. See CPack module for general information about CPack.
2166 For certain kinds of binary installers (including the graphical in‐
2168 stallers on macOS and Windows), CPack generates installers that allow
2169 users to select individual application components to install. The con‐
2170 tents of each of the components are identified by the COMPONENT argu‐
2171 ment of CMake’s INSTALL command. These components can be annotated
2172 with user-friendly names and descriptions, inter-component dependen‐
2173 cies, etc., and grouped in various ways to customize the resulting in‐
2174 staller. See the cpack_add_* commands, described below, for more
2175 information about component-specific installations.
2176 Component-specific installation allows users to select specific sets of
2178 components to install during the install process. Installation compo‐
2179 nents are identified by the COMPONENT argument of CMake’s INSTALL com‐
2180 mands, and should be further described by the following CPack commands:
2181 CPACK_COMPONENTS_ALL
2183 The list of component to install.
2184 The default value of this variable is computed by CPack and con‐
2186 tains all components defined by the project. The user may set
2187 it to only include the specified components.
2188 Instead of specifying all the desired components, it is possible
2190 to obtain a list of all defined components and then remove the
2191 unwanted ones from the list. The get_cmake_property() command
2192 can be used to obtain the COMPONENTS property, then the
2193 list(REMOVE_ITEM) command can be used to remove the unwanted
2194 ones. For example, to use all defined components except foo and
2195 bar:
2196 get_cmake_property(CPACK_COMPONENTS_ALL COMPONENTS)
2198 list(REMOVE_ITEM CPACK_COMPONENTS_ALL "foo" "bar")
2199 CPACK_<GENNAME>_COMPONENT_INSTALL
2201 Enable/Disable component install for CPack generator <GENNAME>.
2202 Each CPack Generator (RPM, DEB, ARCHIVE, NSIS, DMG, etc…) has a
2204 legacy default behavior. e.g. RPM builds monolithic whereas
2205 NSIS builds component. One can change the default behavior by
2206 setting this variable to 0/1 or OFF/ON.
2207 CPACK_COMPONENTS_GROUPING
2209 Specify how components are grouped for multi-package compo‐
2210 nent-aware CPack generators.
2211 Some generators like RPM or ARCHIVE family (TGZ, ZIP, …) gener‐
2213 ates several packages files when asked for component packaging.
2214 They group the component differently depending on the value of
2215 this variable:
2216 · ONE_PER_GROUP (default): creates one package file per compo‐
2218 nent group
2219 · ALL_COMPONENTS_IN_ONE : creates a single package with all
2221 (requested) components
2222 · IGNORE : creates one package per component, i.e. IGNORE compo‐
2224 nent group
2225 One can specify different grouping for different CPack generator
2227 by using a CPACK_PROJECT_CONFIG_FILE.
2228 CPACK_COMPONENT_<compName>_DISPLAY_NAME
2230 The name to be displayed for a component.
2231 CPACK_COMPONENT_<compName>_DESCRIPTION
2233 The description of a component.
2234 CPACK_COMPONENT_<compName>_GROUP
2236 The group of a component.
2237 CPACK_COMPONENT_<compName>_DEPENDS
2239 The dependencies (list of components) on which this component
2240 depends.
2241 CPACK_COMPONENT_<compName>_HIDDEN
2243 True if this component is hidden from the user.
2244 CPACK_COMPONENT_<compName>_REQUIRED
2246 True if this component is required.
2247 CPACK_COMPONENT_<compName>_DISABLED
2249 True if this component is not selected to be installed by
2250 default.
2251 cpack_add_component
2253 Describes a CPack installation component named by the COMPONENT argu‐
2255 ment to a CMake INSTALL command.
2256 cpack_add_component(compname
2258 [DISPLAY_NAME name]
2259 [DESCRIPTION description]
2260 [HIDDEN | REQUIRED | DISABLED ]
2261 [GROUP group]
2262 [DEPENDS comp1 comp2 ... ]
2263 [INSTALL_TYPES type1 type2 ... ]
2264 [DOWNLOADED]
2265 [ARCHIVE_FILE filename]
2266 [PLIST filename])
2267 The cmake_add_component command describes an installation component,
2269 which the user can opt to install or remove as part of the graphical
2270 installation process. compname is the name of the component, as pro‐
2271 vided to the COMPONENT argument of one or more CMake INSTALL commands.
2272 DISPLAY_NAME is the displayed name of the component, used in graphical
2274 installers to display the component name. This value can be any
2275 string.
2276 DESCRIPTION is an extended description of the component, used in graph‐
2278 ical installers to give the user additional information about the com‐
2279 ponent. Descriptions can span multiple lines using \n as the line sep‐
2280 arator. Typically, these descriptions should be no more than a few
2281 lines long.
2282 HIDDEN indicates that this component will be hidden in the graphical
2284 installer, so that the user cannot directly change whether it is
2285 installed or not.
2286 REQUIRED indicates that this component is required, and therefore will
2288 always be installed. It will be visible in the graphical installer,
2289 but it cannot be unselected. (Typically, required components are shown
2290 greyed out).
2291 DISABLED indicates that this component should be disabled (unselected)
2293 by default. The user is free to select this component for installa‐
2294 tion, unless it is also HIDDEN.
2295 DEPENDS lists the components on which this component depends. If this
2297 component is selected, then each of the components listed must also be
2298 selected. The dependency information is encoded within the installer
2299 itself, so that users cannot install inconsistent sets of components.
2300 GROUP names the component group of which this component is a part. If
2302 not provided, the component will be a standalone component, not part of
2303 any component group. Component groups are described with the
2304 cpack_add_component_group command, detailed below.
2305 INSTALL_TYPES lists the installation types of which this component is a
2307 part. When one of these installations types is selected, this compo‐
2308 nent will automatically be selected. Installation types are described
2309 with the cpack_add_install_type command, detailed below.
2310 DOWNLOADED indicates that this component should be downloaded
2312 on-the-fly by the installer, rather than packaged in with the installer
2313 itself. For more information, see the cpack_configure_downloads com‐
2314 mand.
2315 ARCHIVE_FILE provides a name for the archive file created by CPack to
2317 be used for downloaded components. If not supplied, CPack will create
2318 a file with some name based on CPACK_PACKAGE_FILE_NAME and the name of
2319 the component. See cpack_configure_downloads for more information.
2320 PLIST gives a filename that is passed to pkgbuild with the --compo‐
2322 nent-plist argument when using the productbuild generator.
2323 cpack_add_component_group
2325 Describes a group of related CPack installation components.
2327 cpack_add_component_group(groupname
2329 [DISPLAY_NAME name]
2330 [DESCRIPTION description]
2331 [PARENT_GROUP parent]
2332 [EXPANDED]
2333 [BOLD_TITLE])
2334 The cpack_add_component_group describes a group of installation compo‐
2336 nents, which will be placed together within the listing of options.
2337 Typically, component groups allow the user to select/deselect all of
2338 the components within a single group via a single group-level option.
2339 Use component groups to reduce the complexity of installers with many
2340 options. groupname is an arbitrary name used to identify the group in
2341 the GROUP argument of the cpack_add_component command, which is used to
2342 place a component in a group. The name of the group must not conflict
2343 with the name of any component.
2344 DISPLAY_NAME is the displayed name of the component group, used in
2346 graphical installers to display the component group name. This value
2347 can be any string.
2348 DESCRIPTION is an extended description of the component group, used in
2350 graphical installers to give the user additional information about the
2351 components within that group. Descriptions can span multiple lines
2352 using \n as the line separator. Typically, these descriptions should
2353 be no more than a few lines long.
2354 PARENT_GROUP, if supplied, names the parent group of this group. Par‐
2356 ent groups are used to establish a hierarchy of groups, providing an
2357 arbitrary hierarchy of groups.
2358 EXPANDED indicates that, by default, the group should show up as
2360 “expanded”, so that the user immediately sees all of the components
2361 within the group. Otherwise, the group will initially show up as a
2362 single entry.
2363 BOLD_TITLE indicates that the group title should appear in bold, to
2365 call the user’s attention to the group.
2366 cpack_add_install_type
2368 Add a new installation type containing a set of predefined component
2370 selections to the graphical installer.
2371 cpack_add_install_type(typename
2373 [DISPLAY_NAME name])
2374 The cpack_add_install_type command identifies a set of preselected com‐
2376 ponents that represents a common use case for an application. For
2377 example, a “Developer” install type might include an application along
2378 with its header and library files, while an “End user” install type
2379 might just include the application’s executable. Each component iden‐
2380 tifies itself with one or more install types via the INSTALL_TYPES
2381 argument to cpack_add_component.
2382 DISPLAY_NAME is the displayed name of the install type, which will typ‐
2384 ically show up in a drop-down box within a graphical installer. This
2385 value can be any string.
2386 cpack_configure_downloads
2388 Configure CPack to download selected components on-the-fly as part of
2390 the installation process.
2391 cpack_configure_downloads(site
2393 [UPLOAD_DIRECTORY dirname]
2394 [ALL]
2395 [ADD_REMOVE|NO_ADD_REMOVE])
2396 The cpack_configure_downloads command configures installation-time
2398 downloads of selected components. For each downloadable component,
2399 CPack will create an archive containing the contents of that component,
2400 which should be uploaded to the given site. When the user selects that
2401 component for installation, the installer will download and extract the
2402 component in place. This feature is useful for creating small install‐
2403 ers that only download the requested components, saving bandwidth.
2404 Additionally, the installers are small enough that they will be
2405 installed as part of the normal installation process, and the “Change”
2406 button in Windows Add/Remove Programs control panel will allow one to
2407 add or remove parts of the application after the original installation.
2408 On Windows, the downloaded-components functionality requires the ZipDLL
2409 plug-in for NSIS, available at:
2410 http://nsis.sourceforge.net/ZipDLL_plug-in
2412 On macOS, installers that download components on-the-fly can only be
2414 built and installed on system using macOS 10.5 or later.
2415 The site argument is a URL where the archives for downloadable compo‐
2417 nents will reside, e.g., https://cmake.org/files/2.6.1/installer/ All
2418 of the archives produced by CPack should be uploaded to that location.
2419 UPLOAD_DIRECTORY is the local directory where CPack will create the
2421 various archives for each of the components. The contents of this
2422 directory should be uploaded to a location accessible by the URL given
2423 in the site argument. If omitted, CPack will use the directory CPackU‐
2424 ploads inside the CMake binary directory to store the generated ar‐
2425 chives.
2426 The ALL flag indicates that all components be downloaded. Otherwise,
2428 only those components explicitly marked as DOWNLOADED or that have a
2429 specified ARCHIVE_FILE will be downloaded. Additionally, the ALL
2430 option implies ADD_REMOVE (unless NO_ADD_REMOVE is specified).
2431 ADD_REMOVE indicates that CPack should install a copy of the installer
2433 that can be called from Windows’ Add/Remove Programs dialog (via the
2434 “Modify” button) to change the set of installed components.
2435 NO_ADD_REMOVE turns off this behavior. This option is ignored on Mac
2436 OS X.
2437 CPackIFW
2439 The documentation for the CPack IFW generator has moved here: CPack IFW
2440 Generator
2441 This module looks for the location of the command line utilities sup‐
2443 plied with the Qt Installer Framework (QtIFW).
2444 The module also defines several commands to control the behavior of the
2446 CPack IFW generator.
2447 Commands
2449 The module defines the following commands:
2450 cpack_ifw_configure_component
2452 Sets the arguments specific to the CPack IFW generator.
2453 cpack_ifw_configure_component(<compname> [COMMON] [ESSENTIAL] [VIRTUAL]
2455 [FORCED_INSTALLATION] [REQUIRES_ADMIN_RIGHTS]
2456 [NAME <name>]
2457 [DISPLAY_NAME <display_name>] # Note: Internationalization supported
2458 [DESCRIPTION <description>] # Note: Internationalization supported
2459 [UPDATE_TEXT <update_text>]
2460 [VERSION <version>]
2461 [RELEASE_DATE <release_date>]
2462 [SCRIPT <script>]
2463 [PRIORITY|SORTING_PRIORITY <sorting_priority>] # Note: PRIORITY is deprecated
2464 [DEPENDS|DEPENDENCIES <com_id> ...]
2465 [AUTO_DEPEND_ON <comp_id> ...]
2466 [LICENSES <display_name> <file_path> ...]
2467 [DEFAULT <value>]
2468 [USER_INTERFACES <file_path> <file_path> ...]
2469 [TRANSLATIONS <file_path> <file_path> ...]
2470 [REPLACES <comp_id> ...]
2471 [CHECKABLE <value>])
2472 This command should be called after cpack_add_component() com‐
2474 mand.
2475 COMMON if set, then the component will be packaged and installed
2477 as part of a group to which it belongs.
2478 ESSENTIAL
2480 if set, then the package manager stays disabled until
2481 that component is updated.
2482 VIRTUAL
2484 if set, then the component will be hidden from the in‐
2485 staller. It is a equivalent of the HIDDEN option from
2486 the cpack_add_component() command.
2487 FORCED_INSTALLATION
2489 if set, then the component must always be installed. It
2490 is a equivalent of the REQUARED option from the
2491 cpack_add_component() command.
2492 REQUIRES_ADMIN_RIGHTS
2494 set it if the component needs to be installed with ele‐
2495 vated permissions.
2496 NAME is used to create domain-like identification for this
2498 component. By default used origin component name.
2499 DISPLAY_NAME
2501 set to rewrite original name configured by cpack_add_com‐
2502 ponent() command.
2503 DESCRIPTION
2505 set to rewrite original description configured by
2506 cpack_add_component() command.
2507 UPDATE_TEXT
2509 will be added to the component description if this is an
2510 update to the component.
2511 VERSION
2513 is version of component. By default used CPACK_PACK‐
2514 AGE_VERSION.
2515 RELEASE_DATE
2517 keep empty to auto generate.
2518 SCRIPT is a relative or absolute path to operations script for
2520 this component.
2521 PRIORITY | SORTING_PRIORITY
2523 is priority of the component in the tree. The PRIORITY
2524 option is deprecated and will be removed in a future ver‐
2525 sion of CMake. Please use SORTING_PRIORITY option
2526 instead.
2527 DEPENDS | DEPENDENCIES
2529 list of dependency component or component group identi‐
2530 fiers in QtIFW style.
2531 AUTO_DEPEND_ON
2533 list of identifiers of component or component group in
2534 QtIFW style that this component has an automatic depen‐
2535 dency on.
2536 LICENSES
2538 pair of <display_name> and <file_path> of license text
2539 for this component. You can specify more then one
2540 license.
2541 DEFAULT
2543 Possible values are: TRUE, FALSE, and SCRIPT. Set to
2544 FALSE to disable the component in the installer or to
2545 SCRIPT to resolved during runtime (don’t forget add the
2546 file of the script as a value of the SCRIPT option).
2547 USER_INTERFACES
2549 is a list of <file_path> (‘.ui’ files) representing pages
2550 to load.
2551 TRANSLATIONS
2553 is a list of <file_path> (‘.qm’ files) representing
2554 translations to load.
2555 REPLACES
2557 list of identifiers of component or component group to
2558 replace.
2559 CHECKABLE
2561 Possible values are: TRUE, FALSE. Set to FALSE if you
2562 want to hide the checkbox for an item. This is useful
2563 when only a few subcomponents should be selected instead
2564 of all.
2565 cpack_ifw_configure_component_group
2567 Sets the arguments specific to the CPack IFW generator.
2568 cpack_ifw_configure_component_group(<groupname> [VIRTUAL]
2570 [FORCED_INSTALLATION] [REQUIRES_ADMIN_RIGHTS]
2571 [NAME <name>]
2572 [DISPLAY_NAME <display_name>] # Note: Internationalization supported
2573 [DESCRIPTION <description>] # Note: Internationalization supported
2574 [UPDATE_TEXT <update_text>]
2575 [VERSION <version>]
2576 [RELEASE_DATE <release_date>]
2577 [SCRIPT <script>]
2578 [PRIORITY|SORTING_PRIORITY <sorting_priority>] # Note: PRIORITY is deprecated
2579 [DEPENDS|DEPENDENCIES <com_id> ...]
2580 [AUTO_DEPEND_ON <comp_id> ...]
2581 [LICENSES <display_name> <file_path> ...]
2582 [DEFAULT <value>]
2583 [USER_INTERFACES <file_path> <file_path> ...]
2584 [TRANSLATIONS <file_path> <file_path> ...]
2585 [REPLACES <comp_id> ...]
2586 [CHECKABLE <value>])
2587 This command should be called after cpack_add_component_group()
2589 command.
2590 VIRTUAL
2592 if set, then the group will be hidden from the installer.
2593 Note that setting this on a root component does not work.
2594 FORCED_INSTALLATION
2596 if set, then the group must always be installed.
2597 REQUIRES_ADMIN_RIGHTS
2599 set it if the component group needs to be installed with
2600 elevated permissions.
2601 NAME is used to create domain-like identification for this
2603 component group. By default used origin component group
2604 name.
2605 DISPLAY_NAME
2607 set to rewrite original name configured by cpack_add_com‐
2608 ponent_group() command.
2609 DESCRIPTION
2611 set to rewrite original description configured by
2612 cpack_add_component_group() command.
2613 UPDATE_TEXT
2615 will be added to the component group description if this
2616 is an update to the component group.
2617 VERSION
2619 is version of component group. By default used
2620 CPACK_PACKAGE_VERSION.
2621 RELEASE_DATE
2623 keep empty to auto generate.
2624 SCRIPT is a relative or absolute path to operations script for
2626 this component group.
2627 PRIORITY | SORTING_PRIORITY
2629 is priority of the component group in the tree. The PRI‐
2630 ORITY option is deprecated and will be removed in a
2631 future version of CMake. Please use SORTING_PRIORITY
2632 option instead.
2633 DEPENDS | DEPENDENCIES
2635 list of dependency component or component group identi‐
2636 fiers in QtIFW style.
2637 AUTO_DEPEND_ON
2639 list of identifiers of component or component group in
2640 QtIFW style that this component group has an automatic
2641 dependency on.
2642 LICENSES
2644 pair of <display_name> and <file_path> of license text
2645 for this component group. You can specify more then one
2646 license.
2647 DEFAULT
2649 Possible values are: TRUE, FALSE, and SCRIPT. Set to
2650 TRUE to preselect the group in the installer (this takes
2651 effect only on groups that have no visible child compo‐
2652 nents) or to SCRIPT to resolved during runtime (don’t
2653 forget add the file of the script as a value of the
2654 SCRIPT option).
2655 USER_INTERFACES
2657 is a list of <file_path> (‘.ui’ files) representing pages
2658 to load.
2659 TRANSLATIONS
2661 is a list of <file_path> (‘.qm’ files) representing
2662 translations to load.
2663 REPLACES
2665 list of identifiers of component or component group to
2666 replace.
2667 CHECKABLE
2669 Possible values are: TRUE, FALSE. Set to FALSE if you
2670 want to hide the checkbox for an item. This is useful
2671 when only a few subcomponents should be selected instead
2672 of all.
2673 cpack_ifw_add_repository
2675 Add QtIFW specific remote repository to binary installer.
2676 cpack_ifw_add_repository(<reponame> [DISABLED]
2678 URL <url>
2679 [USERNAME <username>]
2680 [PASSWORD <password>]
2681 [DISPLAY_NAME <display_name>])
2682 This command will also add the <reponame> repository to a vari‐
2684 able CPACK_IFW_REPOSITORIES_ALL.
2685 DISABLED
2687 if set, then the repository will be disabled by default.
2688 URL is points to a list of available components.
2690 USERNAME
2692 is used as user on a protected repository.
2693 PASSWORD
2695 is password to use on a protected repository.
2696 DISPLAY_NAME
2698 is string to display instead of the URL.
2699 cpack_ifw_update_repository
2701 Update QtIFW specific repository from remote repository.
2702 cpack_ifw_update_repository(<reponame>
2704 [[ADD|REMOVE] URL <url>]|
2705 [REPLACE OLD_URL <old_url> NEW_URL <new_url>]]
2706 [USERNAME <username>]
2707 [PASSWORD <password>]
2708 [DISPLAY_NAME <display_name>])
2709 This command will also add the <reponame> repository to a vari‐
2711 able CPACK_IFW_REPOSITORIES_ALL.
2712 URL is points to a list of available components.
2714 OLD_URL
2716 is points to a list that will replaced.
2717 NEW_URL
2719 is points to a list that will replace to.
2720 USERNAME
2722 is used as user on a protected repository.
2723 PASSWORD
2725 is password to use on a protected repository.
2726 DISPLAY_NAME
2728 is string to display instead of the URL.
2729 cpack_ifw_add_package_resources
2731 Add additional resources in the installer binary.
2732 cpack_ifw_add_package_resources(<file_path> <file_path> ...)
2734 This command will also add the specified files to a variable
2736 CPACK_IFW_PACKAGE_RESOURCES.
2737 CPackIFWConfigureFile
2739 The module defines configure_file() similar command to configure file
2740 templates prepared in QtIFW/SDK/Creator style.
2741 Commands
2743 The module defines the following commands:
2744 cpack_ifw_configure_file
2746 Copy a file to another location and modify its contents.
2747 cpack_ifw_configure_file(<input> <output>)
2749 Copies an <input> file to an <output> file and substitutes vari‐
2751 able values referenced as %{VAR} or %VAR% in the input file con‐
2752 tent. Each variable reference will be replaced with the current
2753 value of the variable, or the empty string if the variable is
2754 not defined.
2755 CPack
2757 Build binary and source package installers.
2758 Introduction
2760 The CPack module generates a file CPackConfig.cmake intended for use in
2761 a subsequent run of the cpack program where it steers the generation
2762 of installers or/and source packages.
2763 Inclusion of the CPack module adds two new build targets, package and
2765 package_source, which build the binary and source installers respec‐
2766 tively. The generated binary installers contain everything installed
2767 via CMake’s install() command (and the deprecated commands
2768 install_files(), install_programs(), and install_targets()).
2769 For certain kinds of binary installers (including the graphical in‐
2771 stallers on macOS and Windows), CPack generates installers that allow
2772 users to select individual application components to install. See
2773 CPackComponent module for further details.
2774 CPack Generators
2776 The CPACK_GENERATOR variable has different meanings in different con‐
2777 texts. In a CMakeLists.txt file, CPACK_GENERATOR is a list of genera‐
2778 tors: and when cpack is run with no other arguments, it will iterate
2779 over that list and produce one package for each generator. In a
2780 CPACK_PROJECT_CONFIG_FILE, CPACK_GENERATOR is a string naming a single
2781 generator. If you need per-cpack-generator logic to control other
2782 cpack settings, then you need a CPACK_PROJECT_CONFIG_FILE.
2783 The CMake source tree itself contains a CPACK_PROJECT_CONFIG_FILE. See
2785 the top level file CMakeCPackOptions.cmake.in for an example.
2786 If set, the CPACK_PROJECT_CONFIG_FILE is included automatically on a
2788 per-generator basis. It only need contain overrides.
2789 Here’s how it works:
2791 · cpack runs
2793 · it includes CPackConfig.cmake
2795 · it iterates over the generators given by the -G command line option,
2797 or if no such option was specified, over the list of generators given
2798 by the CPACK_GENERATOR variable set in the CPackConfig.cmake input
2799 file.
2800 · foreach generator, it then
2802 · sets CPACK_GENERATOR to the one currently being iterated
2804 · includes the CPACK_PROJECT_CONFIG_FILE
2806 · produces the package for that generator
2808 This is the key: For each generator listed in CPACK_GENERATOR in CPack‐
2810 Config.cmake, cpack will reset CPACK_GENERATOR internally to the one
2811 currently being used and then include the CPACK_PROJECT_CONFIG_FILE.
2812 Variables common to all CPack Generators
2814 Before including this CPack module in your CMakeLists.txt file, there
2815 are a variety of variables that can be set to customize the resulting
2816 installers. The most commonly-used variables are:
2817 CPACK_PACKAGE_NAME
2819 The name of the package (or application). If not specified, it
2820 defaults to the project name.
2821 CPACK_PACKAGE_VENDOR
2823 The name of the package vendor. (e.g., “Kitware”). The default
2824 is “Humanity”.
2825 CPACK_PACKAGE_DIRECTORY
2827 The directory in which CPack is doing its packaging. If it is
2828 not set then this will default (internally) to the build dir.
2829 This variable may be defined in a CPack config file or from the
2830 cpack command line option -B. If set, the command line option
2831 overrides the value found in the config file.
2832 CPACK_PACKAGE_VERSION_MAJOR
2834 Package major version. This variable will always be set, but
2835 its default value depends on whether or not version details were
2836 given to the project() command in the top level CMakeLists.txt
2837 file. If version details were given, the default value will be
2838 CMAKE_PROJECT_VERSION_MAJOR. If no version details were given,
2839 a default version of 0.1.1 will be assumed, leading to
2840 CPACK_PACKAGE_VERSION_MAJOR having a default value of 0.
2841 CPACK_PACKAGE_VERSION_MINOR
2843 Package minor version. The default value is determined based on
2844 whether or not version details were given to the project() com‐
2845 mand in the top level CMakeLists.txt file. If version details
2846 were given, the default value will be CMAKE_PROJECT_VER‐
2847 SION_MINOR, but if no minor version component was specified then
2848 CPACK_PACKAGE_VERSION_MINOR will be left unset. If no project
2849 version was given at all, a default version of 0.1.1 will be
2850 assumed, leading to CPACK_PACKAGE_VERSION_MINOR having a default
2851 value of 1.
2852 CPACK_PACKAGE_VERSION_PATCH
2854 Package patch version. The default value is determined based on
2855 whether or not version details were given to the project() com‐
2856 mand in the top level CMakeLists.txt file. If version details
2857 were given, the default value will be CMAKE_PROJECT_VER‐
2858 SION_PATCH, but if no patch version component was specified then
2859 CPACK_PACKAGE_VERSION_PATCH will be left unset. If no project
2860 version was given at all, a default version of 0.1.1 will be
2861 assumed, leading to CPACK_PACKAGE_VERSION_PATCH having a default
2862 value of 1.
2863 CPACK_PACKAGE_DESCRIPTION
2865 A description of the project, used in places such as the intro‐
2866 duction screen of CPack-generated Windows installers. If not
2867 set, the value of this variable is populated from the file named
2868 by CPACK_PACKAGE_DESCRIPTION_FILE.
2869 CPACK_PACKAGE_DESCRIPTION_FILE
2871 A text file used to describe the project when
2872 CPACK_PACKAGE_DESCRIPTION is not explicitly set. The default
2873 value for CPACK_PACKAGE_DESCRIPTION_FILE points to a built-in
2874 template file Templates/CPack.GenericDescription.txt.
2875 CPACK_PACKAGE_DESCRIPTION_SUMMARY
2877 Short description of the project (only a few words). If the
2878 CMAKE_PROJECT_DESCRIPTION variable is set, it is used as the
2879 default value, otherwise the default will be a string generated
2880 by CMake based on CMAKE_PROJECT_NAME.
2881 CPACK_PACKAGE_HOMEPAGE_URL
2883 Project homepage URL. The default value is taken from the
2884 CMAKE_PROJECT_HOMEPAGE_URL variable, which is set by the top
2885 level project() command, or else the default will be empty if no
2886 URL was provided to project().
2887 CPACK_PACKAGE_FILE_NAME
2889 The name of the package file to generate, not including the
2890 extension. For example, cmake-2.6.1-Linux-i686. The default
2891 value is:
2892 ${CPACK_PACKAGE_NAME}-${CPACK_PACKAGE_VERSION}-${CPACK_SYSTEM_NAME}
2894 CPACK_PACKAGE_INSTALL_DIRECTORY
2896 Installation directory on the target system. This may be used by
2897 some CPack generators like NSIS to create an installation direc‐
2898 tory e.g., “CMake 2.5” below the installation prefix. All
2899 installed elements will be put inside this directory.
2900 CPACK_PACKAGE_ICON
2902 A branding image that will be displayed inside the installer
2903 (used by GUI installers).
2904 CPACK_PACKAGE_CHECKSUM
2906 An algorithm that will be used to generate an additional file
2907 with the checksum of the package. The output file name will be:
2908 ${CPACK_PACKAGE_FILE_NAME}.${CPACK_PACKAGE_CHECKSUM}
2910 Supported algorithms are those listed by the string(<HASH>) com‐
2912 mand.
2913 CPACK_PROJECT_CONFIG_FILE
2915 CPack-time project CPack configuration file. This file is
2916 included at cpack time, once per generator after CPack has set
2917 CPACK_GENERATOR to the actual generator being used. It allows
2918 per-generator setting of CPACK_* variables at cpack time.
2919 CPACK_RESOURCE_FILE_LICENSE
2921 License to be embedded in the installer. It will typically be
2922 displayed to the user by the produced installer (often with an
2923 explicit “Accept” button, for graphical installers) prior to
2924 installation. This license file is NOT added to the installed
2925 files but is used by some CPack generators like NSIS. If you
2926 want to install a license file (may be the same as this one)
2927 along with your project, you must add an appropriate CMake
2928 install() command in your CMakeLists.txt.
2929 CPACK_RESOURCE_FILE_README
2931 ReadMe file to be embedded in the installer. It typically
2932 describes in some detail the purpose of the project during the
2933 installation. Not all CPack generators use this file.
2934 CPACK_RESOURCE_FILE_WELCOME
2936 Welcome file to be embedded in the installer. It welcomes users
2937 to this installer. Typically used in the graphical installers
2938 on Windows and Mac OS X.
2939 CPACK_MONOLITHIC_INSTALL
2941 Disables the component-based installation mechanism. When set,
2942 the component specification is ignored and all installed items
2943 are put in a single “MONOLITHIC” package. Some CPack generators
2944 do monolithic packaging by default and may be asked to do compo‐
2945 nent packaging by setting CPACK_<GENNAME>_COMPONENT_INSTALL to
2946 TRUE.
2947 CPACK_GENERATOR
2949 List of CPack generators to use. If not specified, CPack will
2950 create a set of options following the naming pattern
2951 CPACK_BINARY_<GENNAME> (e.g. CPACK_BINARY_NSIS) allowing the
2952 user to enable/disable individual generators. If the -G option
2953 is given on the cpack command line, it will override this vari‐
2954 able and any CPACK_BINARY_<GENNAME> options.
2955 CPACK_OUTPUT_CONFIG_FILE
2957 The name of the CPack binary configuration file. This file is
2958 the CPack configuration generated by the CPack module for binary
2959 installers. Defaults to CPackConfig.cmake.
2960 CPACK_PACKAGE_EXECUTABLES
2962 Lists each of the executables and associated text label to be
2963 used to create Start Menu shortcuts. For example, setting this
2964 to the list ccmake;CMake will create a shortcut named “CMake”
2965 that will execute the installed executable ccmake. Not all
2966 CPack generators use it (at least NSIS, WIX and OSXX11 do).
2967 CPACK_STRIP_FILES
2969 List of files to be stripped. Starting with CMake 2.6.0,
2970 CPACK_STRIP_FILES will be a boolean variable which enables
2971 stripping of all files (a list of files evaluates to TRUE in
2972 CMake, so this change is compatible).
2973 CPACK_VERBATIM_VARIABLES
2975 If set to TRUE, values of variables prefixed with CPACK_ will be
2976 escaped before being written to the configuration files, so that
2977 the cpack program receives them exactly as they were specified.
2978 If not, characters like quotes and backslashes can cause parsing
2979 errors or alter the value received by the cpack program.
2980 Defaults to FALSE for backwards compatibility.
2981 Variables for Source Package Generators
2983 The following CPack variables are specific to source packages, and will
2984 not affect binary packages:
2985 CPACK_SOURCE_PACKAGE_FILE_NAME
2987 The name of the source package. For example cmake-2.6.1.
2988 CPACK_SOURCE_STRIP_FILES
2990 List of files in the source tree that will be stripped. Start‐
2991 ing with CMake 2.6.0, CPACK_SOURCE_STRIP_FILES will be a boolean
2992 variable which enables stripping of all files (a list of files
2993 evaluates to TRUE in CMake, so this change is compatible).
2994 CPACK_SOURCE_GENERATOR
2996 List of generators used for the source packages. As with
2997 CPACK_GENERATOR, if this is not specified then CPack will create
2998 a set of options (e.g. CPACK_SOURCE_ZIP) allowing users to
2999 select which packages will be generated.
3000 CPACK_SOURCE_OUTPUT_CONFIG_FILE
3002 The name of the CPack source configuration file. This file is
3003 the CPack configuration generated by the CPack module for source
3004 installers. Defaults to CPackSourceConfig.cmake.
3005 CPACK_SOURCE_IGNORE_FILES
3007 Pattern of files in the source tree that won’t be packaged when
3008 building a source package. This is a list of regular expression
3009 patterns (that must be properly escaped), e.g.,
3010 /CVS/;/\\.svn/;\\.swp$;\\.#;/#;.*~;cscope.*
3011 Variables for Advanced Use
3013 The following variables are for advanced uses of CPack:
3014 CPACK_CMAKE_GENERATOR
3016 What CMake generator should be used if the project is a CMake
3017 project. Defaults to the value of CMAKE_GENERATOR. Few users
3018 will want to change this setting.
3019 CPACK_INSTALL_CMAKE_PROJECTS
3021 List of four values that specify what project to install. The
3022 four values are: Build directory, Project Name, Project Compo‐
3023 nent, Directory. If omitted, CPack will build an installer that
3024 installs everything.
3025 CPACK_SYSTEM_NAME
3027 System name, defaults to the value of CMAKE_SYSTEM_NAME, except
3028 on Windows where it will be win32 or win64.
3029 CPACK_PACKAGE_VERSION
3031 Package full version, used internally. By default, this is
3032 built from CPACK_PACKAGE_VERSION_MAJOR,
3033 CPACK_PACKAGE_VERSION_MINOR, and CPACK_PACKAGE_VERSION_PATCH.
3034 CPACK_TOPLEVEL_TAG
3036 Directory for the installed files.
3037 CPACK_INSTALL_COMMANDS
3039 Extra commands to install components. The environment variable
3040 CMAKE_INSTALL_PREFIX is set to the temporary install directory
3041 during execution.
3042 CPACK_INSTALL_SCRIPTS
3044 Extra CMake scripts executed by CPack during its local staging
3045 installation, which is done right before packaging the files.
3046 The scripts are not called by a standalone install (e.g.: make
3047 install). For every script, the following variables will be
3048 set: CMAKE_CURRENT_SOURCE_DIR, CMAKE_CURRENT_BINARY_DIR and
3049 CMAKE_INSTALL_PREFIX (which is set to the staging install direc‐
3050 tory). The singular form CMAKE_INSTALL_SCRIPT is supported as
3051 an alternative variable for historical reasons, but its value is
3052 ignored if CMAKE_INSTALL_SCRIPTS is set and a warning will be
3053 issued.
3054 CPACK_INSTALLED_DIRECTORIES
3056 Extra directories to install.
3057 CPACK_PACKAGE_INSTALL_REGISTRY_KEY
3059 Registry key used when installing this project. This is only
3060 used by installers for Windows. The default value is based on
3061 the installation directory.
3062 CPACK_CREATE_DESKTOP_LINKS
3064 List of desktop links to create. Each desktop link requires a
3065 corresponding start menu shortcut as created by
3066 CPACK_PACKAGE_EXECUTABLES.
3067 CPACK_BINARY_<GENNAME>
3069 CPack generated options for binary generators. The CPack.cmake
3070 module generates (when CPACK_GENERATOR is not set) a set of
3071 CMake options (see CMake option() command) which may then be
3072 used to select the CPack generator(s) to be used when building
3073 the package target or when running cpack without the -G option.
3074 CSharpUtilities
3076 Functions to make configuration of CSharp/.NET targets easier.
3077 A collection of CMake utility functions useful for dealing with CSharp
3079 targets for Visual Studio generators from version 2010 and later.
3080 The following functions are provided by this module:
3082 Main functions
3084 · csharp_set_windows_forms_properties()
3086 · csharp_set_designer_cs_properties()
3088 · csharp_set_xaml_cs_properties()
3090 Helper functions
3092 · csharp_get_filename_keys()
3094 · csharp_get_filename_key_base()
3096 · csharp_get_dependentupon_name()
3098 Main functions provided by the module
3100 csharp_set_windows_forms_properties
3101 Sets source file properties for use of Windows Forms. Use this,
3102 if your CSharp target uses Windows Forms:
3103 csharp_set_windows_forms_properties([<file1> [<file2> [...]]])
3105 <fileN>
3107 List of all source files which are relevant for setting
3108 the VS_CSHARP_<tagname> properties (including .cs, .resx
3109 and .Designer.cs extensions).
3110 In the list of all given files for all files ending with
3112 .Designer.cs and .resx is searched. For every designer or
3113 resource file a file with the same base name but only .cs as
3114 extension is searched. If this is found, the VS_CSHARP_<tag‐
3115 name> properties are set as follows:
3116 for the .cs file:
3118 · VS_CSHARP_SubType “Form”
3120 for the .Designer.cs file (if it exists):
3122 · VS_CSHARP_DependentUpon <cs-filename>
3124 · VS_CSHARP_DesignTime “” (delete tag if previously
3126 defined)
3127 · VS_CSHARP_AutoGen “”(delete tag if previously defined)
3129 for the .resx file (if it exists):
3131 · VS_RESOURCE_GENERATOR “” (delete tag if previously
3133 defined)
3134 · VS_CSHARP_DependentUpon <cs-filename>
3136 · VS_CSHARP_SubType “Designer”
3138 csharp_set_designer_cs_properties
3140 Sets source file properties of .Designer.cs files depending on
3141 sibling filenames. Use this, if your CSharp target does not use
3142 Windows Forms (for Windows Forms use
3143 csharp_set_designer_cs_properties() instead):
3144 csharp_set_designer_cs_properties([<file1> [<file2> [...]]])
3146 <fileN>
3148 List of all source files which are relevant for setting
3149 the VS_CSHARP_<tagname> properties (including .cs, .resx,
3150 .settings and .Designer.cs extensions).
3151 In the list of all given files for all files ending with
3153 .Designer.cs is searched. For every designer file all files with
3154 the same base name but different extensions are searched. If a
3155 match is found, the source file properties of the designer file
3156 are set depending on the extension of the matched file:
3157 if match is .resx file:
3159 · VS_CSHARP_AutoGen “True”
3161 · VS_CSHARP_DesignTime “True”
3163 · VS_CSHARP_DependentUpon <resx-filename>
3165 if match is .cs file:
3167 · VS_CSHARP_DependentUpon <cs-filename>
3169 if match is .settings file:
3171 · VS_CSHARP_AutoGen “True”
3173 · VS_CSHARP_DesignTimeSharedInput “True”
3175 · VS_CSHARP_DependentUpon <settings-filename>
3177 NOTE:
3179 Because the source file properties of the .Designer.cs file are set
3180 according to the found matches and every match sets the
3181 VS_CSHARP_DependentUpon property, there should only be one match for
3182 each Designer.cs file.
3183 csharp_set_xaml_cs_properties
3185 Sets source file properties for use of Windows Presentation
3186 Foundation (WPF) and XAML. Use this, if your CSharp target uses
3187 WPF/XAML:
3188 csharp_set_xaml_cs_properties([<file1> [<file2> [...]]])
3190 <fileN>
3192 List of all source files which are relevant for setting
3193 the VS_CSHARP_<tagname> properties (including .cs, .xaml,
3194 and .xaml.cs extensions).
3195 In the list of all given files for all files ending with
3197 .xaml.cs is searched. For every xaml-cs file, a file with the
3198 same base name but extension .xaml is searched. If a match is
3199 found, the source file properties of the .xaml.cs file are set:
3200 · VS_CSHARP_DependentUpon <xaml-filename>
3202 Helper functions which are used by the above ones
3204 csharp_get_filename_keys
3205 Helper function which computes a list of key values to identify
3206 source files independently of relative/absolute paths given in
3207 cmake and eliminates case sensitivity:
3208 csharp_get_filename_keys(OUT [<file1> [<file2> [...]]])
3210 OUT Name of the variable in which the list of keys is stored
3212 <fileN>
3214 filename(s) as given to to CSharp target using
3215 add_library() or add_executable()
3216 In some way the function applies a canonicalization to the
3218 source names. This is necessary to find file matches if the
3219 files have been added to the target with different directory
3220 prefixes:
3221 add_library(lib
3223 myfile.cs
3224 ${CMAKE_CURRENT_SOURCE_DIR}/myfile.Designer.cs)
3225 set_source_files_properties(myfile.Designer.cs PROPERTIES
3227 VS_CSHARP_DependentUpon myfile.cs)
3228 # this will fail, because in cmake
3230 # - ${CMAKE_CURRENT_SOURCE_DIR}/myfile.Designer.cs
3231 # - myfile.Designer.cs
3232 # are not the same source file. The source file property is not set.
3233 csharp_get_filename_key_base
3235 Returns the full filepath and name without extension of a key.
3236 KEY is expected to be a key from csharp_get_filename_keys. In
3237 BASE the value of KEY without the file extension is returned:
3238 csharp_get_filename_key_base(BASE KEY)
3240 BASE Name of the variable with the computed “base” of KEY.
3242 KEY The key of which the base will be computed. Expected to
3244 be a upper case full filename.
3245 csharp_get_dependentupon_name
3247 Computes a string which can be used as value for the source file
3248 property VS_CSHARP_<tagname> with target being DependentUpon:
3249 csharp_get_dependentupon_name(NAME FILE)
3251 NAME Name of the variable with the result value
3253 FILE Filename to convert to <DependentUpon> value
3255 Actually this is only the filename without any path given at the
3257 moment.
3258 CTest
3260 Configure a project for testing with CTest/CDash
3261 Include this module in the top CMakeLists.txt file of a project to
3263 enable testing with CTest and dashboard submissions to CDash:
3264 project(MyProject)
3266 ...
3267 include(CTest)
3268 The module automatically creates a BUILD_TESTING option that selects
3270 whether to enable testing support (ON by default). After including the
3271 module, use code like:
3272 if(BUILD_TESTING)
3274 # ... CMake code to create tests ...
3275 endif()
3276 to creating tests when testing is enabled.
3278 To enable submissions to a CDash server, create a CTestConfig.cmake
3280 file at the top of the project with content such as:
3281 set(CTEST_NIGHTLY_START_TIME "01:00:00 UTC")
3283 set(CTEST_SUBMIT_URL "http://my.cdash.org/submit.php?project=MyProject")
3284 (the CDash server can provide the file to a project administrator who
3286 configures MyProject). Settings in the config file are shared by both
3287 this CTest module and the ctest(1) command-line Dashboard Client mode
3288 (ctest -S).
3289 While building a project for submission to CDash, CTest scans the build
3291 output for errors and warnings and reports them with surrounding con‐
3292 text from the build log. This generic approach works for all build
3293 tools, but does not give details about the command invocation that pro‐
3294 duced a given problem. One may get more detailed reports by setting
3295 the CTEST_USE_LAUNCHERS variable:
3296 set(CTEST_USE_LAUNCHERS 1)
3298 in the CTestConfig.cmake file.
3300 CTestCoverageCollectGCOV
3302 This module provides the ctest_coverage_collect_gcov function.
3303 This function runs gcov on all .gcda files found in the binary tree and
3305 packages the resulting .gcov files into a tar file. This tarball also
3306 contains the following:
3307 · data.json defines the source and build directories for use by CDash.
3309 · Labels.json indicates any LABELS that have been set on the source
3311 files.
3312 · The uncovered directory holds any uncovered files found by
3314 CTEST_EXTRA_COVERAGE_GLOB.
3315 After generating this tar file, it can be sent to CDash for display
3317 with the ctest_submit(CDASH_UPLOAD) command.
3318 ctest_coverage_collect_gcov
3320 ctest_coverage_collect_gcov(TARBALL <tarfile>
3322 [SOURCE <source_dir>][BUILD <build_dir>]
3323 [GCOV_COMMAND <gcov_command>]
3324 [GCOV_OPTIONS <options>...]
3325 )
3326 Run gcov and package a tar file for CDash. The options are:
3328 TARBALL <tarfile>
3330 Specify the location of the .tar file to be created for
3331 later upload to CDash. Relative paths will be inter‐
3332 preted with respect to the top-level build directory.
3333 SOURCE <source_dir>
3335 Specify the top-level source directory for the build.
3336 Default is the value of CTEST_SOURCE_DIRECTORY.
3337 BUILD <build_dir>
3339 Specify the top-level build directory for the build.
3340 Default is the value of CTEST_BINARY_DIRECTORY.
3341 GCOV_COMMAND <gcov_command>
3343 Specify the full path to the gcov command on the machine.
3344 Default is the value of CTEST_COVERAGE_COMMAND.
3345 GCOV_OPTIONS <options>...
3347 Specify options to be passed to gcov. The gcov command
3348 is run as gcov <options>... -o <gcov-dir> <file>.gcda.
3349 If not specified, the default option is just -b -x.
3350 GLOB Recursively search for .gcda files in build_dir rather
3352 than determining search locations by reading TargetDirec‐
3353 tories.txt.
3354 DELETE Delete coverage files after they’ve been packaged into
3356 the .tar.
3357 QUIET Suppress non-error messages that otherwise would have
3359 been printed out by this function.
3360 CTestScriptMode
3362 This file is read by ctest in script mode (-S)
3363 CTestUseLaunchers
3365 Set the RULE_LAUNCH_* global properties when CTEST_USE_LAUNCHERS is on.
3366 CTestUseLaunchers is automatically included when you include(CTest).
3368 However, it is split out into its own module file so projects can use
3369 the CTEST_USE_LAUNCHERS functionality independently.
3370 To use launchers, set CTEST_USE_LAUNCHERS to ON in a ctest -S dashboard
3372 script, and then also set it in the cache of the configured project.
3373 Both cmake and ctest need to know the value of it for the launchers to
3374 work properly. CMake needs to know in order to generate proper build
3375 rules, and ctest, in order to produce the proper error and warning
3376 analysis.
3377 For convenience, you may set the ENV variable CTEST_USE_LAUNCH‐
3379 ERS_DEFAULT in your ctest -S script, too. Then, as long as your CMake‐
3380 Lists uses include(CTest) or include(CTestUseLaunchers), it will use
3381 the value of the ENV variable to initialize a CTEST_USE_LAUNCHERS cache
3382 variable. This cache variable initialization only occurs if
3383 CTEST_USE_LAUNCHERS is not already defined. If CTEST_USE_LAUNCHERS is
3384 on in a ctest -S script the ctest_configure command will add
3385 -DCTEST_USE_LAUNCHERS:BOOL=TRUE to the cmake command used to configure
3386 the project.
3387 Dart
3389 Configure a project for testing with CTest or old Dart Tcl Client
3390 This file is the backwards-compatibility version of the CTest module.
3392 It supports using the old Dart 1 Tcl client for driving dashboard sub‐
3393 missions as well as testing with CTest. This module should be included
3394 in the CMakeLists.txt file at the top of a project. Typical usage:
3395 include(Dart)
3397 if(BUILD_TESTING)
3398 # ... testing related CMake code ...
3399 endif()
3400 The BUILD_TESTING option is created by the Dart module to determine
3402 whether testing support should be enabled. The default is ON.
3403 DeployQt4
3405 Functions to help assemble a standalone Qt4 executable.
3406 A collection of CMake utility functions useful for deploying Qt4 exe‐
3408 cutables.
3409 The following functions are provided by this module:
3411 write_qt4_conf
3413 resolve_qt4_paths
3414 fixup_qt4_executable
3415 install_qt4_plugin_path
3416 install_qt4_plugin
3417 install_qt4_executable
3418 Requires CMake 2.6 or greater because it uses function and PAR‐
3420 ENT_SCOPE. Also depends on BundleUtilities.cmake.
3421 write_qt4_conf(<qt_conf_dir> <qt_conf_contents>)
3423 Writes a qt.conf file with the <qt_conf_contents> into <qt_conf_dir>.
3425 resolve_qt4_paths(<paths_var> [<executable_path>])
3427 Loop through <paths_var> list and if any don’t exist resolve them rela‐
3429 tive to the <executable_path> (if supplied) or the CMAKE_INSTALL_PRE‐
3430 FIX.
3431 fixup_qt4_executable(<executable>
3433 [<qtplugins> <libs> <dirs> <plugins_dir> <request_qt_conf>])
3434 Copies Qt plugins, writes a Qt configuration file (if needed) and fixes
3436 up a Qt4 executable using BundleUtilities so it is standalone and can
3437 be drag-and-drop copied to another machine as long as all of the system
3438 libraries are compatible.
3439 <executable> should point to the executable to be fixed-up.
3441 <qtplugins> should contain a list of the names or paths of any Qt plug‐
3443 ins to be installed.
3444 <libs> will be passed to BundleUtilities and should be a list of any
3446 already installed plugins, libraries or executables to also be
3447 fixed-up.
3448 <dirs> will be passed to BundleUtilities and should contain and direc‐
3450 tories to be searched to find library dependencies.
3451 <plugins_dir> allows an custom plugins directory to be used.
3453 <request_qt_conf> will force a qt.conf file to be written even if not
3455 needed.
3456 install_qt4_plugin_path(plugin executable copy installed_plugin_path_var
3458 <plugins_dir> <component> <configurations>)
3459 Install (or copy) a resolved <plugin> to the default plugins directory
3461 (or <plugins_dir>) relative to <executable> and store the result in
3462 <installed_plugin_path_var>.
3463 If <copy> is set to TRUE then the plugins will be copied rather than
3465 installed. This is to allow this module to be used at CMake time
3466 rather than install time.
3467 If <component> is set then anything installed will use this COMPONENT.
3469 install_qt4_plugin(plugin executable copy installed_plugin_path_var
3471 <plugins_dir> <component>)
3472 Install (or copy) an unresolved <plugin> to the default plugins direc‐
3474 tory (or <plugins_dir>) relative to <executable> and store the result
3475 in <installed_plugin_path_var>. See documentation of INSTALL_QT4_PLUG‐
3476 IN_PATH.
3477 install_qt4_executable(<executable>
3479 [<qtplugins> <libs> <dirs> <plugins_dir> <request_qt_conf> <component>])
3480 Installs Qt plugins, writes a Qt configuration file (if needed) and
3482 fixes up a Qt4 executable using BundleUtilities so it is standalone and
3483 can be drag-and-drop copied to another machine as long as all of the
3484 system libraries are compatible. The executable will be fixed-up at
3485 install time. <component> is the COMPONENT used for bundle fixup and
3486 plugin installation. See documentation of FIXUP_QT4_BUNDLE.
3487 Documentation
3489 This module provides support for the VTK documentation framework. It
3490 relies on several tools (Doxygen, Perl, etc).
3491 ExternalData
3493 Manage data files stored outside source tree
3494 Introduction
3496 Use this module to unambiguously reference data files stored outside
3497 the source tree and fetch them at build time from arbitrary local and
3498 remote content-addressed locations. Functions provided by this module
3499 recognize arguments with the syntax DATA{<name>} as references to
3500 external data, replace them with full paths to local copies of those
3501 data, and create build rules to fetch and update the local copies.
3502 For example:
3504 include(ExternalData)
3506 set(ExternalData_URL_TEMPLATES "file:///local/%(algo)/%(hash)"
3507 "file:////host/share/%(algo)/%(hash)"
3508 "http://data.org/%(algo)/%(hash)")
3509 ExternalData_Add_Test(MyData
3510 NAME MyTest
3511 COMMAND MyExe DATA{MyInput.png}
3512 )
3513 ExternalData_Add_Target(MyData)
3514 When test MyTest runs the DATA{MyInput.png} argument will be replaced
3516 by the full path to a real instance of the data file MyInput.png on
3517 disk. If the source tree contains a content link such as MyIn‐
3518 put.png.md5 then the MyData target creates a real MyInput.png in the
3519 build tree.
3520 Module Functions
3522 ExternalData_Expand_Arguments
3523 The ExternalData_Expand_Arguments function evaluates DATA{} ref‐
3524 erences in its arguments and constructs a new list of arguments:
3525 ExternalData_Expand_Arguments(
3527 <target> # Name of data management target
3528 <outVar> # Output variable
3529 [args...] # Input arguments, DATA{} allowed
3530 )
3531 It replaces each DATA{} reference in an argument with the full
3533 path of a real data file on disk that will exist after the <tar‐
3534 get> builds.
3535 ExternalData_Add_Test
3537 The ExternalData_Add_Test function wraps around the CMake
3538 add_test() command but supports DATA{} references in its argu‐
3539 ments:
3540 ExternalData_Add_Test(
3542 <target> # Name of data management target
3543 ... # Arguments of add_test(), DATA{} allowed
3544 )
3545 It passes its arguments through ExternalData_Expand_Arguments
3547 and then invokes the add_test() command using the results.
3548 ExternalData_Add_Target
3550 The ExternalData_Add_Target function creates a custom target to
3551 manage local instances of data files stored externally:
3552 ExternalData_Add_Target(
3554 <target> # Name of data management target
3555 )
3556 It creates custom commands in the target as necessary to make
3558 data files available for each DATA{} reference previously evalu‐
3559 ated by other functions provided by this module. Data files may
3560 be fetched from one of the URL templates specified in the Exter‐
3561 nalData_URL_TEMPLATES variable, or may be found locally in one
3562 of the paths specified in the ExternalData_OBJECT_STORES vari‐
3563 able.
3564 Typically only one target is needed to manage all external data
3566 within a project. Call this function once at the end of config‐
3567 uration after all data references have been processed.
3568 Module Variables
3570 The following variables configure behavior. They should be set before
3571 calling any of the functions provided by this module.
3572 ExternalData_BINARY_ROOT
3574 The ExternalData_BINARY_ROOT variable may be set to the direc‐
3575 tory to hold the real data files named by expanded DATA{} refer‐
3576 ences. The default is CMAKE_BINARY_DIR. The directory layout
3577 will mirror that of content links under External‐
3578 Data_SOURCE_ROOT.
3579 ExternalData_CUSTOM_SCRIPT_<key>
3581 Specify a full path to a .cmake custom fetch script identified
3582 by <key> in entries of the ExternalData_URL_TEMPLATES list. See
3583 Custom Fetch Scripts.
3584 ExternalData_LINK_CONTENT
3586 The ExternalData_LINK_CONTENT variable may be set to the name of
3587 a supported hash algorithm to enable automatic conversion of
3588 real data files referenced by the DATA{} syntax into content
3589 links. For each such <file> a content link named <file><ext> is
3590 created. The original file is renamed to the form .External‐
3591 Data_<algo>_<hash> to stage it for future transmission to one of
3592 the locations in the list of URL templates (by means outside the
3593 scope of this module). The data fetch rule created for the con‐
3594 tent link will use the staged object if it cannot be found using
3595 any URL template.
3596 ExternalData_NO_SYMLINKS
3598 The real data files named by expanded DATA{} references may be
3599 made available under ExternalData_BINARY_ROOT using symbolic
3600 links on some platforms. The ExternalData_NO_SYMLINKS variable
3601 may be set to disable use of symbolic links and enable use of
3602 copies instead.
3603 ExternalData_OBJECT_STORES
3605 The ExternalData_OBJECT_STORES variable may be set to a list of
3606 local directories that store objects using the layout
3607 <dir>/%(algo)/%(hash). These directories will be searched first
3608 for a needed object. If the object is not available in any
3609 store then it will be fetched remotely using the URL templates
3610 and added to the first local store listed. If no stores are
3611 specified the default is a location inside the build tree.
3612 ExternalData_SERIES_PARSE
3614 ExternalData_SERIES_PARSE_PREFIX
3616 ExternalData_SERIES_PARSE_NUMBER
3618 ExternalData_SERIES_PARSE_SUFFIX
3620 ExternalData_SERIES_MATCH
3622 See Referencing File Series.
3623 ExternalData_SOURCE_ROOT
3625 The ExternalData_SOURCE_ROOT variable may be set to the highest
3626 source directory containing any path named by a DATA{} refer‐
3627 ence. The default is CMAKE_SOURCE_DIR. External‐
3628 Data_SOURCE_ROOT and CMAKE_SOURCE_DIR must refer to directories
3629 within a single source distribution (e.g. they come together in
3630 one tarball).
3631 ExternalData_TIMEOUT_ABSOLUTE
3633 The ExternalData_TIMEOUT_ABSOLUTE variable sets the download
3634 absolute timeout, in seconds, with a default of 300 seconds.
3635 Set to 0 to disable enforcement.
3636 ExternalData_TIMEOUT_INACTIVITY
3638 The ExternalData_TIMEOUT_INACTIVITY variable sets the download
3639 inactivity timeout, in seconds, with a default of 60 seconds.
3640 Set to 0 to disable enforcement.
3641 ExternalData_URL_ALGO_<algo>_<key>
3643 Specify a custom URL component to be substituted for URL tem‐
3644 plate placeholders of the form %(algo:<key>), where <key> is a
3645 valid C identifier, when fetching an object referenced via hash
3646 algorithm <algo>. If not defined, the default URL component is
3647 just <algo> for any <key>.
3648 ExternalData_URL_TEMPLATES
3650 The ExternalData_URL_TEMPLATES may be set to provide a list of
3651 of URL templates using the placeholders %(algo) and %(hash) in
3652 each template. Data fetch rules try each URL template in order
3653 by substituting the hash algorithm name for %(algo) and the hash
3654 value for %(hash). Alternatively one may use %(algo:<key>) with
3655 ExternalData_URL_ALGO_<algo>_<key> variables to gain more flexi‐
3656 bility in remote URLs.
3657 Referencing Files
3659 Referencing Single Files
3660 The DATA{} syntax is literal and the <name> is a full or relative path
3661 within the source tree. The source tree must contain either a real
3662 data file at <name> or a “content link” at <name><ext> containing a
3663 hash of the real file using a hash algorithm corresponding to <ext>.
3664 For example, the argument DATA{img.png} may be satisfied by either a
3665 real img.png file in the current source directory or a img.png.md5 file
3666 containing its MD5 sum.
3667 Multiple content links of the same name with different hash algorithms
3669 are supported (e.g. img.png.sha256 and img.png.sha1) so long as they
3670 all correspond to the same real file. This allows objects to be
3671 fetched from sources indexed by different hash algorithms.
3672 Referencing File Series
3674 The DATA{} syntax can be told to fetch a file series using the form
3675 DATA{<name>,:}, where the : is literal. If the source tree contains a
3676 group of files or content links named like a series then a reference to
3677 one member adds rules to fetch all of them. Although all members of a
3678 series are fetched, only the file originally named by the DATA{} argu‐
3679 ment is substituted for it. The default configuration recognizes file
3680 series names ending with #.ext, _#.ext, .#.ext, or -#.ext where # is a
3681 sequence of decimal digits and .ext is any single extension. Configure
3682 it with a regex that parses <number> and <suffix> parts from the end of
3683 <name>:
3684 ExternalData_SERIES_PARSE = regex of the form (<number>)(<suffix>)$
3686 For more complicated cases set:
3688 ExternalData_SERIES_PARSE = regex with at least two () groups
3690 ExternalData_SERIES_PARSE_PREFIX = <prefix> regex group number, if any
3691 ExternalData_SERIES_PARSE_NUMBER = <number> regex group number
3692 ExternalData_SERIES_PARSE_SUFFIX = <suffix> regex group number
3693 Configure series number matching with a regex that matches the <number>
3695 part of series members named <prefix><number><suffix>:
3696 ExternalData_SERIES_MATCH = regex matching <number> in all series members
3698 Note that the <suffix> of a series does not include a hash-algorithm
3700 extension.
3701 Referencing Associated Files
3703 The DATA{} syntax can alternatively match files associated with the
3704 named file and contained in the same directory. Associated files may
3705 be specified by options using the syntax
3706 DATA{<name>,<opt1>,<opt2>,...}. Each option may specify one file by
3707 name or specify a regular expression to match file names using the syn‐
3708 tax REGEX:<regex>. For example, the arguments:
3709 DATA{MyData/MyInput.mhd,MyInput.img} # File pair
3711 DATA{MyData/MyFrames00.png,REGEX:MyFrames[0-9]+\\.png} # Series
3712 will pass MyInput.mha and MyFrames00.png on the command line but ensure
3714 that the associated files are present next to them.
3715 Referencing Directories
3717 The DATA{} syntax may reference a directory using a trailing slash and
3718 a list of associated files. The form DATA{<name>/,<opt1>,<opt2>,...}
3719 adds rules to fetch any files in the directory that match one of the
3720 associated file options. For example, the argument
3721 DATA{MyDataDir/,REGEX:.*} will pass the full path to a MyDataDir direc‐
3722 tory on the command line and ensure that the directory contains files
3723 corresponding to every file or content link in the MyDataDir source
3724 directory. In order to match associated files in subdirectories, spec‐
3725 ify a RECURSE: option, e.g. DATA{MyDataDir/,RECURSE:,REGEX:.*}.
3726 Hash Algorithms
3728 The following hash algorithms are supported:
3729 %(algo) <ext> Description
3731 ------- ----- -----------
3732 MD5 .md5 Message-Digest Algorithm 5, RFC 1321
3733 SHA1 .sha1 US Secure Hash Algorithm 1, RFC 3174
3734 SHA224 .sha224 US Secure Hash Algorithms, RFC 4634
3735 SHA256 .sha256 US Secure Hash Algorithms, RFC 4634
3736 SHA384 .sha384 US Secure Hash Algorithms, RFC 4634
3737 SHA512 .sha512 US Secure Hash Algorithms, RFC 4634
3738 SHA3_224 .sha3-224 Keccak SHA-3
3739 SHA3_256 .sha3-256 Keccak SHA-3
3740 SHA3_384 .sha3-384 Keccak SHA-3
3741 SHA3_512 .sha3-512 Keccak SHA-3
3742 Note that the hashes are used only for unique data identification and
3744 download verification.
3745 Custom Fetch Scripts
3747 When a data file must be fetched from one of the URL templates speci‐
3748 fied in the ExternalData_URL_TEMPLATES variable, it is normally down‐
3749 loaded using the file(DOWNLOAD) command. One may specify usage of a
3750 custom fetch script by using a URL template of the form ExternalData‐
3751 CustomScript://<key>/<loc>. The <key> must be a C identifier, and the
3752 <loc> must contain the %(algo) and %(hash) placeholders. A variable
3753 corresponding to the key, ExternalData_CUSTOM_SCRIPT_<key>, must be set
3754 to the full path to a .cmake script file. The script will be included
3755 to perform the actual fetch, and provided with the following variables:
3756 ExternalData_CUSTOM_LOCATION
3758 When a custom fetch script is loaded, this variable is set to
3759 the location part of the URL, which will contain the substituted
3760 hash algorithm name and content hash value.
3761 ExternalData_CUSTOM_FILE
3763 When a custom fetch script is loaded, this variable is set to
3764 the full path to a file in which the script must store the
3765 fetched content. The name of the file is unspecified and should
3766 not be interpreted in any way.
3767 The custom fetch script is expected to store fetched content in the
3769 file or set a variable:
3770 ExternalData_CUSTOM_ERROR
3772 When a custom fetch script fails to fetch the requested content,
3773 it must set this variable to a short one-line message describing
3774 the reason for failure.
3775 ExternalProject
3777 External Project Definition
3778 ExternalProject_Add
3779 The ExternalProject_Add() function creates a custom target to
3780 drive download, update/patch, configure, build, install and test
3781 steps of an external project:
3782 ExternalProject_Add(<name> [<option>...])
3784 The individual steps within the process can be driven indepen‐
3786 dently if required (e.g. for CDash submission) and extra custom
3787 steps can be defined, along with the ability to control the step
3788 dependencies. The directory structure used for the management of
3789 the external project can also be customized. The function sup‐
3790 ports a large number of options which can be used to tailor the
3791 external project behavior.
3792 Directory Options:
3794 Most of the time, the default directory layout is suffi‐
3795 cient. It is largely an implementation detail that the
3796 main project usually doesn’t need to change. In some cir‐
3797 cumstances, however, control over the directory layout
3798 can be useful or necessary. The directory options are
3799 potentially more useful from the point of view that the
3800 main build can use the ExternalProject_Get_Property()
3801 command to retrieve their values, thereby allowing the
3802 main project to refer to build artifacts of the external
3803 project.
3804 PREFIX <dir>
3806 Root directory for the external project. Unless
3807 otherwise noted below, all other directories asso‐
3808 ciated with the external project will be created
3809 under here.
3810 TMP_DIR <dir>
3812 Directory in which to store temporary files.
3813 STAMP_DIR <dir>
3815 Directory in which to store the timestamps of each
3816 step. Log files from individual steps are also
3817 created in here unless overridden by LOG_DIR (see
3818 Logging Options below).
3819 LOG_DIR <dir>
3821 Directory in which to store the logs of each step.
3822 DOWNLOAD_DIR <dir>
3824 Directory in which to store downloaded files
3825 before unpacking them. This directory is only used
3826 by the URL download method, all other download
3827 methods use SOURCE_DIR directly instead.
3828 SOURCE_DIR <dir>
3830 Source directory into which downloaded contents
3831 will be unpacked, or for non-URL download methods,
3832 the directory in which the repository should be
3833 checked out, cloned, etc. If no download method is
3834 specified, this must point to an existing direc‐
3835 tory where the external project has already been
3836 unpacked or cloned/checked out.
3837 NOTE:
3839 If a download method is specified, any existing
3840 contents of the source directory may be
3841 deleted. Only the URL download method checks
3842 whether this directory is either missing or
3843 empty before initiating the download, stopping
3844 with an error if it is not empty. All other
3845 download methods silently discard any previous
3846 contents of the source directory.
3847 BINARY_DIR <dir>
3849 Specify the build directory location. This option
3850 is ignored if BUILD_IN_SOURCE is enabled.
3851 INSTALL_DIR <dir>
3853 Installation prefix to be placed in the
3854 <INSTALL_DIR> placeholder. This does not actually
3855 configure the external project to install to the
3856 given prefix. That must be done by passing appro‐
3857 priate arguments to the external project configu‐
3858 ration step, e.g. using <INSTALL_DIR>.
3859 If any of the above ..._DIR options are not specified,
3861 their defaults are computed as follows. If the PREFIX
3862 option is given or the EP_PREFIX directory property is
3863 set, then an external project is built and installed
3864 under the specified prefix:
3865 TMP_DIR = <prefix>/tmp
3867 STAMP_DIR = <prefix>/src/<name>-stamp
3868 DOWNLOAD_DIR = <prefix>/src
3869 SOURCE_DIR = <prefix>/src/<name>
3870 BINARY_DIR = <prefix>/src/<name>-build
3871 INSTALL_DIR = <prefix>
3872 LOG_DIR = <STAMP_DIR>
3873 Otherwise, if the EP_BASE directory property is set then
3875 components of an external project are stored under the
3876 specified base:
3877 TMP_DIR = <base>/tmp/<name>
3879 STAMP_DIR = <base>/Stamp/<name>
3880 DOWNLOAD_DIR = <base>/Download/<name>
3881 SOURCE_DIR = <base>/Source/<name>
3882 BINARY_DIR = <base>/Build/<name>
3883 INSTALL_DIR = <base>/Install/<name>
3884 LOG_DIR = <STAMP_DIR>
3885 If no PREFIX, EP_PREFIX, or EP_BASE is specified, then
3887 the default is to set PREFIX to <name>-prefix. Relative
3888 paths are interpreted with respect to CMAKE_CUR‐
3889 RENT_BINARY_DIR at the point where ExternalProject_Add()
3890 is called.
3891 Download Step Options:
3893 A download method can be omitted if the SOURCE_DIR option
3894 is used to point to an existing non-empty directory. Oth‐
3895 erwise, one of the download methods below must be speci‐
3896 fied (multiple download methods should not be given) or a
3897 custom DOWNLOAD_COMMAND provided.
3898 DOWNLOAD_COMMAND <cmd>...
3900 Overrides the command used for the download step
3901 (generator expressions are supported). If this
3902 option is specified, all other download options
3903 will be ignored. Providing an empty string for
3904 <cmd> effectively disables the download step.
3905 URL Download
3907 URL <url1> [<url2>...]
3909 List of paths and/or URL(s) of the external
3910 project’s source. When more than one URL is
3911 given, they are tried in turn until one
3912 succeeds. A URL may be an ordinary path in
3913 the local file system (in which case it
3914 must be the only URL provided) or any down‐
3915 loadable URL supported by the file(DOWN‐
3916 LOAD) command. A local filesystem path may
3917 refer to either an existing directory or to
3918 an archive file, whereas a URL is expected
3919 to point to a file which can be treated as
3920 an archive. When an archive is used, it
3921 will be unpacked automatically unless the
3922 DOWNLOAD_NO_EXTRACT option is set to pre‐
3923 vent it. The archive type is determined by
3924 inspecting the actual content rather than
3925 using logic based on the file extension.
3926 URL_HASH <algo>=<hashValue>
3928 Hash of the archive file to be downloaded.
3929 The argument should be of the form
3930 <algo>=<hashValue> where algo can be any of
3931 the hashing algorithms supported by the
3932 file() command. Specifying this option is
3933 strongly recommended for URL downloads, as
3934 it ensures the integrity of the downloaded
3935 content. It is also used as a check for a
3936 previously downloaded file, allowing con‐
3937 nection to the remote location to be
3938 avoided altogether if the local directory
3939 already has a file from an earlier download
3940 that matches the specified hash.
3941 URL_MD5 <md5>
3943 Equivalent to URL_HASH MD5=<md5>.
3944 DOWNLOAD_NAME <fname>
3946 File name to use for the downloaded file.
3947 If not given, the end of the URL is used to
3948 determine the file name. This option is
3949 rarely needed, the default name is gener‐
3950 ally suitable and is not normally used out‐
3951 side of code internal to the ExternalPro‐
3952 ject module.
3953 DOWNLOAD_NO_EXTRACT <bool>
3955 Allows the extraction part of the download
3956 step to be disabled by passing a boolean
3957 true value for this option. If this option
3958 is not given, the downloaded contents will
3959 be unpacked automatically if required. If
3960 extraction has been disabled, the full path
3961 to the downloaded file is available as
3962 <DOWNLOADED_FILE> in subsequent steps or as
3963 the property DOWNLOADED_FILE with the
3964 ExternalProject_Get_Property() command.
3965 DOWNLOAD_NO_PROGRESS <bool>
3967 Can be used to disable logging the download
3968 progress. If this option is not given,
3969 download progress messages will be logged.
3970 TIMEOUT <seconds>
3972 Maximum time allowed for file download
3973 operations.
3974 HTTP_USERNAME <username>
3976 Username for the download operation if
3977 authentication is required.
3978 HTTP_PASSWORD <password>
3980 Password for the download operation if
3981 authentication is required.
3982 HTTP_HEADER <header1> [<header2>...]
3984 Provides an arbitrary list of HTTP headers
3985 for the download operation. This can be
3986 useful for accessing content in systems
3987 like AWS, etc.
3988 TLS_VERIFY <bool>
3990 Specifies whether certificate verification
3991 should be performed for https URLs. If this
3992 option is not provided, the default behav‐
3993 ior is determined by the CMAKE_TLS_VERIFY
3994 variable (see file(DOWNLOAD)). If that is
3995 also not set, certificate verification will
3996 not be performed. In situations where
3997 URL_HASH cannot be provided, this option
3998 can be an alternative verification measure.
3999 TLS_CAINFO <file>
4001 Specify a custom certificate authority file
4002 to use if TLS_VERIFY is enabled. If this
4003 option is not specified, the value of the
4004 CMAKE_TLS_CAINFO variable will be used
4005 instead (see file(DOWNLOAD))
4006 NETRC <level>
4008 Specify whether the .netrc file is to be
4009 used for operation. If this option is not
4010 specified, the value of the CMAKE_NETRC
4011 variable will be used instead (see
4012 file(DOWNLOAD)) Valid levels are:
4013 IGNORED
4015 The .netrc file is ignored. This is
4016 the default.
4017 OPTIONAL
4019 The .netrc file is optional, and
4020 information in the URL is preferred.
4021 The file will be scanned to find
4022 which ever information is not speci‐
4023 fied in the URL.
4024 REQUIRED
4026 The .netrc file is required, and
4027 information in the URL is ignored.
4028 NETRC_FILE <file>
4030 Specify an alternative .netrc file to the
4031 one in your home directory if the NETRC
4032 level is OPTIONAL or REQUIRED. If this
4033 option is not specified, the value of the
4034 CMAKE_NETRC_FILE variable will be used
4035 instead (see file(DOWNLOAD))
4036 Git NOTE: A git version of 1.6.5 or later is required
4038 if this download method is used.
4039 GIT_REPOSITORY <url>
4041 URL of the git repository. Any URL under‐
4042 stood by the git command may be used.
4043 GIT_TAG <tag>
4045 Git branch name, tag or commit hash. Note
4046 that branch names and tags should generally
4047 be specified as remote names (i.e. ori‐
4048 gin/myBranch rather than simply myBranch).
4049 This ensures that if the remote end has its
4050 tag moved or branch rebased or history
4051 rewritten, the local clone will still be
4052 updated correctly. In general, however,
4053 specifying a commit hash should be pre‐
4054 ferred for a number of reasons:
4055 · If the local clone already has the commit
4057 corresponding to the hash, no git fetch
4058 needs to be performed to check for
4059 changes each time CMake is re-run. This
4060 can result in a significant speed up if
4061 many external projects are being used.
4062 · Using a specific git hash ensures that
4064 the main project’s own history is fully
4065 traceable to a specific point in the
4066 external project’s evolution. If a branch
4067 or tag name is used instead, then check‐
4068 ing out a specific commit of the main
4069 project doesn’t necessarily pin the whole
4070 build to a specific point in the life of
4071 the external project. The lack of such
4072 deterministic behavior makes the main
4073 project lose traceability and repeatabil‐
4074 ity.
4075 If GIT_SHALLOW is enabled then GIT_TAG
4077 works only with branch names and tags. A
4078 commit hash is not allowed.
4079 GIT_REMOTE_NAME <name>
4081 The optional name of the remote. If this
4082 option is not specified, it defaults to
4083 origin.
4084 GIT_SUBMODULES <module>...
4086 Specific git submodules that should also be
4087 updated. If this option is not provided,
4088 all git submodules will be updated. When
4089 CMP0097 is set to NEW if this value is set
4090 to an empty string then no submodules are
4091 initialized or updated.
4092 GIT_SHALLOW <bool>
4094 When this option is enabled, the git clone
4095 operation will be given the --depth 1
4096 option. This performs a shallow clone,
4097 which avoids downloading the whole history
4098 and instead retrieves just the commit
4099 denoted by the GIT_TAG option.
4100 GIT_PROGRESS <bool>
4102 When enabled, this option instructs the git
4103 clone operation to report its progress by
4104 passing it the --progress option. Without
4105 this option, the clone step for large
4106 projects may appear to make the build
4107 stall, since nothing will be logged until
4108 the clone operation finishes. While this
4109 option can be used to provide progress to
4110 prevent the appearance of the build having
4111 stalled, it may also make the build overly
4112 noisy if lots of external projects are
4113 used.
4114 GIT_CONFIG <option1> [<option2>...]
4116 Specify a list of config options to pass to
4117 git clone. Each option listed will be
4118 transformed into its own --config <option>
4119 on the git clone command line, with each
4120 option required to be in the form
4121 key=value.
4122 Subversion
4124 SVN_REPOSITORY <url>
4126 URL of the Subversion repository.
4127 SVN_REVISION -r<rev>
4129 Revision to checkout from the Subversion
4130 repository.
4131 SVN_USERNAME <username>
4133 Username for the Subversion checkout and
4134 update.
4135 SVN_PASSWORD <password>
4137 Password for the Subversion checkout and
4138 update.
4139 SVN_TRUST_CERT <bool>
4141 Specifies whether to trust the Subversion
4142 server site certificate. If enabled, the
4143 --trust-server-cert option is passed to the
4144 svn checkout and update commands.
4145 Mercurial
4147 HG_REPOSITORY <url>
4149 URL of the mercurial repository.
4150 HG_TAG <tag>
4152 Mercurial branch name, tag or commit id.
4153 CVS
4155 CVS_REPOSITORY <cvsroot>
4157 CVSROOT of the CVS repository.
4158 CVS_MODULE <mod>
4160 Module to checkout from the CVS repository.
4161 CVS_TAG <tag>
4163 Tag to checkout from the CVS repository.
4164 Update/Patch Step Options:
4166 Whenever CMake is re-run, by default the external
4167 project’s sources will be updated if the download method
4168 supports updates (e.g. a git repository would be checked
4169 if the GIT_TAG does not refer to a specific commit).
4170 UPDATE_COMMAND <cmd>...
4172 Overrides the download method’s update step with a
4173 custom command. The command may use generator
4174 expressions.
4175 UPDATE_DISCONNECTED <bool>
4177 When enabled, this option causes the update step
4178 to be skipped. It does not, however, prevent the
4179 download step. The update step can still be added
4180 as a step target (see
4181 ExternalProject_Add_StepTargets()) and called man‐
4182 ually. This is useful if you want to allow devel‐
4183 opers to build the project when disconnected from
4184 the network (the network may still be needed for
4185 the download step though).
4186 When this option is present, it is generally
4188 advisable to make the value a cache variable under
4189 the developer’s control rather than hard-coding
4190 it. If this option is not present, the default
4191 value is taken from the EP_UPDATE_DISCONNECTED
4192 directory property. If that is also not defined,
4193 updates are performed as normal. The
4194 EP_UPDATE_DISCONNECTED directory property is
4195 intended as a convenience for controlling the
4196 UPDATE_DISCONNECTED behavior for an entire section
4197 of a project’s directory hierarchy and may be a
4198 more convenient method of giving developers con‐
4199 trol over whether or not to perform updates
4200 (assuming the project also provides a cache vari‐
4201 able or some other convenient method for setting
4202 the directory property).
4203 PATCH_COMMAND <cmd>...
4205 Specifies a custom command to patch the sources
4206 after an update. By default, no patch command is
4207 defined. Note that it can be quite difficult to
4208 define an appropriate patch command that performs
4209 robustly, especially for download methods such as
4210 git where changing the GIT_TAG will not discard
4211 changes from a previous patch, but the patch com‐
4212 mand will be called again after updating to the
4213 new tag.
4214 Configure Step Options:
4216 The configure step is run after the download and update
4217 steps. By default, the external project is assumed to be
4218 a CMake project, but this can be overridden if required.
4219 CONFIGURE_COMMAND <cmd>...
4221 The default configure command runs CMake with
4222 options based on the main project. For non-CMake
4223 external projects, the CONFIGURE_COMMAND option
4224 must be used to override this behavior (generator
4225 expressions are supported). For projects that
4226 require no configure step, specify this option
4227 with an empty string as the command to execute.
4228 CMAKE_COMMAND /.../cmake
4230 Specify an alternative cmake executable for the
4231 configure step (use an absolute path). This is
4232 generally not recommended, since it is usually
4233 desirable to use the same CMake version throughout
4234 the whole build. This option is ignored if a cus‐
4235 tom configure command has been specified with CON‐
4236 FIGURE_COMMAND.
4237 CMAKE_GENERATOR <gen>
4239 Override the CMake generator used for the config‐
4240 ure step. Without this option, the same generator
4241 as the main build will be used. This option is
4242 ignored if a custom configure command has been
4243 specified with the CONFIGURE_COMMAND option.
4244 CMAKE_GENERATOR_PLATFORM <platform>
4246 Pass a generator-specific platform name to the
4247 CMake command (see CMAKE_GENERATOR_PLATFORM). It
4248 is an error to provide this option without the
4249 CMAKE_GENERATOR option.
4250 CMAKE_GENERATOR_TOOLSET <toolset>
4252 Pass a generator-specific toolset name to the
4253 CMake command (see CMAKE_GENERATOR_TOOLSET). It is
4254 an error to provide this option without the
4255 CMAKE_GENERATOR option.
4256 CMAKE_GENERATOR_INSTANCE <instance>
4258 Pass a generator-specific instance selection to
4259 the CMake command (see CMAKE_GENERATOR_INSTANCE).
4260 It is an error to provide this option without the
4261 CMAKE_GENERATOR option.
4262 CMAKE_ARGS <arg>...
4264 The specified arguments are passed to the cmake
4265 command line. They can be any argument the cmake
4266 command understands, not just cache values defined
4267 by -D... arguments (see also CMake Options). In
4268 addition, arguments may use generator expressions.
4269 CMAKE_CACHE_ARGS <arg>...
4271 This is an alternate way of specifying cache vari‐
4272 ables where command line length issues may become
4273 a problem. The arguments are expected to be in the
4274 form -Dvar:STRING=value, which are then trans‐
4275 formed into CMake set() commands with the FORCE
4276 option used. These set() commands are written to a
4277 pre-load script which is then applied using the
4278 cmake -C command line option. Arguments may use
4279 generator expressions.
4280 CMAKE_CACHE_DEFAULT_ARGS <arg>...
4282 This is the same as the CMAKE_CACHE_ARGS option
4283 except the set() commands do not include the FORCE
4284 keyword. This means the values act as initial
4285 defaults only and will not override any variables
4286 already set from a previous run. Use this option
4287 with care, as it can lead to different behavior
4288 depending on whether the build starts from a fresh
4289 build directory or re-uses previous build con‐
4290 tents.
4291 If the CMake generator is the Green Hills MULTI
4293 and not overridden then the original project’s
4294 settings for the GHS toolset and target system
4295 customization cache variables are propagated into
4296 the external project.
4297 SOURCE_SUBDIR <dir>
4299 When no CONFIGURE_COMMAND option is specified, the
4300 configure step assumes the external project has a
4301 CMakeLists.txt file at the top of its source tree
4302 (i.e. in SOURCE_DIR). The SOURCE_SUBDIR option can
4303 be used to point to an alternative directory
4304 within the source tree to use as the top of the
4305 CMake source tree instead. This must be a relative
4306 path and it will be interpreted as being relative
4307 to SOURCE_DIR. When BUILD_IN_SOURCE 1 is speci‐
4308 fied, the BUILD_COMMAND is used to point to an
4309 alternative directory within the source tree.
4310 Build Step Options:
4312 If the configure step assumed the external project uses
4313 CMake as its build system, the build step will also. Oth‐
4314 erwise, the build step will assume a Makefile-based build
4315 and simply run make with no arguments as the default
4316 build step. This can be overridden with custom build com‐
4317 mands if required.
4318 BUILD_COMMAND <cmd>...
4320 Overrides the default build command (generator
4321 expressions are supported). If this option is not
4322 given, the default build command will be chosen to
4323 integrate with the main build in the most appro‐
4324 priate way (e.g. using recursive make for Makefile
4325 generators or cmake --build if the project uses a
4326 CMake build). This option can be specified with an
4327 empty string as the command to make the build step
4328 do nothing.
4329 BUILD_IN_SOURCE <bool>
4331 When this option is enabled, the build will be
4332 done directly within the external project’s source
4333 tree. This should generally be avoided, the use of
4334 a separate build directory is usually preferred,
4335 but it can be useful when the external project
4336 assumes an in-source build. The BINARY_DIR option
4337 should not be specified if building in-source.
4338 BUILD_ALWAYS <bool>
4340 Enabling this option forces the build step to
4341 always be run. This can be the easiest way to
4342 robustly ensure that the external project’s own
4343 build dependencies are evaluated rather than rely‐
4344 ing on the default success timestamp-based method.
4345 This option is not normally needed unless develop‐
4346 ers are expected to modify something the external
4347 project’s build depends on in a way that is not
4348 detectable via the step target dependencies (e.g.
4349 SOURCE_DIR is used without a download method and
4350 developers might modify the sources in
4351 SOURCE_DIR).
4352 BUILD_BYPRODUCTS <file>...
4354 Specifies files that will be generated by the
4355 build command but which might or might not have
4356 their modification time updated by subsequent
4357 builds. These ultimately get passed through as
4358 BYPRODUCTS to the build step’s own underlying call
4359 to add_custom_command().
4360 Install Step Options:
4362 If the configure step assumed the external project uses
4363 CMake as its build system, the install step will also.
4364 Otherwise, the install step will assume a Makefile-based
4365 build and simply run make install as the default build
4366 step. This can be overridden with custom install commands
4367 if required.
4368 INSTALL_COMMAND <cmd>...
4370 The external project’s own install step is invoked
4371 as part of the main project’s build. It is done
4372 after the external project’s build step and may be
4373 before or after the external project’s test step
4374 (see the TEST_BEFORE_INSTALL option below). The
4375 external project’s install rules are not part of
4376 the main project’s install rules, so if anything
4377 from the external project should be installed as
4378 part of the main build, these need to be specified
4379 in the main build as additional install() com‐
4380 mands. The default install step builds the install
4381 target of the external project, but this can be
4382 overridden with a custom command using this option
4383 (generator expressions are supported). Passing an
4384 empty string as the <cmd> makes the install step
4385 do nothing.
4386 Test Step Options:
4388 The test step is only defined if at least one of the fol‐
4389 lowing TEST_... options are provided.
4390 TEST_COMMAND <cmd>...
4392 Overrides the default test command (generator
4393 expressions are supported). If this option is not
4394 given, the default behavior of the test step is to
4395 build the external project’s own test target. This
4396 option can be specified with <cmd> as an empty
4397 string, which allows the test step to still be
4398 defined, but it will do nothing. Do not specify
4399 any of the other TEST_... options if providing an
4400 empty string as the test command, but prefer to
4401 omit all TEST_... options altogether if the test
4402 step target is not needed.
4403 TEST_BEFORE_INSTALL <bool>
4405 When this option is enabled, the test step will be
4406 executed before the install step. The default
4407 behavior is for the test step to run after the
4408 install step.
4409 TEST_AFTER_INSTALL <bool>
4411 This option is mainly useful as a way to indicate
4412 that the test step is desired but all default
4413 behavior is sufficient. Specifying this option
4414 with a boolean true value ensures the test step is
4415 defined and that it comes after the install step.
4416 If both TEST_BEFORE_INSTALL and TEST_AFTER_INSTALL
4417 are enabled, the latter is silently ignored.
4418 TEST_EXCLUDE_FROM_MAIN <bool>
4420 If enabled, the main build’s default ALL target
4421 will not depend on the test step. This can be a
4422 useful way of ensuring the test step is defined
4423 but only gets invoked when manually requested.
4424 Output Logging Options:
4426 Each of the following LOG_... options can be used to wrap
4427 the relevant step in a script to capture its output to
4428 files. The log files will be created in LOG_DIR if sup‐
4429 plied or otherwise the STAMP_DIR directory with step-spe‐
4430 cific file names.
4431 LOG_DOWNLOAD <bool>
4433 When enabled, the output of the download step is
4434 logged to files.
4435 LOG_UPDATE <bool>
4437 When enabled, the output of the update step is
4438 logged to files.
4439 LOG_PATCH <bool>
4441 When enabled, the output of the patch step is
4442 logged to files.
4443 LOG_CONFIGURE <bool>
4445 When enabled, the output of the configure step is
4446 logged to files.
4447 LOG_BUILD <bool>
4449 When enabled, the output of the build step is
4450 logged to files.
4451 LOG_INSTALL <bool>
4453 When enabled, the output of the install step is
4454 logged to files.
4455 LOG_TEST <bool>
4457 When enabled, the output of the test step is
4458 logged to files.
4459 LOG_MERGED_STDOUTERR <bool>
4461 When enabled, stdout and stderr will be merged for
4462 any step whose output is being logged to files.
4463 LOG_OUTPUT_ON_FAILURE <bool>
4465 This option only has an effect if at least one of
4466 the other LOG_<step> options is enabled. If an
4467 error occurs for a step which has logging to file
4468 enabled, that step’s output will be printed to the
4469 console if LOG_OUTPUT_ON_FAILURE is set to true.
4470 For cases where a large amount of output is
4471 recorded, just the end of that output may be
4472 printed to the console.
4473 Terminal Access Options:
4475 Steps can be given direct access to the terminal in some
4476 cases. Giving a step access to the terminal may allow it
4477 to receive terminal input if required, such as for
4478 authentication details not provided by other options.
4479 With the Ninja generator, these options place the steps
4480 in the console job pool. Each step can be given access to
4481 the terminal individually via the following options:
4482 USES_TERMINAL_DOWNLOAD <bool>
4484 Give the download step access to the terminal.
4485 USES_TERMINAL_UPDATE <bool>
4487 Give the update step access to the terminal.
4488 USES_TERMINAL_CONFIGURE <bool>
4490 Give the configure step access to the terminal.
4491 USES_TERMINAL_BUILD <bool>
4493 Give the build step access to the terminal.
4494 USES_TERMINAL_INSTALL <bool>
4496 Give the install step access to the terminal.
4497 USES_TERMINAL_TEST <bool>
4499 Give the test step access to the terminal.
4500 Target Options:
4502 DEPENDS <targets>...
4504 Specify other targets on which the external
4505 project depends. The other targets will be brought
4506 up to date before any of the external project’s
4507 steps are executed. Because the external project
4508 uses additional custom targets internally for each
4509 step, the DEPENDS option is the most convenient
4510 way to ensure all of those steps depend on the
4511 other targets. Simply doing add_dependen‐
4512 cies(<name> <targets>) will not make any of the
4513 steps dependent on <targets>.
4514 EXCLUDE_FROM_ALL <bool>
4516 When enabled, this option excludes the external
4517 project from the default ALL target of the main
4518 build.
4519 STEP_TARGETS <step-target>...
4521 Generate custom targets for the specified steps.
4522 This is required if the steps need to be triggered
4523 manually or if they need to be used as dependen‐
4524 cies of other targets. If this option is not spec‐
4525 ified, the default value is taken from the
4526 EP_STEP_TARGETS directory property. See
4527 ExternalProject_Add_Step() below for further dis‐
4528 cussion of the effects of this option.
4529 INDEPENDENT_STEP_TARGETS <step-target>...
4531 Generate custom targets for the specified steps
4532 and prevent these targets from having the usual
4533 dependencies applied to them. If this option is
4534 not specified, the default value is taken from the
4535 EP_INDEPENDENT_STEP_TARGETS directory property.
4536 This option is mostly useful for allowing individ‐
4537 ual steps to be driven independently, such as for
4538 a CDash setup where each step should be initiated
4539 and reported individually rather than as one whole
4540 build. See ExternalProject_Add_Step() below for
4541 further discussion of the effects of this option.
4542 Miscellaneous Options:
4544 LIST_SEPARATOR <sep>
4546 For any of the various ..._COMMAND options,
4547 replace ; with <sep> in the specified command
4548 lines. This can be useful where list variables may
4549 be given in commands where they should end up as
4550 space-separated arguments (<sep> would be a single
4551 space character string in this case).
4552 COMMAND <cmd>...
4554 Any of the other ..._COMMAND options can have
4555 additional commands appended to them by following
4556 them with as many COMMAND ... options as needed
4557 (generator expressions are supported). For exam‐
4558 ple:
4559 ExternalProject_Add(example
4561 ... # Download options, etc.
4562 BUILD_COMMAND ${CMAKE_COMMAND} -E echo "Starting $<CONFIG> build"
4563 COMMAND ${CMAKE_COMMAND} --build <BINARY_DIR> --config $<CONFIG>
4564 COMMAND ${CMAKE_COMMAND} -E echo "$<CONFIG> build complete"
4565 )
4566 It should also be noted that each build step is created via a
4568 call to ExternalProject_Add_Step(). See that command’s documen‐
4569 tation for the automatic substitutions that are supported for
4570 some options.
4571 Obtaining Project Properties
4573 ExternalProject_Get_Property
4574 The ExternalProject_Get_Property() function retrieves external
4575 project target properties:
4576 ExternalProject_Get_Property(<name> <prop1> [<prop2>...])
4578 The function stores property values in variables of the same
4580 name. Property names correspond to the keyword argument names of
4581 ExternalProject_Add(). For example, the source directory might
4582 be retrieved like so:
4583 ExternalProject_Get_property(myExtProj SOURCE_DIR)
4585 message("Source dir of myExtProj = ${SOURCE_DIR}")
4586 Explicit Step Management
4588 The ExternalProject_Add() function on its own is often sufficient for
4589 incorporating an external project into the main build. Certain scenar‐
4590 ios require additional work to implement desired behavior, such as
4591 adding in a custom step or making steps available as manually trigger‐
4592 able targets. The ExternalProject_Add_Step(), ExternalProject_Add_Step‐
4593 Targets() and ExternalProject_Add_StepDependencies functions provide
4594 the lower level control needed to implement such step-level capabili‐
4595 ties.
4596 ExternalProject_Add_Step
4598 The ExternalProject_Add_Step() function specifies an additional
4599 custom step for an external project defined by an earlier call
4600 to ExternalProject_Add():
4601 ExternalProject_Add_Step(<name> <step> [<option>...])
4603 <name> is the same as the name passed to the original call to
4605 ExternalProject_Add(). The specified <step> must not be one of
4606 the pre-defined steps (mkdir, download, update, skip-update,
4607 patch, configure, build, install or test). The supported options
4608 are:
4609 COMMAND <cmd>...
4611 The command line to be executed by this custom step (gen‐
4612 erator expressions are supported). This option can be
4613 repeated multiple times to specify multiple commands to
4614 be executed in order.
4615 COMMENT <text>...
4617 Text to be printed when the custom step executes.
4618 DEPENDEES <step>...
4620 Other steps (custom or pre-defined) on which this step
4621 depends.
4622 DEPENDERS <step>...
4624 Other steps (custom or pre-defined) that depend on this
4625 new custom step.
4626 DEPENDS <file>...
4628 Files on which this custom step depends.
4629 BYPRODUCTS <file>...
4631 Files that will be generated by this custom step but
4632 which might or might not have their modification time
4633 updated by subsequent builds. This list of files will
4634 ultimately be passed through as the BYPRODUCTS option to
4635 the add_custom_command() used to implement the custom
4636 step internally.
4637 ALWAYS <bool>
4639 When enabled, this option specifies that the custom step
4640 should always be run (i.e. that it is always considered
4641 out of date).
4642 EXCLUDE_FROM_MAIN <bool>
4644 When enabled, this option specifies that the external
4645 project’s main target does not depend on the custom step.
4646 WORKING_DIRECTORY <dir>
4648 Specifies the working directory to set before running the
4649 custom step’s command. If this option is not specified,
4650 the directory will be the value of the CMAKE_CUR‐
4651 RENT_BINARY_DIR at the point where ExternalPro‐
4652 ject_Add_Step() was called.
4653 LOG <bool>
4655 If set, this causes the output from the custom step to be
4656 captured to files in the external project’s LOG_DIR if
4657 supplied or STAMP_DIR.
4658 USES_TERMINAL <bool>
4660 If enabled, this gives the custom step direct access to
4661 the terminal if possible.
4662 The command line, comment, working directory and byproducts of
4664 every standard and custom step are processed to replace the
4665 tokens <SOURCE_DIR>, <SOURCE_SUBDIR>, <BINARY_DIR>,
4666 <INSTALL_DIR> <TMP_DIR>, <DOWNLOAD_DIR> and <DOWNLOADED_FILE>
4667 with their corresponding property values defined in the original
4668 call to ExternalProject_Add().
4669 ExternalProject_Add_StepTargets
4671 The ExternalProject_Add_StepTargets() function generates targets
4672 for the steps listed. The name of each created target will be of
4673 the form <name>-<step>:
4674 ExternalProject_Add_StepTargets(<name> [NO_DEPENDS] <step1> [<step2>...])
4676 Creating a target for a step allows it to be used as a depen‐
4678 dency of another target or to be triggered manually. Having tar‐
4679 gets for specific steps also allows them to be driven indepen‐
4680 dently of each other by specifying targets on build command
4681 lines. For example, you may be submitting to a sub-project based
4682 dashboard where you want to drive the configure portion of the
4683 build, then submit to the dashboard, followed by the build por‐
4684 tion, followed by tests. If you invoke a custom target that
4685 depends on a step halfway through the step dependency chain,
4686 then all the previous steps will also run to ensure everything
4687 is up to date.
4688 If the NO_DEPENDS option is specified, the step target will not
4690 depend on the dependencies of the external project (i.e. on any
4691 dependencies of the <name> custom target created by
4692 ExternalProject_Add()). This is usually safe for the download,
4693 update and patch steps, since they do not typically require that
4694 the dependencies are updated and built. Using NO_DEPENDS for any
4695 of the other pre-defined steps, however, may break parallel
4696 builds. Only use NO_DEPENDS where it is certain that the named
4697 steps genuinely do not have dependencies. For custom steps, con‐
4698 sider whether or not the custom commands require the dependen‐
4699 cies to be configured, built and installed.
4700 Internally, ExternalProject_Add() calls
4702 ExternalProject_Add_Step() to create each step. If any STEP_TAR‐
4703 GETS or INDEPENDENT_STEP_TARGETS were specified, then External‐
4704 Project_Add_StepTargets() will also be called after
4705 ExternalProject_Add_Step(). INDEPENDENT_STEP_TARGETS have the
4706 NO_DEPENDS option set, whereas STEP_TARGETS do not. Other than
4707 that, the two options result in ExternalProject_Add_StepTar‐
4708 gets() being called in the same way. Even if a step is not men‐
4709 tioned in either of those two options, ExternalProject_Add_Step‐
4710 Targets() can still be called later to manually define a target
4711 for the step.
4712 The STEP_TARGETS and INDEPENDENT_STEP_TARGETS options for
4714 ExternalProject_Add() are generally the easiest way to ensure
4715 targets are created for specific steps of interest. For custom
4716 steps, ExternalProject_Add_StepTargets() must be called explic‐
4717 itly if a target should also be created for that custom step. An
4718 alternative to these two options is to populate the EP_STEP_TAR‐
4719 GETS and EP_INDEPENDENT_STEP_TARGETS directory properties. These
4720 act as defaults for the step target options and can save having
4721 to repeatedly specify the same set of step targets when multiple
4722 external projects are being defined.
4723 ExternalProject_Add_StepDependencies
4725 The ExternalProject_Add_StepDependencies() function can be used
4726 to add dependencies to a step. The dependencies added must be
4727 targets CMake already knows about (these can be ordinary exe‐
4728 cutable or library targets, custom targets or even step targets
4729 of another external project):
4730 ExternalProject_Add_StepDependencies(<name> <step> <target1> [<target2>...])
4732 This function takes care to set both target and file level
4734 dependencies and will ensure that parallel builds will not
4735 break. It should be used instead of add_dependencies() whenever
4736 adding a dependency for some of the step targets generated by
4737 the ExternalProject module.
4738 Examples
4740 The following example shows how to download and build a hypothetical
4741 project called FooBar from github:
4742 include(ExternalProject)
4744 ExternalProject_Add(foobar
4745 GIT_REPOSITORY git@github.com:FooCo/FooBar.git
4746 GIT_TAG origin/release/1.2.3
4747 )
4748 For the sake of the example, also define a second hypothetical external
4750 project called SecretSauce, which is downloaded from a web server. Two
4751 URLs are given to take advantage of a faster internal network if avail‐
4752 able, with a fallback to a slower external server. The project is a
4753 typical Makefile project with no configure step, so some of the default
4754 commands are overridden. The build is only required to build the sauce
4755 target:
4756 find_program(MAKE_EXE NAMES gmake nmake make)
4758 ExternalProject_Add(secretsauce
4759 URL http://intranet.somecompany.com/artifacts/sauce-2.7.tgz
4760 https://www.somecompany.com/downloads/sauce-2.7.zip
4761 URL_HASH MD5=d41d8cd98f00b204e9800998ecf8427e
4762 CONFIGURE_COMMAND ""
4763 BUILD_COMMAND ${MAKE_EXE} sauce
4764 )
4765 Suppose the build step of secretsauce requires that foobar must already
4767 be built. This could be enforced like so:
4768 ExternalProject_Add_StepDependencies(secretsauce build foobar)
4770 Another alternative would be to create a custom target for foobar’s
4772 build step and make secretsauce depend on that rather than the whole
4773 foobar project. This would mean foobar only needs to be built, it
4774 doesn’t need to run its install or test steps before secretsauce can be
4775 built. The dependency can also be defined along with the secretsauce
4776 project:
4777 ExternalProject_Add_StepTargets(foobar build)
4779 ExternalProject_Add(secretsauce
4780 URL http://intranet.somecompany.com/artifacts/sauce-2.7.tgz
4781 https://www.somecompany.com/downloads/sauce-2.7.zip
4782 URL_HASH MD5=d41d8cd98f00b204e9800998ecf8427e
4783 CONFIGURE_COMMAND ""
4784 BUILD_COMMAND ${MAKE_EXE} sauce
4785 DEPENDS foobar-build
4786 )
4787 Instead of calling ExternalProject_Add_StepTargets(), the target could
4789 be defined along with the foobar project itself:
4790 ExternalProject_Add(foobar
4792 GIT_REPOSITORY git@github.com:FooCo/FooBar.git
4793 GIT_TAG origin/release/1.2.3
4794 STEP_TARGETS build
4795 )
4796 If many external projects should have the same set of step targets,
4798 setting a directory property may be more convenient. The build step
4799 target could be created automatically by setting the EP_STEP_TARGETS
4800 directory property before creating the external projects with
4801 ExternalProject_Add():
4802 set_property(DIRECTORY PROPERTY EP_STEP_TARGETS build)
4804 Lastly, suppose that secretsauce provides a script called makedoc which
4806 can be used to generate its own documentation. Further suppose that the
4807 script expects the output directory to be provided as the only parame‐
4808 ter and that it should be run from the secretsauce source directory. A
4809 custom step and a custom target to trigger the script can be defined
4810 like so:
4811 ExternalProject_Add_Step(secretsauce docs
4813 COMMAND <SOURCE_DIR>/makedoc <BINARY_DIR>
4814 WORKING_DIRECTORY <SOURCE_DIR>
4815 COMMENT "Building secretsauce docs"
4816 ALWAYS TRUE
4817 EXCLUDE_FROM_MAIN TRUE
4818 )
4819 ExternalProject_Add_StepTargets(secretsauce docs)
4820 The custom step could then be triggered from the main build like so:
4822 cmake --build . --target secretsauce-docs
4824 FeatureSummary
4826 Functions for generating a summary of enabled/disabled features.
4827 These functions can be used to generate a summary of enabled and dis‐
4829 abled packages and/or feature for a build tree such as:
4830 -- The following OPTIONAL packages have been found:
4832 LibXml2 (required version >= 2.4), XML processing lib, <http://xmlsoft.org>
4833 * Enables HTML-import in MyWordProcessor
4834 * Enables odt-export in MyWordProcessor
4835 PNG, A PNG image library., <http://www.libpng.org/pub/png/>
4836 * Enables saving screenshots
4837 -- The following OPTIONAL packages have not been found:
4838 Lua51, The Lua scripting language., <http://www.lua.org>
4839 * Enables macros in MyWordProcessor
4840 Foo, Foo provides cool stuff.
4841 Global Properties
4843 FeatureSummary_PKG_TYPES
4844 The global property FeatureSummary_PKG_TYPES defines the type of pack‐
4846 ages used by FeatureSummary.
4847 The order in this list is important, the first package type in the list
4849 is the least important, the last is the most important. the of a pack‐
4850 age can only be changed to higher types.
4851 The default package types are , RUNTIME, OPTIONAL, RECOMMENDED and
4853 REQUIRED, and their importance is RUNTIME < OPTIONAL < RECOMMENDED <
4854 REQUIRED.
4855 FeatureSummary_REQUIRED_PKG_TYPES
4857 The global property FeatureSummary_REQUIRED_PKG_TYPES defines which
4859 package types are required.
4860 If one or more package in this categories has not been found, CMake
4862 will abort when calling feature_summary() with the ‘FATAL_ON_MISS‐
4863 ING_REQUIRED_PACKAGES’ option enabled.
4864 The default value for this global property is REQUIRED.
4866 FeatureSummary_DEFAULT_PKG_TYPE
4868 The global property FeatureSummary_DEFAULT_PKG_TYPE defines which pack‐
4870 age type is the default one. When calling feature_summary(), if the
4871 user did not set the package type explicitly, the package will be
4872 assigned to this category.
4873 This value must be one of the types defined in the
4875 FeatureSummary_PKG_TYPES global property unless the package type is set
4876 for all the packages.
4877 The default value for this global property is OPTIONAL.
4879 FeatureSummary_<TYPE>_DESCRIPTION
4881 The global property FeatureSummary_<TYPE>_DESCRIPTION can be defined
4883 for each type to replace the type name with the specified string when‐
4884 ever the package type is used in an output string.
4885 If not set, the string “<TYPE> packages” is used.
4887 Functions
4889 feature_summary
4890 feature_summary( [FILENAME <file>]
4892 [APPEND]
4893 [VAR <variable_name>]
4894 [INCLUDE_QUIET_PACKAGES]
4895 [FATAL_ON_MISSING_REQUIRED_PACKAGES]
4896 [DESCRIPTION "<description>" | DEFAULT_DESCRIPTION]
4897 [QUIET_ON_EMPTY]
4898 WHAT (ALL
4899 | PACKAGES_FOUND | PACKAGES_NOT_FOUND
4900 | <TYPE>_PACKAGES_FOUND | <TYPE>_PACKAGES_NOT_FOUND
4901 | ENABLED_FEATURES | DISABLED_FEATURES)
4902 )
4903 The feature_summary() macro can be used to print information
4905 about enabled or disabled packages or features of a project. By
4906 default, only the names of the features/packages will be printed
4907 and their required version when one was specified. Use
4908 set_package_properties() to add more useful information, like
4909 e.g. a download URL for the respective package or their purpose
4910 in the project.
4911 The WHAT option is the only mandatory option. Here you specify
4913 what information will be printed:
4914 ALL print everything
4916 ENABLED_FEATURES
4918 the list of all features which are enabled
4919 DISABLED_FEATURES
4921 the list of all features which are disabled
4922 PACKAGES_FOUND
4924 the list of all packages which have been found
4925 PACKAGES_NOT_FOUND
4927 the list of all packages which have not been found
4928 For each package type <TYPE> defined by the
4930 FeatureSummary_PKG_TYPES global property, the following informa‐
4931 tion can also be used:
4932 <TYPE>_PACKAGES_FOUND
4934 only those packages which have been found which have the
4935 type <TYPE>
4936 <TYPE>_PACKAGES_NOT_FOUND
4938 only those packages which have not been found which have
4939 the type <TYPE>
4940 With the exception of the ALL value, these values can be com‐
4942 bined in order to customize the output. For example:
4943 feature_summary(WHAT ENABLED_FEATURES DISABLED_FEATURES)
4945 If a FILENAME is given, the information is printed into this
4947 file. If APPEND is used, it is appended to this file, otherwise
4948 the file is overwritten if it already existed. If the VAR
4949 option is used, the information is “printed” into the specified
4950 variable. If FILENAME is not used, the information is printed
4951 to the terminal. Using the DESCRIPTION option a description or
4952 headline can be set which will be printed above the actual con‐
4953 tent. If only one type of package was requested, no title is
4954 printed, unless it is explicitly set using either DESCRIPTION to
4955 use a custom string, or DEFAULT_DESCRIPTION to use a default
4956 title for the requested type. If INCLUDE_QUIET_PACKAGES is
4957 given, packages which have been searched with find_package(...
4958 QUIET) will also be listed. By default they are skipped. If
4959 FATAL_ON_MISSING_REQUIRED_PACKAGES is given, CMake will abort if
4960 a package which is marked as one of the package types listed in
4961 the FeatureSummary_REQUIRED_PKG_TYPES global property has not
4962 been found. The default value for the
4963 FeatureSummary_REQUIRED_PKG_TYPES global property is REQUIRED.
4964 The FeatureSummary_DEFAULT_PKG_TYPE global property can be modi‐
4966 fied to change the default package type assigned when not
4967 explicitly assigned by the user.
4968 If the QUIET_ON_EMPTY option is used, if only one type of pack‐
4970 age was requested, and no packages belonging to that category
4971 were found, then no output (including the DESCRIPTION) is
4972 printed or added to the VAR variable.
4973 Example 1, append everything to a file:
4975 include(FeatureSummary)
4977 feature_summary(WHAT ALL
4978 FILENAME ${CMAKE_BINARY_DIR}/all.log APPEND)
4979 Example 2, print the enabled features into the variable enabled‐
4981 FeaturesText, including QUIET packages:
4982 include(FeatureSummary)
4984 feature_summary(WHAT ENABLED_FEATURES
4985 INCLUDE_QUIET_PACKAGES
4986 DESCRIPTION "Enabled Features:"
4987 VAR enabledFeaturesText)
4988 message(STATUS "${enabledFeaturesText}")
4989 Example 3, change default package types and print only the cate‐
4991 gories that are not empty:
4992 include(FeatureSummary)
4994 set_property(GLOBAL APPEND PROPERTY FeatureSummary_PKG_TYPES BUILD)
4995 find_package(FOO)
4996 set_package_properties(FOO PROPERTIES TYPE BUILD)
4997 feature_summary(WHAT BUILD_PACKAGES_FOUND
4998 Description "Build tools found:"
4999 QUIET_ON_EMPTY)
5000 feature_summary(WHAT BUILD_PACKAGES_NOT_FOUND
5001 Description "Build tools not found:"
5002 QUIET_ON_EMPTY)
5003 set_package_properties
5005 set_package_properties(<name> PROPERTIES
5007 [ URL <url> ]
5008 [ DESCRIPTION <description> ]
5009 [ TYPE (RUNTIME|OPTIONAL|RECOMMENDED|REQUIRED) ]
5010 [ PURPOSE <purpose> ]
5011 )
5012 Use this macro to set up information about the named package,
5014 which can then be displayed via FEATURE_SUMMARY(). This can be
5015 done either directly in the Find-module or in the project which
5016 uses the module after the find_package() call. The features for
5017 which information can be set are added automatically by the
5018 find_package() command.
5019 URL <url>
5021 This should be the homepage of the package, or something
5022 similar. Ideally this is set already directly in the
5023 Find-module.
5024 DESCRIPTION <description>
5026 A short description what that package is, at most one
5027 sentence. Ideally this is set already directly in the
5028 Find-module.
5029 TYPE <type>
5031 What type of dependency has the using project on that
5032 package. Default is OPTIONAL. In this case it is a
5033 package which can be used by the project when available
5034 at buildtime, but it also work without. RECOMMENDED is
5035 similar to OPTIONAL, i.e. the project will build if the
5036 package is not present, but the functionality of the
5037 resulting binaries will be severely limited. If a
5038 REQUIRED package is not available at buildtime, the
5039 project may not even build. This can be combined with
5040 the FATAL_ON_MISSING_REQUIRED_PACKAGES argument for fea‐
5041 ture_summary(). Last, a RUNTIME package is a package
5042 which is actually not used at all during the build, but
5043 which is required for actually running the resulting
5044 binaries. So if such a package is missing, the project
5045 can still be built, but it may not work later on. If
5046 set_package_properties() is called multiple times for the
5047 same package with different TYPEs, the TYPE is only
5048 changed to higher TYPEs (RUNTIME < OPTIONAL < RECOMMENDED
5049 < REQUIRED), lower TYPEs are ignored. The TYPE property
5050 is project-specific, so it cannot be set by the Find-mod‐
5051 ule, but must be set in the project. Type accepted can
5052 be changed by setting the FeatureSummary_PKG_TYPES global
5053 property.
5054 PURPOSE <purpose>
5056 This describes which features this package enables in the
5057 project, i.e. it tells the user what functionality he
5058 gets in the resulting binaries. If set_package_proper‐
5059 ties() is called multiple times for a package, all PUR‐
5060 POSE properties are appended to a list of purposes of the
5061 package in the project. As the TYPE property, also the
5062 PURPOSE property is project-specific, so it cannot be set
5063 by the Find-module, but must be set in the project.
5064 Example for setting the info for a package:
5066 find_package(LibXml2)
5068 set_package_properties(LibXml2 PROPERTIES
5069 DESCRIPTION "A XML processing library."
5070 URL "http://xmlsoft.org/")
5071 # or
5072 set_package_properties(LibXml2 PROPERTIES
5073 TYPE RECOMMENDED
5074 PURPOSE "Enables HTML-import in MyWordProcessor")
5075 # or
5076 set_package_properties(LibXml2 PROPERTIES
5077 TYPE OPTIONAL
5078 PURPOSE "Enables odt-export in MyWordProcessor")
5079 find_package(DBUS)
5081 set_package_properties(DBUS PROPERTIES
5082 TYPE RUNTIME
5083 PURPOSE "Necessary to disable the screensaver during a presentation")
5084 add_feature_info
5086 add_feature_info(<name> <enabled> <description>)
5088 Use this macro to add information about a feature with the given
5090 <name>. <enabled> contains whether this feature is enabled or
5091 not. It can be a variable or a list of conditions. <descrip‐
5092 tion> is a text describing the feature. The information can be
5093 displayed using feature_summary() for ENABLED_FEATURES and DIS‐
5094 ABLED_FEATURES respectively.
5095 Example for setting the info for a feature:
5097 option(WITH_FOO "Help for foo" ON)
5099 add_feature_info(Foo WITH_FOO "The Foo feature provides very cool stuff.")
5100 Legacy Macros
5102 The following macros are provided for compatibility with previous CMake
5103 versions:
5104 set_package_info
5106 set_package_info(<name> <description> [ <url> [<purpose>] ])
5108 Use this macro to set up information about the named package,
5110 which can then be displayed via feature_summary(). This can be
5111 done either directly in the Find-module or in the project which
5112 uses the module after the find_package() call. The features for
5113 which information can be set are added automatically by the
5114 find_package() command.
5115 set_feature_info
5117 set_feature_info(<name> <description> [<url>])
5119 Does the same as:
5121 set_package_info(<name> <description> <url>)
5123 print_enabled_features
5125 print_enabled_features()
5127 Does the same as
5129 feature_summary(WHAT ENABLED_FEATURES DESCRIPTION "Enabled features:")
5131 print_disabled_features
5133 print_disabled_features()
5135 Does the same as
5137 feature_summary(WHAT DISABLED_FEATURES DESCRIPTION "Disabled features:")
5139 FetchContent
5141 Overview
5142 This module enables populating content at configure time via any method
5143 supported by the ExternalProject module. Whereas ExternalProject_Add()
5144 downloads at build time, the FetchContent module makes content avail‐
5145 able immediately, allowing the configure step to use the content in
5146 commands like add_subdirectory(), include() or file() operations.
5147 Content population details would normally be defined separately from
5149 the command that performs the actual population. This separation
5150 ensures that all of the dependency details are defined before anything
5151 may try to use those details to populate content. This is particularly
5152 important in more complex project hierarchies where dependencies may be
5153 shared between multiple projects.
5154 The following shows a typical example of declaring content details:
5156 FetchContent_Declare(
5158 googletest
5159 GIT_REPOSITORY https://github.com/google/googletest.git
5160 GIT_TAG release-1.8.0
5161 )
5162 For most typical cases, populating the content can then be done with a
5164 single command like so:
5165 FetchContent_MakeAvailable(googletest)
5167 The above command not only populates the content, it also adds it to
5169 the main build (if possible) so that the main build can use the popu‐
5170 lated project’s targets, etc. In some cases, the main project may need
5171 to have more precise control over the population or may be required to
5172 explicitly define the population steps (e.g. if CMake versions earlier
5173 than 3.14 need to be supported). The typical pattern of such custom
5174 steps looks like this:
5175 FetchContent_GetProperties(googletest)
5177 if(NOT googletest_POPULATED)
5178 FetchContent_Populate(googletest)
5179 add_subdirectory(${googletest_SOURCE_DIR} ${googletest_BINARY_DIR})
5180 endif()
5181 Regardless of which population method is used, when using the
5183 declare-populate pattern with a hierarchical project arrangement,
5184 projects at higher levels in the hierarchy are able to override the
5185 population details of content specified anywhere lower in the project
5186 hierarchy. The ability to detect whether content has already been pop‐
5187 ulated ensures that even if multiple child projects want certain con‐
5188 tent to be available, the first one to populate it wins. The other
5189 child project can simply make use of the already available content
5190 instead of repeating the population for itself. See the Examples sec‐
5191 tion which demonstrates this scenario.
5192 The FetchContent module also supports defining and populating content
5194 in a single call, with no check for whether the content has been popu‐
5195 lated elsewhere in the project already. This is a more low level oper‐
5196 ation and would not normally be the way the module is used, but it is
5197 sometimes useful as part of implementing some higher level feature or
5198 to populate some content in CMake’s script mode.
5199 Declaring Content Details
5201 FetchContent_Declare
5202 FetchContent_Declare(<name> <contentOptions>...)
5204 The FetchContent_Declare() function records the options that
5206 describe how to populate the specified content, but if such
5207 details have already been recorded earlier in this project
5208 (regardless of where in the project hierarchy), this and all
5209 later calls for the same content <name> are ignored. This
5210 “first to record, wins” approach is what allows hierarchical
5211 projects to have parent projects override content details of
5212 child projects.
5213 The content <name> can be any string without spaces, but good
5215 practice would be to use only letters, numbers and underscores.
5216 The name will be treated case-insensitively and it should be
5217 obvious for the content it represents, often being the name of
5218 the child project or the value given to its top level project()
5219 command (if it is a CMake project). For well-known public
5220 projects, the name should generally be the official name of the
5221 project. Choosing an unusual name makes it unlikely that other
5222 projects needing that same content will use the same name, lead‐
5223 ing to the content being populated multiple times.
5224 The <contentOptions> can be any of the download or update/patch
5226 options that the ExternalProject_Add() command understands. The
5227 configure, build, install and test steps are explicitly disabled
5228 and therefore options related to them will be ignored. In most
5229 cases, <contentOptions> will just be a couple of options defin‐
5230 ing the download method and method-specific details like a com‐
5231 mit tag or archive hash. For example:
5232 FetchContent_Declare(
5234 googletest
5235 GIT_REPOSITORY https://github.com/google/googletest.git
5236 GIT_TAG release-1.8.0
5237 )
5238 FetchContent_Declare(
5240 myCompanyIcons
5241 URL https://intranet.mycompany.com/assets/iconset_1.12.tar.gz
5242 URL_HASH 5588a7b18261c20068beabfb4f530b87
5243 )
5244 FetchContent_Declare(
5246 myCompanyCertificates
5247 SVN_REPOSITORY svn+ssh://svn.mycompany.com/srv/svn/trunk/certs
5248 SVN_REVISION -r12345
5249 )
5250 Populating The Content
5252 For most common scenarios, population means making content available to
5253 the main build according to previously declared details for that depen‐
5254 dency. There are two main patterns for populating content, one based
5255 on calling FetchContent_GetProperties() and FetchContent_Populate() for
5256 more precise control and the other on calling
5257 FetchContent_MakeAvailable() for a simpler, more automated approach.
5258 The former generally follows this canonical pattern:
5259 # Check if population has already been performed
5261 FetchContent_GetProperties(<name>)
5262 string(TOLOWER "<name>" lcName)
5263 if(NOT ${lcName}_POPULATED)
5264 # Fetch the content using previously declared details
5265 FetchContent_Populate(<name>)
5266 # Set custom variables, policies, etc.
5268 # ...
5269 # Bring the populated content into the build
5271 add_subdirectory(${${lcName}_SOURCE_DIR} ${${lcName}_BINARY_DIR})
5272 endif()
5273 The above is such a common pattern that, where no custom steps are
5275 needed between the calls to FetchContent_Populate() and add_subdirec‐
5276 tory(), equivalent logic can be obtained by calling
5277 FetchContent_MakeAvailable() instead (and should be preferred where it
5278 meets the needs of the project).
5279 FetchContent_Populate
5281 FetchContent_Populate( <name> )
5283 In most cases, the only argument given to FetchContent_Popu‐
5285 late() is the <name>. When used this way, the command assumes
5286 the content details have been recorded by an earlier call to
5287 FetchContent_Declare(). The details are stored in a global
5288 property, so they are unaffected by things like variable or
5289 directory scope. Therefore, it doesn’t matter where in the
5290 project the details were previously declared, as long as they
5291 have been declared before the call to FetchContent_Populate().
5292 Those saved details are then used to construct a call to Exter‐
5293 nalProject_Add() in a private sub-build to perform the content
5294 population immediately. The implementation of ExternalPro‐
5295 ject_Add() ensures that if the content has already been popu‐
5296 lated in a previous CMake run, that content will be reused
5297 rather than repopulating them again. For the common case where
5298 population involves downloading content, the cost of the down‐
5299 load is only paid once.
5300 An internal global property records when a particular content
5302 population request has been processed. If FetchContent_Popu‐
5303 late() is called more than once for the same content name within
5304 a configure run, the second call will halt with an error.
5305 Projects can and should check whether content population has
5306 already been processed with the FetchContent_GetProperties()
5307 command before calling FetchContent_Populate().
5308 FetchContent_Populate() will set three variables in the scope of
5310 the caller; <lcName>_POPULATED, <lcName>_SOURCE_DIR and
5311 <lcName>_BINARY_DIR, where <lcName> is the lowercased <name>.
5312 <lcName>_POPULATED will always be set to True by the call.
5313 <lcName>_SOURCE_DIR is the location where the content can be
5314 found upon return (it will have already been populated), while
5315 <lcName>_BINARY_DIR is a directory intended for use as a corre‐
5316 sponding build directory. The main use case for the two direc‐
5317 tory variables is to call add_subdirectory() immediately after
5318 population, i.e.:
5319 FetchContent_Populate(FooBar ...)
5321 add_subdirectory(${foobar_SOURCE_DIR} ${foobar_BINARY_DIR})
5322 The values of the three variables can also be retrieved from
5324 anywhere in the project hierarchy using the
5325 FetchContent_GetProperties() command.
5326 A number of cache variables influence the behavior of all con‐
5328 tent population performed using details saved from a
5329 FetchContent_Declare() call:
5330 FETCHCONTENT_BASE_DIR
5332 In most cases, the saved details do not specify any
5333 options relating to the directories to use for the inter‐
5334 nal sub-build, final source and build areas. It is gen‐
5335 erally best to leave these decisions up to the FetchCon‐
5336 tent module to handle on the project’s behalf. The
5337 FETCHCONTENT_BASE_DIR cache variable controls the point
5338 under which all content population directories are col‐
5339 lected, but in most cases developers would not need to
5340 change this. The default location is
5341 ${CMAKE_BINARY_DIR}/_deps, but if developers change this
5342 value, they should aim to keep the path short and just
5343 below the top level of the build tree to avoid running
5344 into path length problems on Windows.
5345 FETCHCONTENT_QUIET
5347 The logging output during population can be quite ver‐
5348 bose, making the configure stage quite noisy. This cache
5349 option (ON by default) hides all population output unless
5350 an error is encountered. If experiencing problems with
5351 hung downloads, temporarily switching this option off may
5352 help diagnose which content population is causing the
5353 issue.
5354 FETCHCONTENT_FULLY_DISCONNECTED
5356 When this option is enabled, no attempt is made to down‐
5357 load or update any content. It is assumed that all con‐
5358 tent has already been populated in a previous run or the
5359 source directories have been pointed at existing contents
5360 the developer has provided manually (using options
5361 described further below). When the developer knows that
5362 no changes have been made to any content details, turning
5363 this option ON can significantly speed up the configure
5364 stage. It is OFF by default.
5365 FETCHCONTENT_UPDATES_DISCONNECTED
5367 This is a less severe download/update control compared to
5368 FETCHCONTENT_FULLY_DISCONNECTED. Instead of bypassing
5369 all download and update logic, the FETCHCON‐
5370 TENT_UPDATES_DISCONNECTED only disables the update stage.
5371 Therefore, if content has not been downloaded previously,
5372 it will still be downloaded when this option is enabled.
5373 This can speed up the configure stage, but not as much as
5374 FETCHCONTENT_FULLY_DISCONNECTED. It is OFF by default.
5375 In addition to the above cache variables, the following cache
5377 variables are also defined for each content name (<ucName> is
5378 the uppercased value of <name>):
5379 FETCHCONTENT_SOURCE_DIR_<ucName>
5381 If this is set, no download or update steps are performed
5382 for the specified content and the <lcName>_SOURCE_DIR
5383 variable returned to the caller is pointed at this loca‐
5384 tion. This gives developers a way to have a separate
5385 checkout of the content that they can modify freely with‐
5386 out interference from the build. The build simply uses
5387 that existing source, but it still defines
5388 <lcName>_BINARY_DIR to point inside its own build area.
5389 Developers are strongly encouraged to use this mechanism
5390 rather than editing the sources populated in the default
5391 location, as changes to sources in the default location
5392 can be lost when content population details are changed
5393 by the project.
5394 FETCHCONTENT_UPDATES_DISCONNECTED_<ucName>
5396 This is the per-content equivalent of FETCHCON‐
5397 TENT_UPDATES_DISCONNECTED. If the global option or this
5398 option is ON, then updates will be disabled for the named
5399 content. Disabling updates for individual content can be
5400 useful for content whose details rarely change, while
5401 still leaving other frequently changing content with
5402 updates enabled.
5403 The FetchContent_Populate() command also supports a syntax
5405 allowing the content details to be specified directly rather
5406 than using any saved details. This is more low-level and use of
5407 this form is generally to be avoided in favour of using saved
5408 content details as outlined above. Nevertheless, in certain
5409 situations it can be useful to invoke the content population as
5410 an isolated operation (typically as part of implementing some
5411 other higher level feature or when using CMake in script mode):
5412 FetchContent_Populate( <name>
5414 [QUIET]
5415 [SUBBUILD_DIR <subBuildDir>]
5416 [SOURCE_DIR <srcDir>]
5417 [BINARY_DIR <binDir>]
5418 ...
5419 )
5420 This form has a number of key differences to that where only
5422 <name> is provided:
5423 · All required population details are assumed to have been pro‐
5425 vided directly in the call to FetchContent_Populate(). Any
5426 saved details for <name> are ignored.
5427 · No check is made for whether content for <name> has already
5429 been populated.
5430 · No global property is set to record that the population has
5432 occurred.
5433 · No global properties record the source or binary directories
5435 used for the populated content.
5436 · The FETCHCONTENT_FULLY_DISCONNECTED and FETCHCON‐
5438 TENT_UPDATES_DISCONNECTED cache variables are ignored.
5439 The <lcName>_SOURCE_DIR and <lcName>_BINARY_DIR variables are
5441 still returned to the caller, but since these locations are not
5442 stored as global properties when this form is used, they are
5443 only available to the calling scope and below rather than the
5444 entire project hierarchy. No <lcName>_POPULATED variable is set
5445 in the caller’s scope with this form.
5446 The supported options for FetchContent_Populate() are the same
5448 as those for FetchContent_Declare(). Those few options shown
5449 just above are either specific to FetchContent_Populate() or
5450 their behavior is slightly modified from how ExternalPro‐
5451 ject_Add() treats them.
5452 QUIET The QUIET option can be given to hide the output associ‐
5454 ated with populating the specified content. If the popu‐
5455 lation fails, the output will be shown regardless of
5456 whether this option was given or not so that the cause of
5457 the failure can be diagnosed. The global FETCHCON‐
5458 TENT_QUIET cache variable has no effect on FetchCon‐
5459 tent_Populate() calls where the content details are pro‐
5460 vided directly.
5461 SUBBUILD_DIR
5463 The SUBBUILD_DIR argument can be provided to change the
5464 location of the sub-build created to perform the popula‐
5465 tion. The default value is ${CMAKE_CUR‐
5466 RENT_BINARY_DIR}/<lcName>-subbuild and it would be
5467 unusual to need to override this default. If a relative
5468 path is specified, it will be interpreted as relative to
5469 CMAKE_CURRENT_BINARY_DIR.
5470 SOURCE_DIR, BINARY_DIR
5472 The SOURCE_DIR and BINARY_DIR arguments are supported by
5473 ExternalProject_Add(), but different default values are
5474 used by FetchContent_Populate(). SOURCE_DIR defaults to
5475 ${CMAKE_CURRENT_BINARY_DIR}/<lcName>-src and BINARY_DIR
5476 defaults to ${CMAKE_CURRENT_BINARY_DIR}/<lcName>-build.
5477 If a relative path is specified, it will be interpreted
5478 as relative to CMAKE_CURRENT_BINARY_DIR.
5479 In addition to the above explicit options, any other unrecog‐
5481 nized options are passed through unmodified to ExternalPro‐
5482 ject_Add() to perform the download, patch and update steps. The
5483 following options are explicitly prohibited (they are disabled
5484 by the FetchContent_Populate() command):
5485 · CONFIGURE_COMMAND
5487 · BUILD_COMMAND
5489 · INSTALL_COMMAND
5491 · TEST_COMMAND
5493 If using FetchContent_Populate() within CMake’s script mode, be
5495 aware that the implementation sets up a sub-build which there‐
5496 fore requires a CMake generator and build tool to be available.
5497 If these cannot be found by default, then the CMAKE_GENERATOR
5498 and/or CMAKE_MAKE_PROGRAM variables will need to be set appro‐
5499 priately on the command line invoking the script.
5500 FetchContent_GetProperties
5502 When using saved content details, a call to
5503 FetchContent_Populate() records information in global properties
5504 which can be queried at any time. This information includes the
5505 source and binary directories associated with the content and
5506 also whether or not the content population has been processed
5507 during the current configure run.
5508 FetchContent_GetProperties( <name>
5510 [SOURCE_DIR <srcDirVar>]
5511 [BINARY_DIR <binDirVar>]
5512 [POPULATED <doneVar>]
5513 )
5514 The SOURCE_DIR, BINARY_DIR and POPULATED options can be used to
5516 specify which properties should be retrieved. Each option
5517 accepts a value which is the name of the variable in which to
5518 store that property. Most of the time though, only <name> is
5519 given, in which case the call will then set the same variables
5520 as a call to FetchContent_Populate(name). This allows the fol‐
5521 lowing canonical pattern to be used, which ensures that the rel‐
5522 evant variables will always be defined regardless of whether or
5523 not the population has been performed elsewhere in the project
5524 already:
5525 FetchContent_GetProperties(foobar)
5527 if(NOT foobar_POPULATED)
5528 FetchContent_Populate(foobar)
5529 ...
5530 endif()
5531 The above pattern allows other parts of the overall project
5533 hierarchy to re-use the same content and ensure that it is only
5534 populated once.
5535 FetchContent_MakeAvailable
5537 FetchContent_MakeAvailable( <name1> [<name2>...] )
5539 This command implements the common pattern typically needed for
5541 most dependencies. It iterates over each of the named dependen‐
5542 cies in turn and for each one it loosely follows the same
5543 canonical pattern as presented at the beginning of this section.
5544 One small difference to that pattern is that it will only call
5545 add_subdirectory() on the populated content if there is a CMake‐
5546 Lists.txt file in its top level source directory. This allows
5547 the command to be used for dependencies that make downloaded
5548 content available at a known location but which do not need or
5549 support being added directly to the build.
5550 Examples
5552 This first fairly straightforward example ensures that some popular
5553 testing frameworks are available to the main build:
5554 include(FetchContent)
5556 FetchContent_Declare(
5557 googletest
5558 GIT_REPOSITORY https://github.com/google/googletest.git
5559 GIT_TAG release-1.8.0
5560 )
5561 FetchContent_Declare(
5562 Catch2
5563 GIT_REPOSITORY https://github.com/catchorg/Catch2.git
5564 GIT_TAG v2.5.0
5565 )
5566 # After the following call, the CMake targets defined by googletest and
5568 # Catch2 will be defined and available to the rest of the build
5569 FetchContent_MakeAvailable(googletest Catch2)
5570 In more complex project hierarchies, the dependency relationships can
5572 be more complicated. Consider a hierarchy where projA is the top level
5573 project and it depends directly on projects projB and projC. Both
5574 projB and projC can be built standalone and they also both depend on
5575 another project projD. projB additionally depends on projE. This
5576 example assumes that all five projects are available on a company git
5577 server. The CMakeLists.txt of each project might have sections like
5578 the following:
5579 projA:
5581 include(FetchContent)
5583 FetchContent_Declare(
5584 projB
5585 GIT_REPOSITORY git@mycompany.com:git/projB.git
5586 GIT_TAG 4a89dc7e24ff212a7b5167bef7ab079d
5587 )
5588 FetchContent_Declare(
5589 projC
5590 GIT_REPOSITORY git@mycompany.com:git/projC.git
5591 GIT_TAG 4ad4016bd1d8d5412d135cf8ceea1bb9
5592 )
5593 FetchContent_Declare(
5594 projD
5595 GIT_REPOSITORY git@mycompany.com:git/projD.git
5596 GIT_TAG origin/integrationBranch
5597 )
5598 FetchContent_Declare(
5599 projE
5600 GIT_REPOSITORY git@mycompany.com:git/projE.git
5601 GIT_TAG origin/release/2.3-rc1
5602 )
5603 # Order is important, see notes in the discussion further below
5605 FetchContent_MakeAvailable(projD projB projC)
5606 projB:
5608 include(FetchContent)
5610 FetchContent_Declare(
5611 projD
5612 GIT_REPOSITORY git@mycompany.com:git/projD.git
5613 GIT_TAG 20b415f9034bbd2a2e8216e9a5c9e632
5614 )
5615 FetchContent_Declare(
5616 projE
5617 GIT_REPOSITORY git@mycompany.com:git/projE.git
5618 GIT_TAG 68e20f674a48be38d60e129f600faf7d
5619 )
5620 FetchContent_MakeAvailable(projD projE)
5622 projC:
5624 include(FetchContent)
5626 FetchContent_Declare(
5627 projD
5628 GIT_REPOSITORY git@mycompany.com:git/projD.git
5629 GIT_TAG 7d9a17ad2c962aa13e2fbb8043fb6b8a
5630 )
5631 # This particular version of projD requires workarounds
5633 FetchContent_GetProperties(projD)
5634 if(NOT projd_POPULATED)
5635 FetchContent_Populate(projD)
5636 # Copy an additional/replacement file into the populated source
5638 file(COPY someFile.c DESTINATION ${projd_SOURCE_DIR}/src)
5639 add_subdirectory(${projd_SOURCE_DIR} ${projd_BINARY_DIR})
5641 endif()
5642 A few key points should be noted in the above:
5644 · projB and projC define different content details for projD, but projA
5646 also defines a set of content details for projD. Because projA will
5647 define them first, the details from projB and projC will not be used.
5648 The override details defined by projA are not required to match
5649 either of those from projB or projC, but it is up to the higher level
5650 project to ensure that the details it does define still make sense
5651 for the child projects.
5652 · In the projA call to FetchContent_MakeAvailable(), projD is listed
5654 ahead of projB and projC to ensure that projA is in control of how
5655 projD is populated.
5656 · While projA defines content details for projE, it does not need to
5658 explicitly call FetchContent_MakeAvailable(projE) or FetchCon‐
5659 tent_Populate(projD) itself. Instead, it leaves that to the child
5660 projB. For higher level projects, it is often enough to just define
5661 the override content details and leave the actual population to the
5662 child projects. This saves repeating the same thing at each level of
5663 the project hierarchy unnecessarily.
5664 Projects don’t always need to add the populated content to the build.
5666 Sometimes the project just wants to make the downloaded content avail‐
5667 able at a predictable location. The next example ensures that a set of
5668 standard company toolchain files (and potentially even the toolchain
5669 binaries themselves) is available early enough to be used for that same
5670 build.
5671 cmake_minimum_required(VERSION 3.14)
5673 include(FetchContent)
5675 FetchContent_Declare(
5676 mycom_toolchains
5677 URL https://intranet.mycompany.com//toolchains_1.3.2.tar.gz
5678 )
5679 FetchContent_MakeAvailable(mycom_toolchains)
5680 project(CrossCompileExample)
5682 The project could be configured to use one of the downloaded toolchains
5684 like so:
5685 cmake -DCMAKE_TOOLCHAIN_FILE=_deps/mycom_toolchains-src/toolchain_arm.cmake /path/to/src
5687 When CMake processes the CMakeLists.txt file, it will download and
5689 unpack the tarball into _deps/mycompany_toolchains-src relative to the
5690 build directory. The CMAKE_TOOLCHAIN_FILE variable is not used until
5691 the project() command is reached, at which point CMake looks for the
5692 named toolchain file relative to the build directory. Because the tar‐
5693 ball has already been downloaded and unpacked by then, the toolchain
5694 file will be in place, even the very first time that cmake is run in
5695 the build directory.
5696 Lastly, the following example demonstrates how one might download and
5698 unpack a firmware tarball using CMake’s script mode. The call to
5699 FetchContent_Populate() specifies all the content details and the
5700 unpacked firmware will be placed in a firmware directory below the cur‐
5701 rent working directory.
5702 getFirmware.cmake:
5704 # NOTE: Intended to be run in script mode with cmake -P
5706 include(FetchContent)
5707 FetchContent_Populate(
5708 firmware
5709 URL https://mycompany.com/assets/firmware-1.23-arm.tar.gz
5710 URL_HASH MD5=68247684da89b608d466253762b0ff11
5711 SOURCE_DIR firmware
5712 )
5713 FindPackageHandleStandardArgs
5715 This module provides a function intended to be used in Find Modules
5716 implementing find_package(<PackageName>) calls. It handles the
5717 REQUIRED, QUIET and version-related arguments of find_package. It also
5718 sets the <PackageName>_FOUND variable. The package is considered found
5719 if all variables listed contain valid results, e.g. valid filepaths.
5720 find_package_handle_standard_args
5722 There are two signatures:
5723 find_package_handle_standard_args(<PackageName>
5725 (DEFAULT_MSG|<custom-failure-message>)
5726 <required-var>...
5727 )
5728 find_package_handle_standard_args(<PackageName>
5730 [FOUND_VAR <result-var>]
5731 [REQUIRED_VARS <required-var>...]
5732 [VERSION_VAR <version-var>]
5733 [HANDLE_COMPONENTS]
5734 [CONFIG_MODE]
5735 [REASON_FAILURE_MESSAGE <reason-failure-message>]
5736 [FAIL_MESSAGE <custom-failure-message>]
5737 )
5738 The <PackageName>_FOUND variable will be set to TRUE if all the
5740 variables <required-var>... are valid and any optional con‐
5741 straints are satisfied, and FALSE otherwise. A success or fail‐
5742 ure message may be displayed based on the results and on whether
5743 the REQUIRED and/or QUIET option was given to the find_package()
5744 call.
5745 The options are:
5747 (DEFAULT_MSG|<custom-failure-message>)
5749 In the simple signature this specifies the failure mes‐
5750 sage. Use DEFAULT_MSG to ask for a default message to be
5751 computed (recommended). Not valid in the full signature.
5752 FOUND_VAR <result-var>
5754 Obsolete. Specifies either <PackageName>_FOUND or <PACK‐
5755 AGENAME>_FOUND as the result variable. This exists only
5756 for compatibility with older versions of CMake and is now
5757 ignored. Result variables of both names are always set
5758 for compatibility.
5759 REQUIRED_VARS <required-var>...
5761 Specify the variables which are required for this pack‐
5762 age. These may be named in the generated failure message
5763 asking the user to set the missing variable values.
5764 Therefore these should typically be cache entries such as
5765 FOO_LIBRARY and not output variables like FOO_LIBRARIES.
5766 VERSION_VAR <version-var>
5768 Specify the name of a variable that holds the version of
5769 the package that has been found. This version will be
5770 checked against the (potentially) specified required ver‐
5771 sion given to the find_package() call, including its
5772 EXACT option. The default messages include information
5773 about the required version and the version which has been
5774 actually found, both if the version is ok or not.
5775 HANDLE_COMPONENTS
5777 Enable handling of package components. In this case, the
5778 command will report which components have been found and
5779 which are missing, and the <PackageName>_FOUND variable
5780 will be set to FALSE if any of the required components
5781 (i.e. not the ones listed after the OPTIONAL_COMPONENTS
5782 option of find_package()) are missing.
5783 CONFIG_MODE
5785 Specify that the calling find module is a wrapper around
5786 a call to find_package(<PackageName> NO_MODULE). This
5787 implies a VERSION_VAR value of <PackageName>_VERSION.
5788 The command will automatically check whether the package
5789 configuration file was found.
5790 REASON_FAILURE_MESSAGE <reason-failure-message>
5792 Specify a custom message of the reason for the failure
5793 which will be appended to the default generated message.
5794 FAIL_MESSAGE <custom-failure-message>
5796 Specify a custom failure message instead of using the
5797 default generated message. Not recommended.
5798 Example for the simple signature:
5800 find_package_handle_standard_args(LibXml2 DEFAULT_MSG
5802 LIBXML2_LIBRARY LIBXML2_INCLUDE_DIR)
5803 The LibXml2 package is considered to be found if both LIBXML2_LIBRARY
5805 and LIBXML2_INCLUDE_DIR are valid. Then also LibXml2_FOUND is set to
5806 TRUE. If it is not found and REQUIRED was used, it fails with a mes‐
5807 sage(FATAL_ERROR), independent whether QUIET was used or not. If it is
5808 found, success will be reported, including the content of the first
5809 <required-var>. On repeated CMake runs, the same message will not be
5810 printed again.
5811 Example for the full signature:
5813 find_package_handle_standard_args(LibArchive
5815 REQUIRED_VARS LibArchive_LIBRARY LibArchive_INCLUDE_DIR
5816 VERSION_VAR LibArchive_VERSION)
5817 In this case, the LibArchive package is considered to be found if both
5819 LibArchive_LIBRARY and LibArchive_INCLUDE_DIR are valid. Also the ver‐
5820 sion of LibArchive will be checked by using the version contained in
5821 LibArchive_VERSION. Since no FAIL_MESSAGE is given, the default mes‐
5822 sages will be printed.
5823 Another example for the full signature:
5825 find_package(Automoc4 QUIET NO_MODULE HINTS /opt/automoc4)
5827 find_package_handle_standard_args(Automoc4 CONFIG_MODE)
5828 In this case, a FindAutmoc4.cmake module wraps a call to find_pack‐
5830 age(Automoc4 NO_MODULE) and adds an additional search directory for
5831 automoc4. Then the call to find_package_handle_standard_args produces
5832 a proper success/failure message.
5833 FindPackageMessage
5835 find_package_message(<name> "message for user" "find result details")
5836 This function is intended to be used in FindXXX.cmake modules files.
5838 It will print a message once for each unique find result. This is use‐
5839 ful for telling the user where a package was found. The first argument
5840 specifies the name (XXX) of the package. The second argument specifies
5841 the message to display. The third argument lists details about the
5842 find result so that if they change the message will be displayed again.
5843 The macro also obeys the QUIET argument to the find_package command.
5844 Example:
5846 if(X11_FOUND)
5848 find_package_message(X11 "Found X11: ${X11_X11_LIB}"
5849 "[${X11_X11_LIB}][${X11_INCLUDE_DIR}]")
5850 else()
5851 ...
5852 endif()
5853 FortranCInterface
5855 Fortran/C Interface Detection
5856 This module automatically detects the API by which C and Fortran lan‐
5858 guages interact.
5859 Module Variables
5861 Variables that indicate if the mangling is found:
5862 FortranCInterface_GLOBAL_FOUND
5864 Global subroutines and functions.
5865 FortranCInterface_MODULE_FOUND
5867 Module subroutines and functions (declared by “MODULE PROCE‐
5868 DURE”).
5869 This module also provides the following variables to specify the
5871 detected mangling, though a typical use case does not need to reference
5872 them and can use the Module Functions below.
5873 FortranCInterface_GLOBAL_PREFIX
5875 Prefix for a global symbol without an underscore.
5876 FortranCInterface_GLOBAL_SUFFIX
5878 Suffix for a global symbol without an underscore.
5879 FortranCInterface_GLOBAL_CASE
5881 The case for a global symbol without an underscore, either UPPER
5882 or LOWER.
5883 FortranCInterface_GLOBAL__PREFIX
5885 Prefix for a global symbol with an underscore.
5886 FortranCInterface_GLOBAL__SUFFIX
5888 Suffix for a global symbol with an underscore.
5889 FortranCInterface_GLOBAL__CASE
5891 The case for a global symbol with an underscore, either UPPER or
5892 LOWER.
5893 FortranCInterface_MODULE_PREFIX
5895 Prefix for a module symbol without an underscore.
5896 FortranCInterface_MODULE_MIDDLE
5898 Middle of a module symbol without an underscore that appears
5899 between the name of the module and the name of the symbol.
5900 FortranCInterface_MODULE_SUFFIX
5902 Suffix for a module symbol without an underscore.
5903 FortranCInterface_MODULE_CASE
5905 The case for a module symbol without an underscore, either UPPER
5906 or LOWER.
5907 FortranCInterface_MODULE__PREFIX
5909 Prefix for a module symbol with an underscore.
5910 FortranCInterface_MODULE__MIDDLE
5912 Middle of a module symbol with an underscore that appears
5913 between the name of the module and the name of the symbol.
5914 FortranCInterface_MODULE__SUFFIX
5916 Suffix for a module symbol with an underscore.
5917 FortranCInterface_MODULE__CASE
5919 The case for a module symbol with an underscore, either UPPER or
5920 LOWER.
5921 Module Functions
5923 FortranCInterface_HEADER
5924 The FortranCInterface_HEADER function is provided to generate a
5925 C header file containing macros to mangle symbol names:
5926 FortranCInterface_HEADER(<file>
5928 [MACRO_NAMESPACE <macro-ns>]
5929 [SYMBOL_NAMESPACE <ns>]
5930 [SYMBOLS [<module>:]<function> ...])
5931 It generates in <file> definitions of the following macros:
5933 #define FortranCInterface_GLOBAL (name,NAME) ...
5935 #define FortranCInterface_GLOBAL_(name,NAME) ...
5936 #define FortranCInterface_MODULE (mod,name, MOD,NAME) ...
5937 #define FortranCInterface_MODULE_(mod,name, MOD,NAME) ...
5938 These macros mangle four categories of Fortran symbols, respec‐
5940 tively:
5941 · Global symbols without ‘_’: call mysub()
5943 · Global symbols with ‘_’ : call my_sub()
5945 · Module symbols without ‘_’: use mymod; call mysub()
5947 · Module symbols with ‘_’ : use mymod; call my_sub()
5949 If mangling for a category is not known, its macro is left unde‐
5951 fined. All macros require raw names in both lower case and
5952 upper case.
5953 The options are:
5955 MACRO_NAMESPACE
5957 Replace the default FortranCInterface_ prefix with a
5958 given namespace <macro-ns>.
5959 SYMBOLS
5961 List symbols to mangle automatically with C preprocessor
5962 definitions:
5963 <function> ==> #define <ns><function> ...
5965 <module>:<function> ==> #define <ns><module>_<function> ...
5966 If the mangling for some symbol is not known then no pre‐
5968 processor definition is created, and a warning is dis‐
5969 played.
5970 SYMBOL_NAMESPACE
5972 Prefix all preprocessor definitions generated by the SYM‐
5973 BOLS option with a given namespace <ns>.
5974 FortranCInterface_VERIFY
5976 The FortranCInterface_VERIFY function is provided to verify that
5977 the Fortran and C/C++ compilers work together:
5978 FortranCInterface_VERIFY([CXX] [QUIET])
5980 It tests whether a simple test executable using Fortran and C
5982 (and C++ when the CXX option is given) compiles and links suc‐
5983 cessfully. The result is stored in the cache entry FortranCIn‐
5984 terface_VERIFIED_C (or FortranCInterface_VERIFIED_CXX if CXX is
5985 given) as a boolean. If the check fails and QUIET is not given
5986 the function terminates with a fatal error message describing
5987 the problem. The purpose of this check is to stop a build early
5988 for incompatible compiler combinations. The test is built in
5989 the Release configuration.
5990 Example Usage
5992 include(FortranCInterface)
5993 FortranCInterface_HEADER(FC.h MACRO_NAMESPACE "FC_")
5994 This creates a “FC.h” header that defines mangling macros FC_GLOBAL(),
5996 FC_GLOBAL_(), FC_MODULE(), and FC_MODULE_().
5997 include(FortranCInterface)
5999 FortranCInterface_HEADER(FCMangle.h
6000 MACRO_NAMESPACE "FC_"
6001 SYMBOL_NAMESPACE "FC_"
6002 SYMBOLS mysub mymod:my_sub)
6003 This creates a “FCMangle.h” header that defines the same FC_*() man‐
6005 gling macros as the previous example plus preprocessor symbols FC_mysub
6006 and FC_mymod_my_sub.
6007 Additional Manglings
6009 FortranCInterface is aware of possible GLOBAL and MODULE manglings for
6010 many Fortran compilers, but it also provides an interface to specify
6011 new possible manglings. Set the variables:
6012 FortranCInterface_GLOBAL_SYMBOLS
6014 FortranCInterface_MODULE_SYMBOLS
6015 before including FortranCInterface to specify manglings of the symbols
6017 MySub, My_Sub, MyModule:MySub, and My_Module:My_Sub. For example, the
6018 code:
6019 set(FortranCInterface_GLOBAL_SYMBOLS mysub_ my_sub__ MYSUB_)
6021 # ^^^^^ ^^^^^^ ^^^^^
6022 set(FortranCInterface_MODULE_SYMBOLS
6023 __mymodule_MOD_mysub __my_module_MOD_my_sub)
6024 # ^^^^^^^^ ^^^^^ ^^^^^^^^^ ^^^^^^
6025 include(FortranCInterface)
6026 tells FortranCInterface to try given GLOBAL and MODULE manglings. (The
6028 carets point at raw symbol names for clarity in this example but are
6029 not needed.)
6030 GenerateExportHeader
6032 Function for generation of export macros for libraries
6033 This module provides the function GENERATE_EXPORT_HEADER().
6035 The GENERATE_EXPORT_HEADER function can be used to generate a file
6037 suitable for preprocessor inclusion which contains EXPORT macros to be
6038 used in library classes:
6039 GENERATE_EXPORT_HEADER( LIBRARY_TARGET
6041 [BASE_NAME <base_name>]
6042 [EXPORT_MACRO_NAME <export_macro_name>]
6043 [EXPORT_FILE_NAME <export_file_name>]
6044 [DEPRECATED_MACRO_NAME <deprecated_macro_name>]
6045 [NO_EXPORT_MACRO_NAME <no_export_macro_name>]
6046 [INCLUDE_GUARD_NAME <include_guard_name>]
6047 [STATIC_DEFINE <static_define>]
6048 [NO_DEPRECATED_MACRO_NAME <no_deprecated_macro_name>]
6049 [DEFINE_NO_DEPRECATED]
6050 [PREFIX_NAME <prefix_name>]
6051 [CUSTOM_CONTENT_FROM_VARIABLE <variable>]
6052 )
6053 The target properties CXX_VISIBILITY_PRESET and VISIBILITY_INLINES_HID‐
6055 DEN can be used to add the appropriate compile flags for targets. See
6056 the documentation of those target properties, and the convenience vari‐
6057 ables CMAKE_CXX_VISIBILITY_PRESET and CMAKE_VISIBILITY_INLINES_HIDDEN.
6058 By default GENERATE_EXPORT_HEADER() generates macro names in a file
6060 name determined by the name of the library. This means that in the
6061 simplest case, users of GenerateExportHeader will be equivalent to:
6062 set(CMAKE_CXX_VISIBILITY_PRESET hidden)
6064 set(CMAKE_VISIBILITY_INLINES_HIDDEN 1)
6065 add_library(somelib someclass.cpp)
6066 generate_export_header(somelib)
6067 install(TARGETS somelib DESTINATION ${LIBRARY_INSTALL_DIR})
6068 install(FILES
6069 someclass.h
6070 ${PROJECT_BINARY_DIR}/somelib_export.h DESTINATION ${INCLUDE_INSTALL_DIR}
6071 )
6072 And in the ABI header files:
6074 #include "somelib_export.h"
6076 class SOMELIB_EXPORT SomeClass {
6077 ...
6078 };
6079 The CMake fragment will generate a file in the ${CMAKE_CUR‐
6081 RENT_BINARY_DIR} called somelib_export.h containing the macros
6082 SOMELIB_EXPORT, SOMELIB_NO_EXPORT, SOMELIB_DEPRECATED, SOMELIB_DEPRE‐
6083 CATED_EXPORT and SOMELIB_DEPRECATED_NO_EXPORT. They will be followed
6084 by content taken from the variable specified by the CUSTOM_CON‐
6085 TENT_FROM_VARIABLE option, if any. The resulting file should be
6086 installed with other headers in the library.
6087 The BASE_NAME argument can be used to override the file name and the
6089 names used for the macros:
6090 add_library(somelib someclass.cpp)
6092 generate_export_header(somelib
6093 BASE_NAME other_name
6094 )
6095 Generates a file called other_name_export.h containing the macros
6097 OTHER_NAME_EXPORT, OTHER_NAME_NO_EXPORT and OTHER_NAME_DEPRECATED etc.
6098 The BASE_NAME may be overridden by specifying other options in the
6100 function. For example:
6101 add_library(somelib someclass.cpp)
6103 generate_export_header(somelib
6104 EXPORT_MACRO_NAME OTHER_NAME_EXPORT
6105 )
6106 creates the macro OTHER_NAME_EXPORT instead of SOMELIB_EXPORT, but
6108 other macros and the generated file name is as default:
6109 add_library(somelib someclass.cpp)
6111 generate_export_header(somelib
6112 DEPRECATED_MACRO_NAME KDE_DEPRECATED
6113 )
6114 creates the macro KDE_DEPRECATED instead of SOMELIB_DEPRECATED.
6116 If LIBRARY_TARGET is a static library, macros are defined without val‐
6118 ues.
6119 If the same sources are used to create both a shared and a static
6121 library, the uppercased symbol ${BASE_NAME}_STATIC_DEFINE should be
6122 used when building the static library:
6123 add_library(shared_variant SHARED ${lib_SRCS})
6125 add_library(static_variant ${lib_SRCS})
6126 generate_export_header(shared_variant BASE_NAME libshared_and_static)
6127 set_target_properties(static_variant PROPERTIES
6128 COMPILE_FLAGS -DLIBSHARED_AND_STATIC_STATIC_DEFINE)
6129 This will cause the export macros to expand to nothing when building
6131 the static library.
6132 If DEFINE_NO_DEPRECATED is specified, then a macro ${BASE_NAME}_NO_DEP‐
6134 RECATED will be defined This macro can be used to remove deprecated
6135 code from preprocessor output:
6136 option(EXCLUDE_DEPRECATED "Exclude deprecated parts of the library" FALSE)
6138 if (EXCLUDE_DEPRECATED)
6139 set(NO_BUILD_DEPRECATED DEFINE_NO_DEPRECATED)
6140 endif()
6141 generate_export_header(somelib ${NO_BUILD_DEPRECATED})
6142 And then in somelib:
6144 class SOMELIB_EXPORT SomeClass
6146 {
6147 public:
6148 #ifndef SOMELIB_NO_DEPRECATED
6149 SOMELIB_DEPRECATED void oldMethod();
6150 #endif
6151 };
6152 #ifndef SOMELIB_NO_DEPRECATED
6154 void SomeClass::oldMethod() { }
6155 #endif
6156 If PREFIX_NAME is specified, the argument will be used as a prefix to
6158 all generated macros.
6159 For example:
6161 generate_export_header(somelib PREFIX_NAME VTK_)
6163 Generates the macros VTK_SOMELIB_EXPORT etc.
6165 ADD_COMPILER_EXPORT_FLAGS( [<output_variable>] )
6167 The ADD_COMPILER_EXPORT_FLAGS function adds -fvisibility=hidden to
6169 CMAKE_CXX_FLAGS if supported, and is a no-op on Windows which does not
6170 need extra compiler flags for exporting support. You may optionally
6171 pass a single argument to ADD_COMPILER_EXPORT_FLAGS that will be popu‐
6172 lated with the CXX_FLAGS required to enable visibility support for the
6173 compiler/architecture in use.
6174 This function is deprecated. Set the target properties CXX_VISIBIL‐
6176 ITY_PRESET and VISIBILITY_INLINES_HIDDEN instead.
6177 GetPrerequisites
6179 Deprecated since version 3.16: Use file(GET_RUNTIME_DEPENDENCIES)
6180 instead.
6181 Functions to analyze and list executable file prerequisites.
6184 This module provides functions to list the .dll, .dylib or .so files
6186 that an executable or shared library file depends on. (Its prerequi‐
6187 sites.)
6188 It uses various tools to obtain the list of required shared library
6190 files:
6191 dumpbin (Windows)
6193 objdump (MinGW on Windows)
6194 ldd (Linux/Unix)
6195 otool (Mac OSX)
6196 The following functions are provided by this module:
6198 get_prerequisites
6200 list_prerequisites
6201 list_prerequisites_by_glob
6202 gp_append_unique
6203 is_file_executable
6204 gp_item_default_embedded_path
6205 (projects can override with gp_item_default_embedded_path_override)
6206 gp_resolve_item
6207 (projects can override with gp_resolve_item_override)
6208 gp_resolved_file_type
6209 (projects can override with gp_resolved_file_type_override)
6210 gp_file_type
6211 Requires CMake 2.6 or greater because it uses function, break, return
6213 and PARENT_SCOPE.
6214 GET_PREREQUISITES(<target> <prerequisites_var> <exclude_system> <recurse>
6216 <exepath> <dirs> [<rpaths>])
6217 Get the list of shared library files required by <target>. The list in
6219 the variable named <prerequisites_var> should be empty on first entry
6220 to this function. On exit, <prerequisites_var> will contain the list
6221 of required shared library files.
6222 <target> is the full path to an executable file. <prerequisites_var>
6224 is the name of a CMake variable to contain the results. <exclude_sys‐
6225 tem> must be 0 or 1 indicating whether to include or exclude “system”
6226 prerequisites. If <recurse> is set to 1 all prerequisites will be
6227 found recursively, if set to 0 only direct prerequisites are listed.
6228 <exepath> is the path to the top level executable used for @exe‐
6229 cutable_path replacment on the Mac. <dirs> is a list of paths where
6230 libraries might be found: these paths are searched first when a target
6231 without any path info is given. Then standard system locations are
6232 also searched: PATH, Framework locations, /usr/lib…
6233 The variable GET_PREREQUISITES_VERBOSE can be set to true to enable
6235 verbose output.
6236 LIST_PREREQUISITES(<target> [<recurse> [<exclude_system> [<verbose>]]])
6238 Print a message listing the prerequisites of <target>.
6240 <target> is the name of a shared library or executable target or the
6242 full path to a shared library or executable file. If <recurse> is set
6243 to 1 all prerequisites will be found recursively, if set to 0 only
6244 direct prerequisites are listed. <exclude_system> must be 0 or 1 indi‐
6245 cating whether to include or exclude “system” prerequisites. With
6246 <verbose> set to 0 only the full path names of the prerequisites are
6247 printed, set to 1 extra informatin will be displayed.
6248 LIST_PREREQUISITES_BY_GLOB(<glob_arg> <glob_exp>)
6250 Print the prerequisites of shared library and executable files matching
6252 a globbing pattern. <glob_arg> is GLOB or GLOB_RECURSE and <glob_exp>
6253 is a globbing expression used with “file(GLOB” or “file(GLOB_RECURSE”
6254 to retrieve a list of matching files. If a matching file is exe‐
6255 cutable, its prerequisites are listed.
6256 Any additional (optional) arguments provided are passed along as the
6258 optional arguments to the list_prerequisites calls.
6259 GP_APPEND_UNIQUE(<list_var> <value>)
6261 Append <value> to the list variable <list_var> only if the value is not
6263 already in the list.
6264 IS_FILE_EXECUTABLE(<file> <result_var>)
6266 Return 1 in <result_var> if <file> is a binary executable, 0 otherwise.
6268 GP_ITEM_DEFAULT_EMBEDDED_PATH(<item> <default_embedded_path_var>)
6270 Return the path that others should refer to the item by when the item
6272 is embedded inside a bundle.
6273 Override on a per-project basis by providing a project-specific
6275 gp_item_default_embedded_path_override function.
6276 GP_RESOLVE_ITEM(<context> <item> <exepath> <dirs> <resolved_item_var>
6278 [<rpaths>])
6279 Resolve an item into an existing full path file.
6281 Override on a per-project basis by providing a project-specific
6283 gp_resolve_item_override function.
6284 GP_RESOLVED_FILE_TYPE(<original_file> <file> <exepath> <dirs> <type_var>
6286 [<rpaths>])
6287 Return the type of <file> with respect to <original_file>. String
6289 describing type of prerequisite is returned in variable named
6290 <type_var>.
6291 Use <exepath> and <dirs> if necessary to resolve non-absolute <file>
6293 values – but only for non-embedded items.
6294 Possible types are:
6296 system
6298 local
6299 embedded
6300 other
6301 Override on a per-project basis by providing a project-specific
6303 gp_resolved_file_type_override function.
6304 GP_FILE_TYPE(<original_file> <file> <type_var>)
6306 Return the type of <file> with respect to <original_file>. String
6308 describing type of prerequisite is returned in variable named
6309 <type_var>.
6310 Possible types are:
6312 system
6314 local
6315 embedded
6316 other
6317 GNUInstallDirs
6319 Define GNU standard installation directories
6320 Provides install directory variables as defined by the GNU Coding Stan‐
6322 dards.
6323 Result Variables
6325 Inclusion of this module defines the following variables:
6326 CMAKE_INSTALL_<dir>
6328 Destination for files of a given type. This value may be passed to
6329 the DESTINATION options of install() commands for the corresponding
6330 file type.
6331 CMAKE_INSTALL_FULL_<dir>
6333 The absolute path generated from the corresponding
6334 CMAKE_INSTALL_<dir> value. If the value is not already an absolute
6335 path, an absolute path is constructed typically by prepending the
6336 value of the CMAKE_INSTALL_PREFIX variable. However, there are some
6337 special cases as documented below.
6338 where <dir> is one of:
6340 BINDIR user executables (bin)
6342 SBINDIR
6344 system admin executables (sbin)
6345 LIBEXECDIR
6347 program executables (libexec)
6348 SYSCONFDIR
6350 read-only single-machine data (etc)
6351 SHAREDSTATEDIR
6353 modifiable architecture-independent data (com)
6354 LOCALSTATEDIR
6356 modifiable single-machine data (var)
6357 RUNSTATEDIR
6359 run-time variable data (LOCALSTATEDIR/run)
6360 LIBDIR object code libraries (lib or lib64 or lib/<multiarch-tuple> on
6362 Debian)
6363 INCLUDEDIR
6365 C header files (include)
6366 OLDINCLUDEDIR
6368 C header files for non-gcc (/usr/include)
6369 DATAROOTDIR
6371 read-only architecture-independent data root (share)
6372 DATADIR
6374 read-only architecture-independent data (DATAROOTDIR)
6375 INFODIR
6377 info documentation (DATAROOTDIR/info)
6378 LOCALEDIR
6380 locale-dependent data (DATAROOTDIR/locale)
6381 MANDIR man documentation (DATAROOTDIR/man)
6383 DOCDIR documentation root (DATAROOTDIR/doc/PROJECT_NAME)
6385 If the includer does not define a value the above-shown default will be
6387 used and the value will appear in the cache for editing by the user.
6388 Special Cases
6390 The following values of CMAKE_INSTALL_PREFIX are special:
6391 /
6393 For <dir> other than the SYSCONFDIR, LOCALSTATEDIR and RUNSTATEDIR,
6394 the value of CMAKE_INSTALL_<dir> is prefixed with usr/ if it is not
6395 user-specified as an absolute path. For example, the INCLUDEDIR
6396 value include becomes usr/include. This is required by the GNU Cod‐
6397 ing Standards, which state:
6398 When building the complete GNU system, the prefix will be empty
6399 and /usr will be a symbolic link to /.
6400 /usr
6402 For <dir> equal to SYSCONFDIR, LOCALSTATEDIR or RUNSTATEDIR, the
6403 CMAKE_INSTALL_FULL_<dir> is computed by prepending just / to the
6404 value of CMAKE_INSTALL_<dir> if it is not user-specified as an abso‐
6405 lute path. For example, the SYSCONFDIR value etc becomes /etc.
6406 This is required by the GNU Coding Standards.
6407 /opt/...
6409 For <dir> equal to SYSCONFDIR, LOCALSTATEDIR or RUNSTATEDIR, the
6410 CMAKE_INSTALL_FULL_<dir> is computed by appending the prefix to the
6411 value of CMAKE_INSTALL_<dir> if it is not user-specified as an abso‐
6412 lute path. For example, the SYSCONFDIR value etc becomes
6413 /etc/opt/.... This is defined by the Filesystem Hierarchy Standard.
6414 Macros
6416 GNUInstallDirs_get_absolute_install_dir
6417 GNUInstallDirs_get_absolute_install_dir(absvar var)
6419 Set the given variable absvar to the absolute path contained
6421 within the variable var. This is to allow the computation of an
6422 absolute path, accounting for all the special cases documented
6423 above. While this macro is used to compute the various
6424 CMAKE_INSTALL_FULL_<dir> variables, it is exposed publicly to
6425 allow users who create additional path variables to also compute
6426 absolute paths where necessary, using the same logic.
6427 GoogleTest
6429 This module defines functions to help use the Google Test infrastruc‐
6430 ture. Two mechanisms for adding tests are provided. gtest_add_tests()
6431 has been around for some time, originally via find_package(GTest).
6432 gtest_discover_tests() was introduced in CMake 3.10.
6433 The (older) gtest_add_tests() scans source files to identify tests.
6435 This is usually effective, with some caveats, including in cross-com‐
6436 piling environments, and makes setting additional properties on tests
6437 more convenient. However, its handling of parameterized tests is less
6438 comprehensive, and it requires re-running CMake to detect changes to
6439 the list of tests.
6440 The (newer) gtest_discover_tests() discovers tests by asking the com‐
6442 piled test executable to enumerate its tests. This is more robust and
6443 provides better handling of parameterized tests, and does not require
6444 CMake to be re-run when tests change. However, it may not work in a
6445 cross-compiling environment, and setting test properties is less conve‐
6446 nient.
6447 More details can be found in the documentation of the respective func‐
6449 tions.
6450 Both commands are intended to replace use of add_test() to register
6452 tests, and will create a separate CTest test for each Google Test test
6453 case. Note that this is in some cases less efficient, as common set-up
6454 and tear-down logic cannot be shared by multiple test cases executing
6455 in the same instance. However, it provides more fine-grained pass/fail
6456 information to CTest, which is usually considered as more beneficial.
6457 By default, the CTest test name is the same as the Google Test name
6458 (i.e. suite.testcase); see also TEST_PREFIX and TEST_SUFFIX.
6459 gtest_add_tests
6461 Automatically add tests with CTest by scanning source code for
6462 Google Test macros:
6463 gtest_add_tests(TARGET target
6465 [SOURCES src1...]
6466 [EXTRA_ARGS arg1...]
6467 [WORKING_DIRECTORY dir]
6468 [TEST_PREFIX prefix]
6469 [TEST_SUFFIX suffix]
6470 [SKIP_DEPENDENCY]
6471 [TEST_LIST outVar]
6472 )
6473 gtest_add_tests attempts to identify tests by scanning source
6475 files. Although this is generally effective, it uses only a
6476 basic regular expression match, which can be defeated by atypi‐
6477 cal test declarations, and is unable to fully “split” parameter‐
6478 ized tests. Additionally, it requires that CMake be re-run to
6479 discover any newly added, removed or renamed tests (by default,
6480 this means that CMake is re-run when any test source file is
6481 changed, but see SKIP_DEPENDENCY). However, it has the advan‐
6482 tage of declaring tests at CMake time, which somewhat simplifies
6483 setting additional properties on tests, and always works in a
6484 cross-compiling environment.
6485 The options are:
6487 TARGET target
6489 Specifies the Google Test executable, which must be a
6490 known CMake executable target. CMake will substitute the
6491 location of the built executable when running the test.
6492 SOURCES src1...
6494 When provided, only the listed files will be scanned for
6495 test cases. If this option is not given, the SOURCES
6496 property of the specified target will be used to obtain
6497 the list of sources.
6498 EXTRA_ARGS arg1...
6500 Any extra arguments to pass on the command line to each
6501 test case.
6502 WORKING_DIRECTORY dir
6504 Specifies the directory in which to run the discovered
6505 test cases. If this option is not provided, the current
6506 binary directory is used.
6507 TEST_PREFIX prefix
6509 Specifies a prefix to be prepended to the name of each
6510 discovered test case. This can be useful when the same
6511 source files are being used in multiple calls to
6512 gtest_add_test() but with different EXTRA_ARGS.
6513 TEST_SUFFIX suffix
6515 Similar to TEST_PREFIX except the suffix is appended to
6516 the name of every discovered test case. Both TEST_PREFIX
6517 and TEST_SUFFIX may be specified.
6518 SKIP_DEPENDENCY
6520 Normally, the function creates a dependency which will
6521 cause CMake to be re-run if any of the sources being
6522 scanned are changed. This is to ensure that the list of
6523 discovered tests is updated. If this behavior is not
6524 desired (as may be the case while actually writing the
6525 test cases), this option can be used to prevent the
6526 dependency from being added.
6527 TEST_LIST outVar
6529 The variable named by outVar will be populated in the
6530 calling scope with the list of discovered test cases.
6531 This allows the caller to do things like manipulate test
6532 properties of the discovered tests.
6533 include(GoogleTest)
6535 add_executable(FooTest FooUnitTest.cxx)
6536 gtest_add_tests(TARGET FooTest
6537 TEST_SUFFIX .noArgs
6538 TEST_LIST noArgsTests
6539 )
6540 gtest_add_tests(TARGET FooTest
6541 EXTRA_ARGS --someArg someValue
6542 TEST_SUFFIX .withArgs
6543 TEST_LIST withArgsTests
6544 )
6545 set_tests_properties(${noArgsTests} PROPERTIES TIMEOUT 10)
6546 set_tests_properties(${withArgsTests} PROPERTIES TIMEOUT 20)
6547 For backward compatibility, the following form is also sup‐
6549 ported:
6550 gtest_add_tests(exe args files...)
6552 exe The path to the test executable or the name of a CMake
6554 target.
6555 args A ;-list of extra arguments to be passed to executable.
6557 The entire list must be passed as a single argument.
6558 Enclose it in quotes, or pass "" for no arguments.
6559 files...
6561 A list of source files to search for tests and test fix‐
6562 tures. Alternatively, use AUTO to specify that exe is
6563 the name of a CMake executable target whose sources
6564 should be scanned.
6565 include(GoogleTest)
6567 set(FooTestArgs --foo 1 --bar 2)
6568 add_executable(FooTest FooUnitTest.cxx)
6569 gtest_add_tests(FooTest "${FooTestArgs}" AUTO)
6570 gtest_discover_tests
6572 Automatically add tests with CTest by querying the compiled test
6573 executable for available tests:
6574 gtest_discover_tests(target
6576 [EXTRA_ARGS arg1...]
6577 [WORKING_DIRECTORY dir]
6578 [TEST_PREFIX prefix]
6579 [TEST_SUFFIX suffix]
6580 [NO_PRETTY_TYPES] [NO_PRETTY_VALUES]
6581 [PROPERTIES name1 value1...]
6582 [TEST_LIST var]
6583 [DISCOVERY_TIMEOUT seconds]
6584 )
6585 gtest_discover_tests sets up a post-build command on the test
6587 executable that generates the list of tests by parsing the out‐
6588 put from running the test with the --gtest_list_tests argument.
6589 Compared to the source parsing approach of gtest_add_tests(),
6590 this ensures that the full list of tests, including instantia‐
6591 tions of parameterized tests, is obtained. Since test discovery
6592 occurs at build time, it is not necessary to re-run CMake when
6593 the list of tests changes. However, it requires that CROSSCOM‐
6594 PILING_EMULATOR is properly set in order to function in a
6595 cross-compiling environment.
6596 Additionally, setting properties on tests is somewhat less con‐
6598 venient, since the tests are not available at CMake time. Addi‐
6599 tional test properties may be assigned to the set of tests as a
6600 whole using the PROPERTIES option. If more fine-grained test
6601 control is needed, custom content may be provided through an
6602 external CTest script using the TEST_INCLUDE_FILES directory
6603 property. The set of discovered tests is made accessible to
6604 such a script via the <target>_TESTS variable.
6605 The options are:
6607 target Specifies the Google Test executable, which must be a
6609 known CMake executable target. CMake will substitute the
6610 location of the built executable when running the test.
6611 EXTRA_ARGS arg1...
6613 Any extra arguments to pass on the command line to each
6614 test case.
6615 WORKING_DIRECTORY dir
6617 Specifies the directory in which to run the discovered
6618 test cases. If this option is not provided, the current
6619 binary directory is used.
6620 TEST_PREFIX prefix
6622 Specifies a prefix to be prepended to the name of each
6623 discovered test case. This can be useful when the same
6624 test executable is being used in multiple calls to
6625 gtest_discover_tests() but with different EXTRA_ARGS.
6626 TEST_SUFFIX suffix
6628 Similar to TEST_PREFIX except the suffix is appended to
6629 the name of every discovered test case. Both TEST_PREFIX
6630 and TEST_SUFFIX may be specified.
6631 NO_PRETTY_TYPES
6633 By default, the type index of type-parameterized tests is
6634 replaced by the actual type name in the CTest test name.
6635 If this behavior is undesirable (e.g. because the type
6636 names are unwieldy), this option will suppress this
6637 behavior.
6638 NO_PRETTY_VALUES
6640 By default, the value index of value-parameterized tests
6641 is replaced by the actual value in the CTest test name.
6642 If this behavior is undesirable (e.g. because the value
6643 strings are unwieldy), this option will suppress this
6644 behavior.
6645 PROPERTIES name1 value1...
6647 Specifies additional properties to be set on all tests
6648 discovered by this invocation of gtest_discover_tests.
6649 TEST_LIST var
6651 Make the list of tests available in the variable var,
6652 rather than the default <target>_TESTS. This can be use‐
6653 ful when the same test executable is being used in multi‐
6654 ple calls to gtest_discover_tests(). Note that this
6655 variable is only available in CTest.
6656 DISCOVERY_TIMEOUT num
6658 Specifies how long (in seconds) CMake will wait for the
6659 test to enumerate available tests. If the test takes
6660 longer than this, discovery (and your build) will fail.
6661 Most test executables will enumerate their tests very
6662 quickly, but under some exceptional circumstances, a test
6663 may require a longer timeout. The default is 5. See
6664 also the TIMEOUT option of execute_process().
6665 NOTE:
6667 In CMake versions 3.10.1 and 3.10.2, this option was
6668 called TIMEOUT. This clashed with the TIMEOUT test
6669 property, which is one of the common properties that
6670 would be set with the PROPERTIES keyword, usually
6671 leading to legal but unintended behavior. The keyword
6672 was changed to DISCOVERY_TIMEOUT in CMake 3.10.3 to
6673 address this problem. The ambiguous behavior of the
6674 TIMEOUT keyword in 3.10.1 and 3.10.2 has not been pre‐
6675 served.
6676 InstallRequiredSystemLibraries
6678 Include this module to search for compiler-provided system runtime
6679 libraries and add install rules for them. Some optional variables may
6680 be set prior to including the module to adjust behavior:
6681 CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS
6683 Specify additional runtime libraries that may not be detected.
6684 After inclusion any detected libraries will be appended to this.
6685 CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS_SKIP
6687 Set to TRUE to skip calling the install(PROGRAMS) command to
6688 allow the includer to specify its own install rule, using the
6689 value of CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS to get the list of
6690 libraries.
6691 CMAKE_INSTALL_DEBUG_LIBRARIES
6693 Set to TRUE to install the debug runtime libraries when avail‐
6694 able with MSVC tools.
6695 CMAKE_INSTALL_DEBUG_LIBRARIES_ONLY
6697 Set to TRUE to install only the debug runtime libraries with
6698 MSVC tools even if the release runtime libraries are also avail‐
6699 able.
6700 CMAKE_INSTALL_UCRT_LIBRARIES
6702 Set to TRUE to install the Windows Universal CRT libraries for
6703 app-local deployment (e.g. to Windows XP). This is meaningful
6704 only with MSVC from Visual Studio 2015 or higher.
6705 One may set a CMAKE_WINDOWS_KITS_10_DIR environment variable to
6707 an absolute path to tell CMake to look for Windows 10 SDKs in a
6708 custom location. The specified directory is expected to contain
6709 Redist/ucrt/DLLs/* directories.
6710 CMAKE_INSTALL_MFC_LIBRARIES
6712 Set to TRUE to install the MSVC MFC runtime libraries.
6713 CMAKE_INSTALL_OPENMP_LIBRARIES
6715 Set to TRUE to install the MSVC OpenMP runtime libraries
6716 CMAKE_INSTALL_SYSTEM_RUNTIME_DESTINATION
6718 Specify the install(PROGRAMS) command DESTINATION option. If
6719 not specified, the default is bin on Windows and lib elsewhere.
6720 CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS_NO_WARNINGS
6722 Set to TRUE to disable warnings about required library files
6723 that do not exist. (For example, Visual Studio Express editions
6724 may not provide the redistributable files.)
6725 CMAKE_INSTALL_SYSTEM_RUNTIME_COMPONENT
6727 Specify the install(PROGRAMS) command COMPONENT option. If not
6728 specified, no such option will be used.
6729 ProcessorCount
6731 ProcessorCount(var)
6732 Determine the number of processors/cores and save value in ${var}
6734 Sets the variable named ${var} to the number of physical cores avail‐
6736 able on the machine if the information can be determined. Otherwise it
6737 is set to 0. Currently this functionality is implemented for AIX, cyg‐
6738 win, FreeBSD, HPUX, Linux, macOS, QNX, Sun and Windows.
6739 This function is guaranteed to return a positive integer (>=1) if it
6741 succeeds. It returns 0 if there’s a problem determining the processor
6742 count.
6743 Example use, in a ctest -S dashboard script:
6745 include(ProcessorCount)
6747 ProcessorCount(N)
6748 if(NOT N EQUAL 0)
6749 set(CTEST_BUILD_FLAGS -j${N})
6750 set(ctest_test_args ${ctest_test_args} PARALLEL_LEVEL ${N})
6751 endif()
6752 This function is intended to offer an approximation of the value of the
6754 number of compute cores available on the current machine, such that you
6755 may use that value for parallel building and parallel testing. It is
6756 meant to help utilize as much of the machine as seems reasonable. Of
6757 course, knowledge of what else might be running on the machine simulta‐
6758 neously should be used when deciding whether to request a machine’s
6759 full capacity all for yourself.
6760 SelectLibraryConfigurations
6762 select_library_configurations(basename)
6763 This macro takes a library base name as an argument, and will choose
6765 good values for the variables
6766 basename_LIBRARY
6768 basename_LIBRARIES
6769 basename_LIBRARY_DEBUG
6770 basename_LIBRARY_RELEASE
6771 depending on what has been found and set.
6773 If only basename_LIBRARY_RELEASE is defined, basename_LIBRARY will be
6775 set to the release value, and basename_LIBRARY_DEBUG will be set to
6776 basename_LIBRARY_DEBUG-NOTFOUND. If only basename_LIBRARY_DEBUG is
6777 defined, then basename_LIBRARY will take the debug value, and base‐
6778 name_LIBRARY_RELEASE will be set to basename_LIBRARY_RELEASE-NOTFOUND.
6779 If the generator supports configuration types, then basename_LIBRARY
6781 and basename_LIBRARIES will be set with debug and optimized flags spec‐
6782 ifying the library to be used for the given configuration. If no build
6783 type has been set or the generator in use does not support configura‐
6784 tion types, then basename_LIBRARY and basename_LIBRARIES will take only
6785 the release value, or the debug value if the release one is not set.
6786 SquishTestScript
6788 This script launches a GUI test using Squish. You should not call the
6789 script directly; instead, you should access it via the SQUISH_ADD_TEST
6790 macro that is defined in FindSquish.cmake.
6791 This script starts the Squish server, launches the test on the client,
6793 and finally stops the squish server. If any of these steps fail
6794 (including if the tests do not pass) then a fatal error is raised.
6795 TestBigEndian
6797 Define macro to determine endian type
6798 Check if the system is big endian or little endian
6800 TEST_BIG_ENDIAN(VARIABLE)
6802 VARIABLE - variable to store the result to
6803 TestForANSIForScope
6805 Check for ANSI for scope support
6806 Check if the compiler restricts the scope of variables declared in a
6808 for-init-statement to the loop body.
6809 CMAKE_NO_ANSI_FOR_SCOPE - holds result
6811 TestForANSIStreamHeaders
6813 Test for compiler support of ANSI stream headers iostream, etc.
6814 check if the compiler supports the standard ANSI iostream header (with‐
6816 out the .h)
6817 CMAKE_NO_ANSI_STREAM_HEADERS - defined by the results
6819 TestForSSTREAM
6821 Test for compiler support of ANSI sstream header
6822 check if the compiler supports the standard ANSI sstream header
6824 CMAKE_NO_ANSI_STRING_STREAM - defined by the results
6826 TestForSTDNamespace
6828 Test for std:: namespace support
6829 check if the compiler supports std:: on stl classes
6831 CMAKE_NO_STD_NAMESPACE - defined by the results
6833 UseEcos
6835 This module defines variables and macros required to build eCos appli‐
6836 cation.
6837 This file contains the following macros: ECOS_ADD_INCLUDE_DIRECTORIES()
6839 - add the eCos include dirs ECOS_ADD_EXECUTABLE(name source1 … sourceN
6840 ) - create an eCos executable ECOS_ADJUST_DIRECTORY(VAR source1 …
6841 sourceN ) - adjusts the path of the source files and puts the result
6842 into VAR
6843 Macros for selecting the toolchain: ECOS_USE_ARM_ELF_TOOLS() - enable
6845 the ARM ELF toolchain for the directory where it is called
6846 ECOS_USE_I386_ELF_TOOLS() - enable the i386 ELF toolchain for the
6847 directory where it is called ECOS_USE_PPC_EABI_TOOLS() - enable the
6848 PowerPC toolchain for the directory where it is called
6849 It contains the following variables: ECOS_DEFINITIONS ECOSCONFIG_EXE‐
6851 CUTABLE ECOS_CONFIG_FILE - defaults to ecos.ecc, if your eCos configu‐
6852 ration file has a different name, adjust this variable for internal use
6853 only:
6854 ECOS_ADD_TARGET_LIB
6856 UseJavaClassFilelist
6858 This script create a list of compiled Java class files to be added to a
6859 jar file. This avoids including cmake files which get created in the
6860 binary directory.
6861 UseJava
6863 Use Module for Java
6864 This file provides functions for Java. It is assumed that FindJava has
6866 already been loaded. See FindJava for information on how to load Java
6867 into your CMake project.
6868 Creating And Installing JARs
6870 add_jar(<target_name>
6871 [SOURCES] <source1> [<source2>...] [<resource1>...]
6872 [INCLUDE_JARS <jar1> [<jar2>...]]
6873 [ENTRY_POINT <entry>]
6874 [VERSION <version>]
6875 [OUTPUT_NAME <name>]
6876 [OUTPUT_DIR <dir>]
6877 [GENERATE_NATIVE_HEADERS <target> [DESTINATION <dir>]]
6878 )
6879 This command creates a <target_name>.jar. It compiles the given
6881 <source> files and adds the given <resource> files to the jar file.
6882 Source files can be java files or listing files (prefixed by @). If
6883 only resource files are given then just a jar file is created. The
6884 list of INCLUDE_JARS are added to the classpath when compiling the java
6885 sources and also to the dependencies of the target. INCLUDE_JARS also
6886 accepts other target names created by add_jar(). For backwards compat‐
6887 ibility, jar files listed as sources are ignored (as they have been
6888 since the first version of this module).
6889 The default OUTPUT_DIR can also be changed by setting the variable
6891 CMAKE_JAVA_TARGET_OUTPUT_DIR.
6892 Optionally, using option GENERATE_NATIVE_HEADERS, native header files
6894 can be generated for methods declared as native. These files provide
6895 the connective glue that allow your Java and C code to interact. An
6896 INTERFACE target will be created for an easy usage of generated files.
6897 Sub-option DESTINATION can be used to specify the output directory for
6898 generated header files.
6899 GENERATE_NATIVE_HEADERS option requires, at least, version 1.8 of the
6901 JDK.
6902 The add_jar() function sets the following target properties on <tar‐
6904 get_name>:
6905 INSTALL_FILES
6907 The files which should be installed. This is used by
6908 install_jar().
6909 JNI_SYMLINK
6911 The JNI symlink which should be installed. This is used by
6912 install_jni_symlink().
6913 JAR_FILE
6915 The location of the jar file so that you can include it.
6916 CLASSDIR
6918 The directory where the class files can be found. For example
6919 to use them with javah.
6920 install_jar(<target_name> <destination>)
6922 install_jar(<target_name> DESTINATION <destination> [COMPONENT <component>])
6923 This command installs the <target_name> files to the given <destina‐
6925 tion>. It should be called in the same scope as add_jar() or it will
6926 fail.
6927 The install_jar() function sets the INSTALL_DESTINATION target property
6929 on jars so installed. This property holds the <destination> as
6930 described above, and is used by install_jar_exports(). You can get
6931 this information with get_property() and the INSTALL_DESTINATION prop‐
6932 erty key.
6933 install_jni_symlink(<target_name> <destination>)
6935 install_jni_symlink(<target_name> DESTINATION <destination> [COMPONENT <component>])
6936 This command installs the <target_name> JNI symlinks to the given <des‐
6938 tination>. It should be called in the same scope as add_jar() or it
6939 will fail.
6940 install_jar_exports(TARGETS <jars>...
6942 [NAMESPACE <namespace>]
6943 FILE <filename>
6944 DESTINATION <destination> [COMPONENT <component>])
6945 This command installs a target export file <filename> for the named jar
6947 targets to the given <destination> directory. Its function is similar
6948 to that of install(EXPORTS).
6949 export_jars(TARGETS <jars>...
6951 [NAMESPACE <namespace>]
6952 FILE <filename>)
6953 This command writes a target export file <filename> for the named
6955 <jars> targets. Its function is similar to that of export().
6956 Examples
6958 To add compile flags to the target you can set these flags with the
6959 following variable:
6960 set(CMAKE_JAVA_COMPILE_FLAGS -nowarn)
6962 To add a path or a jar file to the class path you can do this with the
6964 CMAKE_JAVA_INCLUDE_PATH variable.
6965 set(CMAKE_JAVA_INCLUDE_PATH /usr/share/java/shibboleet.jar)
6967 To use a different output name for the target you can set it with:
6969 add_jar(foobar foobar.java OUTPUT_NAME shibboleet.jar)
6971 To use a different output directory than CMAKE_CURRENT_BINARY_DIR you
6973 can set it with:
6974 add_jar(foobar foobar.java OUTPUT_DIR ${PROJECT_BINARY_DIR}/bin)
6976 To define an entry point in your jar you can set it with the
6978 ENTRY_POINT named argument:
6979 add_jar(example ENTRY_POINT com/examples/MyProject/Main)
6981 To define a custom manifest for the jar, you can set it with the MANI‐
6983 FEST named argument:
6984 add_jar(example MANIFEST /path/to/manifest)
6986 To add a version to the target output name you can set it using the
6988 VERSION named argument to add_jar(). The following example will create
6989 a jar file with the name shibboleet-1.0.0.jar and will create a symlink
6990 shibboleet.jar pointing to the jar with the version information.
6991 add_jar(shibboleet shibbotleet.java VERSION 1.2.0)
6993 If the target is a JNI library, utilize the following commands to cre‐
6995 ate a JNI symbolic link:
6996 set(CMAKE_JNI_TARGET TRUE)
6998 add_jar(shibboleet shibbotleet.java VERSION 1.2.0)
6999 install_jar(shibboleet ${LIB_INSTALL_DIR}/shibboleet)
7000 install_jni_symlink(shibboleet ${JAVA_LIB_INSTALL_DIR})
7001 If a single target needs to produce more than one jar from its java
7003 source code, to prevent the accumulation of duplicate class files in
7004 subsequent jars, set/reset CMAKE_JAR_CLASSES_PREFIX prior to calling
7005 the add_jar() function:
7006 set(CMAKE_JAR_CLASSES_PREFIX com/redhat/foo)
7008 add_jar(foo foo.java)
7009 set(CMAKE_JAR_CLASSES_PREFIX com/redhat/bar)
7011 add_jar(bar bar.java)
7012 For an optimum usage of option GENERATE_NATIVE_HEADERS, it is recom‐
7014 mended to include module JNI before any call to add_jar(). The produced
7015 target for native headers can then be used to compile C/C++ sources
7016 with the target_link_libraries() command.
7017 find_package(JNI)
7019 add_jar(foo foo.java GENERATE_NATIVE_HEADERS foo-native)
7020 add_library(bar bar.cpp)
7021 target_link_libraries(bar PRIVATE foo-native)
7022 Finding JARs
7024 find_jar(<VAR>
7025 <name> | NAMES <name1> [<name2>...]
7026 [PATHS <path1> [<path2>... ENV <var>]]
7027 [VERSIONS <version1> [<version2>]]
7028 [DOC "cache documentation string"]
7029 )
7030 This command is used to find a full path to the named jar. A cache
7032 entry named by <VAR> is created to store the result of this command.
7033 If the full path to a jar is found the result is stored in the variable
7034 and the search will not repeated unless the variable is cleared. If
7035 nothing is found, the result will be <VAR>-NOTFOUND, and the search
7036 will be attempted again next time find_jar() is invoked with the same
7037 variable. The name of the full path to a file that is searched for is
7038 specified by the names listed after NAMES argument. Additional search
7039 locations can be specified after the PATHS argument. If you require
7040 special a version of a jar file you can specify it with the VERSIONS
7041 argument. The argument after DOC will be used for the documentation
7042 string in the cache.
7043 Javadoc
7045 The create_javadoc() command can be used to create java documentation
7046 based on files or packages. For more details please read the javadoc
7047 manpage.
7048 There are two main signatures for create_javadoc(). The first signa‐
7050 ture works with package names on a path with source files.
7051 create_javadoc(<VAR>
7053 PACKAGES <pkg1> [<pkg2>...]
7054 [SOURCEPATH <sourcepath>]
7055 [CLASSPATH <classpath>]
7056 [INSTALLPATH <install path>]
7057 [DOCTITLE "the documentation title"]
7058 [WINDOWTITLE "the title of the document"]
7059 [AUTHOR TRUE|FALSE]
7060 [USE TRUE|FALSE]
7061 [VERSION TRUE|FALSE]
7062 )
7063 For example:
7065 create_javadoc(my_example_doc
7067 PACKAGES com.example.foo com.example.bar
7068 SOURCEPATH "${CMAKE_CURRENT_SOURCE_DIR}"
7069 CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH}
7070 WINDOWTITLE "My example"
7071 DOCTITLE "<h1>My example</h1>"
7072 AUTHOR TRUE
7073 USE TRUE
7074 VERSION TRUE
7075 )
7076 The second signature for create_javadoc() works on a given list of
7078 files.
7079 create_javadoc(<VAR>
7081 FILES <file1> [<file2>...]
7082 [CLASSPATH <classpath>]
7083 [INSTALLPATH <install path>]
7084 [DOCTITLE "the documentation title"]
7085 [WINDOWTITLE "the title of the document"]
7086 [AUTHOR TRUE|FALSE]
7087 [USE TRUE|FALSE]
7088 [VERSION TRUE|FALSE]
7089 )
7090 For example:
7092 create_javadoc(my_example_doc
7094 FILES ${example_SRCS}
7095 CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH}
7096 WINDOWTITLE "My example"
7097 DOCTITLE "<h1>My example</h1>"
7098 AUTHOR TRUE
7099 USE TRUE
7100 VERSION TRUE
7101 )
7102 Both signatures share most of the options. These options are the same
7104 as what you can find in the javadoc manpage. Please look at the man‐
7105 page for CLASSPATH, DOCTITLE, WINDOWTITLE, AUTHOR, USE and VERSION.
7106 If you don’t set the INSTALLPATH, then by default the documentation
7108 will be installed to :
7109 ${CMAKE_INSTALL_PREFIX}/share/javadoc/<VAR>
7111 Header Generation
7113 create_javah(TARGET <target> | GENERATED_FILES <VAR>
7114 CLASSES <class>...
7115 [CLASSPATH <classpath>...]
7116 [DEPENDS <depend>...]
7117 [OUTPUT_NAME <path>|OUTPUT_DIR <path>]
7118 )
7119 Create C header files from java classes. These files provide the con‐
7121 nective glue that allow your Java and C code to interact.
7122 Deprecated since version 3.11.
7124 NOTE:
7127 This command will no longer be supported starting with version 10 of
7128 the JDK due to the suppression of javah tool. The add_jar(GENER‐
7129 ATE_NATIVE_HEADERS) command should be used instead.
7130 There are two main signatures for create_javah(). The first signature
7132 returns generated files through variable specified by the GENER‐
7133 ATED_FILES option. For example:
7134 create_javah(GENERATED_FILES files_headers
7136 CLASSES org.cmake.HelloWorld
7137 CLASSPATH hello.jar
7138 )
7139 The second signature for create_javah() creates a target which encapsu‐
7141 lates header files generation. E.g.
7142 create_javah(TARGET target_headers
7144 CLASSES org.cmake.HelloWorld
7145 CLASSPATH hello.jar
7146 )
7147 Both signatures share same options.
7149 CLASSES <class>...
7151 Specifies Java classes used to generate headers.
7152 CLASSPATH <classpath>...
7154 Specifies various paths to look up classes. Here .class files,
7155 jar files or targets created by command add_jar can be used.
7156 DEPENDS <depend>...
7158 Targets on which the javah target depends.
7159 OUTPUT_NAME <path>
7161 Concatenates the resulting header files for all the classes
7162 listed by option CLASSES into <path>. Same behavior as option
7163 -o of javah tool.
7164 OUTPUT_DIR <path>
7166 Sets the directory where the header files will be generated.
7167 Same behavior as option -d of javah tool. If not specified,
7168 CMAKE_CURRENT_BINARY_DIR is used as the output directory.
7169 UseJavaSymlinks
7171 Helper script for UseJava.cmake
7172 UseSWIG
7174 This file provides support for SWIG. It is assumed that FindSWIG module
7175 has already been loaded.
7176 Defines the following command for use with SWIG:
7178 swig_add_library
7180 Define swig module with given name and specified language:
7181 swig_add_library(<name>
7183 [TYPE <SHARED|MODULE|STATIC|USE_BUILD_SHARED_LIBS>]
7184 LANGUAGE <language>
7185 [NO_PROXY]
7186 [OUTPUT_DIR <directory>]
7187 [OUTFILE_DIR <directory>]
7188 SOURCES <file>...
7189 )
7190 Targets created with the swig_add_library command have the same
7192 capabilities as targets created with the add_library() command,
7193 so those targets can be used with any command expecting a target
7194 (e.g. target_link_libraries()).
7195 NOTE:
7197 This command creates a target with the specified <name> when
7198 policy CMP0078 is set to NEW. Otherwise, the legacy behavior
7199 will choose a different target name and store it in the
7200 SWIG_MODULE_<name>_REAL_NAME variable.
7201 NOTE:
7203 For multi-config generators, this module does not support
7204 configuration-specific files generated by SWIG. All build
7205 configurations must result in the same generated source file.
7206 TYPE SHARED, MODULE and STATIC have the same semantic as for
7208 the add_library() command. If USE_BUILD_SHARED_LIBS is
7209 specified, the library type will be STATIC or SHARED
7210 based on whether the current value of the
7211 BUILD_SHARED_LIBS variable is ON. If no type is speci‐
7212 fied, MODULE will be used.
7213 LANGUAGE
7215 Specify the target language.
7216 NO_PROXY
7218 Prevent the generation of the wrapper layer (swig
7219 -noproxy option).
7220 OUTPUT_DIR
7222 Specify where to write the language specific files (swig
7223 -outdir option). If not given, the CMAKE_SWIG_OUTDIR
7224 variable will be used. If neither is specified, the
7225 default depends on the value of the UseSWIG_MODULE_VER‐
7226 SION variable as follows:
7227 · If UseSWIG_MODULE_VERSION is 1 or is undefined, output
7229 is written to the CMAKE_CURRENT_BINARY_DIR directory.
7230 · If UseSWIG_MODULE_VERSION is 2, a dedicated directory
7232 will be used. The path of this directory can be
7233 retrieved from the SWIG_SUPPORT_FILES_DIRECTORY target
7234 property.
7235 OUTFILE_DIR
7237 Specify an output directory name where the generated
7238 source file will be placed (swig -o option). If not spec‐
7239 ified, the SWIG_OUTFILE_DIR variable will be used. If
7240 neither is specified, OUTPUT_DIR or CMAKE_SWIG_OUTDIR is
7241 used instead.
7242 SOURCES
7244 List of sources for the library. Files with extension .i
7245 will be identified as sources for the SWIG tool. Other
7246 files will be handled in the standard way. This behavior
7247 can be overriden by specifying the variable
7248 SWIG_SOURCE_FILE_EXTENSIONS.
7249 NOTE:
7251 If UseSWIG_MODULE_VERSION is set to 2, it is strongly recom‐
7252 mended to use a dedicated directory unique to the target when
7253 either the OUTPUT_DIR option or the CMAKE_SWIG_OUTDIR vari‐
7254 able are specified. The output directory contents are erased
7255 as part of the target build, so to prevent interference
7256 between targets or losing other important files, each target
7257 should have its own dedicated output directory.
7258 swig_link_libraries
7260 Link libraries to swig module:
7261 swig_link_libraries(<name> <item>...)
7263 This command has same capabilities as target_link_libraries()
7265 command.
7266 NOTE:
7268 If variable UseSWIG_TARGET_NAME_PREFERENCE is set to STAN‐
7269 DARD, this command is deprecated and target_link_libraries()
7270 command must be used instead.
7271 Source file properties on module files must be set before the invoca‐
7273 tion of the swig_add_library command to specify special behavior of
7274 SWIG and ensure generated files will receive the required settings.
7275 CPLUSPLUS
7277 Call SWIG in c++ mode. For example:
7278 set_property(SOURCE mymod.i PROPERTY CPLUSPLUS ON)
7280 swig_add_library(mymod LANGUAGE python SOURCES mymod.i)
7281 INCLUDE_DIRECTORIES, COMPILE_DEFINITIONS and COMPILE_OPTIONS
7283 Add custom flags to SWIG compiler and have same semantic as
7284 properties INCLUDE_DIRECTORIES, COMPILE_DEFINITIONS and COM‐
7285 PILE_OPTIONS.
7286 USE_TARGET_INCLUDE_DIRECTORIES
7288 If set to TRUE, contents of target property INCLUDE_DIRECTORIES
7289 will be forwarded to SWIG compiler. If set to FALSE target
7290 property INCLUDE_DIRECTORIES will be ignored. If not set, target
7291 property SWIG_USE_TARGET_INCLUDE_DIRECTORIES will be considered.
7292 GENERATED_INCLUDE_DIRECTORIES, GENERATED_COMPILE_DEFINITIONS and GENER‐
7294 ATED_COMPILE_OPTIONS
7295 Add custom flags to the C/C++ generated source. They will fill,
7296 respectively, properties INCLUDE_DIRECTORIES, COMPILE_DEFINI‐
7297 TIONS and COMPILE_OPTIONS of generated C/C++ file.
7298 DEPENDS
7300 Specify additional dependencies to the source file.
7301 SWIG_MODULE_NAME
7303 Specify the actual import name of the module in the target lan‐
7304 guage. This is required if it cannot be scanned automatically
7305 from source or different from the module file basename. For
7306 example:
7307 set_property(SOURCE mymod.i PROPERTY SWIG_MODULE_NAME mymod_realname)
7309 NOTE:
7311 If policy CMP0086 is set to NEW, -module <module_name> is
7312 passed to SWIG compiler.
7313 Target library properties can be set to apply same configuration to all
7315 SWIG input files.
7316 SWIG_INCLUDE_DIRECTORIES, SWIG_COMPILE_DEFINITIONS and SWIG_COM‐
7318 PILE_OPTIONS
7319 These properties will be applied to all SWIG input files and
7320 have same semantic as target properties INCLUDE_DIRECTORIES,
7321 COMPILE_DEFINITIONS and COMPILE_OPTIONS.
7322 set (UseSWIG_TARGET_NAME_PREFERENCE STANDARD)
7324 swig_add_library(mymod LANGUAGE python SOURCES mymod.i)
7325 set_property(TARGET mymod PROPERTY SWIG_COMPILE_DEFINITIONS MY_DEF1 MY_DEF2)
7326 set_property(TARGET mymod PROPERTY SWIG_COMPILE_OPTIONS -bla -blb)
7327 SWIG_USE_TARGET_INCLUDE_DIRECTORIES
7329 If set to TRUE, contents of target property INCLUDE_DIRECTORIES
7330 will be forwarded to SWIG compiler. If set to FALSE or not
7331 defined, target property INCLUDE_DIRECTORIES will be ignored.
7332 This behavior can be overridden by specifying source property
7333 USE_TARGET_INCLUDE_DIRECTORIES.
7334 SWIG_GENERATED_INCLUDE_DIRECTORIES, SWIG_GENERATED_COMPILE_DEFINITIONS
7336 and SWIG_GENERATED_COMPILE_OPTIONS
7337 These properties will populate, respectively, properties
7338 INCLUDE_DIRECTORIES, COMPILE_DEFINITIONS and COMPILE_FLAGS of
7339 all generated C/C++ files.
7340 SWIG_DEPENDS
7342 Add dependencies to all SWIG input files.
7343 The following target properties are output properties and can be used
7345 to get information about support files generated by SWIG interface com‐
7346 pilation.
7347 SWIG_SUPPORT_FILES
7349 This output property list of wrapper files generated during SWIG
7350 compilation.
7351 set (UseSWIG_TARGET_NAME_PREFERENCE STANDARD)
7353 swig_add_library(mymod LANGUAGE python SOURCES mymod.i)
7354 get_property(support_files TARGET mymod PROPERTY SWIG_SUPPORT_FILES)
7355 NOTE:
7357 Only most principal support files are listed. In case some
7358 advanced features of SWIG are used (for example %template),
7359 associated support files may not be listed. Prefer to use the
7360 SWIG_SUPPORT_FILES_DIRECTORY property to handle support
7361 files.
7362 SWIG_SUPPORT_FILES_DIRECTORY
7364 This output property specifies the directory where support files
7365 will be generated.
7366 Some variables can be set to customize the behavior of swig_add_library
7368 as well as SWIG:
7369 UseSWIG_MODULE_VERSION
7371 Specify different behaviors for UseSWIG module.
7372 · Set to 1 or undefined: Legacy behavior is applied.
7374 · Set to 2: A new strategy is applied regarding support files:
7376 the output directory of support files is erased before SWIG
7377 interface compilation.
7378 CMAKE_SWIG_FLAGS
7380 Add flags to all swig calls.
7381 CMAKE_SWIG_OUTDIR
7383 Specify where to write the language specific files (swig -outdir
7384 option).
7385 SWIG_OUTFILE_DIR
7387 Specify an output directory name where the generated source file
7388 will be placed. If not specified, CMAKE_SWIG_OUTDIR is used.
7389 SWIG_MODULE_<name>_EXTRA_DEPS
7391 Specify extra dependencies for the generated module for <name>.
7392 SWIG_SOURCE_FILE_EXTENSIONS
7394 Specify a list of source file extensions to override the default
7395 behavior of considering only .i files as sources for the SWIG
7396 tool. For example:
7397 set(SWIG_SOURCE_FILE_EXTENSIONS ".i" ".swg")
7399 UsewxWidgets
7401 Convenience include for using wxWidgets library.
7402 Determines if wxWidgets was FOUND and sets the appropriate libs,
7404 incdirs, flags, etc. INCLUDE_DIRECTORIES and LINK_DIRECTORIES are
7405 called.
7406 USAGE
7408 # Note that for MinGW users the order of libs is important!
7410 find_package(wxWidgets REQUIRED net gl core base)
7411 include(${wxWidgets_USE_FILE})
7412 # and for each of your dependent executable/library targets:
7413 target_link_libraries(<YourTarget> ${wxWidgets_LIBRARIES})
7414 DEPRECATED
7416 LINK_LIBRARIES is not called in favor of adding dependencies per target.
7418 AUTHOR
7420 Jan Woetzel <jw -at- mip.informatik.uni-kiel.de>
7422 WriteCompilerDetectionHeader
7424 This module provides the function write_compiler_detection_header().
7425 This function can be used to generate a file suitable for preprocessor
7427 inclusion which contains macros to be used in source code:
7428 write_compiler_detection_header(
7430 FILE <file>
7431 PREFIX <prefix>
7432 [OUTPUT_FILES_VAR <output_files_var> OUTPUT_DIR <output_dir>]
7433 COMPILERS <compiler> [...]
7434 FEATURES <feature> [...]
7435 [BARE_FEATURES <feature> [...]]
7436 [VERSION <version>]
7437 [PROLOG <prolog>]
7438 [EPILOG <epilog>]
7439 [ALLOW_UNKNOWN_COMPILERS]
7440 [ALLOW_UNKNOWN_COMPILER_VERSIONS]
7441 )
7442 This generates the file <file> with macros which all have the prefix
7444 <prefix>.
7445 By default, all content is written directly to the <file>. The OUT‐
7447 PUT_FILES_VAR may be specified to cause the compiler-specific content
7448 to be written to separate files. The separate files are then available
7449 in the <output_files_var> and may be consumed by the caller for instal‐
7450 lation for example. The OUTPUT_DIR specifies a relative path from the
7451 main <file> to the compiler-specific files. For example:
7452 write_compiler_detection_header(
7454 FILE climbingstats_compiler_detection.h
7455 PREFIX ClimbingStats
7456 OUTPUT_FILES_VAR support_files
7457 OUTPUT_DIR compilers
7458 COMPILERS GNU Clang MSVC Intel
7459 FEATURES cxx_variadic_templates
7460 )
7461 install(FILES
7462 ${CMAKE_CURRENT_BINARY_DIR}/climbingstats_compiler_detection.h
7463 DESTINATION include
7464 )
7465 install(FILES
7466 ${support_files}
7467 DESTINATION include/compilers
7468 )
7469 VERSION may be used to specify the API version to be generated. Future
7471 versions of CMake may introduce alternative APIs. A given API is
7472 selected by any <version> value greater than or equal to the version of
7473 CMake that introduced the given API and less than the version of CMake
7474 that introduced its succeeding API. The value of the CMAKE_MINI‐
7475 MUM_REQUIRED_VERSION variable is used if no explicit version is speci‐
7476 fied. (As of CMake version 3.16.1 there is only one API version.)
7477 PROLOG may be specified as text content to write at the start of the
7479 header. EPILOG may be specified as text content to write at the end of
7480 the header
7481 At least one <compiler> and one <feature> must be listed. Compilers
7483 which are known to CMake, but not specified are detected and a pre‐
7484 processor #error is generated for them. A preprocessor macro matching
7485 <PREFIX>_COMPILER_IS_<compiler> is generated for each compiler known to
7486 CMake to contain the value 0 or 1.
7487 Possible compiler identifiers are documented with the CMAKE_<LANG>_COM‐
7489 PILER_ID variable. Available features in this version of CMake are
7490 listed in the CMAKE_C_KNOWN_FEATURES and CMAKE_CXX_KNOWN_FEATURES
7491 global properties. The {c,cxx}_std_* meta-features are ignored if
7492 requested.
7493 See the cmake-compile-features(7) manual for information on compile
7495 features.
7496 BARE_FEATURES will define the compatibility macros with the name used
7498 in newer versions of the language standard, so the code can use the new
7499 feature name unconditionally.
7500 ALLOW_UNKNOWN_COMPILERS and ALLOW_UNKNOWN_COMPILER_VERSIONS cause the
7502 module to generate conditions that treat unknown compilers as simply
7503 lacking all features. Without these options the default behavior is to
7504 generate a #error for unknown compilers and versions.
7505 Feature Test Macros
7507 For each compiler, a preprocessor macro is generated matching <PRE‐
7508 FIX>_COMPILER_IS_<compiler> which has the content either 0 or 1,
7509 depending on the compiler in use. Preprocessor macros for compiler ver‐
7510 sion components are generated matching <PREFIX>_COMPILER_VERSION_MAJOR
7511 <PREFIX>_COMPILER_VERSION_MINOR and <PREFIX>_COMPILER_VERSION_PATCH
7512 containing decimal values for the corresponding compiler version compo‐
7513 nents, if defined.
7514 A preprocessor test is generated based on the compiler version denoting
7516 whether each feature is enabled. A preprocessor macro matching <PRE‐
7517 FIX>_COMPILER_<FEATURE>, where <FEATURE> is the upper-case <feature>
7518 name, is generated to contain the value 0 or 1 depending on whether the
7519 compiler in use supports the feature:
7520 write_compiler_detection_header(
7522 FILE climbingstats_compiler_detection.h
7523 PREFIX ClimbingStats
7524 COMPILERS GNU Clang AppleClang MSVC Intel
7525 FEATURES cxx_variadic_templates
7526 )
7527 #if ClimbingStats_COMPILER_CXX_VARIADIC_TEMPLATES
7529 template<typename... T>
7530 void someInterface(T t...) { /* ... */ }
7531 #else
7532 // Compatibility versions
7533 template<typename T1>
7534 void someInterface(T1 t1) { /* ... */ }
7535 template<typename T1, typename T2>
7536 void someInterface(T1 t1, T2 t2) { /* ... */ }
7537 template<typename T1, typename T2, typename T3>
7538 void someInterface(T1 t1, T2 t2, T3 t3) { /* ... */ }
7539 #endif
7540 Symbol Macros
7542 Some additional symbol-defines are created for particular features for
7543 use as symbols which may be conditionally defined empty:
7544 class MyClass ClimbingStats_FINAL
7546 {
7547 ClimbingStats_CONSTEXPR int someInterface() { return 42; }
7548 };
7549 The ClimbingStats_FINAL macro will expand to final if the compiler (and
7551 its flags) support the cxx_final feature, and the ClimbingStats_CONST‐
7552 EXPR macro will expand to constexpr if cxx_constexpr is supported.
7553 If BARE_FEATURES cxx_final was given as argument the final keyword will
7555 be defined for old compilers, too.
7556 The following features generate corresponding symbol defines and if
7558 they are available as BARE_FEATURES:
7559 ┌──────────────────┬────────────────────┬─────────────┬──────┐
7561 │Feature │ Define │ Symbol │ bare │
7562 ├──────────────────┼────────────────────┼─────────────┼──────┤
7563 │c_restrict │ <PRE‐ │ restrict │ yes │
7564 │ │ FIX>_RESTRICT │ │ │
7565 ├──────────────────┼────────────────────┼─────────────┼──────┤
7566 │cxx_constexpr │ <PREFIX>_CONST‐ │ constexpr │ yes │
7567 │ │ EXPR │ │ │
7568 ├──────────────────┼────────────────────┼─────────────┼──────┤
7569 │cxx_deleted_func‐ │ <PRE‐ │ = delete │ │
7570 │tions │ FIX>_DELETED_FUNC‐ │ │ │
7571 │ │ TION │ │ │
7572 └──────────────────┴────────────────────┴─────────────┴──────┘
7573 │cxx_extern_tem‐ │ <PRE‐ │ extern │ │
7576 │plates │ FIX>_EXTERN_TEM‐ │ │ │
7577 │ │ PLATE │ │ │
7578 ├──────────────────┼────────────────────┼─────────────┼──────┤
7579 │cxx_final │ <PREFIX>_FINAL │ final │ yes │
7580 ├──────────────────┼────────────────────┼─────────────┼──────┤
7581 │cxx_noexcept │ <PREFIX>_NOEXCEPT │ noexcept │ yes │
7582 ├──────────────────┼────────────────────┼─────────────┼──────┤
7583 │cxx_noexcept │ <PREFIX>_NOEX‐ │ noexcept(X) │ │
7584 │ │ CEPT_EXPR(X) │ │ │
7585 ├──────────────────┼────────────────────┼─────────────┼──────┤
7586 │cxx_override │ <PREFIX>_OVERRIDE │ override │ yes │
7587 └──────────────────┴────────────────────┴─────────────┴──────┘
7588 Compatibility Implementation Macros
7590 Some features are suitable for wrapping in a macro with a backward com‐
7591 patibility implementation if the compiler does not support the feature.
7592 When the cxx_static_assert feature is not provided by the compiler, a
7594 compatibility implementation is available via the <PRE‐
7595 FIX>_STATIC_ASSERT(COND) and <PREFIX>_STATIC_ASSERT_MSG(COND, MSG)
7596 function-like macros. The macros expand to static_assert where that
7597 compiler feature is available, and to a compatibility implementation
7598 otherwise. In the first form, the condition is stringified in the mes‐
7599 sage field of static_assert. In the second form, the message MSG is
7600 passed to the message field of static_assert, or ignored if using the
7601 backward compatibility implementation.
7602 The cxx_attribute_deprecated feature provides a macro definition <PRE‐
7604 FIX>_DEPRECATED, which expands to either the standard [[deprecated]]
7605 attribute or a compiler-specific decorator such as
7606 __attribute__((__deprecated__)) used by GNU compilers.
7607 The cxx_alignas feature provides a macro definition <PREFIX>_ALIGNAS
7609 which expands to either the standard alignas decorator or a com‐
7610 piler-specific decorator such as __attribute__ ((__aligned__)) used by
7611 GNU compilers.
7612 The cxx_alignof feature provides a macro definition <PREFIX>_ALIGNOF
7614 which expands to either the standard alignof decorator or a com‐
7615 piler-specific decorator such as __alignof__ used by GNU compilers.
7616 ┌───────────────────┬────────────────────────┬────────────────┬──────┐
7618 │Feature │ Define │ Symbol │ bare │
7619 ├───────────────────┼────────────────────────┼────────────────┼──────┤
7620 │cxx_alignas │ <PREFIX>_ALIGNAS │ alignas │ │
7621 ├───────────────────┼────────────────────────┼────────────────┼──────┤
7622 │cxx_alignof │ <PREFIX>_ALIGNOF │ alignof │ │
7623 ├───────────────────┼────────────────────────┼────────────────┼──────┤
7624 │cxx_nullptr │ <PREFIX>_NULLPTR │ nullptr │ yes │
7625 ├───────────────────┼────────────────────────┼────────────────┼──────┤
7626 │cxx_static_assert │ <PRE‐ │ static_assert │ │
7627 │ │ FIX>_STATIC_ASSERT │ │ │
7628 ├───────────────────┼────────────────────────┼────────────────┼──────┤
7629 │cxx_static_assert │ <PRE‐ │ static_assert │ │
7630 │ │ FIX>_STATIC_ASSERT_MSG │ │ │
7631 ├───────────────────┼────────────────────────┼────────────────┼──────┤
7632 │cxx_attribute_dep‐ │ <PREFIX>_DEPRECATED │ [[deprecated]] │ │
7633 │recated │ │ │ │
7634 ├───────────────────┼────────────────────────┼────────────────┼──────┤
7635 │cxx_attribute_dep‐ │ <PREFIX>_DEPRE‐ │ [[deprecated]] │ │
7636 │recated │ CATED_MSG │ │ │
7637 ├───────────────────┼────────────────────────┼────────────────┼──────┤
7638 │cxx_thread_local │ <PREFIX>_THREAD_LOCAL │ thread_local │ │
7639 └───────────────────┴────────────────────────┴────────────────┴──────┘
7640 A use-case which arises with such deprecation macros is the deprecation
7642 of an entire library. In that case, all public API in the library may
7643 be decorated with the <PREFIX>_DEPRECATED macro. This results in very
7644 noisy build output when building the library itself, so the macro may
7645 be may be defined to empty in that case when building the deprecated
7646 library:
7647 add_library(compat_support ${srcs})
7649 target_compile_definitions(compat_support
7650 PRIVATE
7651 CompatSupport_DEPRECATED=
7652 )
7653
7655 These modules search for third-party software. They are normally
7656 called through the find_package() command.
7657 FindALSA
7659 Find Advanced Linux Sound Architecture (ALSA)
7660 Find the alsa libraries (asound)
7662 IMPORTED Targets
7664 This module defines IMPORTED target ALSA::ALSA, if ALSA has been found.
7665 Result Variables
7667 This module defines the following variables:
7668 ALSA_FOUND
7670 True if ALSA_INCLUDE_DIR & ALSA_LIBRARY are found
7671 ALSA_LIBRARIES
7673 List of libraries when using ALSA.
7674 ALSA_INCLUDE_DIRS
7676 Where to find the ALSA headers.
7677 Cache variables
7679 The following cache variables may also be set:
7680 ALSA_INCLUDE_DIR
7682 the ALSA include directory
7683 ALSA_LIBRARY
7685 the absolute path of the asound library
7686 FindArmadillo
7688 Find the Armadillo C++ library. Armadillo is library for linear alge‐
7689 bra & scientific computing.
7690 Using Armadillo:
7692 find_package(Armadillo REQUIRED)
7694 include_directories(${ARMADILLO_INCLUDE_DIRS})
7695 add_executable(foo foo.cc)
7696 target_link_libraries(foo ${ARMADILLO_LIBRARIES})
7697 This module sets the following variables:
7699 ARMADILLO_FOUND - set to true if the library is found
7701 ARMADILLO_INCLUDE_DIRS - list of required include directories
7702 ARMADILLO_LIBRARIES - list of libraries to be linked
7703 ARMADILLO_VERSION_MAJOR - major version number
7704 ARMADILLO_VERSION_MINOR - minor version number
7705 ARMADILLO_VERSION_PATCH - patch version number
7706 ARMADILLO_VERSION_STRING - version number as a string (ex: "1.0.4")
7707 ARMADILLO_VERSION_NAME - name of the version (ex: "Antipodean Antileech")
7708 FindASPELL
7710 Try to find ASPELL
7711 Once done this will define
7713 ASPELL_FOUND - system has ASPELL
7715 ASPELL_EXECUTABLE - the ASPELL executable
7716 ASPELL_INCLUDE_DIR - the ASPELL include directory
7717 ASPELL_LIBRARIES - The libraries needed to use ASPELL
7718 ASPELL_DEFINITIONS - Compiler switches required for using ASPELL
7719 FindAVIFile
7721 Locate AVIFILE library and include paths
7722 AVIFILE (http://avifile.sourceforge.net/) is a set of libraries for
7724 i386 machines to use various AVI codecs. Support is limited beyond
7725 Linux. Windows provides native AVI support, and so doesn’t need this
7726 library. This module defines
7727 AVIFILE_INCLUDE_DIR, where to find avifile.h , etc.
7729 AVIFILE_LIBRARIES, the libraries to link against
7730 AVIFILE_DEFINITIONS, definitions to use when compiling
7731 AVIFILE_FOUND, If false, don't try to use AVIFILE
7732 FindBISON
7734 Find bison executable and provide a macro to generate custom build
7735 rules.
7736 The module defines the following variables:
7738 BISON_EXECUTABLE
7740 path to the bison program
7741 BISON_VERSION
7743 version of bison
7744 BISON_FOUND
7746 “True” if the program was found
7747 The minimum required version of bison can be specified using the stan‐
7749 dard CMake syntax, e.g. find_package(BISON 2.1.3).
7750 If bison is found, the module defines the macro:
7752 BISON_TARGET(<Name> <YaccInput> <CodeOutput>
7754 [COMPILE_FLAGS <flags>]
7755 [DEFINES_FILE <file>]
7756 [VERBOSE [<file>]]
7757 [REPORT_FILE <file>]
7758 )
7759 which will create a custom rule to generate a parser. <YaccInput> is
7761 the path to a yacc file. <CodeOutput> is the name of the source file
7762 generated by bison. A header file is also be generated, and contains
7763 the token list.
7764 The options are:
7766 COMPILE_FLAGS <flags>
7768 Specify flags to be added to the bison command line.
7769 DEFINES_FILE <file>
7771 Specify a non-default header <file> to be generated by bison.
7772 VERBOSE [<file>]
7774 Tell bison to write a report file of the grammar and parser. If
7775 <file> is given, it specifies path the report file is copied to.
7776 [<file>] is left for backward compatibility of this module. Use
7777 VERBOSE REPORT_FILE <file>.
7778 REPORT_FILE <file>
7780 Specify a non-default report <file>, if generated.
7781 The macro defines the following variables:
7783 BISON_<Name>_DEFINED
7785 True is the macro ran successfully
7786 BISON_<Name>_INPUT
7788 The input source file, an alias for <YaccInput>
7789 BISON_<Name>_OUTPUT_SOURCE
7791 The source file generated by bison
7792 BISON_<Name>_OUTPUT_HEADER
7794 The header file generated by bison
7795 BISON_<Name>_OUTPUTS
7797 All files generated by bison including the source, the header
7798 and the report
7799 BISON_<Name>_COMPILE_FLAGS
7801 Options used in the bison command line
7802 Example usage:
7804 find_package(BISON)
7806 BISON_TARGET(MyParser parser.y ${CMAKE_CURRENT_BINARY_DIR}/parser.cpp
7807 DEFINES_FILE ${CMAKE_CURRENT_BINARY_DIR}/parser.h)
7808 add_executable(Foo main.cpp ${BISON_MyParser_OUTPUTS})
7809 FindBLAS
7811 Find Basic Linear Algebra Subprograms (BLAS) library
7812 This module finds an installed Fortran library that implements the BLAS
7814 linear-algebra interface (see http://www.netlib.org/blas/). The list
7815 of libraries searched for is taken from the autoconf macro file,
7816 acx_blas.m4 (distributed at
7817 http://ac-archive.sourceforge.net/ac-archive/acx_blas.html).
7818 Input Variables
7820 The following variables may be set to influence this module’s behavior:
7821 BLA_STATIC
7823 if ON use static linkage
7824 BLA_VENDOR
7826 If set, checks only the specified vendor, if not set checks all
7827 the possibilities. List of vendors valid in this module:
7828 · Goto
7830 · OpenBLAS
7832 · FLAME
7834 · ATLAS PhiPACK
7836 · CXML
7838 · DXML
7840 · SunPerf
7842 · SCSL
7844 · SGIMATH
7846 · IBMESSL
7848 · Intel10_32 (intel mkl v10 32 bit)
7850 · Intel10_64lp (intel mkl v10+ 64 bit, threaded code, lp64
7852 model)
7853 · Intel10_64lp_seq (intel mkl v10+ 64 bit, sequential code, lp64
7855 model)
7856 · Intel10_64ilp (intel mkl v10+ 64 bit, threaded code, ilp64
7858 model)
7859 · Intel10_64ilp_seq (intel mkl v10+ 64 bit, sequential code,
7861 ilp64 model)
7862 · Intel (obsolete versions of mkl 32 and 64 bit)
7864 · ACML
7866 · ACML_MP
7868 · ACML_GPU
7870 · Apple
7872 · NAS
7874 · Generic
7876 BLA_F95
7878 if ON tries to find the BLAS95 interfaces
7879 BLA_PREFER_PKGCONFIG
7881 if set pkg-config will be used to search for a BLAS library
7882 first and if one is found that is preferred
7883 Result Variables
7885 This module defines the following variables:
7886 BLAS_FOUND
7888 library implementing the BLAS interface is found
7889 BLAS_LINKER_FLAGS
7891 uncached list of required linker flags (excluding -l and -L).
7892 BLAS_LIBRARIES
7894 uncached list of libraries (using full path name) to link
7895 against to use BLAS (may be empty if compiler implicitly links
7896 BLAS)
7897 BLAS95_LIBRARIES
7899 uncached list of libraries (using full path name) to link
7900 against to use BLAS95 interface
7901 BLAS95_FOUND
7903 library implementing the BLAS95 interface is found
7904 NOTE:
7906 C or CXX must be enabled to use Intel Math Kernel Library (MKL)
7907 For example, to use Intel MKL libraries and/or Intel compiler:
7909 set(BLA_VENDOR Intel10_64lp)
7911 find_package(BLAS)
7912 Hints
7914 Set MKLROOT environment variable to a directory that contains an MKL
7915 installation.
7916 FindBacktrace
7918 Find provider for backtrace(3).
7919 Checks if OS supports backtrace(3) via either libc or custom library.
7921 This module defines the following variables:
7922 Backtrace_HEADER
7924 The header file needed for backtrace(3). Cached. Could be
7925 forcibly set by user.
7926 Backtrace_INCLUDE_DIRS
7928 The include directories needed to use backtrace(3) header.
7929 Backtrace_LIBRARIES
7931 The libraries (linker flags) needed to use backtrace(3), if any.
7932 Backtrace_FOUND
7934 Is set if and only if backtrace(3) support detected.
7935 The following cache variables are also available to set or use:
7937 Backtrace_LIBRARY
7939 The external library providing backtrace, if any.
7940 Backtrace_INCLUDE_DIR
7942 The directory holding the backtrace(3) header.
7943 Typical usage is to generate of header file using configure_file() with
7945 the contents like the following:
7946 #cmakedefine01 Backtrace_FOUND
7948 #if Backtrace_FOUND
7949 # include <${Backtrace_HEADER}>
7950 #endif
7951 And then reference that generated header file in actual source.
7953 FindBoost
7955 Find Boost include dirs and libraries
7956 Use this module by invoking find_package with the form:
7958 find_package(Boost
7960 [version] [EXACT] # Minimum or EXACT version e.g. 1.67.0
7961 [REQUIRED] # Fail with error if Boost is not found
7962 [COMPONENTS <libs>...] # Boost libraries by their canonical name
7963 # e.g. "date_time" for "libboost_date_time"
7964 [OPTIONAL_COMPONENTS <libs>...]
7965 # Optional Boost libraries by their canonical name)
7966 ) # e.g. "date_time" for "libboost_date_time"
7967 This module finds headers and requested component libraries OR a CMake
7969 package configuration file provided by a “Boost CMake” build. For the
7970 latter case skip to the “Boost CMake” section below. For the former
7971 case results are reported in variables:
7972 Boost_FOUND - True if headers and requested libraries were found
7974 Boost_INCLUDE_DIRS - Boost include directories
7975 Boost_LIBRARY_DIRS - Link directories for Boost libraries
7976 Boost_LIBRARIES - Boost component libraries to be linked
7977 Boost_<C>_FOUND - True if component <C> was found (<C> is upper-case)
7978 Boost_<C>_LIBRARY - Libraries to link for component <C> (may include
7979 target_link_libraries debug/optimized keywords)
7980 Boost_VERSION_MACRO - BOOST_VERSION value from boost/version.hpp
7981 Boost_VERSION_STRING - Boost version number in x.y.z format
7982 Boost_VERSION - if CMP0093 NEW => same as Boost_VERSION_STRING
7983 if CMP0093 OLD or unset => same as Boost_VERSION_MACRO
7984 Boost_LIB_VERSION - Version string appended to library filenames
7985 Boost_VERSION_MAJOR - Boost major version number (X in X.y.z)
7986 alias: Boost_MAJOR_VERSION
7987 Boost_VERSION_MINOR - Boost minor version number (Y in x.Y.z)
7988 alias: Boost_MINOR_VERSION
7989 Boost_VERSION_PATCH - Boost subminor version number (Z in x.y.Z)
7990 alias: Boost_SUBMINOR_VERSION
7991 Boost_VERSION_COUNT - Amount of version components (3)
7992 Boost_LIB_DIAGNOSTIC_DEFINITIONS (Windows)
7993 - Pass to add_definitions() to have diagnostic
7994 information about Boost's automatic linking
7995 displayed during compilation
7996 Note that Boost Python components require a Python version suffix
7998 (Boost 1.67 and later), e.g. python36 or python27 for the versions
7999 built against Python 3.6 and 2.7, respectively. This also applies to
8000 additional components using Python including mpi_python and numpy.
8001 Earlier Boost releases may use distribution-specific suffixes such as
8002 2, 3 or 2.7. These may also be used as suffixes, but note that they
8003 are not portable.
8004 This module reads hints about search locations from variables:
8006 BOOST_ROOT - Preferred installation prefix
8008 (or BOOSTROOT)
8009 BOOST_INCLUDEDIR - Preferred include directory e.g. <prefix>/include
8010 BOOST_LIBRARYDIR - Preferred library directory e.g. <prefix>/lib
8011 Boost_NO_SYSTEM_PATHS - Set to ON to disable searching in locations not
8012 specified by these hint variables. Default is OFF.
8013 Boost_ADDITIONAL_VERSIONS
8014 - List of Boost versions not known to this module
8015 (Boost install locations may contain the version)
8016 and saves search results persistently in CMake cache entries:
8018 Boost_INCLUDE_DIR - Directory containing Boost headers
8020 Boost_LIBRARY_DIR_RELEASE - Directory containing release Boost libraries
8021 Boost_LIBRARY_DIR_DEBUG - Directory containing debug Boost libraries
8022 Boost_<C>_LIBRARY_DEBUG - Component <C> library debug variant
8023 Boost_<C>_LIBRARY_RELEASE - Component <C> library release variant
8024 The following IMPORTED targets are also defined:
8026 Boost::headers - Target for header-only dependencies
8028 (Boost include directory)
8029 alias: Boost::boost
8030 Boost::<C> - Target for specific component dependency
8031 (shared or static library); <C> is lower-
8032 case
8033 Boost::diagnostic_definitions - interface target to enable diagnostic
8034 information about Boost's automatic linking
8035 during compilation (adds BOOST_LIB_DIAGNOSTIC)
8036 Boost::disable_autolinking - interface target to disable automatic
8037 linking with MSVC (adds BOOST_ALL_NO_LIB)
8038 Boost::dynamic_linking - interface target to enable dynamic linking
8039 linking with MSVC (adds BOOST_ALL_DYN_LINK)
8040 Implicit dependencies such as Boost::filesystem requiring Boost::system
8042 will be automatically detected and satisfied, even if system is not
8043 specified when using find_package() and if Boost::system is not added
8044 to target_link_libraries(). If using Boost::thread, then
8045 Threads::Threads will also be added automatically.
8046 It is important to note that the imported targets behave differently
8048 than variables created by this module: multiple calls to find_pack‐
8049 age(Boost) in the same directory or sub-directories with different
8050 options (e.g. static or shared) will not override the values of the
8051 targets created by the first call.
8052 Users may set these hints or results as CACHE entries. Projects should
8054 not read these entries directly but instead use the above result vari‐
8055 ables. Note that some hint names start in upper-case “BOOST”. One may
8056 specify these as environment variables if they are not specified as
8057 CMake variables or cache entries.
8058 This module first searches for the Boost header files using the above
8060 hint variables (excluding BOOST_LIBRARYDIR) and saves the result in
8061 Boost_INCLUDE_DIR. Then it searches for requested component libraries
8062 using the above hints (excluding BOOST_INCLUDEDIR and Boost_ADDI‐
8063 TIONAL_VERSIONS), “lib” directories near Boost_INCLUDE_DIR, and the
8064 library name configuration settings below. It saves the library direc‐
8065 tories in Boost_LIBRARY_DIR_DEBUG and Boost_LIBRARY_DIR_RELEASE and
8066 individual library locations in Boost_<C>_LIBRARY_DEBUG and
8067 Boost_<C>_LIBRARY_RELEASE. When one changes settings used by previous
8068 searches in the same build tree (excluding environment variables) this
8069 module discards previous search results affected by the changes and
8070 searches again.
8071 Boost libraries come in many variants encoded in their file name.
8073 Users or projects may tell this module which variant to find by setting
8074 variables:
8075 Boost_USE_DEBUG_LIBS - Set to ON or OFF to specify whether to search
8077 and use the debug libraries. Default is ON.
8078 Boost_USE_RELEASE_LIBS - Set to ON or OFF to specify whether to search
8079 and use the release libraries. Default is ON.
8080 Boost_USE_MULTITHREADED - Set to OFF to use the non-multithreaded
8081 libraries ('mt' tag). Default is ON.
8082 Boost_USE_STATIC_LIBS - Set to ON to force the use of the static
8083 libraries. Default is OFF.
8084 Boost_USE_STATIC_RUNTIME - Set to ON or OFF to specify whether to use
8085 libraries linked statically to the C++ runtime
8086 ('s' tag). Default is platform dependent.
8087 Boost_USE_DEBUG_RUNTIME - Set to ON or OFF to specify whether to use
8088 libraries linked to the MS debug C++ runtime
8089 ('g' tag). Default is ON.
8090 Boost_USE_DEBUG_PYTHON - Set to ON to use libraries compiled with a
8091 debug Python build ('y' tag). Default is OFF.
8092 Boost_USE_STLPORT - Set to ON to use libraries compiled with
8093 STLPort ('p' tag). Default is OFF.
8094 Boost_USE_STLPORT_DEPRECATED_NATIVE_IOSTREAMS
8095 - Set to ON to use libraries compiled with
8096 STLPort deprecated "native iostreams"
8097 ('n' tag). Default is OFF.
8098 Boost_COMPILER - Set to the compiler-specific library suffix
8099 (e.g. "-gcc43"). Default is auto-computed
8100 for the C++ compiler in use. A list may be
8101 used if multiple compatible suffixes should
8102 be tested for, in decreasing order of
8103 preference.
8104 Boost_ARCHITECTURE - Set to the architecture-specific library suffix
8105 (e.g. "-x64"). Default is auto-computed for the
8106 C++ compiler in use.
8107 Boost_THREADAPI - Suffix for "thread" component library name,
8108 such as "pthread" or "win32". Names with
8109 and without this suffix will both be tried.
8110 Boost_NAMESPACE - Alternate namespace used to build boost with
8111 e.g. if set to "myboost", will search for
8112 myboost_thread instead of boost_thread.
8113 Other variables one may set to control this module are:
8115 Boost_DEBUG - Set to ON to enable debug output from FindBoost.
8117 Please enable this before filing any bug report.
8118 Boost_REALPATH - Set to ON to resolve symlinks for discovered
8119 libraries to assist with packaging. For example,
8120 the "system" component library may be resolved to
8121 "/usr/lib/libboost_system.so.1.67.0" instead of
8122 "/usr/lib/libboost_system.so". This does not
8123 affect linking and should not be enabled unless
8124 the user needs this information.
8125 Boost_LIBRARY_DIR - Default value for Boost_LIBRARY_DIR_RELEASE and
8126 Boost_LIBRARY_DIR_DEBUG.
8127 On Visual Studio and Borland compilers Boost headers request automatic
8129 linking to corresponding libraries. This requires matching libraries
8130 to be linked explicitly or available in the link library search path.
8131 In this case setting Boost_USE_STATIC_LIBS to OFF may not achieve
8132 dynamic linking. Boost automatic linking typically requests static
8133 libraries with a few exceptions (such as Boost.Python). Use:
8134 add_definitions(${Boost_LIB_DIAGNOSTIC_DEFINITIONS})
8136 to ask Boost to report information about automatic linking requests.
8138 Example to find Boost headers only:
8140 find_package(Boost 1.36.0)
8142 if(Boost_FOUND)
8143 include_directories(${Boost_INCLUDE_DIRS})
8144 add_executable(foo foo.cc)
8145 endif()
8146 Example to find Boost libraries and use imported targets:
8148 find_package(Boost 1.56 REQUIRED COMPONENTS
8150 date_time filesystem iostreams)
8151 add_executable(foo foo.cc)
8152 target_link_libraries(foo Boost::date_time Boost::filesystem
8153 Boost::iostreams)
8154 Example to find Boost Python 3.6 libraries and use imported targets:
8156 find_package(Boost 1.67 REQUIRED COMPONENTS
8158 python36 numpy36)
8159 add_executable(foo foo.cc)
8160 target_link_libraries(foo Boost::python36 Boost::numpy36)
8161 Example to find Boost headers and some static (release only) libraries:
8163 set(Boost_USE_STATIC_LIBS ON) # only find static libs
8165 set(Boost_USE_DEBUG_LIBS OFF) # ignore debug libs and
8166 set(Boost_USE_RELEASE_LIBS ON) # only find release libs
8167 set(Boost_USE_MULTITHREADED ON)
8168 set(Boost_USE_STATIC_RUNTIME OFF)
8169 find_package(Boost 1.66.0 COMPONENTS date_time filesystem system ...)
8170 if(Boost_FOUND)
8171 include_directories(${Boost_INCLUDE_DIRS})
8172 add_executable(foo foo.cc)
8173 target_link_libraries(foo ${Boost_LIBRARIES})
8174 endif()
8175 Boost CMake
8177 If Boost was built using the boost-cmake project or from Boost 1.70.0
8178 on it provides a package configuration file for use with find_package’s
8179 config mode. This module looks for the package configuration file
8180 called BoostConfig.cmake or boost-config.cmake and stores the result in
8181 CACHE entry “Boost_DIR”. If found, the package configuration file is
8182 loaded and this module returns with no further action. See documenta‐
8183 tion of the Boost CMake package configuration for details on what it
8184 provides.
8185 Set Boost_NO_BOOST_CMAKE to ON, to disable the search for boost-cmake.
8187 FindBullet
8189 Try to find the Bullet physics engine
8190 This module defines the following variables
8192 BULLET_FOUND - Was bullet found
8194 BULLET_INCLUDE_DIRS - the Bullet include directories
8195 BULLET_LIBRARIES - Link to this, by default it includes
8196 all bullet components (Dynamics,
8197 Collision, LinearMath, & SoftBody)
8198 This module accepts the following variables
8200 BULLET_ROOT - Can be set to bullet install path or Windows build path
8202 FindBZip2
8204 Try to find BZip2
8205 IMPORTED Targets
8207 This module defines IMPORTED target BZip2::BZip2, if BZip2 has been
8208 found.
8209 Result Variables
8211 This module defines the following variables:
8212 BZIP2_FOUND
8214 system has BZip2
8215 BZIP2_INCLUDE_DIRS
8217 the BZip2 include directories
8218 BZIP2_LIBRARIES
8220 Link these to use BZip2
8221 BZIP2_NEED_PREFIX
8223 this is set if the functions are prefixed with BZ2_
8224 BZIP2_VERSION_STRING
8226 the version of BZip2 found
8227 Cache variables
8229 The following cache variables may also be set:
8230 BZIP2_INCLUDE_DIR
8232 the BZip2 include directory
8233 FindCABLE
8235 Find CABLE
8236 This module finds if CABLE is installed and determines where the
8238 include files and libraries are. This code sets the following vari‐
8239 ables:
8240 CABLE the path to the cable executable
8242 CABLE_TCL_LIBRARY the path to the Tcl wrapper library
8243 CABLE_INCLUDE_DIR the path to the include directory
8244 To build Tcl wrappers, you should add shared library and link it to
8246 ${CABLE_TCL_LIBRARY}. You should also add ${CABLE_INCLUDE_DIR} as an
8247 include directory.
8248 FindCoin3D
8250 Find Coin3D (Open Inventor)
8251 Coin3D is an implementation of the Open Inventor API. It provides data
8253 structures and algorithms for 3D visualization.
8254 This module defines the following variables
8256 COIN3D_FOUND - system has Coin3D - Open Inventor
8258 COIN3D_INCLUDE_DIRS - where the Inventor include directory can be found
8259 COIN3D_LIBRARIES - Link to this to use Coin3D
8260 FindCups
8262 Find the Common UNIX Printing System (CUPS).
8263 Set CUPS_REQUIRE_IPP_DELETE_ATTRIBUTE to TRUE if you need a version
8265 which features this function (i.e. at least 1.1.19)
8266 Imported targets
8268 This module defines IMPORTED target Cups::Cups, if Cups has been found.
8269 Result variables
8271 This module will set the following variables in your project:
8272 CUPS_FOUND
8274 true if CUPS headers and libraries were found
8275 CUPS_INCLUDE_DIRS
8277 the directory containing the Cups headers
8278 CUPS_LIBRARIES
8280 the libraries to link against to use CUPS.
8281 CUPS_VERSION_STRING
8283 the version of CUPS found (since CMake 2.8.8)
8284 Cache variables
8286 The following cache variables may also be set:
8287 CUPS_INCLUDE_DIR
8289 the directory containing the Cups headers
8290 FindCURL
8292 Find the native CURL headers and libraries.
8293 This module accept optional COMPONENTS to check supported features and
8295 protocols:
8296 PROTOCOLS: ICT FILE FTP FTPS GOPHER HTTP HTTPS IMAP IMAPS LDAP LDAPS POP3
8298 POP3S RTMP RTSP SCP SFTP SMB SMBS SMTP SMTPS TELNET TFTP
8299 FEATURES: SSL IPv6 UnixSockets libz AsynchDNS IDN GSS-API PSL SPNEGO
8300 Kerberos NTLM NTLM_WB TLS-SRP HTTP2 HTTPS-proxy
8301 IMPORTED Targets
8303 This module defines IMPORTED target CURL::libcurl, if curl has been
8304 found.
8305 Result Variables
8307 This module defines the following variables:
8308 CURL_FOUND
8310 “True” if curl found.
8311 CURL_INCLUDE_DIRS
8313 where to find curl/curl.h, etc.
8314 CURL_LIBRARIES
8316 List of libraries when using curl.
8317 CURL_VERSION_STRING
8319 The version of curl found.
8320 FindCurses
8322 Find the curses or ncurses include file and library.
8323 Result Variables
8325 This module defines the following variables:
8326 CURSES_FOUND
8328 True if Curses is found.
8329 CURSES_INCLUDE_DIRS
8331 The include directories needed to use Curses.
8332 CURSES_LIBRARIES
8334 The libraries needed to use Curses.
8335 CURSES_CFLAGS
8337 Parameters which ought be given to C/C++ compilers when using
8338 Curses.
8339 CURSES_HAVE_CURSES_H
8341 True if curses.h is available.
8342 CURSES_HAVE_NCURSES_H
8344 True if ncurses.h is available.
8345 CURSES_HAVE_NCURSES_NCURSES_H
8347 True if ncurses/ncurses.h is available.
8348 CURSES_HAVE_NCURSES_CURSES_H
8350 True if ncurses/curses.h is available.
8351 Set CURSES_NEED_NCURSES to TRUE before the find_package(Curses) call if
8353 NCurses functionality is required. Set CURSES_NEED_WIDE to TRUE before
8354 the find_package(Curses) call if unicode functionality is required.
8355 Backward Compatibility
8357 The following variable are provided for backward compatibility:
8358 CURSES_INCLUDE_DIR
8360 Path to Curses include. Use CURSES_INCLUDE_DIRS instead.
8361 CURSES_LIBRARY
8363 Path to Curses library. Use CURSES_LIBRARIES instead.
8364 FindCVS
8366 Find the Concurrent Versions System (CVS).
8367 The module defines the following variables:
8369 CVS_EXECUTABLE - path to cvs command line client
8371 CVS_FOUND - true if the command line client was found
8372 Example usage:
8374 find_package(CVS)
8376 if(CVS_FOUND)
8377 message("CVS found: ${CVS_EXECUTABLE}")
8378 endif()
8379 FindCxxTest
8381 Find CxxTest unit testing framework.
8382 Find the CxxTest suite and declare a helper macro for creating unit
8384 tests and integrating them with CTest. For more details on CxxTest see
8385 http://cxxtest.tigris.org
8386 INPUT Variables
8388 CXXTEST_USE_PYTHON [deprecated since 1.3]
8390 Only used in the case both Python & Perl
8391 are detected on the system to control
8392 which CxxTest code generator is used.
8393 Valid only for CxxTest version 3.
8394 NOTE: In older versions of this Find Module,
8396 this variable controlled if the Python test
8397 generator was used instead of the Perl one,
8398 regardless of which scripting language the
8399 user had installed.
8400 CXXTEST_TESTGEN_ARGS (since CMake 2.8.3)
8402 Specify a list of options to pass to the CxxTest code
8403 generator. If not defined, --error-printer is
8404 passed.
8405 OUTPUT Variables
8407 CXXTEST_FOUND
8409 True if the CxxTest framework was found
8410 CXXTEST_INCLUDE_DIRS
8411 Where to find the CxxTest include directory
8412 CXXTEST_PERL_TESTGEN_EXECUTABLE
8413 The perl-based test generator
8414 CXXTEST_PYTHON_TESTGEN_EXECUTABLE
8415 The python-based test generator
8416 CXXTEST_TESTGEN_EXECUTABLE (since CMake 2.8.3)
8417 The test generator that is actually used (chosen using user preferences
8418 and interpreters found in the system)
8419 CXXTEST_TESTGEN_INTERPRETER (since CMake 2.8.3)
8420 The full path to the Perl or Python executable on the system, on
8421 platforms where the script cannot be executed using its shebang line.
8422 MACROS for optional use by CMake users:
8424 CXXTEST_ADD_TEST(<test_name> <gen_source_file> <input_files_to_testgen...>)
8426 Creates a CxxTest runner and adds it to the CTest testing suite
8427 Parameters:
8428 test_name The name of the test
8429 gen_source_file The generated source filename to be
8430 generated by CxxTest
8431 input_files_to_testgen The list of header files containing the
8432 CxxTest::TestSuite's to be included in
8433 this runner
8434 #==============
8436 Example Usage:
8437 find_package(CxxTest)
8439 if(CXXTEST_FOUND)
8440 include_directories(${CXXTEST_INCLUDE_DIR})
8441 enable_testing()
8442 CXXTEST_ADD_TEST(unittest_foo foo_test.cc
8444 ${CMAKE_CURRENT_SOURCE_DIR}/foo_test.h)
8445 target_link_libraries(unittest_foo foo) # as needed
8446 endif()
8447 This will (if CxxTest is found):
8449 1. Invoke the testgen executable to autogenerate foo_test.cc in the
8450 binary tree from "foo_test.h" in the current source directory.
8451 2. Create an executable and test called unittest_foo.
8452 #=============
8454 Example foo_test.h:
8455 #include <cxxtest/TestSuite.h>
8457 class MyTestSuite : public CxxTest::TestSuite
8459 {
8460 public:
8461 void testAddition( void )
8462 {
8463 TS_ASSERT( 1 + 1 > 1 );
8464 TS_ASSERT_EQUALS( 1 + 1, 2 );
8465 }
8466 };
8467 FindCygwin
8469 Find Cygwin, a POSIX-compatible environment that runs natively on Mi‐
8470 crosoft Windows
8471 FindDart
8473 Find DART
8474 This module looks for the dart testing software and sets DART_ROOT to
8476 point to where it found it.
8477 FindDCMTK
8479 Find DICOM ToolKit (DCMTK) libraries and applications
8480 The module defines the following variables:
8482 DCMTK_INCLUDE_DIRS - Directories to include to use DCMTK
8484 DCMTK_LIBRARIES - Files to link against to use DCMTK
8485 DCMTK_FOUND - If false, don't try to use DCMTK
8486 DCMTK_DIR - (optional) Source directory for DCMTK
8487 Compatibility
8489 This module is able to find a version of DCMTK that does or does not
8490 export a DCMTKConfig.cmake file. It applies a two step process:
8491 · Step 1: Attempt to find DCMTK version providing a DCMTKConfig.cmake
8493 file.
8494 · Step 2: If step 1 failed, rely on FindDCMTK.cmake to set DCMTK_*
8496 variables details below.
8497 Recent DCMTK provides a DCMTKConfig.cmake package configuration file.
8499 To exclusively use the package configuration file (recommended when
8500 possible), pass the NO_MODULE option to find_package(). For example,
8501 find_package(DCMTK NO_MODULE). This requires official DCMTK snapshot
8502 3.6.1_20140617 or newer.
8503 Until all clients update to the more recent DCMTK, build systems will
8505 need to support different versions of DCMTK.
8506 On any given system, the following combinations of DCMTK versions could
8508 be considered:
8509 ┌───────┬─────────────────┬─────────────────┬─────────────┐
8511 │ │ SYSTEM DCMTK │ LOCAL DCMTK │ Supported ? │
8512 ├───────┼─────────────────┼─────────────────┼─────────────┤
8513 │Case A │ NA │ [ ] DCMTKConfig │ YES │
8514 ├───────┼─────────────────┼─────────────────┼─────────────┤
8515 │Case B │ NA │ [X] DCMTKConfig │ YES │
8516 ├───────┼─────────────────┼─────────────────┼─────────────┤
8517 │Case C │ [ ] DCMTKConfig │ NA │ YES │
8518 ├───────┼─────────────────┼─────────────────┼─────────────┤
8519 │Case D │ [X] DCMTKConfig │ NA │ YES │
8520 ├───────┼─────────────────┼─────────────────┼─────────────┤
8521 │Case E │ [ ] DCMTKConfig │ [ ] DCMTKConfig │ YES (*) │
8522 ├───────┼─────────────────┼─────────────────┼─────────────┤
8523 │Case F │ [X] DCMTKConfig │ [ ] DCMTKConfig │ NO │
8524 ├───────┼─────────────────┼─────────────────┼─────────────┤
8525 │Case G │ [ ] DCMTKConfig │ [X] DCMTKConfig │ YES │
8526 ├───────┼─────────────────┼─────────────────┼─────────────┤
8527 │Case H │ [X] DCMTKConfig │ [X] DCMTKConfig │ YES │
8528 └───────┴─────────────────┴─────────────────┴─────────────┘
8529 (*) See Troubleshooting section.
8530 Legend:
8532 NA ……………: Means that no System or Local DCMTK is available
8533 [ ] DCMTKConfig ..: Means that the version of DCMTK does NOT export
8535 a DCMTKConfig.cmake file.
8536 [X] DCMTKConfig ..: Means that the version of DCMTK exports a DCMTK‐
8538 Config.cmake file.
8539 Troubleshooting
8541 What to do if my project finds a different version of DCMTK?
8542 Remove DCMTK entry from the CMake cache per find_package() documenta‐
8544 tion.
8545 FindDevIL
8547 This module locates the developer’s image library.
8548 http://openil.sourceforge.net/
8549 This module sets:
8551 IL_LIBRARIES - the name of the IL library. These include the full path to
8553 the core DevIL library. This one has to be linked into the
8554 application.
8555 ILU_LIBRARIES - the name of the ILU library. Again, the full path. This
8556 library is for filters and effects, not actual loading. It
8557 doesn't have to be linked if the functionality it provides
8558 is not used.
8559 ILUT_LIBRARIES - the name of the ILUT library. Full path. This part of the
8560 library interfaces with OpenGL. It is not strictly needed
8561 in applications.
8562 IL_INCLUDE_DIR - where to find the il.h, ilu.h and ilut.h files.
8563 DevIL_FOUND - this is set to TRUE if all the above variables were set.
8564 This will be set to false if ILU or ILUT are not found,
8565 even if they are not needed. In most systems, if one
8566 library is found all the others are as well. That's the
8567 way the DevIL developers release it.
8568 FindDoxygen
8570 Doxygen is a documentation generation tool (see
8571 http://www.doxygen.org). This module looks for Doxygen and some
8572 optional tools it supports. These tools are enabled as components in
8573 the find_package() command:
8574 dot Graphviz dot utility used to render various graphs.
8576 mscgen Message Chart Generator utility used by Doxygen’s \msc and \msc‐
8578 file commands.
8579 dia Dia the diagram editor used by Doxygen’s \diafile command.
8581 Examples:
8583 # Require dot, treat the other components as optional
8585 find_package(Doxygen
8586 REQUIRED dot
8587 OPTIONAL_COMPONENTS mscgen dia)
8588 The following variables are defined by this module:
8590 DOXYGEN_FOUND
8592 True if the doxygen executable was found.
8593 DOXYGEN_VERSION
8595 The version reported by doxygen --version.
8596 The module defines IMPORTED targets for Doxygen and each component
8598 found. These can be used as part of custom commands, etc. and should
8599 be preferred over old-style (and now deprecated) variables like DOXY‐
8600 GEN_EXECUTABLE. The following import targets are defined if their cor‐
8601 responding executable could be found (the component import targets will
8602 only be defined if that component was requested):
8603 Doxygen::doxygen
8605 Doxygen::dot
8606 Doxygen::mscgen
8607 Doxygen::dia
8608 Functions
8610 doxygen_add_docs
8611 This function is intended as a convenience for adding a target
8612 for generating documentation with Doxygen. It aims to provide
8613 sensible defaults so that projects can generally just provide
8614 the input files and directories and that will be sufficient to
8615 give sensible results. The function supports the ability to cus‐
8616 tomize the Doxygen configuration used to build the documenta‐
8617 tion.
8618 doxygen_add_docs(targetName
8620 [filesOrDirs...]
8621 [ALL]
8622 [USE_STAMP_FILE]
8623 [WORKING_DIRECTORY dir]
8624 [COMMENT comment])
8625 The function constructs a Doxyfile and defines a custom target
8627 that runs Doxygen on that generated file. The listed files and
8628 directories are used as the INPUT of the generated Doxyfile and
8629 they can contain wildcards. Any files that are listed explic‐
8630 itly will also be added as SOURCES of the custom target so they
8631 will show up in an IDE project’s source list.
8632 So that relative input paths work as expected, by default the
8634 working directory of the Doxygen command will be the current
8635 source directory (i.e. CMAKE_CURRENT_SOURCE_DIR). This can be
8636 overridden with the WORKING_DIRECTORY option to change the
8637 directory used as the relative base point. Note also that Doxy‐
8638 gen’s default behavior is to strip the working directory from
8639 relative paths in the generated documentation (see the
8640 STRIP_FROM_PATH Doxygen config option for details).
8641 If provided, the optional comment will be passed as the COMMENT
8643 for the add_custom_target() command used to create the custom
8644 target internally.
8645 If ALL is set, the target will be added to the default build
8647 target.
8648 If USE_STAMP_FILE is set, the custom command defined by this
8650 function will create a stamp file with the name <target‐
8651 Name>.stamp in the current binary directory whenever doxygen is
8652 re-run. With this option present, all items in <filesOrDirs>
8653 must be files (i.e. no directories, symlinks or wildcards) and
8654 each of the files must exist at the time doxygen_add_docs() is
8655 called. An error will be raised if any of the items listed is
8656 missing or is not a file when USE_STAMP_FILE is given. A depen‐
8657 dency will be created on each of the files so that doxygen will
8658 only be re-run if one of the files is updated. Without the
8659 USE_STAMP_FILE option, doxygen will always be re-run if the
8660 <targetName> target is built regardless of whether anything
8661 listed in <filesOrDirs> has changed.
8662 The contents of the generated Doxyfile can be customized by set‐
8664 ting CMake variables before calling doxygen_add_docs(). Any
8665 variable with a name of the form DOXYGEN_<tag> will have its
8666 value substituted for the corresponding <tag> configuration
8667 option in the Doxyfile. See the Doxygen documentation for the
8668 full list of supported configuration options.
8669 Some of Doxygen’s defaults are overridden to provide more appro‐
8671 priate behavior for a CMake project. Each of the following will
8672 be explicitly set unless the variable already has a value before
8673 doxygen_add_docs() is called (with some exceptions noted):
8674 DOXYGEN_HAVE_DOT
8676 Set to YES if the dot component was requested and it was
8677 found, NO otherwise. Any existing value of DOXY‐
8678 GEN_HAVE_DOT is ignored.
8679 DOXYGEN_DOT_MULTI_TARGETS
8681 Set to YES by this module (note that this requires a dot
8682 version newer than 1.8.10). This option is only meaning‐
8683 ful if DOXYGEN_HAVE_DOT is also set to YES.
8684 DOXYGEN_GENERATE_LATEX
8686 Set to NO by this module.
8687 DOXYGEN_WARN_FORMAT
8689 For Visual Studio based generators, this is set to the
8690 form recognized by the Visual Studio IDE: $file($line) :
8691 $text. For all other generators, Doxygen’s default value
8692 is not overridden.
8693 DOXYGEN_PROJECT_NAME
8695 Populated with the name of the current project (i.e.
8696 PROJECT_NAME).
8697 DOXYGEN_PROJECT_NUMBER
8699 Populated with the version of the current project (i.e.
8700 PROJECT_VERSION).
8701 DOXYGEN_PROJECT_BRIEF
8703 Populated with the description of the current project
8704 (i.e. PROJECT_DESCRIPTION).
8705 DOXYGEN_INPUT
8707 Projects should not set this variable. It will be popu‐
8708 lated with the set of files and directories passed to
8709 doxygen_add_docs(), thereby providing consistent behavior
8710 with the other built-in commands like add_executable(),
8711 add_library() and add_custom_target(). If a variable
8712 named DOXYGEN_INPUT is set by the project, it will be
8713 ignored and a warning will be issued.
8714 DOXYGEN_RECURSIVE
8716 Set to YES by this module.
8717 DOXYGEN_EXCLUDE_PATTERNS
8719 If the set of inputs includes directories, this variable
8720 will specify patterns used to exclude files from them.
8721 The following patterns are added by doxygen_add_docs() to
8722 ensure CMake-specific files and directories are not
8723 included in the input. If the project sets DOXY‐
8724 GEN_EXCLUDE_PATTERNS, those contents are merged with
8725 these additional patterns rather than replacing them:
8726 */.git/*
8728 */.svn/*
8729 */.hg/*
8730 */CMakeFiles/*
8731 */_CPack_Packages/*
8732 DartConfiguration.tcl
8733 CMakeLists.txt
8734 CMakeCache.txt
8735 DOXYGEN_OUTPUT_DIRECTORY
8737 Set to CMAKE_CURRENT_BINARY_DIR by this module. Note that
8738 if the project provides its own value for this and it is
8739 a relative path, it will be converted to an absolute path
8740 relative to the current binary directory. This is neces‐
8741 sary because doxygen will normally be run from a direc‐
8742 tory within the source tree so that relative source paths
8743 work as expected. If this directory does not exist, it
8744 will be recursively created prior to executing the doxy‐
8745 gen commands.
8746 To change any of these defaults or override any other Doxygen config
8748 option, set relevant variables before calling doxygen_add_docs(). For
8749 example:
8750 set(DOXYGEN_GENERATE_HTML NO)
8752 set(DOXYGEN_GENERATE_MAN YES)
8753 doxygen_add_docs(
8755 doxygen
8756 ${PROJECT_SOURCE_DIR}
8757 COMMENT "Generate man pages"
8758 )
8759 A number of Doxygen config options accept lists of values, but Doxygen
8761 requires them to be separated by whitespace. CMake variables hold lists
8762 as a string with items separated by semi-colons, so a conversion needs
8763 to be performed. The doxygen_add_docs() command specifically checks the
8764 following Doxygen config options and will convert their associated
8765 CMake variable’s contents into the required form if set.
8766 ABBREVIATE_BRIEF
8768 ALIASES
8769 CITE_BIB_FILES
8770 DIAFILE_DIRS
8771 DOTFILE_DIRS
8772 DOT_FONTPATH
8773 ENABLED_SECTIONS
8774 EXAMPLE_PATH
8775 EXAMPLE_PATTERNS
8776 EXCLUDE
8777 EXCLUDE_PATTERNS
8778 EXCLUDE_SYMBOLS
8779 EXPAND_AS_DEFINED
8780 EXTENSION_MAPPING
8781 EXTRA_PACKAGES
8782 EXTRA_SEARCH_MAPPINGS
8783 FILE_PATTERNS
8784 FILTER_PATTERNS
8785 FILTER_SOURCE_PATTERNS
8786 HTML_EXTRA_FILES
8787 HTML_EXTRA_STYLESHEET
8788 IGNORE_PREFIX
8789 IMAGE_PATH
8790 INCLUDE_FILE_PATTERNS
8791 INCLUDE_PATH
8792 INPUT
8793 LATEX_EXTRA_FILES
8794 LATEX_EXTRA_STYLESHEET
8795 MATHJAX_EXTENSIONS
8796 MSCFILE_DIRS
8797 PLANTUML_INCLUDE_PATH
8798 PREDEFINED
8799 QHP_CUST_FILTER_ATTRS
8800 QHP_SECT_FILTER_ATTRS
8801 STRIP_FROM_INC_PATH
8802 STRIP_FROM_PATH
8803 TAGFILES
8804 TCL_SUBST
8805 The following single value Doxygen options will be quoted automatically
8807 if they contain at least one space:
8808 CHM_FILE
8810 DIA_PATH
8811 DOCBOOK_OUTPUT
8812 DOCSET_FEEDNAME
8813 DOCSET_PUBLISHER_NAME
8814 DOT_FONTNAME
8815 DOT_PATH
8816 EXTERNAL_SEARCH_ID
8817 FILE_VERSION_FILTER
8818 GENERATE_TAGFILE
8819 HHC_LOCATION
8820 HTML_FOOTER
8821 HTML_HEADER
8822 HTML_OUTPUT
8823 HTML_STYLESHEET
8824 INPUT_FILTER
8825 LATEX_FOOTER
8826 LATEX_HEADER
8827 LATEX_OUTPUT
8828 LAYOUT_FILE
8829 MAN_OUTPUT
8830 MAN_SUBDIR
8831 MATHJAX_CODEFILE
8832 MSCGEN_PATH
8833 OUTPUT_DIRECTORY
8834 PERL_PATH
8835 PLANTUML_JAR_PATH
8836 PROJECT_BRIEF
8837 PROJECT_LOGO
8838 PROJECT_NAME
8839 QCH_FILE
8840 QHG_LOCATION
8841 QHP_CUST_FILTER_NAME
8842 QHP_VIRTUAL_FOLDER
8843 RTF_EXTENSIONS_FILE
8844 RTF_OUTPUT
8845 RTF_STYLESHEET_FILE
8846 SEARCHDATA_FILE
8847 USE_MDFILE_AS_MAINPAGE
8848 WARN_FORMAT
8849 WARN_LOGFILE
8850 XML_OUTPUT
8851 There are situations where it may be undesirable for a particular con‐
8853 fig option to be automatically quoted by doxygen_add_docs(), such as
8854 ALIASES which may need to include its own embedded quoting. The DOXY‐
8855 GEN_VERBATIM_VARS variable can be used to specify a list of Doxygen
8856 variables (including the leading DOXYGEN_ prefix) which should not be
8857 quoted. The project is then responsible for ensuring that those vari‐
8858 ables’ values make sense when placed directly in the Doxygen input
8859 file. In the case of list variables, list items are still separated by
8860 spaces, it is only the automatic quoting that is skipped. For example,
8861 the following allows doxygen_add_docs() to apply quoting to DOXY‐
8862 GEN_PROJECT_BRIEF, but not each item in the DOXYGEN_ALIASES list
8863 (bracket syntax can also be used to make working with embedded quotes
8864 easier):
8865 set(DOXYGEN_PROJECT_BRIEF "String with spaces")
8867 set(DOXYGEN_ALIASES
8868 [[somealias="@some_command param"]]
8869 "anotherAlias=@foobar"
8870 )
8871 set(DOXYGEN_VERBATIM_VARS DOXYGEN_ALIASES)
8872 The resultant Doxyfile will contain the following lines:
8874 PROJECT_BRIEF = "String with spaces"
8876 ALIASES = somealias="@some_command param" anotherAlias=@foobar
8877 Deprecated Result Variables
8879 For compatibility with previous versions of CMake, the following vari‐
8880 ables are also defined but they are deprecated and should no longer be
8881 used:
8882 DOXYGEN_EXECUTABLE
8884 The path to the doxygen command. If projects need to refer to
8885 the doxygen executable directly, they should use the Doxy‐
8886 gen::doxygen import target instead.
8887 DOXYGEN_DOT_FOUND
8889 True if the dot executable was found.
8890 DOXYGEN_DOT_EXECUTABLE
8892 The path to the dot command. If projects need to refer to the
8893 dot executable directly, they should use the Doxygen::dot import
8894 target instead.
8895 DOXYGEN_DOT_PATH
8897 The path to the directory containing the dot executable as
8898 reported in DOXYGEN_DOT_EXECUTABLE. The path may have forward
8899 slashes even on Windows and is not suitable for direct substitu‐
8900 tion into a Doxyfile.in template. If you need this value, get
8901 the IMPORTED_LOCATION property of the Doxygen::dot target and
8902 use get_filename_component() to extract the directory part of
8903 that path. You may also want to consider using
8904 file(TO_NATIVE_PATH) to prepare the path for a Doxygen configu‐
8905 ration file.
8906 Deprecated Hint Variables
8908 DOXYGEN_SKIP_DOT
8909 This variable has no effect for the component form of find_pack‐
8910 age. In backward compatibility mode (i.e. without components
8911 list) it prevents the finder module from searching for
8912 Graphviz’s dot utility.
8913 FindEnvModules
8915 Locate an environment module implementation and make commands available
8916 to CMake scripts to use them. This is compatible with both Lua-based
8917 Lmod and TCL-based EnvironmentModules.
8918 This module is intended for the use case of setting up the compiler and
8920 library environment within a CTest Script (ctest -S). It can also be
8921 used in a CMake Script (cmake -P).
8922 NOTE:
8924 The loaded environment will not survive past the end of the calling
8925 process. Do not use this module in project code (CMakeLists.txt
8926 files) to load a compiler environment; it will not be available dur‐
8927 ing the build. Instead load the environment manually before running
8928 CMake or using the generated build system.
8929 Example Usage
8931 set(CTEST_BUILD_NAME "CrayLinux-CrayPE-Cray-dynamic")
8932 set(CTEST_BUILD_CONFIGURATION Release)
8933 set(CTEST_BUILD_FLAGS "-k -j8")
8934 set(CTEST_CMAKE_GENERATOR "Unix Makefiles")
8935 ...
8937 find_package(EnvModules REQUIRED)
8939 env_module(purge)
8941 env_module(load modules)
8942 env_module(load craype)
8943 env_module(load PrgEnv-cray)
8944 env_module(load craype-knl)
8945 env_module(load cray-mpich)
8946 env_module(load cray-libsci)
8947 set(ENV{CRAYPE_LINK_TYPE} dynamic)
8949 ...
8951 Result Variables
8953 This module will set the following variables in your project:
8954 EnvModules_FOUND
8956 True if a compatible environment modules framework was found.
8957 Cache Variables
8959 The following cache variable will be set:
8960 EnvModules_COMMAND
8962 The low level module command to use. Currently supported imple‐
8963 mentations are the Lua based Lmod and TCL based EnvironmentMod‐
8964 ules.
8965 Environment Variables
8967 ENV{MODULESHOME}
8968 Usually set by the module environment implementation, used as a
8969 hint to locate the module command to execute.
8970 Provided Functions
8972 This defines the following CMake functions for interacting with envi‐
8973 ronment modules:
8974 env_module
8976 Execute an aribitrary module command:
8977 env_module(cmd arg1 ... argN)
8979 env_module(
8980 COMMAND cmd arg1 ... argN
8981 [OUTPUT_VARIABLE <out-var>]
8982 [RESULT_VARIABLE <ret-var>]
8983 )
8984 The options are:
8986 cmd arg1 ... argN
8988 The module sub-command and arguments to execute as if
8989 they were passed directly to the module command in your
8990 shell environment.
8991 OUTPUT_VARIABLE <out-var>
8993 The standard output from executing the module command.
8994 RESULT_VARIABLE <ret-var>
8996 The return code from executing the module command.
8997 env_module_swap
8999 Swap one module for another:
9000 env_module_swap(out_mod in_mod
9002 [OUTPUT_VARIABLE <out-var>]
9003 [RESULT_VARIABLE <ret-var>]
9004 )
9005 This is functionally equivalent to the module swap out_mod
9007 in_mod shell command. The options are:
9008 OUTPUT_VARIABLE <out-var>
9010 The standard output from executing the module command.
9011 RESULT_VARIABLE <ret-var>
9013 The return code from executing the module command.
9014 env_module_list
9016 Retrieve the list of currently loaded modules:
9017 env_module_list(<out-var>)
9019 This is functionally equivalent to the module list shell com‐
9021 mand. The result is stored in <out-var> as a properly formatted
9022 CMake semicolon-separated list variable.
9023 env_module_avail
9025 Retrieve the list of available modules:
9026 env_module_avail([<mod-prefix>] <out-var>)
9028 This is functionally equivalent to the module avail <mod-prefix>
9030 shell command. The result is stored in <out-var> as a properly
9031 formatted CMake semicolon-separated list variable.
9032 FindEXPAT
9034 Find the native Expat headers and library. Expat is a stream-oriented
9035 XML parser library written in C.
9036 Imported Targets
9038 This module defines the following IMPORTED targets:
9039 EXPAT::EXPAT
9041 The Expat expat library, if found.
9042 Result Variables
9044 This module will set the following variables in your project:
9045 EXPAT_INCLUDE_DIRS
9047 where to find expat.h, etc.
9048 EXPAT_LIBRARIES
9050 the libraries to link against to use Expat.
9051 EXPAT_FOUND
9053 true if the Expat headers and libraries were found.
9054 FindFLEX
9056 Find Fast Lexical Analyzer (Flex) executable and provides a macro to
9057 generate custom build rules
9058 The module defines the following variables:
9060 FLEX_FOUND - True is flex executable is found
9062 FLEX_EXECUTABLE - the path to the flex executable
9063 FLEX_VERSION - the version of flex
9064 FLEX_LIBRARIES - The flex libraries
9065 FLEX_INCLUDE_DIRS - The path to the flex headers
9066 The minimum required version of flex can be specified using the stan‐
9068 dard syntax, e.g. find_package(FLEX 2.5.13)
9069 If flex is found on the system, the module provides the macro:
9071 FLEX_TARGET(Name FlexInput FlexOutput
9073 [COMPILE_FLAGS <string>]
9074 [DEFINES_FILE <string>]
9075 )
9076 which creates a custom command to generate the FlexOutput file from the
9078 FlexInput file. If COMPILE_FLAGS option is specified, the next parame‐
9079 ter is added to the flex command line. If flex is configured to output
9080 a header file, the DEFINES_FILE option may be used to specify its name.
9081 Name is an alias used to get details of this custom command. Indeed
9082 the macro defines the following variables:
9083 FLEX_${Name}_DEFINED - true is the macro ran successfully
9085 FLEX_${Name}_OUTPUTS - the source file generated by the custom rule, an
9086 alias for FlexOutput
9087 FLEX_${Name}_INPUT - the flex source file, an alias for ${FlexInput}
9088 FLEX_${Name}_OUTPUT_HEADER - the header flex output, if any.
9089 Flex scanners often use tokens defined by Bison: the code generated by
9091 Flex depends of the header generated by Bison. This module also
9092 defines a macro:
9093 ADD_FLEX_BISON_DEPENDENCY(FlexTarget BisonTarget)
9095 which adds the required dependency between a scanner and a parser where
9097 FlexTarget and BisonTarget are the first parameters of respectively
9098 FLEX_TARGET and BISON_TARGET macros.
9099 ====================================================================
9101 Example:
9102 find_package(BISON)
9104 find_package(FLEX)
9105 BISON_TARGET(MyParser parser.y ${CMAKE_CURRENT_BINARY_DIR}/parser.cpp)
9107 FLEX_TARGET(MyScanner lexer.l ${CMAKE_CURRENT_BINARY_DIR}/lexer.cpp)
9108 ADD_FLEX_BISON_DEPENDENCY(MyScanner MyParser)
9109 include_directories(${CMAKE_CURRENT_BINARY_DIR})
9111 add_executable(Foo
9112 Foo.cc
9113 ${BISON_MyParser_OUTPUTS}
9114 ${FLEX_MyScanner_OUTPUTS}
9115 )
9116 target_link_libraries(Foo ${FLEX_LIBRARIES})
9117 ====================================================================
9118 FindFLTK2
9120 Find the native FLTK 2.0 includes and library
9121 The following settings are defined
9123 FLTK2_FLUID_EXECUTABLE, where to find the Fluid tool
9125 FLTK2_WRAP_UI, This enables the FLTK2_WRAP_UI command
9126 FLTK2_INCLUDE_DIR, where to find include files
9127 FLTK2_LIBRARIES, list of fltk2 libraries
9128 FLTK2_FOUND, Don't use FLTK2 if false.
9129 The following settings should not be used in general.
9131 FLTK2_BASE_LIBRARY = the full path to fltk2.lib
9133 FLTK2_GL_LIBRARY = the full path to fltk2_gl.lib
9134 FLTK2_IMAGES_LIBRARY = the full path to fltk2_images.lib
9135 FindFLTK
9137 Find the Fast Light Toolkit (FLTK) library
9138 Input Variables
9140 By default this module will search for all of the FLTK components and
9141 add them to the FLTK_LIBRARIES variable. You can limit the components
9142 which get placed in FLTK_LIBRARIES by defining one or more of the fol‐
9143 lowing three options:
9144 FLTK_SKIP_OPENGL
9146 Set to true to disable searching for the FLTK GL library
9147 FLTK_SKIP_FORMS
9149 Set to true to disable searching for the FLTK Forms library
9150 FLTK_SKIP_IMAGES
9152 Set to true to disable searching for the FLTK Images library
9153 FLTK is composed also by a binary tool. You can set the following
9155 option:
9156 FLTK_SKIP_FLUID
9158 Set to true to not look for the FLUID binary
9159 Result Variables
9161 The following variables will be defined:
9162 FLTK_FOUND
9164 True if all components not skipped were found
9165 FLTK_INCLUDE_DIR
9167 Path to the include directory for FLTK header files
9168 FLTK_LIBRARIES
9170 List of the FLTK libraries found
9171 FLTK_FLUID_EXECUTABLE
9173 Path to the FLUID binary tool
9174 FLTK_WRAP_UI
9176 True if FLUID is found, used to enable the FLTK_WRAP_UI command
9177 Cache Variables
9179 The following cache variables are also available to set or use:
9180 FLTK_BASE_LIBRARY_RELEASE
9182 The FLTK base library (optimized)
9183 FLTK_BASE_LIBRARY_DEBUG
9185 The FLTK base library (debug)
9186 FLTK_GL_LIBRARY_RELEASE
9188 The FLTK GL library (optimized)
9189 FLTK_GL_LIBRARY_DEBUG
9191 The FLTK GL library (debug)
9192 FLTK_FORMS_LIBRARY_RELEASE
9194 The FLTK Forms library (optimized)
9195 FLTK_FORMS_LIBRARY_DEBUG
9197 The FLTK Forms library (debug)
9198 FLTK_IMAGES_LIBRARY_RELEASE
9200 The FLTK Images protobuf library (optimized)
9201 FLTK_IMAGES_LIBRARY_DEBUG
9203 The FLTK Images library (debug)
9204 FindFontconfig
9206 Find Fontconfig headers and library.
9207 Imported Targets
9209 Fontconfig::Fontconfig
9210 The Fontconfig library, if found.
9211 Result Variables
9213 This will define the following variables in your project:
9214 Fontconfig_FOUND
9216 true if (the requested version of) Fontconfig is available.
9217 Fontconfig_VERSION
9219 the version of Fontconfig.
9220 Fontconfig_LIBRARIES
9222 the libraries to link against to use Fontconfig.
9223 Fontconfig_INCLUDE_DIRS
9225 where to find the Fontconfig headers.
9226 Fontconfig_COMPILE_OPTIONS
9228 this should be passed to target_compile_options(), if the target
9229 is not used for linking
9230 FindFreetype
9232 Find the FreeType font renderer includes and library.
9233 Imported Targets
9235 This module defines the following IMPORTED target:
9236 Freetype::Freetype
9238 The Freetype freetype library, if found
9239 Result Variables
9241 This module will set the following variables in your project:
9242 FREETYPE_FOUND
9244 true if the Freetype headers and libraries were found
9245 FREETYPE_INCLUDE_DIRS
9247 directories containing the Freetype headers. This is the con‐
9248 catenation of the variables:
9249 FREETYPE_INCLUDE_DIR_ft2build
9251 directory holding the main Freetype API configuration
9252 header
9253 FREETYPE_INCLUDE_DIR_freetype2
9255 directory holding Freetype public headers
9256 FREETYPE_LIBRARIES
9258 the library to link against
9259 FREETYPE_VERSION_STRING
9261 the version of freetype found (since CMake 2.8.8)
9262 Hints
9264 The user may set the environment variable FREETYPE_DIR to the root
9265 directory of a Freetype installation.
9266 FindGCCXML
9268 Find the GCC-XML front-end executable.
9269 This module will define the following variables:
9271 GCCXML - the GCC-XML front-end executable.
9273 FindGDAL
9275 Find Geospatial Data Abstraction Library (GDAL).
9276 IMPORTED Targets
9278 This module defines IMPORTED target GDAL::GDAL if GDAL has been found.
9279 Result Variables
9281 This module will set the following variables in your project:
9282 GDAL_FOUND
9284 True if GDAL is found.
9285 GDAL_INCLUDE_DIRS
9287 Include directories for GDAL headers.
9288 GDAL_LIBRARIES
9290 Libraries to link to GDAL.
9291 GDAL_VERSION
9293 The version of GDAL found.
9294 Cache variables
9296 The following cache variables may also be set:
9297 GDAL_LIBRARY
9299 The libgdal library file.
9300 GDAL_INCLUDE_DIR
9302 The directory containing gdal.h.
9303 Hints
9305 Set GDAL_DIR or GDAL_ROOT in the environment to specify the GDAL
9306 installation prefix.
9307 FindGettext
9309 Find GNU gettext tools
9310 This module looks for the GNU gettext tools. This module defines the
9312 following values:
9313 GETTEXT_MSGMERGE_EXECUTABLE: the full path to the msgmerge tool.
9315 GETTEXT_MSGFMT_EXECUTABLE: the full path to the msgfmt tool.
9316 GETTEXT_FOUND: True if gettext has been found.
9317 GETTEXT_VERSION_STRING: the version of gettext found (since CMake 2.8.8)
9318 Additionally it provides the following macros:
9320 GETTEXT_CREATE_TRANSLATIONS ( outputFile [ALL] file1 … fileN )
9322 This will create a target "translations" which will convert the
9324 given input po files into the binary output mo file. If the
9325 ALL option is used, the translations will also be created when
9326 building the default target.
9327 GETTEXT_PROCESS_POT_FILE( <potfile> [ALL] [INSTALL_DESTINATION <dest‐
9329 dir>] LANGUAGES <lang1> <lang2> … )
9330 Process the given pot file to mo files.
9332 If INSTALL_DESTINATION is given then automatically install rules will
9333 be created, the language subdirectory will be taken into account
9334 (by default use share/locale/).
9335 If ALL is specified, the pot file is processed when building the all traget.
9336 It creates a custom target "potfile".
9337 GETTEXT_PROCESS_PO_FILES( <lang> [ALL] [INSTALL_DESTINATION <dir>]
9339 PO_FILES <po1> <po2> … )
9340 Process the given po files to mo files for the given language.
9342 If INSTALL_DESTINATION is given then automatically install rules will
9343 be created, the language subdirectory will be taken into account
9344 (by default use share/locale/).
9345 If ALL is specified, the po files are processed when building the all traget.
9346 It creates a custom target "pofiles".
9347 NOTE:
9349 If you wish to use the Gettext library (libintl), use FindIntl.
9350 FindGIF
9352 This finds the Graphics Interchange Format (GIF) library (giflib)
9353 Imported targets
9355 This module defines the following IMPORTED target:
9356 GIF::GIF
9358 The giflib library, if found.
9359 Result variables
9361 This module will set the following variables in your project:
9362 GIF_FOUND
9364 If false, do not try to use GIF.
9365 GIF_INCLUDE_DIRS
9367 where to find gif_lib.h, etc.
9368 GIF_LIBRARIES
9370 the libraries needed to use GIF.
9371 GIF_VERSION
9373 3, 4 or a full version string (eg 5.1.4) for versions >= 4.1.6.
9374 Cache variables
9376 The following cache variables may also be set:
9377 GIF_INCLUDE_DIR
9379 where to find the GIF headers.
9380 GIF_LIBRARY
9382 where to find the GIF library.
9383 Hints
9385 GIF_DIR is an environment variable that would correspond to the ./con‐
9386 figure --prefix=$GIF_DIR.
9387 FindGit
9389 The module defines the following IMPORTED targets (when CMAKE_ROLE is
9390 PROJECT):
9391 Git::Git
9393 Executable of the Git command-line client.
9394 The module defines the following variables:
9396 GIT_EXECUTABLE
9398 Path to Git command-line client.
9399 Git_FOUND, GIT_FOUND
9401 True if the Git command-line client was found.
9402 GIT_VERSION_STRING
9404 The version of Git found.
9405 Example usage:
9407 find_package(Git)
9409 if(Git_FOUND)
9410 message("Git found: ${GIT_EXECUTABLE}")
9411 endif()
9412 FindGLEW
9414 Find the OpenGL Extension Wrangler Library (GLEW)
9415 Input Variables
9417 The following variables may be set to influence this module’s behavior:
9418 GLEW_USE_STATIC_LIBS
9420 to find and create IMPORTED target for static linkage.
9421 GLEW_VERBOSE
9423 to output a detailed log of this module.
9424 Imported Targets
9426 This module defines the following Imported Targets:
9427 GLEW::glew
9429 The GLEW shared library.
9430 GLEW::glew_s
9432 The GLEW static library, if GLEW_USE_STATIC_LIBS is set to TRUE.
9433 GLEW::GLEW
9435 Duplicates either GLEW::glew or GLEW::glew_s based on availabil‐
9436 ity.
9437 Result Variables
9439 This module defines the following variables:
9440 GLEW_INCLUDE_DIRS
9442 include directories for GLEW
9443 GLEW_LIBRARIES
9445 libraries to link against GLEW
9446 GLEW_SHARED_LIBRARIES
9448 libraries to link against shared GLEW
9449 GLEW_STATIC_LIBRARIES
9451 libraries to link against static GLEW
9452 GLEW_FOUND
9454 true if GLEW has been found and can be used
9455 GLEW_VERSION
9457 GLEW version
9458 GLEW_VERSION_MAJOR
9460 GLEW major version
9461 GLEW_VERSION_MINOR
9463 GLEW minor version
9464 GLEW_VERSION_MICRO
9466 GLEW micro version
9467 FindGLUT
9469 Find OpenGL Utility Toolkit (GLUT) library and include files.
9470 IMPORTED Targets
9472 This module defines the IMPORTED targets:
9473 GLUT::GLUT
9475 Defined if the system has GLUT.
9476 Result Variables
9478 This module sets the following variables:
9479 GLUT_INCLUDE_DIR, where to find GL/glut.h, etc.
9481 GLUT_LIBRARIES, the libraries to link against
9482 GLUT_FOUND, If false, do not try to use GLUT.
9483 Also defined, but not for general use are:
9485 GLUT_glut_LIBRARY = the full path to the glut library.
9487 GLUT_Xmu_LIBRARY = the full path to the Xmu library.
9488 GLUT_Xi_LIBRARY = the full path to the Xi Library.
9489 FindGnuplot
9491 this module looks for gnuplot
9492 Once done this will define
9494 GNUPLOT_FOUND - system has Gnuplot
9496 GNUPLOT_EXECUTABLE - the Gnuplot executable
9497 GNUPLOT_VERSION_STRING - the version of Gnuplot found (since CMake 2.8.8)
9498 GNUPLOT_VERSION_STRING will not work for old versions like 3.7.1.
9500 FindGnuTLS
9502 Find the GNU Transport Layer Security library (gnutls)
9503 IMPORTED Targets
9505 This module defines IMPORTED target GnuTLS::GnuTLS, if gnutls has been
9506 found.
9507 Result Variables
9509 GNUTLS_FOUND
9510 System has gnutls
9511 GNUTLS_INCLUDE_DIR
9513 The gnutls include directory
9514 GNUTLS_LIBRARIES
9516 The libraries needed to use gnutls
9517 GNUTLS_DEFINITIONS
9519 Compiler switches required for using gnutls
9520 GNUTLS_VERSION
9522 version of gnutls.
9523 FindGSL
9525 Find the native GNU Scientific Library (GSL) includes and libraries.
9526 The GNU Scientific Library (GSL) is a numerical library for C and C++
9528 programmers. It is free software under the GNU General Public License.
9529 Imported Targets
9531 If GSL is found, this module defines the following IMPORTED targets:
9532 GSL::gsl - The main GSL library.
9534 GSL::gslcblas - The CBLAS support library used by GSL.
9535 Result Variables
9537 This module will set the following variables in your project:
9538 GSL_FOUND - True if GSL found on the local system
9540 GSL_INCLUDE_DIRS - Location of GSL header files.
9541 GSL_LIBRARIES - The GSL libraries.
9542 GSL_VERSION - The version of the discovered GSL install.
9543 Hints
9545 Set GSL_ROOT_DIR to a directory that contains a GSL installation.
9546 This script expects to find libraries at $GSL_ROOT_DIR/lib and the GSL
9548 headers at $GSL_ROOT_DIR/include/gsl. The library directory may
9549 optionally provide Release and Debug folders. If available, the
9550 libraries named gsld, gslblasd or cblasd are recognized as debug
9551 libraries. For Unix-like systems, this script will use
9552 $GSL_ROOT_DIR/bin/gsl-config (if found) to aid in the discovery of GSL.
9553 Cache Variables
9555 This module may set the following variables depending on platform and
9556 type of GSL installation discovered. These variables may optionally be
9557 set to help this module find the correct files:
9558 GSL_CBLAS_LIBRARY - Location of the GSL CBLAS library.
9560 GSL_CBLAS_LIBRARY_DEBUG - Location of the debug GSL CBLAS library (if any).
9561 GSL_CONFIG_EXECUTABLE - Location of the ``gsl-config`` script (if any).
9562 GSL_LIBRARY - Location of the GSL library.
9563 GSL_LIBRARY_DEBUG - Location of the debug GSL library (if any).
9564 FindGTest
9566 Locate the Google C++ Testing Framework.
9567 Imported targets
9569 This module defines the following IMPORTED targets:
9570 GTest::GTest
9572 The Google Test gtest library, if found; adds Thread::Thread
9573 automatically
9574 GTest::Main
9576 The Google Test gtest_main library, if found
9577 Result variables
9579 This module will set the following variables in your project:
9580 GTEST_FOUND
9582 Found the Google Testing framework
9583 GTEST_INCLUDE_DIRS
9585 the directory containing the Google Test headers
9586 The library variables below are set as normal variables. These contain
9588 debug/optimized keywords when a debugging library is found.
9589 GTEST_LIBRARIES
9591 The Google Test gtest library; note it also requires linking
9592 with an appropriate thread library
9593 GTEST_MAIN_LIBRARIES
9595 The Google Test gtest_main library
9596 GTEST_BOTH_LIBRARIES
9598 Both gtest and gtest_main
9599 Cache variables
9601 The following cache variables may also be set:
9602 GTEST_ROOT
9604 The root directory of the Google Test installation (may also be
9605 set as an environment variable)
9606 GTEST_MSVC_SEARCH
9608 If compiling with MSVC, this variable can be set to MT or MD
9609 (the default) to enable searching a GTest build tree
9610 Example usage
9612 enable_testing()
9613 find_package(GTest REQUIRED)
9614 add_executable(foo foo.cc)
9616 target_link_libraries(foo GTest::GTest GTest::Main)
9617 add_test(AllTestsInFoo foo)
9619 Deeper integration with CTest
9621 See GoogleTest for information on the gtest_add_tests() and gtest_dis‐
9622 cover_tests() commands.
9623 FindGTK2
9625 Find the GTK2 widget libraries and several of its other optional compo‐
9626 nents like gtkmm, glade, and glademm.
9627 NOTE: If you intend to use version checking, CMake 2.6.2 or later is
9629 required.
9631 Specify one or more of the following components as you call this find
9633 module. See example below.
9634 gtk
9636 gtkmm
9637 glade
9638 glademm
9639 The following variables will be defined for your use
9641 GTK2_FOUND - Were all of your specified components found?
9643 GTK2_INCLUDE_DIRS - All include directories
9644 GTK2_LIBRARIES - All libraries
9645 GTK2_TARGETS - All imported targets
9646 GTK2_DEFINITIONS - Additional compiler flags
9647 GTK2_VERSION - The version of GTK2 found (x.y.z)
9649 GTK2_MAJOR_VERSION - The major version of GTK2
9650 GTK2_MINOR_VERSION - The minor version of GTK2
9651 GTK2_PATCH_VERSION - The patch version of GTK2
9652 Optional variables you can define prior to calling this module:
9654 GTK2_DEBUG - Enables verbose debugging of the module
9656 GTK2_ADDITIONAL_SUFFIXES - Allows defining additional directories to
9657 search for include files
9658 ================= Example Usage:
9660 Call find_package() once, here are some examples to pick from:
9662 Require GTK 2.6 or later
9664 find_package(GTK2 2.6 REQUIRED gtk)
9665 Require GTK 2.10 or later and Glade
9667 find_package(GTK2 2.10 REQUIRED gtk glade)
9668 Search for GTK/GTKMM 2.8 or later
9670 find_package(GTK2 2.8 COMPONENTS gtk gtkmm)
9671 if(GTK2_FOUND)
9673 include_directories(${GTK2_INCLUDE_DIRS})
9674 add_executable(mygui mygui.cc)
9675 target_link_libraries(mygui ${GTK2_LIBRARIES})
9676 endif()
9677 FindGTK
9679 Find GTK, glib and GTKGLArea
9680 GTK_INCLUDE_DIR - Directories to include to use GTK
9682 GTK_LIBRARIES - Files to link against to use GTK
9683 GTK_FOUND - GTK was found
9684 GTK_GL_FOUND - GTK's GL features were found
9685 FindHDF5
9687 Find Hierarchical Data Format (HDF5), a library for reading and writing
9688 self describing array data.
9689 This module invokes the HDF5 wrapper compiler that should be installed
9691 alongside HDF5. Depending upon the HDF5 Configuration, the wrapper
9692 compiler is called either h5cc or h5pcc. If this succeeds, the module
9693 will then call the compiler with the show argument to see what flags
9694 are used when compiling an HDF5 client application.
9695 The module will optionally accept the COMPONENTS argument. If no COM‐
9697 PONENTS are specified, then the find module will default to finding
9698 only the HDF5 C library. If one or more COMPONENTS are specified, the
9699 module will attempt to find the language bindings for the specified
9700 components. The only valid components are C, CXX, Fortran, HL, and
9701 Fortran_HL. If the COMPONENTS argument is not given, the module will
9702 attempt to find only the C bindings.
9703 This module will read the variable HDF5_USE_STATIC_LIBRARIES to deter‐
9705 mine whether or not to prefer a static link to a dynamic link for HDF5
9706 and all of it’s dependencies. To use this feature, make sure that the
9707 HDF5_USE_STATIC_LIBRARIES variable is set before the call to find_pack‐
9708 age.
9709 To provide the module with a hint about where to find your HDF5 instal‐
9711 lation, you can set the environment variable HDF5_ROOT. The Find mod‐
9712 ule will then look in this path when searching for HDF5 executables,
9713 paths, and libraries.
9714 Both the serial and parallel HDF5 wrappers are considered and the first
9716 directory to contain either one will be used. In the event that both
9717 appear in the same directory the serial version is preferentially
9718 selected. This behavior can be reversed by setting the variable
9719 HDF5_PREFER_PARALLEL to True.
9720 In addition to finding the includes and libraries required to compile
9722 an HDF5 client application, this module also makes an effort to find
9723 tools that come with the HDF5 distribution that may be useful for
9724 regression testing.
9725 Result Variables
9727 This module will set the following variables in your project:
9728 HDF5_FOUND
9730 HDF5 was found on the system
9731 HDF5_VERSION
9733 HDF5 library version
9734 HDF5_INCLUDE_DIRS
9736 Location of the HDF5 header files
9737 HDF5_DEFINITIONS
9739 Required compiler definitions for HDF5
9740 HDF5_LIBRARIES
9742 Required libraries for all requested bindings
9743 HDF5_HL_LIBRARIES
9745 Required libraries for the HDF5 high level API for all bindings,
9746 if the HL component is enabled
9747 Available components are: C CXX Fortran and HL. For each enabled lan‐
9749 guage binding, a corresponding HDF5_${LANG}_LIBRARIES variable, and
9750 potentially HDF5_${LANG}_DEFINITIONS, will be defined. If the HL com‐
9751 ponent is enabled, then an HDF5_${LANG}_HL_LIBRARIES will also be
9752 defined. With all components enabled, the following variables will be
9753 defined:
9754 HDF5_C_DEFINITIONS
9756 Required compiler definitions for HDF5 C bindings
9757 HDF5_CXX_DEFINITIONS
9759 Required compiler definitions for HDF5 C++ bindings
9760 HDF5_Fortran_DEFINITIONS
9762 Required compiler definitions for HDF5 Fortran bindings
9763 HDF5_C_INCLUDE_DIRS
9765 Required include directories for HDF5 C bindings
9766 HDF5_CXX_INCLUDE_DIRS
9768 Required include directories for HDF5 C++ bindings
9769 HDF5_Fortran_INCLUDE_DIRS
9771 Required include directories for HDF5 Fortran bindings
9772 HDF5_C_LIBRARIES
9774 Required libraries for the HDF5 C bindings
9775 HDF5_CXX_LIBRARIES
9777 Required libraries for the HDF5 C++ bindings
9778 HDF5_Fortran_LIBRARIES
9780 Required libraries for the HDF5 Fortran bindings
9781 HDF5_C_HL_LIBRARIES
9783 Required libraries for the high level C bindings
9784 HDF5_CXX_HL_LIBRARIES
9786 Required libraries for the high level C++ bindings
9787 HDF5_Fortran_HL_LIBRARIES
9789 Required libraries for the high level Fortran bindings.
9790 HDF5_IS_PARALLEL
9792 HDF5 library has parallel IO support
9793 HDF5_C_COMPILER_EXECUTABLE
9795 path to the HDF5 C wrapper compiler
9796 HDF5_CXX_COMPILER_EXECUTABLE
9798 path to the HDF5 C++ wrapper compiler
9799 HDF5_Fortran_COMPILER_EXECUTABLE
9801 path to the HDF5 Fortran wrapper compiler
9802 HDF5_C_COMPILER_EXECUTABLE_NO_INTERROGATE
9804 path to the primary C compiler which is also the HDF5 wrapper
9805 HDF5_CXX_COMPILER_EXECUTABLE_NO_INTERROGATE
9807 path to the primary C++ compiler which is also the HDF5 wrapper
9808 HDF5_Fortran_COMPILER_EXECUTABLE_NO_INTERROGATE
9810 path to the primary Fortran compiler which is also the HDF5
9811 wrapper
9812 HDF5_DIFF_EXECUTABLE
9814 path to the HDF5 dataset comparison tool
9815 Hints
9817 The following variable can be set to guide the search for HDF5
9818 libraries and includes:
9819 HDF5_ROOT
9821 Specify the path to the HDF5 installation to use.
9822 HDF5_FIND_DEBUG
9824 Set true to get extra debugging output.
9825 HDF5_NO_FIND_PACKAGE_CONFIG_FILE
9827 Set true to skip trying to find hdf5-config.cmake.
9828 FindHg
9830 Extract information from a mercurial working copy.
9831 The module defines the following variables:
9833 HG_EXECUTABLE - path to mercurial command line client (hg)
9835 HG_FOUND - true if the command line client was found
9836 HG_VERSION_STRING - the version of mercurial found
9837 If the command line client executable is found the following macro is
9839 defined:
9840 HG_WC_INFO(<dir> <var-prefix>)
9842 Hg_WC_INFO extracts information of a mercurial working copy at a given
9844 location. This macro defines the following variables:
9845 <var-prefix>_WC_CHANGESET - current changeset
9847 <var-prefix>_WC_REVISION - current revision
9848 Example usage:
9850 find_package(Hg)
9852 if(HG_FOUND)
9853 message("hg found: ${HG_EXECUTABLE}")
9854 HG_WC_INFO(${PROJECT_SOURCE_DIR} Project)
9855 message("Current revision is ${Project_WC_REVISION}")
9856 message("Current changeset is ${Project_WC_CHANGESET}")
9857 endif()
9858 FindHSPELL
9860 Try to find Hebrew spell-checker (Hspell) and morphology engine.
9861 Once done this will define
9863 HSPELL_FOUND - system has Hspell
9865 HSPELL_INCLUDE_DIR - the Hspell include directory
9866 HSPELL_LIBRARIES - The libraries needed to use Hspell
9867 HSPELL_DEFINITIONS - Compiler switches required for using Hspell
9868 HSPELL_VERSION_STRING - The version of Hspell found (x.y)
9870 HSPELL_MAJOR_VERSION - the major version of Hspell
9871 HSPELL_MINOR_VERSION - The minor version of Hspell
9872 FindHTMLHelp
9874 This module looks for Microsoft HTML Help Compiler
9875 It defines:
9877 HTML_HELP_COMPILER : full path to the Compiler (hhc.exe)
9879 HTML_HELP_INCLUDE_PATH : include path to the API (htmlhelp.h)
9880 HTML_HELP_LIBRARY : full path to the library (htmlhelp.lib)
9881 FindIce
9883 Find the ZeroC Internet Communication Engine (ICE) programs, libraries
9884 and datafiles.
9885 This module supports multiple components. Components can include any
9887 of: Freeze, Glacier2, Ice, IceBox, IceDB, IceDiscovery, IceGrid, IceLo‐
9888 catorDiscovery, IcePatch, IceSSL, IceStorm, IceUtil, IceXML, or Slice.
9889 Ice 3.7 and later also include C++11-specific components: Glacier2++11,
9891 Ice++11, IceBox++11, IceDiscovery++11 IceGrid, IceLocatorDiscovery++11,
9892 IceSSL++11, IceStorm++11
9893 Note that the set of supported components is Ice version-specific.
9895 This module reports information about the Ice installation in several
9897 variables. General variables:
9898 Ice_VERSION - Ice release version
9900 Ice_FOUND - true if the main programs and libraries were found
9901 Ice_LIBRARIES - component libraries to be linked
9902 Ice_INCLUDE_DIRS - the directories containing the Ice headers
9903 Ice_SLICE_DIRS - the directories containing the Ice slice interface
9904 definitions
9905 Imported targets:
9907 Ice::<C>
9909 Where <C> is the name of an Ice component, for example Ice::Glacier2 or
9911 Ice++11.
9912 Ice slice programs are reported in:
9914 Ice_SLICE2CONFLUENCE_EXECUTABLE - path to slice2confluence executable
9916 Ice_SLICE2CPP_EXECUTABLE - path to slice2cpp executable
9917 Ice_SLICE2CS_EXECUTABLE - path to slice2cs executable
9918 Ice_SLICE2FREEZEJ_EXECUTABLE - path to slice2freezej executable
9919 Ice_SLICE2FREEZE_EXECUTABLE - path to slice2freeze executable
9920 Ice_SLICE2HTML_EXECUTABLE - path to slice2html executable
9921 Ice_SLICE2JAVA_EXECUTABLE - path to slice2java executable
9922 Ice_SLICE2JS_EXECUTABLE - path to slice2js executable
9923 Ice_SLICE2MATLAB_EXECUTABLE - path to slice2matlab executable
9924 Ice_SLICE2OBJC_EXECUTABLE - path to slice2objc executable
9925 Ice_SLICE2PHP_EXECUTABLE - path to slice2php executable
9926 Ice_SLICE2PY_EXECUTABLE - path to slice2py executable
9927 Ice_SLICE2RB_EXECUTABLE - path to slice2rb executable
9928 Ice programs are reported in:
9930 Ice_GLACIER2ROUTER_EXECUTABLE - path to glacier2router executable
9932 Ice_ICEBOX_EXECUTABLE - path to icebox executable
9933 Ice_ICEBOXXX11_EXECUTABLE - path to icebox++11 executable
9934 Ice_ICEBOXADMIN_EXECUTABLE - path to iceboxadmin executable
9935 Ice_ICEBOXD_EXECUTABLE - path to iceboxd executable
9936 Ice_ICEBOXNET_EXECUTABLE - path to iceboxnet executable
9937 Ice_ICEBRIDGE_EXECUTABLE - path to icebridge executable
9938 Ice_ICEGRIDADMIN_EXECUTABLE - path to icegridadmin executable
9939 Ice_ICEGRIDDB_EXECUTABLE - path to icegriddb executable
9940 Ice_ICEGRIDNODE_EXECUTABLE - path to icegridnode executable
9941 Ice_ICEGRIDNODED_EXECUTABLE - path to icegridnoded executable
9942 Ice_ICEGRIDREGISTRY_EXECUTABLE - path to icegridregistry executable
9943 Ice_ICEGRIDREGISTRYD_EXECUTABLE - path to icegridregistryd executable
9944 Ice_ICEPATCH2CALC_EXECUTABLE - path to icepatch2calc executable
9945 Ice_ICEPATCH2CLIENT_EXECUTABLE - path to icepatch2client executable
9946 Ice_ICEPATCH2SERVER_EXECUTABLE - path to icepatch2server executable
9947 Ice_ICESERVICEINSTALL_EXECUTABLE - path to iceserviceinstall executable
9948 Ice_ICESTORMADMIN_EXECUTABLE - path to icestormadmin executable
9949 Ice_ICESTORMDB_EXECUTABLE - path to icestormdb executable
9950 Ice_ICESTORMMIGRATE_EXECUTABLE - path to icestormmigrate executable
9951 Ice db programs (Windows only; standard system versions on all other
9953 platforms) are reported in:
9954 Ice_DB_ARCHIVE_EXECUTABLE - path to db_archive executable
9956 Ice_DB_CHECKPOINT_EXECUTABLE - path to db_checkpoint executable
9957 Ice_DB_DEADLOCK_EXECUTABLE - path to db_deadlock executable
9958 Ice_DB_DUMP_EXECUTABLE - path to db_dump executable
9959 Ice_DB_HOTBACKUP_EXECUTABLE - path to db_hotbackup executable
9960 Ice_DB_LOAD_EXECUTABLE - path to db_load executable
9961 Ice_DB_LOG_VERIFY_EXECUTABLE - path to db_log_verify executable
9962 Ice_DB_PRINTLOG_EXECUTABLE - path to db_printlog executable
9963 Ice_DB_RECOVER_EXECUTABLE - path to db_recover executable
9964 Ice_DB_STAT_EXECUTABLE - path to db_stat executable
9965 Ice_DB_TUNER_EXECUTABLE - path to db_tuner executable
9966 Ice_DB_UPGRADE_EXECUTABLE - path to db_upgrade executable
9967 Ice_DB_VERIFY_EXECUTABLE - path to db_verify executable
9968 Ice_DUMPDB_EXECUTABLE - path to dumpdb executable
9969 Ice_TRANSFORMDB_EXECUTABLE - path to transformdb executable
9970 Ice component libraries are reported in:
9972 Ice_<C>_FOUND - ON if component was found
9974 Ice_<C>_LIBRARIES - libraries for component
9975 Note that <C> is the uppercased name of the component.
9977 This module reads hints about search results from:
9979 Ice_HOME - the root of the Ice installation
9981 The environment variable ICE_HOME may also be used; the Ice_HOME vari‐
9983 able takes precedence.
9984 NOTE:
9986 On Windows, Ice 3.7.0 and later provide libraries via the NuGet
9987 package manager. Appropriate NuGet packages will be searched for
9988 using CMAKE_PREFIX_PATH, or alternatively Ice_HOME may be set to the
9989 location of a specific NuGet package to restrict the search.
9990 The following cache variables may also be set:
9992 Ice_<P>_EXECUTABLE - the path to executable <P>
9994 Ice_INCLUDE_DIR - the directory containing the Ice headers
9995 Ice_SLICE_DIR - the directory containing the Ice slice interface
9996 definitions
9997 Ice_<C>_LIBRARY - the library for component <C>
9998 NOTE:
10000 In most cases none of the above variables will require setting,
10001 unless multiple Ice versions are available and a specific version is
10002 required. On Windows, the most recent version of Ice will be found
10003 through the registry. On Unix, the programs, headers and libraries
10004 will usually be in standard locations, but Ice_SLICE_DIRS might not
10005 be automatically detected (commonly known locations are searched).
10006 All the other variables are defaulted using Ice_HOME, if set. It’s
10007 possible to set Ice_HOME and selectively specify alternative loca‐
10008 tions for the other components; this might be required for e.g.
10009 newer versions of Visual Studio if the heuristics are not sufficient
10010 to identify the correct programs and libraries for the specific Vis‐
10011 ual Studio version.
10012 Other variables one may set to control this module are:
10014 Ice_DEBUG - Set to ON to enable debug output from FindIce.
10016 FindIcotool
10018 Find icotool
10019 This module looks for icotool. Convert and create Win32 icon and cursor
10021 files. This module defines the following values:
10022 ICOTOOL_EXECUTABLE: the full path to the icotool tool.
10024 ICOTOOL_FOUND: True if icotool has been found.
10025 ICOTOOL_VERSION_STRING: the version of icotool found.
10026 FindICU
10028 Find the International Components for Unicode (ICU) libraries and pro‐
10029 grams.
10030 This module supports multiple components. Components can include any
10032 of: data, i18n, io, le, lx, test, tu and uc.
10033 Note that on Windows data is named dt and i18n is named in; any of the
10035 names may be used, and the appropriate platform-specific library name
10036 will be automatically selected.
10037 This module reports information about the ICU installation in several
10039 variables. General variables:
10040 ICU_VERSION - ICU release version
10042 ICU_FOUND - true if the main programs and libraries were found
10043 ICU_LIBRARIES - component libraries to be linked
10044 ICU_INCLUDE_DIRS - the directories containing the ICU headers
10045 Imported targets:
10047 ICU::<C>
10049 Where <C> is the name of an ICU component, for example ICU::i18n.
10051 ICU programs are reported in:
10053 ICU_GENCNVAL_EXECUTABLE - path to gencnval executable
10055 ICU_ICUINFO_EXECUTABLE - path to icuinfo executable
10056 ICU_GENBRK_EXECUTABLE - path to genbrk executable
10057 ICU_ICU-CONFIG_EXECUTABLE - path to icu-config executable
10058 ICU_GENRB_EXECUTABLE - path to genrb executable
10059 ICU_GENDICT_EXECUTABLE - path to gendict executable
10060 ICU_DERB_EXECUTABLE - path to derb executable
10061 ICU_PKGDATA_EXECUTABLE - path to pkgdata executable
10062 ICU_UCONV_EXECUTABLE - path to uconv executable
10063 ICU_GENCFU_EXECUTABLE - path to gencfu executable
10064 ICU_MAKECONV_EXECUTABLE - path to makeconv executable
10065 ICU_GENNORM2_EXECUTABLE - path to gennorm2 executable
10066 ICU_GENCCODE_EXECUTABLE - path to genccode executable
10067 ICU_GENSPREP_EXECUTABLE - path to gensprep executable
10068 ICU_ICUPKG_EXECUTABLE - path to icupkg executable
10069 ICU_GENCMN_EXECUTABLE - path to gencmn executable
10070 ICU component libraries are reported in:
10072 ICU_<C>_FOUND - ON if component was found
10074 ICU_<C>_LIBRARIES - libraries for component
10075 ICU datafiles are reported in:
10077 ICU_MAKEFILE_INC - Makefile.inc
10079 ICU_PKGDATA_INC - pkgdata.inc
10080 Note that <C> is the uppercased name of the component.
10082 This module reads hints about search results from:
10084 ICU_ROOT - the root of the ICU installation
10086 The environment variable ICU_ROOT may also be used; the ICU_ROOT vari‐
10088 able takes precedence.
10089 The following cache variables may also be set:
10091 ICU_<P>_EXECUTABLE - the path to executable <P>
10093 ICU_INCLUDE_DIR - the directory containing the ICU headers
10094 ICU_<C>_LIBRARY - the library for component <C>
10095 NOTE:
10097 In most cases none of the above variables will require setting,
10098 unless multiple ICU versions are available and a specific version is
10099 required.
10100 Other variables one may set to control this module are:
10102 ICU_DEBUG - Set to ON to enable debug output from FindICU.
10104 FindImageMagick
10106 Find ImageMagick binary suite.
10107 This module will search for a set of ImageMagick tools specified as
10109 components in the find_package() call. Typical components include, but
10110 are not limited to (future versions of ImageMagick might have addi‐
10111 tional components not listed here):
10112 animate
10114 compare
10115 composite
10116 conjure
10117 convert
10118 display
10119 identify
10120 import
10121 mogrify
10122 montage
10123 stream
10124 If no component is specified in the find_package() call, then it only
10126 searches for the ImageMagick executable directory. This code defines
10127 the following variables:
10128 ImageMagick_FOUND - TRUE if all components are found.
10130 ImageMagick_EXECUTABLE_DIR - Full path to executables directory.
10131 ImageMagick_<component>_FOUND - TRUE if <component> is found.
10132 ImageMagick_<component>_EXECUTABLE - Full path to <component> executable.
10133 ImageMagick_VERSION_STRING - the version of ImageMagick found
10134 (since CMake 2.8.8)
10135 ImageMagick_VERSION_STRING will not work for old versions like 5.2.3.
10137 There are also components for the following ImageMagick APIs:
10139 Magick++
10141 MagickWand
10142 MagickCore
10143 For these components the following variables are set:
10145 ImageMagick_FOUND - TRUE if all components are found.
10147 ImageMagick_INCLUDE_DIRS - Full paths to all include dirs.
10148 ImageMagick_LIBRARIES - Full paths to all libraries.
10149 ImageMagick_<component>_FOUND - TRUE if <component> is found.
10150 ImageMagick_<component>_INCLUDE_DIRS - Full path to <component> include dirs.
10151 ImageMagick_<component>_LIBRARIES - Full path to <component> libraries.
10152 Example Usages:
10154 find_package(ImageMagick)
10156 find_package(ImageMagick COMPONENTS convert)
10157 find_package(ImageMagick COMPONENTS convert mogrify display)
10158 find_package(ImageMagick COMPONENTS Magick++)
10159 find_package(ImageMagick COMPONENTS Magick++ convert)
10160 Note that the standard find_package() features are supported (i.e.,
10162 QUIET, REQUIRED, etc.).
10163 FindIconv
10165 This module finds the iconv() POSIX.1 functions on the system. These
10166 functions might be provided in the regular C library or externally in
10167 the form of an additional library.
10168 The following variables are provided to indicate iconv support:
10170 Iconv_FOUND
10172 Variable indicating if the iconv support was found.
10173 Iconv_INCLUDE_DIRS
10175 The directories containing the iconv headers.
10176 Iconv_LIBRARIES
10178 The iconv libraries to be linked.
10179 Iconv_IS_BUILT_IN
10181 A variable indicating whether iconv support is stemming from the
10182 C library or not. Even if the C library provides iconv(), the
10183 presence of an external libiconv implementation might lead to
10184 this being false.
10185 Additionally, the following IMPORTED target is being provided:
10187 Iconv::Iconv
10189 Imported target for using iconv.
10190 The following cache variables may also be set:
10192 Iconv_INCLUDE_DIR
10194 The directory containing the iconv headers.
10195 Iconv_LIBRARY
10197 The iconv library (if not implicitly given in the C library).
10198 NOTE:
10200 On POSIX platforms, iconv might be part of the C library and the
10201 cache variables Iconv_INCLUDE_DIR and Iconv_LIBRARY might be empty.
10202 FindIntl
10204 Find the Gettext libintl headers and libraries.
10205 This module reports information about the Gettext libintl installation
10207 in several variables. General variables:
10208 Intl_FOUND - true if the libintl headers and libraries were found
10210 Intl_INCLUDE_DIRS - the directory containing the libintl headers
10211 Intl_LIBRARIES - libintl libraries to be linked
10212 The following cache variables may also be set:
10214 Intl_INCLUDE_DIR - the directory containing the libintl headers
10216 Intl_LIBRARY - the libintl library (if any)
10217 NOTE:
10219 On some platforms, such as Linux with GNU libc, the gettext func‐
10220 tions are present in the C standard library and libintl is not
10221 required. Intl_LIBRARIES will be empty in this case.
10222 NOTE:
10224 If you wish to use the Gettext tools (msgmerge, msgfmt, etc.), use
10225 FindGettext.
10226 FindITK
10228 This module no longer exists.
10229 This module existed in versions of CMake prior to 3.1, but became only
10231 a thin wrapper around find_package(ITK NO_MODULE) to provide compati‐
10232 bility for projects using long-outdated conventions. Now find_pack‐
10233 age(ITK) will search for ITKConfig.cmake directly.
10234 FindJasper
10236 Try to find the Jasper JPEG2000 library
10237 Once done this will define
10239 JASPER_FOUND - system has Jasper
10241 JASPER_INCLUDE_DIR - the Jasper include directory
10242 JASPER_LIBRARIES - the libraries needed to use Jasper
10243 JASPER_VERSION_STRING - the version of Jasper found (since CMake 2.8.8)
10244 FindJava
10246 Find Java
10247 This module finds if Java is installed and determines where the include
10249 files and libraries are. The caller may set variable JAVA_HOME to
10250 specify a Java installation prefix explicitly.
10251 See also the FindJNI module to find Java Native Interface (JNI).
10253 Specify one or more of the following components as you call this find
10255 module. See example below.
10256 Runtime = Java Runtime Environment used to execute Java byte-compiled applications
10258 Development = Development tools (java, javac, javah, jar and javadoc), includes Runtime component
10259 IdlJ = Interface Description Language (IDL) to Java compiler
10260 JarSigner = Signer and verifier tool for Java Archive (JAR) files
10261 This module sets the following result variables:
10263 Java_JAVA_EXECUTABLE = the full path to the Java runtime
10265 Java_JAVAC_EXECUTABLE = the full path to the Java compiler
10266 Java_JAVAH_EXECUTABLE = the full path to the Java header generator
10267 Java_JAVADOC_EXECUTABLE = the full path to the Java documentation generator
10268 Java_IDLJ_EXECUTABLE = the full path to the Java idl compiler
10269 Java_JAR_EXECUTABLE = the full path to the Java archiver
10270 Java_JARSIGNER_EXECUTABLE = the full path to the Java jar signer
10271 Java_VERSION_STRING = Version of java found, eg. 1.6.0_12
10272 Java_VERSION_MAJOR = The major version of the package found.
10273 Java_VERSION_MINOR = The minor version of the package found.
10274 Java_VERSION_PATCH = The patch version of the package found.
10275 Java_VERSION_TWEAK = The tweak version of the package found (after '_')
10276 Java_VERSION = This is set to: $major[.$minor[.$patch[.$tweak]]]
10277 The minimum required version of Java can be specified using the
10279 find_package() syntax, e.g.
10280 find_package(Java 1.8)
10282 NOTE: ${Java_VERSION} and ${Java_VERSION_STRING} are not guaranteed to
10284 be identical. For example some java version may return: Java_VER‐
10285 SION_STRING = 1.8.0_17 and Java_VERSION = 1.8.0.17
10286 another example is the Java OEM, with: Java_VERSION_STRING = 1.8.0-oem
10288 and Java_VERSION = 1.8.0
10289 For these components the following variables are set:
10291 Java_FOUND - TRUE if all components are found.
10293 Java_<component>_FOUND - TRUE if <component> is found.
10294 Example Usages:
10296 find_package(Java)
10298 find_package(Java 1.8 REQUIRED)
10299 find_package(Java COMPONENTS Runtime)
10300 find_package(Java COMPONENTS Development)
10301 FindJNI
10303 Find Java Native Interface (JNI) libraries.
10304 JNI enables Java code running in a Java Virtual Machine (JVM) to call
10306 and be called by native applications and libraries written in other
10307 languages such as C, C++.
10308 This module finds if Java is installed and determines where the include
10310 files and libraries are. It also determines what the name of the
10311 library is. The caller may set variable JAVA_HOME to specify a Java
10312 installation prefix explicitly.
10313 Result Variables
10315 This module sets the following result variables:
10316 JNI_INCLUDE_DIRS
10318 the include dirs to use
10319 JNI_LIBRARIES
10321 the libraries to use (JAWT and JVM)
10322 JNI_FOUND
10324 TRUE if JNI headers and libraries were found.
10325 Cache Variables
10327 The following cache variables are also available to set or use:
10328 JAVA_AWT_LIBRARY
10330 the path to the Java AWT Native Interface (JAWT) library
10331 JAVA_JVM_LIBRARY
10333 the path to the Java Virtual Machine (JVM) library
10334 JAVA_INCLUDE_PATH
10336 the include path to jni.h
10337 JAVA_INCLUDE_PATH2
10339 the include path to jni_md.h and jniport.h
10340 JAVA_AWT_INCLUDE_PATH
10342 the include path to jawt.h
10343 FindJPEG
10345 Find the Joint Photographic Experts Group (JPEG) library (libjpeg)
10346 Imported targets
10348 This module defines the following IMPORTED targets:
10349 JPEG::JPEG
10351 The JPEG library, if found.
10352 Result variables
10354 This module will set the following variables in your project:
10355 JPEG_FOUND
10357 If false, do not try to use JPEG.
10358 JPEG_INCLUDE_DIRS
10360 where to find jpeglib.h, etc.
10361 JPEG_LIBRARIES
10363 the libraries needed to use JPEG.
10364 JPEG_VERSION
10366 the version of the JPEG library found
10367 Cache variables
10369 The following cache variables may also be set:
10370 JPEG_INCLUDE_DIRS
10372 where to find jpeglib.h, etc.
10373 JPEG_LIBRARY_RELEASE
10375 where to find the JPEG library (optimized).
10376 JPEG_LIBRARY_DEBUG
10378 where to find the JPEG library (debug).
10379 Obsolete variables
10381 JPEG_INCLUDE_DIR
10382 where to find jpeglib.h, etc. (same as JPEG_INCLUDE_DIRS)
10383 JPEG_LIBRARY
10385 where to find the JPEG library.
10386 FindKDE3
10388 Find the KDE3 include and library dirs, KDE preprocessors and define a
10389 some macros
10390 This module defines the following variables:
10392 KDE3_DEFINITIONS
10394 compiler definitions required for compiling KDE software
10395 KDE3_INCLUDE_DIR
10397 the KDE include directory
10398 KDE3_INCLUDE_DIRS
10400 the KDE and the Qt include directory, for use with
10401 include_directories()
10402 KDE3_LIB_DIR
10404 the directory where the KDE libraries are installed, for use
10405 with link_directories()
10406 QT_AND_KDECORE_LIBS
10408 this contains both the Qt and the kdecore library
10409 KDE3_DCOPIDL_EXECUTABLE
10411 the dcopidl executable
10412 KDE3_DCOPIDL2CPP_EXECUTABLE
10414 the dcopidl2cpp executable
10415 KDE3_KCFGC_EXECUTABLE
10417 the kconfig_compiler executable
10418 KDE3_FOUND
10420 set to TRUE if all of the above has been found
10421 The following user adjustable options are provided:
10423 KDE3_BUILD_TESTS
10425 enable this to build KDE testcases
10426 It also adds the following macros (from KDE3Macros.cmake) SRCS_VAR is
10428 always the variable which contains the list of source files for your
10429 application or library.
10430 KDE3_AUTOMOC(file1 … fileN)
10432 Call this if you want to have automatic moc file handling.
10434 This means if you include "foo.moc" in the source file foo.cpp
10435 a moc file for the header foo.h will be created automatically.
10436 You can set the property SKIP_AUTOMAKE using set_source_files_properties()
10437 to exclude some files in the list from being processed.
10438 KDE3_ADD_MOC_FILES(SRCS_VAR file1 … fileN )
10440 If you don't use the KDE3_AUTOMOC() macro, for the files
10442 listed here moc files will be created (named "foo.moc.cpp")
10443 KDE3_ADD_DCOP_SKELS(SRCS_VAR header1.h … headerN.h )
10445 Use this to generate DCOP skeletions from the listed headers.
10447 KDE3_ADD_DCOP_STUBS(SRCS_VAR header1.h … headerN.h )
10449 Use this to generate DCOP stubs from the listed headers.
10451 KDE3_ADD_UI_FILES(SRCS_VAR file1.ui … fileN.ui )
10453 Use this to add the Qt designer ui files to your application/library.
10455 KDE3_ADD_KCFG_FILES(SRCS_VAR file1.kcfgc … fileN.kcfgc )
10457 Use this to add KDE kconfig compiler files to your application/library.
10459 KDE3_INSTALL_LIBTOOL_FILE(target)
10461 This will create and install a simple libtool file for the given target.
10463 KDE3_ADD_EXECUTABLE(name file1 … fileN )
10465 Currently identical to add_executable(), may provide some advanced
10467 features in the future.
10468 KDE3_ADD_KPART(name [WITH_PREFIX] file1 … fileN )
10470 Create a KDE plugin (KPart, kioslave, etc.) from the given source files.
10472 If WITH_PREFIX is given, the resulting plugin will have the prefix "lib",
10473 otherwise it won't.
10474 It creates and installs an appropriate libtool la-file.
10475 KDE3_ADD_KDEINIT_EXECUTABLE(name file1 … fileN )
10477 Create a KDE application in the form of a module loadable via kdeinit.
10479 A library named kdeinit_<name> will be created and a small executable
10480 which links to it.
10481 The option KDE3_ENABLE_FINAL to enable all-in-one compilation is no
10483 longer supported.
10484 Author: Alexander Neundorf <neundorf@kde.org>
10486 FindKDE4
10488 Find KDE4 and provide all necessary variables and macros to compile
10489 software for it. It looks for KDE 4 in the following directories in
10490 the given order:
10491 CMAKE_INSTALL_PREFIX
10493 KDEDIRS
10494 /opt/kde4
10495 Please look in FindKDE4Internal.cmake and KDE4Macros.cmake for more
10497 information. They are installed with the KDE 4 libraries in
10498 $KDEDIRS/share/apps/cmake/modules/.
10499 Author: Alexander Neundorf <neundorf@kde.org>
10501 FindLAPACK
10503 Find Linear Algebra PACKage (LAPACK) library
10504 This module finds an installed fortran library that implements the
10506 LAPACK linear-algebra interface (see http://www.netlib.org/lapack/).
10507 The approach follows that taken for the autoconf macro file,
10509 acx_lapack.m4 (distributed at
10510 http://ac-archive.sourceforge.net/ac-archive/acx_lapack.html).
10511 Input Variables
10513 The following variables may be set to influence this module’s behavior:
10514 BLA_STATIC
10516 if ON use static linkage
10517 BLA_VENDOR
10519 If set, checks only the specified vendor, if not set checks all
10520 the possibilities. List of vendors valid in this module:
10521 · Intel10_32 (intel mkl v10 32 bit)
10523 · Intel10_64lp (intel mkl v10+ 64 bit, threaded code, lp64
10525 model)
10526 · Intel10_64lp_seq (intel mkl v10+ 64 bit, sequential code, lp64
10528 model)
10529 · Intel10_64ilp (intel mkl v10+ 64 bit, threaded code, ilp64
10531 model)
10532 · Intel10_64ilp_seq (intel mkl v10+ 64 bit, sequential code,
10534 ilp64 model)
10535 · Intel (obsolete versions of mkl 32 and 64 bit)
10537 · OpenBLAS
10539 · FLAME
10541 · ACML
10543 · Apple
10545 · NAS
10547 · Generic
10549 BLA_F95
10551 if ON tries to find BLAS95/LAPACK95
10552 Result Variables
10554 This module defines the following variables:
10555 LAPACK_FOUND
10557 library implementing the LAPACK interface is found
10558 LAPACK_LINKER_FLAGS
10560 uncached list of required linker flags (excluding -l and -L).
10561 LAPACK_LIBRARIES
10563 uncached list of libraries (using full path name) to link
10564 against to use LAPACK
10565 LAPACK95_LIBRARIES
10567 uncached list of libraries (using full path name) to link
10568 against to use LAPACK95
10569 LAPACK95_FOUND
10571 library implementing the LAPACK95 interface is found
10572 NOTE:
10574 C or CXX must be enabled to use Intel MKL
10575 For example, to use Intel MKL libraries and/or Intel compiler:
10577 set(BLA_VENDOR Intel10_64lp)
10579 find_package(LAPACK)
10580 FindLATEX
10582 Find LaTeX
10583 This module finds an installed LaTeX and determines the location of the
10585 compiler. Additionally the module looks for Latex-related software
10586 like BibTeX.
10587 This module sets the following result variables:
10589 LATEX_FOUND: whether found Latex and requested components
10591 LATEX_<component>_FOUND: whether found <component>
10592 LATEX_COMPILER: path to the LaTeX compiler
10593 PDFLATEX_COMPILER: path to the PdfLaTeX compiler
10594 XELATEX_COMPILER: path to the XeLaTeX compiler
10595 LUALATEX_COMPILER: path to the LuaLaTeX compiler
10596 BIBTEX_COMPILER: path to the BibTeX compiler
10597 BIBER_COMPILER: path to the Biber compiler
10598 MAKEINDEX_COMPILER: path to the MakeIndex compiler
10599 XINDY_COMPILER: path to the xindy compiler
10600 DVIPS_CONVERTER: path to the DVIPS converter
10601 DVIPDF_CONVERTER: path to the DVIPDF converter
10602 PS2PDF_CONVERTER: path to the PS2PDF converter
10603 PDFTOPS_CONVERTER: path to the pdftops converter
10604 LATEX2HTML_CONVERTER: path to the LaTeX2Html converter
10605 HTLATEX_COMPILER: path to the htlatex compiler
10606 Possible components are:
10608 PDFLATEX
10610 XELATEX
10611 LUALATEX
10612 BIBTEX
10613 BIBER
10614 MAKEINDEX
10615 XINDY
10616 DVIPS
10617 DVIPDF
10618 PS2PDF
10619 PDFTOPS
10620 LATEX2HTML
10621 HTLATEX
10622 Example Usages:
10624 find_package(LATEX)
10626 find_package(LATEX COMPONENTS PDFLATEX)
10627 find_package(LATEX COMPONENTS BIBTEX PS2PDF)
10628 FindLibArchive
10630 Find libarchive library and headers. Libarchive is multi-format ar‐
10631 chive and compression library.
10632 The module defines the following variables:
10634 LibArchive_FOUND - true if libarchive was found
10636 LibArchive_INCLUDE_DIRS - include search path
10637 LibArchive_LIBRARIES - libraries to link
10638 LibArchive_VERSION - libarchive 3-component version number
10639 FindLibinput
10641 Find libinput headers and library.
10642 Imported Targets
10644 Libinput::Libinput
10645 The libinput library, if found.
10646 Result Variables
10648 This will define the following variables in your project:
10649 Libinput_FOUND
10651 true if (the requested version of) libinput is available.
10652 Libinput_VERSION
10654 the version of libinput.
10655 Libinput_LIBRARIES
10657 the libraries to link against to use libinput.
10658 Libinput_INCLUDE_DIRS
10660 where to find the libinput headers.
10661 Libinput_COMPILE_OPTIONS
10663 this should be passed to target_compile_options(), if the target
10664 is not used for linking
10665 FindLibLZMA
10667 Find LZMA compression algorithm headers and library.
10668 Imported Targets
10670 This module defines IMPORTED target LibLZMA::LibLZMA, if liblzma has
10671 been found.
10672 Result variables
10674 This module will set the following variables in your project:
10675 LIBLZMA_FOUND
10677 True if liblzma headers and library were found.
10678 LIBLZMA_INCLUDE_DIRS
10680 Directory where liblzma headers are located.
10681 LIBLZMA_LIBRARIES
10683 Lzma libraries to link against.
10684 LIBLZMA_HAS_AUTO_DECODER
10686 True if lzma_auto_decoder() is found (required).
10687 LIBLZMA_HAS_EASY_ENCODER
10689 True if lzma_easy_encoder() is found (required).
10690 LIBLZMA_HAS_LZMA_PRESET
10692 True if lzma_lzma_preset() is found (required).
10693 LIBLZMA_VERSION_MAJOR
10695 The major version of lzma
10696 LIBLZMA_VERSION_MINOR
10698 The minor version of lzma
10699 LIBLZMA_VERSION_PATCH
10701 The patch version of lzma
10702 LIBLZMA_VERSION_STRING
10704 version number as a string (ex: “5.0.3”)
10705 FindLibXml2
10707 Find the XML processing library (libxml2).
10708 IMPORTED Targets
10710 This module defines IMPORTED target LibXml2::LibXml2, if libxml2 has
10711 been found.
10712 Result variables
10714 This module will set the following variables in your project:
10715 LibXml2_FOUND
10717 true if libxml2 headers and libraries were found
10718 LIBXML2_INCLUDE_DIR
10720 the directory containing LibXml2 headers
10721 LIBXML2_INCLUDE_DIRS
10723 list of the include directories needed to use LibXml2
10724 LIBXML2_LIBRARIES
10726 LibXml2 libraries to be linked
10727 LIBXML2_DEFINITIONS
10729 the compiler switches required for using LibXml2
10730 LIBXML2_XMLLINT_EXECUTABLE
10732 path to the XML checking tool xmllint coming with LibXml2
10733 LIBXML2_VERSION_STRING
10735 the version of LibXml2 found (since CMake 2.8.8)
10736 Cache variables
10738 The following cache variables may also be set:
10739 LIBXML2_INCLUDE_DIR
10741 the directory containing LibXml2 headers
10742 LIBXML2_LIBRARY
10744 path to the LibXml2 library
10745 FindLibXslt
10747 Find the XSL Transformations, Extensible Stylesheet Language Transfor‐
10748 mations (XSLT) library (LibXslt)
10749 Once done this will define
10751 LIBXSLT_FOUND - system has LibXslt
10753 LIBXSLT_INCLUDE_DIR - the LibXslt include directory
10754 LIBXSLT_LIBRARIES - Link these to LibXslt
10755 LIBXSLT_DEFINITIONS - Compiler switches required for using LibXslt
10756 LIBXSLT_VERSION_STRING - version of LibXslt found (since CMake 2.8.8)
10757 Additionally, the following two variables are set (but not required for
10759 using xslt):
10760 LIBXSLT_EXSLT_LIBRARIES
10762 Link to these if you need to link against the exslt library.
10763 LIBXSLT_XSLTPROC_EXECUTABLE
10765 Contains the full path to the xsltproc executable if found.
10766 FindLTTngUST
10768 Find Linux Trace Toolkit Next Generation (LTTng-UST) library.
10769 Imported target
10771 This module defines the following IMPORTED target:
10772 LTTng::UST
10774 The LTTng-UST library, if found
10775 Result variables
10777 This module sets the following
10778 LTTNGUST_FOUND
10780 TRUE if system has LTTng-UST
10781 LTTNGUST_INCLUDE_DIRS
10783 The LTTng-UST include directories
10784 LTTNGUST_LIBRARIES
10786 The libraries needed to use LTTng-UST
10787 LTTNGUST_VERSION_STRING
10789 The LTTng-UST version
10790 LTTNGUST_HAS_TRACEF
10792 TRUE if the tracef() API is available in the system’s LTTng-UST
10793 LTTNGUST_HAS_TRACELOG
10795 TRUE if the tracelog() API is available in the system’s
10796 LTTng-UST
10797 FindLua50
10799 Locate Lua library. This module defines:
10800 ::
10802 LUA50_FOUND, if false, do not try to link to Lua LUA_LIBRARIES, both
10803 lua and lualib LUA_INCLUDE_DIR, where to find lua.h and lualib.h
10804 (and probably lauxlib.h)
10805 Note that the expected include convention is
10807 #include "lua.h"
10809 and not
10811 #include <lua/lua.h>
10813 This is because, the lua location is not standardized and may exist in
10815 locations other than lua/
10816 FindLua51
10818 Locate Lua library. This module defines:
10819 ::
10821 LUA51_FOUND, if false, do not try to link to Lua LUA_LIBRARIES
10822 LUA_INCLUDE_DIR, where to find lua.h LUA_VERSION_STRING, the version
10823 of Lua found (since CMake 2.8.8)
10824 Note that the expected include convention is
10826 #include "lua.h"
10828 and not
10830 #include <lua/lua.h>
10832 This is because, the lua location is not standardized and may exist in
10834 locations other than lua/
10835 FindLua
10837 Locate Lua library.
10838 This module defines:
10840 ::
10842 LUA_FOUND - if false, do not try to link to Lua
10843 LUA_LIBRARIES - both lua and lualib LUA_INCLUDE_DIR - where
10844 to find lua.h LUA_VERSION_STRING - the version of Lua found LUA_VER‐
10845 SION_MAJOR - the major version of Lua LUA_VERSION_MINOR - the
10846 minor version of Lua LUA_VERSION_PATCH - the patch version of Lua
10847 Note that the expected include convention is
10849 #include "lua.h"
10851 and not
10853 #include <lua/lua.h>
10855 This is because, the lua location is not standardized and may exist in
10857 locations other than lua/
10858 FindMatlab
10860 Finds Matlab or Matlab Compiler Runtime (MCR) and provides Matlab
10861 tools, libraries and compilers to CMake.
10862 This package primary purpose is to find the libraries associated with
10864 Matlab or the MCR in order to be able to build Matlab extensions (mex
10865 files). It can also be used:
10866 · to run specific commands in Matlab in case Matlab is available
10868 · for declaring Matlab unit test
10870 · to retrieve various information from Matlab (mex extensions, versions
10872 and release queries, …)
10873 The module supports the following components:
10875 · ENG_LIBRARY and MAT_LIBRARY: respectively the ENG and MAT libraries
10877 of Matlab
10878 · MAIN_PROGRAM the Matlab binary program. Note that this component is
10880 not available on the MCR version, and will yield an error if the MCR
10881 is found instead of the regular Matlab installation.
10882 · MEX_COMPILER the MEX compiler.
10884 · MCC_COMPILER the MCC compiler, included with the Matlab Compiler
10886 add-on.
10887 · SIMULINK the Simulink environment.
10889 NOTE:
10891 The version given to the find_package() directive is the Matlab ver‐
10892 sion, which should not be confused with the Matlab release name (eg.
10893 R2014). The matlab_get_version_from_release_name() and
10894 matlab_get_release_name_from_version() provide a mapping between the
10895 release name and the version.
10896 The variable Matlab_ROOT_DIR may be specified in order to give the path
10898 of the desired Matlab version. Otherwise, the behaviour is platform
10899 specific:
10900 · Windows: The installed versions of Matlab/MCR are retrieved from the
10902 Windows registry
10903 · OS X: The installed versions of Matlab/MCR are given by the MATLAB
10905 default installation paths in /Application. If no such application is
10906 found, it falls back to the one that might be accessible from the
10907 PATH.
10908 · Unix: The desired Matlab should be accessible from the PATH. This
10910 does not work for MCR installation and Matlab_ROOT_DIR should be
10911 specified on this platform.
10912 Additional information is provided when MATLAB_FIND_DEBUG is set. When
10914 a Matlab/MCR installation is found automatically and the MATLAB_VERSION
10915 is not given, the version is queried from Matlab directly (on Windows
10916 this may pop up a Matlab window) or from the MCR installation.
10917 The mapping of the release names and the version of Matlab is performed
10919 by defining pairs (name, version). The variable
10920 MATLAB_ADDITIONAL_VERSIONS may be provided before the call to the
10921 find_package() in order to handle additional versions.
10922 A Matlab scripts can be added to the set of tests using the
10924 matlab_add_unit_test(). By default, the Matlab unit test framework will
10925 be used (>= 2013a) to run this script, but regular .m files returning
10926 an exit code can be used as well (0 indicating a success).
10927 Module Input Variables
10929 Users or projects may set the following variables to configure the mod‐
10930 ule behaviour:
10931 Matlab_ROOT_DIR
10933 the root of the Matlab installation.
10934 MATLAB_FIND_DEBUG
10936 outputs debug information
10937 MATLAB_ADDITIONAL_VERSIONS
10939 additional versions of Matlab for the automatic retrieval of the
10940 installed versions.
10941 Variables defined by the module
10943 Result variables
10944 Matlab_FOUND
10945 TRUE if the Matlab installation is found, FALSE otherwise. All
10946 variable below are defined if Matlab is found.
10947 Matlab_ROOT_DIR
10949 the final root of the Matlab installation determined by the
10950 FindMatlab module.
10951 Matlab_MAIN_PROGRAM
10953 the Matlab binary program. Available only if the component
10954 MAIN_PROGRAM is given in the find_package() directive.
10955 Matlab_INCLUDE_DIRS
10957 the path of the Matlab libraries headers
10958 Matlab_MEX_LIBRARY
10960 library for mex, always available.
10961 Matlab_MX_LIBRARY
10963 mx library of Matlab (arrays), always available.
10964 Matlab_ENG_LIBRARY
10966 Matlab engine library. Available only if the component
10967 ENG_LIBRARY is requested.
10968 Matlab_MAT_LIBRARY
10970 Matlab matrix library. Available only if the component
10971 MAT_LIBRARY is requested.
10972 Matlab_ENGINE_LIBRARY
10974 Matlab C++ engine library, always available for R2018a and
10975 newer.
10976 Matlab_DATAARRAY_LIBRARY
10978 Matlab C++ data array library, always available for R2018a and
10979 newer.
10980 Matlab_LIBRARIES
10982 the whole set of libraries of Matlab
10983 Matlab_MEX_COMPILER
10985 the mex compiler of Matlab. Currently not used. Available only
10986 if the component MEX_COMPILER is requested.
10987 Matlab_MCC_COMPILER
10989 the mcc compiler of Matlab. Included with the Matlab Compiler
10990 add-on. Available only if the component MCC_COMPILER is
10991 requested.
10992 Cached variables
10994 Matlab_MEX_EXTENSION
10995 the extension of the mex files for the current platform (given
10996 by Matlab).
10997 Matlab_ROOT_DIR
10999 the location of the root of the Matlab installation found. If
11000 this value is changed by the user, the result variables are
11001 recomputed.
11002 Provided macros
11004 matlab_get_version_from_release_name()
11005 returns the version from the release name
11006 matlab_get_release_name_from_version()
11008 returns the release name from the Matlab version
11009 Provided functions
11011 matlab_add_mex()
11012 adds a target compiling a MEX file.
11013 matlab_add_unit_test()
11015 adds a Matlab unit test file as a test to the project.
11016 matlab_extract_all_installed_versions_from_registry()
11018 parses the registry for all Matlab versions. Available on Win‐
11019 dows only. The part of the registry parsed is dependent on the
11020 host processor
11021 matlab_get_all_valid_matlab_roots_from_registry()
11023 returns all the possible Matlab or MCR paths, according to a
11024 previously given list. Only the existing/accessible paths are
11025 kept. This is mainly useful for the searching all possible Mat‐
11026 lab installation.
11027 matlab_get_mex_suffix()
11029 returns the suffix to be used for the mex files (platform/archi‐
11030 tecture dependent)
11031 matlab_get_version_from_matlab_run()
11033 returns the version of Matlab/MCR, given the full directory of
11034 the Matlab/MCR installation path.
11035 Known issues
11037 Symbol clash in a MEX target
11038 By default, every symbols inside a MEX file defined with the
11039 command matlab_add_mex() have hidden visibility, except for the
11040 entry point. This is the default behaviour of the MEX compiler,
11041 which lowers the risk of symbol collision between the libraries
11042 shipped with Matlab, and the libraries to which the MEX file is
11043 linking to. This is also the default on Windows platforms.
11044 However, this is not sufficient in certain case, where for
11046 instance your MEX file is linking against libraries that are
11047 already loaded by Matlab, even if those libraries have different
11048 SONAMES. A possible solution is to hide the symbols of the
11049 libraries to which the MEX target is linking to. This can be
11050 achieved in GNU GCC compilers with the linker option
11051 -Wl,--exclude-libs,ALL.
11052 Tests using GPU resources
11054 in case your MEX file is using the GPU and in order to be able
11055 to run unit tests on this MEX file, the GPU resources should be
11056 properly released by Matlab. A possible solution is to make Mat‐
11057 lab aware of the use of the GPU resources in the session, which
11058 can be performed by a command such as D = gpuDevice() at the
11059 beginning of the test script (or via a fixture).
11060 Reference
11062 Matlab_ROOT_DIR
11063 The root folder of the Matlab installation. If set before the
11064 call to find_package(), the module will look for the components
11065 in that path. If not set, then an automatic search of Matlab
11066 will be performed. If set, it should point to a valid version of
11067 Matlab.
11068 MATLAB_FIND_DEBUG
11070 If set, the lookup of Matlab and the intermediate configuration
11071 steps are outputted to the console.
11072 MATLAB_ADDITIONAL_VERSIONS
11074 If set, specifies additional versions of Matlab that may be
11075 looked for. The variable should be a list of strings, organised
11076 by pairs of release name and versions, such as follows:
11077 set(MATLAB_ADDITIONAL_VERSIONS
11079 "release_name1=corresponding_version1"
11080 "release_name2=corresponding_version2"
11081 ...
11082 )
11083 Example:
11085 set(MATLAB_ADDITIONAL_VERSIONS
11087 "R2013b=8.2"
11088 "R2013a=8.1"
11089 "R2012b=8.0")
11090 The order of entries in this list matters when several versions
11092 of Matlab are installed. The priority is set according to the
11093 ordering in this list.
11094 matlab_get_version_from_release_name
11096 Returns the version of Matlab (17.58) from a release name
11097 (R2017k)
11098 matlab_get_release_name_from_version
11100 Returns the release name (R2017k) from the version of Matlab
11101 (17.58)
11102 matlab_extract_all_installed_versions_from_registry
11104 This function parses the registry and founds the Matlab versions
11105 that are installed. The found versions are returned in mat‐
11106 lab_versions. Set win64 to TRUE if the 64 bit version of Matlab
11107 should be looked for The returned list contains all versions
11108 under HKLM\\SOFTWARE\\Mathworks\\MATLAB and HKLM\\SOFT‐
11109 WARE\\Mathworks\\MATLAB Runtime or an empty list in case an
11110 error occurred (or nothing found).
11111 NOTE:
11113 Only the versions are provided. No check is made over the
11114 existence of the installation referenced in the registry,
11115 matlab_get_all_valid_matlab_roots_from_registry
11117 Populates the Matlab root with valid versions of Matlab or Mat‐
11118 lab Runtime (MCR). The returned matlab_roots is organized in
11119 triplets (type,version_number,matlab_root_path), where type
11120 indicates either MATLAB or MCR.
11121 matlab_get_all_valid_matlab_roots_from_registry(
11123 matlab_versions
11124 matlab_roots)
11125 matlab_versions
11127 the versions of each of the Matlab or MCR installations
11128 matlab_roots
11130 the location of each of the Matlab or MCR installations
11131 matlab_get_mex_suffix
11133 Returns the extension of the mex files (the suffixes). This
11134 function should not be called before the appropriate Matlab root
11135 has been found.
11136 matlab_get_mex_suffix(
11138 matlab_root
11139 mex_suffix)
11140 matlab_root
11142 the root of the Matlab/MCR installation
11143 mex_suffix
11145 the variable name in which the suffix will be returned.
11146 matlab_get_version_from_matlab_run
11148 This function runs Matlab program specified on arguments and
11149 extracts its version. If the path provided for the Matlab
11150 installation points to an MCR installation, the version is
11151 extracted from the installed files.
11152 matlab_get_version_from_matlab_run(
11154 matlab_binary_path
11155 matlab_list_versions)
11156 matlab_binary_path
11158 the location of the matlab binary executable
11159 matlab_list_versions
11161 the version extracted from Matlab
11162 matlab_add_unit_test
11164 Adds a Matlab unit test to the test set of cmake/ctest. This
11165 command requires the component MAIN_PROGRAM and hence is not
11166 available for an MCR installation.
11167 The unit test uses the Matlab unittest framework (default,
11169 available starting Matlab 2013b+) except if the option
11170 NO_UNITTEST_FRAMEWORK is given.
11171 The function expects one Matlab test script file to be given.
11173 In the case NO_UNITTEST_FRAMEWORK is given, the unittest script
11174 file should contain the script to be run, plus an exit command
11175 with the exit value. This exit value will be passed to the ctest
11176 framework (0 success, non 0 failure). Additional arguments
11177 accepted by add_test() can be passed through TEST_ARGS (eg. CON‐
11178 FIGURATION <config> ...).
11179 matlab_add_unit_test(
11181 NAME <name>
11182 UNITTEST_FILE matlab_file_containing_unittest.m
11183 [CUSTOM_TEST_COMMAND matlab_command_to_run_as_test]
11184 [UNITTEST_PRECOMMAND matlab_command_to_run]
11185 [TIMEOUT timeout]
11186 [ADDITIONAL_PATH path1 [path2 ...]]
11187 [MATLAB_ADDITIONAL_STARTUP_OPTIONS option1 [option2 ...]]
11188 [TEST_ARGS arg1 [arg2 ...]]
11189 [NO_UNITTEST_FRAMEWORK]
11190 )
11191 The function arguments are:
11193 NAME name of the unittest in ctest.
11195 UNITTEST_FILE
11197 the matlab unittest file. Its path will be automatically
11198 added to the Matlab path.
11199 CUSTOM_TEST_COMMAND
11201 Matlab script command to run as the test. If this is not
11202 set, then the following is run: runtests('mat‐
11203 lab_file_name'), exit(max([ans(1,:).Failed])) where mat‐
11204 lab_file_name is the UNITTEST_FILE without the extension.
11205 UNITTEST_PRECOMMAND
11207 Matlab script command to be ran before the file contain‐
11208 ing the test (eg. GPU device initialisation based on
11209 CMake variables).
11210 TIMEOUT
11212 the test timeout in seconds. Defaults to 180 seconds as
11213 the Matlab unit test may hang.
11214 ADDITIONAL_PATH
11216 a list of paths to add to the Matlab path prior to run‐
11217 ning the unit test.
11218 MATLAB_ADDITIONAL_STARTUP_OPTIONS
11220 a list of additional option in order to run Matlab from
11221 the command line. -nosplash -nodesktop -nodisplay are
11222 always added.
11223 TEST_ARGS
11225 Additional options provided to the add_test command.
11226 These options are added to the default options (eg. “CON‐
11227 FIGURATIONS Release”)
11228 NO_UNITTEST_FRAMEWORK
11230 when set, indicates that the test should not use the
11231 unittest framework of Matlab (available for versions >=
11232 R2013a).
11233 WORKING_DIRECTORY
11235 This will be the working directory for the test. If spec‐
11236 ified it will also be the output directory used for the
11237 log file of the test run. If not specified the temporary
11238 directory ${CMAKE_BINARY_DIR}/Matlab will be used as the
11239 working directory and the log location.
11240 matlab_add_mex
11242 Adds a Matlab MEX target. This commands compiles the given
11243 sources with the current tool-chain in order to produce a MEX
11244 file. The final name of the produced output may be specified, as
11245 well as additional link libraries, and a documentation entry for
11246 the MEX file. Remaining arguments of the call are passed to the
11247 add_library() or add_executable() command.
11248 matlab_add_mex(
11250 NAME <name>
11251 [EXECUTABLE | MODULE | SHARED]
11252 SRC src1 [src2 ...]
11253 [OUTPUT_NAME output_name]
11254 [DOCUMENTATION file.txt]
11255 [LINK_TO target1 target2 ...]
11256 [R2017b | R2018a]
11257 [EXCLUDE_FROM_ALL]
11258 [...]
11259 )
11260 NAME name of the target.
11262 SRC list of source files.
11264 LINK_TO
11266 a list of additional link dependencies. The target links
11267 to libmex and libmx by default.
11268 OUTPUT_NAME
11270 if given, overrides the default name. The default name is
11271 the name of the target without any prefix and with Mat‐
11272 lab_MEX_EXTENSION suffix.
11273 DOCUMENTATION
11275 if given, the file file.txt will be considered as being
11276 the documentation file for the MEX file. This file is
11277 copied into the same folder without any processing, with
11278 the same name as the final mex file, and with extension
11279 .m. In that case, typing help <name> in Matlab prints the
11280 documentation contained in this file.
11281 R2017b or R2018a may be given to specify the version of the C
11283 API
11284 to use: R2017b specifies the traditional (separate com‐
11285 plex) C API, and corresponds to the -R2017b flag for the
11286 mex command. R2018a specifies the new interleaved complex
11287 C API, and corresponds to the -R2018a flag for the mex
11288 command. Ignored if MATLAB version prior to R2018a.
11289 Defaults to R2017b.
11290 MODULE or SHARED may be given to specify the type of library to
11292 be
11293 created. EXECUTABLE may be given to create an executable
11294 instead of a library. If no type is given explicitly, the
11295 type is SHARED.
11296 EXCLUDE_FROM_ALL
11298 This option has the same meaning as for EXCLUDE_FROM_ALL
11299 and is forwarded to add_library() or add_executable()
11300 commands.
11301 The documentation file is not processed and should be in the
11303 following format:
11304 % This is the documentation
11306 function ret = mex_target_output_name(input1)
11307 FindMFC
11309 Find Microsoft Foundation Class Library (MFC) on Windows
11310 Find the native MFC - i.e. decide if an application can link to the
11312 MFC libraries.
11313 MFC_FOUND - Was MFC support found
11315 You don’t need to include anything or link anything to use it.
11317 FindMotif
11319 Try to find Motif (or lesstif)
11320 Once done this will define:
11322 MOTIF_FOUND - system has MOTIF
11324 MOTIF_INCLUDE_DIR - include paths to use Motif
11325 MOTIF_LIBRARIES - Link these to use Motif
11326 FindMPEG2
11328 Find the native MPEG2 includes and library
11329 This module defines
11331 MPEG2_INCLUDE_DIR, path to mpeg2dec/mpeg2.h, etc.
11333 MPEG2_LIBRARIES, the libraries required to use MPEG2.
11334 MPEG2_FOUND, If false, do not try to use MPEG2.
11335 also defined, but not for general use are
11337 MPEG2_mpeg2_LIBRARY, where to find the MPEG2 library.
11339 MPEG2_vo_LIBRARY, where to find the vo library.
11340 FindMPEG
11342 Find the native MPEG includes and library
11343 This module defines
11345 MPEG_INCLUDE_DIR, where to find MPEG.h, etc.
11347 MPEG_LIBRARIES, the libraries required to use MPEG.
11348 MPEG_FOUND, If false, do not try to use MPEG.
11349 also defined, but not for general use are
11351 MPEG_mpeg2_LIBRARY, where to find the MPEG library.
11353 MPEG_vo_LIBRARY, where to find the vo library.
11354 FindMPI
11356 Find a Message Passing Interface (MPI) implementation.
11357 The Message Passing Interface (MPI) is a library used to write
11359 high-performance distributed-memory parallel applications, and is typi‐
11360 cally deployed on a cluster. MPI is a standard interface (defined by
11361 the MPI forum) for which many implementations are available.
11362 Variables for using MPI
11364 The module exposes the components C, CXX, MPICXX and Fortran. Each of
11365 these controls the various MPI languages to search for. The difference
11366 between CXX and MPICXX is that CXX refers to the MPI C API being usable
11367 from C++, whereas MPICXX refers to the MPI-2 C++ API that was removed
11368 again in MPI-3.
11369 Depending on the enabled components the following variables will be
11371 set:
11372 MPI_FOUND
11374 Variable indicating that MPI settings for all requested lan‐
11375 guages have been found. If no components are specified, this is
11376 true if MPI settings for all enabled languages were detected.
11377 Note that the MPICXX component does not affect this variable.
11378 MPI_VERSION
11380 Minimal version of MPI detected among the requested languages,
11381 or all enabled languages if no components were specified.
11382 This module will set the following variables per language in your
11384 project, where <lang> is one of C, CXX, or Fortran:
11385 MPI_<lang>_FOUND
11387 Variable indicating the MPI settings for <lang> were found and
11388 that simple MPI test programs compile with the provided set‐
11389 tings.
11390 MPI_<lang>_COMPILER
11392 MPI compiler for <lang> if such a program exists.
11393 MPI_<lang>_COMPILE_OPTIONS
11395 Compilation options for MPI programs in <lang>, given as a
11396 ;-list.
11397 MPI_<lang>_COMPILE_DEFINITIONS
11399 Compilation definitions for MPI programs in <lang>, given as a
11400 ;-list.
11401 MPI_<lang>_INCLUDE_DIRS
11403 Include path(s) for MPI header.
11404 MPI_<lang>_LINK_FLAGS
11406 Linker flags for MPI programs.
11407 MPI_<lang>_LIBRARIES
11409 All libraries to link MPI programs against.
11410 Additionally, the following IMPORTED targets are defined:
11412 MPI::MPI_<lang>
11414 Target for using MPI from <lang>.
11415 The following variables indicating which bindings are present will be
11417 defined:
11418 MPI_MPICXX_FOUND
11420 Variable indicating whether the MPI-2 C++ bindings are present
11421 (introduced in MPI-2, removed with MPI-3).
11422 MPI_Fortran_HAVE_F77_HEADER
11424 True if the Fortran 77 header mpif.h is available.
11425 MPI_Fortran_HAVE_F90_MODULE
11427 True if the Fortran 90 module mpi can be used for accessing MPI
11428 (MPI-2 and higher only).
11429 MPI_Fortran_HAVE_F08_MODULE
11431 True if the Fortran 2008 mpi_f08 is available to MPI programs
11432 (MPI-3 and higher only).
11433 If possible, the MPI version will be determined by this module. The
11435 facilities to detect the MPI version were introduced with MPI-1.2, and
11436 therefore cannot be found for older MPI versions.
11437 MPI_<lang>_VERSION_MAJOR
11439 Major version of MPI implemented for <lang> by the MPI distribu‐
11440 tion.
11441 MPI_<lang>_VERSION_MINOR
11443 Minor version of MPI implemented for <lang> by the MPI distribu‐
11444 tion.
11445 MPI_<lang>_VERSION
11447 MPI version implemented for <lang> by the MPI distribution.
11448 Note that there’s no variable for the C bindings being accessible
11450 through mpi.h, since the MPI standards always have required this bind‐
11451 ing to work in both C and C++ code.
11452 For running MPI programs, the module sets the following variables
11454 MPIEXEC_EXECUTABLE
11456 Executable for running MPI programs, if such exists.
11457 MPIEXEC_NUMPROC_FLAG
11459 Flag to pass to mpiexec before giving it the number of proces‐
11460 sors to run on.
11461 MPIEXEC_MAX_NUMPROCS
11463 Number of MPI processors to utilize. Defaults to the number of
11464 processors detected on the host system.
11465 MPIEXEC_PREFLAGS
11467 Flags to pass to mpiexec directly before the executable to run.
11468 MPIEXEC_POSTFLAGS
11470 Flags to pass to mpiexec after other flags.
11471 Variables for locating MPI
11473 This module performs a three step search for an MPI implementation:
11474 1. Check if the compiler has MPI support built-in. This is the case if
11476 the user passed a compiler wrapper as CMAKE_<LANG>_COMPILER or if
11477 they’re on a Cray system.
11478 2. Attempt to find an MPI compiler wrapper and determine the compiler
11480 information from it.
11481 3. Try to find an MPI implementation that does not ship such a wrapper
11483 by guessing settings. Currently, only Microsoft MPI and MPICH2 on
11484 Windows are supported.
11485 For controlling the second step, the following variables may be set:
11487 MPI_<lang>_COMPILER
11489 Search for the specified compiler wrapper and use it.
11490 MPI_<lang>_COMPILER_FLAGS
11492 Flags to pass to the MPI compiler wrapper during interrogation.
11493 Some compiler wrappers support linking debug or tracing
11494 libraries if a specific flag is passed and this variable may be
11495 used to obtain them.
11496 MPI_COMPILER_FLAGS
11498 Used to initialize MPI_<lang>_COMPILER_FLAGS if no language spe‐
11499 cific flag has been given. Empty by default.
11500 MPI_EXECUTABLE_SUFFIX
11502 A suffix which is appended to all names that are being looked
11503 for. For instance you may set this to .mpich or .openmpi to pre‐
11504 fer the one or the other on Debian and its derivatives.
11505 In order to control the guessing step, the following variable may be
11507 set:
11508 MPI_GUESS_LIBRARY_NAME
11510 Valid values are MSMPI and MPICH2. If set, only the given
11511 library will be searched for. By default, MSMPI will be pre‐
11512 ferred over MPICH2 if both are available. This also sets
11513 MPI_SKIP_COMPILER_WRAPPER to true, which may be overridden.
11514 Each of the search steps may be skipped with the following control
11516 variables:
11517 MPI_ASSUME_NO_BUILTIN_MPI
11519 If true, the module assumes that the compiler itself does not
11520 provide an MPI implementation and skips to step 2.
11521 MPI_SKIP_COMPILER_WRAPPER
11523 If true, no compiler wrapper will be searched for.
11524 MPI_SKIP_GUESSING
11526 If true, the guessing step will be skipped.
11527 Additionally, the following control variable is available to change
11529 search behavior:
11530 MPI_CXX_SKIP_MPICXX
11532 Add some definitions that will disable the MPI-2 C++ bindings.
11533 Currently supported are MPICH, Open MPI, Platform MPI and deriv‐
11534 atives thereof, for example MVAPICH or Intel MPI.
11535 If the find procedure fails for a variable MPI_<lang>_WORKS, then the
11537 settings detected by or passed to the module did not work and even a
11538 simple MPI test program failed to compile.
11539 If all of these parameters were not sufficient to find the right MPI
11541 implementation, a user may disable the entire autodetection process by
11542 specifying both a list of libraries in MPI_<lang>_LIBRARIES and a list
11543 of include directories in MPI_<lang>_ADDITIONAL_INCLUDE_DIRS. Any
11544 other variable may be set in addition to these two. The module will
11545 then validate the MPI settings and store the settings in the cache.
11546 Cache variables for MPI
11548 The variable MPI_<lang>_INCLUDE_DIRS will be assembled from the follow‐
11549 ing variables. For C and CXX:
11550 MPI_<lang>_HEADER_DIR
11552 Location of the mpi.h header on disk.
11553 For Fortran:
11555 MPI_Fortran_F77_HEADER_DIR
11557 Location of the Fortran 77 header mpif.h, if it exists.
11558 MPI_Fortran_MODULE_DIR
11560 Location of the mpi or mpi_f08 modules, if available.
11561 For all languages the following variables are additionally considered:
11563 MPI_<lang>_ADDITIONAL_INCLUDE_DIRS
11565 A ;-list of paths needed in addition to the normal include
11566 directories.
11567 MPI_<include_name>_INCLUDE_DIR
11569 Path variables for include folders referred to by
11570 <include_name>.
11571 MPI_<lang>_ADDITIONAL_INCLUDE_VARS
11573 A ;-list of <include_name> that will be added to the include
11574 locations of <lang>.
11575 The variable MPI_<lang>_LIBRARIES will be assembled from the following
11577 variables:
11578 MPI_<lib_name>_LIBRARY
11580 The location of a library called <lib_name> for use with MPI.
11581 MPI_<lang>_LIB_NAMES
11583 A ;-list of <lib_name> that will be added to the include loca‐
11584 tions of <lang>.
11585 Usage of mpiexec
11587 When using MPIEXEC_EXECUTABLE to execute MPI applications, you should
11588 typically use all of the MPIEXEC_EXECUTABLE flags as follows:
11589 ${MPIEXEC_EXECUTABLE} ${MPIEXEC_NUMPROC_FLAG} ${MPIEXEC_MAX_NUMPROCS}
11591 ${MPIEXEC_PREFLAGS} EXECUTABLE ${MPIEXEC_POSTFLAGS} ARGS
11592 where EXECUTABLE is the MPI program, and ARGS are the arguments to pass
11594 to the MPI program.
11595 Advanced variables for using MPI
11597 The module can perform some advanced feature detections upon explicit
11598 request.
11599 Important notice: The following checks cannot be performed without exe‐
11601 cuting an MPI test program. Consider the special considerations for
11602 the behavior of try_run() during cross compilation. Moreover, running
11603 an MPI program can cause additional issues, like a firewall notifica‐
11604 tion on some systems. You should only enable these detections if you
11605 absolutely need the information.
11606 If the following variables are set to true, the respective search will
11608 be performed:
11609 MPI_DETERMINE_Fortran_CAPABILITIES
11611 Determine for all available Fortran bindings what the values of
11612 MPI_SUBARRAYS_SUPPORTED and MPI_ASYNC_PROTECTS_NONBLOCKING are
11613 and make their values available as MPI_Fortran_<binding>_SUBAR‐
11614 RAYS and MPI_Fortran_<binding>_ASYNCPROT, where <binding> is one
11615 of F77_HEADER, F90_MODULE and F08_MODULE.
11616 MPI_DETERMINE_LIBRARY_VERSION
11618 For each language, find the output of MPI_Get_library_version
11619 and make it available as MPI_<lang>_LIBRARY_VERSION_STRING.
11620 This information is usually tied to the runtime component of an
11621 MPI implementation and might differ depending on <lang>. Note
11622 that the return value is entirely implementation defined. This
11623 information might be used to identify the MPI vendor and for
11624 example pick the correct one of multiple third party binaries
11625 that matches the MPI vendor.
11626 Backward Compatibility
11628 For backward compatibility with older versions of FindMPI, these vari‐
11629 ables are set, but deprecated:
11630 MPI_COMPILER MPI_LIBRARY MPI_EXTRA_LIBRARY
11632 MPI_COMPILE_FLAGS MPI_INCLUDE_PATH MPI_LINK_FLAGS
11633 MPI_LIBRARIES
11634 In new projects, please use the MPI_<lang>_XXX equivalents. Addition‐
11636 ally, the following variables are deprecated:
11637 MPI_<lang>_COMPILE_FLAGS
11639 Use MPI_<lang>_COMPILE_OPTIONS and MPI_<lang>_COMPILE_DEFINI‐
11640 TIONS instead.
11641 MPI_<lang>_INCLUDE_PATH
11643 For consumption use MPI_<lang>_INCLUDE_DIRS and for specifying
11644 folders use MPI_<lang>_ADDITIONAL_INCLUDE_DIRS instead.
11645 MPIEXEC
11647 Use MPIEXEC_EXECUTABLE instead.
11648 FindODBC
11650 Find an Open Database Connectivity (ODBC) include directory and
11651 library.
11652 On Windows, when building with Visual Studio, this module assumes the
11654 ODBC library is provided by the available Windows SDK.
11655 On Unix, this module allows to search for ODBC library provided by
11657 unixODBC or iODBC implementations of ODBC API. This module reads hint
11658 about location of the config program:
11659 ODBC_CONFIG
11661 Location of odbc_config or iodbc-config program
11662 Otherwise, this module tries to find the config program, first from
11664 unixODBC, then from iODBC. If no config program found, this module
11665 searches for ODBC header and library in list of known locations.
11666 Imported targets
11668 This module defines the following IMPORTED targets:
11669 ODBC::ODBC
11671 Imported target for using the ODBC library, if found.
11672 Result variables
11674 ODBC_FOUND
11675 Set to true if ODBC library found, otherwise false or undefined.
11676 ODBC_INCLUDE_DIRS
11678 Paths to include directories listed in one variable for use by
11679 ODBC client. May be empty on Windows, where the include direc‐
11680 tory corresponding to the expected Windows SDK is already avail‐
11681 able in the compilation environment.
11682 ODBC_LIBRARIES
11684 Paths to libraries to linked against to use ODBC. May just a
11685 library name on Windows, where the library directory correspond‐
11686 ing to the expected Windows SDK is already available in the com‐
11687 pilation environment.
11688 ODBC_CONFIG
11690 Path to unixODBC or iODBC config program, if found or specified.
11691 Cache variables
11693 For users who wish to edit and control the module behavior, this module
11694 reads hints about search locations from the following variables:
11695 ODBC_INCLUDE_DIR
11697 Path to ODBC include directory with sql.h header.
11698 ODBC_LIBRARY
11700 Path to ODBC library to be linked.
11701 These variables should not be used directly by project code.
11703 Limitations
11705 On Windows, this module does not search for iODBC. On Unix, there is
11706 no way to prefer unixODBC over iODBC, or vice versa, other than provid‐
11707 ing the config program location using the ODBC_CONFIG. This module
11708 does not allow to search for a specific ODBC driver.
11709 FindOpenACC
11711 Detect OpenACC support by the compiler.
11712 This module can be used to detect OpenACC support in a compiler. If
11714 the compiler supports OpenACC, the flags required to compile with Ope‐
11715 nACC support are returned in variables for the different languages.
11716 Currently, only PGI, GNU and Cray compilers are supported.
11717 Variables
11719 This module will set the following variables per language in your
11720 project, where <lang> is one of C, CXX, or Fortran:
11721 OpenACC_<lang>_FOUND
11723 Variable indicating if OpenACC support for <lang> was detected.
11724 OpenACC_<lang>_FLAGS
11726 OpenACC compiler flags for <lang>, separated by spaces.
11727 OpenACC_<lang>_OPTIONS
11729 OpenACC compiler flags for <lang>, as a list. Suitable for usage
11730 with target_compile_options or target_link_options.
11731 Additionally, the module provides IMPORTED targets:
11733 OpenACC::OpenACC_<lang>
11735 Target for using OpenACC from <lang>.
11736 The module will also try to provide the OpenACC version variables:
11738 OpenACC_<lang>_SPEC_DATE
11740 Date of the OpenACC specification implemented by the <lang> com‐
11741 piler.
11742 OpenACC_<lang>_VERSION_MAJOR
11744 Major version of OpenACC implemented by the <lang> compiler.
11745 OpenACC_<lang>_VERSION_MINOR
11747 Minor version of OpenACC implemented by the <lang> compiler.
11748 OpenACC_<lang>_VERSION
11750 OpenACC version implemented by the <lang> compiler.
11751 The specification date is formatted as given in the OpenACC standard:
11753 yyyymm where yyyy and mm represents the year and month of the OpenACC
11754 specification implemented by the <lang> compiler.
11755 Input Variables
11757 OpenACC_ACCEL_TARGET=<target> If set, will the correct target accelera‐
11758 tor flag set to the <target> will be returned with Ope‐
11759 nACC_<lang>_FLAGS.
11760 FindOpenAL
11762 Finds Open Audio Library (OpenAL). This module defines OPENAL_LIBRARY
11763 OPENAL_FOUND, if false, do not try to link to OpenAL OPE‐
11764 NAL_INCLUDE_DIR, where to find the headers.
11765 $OPENALDIR is an environment variable that would correspond to the
11767 ./configure --prefix=$OPENALDIR used in building OpenAL.
11768 Created by Eric Wing. This was influenced by the FindSDL.cmake module.
11770 FindOpenCL
11772 Finds Open Computing Language (OpenCL)
11773 IMPORTED Targets
11775 This module defines IMPORTED target OpenCL::OpenCL, if OpenCL has been
11776 found.
11777 Result Variables
11779 This module defines the following variables:
11780 OpenCL_FOUND - True if OpenCL was found
11782 OpenCL_INCLUDE_DIRS - include directories for OpenCL
11783 OpenCL_LIBRARIES - link against this library to use OpenCL
11784 OpenCL_VERSION_STRING - Highest supported OpenCL version (eg. 1.2)
11785 OpenCL_VERSION_MAJOR - The major version of the OpenCL implementation
11786 OpenCL_VERSION_MINOR - The minor version of the OpenCL implementation
11787 The module will also define two cache variables:
11789 OpenCL_INCLUDE_DIR - the OpenCL include directory
11791 OpenCL_LIBRARY - the path to the OpenCL library
11792 FindOpenGL
11794 FindModule for OpenGL and OpenGL Utility Library (GLU).
11795 Optional COMPONENTS
11797 This module respects several optional COMPONENTS: EGL, GLX, and OpenGL.
11798 There are corresponding import targets for each of these flags.
11799 IMPORTED Targets
11801 This module defines the IMPORTED targets:
11802 OpenGL::GL
11804 Defined to the platform-specific OpenGL libraries if the system
11805 has OpenGL.
11806 OpenGL::OpenGL
11808 Defined to libOpenGL if the system is GLVND-based.
11809 OpenGL::GLU
11811 Defined if the system has OpenGL Utility Library (GLU).
11812 OpenGL::GLX
11814 Defined if the system has OpenGL Extension to the X Window Sys‐
11815 tem (GLX).
11816 OpenGL::EGL
11818 Defined if the system has EGL.
11819 Result Variables
11821 This module sets the following variables:
11822 OPENGL_FOUND
11824 True, if the system has OpenGL and all components are found.
11825 OPENGL_XMESA_FOUND
11827 True, if the system has XMESA.
11828 OPENGL_GLU_FOUND
11830 True, if the system has GLU.
11831 OpenGL_OpenGL_FOUND
11833 True, if the system has an OpenGL library.
11834 OpenGL_GLX_FOUND
11836 True, if the system has GLX.
11837 OpenGL_EGL_FOUND
11839 True, if the system has EGL.
11840 OPENGL_INCLUDE_DIR
11842 Path to the OpenGL include directory.
11843 OPENGL_EGL_INCLUDE_DIRS
11845 Path to the EGL include directory.
11846 OPENGL_LIBRARIES
11848 Paths to the OpenGL library, windowing system libraries, and GLU
11849 libraries. On Linux, this assumes GLX and is never correct for
11850 EGL-based targets. Clients are encouraged to use the OpenGL::*
11851 import targets instead.
11852 Cache variables
11854 The following cache variables may also be set:
11855 OPENGL_egl_LIBRARY
11857 Path to the EGL library.
11858 OPENGL_glu_LIBRARY
11860 Path to the GLU library.
11861 OPENGL_glx_LIBRARY
11863 Path to the GLVND ‘GLX’ library.
11864 OPENGL_opengl_LIBRARY
11866 Path to the GLVND ‘OpenGL’ library
11867 OPENGL_gl_LIBRARY
11869 Path to the OpenGL library. New code should prefer the
11870 OpenGL::* import targets.
11871 Linux-specific
11873 Some Linux systems utilize GLVND as a new ABI for OpenGL. GLVND sepa‐
11874 rates context libraries from OpenGL itself; OpenGL lives in
11875 “libOpenGL”, and contexts are defined in “libGLX” or “libEGL”. GLVND
11876 is currently the only way to get OpenGL 3+ functionality via EGL in a
11877 manner portable across vendors. Projects may use GLVND explicitly with
11878 target OpenGL::OpenGL and either OpenGL::GLX or OpenGL::EGL.
11879 Projects may use the OpenGL::GL target (or OPENGL_LIBRARIES variable)
11881 to use legacy GL interfaces. These will use the legacy GL library
11882 located by OPENGL_gl_LIBRARY, if available. If OPENGL_gl_LIBRARY is
11883 empty or not found and GLVND is available, the OpenGL::GL target will
11884 use GLVND OpenGL::OpenGL and OpenGL::GLX (and the OPENGL_LIBRARIES
11885 variable will use the corresponding libraries). Thus, for
11886 non-EGL-based Linux targets, the OpenGL::GL target is most portable.
11887 A OpenGL_GL_PREFERENCE variable may be set to specify the preferred way
11889 to provide legacy GL interfaces in case multiple choices are available.
11890 The value may be one of:
11891 GLVND If the GLVND OpenGL and GLX libraries are available, prefer
11893 them. This forces OPENGL_gl_LIBRARY to be empty. This is the
11894 default if components were requested (since components corre‐
11895 spond to GLVND libraries) or if policy CMP0072 is set to NEW.
11896 LEGACY Prefer to use the legacy libGL library, if available. This is
11898 the default if no components were requested and policy CMP0072
11899 is not set to NEW.
11900 For EGL targets the client must rely on GLVND support on the user’s
11902 system. Linking should use the OpenGL::OpenGL OpenGL::EGL targets.
11903 Using GLES* libraries is theoretically possible in place of
11904 OpenGL::OpenGL, but this module does not currently support that; con‐
11905 tributions welcome.
11906 OPENGL_egl_LIBRARY and OPENGL_EGL_INCLUDE_DIRS are defined in the case
11908 of GLVND. For non-GLVND Linux and other systems these are left unde‐
11909 fined.
11910 macOS-Specific
11912 On OSX FindOpenGL defaults to using the framework version of OpenGL.
11913 People will have to change the cache values of OPENGL_glu_LIBRARY and
11914 OPENGL_gl_LIBRARY to use OpenGL with X11 on OSX.
11915 FindOpenMP
11917 Finds Open Multi-Processing (OpenMP) support.
11918 This module can be used to detect OpenMP support in a compiler. If the
11920 compiler supports OpenMP, the flags required to compile with OpenMP
11921 support are returned in variables for the different languages. The
11922 variables may be empty if the compiler does not need a special flag to
11923 support OpenMP.
11924 Variables
11926 The module exposes the components C, CXX, and Fortran. Each of these
11927 controls the various languages to search OpenMP support for.
11928 Depending on the enabled components the following variables will be
11930 set:
11931 OpenMP_FOUND
11933 Variable indicating that OpenMP flags for all requested lan‐
11934 guages have been found. If no components are specified, this is
11935 true if OpenMP settings for all enabled languages were detected.
11936 OpenMP_VERSION
11938 Minimal version of the OpenMP standard detected among the
11939 requested languages, or all enabled languages if no components
11940 were specified.
11941 This module will set the following variables per language in your
11943 project, where <lang> is one of C, CXX, or Fortran:
11944 OpenMP_<lang>_FOUND
11946 Variable indicating if OpenMP support for <lang> was detected.
11947 OpenMP_<lang>_FLAGS
11949 OpenMP compiler flags for <lang>, separated by spaces.
11950 OpenMP_<lang>_INCLUDE_DIRS
11952 Directories that must be added to the header search path for
11953 <lang> when using OpenMP.
11954 For linking with OpenMP code written in <lang>, the following variables
11956 are provided:
11957 OpenMP_<lang>_LIB_NAMES
11959 ;-list of libraries for OpenMP programs for <lang>.
11960 OpenMP_<libname>_LIBRARY
11962 Location of the individual libraries needed for OpenMP support
11963 in <lang>.
11964 OpenMP_<lang>_LIBRARIES
11966 A list of libraries needed to link with OpenMP code written in
11967 <lang>.
11968 Additionally, the module provides IMPORTED targets:
11970 OpenMP::OpenMP_<lang>
11972 Target for using OpenMP from <lang>.
11973 Specifically for Fortran, the module sets the following variables:
11975 OpenMP_Fortran_HAVE_OMPLIB_HEADER
11977 Boolean indicating if OpenMP is accessible through omp_lib.h.
11978 OpenMP_Fortran_HAVE_OMPLIB_MODULE
11980 Boolean indicating if OpenMP is accessible through the omp_lib
11981 Fortran module.
11982 The module will also try to provide the OpenMP version variables:
11984 OpenMP_<lang>_SPEC_DATE
11986 Date of the OpenMP specification implemented by the <lang> com‐
11987 piler.
11988 OpenMP_<lang>_VERSION_MAJOR
11990 Major version of OpenMP implemented by the <lang> compiler.
11991 OpenMP_<lang>_VERSION_MINOR
11993 Minor version of OpenMP implemented by the <lang> compiler.
11994 OpenMP_<lang>_VERSION
11996 OpenMP version implemented by the <lang> compiler.
11997 The specification date is formatted as given in the OpenMP standard:
11999 yyyymm where yyyy and mm represents the year and month of the OpenMP
12000 specification implemented by the <lang> compiler.
12001 For some compilers, it may be necessary to add a header search path to
12003 find the relevant OpenMP headers. This location may be language-spe‐
12004 cific. Where this is needed, the module may attempt to find the loca‐
12005 tion, but it can be provided directly by setting the
12006 OpenMP_<lang>_INCLUDE_DIR cache variable. Note that this variable is
12007 an _input_ control to the module. Project code should use the
12008 OpenMP_<lang>_INCLUDE_DIRS _output_ variable if it needs to know what
12009 include directories are needed.
12010 FindOpenSceneGraph
12012 Find OpenSceneGraph (3D graphics application programming interface)
12013 This module searches for the OpenSceneGraph core “osg” library as well
12015 as FindOpenThreads, and whatever additional COMPONENTS (nodekits) that
12016 you specify.
12017 See http://www.openscenegraph.org
12019 NOTE: To use this module effectively you must either require CMake >=
12021 2.6.3 with cmake_minimum_required(VERSION 2.6.3) or download and place
12022 FindOpenThreads, Findosg functions, Findosg and Find<etc>.cmake files
12023 into your CMAKE_MODULE_PATH.
12024 ----
12027 This module accepts the following variables (note mixed case)
12031 OpenSceneGraph_DEBUG - Enable debugging output
12033 OpenSceneGraph_MARK_AS_ADVANCED - Mark cache variables as advanced
12035 automatically
12036 The following environment variables are also respected for finding the
12038 OSG and it’s various components. CMAKE_PREFIX_PATH can also be used
12039 for this (see find_library() CMake documentation).
12040 <MODULE>_DIR
12042 (where MODULE is of the form “OSGVOLUME” and there is a Findos‐
12043 gVolume.cmake` file)
12044 OSG_DIR
12046 OSGDIR
12048 OSG_ROOT
12050 [CMake 2.8.10]: The CMake variable OSG_DIR can now be used as well to
12052 influence detection, instead of needing to specify an environment vari‐
12053 able.
12054 This module defines the following output variables:
12056 OPENSCENEGRAPH_FOUND - Was the OSG and all of the specified components found?
12058 OPENSCENEGRAPH_VERSION - The version of the OSG which was found
12060 OPENSCENEGRAPH_INCLUDE_DIRS - Where to find the headers
12062 OPENSCENEGRAPH_LIBRARIES - The OSG libraries
12064 ================================== Example Usage:
12066 find_package(OpenSceneGraph 2.0.0 REQUIRED osgDB osgUtil)
12068 # libOpenThreads & libosg automatically searched
12069 include_directories(${OPENSCENEGRAPH_INCLUDE_DIRS})
12070 add_executable(foo foo.cc)
12072 target_link_libraries(foo ${OPENSCENEGRAPH_LIBRARIES})
12073 FindOpenSSL
12075 Find the OpenSSL encryption library.
12076 Optional COMPONENTS
12078 This module supports two optional COMPONENTS: Crypto and SSL. Both
12079 components have associated imported targets, as described below.
12080 Imported Targets
12082 This module defines the following IMPORTED targets:
12083 OpenSSL::SSL
12085 The OpenSSL ssl library, if found.
12086 OpenSSL::Crypto
12088 The OpenSSL crypto library, if found.
12089 Result Variables
12091 This module will set the following variables in your project:
12092 OPENSSL_FOUND
12094 System has the OpenSSL library. If no components are requested
12095 it only requires the crypto library.
12096 OPENSSL_INCLUDE_DIR
12098 The OpenSSL include directory.
12099 OPENSSL_CRYPTO_LIBRARY
12101 The OpenSSL crypto library.
12102 OPENSSL_CRYPTO_LIBRARIES
12104 The OpenSSL crypto library and its dependencies.
12105 OPENSSL_SSL_LIBRARY
12107 The OpenSSL SSL library.
12108 OPENSSL_SSL_LIBRARIES
12110 The OpenSSL SSL library and its dependencies.
12111 OPENSSL_LIBRARIES
12113 All OpenSSL libraries and their dependencies.
12114 OPENSSL_VERSION
12116 This is set to $major.$minor.$revision$patch (e.g. 0.9.8s).
12117 Hints
12119 Set OPENSSL_ROOT_DIR to the root directory of an OpenSSL installation.
12120 Set OPENSSL_USE_STATIC_LIBS to TRUE to look for static libraries. Set
12121 OPENSSL_MSVC_STATIC_RT set TRUE to choose the MT version of the lib.
12122 FindOpenThreads
12124 OpenThreads is a C++ based threading library. Its largest userbase
12125 seems to OpenSceneGraph so you might notice I accept OSGDIR as an envi‐
12126 ronment path. I consider this part of the Findosg* suite used to find
12127 OpenSceneGraph components. Each component is separate and you must opt
12128 in to each module.
12129 Locate OpenThreads This module defines OPENTHREADS_LIBRARY
12131 OPENTHREADS_FOUND, if false, do not try to link to OpenThreads
12132 OPENTHREADS_INCLUDE_DIR, where to find the headers
12133 $OPENTHREADS_DIR is an environment variable that would correspond to
12135 the ./configure –prefix=$OPENTHREADS_DIR used in building osg.
12136 [CMake 2.8.10]: The CMake variables OPENTHREADS_DIR or OSG_DIR can now
12138 be used as well to influence detection, instead of needing to specify
12139 an environment variable.
12140 Created by Eric Wing.
12142 FindosgAnimation
12144 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12145 nents. Each component is separate and you must opt in to each module.
12146 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12147 as these modules won’t do it for you. This is to allow you control
12148 over your own system piece by piece in case you need to opt out of cer‐
12149 tain components or change the Find behavior for a particular module
12150 (perhaps because the default FindOpenGL.cmake module doesn’t work with
12151 your system as an example). If you want to use a more convenient mod‐
12152 ule that includes everything, use the FindOpenSceneGraph.cmake instead
12153 of the Findosg*.cmake modules.
12154 Locate osgAnimation This module defines
12156 OSGANIMATION_FOUND - Was osgAnimation found? OSGANIMATION_INCLUDE_DIR -
12158 Where to find the headers OSGANIMATION_LIBRARIES - The libraries to
12159 link against for the OSG (use this)
12160 OSGANIMATION_LIBRARY - The OSG library OSGANIMATION_LIBRARY_DEBUG - The
12162 OSG debug library
12163 $OSGDIR is an environment variable that would correspond to the
12165 Created by Eric Wing.
12167 FindosgDB
12169 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12170 nents. Each component is separate and you must opt in to each module.
12171 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12172 as these modules won’t do it for you. This is to allow you control
12173 over your own system piece by piece in case you need to opt out of cer‐
12174 tain components or change the Find behavior for a particular module
12175 (perhaps because the default FindOpenGL module doesn’t work with your
12176 system as an example). If you want to use a more convenient module
12177 that includes everything, use the FindOpenSceneGraph instead of the
12178 Findosg*.cmake modules.
12179 Locate osgDB This module defines:
12181 OSGDB_FOUND
12183 Was osgDB found?
12184 OSGDB_INCLUDE_DIR
12186 Where to find the headers
12187 OSGDB_LIBRARIES
12189 The libraries to link against for the osgDB
12190 OSGDB_LIBRARY
12192 The osgDB library
12193 OSGDB_LIBRARY_DEBUG
12195 The osgDB debug library
12196 $OSGDIR is an environment variable that would correspond to:
12198 ./configure --prefix=$OSGDIR used in building osg.
12200 Findosg_functions
12202 This CMake file contains two macros to assist with searching for OSG
12203 libraries and nodekits. Please see FindOpenSceneGraph.cmake for full
12204 documentation.
12205 FindosgFX
12207 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12208 nents. Each component is separate and you must opt in to each module.
12209 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12210 as these modules won’t do it for you. This is to allow you control
12211 over your own system piece by piece in case you need to opt out of cer‐
12212 tain components or change the Find behavior for a particular module
12213 (perhaps because the default FindOpenGL.cmake module doesn’t work with
12214 your system as an example). If you want to use a more convenient mod‐
12215 ule that includes everything, use the FindOpenSceneGraph.cmake instead
12216 of the Findosg*.cmake modules.
12217 Locate osgFX This module defines
12219 OSGFX_FOUND - Was osgFX found? OSGFX_INCLUDE_DIR - Where to find the
12221 headers OSGFX_LIBRARIES - The libraries to link against for the osgFX
12222 (use this)
12223 OSGFX_LIBRARY - The osgFX library OSGFX_LIBRARY_DEBUG - The osgFX debug
12225 library
12226 $OSGDIR is an environment variable that would correspond to the
12228 Created by Eric Wing.
12230 FindosgGA
12232 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12233 nents. Each component is separate and you must opt in to each module.
12234 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12235 as these modules won’t do it for you. This is to allow you control
12236 over your own system piece by piece in case you need to opt out of cer‐
12237 tain components or change the Find behavior for a particular module
12238 (perhaps because the default FindOpenGL.cmake module doesn’t work with
12239 your system as an example). If you want to use a more convenient mod‐
12240 ule that includes everything, use the FindOpenSceneGraph.cmake instead
12241 of the Findosg*.cmake modules.
12242 Locate osgGA This module defines
12244 OSGGA_FOUND - Was osgGA found? OSGGA_INCLUDE_DIR - Where to find the
12246 headers OSGGA_LIBRARIES - The libraries to link against for the osgGA
12247 (use this)
12248 OSGGA_LIBRARY - The osgGA library OSGGA_LIBRARY_DEBUG - The osgGA debug
12250 library
12251 $OSGDIR is an environment variable that would correspond to the
12253 Created by Eric Wing.
12255 FindosgIntrospection
12257 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12258 nents. Each component is separate and you must opt in to each module.
12259 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12260 as these modules won’t do it for you. This is to allow you control
12261 over your own system piece by piece in case you need to opt out of cer‐
12262 tain components or change the Find behavior for a particular module
12263 (perhaps because the default FindOpenGL.cmake module doesn’t work with
12264 your system as an example). If you want to use a more convenient mod‐
12265 ule that includes everything, use the FindOpenSceneGraph.cmake instead
12266 of the Findosg*.cmake modules.
12267 Locate osgINTROSPECTION This module defines
12269 OSGINTROSPECTION_FOUND - Was osgIntrospection found? OSGINTROSPEC‐
12271 TION_INCLUDE_DIR - Where to find the headers OSGINTROSPECTION_LIBRARIES
12272 - The libraries to link for osgIntrospection (use this)
12273 OSGINTROSPECTION_LIBRARY - The osgIntrospection library OSGINTROSPEC‐
12275 TION_LIBRARY_DEBUG - The osgIntrospection debug library
12276 $OSGDIR is an environment variable that would correspond to the
12278 Created by Eric Wing.
12280 FindosgManipulator
12282 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12283 nents. Each component is separate and you must opt in to each module.
12284 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12285 as these modules won’t do it for you. This is to allow you control
12286 over your own system piece by piece in case you need to opt out of cer‐
12287 tain components or change the Find behavior for a particular module
12288 (perhaps because the default FindOpenGL.cmake module doesn’t work with
12289 your system as an example). If you want to use a more convenient mod‐
12290 ule that includes everything, use the FindOpenSceneGraph.cmake instead
12291 of the Findosg*.cmake modules.
12292 Locate osgManipulator This module defines
12294 OSGMANIPULATOR_FOUND - Was osgManipulator found? OSGMANIPULA‐
12296 TOR_INCLUDE_DIR - Where to find the headers OSGMANIPULATOR_LIBRARIES -
12297 The libraries to link for osgManipulator (use this)
12298 OSGMANIPULATOR_LIBRARY - The osgManipulator library OSGMANIPULA‐
12300 TOR_LIBRARY_DEBUG - The osgManipulator debug library
12301 $OSGDIR is an environment variable that would correspond to the
12303 Created by Eric Wing.
12305 FindosgParticle
12307 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12308 nents. Each component is separate and you must opt in to each module.
12309 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12310 as these modules won’t do it for you. This is to allow you control
12311 over your own system piece by piece in case you need to opt out of cer‐
12312 tain components or change the Find behavior for a particular module
12313 (perhaps because the default FindOpenGL.cmake module doesn’t work with
12314 your system as an example). If you want to use a more convenient mod‐
12315 ule that includes everything, use the FindOpenSceneGraph.cmake instead
12316 of the Findosg*.cmake modules.
12317 Locate osgParticle This module defines
12319 OSGPARTICLE_FOUND - Was osgParticle found? OSGPARTICLE_INCLUDE_DIR -
12321 Where to find the headers OSGPARTICLE_LIBRARIES - The libraries to link
12322 for osgParticle (use this)
12323 OSGPARTICLE_LIBRARY - The osgParticle library OSGPARTICLE_LIBRARY_DEBUG
12325 - The osgParticle debug library
12326 $OSGDIR is an environment variable that would correspond to the
12328 Created by Eric Wing.
12330 FindosgPresentation
12332 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12333 nents. Each component is separate and you must opt in to each module.
12334 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12335 as these modules won’t do it for you. This is to allow you control
12336 over your own system piece by piece in case you need to opt out of cer‐
12337 tain components or change the Find behavior for a particular module
12338 (perhaps because the default FindOpenGL.cmake module doesn’t work with
12339 your system as an example). If you want to use a more convenient mod‐
12340 ule that includes everything, use the FindOpenSceneGraph.cmake instead
12341 of the Findosg*.cmake modules.
12342 Locate osgPresentation This module defines
12344 OSGPRESENTATION_FOUND - Was osgPresentation found? OSGPRESENTA‐
12346 TION_INCLUDE_DIR - Where to find the headers OSGPRESENTATION_LIBRARIES
12347 - The libraries to link for osgPresentation (use this)
12348 OSGPRESENTATION_LIBRARY - The osgPresentation library OSGPRESENTA‐
12350 TION_LIBRARY_DEBUG - The osgPresentation debug library
12351 $OSGDIR is an environment variable that would correspond to the
12353 Created by Eric Wing. Modified to work with osgPresentation by Robert
12355 Osfield, January 2012.
12356 FindosgProducer
12358 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12359 nents. Each component is separate and you must opt in to each module.
12360 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12361 as these modules won’t do it for you. This is to allow you control
12362 over your own system piece by piece in case you need to opt out of cer‐
12363 tain components or change the Find behavior for a particular module
12364 (perhaps because the default FindOpenGL.cmake module doesn’t work with
12365 your system as an example). If you want to use a more convenient mod‐
12366 ule that includes everything, use the FindOpenSceneGraph.cmake instead
12367 of the Findosg*.cmake modules.
12368 Locate osgProducer This module defines
12370 OSGPRODUCER_FOUND - Was osgProducer found? OSGPRODUCER_INCLUDE_DIR -
12372 Where to find the headers OSGPRODUCER_LIBRARIES - The libraries to link
12373 for osgProducer (use this)
12374 OSGPRODUCER_LIBRARY - The osgProducer library OSGPRODUCER_LIBRARY_DEBUG
12376 - The osgProducer debug library
12377 $OSGDIR is an environment variable that would correspond to the
12379 Created by Eric Wing.
12381 FindosgQt
12383 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12384 nents. Each component is separate and you must opt in to each module.
12385 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12386 as these modules won’t do it for you. This is to allow you control
12387 over your own system piece by piece in case you need to opt out of cer‐
12388 tain components or change the Find behavior for a particular module
12389 (perhaps because the default FindOpenGL.cmake module doesn’t work with
12390 your system as an example). If you want to use a more convenient mod‐
12391 ule that includes everything, use the FindOpenSceneGraph.cmake instead
12392 of the Findosg*.cmake modules.
12393 Locate osgQt This module defines
12395 OSGQT_FOUND - Was osgQt found? OSGQT_INCLUDE_DIR - Where to find the
12397 headers OSGQT_LIBRARIES - The libraries to link for osgQt (use this)
12398 OSGQT_LIBRARY - The osgQt library OSGQT_LIBRARY_DEBUG - The osgQt debug
12400 library
12401 $OSGDIR is an environment variable that would correspond to the
12403 Created by Eric Wing. Modified to work with osgQt by Robert Osfield,
12405 January 2012.
12406 Findosg
12408 NOTE: It is highly recommended that you use the new FindOpenScene‐
12409 Graph.cmake introduced in CMake 2.6.3 and not use this Find module
12410 directly.
12411 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12413 nents. Each component is separate and you must opt in to each module.
12414 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12415 as these modules won’t do it for you. This is to allow you control
12416 over your own system piece by piece in case you need to opt out of cer‐
12417 tain components or change the Find behavior for a particular module
12418 (perhaps because the default FindOpenGL.cmake module doesn’t work with
12419 your system as an example). If you want to use a more convenient mod‐
12420 ule that includes everything, use the FindOpenSceneGraph.cmake instead
12421 of the Findosg*.cmake modules.
12422 Locate osg This module defines
12424 OSG_FOUND - Was the Osg found? OSG_INCLUDE_DIR - Where to find the
12426 headers OSG_LIBRARIES - The libraries to link against for the OSG (use
12427 this)
12428 OSG_LIBRARY - The OSG library OSG_LIBRARY_DEBUG - The OSG debug library
12430 $OSGDIR is an environment variable that would correspond to the
12432 Created by Eric Wing.
12434 FindosgShadow
12436 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12437 nents. Each component is separate and you must opt in to each module.
12438 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12439 as these modules won’t do it for you. This is to allow you control
12440 over your own system piece by piece in case you need to opt out of cer‐
12441 tain components or change the Find behavior for a particular module
12442 (perhaps because the default FindOpenGL.cmake module doesn’t work with
12443 your system as an example). If you want to use a more convenient mod‐
12444 ule that includes everything, use the FindOpenSceneGraph.cmake instead
12445 of the Findosg*.cmake modules.
12446 Locate osgShadow This module defines
12448 OSGSHADOW_FOUND - Was osgShadow found? OSGSHADOW_INCLUDE_DIR - Where to
12450 find the headers OSGSHADOW_LIBRARIES - The libraries to link for
12451 osgShadow (use this)
12452 OSGSHADOW_LIBRARY - The osgShadow library OSGSHADOW_LIBRARY_DEBUG - The
12454 osgShadow debug library
12455 $OSGDIR is an environment variable that would correspond to the
12457 Created by Eric Wing.
12459 FindosgSim
12461 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12462 nents. Each component is separate and you must opt in to each module.
12463 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12464 as these modules won’t do it for you. This is to allow you control
12465 over your own system piece by piece in case you need to opt out of cer‐
12466 tain components or change the Find behavior for a particular module
12467 (perhaps because the default FindOpenGL.cmake module doesn’t work with
12468 your system as an example). If you want to use a more convenient mod‐
12469 ule that includes everything, use the FindOpenSceneGraph.cmake instead
12470 of the Findosg*.cmake modules.
12471 Locate osgSim This module defines
12473 OSGSIM_FOUND - Was osgSim found? OSGSIM_INCLUDE_DIR - Where to find the
12475 headers OSGSIM_LIBRARIES - The libraries to link for osgSim (use this)
12476 OSGSIM_LIBRARY - The osgSim library OSGSIM_LIBRARY_DEBUG - The osgSim
12478 debug library
12479 $OSGDIR is an environment variable that would correspond to the
12481 Created by Eric Wing.
12483 FindosgTerrain
12485 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12486 nents. Each component is separate and you must opt in to each module.
12487 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12488 as these modules won’t do it for you. This is to allow you control
12489 over your own system piece by piece in case you need to opt out of cer‐
12490 tain components or change the Find behavior for a particular module
12491 (perhaps because the default FindOpenGL.cmake module doesn’t work with
12492 your system as an example). If you want to use a more convenient mod‐
12493 ule that includes everything, use the FindOpenSceneGraph.cmake instead
12494 of the Findosg*.cmake modules.
12495 Locate osgTerrain This module defines
12497 OSGTERRAIN_FOUND - Was osgTerrain found? OSGTERRAIN_INCLUDE_DIR - Where
12499 to find the headers OSGTERRAIN_LIBRARIES - The libraries to link for
12500 osgTerrain (use this)
12501 OSGTERRAIN_LIBRARY - The osgTerrain library OSGTERRAIN_LIBRARY_DEBUG -
12503 The osgTerrain debug library
12504 $OSGDIR is an environment variable that would correspond to the
12506 Created by Eric Wing.
12508 FindosgText
12510 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12511 nents. Each component is separate and you must opt in to each module.
12512 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12513 as these modules won’t do it for you. This is to allow you control
12514 over your own system piece by piece in case you need to opt out of cer‐
12515 tain components or change the Find behavior for a particular module
12516 (perhaps because the default FindOpenGL.cmake module doesn’t work with
12517 your system as an example). If you want to use a more convenient mod‐
12518 ule that includes everything, use the FindOpenSceneGraph.cmake instead
12519 of the Findosg*.cmake modules.
12520 Locate osgText This module defines
12522 OSGTEXT_FOUND - Was osgText found? OSGTEXT_INCLUDE_DIR - Where to find
12524 the headers OSGTEXT_LIBRARIES - The libraries to link for osgText (use
12525 this)
12526 OSGTEXT_LIBRARY - The osgText library OSGTEXT_LIBRARY_DEBUG - The osg‐
12528 Text debug library
12529 $OSGDIR is an environment variable that would correspond to the
12531 Created by Eric Wing.
12533 FindosgUtil
12535 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12536 nents. Each component is separate and you must opt in to each module.
12537 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12538 as these modules won’t do it for you. This is to allow you control
12539 over your own system piece by piece in case you need to opt out of cer‐
12540 tain components or change the Find behavior for a particular module
12541 (perhaps because the default FindOpenGL.cmake module doesn’t work with
12542 your system as an example). If you want to use a more convenient mod‐
12543 ule that includes everything, use the FindOpenSceneGraph.cmake instead
12544 of the Findosg*.cmake modules.
12545 Locate osgUtil This module defines
12547 OSGUTIL_FOUND - Was osgUtil found? OSGUTIL_INCLUDE_DIR - Where to find
12549 the headers OSGUTIL_LIBRARIES - The libraries to link for osgUtil (use
12550 this)
12551 OSGUTIL_LIBRARY - The osgUtil library OSGUTIL_LIBRARY_DEBUG - The
12553 osgUtil debug library
12554 $OSGDIR is an environment variable that would correspond to the
12556 Created by Eric Wing.
12558 FindosgViewer
12560 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12561 nents. Each component is separate and you must opt in to each module.
12562 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12563 as these modules won’t do it for you. This is to allow you control
12564 over your own system piece by piece in case you need to opt out of cer‐
12565 tain components or change the Find behavior for a particular module
12566 (perhaps because the default FindOpenGL.cmake module doesn’t work with
12567 your system as an example). If you want to use a more convenient mod‐
12568 ule that includes everything, use the FindOpenSceneGraph.cmake instead
12569 of the Findosg*.cmake modules.
12570 Locate osgViewer This module defines
12572 OSGVIEWER_FOUND - Was osgViewer found? OSGVIEWER_INCLUDE_DIR - Where to
12574 find the headers OSGVIEWER_LIBRARIES - The libraries to link for
12575 osgViewer (use this)
12576 OSGVIEWER_LIBRARY - The osgViewer library OSGVIEWER_LIBRARY_DEBUG - The
12578 osgViewer debug library
12579 $OSGDIR is an environment variable that would correspond to the
12581 Created by Eric Wing.
12583 FindosgVolume
12585 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12586 nents. Each component is separate and you must opt in to each module.
12587 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12588 as these modules won’t do it for you. This is to allow you control
12589 over your own system piece by piece in case you need to opt out of cer‐
12590 tain components or change the Find behavior for a particular module
12591 (perhaps because the default FindOpenGL.cmake module doesn’t work with
12592 your system as an example). If you want to use a more convenient mod‐
12593 ule that includes everything, use the FindOpenSceneGraph.cmake instead
12594 of the Findosg*.cmake modules.
12595 Locate osgVolume This module defines
12597 OSGVOLUME_FOUND - Was osgVolume found? OSGVOLUME_INCLUDE_DIR - Where to
12599 find the headers OSGVOLUME_LIBRARIES - The libraries to link for
12600 osgVolume (use this)
12601 OSGVOLUME_LIBRARY - The osgVolume library OSGVOLUME_LIBRARY_DEBUG - The
12603 osgVolume debug library
12604 $OSGDIR is an environment variable that would correspond to the
12606 Created by Eric Wing.
12608 FindosgWidget
12610 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12611 nents. Each component is separate and you must opt in to each module.
12612 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12613 as these modules won’t do it for you. This is to allow you control
12614 over your own system piece by piece in case you need to opt out of cer‐
12615 tain components or change the Find behavior for a particular module
12616 (perhaps because the default FindOpenGL.cmake module doesn’t work with
12617 your system as an example). If you want to use a more convenient mod‐
12618 ule that includes everything, use the FindOpenSceneGraph.cmake instead
12619 of the Findosg*.cmake modules.
12620 Locate osgWidget This module defines
12622 OSGWIDGET_FOUND - Was osgWidget found? OSGWIDGET_INCLUDE_DIR - Where to
12624 find the headers OSGWIDGET_LIBRARIES - The libraries to link for osg‐
12625 Widget (use this)
12626 OSGWIDGET_LIBRARY - The osgWidget library OSGWIDGET_LIBRARY_DEBUG - The
12628 osgWidget debug library
12629 $OSGDIR is an environment variable that would correspond to the
12631 FindosgWidget.cmake tweaked from Findosg* suite as created by Eric
12633 Wing.
12634 FindPatch
12636 The module defines the following variables:
12637 Patch_EXECUTABLE
12639 Path to patch command-line executable.
12640 Patch_FOUND
12642 True if the patch command-line executable was found.
12643 The following IMPORTED targets are also defined:
12645 Patch::patch
12647 The command-line executable.
12648 Example usage:
12650 find_package(Patch)
12652 if(Patch_FOUND)
12653 message("Patch found: ${Patch_EXECUTABLE}")
12654 endif()
12655 FindPerlLibs
12657 Find Perl libraries
12658 This module finds if PERL is installed and determines where the include
12660 files and libraries are. It also determines what the name of the
12661 library is. This code sets the following variables:
12662 PERLLIBS_FOUND = True if perl.h & libperl were found
12664 PERL_INCLUDE_PATH = path to where perl.h is found
12665 PERL_LIBRARY = path to libperl
12666 PERL_EXECUTABLE = full path to the perl binary
12667 The minimum required version of Perl can be specified using the stan‐
12669 dard syntax, e.g. find_package(PerlLibs 6.0)
12670 The following variables are also available if needed
12672 (introduced after CMake 2.6.4)
12673 PERL_SITESEARCH = path to the sitesearch install dir (-V:installsitesearch)
12675 PERL_SITEARCH = path to the sitelib install directory (-V:installsitearch)
12676 PERL_SITELIB = path to the sitelib install directory (-V:installsitelib)
12677 PERL_VENDORARCH = path to the vendor arch install directory (-V:installvendorarch)
12678 PERL_VENDORLIB = path to the vendor lib install directory (-V:installvendorlib)
12679 PERL_ARCHLIB = path to the core arch lib install directory (-V:archlib)
12680 PERL_PRIVLIB = path to the core priv lib install directory (-V:privlib)
12681 PERL_UPDATE_ARCHLIB = path to the update arch lib install directory (-V:installarchlib)
12682 PERL_UPDATE_PRIVLIB = path to the update priv lib install directory (-V:installprivlib)
12683 PERL_EXTRA_C_FLAGS = Compilation flags used to build perl
12684 FindPerl
12686 Find perl
12687 this module looks for Perl
12689 PERL_EXECUTABLE - the full path to perl
12691 PERL_FOUND - If false, don't attempt to use perl.
12692 PERL_VERSION_STRING - version of perl found (since CMake 2.8.8)
12693 FindPHP4
12695 Find PHP4
12696 This module finds if PHP4 is installed and determines where the include
12698 files and libraries are. It also determines what the name of the
12699 library is. This code sets the following variables:
12700 PHP4_INCLUDE_PATH = path to where php.h can be found
12702 PHP4_EXECUTABLE = full path to the php4 binary
12703 FindPhysFS
12705 Locate PhysFS library This module defines PHYSFS_LIBRARY, the name of
12706 the library to link against PHYSFS_FOUND, if false, do not try to link
12707 to PHYSFS PHYSFS_INCLUDE_DIR, where to find physfs.h
12708 $PHYSFSDIR is an environment variable that would correspond to the
12710 Created by Eric Wing.
12712 FindPike
12714 Find Pike
12715 This module finds if PIKE is installed and determines where the include
12717 files and libraries are. It also determines what the name of the
12718 library is. This code sets the following variables:
12719 PIKE_INCLUDE_PATH = path to where program.h is found
12721 PIKE_EXECUTABLE = full path to the pike binary
12722 FindPkgConfig
12724 A pkg-config module for CMake.
12725 Finds the pkg-config executable and adds the pkg_get_variable(),
12727 pkg_check_modules() and pkg_search_module() commands. The following
12728 variables will also be set:
12729 PKG_CONFIG_FOUND
12731 if pkg-config executable was found
12732 PKG_CONFIG_EXECUTABLE
12734 pathname of the pkg-config program
12735 PKG_CONFIG_VERSION_STRING
12737 version of pkg-config (since CMake 2.8.8)
12738 pkg_check_modules
12740 Checks for all the given modules, setting a variety of result
12741 variables in the calling scope.
12742 pkg_check_modules(<prefix>
12744 [REQUIRED] [QUIET]
12745 [NO_CMAKE_PATH]
12746 [NO_CMAKE_ENVIRONMENT_PATH]
12747 [IMPORTED_TARGET [GLOBAL]]
12748 <moduleSpec> [<moduleSpec>...])
12749 When the REQUIRED argument is given, the command will fail with
12751 an error if module(s) could not be found.
12752 When the QUIET argument is given, no status messages will be
12754 printed.
12755 By default, if CMAKE_MINIMUM_REQUIRED_VERSION is 3.1 or later,
12757 or if PKG_CONFIG_USE_CMAKE_PREFIX_PATH is set to a boolean True
12758 value, then the CMAKE_PREFIX_PATH, CMAKE_FRAMEWORK_PATH, and
12759 CMAKE_APPBUNDLE_PATH cache and environment variables will be
12760 added to the pkg-config search path. The NO_CMAKE_PATH and
12761 NO_CMAKE_ENVIRONMENT_PATH arguments disable this behavior for
12762 the cache variables and environment variables respectively.
12763 The IMPORTED_TARGET argument will create an imported target
12765 named PkgConfig::<prefix> that can be passed directly as an
12766 argument to target_link_libraries(). The GLOBAL argument will
12767 make the imported target available in global scope.
12768 Each <moduleSpec> can be either a bare module name or it can be
12770 a module name with a version constraint (operators =, <, >, <=
12771 and >= are supported). The following are examples for a module
12772 named foo with various constraints:
12773 · foo matches any version.
12775 · foo<2 only matches versions before 2.
12777 · foo>=3.1 matches any version from 3.1 or later.
12779 · foo=1.2.3 requires that foo must be exactly version 1.2.3.
12781 The following variables may be set upon return. Two sets of
12783 values exist: One for the common case (<XXX> = <prefix>) and
12784 another for the information pkg-config provides when called with
12785 the --static option (<XXX> = <prefix>_STATIC).
12786 <XXX>_FOUND
12788 set to 1 if module(s) exist
12789 <XXX>_LIBRARIES
12791 only the libraries (without the ‘-l’)
12792 <XXX>_LINK_LIBRARIES
12794 the libraries and their absolute paths
12795 <XXX>_LIBRARY_DIRS
12797 the paths of the libraries (without the ‘-L’)
12798 <XXX>_LDFLAGS
12800 all required linker flags
12801 <XXX>_LDFLAGS_OTHER
12803 all other linker flags
12804 <XXX>_INCLUDE_DIRS
12806 the ‘-I’ preprocessor flags (without the ‘-I’)
12807 <XXX>_CFLAGS
12809 all required cflags
12810 <XXX>_CFLAGS_OTHER
12812 the other compiler flags
12813 All but <XXX>_FOUND may be a ;-list if the associated variable
12815 returned from pkg-config has multiple values.
12816 There are some special variables whose prefix depends on the
12818 number of <moduleSpec> given. When there is only one <module‐
12819 Spec>, <YYY> will simply be <prefix>, but if two or more <mod‐
12820 uleSpec> items are given, <YYY> will be <prefix>_<moduleName>.
12821 <YYY>_VERSION
12823 version of the module
12824 <YYY>_PREFIX
12826 prefix directory of the module
12827 <YYY>_INCLUDEDIR
12829 include directory of the module
12830 <YYY>_LIBDIR
12832 lib directory of the module
12833 Examples:
12835 pkg_check_modules (GLIB2 glib-2.0)
12837 Looks for any version of glib2. If found, the output variable
12839 GLIB2_VERSION will hold the actual version found.
12840 pkg_check_modules (GLIB2 glib-2.0>=2.10)
12842 Looks for at least version 2.10 of glib2. If found, the output
12844 variable GLIB2_VERSION will hold the actual version found.
12845 pkg_check_modules (FOO glib-2.0>=2.10 gtk+-2.0)
12847 Looks for both glib2-2.0 (at least version 2.10) and any version
12849 of gtk2+-2.0. Only if both are found will FOO be considered
12850 found. The FOO_glib-2.0_VERSION and FOO_gtk+-2.0_VERSION vari‐
12851 ables will be set to their respective found module versions.
12852 pkg_check_modules (XRENDER REQUIRED xrender)
12854 Requires any version of xrender. Example output variables set
12856 by a successful call:
12857 XRENDER_LIBRARIES=Xrender;X11
12859 XRENDER_STATIC_LIBRARIES=Xrender;X11;pthread;Xau;Xdmcp
12860 pkg_search_module
12862 The behavior of this command is the same as pkg_check_modules(),
12863 except that rather than checking for all the specified modules,
12864 it searches for just the first successful match.
12865 pkg_search_module(<prefix>
12867 [REQUIRED] [QUIET]
12868 [NO_CMAKE_PATH]
12869 [NO_CMAKE_ENVIRONMENT_PATH]
12870 [IMPORTED_TARGET [GLOBAL]]
12871 <moduleSpec> [<moduleSpec>...])
12872 If a module is found, the <prefix>_MODULE_NAME variable will
12874 contain the name of the matching module. This variable can be
12875 used if you need to run pkg_get_variable().
12876 Example:
12878 pkg_search_module (BAR libxml-2.0 libxml2 libxml>=2)
12880 pkg_get_variable
12882 Retrieves the value of a pkg-config variable varName and stores
12883 it in the result variable resultVar in the calling scope.
12884 pkg_get_variable(<resultVar> <moduleName> <varName>)
12886 If pkg-config returns multiple values for the specified vari‐
12888 able, resultVar will contain a ;-list.
12889 For example:
12891 pkg_get_variable(GI_GIRDIR gobject-introspection-1.0 girdir)
12893 Variables Affecting Behavior
12895 PKG_CONFIG_EXECUTABLE
12896 This can be set to the path of the pkg-config executable. If
12897 not provided, it will be set by the module as a result of call‐
12898 ing find_program() internally. The PKG_CONFIG environment vari‐
12899 able can be used as a hint.
12900 PKG_CONFIG_USE_CMAKE_PREFIX_PATH
12902 Specifies whether pkg_check_modules() and pkg_search_module()
12903 should add the paths in the CMAKE_PREFIX_PATH, CMAKE_FRAME‐
12904 WORK_PATH and CMAKE_APPBUNDLE_PATH cache and environment vari‐
12905 ables to the pkg-config search path.
12906 If this variable is not set, this behavior is enabled by default
12908 if CMAKE_MINIMUM_REQUIRED_VERSION is 3.1 or later, disabled oth‐
12909 erwise.
12910 FindPNG
12912 Find libpng, the official reference library for the PNG image format.
12913 Imported targets
12915 This module defines the following IMPORTED target:
12916 PNG::PNG
12918 The libpng library, if found.
12919 Result variables
12921 This module will set the following variables in your project:
12922 PNG_INCLUDE_DIRS
12924 where to find png.h, etc.
12925 PNG_LIBRARIES
12927 the libraries to link against to use PNG.
12928 PNG_DEFINITIONS
12930 You should add_definitions(${PNG_DEFINITIONS}) before compiling
12931 code that includes png library files.
12932 PNG_FOUND
12934 If false, do not try to use PNG.
12935 PNG_VERSION_STRING
12937 the version of the PNG library found (since CMake 2.8.8)
12938 Obsolete variables
12940 The following variables may also be set, for backwards compatibility:
12941 PNG_LIBRARY
12943 where to find the PNG library.
12944 PNG_INCLUDE_DIR
12946 where to find the PNG headers (same as PNG_INCLUDE_DIRS)
12947 Since PNG depends on the ZLib compression library, none of the above
12949 will be defined unless ZLib can be found.
12950 FindPostgreSQL
12952 Find the PostgreSQL installation.
12953 IMPORTED Targets
12955 This module defines IMPORTED target PostgreSQL::PostgreSQL if Post‐
12956 greSQL has been found.
12957 Result Variables
12959 This module will set the following variables in your project:
12960 PostgreSQL_FOUND
12962 True if PostgreSQL is found.
12963 PostgreSQL_LIBRARIES
12965 the PostgreSQL libraries needed for linking
12966 PostgreSQL_INCLUDE_DIRS
12968 the directories of the PostgreSQL headers
12969 PostgreSQL_LIBRARY_DIRS
12971 the link directories for PostgreSQL libraries
12972 PostgreSQL_VERSION_STRING
12974 the version of PostgreSQL found
12975 FindProducer
12977 Though Producer isn’t directly part of OpenSceneGraph, its primary user
12978 is OSG so I consider this part of the Findosg* suite used to find Open‐
12979 SceneGraph components. You’ll notice that I accept OSGDIR as an envi‐
12980 ronment path.
12981 Each component is separate and you must opt in to each module. You
12983 must also opt into OpenGL (and OpenThreads?) as these modules won’t do
12984 it for you. This is to allow you control over your own system piece by
12985 piece in case you need to opt out of certain components or change the
12986 Find behavior for a particular module (perhaps because the default
12987 FindOpenGL.cmake module doesn’t work with your system as an example).
12988 If you want to use a more convenient module that includes everything,
12989 use the FindOpenSceneGraph.cmake instead of the Findosg*.cmake modules.
12990 Locate Producer This module defines PRODUCER_LIBRARY PRODUCER_FOUND, if
12992 false, do not try to link to Producer PRODUCER_INCLUDE_DIR, where to
12993 find the headers
12994 $PRODUCER_DIR is an environment variable that would correspond to the
12996 Created by Eric Wing.
12998 FindProtobuf
13000 Locate and configure the Google Protocol Buffers library.
13001 The following variables can be set and are optional:
13003 Protobuf_SRC_ROOT_FOLDER
13005 When compiling with MSVC, if this cache variable is set the pro‐
13006 tobuf-default VS project build locations (vsprojects/Debug and
13007 vsprojects/Release or vsprojects/x64/Debug and vspro‐
13008 jects/x64/Release) will be searched for libraries and binaries.
13009 Protobuf_IMPORT_DIRS
13011 List of additional directories to be searched for imported
13012 .proto files.
13013 Protobuf_DEBUG
13015 Show debug messages.
13016 Protobuf_USE_STATIC_LIBS
13018 Set to ON to force the use of the static libraries. Default is
13019 OFF.
13020 Defines the following variables:
13022 Protobuf_FOUND
13024 Found the Google Protocol Buffers library (libprotobuf & header
13025 files)
13026 Protobuf_VERSION
13028 Version of package found.
13029 Protobuf_INCLUDE_DIRS
13031 Include directories for Google Protocol Buffers
13032 Protobuf_LIBRARIES
13034 The protobuf libraries
13035 Protobuf_PROTOC_LIBRARIES
13037 The protoc libraries
13038 Protobuf_LITE_LIBRARIES
13040 The protobuf-lite libraries
13041 The following IMPORTED targets are also defined:
13043 protobuf::libprotobuf
13045 The protobuf library.
13046 protobuf::libprotobuf-lite
13048 The protobuf lite library.
13049 protobuf::libprotoc
13051 The protoc library.
13052 protobuf::protoc
13054 The protoc compiler.
13055 The following cache variables are also available to set or use:
13057 Protobuf_LIBRARY
13059 The protobuf library
13060 Protobuf_PROTOC_LIBRARY
13062 The protoc library
13063 Protobuf_INCLUDE_DIR
13065 The include directory for protocol buffers
13066 Protobuf_PROTOC_EXECUTABLE
13068 The protoc compiler
13069 Protobuf_LIBRARY_DEBUG
13071 The protobuf library (debug)
13072 Protobuf_PROTOC_LIBRARY_DEBUG
13074 The protoc library (debug)
13075 Protobuf_LITE_LIBRARY
13077 The protobuf lite library
13078 Protobuf_LITE_LIBRARY_DEBUG
13080 The protobuf lite library (debug)
13081 Example:
13083 find_package(Protobuf REQUIRED)
13085 include_directories(${Protobuf_INCLUDE_DIRS})
13086 include_directories(${CMAKE_CURRENT_BINARY_DIR})
13087 protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS foo.proto)
13088 protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS EXPORT_MACRO DLL_EXPORT foo.proto)
13089 protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS DESCRIPTORS PROTO_DESCS foo.proto)
13090 protobuf_generate_python(PROTO_PY foo.proto)
13091 add_executable(bar bar.cc ${PROTO_SRCS} ${PROTO_HDRS})
13092 target_link_libraries(bar ${Protobuf_LIBRARIES})
13093 NOTE:
13095 The protobuf_generate_cpp and protobuf_generate_python functions and
13096 add_executable() or add_library() calls only work properly within
13097 the same directory.
13098 protobuf_generate_cpp
13100 Add custom commands to process .proto files to C++:
13101 protobuf_generate_cpp (<SRCS> <HDRS>
13103 [DESCRIPTORS <DESC>] [EXPORT_MACRO <MACRO>] [<ARGN>...])
13104 SRCS Variable to define with autogenerated source files
13106 HDRS Variable to define with autogenerated header files
13108 DESCRIPTORS
13110 Variable to define with autogenerated descriptor files,
13111 if requested.
13112 EXPORT_MACRO
13114 is a macro which should expand to __declspec(dllexport)
13115 or __declspec(dllimport) depending on what is being com‐
13116 piled.
13117 ARGN .proto files
13119 protobuf_generate_python
13121 Add custom commands to process .proto files to Python:
13122 protobuf_generate_python (<PY> [<ARGN>...])
13124 PY Variable to define with autogenerated Python files
13126 ARGN .proto filess
13128 FindPython
13130 Find Python interpreter, compiler and development environment (include
13131 directories and libraries).
13132 The following components are supported:
13134 · Interpreter: search for Python interpreter.
13136 · Compiler: search for Python compiler. Only offered by IronPython.
13138 · Development: search for development artifacts (include directories
13140 and libraries).
13141 · NumPy: search for NumPy include directories.
13143 If no COMPONENTS are specified, Interpreter is assumed.
13145 To ensure consistent versions between components Interpreter, Compiler,
13147 Development and NumPy, specify all components at the same time:
13148 find_package (Python COMPONENTS Interpreter Development)
13150 This module looks preferably for version 3 of Python. If not found,
13152 version 2 is searched. To manage concurrent versions 3 and 2 of
13153 Python, use FindPython3 and FindPython2 modules rather than this one.
13154 NOTE:
13156 If components Interpreter and Development are both specified, this
13157 module search only for interpreter with same platform architecture
13158 as the one defined by CMake configuration. This contraint does not
13159 apply if only Interpreter component is specified.
13160 Imported Targets
13162 This module defines the following Imported Targets (when CMAKE_ROLE is
13163 PROJECT):
13164 Python::Interpreter
13166 Python interpreter. Target defined if component Interpreter is
13167 found.
13168 Python::Compiler
13170 Python compiler. Target defined if component Compiler is found.
13171 Python::Python
13173 Python library for Python embedding. Target defined if component
13174 Development is found.
13175 Python::Module
13177 Python library for Python module. Target defined if component
13178 Development is found.
13179 Python::NumPy
13181 NumPy Python library. Target defined if component NumPy is
13182 found.
13183 Result Variables
13185 This module will set the following variables in your project (see Stan‐
13186 dard Variable Names):
13187 Python_FOUND
13189 System has the Python requested components.
13190 Python_Interpreter_FOUND
13192 System has the Python interpreter.
13193 Python_EXECUTABLE
13195 Path to the Python interpreter.
13196 Python_INTERPRETER_ID
13198 A short string unique to the interpreter. Possible values
13200 include:
13201 · Python
13203 · ActivePython
13205 · Anaconda
13207 · Canopy
13209 · IronPython
13211 Python_STDLIB
13213 Standard platform independent installation directory.
13214 Information returned by distutils.syscon‐
13216 fig.get_python_lib(plat_specific=False,standard_lib=True).
13217 Python_STDARCH
13219 Standard platform dependent installation directory.
13220 Information returned by distutils.syscon‐
13222 fig.get_python_lib(plat_specific=True,standard_lib=True).
13223 Python_SITELIB
13225 Third-party platform independent installation directory.
13226 Information returned by distutils.syscon‐
13228 fig.get_python_lib(plat_specific=False,standard_lib=False).
13229 Python_SITEARCH
13231 Third-party platform dependent installation directory.
13232 Information returned by distutils.syscon‐
13234 fig.get_python_lib(plat_specific=True,standard_lib=False).
13235 Python_Compiler_FOUND
13237 System has the Python compiler.
13238 Python_COMPILER
13240 Path to the Python compiler. Only offered by IronPython.
13241 Python_COMPILER_ID
13243 A short string unique to the compiler. Possible values include:
13245 · IronPython
13247 Python_Development_FOUND
13249 System has the Python development artifacts.
13250 Python_INCLUDE_DIRS
13252 The Python include directories.
13253 Python_LIBRARIES
13255 The Python libraries.
13256 Python_LIBRARY_DIRS
13258 The Python library directories.
13259 Python_RUNTIME_LIBRARY_DIRS
13261 The Python runtime library directories.
13262 Python_VERSION
13264 Python version.
13265 Python_VERSION_MAJOR
13267 Python major version.
13268 Python_VERSION_MINOR
13270 Python minor version.
13271 Python_VERSION_PATCH
13273 Python patch version.
13274 Python_NumPy_FOUND
13276 System has the NumPy.
13277 Python_NumPy_INCLUDE_DIRS
13279 The NumPy include directries.
13280 Python_NumPy_VERSION
13282 The NumPy version.
13283 Hints
13285 Python_ROOT_DIR
13286 Define the root directory of a Python installation.
13287 Python_USE_STATIC_LIBS
13289 · If not defined, search for shared libraries and static
13291 libraries in that order.
13292 · If set to TRUE, search only for static libraries.
13294 · If set to FALSE, search only for shared libraries.
13296 Python_FIND_ABI
13298 This variable defines which ABIs, as defined in PEP 3149, should
13299 be searched.
13300 NOTE:
13302 This hint will be honored only when searched for Python ver‐
13303 sion 3.
13304 NOTE:
13306 If Python_FIND_ABI is not defined, any ABI will be searched.
13307 The Python_FIND_ABI variable is a 3-tuple specifying, in that
13309 order, pydebug (d), pymalloc (m) and unicode (u) flags. Each
13310 element can be set to one of the following:
13311 · ON: Corresponding flag is selected.
13313 · OFF: Corresponding flag is not selected.
13315 · ANY: The two posibilties (ON and OFF) will be searched.
13317 From this 3-tuple, various ABIs will be searched starting from
13319 the most specialized to the most general. Moreover, debug ver‐
13320 sions will be searched after non-debug ones.
13321 For example, if we have:
13323 set (Python_FIND_ABI "ON" "ANY" "ANY")
13325 The following flags combinations will be appended, in that
13327 order, to the artifact names: dmu, dm, du, and d.
13328 And to search any possible ABIs:
13330 set (Python_FIND_ABI "ANY" "ANY" "ANY")
13332 The following combinations, in that order, will be used: mu, m,
13334 u, <empty>, dmu, dm, du and d.
13335 NOTE:
13337 This hint is useful only on POSIX systems. So, on Windows
13338 systems, when Python_FIND_ABI is defined, Python distribu‐
13339 tions from python.org will be found only if value for each
13340 flag is OFF or ANY.
13341 Python_FIND_STRATEGY
13343 This variable defines how lookup will be done. The
13344 Python_FIND_STRATEGY variable can be set to empty or one of the
13345 following:
13346 · VERSION: Try to find the most recent version in all specified
13348 locations. This is the default if policy CMP0094 is undefined
13349 or set to OLD.
13350 · LOCATION: Stops lookup as soon as a version satisfying version
13352 constraints is founded. This is the default if policy CMP0094
13353 is set to NEW.
13354 Python_FIND_REGISTRY
13356 On Windows the Python_FIND_REGISTRY variable determine the order
13357 of preference between registry and environment variables. the
13358 Python_FIND_REGISTRY variable can be set to empty or one of the
13359 following:
13360 · FIRST: Try to use registry before environment variables. This
13362 is the default.
13363 · LAST: Try to use registry after environment variables.
13365 · NEVER: Never try to use registry.
13367 Python_FIND_FRAMEWORK
13369 On macOS the Python_FIND_FRAMEWORK variable determine the order
13370 of preference between Apple-style and unix-style package compo‐
13371 nents. This variable can be set to empty or take same values as
13372 CMAKE_FIND_FRAMEWORK variable.
13373 NOTE:
13375 Value ONLY is not supported so FIRST will be used instead.
13376 If Python_FIND_FRAMEWORK is not defined, CMAKE_FIND_FRAMEWORK
13378 variable will be used, if any.
13379 Python_FIND_VIRTUALENV
13381 This variable defines the handling of virtual environments. It
13382 is meaningfull only when a virtual environment is active (i.e.
13383 the activate script has been evaluated). In this case, it takes
13384 precedence over Python_FIND_REGISTRY and CMAKE_FIND_FRAMEWORK
13385 variables. The Python_FIND_VIRTUALENV variable can be set to
13386 empty or one of the following:
13387 · FIRST: The virtual environment is used before any other stan‐
13389 dard paths to look-up for the interpreter. This is the
13390 default.
13391 · ONLY: Only the virtual environment is used to look-up for the
13393 interpreter.
13394 · STANDARD: The virtual environment is not used to look-up for
13396 the interpreter. In this case, variable Python_FIND_REGISTRY
13397 (Windows) or CMAKE_FIND_FRAMEWORK (macOS) can be set with
13398 value LAST or NEVER to select preferably the interpreter from
13399 the virtual environment.
13400 NOTE:
13402 If the component Development is requested, it is strongly
13403 recommended to also include the component Interpreter to get
13404 expected result.
13405 Artifacts Specification
13407 To solve special cases, it is possible to specify directly the arti‐
13408 facts by setting the following variables:
13409 Python_EXECUTABLE
13411 The path to the interpreter.
13412 Python_COMPILER
13414 The path to the compiler.
13415 Python_LIBRARY
13417 The path to the library. It will be used to compute the vari‐
13418 ables Python_LIBRARIES, Python_LIBRAY_DIRS and Python_RUN‐
13419 TIME_LIBRARY_DIRS.
13420 Python_INCLUDE_DIR
13422 The path to the directory of the Python headers. It will be used
13423 to compute the variable Python_INCLUDE_DIRS.
13424 Python_NumPy_INCLUDE_DIR
13426 The path to the directory of the NumPy headers. It will be used
13427 to compute the variable Python_NumPy_INCLUDE_DIRS.
13428 NOTE:
13430 All paths must be absolute. Any artifact specified with a relative
13431 path will be ignored.
13432 NOTE:
13434 When an artifact is specified, all HINTS will be ignored and no
13435 search will be performed for this artifact.
13436 If more than one artifact is specified, it is the user’s respons‐
13438 ability to ensure the consistency of the various artifacts.
13439 Commands
13441 This module defines the command Python_add_library (when CMAKE_ROLE is
13442 PROJECT), which has the same semantics as add_library() and adds a
13443 dependency to target Python::Python or, when library type is MODULE, to
13444 target Python::Module and takes care of Python module naming rules:
13445 Python_add_library (my_module MODULE src1.cpp)
13447 If library type is not specified, MODULE is assumed.
13449 FindPython2
13451 Find Python 2 interpreter, compiler and development environment
13452 (include directories and libraries).
13453 The following components are supported:
13455 · Interpreter: search for Python 2 interpreter
13457 · Compiler: search for Python 2 compiler. Only offered by IronPython.
13459 · Development: search for development artifacts (include directories
13461 and libraries)
13462 · NumPy: search for NumPy include directories.
13464 If no COMPONENTS are specified, Interpreter is assumed.
13466 To ensure consistent versions between components Interpreter, Compiler,
13468 Development and NumPy, specify all components at the same time:
13469 find_package (Python2 COMPONENTS Interpreter Development)
13471 This module looks only for version 2 of Python. This module can be used
13473 concurrently with FindPython3 module to use both Python versions.
13474 The FindPython module can be used if Python version does not matter for
13476 you.
13477 NOTE:
13479 If components Interpreter and Development are both specified, this
13480 module search only for interpreter with same platform architecture
13481 as the one defined by CMake configuration. This contraint does not
13482 apply if only Interpreter component is specified.
13483 Imported Targets
13485 This module defines the following Imported Targets (when CMAKE_ROLE is
13486 PROJECT):
13487 Python2::Interpreter
13489 Python 2 interpreter. Target defined if component Interpreter is
13490 found.
13491 Python2::Compiler
13493 Python 2 compiler. Target defined if component Compiler is
13494 found.
13495 Python2::Python
13497 Python 2 library for Python embedding. Target defined if compo‐
13498 nent Development is found.
13499 Python2::Module
13501 Python 2 library for Python module. Target defined if component
13502 Development is found.
13503 Python2::NumPy
13505 NumPy library for Python 2. Target defined if component NumPy is
13506 found.
13507 Result Variables
13509 This module will set the following variables in your project (see Stan‐
13510 dard Variable Names):
13511 Python2_FOUND
13513 System has the Python 2 requested components.
13514 Python2_Interpreter_FOUND
13516 System has the Python 2 interpreter.
13517 Python2_EXECUTABLE
13519 Path to the Python 2 interpreter.
13520 Python2_INTERPRETER_ID
13522 A short string unique to the interpreter. Possible values
13524 include:
13525 · Python
13527 · ActivePython
13529 · Anaconda
13531 · Canopy
13533 · IronPython
13535 Python2_STDLIB
13537 Standard platform independent installation directory.
13538 Information returned by distutils.syscon‐
13540 fig.get_python_lib(plat_specific=False,standard_lib=True).
13541 Python2_STDARCH
13543 Standard platform dependent installation directory.
13544 Information returned by distutils.syscon‐
13546 fig.get_python_lib(plat_specific=True,standard_lib=True).
13547 Python2_SITELIB
13549 Third-party platform independent installation directory.
13550 Information returned by distutils.syscon‐
13552 fig.get_python_lib(plat_specific=False,standard_lib=False).
13553 Python2_SITEARCH
13555 Third-party platform dependent installation directory.
13556 Information returned by distutils.syscon‐
13558 fig.get_python_lib(plat_specific=True,standard_lib=False).
13559 Python2_Compiler_FOUND
13561 System has the Python 2 compiler.
13562 Python2_COMPILER
13564 Path to the Python 2 compiler. Only offered by IronPython.
13565 Python2_COMPILER_ID
13567 A short string unique to the compiler. Possible values include:
13569 · IronPython
13571 Python2_Development_FOUND
13573 System has the Python 2 development artifacts.
13574 Python2_INCLUDE_DIRS
13576 The Python 2 include directories.
13577 Python2_LIBRARIES
13579 The Python 2 libraries.
13580 Python2_LIBRARY_DIRS
13582 The Python 2 library directories.
13583 Python2_RUNTIME_LIBRARY_DIRS
13585 The Python 2 runtime library directories.
13586 Python2_VERSION
13588 Python 2 version.
13589 Python2_VERSION_MAJOR
13591 Python 2 major version.
13592 Python2_VERSION_MINOR
13594 Python 2 minor version.
13595 Python2_VERSION_PATCH
13597 Python 2 patch version.
13598 Python2_NumPy_FOUND
13600 System has the NumPy.
13601 Python2_NumPy_INCLUDE_DIRS
13603 The NumPy include directries.
13604 Python2_NumPy_VERSION
13606 The NumPy version.
13607 Hints
13609 Python2_ROOT_DIR
13610 Define the root directory of a Python 2 installation.
13611 Python2_USE_STATIC_LIBS
13613 · If not defined, search for shared libraries and static
13615 libraries in that order.
13616 · If set to TRUE, search only for static libraries.
13618 · If set to FALSE, search only for shared libraries.
13620 Python2_FIND_STRATEGY
13622 This variable defines how lookup will be done. The
13623 Python2_FIND_STRATEGY variable can be set to empty or one of the
13624 following:
13625 · VERSION: Try to find the most recent version in all specified
13627 locations. This is the default if policy CMP0094 is undefined
13628 or set to OLD.
13629 · LOCATION: Stops lookup as soon as a version satisfying version
13631 constraints is founded. This is the default if policy CMP0094
13632 is set to NEW.
13633 Python2_FIND_REGISTRY
13635 On Windows the Python2_FIND_REGISTRY variable determine the
13636 order of preference between registry and environment variables.
13637 the Python2_FIND_REGISTRY variable can be set to empty or one of
13638 the following:
13639 · FIRST: Try to use registry before environment variables. This
13641 is the default.
13642 · LAST: Try to use registry after environment variables.
13644 · NEVER: Never try to use registry.
13646 Python2_FIND_FRAMEWORK
13648 On macOS the Python2_FIND_FRAMEWORK variable determine the order
13649 of preference between Apple-style and unix-style package compo‐
13650 nents. This variable can be set to empty or take same values as
13651 CMAKE_FIND_FRAMEWORK variable.
13652 NOTE:
13654 Value ONLY is not supported so FIRST will be used instead.
13655 If Python2_FIND_FRAMEWORK is not defined, CMAKE_FIND_FRAMEWORK
13657 variable will be used, if any.
13658 Python2_FIND_VIRTUALENV
13660 This variable defines the handling of virtual environments. It
13661 is meaningfull only when a virtual environment is active (i.e.
13662 the activate script has been evaluated). In this case, it takes
13663 precedence over Python2_FIND_REGISTRY and CMAKE_FIND_FRAMEWORK
13664 variables. The Python2_FIND_VIRTUALENV variable can be set to
13665 empty or one of the following:
13666 · FIRST: The virtual environment is used before any other stan‐
13668 dard paths to look-up for the interpreter. This is the
13669 default.
13670 · ONLY: Only the virtual environment is used to look-up for the
13672 interpreter.
13673 · STANDARD: The virtual environment is not used to look-up for
13675 the interpreter. In this case, variable Python2_FIND_REGISTRY
13676 (Windows) or CMAKE_FIND_FRAMEWORK (macOS) can be set with
13677 value LAST or NEVER to select preferably the interpreter from
13678 the virtual environment.
13679 NOTE:
13681 If the component Development is requested, it is strongly
13682 recommended to also include the component Interpreter to get
13683 expected result.
13684 Artifacts Specification
13686 To solve special cases, it is possible to specify directly the arti‐
13687 facts by setting the following variables:
13688 Python2_EXECUTABLE
13690 The path to the interpreter.
13691 Python2_COMPILER
13693 The path to the compiler.
13694 Python2_LIBRARY
13696 The path to the library. It will be used to compute the vari‐
13697 ables Python2_LIBRARIES, Python2_LIBRAY_DIRS and Python2_RUN‐
13698 TIME_LIBRARY_DIRS.
13699 Python2_INCLUDE_DIR
13701 The path to the directory of the Python headers. It will be used
13702 to compute the variable Python2_INCLUDE_DIRS.
13703 Python2_NumPy_INCLUDE_DIR
13705 The path to the directory of the NumPy headers. It will be used
13706 to compute the variable Python2_NumPy_INCLUDE_DIRS.
13707 NOTE:
13709 All paths must be absolute. Any artifact specified with a relative
13710 path will be ignored.
13711 NOTE:
13713 When an artifact is specified, all HINTS will be ignored and no
13714 search will be performed for this artifact.
13715 If more than one artifact is specified, it is the user’s respons‐
13717 ability to ensure the consistency of the various artifacts.
13718 Commands
13720 This module defines the command Python_add_library (when CMAKE_ROLE is
13721 PROJECT), which has the same semantics as add_library() and adds a
13722 dependency to target Python2::Python or, when library type is MODULE,
13723 to target Python2::Module and takes care of Python module naming rules:
13724 Python2_add_library (my_module MODULE src1.cpp)
13726 If library type is not specified, MODULE is assumed.
13728 FindPython3
13730 Find Python 3 interpreter, compiler and development environment
13731 (include directories and libraries).
13732 The following components are supported:
13734 · Interpreter: search for Python 3 interpreter
13736 · Compiler: search for Python 3 compiler. Only offered by IronPython.
13738 · Development: search for development artifacts (include directories
13740 and libraries)
13741 · NumPy: search for NumPy include directories.
13743 If no COMPONENTS are specified, Interpreter is assumed.
13745 To ensure consistent versions between components Interpreter, Compiler,
13747 Development and NumPy, specify all components at the same time:
13748 find_package (Python3 COMPONENTS Interpreter Development)
13750 This module looks only for version 3 of Python. This module can be used
13752 concurrently with FindPython2 module to use both Python versions.
13753 The FindPython module can be used if Python version does not matter for
13755 you.
13756 NOTE:
13758 If components Interpreter and Development are both specified, this
13759 module search only for interpreter with same platform architecture
13760 as the one defined by CMake configuration. This contraint does not
13761 apply if only Interpreter component is specified.
13762 Imported Targets
13764 This module defines the following Imported Targets (when CMAKE_ROLE is
13765 PROJECT):
13766 Python3::Interpreter
13768 Python 3 interpreter. Target defined if component Interpreter is
13769 found.
13770 Python3::Compiler
13772 Python 3 compiler. Target defined if component Compiler is
13773 found.
13774 Python3::Python
13776 Python 3 library for Python embedding. Target defined if compo‐
13777 nent Development is found.
13778 Python3::Module
13780 Python 3 library for Python module. Target defined if component
13781 Development is found.
13782 Python3::NumPy
13784 NumPy library for Python 3. Target defined if component NumPy is
13785 found.
13786 Result Variables
13788 This module will set the following variables in your project (see Stan‐
13789 dard Variable Names):
13790 Python3_FOUND
13792 System has the Python 3 requested components.
13793 Python3_Interpreter_FOUND
13795 System has the Python 3 interpreter.
13796 Python3_EXECUTABLE
13798 Path to the Python 3 interpreter.
13799 Python3_INTERPRETER_ID
13801 A short string unique to the interpreter. Possible values
13803 include:
13804 · Python
13806 · ActivePython
13808 · Anaconda
13810 · Canopy
13812 · IronPython
13814 Python3_STDLIB
13816 Standard platform independent installation directory.
13817 Information returned by distutils.syscon‐
13819 fig.get_python_lib(plat_specific=False,standard_lib=True).
13820 Python3_STDARCH
13822 Standard platform dependent installation directory.
13823 Information returned by distutils.syscon‐
13825 fig.get_python_lib(plat_specific=True,standard_lib=True).
13826 Python3_SITELIB
13828 Third-party platform independent installation directory.
13829 Information returned by distutils.syscon‐
13831 fig.get_python_lib(plat_specific=False,standard_lib=False).
13832 Python3_SITEARCH
13834 Third-party platform dependent installation directory.
13835 Information returned by distutils.syscon‐
13837 fig.get_python_lib(plat_specific=True,standard_lib=False).
13838 Python3_Compiler_FOUND
13840 System has the Python 3 compiler.
13841 Python3_COMPILER
13843 Path to the Python 3 compiler. Only offered by IronPython.
13844 Python3_COMPILER_ID
13846 A short string unique to the compiler. Possible values include:
13848 · IronPython
13850 Python3_Development_FOUND
13852 System has the Python 3 development artifacts.
13853 Python3_INCLUDE_DIRS
13855 The Python 3 include directories.
13856 Python3_LIBRARIES
13858 The Python 3 libraries.
13859 Python3_LIBRARY_DIRS
13861 The Python 3 library directories.
13862 Python3_RUNTIME_LIBRARY_DIRS
13864 The Python 3 runtime library directories.
13865 Python3_VERSION
13867 Python 3 version.
13868 Python3_VERSION_MAJOR
13870 Python 3 major version.
13871 Python3_VERSION_MINOR
13873 Python 3 minor version.
13874 Python3_VERSION_PATCH
13876 Python 3 patch version.
13877 Python3_NumPy_FOUND
13879 System has the NumPy.
13880 Python3_NumPy_INCLUDE_DIRS
13882 The NumPy include directries.
13883 Python3_NumPy_VERSION
13885 The NumPy version.
13886 Hints
13888 Python3_ROOT_DIR
13889 Define the root directory of a Python 3 installation.
13890 Python3_USE_STATIC_LIBS
13892 · If not defined, search for shared libraries and static
13894 libraries in that order.
13895 · If set to TRUE, search only for static libraries.
13897 · If set to FALSE, search only for shared libraries.
13899 Python3_FIND_ABI
13901 This variable defines which ABIs, as defined in PEP 3149, should
13902 be searched.
13903 NOTE:
13905 If Python3_FIND_ABI is not defined, any ABI will be searched.
13906 The Python3_FIND_ABI variable is a 3-tuple specifying, in that
13908 order, pydebug (d), pymalloc (m) and unicode (u) flags. Each
13909 element can be set to one of the following:
13910 · ON: Corresponding flag is selected.
13912 · OFF: Corresponding flag is not selected.
13914 · ANY: The two posibilties (ON and OFF) will be searched.
13916 From this 3-tuple, various ABIs will be searched starting from
13918 the most specialized to the most general. Moreover, debug ver‐
13919 sions will be searched after non-debug ones.
13920 For example, if we have:
13922 set (Python3_FIND_ABI "ON" "ANY" "ANY")
13924 The following flags combinations will be appended, in that
13926 order, to the artifact names: dmu, dm, du, and d.
13927 And to search any possible ABIs:
13929 set (Python3_FIND_ABI "ANY" "ANY" "ANY")
13931 The following combinations, in that order, will be used: mu, m,
13933 u, <empty>, dmu, dm, du and d.
13934 NOTE:
13936 This hint is useful only on POSIX systems. So, on Windows
13937 systems, when Python3_FIND_ABI is defined, Python distribu‐
13938 tions from python.org will be found only if value for each
13939 flag is OFF or ANY.
13940 Python3_FIND_STRATEGY
13942 This variable defines how lookup will be done. The
13943 Python3_FIND_STRATEGY variable can be set to empty or one of the
13944 following:
13945 · VERSION: Try to find the most recent version in all specified
13947 locations. This is the default if policy CMP0094 is undefined
13948 or set to OLD.
13949 · LOCATION: Stops lookup as soon as a version satisfying version
13951 constraints is founded. This is the default if policy CMP0094
13952 is set to NEW.
13953 Python3_FIND_REGISTRY
13955 On Windows the Python3_FIND_REGISTRY variable determine the
13956 order of preference between registry and environment variables.
13957 The Python3_FIND_REGISTRY variable can be set to empty or one of
13958 the following:
13959 · FIRST: Try to use registry before environment variables. This
13961 is the default.
13962 · LAST: Try to use registry after environment variables.
13964 · NEVER: Never try to use registry.
13966 Python3_FIND_FRAMEWORK
13968 On macOS the Python3_FIND_FRAMEWORK variable determine the order
13969 of preference between Apple-style and unix-style package compo‐
13970 nents. This variable can be set to empty or take same values as
13971 CMAKE_FIND_FRAMEWORK variable.
13972 NOTE:
13974 Value ONLY is not supported so FIRST will be used instead.
13975 If Python3_FIND_FRAMEWORK is not defined, CMAKE_FIND_FRAMEWORK
13977 variable will be used, if any.
13978 Python3_FIND_VIRTUALENV
13980 This variable defines the handling of virtual environments. It
13981 is meaningfull only when a virtual environment is active (i.e.
13982 the activate script has been evaluated). In this case, it takes
13983 precedence over Python3_FIND_REGISTRY and CMAKE_FIND_FRAMEWORK
13984 variables. The Python3_FIND_VIRTUALENV variable can be set to
13985 empty or one of the following:
13986 · FIRST: The virtual environment is used before any other stan‐
13988 dard paths to look-up for the interpreter. This is the
13989 default.
13990 · ONLY: Only the virtual environment is used to look-up for the
13992 interpreter.
13993 · STANDARD: The virtual environment is not used to look-up for
13995 the interpreter. In this case, variable Python3_FIND_REGISTRY
13996 (Windows) or CMAKE_FIND_FRAMEWORK (macOS) can be set with
13997 value LAST or NEVER to select preferably the interpreter from
13998 the virtual environment.
13999 NOTE:
14001 If the component Development is requested, it is strongly
14002 recommended to also include the component Interpreter to get
14003 expected result.
14004 Artifacts Specification
14006 To solve special cases, it is possible to specify directly the arti‐
14007 facts by setting the following variables:
14008 Python3_EXECUTABLE
14010 The path to the interpreter.
14011 Python3_COMPILER
14013 The path to the compiler.
14014 Python3_LIBRARY
14016 The path to the library. It will be used to compute the vari‐
14017 ables Python3_LIBRARIES, Python3_LIBRAY_DIRS and Python3_RUN‐
14018 TIME_LIBRARY_DIRS.
14019 Python3_INCLUDE_DIR
14021 The path to the directory of the Python headers. It will be used
14022 to compute the variable Python3_INCLUDE_DIRS.
14023 Python3_NumPy_INCLUDE_DIR
14025 The path to the directory of the NumPy headers. It will be used
14026 to compute the variable Python3_NumPy_INCLUDE_DIRS.
14027 NOTE:
14029 All paths must be absolute. Any artifact specified with a relative
14030 path will be ignored.
14031 NOTE:
14033 When an artifact is specified, all HINTS will be ignored and no
14034 search will be performed for this artifact.
14035 If more than one artifact is specified, it is the user’s respons‐
14037 ability to ensure the consistency of the various artifacts.
14038 Commands
14040 This module defines the command Python_add_library (when CMAKE_ROLE is
14041 PROJECT), which has the same semantics as add_library() and adds a
14042 dependency to target Python3::Python or, when library type is MODULE,
14043 to target Python3::Module and takes care of Python module naming rules:
14044 Python3_add_library (my_module MODULE src1.cpp)
14046 If library type is not specified, MODULE is assumed.
14048 FindQt3
14050 Locate Qt include paths and libraries
14051 This module defines:
14053 QT_INCLUDE_DIR - where to find qt.h, etc.
14055 QT_LIBRARIES - the libraries to link against to use Qt.
14056 QT_DEFINITIONS - definitions to use when
14057 compiling code that uses Qt.
14058 QT_FOUND - If false, don't try to use Qt.
14059 QT_VERSION_STRING - the version of Qt found
14060 If you need the multithreaded version of Qt, set QT_MT_REQUIRED to TRUE
14062 Also defined, but not for general use are:
14064 QT_MOC_EXECUTABLE, where to find the moc tool.
14066 QT_UIC_EXECUTABLE, where to find the uic tool.
14067 QT_QT_LIBRARY, where to find the Qt library.
14068 QT_QTMAIN_LIBRARY, where to find the qtmain
14069 library. This is only required by Qt3 on Windows.
14070 FindQt4
14072 Finding and Using Qt4
14073 This module can be used to find Qt4. The most important issue is that
14074 the Qt4 qmake is available via the system path. This qmake is then
14075 used to detect basically everything else. This module defines a number
14076 of IMPORTED targets, macros and variables.
14077 Typical usage could be something like:
14079 set(CMAKE_AUTOMOC ON)
14081 set(CMAKE_INCLUDE_CURRENT_DIR ON)
14082 find_package(Qt4 4.4.3 REQUIRED QtGui QtXml)
14083 add_executable(myexe main.cpp)
14084 target_link_libraries(myexe Qt4::QtGui Qt4::QtXml)
14085 NOTE:
14087 When using IMPORTED targets, the qtmain.lib static library is auto‐
14088 matically linked on Windows for WIN32 executables. To disable that
14089 globally, set the QT4_NO_LINK_QTMAIN variable before finding Qt4. To
14090 disable that for a particular executable, set the QT4_NO_LINK_QTMAIN
14091 target property to TRUE on the executable.
14092 Qt Build Tools
14094 Qt relies on some bundled tools for code generation, such as moc for
14095 meta-object code generation,``uic`` for widget layout and population,
14096 and rcc for virtual filesystem content generation. These tools may be
14097 automatically invoked by cmake(1) if the appropriate conditions are
14098 met. See cmake-qt(7) for more.
14099 Qt Macros
14101 In some cases it can be necessary or useful to invoke the Qt build
14102 tools in a more-manual way. Several macros are available to add targets
14103 for such uses.
14104 macro QT4_WRAP_CPP(outfiles inputfile ... [TARGET tgt] OPTIONS ...)
14106 create moc code from a list of files containing Qt class with
14107 the Q_OBJECT declaration. Per-directory preprocessor definitions
14108 are also added. If the <tgt> is specified, the
14109 INTERFACE_INCLUDE_DIRECTORIES and INTERFACE_COMPILE_DEFINITIONS from
14110 the <tgt> are passed to moc. Options may be given to moc, such as
14111 those found when executing "moc -help".
14112 macro QT4_WRAP_UI(outfiles inputfile ... OPTIONS ...)
14114 create code from a list of Qt designer ui files.
14115 Options may be given to uic, such as those found
14116 when executing "uic -help"
14117 macro QT4_ADD_RESOURCES(outfiles inputfile ... OPTIONS ...)
14119 create code from a list of Qt resource files.
14120 Options may be given to rcc, such as those found
14121 when executing "rcc -help"
14122 macro QT4_GENERATE_MOC(inputfile outputfile [TARGET tgt])
14124 creates a rule to run moc on infile and create outfile.
14125 Use this if for some reason QT4_WRAP_CPP() isn't appropriate, e.g.
14126 because you need a custom filename for the moc file or something
14127 similar. If the <tgt> is specified, the
14128 INTERFACE_INCLUDE_DIRECTORIES and INTERFACE_COMPILE_DEFINITIONS from
14129 the <tgt> are passed to moc.
14130 macro QT4_ADD_DBUS_INTERFACE(outfiles interface basename)
14132 Create the interface header and implementation files with the
14133 given basename from the given interface xml file and add it to
14134 the list of sources.
14135 You can pass additional parameters to the qdbusxml2cpp call by setting
14137 properties on the input file:
14138 INCLUDE the given file will be included in the generate interface header
14140 CLASSNAME the generated class is named accordingly
14142 NO_NAMESPACE the generated class is not wrapped in a namespace
14144 macro QT4_ADD_DBUS_INTERFACES(outfiles inputfile ... )
14146 Create the interface header and implementation files
14147 for all listed interface xml files.
14148 The basename will be automatically determined from the name
14149 of the xml file.
14150 The source file properties described for
14152 QT4_ADD_DBUS_INTERFACE also apply here.
14153 macro QT4_ADD_DBUS_ADAPTOR(outfiles xmlfile parentheader parentclassname
14155 [basename] [classname])
14156 create a dbus adaptor (header and implementation file) from the xml file
14157 describing the interface, and add it to the list of sources. The adaptor
14158 forwards the calls to a parent class, defined in parentheader and named
14159 parentclassname. The name of the generated files will be
14160 <basename>adaptor.{cpp,h} where basename defaults to the basename of the
14161 xml file.
14162 If <classname> is provided, then it will be used as the classname of the
14163 adaptor itself.
14164 macro QT4_GENERATE_DBUS_INTERFACE( header [interfacename] OPTIONS ...)
14166 generate the xml interface file from the given header.
14167 If the optional argument interfacename is omitted, the name of the
14168 interface file is constructed from the basename of the header with
14169 the suffix .xml appended.
14170 Options may be given to qdbuscpp2xml, such as those found when
14171 executing "qdbuscpp2xml --help"
14172 macro QT4_CREATE_TRANSLATION( qm_files directories ... sources ...
14174 ts_files ... OPTIONS ...)
14175 out: qm_files
14176 in: directories sources ts_files
14177 options: flags to pass to lupdate, such as -extensions to specify
14178 extensions for a directory scan.
14179 generates commands to create .ts (vie lupdate) and .qm
14180 (via lrelease) - files from directories and/or sources. The ts files are
14181 created and/or updated in the source tree (unless given with full paths).
14182 The qm files are generated in the build tree.
14183 Updating the translations can be done by adding the qm_files
14184 to the source list of your library/executable, so they are
14185 always updated, or by adding a custom target to control when
14186 they get updated/generated.
14187 macro QT4_ADD_TRANSLATION( qm_files ts_files ... )
14189 out: qm_files
14190 in: ts_files
14191 generates commands to create .qm from .ts - files. The generated
14192 filenames can be found in qm_files. The ts_files
14193 must exist and are not updated in any way.
14194 macro QT4_AUTOMOC(sourcefile1 sourcefile2 ... [TARGET tgt])
14196 The qt4_automoc macro is obsolete. Use the CMAKE_AUTOMOC feature instead.
14197 This macro is still experimental.
14198 It can be used to have moc automatically handled.
14199 So if you have the files foo.h and foo.cpp, and in foo.h a
14200 a class uses the Q_OBJECT macro, moc has to run on it. If you don't
14201 want to use QT4_WRAP_CPP() (which is reliable and mature), you can insert
14202 #include "foo.moc"
14203 in foo.cpp and then give foo.cpp as argument to QT4_AUTOMOC(). This will
14204 scan all listed files at cmake-time for such included moc files and if it
14205 finds them cause a rule to be generated to run moc at build time on the
14206 accompanying header file foo.h.
14207 If a source file has the SKIP_AUTOMOC property set it will be ignored by
14208 this macro.
14209 If the <tgt> is specified, the INTERFACE_INCLUDE_DIRECTORIES and
14210 INTERFACE_COMPILE_DEFINITIONS from the <tgt> are passed to moc.
14211 function QT4_USE_MODULES( target [link_type] modules...)
14213 This function is obsolete. Use target_link_libraries with IMPORTED targets
14214 instead.
14215 Make <target> use the <modules> from Qt. Using a Qt module means
14216 to link to the library, add the relevant include directories for the
14217 module, and add the relevant compiler defines for using the module.
14218 Modules are roughly equivalent to components of Qt4, so usage would be
14219 something like:
14220 qt4_use_modules(myexe Core Gui Declarative)
14221 to use QtCore, QtGui and QtDeclarative. The optional <link_type> argument
14222 can be specified as either LINK_PUBLIC or LINK_PRIVATE to specify the
14223 same argument to the target_link_libraries call.
14224 IMPORTED Targets
14226 A particular Qt library may be used by using the corresponding IMPORTED
14227 target with the target_link_libraries() command:
14228 target_link_libraries(myexe Qt4::QtGui Qt4::QtXml)
14230 Using a target in this way causes :cmake(1)` to use the appropriate
14232 include directories and compile definitions for the target when compil‐
14233 ing myexe.
14234 Targets are aware of their dependencies, so for example it is not nec‐
14236 essary to list Qt4::QtCore if another Qt library is listed, and it is
14237 not necessary to list Qt4::QtGui if Qt4::QtDeclarative is listed. Tar‐
14238 gets may be tested for existence in the usual way with the if(TARGET)
14239 command.
14240 The Qt toolkit may contain both debug and release libraries. cmake(1)
14242 will choose the appropriate version based on the build configuration.
14243 Qt4::QtCore
14245 The QtCore target
14246 Qt4::QtGui
14248 The QtGui target
14249 Qt4::Qt3Support
14251 The Qt3Support target
14252 Qt4::QtAssistant
14254 The QtAssistant target
14255 Qt4::QtAssistantClient
14257 The QtAssistantClient target
14258 Qt4::QAxContainer
14260 The QAxContainer target (Windows only)
14261 Qt4::QAxServer
14263 The QAxServer target (Windows only)
14264 Qt4::QtDBus
14266 The QtDBus target
14267 Qt4::QtDeclarative
14269 The QtDeclarative target
14270 Qt4::QtDesigner
14272 The QtDesigner target
14273 Qt4::QtDesignerComponents
14275 The QtDesignerComponents target
14276 Qt4::QtHelp
14278 The QtHelp target
14279 Qt4::QtMotif
14281 The QtMotif target
14282 Qt4::QtMultimedia
14284 The QtMultimedia target
14285 Qt4::QtNetwork
14287 The QtNetwork target
14288 Qt4::QtNsPLugin
14290 The QtNsPLugin target
14291 Qt4::QtOpenGL
14293 The QtOpenGL target
14294 Qt4::QtScript
14296 The QtScript target
14297 Qt4::QtScriptTools
14299 The QtScriptTools target
14300 Qt4::QtSql
14302 The QtSql target
14303 Qt4::QtSvg
14305 The QtSvg target
14306 Qt4::QtTest
14308 The QtTest target
14309 Qt4::QtUiTools
14311 The QtUiTools target
14312 Qt4::QtWebKit
14314 The QtWebKit target
14315 Qt4::QtXml
14317 The QtXml target
14318 Qt4::QtXmlPatterns
14320 The QtXmlPatterns target
14321 Qt4::phonon
14323 The phonon target
14324 Result Variables
14326 Below is a detailed list of variables that FindQt4.cmake sets.
14327 Qt4_FOUND
14329 If false, don’t try to use Qt 4.
14330 QT_FOUND
14332 If false, don’t try to use Qt. This variable is for compatibil‐
14333 ity only.
14334 QT4_FOUND
14336 If false, don’t try to use Qt 4. This variable is for compati‐
14337 bility only.
14338 QT_VERSION_MAJOR
14340 The major version of Qt found.
14341 QT_VERSION_MINOR
14343 The minor version of Qt found.
14344 QT_VERSION_PATCH
14346 The patch version of Qt found.
14347 FindQuickTime
14349 Locate QuickTime This module defines QUICKTIME_LIBRARY QUICKTIME_FOUND,
14350 if false, do not try to link to gdal QUICKTIME_INCLUDE_DIR, where to
14351 find the headers
14352 $QUICKTIME_DIR is an environment variable that would correspond to the
14354 Created by Eric Wing.
14356 FindRTI
14358 Try to find M&S HLA RTI libraries
14359 This module finds if any HLA RTI is installed and locates the standard
14361 RTI include files and libraries.
14362 RTI is a simulation infrastructure standardized by IEEE and SISO. It
14364 has a well defined C++ API that assures that simulation applications
14365 are independent on a particular RTI implementation.
14366 http://en.wikipedia.org/wiki/Run-Time_Infrastructure_(simulation)
14368 This code sets the following variables:
14370 RTI_INCLUDE_DIR = the directory where RTI includes file are found
14372 RTI_LIBRARIES = The libraries to link against to use RTI
14373 RTI_DEFINITIONS = -DRTI_USES_STD_FSTREAM
14374 RTI_FOUND = Set to FALSE if any HLA RTI was not found
14375 Report problems to <certi-devel@nongnu.org>
14377 FindRuby
14379 Find Ruby
14380 This module finds if Ruby is installed and determines where the include
14382 files and libraries are. Ruby 1.8, 1.9, 2.0 and 2.1 are supported.
14383 The minimum required version of Ruby can be specified using the stan‐
14385 dard syntax, e.g. find_package(Ruby 1.8)
14386 It also determines what the name of the library is. This code sets the
14388 following variables:
14389 RUBY_EXECUTABLE
14391 full path to the ruby binary
14392 RUBY_INCLUDE_DIRS
14394 include dirs to be used when using the ruby library
14395 RUBY_LIBRARY
14397 full path to the ruby library
14398 RUBY_VERSION
14400 the version of ruby which was found, e.g. “1.8.7”
14401 RUBY_FOUND
14403 set to true if ruby ws found successfully
14404 Also:
14406 RUBY_INCLUDE_PATH
14408 same as RUBY_INCLUDE_DIRS, only provided for compatibility rea‐
14409 sons, don’t use it
14410 FindSDL_image
14412 Locate SDL_image library
14413 This module defines:
14415 SDL_IMAGE_LIBRARIES, the name of the library to link against
14417 SDL_IMAGE_INCLUDE_DIRS, where to find the headers
14418 SDL_IMAGE_FOUND, if false, do not try to link against
14419 SDL_IMAGE_VERSION_STRING - human-readable string containing the
14420 version of SDL_image
14421 For backward compatibility the following variables are also set:
14423 SDLIMAGE_LIBRARY (same value as SDL_IMAGE_LIBRARIES)
14425 SDLIMAGE_INCLUDE_DIR (same value as SDL_IMAGE_INCLUDE_DIRS)
14426 SDLIMAGE_FOUND (same value as SDL_IMAGE_FOUND)
14427 $SDLDIR is an environment variable that would correspond to the
14429 Created by Eric Wing. This was influenced by the FindSDL.cmake module,
14431 but with modifications to recognize OS X frameworks and additional Unix
14432 paths (FreeBSD, etc).
14433 FindSDL_mixer
14435 Locate SDL_mixer library
14436 This module defines:
14438 SDL_MIXER_LIBRARIES, the name of the library to link against
14440 SDL_MIXER_INCLUDE_DIRS, where to find the headers
14441 SDL_MIXER_FOUND, if false, do not try to link against
14442 SDL_MIXER_VERSION_STRING - human-readable string containing the
14443 version of SDL_mixer
14444 For backward compatibility the following variables are also set:
14446 SDLMIXER_LIBRARY (same value as SDL_MIXER_LIBRARIES)
14448 SDLMIXER_INCLUDE_DIR (same value as SDL_MIXER_INCLUDE_DIRS)
14449 SDLMIXER_FOUND (same value as SDL_MIXER_FOUND)
14450 $SDLDIR is an environment variable that would correspond to the
14452 Created by Eric Wing. This was influenced by the FindSDL.cmake module,
14454 but with modifications to recognize OS X frameworks and additional Unix
14455 paths (FreeBSD, etc).
14456 FindSDL_net
14458 Locate SDL_net library
14459 This module defines:
14461 SDL_NET_LIBRARIES, the name of the library to link against
14463 SDL_NET_INCLUDE_DIRS, where to find the headers
14464 SDL_NET_FOUND, if false, do not try to link against
14465 SDL_NET_VERSION_STRING - human-readable string containing the version of SDL_net
14466 For backward compatibility the following variables are also set:
14468 SDLNET_LIBRARY (same value as SDL_NET_LIBRARIES)
14470 SDLNET_INCLUDE_DIR (same value as SDL_NET_INCLUDE_DIRS)
14471 SDLNET_FOUND (same value as SDL_NET_FOUND)
14472 $SDLDIR is an environment variable that would correspond to the
14474 Created by Eric Wing. This was influenced by the FindSDL.cmake module,
14476 but with modifications to recognize OS X frameworks and additional Unix
14477 paths (FreeBSD, etc).
14478 FindSDL
14480 Locate SDL library
14481 This module defines
14483 SDL_LIBRARY, the name of the library to link against
14485 SDL_FOUND, if false, do not try to link to SDL
14486 SDL_INCLUDE_DIR, where to find SDL.h
14487 SDL_VERSION_STRING, human-readable string containing the version of SDL
14488 This module responds to the flag:
14490 SDL_BUILDING_LIBRARY
14492 If this is defined, then no SDL_main will be linked in because
14493 only applications need main().
14494 Otherwise, it is assumed you are building an application and this
14495 module will attempt to locate and set the proper link flags
14496 as part of the returned SDL_LIBRARY variable.
14497 Don’t forget to include SDLmain.h and SDLmain.m your project for the OS
14499 X framework based version. (Other versions link to -lSDLmain which
14500 this module will try to find on your behalf.) Also for OS X, this mod‐
14501 ule will automatically add the -framework Cocoa on your behalf.
14502 Additional Note: If you see an empty SDL_LIBRARY_TEMP in your configu‐
14504 ration and no SDL_LIBRARY, it means CMake did not find your SDL library
14505 (SDL.dll, libsdl.so, SDL.framework, etc). Set SDL_LIBRARY_TEMP to
14506 point to your SDL library, and configure again. Similarly, if you see
14507 an empty SDLMAIN_LIBRARY, you should set this value as appropriate.
14508 These values are used to generate the final SDL_LIBRARY variable, but
14509 when these values are unset, SDL_LIBRARY does not get created.
14510 $SDLDIR is an environment variable that would correspond to the
14512 Modified by Eric Wing. Added code to assist with automated building by
14514 using environmental variables and providing a more controlled/consis‐
14515 tent search behavior. Added new modifications to recognize OS X frame‐
14516 works and additional Unix paths (FreeBSD, etc). Also corrected the
14517 header search path to follow “proper” SDL guidelines. Added a search
14518 for SDLmain which is needed by some platforms. Added a search for
14519 threads which is needed by some platforms. Added needed compile
14520 switches for MinGW.
14521 On OSX, this will prefer the Framework version (if found) over others.
14523 People will have to manually change the cache values of SDL_LIBRARY to
14524 override this selection or set the CMake environment CMAKE_INCLUDE_PATH
14525 to modify the search paths.
14526 Note that the header path has changed from SDL/SDL.h to just SDL.h This
14528 needed to change because “proper” SDL convention is #include “SDL.h”,
14529 not <SDL/SDL.h>. This is done for portability reasons because not all
14530 systems place things in SDL/ (see FreeBSD).
14531 FindSDL_sound
14533 Locates the SDL_sound library
14534 This module depends on SDL being found and must be called AFTER Find‐
14536 SDL.cmake is called.
14537 This module defines
14539 SDL_SOUND_INCLUDE_DIR, where to find SDL_sound.h
14541 SDL_SOUND_FOUND, if false, do not try to link to SDL_sound
14542 SDL_SOUND_LIBRARIES, this contains the list of libraries that you need
14543 to link against.
14544 SDL_SOUND_EXTRAS, this is an optional variable for you to add your own
14545 flags to SDL_SOUND_LIBRARIES. This is prepended to SDL_SOUND_LIBRARIES.
14546 This is available mostly for cases this module failed to anticipate for
14547 and you must add additional flags. This is marked as ADVANCED.
14548 SDL_SOUND_VERSION_STRING, human-readable string containing the
14549 version of SDL_sound
14550 This module also defines (but you shouldn’t need to use directly)
14552 SDL_SOUND_LIBRARY, the name of just the SDL_sound library you would link
14554 against. Use SDL_SOUND_LIBRARIES for you link instructions and not this one.
14555 And might define the following as needed
14557 MIKMOD_LIBRARY
14559 MODPLUG_LIBRARY
14560 OGG_LIBRARY
14561 VORBIS_LIBRARY
14562 SMPEG_LIBRARY
14563 FLAC_LIBRARY
14564 SPEEX_LIBRARY
14565 Typically, you should not use these variables directly, and you should
14567 use SDL_SOUND_LIBRARIES which contains SDL_SOUND_LIBRARY and the other
14568 audio libraries (if needed) to successfully compile on your system.
14569 Created by Eric Wing. This module is a bit more complicated than the
14571 other FindSDL* family modules. The reason is that SDL_sound can be
14572 compiled in a large variety of different ways which are independent of
14573 platform. SDL_sound may dynamically link against other 3rd party
14574 libraries to get additional codec support, such as Ogg Vorbis, SMPEG,
14575 ModPlug, MikMod, FLAC, Speex, and potentially others. Under some cir‐
14576 cumstances which I don’t fully understand, there seems to be a require‐
14577 ment that dependent libraries of libraries you use must also be explic‐
14578 itly linked against in order to successfully compile. SDL_sound does
14579 not currently have any system in place to know how it was compiled. So
14580 this CMake module does the hard work in trying to discover which 3rd
14581 party libraries are required for building (if any). This module uses a
14582 brute force approach to create a test program that uses SDL_sound, and
14583 then tries to build it. If the build fails, it parses the error output
14584 for known symbol names to figure out which libraries are needed.
14585 Responds to the $SDLDIR and $SDLSOUNDDIR environmental variable that
14587 would correspond to the ./configure –prefix=$SDLDIR used in building
14588 SDL.
14589 On OSX, this will prefer the Framework version (if found) over others.
14591 People will have to manually change the cache values of SDL_LIBRARY to
14592 override this selectionor set the CMake environment CMAKE_INCLUDE_PATH
14593 to modify the search paths.
14594 FindSDL_ttf
14596 Locate SDL_ttf library
14597 This module defines:
14599 SDL_TTF_LIBRARIES, the name of the library to link against
14601 SDL_TTF_INCLUDE_DIRS, where to find the headers
14602 SDL_TTF_FOUND, if false, do not try to link against
14603 SDL_TTF_VERSION_STRING - human-readable string containing the version of SDL_ttf
14604 For backward compatibility the following variables are also set:
14606 SDLTTF_LIBRARY (same value as SDL_TTF_LIBRARIES)
14608 SDLTTF_INCLUDE_DIR (same value as SDL_TTF_INCLUDE_DIRS)
14609 SDLTTF_FOUND (same value as SDL_TTF_FOUND)
14610 $SDLDIR is an environment variable that would correspond to the
14612 Created by Eric Wing. This was influenced by the FindSDL.cmake module,
14614 but with modifications to recognize OS X frameworks and additional Unix
14615 paths (FreeBSD, etc).
14616 FindSelfPackers
14618 Find upx
14619 This module looks for some executable packers (i.e. software that com‐
14621 press executables or shared libs into on-the-fly self-extracting exe‐
14622 cutables or shared libs. Examples:
14623 UPX: http://wildsau.idv.uni-linz.ac.at/mfx/upx.html
14625 FindSquish
14627 – Typical Use
14628 This module can be used to find Squish. Currently Squish versions 3
14630 and 4 are supported.
14631 SQUISH_FOUND If false, don't try to use Squish
14633 SQUISH_VERSION The full version of Squish found
14634 SQUISH_VERSION_MAJOR The major version of Squish found
14635 SQUISH_VERSION_MINOR The minor version of Squish found
14636 SQUISH_VERSION_PATCH The patch version of Squish found
14637 SQUISH_INSTALL_DIR The Squish installation directory
14639 (containing bin, lib, etc)
14640 SQUISH_SERVER_EXECUTABLE The squishserver executable
14641 SQUISH_CLIENT_EXECUTABLE The squishrunner executable
14642 SQUISH_INSTALL_DIR_FOUND Was the install directory found?
14644 SQUISH_SERVER_EXECUTABLE_FOUND Was the server executable found?
14645 SQUISH_CLIENT_EXECUTABLE_FOUND Was the client executable found?
14646 It provides the function squish_v4_add_test() for adding a squish test
14648 to cmake using Squish 4.x:
14649 squish_v4_add_test(cmakeTestName
14651 AUT targetName SUITE suiteName TEST squishTestName
14652 [SETTINGSGROUP group] [PRE_COMMAND command] [POST_COMMAND command] )
14653 The arguments have the following meaning:
14655 cmakeTestName
14657 this will be used as the first argument for add_test()
14658 AUT targetName
14660 the name of the cmake target which will be used as AUT, i.e. the
14661 executable which will be tested.
14662 SUITE suiteName
14664 this is either the full path to the squish suite, or just the
14665 last directory of the suite, i.e. the suite name. In this case
14666 the CMakeLists.txt which calls squish_add_test() must be located
14667 in the parent directory of the suite directory.
14668 TEST squishTestName
14670 the name of the squish test, i.e. the name of the subdirectory
14671 of the test inside the suite directory.
14672 SETTINGSGROUP group
14674 if specified, the given settings group will be used for execut‐
14675 ing the test. If not specified, the groupname will be
14676 “CTest_<username>”
14677 PRE_COMMAND command
14679 if specified, the given command will be executed before starting
14680 the squish test.
14681 POST_COMMAND command
14683 same as PRE_COMMAND, but after the squish test has been exe‐
14684 cuted.
14685 enable_testing()
14687 find_package(Squish 4.0)
14688 if (SQUISH_FOUND)
14689 squish_v4_add_test(myTestName
14690 AUT myApp
14691 SUITE ${CMAKE_SOURCE_DIR}/tests/mySuite
14692 TEST someSquishTest
14693 SETTINGSGROUP myGroup
14694 )
14695 endif ()
14696 For users of Squish version 3.x the macro squish_v3_add_test() is pro‐
14698 vided:
14699 squish_v3_add_test(testName applicationUnderTest testCase envVars testWrapper)
14701 Use this macro to add a test using Squish 3.x.
14702 enable_testing()
14704 find_package(Squish)
14705 if (SQUISH_FOUND)
14706 squish_v3_add_test(myTestName myApplication testCase envVars testWrapper)
14707 endif ()
14708 macro SQUISH_ADD_TEST(testName applicationUnderTest testCase envVars
14710 testWrapper)
14711 This is deprecated. Use SQUISH_V3_ADD_TEST() if you are using Squish 3.x instead.
14713 FindSQLite3
14715 Find the SQLite libraries, v3
14716 IMPORTED targets
14718 This module defines the following IMPORTED target:
14719 SQLite::SQLite3
14721 Result variables
14723 This module will set the following variables if found:
14724 SQLite3_INCLUDE_DIRS
14726 where to find sqlite3.h, etc.
14727 SQLite3_LIBRARIES
14729 the libraries to link against to use SQLite3.
14730 SQLite3_VERSION
14732 version of the SQLite3 library found
14733 SQLite3_FOUND
14735 TRUE if found
14736 FindSubversion
14738 Extract information from a subversion working copy
14739 The module defines the following variables:
14741 Subversion_SVN_EXECUTABLE - path to svn command line client
14743 Subversion_VERSION_SVN - version of svn command line client
14744 Subversion_FOUND - true if the command line client was found
14745 SUBVERSION_FOUND - same as Subversion_FOUND, set for compatibility reasons
14746 The minimum required version of Subversion can be specified using the
14748 standard syntax, e.g. find_package(Subversion 1.4).
14749 If the command line client executable is found two macros are defined:
14751 Subversion_WC_INFO(<dir> <var-prefix> [IGNORE_SVN_FAILURE])
14753 Subversion_WC_LOG(<dir> <var-prefix>)
14754 Subversion_WC_INFO extracts information of a subversion working copy at
14756 a given location. This macro defines the following variables if run‐
14757 ning Subversion’s info command on <dir> succeeds; otherwise a
14758 SEND_ERROR message is generated. The error can be ignored by providing
14759 the IGNORE_SVN_FAILURE option, which causes these variables to remain
14760 undefined.
14761 <var-prefix>_WC_URL - url of the repository (at <dir>)
14763 <var-prefix>_WC_ROOT - root url of the repository
14764 <var-prefix>_WC_REVISION - current revision
14765 <var-prefix>_WC_LAST_CHANGED_AUTHOR - author of last commit
14766 <var-prefix>_WC_LAST_CHANGED_DATE - date of last commit
14767 <var-prefix>_WC_LAST_CHANGED_REV - revision of last commit
14768 <var-prefix>_WC_INFO - output of command `svn info <dir>'
14769 Subversion_WC_LOG retrieves the log message of the base revision of a
14771 subversion working copy at a given location. This macro defines the
14772 variable:
14773 <var-prefix>_LAST_CHANGED_LOG - last log of base revision
14775 Example usage:
14777 find_package(Subversion)
14779 if(SUBVERSION_FOUND)
14780 Subversion_WC_INFO(${PROJECT_SOURCE_DIR} Project)
14781 message("Current revision is ${Project_WC_REVISION}")
14782 Subversion_WC_LOG(${PROJECT_SOURCE_DIR} Project)
14783 message("Last changed log is ${Project_LAST_CHANGED_LOG}")
14784 endif()
14785 FindSWIG
14787 Find Simplified Wrapper and Interface Generator (SWIG)
14788 This module finds an installed SWIG. It sets the following variables:
14790 SWIG_FOUND - set to "True" if SWIG is found
14792 SWIG_DIR - the directory where swig is installed
14793 SWIG_EXECUTABLE - the path to the swig executable
14794 SWIG_VERSION - the version number of the swig executable
14795 The minimum required version of SWIG can be specified using the stan‐
14797 dard syntax, e.g. find_package(SWIG 1.1)
14798 All information is collected from the SWIG_EXECUTABLE, so the version
14800 to be found can be changed from the command line by means of setting
14801 SWIG_EXECUTABLE
14802 FindTCL
14804 TK_INTERNAL_PATH was removed.
14805 This module finds if Tcl is installed and determines where the include
14807 files and libraries are. It also determines what the name of the
14808 library is. This code sets the following variables:
14809 TCL_FOUND = Tcl was found
14811 TK_FOUND = Tk was found
14812 TCLTK_FOUND = Tcl and Tk were found
14813 TCL_LIBRARY = path to Tcl library (tcl tcl80)
14814 TCL_INCLUDE_PATH = path to where tcl.h can be found
14815 TCL_TCLSH = path to tclsh binary (tcl tcl80)
14816 TK_LIBRARY = path to Tk library (tk tk80 etc)
14817 TK_INCLUDE_PATH = path to where tk.h can be found
14818 TK_WISH = full path to the wish executable
14819 In an effort to remove some clutter and clear up some issues for people
14821 who are not necessarily Tcl/Tk gurus/developers, some variables were
14822 moved or removed. Changes compared to CMake 2.4 are:
14823 => they were only useful for people writing Tcl/Tk extensions.
14825 => these libs are not packaged by default with Tcl/Tk distributions.
14826 Even when Tcl/Tk is built from source, several flavors of debug libs
14827 are created and there is no real reason to pick a single one
14828 specifically (say, amongst tcl84g, tcl84gs, or tcl84sgx).
14829 Let's leave that choice to the user by allowing him to assign
14830 TCL_LIBRARY to any Tcl library, debug or not.
14831 => this ended up being only a Win32 variable, and there is a lot of
14832 confusion regarding the location of this file in an installed Tcl/Tk
14833 tree anyway (see 8.5 for example). If you need the internal path at
14834 this point it is safer you ask directly where the *source* tree is
14835 and dig from there.
14836 FindTclsh
14838 Find tclsh
14839 This module finds if TCL is installed and determines where the include
14841 files and libraries are. It also determines what the name of the
14842 library is. This code sets the following variables:
14843 TCLSH_FOUND = TRUE if tclsh has been found
14845 TCL_TCLSH = the path to the tclsh executable
14846 In cygwin, look for the cygwin version first. Don’t look for it later
14848 to avoid finding the cygwin version on a Win32 build.
14849 FindTclStub
14851 TCL_STUB_LIBRARY_DEBUG and TK_STUB_LIBRARY_DEBUG were removed.
14852 This module finds Tcl stub libraries. It first finds Tcl include files
14854 and libraries by calling FindTCL.cmake. How to Use the Tcl Stubs
14855 Library:
14856 http://tcl.activestate.com/doc/howto/stubs.html
14858 Using Stub Libraries:
14860 http://safari.oreilly.com/0130385603/ch48lev1sec3
14862 This code sets the following variables:
14864 TCL_STUB_LIBRARY = path to Tcl stub library
14866 TK_STUB_LIBRARY = path to Tk stub library
14867 TTK_STUB_LIBRARY = path to ttk stub library
14868 In an effort to remove some clutter and clear up some issues for people
14870 who are not necessarily Tcl/Tk gurus/developers, some variables were
14871 moved or removed. Changes compared to CMake 2.4 are:
14872 => these libs are not packaged by default with Tcl/Tk distributions.
14874 Even when Tcl/Tk is built from source, several flavors of debug libs
14875 are created and there is no real reason to pick a single one
14876 specifically (say, amongst tclstub84g, tclstub84gs, or tclstub84sgx).
14877 Let's leave that choice to the user by allowing him to assign
14878 TCL_STUB_LIBRARY to any Tcl library, debug or not.
14879 FindThreads
14881 This module determines the thread library of the system.
14882 The following variables are set
14884 CMAKE_THREAD_LIBS_INIT - the thread library
14886 CMAKE_USE_WIN32_THREADS_INIT - using WIN32 threads?
14887 CMAKE_USE_PTHREADS_INIT - are we using pthreads
14888 CMAKE_HP_PTHREADS_INIT - are we using hp pthreads
14889 The following import target is created
14891 Threads::Threads
14893 If the use of the -pthread compiler and linker flag is preferred then
14895 the caller can set
14896 THREADS_PREFER_PTHREAD_FLAG
14898 The compiler flag can only be used with the imported target. Use of
14900 both the imported target as well as this switch is highly recommended
14901 for new code.
14902 FindTIFF
14904 Find the TIFF library (libtiff).
14905 Imported targets
14907 This module defines the following IMPORTED targets:
14908 TIFF::TIFF
14910 The TIFF library, if found.
14911 Result variables
14913 This module will set the following variables in your project:
14914 TIFF_FOUND
14916 true if the TIFF headers and libraries were found
14917 TIFF_INCLUDE_DIR
14919 the directory containing the TIFF headers
14920 TIFF_INCLUDE_DIRS
14922 the directory containing the TIFF headers
14923 TIFF_LIBRARIES
14925 TIFF libraries to be linked
14926 Cache variables
14928 The following cache variables may also be set:
14929 TIFF_INCLUDE_DIR
14931 the directory containing the TIFF headers
14932 TIFF_LIBRARY
14934 the path to the TIFF library
14935 FindUnixCommands
14937 Find Unix commands, including the ones from Cygwin
14938 This module looks for the Unix commands bash, cp, gzip, mv, rm, and tar
14940 and stores the result in the variables BASH, CP, GZIP, MV, RM, and TAR.
14941 FindVTK
14943 This module no longer exists.
14944 This module existed in versions of CMake prior to 3.1, but became only
14946 a thin wrapper around find_package(VTK NO_MODULE) to provide compati‐
14947 bility for projects using long-outdated conventions. Now find_pack‐
14948 age(VTK) will search for VTKConfig.cmake directly.
14949 FindVulkan
14951 Find Vulkan, which is a low-overhead, cross-platform 3D graphics and
14952 computing API.
14953 IMPORTED Targets
14955 This module defines IMPORTED target Vulkan::Vulkan, if Vulkan has been
14956 found.
14957 Result Variables
14959 This module defines the following variables:
14960 Vulkan_FOUND - "True" if Vulkan was found
14962 Vulkan_INCLUDE_DIRS - include directories for Vulkan
14963 Vulkan_LIBRARIES - link against this library to use Vulkan
14964 The module will also define two cache variables:
14966 Vulkan_INCLUDE_DIR - the Vulkan include directory
14968 Vulkan_LIBRARY - the path to the Vulkan library
14969 FindWget
14971 Find wget
14972 This module looks for wget. This module defines the following values:
14974 WGET_EXECUTABLE: the full path to the wget tool.
14976 WGET_FOUND: True if wget has been found.
14977 FindWish
14979 Find wish installation
14980 This module finds if TCL is installed and determines where the include
14982 files and libraries are. It also determines what the name of the
14983 library is. This code sets the following variables:
14984 TK_WISH = the path to the wish executable
14986 if UNIX is defined, then it will look for the cygwin version first
14988 FindwxWidgets
14990 Find a wxWidgets (a.k.a., wxWindows) installation.
14991 This module finds if wxWidgets is installed and selects a default con‐
14993 figuration to use. wxWidgets is a modular library. To specify the
14994 modules that you will use, you need to name them as components to the
14995 package:
14996 find_package(wxWidgets COMPONENTS core base … OPTIONAL_COMPONENTS net
14998 …)
14999 There are two search branches: a windows style and a unix style. For
15001 windows, the following variables are searched for and set to defaults
15002 in case of multiple choices. Change them if the defaults are not
15003 desired (i.e., these are the only variables you should change to select
15004 a configuration):
15005 wxWidgets_ROOT_DIR - Base wxWidgets directory
15007 (e.g., C:/wxWidgets-2.6.3).
15008 wxWidgets_LIB_DIR - Path to wxWidgets libraries
15009 (e.g., C:/wxWidgets-2.6.3/lib/vc_lib).
15010 wxWidgets_CONFIGURATION - Configuration to use
15011 (e.g., msw, mswd, mswu, mswunivud, etc.)
15012 wxWidgets_EXCLUDE_COMMON_LIBRARIES
15013 - Set to TRUE to exclude linking of
15014 commonly required libs (e.g., png tiff
15015 jpeg zlib regex expat).
15016 For unix style it uses the wx-config utility. You can select between
15018 debug/release, unicode/ansi, universal/non-universal, and static/shared
15019 in the QtDialog or ccmake interfaces by turning ON/OFF the following
15020 variables:
15021 wxWidgets_USE_DEBUG
15023 wxWidgets_USE_UNICODE
15024 wxWidgets_USE_UNIVERSAL
15025 wxWidgets_USE_STATIC
15026 There is also a wxWidgets_CONFIG_OPTIONS variable for all other options
15028 that need to be passed to the wx-config utility. For example, to use
15029 the base toolkit found in the /usr/local path, set the variable (before
15030 calling the FIND_PACKAGE command) as such:
15031 set(wxWidgets_CONFIG_OPTIONS --toolkit=base --prefix=/usr)
15033 The following are set after the configuration is done for both windows
15035 and unix style:
15036 wxWidgets_FOUND - Set to TRUE if wxWidgets was found.
15038 wxWidgets_INCLUDE_DIRS - Include directories for WIN32
15039 i.e., where to find "wx/wx.h" and
15040 "wx/setup.h"; possibly empty for unices.
15041 wxWidgets_LIBRARIES - Path to the wxWidgets libraries.
15042 wxWidgets_LIBRARY_DIRS - compile time link dirs, useful for
15043 rpath on UNIX. Typically an empty string
15044 in WIN32 environment.
15045 wxWidgets_DEFINITIONS - Contains defines required to compile/link
15046 against WX, e.g. WXUSINGDLL
15047 wxWidgets_DEFINITIONS_DEBUG- Contains defines required to compile/link
15048 against WX debug builds, e.g. __WXDEBUG__
15049 wxWidgets_CXX_FLAGS - Include dirs and compiler flags for
15050 unices, empty on WIN32. Essentially
15051 "`wx-config --cxxflags`".
15052 wxWidgets_USE_FILE - Convenience include file.
15053 Sample usage:
15055 # Note that for MinGW users the order of libs is important!
15057 find_package(wxWidgets COMPONENTS gl core base OPTIONAL_COMPONENTS net)
15058 if(wxWidgets_FOUND)
15059 include(${wxWidgets_USE_FILE})
15060 # and for each of your dependent executable/library targets:
15061 target_link_libraries(<YourTarget> ${wxWidgets_LIBRARIES})
15062 endif()
15063 If wxWidgets is required (i.e., not an optional part):
15065 find_package(wxWidgets REQUIRED gl core base OPTIONAL_COMPONENTS net)
15067 include(${wxWidgets_USE_FILE})
15068 # and for each of your dependent executable/library targets:
15069 target_link_libraries(<YourTarget> ${wxWidgets_LIBRARIES})
15070 FindXCTest
15072 Functions to help creating and executing XCTest bundles.
15073 An XCTest bundle is a CFBundle with a special product-type and bundle
15075 extension. The Mac Developer Library provides more information in the
15076 Testing with Xcode document.
15077 Module Functions
15079 xctest_add_bundle
15080 The xctest_add_bundle function creates a XCTest bundle named
15081 <target> which will test the target <testee>. Supported target
15082 types for testee are Frameworks and App Bundles:
15083 xctest_add_bundle(
15085 <target> # Name of the XCTest bundle
15086 <testee> # Target name of the testee
15087 )
15088 xctest_add_test
15090 The xctest_add_test function adds an XCTest bundle to the
15091 project to be run by ctest(1). The test will be named <name> and
15092 tests <bundle>:
15093 xctest_add_test(
15095 <name> # Test name
15096 <bundle> # Target name of XCTest bundle
15097 )
15098 Module Variables
15100 The following variables are set by including this module:
15101 XCTest_FOUND
15103 True if the XCTest Framework and executable were found.
15104 XCTest_EXECUTABLE
15106 The path to the xctest command line tool used to execute XCTest
15107 bundles.
15108 XCTest_INCLUDE_DIRS
15110 The directory containing the XCTest Framework headers.
15111 XCTest_LIBRARIES
15113 The location of the XCTest Framework.
15114 FindXalanC
15116 Find the Apache Xalan-C++ XSL transform processor headers and
15117 libraries.
15118 Imported targets
15120 This module defines the following IMPORTED targets:
15121 XalanC::XalanC
15123 The Xalan-C++ xalan-c library, if found.
15124 Result variables
15126 This module will set the following variables in your project:
15127 XalanC_FOUND
15129 true if the Xalan headers and libraries were found
15130 XalanC_VERSION
15132 Xalan release version
15133 XalanC_INCLUDE_DIRS
15135 the directory containing the Xalan headers; note
15136 XercesC_INCLUDE_DIRS is also required
15137 XalanC_LIBRARIES
15139 Xalan libraries to be linked; note XercesC_LIBRARIES is also
15140 required
15141 Cache variables
15143 The following cache variables may also be set:
15144 XalanC_INCLUDE_DIR
15146 the directory containing the Xalan headers
15147 XalanC_LIBRARY
15149 the Xalan library
15150 FindXercesC
15152 Find the Apache Xerces-C++ validating XML parser headers and libraries.
15153 Imported targets
15155 This module defines the following IMPORTED targets:
15156 XercesC::XercesC
15158 The Xerces-C++ xerces-c library, if found.
15159 Result variables
15161 This module will set the following variables in your project:
15162 XercesC_FOUND
15164 true if the Xerces headers and libraries were found
15165 XercesC_VERSION
15167 Xerces release version
15168 XercesC_INCLUDE_DIRS
15170 the directory containing the Xerces headers
15171 XercesC_LIBRARIES
15173 Xerces libraries to be linked
15174 Cache variables
15176 The following cache variables may also be set:
15177 XercesC_INCLUDE_DIR
15179 the directory containing the Xerces headers
15180 XercesC_LIBRARY
15182 the Xerces library
15183 FindX11
15185 Find X11 installation
15186 Try to find X11 on UNIX systems. The following values are defined
15188 X11_FOUND - True if X11 is available
15190 X11_INCLUDE_DIR - include directories to use X11
15191 X11_LIBRARIES - link against these to use X11
15192 and also the following more fine grained variables and targets:
15194 X11_ICE_INCLUDE_PATH, X11_ICE_LIB, X11_ICE_FOUND, X11::ICE
15196 X11_SM_INCLUDE_PATH, X11_SM_LIB, X11_SM_FOUND, X11::SM
15197 X11_X11_INCLUDE_PATH, X11_X11_LIB, X11::X11
15198 X11_Xaccessrules_INCLUDE_PATH,
15199 X11_Xaccessstr_INCLUDE_PATH, X11_Xaccess_FOUND
15200 X11_Xau_INCLUDE_PATH, X11_Xau_LIB, X11_Xau_FOUND, X11::Xau
15201 X11_Xcomposite_INCLUDE_PATH, X11_Xcomposite_LIB, X11_Xcomposite_FOUND, X11::Xcomposite
15202 X11_Xcursor_INCLUDE_PATH, X11_Xcursor_LIB, X11_Xcursor_FOUND, X11::Xcursor
15203 X11_Xdamage_INCLUDE_PATH, X11_Xdamage_LIB, X11_Xdamage_FOUND, X11::Xdamage
15204 X11_Xdmcp_INCLUDE_PATH, X11_Xdmcp_LIB, X11_Xdmcp_FOUND, X11::Xdmcp
15205 X11_Xext_INCLUDE_PATH, X11_Xext_LIB, X11_Xext_FOUND, X11::Xext
15206 X11_Xxf86misc_INCLUDE_PATH, X11_Xxf86misc_LIB, X11_Xxf86misc_FOUND, X11::Xxf86misc
15207 X11_Xxf86vm_INCLUDE_PATH, X11_Xxf86vm_LIB X11_Xxf86vm_FOUND, X11::Xxf86vm
15208 X11_Xfixes_INCLUDE_PATH, X11_Xfixes_LIB, X11_Xfixes_FOUND, X11::Xfixes
15209 X11_Xft_INCLUDE_PATH, X11_Xft_LIB, X11_Xft_FOUND, X11::Xft
15210 X11_Xi_INCLUDE_PATH, X11_Xi_LIB, X11_Xi_FOUND, X11::Xi
15211 X11_Xinerama_INCLUDE_PATH, X11_Xinerama_LIB, X11_Xinerama_FOUND, X11::Xinerama
15212 X11_Xkb_INCLUDE_PATH,
15213 X11_Xkblib_INCLUDE_PATH, X11_Xkb_FOUND, X11::Xkb
15214 X11_xkbfile_INCLUDE_PATH, X11_xkbfile_LIB, X11_xkbfile_FOUND, X11::xkbfile
15215 X11_Xmu_INCLUDE_PATH, X11_Xmu_LIB, X11_Xmu_FOUND, X11::Xmu
15216 X11_Xpm_INCLUDE_PATH, X11_Xpm_LIB, X11_Xpm_FOUND, X11::Xpm
15217 X11_Xtst_INCLUDE_PATH, X11_Xtst_LIB, X11_Xtst_FOUND, X11::Xtst
15218 X11_Xrandr_INCLUDE_PATH, X11_Xrandr_LIB, X11_Xrandr_FOUND, X11::Xrandr
15219 X11_Xrender_INCLUDE_PATH, X11_Xrender_LIB, X11_Xrender_FOUND, X11::Xrender
15220 X11_XRes_INCLUDE_PATH, X11_XRes_LIB, X11_XRes_FOUND, X11::XRes
15221 X11_Xss_INCLUDE_PATH, X11_Xss_LIB, X11_Xss_FOUND, X11::Xss
15222 X11_Xt_INCLUDE_PATH, X11_Xt_LIB, X11_Xt_FOUND, X11::Xt
15223 X11_Xutil_INCLUDE_PATH, X11_Xutil_FOUND, X11::Xutil
15224 X11_Xv_INCLUDE_PATH, X11_Xv_LIB, X11_Xv_FOUND, X11::Xv
15225 X11_dpms_INCLUDE_PATH, (in X11_Xext_LIB), X11_dpms_FOUND
15226 X11_XShm_INCLUDE_PATH, (in X11_Xext_LIB), X11_XShm_FOUND
15227 X11_Xshape_INCLUDE_PATH, (in X11_Xext_LIB), X11_Xshape_FOUND
15228 X11_XSync_INCLUDE_PATH, (in X11_Xext_LIB), X11_XSync_FOUND
15229 FindXMLRPC
15231 Find xmlrpc
15232 Find the native XMLRPC headers and libraries.
15234 XMLRPC_INCLUDE_DIRS - where to find xmlrpc.h, etc.
15236 XMLRPC_LIBRARIES - List of libraries when using xmlrpc.
15237 XMLRPC_FOUND - True if xmlrpc found.
15238 XMLRPC modules may be specified as components for this find module.
15240 Modules may be listed by running “xmlrpc-c-config”. Modules include:
15241 c++ C++ wrapper code
15243 libwww-client libwww-based client
15244 cgi-server CGI-based server
15245 abyss-server ABYSS-based server
15246 Typical usage:
15248 find_package(XMLRPC REQUIRED libwww-client)
15250 FindZLIB
15252 Find the native ZLIB includes and library.
15253 IMPORTED Targets
15255 This module defines IMPORTED target ZLIB::ZLIB, if ZLIB has been found.
15256 Result Variables
15258 This module defines the following variables:
15259 ZLIB_INCLUDE_DIRS - where to find zlib.h, etc.
15261 ZLIB_LIBRARIES - List of libraries when using zlib.
15262 ZLIB_FOUND - True if zlib found.
15263 ZLIB_VERSION_STRING - The version of zlib found (x.y.z)
15265 ZLIB_VERSION_MAJOR - The major version of zlib
15266 ZLIB_VERSION_MINOR - The minor version of zlib
15267 ZLIB_VERSION_PATCH - The patch version of zlib
15268 ZLIB_VERSION_TWEAK - The tweak version of zlib
15269 Backward Compatibility
15271 The following variable are provided for backward compatibility
15272 ZLIB_MAJOR_VERSION - The major version of zlib
15274 ZLIB_MINOR_VERSION - The minor version of zlib
15275 ZLIB_PATCH_VERSION - The patch version of zlib
15276 Hints
15278 A user may set ZLIB_ROOT to a zlib installation root to tell this mod‐
15279 ule where to look.
15280
15282 Deprecated Utility Modules
15283 CMakeDetermineVSServicePack
15284 Deprecated since version 3.0: Do not use.
15285 The functionality of this module has been superseded by the
15288 CMAKE_<LANG>_COMPILER_VERSION variable that contains the compiler ver‐
15289 sion number.
15290 Determine the Visual Studio service pack of the ‘cl’ in use.
15292 Usage:
15294 if(MSVC)
15296 include(CMakeDetermineVSServicePack)
15297 DetermineVSServicePack( my_service_pack )
15298 if( my_service_pack )
15299 message(STATUS "Detected: ${my_service_pack}")
15300 endif()
15301 endif()
15302 Function DetermineVSServicePack sets the given variable to one of the
15304 following values or an empty string if unknown:
15305 vc80, vc80sp1
15307 vc90, vc90sp1
15308 vc100, vc100sp1
15309 vc110, vc110sp1, vc110sp2, vc110sp3, vc110sp4
15310 CMakeExpandImportedTargets
15312 Deprecated since version 3.4: Do not use.
15313 This module was once needed to expand imported targets to the underly‐
15316 ing libraries they reference on disk for use with the try_compile() and
15317 try_run() commands. These commands now support imported libraries in
15318 their LINK_LIBRARIES options (since CMake 2.8.11 for try_compile() and
15319 since CMake 3.2 for try_run()).
15320 This module does not support the policy CMP0022 NEW behavior or use of
15322 the INTERFACE_LINK_LIBRARIES property because generator expressions
15323 cannot be evaluated during configuration.
15324 CMAKE_EXPAND_IMPORTED_TARGETS(<var> LIBRARIES lib1 lib2...libN
15326 [CONFIGURATION <config>])
15327 CMAKE_EXPAND_IMPORTED_TARGETS() takes a list of libraries and replaces
15329 all imported targets contained in this list with their actual file
15330 paths of the referenced libraries on disk, including the libraries from
15331 their link interfaces. If a CONFIGURATION is given, it uses the
15332 respective configuration of the imported targets if it exists. If no
15333 CONFIGURATION is given, it uses the first configuration from
15334 ${CMAKE_CONFIGURATION_TYPES} if set, otherwise ${CMAKE_BUILD_TYPE}.
15335 cmake_expand_imported_targets(expandedLibs
15337 LIBRARIES ${CMAKE_REQUIRED_LIBRARIES}
15338 CONFIGURATION "${CMAKE_TRY_COMPILE_CONFIGURATION}" )
15339 CMakeForceCompiler
15341 Deprecated since version 3.6: Do not use.
15342 The macros provided by this module were once intended for use by
15345 cross-compiling toolchain files when CMake was not able to automati‐
15346 cally detect the compiler identification. Since the introduction of
15347 this module, CMake’s compiler identification capabilities have improved
15348 and can now be taught to recognize any compiler. Furthermore, the
15349 suite of information CMake detects from a compiler is now too extensive
15350 to be provided by toolchain files using these macros.
15351 One common use case for this module was to skip CMake’s checks for a
15353 working compiler when using a cross-compiler that cannot link binaries
15354 without special flags or custom linker scripts. This case is now sup‐
15355 ported by setting the CMAKE_TRY_COMPILE_TARGET_TYPE variable in the
15356 toolchain file instead.
15357 ----
15360 Macro CMAKE_FORCE_C_COMPILER has the following signature:
15364 CMAKE_FORCE_C_COMPILER(<compiler> <compiler-id>)
15366 It sets CMAKE_C_COMPILER to the given compiler and the cmake internal
15368 variable CMAKE_C_COMPILER_ID to the given compiler-id. It also
15369 bypasses the check for working compiler and basic compiler information
15370 tests.
15371 Macro CMAKE_FORCE_CXX_COMPILER has the following signature:
15373 CMAKE_FORCE_CXX_COMPILER(<compiler> <compiler-id>)
15375 It sets CMAKE_CXX_COMPILER to the given compiler and the cmake internal
15377 variable CMAKE_CXX_COMPILER_ID to the given compiler-id. It also
15378 bypasses the check for working compiler and basic compiler information
15379 tests.
15380 Macro CMAKE_FORCE_Fortran_COMPILER has the following signature:
15382 CMAKE_FORCE_Fortran_COMPILER(<compiler> <compiler-id>)
15384 It sets CMAKE_Fortran_COMPILER to the given compiler and the cmake
15386 internal variable CMAKE_Fortran_COMPILER_ID to the given compiler-id.
15387 It also bypasses the check for working compiler and basic compiler
15388 information tests.
15389 So a simple toolchain file could look like this:
15391 include (CMakeForceCompiler)
15393 set(CMAKE_SYSTEM_NAME Generic)
15394 CMAKE_FORCE_C_COMPILER (chc12 MetrowerksHicross)
15395 CMAKE_FORCE_CXX_COMPILER (chc12 MetrowerksHicross)
15396 CMakeParseArguments
15398 This module once implemented the cmake_parse_arguments() command that
15399 is now implemented natively by CMake. It is now an empty placeholder
15400 for compatibility with projects that include it to get the command from
15401 CMake 3.4 and lower.
15402 MacroAddFileDependencies
15404 MACRO_ADD_FILE_DEPENDENCIES(<_file> depend_files…)
15405 Using the macro MACRO_ADD_FILE_DEPENDENCIES() is discouraged. There
15407 are usually better ways to specify the correct dependencies.
15408 MACRO_ADD_FILE_DEPENDENCIES(<_file> depend_files…) is just a conve‐
15410 nience wrapper around the OBJECT_DEPENDS source file property. You can
15411 just use set_property(SOURCE <file> APPEND PROPERTY OBJECT_DEPENDS
15412 depend_files) instead.
15413 TestCXXAcceptsFlag
15415 Deprecated since version 3.0: See CheckCXXCompilerFlag.
15416 Check if the CXX compiler accepts a flag.
15419 CHECK_CXX_ACCEPTS_FLAG(<flags> <variable>)
15421 <flags>
15423 the flags to try
15424 <variable>
15426 variable to store the result
15427 UsePkgConfig
15429 Obsolete pkg-config module for CMake, use FindPkgConfig instead.
15430 This module defines the following macro:
15432 PKGCONFIG(package includedir libdir linkflags cflags)
15434 Calling PKGCONFIG will fill the desired information into the 4 given
15436 arguments, e.g. PKGCONFIG(libart-2.0 LIBART_INCLUDE_DIR
15437 LIBART_LINK_DIR LIBART_LINK_FLAGS LIBART_CFLAGS) if pkg-config was NOT
15438 found or the specified software package doesn’t exist, the variable
15439 will be empty when the function returns, otherwise they will contain
15440 the respective information
15441 Use_wxWindows
15443 Deprecated since version 2.8.10: Use find_package(wxWidgets) and
15444 include(${wxWidgets_USE_FILE}) instead.
15445 This convenience include finds if wxWindows is installed and set the
15448 appropriate libs, incdirs, flags etc. author Jan Woetzel <jw -at-
15449 mip.informatik.uni-kiel.de> (07/2003)
15450 USAGE:
15452 just include Use_wxWindows.cmake
15454 in your projects CMakeLists.txt
15455 include( ${CMAKE_MODULE_PATH}/Use_wxWindows.cmake)
15457 if you are sure you need GL then
15459 set(WXWINDOWS_USE_GL 1)
15461 *before* you include this file.
15463 WriteBasicConfigVersionFile
15465 Deprecated since version 3.0: Use the identical command
15466 write_basic_package_version_file() from module CMakePackageCon‐
15467 figHelpers.
15468 WRITE_BASIC_CONFIG_VERSION_FILE( filename
15471 [VERSION major.minor.patch]
15472 COMPATIBILITY (AnyNewerVersion|SameMajorVersion|SameMinorVersion|ExactVersion)
15473 [ARCH_INDEPENDENT]
15474 )
15475 Deprecated Find Modules
15477 FindCUDA
15478 Deprecated since version 3.10: Superseded by first-class support for
15479 the CUDA language in CMake.
15480 Replacement
15483 It is no longer necessary to use this module or call find_pack‐
15484 age(CUDA). Instead, list CUDA among the languages named in the
15485 top-level call to the project() command, or call the enable_language()
15486 command with CUDA. Then one can add CUDA (.cu) sources to programs
15487 directly in calls to add_library() and add_executable().
15488 Documentation of Deprecated Usage
15490 Tools for building CUDA C files: libraries and build dependencies.
15491 This script locates the NVIDIA CUDA C tools. It should work on Linux,
15493 Windows, and macOS and should be reasonably up to date with CUDA C
15494 releases.
15495 This script makes use of the standard find_package() arguments of <VER‐
15497 SION>, REQUIRED and QUIET. CUDA_FOUND will report if an acceptable
15498 version of CUDA was found.
15499 The script will prompt the user to specify CUDA_TOOLKIT_ROOT_DIR if the
15501 prefix cannot be determined by the location of nvcc in the system path
15502 and REQUIRED is specified to find_package(). To use a different
15503 installed version of the toolkit set the environment variable
15504 CUDA_BIN_PATH before running cmake (e.g.
15505 CUDA_BIN_PATH=/usr/local/cuda1.0 instead of the default
15506 /usr/local/cuda) or set CUDA_TOOLKIT_ROOT_DIR after configuring. If
15507 you change the value of CUDA_TOOLKIT_ROOT_DIR, various components that
15508 depend on the path will be relocated.
15509 It might be necessary to set CUDA_TOOLKIT_ROOT_DIR manually on certain
15511 platforms, or to use a CUDA runtime not installed in the default loca‐
15512 tion. In newer versions of the toolkit the CUDA library is included
15513 with the graphics driver – be sure that the driver version matches what
15514 is needed by the CUDA runtime version.
15515 The following variables affect the behavior of the macros in the script
15517 (in alphabetical order). Note that any of these flags can be changed
15518 multiple times in the same directory before calling CUDA_ADD_EXE‐
15519 CUTABLE, CUDA_ADD_LIBRARY, CUDA_COMPILE, CUDA_COMPILE_PTX, CUDA_COM‐
15520 PILE_FATBIN, CUDA_COMPILE_CUBIN or CUDA_WRAP_SRCS:
15521 CUDA_64_BIT_DEVICE_CODE (Default matches host bit size)
15523 -- Set to ON to compile for 64 bit device code, OFF for 32 bit device code.
15524 Note that making this different from the host code when generating object
15525 or C files from CUDA code just won't work, because size_t gets defined by
15526 nvcc in the generated source. If you compile to PTX and then load the
15527 file yourself, you can mix bit sizes between device and host.
15528 CUDA_ATTACH_VS_BUILD_RULE_TO_CUDA_FILE (Default ON)
15530 -- Set to ON if you want the custom build rule to be attached to the source
15531 file in Visual Studio. Turn OFF if you add the same cuda file to multiple
15532 targets.
15533 This allows the user to build the target from the CUDA file; however, bad
15535 things can happen if the CUDA source file is added to multiple targets.
15536 When performing parallel builds it is possible for the custom build
15537 command to be run more than once and in parallel causing cryptic build
15538 errors. VS runs the rules for every source file in the target, and a
15539 source can have only one rule no matter how many projects it is added to.
15540 When the rule is run from multiple targets race conditions can occur on
15541 the generated file. Eventually everything will get built, but if the user
15542 is unaware of this behavior, there may be confusion. It would be nice if
15543 this script could detect the reuse of source files across multiple targets
15544 and turn the option off for the user, but no good solution could be found.
15545 CUDA_BUILD_CUBIN (Default OFF)
15547 -- Set to ON to enable and extra compilation pass with the -cubin option in
15548 Device mode. The output is parsed and register, shared memory usage is
15549 printed during build.
15550 CUDA_BUILD_EMULATION (Default OFF for device mode)
15552 -- Set to ON for Emulation mode. -D_DEVICEEMU is defined for CUDA C files
15553 when CUDA_BUILD_EMULATION is TRUE.
15554 CUDA_LINK_LIBRARIES_KEYWORD (Default "")
15556 -- The <PRIVATE|PUBLIC|INTERFACE> keyword to use for internal
15557 target_link_libraries calls. The default is to use no keyword which
15558 uses the old "plain" form of target_link_libraries. Note that is matters
15559 because whatever is used inside the FindCUDA module must also be used
15560 outside - the two forms of target_link_libraries cannot be mixed.
15561 CUDA_GENERATED_OUTPUT_DIR (Default CMAKE_CURRENT_BINARY_DIR)
15563 -- Set to the path you wish to have the generated files placed. If it is
15564 blank output files will be placed in CMAKE_CURRENT_BINARY_DIR.
15565 Intermediate files will always be placed in
15566 CMAKE_CURRENT_BINARY_DIR/CMakeFiles.
15567 CUDA_HOST_COMPILATION_CPP (Default ON)
15569 -- Set to OFF for C compilation of host code.
15570 CUDA_HOST_COMPILER (Default CMAKE_C_COMPILER)
15572 -- Set the host compiler to be used by nvcc. Ignored if -ccbin or
15573 --compiler-bindir is already present in the CUDA_NVCC_FLAGS or
15574 CUDA_NVCC_FLAGS_<CONFIG> variables. For Visual Studio targets,
15575 the host compiler is constructed with one or more visual studio macros
15576 such as $(VCInstallDir), that expands out to the path when
15577 the command is run from within VS.
15578 If the CUDAHOSTCXX environment variable is set it will
15579 be used as the default.
15580 CUDA_NVCC_FLAGS
15582 CUDA_NVCC_FLAGS_<CONFIG>
15583 -- Additional NVCC command line arguments. NOTE: multiple arguments must be
15584 semi-colon delimited (e.g. --compiler-options;-Wall)
15585 CUDA_PROPAGATE_HOST_FLAGS (Default ON)
15587 -- Set to ON to propagate CMAKE_{C,CXX}_FLAGS and their configuration
15588 dependent counterparts (e.g. CMAKE_C_FLAGS_DEBUG) automatically to the
15589 host compiler through nvcc's -Xcompiler flag. This helps make the
15590 generated host code match the rest of the system better. Sometimes
15591 certain flags give nvcc problems, and this will help you turn the flag
15592 propagation off. This does not affect the flags supplied directly to nvcc
15593 via CUDA_NVCC_FLAGS or through the OPTION flags specified through
15594 CUDA_ADD_LIBRARY, CUDA_ADD_EXECUTABLE, or CUDA_WRAP_SRCS. Flags used for
15595 shared library compilation are not affected by this flag.
15596 CUDA_SEPARABLE_COMPILATION (Default OFF)
15598 -- If set this will enable separable compilation for all CUDA runtime object
15599 files. If used outside of CUDA_ADD_EXECUTABLE and CUDA_ADD_LIBRARY
15600 (e.g. calling CUDA_WRAP_SRCS directly),
15601 CUDA_COMPUTE_SEPARABLE_COMPILATION_OBJECT_FILE_NAME and
15602 CUDA_LINK_SEPARABLE_COMPILATION_OBJECTS should be called.
15603 CUDA_SOURCE_PROPERTY_FORMAT
15605 -- If this source file property is set, it can override the format specified
15606 to CUDA_WRAP_SRCS (OBJ, PTX, CUBIN, or FATBIN). If an input source file
15607 is not a .cu file, setting this file will cause it to be treated as a .cu
15608 file. See documentation for set_source_files_properties on how to set
15609 this property.
15610 CUDA_USE_STATIC_CUDA_RUNTIME (Default ON)
15612 -- When enabled the static version of the CUDA runtime library will be used
15613 in CUDA_LIBRARIES. If the version of CUDA configured doesn't support
15614 this option, then it will be silently disabled.
15615 CUDA_VERBOSE_BUILD (Default OFF)
15617 -- Set to ON to see all the commands used when building the CUDA file. When
15618 using a Makefile generator the value defaults to VERBOSE (run make
15619 VERBOSE=1 to see output), although setting CUDA_VERBOSE_BUILD to ON will
15620 always print the output.
15621 The script creates the following macros (in alphabetical order):
15623 CUDA_ADD_CUFFT_TO_TARGET( cuda_target )
15625 -- Adds the cufft library to the target (can be any target). Handles whether
15626 you are in emulation mode or not.
15627 CUDA_ADD_CUBLAS_TO_TARGET( cuda_target )
15629 -- Adds the cublas library to the target (can be any target). Handles
15630 whether you are in emulation mode or not.
15631 CUDA_ADD_EXECUTABLE( cuda_target file0 file1 ...
15633 [WIN32] [MACOSX_BUNDLE] [EXCLUDE_FROM_ALL] [OPTIONS ...] )
15634 -- Creates an executable "cuda_target" which is made up of the files
15635 specified. All of the non CUDA C files are compiled using the standard
15636 build rules specified by CMAKE and the cuda files are compiled to object
15637 files using nvcc and the host compiler. In addition CUDA_INCLUDE_DIRS is
15638 added automatically to include_directories(). Some standard CMake target
15639 calls can be used on the target after calling this macro
15640 (e.g. set_target_properties and target_link_libraries), but setting
15641 properties that adjust compilation flags will not affect code compiled by
15642 nvcc. Such flags should be modified before calling CUDA_ADD_EXECUTABLE,
15643 CUDA_ADD_LIBRARY or CUDA_WRAP_SRCS.
15644 CUDA_ADD_LIBRARY( cuda_target file0 file1 ...
15646 [STATIC | SHARED | MODULE] [EXCLUDE_FROM_ALL] [OPTIONS ...] )
15647 -- Same as CUDA_ADD_EXECUTABLE except that a library is created.
15648 CUDA_BUILD_CLEAN_TARGET()
15650 -- Creates a convenience target that deletes all the dependency files
15651 generated. You should make clean after running this target to ensure the
15652 dependency files get regenerated.
15653 CUDA_COMPILE( generated_files file0 file1 ... [STATIC | SHARED | MODULE]
15655 [OPTIONS ...] )
15656 -- Returns a list of generated files from the input source files to be used
15657 with ADD_LIBRARY or ADD_EXECUTABLE.
15658 CUDA_COMPILE_PTX( generated_files file0 file1 ... [OPTIONS ...] )
15660 -- Returns a list of PTX files generated from the input source files.
15661 CUDA_COMPILE_FATBIN( generated_files file0 file1 ... [OPTIONS ...] )
15663 -- Returns a list of FATBIN files generated from the input source files.
15664 CUDA_COMPILE_CUBIN( generated_files file0 file1 ... [OPTIONS ...] )
15666 -- Returns a list of CUBIN files generated from the input source files.
15667 CUDA_COMPUTE_SEPARABLE_COMPILATION_OBJECT_FILE_NAME( output_file_var
15669 cuda_target
15670 object_files )
15671 -- Compute the name of the intermediate link file used for separable
15672 compilation. This file name is typically passed into
15673 CUDA_LINK_SEPARABLE_COMPILATION_OBJECTS. output_file_var is produced
15674 based on cuda_target the list of objects files that need separable
15675 compilation as specified by object_files. If the object_files list is
15676 empty, then output_file_var will be empty. This function is called
15677 automatically for CUDA_ADD_LIBRARY and CUDA_ADD_EXECUTABLE. Note that
15678 this is a function and not a macro.
15679 CUDA_INCLUDE_DIRECTORIES( path0 path1 ... )
15681 -- Sets the directories that should be passed to nvcc
15682 (e.g. nvcc -Ipath0 -Ipath1 ... ). These paths usually contain other .cu
15683 files.
15684 CUDA_LINK_SEPARABLE_COMPILATION_OBJECTS( output_file_var cuda_target
15687 nvcc_flags object_files)
15688 -- Generates the link object required by separable compilation from the given
15689 object files. This is called automatically for CUDA_ADD_EXECUTABLE and
15690 CUDA_ADD_LIBRARY, but can be called manually when using CUDA_WRAP_SRCS
15691 directly. When called from CUDA_ADD_LIBRARY or CUDA_ADD_EXECUTABLE the
15692 nvcc_flags passed in are the same as the flags passed in via the OPTIONS
15693 argument. The only nvcc flag added automatically is the bitness flag as
15694 specified by CUDA_64_BIT_DEVICE_CODE. Note that this is a function
15695 instead of a macro.
15696 CUDA_SELECT_NVCC_ARCH_FLAGS(out_variable [target_CUDA_architectures])
15698 -- Selects GPU arch flags for nvcc based on target_CUDA_architectures
15699 target_CUDA_architectures : Auto | Common | All | LIST(ARCH_AND_PTX ...)
15700 - "Auto" detects local machine GPU compute arch at runtime.
15701 - "Common" and "All" cover common and entire subsets of architectures
15702 ARCH_AND_PTX : NAME | NUM.NUM | NUM.NUM(NUM.NUM) | NUM.NUM+PTX
15703 NAME: Fermi Kepler Maxwell Kepler+Tegra Kepler+Tesla Maxwell+Tegra Pascal
15704 NUM: Any number. Only those pairs are currently accepted by NVCC though:
15705 2.0 2.1 3.0 3.2 3.5 3.7 5.0 5.2 5.3 6.0 6.2
15706 Returns LIST of flags to be added to CUDA_NVCC_FLAGS in ${out_variable}
15707 Additionally, sets ${out_variable}_readable to the resulting numeric list
15708 Example:
15709 CUDA_SELECT_NVCC_ARCH_FLAGS(ARCH_FLAGS 3.0 3.5+PTX 5.2(5.0) Maxwell)
15710 LIST(APPEND CUDA_NVCC_FLAGS ${ARCH_FLAGS})
15711 More info on CUDA architectures: https://en.wikipedia.org/wiki/CUDA
15713 Note that this is a function instead of a macro.
15714 CUDA_WRAP_SRCS ( cuda_target format generated_files file0 file1 ...
15716 [STATIC | SHARED | MODULE] [OPTIONS ...] )
15717 -- This is where all the magic happens. CUDA_ADD_EXECUTABLE,
15718 CUDA_ADD_LIBRARY, CUDA_COMPILE, and CUDA_COMPILE_PTX all call this
15719 function under the hood.
15720 Given the list of files (file0 file1 ... fileN) this macro generates
15722 custom commands that generate either PTX or linkable objects (use "PTX" or
15723 "OBJ" for the format argument to switch). Files that don't end with .cu
15724 or have the HEADER_FILE_ONLY property are ignored.
15725 The arguments passed in after OPTIONS are extra command line options to
15727 give to nvcc. You can also specify per configuration options by
15728 specifying the name of the configuration followed by the options. General
15729 options must precede configuration specific options. Not all
15730 configurations need to be specified, only the ones provided will be used.
15731 OPTIONS -DFLAG=2 "-DFLAG_OTHER=space in flag"
15733 DEBUG -g
15734 RELEASE --use_fast_math
15735 RELWITHDEBINFO --use_fast_math;-g
15736 MINSIZEREL --use_fast_math
15737 For certain configurations (namely VS generating object files with
15739 CUDA_ATTACH_VS_BUILD_RULE_TO_CUDA_FILE set to ON), no generated file will
15740 be produced for the given cuda file. This is because when you add the
15741 cuda file to Visual Studio it knows that this file produces an object file
15742 and will link in the resulting object file automatically.
15743 This script will also generate a separate cmake script that is used at
15745 build time to invoke nvcc. This is for several reasons.
15746 1. nvcc can return negative numbers as return values which confuses
15748 Visual Studio into thinking that the command succeeded. The script now
15749 checks the error codes and produces errors when there was a problem.
15750 2. nvcc has been known to not delete incomplete results when it
15752 encounters problems. This confuses build systems into thinking the
15753 target was generated when in fact an unusable file exists. The script
15754 now deletes the output files if there was an error.
15755 3. By putting all the options that affect the build into a file and then
15757 make the build rule dependent on the file, the output files will be
15758 regenerated when the options change.
15759 This script also looks at optional arguments STATIC, SHARED, or MODULE to
15761 determine when to target the object compilation for a shared library.
15762 BUILD_SHARED_LIBS is ignored in CUDA_WRAP_SRCS, but it is respected in
15763 CUDA_ADD_LIBRARY. On some systems special flags are added for building
15764 objects intended for shared libraries. A preprocessor macro,
15765 <target_name>_EXPORTS is defined when a shared library compilation is
15766 detected.
15767 Flags passed into add_definitions with -D or /D are passed along to nvcc.
15769 The script defines the following variables:
15771 CUDA_VERSION_MAJOR -- The major version of cuda as reported by nvcc.
15773 CUDA_VERSION_MINOR -- The minor version.
15774 CUDA_VERSION
15775 CUDA_VERSION_STRING -- CUDA_VERSION_MAJOR.CUDA_VERSION_MINOR
15776 CUDA_HAS_FP16 -- Whether a short float (float16,fp16) is supported.
15777 CUDA_TOOLKIT_ROOT_DIR -- Path to the CUDA Toolkit (defined if not set).
15779 CUDA_SDK_ROOT_DIR -- Path to the CUDA SDK. Use this to find files in the
15780 SDK. This script will not directly support finding
15781 specific libraries or headers, as that isn't
15782 supported by NVIDIA. If you want to change
15783 libraries when the path changes see the
15784 FindCUDA.cmake script for an example of how to clear
15785 these variables. There are also examples of how to
15786 use the CUDA_SDK_ROOT_DIR to locate headers or
15787 libraries, if you so choose (at your own risk).
15788 CUDA_INCLUDE_DIRS -- Include directory for cuda headers. Added automatically
15789 for CUDA_ADD_EXECUTABLE and CUDA_ADD_LIBRARY.
15790 CUDA_LIBRARIES -- Cuda RT library.
15791 CUDA_CUFFT_LIBRARIES -- Device or emulation library for the Cuda FFT
15792 implementation (alternative to:
15793 CUDA_ADD_CUFFT_TO_TARGET macro)
15794 CUDA_CUBLAS_LIBRARIES -- Device or emulation library for the Cuda BLAS
15795 implementation (alternative to:
15796 CUDA_ADD_CUBLAS_TO_TARGET macro).
15797 CUDA_cudart_static_LIBRARY -- Statically linkable cuda runtime library.
15798 Only available for CUDA version 5.5+
15799 CUDA_cudadevrt_LIBRARY -- Device runtime library.
15800 Required for separable compilation.
15801 CUDA_cupti_LIBRARY -- CUDA Profiling Tools Interface library.
15802 Only available for CUDA version 4.0+.
15803 CUDA_curand_LIBRARY -- CUDA Random Number Generation library.
15804 Only available for CUDA version 3.2+.
15805 CUDA_cusolver_LIBRARY -- CUDA Direct Solver library.
15806 Only available for CUDA version 7.0+.
15807 CUDA_cusparse_LIBRARY -- CUDA Sparse Matrix library.
15808 Only available for CUDA version 3.2+.
15809 CUDA_npp_LIBRARY -- NVIDIA Performance Primitives lib.
15810 Only available for CUDA version 4.0+.
15811 CUDA_nppc_LIBRARY -- NVIDIA Performance Primitives lib (core).
15812 Only available for CUDA version 5.5+.
15813 CUDA_nppi_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
15814 Only available for CUDA version 5.5 - 8.0.
15815 CUDA_nppial_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
15816 Only available for CUDA version 9.0.
15817 CUDA_nppicc_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
15818 Only available for CUDA version 9.0.
15819 CUDA_nppicom_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
15820 Only available for CUDA version 9.0.
15821 CUDA_nppidei_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
15822 Only available for CUDA version 9.0.
15823 CUDA_nppif_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
15824 Only available for CUDA version 9.0.
15825 CUDA_nppig_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
15826 Only available for CUDA version 9.0.
15827 CUDA_nppim_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
15828 Only available for CUDA version 9.0.
15829 CUDA_nppist_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
15830 Only available for CUDA version 9.0.
15831 CUDA_nppisu_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
15832 Only available for CUDA version 9.0.
15833 CUDA_nppitc_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
15834 Only available for CUDA version 9.0.
15835 CUDA_npps_LIBRARY -- NVIDIA Performance Primitives lib (signal processing).
15836 Only available for CUDA version 5.5+.
15837 CUDA_nvcuvenc_LIBRARY -- CUDA Video Encoder library.
15838 Only available for CUDA version 3.2+.
15839 Windows only.
15840 CUDA_nvcuvid_LIBRARY -- CUDA Video Decoder library.
15841 Only available for CUDA version 3.2+.
15842 Windows only.
15843 CUDA_nvToolsExt_LIBRARY
15844 -- NVIDA CUDA Tools Extension library.
15845 Available for CUDA version 5+.
15846 CUDA_OpenCL_LIBRARY -- NVIDA CUDA OpenCL library.
15847 Available for CUDA version 5+.
15848 FindPythonInterp
15850 Deprecated since version 3.12: Use FindPython3, FindPython2 or Find‐
15851 Python instead.
15852 Find python interpreter
15855 This module finds if Python interpreter is installed and determines
15857 where the executables are. This code sets the following variables:
15858 PYTHONINTERP_FOUND - Was the Python executable found
15860 PYTHON_EXECUTABLE - path to the Python interpreter
15861 PYTHON_VERSION_STRING - Python version found e.g. 2.5.2
15863 PYTHON_VERSION_MAJOR - Python major version found e.g. 2
15864 PYTHON_VERSION_MINOR - Python minor version found e.g. 5
15865 PYTHON_VERSION_PATCH - Python patch version found e.g. 2
15866 The Python_ADDITIONAL_VERSIONS variable can be used to specify a list
15868 of version numbers that should be taken into account when searching for
15869 Python. You need to set this variable before calling find_pack‐
15870 age(PythonInterp).
15871 If calling both find_package(PythonInterp) and find_package(Python‐
15873 Libs), call find_package(PythonInterp) first to get the currently
15874 active Python version by default with a consistent version of
15875 PYTHON_LIBRARIES.
15876 NOTE:
15878 A call to find_package(PythonInterp ${V}) for python version V may
15879 find a python executable with no version suffix. In this case no
15880 attempt is made to avoid python executables from other versions.
15881 Use FindPython3, FindPython2 or FindPython instead.
15882 FindPythonLibs
15884 Deprecated since version 3.12: Use FindPython3, FindPython2 or Find‐
15885 Python instead.
15886 Find python libraries
15889 This module finds if Python is installed and determines where the
15891 include files and libraries are. It also determines what the name of
15892 the library is. This code sets the following variables:
15893 PYTHONLIBS_FOUND - have the Python libs been found
15895 PYTHON_LIBRARIES - path to the python library
15896 PYTHON_INCLUDE_PATH - path to where Python.h is found (deprecated)
15897 PYTHON_INCLUDE_DIRS - path to where Python.h is found
15898 PYTHON_DEBUG_LIBRARIES - path to the debug library (deprecated)
15899 PYTHONLIBS_VERSION_STRING - version of the Python libs found (since CMake 2.8.8)
15900 The Python_ADDITIONAL_VERSIONS variable can be used to specify a list
15902 of version numbers that should be taken into account when searching for
15903 Python. You need to set this variable before calling find_pack‐
15904 age(PythonLibs).
15905 If you’d like to specify the installation of Python to use, you should
15907 modify the following cache variables:
15908 PYTHON_LIBRARY - path to the python library
15910 PYTHON_INCLUDE_DIR - path to where Python.h is found
15911 If calling both find_package(PythonInterp) and find_package(Python‐
15913 Libs), call find_package(PythonInterp) first to get the currently
15914 active Python version by default with a consistent version of
15915 PYTHON_LIBRARIES.
15916 FindQt
15918 Searches for all installed versions of Qt3 or Qt4.
15919 This module cannot handle Qt5 or any later versions. For those, see
15921 cmake-qt(7).
15922 This module exists for the find_package() command only if policy
15924 CMP0084 is not set to NEW.
15925 This module should only be used if your project can work with multiple
15927 versions of Qt. If not, you should just directly use FindQt4 or
15928 FindQt3. If multiple versions of Qt are found on the machine, then The
15929 user must set the option DESIRED_QT_VERSION to the version they want to
15930 use. If only one version of qt is found on the machine, then the
15931 DESIRED_QT_VERSION is set to that version and the matching FindQt3 or
15932 FindQt4 module is included. Once the user sets DESIRED_QT_VERSION,
15933 then the FindQt3 or FindQt4 module is included.
15934 QT_REQUIRED if this is set to TRUE then if CMake can
15936 not find Qt4 or Qt3 an error is raised
15937 and a message is sent to the user.
15938 DESIRED_QT_VERSION OPTION is created
15940 QT4_INSTALLED is set to TRUE if qt4 is found.
15941 QT3_INSTALLED is set to TRUE if qt3 is found.
15942 FindwxWindows
15944 Deprecated since version 3.0: Replaced by FindwxWidgets.
15945 Find wxWindows (wxWidgets) installation
15948 This module finds if wxWindows/wxWidgets is installed and determines
15950 where the include files and libraries are. It also determines what the
15951 name of the library is. This code sets the following variables:
15952 WXWINDOWS_FOUND = system has WxWindows
15954 WXWINDOWS_LIBRARIES = path to the wxWindows libraries
15955 on Unix/Linux with additional
15956 linker flags from
15957 "wx-config --libs"
15958 CMAKE_WXWINDOWS_CXX_FLAGS = Compiler flags for wxWindows,
15959 essentially "`wx-config --cxxflags`"
15960 on Linux
15961 WXWINDOWS_INCLUDE_DIR = where to find "wx/wx.h" and "wx/setup.h"
15962 WXWINDOWS_LINK_DIRECTORIES = link directories, useful for rpath on
15963 Unix
15964 WXWINDOWS_DEFINITIONS = extra defines
15965 OPTIONS If you need OpenGL support please
15967 set(WXWINDOWS_USE_GL 1)
15969 in your CMakeLists.txt before you include this file.
15971 HAVE_ISYSTEM - true required to replace -I by -isystem on g++
15973 For convenience include Use_wxWindows.cmake in your project’s CMake‐
15975 Lists.txt using include(${CMAKE_CURRENT_LIST_DIR}/Use_wxWindows.cmake).
15976 USAGE
15978 set(WXWINDOWS_USE_GL 1)
15980 find_package(wxWindows)
15981 NOTES wxWidgets 2.6.x is supported for monolithic builds e.g. compiled
15983 in wx/build/msw dir as:
15984 nmake -f makefile.vc BUILD=debug SHARED=0 USE_OPENGL=1 MONOLITHIC=1
15986 DEPRECATED
15988 CMAKE_WX_CAN_COMPILE
15990 WXWINDOWS_LIBRARY
15991 CMAKE_WX_CXX_FLAGS
15992 WXWINDOWS_INCLUDE_PATH
15993 AUTHOR Jan Woetzel <http://www.mip.informatik.uni-kiel.de/~jw>
15995 (07/2003-01/2006)
15996 Legacy CPack Modules
15998 These modules used to be mistakenly exposed to the user, and have been
15999 moved out of user visibility. They are for CPack internal use, and
16000 should never be used directly.
16001 CPackArchive
16003 The documentation for the CPack Archive generator has moved here: CPack
16004 Archive Generator
16005 CPackBundle
16007 The documentation for the CPack Bundle generator has moved here: CPack
16008 Bundle Generator
16009 CPackCygwin
16011 The documentation for the CPack Cygwin generator has moved here: CPack
16012 Cygwin Generator
16013 CPackDeb
16015 The documentation for the CPack DEB generator has moved here: CPack DEB
16016 Generator
16017 CPackDMG
16019 The documentation for the CPack DragNDrop generator has moved here:
16020 CPack DragNDrop Generator
16021 CPackFreeBSD
16023 The documentation for the CPack FreeBSD generator has moved here: CPack
16024 FreeBSD Generator
16025 CPackNSIS
16027 The documentation for the CPack NSIS generator has moved here: CPack
16028 NSIS Generator
16029 CPackNuGet
16031 The documentation for the CPack NuGet generator has moved here: CPack
16032 NuGet Generator
16033 CPackPackageMaker
16035 The documentation for the CPack PackageMaker generator has moved here:
16036 CPack PackageMaker Generator
16037 CPackProductBuild
16039 The documentation for the CPack productbuild generator has moved here:
16040 CPack productbuild Generator
16041 CPackRPM
16043 The documentation for the CPack RPM generator has moved here: CPack RPM
16044 Generator
16045 CPackWIX
16047 The documentation for the CPack WIX generator has moved here: CPack WIX
16048 Generator
16049
16051 2000-2019 Kitware, Inc. and Contributors
160523.16.1 Dec 14, 2019 CMAKE-MODULES(7)