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 a bundle in-place and make it standalone, such that it can be
128 drag-n-drop copied to another machine and run on that machine as long
129 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
156 not 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
170 full path to an executable. If there is no such parent dir, then sim‐
171 ply 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
178 nested inside a “.app” directory and returns the path to the “.app”
179 directory in <bundle_var> and the path to its main executable in <exe‐
180 cutable_var>
181 get_bundle_all_executables(<bundle> <exes_var>)
183 Scans the given bundle recursively for all executable files and accumu‐
185 lates them into a variable.
186 get_item_key(<item> <key_var>)
188 Given a file (item) name, generate a key that should be unique consid‐
190 ering the set of libraries that need copying or fixing up to make a
191 bundle standalone. This is essentially the file name including exten‐
192 sion with “.” replaced by “_”
193 This key is used as a prefix for CMake variables so that we can asso‐
195 ciate a set of variables with a given item based on its key.
196 clear_bundle_keys(<keys_var>)
198 Loop over the list of keys, clearing all the variables associated with
200 each key. After the loop, clear the list of keys itself.
201 Caller of get_bundle_keys should call clear_bundle_keys when done with
203 list of keys.
204 set_bundle_key_values(<keys_var> <context> <item> <exepath> <dirs>
206 <copyflag> [<rpaths>])
207 Add a key to the list (if necessary) for the given item. If added,
209 also set all the variables associated with that key.
210 get_bundle_keys(<app> <libs> <dirs> <keys_var>)
212 Loop over all the executable and library files within the bundle (and
214 given as extra <libs>) and accumulate a list of keys representing them.
215 Set values associated with each key such that we can loop over all of
216 them and copy prerequisite libs into the bundle and then do appropriate
217 install_name_tool fixups.
218 As an optional parameter (IGNORE_ITEM) a list of file names can be
220 passed, which are then ignored (e.g. IGNORE_ITEM “vcre‐
221 dist_x86.exe;vcredist_x64.exe”)
222 copy_resolved_item_into_bundle(<resolved_item> <resolved_embedded_item>)
224 Copy a resolved item into the bundle if necessary. Copy is not neces‐
226 sary if the resolved_item is “the same as” the resolved_embedded_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 embedded item.
243 For each prerequisite, change the way it is referenced to the value of
244 the _EMBEDDED_ITEM keyed variable for that prerequisite. (Most likely
245 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 point to other files
277 that are already also in the bundle… Anything that points to an exter‐
278 nal 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 in C++ files, as
584 opposed to CHECK_SYMBOL_EXISTS(), which works only for C.
585 If the header files define the symbol as a macro it is consid‐
587 ered available and assumed to work. If the header files declare
588 the symbol as a function or variable then the symbol must also
589 be available for linking. If the symbol is a type or enum value
590 it will not be recognized (consider using CheckTypeSize or
591 CheckCSourceCompiles).
592 The following variables may be set before calling this macro to modify
594 the way the check is run:
595 CMAKE_REQUIRED_FLAGS
597 string of compile command line flags.
598 CMAKE_REQUIRED_DEFINITIONS
600 a ;-list of macros to define (-DFOO=bar).
601 CMAKE_REQUIRED_INCLUDES
603 a ;-list of header search paths to pass to the compiler.
604 CMAKE_REQUIRED_LINK_OPTIONS
606 a ;-list of options to add to the link command.
607 CMAKE_REQUIRED_LIBRARIES
609 a ;-list of libraries to add to the link command. See policy
610 CMP0075.
611 CMAKE_REQUIRED_QUIET
613 execute quietly without messages.
614 CheckFortranCompilerFlag
616 Check whether the Fortran compiler supports a given flag.
617 check_fortran_compiler_flag
619 check_fortran_compiler_flag(<flag> <var>)
621 Check that the <flag> is accepted by the compiler without a
623 diagnostic. Stores the result in an internal cache entry named
624 <var>.
625 This command temporarily sets the CMAKE_REQUIRED_DEFINITIONS variable
627 and calls the check_fortran_source_compiles macro from the CheckFor‐
628 tranSourceCompiles module. See documentation of that module for a
629 listing of variables that can otherwise modify the build.
630 A positive result from this check indicates only that the compiler did
632 not issue a diagnostic message when given the flag. Whether the flag
633 has any effect or even a specific one is beyond the scope of this mod‐
634 ule.
635 NOTE:
637 Since the try_compile() command forwards flags from variables like
638 CMAKE_Fortran_FLAGS, unknown flags in such variables may cause a
639 false negative for this check.
640 CheckFortranFunctionExists
642 Check if a Fortran function exists.
643 CHECK_FORTRAN_FUNCTION_EXISTS
645 CHECK_FORTRAN_FUNCTION_EXISTS(<function> <result>)
647 where
649 <function>
651 the name of the Fortran function
652 <result>
654 variable to store the result; will be created as an
655 internal cache variable.
656 The following variables may be set before calling this macro to modify
658 the way the check is run:
659 CMAKE_REQUIRED_LINK_OPTIONS
661 A ;-list of options to add to the link command (see try_com‐
662 pile() for further details).
663 CMAKE_REQUIRED_LIBRARIES
665 A ;-list of libraries to add to the link command. These can be
666 the name of system libraries or they can be Imported Targets
667 (see try_compile() for further details).
668 CheckFortranSourceCompiles
670 Check if given Fortran source compiles and links into an executable.
671 check_fortran_source_compiles
673 check_fortran_source_compiles(<code> <resultVar>
675 [FAIL_REGEX <regex>...]
676 [SRC_EXT <extension>]
677 )
678 Checks that the source supplied in <code> can be compiled as a
680 Fortran source file and linked as an executable. The <code> must
681 be a Fortran program containing at least an end statement–for
682 example:
683 check_fortran_source_compiles("character :: b; error stop b; end" F2018ESTOPOK SRC_EXT F90)
685 This command can help avoid costly build processes when a com‐
687 piler lacks support for a necessary feature, or a particular
688 vendor library is not compatible with the Fortran compiler ver‐
689 sion being used. This generate-time check may advise the user of
690 such before the main build process. See also the check_for‐
691 tran_source_runs() command to actually run the compiled code.
692 The result will be stored in the internal cache variable
694 <resultVar>, with a boolean true value for success and boolean
695 false for failure.
696 If FAIL_REGEX is provided, then failure is determined by check‐
698 ing if anything in the output matches any of the specified regu‐
699 lar expressions.
700 By default, the test source file will be given a .F file exten‐
702 sion. The SRC_EXT option can be used to override this with
703 .<extension> instead– .F90 is a typical choice.
704 The underlying check is performed by the try_compile() command.
706 The compile and link commands can be influenced by setting any
707 of the following variables prior to calling check_for‐
708 tran_source_compiles():
709 CMAKE_REQUIRED_FLAGS
711 Additional flags to pass to the compiler. Note that the
712 contents of CMAKE_Fortran_FLAGS and its associated con‐
713 figuration-specific variable are automatically added to
714 the compiler command before the contents of
715 CMAKE_REQUIRED_FLAGS.
716 CMAKE_REQUIRED_DEFINITIONS
718 A ;-list of compiler definitions of the form -DFOO or
719 -DFOO=bar. A definition for the name specified by
720 <resultVar> will also be added automatically.
721 CMAKE_REQUIRED_INCLUDES
723 A ;-list of header search paths to pass to the compiler.
724 These will be the only header search paths used by
725 try_compile(), i.e. the contents of the INCLUDE_DIRECTO‐
726 RIES directory property will be ignored.
727 CMAKE_REQUIRED_LINK_OPTIONS
729 A ;-list of options to add to the link command (see
730 try_compile() for further details).
731 CMAKE_REQUIRED_LIBRARIES
733 A ;-list of libraries to add to the link command. These
734 can be the name of system libraries or they can be
735 Imported Targets (see try_compile() for further details).
736 CMAKE_REQUIRED_QUIET
738 If this variable evaluates to a boolean true value, all
739 status messages associated with the check will be sup‐
740 pressed.
741 The check is only performed once, with the result cached in the
743 variable named by <resultVar>. Every subsequent CMake run will
744 re-use this cached value rather than performing the check again,
745 even if the <code> changes. In order to force the check to be
746 re-evaluated, the variable named by <resultVar> must be manually
747 removed from the cache.
748 CheckFortranSourceRuns
750 Check if given Fortran source compiles and links into an executable and
751 can subsequently be run.
752 check_fortran_source_runs
754 check_fortran_source_runs(<code> <resultVar>
756 [SRC_EXT <extension>])
757 Check that the source supplied in <code> can be compiled as a
759 Fortran source file, linked as an executable and then run. The
760 <code> must be a Fortran program containing at least an end
761 statement–for example:
762 check_fortran_source_runs("real :: x[*]; call co_sum(x); end" F2018coarrayOK)
764 This command can help avoid costly build processes when a com‐
766 piler lacks support for a necessary feature, or a particular
767 vendor library is not compatible with the Fortran compiler ver‐
768 sion being used. Some of these failures only occur at runtime
769 instead of linktime, and a trivial runtime example can catch the
770 issue before the main build process.
771 If the <code> could be built and run successfully, the internal
773 cache variable specified by <resultVar> will be set to 1, other‐
774 wise it will be set to an value that evaluates to boolean false
775 (e.g. an empty string or an error message).
776 By default, the test source file will be given a .F90 file
778 extension. The SRC_EXT option can be used to override this with
779 .<extension> instead.
780 The underlying check is performed by the try_run() command. The
782 compile and link commands can be influenced by setting any of
783 the following variables prior to calling check_for‐
784 tran_source_runs():
785 CMAKE_REQUIRED_FLAGS
787 Additional flags to pass to the compiler. Note that the
788 contents of CMAKE_Fortran_FLAGS and its associated con‐
789 figuration-specific variable are automatically added to
790 the compiler command before the contents of
791 CMAKE_REQUIRED_FLAGS.
792 CMAKE_REQUIRED_DEFINITIONS
794 A ;-list of compiler definitions of the form -DFOO or
795 -DFOO=bar. A definition for the name specified by
796 <resultVar> will also be added automatically.
797 CMAKE_REQUIRED_INCLUDES
799 A ;-list of header search paths to pass to the compiler.
800 These will be the only header search paths used by
801 try_run(), i.e. the contents of the INCLUDE_DIRECTORIES
802 directory property will be ignored.
803 CMAKE_REQUIRED_LINK_OPTIONS
805 A ;-list of options to add to the link command (see
806 try_run() for further details).
807 CMAKE_REQUIRED_LIBRARIES
809 A ;-list of libraries to add to the link command. These
810 can be the name of system libraries or they can be
811 Imported Targets (see try_run() for further details).
812 CMAKE_REQUIRED_QUIET
814 If this variable evaluates to a boolean true value, all
815 status messages associated with the check will be sup‐
816 pressed.
817 The check is only performed once, with the result cached in the
819 variable named by <resultVar>. Every subsequent CMake run will
820 re-use this cached value rather than performing the check again,
821 even if the <code> changes. In order to force the check to be
822 re-evaluated, the variable named by <resultVar> must be manually
823 removed from the cache.
824 CheckFunctionExists
826 Check if a C function can be linked
827 check_function_exists
829 check_function_exists(<function> <variable>)
831 Checks that the <function> is provided by libraries on the sys‐
833 tem and store the result in a <variable>, which will be created
834 as an internal cache variable.
835 The following variables may be set before calling this macro to modify
837 the way the check is run:
838 CMAKE_REQUIRED_FLAGS
840 string of compile command line flags.
841 CMAKE_REQUIRED_DEFINITIONS
843 a ;-list of macros to define (-DFOO=bar).
844 CMAKE_REQUIRED_INCLUDES
846 a ;-list of header search paths to pass to the compiler.
847 CMAKE_REQUIRED_LINK_OPTIONS
849 a ;-list of options to add to the link command.
850 CMAKE_REQUIRED_LIBRARIES
852 a ;-list of libraries to add to the link command. See policy
853 CMP0075.
854 CMAKE_REQUIRED_QUIET
856 execute quietly without messages.
857 NOTE:
859 Prefer using CheckSymbolExists instead of this module, for the fol‐
860 lowing reasons:
861 · check_function_exists() can’t detect functions that are inlined in
863 headers or specified as a macro.
864 · check_function_exists() can’t detect anything in the 32-bit ver‐
866 sions of the Win32 API, because of a mismatch in calling conven‐
867 tions.
868 · check_function_exists() only verifies linking, it does not verify
870 that the function is declared in system headers.
871 CheckIPOSupported
873 Check whether the compiler supports an interprocedural optimization
874 (IPO/LTO). Use this before enabling the INTERPROCEDURAL_OPTIMIZATION
875 target property.
876 check_ipo_supported
878 check_ipo_supported([RESULT <result>] [OUTPUT <output>]
880 [LANGUAGES <lang>...])
881 Options are:
883 RESULT <result>
885 Set <result> variable to YES if IPO is supported by the
886 compiler and NO otherwise. If this option is not given
887 then the command will issue a fatal error if IPO is not
888 supported.
889 OUTPUT <output>
891 Set <output> variable with details about any error.
892 LANGUAGES <lang>...
894 Specify languages whose compilers to check. Languages C,
895 CXX, and Fortran are supported.
896 It makes no sense to use this module when CMP0069 is set to OLD so mod‐
898 ule will return error in this case. See policy CMP0069 for details.
899 Examples
901 check_ipo_supported() # fatal error if IPO is not supported
902 set_property(TARGET foo PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
903 # Optional IPO. Do not use IPO if it's not supported by compiler.
905 check_ipo_supported(RESULT result OUTPUT output)
906 if(result)
907 set_property(TARGET foo PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
908 else()
909 message(WARNING "IPO is not supported: ${output}")
910 endif()
911 CheckIncludeFileCXX
913 Provides a macro to check if a header file can be included in CXX.
914 CHECK_INCLUDE_FILE_CXX
916 CHECK_INCLUDE_FILE_CXX(<include> <variable> [<flags>])
918 Check if the given <include> file may be included in a CXX
920 source file and store the result in an internal cache entry
921 named <variable>. The optional third argument may be used to
922 add compilation flags to the check (or use CMAKE_REQUIRED_FLAGS
923 below).
924 The following variables may be set before calling this macro to modify
926 the way the check is run:
927 CMAKE_REQUIRED_FLAGS
929 string of compile command line flags.
930 CMAKE_REQUIRED_DEFINITIONS
932 a ;-list of macros to define (-DFOO=bar).
933 CMAKE_REQUIRED_INCLUDES
935 a ;-list of header search paths to pass to the compiler.
936 CMAKE_REQUIRED_LINK_OPTIONS
938 a ;-list of options to add to the link command.
939 CMAKE_REQUIRED_LIBRARIES
941 a ;-list of libraries to add to the link command. See policy
942 CMP0075.
943 CMAKE_REQUIRED_QUIET
945 execute quietly without messages.
946 See modules CheckIncludeFile and CheckIncludeFiles to check for one or
948 more C headers.
949 CheckIncludeFile
951 Provides a macro to check if a header file can be included in C.
952 CHECK_INCLUDE_FILE
954 CHECK_INCLUDE_FILE(<include> <variable> [<flags>])
956 Check if the given <include> file may be included in a C source
958 file and store the result in an internal cache entry named
959 <variable>. The optional third argument may be used to add com‐
960 pilation flags to the check (or use CMAKE_REQUIRED_FLAGS below).
961 The following variables may be set before calling this macro to modify
963 the way the check is run:
964 CMAKE_REQUIRED_FLAGS
966 string of compile command line flags.
967 CMAKE_REQUIRED_DEFINITIONS
969 a ;-list of macros to define (-DFOO=bar).
970 CMAKE_REQUIRED_INCLUDES
972 a ;-list of header search paths to pass to the compiler.
973 CMAKE_REQUIRED_LINK_OPTIONS
975 a ;-list of options to add to the link command.
976 CMAKE_REQUIRED_LIBRARIES
978 a ;-list of libraries to add to the link command. See policy
979 CMP0075.
980 CMAKE_REQUIRED_QUIET
982 execute quietly without messages.
983 See the CheckIncludeFiles module to check for multiple headers at once.
985 See the CheckIncludeFileCXX module to check for headers using the CXX
986 language.
987 CheckIncludeFiles
989 Provides a macro to check if a list of one or more header files can be
990 included together.
991 CHECK_INCLUDE_FILES
993 CHECK_INCLUDE_FILES("<includes>" <variable> [LANGUAGE <language>])
995 Check if the given <includes> list may be included together in a
997 source file and store the result in an internal cache entry
998 named <variable>. Specify the <includes> argument as a ;-list
999 of header file names.
1000 If LANGUAGE is set, the specified compiler will be used to per‐
1002 form the check. Acceptable values are C and CXX. If not set, the
1003 C compiler will be used if enabled. If the C compiler is not
1004 enabled, the C++ compiler will be used if enabled.
1005 The following variables may be set before calling this macro to modify
1007 the way the check is run:
1008 CMAKE_REQUIRED_FLAGS
1010 string of compile command line flags.
1011 CMAKE_REQUIRED_DEFINITIONS
1013 a ;-list of macros to define (-DFOO=bar).
1014 CMAKE_REQUIRED_INCLUDES
1016 a ;-list of header search paths to pass to the compiler.
1017 CMAKE_REQUIRED_LINK_OPTIONS
1019 a ;-list of options to add to the link command.
1020 CMAKE_REQUIRED_LIBRARIES
1022 a ;-list of libraries to add to the link command. See policy
1023 CMP0075.
1024 CMAKE_REQUIRED_QUIET
1026 execute quietly without messages.
1027 See modules CheckIncludeFile and CheckIncludeFileCXX to check for a
1029 single header file in C or CXX languages.
1030 CheckLanguage
1032 Check if a language can be enabled
1033 Usage:
1035 check_language(<lang>)
1037 where <lang> is a language that may be passed to enable_language() such
1039 as “Fortran”. If CMAKE_<lang>_COMPILER is already defined the check
1040 does nothing. Otherwise it tries enabling the language in a test
1041 project. The result is cached in CMAKE_<lang>_COMPILER as the compiler
1042 that was found, or NOTFOUND if the language cannot be enabled.
1043 Example:
1045 check_language(Fortran)
1047 if(CMAKE_Fortran_COMPILER)
1048 enable_language(Fortran)
1049 else()
1050 message(STATUS "No Fortran support")
1051 endif()
1052 CheckLibraryExists
1054 Check if the function exists.
1055 CHECK_LIBRARY_EXISTS
1057 CHECK_LIBRARY_EXISTS(LIBRARY FUNCTION LOCATION VARIABLE)
1059 LIBRARY - the name of the library you are looking for
1061 FUNCTION - the name of the function
1062 LOCATION - location where the library should be found
1063 VARIABLE - variable to store the result
1064 Will be created as an internal cache variable.
1065 The following variables may be set before calling this macro to modify
1067 the way the check is run:
1068 CMAKE_REQUIRED_FLAGS = string of compile command line flags
1070 CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
1071 CMAKE_REQUIRED_LINK_OPTIONS = list of options to pass to link command
1072 CMAKE_REQUIRED_LIBRARIES = list of libraries to link
1073 CMAKE_REQUIRED_QUIET = execute quietly without messages
1074 CheckPIESupported
1076 Check whether the linker supports position independent code (PIE) or no
1077 position independent code (NO_PIE) for executables. Use this to ensure
1078 that the POSITION_INDEPENDENT_CODE target property for executables will
1079 be honored at link time.
1080 check_pie_supported
1082 check_pie_supported([OUTPUT_VARIABLE <output>]
1084 [LANGUAGES <lang>...])
1085 Options are:
1087 OUTPUT_VARIABLE <output>
1089 Set <output> variable with details about any error.
1090 LANGUAGES <lang>...
1092 Check the linkers used for each of the specified lan‐
1093 guages. Supported languages are C, CXX, and Fortran.
1094 It makes no sense to use this module when CMP0083 is set to OLD, so the
1096 command will return an error in this case. See policy CMP0083 for
1097 details.
1098 Variables
1100 For each language checked, two boolean cache variables are defined.
1101 CMAKE_<lang>_LINK_PIE_SUPPORTED
1103 Set to YES if PIE is supported by the linker and NO other‐
1104 wise.
1105 CMAKE_<lang>_LINK_NO_PIE_SUPPORTED
1107 Set to YES if NO_PIE is supported by the linker and NO other‐
1108 wise.
1109 Examples
1111 check_pie_supported()
1112 set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE)
1113 # Retrieve any error message.
1115 check_pie_supported(OUTPUT_VARIABLE output LANGUAGES C)
1116 set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE)
1117 if(NOT CMAKE_C_LINK_PIE_SUPPORTED)
1118 message(WARNING "PIE is not supported at link time: ${output}.\n"
1119 "PIE link options will not be passed to linker.")
1120 endif()
1121 CheckPrototypeDefinition
1123 Check if the prototype we expect is correct.
1124 check_prototype_definition
1126 check_prototype_definition(FUNCTION PROTOTYPE RETURN HEADER VARIABLE)
1128 FUNCTION - The name of the function (used to check if prototype exists)
1130 PROTOTYPE- The prototype to check.
1131 RETURN - The return value of the function.
1132 HEADER - The header files required.
1133 VARIABLE - The variable to store the result.
1134 Will be created as an internal cache variable.
1135 Example:
1137 check_prototype_definition(getpwent_r
1139 "struct passwd *getpwent_r(struct passwd *src, char *buf, int buflen)"
1140 "NULL"
1141 "unistd.h;pwd.h"
1142 SOLARIS_GETPWENT_R)
1143 The following variables may be set before calling this function to mod‐
1145 ify the way the check is run:
1146 CMAKE_REQUIRED_FLAGS = string of compile command line flags
1148 CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
1149 CMAKE_REQUIRED_INCLUDES = list of include directories
1150 CMAKE_REQUIRED_LINK_OPTIONS = list of options to pass to link command
1151 CMAKE_REQUIRED_LIBRARIES = list of libraries to link
1152 CMAKE_REQUIRED_QUIET = execute quietly without messages
1153 CheckStructHasMember
1155 Check if the given struct or class has the specified member variable
1156 CHECK_STRUCT_HAS_MEMBER
1158 CHECK_STRUCT_HAS_MEMBER(<struct> <member> <header> <variable>
1160 [LANGUAGE <language>])
1161 <struct> - the name of the struct or class you are interested in
1163 <member> - the member which existence you want to check
1164 <header> - the header(s) where the prototype should be declared
1165 <variable> - variable to store the result
1166 <language> - the compiler to use (C or CXX)
1167 The following variables may be set before calling this macro to modify
1169 the way the check is run:
1170 CMAKE_REQUIRED_FLAGS = string of compile command line flags
1172 CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
1173 CMAKE_REQUIRED_INCLUDES = list of include directories
1174 CMAKE_REQUIRED_LINK_OPTIONS = list of options to pass to link command
1175 CMAKE_REQUIRED_LIBRARIES = list of libraries to link
1176 CMAKE_REQUIRED_QUIET = execute quietly without messages
1177 Example:
1179 CHECK_STRUCT_HAS_MEMBER("struct timeval" tv_sec sys/select.h
1181 HAVE_TIMEVAL_TV_SEC LANGUAGE C)
1182 CheckSymbolExists
1184 Provides a macro to check if a symbol exists as a function, variable,
1185 or macro in C.
1186 check_symbol_exists
1188 check_symbol_exists(<symbol> <files> <variable>)
1190 Check that the <symbol> is available after including given
1192 header <files> and store the result in a <variable>. Specify
1193 the list of files in one argument as a semicolon-separated list.
1194 <variable> will be created as an internal cache variable.
1195 If the header files define the symbol as a macro it is considered
1197 available and assumed to work. If the header files declare the symbol
1198 as a function or variable then the symbol must also be available for
1199 linking (so intrinsics may not be detected). If the symbol is a type,
1200 enum value, or intrinsic it will not be recognized (consider using
1201 CheckTypeSize or CheckCSourceCompiles). If the check needs to be done
1202 in C++, consider using CheckCXXSymbolExists instead.
1203 The following variables may be set before calling this macro to modify
1205 the way the check is run:
1206 CMAKE_REQUIRED_FLAGS
1208 string of compile command line flags.
1209 CMAKE_REQUIRED_DEFINITIONS
1211 a ;-list of macros to define (-DFOO=bar).
1212 CMAKE_REQUIRED_INCLUDES
1214 a ;-list of header search paths to pass to the compiler.
1215 CMAKE_REQUIRED_LINK_OPTIONS
1217 a ;-list of options to add to the link command.
1218 CMAKE_REQUIRED_LIBRARIES
1220 a ;-list of libraries to add to the link command. See policy
1221 CMP0075.
1222 CMAKE_REQUIRED_QUIET
1224 execute quietly without messages.
1225 CheckTypeSize
1227 Check sizeof a type
1228 CHECK_TYPE_SIZE
1230 CHECK_TYPE_SIZE(TYPE VARIABLE [BUILTIN_TYPES_ONLY]
1232 [LANGUAGE <language>])
1233 Check if the type exists and determine its size. On return,
1235 HAVE_${VARIABLE} holds the existence of the type, and ${VARI‐
1236 ABLE} holds one of the following:
1237 <size> = type has non-zero size <size>
1239 "0" = type has arch-dependent size (see below)
1240 "" = type does not exist
1241 Both HAVE_${VARIABLE} and ${VARIABLE} will be created as inter‐
1243 nal cache variables.
1244 Furthermore, the variable ${VARIABLE}_CODE holds C preprocessor
1246 code to define the macro ${VARIABLE} to the size of the type, or
1247 leave the macro undefined if the type does not exist.
1248 The variable ${VARIABLE} may be 0 when CMAKE_OSX_ARCHITECTURES
1250 has multiple architectures for building OS X universal binaries.
1251 This indicates that the type size varies across architectures.
1252 In this case ${VARIABLE}_CODE contains C preprocessor tests map‐
1253 ping from each architecture macro to the corresponding type
1254 size. The list of architecture macros is stored in ${VARI‐
1255 ABLE}_KEYS, and the value for each key is stored in ${VARI‐
1256 ABLE}-${KEY}.
1257 If the BUILTIN_TYPES_ONLY option is not given, the macro checks
1259 for headers <sys/types.h>, <stdint.h>, and <stddef.h>, and saves
1260 results in HAVE_SYS_TYPES_H, HAVE_STDINT_H, and HAVE_STDDEF_H.
1261 The type size check automatically includes the available head‐
1262 ers, thus supporting checks of types defined in the headers.
1263 If LANGUAGE is set, the specified compiler will be used to per‐
1265 form the check. Acceptable values are C and CXX.
1266 Despite the name of the macro you may use it to check the size of more
1268 complex expressions, too. To check e.g. for the size of a struct mem‐
1269 ber you can do something like this:
1270 check_type_size("((struct something*)0)->member" SIZEOF_MEMBER)
1272 The following variables may be set before calling this macro to modify
1274 the way the check is run:
1275 CMAKE_REQUIRED_FLAGS = string of compile command line flags
1277 CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
1278 CMAKE_REQUIRED_INCLUDES = list of include directories
1279 CMAKE_REQUIRED_LINK_OPTIONS = list of options to pass to link command
1280 CMAKE_REQUIRED_LIBRARIES = list of libraries to link
1281 CMAKE_REQUIRED_QUIET = execute quietly without messages
1282 CMAKE_EXTRA_INCLUDE_FILES = list of extra headers to include
1283 CheckVariableExists
1285 Check if the variable exists.
1286 CHECK_VARIABLE_EXISTS
1288 CHECK_VARIABLE_EXISTS(VAR VARIABLE)
1290 VAR - the name of the variable
1292 VARIABLE - variable to store the result
1293 Will be created as an internal cache variable.
1294 This macro is only for C variables.
1296 The following variables may be set before calling this macro to modify
1298 the way the check is run:
1299 CMAKE_REQUIRED_FLAGS = string of compile command line flags
1301 CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
1302 CMAKE_REQUIRED_LINK_OPTIONS = list of options to pass to link command
1303 CMAKE_REQUIRED_LIBRARIES = list of libraries to link
1304 CMAKE_REQUIRED_QUIET = execute quietly without messages
1305 CMakeAddFortranSubdirectory
1307 Add a fortran-only subdirectory, find a fortran compiler, and build.
1308 The cmake_add_fortran_subdirectory function adds a subdirectory to a
1310 project that contains a fortran-only subproject. The module will check
1311 the current compiler and see if it can support fortran. If no fortran
1312 compiler is found and the compiler is MSVC, then this module will find
1313 the MinGW gfortran. It will then use an external project to build with
1314 the MinGW tools. It will also create imported targets for the
1315 libraries created. This will only work if the fortran code is built
1316 into a dll, so BUILD_SHARED_LIBS is turned on in the project. In addi‐
1317 tion the CMAKE_GNUtoMS option is set to on, so that Microsoft .lib
1318 files are created. Usage is as follows:
1319 cmake_add_fortran_subdirectory(
1321 <subdir> # name of subdirectory
1322 PROJECT <project_name> # project name in subdir top CMakeLists.txt
1323 ARCHIVE_DIR <dir> # dir where project places .lib files
1324 RUNTIME_DIR <dir> # dir where project places .dll files
1325 LIBRARIES <lib>... # names of library targets to import
1326 LINK_LIBRARIES # link interface libraries for LIBRARIES
1327 [LINK_LIBS <lib> <dep>...]...
1328 CMAKE_COMMAND_LINE ... # extra command line flags to pass to cmake
1329 NO_EXTERNAL_INSTALL # skip installation of external project
1330 )
1331 Relative paths in ARCHIVE_DIR and RUNTIME_DIR are interpreted with
1333 respect to the build directory corresponding to the source directory in
1334 which the function is invoked.
1335 Limitations:
1337 NO_EXTERNAL_INSTALL is required for forward compatibility with a future
1339 version that supports installation of the external project binaries
1340 during “make install”.
1341 CMakeBackwardCompatibilityCXX
1343 define a bunch of backwards compatibility variables
1344 CMAKE_ANSI_CXXFLAGS - flag for ansi c++
1346 CMAKE_HAS_ANSI_STRING_STREAM - has <strstream>
1347 include(TestForANSIStreamHeaders)
1348 include(CheckIncludeFileCXX)
1349 include(TestForSTDNamespace)
1350 include(TestForANSIForScope)
1351 CMakeDependentOption
1353 Macro to provide an option dependent on other options.
1354 This macro presents an option to the user only if a set of other condi‐
1356 tions are true. When the option is not presented a default value is
1357 used, but any value set by the user is preserved for when the option is
1358 presented again. Example invocation:
1359 CMAKE_DEPENDENT_OPTION(USE_FOO "Use Foo" ON
1361 "USE_BAR;NOT USE_ZOT" OFF)
1362 If USE_BAR is true and USE_ZOT is false, this provides an option called
1364 USE_FOO that defaults to ON. Otherwise, it sets USE_FOO to OFF. If
1365 the status of USE_BAR or USE_ZOT ever changes, any value for the
1366 USE_FOO option is saved so that when the option is re-enabled it
1367 retains its old value.
1368 CMakeFindDependencyMacro
1370 find_dependency
1371 The find_dependency() macro wraps a find_package() call for a
1372 package dependency:
1373 find_dependency(<dep> [...])
1375 It is designed to be used in a Package Configuration File
1377 (<PackageName>Config.cmake). find_dependency forwards the cor‐
1378 rect parameters for QUIET and REQUIRED which were passed to the
1379 original find_package() call. Any additional arguments speci‐
1380 fied are forwarded to find_package().
1381 If the dependency could not be found it sets an informative
1383 diagnostic message and calls return() to end processing of the
1384 calling package configuration file and return to the find_pack‐
1385 age() command that loaded it.
1386 NOTE:
1388 The call to return() makes this macro unsuitable to call from
1389 Find Modules.
1390 CMakeFindFrameworks
1392 helper module to find OSX frameworks
1393 This module reads hints about search locations from variables:
1395 CMAKE_FIND_FRAMEWORK_EXTRA_LOCATIONS - Extra directories
1397 CMakeFindPackageMode
1399 This file is executed by cmake when invoked with –find-package. It
1400 expects that the following variables are set using -D:
1401 NAME name of the package
1403 COMPILER_ID
1405 the CMake compiler ID for which the result is, i.e.
1406 GNU/Intel/Clang/MSVC, etc.
1407 LANGUAGE
1409 language for which the result will be used, i.e. C/CXX/For‐
1410 tran/ASM
1411 MODE
1413 EXIST only check for existence of the given package
1415 COMPILE
1417 print the flags needed for compiling an object file which
1418 uses the given package
1419 LINK print the flags needed for linking when using the given
1421 package
1422 QUIET if TRUE, don’t print anything
1424 CMakeGraphVizOptions
1426 The builtin graphviz support of CMake.
1427 Variables specific to the graphviz support
1429 CMake can generate graphviz files, showing the dependencies between the
1430 targets in a project and also external libraries which are linked
1431 against. When CMake is run with the --graphviz=foo.dot option, it will
1432 produce:
1433 · a foo.dot file showing all dependencies in the project
1435 · a foo.dot.<target> file for each target, file showing on which other
1437 targets the respective target depends
1438 · a foo.dot.<target>.dependers file, showing which other targets depend
1440 on the respective target
1441 The different dependency types PUBLIC, PRIVATE and INTERFACE are repre‐
1443 sented as solid, dashed and dotted edges.
1444 This can result in huge graphs. Using the file CMakeGraphVizOp‐
1446 tions.cmake the look and content of the generated graphs can be influ‐
1447 enced. This file is searched first in CMAKE_BINARY_DIR and then in
1448 CMAKE_SOURCE_DIR. If found, it is read and the variables set in it are
1449 used to adjust options for the generated graphviz files.
1450 GRAPHVIZ_GRAPH_TYPE
1452 The graph type.
1453 · Mandatory : NO
1455 · Default : “digraph”
1457 Valid graph types are:
1459 · “graph” : Nodes are joined with lines
1461 · “digraph” : Nodes are joined with arrows showing direction
1463 · “strict graph” : Like “graph” but max one line between each
1465 node
1466 · “strict digraph” : Like “graph” but max one line between each
1468 node in each direction
1469 GRAPHVIZ_GRAPH_NAME
1471 The graph name.
1472 · Mandatory : NO
1474 · Default : “GG”
1476 GRAPHVIZ_GRAPH_HEADER
1478 The header written at the top of the graphviz file.
1479 · Mandatory : NO
1481 · Default : “node [n fontsize = “12”];”
1483 GRAPHVIZ_NODE_PREFIX
1485 The prefix for each node in the graphviz file.
1486 · Mandatory : NO
1488 · Default : “node”
1490 GRAPHVIZ_EXECUTABLES
1492 Set this to FALSE to exclude executables from the generated
1493 graphs.
1494 · Mandatory : NO
1496 · Default : TRUE
1498 GRAPHVIZ_STATIC_LIBS
1500 Set this to FALSE to exclude static libraries from the generated
1501 graphs.
1502 · Mandatory : NO
1504 · Default : TRUE
1506 GRAPHVIZ_SHARED_LIBS
1508 Set this to FALSE to exclude shared libraries from the generated
1509 graphs.
1510 · Mandatory : NO
1512 · Default : TRUE
1514 GRAPHVIZ_MODULE_LIBS
1516 Set this to FALSE to exclude module libraries from the generated
1517 graphs.
1518 · Mandatory : NO
1520 · Default : TRUE
1522 GRAPHVIZ_EXTERNAL_LIBS
1524 Set this to FALSE to exclude external libraries from the gener‐
1525 ated graphs.
1526 · Mandatory : NO
1528 · Default : TRUE
1530 GRAPHVIZ_IGNORE_TARGETS
1532 A list of regular expressions for ignoring targets.
1533 · Mandatory : NO
1535 · Default : empty
1537 GRAPHVIZ_GENERATE_PER_TARGET
1539 Set this to FALSE to exclude per target graphs foo.dot.<target>.
1540 · Mandatory : NO
1542 · Default : TRUE
1544 GRAPHVIZ_GENERATE_DEPENDERS
1546 Set this to FALSE to exclude depender graphs foo.dot.<tar‐
1547 get>.dependers.
1548 · Mandatory : NO
1550 · Default : TRUE
1552 CMakePackageConfigHelpers
1554 Helpers functions for creating config files that can be included by
1555 other projects to find and use a package.
1556 Adds the configure_package_config_file() and
1558 write_basic_package_version_file() commands.
1559 Generating a Package Configuration File
1561 configure_package_config_file
1562 Create a config file for a project:
1563 configure_package_config_file(<input> <output>
1565 INSTALL_DESTINATION <path>
1566 [PATH_VARS <var1> <var2> ... <varN>]
1567 [NO_SET_AND_CHECK_MACRO]
1568 [NO_CHECK_REQUIRED_COMPONENTS_MACRO]
1569 [INSTALL_PREFIX <path>]
1570 )
1571 configure_package_config_file() should be used instead of the plain
1573 configure_file() command when creating the <PackageName>Config.cmake or
1574 <PackageName>-config.cmake file for installing a project or library.
1575 It helps making the resulting package relocatable by avoiding hardcoded
1576 paths in the installed Config.cmake file.
1577 In a FooConfig.cmake file there may be code like this to make the
1579 install destinations know to the using project:
1580 set(FOO_INCLUDE_DIR "@CMAKE_INSTALL_FULL_INCLUDEDIR@" )
1582 set(FOO_DATA_DIR "@CMAKE_INSTALL_PREFIX@/@RELATIVE_DATA_INSTALL_DIR@" )
1583 set(FOO_ICONS_DIR "@CMAKE_INSTALL_PREFIX@/share/icons" )
1584 #...logic to determine installedPrefix from the own location...
1585 set(FOO_CONFIG_DIR "${installedPrefix}/@CONFIG_INSTALL_DIR@" )
1586 All 4 options shown above are not sufficient, since the first 3 hard‐
1588 code the absolute directory locations, and the 4th case works only if
1589 the logic to determine the installedPrefix is correct, and if CON‐
1590 FIG_INSTALL_DIR contains a relative path, which in general cannot be
1591 guaranteed. This has the effect that the resulting FooConfig.cmake
1592 file would work poorly under Windows and OSX, where users are used to
1593 choose the install location of a binary package at install time, inde‐
1594 pendent from how CMAKE_INSTALL_PREFIX was set at build/cmake time.
1595 Using configure_package_config_file helps. If used correctly, it makes
1597 the resulting FooConfig.cmake file relocatable. Usage:
1598 1. write a FooConfig.cmake.in file as you are used to
1600 2. insert a line containing only the string @PACKAGE_INIT@
1602 3. instead of set(FOO_DIR "@SOME_INSTALL_DIR@"), use set(FOO_DIR
1604 "@PACKAGE_SOME_INSTALL_DIR@") (this must be after the @PACKAGE_INIT@
1605 line)
1606 4. instead of using the normal configure_file(), use configure_pack‐
1608 age_config_file()
1609 The <input> and <output> arguments are the input and output file, the
1611 same way as in configure_file().
1612 The <path> given to INSTALL_DESTINATION must be the destination where
1614 the FooConfig.cmake file will be installed to. This path can either be
1615 absolute, or relative to the INSTALL_PREFIX path.
1616 The variables <var1> to <varN> given as PATH_VARS are the variables
1618 which contain install destinations. For each of them the macro will
1619 create a helper variable PACKAGE_<var...>. These helper variables must
1620 be used in the FooConfig.cmake.in file for setting the installed loca‐
1621 tion. They are calculated by configure_package_config_file so that
1622 they are always relative to the installed location of the package.
1623 This works both for relative and also for absolute locations. For
1624 absolute locations it works only if the absolute location is a subdi‐
1625 rectory of INSTALL_PREFIX.
1626 If the INSTALL_PREFIX argument is passed, this is used as base path to
1628 calculate all the relative paths. The <path> argument must be an abso‐
1629 lute path. If this argument is not passed, the CMAKE_INSTALL_PREFIX
1630 variable will be used instead. The default value is good when generat‐
1631 ing a FooConfig.cmake file to use your package from the install tree.
1632 When generating a FooConfig.cmake file to use your package from the
1633 build tree this option should be used.
1634 By default configure_package_config_file also generates two helper
1636 macros, set_and_check() and check_required_components() into the
1637 FooConfig.cmake file.
1638 set_and_check() should be used instead of the normal set() command for
1640 setting directories and file locations. Additionally to setting the
1641 variable it also checks that the referenced file or directory actually
1642 exists and fails with a FATAL_ERROR otherwise. This makes sure that
1643 the created FooConfig.cmake file does not contain wrong references.
1644 When using the NO_SET_AND_CHECK_MACRO, this macro is not generated into
1645 the FooConfig.cmake file.
1646 check_required_components(<PackageName>) should be called at the end of
1648 the FooConfig.cmake file. This macro checks whether all requested,
1649 non-optional components have been found, and if this is not the case,
1650 sets the Foo_FOUND variable to FALSE, so that the package is considered
1651 to be not found. It does that by testing the Foo_<Component>_FOUND
1652 variables for all requested required components. This macro should be
1653 called even if the package doesn’t provide any components to make sure
1654 users are not specifying components erroneously. When using the
1655 NO_CHECK_REQUIRED_COMPONENTS_MACRO option, this macro is not generated
1656 into the FooConfig.cmake file.
1657 For an example see below the documentation for
1659 write_basic_package_version_file().
1660 Generating a Package Version File
1662 write_basic_package_version_file
1663 Create a version file for a project:
1664 write_basic_package_version_file(<filename>
1666 [VERSION <major.minor.patch>]
1667 COMPATIBILITY <AnyNewerVersion|SameMajorVersion|SameMinorVersion|ExactVersion>
1668 [ARCH_INDEPENDENT] )
1669 Writes a file for use as <PackageName>ConfigVersion.cmake file to
1671 <filename>. See the documentation of find_package() for details on
1672 this.
1673 <filename> is the output filename, it should be in the build tree.
1675 <major.minor.patch> is the version number of the project to be
1676 installed.
1677 If no VERSION is given, the PROJECT_VERSION variable is used. If this
1679 hasn’t been set, it errors out.
1680 The COMPATIBILITY mode AnyNewerVersion means that the installed package
1682 version will be considered compatible if it is newer or exactly the
1683 same as the requested version. This mode should be used for packages
1684 which are fully backward compatible, also across major versions. If
1685 SameMajorVersion is used instead, then the behaviour differs from
1686 AnyNewerVersion in that the major version number must be the same as
1687 requested, e.g. version 2.0 will not be considered compatible if 1.0
1688 is requested. This mode should be used for packages which guarantee
1689 backward compatibility within the same major version. If SameMinorVer‐
1690 sion is used, the behaviour is the same as SameMajorVersion, but both
1691 major and minor version must be the same as requested, e.g version 0.2
1692 will not be compatible if 0.1 is requested. If ExactVersion is used,
1693 then the package is only considered compatible if the requested version
1694 matches exactly its own version number (not considering the tweak ver‐
1695 sion). For example, version 1.2.3 of a package is only considered com‐
1696 patible to requested version 1.2.3. This mode is for packages without
1697 compatibility guarantees. If your project has more elaborated version
1698 matching rules, you will need to write your own custom ConfigVer‐
1699 sion.cmake file instead of using this macro.
1700 If ARCH_INDEPENDENT is given, the installed package version will be
1702 considered compatible even if it was built for a different architecture
1703 than the requested architecture. Otherwise, an architecture check will
1704 be performed, and the package will be considered compatible only if the
1705 architecture matches exactly. For example, if the package is built for
1706 a 32-bit architecture, the package is only considered compatible if it
1707 is used on a 32-bit architecture, unless ARCH_INDEPENDENT is given, in
1708 which case the package is considered compatible on any architecture.
1709 NOTE:
1711 ARCH_INDEPENDENT is intended for header-only libraries or similar
1712 packages with no binaries.
1713 Internally, this macro executes configure_file() to create the result‐
1715 ing version file. Depending on the COMPATIBILITY, the corresponding
1716 BasicConfigVersion-<COMPATIBILITY>.cmake.in file is used. Please note
1717 that these files are internal to CMake and you should not call config‐
1718 ure_file() on them yourself, but they can be used as starting point to
1719 create more sophisticted custom ConfigVersion.cmake files.
1720 Example Generating Package Files
1722 Example using both configure_package_config_file() and
1723 write_basic_package_version_file():
1724 CMakeLists.txt:
1726 set(INCLUDE_INSTALL_DIR include/ ... CACHE )
1728 set(LIB_INSTALL_DIR lib/ ... CACHE )
1729 set(SYSCONFIG_INSTALL_DIR etc/foo/ ... CACHE )
1730 #...
1731 include(CMakePackageConfigHelpers)
1732 configure_package_config_file(FooConfig.cmake.in
1733 ${CMAKE_CURRENT_BINARY_DIR}/FooConfig.cmake
1734 INSTALL_DESTINATION ${LIB_INSTALL_DIR}/Foo/cmake
1735 PATH_VARS INCLUDE_INSTALL_DIR SYSCONFIG_INSTALL_DIR)
1736 write_basic_package_version_file(
1737 ${CMAKE_CURRENT_BINARY_DIR}/FooConfigVersion.cmake
1738 VERSION 1.2.3
1739 COMPATIBILITY SameMajorVersion )
1740 install(FILES ${CMAKE_CURRENT_BINARY_DIR}/FooConfig.cmake
1741 ${CMAKE_CURRENT_BINARY_DIR}/FooConfigVersion.cmake
1742 DESTINATION ${LIB_INSTALL_DIR}/Foo/cmake )
1743 FooConfig.cmake.in:
1745 set(FOO_VERSION x.y.z)
1747 ...
1748 @PACKAGE_INIT@
1749 ...
1750 set_and_check(FOO_INCLUDE_DIR "@PACKAGE_INCLUDE_INSTALL_DIR@")
1751 set_and_check(FOO_SYSCONFIG_DIR "@PACKAGE_SYSCONFIG_INSTALL_DIR@")
1752 check_required_components(Foo)
1754 CMakePrintHelpers
1756 Convenience functions for printing properties and variables, useful
1757 e.g. for debugging.
1758 cmake_print_properties([TARGETS target1 .. targetN]
1760 [SOURCES source1 .. sourceN]
1761 [DIRECTORIES dir1 .. dirN]
1762 [TESTS test1 .. testN]
1763 [CACHE_ENTRIES entry1 .. entryN]
1764 PROPERTIES prop1 .. propN )
1765 This function prints the values of the properties of the given targets,
1767 source files, directories, tests or cache entries. Exactly one of the
1768 scope keywords must be used. Example:
1769 cmake_print_properties(TARGETS foo bar PROPERTIES
1771 LOCATION INTERFACE_INCLUDE_DIRS)
1772 This will print the LOCATION and INTERFACE_INCLUDE_DIRS properties for
1774 both targets foo and bar.
1775 cmake_print_variables(var1 var2 .. varN)
1777 This function will print the name of each variable followed by its
1779 value. Example:
1780 cmake_print_variables(CMAKE_C_COMPILER CMAKE_MAJOR_VERSION DOES_NOT_EXIST)
1782 Gives:
1784 -- CMAKE_C_COMPILER="/usr/bin/gcc" ; CMAKE_MAJOR_VERSION="2" ; DOES_NOT_EXIST=""
1786 CMakePrintSystemInformation
1788 print system information
1789 This file can be used for diagnostic purposes just include it in a
1791 project to see various internal CMake variables.
1792 CMakePushCheckState
1794 This module defines three macros: CMAKE_PUSH_CHECK_STATE()
1795 CMAKE_POP_CHECK_STATE() and CMAKE_RESET_CHECK_STATE() These macros can
1796 be used to save, restore and reset (i.e., clear contents) the state of
1797 the variables CMAKE_REQUIRED_FLAGS, CMAKE_REQUIRED_DEFINITIONS,
1798 CMAKE_REQUIRED_LINK_OPTIONS, CMAKE_REQUIRED_LIBRARIES,
1799 CMAKE_REQUIRED_INCLUDES and CMAKE_EXTRA_INCLUDE_FILES used by the vari‐
1800 ous Check-files coming with CMake, like e.g. check_function_exists()
1801 etc. The variable contents are pushed on a stack, pushing multiple
1802 times is supported. This is useful e.g. when executing such tests in
1803 a Find-module, where they have to be set, but after the Find-module has
1804 been executed they should have the same value as they had before.
1805 CMAKE_PUSH_CHECK_STATE() macro receives optional argument RESET.
1807 Whether it’s specified, CMAKE_PUSH_CHECK_STATE() will set all
1808 CMAKE_REQUIRED_* variables to empty values, same as
1809 CMAKE_RESET_CHECK_STATE() call will do.
1810 Usage:
1812 cmake_push_check_state(RESET)
1814 set(CMAKE_REQUIRED_DEFINITIONS -DSOME_MORE_DEF)
1815 check_function_exists(...)
1816 cmake_reset_check_state()
1817 set(CMAKE_REQUIRED_DEFINITIONS -DANOTHER_DEF)
1818 check_function_exists(...)
1819 cmake_pop_check_state()
1820 CMakeVerifyManifest
1822 CMakeVerifyManifest.cmake
1823 This script is used to verify that embedded manifests and side by side
1825 manifests for a project match. To run this script, cd to a directory
1826 and run the script with cmake -P. On the command line you can pass in
1827 versions that are OK even if not found in the .manifest files. For
1828 example, cmake -Dallow_versions=8.0.50608.0 -PCmakeVerifyManifest.cmake
1829 could be used to allow an embedded manifest of 8.0.50608.0 to be used
1830 in a project even if that version was not found in the .manifest file.
1831 CPackComponent
1833 Build binary and source package installers
1834 Variables concerning CPack Components
1836 The CPackComponent module is the module which handles the component
1837 part of CPack. See CPack module for general information about CPack.
1838 For certain kinds of binary installers (including the graphical in‐
1840 stallers on macOS and Windows), CPack generates installers that allow
1841 users to select individual application components to install. The con‐
1842 tents of each of the components are identified by the COMPONENT argu‐
1843 ment of CMake’s INSTALL command. These components can be annotated
1844 with user-friendly names and descriptions, inter-component dependen‐
1845 cies, etc., and grouped in various ways to customize the resulting in‐
1846 staller. See the cpack_add_* commands, described below, for more
1847 information about component-specific installations.
1848 Component-specific installation allows users to select specific sets of
1850 components to install during the install process. Installation compo‐
1851 nents are identified by the COMPONENT argument of CMake’s INSTALL com‐
1852 mands, and should be further described by the following CPack commands:
1853 CPACK_COMPONENTS_ALL
1855 The list of component to install.
1856 The default value of this variable is computed by CPack and con‐
1858 tains all components defined by the project. The user may set
1859 it to only include the specified components.
1860 Instead of specifying all the desired components, it is possible
1862 to obtain a list of all defined components and then remove the
1863 unwanted ones from the list. The get_cmake_property() command
1864 can be used to obtain the COMPONENTS property, then the
1865 list(REMOVE_ITEM) command can be used to remove the unwanted
1866 ones. For example, to use all defined components except foo and
1867 bar:
1868 get_cmake_property(CPACK_COMPONENTS_ALL COMPONENTS)
1870 list(REMOVE_ITEM CPACK_COMPONENTS_ALL "foo" "bar")
1871 CPACK_<GENNAME>_COMPONENT_INSTALL
1873 Enable/Disable component install for CPack generator <GENNAME>.
1874 Each CPack Generator (RPM, DEB, ARCHIVE, NSIS, DMG, etc…) has a
1876 legacy default behavior. e.g. RPM builds monolithic whereas
1877 NSIS builds component. One can change the default behavior by
1878 setting this variable to 0/1 or OFF/ON.
1879 CPACK_COMPONENTS_GROUPING
1881 Specify how components are grouped for multi-package compo‐
1882 nent-aware CPack generators.
1883 Some generators like RPM or ARCHIVE family (TGZ, ZIP, …) gener‐
1885 ates several packages files when asked for component packaging.
1886 They group the component differently depending on the value of
1887 this variable:
1888 · ONE_PER_GROUP (default): creates one package file per compo‐
1890 nent group
1891 · ALL_COMPONENTS_IN_ONE : creates a single package with all
1893 (requested) components
1894 · IGNORE : creates one package per component, i.e. IGNORE compo‐
1896 nent group
1897 One can specify different grouping for different CPack generator
1899 by using a CPACK_PROJECT_CONFIG_FILE.
1900 CPACK_COMPONENT_<compName>_DISPLAY_NAME
1902 The name to be displayed for a component.
1903 CPACK_COMPONENT_<compName>_DESCRIPTION
1905 The description of a component.
1906 CPACK_COMPONENT_<compName>_GROUP
1908 The group of a component.
1909 CPACK_COMPONENT_<compName>_DEPENDS
1911 The dependencies (list of components) on which this component
1912 depends.
1913 CPACK_COMPONENT_<compName>_HIDDEN
1915 True if this component is hidden from the user.
1916 CPACK_COMPONENT_<compName>_REQUIRED
1918 True if this component is required.
1919 CPACK_COMPONENT_<compName>_DISABLED
1921 True if this component is not selected to be installed by
1922 default.
1923 cpack_add_component
1925 Describes a CPack installation component named by the COMPONENT argu‐
1927 ment to a CMake INSTALL command.
1928 cpack_add_component(compname
1930 [DISPLAY_NAME name]
1931 [DESCRIPTION description]
1932 [HIDDEN | REQUIRED | DISABLED ]
1933 [GROUP group]
1934 [DEPENDS comp1 comp2 ... ]
1935 [INSTALL_TYPES type1 type2 ... ]
1936 [DOWNLOADED]
1937 [ARCHIVE_FILE filename]
1938 [PLIST filename])
1939 The cmake_add_component command describes an installation component,
1941 which the user can opt to install or remove as part of the graphical
1942 installation process. compname is the name of the component, as pro‐
1943 vided to the COMPONENT argument of one or more CMake INSTALL commands.
1944 DISPLAY_NAME is the displayed name of the component, used in graphical
1946 installers to display the component name. This value can be any
1947 string.
1948 DESCRIPTION is an extended description of the component, used in graph‐
1950 ical installers to give the user additional information about the com‐
1951 ponent. Descriptions can span multiple lines using \n as the line sep‐
1952 arator. Typically, these descriptions should be no more than a few
1953 lines long.
1954 HIDDEN indicates that this component will be hidden in the graphical
1956 installer, so that the user cannot directly change whether it is
1957 installed or not.
1958 REQUIRED indicates that this component is required, and therefore will
1960 always be installed. It will be visible in the graphical installer,
1961 but it cannot be unselected. (Typically, required components are shown
1962 greyed out).
1963 DISABLED indicates that this component should be disabled (unselected)
1965 by default. The user is free to select this component for installa‐
1966 tion, unless it is also HIDDEN.
1967 DEPENDS lists the components on which this component depends. If this
1969 component is selected, then each of the components listed must also be
1970 selected. The dependency information is encoded within the installer
1971 itself, so that users cannot install inconsistent sets of components.
1972 GROUP names the component group of which this component is a part. If
1974 not provided, the component will be a standalone component, not part of
1975 any component group. Component groups are described with the
1976 cpack_add_component_group command, detailed below.
1977 INSTALL_TYPES lists the installation types of which this component is a
1979 part. When one of these installations types is selected, this compo‐
1980 nent will automatically be selected. Installation types are described
1981 with the cpack_add_install_type command, detailed below.
1982 DOWNLOADED indicates that this component should be downloaded
1984 on-the-fly by the installer, rather than packaged in with the installer
1985 itself. For more information, see the cpack_configure_downloads com‐
1986 mand.
1987 ARCHIVE_FILE provides a name for the archive file created by CPack to
1989 be used for downloaded components. If not supplied, CPack will create
1990 a file with some name based on CPACK_PACKAGE_FILE_NAME and the name of
1991 the component. See cpack_configure_downloads for more information.
1992 PLIST gives a filename that is passed to pkgbuild with the --compo‐
1994 nent-plist argument when using the productbuild generator.
1995 cpack_add_component_group
1997 Describes a group of related CPack installation components.
1999 cpack_add_component_group(groupname
2001 [DISPLAY_NAME name]
2002 [DESCRIPTION description]
2003 [PARENT_GROUP parent]
2004 [EXPANDED]
2005 [BOLD_TITLE])
2006 The cpack_add_component_group describes a group of installation compo‐
2008 nents, which will be placed together within the listing of options.
2009 Typically, component groups allow the user to select/deselect all of
2010 the components within a single group via a single group-level option.
2011 Use component groups to reduce the complexity of installers with many
2012 options. groupname is an arbitrary name used to identify the group in
2013 the GROUP argument of the cpack_add_component command, which is used to
2014 place a component in a group. The name of the group must not conflict
2015 with the name of any component.
2016 DISPLAY_NAME is the displayed name of the component group, used in
2018 graphical installers to display the component group name. This value
2019 can be any string.
2020 DESCRIPTION is an extended description of the component group, used in
2022 graphical installers to give the user additional information about the
2023 components within that group. Descriptions can span multiple lines
2024 using \n as the line separator. Typically, these descriptions should
2025 be no more than a few lines long.
2026 PARENT_GROUP, if supplied, names the parent group of this group. Par‐
2028 ent groups are used to establish a hierarchy of groups, providing an
2029 arbitrary hierarchy of groups.
2030 EXPANDED indicates that, by default, the group should show up as
2032 “expanded”, so that the user immediately sees all of the components
2033 within the group. Otherwise, the group will initially show up as a
2034 single entry.
2035 BOLD_TITLE indicates that the group title should appear in bold, to
2037 call the user’s attention to the group.
2038 cpack_add_install_type
2040 Add a new installation type containing a set of predefined component
2042 selections to the graphical installer.
2043 cpack_add_install_type(typename
2045 [DISPLAY_NAME name])
2046 The cpack_add_install_type command identifies a set of preselected com‐
2048 ponents that represents a common use case for an application. For
2049 example, a “Developer” install type might include an application along
2050 with its header and library files, while an “End user” install type
2051 might just include the application’s executable. Each component iden‐
2052 tifies itself with one or more install types via the INSTALL_TYPES
2053 argument to cpack_add_component.
2054 DISPLAY_NAME is the displayed name of the install type, which will typ‐
2056 ically show up in a drop-down box within a graphical installer. This
2057 value can be any string.
2058 cpack_configure_downloads
2060 Configure CPack to download selected components on-the-fly as part of
2062 the installation process.
2063 cpack_configure_downloads(site
2065 [UPLOAD_DIRECTORY dirname]
2066 [ALL]
2067 [ADD_REMOVE|NO_ADD_REMOVE])
2068 The cpack_configure_downloads command configures installation-time
2070 downloads of selected components. For each downloadable component,
2071 CPack will create an archive containing the contents of that component,
2072 which should be uploaded to the given site. When the user selects that
2073 component for installation, the installer will download and extract the
2074 component in place. This feature is useful for creating small install‐
2075 ers that only download the requested components, saving bandwidth.
2076 Additionally, the installers are small enough that they will be
2077 installed as part of the normal installation process, and the “Change”
2078 button in Windows Add/Remove Programs control panel will allow one to
2079 add or remove parts of the application after the original installation.
2080 On Windows, the downloaded-components functionality requires the ZipDLL
2081 plug-in for NSIS, available at:
2082 http://nsis.sourceforge.net/ZipDLL_plug-in
2084 On macOS, installers that download components on-the-fly can only be
2086 built and installed on system using macOS 10.5 or later.
2087 The site argument is a URL where the archives for downloadable compo‐
2089 nents will reside, e.g., https://cmake.org/files/2.6.1/installer/ All
2090 of the archives produced by CPack should be uploaded to that location.
2091 UPLOAD_DIRECTORY is the local directory where CPack will create the
2093 various archives for each of the components. The contents of this
2094 directory should be uploaded to a location accessible by the URL given
2095 in the site argument. If omitted, CPack will use the directory CPackU‐
2096 ploads inside the CMake binary directory to store the generated ar‐
2097 chives.
2098 The ALL flag indicates that all components be downloaded. Otherwise,
2100 only those components explicitly marked as DOWNLOADED or that have a
2101 specified ARCHIVE_FILE will be downloaded. Additionally, the ALL
2102 option implies ADD_REMOVE (unless NO_ADD_REMOVE is specified).
2103 ADD_REMOVE indicates that CPack should install a copy of the installer
2105 that can be called from Windows’ Add/Remove Programs dialog (via the
2106 “Modify” button) to change the set of installed components.
2107 NO_ADD_REMOVE turns off this behavior. This option is ignored on Mac
2108 OS X.
2109 CPackIFW
2111 The documentation for the CPack IFW generator has moved here: CPack IFW
2112 Generator
2113 This module looks for the location of the command line utilities sup‐
2115 plied with the Qt Installer Framework (QtIFW).
2116 The module also defines several commands to control the behavior of the
2118 CPack IFW generator.
2119 Commands
2121 The module defines the following commands:
2122 cpack_ifw_configure_component
2124 Sets the arguments specific to the CPack IFW generator.
2125 cpack_ifw_configure_component(<compname> [COMMON] [ESSENTIAL] [VIRTUAL]
2127 [FORCED_INSTALLATION] [REQUIRES_ADMIN_RIGHTS]
2128 [NAME <name>]
2129 [DISPLAY_NAME <display_name>] # Note: Internationalization supported
2130 [DESCRIPTION <description>] # Note: Internationalization supported
2131 [UPDATE_TEXT <update_text>]
2132 [VERSION <version>]
2133 [RELEASE_DATE <release_date>]
2134 [SCRIPT <script>]
2135 [PRIORITY|SORTING_PRIORITY <sorting_priority>] # Note: PRIORITY is deprecated
2136 [DEPENDS|DEPENDENCIES <com_id> ...]
2137 [AUTO_DEPEND_ON <comp_id> ...]
2138 [LICENSES <display_name> <file_path> ...]
2139 [DEFAULT <value>]
2140 [USER_INTERFACES <file_path> <file_path> ...]
2141 [TRANSLATIONS <file_path> <file_path> ...]
2142 [REPLACES <comp_id> ...]
2143 [CHECKABLE <value>])
2144 This command should be called after cpack_add_component() com‐
2146 mand.
2147 COMMON if set, then the component will be packaged and installed
2149 as part of a group to which it belongs.
2150 ESSENTIAL
2152 if set, then the package manager stays disabled until
2153 that component is updated.
2154 VIRTUAL
2156 if set, then the component will be hidden from the in‐
2157 staller. It is a equivalent of the HIDDEN option from
2158 the cpack_add_component() command.
2159 FORCED_INSTALLATION
2161 if set, then the component must always be installed. It
2162 is a equivalent of the REQUARED option from the
2163 cpack_add_component() command.
2164 REQUIRES_ADMIN_RIGHTS
2166 set it if the component needs to be installed with ele‐
2167 vated permissions.
2168 NAME is used to create domain-like identification for this
2170 component. By default used origin component name.
2171 DISPLAY_NAME
2173 set to rewrite original name configured by cpack_add_com‐
2174 ponent() command.
2175 DESCRIPTION
2177 set to rewrite original description configured by
2178 cpack_add_component() command.
2179 UPDATE_TEXT
2181 will be added to the component description if this is an
2182 update to the component.
2183 VERSION
2185 is version of component. By default used CPACK_PACK‐
2186 AGE_VERSION.
2187 RELEASE_DATE
2189 keep empty to auto generate.
2190 SCRIPT is a relative or absolute path to operations script for
2192 this component.
2193 PRIORITY | SORTING_PRIORITY
2195 is priority of the component in the tree. The PRIORITY
2196 option is deprecated and will be removed in a future ver‐
2197 sion of CMake. Please use SORTING_PRIORITY option
2198 instead.
2199 DEPENDS | DEPENDENCIES
2201 list of dependency component or component group identi‐
2202 fiers in QtIFW style.
2203 AUTO_DEPEND_ON
2205 list of identifiers of component or component group in
2206 QtIFW style that this component has an automatic depen‐
2207 dency on.
2208 LICENSES
2210 pair of <display_name> and <file_path> of license text
2211 for this component. You can specify more then one
2212 license.
2213 DEFAULT
2215 Possible values are: TRUE, FALSE, and SCRIPT. Set to
2216 FALSE to disable the component in the installer or to
2217 SCRIPT to resolved during runtime (don’t forget add the
2218 file of the script as a value of the SCRIPT option).
2219 USER_INTERFACES
2221 is a list of <file_path> (‘.ui’ files) representing pages
2222 to load.
2223 TRANSLATIONS
2225 is a list of <file_path> (‘.qm’ files) representing
2226 translations to load.
2227 REPLACES
2229 list of identifiers of component or component group to
2230 replace.
2231 CHECKABLE
2233 Possible values are: TRUE, FALSE. Set to FALSE if you
2234 want to hide the checkbox for an item. This is useful
2235 when only a few subcomponents should be selected instead
2236 of all.
2237 cpack_ifw_configure_component_group
2239 Sets the arguments specific to the CPack IFW generator.
2240 cpack_ifw_configure_component_group(<groupname> [VIRTUAL]
2242 [FORCED_INSTALLATION] [REQUIRES_ADMIN_RIGHTS]
2243 [NAME <name>]
2244 [DISPLAY_NAME <display_name>] # Note: Internationalization supported
2245 [DESCRIPTION <description>] # Note: Internationalization supported
2246 [UPDATE_TEXT <update_text>]
2247 [VERSION <version>]
2248 [RELEASE_DATE <release_date>]
2249 [SCRIPT <script>]
2250 [PRIORITY|SORTING_PRIORITY <sorting_priority>] # Note: PRIORITY is deprecated
2251 [DEPENDS|DEPENDENCIES <com_id> ...]
2252 [AUTO_DEPEND_ON <comp_id> ...]
2253 [LICENSES <display_name> <file_path> ...]
2254 [DEFAULT <value>]
2255 [USER_INTERFACES <file_path> <file_path> ...]
2256 [TRANSLATIONS <file_path> <file_path> ...]
2257 [REPLACES <comp_id> ...]
2258 [CHECKABLE <value>])
2259 This command should be called after cpack_add_component_group()
2261 command.
2262 VIRTUAL
2264 if set, then the group will be hidden from the installer.
2265 Note that setting this on a root component does not work.
2266 FORCED_INSTALLATION
2268 if set, then the group must always be installed.
2269 REQUIRES_ADMIN_RIGHTS
2271 set it if the component group needs to be installed with
2272 elevated permissions.
2273 NAME is used to create domain-like identification for this
2275 component group. By default used origin component group
2276 name.
2277 DISPLAY_NAME
2279 set to rewrite original name configured by cpack_add_com‐
2280 ponent_group() command.
2281 DESCRIPTION
2283 set to rewrite original description configured by
2284 cpack_add_component_group() command.
2285 UPDATE_TEXT
2287 will be added to the component group description if this
2288 is an update to the component group.
2289 VERSION
2291 is version of component group. By default used
2292 CPACK_PACKAGE_VERSION.
2293 RELEASE_DATE
2295 keep empty to auto generate.
2296 SCRIPT is a relative or absolute path to operations script for
2298 this component group.
2299 PRIORITY | SORTING_PRIORITY
2301 is priority of the component group in the tree. The PRI‐
2302 ORITY option is deprecated and will be removed in a
2303 future version of CMake. Please use SORTING_PRIORITY
2304 option instead.
2305 DEPENDS | DEPENDENCIES
2307 list of dependency component or component group identi‐
2308 fiers in QtIFW style.
2309 AUTO_DEPEND_ON
2311 list of identifiers of component or component group in
2312 QtIFW style that this component group has an automatic
2313 dependency on.
2314 LICENSES
2316 pair of <display_name> and <file_path> of license text
2317 for this component group. You can specify more then one
2318 license.
2319 DEFAULT
2321 Possible values are: TRUE, FALSE, and SCRIPT. Set to
2322 TRUE to preselect the group in the installer (this takes
2323 effect only on groups that have no visible child compo‐
2324 nents) or to SCRIPT to resolved during runtime (don’t
2325 forget add the file of the script as a value of the
2326 SCRIPT option).
2327 USER_INTERFACES
2329 is a list of <file_path> (‘.ui’ files) representing pages
2330 to load.
2331 TRANSLATIONS
2333 is a list of <file_path> (‘.qm’ files) representing
2334 translations to load.
2335 REPLACES
2337 list of identifiers of component or component group to
2338 replace.
2339 CHECKABLE
2341 Possible values are: TRUE, FALSE. Set to FALSE if you
2342 want to hide the checkbox for an item. This is useful
2343 when only a few subcomponents should be selected instead
2344 of all.
2345 cpack_ifw_add_repository
2347 Add QtIFW specific remote repository to binary installer.
2348 cpack_ifw_add_repository(<reponame> [DISABLED]
2350 URL <url>
2351 [USERNAME <username>]
2352 [PASSWORD <password>]
2353 [DISPLAY_NAME <display_name>])
2354 This command will also add the <reponame> repository to a vari‐
2356 able CPACK_IFW_REPOSITORIES_ALL.
2357 DISABLED
2359 if set, then the repository will be disabled by default.
2360 URL is points to a list of available components.
2362 USERNAME
2364 is used as user on a protected repository.
2365 PASSWORD
2367 is password to use on a protected repository.
2368 DISPLAY_NAME
2370 is string to display instead of the URL.
2371 cpack_ifw_update_repository
2373 Update QtIFW specific repository from remote repository.
2374 cpack_ifw_update_repository(<reponame>
2376 [[ADD|REMOVE] URL <url>]|
2377 [REPLACE OLD_URL <old_url> NEW_URL <new_url>]]
2378 [USERNAME <username>]
2379 [PASSWORD <password>]
2380 [DISPLAY_NAME <display_name>])
2381 This command will also add the <reponame> repository to a vari‐
2383 able CPACK_IFW_REPOSITORIES_ALL.
2384 URL is points to a list of available components.
2386 OLD_URL
2388 is points to a list that will replaced.
2389 NEW_URL
2391 is points to a list that will replace to.
2392 USERNAME
2394 is used as user on a protected repository.
2395 PASSWORD
2397 is password to use on a protected repository.
2398 DISPLAY_NAME
2400 is string to display instead of the URL.
2401 cpack_ifw_add_package_resources
2403 Add additional resources in the installer binary.
2404 cpack_ifw_add_package_resources(<file_path> <file_path> ...)
2406 This command will also add the specified files to a variable
2408 CPACK_IFW_PACKAGE_RESOURCES.
2409 CPackIFWConfigureFile
2411 The module defines configure_file() similar command to configure file
2412 templates prepared in QtIFW/SDK/Creator style.
2413 Commands
2415 The module defines the following commands:
2416 cpack_ifw_configure_file
2418 Copy a file to another location and modify its contents.
2419 cpack_ifw_configure_file(<input> <output>)
2421 Copies an <input> file to an <output> file and substitutes vari‐
2423 able values referenced as %{VAR} or %VAR% in the input file con‐
2424 tent. Each variable reference will be replaced with the current
2425 value of the variable, or the empty string if the variable is
2426 not defined.
2427 CPack
2429 Build binary and source package installers.
2430 Introduction
2432 The CPack module generates a file CPackConfig.cmake intended for use in
2433 a subsequent run of the cpack program where it steers the generation
2434 of installers or/and source packages.
2435 Inclusion of the CPack module adds two new build targets, package and
2437 package_source, which build the binary and source installers respec‐
2438 tively. The generated binary installers contain everything installed
2439 via CMake’s install() command (and the deprecated commands
2440 install_files(), install_programs(), and install_targets()).
2441 For certain kinds of binary installers (including the graphical in‐
2443 stallers on macOS and Windows), CPack generates installers that allow
2444 users to select individual application components to install. See
2445 CPackComponent module for further details.
2446 CPack Generators
2448 The CPACK_GENERATOR variable has different meanings in different con‐
2449 texts. In a CMakeLists.txt file, CPACK_GENERATOR is a list of genera‐
2450 tors: and when cpack is run with no other arguments, it will iterate
2451 over that list and produce one package for each generator. In a
2452 CPACK_PROJECT_CONFIG_FILE, CPACK_GENERATOR is a string naming a single
2453 generator. If you need per-cpack-generator logic to control other
2454 cpack settings, then you need a CPACK_PROJECT_CONFIG_FILE.
2455 The CMake source tree itself contains a CPACK_PROJECT_CONFIG_FILE. See
2457 the top level file CMakeCPackOptions.cmake.in for an example.
2458 If set, the CPACK_PROJECT_CONFIG_FILE is included automatically on a
2460 per-generator basis. It only need contain overrides.
2461 Here’s how it works:
2463 · cpack runs
2465 · it includes CPackConfig.cmake
2467 · it iterates over the generators given by the -G command line option,
2469 or if no such option was specified, over the list of generators given
2470 by the CPACK_GENERATOR variable set in the CPackConfig.cmake input
2471 file.
2472 · foreach generator, it then
2474 · sets CPACK_GENERATOR to the one currently being iterated
2476 · includes the CPACK_PROJECT_CONFIG_FILE
2478 · produces the package for that generator
2480 This is the key: For each generator listed in CPACK_GENERATOR in CPack‐
2482 Config.cmake, cpack will reset CPACK_GENERATOR internally to the one
2483 currently being used and then include the CPACK_PROJECT_CONFIG_FILE.
2484 Variables common to all CPack Generators
2486 Before including this CPack module in your CMakeLists.txt file, there
2487 are a variety of variables that can be set to customize the resulting
2488 installers. The most commonly-used variables are:
2489 CPACK_PACKAGE_NAME
2491 The name of the package (or application). If not specified, it
2492 defaults to the project name.
2493 CPACK_PACKAGE_VENDOR
2495 The name of the package vendor. (e.g., “Kitware”). The default
2496 is “Humanity”.
2497 CPACK_PACKAGE_DIRECTORY
2499 The directory in which CPack is doing its packaging. If it is
2500 not set then this will default (internally) to the build dir.
2501 This variable may be defined in a CPack config file or from the
2502 cpack command line option -B. If set, the command line option
2503 overrides the value found in the config file.
2504 CPACK_PACKAGE_VERSION_MAJOR
2506 Package major version. This variable will always be set, but
2507 its default value depends on whether or not version details were
2508 given to the project() command in the top level CMakeLists.txt
2509 file. If version details were given, the default value will be
2510 CMAKE_PROJECT_VERSION_MAJOR. If no version details were given,
2511 a default version of 0.1.1 will be assumed, leading to
2512 CPACK_PACKAGE_VERSION_MAJOR having a default value of 0.
2513 CPACK_PACKAGE_VERSION_MINOR
2515 Package minor version. The default value is determined based on
2516 whether or not version details were given to the project() com‐
2517 mand in the top level CMakeLists.txt file. If version details
2518 were given, the default value will be CMAKE_PROJECT_VER‐
2519 SION_MINOR, but if no minor version component was specified then
2520 CPACK_PACKAGE_VERSION_MINOR will be left unset. If no project
2521 version was given at all, a default version of 0.1.1 will be
2522 assumed, leading to CPACK_PACKAGE_VERSION_MINOR having a default
2523 value of 1.
2524 CPACK_PACKAGE_VERSION_PATCH
2526 Package patch version. The default value is determined based on
2527 whether or not version details were given to the project() com‐
2528 mand in the top level CMakeLists.txt file. If version details
2529 were given, the default value will be CMAKE_PROJECT_VER‐
2530 SION_PATCH, but if no patch version component was specified then
2531 CPACK_PACKAGE_VERSION_PATCH will be left unset. If no project
2532 version was given at all, a default version of 0.1.1 will be
2533 assumed, leading to CPACK_PACKAGE_VERSION_PATCH having a default
2534 value of 1.
2535 CPACK_PACKAGE_DESCRIPTION
2537 A description of the project, used in places such as the intro‐
2538 duction screen of CPack-generated Windows installers. If not
2539 set, the value of this variable is populated from the file named
2540 by CPACK_PACKAGE_DESCRIPTION_FILE.
2541 CPACK_PACKAGE_DESCRIPTION_FILE
2543 A text file used to describe the project when
2544 CPACK_PACKAGE_DESCRIPTION is not explicitly set. The default
2545 value for CPACK_PACKAGE_DESCRIPTION_FILE points to a built-in
2546 template file Templates/CPack.GenericDescription.txt.
2547 CPACK_PACKAGE_DESCRIPTION_SUMMARY
2549 Short description of the project (only a few words). If the
2550 CMAKE_PROJECT_DESCRIPTION variable is set, it is used as the
2551 default value, otherwise the default will be a string generated
2552 by CMake based on CMAKE_PROJECT_NAME.
2553 CPACK_PACKAGE_HOMEPAGE_URL
2555 Project homepage URL. The default value is taken from the
2556 CMAKE_PROJECT_HOMEPAGE_URL variable, which is set by the top
2557 level project() command, or else the default will be empty if no
2558 URL was provided to project().
2559 CPACK_PACKAGE_FILE_NAME
2561 The name of the package file to generate, not including the
2562 extension. For example, cmake-2.6.1-Linux-i686. The default
2563 value is:
2564 ${CPACK_PACKAGE_NAME}-${CPACK_PACKAGE_VERSION}-${CPACK_SYSTEM_NAME}
2566 CPACK_PACKAGE_INSTALL_DIRECTORY
2568 Installation directory on the target system. This may be used by
2569 some CPack generators like NSIS to create an installation direc‐
2570 tory e.g., “CMake 2.5” below the installation prefix. All
2571 installed elements will be put inside this directory.
2572 CPACK_PACKAGE_ICON
2574 A branding image that will be displayed inside the installer
2575 (used by GUI installers).
2576 CPACK_PACKAGE_CHECKSUM
2578 An algorithm that will be used to generate an additional file
2579 with the checksum of the package. The output file name will be:
2580 ${CPACK_PACKAGE_FILE_NAME}.${CPACK_PACKAGE_CHECKSUM}
2582 Supported algorithms are those listed by the string(<HASH>) com‐
2584 mand.
2585 CPACK_PROJECT_CONFIG_FILE
2587 CPack-time project CPack configuration file. This file is
2588 included at cpack time, once per generator after CPack has set
2589 CPACK_GENERATOR to the actual generator being used. It allows
2590 per-generator setting of CPACK_* variables at cpack time.
2591 CPACK_RESOURCE_FILE_LICENSE
2593 License to be embedded in the installer. It will typically be
2594 displayed to the user by the produced installer (often with an
2595 explicit “Accept” button, for graphical installers) prior to
2596 installation. This license file is NOT added to the installed
2597 files but is used by some CPack generators like NSIS. If you
2598 want to install a license file (may be the same as this one)
2599 along with your project, you must add an appropriate CMake
2600 install() command in your CMakeLists.txt.
2601 CPACK_RESOURCE_FILE_README
2603 ReadMe file to be embedded in the installer. It typically
2604 describes in some detail the purpose of the project during the
2605 installation. Not all CPack generators use this file.
2606 CPACK_RESOURCE_FILE_WELCOME
2608 Welcome file to be embedded in the installer. It welcomes users
2609 to this installer. Typically used in the graphical installers
2610 on Windows and Mac OS X.
2611 CPACK_MONOLITHIC_INSTALL
2613 Disables the component-based installation mechanism. When set,
2614 the component specification is ignored and all installed items
2615 are put in a single “MONOLITHIC” package. Some CPack generators
2616 do monolithic packaging by default and may be asked to do compo‐
2617 nent packaging by setting CPACK_<GENNAME>_COMPONENT_INSTALL to
2618 TRUE.
2619 CPACK_GENERATOR
2621 List of CPack generators to use. If not specified, CPack will
2622 create a set of options following the naming pattern
2623 CPACK_BINARY_<GENNAME> (e.g. CPACK_BINARY_NSIS) allowing the
2624 user to enable/disable individual generators. If the -G option
2625 is given on the cpack command line, it will override this vari‐
2626 able and any CPACK_BINARY_<GENNAME> options.
2627 CPACK_OUTPUT_CONFIG_FILE
2629 The name of the CPack binary configuration file. This file is
2630 the CPack configuration generated by the CPack module for binary
2631 installers. Defaults to CPackConfig.cmake.
2632 CPACK_PACKAGE_EXECUTABLES
2634 Lists each of the executables and associated text label to be
2635 used to create Start Menu shortcuts. For example, setting this
2636 to the list ccmake;CMake will create a shortcut named “CMake”
2637 that will execute the installed executable ccmake. Not all
2638 CPack generators use it (at least NSIS, WIX and OSXX11 do).
2639 CPACK_STRIP_FILES
2641 List of files to be stripped. Starting with CMake 2.6.0,
2642 CPACK_STRIP_FILES will be a boolean variable which enables
2643 stripping of all files (a list of files evaluates to TRUE in
2644 CMake, so this change is compatible).
2645 CPACK_VERBATIM_VARIABLES
2647 If set to TRUE, values of variables prefixed with CPACK_ will be
2648 escaped before being written to the configuration files, so that
2649 the cpack program receives them exactly as they were specified.
2650 If not, characters like quotes and backslashes can cause parsing
2651 errors or alter the value received by the cpack program.
2652 Defaults to FALSE for backwards compatibility.
2653 Variables for Source Package Generators
2655 The following CPack variables are specific to source packages, and will
2656 not affect binary packages:
2657 CPACK_SOURCE_PACKAGE_FILE_NAME
2659 The name of the source package. For example cmake-2.6.1.
2660 CPACK_SOURCE_STRIP_FILES
2662 List of files in the source tree that will be stripped. Start‐
2663 ing with CMake 2.6.0, CPACK_SOURCE_STRIP_FILES will be a boolean
2664 variable which enables stripping of all files (a list of files
2665 evaluates to TRUE in CMake, so this change is compatible).
2666 CPACK_SOURCE_GENERATOR
2668 List of generators used for the source packages. As with
2669 CPACK_GENERATOR, if this is not specified then CPack will create
2670 a set of options (e.g. CPACK_SOURCE_ZIP) allowing users to
2671 select which packages will be generated.
2672 CPACK_SOURCE_OUTPUT_CONFIG_FILE
2674 The name of the CPack source configuration file. This file is
2675 the CPack configuration generated by the CPack module for source
2676 installers. Defaults to CPackSourceConfig.cmake.
2677 CPACK_SOURCE_IGNORE_FILES
2679 Pattern of files in the source tree that won’t be packaged when
2680 building a source package. This is a list of regular expression
2681 patterns (that must be properly escaped), e.g.,
2682 /CVS/;/\\.svn/;\\.swp$;\\.#;/#;.*~;cscope.*
2683 Variables for Advanced Use
2685 The following variables are for advanced uses of CPack:
2686 CPACK_CMAKE_GENERATOR
2688 What CMake generator should be used if the project is a CMake
2689 project. Defaults to the value of CMAKE_GENERATOR. Few users
2690 will want to change this setting.
2691 CPACK_INSTALL_CMAKE_PROJECTS
2693 List of four values that specify what project to install. The
2694 four values are: Build directory, Project Name, Project Compo‐
2695 nent, Directory. If omitted, CPack will build an installer that
2696 installs everything.
2697 CPACK_SYSTEM_NAME
2699 System name, defaults to the value of CMAKE_SYSTEM_NAME, except
2700 on Windows where it will be win32 or win64.
2701 CPACK_PACKAGE_VERSION
2703 Package full version, used internally. By default, this is
2704 built from CPACK_PACKAGE_VERSION_MAJOR,
2705 CPACK_PACKAGE_VERSION_MINOR, and CPACK_PACKAGE_VERSION_PATCH.
2706 CPACK_TOPLEVEL_TAG
2708 Directory for the installed files.
2709 CPACK_INSTALL_COMMANDS
2711 Extra commands to install components.
2712 CPACK_INSTALLED_DIRECTORIES
2714 Extra directories to install.
2715 CPACK_PACKAGE_INSTALL_REGISTRY_KEY
2717 Registry key used when installing this project. This is only
2718 used by installers for Windows. The default value is based on
2719 the installation directory.
2720 CPACK_CREATE_DESKTOP_LINKS
2722 List of desktop links to create. Each desktop link requires a
2723 corresponding start menu shortcut as created by
2724 CPACK_PACKAGE_EXECUTABLES.
2725 CPACK_BINARY_<GENNAME>
2727 CPack generated options for binary generators. The CPack.cmake
2728 module generates (when CPACK_GENERATOR is not set) a set of
2729 CMake options (see CMake option() command) which may then be
2730 used to select the CPack generator(s) to be used when building
2731 the package target or when running cpack without the -G option.
2732 CSharpUtilities
2734 Functions to make configuration of CSharp/.NET targets easier.
2735 A collection of CMake utility functions useful for dealing with CSharp
2737 targets for Visual Studio generators from version 2010 and later.
2738 The following functions are provided by this module:
2740 Main functions
2742 · csharp_set_windows_forms_properties()
2744 · csharp_set_designer_cs_properties()
2746 · csharp_set_xaml_cs_properties()
2748 Helper functions
2750 · csharp_get_filename_keys()
2752 · csharp_get_filename_key_base()
2754 · csharp_get_dependentupon_name()
2756 Main functions provided by the module
2758 csharp_set_windows_forms_properties
2759 Sets source file properties for use of Windows Forms. Use this,
2760 if your CSharp target uses Windows Forms:
2761 csharp_set_windows_forms_properties([<file1> [<file2> [...]]])
2763 <fileN>
2765 List of all source files which are relevant for setting
2766 the VS_CSHARP_<tagname> properties (including .cs, .resx
2767 and .Designer.cs extensions).
2768 In the list of all given files for all files ending with
2770 .Designer.cs and .resx is searched. For every designer or
2771 resource file a file with the same base name but only .cs as
2772 extension is searched. If this is found, the VS_CSHARP_<tag‐
2773 name> properties are set as follows:
2774 for the .cs file:
2776 · VS_CSHARP_SubType “Form”
2778 for the .Designer.cs file (if it exists):
2780 · VS_CSHARP_DependentUpon <cs-filename>
2782 · VS_CSHARP_DesignTime “” (delete tag if previously
2784 defined)
2785 · VS_CSHARP_AutoGen “”(delete tag if previously defined)
2787 for the .resx file (if it exists):
2789 · VS_RESOURCE_GENERATOR “” (delete tag if previously
2791 defined)
2792 · VS_CSHARP_DependentUpon <cs-filename>
2794 · VS_CSHARP_SubType “Designer”
2796 csharp_set_designer_cs_properties
2798 Sets source file properties of .Designer.cs files depending on
2799 sibling filenames. Use this, if your CSharp target does not use
2800 Windows Forms (for Windows Forms use
2801 csharp_set_designer_cs_properties() instead):
2802 csharp_set_designer_cs_properties([<file1> [<file2> [...]]])
2804 <fileN>
2806 List of all source files which are relevant for setting
2807 the VS_CSHARP_<tagname> properties (including .cs, .resx,
2808 .settings and .Designer.cs extensions).
2809 In the list of all given files for all files ending with
2811 .Designer.cs is searched. For every designer file all files with
2812 the same base name but different extensions are searched. If a
2813 match is found, the source file properties of the designer file
2814 are set depending on the extension of the matched file:
2815 if match is .resx file:
2817 · VS_CSHARP_AutoGen “True”
2819 · VS_CSHARP_DesignTime “True”
2821 · VS_CSHARP_DependentUpon <resx-filename>
2823 if match is .cs file:
2825 · VS_CSHARP_DependentUpon <cs-filename>
2827 if match is .settings file:
2829 · VS_CSHARP_AutoGen “True”
2831 · VS_CSHARP_DesignTimeSharedInput “True”
2833 · VS_CSHARP_DependentUpon <settings-filename>
2835 NOTE:
2837 Because the source file properties of the .Designer.cs file are set
2838 according to the found matches and every match sets the
2839 VS_CSHARP_DependentUpon property, there should only be one match for
2840 each Designer.cs file.
2841 csharp_set_xaml_cs_properties
2843 Sets source file properties for use of Windows Presentation
2844 Foundation (WPF) and XAML. Use this, if your CSharp target uses
2845 WPF/XAML:
2846 csharp_set_xaml_cs_properties([<file1> [<file2> [...]]])
2848 <fileN>
2850 List of all source files which are relevant for setting
2851 the VS_CSHARP_<tagname> properties (including .cs, .xaml,
2852 and .xaml.cs extensions).
2853 In the list of all given files for all files ending with
2855 .xaml.cs is searched. For every xaml-cs file, a file with the
2856 same base name but extension .xaml is searched. If a match is
2857 found, the source file properties of the .xaml.cs file are set:
2858 · VS_CSHARP_DependentUpon <xaml-filename>
2860 Helper functions which are used by the above ones
2862 csharp_get_filename_keys
2863 Helper function which computes a list of key values to identify
2864 source files independently of relative/absolute paths given in
2865 cmake and eliminates case sensitivity:
2866 csharp_get_filename_keys(OUT [<file1> [<file2> [...]]])
2868 OUT Name of the variable in which the list of keys is stored
2870 <fileN>
2872 filename(s) as given to to CSharp target using
2873 add_library() or add_executable()
2874 In some way the function applies a canonicalization to the
2876 source names. This is necessary to find file matches if the
2877 files have been added to the target with different directory
2878 prefixes:
2879 add_library(lib
2881 myfile.cs
2882 ${CMAKE_CURRENT_SOURCE_DIR}/myfile.Designer.cs)
2883 set_source_files_properties(myfile.Designer.cs PROPERTIES
2885 VS_CSHARP_DependentUpon myfile.cs)
2886 # this will fail, because in cmake
2888 # - ${CMAKE_CURRENT_SOURCE_DIR}/myfile.Designer.cs
2889 # - myfile.Designer.cs
2890 # are not the same source file. The source file property is not set.
2891 csharp_get_filename_key_base
2893 Returns the full filepath and name without extension of a key.
2894 KEY is expected to be a key from csharp_get_filename_keys. In
2895 BASE the value of KEY without the file extension is returned:
2896 csharp_get_filename_key_base(BASE KEY)
2898 BASE Name of the variable with the computed “base” of KEY.
2900 KEY The key of which the base will be computed. Expected to
2902 be a upper case full filename.
2903 csharp_get_dependentupon_name
2905 Computes a string which can be used as value for the source file
2906 property VS_CSHARP_<tagname> with target being DependentUpon:
2907 csharp_get_dependentupon_name(NAME FILE)
2909 NAME Name of the variable with the result value
2911 FILE Filename to convert to <DependentUpon> value
2913 Actually this is only the filename without any path given at the
2915 moment.
2916 CTest
2918 Configure a project for testing with CTest/CDash
2919 Include this module in the top CMakeLists.txt file of a project to
2921 enable testing with CTest and dashboard submissions to CDash:
2922 project(MyProject)
2924 ...
2925 include(CTest)
2926 The module automatically creates a BUILD_TESTING option that selects
2928 whether to enable testing support (ON by default). After including the
2929 module, use code like:
2930 if(BUILD_TESTING)
2932 # ... CMake code to create tests ...
2933 endif()
2934 to creating tests when testing is enabled.
2936 To enable submissions to a CDash server, create a CTestConfig.cmake
2938 file at the top of the project with content such as:
2939 set(CTEST_NIGHTLY_START_TIME "01:00:00 UTC")
2941 set(CTEST_SUBMIT_URL "http://my.cdash.org/submit.php?project=MyProject")
2942 (the CDash server can provide the file to a project administrator who
2944 configures MyProject). Settings in the config file are shared by both
2945 this CTest module and the ctest(1) command-line Dashboard Client mode
2946 (ctest -S).
2947 While building a project for submission to CDash, CTest scans the build
2949 output for errors and warnings and reports them with surrounding con‐
2950 text from the build log. This generic approach works for all build
2951 tools, but does not give details about the command invocation that pro‐
2952 duced a given problem. One may get more detailed reports by setting
2953 the CTEST_USE_LAUNCHERS variable:
2954 set(CTEST_USE_LAUNCHERS 1)
2956 in the CTestConfig.cmake file.
2958 CTestCoverageCollectGCOV
2960 This module provides the ctest_coverage_collect_gcov function.
2961 This function runs gcov on all .gcda files found in the binary tree and
2963 packages the resulting .gcov files into a tar file. This tarball also
2964 contains the following:
2965 · data.json defines the source and build directories for use by CDash.
2967 · Labels.json indicates any LABELS that have been set on the source
2969 files.
2970 · The uncovered directory holds any uncovered files found by
2972 CTEST_EXTRA_COVERAGE_GLOB.
2973 After generating this tar file, it can be sent to CDash for display
2975 with the ctest_submit(CDASH_UPLOAD) command.
2976 cdash_coverage_collect_gcov
2978 ctest_coverage_collect_gcov(TARBALL <tarfile>
2980 [SOURCE <source_dir>][BUILD <build_dir>]
2981 [GCOV_COMMAND <gcov_command>]
2982 [GCOV_OPTIONS <options>...]
2983 )
2984 Run gcov and package a tar file for CDash. The options are:
2986 TARBALL <tarfile>
2988 Specify the location of the .tar file to be created for
2989 later upload to CDash. Relative paths will be inter‐
2990 preted with respect to the top-level build directory.
2991 SOURCE <source_dir>
2993 Specify the top-level source directory for the build.
2994 Default is the value of CTEST_SOURCE_DIRECTORY.
2995 BUILD <build_dir>
2997 Specify the top-level build directory for the build.
2998 Default is the value of CTEST_BINARY_DIRECTORY.
2999 GCOV_COMMAND <gcov_command>
3001 Specify the full path to the gcov command on the machine.
3002 Default is the value of CTEST_COVERAGE_COMMAND.
3003 GCOV_OPTIONS <options>...
3005 Specify options to be passed to gcov. The gcov command
3006 is run as gcov <options>... -o <gcov-dir> <file>.gcda.
3007 If not specified, the default option is just -b.
3008 GLOB Recursively search for .gcda files in build_dir rather
3010 than determining search locations by reading TargetDirec‐
3011 tories.txt.
3012 DELETE Delete coverage files after they’ve been packaged into
3014 the .tar.
3015 QUIET Suppress non-error messages that otherwise would have
3017 been printed out by this function.
3018 CTestScriptMode
3020 This file is read by ctest in script mode (-S)
3021 CTestUseLaunchers
3023 Set the RULE_LAUNCH_* global properties when CTEST_USE_LAUNCHERS is on.
3024 CTestUseLaunchers is automatically included when you include(CTest).
3026 However, it is split out into its own module file so projects can use
3027 the CTEST_USE_LAUNCHERS functionality independently.
3028 To use launchers, set CTEST_USE_LAUNCHERS to ON in a ctest -S dashboard
3030 script, and then also set it in the cache of the configured project.
3031 Both cmake and ctest need to know the value of it for the launchers to
3032 work properly. CMake needs to know in order to generate proper build
3033 rules, and ctest, in order to produce the proper error and warning
3034 analysis.
3035 For convenience, you may set the ENV variable CTEST_USE_LAUNCH‐
3037 ERS_DEFAULT in your ctest -S script, too. Then, as long as your CMake‐
3038 Lists uses include(CTest) or include(CTestUseLaunchers), it will use
3039 the value of the ENV variable to initialize a CTEST_USE_LAUNCHERS cache
3040 variable. This cache variable initialization only occurs if
3041 CTEST_USE_LAUNCHERS is not already defined. If CTEST_USE_LAUNCHERS is
3042 on in a ctest -S script the ctest_configure command will add
3043 -DCTEST_USE_LAUNCHERS:BOOL=TRUE to the cmake command used to configure
3044 the project.
3045 Dart
3047 Configure a project for testing with CTest or old Dart Tcl Client
3048 This file is the backwards-compatibility version of the CTest module.
3050 It supports using the old Dart 1 Tcl client for driving dashboard sub‐
3051 missions as well as testing with CTest. This module should be included
3052 in the CMakeLists.txt file at the top of a project. Typical usage:
3053 include(Dart)
3055 if(BUILD_TESTING)
3056 # ... testing related CMake code ...
3057 endif()
3058 The BUILD_TESTING option is created by the Dart module to determine
3060 whether testing support should be enabled. The default is ON.
3061 DeployQt4
3063 Functions to help assemble a standalone Qt4 executable.
3064 A collection of CMake utility functions useful for deploying Qt4 exe‐
3066 cutables.
3067 The following functions are provided by this module:
3069 write_qt4_conf
3071 resolve_qt4_paths
3072 fixup_qt4_executable
3073 install_qt4_plugin_path
3074 install_qt4_plugin
3075 install_qt4_executable
3076 Requires CMake 2.6 or greater because it uses function and PAR‐
3078 ENT_SCOPE. Also depends on BundleUtilities.cmake.
3079 write_qt4_conf(<qt_conf_dir> <qt_conf_contents>)
3081 Writes a qt.conf file with the <qt_conf_contents> into <qt_conf_dir>.
3083 resolve_qt4_paths(<paths_var> [<executable_path>])
3085 Loop through <paths_var> list and if any don’t exist resolve them rela‐
3087 tive to the <executable_path> (if supplied) or the CMAKE_INSTALL_PRE‐
3088 FIX.
3089 fixup_qt4_executable(<executable>
3091 [<qtplugins> <libs> <dirs> <plugins_dir> <request_qt_conf>])
3092 Copies Qt plugins, writes a Qt configuration file (if needed) and fixes
3094 up a Qt4 executable using BundleUtilities so it is standalone and can
3095 be drag-and-drop copied to another machine as long as all of the system
3096 libraries are compatible.
3097 <executable> should point to the executable to be fixed-up.
3099 <qtplugins> should contain a list of the names or paths of any Qt plug‐
3101 ins to be installed.
3102 <libs> will be passed to BundleUtilities and should be a list of any
3104 already installed plugins, libraries or executables to also be
3105 fixed-up.
3106 <dirs> will be passed to BundleUtilities and should contain and direc‐
3108 tories to be searched to find library dependencies.
3109 <plugins_dir> allows an custom plugins directory to be used.
3111 <request_qt_conf> will force a qt.conf file to be written even if not
3113 needed.
3114 install_qt4_plugin_path(plugin executable copy installed_plugin_path_var
3116 <plugins_dir> <component> <configurations>)
3117 Install (or copy) a resolved <plugin> to the default plugins directory
3119 (or <plugins_dir>) relative to <executable> and store the result in
3120 <installed_plugin_path_var>.
3121 If <copy> is set to TRUE then the plugins will be copied rather than
3123 installed. This is to allow this module to be used at CMake time
3124 rather than install time.
3125 If <component> is set then anything installed will use this COMPONENT.
3127 install_qt4_plugin(plugin executable copy installed_plugin_path_var
3129 <plugins_dir> <component>)
3130 Install (or copy) an unresolved <plugin> to the default plugins direc‐
3132 tory (or <plugins_dir>) relative to <executable> and store the result
3133 in <installed_plugin_path_var>. See documentation of INSTALL_QT4_PLUG‐
3134 IN_PATH.
3135 install_qt4_executable(<executable>
3137 [<qtplugins> <libs> <dirs> <plugins_dir> <request_qt_conf> <component>])
3138 Installs Qt plugins, writes a Qt configuration file (if needed) and
3140 fixes up a Qt4 executable using BundleUtilities so it is standalone and
3141 can be drag-and-drop copied to another machine as long as all of the
3142 system libraries are compatible. The executable will be fixed-up at
3143 install time. <component> is the COMPONENT used for bundle fixup and
3144 plugin installation. See documentation of FIXUP_QT4_BUNDLE.
3145 Documentation
3147 This module provides support for the VTK documentation framework. It
3148 relies on several tools (Doxygen, Perl, etc).
3149 ExternalData
3151 Manage data files stored outside source tree
3152 Introduction
3154 Use this module to unambiguously reference data files stored outside
3155 the source tree and fetch them at build time from arbitrary local and
3156 remote content-addressed locations. Functions provided by this module
3157 recognize arguments with the syntax DATA{<name>} as references to
3158 external data, replace them with full paths to local copies of those
3159 data, and create build rules to fetch and update the local copies.
3160 For example:
3162 include(ExternalData)
3164 set(ExternalData_URL_TEMPLATES "file:///local/%(algo)/%(hash)"
3165 "file:////host/share/%(algo)/%(hash)"
3166 "http://data.org/%(algo)/%(hash)")
3167 ExternalData_Add_Test(MyData
3168 NAME MyTest
3169 COMMAND MyExe DATA{MyInput.png}
3170 )
3171 ExternalData_Add_Target(MyData)
3172 When test MyTest runs the DATA{MyInput.png} argument will be replaced
3174 by the full path to a real instance of the data file MyInput.png on
3175 disk. If the source tree contains a content link such as MyIn‐
3176 put.png.md5 then the MyData target creates a real MyInput.png in the
3177 build tree.
3178 Module Functions
3180 ExternalData_Expand_Arguments
3181 The ExternalData_Expand_Arguments function evaluates DATA{} ref‐
3182 erences in its arguments and constructs a new list of arguments:
3183 ExternalData_Expand_Arguments(
3185 <target> # Name of data management target
3186 <outVar> # Output variable
3187 [args...] # Input arguments, DATA{} allowed
3188 )
3189 It replaces each DATA{} reference in an argument with the full
3191 path of a real data file on disk that will exist after the <tar‐
3192 get> builds.
3193 ExternalData_Add_Test
3195 The ExternalData_Add_Test function wraps around the CMake
3196 add_test() command but supports DATA{} references in its argu‐
3197 ments:
3198 ExternalData_Add_Test(
3200 <target> # Name of data management target
3201 ... # Arguments of add_test(), DATA{} allowed
3202 )
3203 It passes its arguments through ExternalData_Expand_Arguments
3205 and then invokes the add_test() command using the results.
3206 ExternalData_Add_Target
3208 The ExternalData_Add_Target function creates a custom target to
3209 manage local instances of data files stored externally:
3210 ExternalData_Add_Target(
3212 <target> # Name of data management target
3213 )
3214 It creates custom commands in the target as necessary to make
3216 data files available for each DATA{} reference previously evalu‐
3217 ated by other functions provided by this module. Data files may
3218 be fetched from one of the URL templates specified in the Exter‐
3219 nalData_URL_TEMPLATES variable, or may be found locally in one
3220 of the paths specified in the ExternalData_OBJECT_STORES vari‐
3221 able.
3222 Typically only one target is needed to manage all external data
3224 within a project. Call this function once at the end of config‐
3225 uration after all data references have been processed.
3226 Module Variables
3228 The following variables configure behavior. They should be set before
3229 calling any of the functions provided by this module.
3230 ExternalData_BINARY_ROOT
3232 The ExternalData_BINARY_ROOT variable may be set to the direc‐
3233 tory to hold the real data files named by expanded DATA{} refer‐
3234 ences. The default is CMAKE_BINARY_DIR. The directory layout
3235 will mirror that of content links under External‐
3236 Data_SOURCE_ROOT.
3237 ExternalData_CUSTOM_SCRIPT_<key>
3239 Specify a full path to a .cmake custom fetch script identified
3240 by <key> in entries of the ExternalData_URL_TEMPLATES list. See
3241 Custom Fetch Scripts.
3242 ExternalData_LINK_CONTENT
3244 The ExternalData_LINK_CONTENT variable may be set to the name of
3245 a supported hash algorithm to enable automatic conversion of
3246 real data files referenced by the DATA{} syntax into content
3247 links. For each such <file> a content link named <file><ext> is
3248 created. The original file is renamed to the form .External‐
3249 Data_<algo>_<hash> to stage it for future transmission to one of
3250 the locations in the list of URL templates (by means outside the
3251 scope of this module). The data fetch rule created for the con‐
3252 tent link will use the staged object if it cannot be found using
3253 any URL template.
3254 ExternalData_NO_SYMLINKS
3256 The real data files named by expanded DATA{} references may be
3257 made available under ExternalData_BINARY_ROOT using symbolic
3258 links on some platforms. The ExternalData_NO_SYMLINKS variable
3259 may be set to disable use of symbolic links and enable use of
3260 copies instead.
3261 ExternalData_OBJECT_STORES
3263 The ExternalData_OBJECT_STORES variable may be set to a list of
3264 local directories that store objects using the layout
3265 <dir>/%(algo)/%(hash). These directories will be searched first
3266 for a needed object. If the object is not available in any
3267 store then it will be fetched remotely using the URL templates
3268 and added to the first local store listed. If no stores are
3269 specified the default is a location inside the build tree.
3270 ExternalData_SERIES_PARSE
3272 ExternalData_SERIES_PARSE_PREFIX
3274 ExternalData_SERIES_PARSE_NUMBER
3276 ExternalData_SERIES_PARSE_SUFFIX
3278 ExternalData_SERIES_MATCH
3280 See Referencing File Series.
3281 ExternalData_SOURCE_ROOT
3283 The ExternalData_SOURCE_ROOT variable may be set to the highest
3284 source directory containing any path named by a DATA{} refer‐
3285 ence. The default is CMAKE_SOURCE_DIR. External‐
3286 Data_SOURCE_ROOT and CMAKE_SOURCE_DIR must refer to directories
3287 within a single source distribution (e.g. they come together in
3288 one tarball).
3289 ExternalData_TIMEOUT_ABSOLUTE
3291 The ExternalData_TIMEOUT_ABSOLUTE variable sets the download
3292 absolute timeout, in seconds, with a default of 300 seconds.
3293 Set to 0 to disable enforcement.
3294 ExternalData_TIMEOUT_INACTIVITY
3296 The ExternalData_TIMEOUT_INACTIVITY variable sets the download
3297 inactivity timeout, in seconds, with a default of 60 seconds.
3298 Set to 0 to disable enforcement.
3299 ExternalData_URL_ALGO_<algo>_<key>
3301 Specify a custom URL component to be substituted for URL tem‐
3302 plate placeholders of the form %(algo:<key>), where <key> is a
3303 valid C identifier, when fetching an object referenced via hash
3304 algorithm <algo>. If not defined, the default URL component is
3305 just <algo> for any <key>.
3306 ExternalData_URL_TEMPLATES
3308 The ExternalData_URL_TEMPLATES may be set to provide a list of
3309 of URL templates using the placeholders %(algo) and %(hash) in
3310 each template. Data fetch rules try each URL template in order
3311 by substituting the hash algorithm name for %(algo) and the hash
3312 value for %(hash). Alternatively one may use %(algo:<key>) with
3313 ExternalData_URL_ALGO_<algo>_<key> variables to gain more flexi‐
3314 bility in remote URLs.
3315 Referencing Files
3317 Referencing Single Files
3318 The DATA{} syntax is literal and the <name> is a full or relative path
3319 within the source tree. The source tree must contain either a real
3320 data file at <name> or a “content link” at <name><ext> containing a
3321 hash of the real file using a hash algorithm corresponding to <ext>.
3322 For example, the argument DATA{img.png} may be satisfied by either a
3323 real img.png file in the current source directory or a img.png.md5 file
3324 containing its MD5 sum.
3325 Multiple content links of the same name with different hash algorithms
3327 are supported (e.g. img.png.sha256 and img.png.sha1) so long as they
3328 all correspond to the same real file. This allows objects to be
3329 fetched from sources indexed by different hash algorithms.
3330 Referencing File Series
3332 The DATA{} syntax can be told to fetch a file series using the form
3333 DATA{<name>,:}, where the : is literal. If the source tree contains a
3334 group of files or content links named like a series then a reference to
3335 one member adds rules to fetch all of them. Although all members of a
3336 series are fetched, only the file originally named by the DATA{} argu‐
3337 ment is substituted for it. The default configuration recognizes file
3338 series names ending with #.ext, _#.ext, .#.ext, or -#.ext where # is a
3339 sequence of decimal digits and .ext is any single extension. Configure
3340 it with a regex that parses <number> and <suffix> parts from the end of
3341 <name>:
3342 ExternalData_SERIES_PARSE = regex of the form (<number>)(<suffix>)$
3344 For more complicated cases set:
3346 ExternalData_SERIES_PARSE = regex with at least two () groups
3348 ExternalData_SERIES_PARSE_PREFIX = <prefix> regex group number, if any
3349 ExternalData_SERIES_PARSE_NUMBER = <number> regex group number
3350 ExternalData_SERIES_PARSE_SUFFIX = <suffix> regex group number
3351 Configure series number matching with a regex that matches the <number>
3353 part of series members named <prefix><number><suffix>:
3354 ExternalData_SERIES_MATCH = regex matching <number> in all series members
3356 Note that the <suffix> of a series does not include a hash-algorithm
3358 extension.
3359 Referencing Associated Files
3361 The DATA{} syntax can alternatively match files associated with the
3362 named file and contained in the same directory. Associated files may
3363 be specified by options using the syntax
3364 DATA{<name>,<opt1>,<opt2>,...}. Each option may specify one file by
3365 name or specify a regular expression to match file names using the syn‐
3366 tax REGEX:<regex>. For example, the arguments:
3367 DATA{MyData/MyInput.mhd,MyInput.img} # File pair
3369 DATA{MyData/MyFrames00.png,REGEX:MyFrames[0-9]+\\.png} # Series
3370 will pass MyInput.mha and MyFrames00.png on the command line but ensure
3372 that the associated files are present next to them.
3373 Referencing Directories
3375 The DATA{} syntax may reference a directory using a trailing slash and
3376 a list of associated files. The form DATA{<name>/,<opt1>,<opt2>,...}
3377 adds rules to fetch any files in the directory that match one of the
3378 associated file options. For example, the argument
3379 DATA{MyDataDir/,REGEX:.*} will pass the full path to a MyDataDir direc‐
3380 tory on the command line and ensure that the directory contains files
3381 corresponding to every file or content link in the MyDataDir source
3382 directory. In order to match associated files in subdirectories, spec‐
3383 ify a RECURSE: option, e.g. DATA{MyDataDir/,RECURSE:,REGEX:.*}.
3384 Hash Algorithms
3386 The following hash algorithms are supported:
3387 %(algo) <ext> Description
3389 ------- ----- -----------
3390 MD5 .md5 Message-Digest Algorithm 5, RFC 1321
3391 SHA1 .sha1 US Secure Hash Algorithm 1, RFC 3174
3392 SHA224 .sha224 US Secure Hash Algorithms, RFC 4634
3393 SHA256 .sha256 US Secure Hash Algorithms, RFC 4634
3394 SHA384 .sha384 US Secure Hash Algorithms, RFC 4634
3395 SHA512 .sha512 US Secure Hash Algorithms, RFC 4634
3396 SHA3_224 .sha3-224 Keccak SHA-3
3397 SHA3_256 .sha3-256 Keccak SHA-3
3398 SHA3_384 .sha3-384 Keccak SHA-3
3399 SHA3_512 .sha3-512 Keccak SHA-3
3400 Note that the hashes are used only for unique data identification and
3402 download verification.
3403 Custom Fetch Scripts
3405 When a data file must be fetched from one of the URL templates speci‐
3406 fied in the ExternalData_URL_TEMPLATES variable, it is normally down‐
3407 loaded using the file(DOWNLOAD) command. One may specify usage of a
3408 custom fetch script by using a URL template of the form ExternalData‐
3409 CustomScript://<key>/<loc>. The <key> must be a C identifier, and the
3410 <loc> must contain the %(algo) and %(hash) placeholders. A variable
3411 corresponding to the key, ExternalData_CUSTOM_SCRIPT_<key>, must be set
3412 to the full path to a .cmake script file. The script will be included
3413 to perform the actual fetch, and provided with the following variables:
3414 ExternalData_CUSTOM_LOCATION
3416 When a custom fetch script is loaded, this variable is set to
3417 the location part of the URL, which will contain the substituted
3418 hash algorithm name and content hash value.
3419 ExternalData_CUSTOM_FILE
3421 When a custom fetch script is loaded, this variable is set to
3422 the full path to a file in which the script must store the
3423 fetched content. The name of the file is unspecified and should
3424 not be interpreted in any way.
3425 The custom fetch script is expected to store fetched content in the
3427 file or set a variable:
3428 ExternalData_CUSTOM_ERROR
3430 When a custom fetch script fails to fetch the requested content,
3431 it must set this variable to a short one-line message describing
3432 the reason for failure.
3433 ExternalProject
3435 External Project Definition
3436 ExternalProject_Add
3437 The ExternalProject_Add() function creates a custom target to
3438 drive download, update/patch, configure, build, install and test
3439 steps of an external project:
3440 ExternalProject_Add(<name> [<option>...])
3442 The individual steps within the process can be driven indepen‐
3444 dently if required (e.g. for CDash submission) and extra custom
3445 steps can be defined, along with the ability to control the step
3446 dependencies. The directory structure used for the management of
3447 the external project can also be customized. The function sup‐
3448 ports a large number of options which can be used to tailor the
3449 external project behavior.
3450 Directory Options:
3452 Most of the time, the default directory layout is suffi‐
3453 cient. It is largely an implementation detail that the
3454 main project usually doesn’t need to change. In some cir‐
3455 cumstances, however, control over the directory layout
3456 can be useful or necessary. The directory options are
3457 potentially more useful from the point of view that the
3458 main build can use the ExternalProject_Get_Property()
3459 command to retrieve their values, thereby allowing the
3460 main project to refer to build artifacts of the external
3461 project.
3462 PREFIX <dir>
3464 Root directory for the external project. Unless
3465 otherwise noted below, all other directories asso‐
3466 ciated with the external project will be created
3467 under here.
3468 TMP_DIR <dir>
3470 Directory in which to store temporary files.
3471 STAMP_DIR <dir>
3473 Directory in which to store the timestamps of each
3474 step. Log files from individual steps are also
3475 created in here unless overriden by LOG_DIR (see
3476 Logging Options below).
3477 LOG_DIR <dir>
3479 Directory in which to store the logs of each step.
3480 DOWNLOAD_DIR <dir>
3482 Directory in which to store downloaded files
3483 before unpacking them. This directory is only used
3484 by the URL download method, all other download
3485 methods use SOURCE_DIR directly instead.
3486 SOURCE_DIR <dir>
3488 Source directory into which downloaded contents
3489 will be unpacked, or for non-URL download methods,
3490 the directory in which the repository should be
3491 checked out, cloned, etc. If no download method is
3492 specified, this must point to an existing direc‐
3493 tory where the external project has already been
3494 unpacked or cloned/checked out.
3495 NOTE:
3497 If a download method is specified, any existing
3498 contents of the source directory may be
3499 deleted. Only the URL download method checks
3500 whether this directory is either missing or
3501 empty before initiating the download, stopping
3502 with an error if it is not empty. All other
3503 download methods silently discard any previous
3504 contents of the source directory.
3505 BINARY_DIR <dir>
3507 Specify the build directory location. This option
3508 is ignored if BUILD_IN_SOURCE is enabled.
3509 INSTALL_DIR <dir>
3511 Installation prefix to be placed in the
3512 <INSTALL_DIR> placeholder. This does not actually
3513 configure the external project to install to the
3514 given prefix. That must be done by passing appro‐
3515 priate arguments to the external project configu‐
3516 ration step, e.g. using <INSTALL_DIR>.
3517 If any of the above ..._DIR options are not specified,
3519 their defaults are computed as follows. If the PREFIX
3520 option is given or the EP_PREFIX directory property is
3521 set, then an external project is built and installed
3522 under the specified prefix:
3523 TMP_DIR = <prefix>/tmp
3525 STAMP_DIR = <prefix>/src/<name>-stamp
3526 DOWNLOAD_DIR = <prefix>/src
3527 SOURCE_DIR = <prefix>/src/<name>
3528 BINARY_DIR = <prefix>/src/<name>-build
3529 INSTALL_DIR = <prefix>
3530 LOG_DIR = <STAMP_DIR>
3531 Otherwise, if the EP_BASE directory property is set then
3533 components of an external project are stored under the
3534 specified base:
3535 TMP_DIR = <base>/tmp/<name>
3537 STAMP_DIR = <base>/Stamp/<name>
3538 DOWNLOAD_DIR = <base>/Download/<name>
3539 SOURCE_DIR = <base>/Source/<name>
3540 BINARY_DIR = <base>/Build/<name>
3541 INSTALL_DIR = <base>/Install/<name>
3542 LOG_DIR = <STAMP_DIR>
3543 If no PREFIX, EP_PREFIX, or EP_BASE is specified, then
3545 the default is to set PREFIX to <name>-prefix. Relative
3546 paths are interpreted with respect to CMAKE_CUR‐
3547 RENT_BINARY_DIR at the point where ExternalProject_Add()
3548 is called.
3549 Download Step Options:
3551 A download method can be omitted if the SOURCE_DIR option
3552 is used to point to an existing non-empty directory. Oth‐
3553 erwise, one of the download methods below must be speci‐
3554 fied (multiple download methods should not be given) or a
3555 custom DOWNLOAD_COMMAND provided.
3556 DOWNLOAD_COMMAND <cmd>...
3558 Overrides the command used for the download step
3559 (generator expressions are supported). If this
3560 option is specified, all other download options
3561 will be ignored. Providing an empty string for
3562 <cmd> effectively disables the download step.
3563 URL Download
3565 URL <url1> [<url2>...]
3567 List of paths and/or URL(s) of the external
3568 project’s source. When more than one URL is
3569 given, they are tried in turn until one
3570 succeeds. A URL may be an ordinary path in
3571 the local file system (in which case it
3572 must be the only URL provided) or any down‐
3573 loadable URL supported by the file(DOWN‐
3574 LOAD) command. A local filesystem path may
3575 refer to either an existing directory or to
3576 an archive file, whereas a URL is expected
3577 to point to a file which can be treated as
3578 an archive. When an archive is used, it
3579 will be unpacked automatically unless the
3580 DOWNLOAD_NO_EXTRACT option is set to pre‐
3581 vent it. The archive type is determined by
3582 inspecting the actual content rather than
3583 using logic based on the file extension.
3584 URL_HASH <algo>=<hashValue>
3586 Hash of the archive file to be downloaded.
3587 The argument should be of the form
3588 <algo>=<hashValue> where algo can be any of
3589 the hashing algorithms supported by the
3590 file() command. Specifying this option is
3591 strongly recommended for URL downloads, as
3592 it ensures the integrity of the downloaded
3593 content. It is also used as a check for a
3594 previously downloaded file, allowing con‐
3595 nection to the remote location to be
3596 avoided altogether if the local directory
3597 already has a file from an earlier download
3598 that matches the specified hash.
3599 URL_MD5 <md5>
3601 Equivalent to URL_HASH MD5=<md5>.
3602 DOWNLOAD_NAME <fname>
3604 File name to use for the downloaded file.
3605 If not given, the end of the URL is used to
3606 determine the file name. This option is
3607 rarely needed, the default name is gener‐
3608 ally suitable and is not normally used out‐
3609 side of code internal to the ExternalPro‐
3610 ject module.
3611 DOWNLOAD_NO_EXTRACT <bool>
3613 Allows the extraction part of the download
3614 step to be disabled by passing a boolean
3615 true value for this option. If this option
3616 is not given, the downloaded contents will
3617 be unpacked automatically if required. If
3618 extraction has been disabled, the full path
3619 to the downloaded file is available as
3620 <DOWNLOADED_FILE> in subsequent steps or as
3621 the property DOWNLOADED_FILE with the
3622 ExternalProject_Get_Property() command.
3623 DOWNLOAD_NO_PROGRESS <bool>
3625 Can be used to disable logging the download
3626 progress. If this option is not given,
3627 download progress messages will be logged.
3628 TIMEOUT <seconds>
3630 Maximum time allowed for file download
3631 operations.
3632 HTTP_USERNAME <username>
3634 Username for the download operation if
3635 authentication is required.
3636 HTTP_PASSWORD <password>
3638 Password for the download operation if
3639 authentication is required.
3640 HTTP_HEADER <header1> [<header2>...]
3642 Provides an arbitrary list of HTTP headers
3643 for the download operation. This can be
3644 useful for accessing content in systems
3645 like AWS, etc.
3646 TLS_VERIFY <bool>
3648 Specifies whether certificate verification
3649 should be performed for https URLs. If this
3650 option is not provided, the default behav‐
3651 ior is determined by the CMAKE_TLS_VERIFY
3652 variable (see file(DOWNLOAD)). If that is
3653 also not set, certificate verification will
3654 not be performed. In situations where
3655 URL_HASH cannot be provided, this option
3656 can be an alternative verification measure.
3657 TLS_CAINFO <file>
3659 Specify a custom certificate authority file
3660 to use if TLS_VERIFY is enabled. If this
3661 option is not specified, the value of the
3662 CMAKE_TLS_CAINFO variable will be used
3663 instead (see file(DOWNLOAD))
3664 NETRC <level>
3666 Specify whether the .netrc file is to be
3667 used for operation. If this option is not
3668 specified, the value of the CMAKE_NETRC
3669 variable will be used instead (see
3670 file(DOWNLOAD)) Valid levels are:
3671 IGNORED
3673 The .netrc file is ignored. This is
3674 the default.
3675 OPTIONAL
3677 The .netrc file is optional, and
3678 information in the URL is preferred.
3679 The file will be scanned to find
3680 which ever information is not speci‐
3681 fied in the URL.
3682 REQUIRED
3684 The .netrc file is required, and
3685 information in the URL is ignored.
3686 NETRC_FILE <file>
3688 Specify an alternative .netrc file to the
3689 one in your home directory if the NETRC
3690 level is OPTIONAL or REQUIRED. If this
3691 option is not specified, the value of the
3692 CMAKE_NETRC_FILE variable will be used
3693 instead (see file(DOWNLOAD))
3694 Git NOTE: A git version of 1.6.5 or later is required
3696 if this download method is used.
3697 GIT_REPOSITORY <url>
3699 URL of the git repository. Any URL under‐
3700 stood by the git command may be used.
3701 GIT_TAG <tag>
3703 Git branch name, tag or commit hash. Note
3704 that branch names and tags should generally
3705 be specified as remote names (i.e. ori‐
3706 gin/myBranch rather than simply myBranch).
3707 This ensures that if the remote end has its
3708 tag moved or branch rebased or history
3709 rewritten, the local clone will still be
3710 updated correctly. In general, however,
3711 specifying a commit hash should be pre‐
3712 ferred for a number of reasons:
3713 · If the local clone already has the commit
3715 corresponding to the hash, no git fetch
3716 needs to be performed to check for
3717 changes each time CMake is re-run. This
3718 can result in a significant speed up if
3719 many external projects are being used.
3720 · Using a specific git hash ensures that
3722 the main project’s own history is fully
3723 traceable to a specific point in the
3724 external project’s evolution. If a branch
3725 or tag name is used instead, then check‐
3726 ing out a specific commit of the main
3727 project doesn’t necessarily pin the whole
3728 build to a specific point in the life of
3729 the external project. The lack of such
3730 deterministic behavior makes the main
3731 project lose traceability and repeatabil‐
3732 ity.
3733 GIT_REMOTE_NAME <name>
3735 The optional name of the remote. If this
3736 option is not specified, it defaults to
3737 origin.
3738 GIT_SUBMODULES <module>...
3740 Specific git submodules that should also be
3741 updated. If this option is not provided,
3742 all git submodules will be updated.
3743 GIT_SHALLOW <bool>
3745 When this option is enabled, the git clone
3746 operation will be given the --depth 1
3747 option. This performs a shallow clone,
3748 which avoids downloading the whole history
3749 and instead retrieves just the commit
3750 denoted by the GIT_TAG option.
3751 GIT_PROGRESS <bool>
3753 When enabled, this option instructs the git
3754 clone operation to report its progress by
3755 passing it the --progress option. Without
3756 this option, the clone step for large
3757 projects may appear to make the build
3758 stall, since nothing will be logged until
3759 the clone operation finishes. While this
3760 option can be used to provide progress to
3761 prevent the appearance of the build having
3762 stalled, it may also make the build overly
3763 noisy if lots of external projects are
3764 used.
3765 GIT_CONFIG <option1> [<option2>...]
3767 Specify a list of config options to pass to
3768 git clone. Each option listed will be
3769 transformed into its own --config <option>
3770 on the git clone command line, with each
3771 option required to be in the form
3772 key=value.
3773 Subversion
3775 SVN_REPOSITORY <url>
3777 URL of the Subversion repository.
3778 SVN_REVISION -r<rev>
3780 Revision to checkout from the Subversion
3781 repository.
3782 SVN_USERNAME <username>
3784 Username for the Subversion checkout and
3785 update.
3786 SVN_PASSWORD <password>
3788 Password for the Subversion checkout and
3789 update.
3790 SVN_TRUST_CERT <bool>
3792 Specifies whether to trust the Subversion
3793 server site certificate. If enabled, the
3794 --trust-server-cert option is passed to the
3795 svn checkout and update commands.
3796 Mercurial
3798 HG_REPOSITORY <url>
3800 URL of the mercurial repository.
3801 HG_TAG <tag>
3803 Mercurial branch name, tag or commit id.
3804 CVS
3806 CVS_REPOSITORY <cvsroot>
3808 CVSROOT of the CVS repository.
3809 CVS_MODULE <mod>
3811 Module to checkout from the CVS repository.
3812 CVS_TAG <tag>
3814 Tag to checkout from the CVS repository.
3815 Update/Patch Step Options:
3817 Whenever CMake is re-run, by default the external
3818 project’s sources will be updated if the download method
3819 supports updates (e.g. a git repository would be checked
3820 if the GIT_TAG does not refer to a specific commit).
3821 UPDATE_COMMAND <cmd>...
3823 Overrides the download method’s update step with a
3824 custom command. The command may use generator
3825 expressions.
3826 UPDATE_DISCONNECTED <bool>
3828 When enabled, this option causes the update step
3829 to be skipped. It does not, however, prevent the
3830 download step. The update step can still be added
3831 as a step target (see
3832 ExternalProject_Add_StepTargets()) and called man‐
3833 ually. This is useful if you want to allow devel‐
3834 opers to build the project when disconnected from
3835 the network (the network may still be needed for
3836 the download step though).
3837 When this option is present, it is generally
3839 advisable to make the value a cache variable under
3840 the developer’s control rather than hard-coding
3841 it. If this option is not present, the default
3842 value is taken from the EP_UPDATE_DISCONNECTED
3843 directory property. If that is also not defined,
3844 updates are performed as normal. The
3845 EP_UPDATE_DISCONNECTED directory property is
3846 intended as a convenience for controlling the
3847 UPDATE_DISCONNECTED behavior for an entire section
3848 of a project’s directory hierarchy and may be a
3849 more convenient method of giving developers con‐
3850 trol over whether or not to perform updates
3851 (assuming the project also provides a cache vari‐
3852 able or some other convenient method for setting
3853 the directory property).
3854 PATCH_COMMAND <cmd>...
3856 Specifies a custom command to patch the sources
3857 after an update. By default, no patch command is
3858 defined. Note that it can be quite difficult to
3859 define an appropriate patch command that performs
3860 robustly, especially for download methods such as
3861 git where changing the GIT_TAG will not discard
3862 changes from a previous patch, but the patch com‐
3863 mand will be called again after updating to the
3864 new tag.
3865 Configure Step Options:
3867 The configure step is run after the download and update
3868 steps. By default, the external project is assumed to be
3869 a CMake project, but this can be overridden if required.
3870 CONFIGURE_COMMAND <cmd>...
3872 The default configure command runs CMake with
3873 options based on the main project. For non-CMake
3874 external projects, the CONFIGURE_COMMAND option
3875 must be used to override this behavior (generator
3876 expressions are supported). For projects that
3877 require no configure step, specify this option
3878 with an empty string as the command to execute.
3879 CMAKE_COMMAND /.../cmake
3881 Specify an alternative cmake executable for the
3882 configure step (use an absolute path). This is
3883 generally not recommended, since it is usually
3884 desirable to use the same CMake version throughout
3885 the whole build. This option is ignored if a cus‐
3886 tom configure command has been specified with CON‐
3887 FIGURE_COMMAND.
3888 CMAKE_GENERATOR <gen>
3890 Override the CMake generator used for the config‐
3891 ure step. Without this option, the same generator
3892 as the main build will be used. This option is
3893 ignored if a custom configure command has been
3894 specified with the CONFIGURE_COMMAND option.
3895 CMAKE_GENERATOR_PLATFORM <platform>
3897 Pass a generator-specific platform name to the
3898 CMake command (see CMAKE_GENERATOR_PLATFORM). It
3899 is an error to provide this option without the
3900 CMAKE_GENERATOR option.
3901 CMAKE_GENERATOR_TOOLSET <toolset>
3903 Pass a generator-specific toolset name to the
3904 CMake command (see CMAKE_GENERATOR_TOOLSET). It is
3905 an error to provide this option without the
3906 CMAKE_GENERATOR option.
3907 CMAKE_GENERATOR_INSTANCE <instance>
3909 Pass a generator-specific instance selection to
3910 the CMake command (see CMAKE_GENERATOR_INSTANCE).
3911 It is an error to provide this option without the
3912 CMAKE_GENERATOR option.
3913 CMAKE_ARGS <arg>...
3915 The specified arguments are passed to the cmake
3916 command line. They can be any argument the cmake
3917 command understands, not just cache values defined
3918 by -D... arguments (see also CMake Options). In
3919 addition, arguments may use generator expressions.
3920 CMAKE_CACHE_ARGS <arg>...
3922 This is an alternate way of specifying cache vari‐
3923 ables where command line length issues may become
3924 a problem. The arguments are expected to be in the
3925 form -Dvar:STRING=value, which are then trans‐
3926 formed into CMake set() commands with the FORCE
3927 option used. These set() commands are written to a
3928 pre-load script which is then applied using the
3929 cmake -C command line option. Arguments may use
3930 generator expressions.
3931 CMAKE_CACHE_DEFAULT_ARGS <arg>...
3933 This is the same as the CMAKE_CACHE_ARGS option
3934 except the set() commands do not include the FORCE
3935 keyword. This means the values act as initial
3936 defaults only and will not override any variables
3937 already set from a previous run. Use this option
3938 with care, as it can lead to different behavior
3939 depending on whether the build starts from a fresh
3940 build directory or re-uses previous build con‐
3941 tents.
3942 SOURCE_SUBDIR <dir>
3944 When no CONFIGURE_COMMAND option is specified, the
3945 configure step assumes the external project has a
3946 CMakeLists.txt file at the top of its source tree
3947 (i.e. in SOURCE_DIR). The SOURCE_SUBDIR option can
3948 be used to point to an alternative directory
3949 within the source tree to use as the top of the
3950 CMake source tree instead. This must be a relative
3951 path and it will be interpreted as being relative
3952 to SOURCE_DIR. When BUILD_IN_SOURCE 1 is speci‐
3953 fied, the BUILD_COMMAND is used to point to an
3954 alternative directory within the source tree.
3955 Build Step Options:
3957 If the configure step assumed the external project uses
3958 CMake as its build system, the build step will also. Oth‐
3959 erwise, the build step will assume a Makefile-based build
3960 and simply run make with no arguments as the default
3961 build step. This can be overridden with custom build com‐
3962 mands if required.
3963 BUILD_COMMAND <cmd>...
3965 Overrides the default build command (generator
3966 expressions are supported). If this option is not
3967 given, the default build command will be chosen to
3968 integrate with the main build in the most appro‐
3969 priate way (e.g. using recursive make for Makefile
3970 generators or cmake --build if the project uses a
3971 CMake build). This option can be specified with an
3972 empty string as the command to make the build step
3973 do nothing.
3974 BUILD_IN_SOURCE <bool>
3976 When this option is enabled, the build will be
3977 done directly within the external project’s source
3978 tree. This should generally be avoided, the use of
3979 a separate build directory is usually preferred,
3980 but it can be useful when the external project
3981 assumes an in-source build. The BINARY_DIR option
3982 should not be specified if building in-source.
3983 BUILD_ALWAYS <bool>
3985 Enabling this option forces the build step to
3986 always be run. This can be the easiest way to
3987 robustly ensure that the external project’s own
3988 build dependencies are evaluated rather than rely‐
3989 ing on the default success timestamp-based method.
3990 This option is not normally needed unless develop‐
3991 ers are expected to modify something the external
3992 project’s build depends on in a way that is not
3993 detectable via the step target dependencies (e.g.
3994 SOURCE_DIR is used without a download method and
3995 developers might modify the sources in
3996 SOURCE_DIR).
3997 BUILD_BYPRODUCTS <file>...
3999 Specifies files that will be generated by the
4000 build command but which might or might not have
4001 their modification time updated by subsequent
4002 builds. These ultimately get passed through as
4003 BYPRODUCTS to the build step’s own underlying call
4004 to add_custom_command().
4005 Install Step Options:
4007 If the configure step assumed the external project uses
4008 CMake as its build system, the install step will also.
4009 Otherwise, the install step will assume a Makefile-based
4010 build and simply run make install as the default build
4011 step. This can be overridden with custom install commands
4012 if required.
4013 INSTALL_COMMAND <cmd>...
4015 The external project’s own install step is invoked
4016 as part of the main project’s build. It is done
4017 after the external project’s build step and may be
4018 before or after the external project’s test step
4019 (see the TEST_BEFORE_INSTALL option below). The
4020 external project’s install rules are not part of
4021 the main project’s install rules, so if anything
4022 from the external project should be installed as
4023 part of the main build, these need to be specified
4024 in the main build as additional install() com‐
4025 mands. The default install step builds the install
4026 target of the external project, but this can be
4027 overridden with a custom command using this option
4028 (generator expressions are supported). Passing an
4029 empty string as the <cmd> makes the install step
4030 do nothing.
4031 Test Step Options:
4033 The test step is only defined if at least one of the fol‐
4034 lowing TEST_... options are provided.
4035 TEST_COMMAND <cmd>...
4037 Overrides the default test command (generator
4038 expressions are supported). If this option is not
4039 given, the default behavior of the test step is to
4040 build the external project’s own test target. This
4041 option can be specified with <cmd> as an empty
4042 string, which allows the test step to still be
4043 defined, but it will do nothing. Do not specify
4044 any of the other TEST_... options if providing an
4045 empty string as the test command, but prefer to
4046 omit all TEST_... options altogether if the test
4047 step target is not needed.
4048 TEST_BEFORE_INSTALL <bool>
4050 When this option is enabled, the test step will be
4051 executed before the install step. The default
4052 behavior is for the test step to run after the
4053 install step.
4054 TEST_AFTER_INSTALL <bool>
4056 This option is mainly useful as a way to indicate
4057 that the test step is desired but all default
4058 behavior is sufficient. Specifying this option
4059 with a boolean true value ensures the test step is
4060 defined and that it comes after the install step.
4061 If both TEST_BEFORE_INSTALL and TEST_AFTER_INSTALL
4062 are enabled, the latter is silently ignored.
4063 TEST_EXCLUDE_FROM_MAIN <bool>
4065 If enabled, the main build’s default ALL target
4066 will not depend on the test step. This can be a
4067 useful way of ensuring the test step is defined
4068 but only gets invoked when manually requested.
4069 Output Logging Options:
4071 Each of the following LOG_... options can be used to wrap
4072 the relevant step in a script to capture its output to
4073 files. The log files will be created in LOG_DIR if sup‐
4074 plied or otherwise the STAMP_DIR directory with step-spe‐
4075 cific file names.
4076 LOG_DOWNLOAD <bool>
4078 When enabled, the output of the download step is
4079 logged to files.
4080 LOG_UPDATE <bool>
4082 When enabled, the output of the update step is
4083 logged to files.
4084 LOG_PATCH <bool>
4086 When enabled, the output of the patch step is
4087 logged to files.
4088 LOG_CONFIGURE <bool>
4090 When enabled, the output of the configure step is
4091 logged to files.
4092 LOG_BUILD <bool>
4094 When enabled, the output of the build step is
4095 logged to files.
4096 LOG_INSTALL <bool>
4098 When enabled, the output of the install step is
4099 logged to files.
4100 LOG_TEST <bool>
4102 When enabled, the output of the test step is
4103 logged to files.
4104 LOG_MERGED_STDOUTERR <bool>
4106 When enabled, stdout and stderr will be merged for
4107 any step whose output is being logged to files.
4108 LOG_OUTPUT_ON_FAILURE <bool>
4110 This option only has an effect if at least one of
4111 the other LOG_<step> options is enabled. If an
4112 error occurs for a step which has logging to file
4113 enabled, that step’s output will be printed to the
4114 console if LOG_OUTPUT_ON_FAILURE is set to true.
4115 For cases where a large amount of output is
4116 recorded, just the end of that output may be
4117 printed to the console.
4118 Terminal Access Options:
4120 Steps can be given direct access to the terminal in some
4121 cases. Giving a step access to the terminal may allow it
4122 to receive terminal input if required, such as for
4123 authentication details not provided by other options.
4124 With the Ninja generator, these options place the steps
4125 in the console job pool. Each step can be given access to
4126 the terminal individually via the following options:
4127 USES_TERMINAL_DOWNLOAD <bool>
4129 Give the download step access to the terminal.
4130 USES_TERMINAL_UPDATE <bool>
4132 Give the update step access to the terminal.
4133 USES_TERMINAL_CONFIGURE <bool>
4135 Give the configure step access to the terminal.
4136 USES_TERMINAL_BUILD <bool>
4138 Give the build step access to the terminal.
4139 USES_TERMINAL_INSTALL <bool>
4141 Give the install step access to the terminal.
4142 USES_TERMINAL_TEST <bool>
4144 Give the test step access to the terminal.
4145 Target Options:
4147 DEPENDS <targets>...
4149 Specify other targets on which the external
4150 project depends. The other targets will be brought
4151 up to date before any of the external project’s
4152 steps are executed. Because the external project
4153 uses additional custom targets internally for each
4154 step, the DEPENDS option is the most convenient
4155 way to ensure all of those steps depend on the
4156 other targets. Simply doing add_dependen‐
4157 cies(<name> <targets>) will not make any of the
4158 steps dependent on <targets>.
4159 EXCLUDE_FROM_ALL <bool>
4161 When enabled, this option excludes the external
4162 project from the default ALL target of the main
4163 build.
4164 STEP_TARGETS <step-target>...
4166 Generate custom targets for the specified steps.
4167 This is required if the steps need to be triggered
4168 manually or if they need to be used as dependen‐
4169 cies of other targets. If this option is not spec‐
4170 ified, the default value is taken from the
4171 EP_STEP_TARGETS directory property. See
4172 ExternalProject_Add_Step() below for further dis‐
4173 cussion of the effects of this option.
4174 INDEPENDENT_STEP_TARGETS <step-target>...
4176 Generate custom targets for the specified steps
4177 and prevent these targets from having the usual
4178 dependencies applied to them. If this option is
4179 not specified, the default value is taken from the
4180 EP_INDEPENDENT_STEP_TARGETS directory property.
4181 This option is mostly useful for allowing individ‐
4182 ual steps to be driven independently, such as for
4183 a CDash setup where each step should be initiated
4184 and reported individually rather than as one whole
4185 build. See ExternalProject_Add_Step() below for
4186 further discussion of the effects of this option.
4187 Miscellaneous Options:
4189 LIST_SEPARATOR <sep>
4191 For any of the various ..._COMMAND options,
4192 replace ; with <sep> in the specified command
4193 lines. This can be useful where list variables may
4194 be given in commands where they should end up as
4195 space-separated arguments (<sep> would be a single
4196 space character string in this case).
4197 COMMAND <cmd>...
4199 Any of the other ..._COMMAND options can have
4200 additional commands appended to them by following
4201 them with as many COMMAND ... options as needed
4202 (generator expressions are supported). For exam‐
4203 ple:
4204 ExternalProject_Add(example
4206 ... # Download options, etc.
4207 BUILD_COMMAND ${CMAKE_COMMAND} -E echo "Starting $<CONFIG> build"
4208 COMMAND ${CMAKE_COMMAND} --build <BINARY_DIR> --config $<CONFIG>
4209 COMMAND ${CMAKE_COMMAND} -E echo "$<CONFIG> build complete"
4210 )
4211 It should also be noted that each build step is created via a
4213 call to ExternalProject_Add_Step(). See that command’s documen‐
4214 tation for the automatic substitutions that are supported for
4215 some options.
4216 Obtaining Project Properties
4218 ExternalProject_Get_Property
4219 The ExternalProject_Get_Property() function retrieves external
4220 project target properties:
4221 ExternalProject_Get_Property(<name> <prop1> [<prop2>...])
4223 The function stores property values in variables of the same
4225 name. Property names correspond to the keyword argument names of
4226 ExternalProject_Add(). For example, the source directory might
4227 be retrieved like so:
4228 ExternalProject_Get_property(myExtProj SOURCE_DIR)
4230 message("Source dir of myExtProj = ${SOURCE_DIR}")
4231 Explicit Step Management
4233 The ExternalProject_Add() function on its own is often sufficient for
4234 incorporating an external project into the main build. Certain scenar‐
4235 ios require additional work to implement desired behavior, such as
4236 adding in a custom step or making steps available as manually trigger‐
4237 able targets. The ExternalProject_Add_Step(), ExternalProject_Add_Step‐
4238 Targets() and ExternalProject_Add_StepDependencies functions provide
4239 the lower level control needed to implement such step-level capabili‐
4240 ties.
4241 ExternalProject_Add_Step
4243 The ExternalProject_Add_Step() function specifies an additional
4244 custom step for an external project defined by an earlier call
4245 to ExternalProject_Add():
4246 ExternalProject_Add_Step(<name> <step> [<option>...])
4248 <name> is the same as the name passed to the original call to
4250 ExternalProject_Add(). The specified <step> must not be one of
4251 the pre-defined steps (mkdir, download, update, skip-update,
4252 patch, configure, build, install or test). The supported options
4253 are:
4254 COMMAND <cmd>...
4256 The command line to be executed by this custom step (gen‐
4257 erator expressions are supported). This option can be
4258 repeated multiple times to specify multiple commands to
4259 be executed in order.
4260 COMMENT <text>...
4262 Text to be printed when the custom step executes.
4263 DEPENDEES <step>...
4265 Other steps (custom or pre-defined) on which this step
4266 depends.
4267 DEPENDERS <step>...
4269 Other steps (custom or pre-defined) that depend on this
4270 new custom step.
4271 DEPENDS <file>...
4273 Files on which this custom step depends.
4274 BYPRODUCTS <file>...
4276 Files that will be generated by this custom step but
4277 which might or might not have their modification time
4278 updated by subsequent builds. This list of files will
4279 ultimately be passed through as the BYPRODUCTS option to
4280 the add_custom_command() used to implement the custom
4281 step internally.
4282 ALWAYS <bool>
4284 When enabled, this option specifies that the custom step
4285 should always be run (i.e. that it is always considered
4286 out of date).
4287 EXCLUDE_FROM_MAIN <bool>
4289 When enabled, this option specifies that the external
4290 project’s main target does not depend on the custom step.
4291 WORKING_DIRECTORY <dir>
4293 Specifies the working directory to set before running the
4294 custom step’s command. If this option is not specified,
4295 the directory will be the value of the CMAKE_CUR‐
4296 RENT_BINARY_DIR at the point where ExternalPro‐
4297 ject_Add_Step() was called.
4298 LOG <bool>
4300 If set, this causes the output from the custom step to be
4301 captured to files in the external project’s LOG_DIR if
4302 supplied or STAMP_DIR.
4303 USES_TERMINAL <bool>
4305 If enabled, this gives the custom step direct access to
4306 the terminal if possible.
4307 The command line, comment, working directory and byproducts of
4309 every standard and custom step are processed to replace the
4310 tokens <SOURCE_DIR>, <SOURCE_SUBDIR>, <BINARY_DIR>,
4311 <INSTALL_DIR> <TMP_DIR>, <DOWNLOAD_DIR> and <DOWNLOADED_FILE>
4312 with their corresponding property values defined in the original
4313 call to ExternalProject_Add().
4314 ExternalProject_Add_StepTargets
4316 The ExternalProject_Add_StepTargets() function generates targets
4317 for the steps listed. The name of each created target will be of
4318 the form <name>-<step>:
4319 ExternalProject_Add_StepTargets(<name> [NO_DEPENDS] <step1> [<step2>...])
4321 Creating a target for a step allows it to be used as a depen‐
4323 dency of another target or to be triggered manually. Having tar‐
4324 gets for specific steps also allows them to be driven indepen‐
4325 dently of each other by specifying targets on build command
4326 lines. For example, you may be submitting to a sub-project based
4327 dashboard where you want to drive the configure portion of the
4328 build, then submit to the dashboard, followed by the build por‐
4329 tion, followed by tests. If you invoke a custom target that
4330 depends on a step halfway through the step dependency chain,
4331 then all the previous steps will also run to ensure everything
4332 is up to date.
4333 If the NO_DEPENDS option is specified, the step target will not
4335 depend on the dependencies of the external project (i.e. on any
4336 dependencies of the <name> custom target created by
4337 ExternalProject_Add()). This is usually safe for the download,
4338 update and patch steps, since they do not typically require that
4339 the dependencies are updated and built. Using NO_DEPENDS for any
4340 of the other pre-defined steps, however, may break parallel
4341 builds. Only use NO_DEPENDS where it is certain that the named
4342 steps genuinely do not have dependencies. For custom steps, con‐
4343 sider whether or not the custom commands require the dependen‐
4344 cies to be configured, built and installed.
4345 Internally, ExternalProject_Add() calls
4347 ExternalProject_Add_Step() to create each step. If any STEP_TAR‐
4348 GETS or INDEPENDENT_STEP_TARGETS were specified, then External‐
4349 Project_Add_StepTargets() will also be called after
4350 ExternalProject_Add_Step(). INDEPENDENT_STEP_TARGETS have the
4351 NO_DEPENDS option set, whereas STEP_TARGETS do not. Other than
4352 that, the two options result in ExternalProject_Add_StepTar‐
4353 gets() being called in the same way. Even if a step is not men‐
4354 tioned in either of those two options, ExternalProject_Add_Step‐
4355 Targets() can still be called later to manually define a target
4356 for the step.
4357 The STEP_TARGETS and INDEPENDENT_STEP_TARGETS options for
4359 ExternalProject_Add() are generally the easiest way to ensure
4360 targets are created for specific steps of interest. For custom
4361 steps, ExternalProject_Add_StepTargets() must be called explic‐
4362 itly if a target should also be created for that custom step. An
4363 alternative to these two options is to populate the EP_STEP_TAR‐
4364 GETS and EP_INDEPENDENT_STEP_TARGETS directory properties. These
4365 act as defaults for the step target options and can save having
4366 to repeatedly specify the same set of step targets when multiple
4367 external projects are being defined.
4368 ExternalProject_Add_StepDependencies
4370 The ExternalProject_Add_StepDependencies() function can be used
4371 to add dependencies to a step. The dependencies added must be
4372 targets CMake already knows about (these can be ordinary exe‐
4373 cutable or library targets, custom targets or even step targets
4374 of another external project):
4375 ExternalProject_Add_StepDependencies(<name> <step> <target1> [<target2>...])
4377 This function takes care to set both target and file level
4379 dependencies and will ensure that parallel builds will not
4380 break. It should be used instead of add_dependencies() whenever
4381 adding a dependency for some of the step targets generated by
4382 the ExternalProject module.
4383 Examples
4385 The following example shows how to download and build a hypothetical
4386 project called FooBar from github:
4387 include(ExternalProject)
4389 ExternalProject_Add(foobar
4390 GIT_REPOSITORY git@github.com:FooCo/FooBar.git
4391 GIT_TAG origin/release/1.2.3
4392 )
4393 For the sake of the example, also define a second hypothetical external
4395 project called SecretSauce, which is downloaded from a web server. Two
4396 URLs are given to take advantage of a faster internal network if avail‐
4397 able, with a fallback to a slower external server. The project is a
4398 typical Makefile project with no configure step, so some of the default
4399 commands are overridden. The build is only required to build the sauce
4400 target:
4401 find_program(MAKE_EXE NAMES gmake nmake make)
4403 ExternalProject_Add(secretsauce
4404 URL http://intranet.somecompany.com/artifacts/sauce-2.7.tgz
4405 https://www.somecompany.com/downloads/sauce-2.7.zip
4406 URL_HASH MD5=d41d8cd98f00b204e9800998ecf8427e
4407 CONFIGURE_COMMAND ""
4408 BUILD_COMMAND ${MAKE_EXE} sauce
4409 )
4410 Suppose the build step of secretsauce requires that foobar must already
4412 be built. This could be enforced like so:
4413 ExternalProject_Add_StepDependencies(secretsauce build foobar)
4415 Another alternative would be to create a custom target for foobar’s
4417 build step and make secretsauce depend on that rather than the whole
4418 foobar project. This would mean foobar only needs to be built, it
4419 doesn’t need to run its install or test steps before secretsauce can be
4420 built. The dependency can also be defined along with the secretsauce
4421 project:
4422 ExternalProject_Add_StepTargets(foobar build)
4424 ExternalProject_Add(secretsauce
4425 URL http://intranet.somecompany.com/artifacts/sauce-2.7.tgz
4426 https://www.somecompany.com/downloads/sauce-2.7.zip
4427 URL_HASH MD5=d41d8cd98f00b204e9800998ecf8427e
4428 CONFIGURE_COMMAND ""
4429 BUILD_COMMAND ${MAKE_EXE} sauce
4430 DEPENDS foobar-build
4431 )
4432 Instead of calling ExternalProject_Add_StepTargets(), the target could
4434 be defined along with the foobar project itself:
4435 ExternalProject_Add(foobar
4437 GIT_REPOSITORY git@github.com:FooCo/FooBar.git
4438 GIT_TAG origin/release/1.2.3
4439 STEP_TARGETS build
4440 )
4441 If many external projects should have the same set of step targets,
4443 setting a directory property may be more convenient. The build step
4444 target could be created automatically by setting the EP_STEP_TARGETS
4445 directory property before creating the external projects with
4446 ExternalProject_Add():
4447 set_property(DIRECTORY PROPERTY EP_STEP_TARGETS build)
4449 Lastly, suppose that secretsauce provides a script called makedoc which
4451 can be used to generate its own documentation. Further suppose that the
4452 script expects the output directory to be provided as the only parame‐
4453 ter and that it should be run from the secretsauce source directory. A
4454 custom step and a custom target to trigger the script can be defined
4455 like so:
4456 ExternalProject_Add_Step(secretsauce docs
4458 COMMAND <SOURCE_DIR>/makedoc <BINARY_DIR>
4459 WORKING_DIRECTORY <SOURCE_DIR>
4460 COMMENT "Building secretsauce docs"
4461 ALWAYS TRUE
4462 EXCLUDE_FROM_MAIN TRUE
4463 )
4464 ExternalProject_Add_StepTargets(secretsauce docs)
4465 The custom step could then be triggered from the main build like so:
4467 cmake --build . --target secretsauce-docs
4469 FeatureSummary
4471 Functions for generating a summary of enabled/disabled features.
4472 These functions can be used to generate a summary of enabled and dis‐
4474 abled packages and/or feature for a build tree such as:
4475 -- The following OPTIONAL packages have been found:
4477 LibXml2 (required version >= 2.4), XML processing lib, <http://xmlsoft.org>
4478 * Enables HTML-import in MyWordProcessor
4479 * Enables odt-export in MyWordProcessor
4480 PNG, A PNG image library., <http://www.libpng.org/pub/png/>
4481 * Enables saving screenshots
4482 -- The following OPTIONAL packages have not been found:
4483 Lua51, The Lua scripting language., <http://www.lua.org>
4484 * Enables macros in MyWordProcessor
4485 Foo, Foo provides cool stuff.
4486 Global Properties
4488 FeatureSummary_PKG_TYPES
4489 The global property FeatureSummary_PKG_TYPES defines the type of pack‐
4491 ages used by FeatureSummary.
4492 The order in this list is important, the first package type in the list
4494 is the least important, the last is the most important. the of a pack‐
4495 age can only be changed to higher types.
4496 The default package types are , RUNTIME, OPTIONAL, RECOMMENDED and
4498 REQUIRED, and their importance is RUNTIME < OPTIONAL < RECOMMENDED <
4499 REQUIRED.
4500 FeatureSummary_REQUIRED_PKG_TYPES
4502 The global property FeatureSummary_REQUIRED_PKG_TYPES defines which
4504 package types are required.
4505 If one or more package in this categories has not been found, CMake
4507 will abort when calling feature_summary() with the ‘FATAL_ON_MISS‐
4508 ING_REQUIRED_PACKAGES’ option enabled.
4509 The default value for this global property is REQUIRED.
4511 FeatureSummary_DEFAULT_PKG_TYPE
4513 The global property FeatureSummary_DEFAULT_PKG_TYPE defines which pack‐
4515 age type is the default one. When calling feature_summary(), if the
4516 user did not set the package type explicitly, the package will be
4517 assigned to this category.
4518 This value must be one of the types defined in the
4520 FeatureSummary_PKG_TYPES global property unless the package type is set
4521 for all the packages.
4522 The default value for this global property is OPTIONAL.
4524 FeatureSummary_<TYPE>_DESCRIPTION
4526 The global property FeatureSummary_<TYPE>_DESCRIPTION can be defined
4528 for each type to replace the type name with the specified string when‐
4529 ever the package type is used in an output string.
4530 If not set, the string “<TYPE> packages” is used.
4532 Functions
4534 feature_summary
4535 feature_summary( [FILENAME <file>]
4537 [APPEND]
4538 [VAR <variable_name>]
4539 [INCLUDE_QUIET_PACKAGES]
4540 [FATAL_ON_MISSING_REQUIRED_PACKAGES]
4541 [DESCRIPTION "<description>" | DEFAULT_DESCRIPTION]
4542 [QUIET_ON_EMPTY]
4543 WHAT (ALL
4544 | PACKAGES_FOUND | PACKAGES_NOT_FOUND
4545 | <TYPE>_PACKAGES_FOUND | <TYPE>_PACKAGES_NOT_FOUND
4546 | ENABLED_FEATURES | DISABLED_FEATURES)
4547 )
4548 The feature_summary() macro can be used to print information
4550 about enabled or disabled packages or features of a project. By
4551 default, only the names of the features/packages will be printed
4552 and their required version when one was specified. Use
4553 set_package_properties() to add more useful information, like
4554 e.g. a download URL for the respective package or their purpose
4555 in the project.
4556 The WHAT option is the only mandatory option. Here you specify
4558 what information will be printed:
4559 ALL print everything
4561 ENABLED_FEATURES
4563 the list of all features which are enabled
4564 DISABLED_FEATURES
4566 the list of all features which are disabled
4567 PACKAGES_FOUND
4569 the list of all packages which have been found
4570 PACKAGES_NOT_FOUND
4572 the list of all packages which have not been found
4573 For each package type <TYPE> defined by the
4575 FeatureSummary_PKG_TYPES global property, the following informa‐
4576 tion can also be used:
4577 <TYPE>_PACKAGES_FOUND
4579 only those packages which have been found which have the
4580 type <TYPE>
4581 <TYPE>_PACKAGES_NOT_FOUND
4583 only those packages which have not been found which have
4584 the type <TYPE>
4585 With the exception of the ALL value, these values can be com‐
4587 bined in order to customize the output. For example:
4588 feature_summary(WHAT ENABLED_FEATURES DISABLED_FEATURES)
4590 If a FILENAME is given, the information is printed into this
4592 file. If APPEND is used, it is appended to this file, otherwise
4593 the file is overwritten if it already existed. If the VAR
4594 option is used, the information is “printed” into the specified
4595 variable. If FILENAME is not used, the information is printed
4596 to the terminal. Using the DESCRIPTION option a description or
4597 headline can be set which will be printed above the actual con‐
4598 tent. If only one type of package was requested, no title is
4599 printed, unless it is explicitly set using either DESCRIPTION to
4600 use a custom string, or DEFAULT_DESCRIPTION to use a default
4601 title for the requested type. If INCLUDE_QUIET_PACKAGES is
4602 given, packages which have been searched with find_package(...
4603 QUIET) will also be listed. By default they are skipped. If
4604 FATAL_ON_MISSING_REQUIRED_PACKAGES is given, CMake will abort if
4605 a package which is marked as one of the package types listed in
4606 the FeatureSummary_REQUIRED_PKG_TYPES global property has not
4607 been found. The default value for the
4608 FeatureSummary_REQUIRED_PKG_TYPES global property is REQUIRED.
4609 The FeatureSummary_DEFAULT_PKG_TYPE global property can be modi‐
4611 fied to change the default package type assigned when not
4612 explicitly assigned by the user.
4613 If the QUIET_ON_EMPTY option is used, if only one type of pack‐
4615 age was requested, and no packages belonging to that category
4616 were found, then no output (including the DESCRIPTION) is
4617 printed or added to the VAR variable.
4618 Example 1, append everything to a file:
4620 include(FeatureSummary)
4622 feature_summary(WHAT ALL
4623 FILENAME ${CMAKE_BINARY_DIR}/all.log APPEND)
4624 Example 2, print the enabled features into the variable enabled‐
4626 FeaturesText, including QUIET packages:
4627 include(FeatureSummary)
4629 feature_summary(WHAT ENABLED_FEATURES
4630 INCLUDE_QUIET_PACKAGES
4631 DESCRIPTION "Enabled Features:"
4632 VAR enabledFeaturesText)
4633 message(STATUS "${enabledFeaturesText}")
4634 Example 3, change default package types and print only the cate‐
4636 gories that are not empty:
4637 include(FeatureSummary)
4639 set_property(GLOBAL APPEND PROPERTY FeatureSummary_PKG_TYPES BUILD)
4640 find_package(FOO)
4641 set_package_properties(FOO PROPERTIES TYPE BUILD)
4642 feature_summary(WHAT BUILD_PACKAGES_FOUND
4643 Description "Build tools found:"
4644 QUIET_ON_EMPTY)
4645 feature_summary(WHAT BUILD_PACKAGES_NOT_FOUND
4646 Description "Build tools not found:"
4647 QUIET_ON_EMPTY)
4648 set_package_properties
4650 set_package_properties(<name> PROPERTIES
4652 [ URL <url> ]
4653 [ DESCRIPTION <description> ]
4654 [ TYPE (RUNTIME|OPTIONAL|RECOMMENDED|REQUIRED) ]
4655 [ PURPOSE <purpose> ]
4656 )
4657 Use this macro to set up information about the named package,
4659 which can then be displayed via FEATURE_SUMMARY(). This can be
4660 done either directly in the Find-module or in the project which
4661 uses the module after the find_package() call. The features for
4662 which information can be set are added automatically by the
4663 find_package() command.
4664 URL <url>
4666 This should be the homepage of the package, or something
4667 similar. Ideally this is set already directly in the
4668 Find-module.
4669 DESCRIPTION <description>
4671 A short description what that package is, at most one
4672 sentence. Ideally this is set already directly in the
4673 Find-module.
4674 TYPE <type>
4676 What type of dependency has the using project on that
4677 package. Default is OPTIONAL. In this case it is a
4678 package which can be used by the project when available
4679 at buildtime, but it also work without. RECOMMENDED is
4680 similar to OPTIONAL, i.e. the project will build if the
4681 package is not present, but the functionality of the
4682 resulting binaries will be severely limited. If a
4683 REQUIRED package is not available at buildtime, the
4684 project may not even build. This can be combined with
4685 the FATAL_ON_MISSING_REQUIRED_PACKAGES argument for fea‐
4686 ture_summary(). Last, a RUNTIME package is a package
4687 which is actually not used at all during the build, but
4688 which is required for actually running the resulting
4689 binaries. So if such a package is missing, the project
4690 can still be built, but it may not work later on. If
4691 set_package_properties() is called multiple times for the
4692 same package with different TYPEs, the TYPE is only
4693 changed to higher TYPEs (RUNTIME < OPTIONAL < RECOMMENDED
4694 < REQUIRED), lower TYPEs are ignored. The TYPE property
4695 is project-specific, so it cannot be set by the Find-mod‐
4696 ule, but must be set in the project. Type accepted can
4697 be changed by setting the FeatureSummary_PKG_TYPES global
4698 property.
4699 PURPOSE <purpose>
4701 This describes which features this package enables in the
4702 project, i.e. it tells the user what functionality he
4703 gets in the resulting binaries. If set_package_proper‐
4704 ties() is called multiple times for a package, all PUR‐
4705 POSE properties are appended to a list of purposes of the
4706 package in the project. As the TYPE property, also the
4707 PURPOSE property is project-specific, so it cannot be set
4708 by the Find-module, but must be set in the project.
4709 Example for setting the info for a package:
4711 find_package(LibXml2)
4713 set_package_properties(LibXml2 PROPERTIES
4714 DESCRIPTION "A XML processing library."
4715 URL "http://xmlsoft.org/")
4716 # or
4717 set_package_properties(LibXml2 PROPERTIES
4718 TYPE RECOMMENDED
4719 PURPOSE "Enables HTML-import in MyWordProcessor")
4720 # or
4721 set_package_properties(LibXml2 PROPERTIES
4722 TYPE OPTIONAL
4723 PURPOSE "Enables odt-export in MyWordProcessor")
4724 find_package(DBUS)
4726 set_package_properties(DBUS PROPERTIES
4727 TYPE RUNTIME
4728 PURPOSE "Necessary to disable the screensaver during a presentation")
4729 add_feature_info
4731 add_feature_info(<name> <enabled> <description>)
4733 Use this macro to add information about a feature with the given
4735 <name>. <enabled> contains whether this feature is enabled or
4736 not. It can be a variable or a list of conditions. <descrip‐
4737 tion> is a text describing the feature. The information can be
4738 displayed using feature_summary() for ENABLED_FEATURES and DIS‐
4739 ABLED_FEATURES respectively.
4740 Example for setting the info for a feature:
4742 option(WITH_FOO "Help for foo" ON)
4744 add_feature_info(Foo WITH_FOO "The Foo feature provides very cool stuff.")
4745 Legacy Macros
4747 The following macros are provided for compatibility with previous CMake
4748 versions:
4749 set_package_info
4751 set_package_info(<name> <description> [ <url> [<purpose>] ])
4753 Use this macro to set up information about the named package,
4755 which can then be displayed via feature_summary(). This can be
4756 done either directly in the Find-module or in the project which
4757 uses the module after the find_package() call. The features for
4758 which information can be set are added automatically by the
4759 find_package() command.
4760 set_feature_info
4762 set_feature_info(<name> <description> [<url>])
4764 Does the same as:
4766 set_package_info(<name> <description> <url>)
4768 print_enabled_features
4770 print_enabled_features()
4772 Does the same as
4774 feature_summary(WHAT ENABLED_FEATURES DESCRIPTION "Enabled features:")
4776 print_disabled_features
4778 print_disabled_features()
4780 Does the same as
4782 feature_summary(WHAT DISABLED_FEATURES DESCRIPTION "Disabled features:")
4784 FetchContent
4786 Overview
4787 This module enables populating content at configure time via any method
4788 supported by the ExternalProject module. Whereas ExternalProject_Add()
4789 downloads at build time, the FetchContent module makes content avail‐
4790 able immediately, allowing the configure step to use the content in
4791 commands like add_subdirectory(), include() or file() operations.
4792 Content population details would normally be defined separately from
4794 the command that performs the actual population. This separation
4795 ensures that all of the dependency details are defined before anything
4796 may try to use those details to populate content. This is particularly
4797 important in more complex project hierarchies where dependencies may be
4798 shared between multiple projects.
4799 The following shows a typical example of declaring content details:
4801 FetchContent_Declare(
4803 googletest
4804 GIT_REPOSITORY https://github.com/google/googletest.git
4805 GIT_TAG release-1.8.0
4806 )
4807 For most typical cases, populating the content can then be done with a
4809 single command like so:
4810 FetchContent_MakeAvailable(googletest)
4812 The above command not only populates the content, it also adds it to
4814 the main build (if possible) so that the main build can use the popu‐
4815 lated project’s targets, etc. In some cases, the main project may need
4816 to have more precise control over the population or may be required to
4817 explicitly define the population steps (e.g. if CMake versions earlier
4818 than 3.14 need to be supported). The typical pattern of such custom
4819 steps looks like this:
4820 FetchContent_GetProperties(googletest)
4822 if(NOT googletest_POPULATED)
4823 FetchContent_Populate(googletest)
4824 add_subdirectory(${googletest_SOURCE_DIR} ${googletest_BINARY_DIR})
4825 endif()
4826 Regardless of which population method is used, when using the
4828 declare-populate pattern with a hierarchical project arrangement,
4829 projects at higher levels in the hierarchy are able to override the
4830 population details of content specified anywhere lower in the project
4831 hierarchy. The ability to detect whether content has already been pop‐
4832 ulated ensures that even if multiple child projects want certain con‐
4833 tent to be available, the first one to populate it wins. The other
4834 child project can simply make use of the already available content
4835 instead of repeating the population for itself. See the Examples sec‐
4836 tion which demonstrates this scenario.
4837 The FetchContent module also supports defining and populating content
4839 in a single call, with no check for whether the content has been popu‐
4840 lated elsewhere in the project already. This is a more low level oper‐
4841 ation and would not normally be the way the module is used, but it is
4842 sometimes useful as part of implementing some higher level feature or
4843 to populate some content in CMake’s script mode.
4844 Declaring Content Details
4846 FetchContent_Declare
4847 FetchContent_Declare(<name> <contentOptions>...)
4849 The FetchContent_Declare() function records the options that
4851 describe how to populate the specified content, but if such
4852 details have already been recorded earlier in this project
4853 (regardless of where in the project hierarchy), this and all
4854 later calls for the same content <name> are ignored. This
4855 “first to record, wins” approach is what allows hierarchical
4856 projects to have parent projects override content details of
4857 child projects.
4858 The content <name> can be any string without spaces, but good
4860 practice would be to use only letters, numbers and underscores.
4861 The name will be treated case-insensitively and it should be
4862 obvious for the content it represents, often being the name of
4863 the child project or the value given to its top level project()
4864 command (if it is a CMake project). For well-known public
4865 projects, the name should generally be the official name of the
4866 project. Choosing an unusual name makes it unlikely that other
4867 projects needing that same content will use the same name, lead‐
4868 ing to the content being populated multiple times.
4869 The <contentOptions> can be any of the download or update/patch
4871 options that the ExternalProject_Add() command understands. The
4872 configure, build, install and test steps are explicitly disabled
4873 and therefore options related to them will be ignored. In most
4874 cases, <contentOptions> will just be a couple of options defin‐
4875 ing the download method and method-specific details like a com‐
4876 mit tag or archive hash. For example:
4877 FetchContent_Declare(
4879 googletest
4880 GIT_REPOSITORY https://github.com/google/googletest.git
4881 GIT_TAG release-1.8.0
4882 )
4883 FetchContent_Declare(
4885 myCompanyIcons
4886 URL https://intranet.mycompany.com/assets/iconset_1.12.tar.gz
4887 URL_HASH 5588a7b18261c20068beabfb4f530b87
4888 )
4889 FetchContent_Declare(
4891 myCompanyCertificates
4892 SVN_REPOSITORY svn+ssh://svn.mycompany.com/srv/svn/trunk/certs
4893 SVN_REVISION -r12345
4894 )
4895 Populating The Content
4897 For most common scenarios, population means making content available to
4898 the main build according to previously declared details for that depen‐
4899 dency. There are two main patterns for populating content, one based
4900 on calling FetchContent_GetProperties() and FetchContent_Populate() for
4901 more precise control and the other on calling
4902 FetchContent_MakeAvailable() for a simpler, more automated approach.
4903 The former generally follows this canonical pattern:
4904 # Check if population has already been performed
4906 FetchContent_GetProperties(<name>)
4907 string(TOLOWER "<name>" lcName)
4908 if(NOT ${lcName}_POPULATED)
4909 # Fetch the content using previously declared details
4910 FetchContent_Populate(<name>)
4911 # Set custom variables, policies, etc.
4913 # ...
4914 # Bring the populated content into the build
4916 add_subdirectory(${${lcName}_SOURCE_DIR} ${${lcName}_BINARY_DIR})
4917 endif()
4918 The above is such a common pattern that, where no custom steps are
4920 needed between the calls to FetchContent_Populate() and add_subdirec‐
4921 tory(), equivalent logic can be obtained by calling
4922 FetchContent_MakeAvailable() instead (and should be preferred where it
4923 meets the needs of the project).
4924 FetchContent_Populate
4926 FetchContent_Populate( <name> )
4928 In most cases, the only argument given to FetchContent_Popu‐
4930 late() is the <name>. When used this way, the command assumes
4931 the content details have been recorded by an earlier call to
4932 FetchContent_Declare(). The details are stored in a global
4933 property, so they are unaffected by things like variable or
4934 directory scope. Therefore, it doesn’t matter where in the
4935 project the details were previously declared, as long as they
4936 have been declared before the call to FetchContent_Populate().
4937 Those saved details are then used to construct a call to Exter‐
4938 nalProject_Add() in a private sub-build to perform the content
4939 population immediately. The implementation of ExternalPro‐
4940 ject_Add() ensures that if the content has already been popu‐
4941 lated in a previous CMake run, that content will be reused
4942 rather than repopulating them again. For the common case where
4943 population involves downloading content, the cost of the down‐
4944 load is only paid once.
4945 An internal global property records when a particular content
4947 population request has been processed. If FetchContent_Popu‐
4948 late() is called more than once for the same content name within
4949 a configure run, the second call will halt with an error.
4950 Projects can and should check whether content population has
4951 already been processed with the FetchContent_GetProperties()
4952 command before calling FetchContent_Populate().
4953 FetchContent_Populate() will set three variables in the scope of
4955 the caller; <lcName>_POPULATED, <lcName>_SOURCE_DIR and
4956 <lcName>_BINARY_DIR, where <lcName> is the lowercased <name>.
4957 <lcName>_POPULATED will always be set to True by the call.
4958 <lcName>_SOURCE_DIR is the location where the content can be
4959 found upon return (it will have already been populated), while
4960 <lcName>_BINARY_DIR is a directory intended for use as a corre‐
4961 sponding build directory. The main use case for the two direc‐
4962 tory variables is to call add_subdirectory() immediately after
4963 population, i.e.:
4964 FetchContent_Populate(FooBar ...)
4966 add_subdirectory(${foobar_SOURCE_DIR} ${foobar_BINARY_DIR})
4967 The values of the three variables can also be retrieved from
4969 anywhere in the project hierarchy using the
4970 FetchContent_GetProperties() command.
4971 A number of cache variables influence the behavior of all con‐
4973 tent population performed using details saved from a
4974 FetchContent_Declare() call:
4975 FETCHCONTENT_BASE_DIR
4977 In most cases, the saved details do not specify any
4978 options relating to the directories to use for the inter‐
4979 nal sub-build, final source and build areas. It is gen‐
4980 erally best to leave these decisions up to the FetchCon‐
4981 tent module to handle on the project’s behalf. The
4982 FETCHCONTENT_BASE_DIR cache variable controls the point
4983 under which all content population directories are col‐
4984 lected, but in most cases developers would not need to
4985 change this. The default location is
4986 ${CMAKE_BINARY_DIR}/_deps, but if developers change this
4987 value, they should aim to keep the path short and just
4988 below the top level of the build tree to avoid running
4989 into path length problems on Windows.
4990 FETCHCONTENT_QUIET
4992 The logging output during population can be quite ver‐
4993 bose, making the configure stage quite noisy. This cache
4994 option (ON by default) hides all population output unless
4995 an error is encountered. If experiencing problems with
4996 hung downloads, temporarily switching this option off may
4997 help diagnose which content population is causing the
4998 issue.
4999 FETCHCONTENT_FULLY_DISCONNECTED
5001 When this option is enabled, no attempt is made to down‐
5002 load or update any content. It is assumed that all con‐
5003 tent has already been populated in a previous run or the
5004 source directories have been pointed at existing contents
5005 the developer has provided manually (using options
5006 described further below). When the developer knows that
5007 no changes have been made to any content details, turning
5008 this option ON can significantly speed up the configure
5009 stage. It is OFF by default.
5010 FETCHCONTENT_UPDATES_DISCONNECTED
5012 This is a less severe download/update control compared to
5013 FETCHCONTENT_FULLY_DISCONNECTED. Instead of bypassing
5014 all download and update logic, the FETCHCON‐
5015 TENT_UPDATES_DISCONNECTED only disables the update stage.
5016 Therefore, if content has not been downloaded previously,
5017 it will still be downloaded when this option is enabled.
5018 This can speed up the configure stage, but not as much as
5019 FETCHCONTENT_FULLY_DISCONNECTED. It is OFF by default.
5020 In addition to the above cache variables, the following cache
5022 variables are also defined for each content name (<ucName> is
5023 the uppercased value of <name>):
5024 FETCHCONTENT_SOURCE_DIR_<ucName>
5026 If this is set, no download or update steps are performed
5027 for the specified content and the <lcName>_SOURCE_DIR
5028 variable returned to the caller is pointed at this loca‐
5029 tion. This gives developers a way to have a separate
5030 checkout of the content that they can modify freely with‐
5031 out interference from the build. The build simply uses
5032 that existing source, but it still defines
5033 <lcName>_BINARY_DIR to point inside its own build area.
5034 Developers are strongly encouraged to use this mechanism
5035 rather than editing the sources populated in the default
5036 location, as changes to sources in the default location
5037 can be lost when content population details are changed
5038 by the project.
5039 FETCHCONTENT_UPDATES_DISCONNECTED_<ucName>
5041 This is the per-content equivalent of FETCHCON‐
5042 TENT_UPDATES_DISCONNECTED. If the global option or this
5043 option is ON, then updates will be disabled for the named
5044 content. Disabling updates for individual content can be
5045 useful for content whose details rarely change, while
5046 still leaving other frequently changing content with
5047 updates enabled.
5048 The FetchContent_Populate() command also supports a syntax
5050 allowing the content details to be specified directly rather
5051 than using any saved details. This is more low-level and use of
5052 this form is generally to be avoided in favour of using saved
5053 content details as outlined above. Nevertheless, in certain
5054 situations it can be useful to invoke the content population as
5055 an isolated operation (typically as part of implementing some
5056 other higher level feature or when using CMake in script mode):
5057 FetchContent_Populate( <name>
5059 [QUIET]
5060 [SUBBUILD_DIR <subBuildDir>]
5061 [SOURCE_DIR <srcDir>]
5062 [BINARY_DIR <binDir>]
5063 ...
5064 )
5065 This form has a number of key differences to that where only
5067 <name> is provided:
5068 · All required population details are assumed to have been pro‐
5070 vided directly in the call to FetchContent_Populate(). Any
5071 saved details for <name> are ignored.
5072 · No check is made for whether content for <name> has already
5074 been populated.
5075 · No global property is set to record that the population has
5077 occurred.
5078 · No global properties record the source or binary directories
5080 used for the populated content.
5081 · The FETCHCONTENT_FULLY_DISCONNECTED and FETCHCON‐
5083 TENT_UPDATES_DISCONNECTED cache variables are ignored.
5084 The <lcName>_SOURCE_DIR and <lcName>_BINARY_DIR variables are
5086 still returned to the caller, but since these locations are not
5087 stored as global properties when this form is used, they are
5088 only available to the calling scope and below rather than the
5089 entire project hierarchy. No <lcName>_POPULATED variable is set
5090 in the caller’s scope with this form.
5091 The supported options for FetchContent_Populate() are the same
5093 as those for FetchContent_Declare(). Those few options shown
5094 just above are either specific to FetchContent_Populate() or
5095 their behavior is slightly modified from how ExternalPro‐
5096 ject_Add() treats them.
5097 QUIET The QUIET option can be given to hide the output associ‐
5099 ated with populating the specified content. If the popu‐
5100 lation fails, the output will be shown regardless of
5101 whether this option was given or not so that the cause of
5102 the failure can be diagnosed. The global FETCHCON‐
5103 TENT_QUIET cache variable has no effect on FetchCon‐
5104 tent_Populate() calls where the content details are pro‐
5105 vided directly.
5106 SUBBUILD_DIR
5108 The SUBBUILD_DIR argument can be provided to change the
5109 location of the sub-build created to perform the popula‐
5110 tion. The default value is ${CMAKE_CUR‐
5111 RENT_BINARY_DIR}/<lcName>-subbuild and it would be
5112 unusual to need to override this default. If a relative
5113 path is specified, it will be interpreted as relative to
5114 CMAKE_CURRENT_BINARY_DIR.
5115 SOURCE_DIR, BINARY_DIR
5117 The SOURCE_DIR and BINARY_DIR arguments are supported by
5118 ExternalProject_Add(), but different default values are
5119 used by FetchContent_Populate(). SOURCE_DIR defaults to
5120 ${CMAKE_CURRENT_BINARY_DIR}/<lcName>-src and BINARY_DIR
5121 defaults to ${CMAKE_CURRENT_BINARY_DIR}/<lcName>-build.
5122 If a relative path is specified, it will be interpreted
5123 as relative to CMAKE_CURRENT_BINARY_DIR.
5124 In addition to the above explicit options, any other unrecog‐
5126 nized options are passed through unmodified to ExternalPro‐
5127 ject_Add() to perform the download, patch and update steps. The
5128 following options are explicitly prohibited (they are disabled
5129 by the FetchContent_Populate() command):
5130 · CONFIGURE_COMMAND
5132 · BUILD_COMMAND
5134 · INSTALL_COMMAND
5136 · TEST_COMMAND
5138 If using FetchContent_Populate() within CMake’s script mode, be
5140 aware that the implementation sets up a sub-build which there‐
5141 fore requires a CMake generator and build tool to be available.
5142 If these cannot be found by default, then the CMAKE_GENERATOR
5143 and/or CMAKE_MAKE_PROGRAM variables will need to be set appro‐
5144 priately on the command line invoking the script.
5145 FetchContent_GetProperties
5147 When using saved content details, a call to
5148 FetchContent_Populate() records information in global properties
5149 which can be queried at any time. This information includes the
5150 source and binary directories associated with the content and
5151 also whether or not the content population has been processed
5152 during the current configure run.
5153 FetchContent_GetProperties( <name>
5155 [SOURCE_DIR <srcDirVar>]
5156 [BINARY_DIR <binDirVar>]
5157 [POPULATED <doneVar>]
5158 )
5159 The SOURCE_DIR, BINARY_DIR and POPULATED options can be used to
5161 specify which properties should be retrieved. Each option
5162 accepts a value which is the name of the variable in which to
5163 store that property. Most of the time though, only <name> is
5164 given, in which case the call will then set the same variables
5165 as a call to FetchContent_Populate(name). This allows the fol‐
5166 lowing canonical pattern to be used, which ensures that the rel‐
5167 evant variables will always be defined regardless of whether or
5168 not the population has been performed elsewhere in the project
5169 already:
5170 FetchContent_GetProperties(foobar)
5172 if(NOT foobar_POPULATED)
5173 FetchContent_Populate(foobar)
5174 ...
5175 endif()
5176 The above pattern allows other parts of the overall project
5178 hierarchy to re-use the same content and ensure that it is only
5179 populated once.
5180 FetchContent_MakeAvailable
5182 FetchContent_MakeAvailable( <name1> [<name2>...] )
5184 This command implements the common pattern typically needed for
5186 most dependencies. It iterates over each of the named dependen‐
5187 cies in turn and for each one it loosely follows the same
5188 canonical pattern as presented at the beginning of this section.
5189 One small difference to that pattern is that it will only call
5190 add_subdirectory() on the populated content if there is a CMake‐
5191 Lists.txt file in its top level source directory. This allows
5192 the command to be used for dependencies that make downloaded
5193 content available at a known location but which do not need or
5194 support being added directly to the build.
5195 Examples
5197 This first fairly straightforward example ensures that some popular
5198 testing frameworks are available to the main build:
5199 include(FetchContent)
5201 FetchContent_Declare(
5202 googletest
5203 GIT_REPOSITORY https://github.com/google/googletest.git
5204 GIT_TAG release-1.8.0
5205 )
5206 FetchContent_Declare(
5207 Catch2
5208 GIT_REPOSITORY https://github.com/catchorg/Catch2.git
5209 GIT_TAG v2.5.0
5210 )
5211 # After the following call, the CMake targets defined by googletest and
5213 # Catch2 will be defined and available to the rest of the build
5214 FetchContent_MakeAvailable(googletest Catch2)
5215 In more complex project hierarchies, the dependency relationships can
5217 be more complicated. Consider a hierarchy where projA is the top level
5218 project and it depends directly on projects projB and projC. Both
5219 projB and projC can be built standalone and they also both depend on
5220 another project projD. projB additionally depends on projE. This
5221 example assumes that all five projects are available on a company git
5222 server. The CMakeLists.txt of each project might have sections like
5223 the following:
5224 projA:
5226 include(FetchContent)
5228 FetchContent_Declare(
5229 projB
5230 GIT_REPOSITORY git@mycompany.com:git/projB.git
5231 GIT_TAG 4a89dc7e24ff212a7b5167bef7ab079d
5232 )
5233 FetchContent_Declare(
5234 projC
5235 GIT_REPOSITORY git@mycompany.com:git/projC.git
5236 GIT_TAG 4ad4016bd1d8d5412d135cf8ceea1bb9
5237 )
5238 FetchContent_Declare(
5239 projD
5240 GIT_REPOSITORY git@mycompany.com:git/projD.git
5241 GIT_TAG origin/integrationBranch
5242 )
5243 FetchContent_Declare(
5244 projE
5245 GIT_REPOSITORY git@mycompany.com:git/projE.git
5246 GIT_TAG origin/release/2.3-rc1
5247 )
5248 # Order is important, see notes in the discussion further below
5250 FetchContent_MakeAvailable(projD projB projC)
5251 projB:
5253 include(FetchContent)
5255 FetchContent_Declare(
5256 projD
5257 GIT_REPOSITORY git@mycompany.com:git/projD.git
5258 GIT_TAG 20b415f9034bbd2a2e8216e9a5c9e632
5259 )
5260 FetchContent_Declare(
5261 projE
5262 GIT_REPOSITORY git@mycompany.com:git/projE.git
5263 GIT_TAG 68e20f674a48be38d60e129f600faf7d
5264 )
5265 FetchContent_MakeAvailable(projD projE)
5267 projC:
5269 include(FetchContent)
5271 FetchContent_Declare(
5272 projD
5273 GIT_REPOSITORY git@mycompany.com:git/projD.git
5274 GIT_TAG 7d9a17ad2c962aa13e2fbb8043fb6b8a
5275 )
5276 # This particular version of projD requires workarounds
5278 FetchContent_GetProperties(projD)
5279 if(NOT projd_POPULATED)
5280 FetchContent_Populate(projD)
5281 # Copy an additional/replacement file into the populated source
5283 file(COPY someFile.c DESTINATION ${projd_SOURCE_DIR}/src)
5284 add_subdirectory(${projd_SOURCE_DIR} ${projd_BINARY_DIR})
5286 endif()
5287 A few key points should be noted in the above:
5289 · projB and projC define different content details for projD, but projA
5291 also defines a set of content details for projD. Because projA will
5292 define them first, the details from projB and projC will not be used.
5293 The override details defined by projA are not required to match
5294 either of those from projB or projC, but it is up to the higher level
5295 project to ensure that the details it does define still make sense
5296 for the child projects.
5297 · In the projA call to FetchContent_MakeAvailable(), projD is listed
5299 ahead of projB and projC to ensure that projA is in control of how
5300 projD is populated.
5301 · While projA defines content details for projE, it does not need to
5303 explicitly call FetchContent_MakeAvailable(projE) or FetchCon‐
5304 tent_Populate(projD) itself. Instead, it leaves that to the child
5305 projB. For higher level projects, it is often enough to just define
5306 the override content details and leave the actual population to the
5307 child projects. This saves repeating the same thing at each level of
5308 the project hierarchy unnecessarily.
5309 Projects don’t always need to add the populated content to the build.
5311 Sometimes the project just wants to make the downloaded content avail‐
5312 able at a predictable location. The next example ensures that a set of
5313 standard company toolchain files (and potentially even the toolchain
5314 binaries themselves) is available early enough to be used for that same
5315 build.
5316 cmake_minimum_required(VERSION 3.14)
5318 include(FetchContent)
5320 FetchContent_Declare(
5321 mycom_toolchains
5322 URL https://intranet.mycompany.com//toolchains_1.3.2.tar.gz
5323 )
5324 FetchContent_MakeAvailable(mycom_toolchains)
5325 project(CrossCompileExample)
5327 The project could be configured to use one of the downloaded toolchains
5329 like so:
5330 cmake -DCMAKE_TOOLCHAIN_FILE=_deps/mycom_toolchains-src/toolchain_arm.cmake /path/to/src
5332 When CMake processes the CMakeLists.txt file, it will download and
5334 unpack the tarball into _deps/mycompany_toolchains-src relative to the
5335 build directory. The CMAKE_TOOLCHAIN_FILE variable is not used until
5336 the project() command is reached, at which point CMake looks for the
5337 named toolchain file relative to the build directory. Because the tar‐
5338 ball has already been downloaded and unpacked by then, the toolchain
5339 file will be in place, even the very first time that cmake is run in
5340 the build directory.
5341 Lastly, the following example demonstrates how one might download and
5343 unpack a firmware tarball using CMake’s script mode. The call to
5344 FetchContent_Populate() specifies all the content details and the
5345 unpacked firmware will be placed in a firmware directory below the cur‐
5346 rent working directory.
5347 getFirmware.cmake:
5349 # NOTE: Intended to be run in script mode with cmake -P
5351 include(FetchContent)
5352 FetchContent_Populate(
5353 firmware
5354 URL https://mycompany.com/assets/firmware-1.23-arm.tar.gz
5355 URL_HASH MD5=68247684da89b608d466253762b0ff11
5356 SOURCE_DIR firmware
5357 )
5358 FindPackageHandleStandardArgs
5360 This module provides a function intended to be used in Find Modules
5361 implementing find_package(<PackageName>) calls. It handles the
5362 REQUIRED, QUIET and version-related arguments of find_package. It also
5363 sets the <PackageName>_FOUND variable. The package is considered found
5364 if all variables listed contain valid results, e.g. valid filepaths.
5365 find_package_handle_standard_args
5367 There are two signatures:
5368 find_package_handle_standard_args(<PackageName>
5370 (DEFAULT_MSG|<custom-failure-message>)
5371 <required-var>...
5372 )
5373 find_package_handle_standard_args(<PackageName>
5375 [FOUND_VAR <result-var>]
5376 [REQUIRED_VARS <required-var>...]
5377 [VERSION_VAR <version-var>]
5378 [HANDLE_COMPONENTS]
5379 [CONFIG_MODE]
5380 [FAIL_MESSAGE <custom-failure-message>]
5381 )
5382 The <PackageName>_FOUND variable will be set to TRUE if all the
5384 variables <required-var>... are valid and any optional con‐
5385 straints are satisfied, and FALSE otherwise. A success or fail‐
5386 ure message may be displayed based on the results and on whether
5387 the REQUIRED and/or QUIET option was given to the find_package()
5388 call.
5389 The options are:
5391 (DEFAULT_MSG|<custom-failure-message>)
5393 In the simple signature this specifies the failure mes‐
5394 sage. Use DEFAULT_MSG to ask for a default message to be
5395 computed (recommended). Not valid in the full signature.
5396 FOUND_VAR <result-var>
5398 Obsolete. Specifies either <PackageName>_FOUND or <PACK‐
5399 AGENAME>_FOUND as the result variable. This exists only
5400 for compatibility with older versions of CMake and is now
5401 ignored. Result variables of both names are always set
5402 for compatibility.
5403 REQUIRED_VARS <required-var>...
5405 Specify the variables which are required for this pack‐
5406 age. These may be named in the generated failure message
5407 asking the user to set the missing variable values.
5408 Therefore these should typically be cache entries such as
5409 FOO_LIBRARY and not output variables like FOO_LIBRARIES.
5410 VERSION_VAR <version-var>
5412 Specify the name of a variable that holds the version of
5413 the package that has been found. This version will be
5414 checked against the (potentially) specified required ver‐
5415 sion given to the find_package() call, including its
5416 EXACT option. The default messages include information
5417 about the required version and the version which has been
5418 actually found, both if the version is ok or not.
5419 HANDLE_COMPONENTS
5421 Enable handling of package components. In this case, the
5422 command will report which components have been found and
5423 which are missing, and the <PackageName>_FOUND variable
5424 will be set to FALSE if any of the required components
5425 (i.e. not the ones listed after the OPTIONAL_COMPONENTS
5426 option of find_package()) are missing.
5427 CONFIG_MODE
5429 Specify that the calling find module is a wrapper around
5430 a call to find_package(<PackageName> NO_MODULE). This
5431 implies a VERSION_VAR value of <PackageName>_VERSION.
5432 The command will automatically check whether the package
5433 configuration file was found.
5434 FAIL_MESSAGE <custom-failure-message>
5436 Specify a custom failure message instead of using the
5437 default generated message. Not recommended.
5438 Example for the simple signature:
5440 find_package_handle_standard_args(LibXml2 DEFAULT_MSG
5442 LIBXML2_LIBRARY LIBXML2_INCLUDE_DIR)
5443 The LibXml2 package is considered to be found if both LIBXML2_LIBRARY
5445 and LIBXML2_INCLUDE_DIR are valid. Then also LibXml2_FOUND is set to
5446 TRUE. If it is not found and REQUIRED was used, it fails with a mes‐
5447 sage(FATAL_ERROR), independent whether QUIET was used or not. If it is
5448 found, success will be reported, including the content of the first
5449 <required-var>. On repeated CMake runs, the same message will not be
5450 printed again.
5451 Example for the full signature:
5453 find_package_handle_standard_args(LibArchive
5455 REQUIRED_VARS LibArchive_LIBRARY LibArchive_INCLUDE_DIR
5456 VERSION_VAR LibArchive_VERSION)
5457 In this case, the LibArchive package is considered to be found if both
5459 LibArchive_LIBRARY and LibArchive_INCLUDE_DIR are valid. Also the ver‐
5460 sion of LibArchive will be checked by using the version contained in
5461 LibArchive_VERSION. Since no FAIL_MESSAGE is given, the default mes‐
5462 sages will be printed.
5463 Another example for the full signature:
5465 find_package(Automoc4 QUIET NO_MODULE HINTS /opt/automoc4)
5467 find_package_handle_standard_args(Automoc4 CONFIG_MODE)
5468 In this case, a FindAutmoc4.cmake module wraps a call to find_pack‐
5470 age(Automoc4 NO_MODULE) and adds an additional search directory for
5471 automoc4. Then the call to find_package_handle_standard_args produces
5472 a proper success/failure message.
5473 FindPackageMessage
5475 find_package_message(<name> "message for user" "find result details")
5476 This function is intended to be used in FindXXX.cmake modules files.
5478 It will print a message once for each unique find result. This is use‐
5479 ful for telling the user where a package was found. The first argument
5480 specifies the name (XXX) of the package. The second argument specifies
5481 the message to display. The third argument lists details about the
5482 find result so that if they change the message will be displayed again.
5483 The macro also obeys the QUIET argument to the find_package command.
5484 Example:
5486 if(X11_FOUND)
5488 find_package_message(X11 "Found X11: ${X11_X11_LIB}"
5489 "[${X11_X11_LIB}][${X11_INCLUDE_DIR}]")
5490 else()
5491 ...
5492 endif()
5493 FortranCInterface
5495 Fortran/C Interface Detection
5496 This module automatically detects the API by which C and Fortran lan‐
5498 guages interact.
5499 Module Variables
5501 Variables that indicate if the mangling is found:
5502 FortranCInterface_GLOBAL_FOUND
5504 Global subroutines and functions.
5505 FortranCInterface_MODULE_FOUND
5507 Module subroutines and functions (declared by “MODULE PROCE‐
5508 DURE”).
5509 This module also provides the following variables to specify the
5511 detected mangling, though a typical use case does not need to reference
5512 them and can use the Module Functions below.
5513 FortranCInterface_GLOBAL_PREFIX
5515 Prefix for a global symbol without an underscore.
5516 FortranCInterface_GLOBAL_SUFFIX
5518 Suffix for a global symbol without an underscore.
5519 FortranCInterface_GLOBAL_CASE
5521 The case for a global symbol without an underscore, either UPPER
5522 or LOWER.
5523 FortranCInterface_GLOBAL__PREFIX
5525 Prefix for a global symbol with an underscore.
5526 FortranCInterface_GLOBAL__SUFFIX
5528 Suffix for a global symbol with an underscore.
5529 FortranCInterface_GLOBAL__CASE
5531 The case for a global symbol with an underscore, either UPPER or
5532 LOWER.
5533 FortranCInterface_MODULE_PREFIX
5535 Prefix for a module symbol without an underscore.
5536 FortranCInterface_MODULE_MIDDLE
5538 Middle of a module symbol without an underscore that appears
5539 between the name of the module and the name of the symbol.
5540 FortranCInterface_MODULE_SUFFIX
5542 Suffix for a module symbol without an underscore.
5543 FortranCInterface_MODULE_CASE
5545 The case for a module symbol without an underscore, either UPPER
5546 or LOWER.
5547 FortranCInterface_MODULE__PREFIX
5549 Prefix for a module symbol with an underscore.
5550 FortranCInterface_MODULE__MIDDLE
5552 Middle of a module symbol with an underscore that appears
5553 between the name of the module and the name of the symbol.
5554 FortranCInterface_MODULE__SUFFIX
5556 Suffix for a module symbol with an underscore.
5557 FortranCInterface_MODULE__CASE
5559 The case for a module symbol with an underscore, either UPPER or
5560 LOWER.
5561 Module Functions
5563 FortranCInterface_HEADER
5564 The FortranCInterface_HEADER function is provided to generate a
5565 C header file containing macros to mangle symbol names:
5566 FortranCInterface_HEADER(<file>
5568 [MACRO_NAMESPACE <macro-ns>]
5569 [SYMBOL_NAMESPACE <ns>]
5570 [SYMBOLS [<module>:]<function> ...])
5571 It generates in <file> definitions of the following macros:
5573 #define FortranCInterface_GLOBAL (name,NAME) ...
5575 #define FortranCInterface_GLOBAL_(name,NAME) ...
5576 #define FortranCInterface_MODULE (mod,name, MOD,NAME) ...
5577 #define FortranCInterface_MODULE_(mod,name, MOD,NAME) ...
5578 These macros mangle four categories of Fortran symbols, respec‐
5580 tively:
5581 · Global symbols without ‘_’: call mysub()
5583 · Global symbols with ‘_’ : call my_sub()
5585 · Module symbols without ‘_’: use mymod; call mysub()
5587 · Module symbols with ‘_’ : use mymod; call my_sub()
5589 If mangling for a category is not known, its macro is left unde‐
5591 fined. All macros require raw names in both lower case and
5592 upper case.
5593 The options are:
5595 MACRO_NAMESPACE
5597 Replace the default FortranCInterface_ prefix with a
5598 given namespace <macro-ns>.
5599 SYMBOLS
5601 List symbols to mangle automatically with C preprocessor
5602 definitions:
5603 <function> ==> #define <ns><function> ...
5605 <module>:<function> ==> #define <ns><module>_<function> ...
5606 If the mangling for some symbol is not known then no pre‐
5608 processor definition is created, and a warning is dis‐
5609 played.
5610 SYMBOL_NAMESPACE
5612 Prefix all preprocessor definitions generated by the SYM‐
5613 BOLS option with a given namespace <ns>.
5614 FortranCInterface_VERIFY
5616 The FortranCInterface_VERIFY function is provided to verify that
5617 the Fortran and C/C++ compilers work together:
5618 FortranCInterface_VERIFY([CXX] [QUIET])
5620 It tests whether a simple test executable using Fortran and C
5622 (and C++ when the CXX option is given) compiles and links suc‐
5623 cessfully. The result is stored in the cache entry FortranCIn‐
5624 terface_VERIFIED_C (or FortranCInterface_VERIFIED_CXX if CXX is
5625 given) as a boolean. If the check fails and QUIET is not given
5626 the function terminates with a fatal error message describing
5627 the problem. The purpose of this check is to stop a build early
5628 for incompatible compiler combinations. The test is built in
5629 the Release configuration.
5630 Example Usage
5632 include(FortranCInterface)
5633 FortranCInterface_HEADER(FC.h MACRO_NAMESPACE "FC_")
5634 This creates a “FC.h” header that defines mangling macros FC_GLOBAL(),
5636 FC_GLOBAL_(), FC_MODULE(), and FC_MODULE_().
5637 include(FortranCInterface)
5639 FortranCInterface_HEADER(FCMangle.h
5640 MACRO_NAMESPACE "FC_"
5641 SYMBOL_NAMESPACE "FC_"
5642 SYMBOLS mysub mymod:my_sub)
5643 This creates a “FCMangle.h” header that defines the same FC_*() man‐
5645 gling macros as the previous example plus preprocessor symbols FC_mysub
5646 and FC_mymod_my_sub.
5647 Additional Manglings
5649 FortranCInterface is aware of possible GLOBAL and MODULE manglings for
5650 many Fortran compilers, but it also provides an interface to specify
5651 new possible manglings. Set the variables:
5652 FortranCInterface_GLOBAL_SYMBOLS
5654 FortranCInterface_MODULE_SYMBOLS
5655 before including FortranCInterface to specify manglings of the symbols
5657 MySub, My_Sub, MyModule:MySub, and My_Module:My_Sub. For example, the
5658 code:
5659 set(FortranCInterface_GLOBAL_SYMBOLS mysub_ my_sub__ MYSUB_)
5661 # ^^^^^ ^^^^^^ ^^^^^
5662 set(FortranCInterface_MODULE_SYMBOLS
5663 __mymodule_MOD_mysub __my_module_MOD_my_sub)
5664 # ^^^^^^^^ ^^^^^ ^^^^^^^^^ ^^^^^^
5665 include(FortranCInterface)
5666 tells FortranCInterface to try given GLOBAL and MODULE manglings. (The
5668 carets point at raw symbol names for clarity in this example but are
5669 not needed.)
5670 GenerateExportHeader
5672 Function for generation of export macros for libraries
5673 This module provides the function GENERATE_EXPORT_HEADER().
5675 The GENERATE_EXPORT_HEADER function can be used to generate a file
5677 suitable for preprocessor inclusion which contains EXPORT macros to be
5678 used in library classes:
5679 GENERATE_EXPORT_HEADER( LIBRARY_TARGET
5681 [BASE_NAME <base_name>]
5682 [EXPORT_MACRO_NAME <export_macro_name>]
5683 [EXPORT_FILE_NAME <export_file_name>]
5684 [DEPRECATED_MACRO_NAME <deprecated_macro_name>]
5685 [NO_EXPORT_MACRO_NAME <no_export_macro_name>]
5686 [INCLUDE_GUARD_NAME <include_guard_name>]
5687 [STATIC_DEFINE <static_define>]
5688 [NO_DEPRECATED_MACRO_NAME <no_deprecated_macro_name>]
5689 [DEFINE_NO_DEPRECATED]
5690 [PREFIX_NAME <prefix_name>]
5691 [CUSTOM_CONTENT_FROM_VARIABLE <variable>]
5692 )
5693 The target properties CXX_VISIBILITY_PRESET and VISIBILITY_INLINES_HID‐
5695 DEN can be used to add the appropriate compile flags for targets. See
5696 the documentation of those target properties, and the convenience vari‐
5697 ables CMAKE_CXX_VISIBILITY_PRESET and CMAKE_VISIBILITY_INLINES_HIDDEN.
5698 By default GENERATE_EXPORT_HEADER() generates macro names in a file
5700 name determined by the name of the library. This means that in the
5701 simplest case, users of GenerateExportHeader will be equivalent to:
5702 set(CMAKE_CXX_VISIBILITY_PRESET hidden)
5704 set(CMAKE_VISIBILITY_INLINES_HIDDEN 1)
5705 add_library(somelib someclass.cpp)
5706 generate_export_header(somelib)
5707 install(TARGETS somelib DESTINATION ${LIBRARY_INSTALL_DIR})
5708 install(FILES
5709 someclass.h
5710 ${PROJECT_BINARY_DIR}/somelib_export.h DESTINATION ${INCLUDE_INSTALL_DIR}
5711 )
5712 And in the ABI header files:
5714 #include "somelib_export.h"
5716 class SOMELIB_EXPORT SomeClass {
5717 ...
5718 };
5719 The CMake fragment will generate a file in the ${CMAKE_CUR‐
5721 RENT_BINARY_DIR} called somelib_export.h containing the macros
5722 SOMELIB_EXPORT, SOMELIB_NO_EXPORT, SOMELIB_DEPRECATED, SOMELIB_DEPRE‐
5723 CATED_EXPORT and SOMELIB_DEPRECATED_NO_EXPORT. They will be followed
5724 by content taken from the variable specified by the CUSTOM_CON‐
5725 TENT_FROM_VARIABLE option, if any. The resulting file should be
5726 installed with other headers in the library.
5727 The BASE_NAME argument can be used to override the file name and the
5729 names used for the macros:
5730 add_library(somelib someclass.cpp)
5732 generate_export_header(somelib
5733 BASE_NAME other_name
5734 )
5735 Generates a file called other_name_export.h containing the macros
5737 OTHER_NAME_EXPORT, OTHER_NAME_NO_EXPORT and OTHER_NAME_DEPRECATED etc.
5738 The BASE_NAME may be overridden by specifying other options in the
5740 function. For example:
5741 add_library(somelib someclass.cpp)
5743 generate_export_header(somelib
5744 EXPORT_MACRO_NAME OTHER_NAME_EXPORT
5745 )
5746 creates the macro OTHER_NAME_EXPORT instead of SOMELIB_EXPORT, but
5748 other macros and the generated file name is as default:
5749 add_library(somelib someclass.cpp)
5751 generate_export_header(somelib
5752 DEPRECATED_MACRO_NAME KDE_DEPRECATED
5753 )
5754 creates the macro KDE_DEPRECATED instead of SOMELIB_DEPRECATED.
5756 If LIBRARY_TARGET is a static library, macros are defined without val‐
5758 ues.
5759 If the same sources are used to create both a shared and a static
5761 library, the uppercased symbol ${BASE_NAME}_STATIC_DEFINE should be
5762 used when building the static library:
5763 add_library(shared_variant SHARED ${lib_SRCS})
5765 add_library(static_variant ${lib_SRCS})
5766 generate_export_header(shared_variant BASE_NAME libshared_and_static)
5767 set_target_properties(static_variant PROPERTIES
5768 COMPILE_FLAGS -DLIBSHARED_AND_STATIC_STATIC_DEFINE)
5769 This will cause the export macros to expand to nothing when building
5771 the static library.
5772 If DEFINE_NO_DEPRECATED is specified, then a macro ${BASE_NAME}_NO_DEP‐
5774 RECATED will be defined This macro can be used to remove deprecated
5775 code from preprocessor output:
5776 option(EXCLUDE_DEPRECATED "Exclude deprecated parts of the library" FALSE)
5778 if (EXCLUDE_DEPRECATED)
5779 set(NO_BUILD_DEPRECATED DEFINE_NO_DEPRECATED)
5780 endif()
5781 generate_export_header(somelib ${NO_BUILD_DEPRECATED})
5782 And then in somelib:
5784 class SOMELIB_EXPORT SomeClass
5786 {
5787 public:
5788 #ifndef SOMELIB_NO_DEPRECATED
5789 SOMELIB_DEPRECATED void oldMethod();
5790 #endif
5791 };
5792 #ifndef SOMELIB_NO_DEPRECATED
5794 void SomeClass::oldMethod() { }
5795 #endif
5796 If PREFIX_NAME is specified, the argument will be used as a prefix to
5798 all generated macros.
5799 For example:
5801 generate_export_header(somelib PREFIX_NAME VTK_)
5803 Generates the macros VTK_SOMELIB_EXPORT etc.
5805 ADD_COMPILER_EXPORT_FLAGS( [<output_variable>] )
5807 The ADD_COMPILER_EXPORT_FLAGS function adds -fvisibility=hidden to
5809 CMAKE_CXX_FLAGS if supported, and is a no-op on Windows which does not
5810 need extra compiler flags for exporting support. You may optionally
5811 pass a single argument to ADD_COMPILER_EXPORT_FLAGS that will be popu‐
5812 lated with the CXX_FLAGS required to enable visibility support for the
5813 compiler/architecture in use.
5814 This function is deprecated. Set the target properties CXX_VISIBIL‐
5816 ITY_PRESET and VISIBILITY_INLINES_HIDDEN instead.
5817 GetPrerequisites
5819 Functions to analyze and list executable file prerequisites.
5820 This module provides functions to list the .dll, .dylib or .so files
5822 that an executable or shared library file depends on. (Its prerequi‐
5823 sites.)
5824 It uses various tools to obtain the list of required shared library
5826 files:
5827 dumpbin (Windows)
5829 objdump (MinGW on Windows)
5830 ldd (Linux/Unix)
5831 otool (Mac OSX)
5832 The following functions are provided by this module:
5834 get_prerequisites
5836 list_prerequisites
5837 list_prerequisites_by_glob
5838 gp_append_unique
5839 is_file_executable
5840 gp_item_default_embedded_path
5841 (projects can override with gp_item_default_embedded_path_override)
5842 gp_resolve_item
5843 (projects can override with gp_resolve_item_override)
5844 gp_resolved_file_type
5845 (projects can override with gp_resolved_file_type_override)
5846 gp_file_type
5847 Requires CMake 2.6 or greater because it uses function, break, return
5849 and PARENT_SCOPE.
5850 GET_PREREQUISITES(<target> <prerequisites_var> <exclude_system> <recurse>
5852 <exepath> <dirs> [<rpaths>])
5853 Get the list of shared library files required by <target>. The list in
5855 the variable named <prerequisites_var> should be empty on first entry
5856 to this function. On exit, <prerequisites_var> will contain the list
5857 of required shared library files.
5858 <target> is the full path to an executable file. <prerequisites_var>
5860 is the name of a CMake variable to contain the results. <exclude_sys‐
5861 tem> must be 0 or 1 indicating whether to include or exclude “system”
5862 prerequisites. If <recurse> is set to 1 all prerequisites will be
5863 found recursively, if set to 0 only direct prerequisites are listed.
5864 <exepath> is the path to the top level executable used for @exe‐
5865 cutable_path replacment on the Mac. <dirs> is a list of paths where
5866 libraries might be found: these paths are searched first when a target
5867 without any path info is given. Then standard system locations are
5868 also searched: PATH, Framework locations, /usr/lib…
5869 The variable GET_PREREQUISITES_VERBOSE can be set to true to enable
5871 verbose output.
5872 LIST_PREREQUISITES(<target> [<recurse> [<exclude_system> [<verbose>]]])
5874 Print a message listing the prerequisites of <target>.
5876 <target> is the name of a shared library or executable target or the
5878 full path to a shared library or executable file. If <recurse> is set
5879 to 1 all prerequisites will be found recursively, if set to 0 only
5880 direct prerequisites are listed. <exclude_system> must be 0 or 1 indi‐
5881 cating whether to include or exclude “system” prerequisites. With
5882 <verbose> set to 0 only the full path names of the prerequisites are
5883 printed, set to 1 extra informatin will be displayed.
5884 LIST_PREREQUISITES_BY_GLOB(<glob_arg> <glob_exp>)
5886 Print the prerequisites of shared library and executable files matching
5888 a globbing pattern. <glob_arg> is GLOB or GLOB_RECURSE and <glob_exp>
5889 is a globbing expression used with “file(GLOB” or “file(GLOB_RECURSE”
5890 to retrieve a list of matching files. If a matching file is exe‐
5891 cutable, its prerequisites are listed.
5892 Any additional (optional) arguments provided are passed along as the
5894 optional arguments to the list_prerequisites calls.
5895 GP_APPEND_UNIQUE(<list_var> <value>)
5897 Append <value> to the list variable <list_var> only if the value is not
5899 already in the list.
5900 IS_FILE_EXECUTABLE(<file> <result_var>)
5902 Return 1 in <result_var> if <file> is a binary executable, 0 otherwise.
5904 GP_ITEM_DEFAULT_EMBEDDED_PATH(<item> <default_embedded_path_var>)
5906 Return the path that others should refer to the item by when the item
5908 is embedded inside a bundle.
5909 Override on a per-project basis by providing a project-specific
5911 gp_item_default_embedded_path_override function.
5912 GP_RESOLVE_ITEM(<context> <item> <exepath> <dirs> <resolved_item_var>
5914 [<rpaths>])
5915 Resolve an item into an existing full path file.
5917 Override on a per-project basis by providing a project-specific
5919 gp_resolve_item_override function.
5920 GP_RESOLVED_FILE_TYPE(<original_file> <file> <exepath> <dirs> <type_var>
5922 [<rpaths>])
5923 Return the type of <file> with respect to <original_file>. String
5925 describing type of prerequisite is returned in variable named
5926 <type_var>.
5927 Use <exepath> and <dirs> if necessary to resolve non-absolute <file>
5929 values – but only for non-embedded items.
5930 Possible types are:
5932 system
5934 local
5935 embedded
5936 other
5937 Override on a per-project basis by providing a project-specific
5939 gp_resolved_file_type_override function.
5940 GP_FILE_TYPE(<original_file> <file> <type_var>)
5942 Return the type of <file> with respect to <original_file>. String
5944 describing type of prerequisite is returned in variable named
5945 <type_var>.
5946 Possible types are:
5948 system
5950 local
5951 embedded
5952 other
5953 GNUInstallDirs
5955 Define GNU standard installation directories
5956 Provides install directory variables as defined by the GNU Coding Stan‐
5958 dards.
5959 Result Variables
5961 Inclusion of this module defines the following variables:
5962 CMAKE_INSTALL_<dir>
5964 Destination for files of a given type. This value may be passed to
5965 the DESTINATION options of install() commands for the corresponding
5966 file type.
5967 CMAKE_INSTALL_FULL_<dir>
5969 The absolute path generated from the corresponding
5970 CMAKE_INSTALL_<dir> value. If the value is not already an absolute
5971 path, an absolute path is constructed typically by prepending the
5972 value of the CMAKE_INSTALL_PREFIX variable. However, there are some
5973 special cases as documented below.
5974 where <dir> is one of:
5976 BINDIR user executables (bin)
5978 SBINDIR
5980 system admin executables (sbin)
5981 LIBEXECDIR
5983 program executables (libexec)
5984 SYSCONFDIR
5986 read-only single-machine data (etc)
5987 SHAREDSTATEDIR
5989 modifiable architecture-independent data (com)
5990 LOCALSTATEDIR
5992 modifiable single-machine data (var)
5993 RUNSTATEDIR
5995 run-time variable data (LOCALSTATEDIR/run)
5996 LIBDIR object code libraries (lib or lib64 or lib/<multiarch-tuple> on
5998 Debian)
5999 INCLUDEDIR
6001 C header files (include)
6002 OLDINCLUDEDIR
6004 C header files for non-gcc (/usr/include)
6005 DATAROOTDIR
6007 read-only architecture-independent data root (share)
6008 DATADIR
6010 read-only architecture-independent data (DATAROOTDIR)
6011 INFODIR
6013 info documentation (DATAROOTDIR/info)
6014 LOCALEDIR
6016 locale-dependent data (DATAROOTDIR/locale)
6017 MANDIR man documentation (DATAROOTDIR/man)
6019 DOCDIR documentation root (DATAROOTDIR/doc/PROJECT_NAME)
6021 If the includer does not define a value the above-shown default will be
6023 used and the value will appear in the cache for editing by the user.
6024 Special Cases
6026 The following values of CMAKE_INSTALL_PREFIX are special:
6027 /
6029 For <dir> other than the SYSCONFDIR, LOCALSTATEDIR and RUNSTATEDIR,
6030 the value of CMAKE_INSTALL_<dir> is prefixed with usr/ if it is not
6031 user-specified as an absolute path. For example, the INCLUDEDIR
6032 value include becomes usr/include. This is required by the GNU Cod‐
6033 ing Standards, which state:
6034 When building the complete GNU system, the prefix will be empty
6035 and /usr will be a symbolic link to /.
6036 /usr
6038 For <dir> equal to SYSCONFDIR, LOCALSTATEDIR or RUNSTATEDIR, the
6039 CMAKE_INSTALL_FULL_<dir> is computed by prepending just / to the
6040 value of CMAKE_INSTALL_<dir> if it is not user-specified as an abso‐
6041 lute path. For example, the SYSCONFDIR value etc becomes /etc.
6042 This is required by the GNU Coding Standards.
6043 /opt/...
6045 For <dir> equal to SYSCONFDIR, LOCALSTATEDIR or RUNSTATEDIR, the
6046 CMAKE_INSTALL_FULL_<dir> is computed by appending the prefix to the
6047 value of CMAKE_INSTALL_<dir> if it is not user-specified as an abso‐
6048 lute path. For example, the SYSCONFDIR value etc becomes
6049 /etc/opt/.... This is defined by the Filesystem Hierarchy Standard.
6050 Macros
6052 GNUInstallDirs_get_absolute_install_dir
6053 GNUInstallDirs_get_absolute_install_dir(absvar var)
6055 Set the given variable absvar to the absolute path contained
6057 within the variable var. This is to allow the computation of an
6058 absolute path, accounting for all the special cases documented
6059 above. While this macro is used to compute the various
6060 CMAKE_INSTALL_FULL_<dir> variables, it is exposed publicly to
6061 allow users who create additional path variables to also compute
6062 absolute paths where necessary, using the same logic.
6063 GoogleTest
6065 This module defines functions to help use the Google Test infrastruc‐
6066 ture. Two mechanisms for adding tests are provided. gtest_add_tests()
6067 has been around for some time, originally via find_package(GTest).
6068 gtest_discover_tests() was introduced in CMake 3.10.
6069 The (older) gtest_add_tests() scans source files to identify tests.
6071 This is usually effective, with some caveats, including in cross-com‐
6072 piling environments, and makes setting additional properties on tests
6073 more convenient. However, its handling of parameterized tests is less
6074 comprehensive, and it requires re-running CMake to detect changes to
6075 the list of tests.
6076 The (newer) gtest_discover_tests() discovers tests by asking the com‐
6078 piled test executable to enumerate its tests. This is more robust and
6079 provides better handling of parameterized tests, and does not require
6080 CMake to be re-run when tests change. However, it may not work in a
6081 cross-compiling environment, and setting test properties is less conve‐
6082 nient.
6083 More details can be found in the documentation of the respective func‐
6085 tions.
6086 Both commands are intended to replace use of add_test() to register
6088 tests, and will create a separate CTest test for each Google Test test
6089 case. Note that this is in some cases less efficient, as common set-up
6090 and tear-down logic cannot be shared by multiple test cases executing
6091 in the same instance. However, it provides more fine-grained pass/fail
6092 information to CTest, which is usually considered as more beneficial.
6093 By default, the CTest test name is the same as the Google Test name
6094 (i.e. suite.testcase); see also TEST_PREFIX and TEST_SUFFIX.
6095 gtest_add_tests
6097 Automatically add tests with CTest by scanning source code for
6098 Google Test macros:
6099 gtest_add_tests(TARGET target
6101 [SOURCES src1...]
6102 [EXTRA_ARGS arg1...]
6103 [WORKING_DIRECTORY dir]
6104 [TEST_PREFIX prefix]
6105 [TEST_SUFFIX suffix]
6106 [SKIP_DEPENDENCY]
6107 [TEST_LIST outVar]
6108 )
6109 gtest_add_tests attempts to identify tests by scanning source
6111 files. Although this is generally effective, it uses only a
6112 basic regular expression match, which can be defeated by atypi‐
6113 cal test declarations, and is unable to fully “split” parameter‐
6114 ized tests. Additionally, it requires that CMake be re-run to
6115 discover any newly added, removed or renamed tests (by default,
6116 this means that CMake is re-run when any test source file is
6117 changed, but see SKIP_DEPENDENCY). However, it has the advan‐
6118 tage of declaring tests at CMake time, which somewhat simplifies
6119 setting additional properties on tests, and always works in a
6120 cross-compiling environment.
6121 The options are:
6123 TARGET target
6125 Specifies the Google Test executable, which must be a
6126 known CMake executable target. CMake will substitute the
6127 location of the built executable when running the test.
6128 SOURCES src1...
6130 When provided, only the listed files will be scanned for
6131 test cases. If this option is not given, the SOURCES
6132 property of the specified target will be used to obtain
6133 the list of sources.
6134 EXTRA_ARGS arg1...
6136 Any extra arguments to pass on the command line to each
6137 test case.
6138 WORKING_DIRECTORY dir
6140 Specifies the directory in which to run the discovered
6141 test cases. If this option is not provided, the current
6142 binary directory is used.
6143 TEST_PREFIX prefix
6145 Specifies a prefix to be prepended to the name of each
6146 discovered test case. This can be useful when the same
6147 source files are being used in multiple calls to
6148 gtest_add_test() but with different EXTRA_ARGS.
6149 TEST_SUFFIX suffix
6151 Similar to TEST_PREFIX except the suffix is appended to
6152 the name of every discovered test case. Both TEST_PREFIX
6153 and TEST_SUFFIX may be specified.
6154 SKIP_DEPENDENCY
6156 Normally, the function creates a dependency which will
6157 cause CMake to be re-run if any of the sources being
6158 scanned are changed. This is to ensure that the list of
6159 discovered tests is updated. If this behavior is not
6160 desired (as may be the case while actually writing the
6161 test cases), this option can be used to prevent the
6162 dependency from being added.
6163 TEST_LIST outVar
6165 The variable named by outVar will be populated in the
6166 calling scope with the list of discovered test cases.
6167 This allows the caller to do things like manipulate test
6168 properties of the discovered tests.
6169 include(GoogleTest)
6171 add_executable(FooTest FooUnitTest.cxx)
6172 gtest_add_tests(TARGET FooTest
6173 TEST_SUFFIX .noArgs
6174 TEST_LIST noArgsTests
6175 )
6176 gtest_add_tests(TARGET FooTest
6177 EXTRA_ARGS --someArg someValue
6178 TEST_SUFFIX .withArgs
6179 TEST_LIST withArgsTests
6180 )
6181 set_tests_properties(${noArgsTests} PROPERTIES TIMEOUT 10)
6182 set_tests_properties(${withArgsTests} PROPERTIES TIMEOUT 20)
6183 For backward compatibility, the following form is also sup‐
6185 ported:
6186 gtest_add_tests(exe args files...)
6188 exe The path to the test executable or the name of a CMake
6190 target.
6191 args A ;-list of extra arguments to be passed to executable.
6193 The entire list must be passed as a single argument.
6194 Enclose it in quotes, or pass "" for no arguments.
6195 files...
6197 A list of source files to search for tests and test fix‐
6198 tures. Alternatively, use AUTO to specify that exe is
6199 the name of a CMake executable target whose sources
6200 should be scanned.
6201 include(GoogleTest)
6203 set(FooTestArgs --foo 1 --bar 2)
6204 add_executable(FooTest FooUnitTest.cxx)
6205 gtest_add_tests(FooTest "${FooTestArgs}" AUTO)
6206 gtest_discover_tests
6208 Automatically add tests with CTest by querying the compiled test
6209 executable for available tests:
6210 gtest_discover_tests(target
6212 [EXTRA_ARGS arg1...]
6213 [WORKING_DIRECTORY dir]
6214 [TEST_PREFIX prefix]
6215 [TEST_SUFFIX suffix]
6216 [NO_PRETTY_TYPES] [NO_PRETTY_VALUES]
6217 [PROPERTIES name1 value1...]
6218 [TEST_LIST var]
6219 [DISCOVERY_TIMEOUT seconds]
6220 )
6221 gtest_discover_tests sets up a post-build command on the test
6223 executable that generates the list of tests by parsing the out‐
6224 put from running the test with the --gtest_list_tests argument.
6225 Compared to the source parsing approach of gtest_add_tests(),
6226 this ensures that the full list of tests, including instantia‐
6227 tions of parameterized tests, is obtained. Since test discovery
6228 occurs at build time, it is not necessary to re-run CMake when
6229 the list of tests changes. However, it requires that CROSSCOM‐
6230 PILING_EMULATOR is properly set in order to function in a
6231 cross-compiling environment.
6232 Additionally, setting properties on tests is somewhat less con‐
6234 venient, since the tests are not available at CMake time. Addi‐
6235 tional test properties may be assigned to the set of tests as a
6236 whole using the PROPERTIES option. If more fine-grained test
6237 control is needed, custom content may be provided through an
6238 external CTest script using the TEST_INCLUDE_FILES directory
6239 property. The set of discovered tests is made accessible to
6240 such a script via the <target>_TESTS variable.
6241 The options are:
6243 target Specifies the Google Test executable, which must be a
6245 known CMake executable target. CMake will substitute the
6246 location of the built executable when running the test.
6247 EXTRA_ARGS arg1...
6249 Any extra arguments to pass on the command line to each
6250 test case.
6251 WORKING_DIRECTORY dir
6253 Specifies the directory in which to run the discovered
6254 test cases. If this option is not provided, the current
6255 binary directory is used.
6256 TEST_PREFIX prefix
6258 Specifies a prefix to be prepended to the name of each
6259 discovered test case. This can be useful when the same
6260 test executable is being used in multiple calls to
6261 gtest_discover_tests() but with different EXTRA_ARGS.
6262 TEST_SUFFIX suffix
6264 Similar to TEST_PREFIX except the suffix is appended to
6265 the name of every discovered test case. Both TEST_PREFIX
6266 and TEST_SUFFIX may be specified.
6267 NO_PRETTY_TYPES
6269 By default, the type index of type-parameterized tests is
6270 replaced by the actual type name in the CTest test name.
6271 If this behavior is undesirable (e.g. because the type
6272 names are unwieldy), this option will suppress this
6273 behavior.
6274 NO_PRETTY_VALUES
6276 By default, the value index of value-parameterized tests
6277 is replaced by the actual value in the CTest test name.
6278 If this behavior is undesirable (e.g. because the value
6279 strings are unwieldy), this option will suppress this
6280 behavior.
6281 PROPERTIES name1 value1...
6283 Specifies additional properties to be set on all tests
6284 discovered by this invocation of gtest_discover_tests.
6285 TEST_LIST var
6287 Make the list of tests available in the variable var,
6288 rather than the default <target>_TESTS. This can be use‐
6289 ful when the same test executable is being used in multi‐
6290 ple calls to gtest_discover_tests(). Note that this
6291 variable is only available in CTest.
6292 DISCOVERY_TIMEOUT num
6294 Specifies how long (in seconds) CMake will wait for the
6295 test to enumerate available tests. If the test takes
6296 longer than this, discovery (and your build) will fail.
6297 Most test executables will enumerate their tests very
6298 quickly, but under some exceptional circumstances, a test
6299 may require a longer timeout. The default is 5. See
6300 also the TIMEOUT option of execute_process().
6301 NOTE:
6303 In CMake versions 3.10.1 and 3.10.2, this option was
6304 called TIMEOUT. This clashed with the TIMEOUT test
6305 property, which is one of the common properties that
6306 would be set with the PROPERTIES keyword, usually
6307 leading to legal but unintended behavior. The keyword
6308 was changed to DISCOVERY_TIMEOUT in CMake 3.10.3 to
6309 address this problem. The ambiguous behavior of the
6310 TIMEOUT keyword in 3.10.1 and 3.10.2 has not been pre‐
6311 served.
6312 InstallRequiredSystemLibraries
6314 Include this module to search for compiler-provided system runtime
6315 libraries and add install rules for them. Some optional variables may
6316 be set prior to including the module to adjust behavior:
6317 CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS
6319 Specify additional runtime libraries that may not be detected.
6320 After inclusion any detected libraries will be appended to this.
6321 CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS_SKIP
6323 Set to TRUE to skip calling the install(PROGRAMS) command to
6324 allow the includer to specify its own install rule, using the
6325 value of CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS to get the list of
6326 libraries.
6327 CMAKE_INSTALL_DEBUG_LIBRARIES
6329 Set to TRUE to install the debug runtime libraries when avail‐
6330 able with MSVC tools.
6331 CMAKE_INSTALL_DEBUG_LIBRARIES_ONLY
6333 Set to TRUE to install only the debug runtime libraries with
6334 MSVC tools even if the release runtime libraries are also avail‐
6335 able.
6336 CMAKE_INSTALL_UCRT_LIBRARIES
6338 Set to TRUE to install the Windows Universal CRT libraries for
6339 app-local deployment (e.g. to Windows XP). This is meaningful
6340 only with MSVC from Visual Studio 2015 or higher.
6341 One may set a CMAKE_WINDOWS_KITS_10_DIR environment variable to
6343 an absolute path to tell CMake to look for Windows 10 SDKs in a
6344 custom location. The specified directory is expected to contain
6345 Redist/ucrt/DLLs/* directories.
6346 CMAKE_INSTALL_MFC_LIBRARIES
6348 Set to TRUE to install the MSVC MFC runtime libraries.
6349 CMAKE_INSTALL_OPENMP_LIBRARIES
6351 Set to TRUE to install the MSVC OpenMP runtime libraries
6352 CMAKE_INSTALL_SYSTEM_RUNTIME_DESTINATION
6354 Specify the install(PROGRAMS) command DESTINATION option. If
6355 not specified, the default is bin on Windows and lib elsewhere.
6356 CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS_NO_WARNINGS
6358 Set to TRUE to disable warnings about required library files
6359 that do not exist. (For example, Visual Studio Express editions
6360 may not provide the redistributable files.)
6361 CMAKE_INSTALL_SYSTEM_RUNTIME_COMPONENT
6363 Specify the install(PROGRAMS) command COMPONENT option. If not
6364 specified, no such option will be used.
6365 ProcessorCount
6367 ProcessorCount(var)
6368 Determine the number of processors/cores and save value in ${var}
6370 Sets the variable named ${var} to the number of physical cores avail‐
6372 able on the machine if the information can be determined. Otherwise it
6373 is set to 0. Currently this functionality is implemented for AIX, cyg‐
6374 win, FreeBSD, HPUX, Linux, macOS, QNX, Sun and Windows.
6375 This function is guaranteed to return a positive integer (>=1) if it
6377 succeeds. It returns 0 if there’s a problem determining the processor
6378 count.
6379 Example use, in a ctest -S dashboard script:
6381 include(ProcessorCount)
6383 ProcessorCount(N)
6384 if(NOT N EQUAL 0)
6385 set(CTEST_BUILD_FLAGS -j${N})
6386 set(ctest_test_args ${ctest_test_args} PARALLEL_LEVEL ${N})
6387 endif()
6388 This function is intended to offer an approximation of the value of the
6390 number of compute cores available on the current machine, such that you
6391 may use that value for parallel building and parallel testing. It is
6392 meant to help utilize as much of the machine as seems reasonable. Of
6393 course, knowledge of what else might be running on the machine simulta‐
6394 neously should be used when deciding whether to request a machine’s
6395 full capacity all for yourself.
6396 SelectLibraryConfigurations
6398 select_library_configurations(basename)
6399 This macro takes a library base name as an argument, and will choose
6401 good values for the variables
6402 basename_LIBRARY
6404 basename_LIBRARIES
6405 basename_LIBRARY_DEBUG
6406 basename_LIBRARY_RELEASE
6407 depending on what has been found and set.
6409 If only basename_LIBRARY_RELEASE is defined, basename_LIBRARY will be
6411 set to the release value, and basename_LIBRARY_DEBUG will be set to
6412 basename_LIBRARY_DEBUG-NOTFOUND. If only basename_LIBRARY_DEBUG is
6413 defined, then basename_LIBRARY will take the debug value, and base‐
6414 name_LIBRARY_RELEASE will be set to basename_LIBRARY_RELEASE-NOTFOUND.
6415 If the generator supports configuration types, then basename_LIBRARY
6417 and basename_LIBRARIES will be set with debug and optimized flags spec‐
6418 ifying the library to be used for the given configuration. If no build
6419 type has been set or the generator in use does not support configura‐
6420 tion types, then basename_LIBRARY and basename_LIBRARIES will take only
6421 the release value, or the debug value if the release one is not set.
6422 SquishTestScript
6424 This script launches a GUI test using Squish. You should not call the
6425 script directly; instead, you should access it via the SQUISH_ADD_TEST
6426 macro that is defined in FindSquish.cmake.
6427 This script starts the Squish server, launches the test on the client,
6429 and finally stops the squish server. If any of these steps fail
6430 (including if the tests do not pass) then a fatal error is raised.
6431 TestBigEndian
6433 Define macro to determine endian type
6434 Check if the system is big endian or little endian
6436 TEST_BIG_ENDIAN(VARIABLE)
6438 VARIABLE - variable to store the result to
6439 TestForANSIForScope
6441 Check for ANSI for scope support
6442 Check if the compiler restricts the scope of variables declared in a
6444 for-init-statement to the loop body.
6445 CMAKE_NO_ANSI_FOR_SCOPE - holds result
6447 TestForANSIStreamHeaders
6449 Test for compiler support of ANSI stream headers iostream, etc.
6450 check if the compiler supports the standard ANSI iostream header (with‐
6452 out the .h)
6453 CMAKE_NO_ANSI_STREAM_HEADERS - defined by the results
6455 TestForSSTREAM
6457 Test for compiler support of ANSI sstream header
6458 check if the compiler supports the standard ANSI sstream header
6460 CMAKE_NO_ANSI_STRING_STREAM - defined by the results
6462 TestForSTDNamespace
6464 Test for std:: namespace support
6465 check if the compiler supports std:: on stl classes
6467 CMAKE_NO_STD_NAMESPACE - defined by the results
6469 UseEcos
6471 This module defines variables and macros required to build eCos appli‐
6472 cation.
6473 This file contains the following macros: ECOS_ADD_INCLUDE_DIRECTORIES()
6475 - add the eCos include dirs ECOS_ADD_EXECUTABLE(name source1 … sourceN
6476 ) - create an eCos executable ECOS_ADJUST_DIRECTORY(VAR source1 …
6477 sourceN ) - adjusts the path of the source files and puts the result
6478 into VAR
6479 Macros for selecting the toolchain: ECOS_USE_ARM_ELF_TOOLS() - enable
6481 the ARM ELF toolchain for the directory where it is called
6482 ECOS_USE_I386_ELF_TOOLS() - enable the i386 ELF toolchain for the
6483 directory where it is called ECOS_USE_PPC_EABI_TOOLS() - enable the
6484 PowerPC toolchain for the directory where it is called
6485 It contains the following variables: ECOS_DEFINITIONS ECOSCONFIG_EXE‐
6487 CUTABLE ECOS_CONFIG_FILE - defaults to ecos.ecc, if your eCos configu‐
6488 ration file has a different name, adjust this variable for internal use
6489 only:
6490 ECOS_ADD_TARGET_LIB
6492 UseJavaClassFilelist
6494 This script create a list of compiled Java class files to be added to a
6495 jar file. This avoids including cmake files which get created in the
6496 binary directory.
6497 UseJava
6499 Use Module for Java
6500 This file provides functions for Java. It is assumed that Find‐
6502 Java.cmake has already been loaded. See FindJava.cmake for information
6503 on how to load Java into your CMake project.
6504 add_jar(target_name
6506 [SOURCES] source1 [source2 ...] [resource1 ...]
6507 [INCLUDE_JARS jar1 [jar2 ...]]
6508 [ENTRY_POINT entry]
6509 [VERSION version]
6510 [OUTPUT_NAME name]
6511 [OUTPUT_DIR dir]
6512 [GENERATE_NATIVE_HEADERS target [DESTINATION dir]]
6513 )
6514 This command creates a <target_name>.jar. It compiles the given source
6516 files (source) and adds the given resource files (resource) to the jar
6517 file. Source files can be java files or listing files (prefixed by
6518 ‘@’). If only resource files are given then just a jar file is cre‐
6519 ated. The list of include jars are added to the classpath when compil‐
6520 ing the java sources and also to the dependencies of the target.
6521 INCLUDE_JARS also accepts other target names created by add_jar. For
6522 backwards compatibility, jar files listed as sources are ignored (as
6523 they have been since the first version of this module).
6524 The default OUTPUT_DIR can also be changed by setting the variable
6526 CMAKE_JAVA_TARGET_OUTPUT_DIR.
6527 Optionally, using option GENERATE_NATIVE_HEADERS, native header files
6529 can be generated for methods declared as native. These files provide
6530 the connective glue that allow your Java and C code to interact. An
6531 INTERFACE target will be created for an easy usage of generated files.
6532 Sub-option DESTINATION can be used to specify output directory for gen‐
6533 erated header files.
6534 GENERATE_NATIVE_HEADERS option requires, at least, version 1.8 of the
6536 JDK.
6537 Additional instructions:
6539 To add compile flags to the target you can set these flags with
6541 the following variable:
6542 set(CMAKE_JAVA_COMPILE_FLAGS -nowarn)
6544 To add a path or a jar file to the class path you can do this
6546 with the CMAKE_JAVA_INCLUDE_PATH variable.
6547 set(CMAKE_JAVA_INCLUDE_PATH /usr/share/java/shibboleet.jar)
6549 To use a different output name for the target you can set it with:
6551 add_jar(foobar foobar.java OUTPUT_NAME shibboleet.jar)
6553 To use a different output directory than CMAKE_CURRENT_BINARY_DIR
6555 you can set it with:
6556 add_jar(foobar foobar.java OUTPUT_DIR ${PROJECT_BINARY_DIR}/bin)
6558 To define an entry point in your jar you can set it with the ENTRY_POINT
6560 named argument:
6561 add_jar(example ENTRY_POINT com/examples/MyProject/Main)
6563 To define a custom manifest for the jar, you can set it with the manifest
6565 named argument:
6566 add_jar(example MANIFEST /path/to/manifest)
6568 To add a VERSION to the target output name you can set it using
6570 the VERSION named argument to add_jar. This will create a jar file with the
6571 name shibboleet-1.0.0.jar and will create a symlink shibboleet.jar
6572 pointing to the jar with the version information.
6573 add_jar(shibboleet shibbotleet.java VERSION 1.2.0)
6575 If the target is a JNI library, utilize the following commands to
6577 create a JNI symbolic link:
6578 set(CMAKE_JNI_TARGET TRUE)
6580 add_jar(shibboleet shibbotleet.java VERSION 1.2.0)
6581 install_jar(shibboleet ${LIB_INSTALL_DIR}/shibboleet)
6582 install_jni_symlink(shibboleet ${JAVA_LIB_INSTALL_DIR})
6583 If a single target needs to produce more than one jar from its
6585 java source code, to prevent the accumulation of duplicate class
6586 files in subsequent jars, set/reset CMAKE_JAR_CLASSES_PREFIX prior
6587 to calling the add_jar() function:
6588 set(CMAKE_JAR_CLASSES_PREFIX com/redhat/foo)
6590 add_jar(foo foo.java)
6591 set(CMAKE_JAR_CLASSES_PREFIX com/redhat/bar)
6593 add_jar(bar bar.java)
6594 For an optimum usage of option GENERATE_NATIVE_HEADERS, it is recommended to
6596 include module JNI before any call to add_jar. The produced target for native
6597 headers can then be used to compile C/C++ sources with command
6598 target_link_libraries.
6599 find_package(JNI)
6601 add_jar(foo foo.java GENERATE_NATIVE_HEADERS foo-native)
6602 add_library(bar bar.cpp)
6603 target_link_libraries(bar PRIVATE foo-native)
6604 Target Properties:
6606 The add_jar() function sets some target properties. You can get these
6608 properties with the
6609 get_property(TARGET <target_name> PROPERTY <propery_name>)
6610 command.
6611 INSTALL_FILES The files which should be installed. This is used by
6613 install_jar().
6614 JNI_SYMLINK The JNI symlink which should be installed.
6615 This is used by install_jni_symlink().
6616 JAR_FILE The location of the jar file so that you can include
6617 it.
6618 CLASSDIR The directory where the class files can be found. For
6619 example to use them with javah.
6620 find_jar(<VAR>
6622 name | NAMES name1 [name2 ...]
6623 [PATHS path1 [path2 ... ENV var]]
6624 [VERSIONS version1 [version2]]
6625 [DOC "cache documentation string"]
6626 )
6627 This command is used to find a full path to the named jar. A cache
6629 entry named by <VAR> is created to stor the result of this command. If
6630 the full path to a jar is found the result is stored in the variable
6631 and the search will not repeated unless the variable is cleared. If
6632 nothing is found, the result will be <VAR>-NOTFOUND, and the search
6633 will be attempted again next time find_jar is invoked with the same
6634 variable. The name of the full path to a file that is searched for is
6635 specified by the names listed after NAMES argument. Additional search
6636 locations can be specified after the PATHS argument. If you require
6637 special a version of a jar file you can specify it with the VERSIONS
6638 argument. The argument after DOC will be used for the documentation
6639 string in the cache.
6640 install_jar(target_name destination)
6642 install_jar(target_name DESTINATION destination [COMPONENT component])
6643 This command installs the TARGET_NAME files to the given DESTINATION.
6645 It should be called in the same scope as add_jar() or it will fail.
6646 Target Properties:
6648 The install_jar() function sets the INSTALL_DESTINATION target property
6650 on jars so installed. This property holds the DESTINATION as described
6651 above, and is used by install_jar_exports(). You can get this property
6652 with the
6653 get_property(TARGET <target_name> PROPERTY INSTALL_DESTINATION)
6654 command.
6655 install_jni_symlink(target_name destination)
6657 install_jni_symlink(target_name DESTINATION destination [COMPONENT component])
6658 This command installs the TARGET_NAME JNI symlinks to the given DESTI‐
6660 NATION. It should be called in the same scope as add_jar() or it will
6661 fail.
6662 install_jar_exports(TARGETS jars...
6664 [NAMESPACE <namespace>]
6665 FILE <filename>
6666 DESTINATION <dir> [COMPONENT <component>])
6667 This command installs a target export file <filename> for the named jar
6669 targets to the given DESTINATION. Its function is similar to that of
6670 install(EXPORTS ...).
6671 export_jars(TARGETS jars...
6673 [NAMESPACE <namespace>]
6674 FILE <filename>)
6675 This command writes a target export file <filename> for the named jar
6677 targets. Its function is similar to that of export(...).
6678 create_javadoc(<VAR>
6680 PACKAGES pkg1 [pkg2 ...]
6681 [SOURCEPATH <sourcepath>]
6682 [CLASSPATH <classpath>]
6683 [INSTALLPATH <install path>]
6684 [DOCTITLE "the documentation title"]
6685 [WINDOWTITLE "the title of the document"]
6686 [AUTHOR TRUE|FALSE]
6687 [USE TRUE|FALSE]
6688 [VERSION TRUE|FALSE]
6689 )
6690 Create java documentation based on files or packages. For more details
6692 please read the javadoc manpage.
6693 There are two main signatures for create_javadoc. The first signature
6695 works with package names on a path with source files:
6696 Example:
6698 create_javadoc(my_example_doc
6699 PACKAGES com.example.foo com.example.bar
6700 SOURCEPATH "${CMAKE_CURRENT_SOURCE_DIR}"
6701 CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH}
6702 WINDOWTITLE "My example"
6703 DOCTITLE "<h1>My example</h1>"
6704 AUTHOR TRUE
6705 USE TRUE
6706 VERSION TRUE
6707 )
6708 The second signature for create_javadoc works on a given list of files.
6710 create_javadoc(<VAR>
6712 FILES file1 [file2 ...]
6713 [CLASSPATH <classpath>]
6714 [INSTALLPATH <install path>]
6715 [DOCTITLE "the documentation title"]
6716 [WINDOWTITLE "the title of the document"]
6717 [AUTHOR TRUE|FALSE]
6718 [USE TRUE|FALSE]
6719 [VERSION TRUE|FALSE]
6720 )
6721 Example:
6723 create_javadoc(my_example_doc
6725 FILES ${example_SRCS}
6726 CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH}
6727 WINDOWTITLE "My example"
6728 DOCTITLE "<h1>My example</h1>"
6729 AUTHOR TRUE
6730 USE TRUE
6731 VERSION TRUE
6732 )
6733 Both signatures share most of the options. These options are the same
6735 as what you can find in the javadoc manpage. Please look at the man‐
6736 page for CLASSPATH, DOCTITLE, WINDOWTITLE, AUTHOR, USE and VERSION.
6737 The documentation will be by default installed to
6739 ${CMAKE_INSTALL_PREFIX}/share/javadoc/<VAR>
6741 if you don’t set the INSTALLPATH.
6743 create_javah(TARGET <target>
6745 GENERATED_FILES <VAR>
6746 CLASSES <class>...
6747 [CLASSPATH <classpath>...]
6748 [DEPENDS <depend>...]
6749 [OUTPUT_NAME <path>|OUTPUT_DIR <path>]
6750 )
6751 Create C header files from java classes. These files provide the con‐
6753 nective glue that allow your Java and C code to interact.
6754 This command will no longer be supported starting with version 10 of
6756 the JDK due to the suppression of javah tool. Command add_jar(GENER‐
6757 ATE_NATIVE_HEADERS) must be used instead.
6758 There are two main signatures for create_javah. The first signature
6760 returns generated files through variable specified by GENERATED_FILES
6761 option:
6762 Example:
6764 Create_javah(GENERATED_FILES files_headers
6765 CLASSES org.cmake.HelloWorld
6766 CLASSPATH hello.jar
6767 )
6768 The second signature for create_javah creates a target which encapsu‐
6770 lates header files generation.
6771 Example:
6773 Create_javah(TARGET target_headers
6774 CLASSES org.cmake.HelloWorld
6775 CLASSPATH hello.jar
6776 )
6777 Both signatures share same options.
6779 CLASSES <class>...
6781 Specifies Java classes used to generate headers.
6782 CLASSPATH <classpath>...
6784 Specifies various paths to look up classes. Here .class
6785 files, jar files or targets created by command add_jar can be
6786 used.
6787 DEPENDS <depend>...
6789 Targets on which the javah target depends
6790 OUTPUT_NAME <path>
6792 Concatenates the resulting header files for all the classes
6793 listed by option CLASSES into <path>. Same behavior as option
6794 ‘-o’ of javah tool.
6795 OUTPUT_DIR <path>
6797 Sets the directory where the header files will be generated.
6798 Same behavior as option ‘-d’ of javah tool. If not specified,
6799 ${CMAKE_CURRENT_BINARY_DIR} is used as output directory.
6800 UseJavaSymlinks
6802 Helper script for UseJava.cmake
6803 UseSWIG
6805 This file provides support for SWIG. It is assumed that FindSWIG module
6806 has already been loaded.
6807 Defines the following command for use with SWIG:
6809 swig_add_library
6811 Define swig module with given name and specified language:
6812 swig_add_library(<name>
6814 [TYPE <SHARED|MODULE|STATIC|USE_BUILD_SHARED_LIBS>]
6815 LANGUAGE <language>
6816 [NO_PROXY]
6817 [OUTPUT_DIR <directory>]
6818 [OUTFILE_DIR <directory>]
6819 SOURCES <file>...
6820 )
6821 Targets created with the swig_add_library command have the same
6823 capabilities as targets created with the add_library() command,
6824 so those targets can be used with any command expecting a target
6825 (e.g. target_link_libraries()).
6826 NOTE:
6828 This command creates a target with the specified <name> when
6829 policy CMP0078 is set to NEW. Otherwise, the legacy behavior
6830 will choose a different target name and store it in the
6831 SWIG_MODULE_<name>_REAL_NAME variable.
6832 NOTE:
6834 For multi-config generators, this module does not support
6835 configuration-specific files generated by SWIG. All build
6836 configurations must result in the same generated source file.
6837 TYPE SHARED, MODULE and STATIC have the same semantic as for
6839 the add_library() command. If USE_BUILD_SHARED_LIBS is
6840 specified, the library type will be STATIC or SHARED
6841 based on whether the current value of the
6842 BUILD_SHARED_LIBS variable is ON. If no type is speci‐
6843 fied, MODULE will be used.
6844 LANGUAGE
6846 Specify the target language.
6847 NO_PROXY
6849 Prevent the generation of the wrapper layer (swig
6850 -noproxy option).
6851 OUTPUT_DIR
6853 Specify where to write the language specific files (swig
6854 -outdir option). If not given, the CMAKE_SWIG_OUTDIR
6855 variable will be used. If neither is specified, the
6856 default depends on the value of the UseSWIG_MODULE_VER‐
6857 SION variable as follows:
6858 · If UseSWIG_MODULE_VERSION is 1 or is undefined, output
6860 is written to the CMAKE_CURRENT_BINARY_DIR directory.
6861 · If UseSWIG_MODULE_VERSION is 2, a dedicated directory
6863 will be used. The path of this directory can be
6864 retrieved from the SWIG_SUPPORT_FILES_DIRECTORY target
6865 property.
6866 OUTFILE_DIR
6868 Specify an output directory name where the generated
6869 source file will be placed (swig -o option). If not spec‐
6870 ified, the SWIG_OUTFILE_DIR variable will be used. If
6871 neither is specified, OUTPUT_DIR or CMAKE_SWIG_OUTDIR is
6872 used instead.
6873 SOURCES
6875 List of sources for the library. Files with extension .i
6876 will be identified as sources for the SWIG tool. Other
6877 files will be handled in the standard way. This behavior
6878 can be overriden by specifying the variable
6879 SWIG_SOURCE_FILE_EXTENSIONS.
6880 NOTE:
6882 If UseSWIG_MODULE_VERSION is set to 2, it is strongly recom‐
6883 mended to use a dedicated directory unique to the target when
6884 either the OUTPUT_DIR option or the CMAKE_SWIG_OUTDIR vari‐
6885 able are specified. The output directory contents are erased
6886 as part of the target build, so to prevent interference
6887 between targets or losing other important files, each target
6888 should have its own dedicated output directory.
6889 swig_link_libraries
6891 Link libraries to swig module:
6892 swig_link_libraries(<name> <item>...)
6894 This command has same capabilities as target_link_libraries()
6896 command.
6897 NOTE:
6899 If variable UseSWIG_TARGET_NAME_PREFERENCE is set to STAN‐
6900 DARD, this command is deprecated and target_link_libraries()
6901 command must be used instead.
6902 Source file properties on module files must be set before the invoca‐
6904 tion of the swig_add_library command to specify special behavior of
6905 SWIG and ensure generated files will receive the required settings.
6906 CPLUSPLUS
6908 Call SWIG in c++ mode. For example:
6909 set_property(SOURCE mymod.i PROPERTY CPLUSPLUS ON)
6911 swig_add_library(mymod LANGUAGE python SOURCES mymod.i)
6912 INCLUDE_DIRECTORIES, COMPILE_DEFINITIONS and COMPILE_OPTIONS
6914 Add custom flags to SWIG compiler and have same semantic as
6915 properties INCLUDE_DIRECTORIES, COMPILE_DEFINITIONS and COM‐
6916 PILE_OPTIONS.
6917 USE_TARGET_INCLUDE_DIRECTORIES
6919 If set to TRUE, contents of target property INCLUDE_DIRECTORIES
6920 will be forwarded to SWIG compiler. If set to FALSE target
6921 property INCLUDE_DIRECTORIES will be ignored. If not set, target
6922 property SWIG_USE_TARGET_INCLUDE_DIRECTORIES will be considered.
6923 GENERATED_INCLUDE_DIRECTORIES, GENERATED_COMPILE_DEFINITIONS and GENER‐
6925 ATED_COMPILE_OPTIONS
6926 Add custom flags to the C/C++ generated source. They will fill,
6927 respectively, properties INCLUDE_DIRECTORIES, COMPILE_DEFINI‐
6928 TIONS and COMPILE_OPTIONS of generated C/C++ file.
6929 DEPENDS
6931 Specify additional dependencies to the source file.
6932 SWIG_MODULE_NAME
6934 Specify the actual import name of the module in the target lan‐
6935 guage. This is required if it cannot be scanned automatically
6936 from source or different from the module file basename. For
6937 example:
6938 set_property(SOURCE mymod.i PROPERTY SWIG_MODULE_NAME mymod_realname)
6940 NOTE:
6942 If policy CMP0086 is set to NEW, -module <module_name> is
6943 passed to SWIG compiler.
6944 Target library properties can be set to apply same configuration to all
6946 SWIG input files.
6947 SWIG_INCLUDE_DIRECTORIES, SWIG_COMPILE_DEFINITIONS and SWIG_COM‐
6949 PILE_OPTIONS
6950 These properties will be applied to all SWIG input files and
6951 have same semantic as target properties INCLUDE_DIRECTORIES,
6952 COMPILE_DEFINITIONS and COMPILE_OPTIONS.
6953 set (UseSWIG_TARGET_NAME_PREFERENCE STANDARD)
6955 swig_add_library(mymod LANGUAGE python SOURCES mymod.i)
6956 set_property(TARGET mymod PROPERTY SWIG_COMPILE_DEFINITIONS MY_DEF1 MY_DEF2)
6957 set_property(TARGET mymod PROPERTY SWIG_COMPILE_OPTIONS -bla -blb)
6958 SWIG_USE_TARGET_INCLUDE_DIRECTORIES
6960 If set to TRUE, contents of target property INCLUDE_DIRECTORIES
6961 will be forwarded to SWIG compiler. If set to FALSE or not
6962 defined, target property INCLUDE_DIRECTORIES will be ignored.
6963 This behavior can be overridden by specifying source property
6964 USE_TARGET_INCLUDE_DIRECTORIES.
6965 SWIG_GENERATED_INCLUDE_DIRECTORIES, SWIG_GENERATED_COMPILE_DEFINITIONS
6967 and SWIG_GENERATED_COMPILE_OPTIONS
6968 These properties will populate, respectively, properties
6969 INCLUDE_DIRECTORIES, COMPILE_DEFINITIONS and COMPILE_FLAGS of
6970 all generated C/C++ files.
6971 SWIG_DEPENDS
6973 Add dependencies to all SWIG input files.
6974 The following target properties are output properties and can be used
6976 to get information about support files generated by SWIG interface com‐
6977 pilation.
6978 SWIG_SUPPORT_FILES
6980 This output property list of wrapper files generated during SWIG
6981 compilation.
6982 set (UseSWIG_TARGET_NAME_PREFERENCE STANDARD)
6984 swig_add_library(mymod LANGUAGE python SOURCES mymod.i)
6985 get_property(support_files TARGET mymod PROPERTY SWIG_SUPPORT_FILES)
6986 NOTE:
6988 Only most principal support files are listed. In case some
6989 advanced features of SWIG are used (for example %template),
6990 associated support files may not be listed. Prefer to use the
6991 SWIG_SUPPORT_FILES_DIRECTORY property to handle support
6992 files.
6993 SWIG_SUPPORT_FILES_DIRECTORY
6995 This output property specifies the directory where support files
6996 will be generated.
6997 Some variables can be set to customize the behavior of swig_add_library
6999 as well as SWIG:
7000 UseSWIG_MODULE_VERSION
7002 Specify different behaviors for UseSWIG module.
7003 · Set to 1 or undefined: Legacy behavior is applied.
7005 · Set to 2: A new strategy is applied regarding support files:
7007 the output directory of support files is erased before SWIG
7008 interface compilation.
7009 CMAKE_SWIG_FLAGS
7011 Add flags to all swig calls.
7012 CMAKE_SWIG_OUTDIR
7014 Specify where to write the language specific files (swig -outdir
7015 option).
7016 SWIG_OUTFILE_DIR
7018 Specify an output directory name where the generated source file
7019 will be placed. If not specified, CMAKE_SWIG_OUTDIR is used.
7020 SWIG_MODULE_<name>_EXTRA_DEPS
7022 Specify extra dependencies for the generated module for <name>.
7023 SWIG_SOURCE_FILE_EXTENSIONS
7025 Specify a list of source file extensions to override the default
7026 behavior of considering only .i files as sources for the SWIG
7027 tool. For example:
7028 set(SWIG_SOURCE_FILE_EXTENSIONS ".i" ".swg")
7030 UsewxWidgets
7032 Convenience include for using wxWidgets library.
7033 Determines if wxWidgets was FOUND and sets the appropriate libs,
7035 incdirs, flags, etc. INCLUDE_DIRECTORIES and LINK_DIRECTORIES are
7036 called.
7037 USAGE
7039 # Note that for MinGW users the order of libs is important!
7041 find_package(wxWidgets REQUIRED net gl core base)
7042 include(${wxWidgets_USE_FILE})
7043 # and for each of your dependent executable/library targets:
7044 target_link_libraries(<YourTarget> ${wxWidgets_LIBRARIES})
7045 DEPRECATED
7047 LINK_LIBRARIES is not called in favor of adding dependencies per target.
7049 AUTHOR
7051 Jan Woetzel <jw -at- mip.informatik.uni-kiel.de>
7053 WriteCompilerDetectionHeader
7055 This module provides the function write_compiler_detection_header().
7056 This function can be used to generate a file suitable for preprocessor
7058 inclusion which contains macros to be used in source code:
7059 write_compiler_detection_header(
7061 FILE <file>
7062 PREFIX <prefix>
7063 [OUTPUT_FILES_VAR <output_files_var> OUTPUT_DIR <output_dir>]
7064 COMPILERS <compiler> [...]
7065 FEATURES <feature> [...]
7066 [BARE_FEATURES <feature> [...]]
7067 [VERSION <version>]
7068 [PROLOG <prolog>]
7069 [EPILOG <epilog>]
7070 [ALLOW_UNKNOWN_COMPILERS]
7071 [ALLOW_UNKNOWN_COMPILER_VERSIONS]
7072 )
7073 This generates the file <file> with macros which all have the prefix
7075 <prefix>.
7076 By default, all content is written directly to the <file>. The OUT‐
7078 PUT_FILES_VAR may be specified to cause the compiler-specific content
7079 to be written to separate files. The separate files are then available
7080 in the <output_files_var> and may be consumed by the caller for instal‐
7081 lation for example. The OUTPUT_DIR specifies a relative path from the
7082 main <file> to the compiler-specific files. For example:
7083 write_compiler_detection_header(
7085 FILE climbingstats_compiler_detection.h
7086 PREFIX ClimbingStats
7087 OUTPUT_FILES_VAR support_files
7088 OUTPUT_DIR compilers
7089 COMPILERS GNU Clang MSVC Intel
7090 FEATURES cxx_variadic_templates
7091 )
7092 install(FILES
7093 ${CMAKE_CURRENT_BINARY_DIR}/climbingstats_compiler_detection.h
7094 DESTINATION include
7095 )
7096 install(FILES
7097 ${support_files}
7098 DESTINATION include/compilers
7099 )
7100 VERSION may be used to specify the API version to be generated. Future
7102 versions of CMake may introduce alternative APIs. A given API is
7103 selected by any <version> value greater than or equal to the version of
7104 CMake that introduced the given API and less than the version of CMake
7105 that introduced its succeeding API. The value of the CMAKE_MINI‐
7106 MUM_REQUIRED_VERSION variable is used if no explicit version is speci‐
7107 fied. (As of CMake version 3.14.5 there is only one API version.)
7108 PROLOG may be specified as text content to write at the start of the
7110 header. EPILOG may be specified as text content to write at the end of
7111 the header
7112 At least one <compiler> and one <feature> must be listed. Compilers
7114 which are known to CMake, but not specified are detected and a pre‐
7115 processor #error is generated for them. A preprocessor macro matching
7116 <PREFIX>_COMPILER_IS_<compiler> is generated for each compiler known to
7117 CMake to contain the value 0 or 1.
7118 Possible compiler identifiers are documented with the CMAKE_<LANG>_COM‐
7120 PILER_ID variable. Available features in this version of CMake are
7121 listed in the CMAKE_C_KNOWN_FEATURES and CMAKE_CXX_KNOWN_FEATURES
7122 global properties. The {c,cxx}_std_* meta-features are ignored if
7123 requested.
7124 See the cmake-compile-features(7) manual for information on compile
7126 features.
7127 BARE_FEATURES will define the compatibility macros with the name used
7129 in newer versions of the language standard, so the code can use the new
7130 feature name unconditionally.
7131 ALLOW_UNKNOWN_COMPILERS and ALLOW_UNKNOWN_COMPILER_VERSIONS cause the
7133 module to generate conditions that treat unknown compilers as simply
7134 lacking all features. Without these options the default behavior is to
7135 generate a #error for unknown compilers and versions.
7136 Feature Test Macros
7138 For each compiler, a preprocessor macro is generated matching <PRE‐
7139 FIX>_COMPILER_IS_<compiler> which has the content either 0 or 1,
7140 depending on the compiler in use. Preprocessor macros for compiler ver‐
7141 sion components are generated matching <PREFIX>_COMPILER_VERSION_MAJOR
7142 <PREFIX>_COMPILER_VERSION_MINOR and <PREFIX>_COMPILER_VERSION_PATCH
7143 containing decimal values for the corresponding compiler version compo‐
7144 nents, if defined.
7145 A preprocessor test is generated based on the compiler version denoting
7147 whether each feature is enabled. A preprocessor macro matching <PRE‐
7148 FIX>_COMPILER_<FEATURE>, where <FEATURE> is the upper-case <feature>
7149 name, is generated to contain the value 0 or 1 depending on whether the
7150 compiler in use supports the feature:
7151 write_compiler_detection_header(
7153 FILE climbingstats_compiler_detection.h
7154 PREFIX ClimbingStats
7155 COMPILERS GNU Clang AppleClang MSVC Intel
7156 FEATURES cxx_variadic_templates
7157 )
7158 #if ClimbingStats_COMPILER_CXX_VARIADIC_TEMPLATES
7160 template<typename... T>
7161 void someInterface(T t...) { /* ... */ }
7162 #else
7163 // Compatibility versions
7164 template<typename T1>
7165 void someInterface(T1 t1) { /* ... */ }
7166 template<typename T1, typename T2>
7167 void someInterface(T1 t1, T2 t2) { /* ... */ }
7168 template<typename T1, typename T2, typename T3>
7169 void someInterface(T1 t1, T2 t2, T3 t3) { /* ... */ }
7170 #endif
7171 Symbol Macros
7173 Some additional symbol-defines are created for particular features for
7174 use as symbols which may be conditionally defined empty:
7175 class MyClass ClimbingStats_FINAL
7177 {
7178 ClimbingStats_CONSTEXPR int someInterface() { return 42; }
7179 };
7180 The ClimbingStats_FINAL macro will expand to final if the compiler (and
7182 its flags) support the cxx_final feature, and the ClimbingStats_CONST‐
7183 EXPR macro will expand to constexpr if cxx_constexpr is supported.
7184 If BARE_FEATURES cxx_final was given as argument the final keyword will
7186 be defined for old compilers, too.
7187 The following features generate corresponding symbol defines and if
7189 they are available as BARE_FEATURES:
7190 ┌──────────────────┬────────────────────┬─────────────┬──────┐
7192 │Feature │ Define │ Symbol │ bare │
7193 ├──────────────────┼────────────────────┼─────────────┼──────┤
7194 │c_restrict │ <PRE‐ │ restrict │ yes │
7195 │ │ FIX>_RESTRICT │ │ │
7196 ├──────────────────┼────────────────────┼─────────────┼──────┤
7197 │cxx_constexpr │ <PREFIX>_CONST‐ │ constexpr │ yes │
7198 │ │ EXPR │ │ │
7199 ├──────────────────┼────────────────────┼─────────────┼──────┤
7200 │cxx_deleted_func‐ │ <PRE‐ │ = delete │ │
7201 │tions │ FIX>_DELETED_FUNC‐ │ │ │
7202 │ │ TION │ │ │
7203 ├──────────────────┼────────────────────┼─────────────┼──────┤
7204 │cxx_extern_tem‐ │ <PRE‐ │ extern │ │
7205 │plates │ FIX>_EXTERN_TEM‐ │ │ │
7206 │ │ PLATE │ │ │
7207 ├──────────────────┼────────────────────┼─────────────┼──────┤
7208 │cxx_final │ <PREFIX>_FINAL │ final │ yes │
7209 ├──────────────────┼────────────────────┼─────────────┼──────┤
7210 │cxx_noexcept │ <PREFIX>_NOEXCEPT │ noexcept │ yes │
7211 ├──────────────────┼────────────────────┼─────────────┼──────┤
7212 │cxx_noexcept │ <PREFIX>_NOEX‐ │ noexcept(X) │ │
7213 │ │ CEPT_EXPR(X) │ │ │
7214 ├──────────────────┼────────────────────┼─────────────┼──────┤
7215 │cxx_override │ <PREFIX>_OVERRIDE │ override │ yes │
7216 └──────────────────┴────────────────────┴─────────────┴──────┘
7217 Compatibility Implementation Macros
7219 Some features are suitable for wrapping in a macro with a backward com‐
7220 patibility implementation if the compiler does not support the feature.
7221 When the cxx_static_assert feature is not provided by the compiler, a
7223 compatibility implementation is available via the <PRE‐
7224 FIX>_STATIC_ASSERT(COND) and <PREFIX>_STATIC_ASSERT_MSG(COND, MSG)
7225 function-like macros. The macros expand to static_assert where that
7226 compiler feature is available, and to a compatibility implementation
7227 otherwise. In the first form, the condition is stringified in the mes‐
7228 sage field of static_assert. In the second form, the message MSG is
7229 passed to the message field of static_assert, or ignored if using the
7230 backward compatibility implementation.
7231 The cxx_attribute_deprecated feature provides a macro definition <PRE‐
7233 FIX>_DEPRECATED, which expands to either the standard [[deprecated]]
7234 attribute or a compiler-specific decorator such as
7235 __attribute__((__deprecated__)) used by GNU compilers.
7236 The cxx_alignas feature provides a macro definition <PREFIX>_ALIGNAS
7238 which expands to either the standard alignas decorator or a com‐
7239 piler-specific decorator such as __attribute__ ((__aligned__)) used by
7240 GNU compilers.
7241 The cxx_alignof feature provides a macro definition <PREFIX>_ALIGNOF
7243 which expands to either the standard alignof decorator or a com‐
7244 piler-specific decorator such as __alignof__ used by GNU compilers.
7245 ┌───────────────────┬────────────────────────┬────────────────┬──────┐
7247 │Feature │ Define │ Symbol │ bare │
7248 ├───────────────────┼────────────────────────┼────────────────┼──────┤
7249 │cxx_alignas │ <PREFIX>_ALIGNAS │ alignas │ │
7250 ├───────────────────┼────────────────────────┼────────────────┼──────┤
7251 │cxx_alignof │ <PREFIX>_ALIGNOF │ alignof │ │
7252 ├───────────────────┼────────────────────────┼────────────────┼──────┤
7253 │cxx_nullptr │ <PREFIX>_NULLPTR │ nullptr │ yes │
7254 ├───────────────────┼────────────────────────┼────────────────┼──────┤
7255 │cxx_static_assert │ <PRE‐ │ static_assert │ │
7256 │ │ FIX>_STATIC_ASSERT │ │ │
7257 └───────────────────┴────────────────────────┴────────────────┴──────┘
7258 │cxx_static_assert │ <PRE‐ │ static_assert │ │
7260 │ │ FIX>_STATIC_ASSERT_MSG │ │ │
7261 ├───────────────────┼────────────────────────┼────────────────┼──────┤
7262 │cxx_attribute_dep‐ │ <PREFIX>_DEPRECATED │ [[deprecated]] │ │
7263 │recated │ │ │ │
7264 ├───────────────────┼────────────────────────┼────────────────┼──────┤
7265 │cxx_attribute_dep‐ │ <PREFIX>_DEPRE‐ │ [[deprecated]] │ │
7266 │recated │ CATED_MSG │ │ │
7267 ├───────────────────┼────────────────────────┼────────────────┼──────┤
7268 │cxx_thread_local │ <PREFIX>_THREAD_LOCAL │ thread_local │ │
7269 └───────────────────┴────────────────────────┴────────────────┴──────┘
7270 A use-case which arises with such deprecation macros is the deprecation
7272 of an entire library. In that case, all public API in the library may
7273 be decorated with the <PREFIX>_DEPRECATED macro. This results in very
7274 noisy build output when building the library itself, so the macro may
7275 be may be defined to empty in that case when building the deprecated
7276 library:
7277 add_library(compat_support ${srcs})
7279 target_compile_definitions(compat_support
7280 PRIVATE
7281 CompatSupport_DEPRECATED=
7282 )
7283
7285 These modules search for third-party software. They are normally
7286 called through the find_package() command.
7287 FindALSA
7289 Find alsa
7290 Find the alsa libraries (asound)
7292 IMPORTED Targets
7294 This module defines IMPORTED target ALSA::ALSA, if ALSA has been found.
7295 Result Variables
7297 This module defines the following variables:
7298 ALSA_FOUND
7300 True if ALSA_INCLUDE_DIR & ALSA_LIBRARY are found
7301 ALSA_LIBRARIES
7303 List of libraries when using ALSA.
7304 ALSA_INCLUDE_DIRS
7306 Where to find the ALSA headers.
7307 Cache variables
7309 The following cache variables may also be set:
7310 ALSA_INCLUDE_DIR
7312 the ALSA include directory
7313 ALSA_LIBRARY
7315 the absolute path of the asound library
7316 FindArmadillo
7318 Find Armadillo
7319 Find the Armadillo C++ library
7321 Using Armadillo:
7323 find_package(Armadillo REQUIRED)
7325 include_directories(${ARMADILLO_INCLUDE_DIRS})
7326 add_executable(foo foo.cc)
7327 target_link_libraries(foo ${ARMADILLO_LIBRARIES})
7328 This module sets the following variables:
7330 ARMADILLO_FOUND - set to true if the library is found
7332 ARMADILLO_INCLUDE_DIRS - list of required include directories
7333 ARMADILLO_LIBRARIES - list of libraries to be linked
7334 ARMADILLO_VERSION_MAJOR - major version number
7335 ARMADILLO_VERSION_MINOR - minor version number
7336 ARMADILLO_VERSION_PATCH - patch version number
7337 ARMADILLO_VERSION_STRING - version number as a string (ex: "1.0.4")
7338 ARMADILLO_VERSION_NAME - name of the version (ex: "Antipodean Antileech")
7339 FindASPELL
7341 Try to find ASPELL
7342 Once done this will define
7344 ASPELL_FOUND - system has ASPELL
7346 ASPELL_EXECUTABLE - the ASPELL executable
7347 ASPELL_INCLUDE_DIR - the ASPELL include directory
7348 ASPELL_LIBRARIES - The libraries needed to use ASPELL
7349 ASPELL_DEFINITIONS - Compiler switches required for using ASPELL
7350 FindAVIFile
7352 Locate AVIFILE library and include paths
7353 AVIFILE (http://avifile.sourceforge.net/)is a set of libraries for i386
7355 machines to use various AVI codecs. Support is limited beyond Linux.
7356 Windows provides native AVI support, and so doesn’t need this library.
7357 This module defines
7358 AVIFILE_INCLUDE_DIR, where to find avifile.h , etc.
7360 AVIFILE_LIBRARIES, the libraries to link against
7361 AVIFILE_DEFINITIONS, definitions to use when compiling
7362 AVIFILE_FOUND, If false, don't try to use AVIFILE
7363 FindBISON
7365 Find bison executable and provide a macro to generate custom build
7366 rules.
7367 The module defines the following variables:
7369 BISON_EXECUTABLE
7371 path to the bison program
7372 BISON_VERSION
7374 version of bison
7375 BISON_FOUND
7377 true if the program was found
7378 The minimum required version of bison can be specified using the stan‐
7380 dard CMake syntax, e.g. find_package(BISON 2.1.3).
7381 If bison is found, the module defines the macro:
7383 BISON_TARGET(<Name> <YaccInput> <CodeOutput>
7385 [COMPILE_FLAGS <flags>]
7386 [DEFINES_FILE <file>]
7387 [VERBOSE [<file>]]
7388 [REPORT_FILE <file>]
7389 )
7390 which will create a custom rule to generate a parser. <YaccInput> is
7392 the path to a yacc file. <CodeOutput> is the name of the source file
7393 generated by bison. A header file is also be generated, and contains
7394 the token list.
7395 The options are:
7397 COMPILE_FLAGS <flags>
7399 Specify flags to be added to the bison command line.
7400 DEFINES_FILE <file>
7402 Specify a non-default header <file> to be generated by bison.
7403 VERBOSE [<file>]
7405 Tell bison to write a report file of the grammar and parser. If
7406 <file> is given, it specifies path the report file is copied to.
7407 [<file>] is left for backward compatibility of this module. Use
7408 VERBOSE REPORT_FILE <file>.
7409 REPORT_FILE <file>
7411 Specify a non-default report <file>, if generated.
7412 The macro defines the following variables:
7414 BISON_<Name>_DEFINED
7416 true is the macro ran successfully
7417 BISON_<Name>_INPUT
7419 The input source file, an alias for <YaccInput>
7420 BISON_<Name>_OUTPUT_SOURCE
7422 The source file generated by bison
7423 BISON_<Name>_OUTPUT_HEADER
7425 The header file generated by bison
7426 BISON_<Name>_OUTPUTS
7428 All files generated by bison including the source, the header
7429 and the report
7430 BISON_<Name>_COMPILE_FLAGS
7432 Options used in the bison command line
7433 Example usage:
7435 find_package(BISON)
7437 BISON_TARGET(MyParser parser.y ${CMAKE_CURRENT_BINARY_DIR}/parser.cpp
7438 DEFINES_FILE ${CMAKE_CURRENT_BINARY_DIR}/parser.h)
7439 add_executable(Foo main.cpp ${BISON_MyParser_OUTPUTS})
7440 FindBLAS
7442 Find BLAS library
7443 This module finds an installed fortran library that implements the BLAS
7445 linear-algebra interface (see http://www.netlib.org/blas/). The list
7446 of libraries searched for is taken from the autoconf macro file,
7447 acx_blas.m4 (distributed at
7448 http://ac-archive.sourceforge.net/ac-archive/acx_blas.html).
7449 Input Variables
7451 The following variables may be set to influence this module’s behavior:
7452 BLA_STATIC
7454 if ON use static linkage
7455 BLA_VENDOR
7457 If set, checks only the specified vendor, if not set checks all
7458 the possibilities. List of vendors valid in this module:
7459 · Goto
7461 · OpenBLAS
7463 · FLAME
7465 · ATLAS PhiPACK
7467 · CXML
7469 · DXML
7471 · SunPerf
7473 · SCSL
7475 · SGIMATH
7477 · IBMESSL
7479 · Intel10_32 (intel mkl v10 32 bit)
7481 · Intel10_64lp (intel mkl v10+ 64 bit, threaded code, lp64
7483 model)
7484 · Intel10_64lp_seq (intel mkl v10+ 64 bit, sequential code, lp64
7486 model)
7487 · Intel10_64ilp (intel mkl v10+ 64 bit, threaded code, ilp64
7489 model)
7490 · Intel10_64ilp_seq (intel mkl v10+ 64 bit, sequential code,
7492 ilp64 model)
7493 · Intel (obsolete versions of mkl 32 and 64 bit)
7495 · ACML
7497 · ACML_MP
7499 · ACML_GPU
7501 · Apple
7503 · NAS
7505 · Generic
7507 BLA_F95
7509 if ON tries to find the BLAS95 interfaces
7510 BLA_PREFER_PKGCONFIG
7512 if set pkg-config will be used to search for a BLAS library
7513 first and if one is found that is preferred
7514 Result Variables
7516 This module defines the following variables:
7517 BLAS_FOUND
7519 library implementing the BLAS interface is found
7520 BLAS_LINKER_FLAGS
7522 uncached list of required linker flags (excluding -l and -L).
7523 BLAS_LIBRARIES
7525 uncached list of libraries (using full path name) to link
7526 against to use BLAS (may be empty if compiler implicitly links
7527 BLAS)
7528 BLAS95_LIBRARIES
7530 uncached list of libraries (using full path name) to link
7531 against to use BLAS95 interface
7532 BLAS95_FOUND
7534 library implementing the BLAS95 interface is found
7535 NOTE:
7537 C or CXX must be enabled to use Intel MKL
7538 For example, to use Intel MKL libraries and/or Intel compiler:
7540 set(BLA_VENDOR Intel10_64lp)
7542 find_package(BLAS)
7543 FindBacktrace
7545 Find provider for backtrace(3).
7546 Checks if OS supports backtrace(3) via either libc or custom library.
7548 This module defines the following variables:
7549 Backtrace_HEADER
7551 The header file needed for backtrace(3). Cached. Could be
7552 forcibly set by user.
7553 Backtrace_INCLUDE_DIRS
7555 The include directories needed to use backtrace(3) header.
7556 Backtrace_LIBRARIES
7558 The libraries (linker flags) needed to use backtrace(3), if any.
7559 Backtrace_FOUND
7561 Is set if and only if backtrace(3) support detected.
7562 The following cache variables are also available to set or use:
7564 Backtrace_LIBRARY
7566 The external library providing backtrace, if any.
7567 Backtrace_INCLUDE_DIR
7569 The directory holding the backtrace(3) header.
7570 Typical usage is to generate of header file using configure_file() with
7572 the contents like the following:
7573 #cmakedefine01 Backtrace_FOUND
7575 #if Backtrace_FOUND
7576 # include <${Backtrace_HEADER}>
7577 #endif
7578 And then reference that generated header file in actual source.
7580 FindBoost
7582 Find Boost include dirs and libraries
7583 Use this module by invoking find_package with the form:
7585 find_package(Boost
7587 [version] [EXACT] # Minimum or EXACT version e.g. 1.67.0
7588 [REQUIRED] # Fail with error if Boost is not found
7589 [COMPONENTS <libs>...] # Boost libraries by their canonical name
7590 # e.g. "date_time" for "libboost_date_time"
7591 [OPTIONAL_COMPONENTS <libs>...]
7592 # Optional Boost libraries by their canonical name)
7593 ) # e.g. "date_time" for "libboost_date_time"
7594 This module finds headers and requested component libraries OR a CMake
7596 package configuration file provided by a “Boost CMake” build. For the
7597 latter case skip to the “Boost CMake” section below. For the former
7598 case results are reported in variables:
7599 Boost_FOUND - True if headers and requested libraries were found
7601 Boost_INCLUDE_DIRS - Boost include directories
7602 Boost_LIBRARY_DIRS - Link directories for Boost libraries
7603 Boost_LIBRARIES - Boost component libraries to be linked
7604 Boost_<C>_FOUND - True if component <C> was found (<C> is upper-case)
7605 Boost_<C>_LIBRARY - Libraries to link for component <C> (may include
7606 target_link_libraries debug/optimized keywords)
7607 Boost_VERSION - BOOST_VERSION value from boost/version.hpp
7608 Boost_LIB_VERSION - Version string appended to library filenames
7609 Boost_MAJOR_VERSION - Boost major version number (X in X.y.z)
7610 Boost_MINOR_VERSION - Boost minor version number (Y in x.Y.z)
7611 Boost_SUBMINOR_VERSION - Boost subminor version number (Z in x.y.Z)
7612 Boost_VERSION_STRING - Boost version number in x.y.z format
7613 Boost_LIB_DIAGNOSTIC_DEFINITIONS (Windows)
7614 - Pass to add_definitions() to have diagnostic
7615 information about Boost's automatic linking
7616 displayed during compilation
7617 Note that Boost Python components require a Python version suffix
7619 (Boost 1.67 and later), e.g. python36 or python27 for the versions
7620 built against Python 3.6 and 2.7, respectively. This also applies to
7621 additional components using Python including mpi_python and numpy.
7622 Earlier Boost releases may use distribution-specific suffixes such as
7623 2, 3 or 2.7. These may also be used as suffixes, but note that they
7624 are not portable.
7625 This module reads hints about search locations from variables:
7627 BOOST_ROOT - Preferred installation prefix
7629 (or BOOSTROOT)
7630 BOOST_INCLUDEDIR - Preferred include directory e.g. <prefix>/include
7631 BOOST_LIBRARYDIR - Preferred library directory e.g. <prefix>/lib
7632 Boost_NO_SYSTEM_PATHS - Set to ON to disable searching in locations not
7633 specified by these hint variables. Default is OFF.
7634 Boost_ADDITIONAL_VERSIONS
7635 - List of Boost versions not known to this module
7636 (Boost install locations may contain the version)
7637 and saves search results persistently in CMake cache entries:
7639 Boost_INCLUDE_DIR - Directory containing Boost headers
7641 Boost_LIBRARY_DIR_RELEASE - Directory containing release Boost libraries
7642 Boost_LIBRARY_DIR_DEBUG - Directory containing debug Boost libraries
7643 Boost_<C>_LIBRARY_DEBUG - Component <C> library debug variant
7644 Boost_<C>_LIBRARY_RELEASE - Component <C> library release variant
7645 The following IMPORTED targets are also defined:
7647 Boost::boost - Target for header-only dependencies
7649 (Boost include directory)
7650 Boost::<C> - Target for specific component dependency
7651 (shared or static library); <C> is lower-
7652 case
7653 Boost::diagnostic_definitions - interface target to enable diagnostic
7654 information about Boost's automatic linking
7655 during compilation (adds BOOST_LIB_DIAGNOSTIC)
7656 Boost::disable_autolinking - interface target to disable automatic
7657 linking with MSVC (adds BOOST_ALL_NO_LIB)
7658 Boost::dynamic_linking - interface target to enable dynamic linking
7659 linking with MSVC (adds BOOST_ALL_DYN_LINK)
7660 Implicit dependencies such as Boost::filesystem requiring Boost::system
7662 will be automatically detected and satisfied, even if system is not
7663 specified when using find_package and if Boost::system is not added to
7664 target_link_libraries. If using Boost::thread, then Threads::Threads
7665 will also be added automatically.
7666 It is important to note that the imported targets behave differently
7668 than variables created by this module: multiple calls to find_pack‐
7669 age(Boost) in the same directory or sub-directories with different
7670 options (e.g. static or shared) will not override the values of the
7671 targets created by the first call.
7672 Users may set these hints or results as cache entries. Projects should
7674 not read these entries directly but instead use the above result vari‐
7675 ables. Note that some hint names start in upper-case “BOOST”. One may
7676 specify these as environment variables if they are not specified as
7677 CMake variables or cache entries.
7678 This module first searches for the Boost header files using the above
7680 hint variables (excluding BOOST_LIBRARYDIR) and saves the result in
7681 Boost_INCLUDE_DIR. Then it searches for requested component libraries
7682 using the above hints (excluding BOOST_INCLUDEDIR and Boost_ADDI‐
7683 TIONAL_VERSIONS), “lib” directories near Boost_INCLUDE_DIR, and the
7684 library name configuration settings below. It saves the library direc‐
7685 tories in Boost_LIBRARY_DIR_DEBUG and Boost_LIBRARY_DIR_RELEASE and
7686 individual library locations in Boost_<C>_LIBRARY_DEBUG and
7687 Boost_<C>_LIBRARY_RELEASE. When one changes settings used by previous
7688 searches in the same build tree (excluding environment variables) this
7689 module discards previous search results affected by the changes and
7690 searches again.
7691 Boost libraries come in many variants encoded in their file name.
7693 Users or projects may tell this module which variant to find by setting
7694 variables:
7695 Boost_USE_DEBUG_LIBS - Set to ON or OFF to specify whether to search
7697 and use the debug libraries. Default is ON.
7698 Boost_USE_RELEASE_LIBS - Set to ON or OFF to specify whether to search
7699 and use the release libraries. Default is ON.
7700 Boost_USE_MULTITHREADED - Set to OFF to use the non-multithreaded
7701 libraries ('mt' tag). Default is ON.
7702 Boost_USE_STATIC_LIBS - Set to ON to force the use of the static
7703 libraries. Default is OFF.
7704 Boost_USE_STATIC_RUNTIME - Set to ON or OFF to specify whether to use
7705 libraries linked statically to the C++ runtime
7706 ('s' tag). Default is platform dependent.
7707 Boost_USE_DEBUG_RUNTIME - Set to ON or OFF to specify whether to use
7708 libraries linked to the MS debug C++ runtime
7709 ('g' tag). Default is ON.
7710 Boost_USE_DEBUG_PYTHON - Set to ON to use libraries compiled with a
7711 debug Python build ('y' tag). Default is OFF.
7712 Boost_USE_STLPORT - Set to ON to use libraries compiled with
7713 STLPort ('p' tag). Default is OFF.
7714 Boost_USE_STLPORT_DEPRECATED_NATIVE_IOSTREAMS
7715 - Set to ON to use libraries compiled with
7716 STLPort deprecated "native iostreams"
7717 ('n' tag). Default is OFF.
7718 Boost_COMPILER - Set to the compiler-specific library suffix
7719 (e.g. "-gcc43"). Default is auto-computed
7720 for the C++ compiler in use. A list may be
7721 used if multiple compatible suffixes should
7722 be tested for, in decreasing order of
7723 preference.
7724 Boost_ARCHITECTURE - Set to the architecture-specific library suffix
7725 (e.g. "-x64"). Default is auto-computed for the
7726 C++ compiler in use.
7727 Boost_THREADAPI - Suffix for "thread" component library name,
7728 such as "pthread" or "win32". Names with
7729 and without this suffix will both be tried.
7730 Boost_NAMESPACE - Alternate namespace used to build boost with
7731 e.g. if set to "myboost", will search for
7732 myboost_thread instead of boost_thread.
7733 Other variables one may set to control this module are:
7735 Boost_DEBUG - Set to ON to enable debug output from FindBoost.
7737 Please enable this before filing any bug report.
7738 Boost_DETAILED_FAILURE_MSG
7739 - Set to ON to add detailed information to the
7740 failure message even when the REQUIRED option
7741 is not given to the find_package call.
7742 Boost_REALPATH - Set to ON to resolve symlinks for discovered
7743 libraries to assist with packaging. For example,
7744 the "system" component library may be resolved to
7745 "/usr/lib/libboost_system.so.1.67.0" instead of
7746 "/usr/lib/libboost_system.so". This does not
7747 affect linking and should not be enabled unless
7748 the user needs this information.
7749 Boost_LIBRARY_DIR - Default value for Boost_LIBRARY_DIR_RELEASE and
7750 Boost_LIBRARY_DIR_DEBUG.
7751 On Visual Studio and Borland compilers Boost headers request automatic
7753 linking to corresponding libraries. This requires matching libraries
7754 to be linked explicitly or available in the link library search path.
7755 In this case setting Boost_USE_STATIC_LIBS to OFF may not achieve
7756 dynamic linking. Boost automatic linking typically requests static
7757 libraries with a few exceptions (such as Boost.Python). Use:
7758 add_definitions(${Boost_LIB_DIAGNOSTIC_DEFINITIONS})
7760 to ask Boost to report information about automatic linking requests.
7762 Example to find Boost headers only:
7764 find_package(Boost 1.36.0)
7766 if(Boost_FOUND)
7767 include_directories(${Boost_INCLUDE_DIRS})
7768 add_executable(foo foo.cc)
7769 endif()
7770 Example to find Boost libraries and use imported targets:
7772 find_package(Boost 1.56 REQUIRED COMPONENTS
7774 date_time filesystem iostreams)
7775 add_executable(foo foo.cc)
7776 target_link_libraries(foo Boost::date_time Boost::filesystem
7777 Boost::iostreams)
7778 Example to find Boost Python 3.6 libraries and use imported targets:
7780 find_package(Boost 1.67 REQUIRED COMPONENTS
7782 python36 numpy36)
7783 add_executable(foo foo.cc)
7784 target_link_libraries(foo Boost::python36 Boost::numpy36)
7785 Example to find Boost headers and some static (release only) libraries:
7787 set(Boost_USE_STATIC_LIBS ON) # only find static libs
7789 set(Boost_USE_DEBUG_LIBS OFF) # ignore debug libs and
7790 set(Boost_USE_RELEASE_LIBS ON) # only find release libs
7791 set(Boost_USE_MULTITHREADED ON)
7792 set(Boost_USE_STATIC_RUNTIME OFF)
7793 find_package(Boost 1.66.0 COMPONENTS date_time filesystem system ...)
7794 if(Boost_FOUND)
7795 include_directories(${Boost_INCLUDE_DIRS})
7796 add_executable(foo foo.cc)
7797 target_link_libraries(foo ${Boost_LIBRARIES})
7798 endif()
7799 Boost CMake
7801 If Boost was built using the boost-cmake project it provides a package
7802 configuration file for use with find_package’s Config mode. This mod‐
7803 ule looks for the package configuration file called BoostConfig.cmake
7804 or boost-config.cmake and stores the result in cache entry “Boost_DIR”.
7805 If found, the package configuration file is loaded and this module
7806 returns with no further action. See documentation of the Boost CMake
7807 package configuration for details on what it provides.
7808 Set Boost_NO_BOOST_CMAKE to ON to disable the search for boost-cmake.
7810 FindBullet
7812 Try to find the Bullet physics engine
7813 This module defines the following variables
7815 BULLET_FOUND - Was bullet found
7817 BULLET_INCLUDE_DIRS - the Bullet include directories
7818 BULLET_LIBRARIES - Link to this, by default it includes
7819 all bullet components (Dynamics,
7820 Collision, LinearMath, & SoftBody)
7821 This module accepts the following variables
7823 BULLET_ROOT - Can be set to bullet install path or Windows build path
7825 FindBZip2
7827 Try to find BZip2
7828 IMPORTED Targets
7830 This module defines IMPORTED target BZip2::BZip2, if BZip2 has been
7831 found.
7832 Result Variables
7834 This module defines the following variables:
7835 BZIP2_FOUND
7837 system has BZip2
7838 BZIP2_INCLUDE_DIRS
7840 the BZip2 include directories
7841 BZIP2_LIBRARIES
7843 Link these to use BZip2
7844 BZIP2_NEED_PREFIX
7846 this is set if the functions are prefixed with BZ2_
7847 BZIP2_VERSION_STRING
7849 the version of BZip2 found
7850 Cache variables
7852 The following cache variables may also be set:
7853 BZIP2_INCLUDE_DIR
7855 the BZip2 include directory
7856 FindCABLE
7858 Find CABLE
7859 This module finds if CABLE is installed and determines where the
7861 include files and libraries are. This code sets the following vari‐
7862 ables:
7863 CABLE the path to the cable executable
7865 CABLE_TCL_LIBRARY the path to the Tcl wrapper library
7866 CABLE_INCLUDE_DIR the path to the include directory
7867 To build Tcl wrappers, you should add shared library and link it to
7869 ${CABLE_TCL_LIBRARY}. You should also add ${CABLE_INCLUDE_DIR} as an
7870 include directory.
7871 FindCoin3D
7873 Find Coin3D (Open Inventor)
7874 Coin3D is an implementation of the Open Inventor API. It provides data
7876 structures and algorithms for 3D visualization.
7877 This module defines the following variables
7879 COIN3D_FOUND - system has Coin3D - Open Inventor
7881 COIN3D_INCLUDE_DIRS - where the Inventor include directory can be found
7882 COIN3D_LIBRARIES - Link to this to use Coin3D
7883 FindCups
7885 Try to find the Cups printing system
7886 Once done this will define
7888 CUPS_FOUND - system has Cups
7890 CUPS_INCLUDE_DIR - the Cups include directory
7891 CUPS_LIBRARIES - Libraries needed to use Cups
7892 CUPS_VERSION_STRING - version of Cups found (since CMake 2.8.8)
7893 Set CUPS_REQUIRE_IPP_DELETE_ATTRIBUTE to TRUE if you need a version which
7894 features this function (i.e. at least 1.1.19)
7895 FindCURL
7897 Find the native CURL headers and libraries.
7898 This module accept optional COMPONENTS to check supported features and
7900 protocols:
7901 PROTOCOLS: ICT FILE FTP FTPS GOPHER HTTP HTTPS IMAP IMAPS LDAP LDAPS POP3
7903 POP3S RTMP RTSP SCP SFTP SMB SMBS SMTP SMTPS TELNET TFTP
7904 FEATURES: SSL IPv6 UnixSockets libz AsynchDNS IDN GSS-API PSL SPNEGO
7905 Kerberos NTLM NTLM_WB TLS-SRP HTTP2 HTTPS-proxy
7906 IMPORTED Targets
7908 This module defines IMPORTED target CURL::libcurl, if curl has been
7909 found.
7910 Result Variables
7912 This module defines the following variables:
7913 CURL_FOUND
7915 True if curl found.
7916 CURL_INCLUDE_DIRS
7918 where to find curl/curl.h, etc.
7919 CURL_LIBRARIES
7921 List of libraries when using curl.
7922 CURL_VERSION_STRING
7924 The version of curl found.
7925 FindCurses
7927 Find the curses or ncurses include file and library.
7928 Result Variables
7930 This module defines the following variables:
7931 CURSES_FOUND
7933 True if Curses is found.
7934 CURSES_INCLUDE_DIRS
7936 The include directories needed to use Curses.
7937 CURSES_LIBRARIES
7939 The libraries needed to use Curses.
7940 CURSES_HAVE_CURSES_H
7942 True if curses.h is available.
7943 CURSES_HAVE_NCURSES_H
7945 True if ncurses.h is available.
7946 CURSES_HAVE_NCURSES_NCURSES_H
7948 True if ncurses/ncurses.h is available.
7949 CURSES_HAVE_NCURSES_CURSES_H
7951 True if ncurses/curses.h is available.
7952 Set CURSES_NEED_NCURSES to TRUE before the find_package(Curses) call if
7954 NCurses functionality is required. Set CURSES_NEED_WIDE to TRUE before
7955 the find_package(Curses) call if unicode functionality is required.
7956 Backward Compatibility
7958 The following variable are provided for backward compatibility:
7959 CURSES_INCLUDE_DIR
7961 Path to Curses include. Use CURSES_INCLUDE_DIRS instead.
7962 CURSES_LIBRARY
7964 Path to Curses library. Use CURSES_LIBRARIES instead.
7965 FindCVS
7967 The module defines the following variables:
7968 CVS_EXECUTABLE - path to cvs command line client
7970 CVS_FOUND - true if the command line client was found
7971 Example usage:
7973 find_package(CVS)
7975 if(CVS_FOUND)
7976 message("CVS found: ${CVS_EXECUTABLE}")
7977 endif()
7978 FindCxxTest
7980 Find CxxTest
7981 Find the CxxTest suite and declare a helper macro for creating unit
7983 tests and integrating them with CTest. For more details on CxxTest see
7984 http://cxxtest.tigris.org
7985 INPUT Variables
7987 CXXTEST_USE_PYTHON [deprecated since 1.3]
7989 Only used in the case both Python & Perl
7990 are detected on the system to control
7991 which CxxTest code generator is used.
7992 Valid only for CxxTest version 3.
7993 NOTE: In older versions of this Find Module,
7995 this variable controlled if the Python test
7996 generator was used instead of the Perl one,
7997 regardless of which scripting language the
7998 user had installed.
7999 CXXTEST_TESTGEN_ARGS (since CMake 2.8.3)
8001 Specify a list of options to pass to the CxxTest code
8002 generator. If not defined, --error-printer is
8003 passed.
8004 OUTPUT Variables
8006 CXXTEST_FOUND
8008 True if the CxxTest framework was found
8009 CXXTEST_INCLUDE_DIRS
8010 Where to find the CxxTest include directory
8011 CXXTEST_PERL_TESTGEN_EXECUTABLE
8012 The perl-based test generator
8013 CXXTEST_PYTHON_TESTGEN_EXECUTABLE
8014 The python-based test generator
8015 CXXTEST_TESTGEN_EXECUTABLE (since CMake 2.8.3)
8016 The test generator that is actually used (chosen using user preferences
8017 and interpreters found in the system)
8018 CXXTEST_TESTGEN_INTERPRETER (since CMake 2.8.3)
8019 The full path to the Perl or Python executable on the system, on
8020 platforms where the script cannot be executed using its shebang line.
8021 MACROS for optional use by CMake users:
8023 CXXTEST_ADD_TEST(<test_name> <gen_source_file> <input_files_to_testgen...>)
8025 Creates a CxxTest runner and adds it to the CTest testing suite
8026 Parameters:
8027 test_name The name of the test
8028 gen_source_file The generated source filename to be
8029 generated by CxxTest
8030 input_files_to_testgen The list of header files containing the
8031 CxxTest::TestSuite's to be included in
8032 this runner
8033 #==============
8035 Example Usage:
8036 find_package(CxxTest)
8038 if(CXXTEST_FOUND)
8039 include_directories(${CXXTEST_INCLUDE_DIR})
8040 enable_testing()
8041 CXXTEST_ADD_TEST(unittest_foo foo_test.cc
8043 ${CMAKE_CURRENT_SOURCE_DIR}/foo_test.h)
8044 target_link_libraries(unittest_foo foo) # as needed
8045 endif()
8046 This will (if CxxTest is found):
8048 1. Invoke the testgen executable to autogenerate foo_test.cc in the
8049 binary tree from "foo_test.h" in the current source directory.
8050 2. Create an executable and test called unittest_foo.
8051 #=============
8053 Example foo_test.h:
8054 #include <cxxtest/TestSuite.h>
8056 class MyTestSuite : public CxxTest::TestSuite
8058 {
8059 public:
8060 void testAddition( void )
8061 {
8062 TS_ASSERT( 1 + 1 > 1 );
8063 TS_ASSERT_EQUALS( 1 + 1, 2 );
8064 }
8065 };
8066 FindCygwin
8068 this module looks for Cygwin
8069 FindDart
8071 Find DART
8072 This module looks for the dart testing software and sets DART_ROOT to
8074 point to where it found it.
8075 FindDCMTK
8077 Find DCMTK libraries and applications
8078 The module defines the following variables:
8080 DCMTK_INCLUDE_DIRS - Directories to include to use DCMTK
8082 DCMTK_LIBRARIES - Files to link against to use DCMTK
8083 DCMTK_FOUND - If false, don't try to use DCMTK
8084 DCMTK_DIR - (optional) Source directory for DCMTK
8085 Compatibility
8087 This module is able to find a version of DCMTK that does or does not
8088 export a DCMTKConfig.cmake file. It applies a two step process:
8089 · Step 1: Attempt to find DCMTK version providing a DCMTKConfig.cmake
8091 file.
8092 · Step 2: If step 1 failed, rely on FindDCMTK.cmake to set DCMTK_*
8094 variables details below.
8095 Recent DCMTK provides a DCMTKConfig.cmake package configuration file.
8097 To exclusively use the package configuration file (recommended when
8098 possible), pass the NO_MODULE option to find_package(). For example,
8099 find_package(DCMTK NO_MODULE). This requires official DCMTK snapshot
8100 3.6.1_20140617 or newer.
8101 Until all clients update to the more recent DCMTK, build systems will
8103 need to support different versions of DCMTK.
8104 On any given system, the following combinations of DCMTK versions could
8106 be considered:
8107 ┌───────┬─────────────────┬─────────────────┬─────────────┐
8109 │ │ SYSTEM DCMTK │ LOCAL DCMTK │ Supported ? │
8110 ├───────┼─────────────────┼─────────────────┼─────────────┤
8111 │Case A │ NA │ [ ] DCMTKConfig │ YES │
8112 ├───────┼─────────────────┼─────────────────┼─────────────┤
8113 │Case B │ NA │ [X] DCMTKConfig │ YES │
8114 ├───────┼─────────────────┼─────────────────┼─────────────┤
8115 │Case C │ [ ] DCMTKConfig │ NA │ YES │
8116 ├───────┼─────────────────┼─────────────────┼─────────────┤
8117 │Case D │ [X] DCMTKConfig │ NA │ YES │
8118 ├───────┼─────────────────┼─────────────────┼─────────────┤
8119 │Case E │ [ ] DCMTKConfig │ [ ] DCMTKConfig │ YES (*) │
8120 ├───────┼─────────────────┼─────────────────┼─────────────┤
8121 │Case F │ [X] DCMTKConfig │ [ ] DCMTKConfig │ NO │
8122 ├───────┼─────────────────┼─────────────────┼─────────────┤
8123 │Case G │ [ ] DCMTKConfig │ [X] DCMTKConfig │ YES │
8124 ├───────┼─────────────────┼─────────────────┼─────────────┤
8125 │Case H │ [X] DCMTKConfig │ [X] DCMTKConfig │ YES │
8126 └───────┴─────────────────┴─────────────────┴─────────────┘
8127 (*) See Troubleshooting section.
8128 Legend:
8130 NA ……………: Means that no System or Local DCMTK is available
8131 [ ] DCMTKConfig ..: Means that the version of DCMTK does NOT export
8133 a DCMTKConfig.cmake file.
8134 [X] DCMTKConfig ..: Means that the version of DCMTK exports a DCMTK‐
8136 Config.cmake file.
8137 Troubleshooting
8139 What to do if my project finds a different version of DCMTK?
8140 Remove DCMTK entry from the CMake cache per find_package() documenta‐
8142 tion.
8143 FindDevIL
8145 This module locates the developer’s image library.
8146 http://openil.sourceforge.net/
8147 This module sets:
8149 IL_LIBRARIES - the name of the IL library. These include the full path to
8151 the core DevIL library. This one has to be linked into the
8152 application.
8153 ILU_LIBRARIES - the name of the ILU library. Again, the full path. This
8154 library is for filters and effects, not actual loading. It
8155 doesn't have to be linked if the functionality it provides
8156 is not used.
8157 ILUT_LIBRARIES - the name of the ILUT library. Full path. This part of the
8158 library interfaces with OpenGL. It is not strictly needed
8159 in applications.
8160 IL_INCLUDE_DIR - where to find the il.h, ilu.h and ilut.h files.
8161 DevIL_FOUND - this is set to TRUE if all the above variables were set.
8162 This will be set to false if ILU or ILUT are not found,
8163 even if they are not needed. In most systems, if one
8164 library is found all the others are as well. That's the
8165 way the DevIL developers release it.
8166 FindDoxygen
8168 Doxygen is a documentation generation tool (see
8169 http://www.doxygen.org). This module looks for Doxygen and some
8170 optional tools it supports. These tools are enabled as components in
8171 the find_package() command:
8172 dot Graphviz dot utility used to render various graphs.
8174 mscgen Message Chart Generator utility used by Doxygen’s \msc and \msc‐
8176 file commands.
8177 dia Dia the diagram editor used by Doxygen’s \diafile command.
8179 Examples:
8181 # Require dot, treat the other components as optional
8183 find_package(Doxygen
8184 REQUIRED dot
8185 OPTIONAL_COMPONENTS mscgen dia)
8186 The following variables are defined by this module:
8188 DOXYGEN_FOUND
8190 True if the doxygen executable was found.
8191 DOXYGEN_VERSION
8193 The version reported by doxygen --version.
8194 The module defines IMPORTED targets for Doxygen and each component
8196 found. These can be used as part of custom commands, etc. and should
8197 be preferred over old-style (and now deprecated) variables like DOXY‐
8198 GEN_EXECUTABLE. The following import targets are defined if their cor‐
8199 responding executable could be found (the component import targets will
8200 only be defined if that component was requested):
8201 Doxygen::doxygen
8203 Doxygen::dot
8204 Doxygen::mscgen
8205 Doxygen::dia
8206 Functions
8208 doxygen_add_docs
8209 This function is intended as a convenience for adding a target
8210 for generating documentation with Doxygen. It aims to provide
8211 sensible defaults so that projects can generally just provide
8212 the input files and directories and that will be sufficient to
8213 give sensible results. The function supports the ability to cus‐
8214 tomize the Doxygen configuration used to build the documenta‐
8215 tion.
8216 doxygen_add_docs(targetName
8218 [filesOrDirs...]
8219 [ALL]
8220 [WORKING_DIRECTORY dir]
8221 [COMMENT comment])
8222 The function constructs a Doxyfile and defines a custom target
8224 that runs Doxygen on that generated file. The listed files and
8225 directories are used as the INPUT of the generated Doxyfile and
8226 they can contain wildcards. Any files that are listed explic‐
8227 itly will also be added as SOURCES of the custom target so they
8228 will show up in an IDE project’s source list.
8229 So that relative input paths work as expected, by default the
8231 working directory of the Doxygen command will be the current
8232 source directory (i.e. CMAKE_CURRENT_SOURCE_DIR). This can be
8233 overridden with the WORKING_DIRECTORY option to change the
8234 directory used as the relative base point. Note also that Doxy‐
8235 gen’s default behavior is to strip the working directory from
8236 relative paths in the generated documentation (see the
8237 STRIP_FROM_PATH Doxygen config option for details).
8238 If provided, the optional comment will be passed as the COMMENT
8240 for the add_custom_target() command used to create the custom
8241 target internally.
8242 If ALL is set, the target will be added to the default build
8244 target.
8245 The contents of the generated Doxyfile can be customized by set‐
8247 ting CMake variables before calling doxygen_add_docs(). Any
8248 variable with a name of the form DOXYGEN_<tag> will have its
8249 value substituted for the corresponding <tag> configuration
8250 option in the Doxyfile. See the Doxygen documentation for the
8251 full list of supported configuration options.
8252 Some of Doxygen’s defaults are overridden to provide more appro‐
8254 priate behavior for a CMake project. Each of the following will
8255 be explicitly set unless the variable already has a value before
8256 doxygen_add_docs() is called (with some exceptions noted):
8257 DOXYGEN_HAVE_DOT
8259 Set to YES if the dot component was requested and it was
8260 found, NO otherwise. Any existing value of DOXY‐
8261 GEN_HAVE_DOT is ignored.
8262 DOXYGEN_DOT_MULTI_TARGETS
8264 Set to YES by this module (note that this requires a dot
8265 version newer than 1.8.10). This option is only meaning‐
8266 ful if DOXYGEN_HAVE_DOT is also set to YES.
8267 DOXYGEN_GENERATE_LATEX
8269 Set to NO by this module.
8270 DOXYGEN_WARN_FORMAT
8272 For Visual Studio based generators, this is set to the
8273 form recognized by the Visual Studio IDE: $file($line) :
8274 $text. For all other generators, Doxygen’s default value
8275 is not overridden.
8276 DOXYGEN_PROJECT_NAME
8278 Populated with the name of the current project (i.e.
8279 PROJECT_NAME).
8280 DOXYGEN_PROJECT_NUMBER
8282 Populated with the version of the current project (i.e.
8283 PROJECT_VERSION).
8284 DOXYGEN_PROJECT_BRIEF
8286 Populated with the description of the current project
8287 (i.e. PROJECT_DESCRIPTION).
8288 DOXYGEN_INPUT
8290 Projects should not set this variable. It will be popu‐
8291 lated with the set of files and directories passed to
8292 doxygen_add_docs(), thereby providing consistent behavior
8293 with the other built-in commands like add_executable(),
8294 add_library() and add_custom_target(). If a variable
8295 named DOXYGEN_INPUT is set by the project, it will be
8296 ignored and a warning will be issued.
8297 DOXYGEN_RECURSIVE
8299 Set to YES by this module.
8300 DOXYGEN_EXCLUDE_PATTERNS
8302 If the set of inputs includes directories, this variable
8303 will specify patterns used to exclude files from them.
8304 The following patterns are added by doxygen_add_docs() to
8305 ensure CMake-specific files and directories are not
8306 included in the input. If the project sets DOXY‐
8307 GEN_EXCLUDE_PATTERNS, those contents are merged with
8308 these additional patterns rather than replacing them:
8309 */.git/*
8311 */.svn/*
8312 */.hg/*
8313 */CMakeFiles/*
8314 */_CPack_Packages/*
8315 DartConfiguration.tcl
8316 CMakeLists.txt
8317 CMakeCache.txt
8318 DOXYGEN_OUTPUT_DIRECTORY
8320 Set to CMAKE_CURRENT_BINARY_DIR by this module. Note that
8321 if the project provides its own value for this and it is
8322 a relative path, it will be converted to an absolute path
8323 relative to the current binary directory. This is neces‐
8324 sary because doxygen will normally be run from a direc‐
8325 tory within the source tree so that relative source paths
8326 work as expected. If this directory does not exist, it
8327 will be recursively created prior to executing the doxy‐
8328 gen commands.
8329 To change any of these defaults or override any other Doxygen config
8331 option, set relevant variables before calling doxygen_add_docs(). For
8332 example:
8333 set(DOXYGEN_GENERATE_HTML NO)
8335 set(DOXYGEN_GENERATE_MAN YES)
8336 doxygen_add_docs(
8338 doxygen
8339 ${PROJECT_SOURCE_DIR}
8340 COMMENT "Generate man pages"
8341 )
8342 A number of Doxygen config options accept lists of values, but Doxygen
8344 requires them to be separated by whitespace. CMake variables hold lists
8345 as a string with items separated by semi-colons, so a conversion needs
8346 to be performed. The doxygen_add_docs() command specifically checks the
8347 following Doxygen config options and will convert their associated
8348 CMake variable’s contents into the required form if set.
8349 ABBREVIATE_BRIEF
8351 ALIASES
8352 CITE_BIB_FILES
8353 DIAFILE_DIRS
8354 DOTFILE_DIRS
8355 DOT_FONTPATH
8356 ENABLED_SECTIONS
8357 EXAMPLE_PATH
8358 EXAMPLE_PATTERNS
8359 EXCLUDE
8360 EXCLUDE_PATTERNS
8361 EXCLUDE_SYMBOLS
8362 EXPAND_AS_DEFINED
8363 EXTENSION_MAPPING
8364 EXTRA_PACKAGES
8365 EXTRA_SEARCH_MAPPINGS
8366 FILE_PATTERNS
8367 FILTER_PATTERNS
8368 FILTER_SOURCE_PATTERNS
8369 HTML_EXTRA_FILES
8370 HTML_EXTRA_STYLESHEET
8371 IGNORE_PREFIX
8372 IMAGE_PATH
8373 INCLUDE_FILE_PATTERNS
8374 INCLUDE_PATH
8375 INPUT
8376 LATEX_EXTRA_FILES
8377 LATEX_EXTRA_STYLESHEET
8378 MATHJAX_EXTENSIONS
8379 MSCFILE_DIRS
8380 PLANTUML_INCLUDE_PATH
8381 PREDEFINED
8382 QHP_CUST_FILTER_ATTRS
8383 QHP_SECT_FILTER_ATTRS
8384 STRIP_FROM_INC_PATH
8385 STRIP_FROM_PATH
8386 TAGFILES
8387 TCL_SUBST
8388 The following single value Doxygen options will be quoted automatically
8390 if they contain at least one space:
8391 CHM_FILE
8393 DIA_PATH
8394 DOCBOOK_OUTPUT
8395 DOCSET_FEEDNAME
8396 DOCSET_PUBLISHER_NAME
8397 DOT_FONTNAME
8398 DOT_PATH
8399 EXTERNAL_SEARCH_ID
8400 FILE_VERSION_FILTER
8401 GENERATE_TAGFILE
8402 HHC_LOCATION
8403 HTML_FOOTER
8404 HTML_HEADER
8405 HTML_OUTPUT
8406 HTML_STYLESHEET
8407 INPUT_FILTER
8408 LATEX_FOOTER
8409 LATEX_HEADER
8410 LATEX_OUTPUT
8411 LAYOUT_FILE
8412 MAN_OUTPUT
8413 MAN_SUBDIR
8414 MATHJAX_CODEFILE
8415 MSCGEN_PATH
8416 OUTPUT_DIRECTORY
8417 PERL_PATH
8418 PLANTUML_JAR_PATH
8419 PROJECT_BRIEF
8420 PROJECT_LOGO
8421 PROJECT_NAME
8422 QCH_FILE
8423 QHG_LOCATION
8424 QHP_CUST_FILTER_NAME
8425 QHP_VIRTUAL_FOLDER
8426 RTF_EXTENSIONS_FILE
8427 RTF_OUTPUT
8428 RTF_STYLESHEET_FILE
8429 SEARCHDATA_FILE
8430 USE_MDFILE_AS_MAINPAGE
8431 WARN_FORMAT
8432 WARN_LOGFILE
8433 XML_OUTPUT
8434 There are situations where it may be undesirable for a particular con‐
8436 fig option to be automatically quoted by doxygen_add_docs(), such as
8437 ALIASES which may need to include its own embedded quoting. The DOXY‐
8438 GEN_VERBATIM_VARS variable can be used to specify a list of Doxygen
8439 variables (including the leading DOXYGEN_ prefix) which should not be
8440 quoted. The project is then responsible for ensuring that those vari‐
8441 ables’ values make sense when placed directly in the Doxygen input
8442 file. In the case of list variables, list items are still separated by
8443 spaces, it is only the automatic quoting that is skipped. For example,
8444 the following allows doxygen_add_docs() to apply quoting to DOXY‐
8445 GEN_PROJECT_BRIEF, but not each item in the DOXYGEN_ALIASES list
8446 (bracket syntax can also be used to make working with embedded quotes
8447 easier):
8448 set(DOXYGEN_PROJECT_BRIEF "String with spaces")
8450 set(DOXYGEN_ALIASES
8451 [[somealias="@some_command param"]]
8452 "anotherAlias=@foobar"
8453 )
8454 set(DOXYGEN_VERBATIM_VARS DOXYGEN_ALIASES)
8455 The resultant Doxyfile will contain the following lines:
8457 PROJECT_BRIEF = "String with spaces"
8459 ALIASES = somealias="@some_command param" anotherAlias=@foobar
8460 Deprecated Result Variables
8462 For compatibility with previous versions of CMake, the following vari‐
8463 ables are also defined but they are deprecated and should no longer be
8464 used:
8465 DOXYGEN_EXECUTABLE
8467 The path to the doxygen command. If projects need to refer to
8468 the doxygen executable directly, they should use the Doxy‐
8469 gen::doxygen import target instead.
8470 DOXYGEN_DOT_FOUND
8472 True if the dot executable was found.
8473 DOXYGEN_DOT_EXECUTABLE
8475 The path to the dot command. If projects need to refer to the
8476 dot executable directly, they should use the Doxygen::dot import
8477 target instead.
8478 DOXYGEN_DOT_PATH
8480 The path to the directory containing the dot executable as
8481 reported in DOXYGEN_DOT_EXECUTABLE. The path may have forward
8482 slashes even on Windows and is not suitable for direct substitu‐
8483 tion into a Doxyfile.in template. If you need this value, get
8484 the IMPORTED_LOCATION property of the Doxygen::dot target and
8485 use get_filename_component() to extract the directory part of
8486 that path. You may also want to consider using
8487 file(TO_NATIVE_PATH) to prepare the path for a Doxygen configu‐
8488 ration file.
8489 Deprecated Hint Variables
8491 DOXYGEN_SKIP_DOT
8492 This variable has no effect for the component form of find_pack‐
8493 age. In backward compatibility mode (i.e. without components
8494 list) it prevents the finder module from searching for
8495 Graphviz’s dot utility.
8496 FindEXPAT
8498 Find the native Expat headers and library.
8499 Imported Targets
8501 This module defines the following IMPORTED targets:
8502 EXPAT::EXPAT
8504 The Expat expat library, if found.
8505 Result Variables
8507 This module will set the following variables in your project:
8508 EXPAT_INCLUDE_DIRS
8510 where to find expat.h, etc.
8511 EXPAT_LIBRARIES
8513 the libraries to link against to use Expat.
8514 EXPAT_FOUND
8516 true if the Expat headers and libraries were found.
8517 FindFLEX
8519 Find flex executable and provides a macro to generate custom build
8520 rules
8521 The module defines the following variables:
8523 FLEX_FOUND - true is flex executable is found
8525 FLEX_EXECUTABLE - the path to the flex executable
8526 FLEX_VERSION - the version of flex
8527 FLEX_LIBRARIES - The flex libraries
8528 FLEX_INCLUDE_DIRS - The path to the flex headers
8529 The minimum required version of flex can be specified using the stan‐
8531 dard syntax, e.g. find_package(FLEX 2.5.13)
8532 If flex is found on the system, the module provides the macro:
8534 FLEX_TARGET(Name FlexInput FlexOutput
8536 [COMPILE_FLAGS <string>]
8537 [DEFINES_FILE <string>]
8538 )
8539 which creates a custom command to generate the <FlexOutput> file from
8541 the <FlexInput> file. If COMPILE_FLAGS option is specified, the next
8542 parameter is added to the flex command line. If flex is configured to
8543 output a header file, the DEFINES_FILE option may be used to specify
8544 its name. Name is an alias used to get details of this custom command.
8545 Indeed the macro defines the following variables:
8546 FLEX_${Name}_DEFINED - true is the macro ran successfully
8548 FLEX_${Name}_OUTPUTS - the source file generated by the custom rule, an
8549 alias for FlexOutput
8550 FLEX_${Name}_INPUT - the flex source file, an alias for ${FlexInput}
8551 FLEX_${Name}_OUTPUT_HEADER - the header flex output, if any.
8552 Flex scanners often use tokens defined by Bison: the code generated by
8554 Flex depends of the header generated by Bison. This module also
8555 defines a macro:
8556 ADD_FLEX_BISON_DEPENDENCY(FlexTarget BisonTarget)
8558 which adds the required dependency between a scanner and a parser where
8560 <FlexTarget> and <BisonTarget> are the first parameters of respectively
8561 FLEX_TARGET and BISON_TARGET macros.
8562 ====================================================================
8564 Example:
8565 find_package(BISON)
8567 find_package(FLEX)
8568 BISON_TARGET(MyParser parser.y ${CMAKE_CURRENT_BINARY_DIR}/parser.cpp)
8570 FLEX_TARGET(MyScanner lexer.l ${CMAKE_CURRENT_BINARY_DIR}/lexer.cpp)
8571 ADD_FLEX_BISON_DEPENDENCY(MyScanner MyParser)
8572 include_directories(${CMAKE_CURRENT_BINARY_DIR})
8574 add_executable(Foo
8575 Foo.cc
8576 ${BISON_MyParser_OUTPUTS}
8577 ${FLEX_MyScanner_OUTPUTS}
8578 )
8579 ====================================================================
8580 FindFLTK2
8582 Find the native FLTK2 includes and library
8583 The following settings are defined
8585 FLTK2_FLUID_EXECUTABLE, where to find the Fluid tool
8587 FLTK2_WRAP_UI, This enables the FLTK2_WRAP_UI command
8588 FLTK2_INCLUDE_DIR, where to find include files
8589 FLTK2_LIBRARIES, list of fltk2 libraries
8590 FLTK2_FOUND, Don't use FLTK2 if false.
8591 The following settings should not be used in general.
8593 FLTK2_BASE_LIBRARY = the full path to fltk2.lib
8595 FLTK2_GL_LIBRARY = the full path to fltk2_gl.lib
8596 FLTK2_IMAGES_LIBRARY = the full path to fltk2_images.lib
8597 FindFLTK
8599 Find the FLTK library
8600 Input Variables
8602 By default this module will search for all of the FLTK components and
8603 add them to the FLTK_LIBRARIES variable. You can limit the components
8604 which get placed in FLTK_LIBRARIES by defining one or more of the fol‐
8605 lowing three options:
8606 FLTK_SKIP_OPENGL
8608 Set to true to disable searching for the FLTK GL library
8609 FLTK_SKIP_FORMS
8611 Set to true to disable searching for the FLTK Forms library
8612 FLTK_SKIP_IMAGES
8614 Set to true to disable searching for the FLTK Images library
8615 FLTK is composed also by a binary tool. You can set the following
8617 option:
8618 FLTK_SKIP_FLUID
8620 Set to true to not look for the FLUID binary
8621 Result Variables
8623 The following variables will be defined:
8624 FLTK_FOUND
8626 True if all components not skipped were found
8627 FLTK_INCLUDE_DIR
8629 Path to the include directory for FLTK header files
8630 FLTK_LIBRARIES
8632 List of the FLTK libraries found
8633 FLTK_FLUID_EXECUTABLE
8635 Path to the FLUID binary tool
8636 FLTK_WRAP_UI
8638 True if FLUID is found, used to enable the FLTK_WRAP_UI command
8639 Cache Variables
8641 The following cache variables are also available to set or use:
8642 FLTK_BASE_LIBRARY_RELEASE
8644 The FLTK base library (optimized)
8645 FLTK_BASE_LIBRARY_DEBUG
8647 The FLTK base library (debug)
8648 FLTK_GL_LIBRARY_RELEASE
8650 The FLTK GL library (optimized)
8651 FLTK_GL_LIBRARY_DEBUG
8653 The FLTK GL library (debug)
8654 FLTK_FORMS_LIBRARY_RELEASE
8656 The FLTK Forms library (optimized)
8657 FLTK_FORMS_LIBRARY_DEBUG
8659 The FLTK Forms library (debug)
8660 FLTK_IMAGES_LIBRARY_RELEASE
8662 The FLTK Images protobuf library (optimized)
8663 FLTK_IMAGES_LIBRARY_DEBUG
8665 The FLTK Images library (debug)
8666 FindFontconfig
8668 Find Fontconfig headers and library.
8669 Imported Targets
8671 Fontconfig::Fontconfig
8672 The Fontconfig library, if found.
8673 Result Variables
8675 This will define the following variables in your project:
8676 Fontconfig_FOUND
8678 true if (the requested version of) Fontconfig is available.
8679 Fontconfig_VERSION
8681 the version of Fontconfig.
8682 Fontconfig_LIBRARIES
8684 the libraries to link against to use Fontconfig.
8685 Fontconfig_INCLUDE_DIRS
8687 where to find the Fontconfig headers.
8688 Fontconfig_COMPILE_OPTIONS
8690 this should be passed to target_compile_options(), if the target
8691 is not used for linking
8692 FindFreetype
8694 Find the FreeType font renderer includes and library.
8695 Imported Targets
8697 This module defines the following IMPORTED target:
8698 Freetype::Freetype
8700 The Freetype freetype library, if found
8701 Result Variables
8703 This module will set the following variables in your project:
8704 FREETYPE_FOUND
8706 true if the Freetype headers and libraries were found
8707 FREETYPE_INCLUDE_DIRS
8709 directories containing the Freetype headers. This is the con‐
8710 catenation of the variables:
8711 FREETYPE_INCLUDE_DIR_ft2build
8713 directory holding the main Freetype API configuration
8714 header
8715 FREETYPE_INCLUDE_DIR_freetype2
8717 directory holding Freetype public headers
8718 FREETYPE_LIBRARIES
8720 the library to link against
8721 FREETYPE_VERSION_STRING
8723 the version of freetype found (since CMake 2.8.8)
8724 Hints
8726 The user may set the environment variable FREETYPE_DIR to the root
8727 directory of a Freetype installation.
8728 FindGCCXML
8730 Find the GCC-XML front-end executable.
8731 This module will define the following variables:
8733 GCCXML - the GCC-XML front-end executable.
8735 FindGDAL
8737 Find GDAL.
8738 IMPORTED Targets
8740 This module defines IMPORTED target GDAL::GDAL if GDAL has been found.
8741 Result Variables
8743 This module will set the following variables in your project:
8744 GDAL_FOUND
8746 True if GDAL is found.
8747 GDAL_INCLUDE_DIRS
8749 Include directories for GDAL headers.
8750 GDAL_LIBRARIES
8752 Libraries to link to GDAL.
8753 GDAL_VERSION
8755 The version of GDAL found.
8756 Cache variables
8758 The following cache variables may also be set:
8759 GDAL_LIBRARY
8761 The libgdal library file.
8762 GDAL_INCLUDE_DIR
8764 The directory containing gdal.h.
8765 Hints
8767 Set GDAL_DIR or GDAL_ROOT in the environment to specify the GDAL
8768 installation prefix.
8769 FindGettext
8771 Find GNU gettext tools
8772 This module looks for the GNU gettext tools. This module defines the
8774 following values:
8775 GETTEXT_MSGMERGE_EXECUTABLE: the full path to the msgmerge tool.
8777 GETTEXT_MSGFMT_EXECUTABLE: the full path to the msgfmt tool.
8778 GETTEXT_FOUND: True if gettext has been found.
8779 GETTEXT_VERSION_STRING: the version of gettext found (since CMake 2.8.8)
8780 Additionally it provides the following macros:
8782 GETTEXT_CREATE_TRANSLATIONS ( outputFile [ALL] file1 … fileN )
8784 This will create a target "translations" which will convert the
8786 given input po files into the binary output mo file. If the
8787 ALL option is used, the translations will also be created when
8788 building the default target.
8789 GETTEXT_PROCESS_POT_FILE( <potfile> [ALL] [INSTALL_DESTINATION <dest‐
8791 dir>] LANGUAGES <lang1> <lang2> … )
8792 Process the given pot file to mo files.
8794 If INSTALL_DESTINATION is given then automatically install rules will
8795 be created, the language subdirectory will be taken into account
8796 (by default use share/locale/).
8797 If ALL is specified, the pot file is processed when building the all traget.
8798 It creates a custom target "potfile".
8799 GETTEXT_PROCESS_PO_FILES( <lang> [ALL] [INSTALL_DESTINATION <dir>]
8801 PO_FILES <po1> <po2> … )
8802 Process the given po files to mo files for the given language.
8804 If INSTALL_DESTINATION is given then automatically install rules will
8805 be created, the language subdirectory will be taken into account
8806 (by default use share/locale/).
8807 If ALL is specified, the po files are processed when building the all traget.
8808 It creates a custom target "pofiles".
8809 NOTE:
8811 If you wish to use the Gettext library (libintl), use FindIntl.
8812 FindGIF
8814 This finds the GIF library (giflib)
8815 Imported targets
8817 This module defines the following IMPORTED target:
8818 GIF::GIF
8820 The giflib library, if found.
8821 Result variables
8823 This module will set the following variables in your project:
8824 GIF_FOUND
8826 If false, do not try to use GIF.
8827 GIF_INCLUDE_DIRS
8829 where to find gif_lib.h, etc.
8830 GIF_LIBRARIES
8832 the libraries needed to use GIF.
8833 GIF_VERSION
8835 3, 4 or a full version string (eg 5.1.4) for versions >= 4.1.6.
8836 Cache variables
8838 The following cache variables may also be set:
8839 GIF_INCLUDE_DIR
8841 where to find the GIF headers.
8842 GIF_LIBRARY
8844 where to find the GIF library.
8845 Hints
8847 GIF_DIR is an environment variable that would correspond to the ./con‐
8848 figure --prefix=$GIF_DIR.
8849 FindGit
8851 The module defines the following IMPORTED targets (when CMAKE_ROLE is
8852 PROJECT):
8853 Git::Git
8855 Executable of the Git command-line client.
8856 The module defines the following variables:
8858 GIT_EXECUTABLE
8860 Path to Git command-line client.
8861 Git_FOUND, GIT_FOUND
8863 True if the Git command-line client was found.
8864 GIT_VERSION_STRING
8866 The version of Git found.
8867 Example usage:
8869 find_package(Git)
8871 if(Git_FOUND)
8872 message("Git found: ${GIT_EXECUTABLE}")
8873 endif()
8874 FindGLEW
8876 Find the OpenGL Extension Wrangler Library (GLEW)
8877 IMPORTED Targets
8879 This module defines the IMPORTED target GLEW::GLEW, if GLEW has been
8880 found.
8881 Result Variables
8883 This module defines the following variables:
8884 GLEW_INCLUDE_DIRS - include directories for GLEW
8886 GLEW_LIBRARIES - libraries to link against GLEW
8887 GLEW_FOUND - true if GLEW has been found and can be used
8888 FindGLUT
8890 try to find glut library and include files.
8891 IMPORTED Targets
8893 This module defines the IMPORTED targets:
8894 GLUT::GLUT
8896 Defined if the system has GLUT.
8897 Result Variables
8899 This module sets the following variables:
8900 GLUT_INCLUDE_DIR, where to find GL/glut.h, etc.
8902 GLUT_LIBRARIES, the libraries to link against
8903 GLUT_FOUND, If false, do not try to use GLUT.
8904 Also defined, but not for general use are:
8906 GLUT_glut_LIBRARY = the full path to the glut library.
8908 GLUT_Xmu_LIBRARY = the full path to the Xmu library.
8909 GLUT_Xi_LIBRARY = the full path to the Xi Library.
8910 FindGnuplot
8912 this module looks for gnuplot
8913 Once done this will define
8915 GNUPLOT_FOUND - system has Gnuplot
8917 GNUPLOT_EXECUTABLE - the Gnuplot executable
8918 GNUPLOT_VERSION_STRING - the version of Gnuplot found (since CMake 2.8.8)
8919 GNUPLOT_VERSION_STRING will not work for old versions like 3.7.1.
8921 FindGnuTLS
8923 Try to find the GNU Transport Layer Security library (gnutls)
8924 Once done this will define
8926 GNUTLS_FOUND - System has gnutls
8928 GNUTLS_INCLUDE_DIR - The gnutls include directory
8929 GNUTLS_LIBRARIES - The libraries needed to use gnutls
8930 GNUTLS_DEFINITIONS - Compiler switches required for using gnutls
8931 FindGSL
8933 Find the native GSL includes and libraries.
8934 The GNU Scientific Library (GSL) is a numerical library for C and C++
8936 programmers. It is free software under the GNU General Public License.
8937 Imported Targets
8939 If GSL is found, this module defines the following IMPORTED targets:
8940 GSL::gsl - The main GSL library.
8942 GSL::gslcblas - The CBLAS support library used by GSL.
8943 Result Variables
8945 This module will set the following variables in your project:
8946 GSL_FOUND - True if GSL found on the local system
8948 GSL_INCLUDE_DIRS - Location of GSL header files.
8949 GSL_LIBRARIES - The GSL libraries.
8950 GSL_VERSION - The version of the discovered GSL install.
8951 Hints
8953 Set GSL_ROOT_DIR to a directory that contains a GSL installation.
8954 This script expects to find libraries at $GSL_ROOT_DIR/lib and the GSL
8956 headers at $GSL_ROOT_DIR/include/gsl. The library directory may
8957 optionally provide Release and Debug folders. If available, the
8958 libraries named gsld, gslblasd or cblasd are recognized as debug
8959 libraries. For Unix-like systems, this script will use
8960 $GSL_ROOT_DIR/bin/gsl-config (if found) to aid in the discovery of GSL.
8961 Cache Variables
8963 This module may set the following variables depending on platform and
8964 type of GSL installation discovered. These variables may optionally be
8965 set to help this module find the correct files:
8966 GSL_CBLAS_LIBRARY - Location of the GSL CBLAS library.
8968 GSL_CBLAS_LIBRARY_DEBUG - Location of the debug GSL CBLAS library (if any).
8969 GSL_CONFIG_EXECUTABLE - Location of the ``gsl-config`` script (if any).
8970 GSL_LIBRARY - Location of the GSL library.
8971 GSL_LIBRARY_DEBUG - Location of the debug GSL library (if any).
8972 FindGTest
8974 Locate the Google C++ Testing Framework.
8975 Imported targets
8977 This module defines the following IMPORTED targets:
8978 GTest::GTest
8980 The Google Test gtest library, if found; adds Thread::Thread
8981 automatically
8982 GTest::Main
8984 The Google Test gtest_main library, if found
8985 Result variables
8987 This module will set the following variables in your project:
8988 GTEST_FOUND
8990 Found the Google Testing framework
8991 GTEST_INCLUDE_DIRS
8993 the directory containing the Google Test headers
8994 The library variables below are set as normal variables. These contain
8996 debug/optimized keywords when a debugging library is found.
8997 GTEST_LIBRARIES
8999 The Google Test gtest library; note it also requires linking
9000 with an appropriate thread library
9001 GTEST_MAIN_LIBRARIES
9003 The Google Test gtest_main library
9004 GTEST_BOTH_LIBRARIES
9006 Both gtest and gtest_main
9007 Cache variables
9009 The following cache variables may also be set:
9010 GTEST_ROOT
9012 The root directory of the Google Test installation (may also be
9013 set as an environment variable)
9014 GTEST_MSVC_SEARCH
9016 If compiling with MSVC, this variable can be set to MT or MD
9017 (the default) to enable searching a GTest build tree
9018 Example usage
9020 enable_testing()
9021 find_package(GTest REQUIRED)
9022 add_executable(foo foo.cc)
9024 target_link_libraries(foo GTest::GTest GTest::Main)
9025 add_test(AllTestsInFoo foo)
9027 Deeper integration with CTest
9029 See GoogleTest for information on the gtest_add_tests() and gtest_dis‐
9030 cover_tests() commands.
9031 FindGTK2
9033 FindGTK2.cmake
9034 This module can find the GTK2 widget libraries and several of its other
9036 optional components like gtkmm, glade, and glademm.
9037 NOTE: If you intend to use version checking, CMake 2.6.2 or later is
9039 required.
9041 Specify one or more of the following components as you call this find
9043 module. See example below.
9044 gtk
9046 gtkmm
9047 glade
9048 glademm
9049 The following variables will be defined for your use
9051 GTK2_FOUND - Were all of your specified components found?
9053 GTK2_INCLUDE_DIRS - All include directories
9054 GTK2_LIBRARIES - All libraries
9055 GTK2_TARGETS - All imported targets
9056 GTK2_DEFINITIONS - Additional compiler flags
9057 GTK2_VERSION - The version of GTK2 found (x.y.z)
9059 GTK2_MAJOR_VERSION - The major version of GTK2
9060 GTK2_MINOR_VERSION - The minor version of GTK2
9061 GTK2_PATCH_VERSION - The patch version of GTK2
9062 Optional variables you can define prior to calling this module:
9064 GTK2_DEBUG - Enables verbose debugging of the module
9066 GTK2_ADDITIONAL_SUFFIXES - Allows defining additional directories to
9067 search for include files
9068 ================= Example Usage:
9070 Call find_package() once, here are some examples to pick from:
9072 Require GTK 2.6 or later
9074 find_package(GTK2 2.6 REQUIRED gtk)
9075 Require GTK 2.10 or later and Glade
9077 find_package(GTK2 2.10 REQUIRED gtk glade)
9078 Search for GTK/GTKMM 2.8 or later
9080 find_package(GTK2 2.8 COMPONENTS gtk gtkmm)
9081 if(GTK2_FOUND)
9083 include_directories(${GTK2_INCLUDE_DIRS})
9084 add_executable(mygui mygui.cc)
9085 target_link_libraries(mygui ${GTK2_LIBRARIES})
9086 endif()
9087 FindGTK
9089 try to find GTK (and glib) and GTKGLArea
9090 GTK_INCLUDE_DIR - Directories to include to use GTK
9092 GTK_LIBRARIES - Files to link against to use GTK
9093 GTK_FOUND - GTK was found
9094 GTK_GL_FOUND - GTK's GL features were found
9095 FindHDF5
9097 Find HDF5, a library for reading and writing self describing array
9098 data.
9099 This module invokes the HDF5 wrapper compiler that should be installed
9101 alongside HDF5. Depending upon the HDF5 Configuration, the wrapper
9102 compiler is called either h5cc or h5pcc. If this succeeds, the module
9103 will then call the compiler with the -show argument to see what flags
9104 are used when compiling an HDF5 client application.
9105 The module will optionally accept the COMPONENTS argument. If no COM‐
9107 PONENTS are specified, then the find module will default to finding
9108 only the HDF5 C library. If one or more COMPONENTS are specified, the
9109 module will attempt to find the language bindings for the specified
9110 components. The only valid components are C, CXX, Fortran, HL, and
9111 Fortran_HL. If the COMPONENTS argument is not given, the module will
9112 attempt to find only the C bindings.
9113 This module will read the variable HDF5_USE_STATIC_LIBRARIES to deter‐
9115 mine whether or not to prefer a static link to a dynamic link for HDF5
9116 and all of it’s dependencies. To use this feature, make sure that the
9117 HDF5_USE_STATIC_LIBRARIES variable is set before the call to find_pack‐
9118 age.
9119 To provide the module with a hint about where to find your HDF5 instal‐
9121 lation, you can set the environment variable HDF5_ROOT. The Find mod‐
9122 ule will then look in this path when searching for HDF5 executables,
9123 paths, and libraries.
9124 Both the serial and parallel HDF5 wrappers are considered and the first
9126 directory to contain either one will be used. In the event that both
9127 appear in the same directory the serial version is preferentially
9128 selected. This behavior can be reversed by setting the variable
9129 HDF5_PREFER_PARALLEL to true.
9130 In addition to finding the includes and libraries required to compile
9132 an HDF5 client application, this module also makes an effort to find
9133 tools that come with the HDF5 distribution that may be useful for
9134 regression testing.
9135 Result Variables
9137 This module will set the following variables in your project:
9138 HDF5_FOUND
9140 HDF5 was found on the system
9141 HDF5_VERSION
9143 HDF5 library version
9144 HDF5_INCLUDE_DIRS
9146 Location of the HDF5 header files
9147 HDF5_DEFINITIONS
9149 Required compiler definitions for HDF5
9150 HDF5_LIBRARIES
9152 Required libraries for all requested bindings
9153 HDF5_HL_LIBRARIES
9155 Required libraries for the HDF5 high level API for all bindings,
9156 if the HL component is enabled
9157 Available components are: C CXX Fortran and HL. For each enabled lan‐
9159 guage binding, a corresponding HDF5_${LANG}_LIBRARIES variable, and
9160 potentially HDF5_${LANG}_DEFINITIONS, will be defined. If the HL com‐
9161 ponent is enabled, then an HDF5_${LANG}_HL_LIBRARIES will also be
9162 defined. With all components enabled, the following variables will be
9163 defined:
9164 HDF5_C_DEFINITIONS
9166 Required compiler definitions for HDF5 C bindings
9167 HDF5_CXX_DEFINITIONS
9169 Required compiler definitions for HDF5 C++ bindings
9170 HDF5_Fortran_DEFINITIONS
9172 Required compiler definitions for HDF5 Fortran bindings
9173 HDF5_C_INCLUDE_DIRS
9175 Required include directories for HDF5 C bindings
9176 HDF5_CXX_INCLUDE_DIRS
9178 Required include directories for HDF5 C++ bindings
9179 HDF5_Fortran_INCLUDE_DIRS
9181 Required include directories for HDF5 Fortran bindings
9182 HDF5_C_LIBRARIES
9184 Required libraries for the HDF5 C bindings
9185 HDF5_CXX_LIBRARIES
9187 Required libraries for the HDF5 C++ bindings
9188 HDF5_Fortran_LIBRARIES
9190 Required libraries for the HDF5 Fortran bindings
9191 HDF5_C_HL_LIBRARIES
9193 Required libraries for the high level C bindings
9194 HDF5_CXX_HL_LIBRARIES
9196 Required libraries for the high level C++ bindings
9197 HDF5_Fortran_HL_LIBRARIES
9199 Required libraries for the high level Fortran bindings.
9200 HDF5_IS_PARALLEL
9202 HDF5 library has parallel IO support
9203 HDF5_C_COMPILER_EXECUTABLE
9205 path to the HDF5 C wrapper compiler
9206 HDF5_CXX_COMPILER_EXECUTABLE
9208 path to the HDF5 C++ wrapper compiler
9209 HDF5_Fortran_COMPILER_EXECUTABLE
9211 path to the HDF5 Fortran wrapper compiler
9212 HDF5_C_COMPILER_EXECUTABLE_NO_INTERROGATE
9214 path to the primary C compiler which is also the HDF5 wrapper
9215 HDF5_CXX_COMPILER_EXECUTABLE_NO_INTERROGATE
9217 path to the primary C++ compiler which is also the HDF5 wrapper
9218 HDF5_Fortran_COMPILER_EXECUTABLE_NO_INTERROGATE
9220 path to the primary Fortran compiler which is also the HDF5
9221 wrapper
9222 HDF5_DIFF_EXECUTABLE
9224 path to the HDF5 dataset comparison tool
9225 Hints
9227 The following variable can be set to guide the search for HDF5
9228 libraries and includes:
9229 HDF5_ROOT
9231 Specify the path to the HDF5 installation to use.
9232 HDF5_FIND_DEBUG
9234 Set true to get extra debugging output.
9235 HDF5_NO_FIND_PACKAGE_CONFIG_FILE
9237 Set true to skip trying to find hdf5-config.cmake.
9238 FindHg
9240 Extract information from a mercurial working copy.
9241 The module defines the following variables:
9243 HG_EXECUTABLE - path to mercurial command line client (hg)
9245 HG_FOUND - true if the command line client was found
9246 HG_VERSION_STRING - the version of mercurial found
9247 If the command line client executable is found the following macro is
9249 defined:
9250 HG_WC_INFO(<dir> <var-prefix>)
9252 Hg_WC_INFO extracts information of a mercurial working copy at a given
9254 location. This macro defines the following variables:
9255 <var-prefix>_WC_CHANGESET - current changeset
9257 <var-prefix>_WC_REVISION - current revision
9258 Example usage:
9260 find_package(Hg)
9262 if(HG_FOUND)
9263 message("hg found: ${HG_EXECUTABLE}")
9264 HG_WC_INFO(${PROJECT_SOURCE_DIR} Project)
9265 message("Current revision is ${Project_WC_REVISION}")
9266 message("Current changeset is ${Project_WC_CHANGESET}")
9267 endif()
9268 FindHSPELL
9270 Try to find Hspell
9271 Once done this will define
9273 HSPELL_FOUND - system has Hspell
9275 HSPELL_INCLUDE_DIR - the Hspell include directory
9276 HSPELL_LIBRARIES - The libraries needed to use Hspell
9277 HSPELL_DEFINITIONS - Compiler switches required for using Hspell
9278 HSPELL_VERSION_STRING - The version of Hspell found (x.y)
9280 HSPELL_MAJOR_VERSION - the major version of Hspell
9281 HSPELL_MINOR_VERSION - The minor version of Hspell
9282 FindHTMLHelp
9284 This module looks for Microsoft HTML Help Compiler
9285 It defines:
9287 HTML_HELP_COMPILER : full path to the Compiler (hhc.exe)
9289 HTML_HELP_INCLUDE_PATH : include path to the API (htmlhelp.h)
9290 HTML_HELP_LIBRARY : full path to the library (htmlhelp.lib)
9291 FindIce
9293 Find the ZeroC Internet Communication Engine (ICE) programs, libraries
9294 and datafiles.
9295 This module supports multiple components. Components can include any
9297 of: Freeze, Glacier2, Ice, IceBox, IceDB, IceDiscovery, IceGrid, IceLo‐
9298 catorDiscovery, IcePatch, IceSSL, IceStorm, IceUtil, IceXML, or Slice.
9299 Ice 3.7 and later also include C++11-specific components: Glacier2++11,
9301 Ice++11, IceBox++11, IceDiscovery++11 IceGrid, IceLocatorDiscovery++11,
9302 IceSSL++11, IceStorm++11
9303 Note that the set of supported components is Ice version-specific.
9305 This module reports information about the Ice installation in several
9307 variables. General variables:
9308 Ice_VERSION - Ice release version
9310 Ice_FOUND - true if the main programs and libraries were found
9311 Ice_LIBRARIES - component libraries to be linked
9312 Ice_INCLUDE_DIRS - the directories containing the Ice headers
9313 Ice_SLICE_DIRS - the directories containing the Ice slice interface
9314 definitions
9315 Imported targets:
9317 Ice::<C>
9319 Where <C> is the name of an Ice component, for example Ice::Glacier2 or
9321 Ice++11.
9322 Ice slice programs are reported in:
9324 Ice_SLICE2CONFLUENCE_EXECUTABLE - path to slice2confluence executable
9326 Ice_SLICE2CPP_EXECUTABLE - path to slice2cpp executable
9327 Ice_SLICE2CS_EXECUTABLE - path to slice2cs executable
9328 Ice_SLICE2FREEZEJ_EXECUTABLE - path to slice2freezej executable
9329 Ice_SLICE2FREEZE_EXECUTABLE - path to slice2freeze executable
9330 Ice_SLICE2HTML_EXECUTABLE - path to slice2html executable
9331 Ice_SLICE2JAVA_EXECUTABLE - path to slice2java executable
9332 Ice_SLICE2JS_EXECUTABLE - path to slice2js executable
9333 Ice_SLICE2MATLAB_EXECUTABLE - path to slice2matlab executable
9334 Ice_SLICE2OBJC_EXECUTABLE - path to slice2objc executable
9335 Ice_SLICE2PHP_EXECUTABLE - path to slice2php executable
9336 Ice_SLICE2PY_EXECUTABLE - path to slice2py executable
9337 Ice_SLICE2RB_EXECUTABLE - path to slice2rb executable
9338 Ice programs are reported in:
9340 Ice_GLACIER2ROUTER_EXECUTABLE - path to glacier2router executable
9342 Ice_ICEBOX_EXECUTABLE - path to icebox executable
9343 Ice_ICEBOXXX11_EXECUTABLE - path to icebox++11 executable
9344 Ice_ICEBOXADMIN_EXECUTABLE - path to iceboxadmin executable
9345 Ice_ICEBOXD_EXECUTABLE - path to iceboxd executable
9346 Ice_ICEBOXNET_EXECUTABLE - path to iceboxnet executable
9347 Ice_ICEBRIDGE_EXECUTABLE - path to icebridge executable
9348 Ice_ICEGRIDADMIN_EXECUTABLE - path to icegridadmin executable
9349 Ice_ICEGRIDDB_EXECUTABLE - path to icegriddb executable
9350 Ice_ICEGRIDNODE_EXECUTABLE - path to icegridnode executable
9351 Ice_ICEGRIDNODED_EXECUTABLE - path to icegridnoded executable
9352 Ice_ICEGRIDREGISTRY_EXECUTABLE - path to icegridregistry executable
9353 Ice_ICEGRIDREGISTRYD_EXECUTABLE - path to icegridregistryd executable
9354 Ice_ICEPATCH2CALC_EXECUTABLE - path to icepatch2calc executable
9355 Ice_ICEPATCH2CLIENT_EXECUTABLE - path to icepatch2client executable
9356 Ice_ICEPATCH2SERVER_EXECUTABLE - path to icepatch2server executable
9357 Ice_ICESERVICEINSTALL_EXECUTABLE - path to iceserviceinstall executable
9358 Ice_ICESTORMADMIN_EXECUTABLE - path to icestormadmin executable
9359 Ice_ICESTORMDB_EXECUTABLE - path to icestormdb executable
9360 Ice_ICESTORMMIGRATE_EXECUTABLE - path to icestormmigrate executable
9361 Ice db programs (Windows only; standard system versions on all other
9363 platforms) are reported in:
9364 Ice_DB_ARCHIVE_EXECUTABLE - path to db_archive executable
9366 Ice_DB_CHECKPOINT_EXECUTABLE - path to db_checkpoint executable
9367 Ice_DB_DEADLOCK_EXECUTABLE - path to db_deadlock executable
9368 Ice_DB_DUMP_EXECUTABLE - path to db_dump executable
9369 Ice_DB_HOTBACKUP_EXECUTABLE - path to db_hotbackup executable
9370 Ice_DB_LOAD_EXECUTABLE - path to db_load executable
9371 Ice_DB_LOG_VERIFY_EXECUTABLE - path to db_log_verify executable
9372 Ice_DB_PRINTLOG_EXECUTABLE - path to db_printlog executable
9373 Ice_DB_RECOVER_EXECUTABLE - path to db_recover executable
9374 Ice_DB_STAT_EXECUTABLE - path to db_stat executable
9375 Ice_DB_TUNER_EXECUTABLE - path to db_tuner executable
9376 Ice_DB_UPGRADE_EXECUTABLE - path to db_upgrade executable
9377 Ice_DB_VERIFY_EXECUTABLE - path to db_verify executable
9378 Ice_DUMPDB_EXECUTABLE - path to dumpdb executable
9379 Ice_TRANSFORMDB_EXECUTABLE - path to transformdb executable
9380 Ice component libraries are reported in:
9382 Ice_<C>_FOUND - ON if component was found
9384 Ice_<C>_LIBRARIES - libraries for component
9385 Note that <C> is the uppercased name of the component.
9387 This module reads hints about search results from:
9389 Ice_HOME - the root of the Ice installation
9391 The environment variable ICE_HOME may also be used; the Ice_HOME vari‐
9393 able takes precedence.
9394 NOTE:
9396 On Windows, Ice 3.7.0 and later provide libraries via the NuGet
9397 package manager. Appropriate NuGet packages will be searched for
9398 using CMAKE_PREFIX_PATH, or alternatively Ice_HOME may be set to the
9399 location of a specific NuGet package to restrict the search.
9400 The following cache variables may also be set:
9402 Ice_<P>_EXECUTABLE - the path to executable <P>
9404 Ice_INCLUDE_DIR - the directory containing the Ice headers
9405 Ice_SLICE_DIR - the directory containing the Ice slice interface
9406 definitions
9407 Ice_<C>_LIBRARY - the library for component <C>
9408 NOTE:
9410 In most cases none of the above variables will require setting,
9411 unless multiple Ice versions are available and a specific version is
9412 required. On Windows, the most recent version of Ice will be found
9413 through the registry. On Unix, the programs, headers and libraries
9414 will usually be in standard locations, but Ice_SLICE_DIRS might not
9415 be automatically detected (commonly known locations are searched).
9416 All the other variables are defaulted using Ice_HOME, if set. It’s
9417 possible to set Ice_HOME and selectively specify alternative loca‐
9418 tions for the other components; this might be required for e.g.
9419 newer versions of Visual Studio if the heuristics are not sufficient
9420 to identify the correct programs and libraries for the specific Vis‐
9421 ual Studio version.
9422 Other variables one may set to control this module are:
9424 Ice_DEBUG - Set to ON to enable debug output from FindIce.
9426 FindIcotool
9428 Find icotool
9429 This module looks for icotool. This module defines the following val‐
9431 ues:
9432 ICOTOOL_EXECUTABLE: the full path to the icotool tool.
9434 ICOTOOL_FOUND: True if icotool has been found.
9435 ICOTOOL_VERSION_STRING: the version of icotool found.
9436 FindICU
9438 Find the International Components for Unicode (ICU) libraries and pro‐
9439 grams.
9440 This module supports multiple components. Components can include any
9442 of: data, i18n, io, le, lx, test, tu and uc.
9443 Note that on Windows data is named dt and i18n is named in; any of the
9445 names may be used, and the appropriate platform-specific library name
9446 will be automatically selected.
9447 This module reports information about the ICU installation in several
9449 variables. General variables:
9450 ICU_VERSION - ICU release version
9452 ICU_FOUND - true if the main programs and libraries were found
9453 ICU_LIBRARIES - component libraries to be linked
9454 ICU_INCLUDE_DIRS - the directories containing the ICU headers
9455 Imported targets:
9457 ICU::<C>
9459 Where <C> is the name of an ICU component, for example ICU::i18n.
9461 ICU programs are reported in:
9463 ICU_GENCNVAL_EXECUTABLE - path to gencnval executable
9465 ICU_ICUINFO_EXECUTABLE - path to icuinfo executable
9466 ICU_GENBRK_EXECUTABLE - path to genbrk executable
9467 ICU_ICU-CONFIG_EXECUTABLE - path to icu-config executable
9468 ICU_GENRB_EXECUTABLE - path to genrb executable
9469 ICU_GENDICT_EXECUTABLE - path to gendict executable
9470 ICU_DERB_EXECUTABLE - path to derb executable
9471 ICU_PKGDATA_EXECUTABLE - path to pkgdata executable
9472 ICU_UCONV_EXECUTABLE - path to uconv executable
9473 ICU_GENCFU_EXECUTABLE - path to gencfu executable
9474 ICU_MAKECONV_EXECUTABLE - path to makeconv executable
9475 ICU_GENNORM2_EXECUTABLE - path to gennorm2 executable
9476 ICU_GENCCODE_EXECUTABLE - path to genccode executable
9477 ICU_GENSPREP_EXECUTABLE - path to gensprep executable
9478 ICU_ICUPKG_EXECUTABLE - path to icupkg executable
9479 ICU_GENCMN_EXECUTABLE - path to gencmn executable
9480 ICU component libraries are reported in:
9482 ICU_<C>_FOUND - ON if component was found
9484 ICU_<C>_LIBRARIES - libraries for component
9485 ICU datafiles are reported in:
9487 ICU_MAKEFILE_INC - Makefile.inc
9489 ICU_PKGDATA_INC - pkgdata.inc
9490 Note that <C> is the uppercased name of the component.
9492 This module reads hints about search results from:
9494 ICU_ROOT - the root of the ICU installation
9496 The environment variable ICU_ROOT may also be used; the ICU_ROOT vari‐
9498 able takes precedence.
9499 The following cache variables may also be set:
9501 ICU_<P>_EXECUTABLE - the path to executable <P>
9503 ICU_INCLUDE_DIR - the directory containing the ICU headers
9504 ICU_<C>_LIBRARY - the library for component <C>
9505 NOTE:
9507 In most cases none of the above variables will require setting,
9508 unless multiple ICU versions are available and a specific version is
9509 required.
9510 Other variables one may set to control this module are:
9512 ICU_DEBUG - Set to ON to enable debug output from FindICU.
9514 FindImageMagick
9516 Find the ImageMagick binary suite.
9517 This module will search for a set of ImageMagick tools specified as
9519 components in the FIND_PACKAGE call. Typical components include, but
9520 are not limited to (future versions of ImageMagick might have addi‐
9521 tional components not listed here):
9522 animate
9524 compare
9525 composite
9526 conjure
9527 convert
9528 display
9529 identify
9530 import
9531 mogrify
9532 montage
9533 stream
9534 If no component is specified in the FIND_PACKAGE call, then it only
9536 searches for the ImageMagick executable directory. This code defines
9537 the following variables:
9538 ImageMagick_FOUND - TRUE if all components are found.
9540 ImageMagick_EXECUTABLE_DIR - Full path to executables directory.
9541 ImageMagick_<component>_FOUND - TRUE if <component> is found.
9542 ImageMagick_<component>_EXECUTABLE - Full path to <component> executable.
9543 ImageMagick_VERSION_STRING - the version of ImageMagick found
9544 (since CMake 2.8.8)
9545 ImageMagick_VERSION_STRING will not work for old versions like 5.2.3.
9547 There are also components for the following ImageMagick APIs:
9549 Magick++
9551 MagickWand
9552 MagickCore
9553 For these components the following variables are set:
9555 ImageMagick_FOUND - TRUE if all components are found.
9557 ImageMagick_INCLUDE_DIRS - Full paths to all include dirs.
9558 ImageMagick_LIBRARIES - Full paths to all libraries.
9559 ImageMagick_<component>_FOUND - TRUE if <component> is found.
9560 ImageMagick_<component>_INCLUDE_DIRS - Full path to <component> include dirs.
9561 ImageMagick_<component>_LIBRARIES - Full path to <component> libraries.
9562 Example Usages:
9564 find_package(ImageMagick)
9566 find_package(ImageMagick COMPONENTS convert)
9567 find_package(ImageMagick COMPONENTS convert mogrify display)
9568 find_package(ImageMagick COMPONENTS Magick++)
9569 find_package(ImageMagick COMPONENTS Magick++ convert)
9570 Note that the standard FIND_PACKAGE features are supported (i.e.,
9572 QUIET, REQUIRED, etc.).
9573 FindIconv
9575 This module finds the iconv() POSIX.1 functions on the system. These
9576 functions might be provided in the regular C library or externally in
9577 the form of an additional library.
9578 The following variables are provided to indicate iconv support:
9580 Iconv_FOUND
9582 Variable indicating if the iconv support was found.
9583 Iconv_INCLUDE_DIRS
9585 The directories containing the iconv headers.
9586 Iconv_LIBRARIES
9588 The iconv libraries to be linked.
9589 Iconv_IS_BUILT_IN
9591 A variable indicating whether iconv support is stemming from the
9592 C library or not. Even if the C library provides iconv(), the
9593 presence of an external libiconv implementation might lead to
9594 this being false.
9595 Additionally, the following IMPORTED target is being provided:
9597 Iconv::Iconv
9599 Imported target for using iconv.
9600 The following cache variables may also be set:
9602 Iconv_INCLUDE_DIR
9604 The directory containing the iconv headers.
9605 Iconv_LIBRARY
9607 The iconv library (if not implicitly given in the C library).
9608 NOTE:
9610 On POSIX platforms, iconv might be part of the C library and the
9611 cache variables Iconv_INCLUDE_DIR and Iconv_LIBRARY might be empty.
9612 FindIntl
9614 Find the Gettext libintl headers and libraries.
9615 This module reports information about the Gettext libintl installation
9617 in several variables. General variables:
9618 Intl_FOUND - true if the libintl headers and libraries were found
9620 Intl_INCLUDE_DIRS - the directory containing the libintl headers
9621 Intl_LIBRARIES - libintl libraries to be linked
9622 The following cache variables may also be set:
9624 Intl_INCLUDE_DIR - the directory containing the libintl headers
9626 Intl_LIBRARY - the libintl library (if any)
9627 NOTE:
9629 On some platforms, such as Linux with GNU libc, the gettext func‐
9630 tions are present in the C standard library and libintl is not
9631 required. Intl_LIBRARIES will be empty in this case.
9632 NOTE:
9634 If you wish to use the Gettext tools (msgmerge, msgfmt, etc.), use
9635 FindGettext.
9636 FindITK
9638 This module no longer exists.
9639 This module existed in versions of CMake prior to 3.1, but became only
9641 a thin wrapper around find_package(ITK NO_MODULE) to provide compati‐
9642 bility for projects using long-outdated conventions. Now find_pack‐
9643 age(ITK) will search for ITKConfig.cmake directly.
9644 FindJasper
9646 Try to find the Jasper JPEG2000 library
9647 Once done this will define
9649 JASPER_FOUND - system has Jasper
9651 JASPER_INCLUDE_DIR - the Jasper include directory
9652 JASPER_LIBRARIES - the libraries needed to use Jasper
9653 JASPER_VERSION_STRING - the version of Jasper found (since CMake 2.8.8)
9654 FindJava
9656 Find Java
9657 This module finds if Java is installed and determines where the include
9659 files and libraries are. The caller may set variable JAVA_HOME to
9660 specify a Java installation prefix explicitly.
9661 See also the FindJNI module to find Java Native Interface (JNI).
9663 Specify one or more of the following components as you call this find
9665 module. See example below.
9666 Runtime = Java Runtime Environment used to execute Java byte-compiled applications
9668 Development = Development tools (java, javac, javah, jar and javadoc), includes Runtime component
9669 IdlJ = Interface Description Language (IDL) to Java compiler
9670 JarSigner = Signer and verifier tool for Java Archive (JAR) files
9671 This module sets the following result variables:
9673 Java_JAVA_EXECUTABLE = the full path to the Java runtime
9675 Java_JAVAC_EXECUTABLE = the full path to the Java compiler
9676 Java_JAVAH_EXECUTABLE = the full path to the Java header generator
9677 Java_JAVADOC_EXECUTABLE = the full path to the Java documentation generator
9678 Java_IDLJ_EXECUTABLE = the full path to the Java idl compiler
9679 Java_JAR_EXECUTABLE = the full path to the Java archiver
9680 Java_JARSIGNER_EXECUTABLE = the full path to the Java jar signer
9681 Java_VERSION_STRING = Version of java found, eg. 1.6.0_12
9682 Java_VERSION_MAJOR = The major version of the package found.
9683 Java_VERSION_MINOR = The minor version of the package found.
9684 Java_VERSION_PATCH = The patch version of the package found.
9685 Java_VERSION_TWEAK = The tweak version of the package found (after '_')
9686 Java_VERSION = This is set to: $major[.$minor[.$patch[.$tweak]]]
9687 The minimum required version of Java can be specified using the
9689 find_package() syntax, e.g.
9690 find_package(Java 1.8)
9692 NOTE: ${Java_VERSION} and ${Java_VERSION_STRING} are not guaranteed to
9694 be identical. For example some java version may return: Java_VER‐
9695 SION_STRING = 1.8.0_17 and Java_VERSION = 1.8.0.17
9696 another example is the Java OEM, with: Java_VERSION_STRING = 1.8.0-oem
9698 and Java_VERSION = 1.8.0
9699 For these components the following variables are set:
9701 Java_FOUND - TRUE if all components are found.
9703 Java_<component>_FOUND - TRUE if <component> is found.
9704 Example Usages:
9706 find_package(Java)
9708 find_package(Java 1.8 REQUIRED)
9709 find_package(Java COMPONENTS Runtime)
9710 find_package(Java COMPONENTS Development)
9711 FindJNI
9713 Find Java Native Interface (JNI) libraries.
9714 JNI enables Java code running in a Java Virtual Machine (JVM) to call
9716 and be called by native applications and libraries written in other
9717 languages such as C, C++.
9718 This module finds if Java is installed and determines where the include
9720 files and libraries are. It also determines what the name of the
9721 library is. The caller may set variable JAVA_HOME to specify a Java
9722 installation prefix explicitly.
9723 Result Variables
9725 This module sets the following result variables:
9726 JNI_INCLUDE_DIRS
9728 the include dirs to use
9729 JNI_LIBRARIES
9731 the libraries to use (JAWT and JVM)
9732 JNI_FOUND
9734 TRUE if JNI headers and libraries were found.
9735 Cache Variables
9737 The following cache variables are also available to set or use:
9738 JAVA_AWT_LIBRARY
9740 the path to the Java AWT Native Interface (JAWT) library
9741 JAVA_JVM_LIBRARY
9743 the path to the Java Virtual Machine (JVM) library
9744 JAVA_INCLUDE_PATH
9746 the include path to jni.h
9747 JAVA_INCLUDE_PATH2
9749 the include path to jni_md.h and jniport.h
9750 JAVA_AWT_INCLUDE_PATH
9752 the include path to jawt.h
9753 FindJPEG
9755 Find the JPEG library (libjpeg)
9756 Imported targets
9758 This module defines the following IMPORTED targets:
9759 JPEG::JPEG
9761 The JPEG library, if found.
9762 Result variables
9764 This module will set the following variables in your project:
9765 JPEG_FOUND
9767 If false, do not try to use JPEG.
9768 JPEG_INCLUDE_DIRS
9770 where to find jpeglib.h, etc.
9771 JPEG_LIBRARIES
9773 the libraries needed to use JPEG.
9774 JPEG_VERSION
9776 the version of the JPEG library found
9777 Cache variables
9779 The following cache variables may also be set:
9780 JPEG_INCLUDE_DIRS
9782 where to find jpeglib.h, etc.
9783 JPEG_LIBRARY_RELEASE
9785 where to find the JPEG library (optimized).
9786 JPEG_LIBRARY_DEBUG
9788 where to find the JPEG library (debug).
9789 Obsolete variables
9791 JPEG_INCLUDE_DIR
9792 where to find jpeglib.h, etc. (same as JPEG_INCLUDE_DIRS)
9793 JPEG_LIBRARY
9795 where to find the JPEG library.
9796 FindKDE3
9798 Find the KDE3 include and library dirs, KDE preprocessors and define a
9799 some macros
9800 This module defines the following variables:
9802 KDE3_DEFINITIONS
9804 compiler definitions required for compiling KDE software
9805 KDE3_INCLUDE_DIR
9807 the KDE include directory
9808 KDE3_INCLUDE_DIRS
9810 the KDE and the Qt include directory, for use with
9811 include_directories()
9812 KDE3_LIB_DIR
9814 the directory where the KDE libraries are installed, for use
9815 with link_directories()
9816 QT_AND_KDECORE_LIBS
9818 this contains both the Qt and the kdecore library
9819 KDE3_DCOPIDL_EXECUTABLE
9821 the dcopidl executable
9822 KDE3_DCOPIDL2CPP_EXECUTABLE
9824 the dcopidl2cpp executable
9825 KDE3_KCFGC_EXECUTABLE
9827 the kconfig_compiler executable
9828 KDE3_FOUND
9830 set to TRUE if all of the above has been found
9831 The following user adjustable options are provided:
9833 KDE3_BUILD_TESTS
9835 enable this to build KDE testcases
9836 It also adds the following macros (from KDE3Macros.cmake) SRCS_VAR is
9838 always the variable which contains the list of source files for your
9839 application or library.
9840 KDE3_AUTOMOC(file1 … fileN)
9842 Call this if you want to have automatic moc file handling.
9844 This means if you include "foo.moc" in the source file foo.cpp
9845 a moc file for the header foo.h will be created automatically.
9846 You can set the property SKIP_AUTOMAKE using set_source_files_properties()
9847 to exclude some files in the list from being processed.
9848 KDE3_ADD_MOC_FILES(SRCS_VAR file1 … fileN )
9850 If you don't use the KDE3_AUTOMOC() macro, for the files
9852 listed here moc files will be created (named "foo.moc.cpp")
9853 KDE3_ADD_DCOP_SKELS(SRCS_VAR header1.h … headerN.h )
9855 Use this to generate DCOP skeletions from the listed headers.
9857 KDE3_ADD_DCOP_STUBS(SRCS_VAR header1.h … headerN.h )
9859 Use this to generate DCOP stubs from the listed headers.
9861 KDE3_ADD_UI_FILES(SRCS_VAR file1.ui … fileN.ui )
9863 Use this to add the Qt designer ui files to your application/library.
9865 KDE3_ADD_KCFG_FILES(SRCS_VAR file1.kcfgc … fileN.kcfgc )
9867 Use this to add KDE kconfig compiler files to your application/library.
9869 KDE3_INSTALL_LIBTOOL_FILE(target)
9871 This will create and install a simple libtool file for the given target.
9873 KDE3_ADD_EXECUTABLE(name file1 … fileN )
9875 Currently identical to add_executable(), may provide some advanced
9877 features in the future.
9878 KDE3_ADD_KPART(name [WITH_PREFIX] file1 … fileN )
9880 Create a KDE plugin (KPart, kioslave, etc.) from the given source files.
9882 If WITH_PREFIX is given, the resulting plugin will have the prefix "lib",
9883 otherwise it won't.
9884 It creates and installs an appropriate libtool la-file.
9885 KDE3_ADD_KDEINIT_EXECUTABLE(name file1 … fileN )
9887 Create a KDE application in the form of a module loadable via kdeinit.
9889 A library named kdeinit_<name> will be created and a small executable
9890 which links to it.
9891 The option KDE3_ENABLE_FINAL to enable all-in-one compilation is no
9893 longer supported.
9894 Author: Alexander Neundorf <neundorf@kde.org>
9896 FindKDE4
9898 Find KDE4 and provide all necessary variables and macros to compile
9899 software for it. It looks for KDE 4 in the following directories in
9900 the given order:
9901 CMAKE_INSTALL_PREFIX
9903 KDEDIRS
9904 /opt/kde4
9905 Please look in FindKDE4Internal.cmake and KDE4Macros.cmake for more
9907 information. They are installed with the KDE 4 libraries in
9908 $KDEDIRS/share/apps/cmake/modules/.
9909 Author: Alexander Neundorf <neundorf@kde.org>
9911 FindLAPACK
9913 Find LAPACK library
9914 This module finds an installed fortran library that implements the
9916 LAPACK linear-algebra interface (see http://www.netlib.org/lapack/).
9917 The approach follows that taken for the autoconf macro file,
9919 acx_lapack.m4 (distributed at
9920 http://ac-archive.sourceforge.net/ac-archive/acx_lapack.html).
9921 Input Variables
9923 The following variables may be set to influence this module’s behavior:
9924 BLA_STATIC
9926 if ON use static linkage
9927 BLA_VENDOR
9929 If set, checks only the specified vendor, if not set checks all
9930 the possibilities. List of vendors valid in this module:
9931 · Intel10_32 (intel mkl v10 32 bit)
9933 · Intel10_64lp (intel mkl v10+ 64 bit, threaded code, lp64
9935 model)
9936 · Intel10_64lp_seq (intel mkl v10+ 64 bit, sequential code, lp64
9938 model)
9939 · Intel10_64ilp (intel mkl v10+ 64 bit, threaded code, ilp64
9941 model)
9942 · Intel10_64ilp_seq (intel mkl v10+ 64 bit, sequential code,
9944 ilp64 model)
9945 · Intel (obsolete versions of mkl 32 and 64 bit)
9947 · OpenBLAS
9949 · FLAME
9951 · ACML
9953 · Apple
9955 · NAS
9957 · Generic
9959 BLA_F95
9961 if ON tries to find BLAS95/LAPACK95
9962 Result Variables
9964 This module defines the following variables:
9965 LAPACK_FOUND
9967 library implementing the LAPACK interface is found
9968 LAPACK_LINKER_FLAGS
9970 uncached list of required linker flags (excluding -l and -L).
9971 LAPACK_LIBRARIES
9973 uncached list of libraries (using full path name) to link
9974 against to use LAPACK
9975 LAPACK95_LIBRARIES
9977 uncached list of libraries (using full path name) to link
9978 against to use LAPACK95
9979 LAPACK95_FOUND
9981 library implementing the LAPACK95 interface is found
9982 NOTE:
9984 C or CXX must be enabled to use Intel MKL
9985 For example, to use Intel MKL libraries and/or Intel compiler:
9987 set(BLA_VENDOR Intel10_64lp)
9989 find_package(LAPACK)
9990 FindLATEX
9992 Find Latex
9993 This module finds an installed Latex and determines the location of the
9995 compiler. Additionally the module looks for Latex-related software
9996 like BibTeX.
9997 This module sets the following result variables:
9999 LATEX_FOUND: whether found Latex and requested components
10001 LATEX_<component>_FOUND: whether found <component>
10002 LATEX_COMPILER: path to the LaTeX compiler
10003 PDFLATEX_COMPILER: path to the PdfLaTeX compiler
10004 XELATEX_COMPILER: path to the XeLaTeX compiler
10005 LUALATEX_COMPILER: path to the LuaLaTeX compiler
10006 BIBTEX_COMPILER: path to the BibTeX compiler
10007 BIBER_COMPILER: path to the Biber compiler
10008 MAKEINDEX_COMPILER: path to the MakeIndex compiler
10009 XINDY_COMPILER: path to the xindy compiler
10010 DVIPS_CONVERTER: path to the DVIPS converter
10011 DVIPDF_CONVERTER: path to the DVIPDF converter
10012 PS2PDF_CONVERTER: path to the PS2PDF converter
10013 PDFTOPS_CONVERTER: path to the pdftops converter
10014 LATEX2HTML_CONVERTER: path to the LaTeX2Html converter
10015 HTLATEX_COMPILER: path to the htlatex compiler
10016 Possible components are:
10018 PDFLATEX
10020 XELATEX
10021 LUALATEX
10022 BIBTEX
10023 BIBER
10024 MAKEINDEX
10025 XINDY
10026 DVIPS
10027 DVIPDF
10028 PS2PDF
10029 PDFTOPS
10030 LATEX2HTML
10031 HTLATEX
10032 Example Usages:
10034 find_package(LATEX)
10036 find_package(LATEX COMPONENTS PDFLATEX)
10037 find_package(LATEX COMPONENTS BIBTEX PS2PDF)
10038 FindLibArchive
10040 Find libarchive library and headers
10041 The module defines the following variables:
10043 LibArchive_FOUND - true if libarchive was found
10045 LibArchive_INCLUDE_DIRS - include search path
10046 LibArchive_LIBRARIES - libraries to link
10047 LibArchive_VERSION - libarchive 3-component version number
10048 FindLibinput
10050 Find libinput headers and library.
10051 Imported Targets
10053 Libinput::Libinput
10054 The libinput library, if found.
10055 Result Variables
10057 This will define the following variables in your project:
10058 Libinput_FOUND
10060 true if (the requested version of) libinput is available.
10061 Libinput_VERSION
10063 the version of libinput.
10064 Libinput_LIBRARIES
10066 the libraries to link against to use libinput.
10067 Libinput_INCLUDE_DIRS
10069 where to find the libinput headers.
10070 Libinput_COMPILE_OPTIONS
10072 this should be passed to target_compile_options(), if the target
10073 is not used for linking
10074 FindLibLZMA
10076 Find LZMA compression algorithm headers and library.
10077 Imported Targets
10079 This module defines IMPORTED target LibLZMA::LibLZMA, if liblzma has
10080 been found.
10081 Result variables
10083 This module will set the following variables in your project:
10084 LIBLZMA_FOUND
10086 True if liblzma headers and library were found.
10087 LIBLZMA_INCLUDE_DIRS
10089 Directory where liblzma headers are located.
10090 LIBLZMA_LIBRARIES
10092 Lzma libraries to link against.
10093 LIBLZMA_HAS_AUTO_DECODER
10095 True if lzma_auto_decoder() is found (required).
10096 LIBLZMA_HAS_EASY_ENCODER
10098 True if lzma_easy_encoder() is found (required).
10099 LIBLZMA_HAS_LZMA_PRESET
10101 True if lzma_lzma_preset() is found (required).
10102 LIBLZMA_VERSION_MAJOR
10104 The major version of lzma
10105 LIBLZMA_VERSION_MINOR
10107 The minor version of lzma
10108 LIBLZMA_VERSION_PATCH
10110 The patch version of lzma
10111 LIBLZMA_VERSION_STRING
10113 version number as a string (ex: “5.0.3”)
10114 FindLibXml2
10116 Find the XML processing library (libxml2).
10117 IMPORTED Targets
10119 This module defines IMPORTED target LibXml2::LibXml2, if libxml2 has
10120 been found.
10121 Result variables
10123 This module will set the following variables in your project:
10124 LibXml2_FOUND
10126 true if libxml2 headers and libraries were found
10127 LIBXML2_INCLUDE_DIR
10129 the directory containing LibXml2 headers
10130 LIBXML2_INCLUDE_DIRS
10132 list of the include directories needed to use LibXml2
10133 LIBXML2_LIBRARIES
10135 LibXml2 libraries to be linked
10136 LIBXML2_DEFINITIONS
10138 the compiler switches required for using LibXml2
10139 LIBXML2_XMLLINT_EXECUTABLE
10141 path to the XML checking tool xmllint coming with LibXml2
10142 LIBXML2_VERSION_STRING
10144 the version of LibXml2 found (since CMake 2.8.8)
10145 Cache variables
10147 The following cache variables may also be set:
10148 LIBXML2_INCLUDE_DIR
10150 the directory containing LibXml2 headers
10151 LIBXML2_LIBRARY
10153 path to the LibXml2 library
10154 FindLibXslt
10156 Try to find the LibXslt library
10157 Once done this will define
10159 LIBXSLT_FOUND - system has LibXslt
10161 LIBXSLT_INCLUDE_DIR - the LibXslt include directory
10162 LIBXSLT_LIBRARIES - Link these to LibXslt
10163 LIBXSLT_DEFINITIONS - Compiler switches required for using LibXslt
10164 LIBXSLT_VERSION_STRING - version of LibXslt found (since CMake 2.8.8)
10165 Additionally, the following two variables are set (but not required for
10167 using xslt):
10168 LIBXSLT_EXSLT_LIBRARIES
10170 Link to these if you need to link against the exslt library.
10171 LIBXSLT_XSLTPROC_EXECUTABLE
10173 Contains the full path to the xsltproc executable if found.
10174 FindLTTngUST
10176 This module finds the LTTng-UST library.
10177 Imported target
10179 This module defines the following IMPORTED target:
10180 LTTng::UST
10182 The LTTng-UST library, if found
10183 Result variables
10185 This module sets the following
10186 LTTNGUST_FOUND
10188 TRUE if system has LTTng-UST
10189 LTTNGUST_INCLUDE_DIRS
10191 The LTTng-UST include directories
10192 LTTNGUST_LIBRARIES
10194 The libraries needed to use LTTng-UST
10195 LTTNGUST_VERSION_STRING
10197 The LTTng-UST version
10198 LTTNGUST_HAS_TRACEF
10200 TRUE if the tracef() API is available in the system’s LTTng-UST
10201 LTTNGUST_HAS_TRACELOG
10203 TRUE if the tracelog() API is available in the system’s
10204 LTTng-UST
10205 FindLua50
10207 Locate Lua library This module defines
10208 LUA50_FOUND, if false, do not try to link to Lua
10210 LUA_LIBRARIES, both lua and lualib
10211 LUA_INCLUDE_DIR, where to find lua.h and lualib.h (and probably lauxlib.h)
10212 Note that the expected include convention is
10214 #include "lua.h"
10216 and not
10218 #include <lua/lua.h>
10220 This is because, the lua location is not standardized and may exist in
10222 locations other than lua/
10223 FindLua51
10225 Locate Lua library This module defines
10226 LUA51_FOUND, if false, do not try to link to Lua
10228 LUA_LIBRARIES
10229 LUA_INCLUDE_DIR, where to find lua.h
10230 LUA_VERSION_STRING, the version of Lua found (since CMake 2.8.8)
10231 Note that the expected include convention is
10233 #include "lua.h"
10235 and not
10237 #include <lua/lua.h>
10239 This is because, the lua location is not standardized and may exist in
10241 locations other than lua/
10242 FindLua
10244 Locate Lua library This module defines
10245 LUA_FOUND - if false, do not try to link to Lua
10247 LUA_LIBRARIES - both lua and lualib
10248 LUA_INCLUDE_DIR - where to find lua.h
10249 LUA_VERSION_STRING - the version of Lua found
10250 LUA_VERSION_MAJOR - the major version of Lua
10251 LUA_VERSION_MINOR - the minor version of Lua
10252 LUA_VERSION_PATCH - the patch version of Lua
10253 Note that the expected include convention is
10255 #include "lua.h"
10257 and not
10259 #include <lua/lua.h>
10261 This is because, the lua location is not standardized and may exist in
10263 locations other than lua/
10264 FindMatlab
10266 Finds Matlab or Matlab Compiler Runtime (MCR) and provides Matlab
10267 tools, libraries and compilers to CMake.
10268 This package primary purpose is to find the libraries associated with
10270 Matlab or the MCR in order to be able to build Matlab extensions (mex
10271 files). It can also be used:
10272 · to run specific commands in Matlab in case Matlab is available
10274 · for declaring Matlab unit test
10276 · to retrieve various information from Matlab (mex extensions, versions
10278 and release queries, …)
10279 The module supports the following components:
10281 · ENG_LIBRARY and MAT_LIBRARY: respectively the ENG and MAT libraries
10283 of Matlab
10284 · MAIN_PROGRAM the Matlab binary program. Note that this component is
10286 not available on the MCR version, and will yield an error if the MCR
10287 is found instead of the regular Matlab installation.
10288 · MEX_COMPILER the MEX compiler.
10290 · MCC_COMPILER the MCC compiler, included with the Matlab Compiler
10292 add-on.
10293 · SIMULINK the Simulink environment.
10295 NOTE:
10297 The version given to the find_package() directive is the Matlab ver‐
10298 sion, which should not be confused with the Matlab release name (eg.
10299 R2014). The matlab_get_version_from_release_name() and
10300 matlab_get_release_name_from_version() provide a mapping between the
10301 release name and the version.
10302 The variable Matlab_ROOT_DIR may be specified in order to give the path
10304 of the desired Matlab version. Otherwise, the behaviour is platform
10305 specific:
10306 · Windows: The installed versions of Matlab/MCR are retrieved from the
10308 Windows registry
10309 · OS X: The installed versions of Matlab/MCR are given by the MATLAB
10311 default installation paths in /Application. If no such application is
10312 found, it falls back to the one that might be accessible from the
10313 PATH.
10314 · Unix: The desired Matlab should be accessible from the PATH. This
10316 does not work for MCR installation and Matlab_ROOT_DIR should be
10317 specified on this platform.
10318 Additional information is provided when MATLAB_FIND_DEBUG is set. When
10320 a Matlab/MCR installation is found automatically and the MATLAB_VERSION
10321 is not given, the version is queried from Matlab directly (on Windows
10322 this may pop up a Matlab window) or from the MCR installation.
10323 The mapping of the release names and the version of Matlab is performed
10325 by defining pairs (name, version). The variable
10326 MATLAB_ADDITIONAL_VERSIONS may be provided before the call to the
10327 find_package() in order to handle additional versions.
10328 A Matlab scripts can be added to the set of tests using the
10330 matlab_add_unit_test(). By default, the Matlab unit test framework will
10331 be used (>= 2013a) to run this script, but regular .m files returning
10332 an exit code can be used as well (0 indicating a success).
10333 Module Input Variables
10335 Users or projects may set the following variables to configure the mod‐
10336 ule behaviour:
10337 Matlab_ROOT_DIR
10339 the root of the Matlab installation.
10340 MATLAB_FIND_DEBUG
10342 outputs debug information
10343 MATLAB_ADDITIONAL_VERSIONS
10345 additional versions of Matlab for the automatic retrieval of the
10346 installed versions.
10347 Variables defined by the module
10349 Result variables
10350 Matlab_FOUND
10351 TRUE if the Matlab installation is found, FALSE otherwise. All
10352 variable below are defined if Matlab is found.
10353 Matlab_ROOT_DIR
10355 the final root of the Matlab installation determined by the
10356 FindMatlab module.
10357 Matlab_MAIN_PROGRAM
10359 the Matlab binary program. Available only if the component
10360 MAIN_PROGRAM is given in the find_package() directive.
10361 Matlab_INCLUDE_DIRS
10363 the path of the Matlab libraries headers
10364 Matlab_MEX_LIBRARY
10366 library for mex, always available.
10367 Matlab_MX_LIBRARY
10369 mx library of Matlab (arrays), always available.
10370 Matlab_ENG_LIBRARY
10372 Matlab engine library. Available only if the component
10373 ENG_LIBRARY is requested.
10374 Matlab_MAT_LIBRARY
10376 Matlab matrix library. Available only if the component
10377 MAT_LIBRARY is requested.
10378 Matlab_ENGINE_LIBRARY
10380 Matlab C++ engine library, always available for R2018a and
10381 newer.
10382 Matlab_DATAARRAY_LIBRARY
10384 Matlab C++ data array library, always available for R2018a and
10385 newer.
10386 Matlab_LIBRARIES
10388 the whole set of libraries of Matlab
10389 Matlab_MEX_COMPILER
10391 the mex compiler of Matlab. Currently not used. Available only
10392 if the component MEX_COMPILER is requested.
10393 Matlab_MCC_COMPILER
10395 the mcc compiler of Matlab. Included with the Matlab Compiler
10396 add-on. Available only if the component MCC_COMPILER is
10397 requested.
10398 Cached variables
10400 Matlab_MEX_EXTENSION
10401 the extension of the mex files for the current platform (given
10402 by Matlab).
10403 Matlab_ROOT_DIR
10405 the location of the root of the Matlab installation found. If
10406 this value is changed by the user, the result variables are
10407 recomputed.
10408 Provided macros
10410 matlab_get_version_from_release_name()
10411 returns the version from the release name
10412 matlab_get_release_name_from_version()
10414 returns the release name from the Matlab version
10415 Provided functions
10417 matlab_add_mex()
10418 adds a target compiling a MEX file.
10419 matlab_add_unit_test()
10421 adds a Matlab unit test file as a test to the project.
10422 matlab_extract_all_installed_versions_from_registry()
10424 parses the registry for all Matlab versions. Available on Win‐
10425 dows only. The part of the registry parsed is dependent on the
10426 host processor
10427 matlab_get_all_valid_matlab_roots_from_registry()
10429 returns all the possible Matlab or MCR paths, according to a
10430 previously given list. Only the existing/accessible paths are
10431 kept. This is mainly useful for the searching all possible Mat‐
10432 lab installation.
10433 matlab_get_mex_suffix()
10435 returns the suffix to be used for the mex files (platform/archi‐
10436 tecture dependent)
10437 matlab_get_version_from_matlab_run()
10439 returns the version of Matlab/MCR, given the full directory of
10440 the Matlab/MCR installation path.
10441 Known issues
10443 Symbol clash in a MEX target
10444 By default, every symbols inside a MEX file defined with the
10445 command matlab_add_mex() have hidden visibility, except for the
10446 entry point. This is the default behaviour of the MEX compiler,
10447 which lowers the risk of symbol collision between the libraries
10448 shipped with Matlab, and the libraries to which the MEX file is
10449 linking to. This is also the default on Windows platforms.
10450 However, this is not sufficient in certain case, where for
10452 instance your MEX file is linking against libraries that are
10453 already loaded by Matlab, even if those libraries have different
10454 SONAMES. A possible solution is to hide the symbols of the
10455 libraries to which the MEX target is linking to. This can be
10456 achieved in GNU GCC compilers with the linker option
10457 -Wl,--exclude-libs,ALL.
10458 Tests using GPU resources
10460 in case your MEX file is using the GPU and in order to be able
10461 to run unit tests on this MEX file, the GPU resources should be
10462 properly released by Matlab. A possible solution is to make Mat‐
10463 lab aware of the use of the GPU resources in the session, which
10464 can be performed by a command such as D = gpuDevice() at the
10465 beginning of the test script (or via a fixture).
10466 Reference
10468 Matlab_ROOT_DIR
10469 The root folder of the Matlab installation. If set before the
10470 call to find_package(), the module will look for the components
10471 in that path. If not set, then an automatic search of Matlab
10472 will be performed. If set, it should point to a valid version of
10473 Matlab.
10474 MATLAB_FIND_DEBUG
10476 If set, the lookup of Matlab and the intermediate configuration
10477 steps are outputted to the console.
10478 MATLAB_ADDITIONAL_VERSIONS
10480 If set, specifies additional versions of Matlab that may be
10481 looked for. The variable should be a list of strings, organised
10482 by pairs of release name and versions, such as follows:
10483 set(MATLAB_ADDITIONAL_VERSIONS
10485 "release_name1=corresponding_version1"
10486 "release_name2=corresponding_version2"
10487 ...
10488 )
10489 Example:
10491 set(MATLAB_ADDITIONAL_VERSIONS
10493 "R2013b=8.2"
10494 "R2013a=8.1"
10495 "R2012b=8.0")
10496 The order of entries in this list matters when several versions
10498 of Matlab are installed. The priority is set according to the
10499 ordering in this list.
10500 matlab_get_version_from_release_name
10502 Returns the version of Matlab (17.58) from a release name
10503 (R2017k)
10504 matlab_get_release_name_from_version
10506 Returns the release name (R2017k) from the version of Matlab
10507 (17.58)
10508 matlab_extract_all_installed_versions_from_registry
10510 This function parses the registry and founds the Matlab versions
10511 that are installed. The found versions are returned in mat‐
10512 lab_versions. Set win64 to TRUE if the 64 bit version of Matlab
10513 should be looked for The returned list contains all versions
10514 under HKLM\\SOFTWARE\\Mathworks\\MATLAB and HKLM\\SOFT‐
10515 WARE\\Mathworks\\MATLAB Runtime or an empty list in case an
10516 error occurred (or nothing found).
10517 NOTE:
10519 Only the versions are provided. No check is made over the
10520 existence of the installation referenced in the registry,
10521 matlab_get_all_valid_matlab_roots_from_registry
10523 Populates the Matlab root with valid versions of Matlab or Mat‐
10524 lab Runtime (MCR). The returned matlab_roots is organized in
10525 triplets (type,version_number,matlab_root_path), where type
10526 indicates either MATLAB or MCR.
10527 matlab_get_all_valid_matlab_roots_from_registry(
10529 matlab_versions
10530 matlab_roots)
10531 matlab_versions
10533 the versions of each of the Matlab or MCR installations
10534 matlab_roots
10536 the location of each of the Matlab or MCR installations
10537 matlab_get_mex_suffix
10539 Returns the extension of the mex files (the suffixes). This
10540 function should not be called before the appropriate Matlab root
10541 has been found.
10542 matlab_get_mex_suffix(
10544 matlab_root
10545 mex_suffix)
10546 matlab_root
10548 the root of the Matlab/MCR installation
10549 mex_suffix
10551 the variable name in which the suffix will be returned.
10552 matlab_get_version_from_matlab_run
10554 This function runs Matlab program specified on arguments and
10555 extracts its version. If the path provided for the Matlab
10556 installation points to an MCR installation, the version is
10557 extracted from the installed files.
10558 matlab_get_version_from_matlab_run(
10560 matlab_binary_path
10561 matlab_list_versions)
10562 matlab_binary_path
10564 the location of the matlab binary executable
10565 matlab_list_versions
10567 the version extracted from Matlab
10568 matlab_add_unit_test
10570 Adds a Matlab unit test to the test set of cmake/ctest. This
10571 command requires the component MAIN_PROGRAM and hence is not
10572 available for an MCR installation.
10573 The unit test uses the Matlab unittest framework (default,
10575 available starting Matlab 2013b+) except if the option
10576 NO_UNITTEST_FRAMEWORK is given.
10577 The function expects one Matlab test script file to be given.
10579 In the case NO_UNITTEST_FRAMEWORK is given, the unittest script
10580 file should contain the script to be run, plus an exit command
10581 with the exit value. This exit value will be passed to the ctest
10582 framework (0 success, non 0 failure). Additional arguments
10583 accepted by add_test() can be passed through TEST_ARGS (eg. CON‐
10584 FIGURATION <config> ...).
10585 matlab_add_unit_test(
10587 NAME <name>
10588 UNITTEST_FILE matlab_file_containing_unittest.m
10589 [CUSTOM_TEST_COMMAND matlab_command_to_run_as_test]
10590 [UNITTEST_PRECOMMAND matlab_command_to_run]
10591 [TIMEOUT timeout]
10592 [ADDITIONAL_PATH path1 [path2 ...]]
10593 [MATLAB_ADDITIONAL_STARTUP_OPTIONS option1 [option2 ...]]
10594 [TEST_ARGS arg1 [arg2 ...]]
10595 [NO_UNITTEST_FRAMEWORK]
10596 )
10597 The function arguments are:
10599 NAME name of the unittest in ctest.
10601 UNITTEST_FILE
10603 the matlab unittest file. Its path will be automatically
10604 added to the Matlab path.
10605 CUSTOM_TEST_COMMAND
10607 Matlab script command to run as the test. If this is not
10608 set, then the following is run: runtests('mat‐
10609 lab_file_name'), exit(max([ans(1,:).Failed])) where mat‐
10610 lab_file_name is the UNITTEST_FILE without the extension.
10611 UNITTEST_PRECOMMAND
10613 Matlab script command to be ran before the file contain‐
10614 ing the test (eg. GPU device initialisation based on
10615 CMake variables).
10616 TIMEOUT
10618 the test timeout in seconds. Defaults to 180 seconds as
10619 the Matlab unit test may hang.
10620 ADDITIONAL_PATH
10622 a list of paths to add to the Matlab path prior to run‐
10623 ning the unit test.
10624 MATLAB_ADDITIONAL_STARTUP_OPTIONS
10626 a list of additional option in order to run Matlab from
10627 the command line. -nosplash -nodesktop -nodisplay are
10628 always added.
10629 TEST_ARGS
10631 Additional options provided to the add_test command.
10632 These options are added to the default options (eg. “CON‐
10633 FIGURATIONS Release”)
10634 NO_UNITTEST_FRAMEWORK
10636 when set, indicates that the test should not use the
10637 unittest framework of Matlab (available for versions >=
10638 R2013a).
10639 WORKING_DIRECTORY
10641 This will be the working directory for the test. If spec‐
10642 ified it will also be the output directory used for the
10643 log file of the test run. If not specified the temporary
10644 directory ${CMAKE_BINARY_DIR}/Matlab will be used as the
10645 working directory and the log location.
10646 matlab_add_mex
10648 Adds a Matlab MEX target. This commands compiles the given
10649 sources with the current tool-chain in order to produce a MEX
10650 file. The final name of the produced output may be specified, as
10651 well as additional link libraries, and a documentation entry for
10652 the MEX file. Remaining arguments of the call are passed to the
10653 add_library() or add_executable() command.
10654 matlab_add_mex(
10656 NAME <name>
10657 [EXECUTABLE | MODULE | SHARED]
10658 SRC src1 [src2 ...]
10659 [OUTPUT_NAME output_name]
10660 [DOCUMENTATION file.txt]
10661 [LINK_TO target1 target2 ...]
10662 [R2017b | R2018a]
10663 [...]
10664 )
10665 NAME name of the target.
10667 SRC list of source files.
10669 LINK_TO
10671 a list of additional link dependencies. The target links
10672 to libmex and libmx by default.
10673 OUTPUT_NAME
10675 if given, overrides the default name. The default name is
10676 the name of the target without any prefix and with Mat‐
10677 lab_MEX_EXTENSION suffix.
10678 DOCUMENTATION
10680 if given, the file file.txt will be considered as being
10681 the documentation file for the MEX file. This file is
10682 copied into the same folder without any processing, with
10683 the same name as the final mex file, and with extension
10684 .m. In that case, typing help <name> in Matlab prints the
10685 documentation contained in this file.
10686 R2017b or R2018a may be given to specify the version of the C
10688 API
10689 to use: R2017b specifies the traditional (separate com‐
10690 plex) C API, and corresponds to the -R2017b flag for the
10691 mex command. R2018a specifies the new interleaved complex
10692 C API, and corresponds to the -R2018a flag for the mex
10693 command. Ignored if MATLAB version prior to R2018a.
10694 Defaults to R2017b.
10695 MODULE or SHARED may be given to specify the type of library to
10697 be
10698 created. EXECUTABLE may be given to create an executable
10699 instead of a library. If no type is given explicitly, the
10700 type is SHARED.
10701 The documentation file is not processed and should be in the
10703 following format:
10704 % This is the documentation
10706 function ret = mex_target_output_name(input1)
10707 FindMFC
10709 Find MFC on Windows
10710 Find the native MFC - i.e. decide if an application can link to the
10712 MFC libraries.
10713 MFC_FOUND - Was MFC support found
10715 You don’t need to include anything or link anything to use it.
10717 FindMotif
10719 Try to find Motif (or lesstif)
10720 Once done this will define:
10722 MOTIF_FOUND - system has MOTIF
10724 MOTIF_INCLUDE_DIR - include paths to use Motif
10725 MOTIF_LIBRARIES - Link these to use Motif
10726 FindMPEG2
10728 Find the native MPEG2 includes and library
10729 This module defines
10731 MPEG2_INCLUDE_DIR, path to mpeg2dec/mpeg2.h, etc.
10733 MPEG2_LIBRARIES, the libraries required to use MPEG2.
10734 MPEG2_FOUND, If false, do not try to use MPEG2.
10735 also defined, but not for general use are
10737 MPEG2_mpeg2_LIBRARY, where to find the MPEG2 library.
10739 MPEG2_vo_LIBRARY, where to find the vo library.
10740 FindMPEG
10742 Find the native MPEG includes and library
10743 This module defines
10745 MPEG_INCLUDE_DIR, where to find MPEG.h, etc.
10747 MPEG_LIBRARIES, the libraries required to use MPEG.
10748 MPEG_FOUND, If false, do not try to use MPEG.
10749 also defined, but not for general use are
10751 MPEG_mpeg2_LIBRARY, where to find the MPEG library.
10753 MPEG_vo_LIBRARY, where to find the vo library.
10754 FindMPI
10756 Find a Message Passing Interface (MPI) implementation.
10757 The Message Passing Interface (MPI) is a library used to write
10759 high-performance distributed-memory parallel applications, and is typi‐
10760 cally deployed on a cluster. MPI is a standard interface (defined by
10761 the MPI forum) for which many implementations are available.
10762 Variables for using MPI
10764 The module exposes the components C, CXX, MPICXX and Fortran. Each of
10765 these controls the various MPI languages to search for. The difference
10766 between CXX and MPICXX is that CXX refers to the MPI C API being usable
10767 from C++, whereas MPICXX refers to the MPI-2 C++ API that was removed
10768 again in MPI-3.
10769 Depending on the enabled components the following variables will be
10771 set:
10772 MPI_FOUND
10774 Variable indicating that MPI settings for all requested lan‐
10775 guages have been found. If no components are specified, this is
10776 true if MPI settings for all enabled languages were detected.
10777 Note that the MPICXX component does not affect this variable.
10778 MPI_VERSION
10780 Minimal version of MPI detected among the requested languages,
10781 or all enabled languages if no components were specified.
10782 This module will set the following variables per language in your
10784 project, where <lang> is one of C, CXX, or Fortran:
10785 MPI_<lang>_FOUND
10787 Variable indicating the MPI settings for <lang> were found and
10788 that simple MPI test programs compile with the provided set‐
10789 tings.
10790 MPI_<lang>_COMPILER
10792 MPI compiler for <lang> if such a program exists.
10793 MPI_<lang>_COMPILE_OPTIONS
10795 Compilation options for MPI programs in <lang>, given as a
10796 ;-list.
10797 MPI_<lang>_COMPILE_DEFINITIONS
10799 Compilation definitions for MPI programs in <lang>, given as a
10800 ;-list.
10801 MPI_<lang>_INCLUDE_DIRS
10803 Include path(s) for MPI header.
10804 MPI_<lang>_LINK_FLAGS
10806 Linker flags for MPI programs.
10807 MPI_<lang>_LIBRARIES
10809 All libraries to link MPI programs against.
10810 Additionally, the following IMPORTED targets are defined:
10812 MPI::MPI_<lang>
10814 Target for using MPI from <lang>.
10815 The following variables indicating which bindings are present will be
10817 defined:
10818 MPI_MPICXX_FOUND
10820 Variable indicating whether the MPI-2 C++ bindings are present
10821 (introduced in MPI-2, removed with MPI-3).
10822 MPI_Fortran_HAVE_F77_HEADER
10824 True if the Fortran 77 header mpif.h is available.
10825 MPI_Fortran_HAVE_F90_MODULE
10827 True if the Fortran 90 module mpi can be used for accessing MPI
10828 (MPI-2 and higher only).
10829 MPI_Fortran_HAVE_F08_MODULE
10831 True if the Fortran 2008 mpi_f08 is available to MPI programs
10832 (MPI-3 and higher only).
10833 If possible, the MPI version will be determined by this module. The
10835 facilities to detect the MPI version were introduced with MPI-1.2, and
10836 therefore cannot be found for older MPI versions.
10837 MPI_<lang>_VERSION_MAJOR
10839 Major version of MPI implemented for <lang> by the MPI distribu‐
10840 tion.
10841 MPI_<lang>_VERSION_MINOR
10843 Minor version of MPI implemented for <lang> by the MPI distribu‐
10844 tion.
10845 MPI_<lang>_VERSION
10847 MPI version implemented for <lang> by the MPI distribution.
10848 Note that there’s no variable for the C bindings being accessible
10850 through mpi.h, since the MPI standards always have required this bind‐
10851 ing to work in both C and C++ code.
10852 For running MPI programs, the module sets the following variables
10854 MPIEXEC_EXECUTABLE
10856 Executable for running MPI programs, if such exists.
10857 MPIEXEC_NUMPROC_FLAG
10859 Flag to pass to mpiexec before giving it the number of proces‐
10860 sors to run on.
10861 MPIEXEC_MAX_NUMPROCS
10863 Number of MPI processors to utilize. Defaults to the number of
10864 processors detected on the host system.
10865 MPIEXEC_PREFLAGS
10867 Flags to pass to mpiexec directly before the executable to run.
10868 MPIEXEC_POSTFLAGS
10870 Flags to pass to mpiexec after other flags.
10871 Variables for locating MPI
10873 This module performs a three step search for an MPI implementation:
10874 1. Check if the compiler has MPI support built-in. This is the case if
10876 the user passed a compiler wrapper as CMAKE_<LANG>_COMPILER or if
10877 they’re on a Cray system.
10878 2. Attempt to find an MPI compiler wrapper and determine the compiler
10880 information from it.
10881 3. Try to find an MPI implementation that does not ship such a wrapper
10883 by guessing settings. Currently, only Microsoft MPI and MPICH2 on
10884 Windows are supported.
10885 For controlling the second step, the following variables may be set:
10887 MPI_<lang>_COMPILER
10889 Search for the specified compiler wrapper and use it.
10890 MPI_<lang>_COMPILER_FLAGS
10892 Flags to pass to the MPI compiler wrapper during interrogation.
10893 Some compiler wrappers support linking debug or tracing
10894 libraries if a specific flag is passed and this variable may be
10895 used to obtain them.
10896 MPI_COMPILER_FLAGS
10898 Used to initialize MPI_<lang>_COMPILER_FLAGS if no language spe‐
10899 cific flag has been given. Empty by default.
10900 MPI_EXECUTABLE_SUFFIX
10902 A suffix which is appended to all names that are being looked
10903 for. For instance you may set this to .mpich or .openmpi to pre‐
10904 fer the one or the other on Debian and its derivatives.
10905 In order to control the guessing step, the following variable may be
10907 set:
10908 MPI_GUESS_LIBRARY_NAME
10910 Valid values are MSMPI and MPICH2. If set, only the given
10911 library will be searched for. By default, MSMPI will be pre‐
10912 ferred over MPICH2 if both are available. This also sets
10913 MPI_SKIP_COMPILER_WRAPPER to true, which may be overridden.
10914 Each of the search steps may be skipped with the following control
10916 variables:
10917 MPI_ASSUME_NO_BUILTIN_MPI
10919 If true, the module assumes that the compiler itself does not
10920 provide an MPI implementation and skips to step 2.
10921 MPI_SKIP_COMPILER_WRAPPER
10923 If true, no compiler wrapper will be searched for.
10924 MPI_SKIP_GUESSING
10926 If true, the guessing step will be skipped.
10927 Additionally, the following control variable is available to change
10929 search behavior:
10930 MPI_CXX_SKIP_MPICXX
10932 Add some definitions that will disable the MPI-2 C++ bindings.
10933 Currently supported are MPICH, Open MPI, Platform MPI and deriv‐
10934 atives thereof, for example MVAPICH or Intel MPI.
10935 If the find procedure fails for a variable MPI_<lang>_WORKS, then the
10937 settings detected by or passed to the module did not work and even a
10938 simple MPI test program failed to compile.
10939 If all of these parameters were not sufficient to find the right MPI
10941 implementation, a user may disable the entire autodetection process by
10942 specifying both a list of libraries in MPI_<lang>_LIBRARIES and a list
10943 of include directories in MPI_<lang>_ADDITIONAL_INCLUDE_DIRS. Any
10944 other variable may be set in addition to these two. The module will
10945 then validate the MPI settings and store the settings in the cache.
10946 Cache variables for MPI
10948 The variable MPI_<lang>_INCLUDE_DIRS will be assembled from the follow‐
10949 ing variables. For C and CXX:
10950 MPI_<lang>_HEADER_DIR
10952 Location of the mpi.h header on disk.
10953 For Fortran:
10955 MPI_Fortran_F77_HEADER_DIR
10957 Location of the Fortran 77 header mpif.h, if it exists.
10958 MPI_Fortran_MODULE_DIR
10960 Location of the mpi or mpi_f08 modules, if available.
10961 For all languages the following variables are additionally considered:
10963 MPI_<lang>_ADDITIONAL_INCLUDE_DIRS
10965 A ;-list of paths needed in addition to the normal include
10966 directories.
10967 MPI_<include_name>_INCLUDE_DIR
10969 Path variables for include folders referred to by
10970 <include_name>.
10971 MPI_<lang>_ADDITIONAL_INCLUDE_VARS
10973 A ;-list of <include_name> that will be added to the include
10974 locations of <lang>.
10975 The variable MPI_<lang>_LIBRARIES will be assembled from the following
10977 variables:
10978 MPI_<lib_name>_LIBRARY
10980 The location of a library called <lib_name> for use with MPI.
10981 MPI_<lang>_LIB_NAMES
10983 A ;-list of <lib_name> that will be added to the include loca‐
10984 tions of <lang>.
10985 Usage of mpiexec
10987 When using MPIEXEC_EXECUTABLE to execute MPI applications, you should
10988 typically use all of the MPIEXEC_EXECUTABLE flags as follows:
10989 ${MPIEXEC_EXECUTABLE} ${MPIEXEC_NUMPROC_FLAG} ${MPIEXEC_MAX_NUMPROCS}
10991 ${MPIEXEC_PREFLAGS} EXECUTABLE ${MPIEXEC_POSTFLAGS} ARGS
10992 where EXECUTABLE is the MPI program, and ARGS are the arguments to pass
10994 to the MPI program.
10995 Advanced variables for using MPI
10997 The module can perform some advanced feature detections upon explicit
10998 request.
10999 Important notice: The following checks cannot be performed without exe‐
11001 cuting an MPI test program. Consider the special considerations for
11002 the behavior of try_run() during cross compilation. Moreover, running
11003 an MPI program can cause additional issues, like a firewall notifica‐
11004 tion on some systems. You should only enable these detections if you
11005 absolutely need the information.
11006 If the following variables are set to true, the respective search will
11008 be performed:
11009 MPI_DETERMINE_Fortran_CAPABILITIES
11011 Determine for all available Fortran bindings what the values of
11012 MPI_SUBARRAYS_SUPPORTED and MPI_ASYNC_PROTECTS_NONBLOCKING are
11013 and make their values available as MPI_Fortran_<binding>_SUBAR‐
11014 RAYS and MPI_Fortran_<binding>_ASYNCPROT, where <binding> is one
11015 of F77_HEADER, F90_MODULE and F08_MODULE.
11016 MPI_DETERMINE_LIBRARY_VERSION
11018 For each language, find the output of MPI_Get_library_version
11019 and make it available as MPI_<lang>_LIBRARY_VERSION. This
11020 information is usually tied to the runtime component of an MPI
11021 implementation and might differ depending on <lang>. Note that
11022 the return value is entirely implementation defined. This infor‐
11023 mation might be used to identify the MPI vendor and for example
11024 pick the correct one of multiple third party binaries that
11025 matches the MPI vendor.
11026 Backward Compatibility
11028 For backward compatibility with older versions of FindMPI, these vari‐
11029 ables are set, but deprecated:
11030 MPI_COMPILER MPI_LIBRARY MPI_EXTRA_LIBRARY
11032 MPI_COMPILE_FLAGS MPI_INCLUDE_PATH MPI_LINK_FLAGS
11033 MPI_LIBRARIES
11034 In new projects, please use the MPI_<lang>_XXX equivalents. Addition‐
11036 ally, the following variables are deprecated:
11037 MPI_<lang>_COMPILE_FLAGS
11039 Use MPI_<lang>_COMPILE_OPTIONS and MPI_<lang>_COMPILE_DEFINI‐
11040 TIONS instead.
11041 MPI_<lang>_INCLUDE_PATH
11043 For consumption use MPI_<lang>_INCLUDE_DIRS and for specifying
11044 folders use MPI_<lang>_ADDITIONAL_INCLUDE_DIRS instead.
11045 MPIEXEC
11047 Use MPIEXEC_EXECUTABLE instead.
11048 FindODBC
11050 Find an Open Database Connectivity (ODBC) include directory and
11051 library.
11052 On Windows, when building with Visual Studio, this module assumes the
11054 ODBC library is provided by the available Windows SDK.
11055 On Unix, this module allows to search for ODBC library provided by
11057 unixODBC or iODBC implementations of ODBC API. This module reads hint
11058 about location of the config program:
11059 ODBC_CONFIG
11061 Location of odbc_config or iodbc-config program
11062 Otherwise, this module tries to find the config program, first from
11064 unixODBC, then from iODBC. If no config program found, this module
11065 searches for ODBC header and library in list of known locations.
11066 Imported targets
11068 This module defines the following IMPORTED targets:
11069 ODBC::ODBC
11071 Imported target for using the ODBC library, if found.
11072 Result variables
11074 ODBC_FOUND
11075 Set to true if ODBC library found, otherwise false or undefined.
11076 ODBC_INCLUDE_DIRS
11078 Paths to include directories listed in one variable for use by
11079 ODBC client. May be empty on Windows, where the include direc‐
11080 tory corresponding to the expected Windows SDK is already avail‐
11081 able in the compilation environment.
11082 ODBC_LIBRARIES
11084 Paths to libraries to linked against to use ODBC. May just a
11085 library name on Windows, where the library directory correspond‐
11086 ing to the expected Windows SDK is already available in the com‐
11087 pilation environment.
11088 ODBC_CONFIG
11090 Path to unixODBC or iODBC config program, if found or specified.
11091 Cache variables
11093 For users who wish to edit and control the module behavior, this module
11094 reads hints about search locations from the following variables:
11095 ODBC_INCLUDE_DIR
11097 Path to ODBC include directory with sql.h header.
11098 ODBC_LIBRARY
11100 Path to ODBC library to be linked.
11101 These variables should not be used directly by project code.
11103 Limitations
11105 On Windows, this module does not search for iODBC. On Unix, there is
11106 no way to prefer unixODBC over iODBC, or vice versa, other than provid‐
11107 ing the config program location using the ODBC_CONFIG. This module
11108 does not allow to search for a specific ODBC driver.
11109 FindOpenACC
11111 Detect OpenACC support by the compiler.
11112 This module can be used to detect OpenACC support in a compiler. If
11114 the compiler supports OpenACC, the flags required to compile with Ope‐
11115 nACC support are returned in variables for the different languages.
11116 Currently, only PGI, GNU and Cray compilers are supported.
11117 Variables
11119 This module will set the following variables per language in your
11120 project, where <lang> is one of C, CXX, or Fortran:
11121 OpenACC_<lang>_FOUND
11123 Variable indicating if OpenACC support for <lang> was detected.
11124 OpenACC_<lang>_FLAGS
11126 OpenACC compiler flags for <lang>, separated by spaces.
11127 The module will also try to provide the OpenACC version variables:
11129 OpenACC_<lang>_SPEC_DATE
11131 Date of the OpenACC specification implemented by the <lang> com‐
11132 piler.
11133 OpenACC_<lang>_VERSION_MAJOR
11135 Major version of OpenACC implemented by the <lang> compiler.
11136 OpenACC_<lang>_VERSION_MINOR
11138 Minor version of OpenACC implemented by the <lang> compiler.
11139 OpenACC_<lang>_VERSION
11141 OpenACC version implemented by the <lang> compiler.
11142 The specification date is formatted as given in the OpenACC standard:
11144 yyyymm where yyyy and mm represents the year and month of the OpenACC
11145 specification implemented by the <lang> compiler.
11146 Input Variables
11148 OpenACC_ACCEL_TARGET=<target> If set, will the correct target accelera‐
11149 tor flag set to the <target> will be returned with Ope‐
11150 nACC_<lang>_FLAGS.
11151 FindOpenAL
11153 Locate OpenAL This module defines OPENAL_LIBRARY OPENAL_FOUND, if
11154 false, do not try to link to OpenAL OPENAL_INCLUDE_DIR, where to find
11155 the headers
11156 $OPENALDIR is an environment variable that would correspond to the
11158 Created by Eric Wing. This was influenced by the FindSDL.cmake module.
11160 FindOpenCL
11162 Try to find OpenCL
11163 IMPORTED Targets
11165 This module defines IMPORTED target OpenCL::OpenCL, if OpenCL has been
11166 found.
11167 Result Variables
11169 This module defines the following variables:
11170 OpenCL_FOUND - True if OpenCL was found
11172 OpenCL_INCLUDE_DIRS - include directories for OpenCL
11173 OpenCL_LIBRARIES - link against this library to use OpenCL
11174 OpenCL_VERSION_STRING - Highest supported OpenCL version (eg. 1.2)
11175 OpenCL_VERSION_MAJOR - The major version of the OpenCL implementation
11176 OpenCL_VERSION_MINOR - The minor version of the OpenCL implementation
11177 The module will also define two cache variables:
11179 OpenCL_INCLUDE_DIR - the OpenCL include directory
11181 OpenCL_LIBRARY - the path to the OpenCL library
11182 FindOpenGL
11184 FindModule for OpenGL and GLU.
11185 Optional COMPONENTS
11187 This module respects several optional COMPONENTS: EGL, GLX, and OpenGL.
11188 There are corresponding import targets for each of these flags.
11189 IMPORTED Targets
11191 This module defines the IMPORTED targets:
11192 OpenGL::GL
11194 Defined to the platform-specific OpenGL libraries if the system
11195 has OpenGL.
11196 OpenGL::OpenGL
11198 Defined to libOpenGL if the system is GLVND-based.
11199 OpenGL::GLU
11201 Defined if the system has GLU.
11202 OpenGL::GLX
11204 Defined if the system has GLX.
11205 OpenGL::EGL
11207 Defined if the system has EGL.
11208 Result Variables
11210 This module sets the following variables:
11211 OPENGL_FOUND
11213 True, if the system has OpenGL and all components are found.
11214 OPENGL_XMESA_FOUND
11216 True, if the system has XMESA.
11217 OPENGL_GLU_FOUND
11219 True, if the system has GLU.
11220 OpenGL_OpenGL_FOUND
11222 True, if the system has an OpenGL library.
11223 OpenGL_GLX_FOUND
11225 True, if the system has GLX.
11226 OpenGL_EGL_FOUND
11228 True, if the system has EGL.
11229 OPENGL_INCLUDE_DIR
11231 Path to the OpenGL include directory.
11232 OPENGL_EGL_INCLUDE_DIRS
11234 Path to the EGL include directory.
11235 OPENGL_LIBRARIES
11237 Paths to the OpenGL library, windowing system libraries, and GLU
11238 libraries. On Linux, this assumes GLX and is never correct for
11239 EGL-based targets. Clients are encouraged to use the OpenGL::*
11240 import targets instead.
11241 Cache variables
11243 The following cache variables may also be set:
11244 OPENGL_egl_LIBRARY
11246 Path to the EGL library.
11247 OPENGL_glu_LIBRARY
11249 Path to the GLU library.
11250 OPENGL_glx_LIBRARY
11252 Path to the GLVND ‘GLX’ library.
11253 OPENGL_opengl_LIBRARY
11255 Path to the GLVND ‘OpenGL’ library
11256 OPENGL_gl_LIBRARY
11258 Path to the OpenGL library. New code should prefer the
11259 OpenGL::* import targets.
11260 Linux-specific
11262 Some Linux systems utilize GLVND as a new ABI for OpenGL. GLVND sepa‐
11263 rates context libraries from OpenGL itself; OpenGL lives in
11264 “libOpenGL”, and contexts are defined in “libGLX” or “libEGL”. GLVND
11265 is currently the only way to get OpenGL 3+ functionality via EGL in a
11266 manner portable across vendors. Projects may use GLVND explicitly with
11267 target OpenGL::OpenGL and either OpenGL::GLX or OpenGL::EGL.
11268 Projects may use the OpenGL::GL target (or OPENGL_LIBRARIES variable)
11270 to use legacy GL interfaces. These will use the legacy GL library
11271 located by OPENGL_gl_LIBRARY, if available. If OPENGL_gl_LIBRARY is
11272 empty or not found and GLVND is available, the OpenGL::GL target will
11273 use GLVND OpenGL::OpenGL and OpenGL::GLX (and the OPENGL_LIBRARIES
11274 variable will use the corresponding libraries). Thus, for
11275 non-EGL-based Linux targets, the OpenGL::GL target is most portable.
11276 A OpenGL_GL_PREFERENCE variable may be set to specify the preferred way
11278 to provide legacy GL interfaces in case multiple choices are available.
11279 The value may be one of:
11280 GLVND If the GLVND OpenGL and GLX libraries are available, prefer
11282 them. This forces OPENGL_gl_LIBRARY to be empty. This is the
11283 default if components were requested (since components corre‐
11284 spond to GLVND libraries) or if policy CMP0072 is set to NEW.
11285 LEGACY Prefer to use the legacy libGL library, if available. This is
11287 the default if no components were requested and policy CMP0072
11288 is not set to NEW.
11289 For EGL targets the client must rely on GLVND support on the user’s
11291 system. Linking should use the OpenGL::OpenGL OpenGL::EGL targets.
11292 Using GLES* libraries is theoretically possible in place of
11293 OpenGL::OpenGL, but this module does not currently support that; con‐
11294 tributions welcome.
11295 OPENGL_egl_LIBRARY and OPENGL_EGL_INCLUDE_DIRS are defined in the case
11297 of GLVND. For non-GLVND Linux and other systems these are left unde‐
11298 fined.
11299 macOS-Specific
11301 On OSX FindOpenGL defaults to using the framework version of OpenGL.
11302 People will have to change the cache values of OPENGL_glu_LIBRARY and
11303 OPENGL_gl_LIBRARY to use OpenGL with X11 on OSX.
11304 FindOpenMP
11306 Finds OpenMP support
11307 This module can be used to detect OpenMP support in a compiler. If the
11309 compiler supports OpenMP, the flags required to compile with OpenMP
11310 support are returned in variables for the different languages. The
11311 variables may be empty if the compiler does not need a special flag to
11312 support OpenMP.
11313 Variables
11315 The module exposes the components C, CXX, and Fortran. Each of these
11316 controls the various languages to search OpenMP support for.
11317 Depending on the enabled components the following variables will be
11319 set:
11320 OpenMP_FOUND
11322 Variable indicating that OpenMP flags for all requested lan‐
11323 guages have been found. If no components are specified, this is
11324 true if OpenMP settings for all enabled languages were detected.
11325 OpenMP_VERSION
11327 Minimal version of the OpenMP standard detected among the
11328 requested languages, or all enabled languages if no components
11329 were specified.
11330 This module will set the following variables per language in your
11332 project, where <lang> is one of C, CXX, or Fortran:
11333 OpenMP_<lang>_FOUND
11335 Variable indicating if OpenMP support for <lang> was detected.
11336 OpenMP_<lang>_FLAGS
11338 OpenMP compiler flags for <lang>, separated by spaces.
11339 For linking with OpenMP code written in <lang>, the following variables
11341 are provided:
11342 OpenMP_<lang>_LIB_NAMES
11344 ;-list of libraries for OpenMP programs for <lang>.
11345 OpenMP_<libname>_LIBRARY
11347 Location of the individual libraries needed for OpenMP support
11348 in <lang>.
11349 OpenMP_<lang>_LIBRARIES
11351 A list of libraries needed to link with OpenMP code written in
11352 <lang>.
11353 Additionally, the module provides IMPORTED targets:
11355 OpenMP::OpenMP_<lang>
11357 Target for using OpenMP from <lang>.
11358 Specifically for Fortran, the module sets the following variables:
11360 OpenMP_Fortran_HAVE_OMPLIB_HEADER
11362 Boolean indicating if OpenMP is accessible through omp_lib.h.
11363 OpenMP_Fortran_HAVE_OMPLIB_MODULE
11365 Boolean indicating if OpenMP is accessible through the omp_lib
11366 Fortran module.
11367 The module will also try to provide the OpenMP version variables:
11369 OpenMP_<lang>_SPEC_DATE
11371 Date of the OpenMP specification implemented by the <lang> com‐
11372 piler.
11373 OpenMP_<lang>_VERSION_MAJOR
11375 Major version of OpenMP implemented by the <lang> compiler.
11376 OpenMP_<lang>_VERSION_MINOR
11378 Minor version of OpenMP implemented by the <lang> compiler.
11379 OpenMP_<lang>_VERSION
11381 OpenMP version implemented by the <lang> compiler.
11382 The specification date is formatted as given in the OpenMP standard:
11384 yyyymm where yyyy and mm represents the year and month of the OpenMP
11385 specification implemented by the <lang> compiler.
11386 FindOpenSceneGraph
11388 Find OpenSceneGraph
11389 This module searches for the OpenSceneGraph core “osg” library as well
11391 as OpenThreads, and whatever additional COMPONENTS (nodekits) that you
11392 specify.
11393 See http://www.openscenegraph.org
11395 NOTE: To use this module effectively you must either require CMake >=
11397 2.6.3 with cmake_minimum_required(VERSION 2.6.3) or download and place
11398 FindOpenThreads.cmake, Findosg_functions.cmake, Findosg.cmake, and
11399 Find<etc>.cmake files into your CMAKE_MODULE_PATH.
11400 ----
11403 This module accepts the following variables (note mixed case)
11407 OpenSceneGraph_DEBUG - Enable debugging output
11409 OpenSceneGraph_MARK_AS_ADVANCED - Mark cache variables as advanced
11411 automatically
11412 The following environment variables are also respected for finding the
11414 OSG and it’s various components. CMAKE_PREFIX_PATH can also be used
11415 for this (see find_library() CMake documentation).
11416 <MODULE>_DIR
11418 (where MODULE is of the form “OSGVOLUME” and there is a Findos‐
11419 gVolume.cmake file)
11420 OSG_DIR
11422 OSGDIR
11424 OSG_ROOT
11426 [CMake 2.8.10]: The CMake variable OSG_DIR can now be used as well to
11428 influence detection, instead of needing to specify an environment vari‐
11429 able.
11430 This module defines the following output variables:
11432 OPENSCENEGRAPH_FOUND - Was the OSG and all of the specified components found?
11434 OPENSCENEGRAPH_VERSION - The version of the OSG which was found
11436 OPENSCENEGRAPH_INCLUDE_DIRS - Where to find the headers
11438 OPENSCENEGRAPH_LIBRARIES - The OSG libraries
11440 ================================== Example Usage:
11442 find_package(OpenSceneGraph 2.0.0 REQUIRED osgDB osgUtil)
11444 # libOpenThreads & libosg automatically searched
11445 include_directories(${OPENSCENEGRAPH_INCLUDE_DIRS})
11446 add_executable(foo foo.cc)
11448 target_link_libraries(foo ${OPENSCENEGRAPH_LIBRARIES})
11449 FindOpenSSL
11451 Find the OpenSSL encryption library.
11452 Optional COMPONENTS
11454 This module supports two optional COMPONENTS: Crypto and SSL. Both
11455 components have associated imported targets, as described below.
11456 Imported Targets
11458 This module defines the following IMPORTED targets:
11459 OpenSSL::SSL
11461 The OpenSSL ssl library, if found.
11462 OpenSSL::Crypto
11464 The OpenSSL crypto library, if found.
11465 Result Variables
11467 This module will set the following variables in your project:
11468 OPENSSL_FOUND
11470 System has the OpenSSL library. If no components are requested
11471 it only requires the crypto library.
11472 OPENSSL_INCLUDE_DIR
11474 The OpenSSL include directory.
11475 OPENSSL_CRYPTO_LIBRARY
11477 The OpenSSL crypto library.
11478 OPENSSL_SSL_LIBRARY
11480 The OpenSSL SSL library.
11481 OPENSSL_LIBRARIES
11483 All OpenSSL libraries.
11484 OPENSSL_VERSION
11486 This is set to $major.$minor.$revision$patch (e.g. 0.9.8s).
11487 Hints
11489 Set OPENSSL_ROOT_DIR to the root directory of an OpenSSL installation.
11490 Set OPENSSL_USE_STATIC_LIBS to TRUE to look for static libraries. Set
11491 OPENSSL_MSVC_STATIC_RT set TRUE to choose the MT version of the lib.
11492 FindOpenThreads
11494 OpenThreads is a C++ based threading library. Its largest userbase
11495 seems to OpenSceneGraph so you might notice I accept OSGDIR as an envi‐
11496 ronment path. I consider this part of the Findosg* suite used to find
11497 OpenSceneGraph components. Each component is separate and you must opt
11498 in to each module.
11499 Locate OpenThreads This module defines OPENTHREADS_LIBRARY
11501 OPENTHREADS_FOUND, if false, do not try to link to OpenThreads
11502 OPENTHREADS_INCLUDE_DIR, where to find the headers
11503 $OPENTHREADS_DIR is an environment variable that would correspond to
11505 the ./configure –prefix=$OPENTHREADS_DIR used in building osg.
11506 [CMake 2.8.10]: The CMake variables OPENTHREADS_DIR or OSG_DIR can now
11508 be used as well to influence detection, instead of needing to specify
11509 an environment variable.
11510 Created by Eric Wing.
11512 FindosgAnimation
11514 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
11515 nents. Each component is separate and you must opt in to each module.
11516 You must also opt into OpenGL and OpenThreads (and Producer if needed)
11517 as these modules won’t do it for you. This is to allow you control
11518 over your own system piece by piece in case you need to opt out of cer‐
11519 tain components or change the Find behavior for a particular module
11520 (perhaps because the default FindOpenGL.cmake module doesn’t work with
11521 your system as an example). If you want to use a more convenient mod‐
11522 ule that includes everything, use the FindOpenSceneGraph.cmake instead
11523 of the Findosg*.cmake modules.
11524 Locate osgAnimation This module defines
11526 OSGANIMATION_FOUND - Was osgAnimation found? OSGANIMATION_INCLUDE_DIR -
11528 Where to find the headers OSGANIMATION_LIBRARIES - The libraries to
11529 link against for the OSG (use this)
11530 OSGANIMATION_LIBRARY - The OSG library OSGANIMATION_LIBRARY_DEBUG - The
11532 OSG debug library
11533 $OSGDIR is an environment variable that would correspond to the
11535 Created by Eric Wing.
11537 FindosgDB
11539 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
11540 nents. Each component is separate and you must opt in to each module.
11541 You must also opt into OpenGL and OpenThreads (and Producer if needed)
11542 as these modules won’t do it for you. This is to allow you control
11543 over your own system piece by piece in case you need to opt out of cer‐
11544 tain components or change the Find behavior for a particular module
11545 (perhaps because the default FindOpenGL.cmake module doesn’t work with
11546 your system as an example). If you want to use a more convenient mod‐
11547 ule that includes everything, use the FindOpenSceneGraph.cmake instead
11548 of the Findosg*.cmake modules.
11549 Locate osgDB This module defines
11551 OSGDB_FOUND - Was osgDB found? OSGDB_INCLUDE_DIR - Where to find the
11553 headers OSGDB_LIBRARIES - The libraries to link against for the osgDB
11554 (use this)
11555 OSGDB_LIBRARY - The osgDB library OSGDB_LIBRARY_DEBUG - The osgDB debug
11557 library
11558 $OSGDIR is an environment variable that would correspond to the
11560 Created by Eric Wing.
11562 Findosg_functions
11564 This CMake file contains two macros to assist with searching for OSG
11565 libraries and nodekits. Please see FindOpenSceneGraph.cmake for full
11566 documentation.
11567 FindosgFX
11569 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
11570 nents. Each component is separate and you must opt in to each module.
11571 You must also opt into OpenGL and OpenThreads (and Producer if needed)
11572 as these modules won’t do it for you. This is to allow you control
11573 over your own system piece by piece in case you need to opt out of cer‐
11574 tain components or change the Find behavior for a particular module
11575 (perhaps because the default FindOpenGL.cmake module doesn’t work with
11576 your system as an example). If you want to use a more convenient mod‐
11577 ule that includes everything, use the FindOpenSceneGraph.cmake instead
11578 of the Findosg*.cmake modules.
11579 Locate osgFX This module defines
11581 OSGFX_FOUND - Was osgFX found? OSGFX_INCLUDE_DIR - Where to find the
11583 headers OSGFX_LIBRARIES - The libraries to link against for the osgFX
11584 (use this)
11585 OSGFX_LIBRARY - The osgFX library OSGFX_LIBRARY_DEBUG - The osgFX debug
11587 library
11588 $OSGDIR is an environment variable that would correspond to the
11590 Created by Eric Wing.
11592 FindosgGA
11594 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
11595 nents. Each component is separate and you must opt in to each module.
11596 You must also opt into OpenGL and OpenThreads (and Producer if needed)
11597 as these modules won’t do it for you. This is to allow you control
11598 over your own system piece by piece in case you need to opt out of cer‐
11599 tain components or change the Find behavior for a particular module
11600 (perhaps because the default FindOpenGL.cmake module doesn’t work with
11601 your system as an example). If you want to use a more convenient mod‐
11602 ule that includes everything, use the FindOpenSceneGraph.cmake instead
11603 of the Findosg*.cmake modules.
11604 Locate osgGA This module defines
11606 OSGGA_FOUND - Was osgGA found? OSGGA_INCLUDE_DIR - Where to find the
11608 headers OSGGA_LIBRARIES - The libraries to link against for the osgGA
11609 (use this)
11610 OSGGA_LIBRARY - The osgGA library OSGGA_LIBRARY_DEBUG - The osgGA debug
11612 library
11613 $OSGDIR is an environment variable that would correspond to the
11615 Created by Eric Wing.
11617 FindosgIntrospection
11619 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
11620 nents. Each component is separate and you must opt in to each module.
11621 You must also opt into OpenGL and OpenThreads (and Producer if needed)
11622 as these modules won’t do it for you. This is to allow you control
11623 over your own system piece by piece in case you need to opt out of cer‐
11624 tain components or change the Find behavior for a particular module
11625 (perhaps because the default FindOpenGL.cmake module doesn’t work with
11626 your system as an example). If you want to use a more convenient mod‐
11627 ule that includes everything, use the FindOpenSceneGraph.cmake instead
11628 of the Findosg*.cmake modules.
11629 Locate osgINTROSPECTION This module defines
11631 OSGINTROSPECTION_FOUND - Was osgIntrospection found? OSGINTROSPEC‐
11633 TION_INCLUDE_DIR - Where to find the headers OSGINTROSPECTION_LIBRARIES
11634 - The libraries to link for osgIntrospection (use this)
11635 OSGINTROSPECTION_LIBRARY - The osgIntrospection library OSGINTROSPEC‐
11637 TION_LIBRARY_DEBUG - The osgIntrospection debug library
11638 $OSGDIR is an environment variable that would correspond to the
11640 Created by Eric Wing.
11642 FindosgManipulator
11644 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
11645 nents. Each component is separate and you must opt in to each module.
11646 You must also opt into OpenGL and OpenThreads (and Producer if needed)
11647 as these modules won’t do it for you. This is to allow you control
11648 over your own system piece by piece in case you need to opt out of cer‐
11649 tain components or change the Find behavior for a particular module
11650 (perhaps because the default FindOpenGL.cmake module doesn’t work with
11651 your system as an example). If you want to use a more convenient mod‐
11652 ule that includes everything, use the FindOpenSceneGraph.cmake instead
11653 of the Findosg*.cmake modules.
11654 Locate osgManipulator This module defines
11656 OSGMANIPULATOR_FOUND - Was osgManipulator found? OSGMANIPULA‐
11658 TOR_INCLUDE_DIR - Where to find the headers OSGMANIPULATOR_LIBRARIES -
11659 The libraries to link for osgManipulator (use this)
11660 OSGMANIPULATOR_LIBRARY - The osgManipulator library OSGMANIPULA‐
11662 TOR_LIBRARY_DEBUG - The osgManipulator debug library
11663 $OSGDIR is an environment variable that would correspond to the
11665 Created by Eric Wing.
11667 FindosgParticle
11669 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
11670 nents. Each component is separate and you must opt in to each module.
11671 You must also opt into OpenGL and OpenThreads (and Producer if needed)
11672 as these modules won’t do it for you. This is to allow you control
11673 over your own system piece by piece in case you need to opt out of cer‐
11674 tain components or change the Find behavior for a particular module
11675 (perhaps because the default FindOpenGL.cmake module doesn’t work with
11676 your system as an example). If you want to use a more convenient mod‐
11677 ule that includes everything, use the FindOpenSceneGraph.cmake instead
11678 of the Findosg*.cmake modules.
11679 Locate osgParticle This module defines
11681 OSGPARTICLE_FOUND - Was osgParticle found? OSGPARTICLE_INCLUDE_DIR -
11683 Where to find the headers OSGPARTICLE_LIBRARIES - The libraries to link
11684 for osgParticle (use this)
11685 OSGPARTICLE_LIBRARY - The osgParticle library OSGPARTICLE_LIBRARY_DEBUG
11687 - The osgParticle debug library
11688 $OSGDIR is an environment variable that would correspond to the
11690 Created by Eric Wing.
11692 FindosgPresentation
11694 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
11695 nents. Each component is separate and you must opt in to each module.
11696 You must also opt into OpenGL and OpenThreads (and Producer if needed)
11697 as these modules won’t do it for you. This is to allow you control
11698 over your own system piece by piece in case you need to opt out of cer‐
11699 tain components or change the Find behavior for a particular module
11700 (perhaps because the default FindOpenGL.cmake module doesn’t work with
11701 your system as an example). If you want to use a more convenient mod‐
11702 ule that includes everything, use the FindOpenSceneGraph.cmake instead
11703 of the Findosg*.cmake modules.
11704 Locate osgPresentation This module defines
11706 OSGPRESENTATION_FOUND - Was osgPresentation found? OSGPRESENTA‐
11708 TION_INCLUDE_DIR - Where to find the headers OSGPRESENTATION_LIBRARIES
11709 - The libraries to link for osgPresentation (use this)
11710 OSGPRESENTATION_LIBRARY - The osgPresentation library OSGPRESENTA‐
11712 TION_LIBRARY_DEBUG - The osgPresentation debug library
11713 $OSGDIR is an environment variable that would correspond to the
11715 Created by Eric Wing. Modified to work with osgPresentation by Robert
11717 Osfield, January 2012.
11718 FindosgProducer
11720 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
11721 nents. Each component is separate and you must opt in to each module.
11722 You must also opt into OpenGL and OpenThreads (and Producer if needed)
11723 as these modules won’t do it for you. This is to allow you control
11724 over your own system piece by piece in case you need to opt out of cer‐
11725 tain components or change the Find behavior for a particular module
11726 (perhaps because the default FindOpenGL.cmake module doesn’t work with
11727 your system as an example). If you want to use a more convenient mod‐
11728 ule that includes everything, use the FindOpenSceneGraph.cmake instead
11729 of the Findosg*.cmake modules.
11730 Locate osgProducer This module defines
11732 OSGPRODUCER_FOUND - Was osgProducer found? OSGPRODUCER_INCLUDE_DIR -
11734 Where to find the headers OSGPRODUCER_LIBRARIES - The libraries to link
11735 for osgProducer (use this)
11736 OSGPRODUCER_LIBRARY - The osgProducer library OSGPRODUCER_LIBRARY_DEBUG
11738 - The osgProducer debug library
11739 $OSGDIR is an environment variable that would correspond to the
11741 Created by Eric Wing.
11743 FindosgQt
11745 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
11746 nents. Each component is separate and you must opt in to each module.
11747 You must also opt into OpenGL and OpenThreads (and Producer if needed)
11748 as these modules won’t do it for you. This is to allow you control
11749 over your own system piece by piece in case you need to opt out of cer‐
11750 tain components or change the Find behavior for a particular module
11751 (perhaps because the default FindOpenGL.cmake module doesn’t work with
11752 your system as an example). If you want to use a more convenient mod‐
11753 ule that includes everything, use the FindOpenSceneGraph.cmake instead
11754 of the Findosg*.cmake modules.
11755 Locate osgQt This module defines
11757 OSGQT_FOUND - Was osgQt found? OSGQT_INCLUDE_DIR - Where to find the
11759 headers OSGQT_LIBRARIES - The libraries to link for osgQt (use this)
11760 OSGQT_LIBRARY - The osgQt library OSGQT_LIBRARY_DEBUG - The osgQt debug
11762 library
11763 $OSGDIR is an environment variable that would correspond to the
11765 Created by Eric Wing. Modified to work with osgQt by Robert Osfield,
11767 January 2012.
11768 Findosg
11770 NOTE: It is highly recommended that you use the new FindOpenScene‐
11771 Graph.cmake introduced in CMake 2.6.3 and not use this Find module
11772 directly.
11773 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
11775 nents. Each component is separate and you must opt in to each module.
11776 You must also opt into OpenGL and OpenThreads (and Producer if needed)
11777 as these modules won’t do it for you. This is to allow you control
11778 over your own system piece by piece in case you need to opt out of cer‐
11779 tain components or change the Find behavior for a particular module
11780 (perhaps because the default FindOpenGL.cmake module doesn’t work with
11781 your system as an example). If you want to use a more convenient mod‐
11782 ule that includes everything, use the FindOpenSceneGraph.cmake instead
11783 of the Findosg*.cmake modules.
11784 Locate osg This module defines
11786 OSG_FOUND - Was the Osg found? OSG_INCLUDE_DIR - Where to find the
11788 headers OSG_LIBRARIES - The libraries to link against for the OSG (use
11789 this)
11790 OSG_LIBRARY - The OSG library OSG_LIBRARY_DEBUG - The OSG debug library
11792 $OSGDIR is an environment variable that would correspond to the
11794 Created by Eric Wing.
11796 FindosgShadow
11798 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
11799 nents. Each component is separate and you must opt in to each module.
11800 You must also opt into OpenGL and OpenThreads (and Producer if needed)
11801 as these modules won’t do it for you. This is to allow you control
11802 over your own system piece by piece in case you need to opt out of cer‐
11803 tain components or change the Find behavior for a particular module
11804 (perhaps because the default FindOpenGL.cmake module doesn’t work with
11805 your system as an example). If you want to use a more convenient mod‐
11806 ule that includes everything, use the FindOpenSceneGraph.cmake instead
11807 of the Findosg*.cmake modules.
11808 Locate osgShadow This module defines
11810 OSGSHADOW_FOUND - Was osgShadow found? OSGSHADOW_INCLUDE_DIR - Where to
11812 find the headers OSGSHADOW_LIBRARIES - The libraries to link for
11813 osgShadow (use this)
11814 OSGSHADOW_LIBRARY - The osgShadow library OSGSHADOW_LIBRARY_DEBUG - The
11816 osgShadow debug library
11817 $OSGDIR is an environment variable that would correspond to the
11819 Created by Eric Wing.
11821 FindosgSim
11823 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
11824 nents. Each component is separate and you must opt in to each module.
11825 You must also opt into OpenGL and OpenThreads (and Producer if needed)
11826 as these modules won’t do it for you. This is to allow you control
11827 over your own system piece by piece in case you need to opt out of cer‐
11828 tain components or change the Find behavior for a particular module
11829 (perhaps because the default FindOpenGL.cmake module doesn’t work with
11830 your system as an example). If you want to use a more convenient mod‐
11831 ule that includes everything, use the FindOpenSceneGraph.cmake instead
11832 of the Findosg*.cmake modules.
11833 Locate osgSim This module defines
11835 OSGSIM_FOUND - Was osgSim found? OSGSIM_INCLUDE_DIR - Where to find the
11837 headers OSGSIM_LIBRARIES - The libraries to link for osgSim (use this)
11838 OSGSIM_LIBRARY - The osgSim library OSGSIM_LIBRARY_DEBUG - The osgSim
11840 debug library
11841 $OSGDIR is an environment variable that would correspond to the
11843 Created by Eric Wing.
11845 FindosgTerrain
11847 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
11848 nents. Each component is separate and you must opt in to each module.
11849 You must also opt into OpenGL and OpenThreads (and Producer if needed)
11850 as these modules won’t do it for you. This is to allow you control
11851 over your own system piece by piece in case you need to opt out of cer‐
11852 tain components or change the Find behavior for a particular module
11853 (perhaps because the default FindOpenGL.cmake module doesn’t work with
11854 your system as an example). If you want to use a more convenient mod‐
11855 ule that includes everything, use the FindOpenSceneGraph.cmake instead
11856 of the Findosg*.cmake modules.
11857 Locate osgTerrain This module defines
11859 OSGTERRAIN_FOUND - Was osgTerrain found? OSGTERRAIN_INCLUDE_DIR - Where
11861 to find the headers OSGTERRAIN_LIBRARIES - The libraries to link for
11862 osgTerrain (use this)
11863 OSGTERRAIN_LIBRARY - The osgTerrain library OSGTERRAIN_LIBRARY_DEBUG -
11865 The osgTerrain debug library
11866 $OSGDIR is an environment variable that would correspond to the
11868 Created by Eric Wing.
11870 FindosgText
11872 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
11873 nents. Each component is separate and you must opt in to each module.
11874 You must also opt into OpenGL and OpenThreads (and Producer if needed)
11875 as these modules won’t do it for you. This is to allow you control
11876 over your own system piece by piece in case you need to opt out of cer‐
11877 tain components or change the Find behavior for a particular module
11878 (perhaps because the default FindOpenGL.cmake module doesn’t work with
11879 your system as an example). If you want to use a more convenient mod‐
11880 ule that includes everything, use the FindOpenSceneGraph.cmake instead
11881 of the Findosg*.cmake modules.
11882 Locate osgText This module defines
11884 OSGTEXT_FOUND - Was osgText found? OSGTEXT_INCLUDE_DIR - Where to find
11886 the headers OSGTEXT_LIBRARIES - The libraries to link for osgText (use
11887 this)
11888 OSGTEXT_LIBRARY - The osgText library OSGTEXT_LIBRARY_DEBUG - The osg‐
11890 Text debug library
11891 $OSGDIR is an environment variable that would correspond to the
11893 Created by Eric Wing.
11895 FindosgUtil
11897 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
11898 nents. Each component is separate and you must opt in to each module.
11899 You must also opt into OpenGL and OpenThreads (and Producer if needed)
11900 as these modules won’t do it for you. This is to allow you control
11901 over your own system piece by piece in case you need to opt out of cer‐
11902 tain components or change the Find behavior for a particular module
11903 (perhaps because the default FindOpenGL.cmake module doesn’t work with
11904 your system as an example). If you want to use a more convenient mod‐
11905 ule that includes everything, use the FindOpenSceneGraph.cmake instead
11906 of the Findosg*.cmake modules.
11907 Locate osgUtil This module defines
11909 OSGUTIL_FOUND - Was osgUtil found? OSGUTIL_INCLUDE_DIR - Where to find
11911 the headers OSGUTIL_LIBRARIES - The libraries to link for osgUtil (use
11912 this)
11913 OSGUTIL_LIBRARY - The osgUtil library OSGUTIL_LIBRARY_DEBUG - The
11915 osgUtil debug library
11916 $OSGDIR is an environment variable that would correspond to the
11918 Created by Eric Wing.
11920 FindosgViewer
11922 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
11923 nents. Each component is separate and you must opt in to each module.
11924 You must also opt into OpenGL and OpenThreads (and Producer if needed)
11925 as these modules won’t do it for you. This is to allow you control
11926 over your own system piece by piece in case you need to opt out of cer‐
11927 tain components or change the Find behavior for a particular module
11928 (perhaps because the default FindOpenGL.cmake module doesn’t work with
11929 your system as an example). If you want to use a more convenient mod‐
11930 ule that includes everything, use the FindOpenSceneGraph.cmake instead
11931 of the Findosg*.cmake modules.
11932 Locate osgViewer This module defines
11934 OSGVIEWER_FOUND - Was osgViewer found? OSGVIEWER_INCLUDE_DIR - Where to
11936 find the headers OSGVIEWER_LIBRARIES - The libraries to link for
11937 osgViewer (use this)
11938 OSGVIEWER_LIBRARY - The osgViewer library OSGVIEWER_LIBRARY_DEBUG - The
11940 osgViewer debug library
11941 $OSGDIR is an environment variable that would correspond to the
11943 Created by Eric Wing.
11945 FindosgVolume
11947 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
11948 nents. Each component is separate and you must opt in to each module.
11949 You must also opt into OpenGL and OpenThreads (and Producer if needed)
11950 as these modules won’t do it for you. This is to allow you control
11951 over your own system piece by piece in case you need to opt out of cer‐
11952 tain components or change the Find behavior for a particular module
11953 (perhaps because the default FindOpenGL.cmake module doesn’t work with
11954 your system as an example). If you want to use a more convenient mod‐
11955 ule that includes everything, use the FindOpenSceneGraph.cmake instead
11956 of the Findosg*.cmake modules.
11957 Locate osgVolume This module defines
11959 OSGVOLUME_FOUND - Was osgVolume found? OSGVOLUME_INCLUDE_DIR - Where to
11961 find the headers OSGVOLUME_LIBRARIES - The libraries to link for
11962 osgVolume (use this)
11963 OSGVOLUME_LIBRARY - The osgVolume library OSGVOLUME_LIBRARY_DEBUG - The
11965 osgVolume debug library
11966 $OSGDIR is an environment variable that would correspond to the
11968 Created by Eric Wing.
11970 FindosgWidget
11972 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
11973 nents. Each component is separate and you must opt in to each module.
11974 You must also opt into OpenGL and OpenThreads (and Producer if needed)
11975 as these modules won’t do it for you. This is to allow you control
11976 over your own system piece by piece in case you need to opt out of cer‐
11977 tain components or change the Find behavior for a particular module
11978 (perhaps because the default FindOpenGL.cmake module doesn’t work with
11979 your system as an example). If you want to use a more convenient mod‐
11980 ule that includes everything, use the FindOpenSceneGraph.cmake instead
11981 of the Findosg*.cmake modules.
11982 Locate osgWidget This module defines
11984 OSGWIDGET_FOUND - Was osgWidget found? OSGWIDGET_INCLUDE_DIR - Where to
11986 find the headers OSGWIDGET_LIBRARIES - The libraries to link for osg‐
11987 Widget (use this)
11988 OSGWIDGET_LIBRARY - The osgWidget library OSGWIDGET_LIBRARY_DEBUG - The
11990 osgWidget debug library
11991 $OSGDIR is an environment variable that would correspond to the
11993 FindosgWidget.cmake tweaked from Findosg* suite as created by Eric
11995 Wing.
11996 FindPatch
11998 The module defines the following variables:
11999 Patch_EXECUTABLE
12001 Path to patch command-line executable.
12002 Patch_FOUND
12004 True if the patch command-line executable was found.
12005 The following IMPORTED targets are also defined:
12007 Patch::patch
12009 The command-line executable.
12010 Example usage:
12012 find_package(Patch)
12014 if(Patch_FOUND)
12015 message("Patch found: ${Patch_EXECUTABLE}")
12016 endif()
12017 FindPerlLibs
12019 Find Perl libraries
12020 This module finds if PERL is installed and determines where the include
12022 files and libraries are. It also determines what the name of the
12023 library is. This code sets the following variables:
12024 PERLLIBS_FOUND = True if perl.h & libperl were found
12026 PERL_INCLUDE_PATH = path to where perl.h is found
12027 PERL_LIBRARY = path to libperl
12028 PERL_EXECUTABLE = full path to the perl binary
12029 The minimum required version of Perl can be specified using the stan‐
12031 dard syntax, e.g. find_package(PerlLibs 6.0)
12032 The following variables are also available if needed
12034 (introduced after CMake 2.6.4)
12035 PERL_SITESEARCH = path to the sitesearch install dir (-V:installsitesearch)
12037 PERL_SITEARCH = path to the sitelib install directory (-V:installsitearch)
12038 PERL_SITELIB = path to the sitelib install directory (-V:installsitelib)
12039 PERL_VENDORARCH = path to the vendor arch install directory (-V:installvendorarch)
12040 PERL_VENDORLIB = path to the vendor lib install directory (-V:installvendorlib)
12041 PERL_ARCHLIB = path to the core arch lib install directory (-V:archlib)
12042 PERL_PRIVLIB = path to the core priv lib install directory (-V:privlib)
12043 PERL_UPDATE_ARCHLIB = path to the update arch lib install directory (-V:installarchlib)
12044 PERL_UPDATE_PRIVLIB = path to the update priv lib install directory (-V:installprivlib)
12045 PERL_EXTRA_C_FLAGS = Compilation flags used to build perl
12046 FindPerl
12048 Find perl
12049 this module looks for Perl
12051 PERL_EXECUTABLE - the full path to perl
12053 PERL_FOUND - If false, don't attempt to use perl.
12054 PERL_VERSION_STRING - version of perl found (since CMake 2.8.8)
12055 FindPHP4
12057 Find PHP4
12058 This module finds if PHP4 is installed and determines where the include
12060 files and libraries are. It also determines what the name of the
12061 library is. This code sets the following variables:
12062 PHP4_INCLUDE_PATH = path to where php.h can be found
12064 PHP4_EXECUTABLE = full path to the php4 binary
12065 FindPhysFS
12067 Locate PhysFS library This module defines PHYSFS_LIBRARY, the name of
12068 the library to link against PHYSFS_FOUND, if false, do not try to link
12069 to PHYSFS PHYSFS_INCLUDE_DIR, where to find physfs.h
12070 $PHYSFSDIR is an environment variable that would correspond to the
12072 Created by Eric Wing.
12074 FindPike
12076 Find Pike
12077 This module finds if PIKE is installed and determines where the include
12079 files and libraries are. It also determines what the name of the
12080 library is. This code sets the following variables:
12081 PIKE_INCLUDE_PATH = path to where program.h is found
12083 PIKE_EXECUTABLE = full path to the pike binary
12084 FindPkgConfig
12086 A pkg-config module for CMake.
12087 Finds the pkg-config executable and adds the pkg_get_variable(),
12089 pkg_check_modules() and pkg_search_module() commands. The following
12090 variables will also be set:
12091 PKG_CONFIG_FOUND
12093 if pkg-config executable was found
12094 PKG_CONFIG_EXECUTABLE
12096 pathname of the pkg-config program
12097 PKG_CONFIG_VERSION_STRING
12099 version of pkg-config (since CMake 2.8.8)
12100 pkg_get_variable
12102 Retrieves the value of a pkg-config variable varName and stores
12103 it in the result variable resultVar in the calling scope.
12104 pkg_get_variable(<resultVar> <moduleName> <varName>)
12106 If pkg-config returns multiple values for the specified vari‐
12108 able, resultVar will contain a ;-list.
12109 For example:
12111 pkg_get_variable(GI_GIRDIR gobject-introspection-1.0 girdir)
12113 pkg_check_modules
12115 Checks for all the given modules, setting a variety of result
12116 variables in the calling scope.
12117 pkg_check_modules(<prefix>
12119 [REQUIRED] [QUIET]
12120 [NO_CMAKE_PATH]
12121 [NO_CMAKE_ENVIRONMENT_PATH]
12122 [IMPORTED_TARGET [GLOBAL]]
12123 <moduleSpec> [<moduleSpec>...])
12124 When the REQUIRED argument is given, the command will fail with
12126 an error if module(s) could not be found.
12127 When the QUIET argument is given, no status messages will be
12129 printed.
12130 By default, if CMAKE_MINIMUM_REQUIRED_VERSION is 3.1 or later,
12132 or if PKG_CONFIG_USE_CMAKE_PREFIX_PATH is set to a boolean True
12133 value, then the CMAKE_PREFIX_PATH, CMAKE_FRAMEWORK_PATH, and
12134 CMAKE_APPBUNDLE_PATH cache and environment variables will be
12135 added to the pkg-config search path. The NO_CMAKE_PATH and
12136 NO_CMAKE_ENVIRONMENT_PATH arguments disable this behavior for
12137 the cache variables and environment variables respectively.
12138 The IMPORTED_TARGET argument will create an imported target
12140 named PkgConfig::<prefix> that can be passed directly as an
12141 argument to target_link_libraries(). The GLOBAL argument will
12142 make the imported target available in global scope.
12143 Each <moduleSpec> can be either a bare module name or it can be
12145 a module name with a version constraint (operators =, <, >, <=
12146 and >= are supported). The following are examples for a module
12147 named foo with various constraints:
12148 · foo matches any version.
12150 · foo<2 only matches versions before 2.
12152 · foo>=3.1 matches any version from 3.1 or later.
12154 · foo=1.2.3 requires that foo must be exactly version 1.2.3.
12156 The following variables may be set upon return. Two sets of
12158 values exist: One for the common case (<XXX> = <prefix>) and
12159 another for the information pkg-config provides when called with
12160 the --static option (<XXX> = <prefix>_STATIC).
12161 <XXX>_FOUND
12163 set to 1 if module(s) exist
12164 <XXX>_LIBRARIES
12166 only the libraries (without the ‘-l’)
12167 <XXX>_LINK_LIBRARIES
12169 the libraries and their absolute paths
12170 <XXX>_LIBRARY_DIRS
12172 the paths of the libraries (without the ‘-L’)
12173 <XXX>_LDFLAGS
12175 all required linker flags
12176 <XXX>_LDFLAGS_OTHER
12178 all other linker flags
12179 <XXX>_INCLUDE_DIRS
12181 the ‘-I’ preprocessor flags (without the ‘-I’)
12182 <XXX>_CFLAGS
12184 all required cflags
12185 <XXX>_CFLAGS_OTHER
12187 the other compiler flags
12188 All but <XXX>_FOUND may be a ;-list if the associated variable
12190 returned from pkg-config has multiple values.
12191 There are some special variables whose prefix depends on the
12193 number of <moduleSpec> given. When there is only one <module‐
12194 Spec>, <YYY> will simply be <prefix>, but if two or more <mod‐
12195 uleSpec> items are given, <YYY> will be <prefix>_<moduleName>.
12196 <YYY>_VERSION
12198 version of the module
12199 <YYY>_PREFIX
12201 prefix directory of the module
12202 <YYY>_INCLUDEDIR
12204 include directory of the module
12205 <YYY>_LIBDIR
12207 lib directory of the module
12208 Examples:
12210 pkg_check_modules (GLIB2 glib-2.0)
12212 Looks for any version of glib2. If found, the output variable
12214 GLIB2_VERSION will hold the actual version found.
12215 pkg_check_modules (GLIB2 glib-2.0>=2.10)
12217 Looks for at least version 2.10 of glib2. If found, the output
12219 variable GLIB2_VERSION will hold the actual version found.
12220 pkg_check_modules (FOO glib-2.0>=2.10 gtk+-2.0)
12222 Looks for both glib2-2.0 (at least version 2.10) and any version
12224 of gtk2+-2.0. Only if both are found will FOO be considered
12225 found. The FOO_glib-2.0_VERSION and FOO_gtk+-2.0_VERSION vari‐
12226 ables will be set to their respective found module versions.
12227 pkg_check_modules (XRENDER REQUIRED xrender)
12229 Requires any version of xrender. Example output variables set
12231 by a successful call:
12232 XRENDER_LIBRARIES=Xrender;X11
12234 XRENDER_STATIC_LIBRARIES=Xrender;X11;pthread;Xau;Xdmcp
12235 pkg_search_module
12237 The behavior of this command is the same as pkg_check_modules(),
12238 except that rather than checking for all the specified modules,
12239 it searches for just the first successful match.
12240 pkg_search_module(<prefix>
12242 [REQUIRED] [QUIET]
12243 [NO_CMAKE_PATH]
12244 [NO_CMAKE_ENVIRONMENT_PATH]
12245 [IMPORTED_TARGET [GLOBAL]]
12246 <moduleSpec> [<moduleSpec>...])
12247 Example:
12249 pkg_search_module (BAR libxml-2.0 libxml2 libxml>=2)
12251 Variables Affecting Behavior
12253 PKG_CONFIG_EXECUTABLE
12254 This can be set to the path of the pkg-config executable. If
12255 not provided, it will be set by the module as a result of call‐
12256 ing find_program() internally. The PKG_CONFIG environment vari‐
12257 able can be used as a hint.
12258 PKG_CONFIG_USE_CMAKE_PREFIX_PATH
12260 Specifies whether pkg_check_modules() and pkg_search_module()
12261 should add the paths in the CMAKE_PREFIX_PATH, CMAKE_FRAME‐
12262 WORK_PATH and CMAKE_APPBUNDLE_PATH cache and environment vari‐
12263 ables to the pkg-config search path.
12264 If this variable is not set, this behavior is enabled by default
12266 if CMAKE_MINIMUM_REQUIRED_VERSION is 3.1 or later, disabled oth‐
12267 erwise.
12268 FindPNG
12270 Find libpng, the official reference library for the PNG image format.
12271 Imported targets
12273 This module defines the following IMPORTED target:
12274 PNG::PNG
12276 The libpng library, if found.
12277 Result variables
12279 This module will set the following variables in your project:
12280 PNG_INCLUDE_DIRS
12282 where to find png.h, etc.
12283 PNG_LIBRARIES
12285 the libraries to link against to use PNG.
12286 PNG_DEFINITIONS
12288 You should add_definitions(${PNG_DEFINITIONS}) before compiling
12289 code that includes png library files.
12290 PNG_FOUND
12292 If false, do not try to use PNG.
12293 PNG_VERSION_STRING
12295 the version of the PNG library found (since CMake 2.8.8)
12296 Obsolete variables
12298 The following variables may also be set, for backwards compatibility:
12299 PNG_LIBRARY
12301 where to find the PNG library.
12302 PNG_INCLUDE_DIR
12304 where to find the PNG headers (same as PNG_INCLUDE_DIRS)
12305 Since PNG depends on the ZLib compression library, none of the above
12307 will be defined unless ZLib can be found.
12308 FindPostgreSQL
12310 Find the PostgreSQL installation.
12311 IMPORTED Targets
12313 This module defines IMPORTED target PostgreSQL::PostgreSQL if Post‐
12314 greSQL has been found.
12315 Result Variables
12317 This module will set the following variables in your project:
12318 PostgreSQL_FOUND
12320 True if PostgreSQL is found.
12321 PostgreSQL_LIBRARIES
12323 the PostgreSQL libraries needed for linking
12324 PostgreSQL_INCLUDE_DIRS
12326 the directories of the PostgreSQL headers
12327 PostgreSQL_LIBRARY_DIRS
12329 the link directories for PostgreSQL libraries
12330 PostgreSQL_VERSION_STRING
12332 the version of PostgreSQL found
12333 FindProducer
12335 Though Producer isn’t directly part of OpenSceneGraph, its primary user
12336 is OSG so I consider this part of the Findosg* suite used to find Open‐
12337 SceneGraph components. You’ll notice that I accept OSGDIR as an envi‐
12338 ronment path.
12339 Each component is separate and you must opt in to each module. You
12341 must also opt into OpenGL (and OpenThreads?) as these modules won’t do
12342 it for you. This is to allow you control over your own system piece by
12343 piece in case you need to opt out of certain components or change the
12344 Find behavior for a particular module (perhaps because the default
12345 FindOpenGL.cmake module doesn’t work with your system as an example).
12346 If you want to use a more convenient module that includes everything,
12347 use the FindOpenSceneGraph.cmake instead of the Findosg*.cmake modules.
12348 Locate Producer This module defines PRODUCER_LIBRARY PRODUCER_FOUND, if
12350 false, do not try to link to Producer PRODUCER_INCLUDE_DIR, where to
12351 find the headers
12352 $PRODUCER_DIR is an environment variable that would correspond to the
12354 Created by Eric Wing.
12356 FindProtobuf
12358 Locate and configure the Google Protocol Buffers library.
12359 The following variables can be set and are optional:
12361 Protobuf_SRC_ROOT_FOLDER
12363 When compiling with MSVC, if this cache variable is set the pro‐
12364 tobuf-default VS project build locations (vsprojects/Debug and
12365 vsprojects/Release or vsprojects/x64/Debug and vspro‐
12366 jects/x64/Release) will be searched for libraries and binaries.
12367 Protobuf_IMPORT_DIRS
12369 List of additional directories to be searched for imported
12370 .proto files.
12371 Protobuf_DEBUG
12373 Show debug messages.
12374 Protobuf_USE_STATIC_LIBS
12376 Set to ON to force the use of the static libraries. Default is
12377 OFF.
12378 Defines the following variables:
12380 Protobuf_FOUND
12382 Found the Google Protocol Buffers library (libprotobuf & header
12383 files)
12384 Protobuf_VERSION
12386 Version of package found.
12387 Protobuf_INCLUDE_DIRS
12389 Include directories for Google Protocol Buffers
12390 Protobuf_LIBRARIES
12392 The protobuf libraries
12393 Protobuf_PROTOC_LIBRARIES
12395 The protoc libraries
12396 Protobuf_LITE_LIBRARIES
12398 The protobuf-lite libraries
12399 The following IMPORTED targets are also defined:
12401 protobuf::libprotobuf
12403 The protobuf library.
12404 protobuf::libprotobuf-lite
12406 The protobuf lite library.
12407 protobuf::libprotoc
12409 The protoc library.
12410 protobuf::protoc
12412 The protoc compiler.
12413 The following cache variables are also available to set or use:
12415 Protobuf_LIBRARY
12417 The protobuf library
12418 Protobuf_PROTOC_LIBRARY
12420 The protoc library
12421 Protobuf_INCLUDE_DIR
12423 The include directory for protocol buffers
12424 Protobuf_PROTOC_EXECUTABLE
12426 The protoc compiler
12427 Protobuf_LIBRARY_DEBUG
12429 The protobuf library (debug)
12430 Protobuf_PROTOC_LIBRARY_DEBUG
12432 The protoc library (debug)
12433 Protobuf_LITE_LIBRARY
12435 The protobuf lite library
12436 Protobuf_LITE_LIBRARY_DEBUG
12438 The protobuf lite library (debug)
12439 Example:
12441 find_package(Protobuf REQUIRED)
12443 include_directories(${Protobuf_INCLUDE_DIRS})
12444 include_directories(${CMAKE_CURRENT_BINARY_DIR})
12445 protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS foo.proto)
12446 protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS EXPORT_MACRO DLL_EXPORT foo.proto)
12447 protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS DESCRIPTORS PROTO_DESCS foo.proto)
12448 protobuf_generate_python(PROTO_PY foo.proto)
12449 add_executable(bar bar.cc ${PROTO_SRCS} ${PROTO_HDRS})
12450 target_link_libraries(bar ${Protobuf_LIBRARIES})
12451 NOTE:
12453 The protobuf_generate_cpp and protobuf_generate_python functions and
12454 add_executable() or add_library() calls only work properly within
12455 the same directory.
12456 protobuf_generate_cpp
12458 Add custom commands to process .proto files to C++:
12459 protobuf_generate_cpp (<SRCS> <HDRS>
12461 [DESCRIPTORS <DESC>] [EXPORT_MACRO <MACRO>] [<ARGN>...])
12462 SRCS Variable to define with autogenerated source files
12464 HDRS Variable to define with autogenerated header files
12466 DESCRIPTORS
12468 Variable to define with autogenerated descriptor files,
12469 if requested.
12470 EXPORT_MACRO
12472 is a macro which should expand to __declspec(dllexport)
12473 or __declspec(dllimport) depending on what is being com‐
12474 piled.
12475 ARGN .proto files
12477 protobuf_generate_python
12479 Add custom commands to process .proto files to Python:
12480 protobuf_generate_python (<PY> [<ARGN>...])
12482 PY Variable to define with autogenerated Python files
12484 ARGN .proto filess
12486 FindPython
12488 Find Python interpreter, compiler and development environment (include
12489 directories and libraries).
12490 Three components are supported:
12492 · Interpreter: search for Python interpreter.
12494 · Compiler: search for Python compiler. Only offered by IronPython.
12496 · Development: search for development artifacts (include directories
12498 and libraries).
12499 · NumPy: search for NumPy include directories.
12501 If no COMPONENTS is specified, Interpreter is assumed.
12503 To ensure consistent versions between components Interpreter, Compiler,
12505 Development and NumPy, specify all components at the same time:
12506 find_package (Python COMPONENTS Interpreter Development)
12508 This module looks preferably for version 3 of Python. If not found,
12510 version 2 is searched. To manage concurrent versions 3 and 2 of
12511 Python, use FindPython3 and FindPython2 modules rather than this one.
12512 NOTE:
12514 If components Interpreter and Development are both specified, this
12515 module search only for interpreter with same platform architecture
12516 as the one defined by CMake configuration. This contraint does not
12517 apply if only Interpreter component is specified.
12518 Imported Targets
12520 This module defines the following Imported Targets (when CMAKE_ROLE is
12521 PROJECT):
12522 Python::Interpreter
12524 Python interpreter. Target defined if component Interpreter is
12525 found.
12526 Python::Compiler
12528 Python compiler. Target defined if component Compiler is found.
12529 Python::Python
12531 Python library. Target defined if component Development is
12532 found.
12533 Python::NumPy
12535 NumPy Python library. Target defined if component NumPy is
12536 found.
12537 Result Variables
12539 This module will set the following variables in your project (see Stan‐
12540 dard Variable Names):
12541 Python_FOUND
12543 System has the Python requested components.
12544 Python_Interpreter_FOUND
12546 System has the Python interpreter.
12547 Python_EXECUTABLE
12549 Path to the Python interpreter.
12550 Python_INTERPRETER_ID
12552 A short string unique to the interpreter. Possible values
12554 include:
12555 · Python
12557 · ActivePython
12559 · Anaconda
12561 · Canopy
12563 · IronPython
12565 Python_STDLIB
12567 Standard platform independent installation directory.
12568 Information returned by distutils.syscon‐
12570 fig.get_python_lib(plat_specific=False,standard_lib=True).
12571 Python_STDARCH
12573 Standard platform dependent installation directory.
12574 Information returned by distutils.syscon‐
12576 fig.get_python_lib(plat_specific=True,standard_lib=True).
12577 Python_SITELIB
12579 Third-party platform independent installation directory.
12580 Information returned by distutils.syscon‐
12582 fig.get_python_lib(plat_specific=False,standard_lib=False).
12583 Python_SITEARCH
12585 Third-party platform dependent installation directory.
12586 Information returned by distutils.syscon‐
12588 fig.get_python_lib(plat_specific=True,standard_lib=False).
12589 Python_Compiler_FOUND
12591 System has the Python compiler.
12592 Python_COMPILER
12594 Path to the Python compiler. Only offered by IronPython.
12595 Python_COMPILER_ID
12597 A short string unique to the compiler. Possible values include:
12599 · IronPython
12601 Python_Development_FOUND
12603 System has the Python development artifacts.
12604 Python_INCLUDE_DIRS
12606 The Python include directories.
12607 Python_LIBRARIES
12609 The Python libraries.
12610 Python_LIBRARY_DIRS
12612 The Python library directories.
12613 Python_RUNTIME_LIBRARY_DIRS
12615 The Python runtime library directories.
12616 Python_VERSION
12618 Python version.
12619 Python_VERSION_MAJOR
12621 Python major version.
12622 Python_VERSION_MINOR
12624 Python minor version.
12625 Python_VERSION_PATCH
12627 Python patch version.
12628 Python_NumPy_FOUND
12630 System has the NumPy.
12631 Python_NumPy_INCLUDE_DIRS
12633 The NumPy include directries.
12634 Python_NumPy_VERSION
12636 The NumPy version.
12637 Hints
12639 Python_ROOT_DIR
12640 Define the root directory of a Python installation.
12641 Python_USE_STATIC_LIBS
12643 · If not defined, search for shared libraries and static
12645 libraries in that order.
12646 · If set to TRUE, search only for static libraries.
12648 · If set to FALSE, search only for shared libraries.
12650 Python_FIND_REGISTRY
12652 On Windows the Python_FIND_REGISTRY variable determine the order
12653 of preference between registry and environment variables. the
12654 Python_FIND_REGISTRY variable can be set to empty or one of the
12655 following:
12656 · FIRST: Try to use registry before environment variables. This
12658 is the default.
12659 · LAST: Try to use registry after environment variables.
12661 · NEVER: Never try to use registry.
12663 CMAKE_FIND_FRAMEWORK
12665 On OS X the CMAKE_FIND_FRAMEWORK variable determine the order of
12666 preference between Apple-style and unix-style package compo‐
12667 nents.
12668 NOTE:
12670 Value ONLY is not supported so FIRST will be used instead.
12671 NOTE:
12673 If a Python virtual environment is configured, set variable
12674 Python_FIND_REGISTRY (Windows) or CMAKE_FIND_FRAMEWORK (macOS) with
12675 value LAST or NEVER to select it preferably.
12676 Commands
12678 This module defines the command Python_add_library (when CMAKE_ROLE is
12679 PROJECT), which has the same semantics as add_library(), but takes care
12680 of Python module naming rules (only applied if library is of type MOD‐
12681 ULE), and adds a dependency to target Python::Python:
12682 Python_add_library (my_module MODULE src1.cpp)
12684 If library type is not specified, MODULE is assumed.
12686 FindPython2
12688 Find Python 2 interpreter, compiler and development environment
12689 (include directories and libraries).
12690 Three components are supported:
12692 · Interpreter: search for Python 2 interpreter
12694 · Compiler: search for Python 2 compiler. Only offered by IronPython.
12696 · Development: search for development artifacts (include directories
12698 and libraries)
12699 · NumPy: search for NumPy include directories.
12701 If no COMPONENTS is specified, Interpreter is assumed.
12703 To ensure consistent versions between components Interpreter, Compiler,
12705 Development and NumPy, specify all components at the same time:
12706 find_package (Python2 COMPONENTS Interpreter Development)
12708 This module looks only for version 2 of Python. This module can be used
12710 concurrently with FindPython3 module to use both Python versions.
12711 The FindPython module can be used if Python version does not matter for
12713 you.
12714 NOTE:
12716 If components Interpreter and Development are both specified, this
12717 module search only for interpreter with same platform architecture
12718 as the one defined by CMake configuration. This contraint does not
12719 apply if only Interpreter component is specified.
12720 Imported Targets
12722 This module defines the following Imported Targets (when CMAKE_ROLE is
12723 PROJECT):
12724 Python2::Interpreter
12726 Python 2 interpreter. Target defined if component Interpreter is
12727 found.
12728 Python2::Compiler
12730 Python 2 compiler. Target defined if component Compiler is
12731 found.
12732 Python2::Python
12734 Python 2 library. Target defined if component Development is
12735 found.
12736 Python2::NumPy
12738 NumPy library for Python 2. Target defined if component NumPy is
12739 found.
12740 Result Variables
12742 This module will set the following variables in your project (see Stan‐
12743 dard Variable Names):
12744 Python2_FOUND
12746 System has the Python 2 requested components.
12747 Python2_Interpreter_FOUND
12749 System has the Python 2 interpreter.
12750 Python2_EXECUTABLE
12752 Path to the Python 2 interpreter.
12753 Python2_INTERPRETER_ID
12755 A short string unique to the interpreter. Possible values
12757 include:
12758 · Python
12760 · ActivePython
12762 · Anaconda
12764 · Canopy
12766 · IronPython
12768 Python2_STDLIB
12770 Standard platform independent installation directory.
12771 Information returned by distutils.syscon‐
12773 fig.get_python_lib(plat_specific=False,standard_lib=True).
12774 Python2_STDARCH
12776 Standard platform dependent installation directory.
12777 Information returned by distutils.syscon‐
12779 fig.get_python_lib(plat_specific=True,standard_lib=True).
12780 Python2_SITELIB
12782 Third-party platform independent installation directory.
12783 Information returned by distutils.syscon‐
12785 fig.get_python_lib(plat_specific=False,standard_lib=False).
12786 Python2_SITEARCH
12788 Third-party platform dependent installation directory.
12789 Information returned by distutils.syscon‐
12791 fig.get_python_lib(plat_specific=True,standard_lib=False).
12792 Python2_Compiler_FOUND
12794 System has the Python 2 compiler.
12795 Python2_COMPILER
12797 Path to the Python 2 compiler. Only offered by IronPython.
12798 Python2_COMPILER_ID
12800 A short string unique to the compiler. Possible values include:
12802 · IronPython
12804 Python2_Development_FOUND
12806 System has the Python 2 development artifacts.
12807 Python2_INCLUDE_DIRS
12809 The Python 2 include directories.
12810 Python2_LIBRARIES
12812 The Python 2 libraries.
12813 Python2_LIBRARY_DIRS
12815 The Python 2 library directories.
12816 Python2_RUNTIME_LIBRARY_DIRS
12818 The Python 2 runtime library directories.
12819 Python2_VERSION
12821 Python 2 version.
12822 Python2_VERSION_MAJOR
12824 Python 2 major version.
12825 Python2_VERSION_MINOR
12827 Python 2 minor version.
12828 Python2_VERSION_PATCH
12830 Python 2 patch version.
12831 Python2_NumPy_FOUND
12833 System has the NumPy.
12834 Python2_NumPy_INCLUDE_DIRS
12836 The NumPy include directries.
12837 Python2_NumPy_VERSION
12839 The NumPy version.
12840 Hints
12842 Python2_ROOT_DIR
12843 Define the root directory of a Python 2 installation.
12844 Python2_USE_STATIC_LIBS
12846 · If not defined, search for shared libraries and static
12848 libraries in that order.
12849 · If set to TRUE, search only for static libraries.
12851 · If set to FALSE, search only for shared libraries.
12853 Python2_FIND_REGISTRY
12855 On Windows the Python2_FIND_REGISTRY variable determine the
12856 order of preference between registry and environment variables.
12857 the Python2_FIND_REGISTRY variable can be set to empty or one of
12858 the following:
12859 · FIRST: Try to use registry before environment variables. This
12861 is the default.
12862 · LAST: Try to use registry after environment variables.
12864 · NEVER: Never try to use registry.
12866 CMAKE_FIND_FRAMEWORK
12868 On macOS the CMAKE_FIND_FRAMEWORK variable determine the order
12869 of preference between Apple-style and unix-style package compo‐
12870 nents.
12871 NOTE:
12873 Value ONLY is not supported so FIRST will be used instead.
12874 NOTE:
12876 If a Python virtual environment is configured, set variable
12877 Python_FIND_REGISTRY (Windows) or CMAKE_FIND_FRAMEWORK (macOS) with
12878 value LAST or NEVER to select it preferably.
12879 Commands
12881 This module defines the command Python2_add_library (when CMAKE_ROLE is
12882 PROJECT), which has the same semantics as add_library(), but takes care
12883 of Python module naming rules (only applied if library is of type MOD‐
12884 ULE), and adds a dependency to target Python2::Python:
12885 Python2_add_library (my_module MODULE src1.cpp)
12887 If library type is not specified, MODULE is assumed.
12889 FindPython3
12891 Find Python 3 interpreter, compiler and development environment
12892 (include directories and libraries).
12893 Three components are supported:
12895 · Interpreter: search for Python 3 interpreter
12897 · Compiler: search for Python 3 compiler. Only offered by IronPython.
12899 · Development: search for development artifacts (include directories
12901 and libraries)
12902 · NumPy: search for NumPy include directories.
12904 If no COMPONENTS is specified, Interpreter is assumed.
12906 To ensure consistent versions between components Interpreter, Compiler,
12908 Development and NumPy, specify all components at the same time:
12909 find_package (Python3 COMPONENTS Interpreter Development)
12911 This module looks only for version 3 of Python. This module can be used
12913 concurrently with FindPython2 module to use both Python versions.
12914 The FindPython module can be used if Python version does not matter for
12916 you.
12917 NOTE:
12919 If components Interpreter and Development are both specified, this
12920 module search only for interpreter with same platform architecture
12921 as the one defined by CMake configuration. This contraint does not
12922 apply if only Interpreter component is specified.
12923 Imported Targets
12925 This module defines the following Imported Targets (when CMAKE_ROLE is
12926 PROJECT):
12927 Python3::Interpreter
12929 Python 3 interpreter. Target defined if component Interpreter is
12930 found.
12931 Python3::Compiler
12933 Python 3 compiler. Target defined if component Compiler is
12934 found.
12935 Python3::Python
12937 Python 3 library. Target defined if component Development is
12938 found.
12939 Python3::NumPy
12941 NumPy library for Python 3. Target defined if component NumPy is
12942 found.
12943 Result Variables
12945 This module will set the following variables in your project (see Stan‐
12946 dard Variable Names):
12947 Python3_FOUND
12949 System has the Python 3 requested components.
12950 Python3_Interpreter_FOUND
12952 System has the Python 3 interpreter.
12953 Python3_EXECUTABLE
12955 Path to the Python 3 interpreter.
12956 Python3_INTERPRETER_ID
12958 A short string unique to the interpreter. Possible values
12960 include:
12961 · Python
12963 · ActivePython
12965 · Anaconda
12967 · Canopy
12969 · IronPython
12971 Python3_STDLIB
12973 Standard platform independent installation directory.
12974 Information returned by distutils.syscon‐
12976 fig.get_python_lib(plat_specific=False,standard_lib=True).
12977 Python3_STDARCH
12979 Standard platform dependent installation directory.
12980 Information returned by distutils.syscon‐
12982 fig.get_python_lib(plat_specific=True,standard_lib=True).
12983 Python3_SITELIB
12985 Third-party platform independent installation directory.
12986 Information returned by distutils.syscon‐
12988 fig.get_python_lib(plat_specific=False,standard_lib=False).
12989 Python3_SITEARCH
12991 Third-party platform dependent installation directory.
12992 Information returned by distutils.syscon‐
12994 fig.get_python_lib(plat_specific=True,standard_lib=False).
12995 Python3_Compiler_FOUND
12997 System has the Python 3 compiler.
12998 Python3_COMPILER
13000 Path to the Python 3 compiler. Only offered by IronPython.
13001 Python3_COMPILER_ID
13003 A short string unique to the compiler. Possible values include:
13005 · IronPython
13007 Python3_Development_FOUND
13009 System has the Python 3 development artifacts.
13010 Python3_INCLUDE_DIRS
13012 The Python 3 include directories.
13013 Python3_LIBRARIES
13015 The Python 3 libraries.
13016 Python3_LIBRARY_DIRS
13018 The Python 3 library directories.
13019 Python3_RUNTIME_LIBRARY_DIRS
13021 The Python 3 runtime library directories.
13022 Python3_VERSION
13024 Python 3 version.
13025 Python3_VERSION_MAJOR
13027 Python 3 major version.
13028 Python3_VERSION_MINOR
13030 Python 3 minor version.
13031 Python3_VERSION_PATCH
13033 Python 3 patch version.
13034 Python3_NumPy_FOUND
13036 System has the NumPy.
13037 Python3_NumPy_INCLUDE_DIRS
13039 The NumPy include directries.
13040 Python3_NumPy_VERSION
13042 The NumPy version.
13043 Hints
13045 Python3_ROOT_DIR
13046 Define the root directory of a Python 3 installation.
13047 Python3_USE_STATIC_LIBS
13049 · If not defined, search for shared libraries and static
13051 libraries in that order.
13052 · If set to TRUE, search only for static libraries.
13054 · If set to FALSE, search only for shared libraries.
13056 Python3_FIND_REGISTRY
13058 On Windows the Python3_FIND_REGISTRY variable determine the
13059 order of preference between registry and environment variables.
13060 the Python3_FIND_REGISTRY variable can be set to empty or one of
13061 the following:
13062 · FIRST: Try to use registry before environment variables. This
13064 is the default.
13065 · LAST: Try to use registry after environment variables.
13067 · NEVER: Never try to use registry.
13069 CMAKE_FIND_FRAMEWORK
13071 On OS X the CMAKE_FIND_FRAMEWORK variable determine the order of
13072 preference between Apple-style and unix-style package compo‐
13073 nents.
13074 NOTE:
13076 Value ONLY is not supported so FIRST will be used instead.
13077 NOTE:
13079 If a Python virtual environment is configured, set variable
13080 Python_FIND_REGISTRY (Windows) or CMAKE_FIND_FRAMEWORK (macOS) with
13081 value LAST or NEVER to select it preferably.
13082 Commands
13084 This module defines the command Python3_add_library (when CMAKE_ROLE is
13085 PROJECT), which has the same semantics as add_library(), but takes care
13086 of Python module naming rules (only applied if library is of type MOD‐
13087 ULE), and adds a dependency to target Python3::Python:
13088 Python3_add_library (my_module MODULE src1.cpp)
13090 If library type is not specified, MODULE is assumed.
13092 FindQt3
13094 Locate Qt include paths and libraries
13095 This module defines:
13097 QT_INCLUDE_DIR - where to find qt.h, etc.
13099 QT_LIBRARIES - the libraries to link against to use Qt.
13100 QT_DEFINITIONS - definitions to use when
13101 compiling code that uses Qt.
13102 QT_FOUND - If false, don't try to use Qt.
13103 QT_VERSION_STRING - the version of Qt found
13104 If you need the multithreaded version of Qt, set QT_MT_REQUIRED to TRUE
13106 Also defined, but not for general use are:
13108 QT_MOC_EXECUTABLE, where to find the moc tool.
13110 QT_UIC_EXECUTABLE, where to find the uic tool.
13111 QT_QT_LIBRARY, where to find the Qt library.
13112 QT_QTMAIN_LIBRARY, where to find the qtmain
13113 library. This is only required by Qt3 on Windows.
13114 FindQt4
13116 Finding and Using Qt4
13117 This module can be used to find Qt4. The most important issue is that
13118 the Qt4 qmake is available via the system path. This qmake is then
13119 used to detect basically everything else. This module defines a number
13120 of IMPORTED targets, macros and variables.
13121 Typical usage could be something like:
13123 set(CMAKE_AUTOMOC ON)
13125 set(CMAKE_INCLUDE_CURRENT_DIR ON)
13126 find_package(Qt4 4.4.3 REQUIRED QtGui QtXml)
13127 add_executable(myexe main.cpp)
13128 target_link_libraries(myexe Qt4::QtGui Qt4::QtXml)
13129 NOTE:
13131 When using IMPORTED targets, the qtmain.lib static library is auto‐
13132 matically linked on Windows for WIN32 executables. To disable that
13133 globally, set the QT4_NO_LINK_QTMAIN variable before finding Qt4. To
13134 disable that for a particular executable, set the QT4_NO_LINK_QTMAIN
13135 target property to TRUE on the executable.
13136 Qt Build Tools
13138 Qt relies on some bundled tools for code generation, such as moc for
13139 meta-object code generation,``uic`` for widget layout and population,
13140 and rcc for virtual filesystem content generation. These tools may be
13141 automatically invoked by cmake(1) if the appropriate conditions are
13142 met. See cmake-qt(7) for more.
13143 Qt Macros
13145 In some cases it can be necessary or useful to invoke the Qt build
13146 tools in a more-manual way. Several macros are available to add targets
13147 for such uses.
13148 macro QT4_WRAP_CPP(outfiles inputfile ... [TARGET tgt] OPTIONS ...)
13150 create moc code from a list of files containing Qt class with
13151 the Q_OBJECT declaration. Per-directory preprocessor definitions
13152 are also added. If the <tgt> is specified, the
13153 INTERFACE_INCLUDE_DIRECTORIES and INTERFACE_COMPILE_DEFINITIONS from
13154 the <tgt> are passed to moc. Options may be given to moc, such as
13155 those found when executing "moc -help".
13156 macro QT4_WRAP_UI(outfiles inputfile ... OPTIONS ...)
13158 create code from a list of Qt designer ui files.
13159 Options may be given to uic, such as those found
13160 when executing "uic -help"
13161 macro QT4_ADD_RESOURCES(outfiles inputfile ... OPTIONS ...)
13163 create code from a list of Qt resource files.
13164 Options may be given to rcc, such as those found
13165 when executing "rcc -help"
13166 macro QT4_GENERATE_MOC(inputfile outputfile [TARGET tgt])
13168 creates a rule to run moc on infile and create outfile.
13169 Use this if for some reason QT4_WRAP_CPP() isn't appropriate, e.g.
13170 because you need a custom filename for the moc file or something
13171 similar. If the <tgt> is specified, the
13172 INTERFACE_INCLUDE_DIRECTORIES and INTERFACE_COMPILE_DEFINITIONS from
13173 the <tgt> are passed to moc.
13174 macro QT4_ADD_DBUS_INTERFACE(outfiles interface basename)
13176 Create the interface header and implementation files with the
13177 given basename from the given interface xml file and add it to
13178 the list of sources.
13179 You can pass additional parameters to the qdbusxml2cpp call by setting
13181 properties on the input file:
13182 INCLUDE the given file will be included in the generate interface header
13184 CLASSNAME the generated class is named accordingly
13186 NO_NAMESPACE the generated class is not wrapped in a namespace
13188 macro QT4_ADD_DBUS_INTERFACES(outfiles inputfile ... )
13190 Create the interface header and implementation files
13191 for all listed interface xml files.
13192 The basename will be automatically determined from the name
13193 of the xml file.
13194 The source file properties described for
13196 QT4_ADD_DBUS_INTERFACE also apply here.
13197 macro QT4_ADD_DBUS_ADAPTOR(outfiles xmlfile parentheader parentclassname
13199 [basename] [classname])
13200 create a dbus adaptor (header and implementation file) from the xml file
13201 describing the interface, and add it to the list of sources. The adaptor
13202 forwards the calls to a parent class, defined in parentheader and named
13203 parentclassname. The name of the generated files will be
13204 <basename>adaptor.{cpp,h} where basename defaults to the basename of the
13205 xml file.
13206 If <classname> is provided, then it will be used as the classname of the
13207 adaptor itself.
13208 macro QT4_GENERATE_DBUS_INTERFACE( header [interfacename] OPTIONS ...)
13210 generate the xml interface file from the given header.
13211 If the optional argument interfacename is omitted, the name of the
13212 interface file is constructed from the basename of the header with
13213 the suffix .xml appended.
13214 Options may be given to qdbuscpp2xml, such as those found when
13215 executing "qdbuscpp2xml --help"
13216 macro QT4_CREATE_TRANSLATION( qm_files directories ... sources ...
13218 ts_files ... OPTIONS ...)
13219 out: qm_files
13220 in: directories sources ts_files
13221 options: flags to pass to lupdate, such as -extensions to specify
13222 extensions for a directory scan.
13223 generates commands to create .ts (vie lupdate) and .qm
13224 (via lrelease) - files from directories and/or sources. The ts files are
13225 created and/or updated in the source tree (unless given with full paths).
13226 The qm files are generated in the build tree.
13227 Updating the translations can be done by adding the qm_files
13228 to the source list of your library/executable, so they are
13229 always updated, or by adding a custom target to control when
13230 they get updated/generated.
13231 macro QT4_ADD_TRANSLATION( qm_files ts_files ... )
13233 out: qm_files
13234 in: ts_files
13235 generates commands to create .qm from .ts - files. The generated
13236 filenames can be found in qm_files. The ts_files
13237 must exist and are not updated in any way.
13238 macro QT4_AUTOMOC(sourcefile1 sourcefile2 ... [TARGET tgt])
13240 The qt4_automoc macro is obsolete. Use the CMAKE_AUTOMOC feature instead.
13241 This macro is still experimental.
13242 It can be used to have moc automatically handled.
13243 So if you have the files foo.h and foo.cpp, and in foo.h a
13244 a class uses the Q_OBJECT macro, moc has to run on it. If you don't
13245 want to use QT4_WRAP_CPP() (which is reliable and mature), you can insert
13246 #include "foo.moc"
13247 in foo.cpp and then give foo.cpp as argument to QT4_AUTOMOC(). This will
13248 scan all listed files at cmake-time for such included moc files and if it
13249 finds them cause a rule to be generated to run moc at build time on the
13250 accompanying header file foo.h.
13251 If a source file has the SKIP_AUTOMOC property set it will be ignored by
13252 this macro.
13253 If the <tgt> is specified, the INTERFACE_INCLUDE_DIRECTORIES and
13254 INTERFACE_COMPILE_DEFINITIONS from the <tgt> are passed to moc.
13255 function QT4_USE_MODULES( target [link_type] modules...)
13257 This function is obsolete. Use target_link_libraries with IMPORTED targets
13258 instead.
13259 Make <target> use the <modules> from Qt. Using a Qt module means
13260 to link to the library, add the relevant include directories for the
13261 module, and add the relevant compiler defines for using the module.
13262 Modules are roughly equivalent to components of Qt4, so usage would be
13263 something like:
13264 qt4_use_modules(myexe Core Gui Declarative)
13265 to use QtCore, QtGui and QtDeclarative. The optional <link_type> argument
13266 can be specified as either LINK_PUBLIC or LINK_PRIVATE to specify the
13267 same argument to the target_link_libraries call.
13268 IMPORTED Targets
13270 A particular Qt library may be used by using the corresponding IMPORTED
13271 target with the target_link_libraries() command:
13272 target_link_libraries(myexe Qt4::QtGui Qt4::QtXml)
13274 Using a target in this way causes :cmake(1)` to use the appropriate
13276 include directories and compile definitions for the target when compil‐
13277 ing myexe.
13278 Targets are aware of their dependencies, so for example it is not nec‐
13280 essary to list Qt4::QtCore if another Qt library is listed, and it is
13281 not necessary to list Qt4::QtGui if Qt4::QtDeclarative is listed. Tar‐
13282 gets may be tested for existence in the usual way with the if(TARGET)
13283 command.
13284 The Qt toolkit may contain both debug and release libraries. cmake(1)
13286 will choose the appropriate version based on the build configuration.
13287 Qt4::QtCore
13289 The QtCore target
13290 Qt4::QtGui
13292 The QtGui target
13293 Qt4::Qt3Support
13295 The Qt3Support target
13296 Qt4::QtAssistant
13298 The QtAssistant target
13299 Qt4::QtAssistantClient
13301 The QtAssistantClient target
13302 Qt4::QAxContainer
13304 The QAxContainer target (Windows only)
13305 Qt4::QAxServer
13307 The QAxServer target (Windows only)
13308 Qt4::QtDBus
13310 The QtDBus target
13311 Qt4::QtDeclarative
13313 The QtDeclarative target
13314 Qt4::QtDesigner
13316 The QtDesigner target
13317 Qt4::QtDesignerComponents
13319 The QtDesignerComponents target
13320 Qt4::QtHelp
13322 The QtHelp target
13323 Qt4::QtMotif
13325 The QtMotif target
13326 Qt4::QtMultimedia
13328 The QtMultimedia target
13329 Qt4::QtNetwork
13331 The QtNetwork target
13332 Qt4::QtNsPLugin
13334 The QtNsPLugin target
13335 Qt4::QtOpenGL
13337 The QtOpenGL target
13338 Qt4::QtScript
13340 The QtScript target
13341 Qt4::QtScriptTools
13343 The QtScriptTools target
13344 Qt4::QtSql
13346 The QtSql target
13347 Qt4::QtSvg
13349 The QtSvg target
13350 Qt4::QtTest
13352 The QtTest target
13353 Qt4::QtUiTools
13355 The QtUiTools target
13356 Qt4::QtWebKit
13358 The QtWebKit target
13359 Qt4::QtXml
13361 The QtXml target
13362 Qt4::QtXmlPatterns
13364 The QtXmlPatterns target
13365 Qt4::phonon
13367 The phonon target
13368 Result Variables
13370 Below is a detailed list of variables that FindQt4.cmake sets.
13371 Qt4_FOUND
13373 If false, don’t try to use Qt 4.
13374 QT_FOUND
13376 If false, don’t try to use Qt. This variable is for compatibil‐
13377 ity only.
13378 QT4_FOUND
13380 If false, don’t try to use Qt 4. This variable is for compati‐
13381 bility only.
13382 QT_VERSION_MAJOR
13384 The major version of Qt found.
13385 QT_VERSION_MINOR
13387 The minor version of Qt found.
13388 QT_VERSION_PATCH
13390 The patch version of Qt found.
13391 FindQuickTime
13393 Locate QuickTime This module defines QUICKTIME_LIBRARY QUICKTIME_FOUND,
13394 if false, do not try to link to gdal QUICKTIME_INCLUDE_DIR, where to
13395 find the headers
13396 $QUICKTIME_DIR is an environment variable that would correspond to the
13398 Created by Eric Wing.
13400 FindRTI
13402 Try to find M&S HLA RTI libraries
13403 This module finds if any HLA RTI is installed and locates the standard
13405 RTI include files and libraries.
13406 RTI is a simulation infrastructure standardized by IEEE and SISO. It
13408 has a well defined C++ API that assures that simulation applications
13409 are independent on a particular RTI implementation.
13410 http://en.wikipedia.org/wiki/Run-Time_Infrastructure_(simulation)
13412 This code sets the following variables:
13414 RTI_INCLUDE_DIR = the directory where RTI includes file are found
13416 RTI_LIBRARIES = The libraries to link against to use RTI
13417 RTI_DEFINITIONS = -DRTI_USES_STD_FSTREAM
13418 RTI_FOUND = Set to FALSE if any HLA RTI was not found
13419 Report problems to <certi-devel@nongnu.org>
13421 FindRuby
13423 Find Ruby
13424 This module finds if Ruby is installed and determines where the include
13426 files and libraries are. Ruby 1.8, 1.9, 2.0 and 2.1 are supported.
13427 The minimum required version of Ruby can be specified using the stan‐
13429 dard syntax, e.g. find_package(Ruby 1.8)
13430 It also determines what the name of the library is. This code sets the
13432 following variables:
13433 RUBY_EXECUTABLE
13435 full path to the ruby binary
13436 RUBY_INCLUDE_DIRS
13438 include dirs to be used when using the ruby library
13439 RUBY_LIBRARY
13441 full path to the ruby library
13442 RUBY_VERSION
13444 the version of ruby which was found, e.g. “1.8.7”
13445 RUBY_FOUND
13447 set to true if ruby ws found successfully
13448 Also:
13450 RUBY_INCLUDE_PATH
13452 same as RUBY_INCLUDE_DIRS, only provided for compatibility rea‐
13453 sons, don’t use it
13454 FindSDL_image
13456 Locate SDL_image library
13457 This module defines:
13459 SDL_IMAGE_LIBRARIES, the name of the library to link against
13461 SDL_IMAGE_INCLUDE_DIRS, where to find the headers
13462 SDL_IMAGE_FOUND, if false, do not try to link against
13463 SDL_IMAGE_VERSION_STRING - human-readable string containing the
13464 version of SDL_image
13465 For backward compatibility the following variables are also set:
13467 SDLIMAGE_LIBRARY (same value as SDL_IMAGE_LIBRARIES)
13469 SDLIMAGE_INCLUDE_DIR (same value as SDL_IMAGE_INCLUDE_DIRS)
13470 SDLIMAGE_FOUND (same value as SDL_IMAGE_FOUND)
13471 $SDLDIR is an environment variable that would correspond to the
13473 Created by Eric Wing. This was influenced by the FindSDL.cmake module,
13475 but with modifications to recognize OS X frameworks and additional Unix
13476 paths (FreeBSD, etc).
13477 FindSDL_mixer
13479 Locate SDL_mixer library
13480 This module defines:
13482 SDL_MIXER_LIBRARIES, the name of the library to link against
13484 SDL_MIXER_INCLUDE_DIRS, where to find the headers
13485 SDL_MIXER_FOUND, if false, do not try to link against
13486 SDL_MIXER_VERSION_STRING - human-readable string containing the
13487 version of SDL_mixer
13488 For backward compatibility the following variables are also set:
13490 SDLMIXER_LIBRARY (same value as SDL_MIXER_LIBRARIES)
13492 SDLMIXER_INCLUDE_DIR (same value as SDL_MIXER_INCLUDE_DIRS)
13493 SDLMIXER_FOUND (same value as SDL_MIXER_FOUND)
13494 $SDLDIR is an environment variable that would correspond to the
13496 Created by Eric Wing. This was influenced by the FindSDL.cmake module,
13498 but with modifications to recognize OS X frameworks and additional Unix
13499 paths (FreeBSD, etc).
13500 FindSDL_net
13502 Locate SDL_net library
13503 This module defines:
13505 SDL_NET_LIBRARIES, the name of the library to link against
13507 SDL_NET_INCLUDE_DIRS, where to find the headers
13508 SDL_NET_FOUND, if false, do not try to link against
13509 SDL_NET_VERSION_STRING - human-readable string containing the version of SDL_net
13510 For backward compatibility the following variables are also set:
13512 SDLNET_LIBRARY (same value as SDL_NET_LIBRARIES)
13514 SDLNET_INCLUDE_DIR (same value as SDL_NET_INCLUDE_DIRS)
13515 SDLNET_FOUND (same value as SDL_NET_FOUND)
13516 $SDLDIR is an environment variable that would correspond to the
13518 Created by Eric Wing. This was influenced by the FindSDL.cmake module,
13520 but with modifications to recognize OS X frameworks and additional Unix
13521 paths (FreeBSD, etc).
13522 FindSDL
13524 Locate SDL library
13525 This module defines
13527 SDL_LIBRARY, the name of the library to link against
13529 SDL_FOUND, if false, do not try to link to SDL
13530 SDL_INCLUDE_DIR, where to find SDL.h
13531 SDL_VERSION_STRING, human-readable string containing the version of SDL
13532 This module responds to the flag:
13534 SDL_BUILDING_LIBRARY
13536 If this is defined, then no SDL_main will be linked in because
13537 only applications need main().
13538 Otherwise, it is assumed you are building an application and this
13539 module will attempt to locate and set the proper link flags
13540 as part of the returned SDL_LIBRARY variable.
13541 Don’t forget to include SDLmain.h and SDLmain.m your project for the OS
13543 X framework based version. (Other versions link to -lSDLmain which
13544 this module will try to find on your behalf.) Also for OS X, this mod‐
13545 ule will automatically add the -framework Cocoa on your behalf.
13546 Additional Note: If you see an empty SDL_LIBRARY_TEMP in your configu‐
13548 ration and no SDL_LIBRARY, it means CMake did not find your SDL library
13549 (SDL.dll, libsdl.so, SDL.framework, etc). Set SDL_LIBRARY_TEMP to
13550 point to your SDL library, and configure again. Similarly, if you see
13551 an empty SDLMAIN_LIBRARY, you should set this value as appropriate.
13552 These values are used to generate the final SDL_LIBRARY variable, but
13553 when these values are unset, SDL_LIBRARY does not get created.
13554 $SDLDIR is an environment variable that would correspond to the
13556 Modified by Eric Wing. Added code to assist with automated building by
13558 using environmental variables and providing a more controlled/consis‐
13559 tent search behavior. Added new modifications to recognize OS X frame‐
13560 works and additional Unix paths (FreeBSD, etc). Also corrected the
13561 header search path to follow “proper” SDL guidelines. Added a search
13562 for SDLmain which is needed by some platforms. Added a search for
13563 threads which is needed by some platforms. Added needed compile
13564 switches for MinGW.
13565 On OSX, this will prefer the Framework version (if found) over others.
13567 People will have to manually change the cache values of SDL_LIBRARY to
13568 override this selection or set the CMake environment CMAKE_INCLUDE_PATH
13569 to modify the search paths.
13570 Note that the header path has changed from SDL/SDL.h to just SDL.h This
13572 needed to change because “proper” SDL convention is #include “SDL.h”,
13573 not <SDL/SDL.h>. This is done for portability reasons because not all
13574 systems place things in SDL/ (see FreeBSD).
13575 FindSDL_sound
13577 Locates the SDL_sound library
13578 This module depends on SDL being found and must be called AFTER Find‐
13580 SDL.cmake is called.
13581 This module defines
13583 SDL_SOUND_INCLUDE_DIR, where to find SDL_sound.h
13585 SDL_SOUND_FOUND, if false, do not try to link to SDL_sound
13586 SDL_SOUND_LIBRARIES, this contains the list of libraries that you need
13587 to link against.
13588 SDL_SOUND_EXTRAS, this is an optional variable for you to add your own
13589 flags to SDL_SOUND_LIBRARIES. This is prepended to SDL_SOUND_LIBRARIES.
13590 This is available mostly for cases this module failed to anticipate for
13591 and you must add additional flags. This is marked as ADVANCED.
13592 SDL_SOUND_VERSION_STRING, human-readable string containing the
13593 version of SDL_sound
13594 This module also defines (but you shouldn’t need to use directly)
13596 SDL_SOUND_LIBRARY, the name of just the SDL_sound library you would link
13598 against. Use SDL_SOUND_LIBRARIES for you link instructions and not this one.
13599 And might define the following as needed
13601 MIKMOD_LIBRARY
13603 MODPLUG_LIBRARY
13604 OGG_LIBRARY
13605 VORBIS_LIBRARY
13606 SMPEG_LIBRARY
13607 FLAC_LIBRARY
13608 SPEEX_LIBRARY
13609 Typically, you should not use these variables directly, and you should
13611 use SDL_SOUND_LIBRARIES which contains SDL_SOUND_LIBRARY and the other
13612 audio libraries (if needed) to successfully compile on your system.
13613 Created by Eric Wing. This module is a bit more complicated than the
13615 other FindSDL* family modules. The reason is that SDL_sound can be
13616 compiled in a large variety of different ways which are independent of
13617 platform. SDL_sound may dynamically link against other 3rd party
13618 libraries to get additional codec support, such as Ogg Vorbis, SMPEG,
13619 ModPlug, MikMod, FLAC, Speex, and potentially others. Under some cir‐
13620 cumstances which I don’t fully understand, there seems to be a require‐
13621 ment that dependent libraries of libraries you use must also be explic‐
13622 itly linked against in order to successfully compile. SDL_sound does
13623 not currently have any system in place to know how it was compiled. So
13624 this CMake module does the hard work in trying to discover which 3rd
13625 party libraries are required for building (if any). This module uses a
13626 brute force approach to create a test program that uses SDL_sound, and
13627 then tries to build it. If the build fails, it parses the error output
13628 for known symbol names to figure out which libraries are needed.
13629 Responds to the $SDLDIR and $SDLSOUNDDIR environmental variable that
13631 would correspond to the ./configure –prefix=$SDLDIR used in building
13632 SDL.
13633 On OSX, this will prefer the Framework version (if found) over others.
13635 People will have to manually change the cache values of SDL_LIBRARY to
13636 override this selectionor set the CMake environment CMAKE_INCLUDE_PATH
13637 to modify the search paths.
13638 FindSDL_ttf
13640 Locate SDL_ttf library
13641 This module defines:
13643 SDL_TTF_LIBRARIES, the name of the library to link against
13645 SDL_TTF_INCLUDE_DIRS, where to find the headers
13646 SDL_TTF_FOUND, if false, do not try to link against
13647 SDL_TTF_VERSION_STRING - human-readable string containing the version of SDL_ttf
13648 For backward compatibility the following variables are also set:
13650 SDLTTF_LIBRARY (same value as SDL_TTF_LIBRARIES)
13652 SDLTTF_INCLUDE_DIR (same value as SDL_TTF_INCLUDE_DIRS)
13653 SDLTTF_FOUND (same value as SDL_TTF_FOUND)
13654 $SDLDIR is an environment variable that would correspond to the
13656 Created by Eric Wing. This was influenced by the FindSDL.cmake module,
13658 but with modifications to recognize OS X frameworks and additional Unix
13659 paths (FreeBSD, etc).
13660 FindSelfPackers
13662 Find upx
13663 This module looks for some executable packers (i.e. software that com‐
13665 press executables or shared libs into on-the-fly self-extracting exe‐
13666 cutables or shared libs. Examples:
13667 UPX: http://wildsau.idv.uni-linz.ac.at/mfx/upx.html
13669 FindSquish
13671 – Typical Use
13672 This module can be used to find Squish. Currently Squish versions 3
13674 and 4 are supported.
13675 SQUISH_FOUND If false, don't try to use Squish
13677 SQUISH_VERSION The full version of Squish found
13678 SQUISH_VERSION_MAJOR The major version of Squish found
13679 SQUISH_VERSION_MINOR The minor version of Squish found
13680 SQUISH_VERSION_PATCH The patch version of Squish found
13681 SQUISH_INSTALL_DIR The Squish installation directory
13683 (containing bin, lib, etc)
13684 SQUISH_SERVER_EXECUTABLE The squishserver executable
13685 SQUISH_CLIENT_EXECUTABLE The squishrunner executable
13686 SQUISH_INSTALL_DIR_FOUND Was the install directory found?
13688 SQUISH_SERVER_EXECUTABLE_FOUND Was the server executable found?
13689 SQUISH_CLIENT_EXECUTABLE_FOUND Was the client executable found?
13690 It provides the function squish_v4_add_test() for adding a squish test
13692 to cmake using Squish 4.x:
13693 squish_v4_add_test(cmakeTestName
13695 AUT targetName SUITE suiteName TEST squishTestName
13696 [SETTINGSGROUP group] [PRE_COMMAND command] [POST_COMMAND command] )
13697 The arguments have the following meaning:
13699 cmakeTestName
13701 this will be used as the first argument for add_test()
13702 AUT targetName
13704 the name of the cmake target which will be used as AUT, i.e. the
13705 executable which will be tested.
13706 SUITE suiteName
13708 this is either the full path to the squish suite, or just the
13709 last directory of the suite, i.e. the suite name. In this case
13710 the CMakeLists.txt which calls squish_add_test() must be located
13711 in the parent directory of the suite directory.
13712 TEST squishTestName
13714 the name of the squish test, i.e. the name of the subdirectory
13715 of the test inside the suite directory.
13716 SETTINGSGROUP group
13718 if specified, the given settings group will be used for execut‐
13719 ing the test. If not specified, the groupname will be
13720 “CTest_<username>”
13721 PRE_COMMAND command
13723 if specified, the given command will be executed before starting
13724 the squish test.
13725 POST_COMMAND command
13727 same as PRE_COMMAND, but after the squish test has been exe‐
13728 cuted.
13729 enable_testing()
13731 find_package(Squish 4.0)
13732 if (SQUISH_FOUND)
13733 squish_v4_add_test(myTestName
13734 AUT myApp
13735 SUITE ${CMAKE_SOURCE_DIR}/tests/mySuite
13736 TEST someSquishTest
13737 SETTINGSGROUP myGroup
13738 )
13739 endif ()
13740 For users of Squish version 3.x the macro squish_v3_add_test() is pro‐
13742 vided:
13743 squish_v3_add_test(testName applicationUnderTest testCase envVars testWrapper)
13745 Use this macro to add a test using Squish 3.x.
13746 enable_testing()
13748 find_package(Squish)
13749 if (SQUISH_FOUND)
13750 squish_v3_add_test(myTestName myApplication testCase envVars testWrapper)
13751 endif ()
13752 macro SQUISH_ADD_TEST(testName applicationUnderTest testCase envVars
13754 testWrapper)
13755 This is deprecated. Use SQUISH_V3_ADD_TEST() if you are using Squish 3.x instead.
13757 FindSQLite3
13759 Find the SQLite libraries, v3
13760 IMPORTED targets
13762 This module defines the following IMPORTED target:
13763 SQLite::SQLite3
13765 Result variables
13767 This module will set the following variables if found:
13768 SQLite3_INCLUDE_DIRS
13770 where to find sqlite3.h, etc.
13771 SQLite3_LIBRARIES
13773 the libraries to link against to use SQLite3.
13774 SQLite3_VERSION
13776 version of the SQLite3 library found
13777 SQLite3_FOUND
13779 TRUE if found
13780 FindSubversion
13782 Extract information from a subversion working copy
13783 The module defines the following variables:
13785 Subversion_SVN_EXECUTABLE - path to svn command line client
13787 Subversion_VERSION_SVN - version of svn command line client
13788 Subversion_FOUND - true if the command line client was found
13789 SUBVERSION_FOUND - same as Subversion_FOUND, set for compatibility reasons
13790 The minimum required version of Subversion can be specified using the
13792 standard syntax, e.g. find_package(Subversion 1.4).
13793 If the command line client executable is found two macros are defined:
13795 Subversion_WC_INFO(<dir> <var-prefix> [IGNORE_SVN_FAILURE])
13797 Subversion_WC_LOG(<dir> <var-prefix>)
13798 Subversion_WC_INFO extracts information of a subversion working copy at
13800 a given location. This macro defines the following variables if run‐
13801 ning Subversion’s info command on <dir> succeeds; otherwise a
13802 SEND_ERROR message is generated. The error can be ignored by providing
13803 the IGNORE_SVN_FAILURE option, which causes these variables to remain
13804 undefined.
13805 <var-prefix>_WC_URL - url of the repository (at <dir>)
13807 <var-prefix>_WC_ROOT - root url of the repository
13808 <var-prefix>_WC_REVISION - current revision
13809 <var-prefix>_WC_LAST_CHANGED_AUTHOR - author of last commit
13810 <var-prefix>_WC_LAST_CHANGED_DATE - date of last commit
13811 <var-prefix>_WC_LAST_CHANGED_REV - revision of last commit
13812 <var-prefix>_WC_INFO - output of command `svn info <dir>'
13813 Subversion_WC_LOG retrieves the log message of the base revision of a
13815 subversion working copy at a given location. This macro defines the
13816 variable:
13817 <var-prefix>_LAST_CHANGED_LOG - last log of base revision
13819 Example usage:
13821 find_package(Subversion)
13823 if(SUBVERSION_FOUND)
13824 Subversion_WC_INFO(${PROJECT_SOURCE_DIR} Project)
13825 message("Current revision is ${Project_WC_REVISION}")
13826 Subversion_WC_LOG(${PROJECT_SOURCE_DIR} Project)
13827 message("Last changed log is ${Project_LAST_CHANGED_LOG}")
13828 endif()
13829 FindSWIG
13831 Find SWIG
13832 This module finds an installed SWIG. It sets the following variables:
13834 SWIG_FOUND - set to true if SWIG is found
13836 SWIG_DIR - the directory where swig is installed
13837 SWIG_EXECUTABLE - the path to the swig executable
13838 SWIG_VERSION - the version number of the swig executable
13839 The minimum required version of SWIG can be specified using the stan‐
13841 dard syntax, e.g. find_package(SWIG 1.1)
13842 All information is collected from the SWIG_EXECUTABLE so the version to
13844 be found can be changed from the command line by means of setting
13845 SWIG_EXECUTABLE
13846 FindTCL
13848 TK_INTERNAL_PATH was removed.
13849 This module finds if Tcl is installed and determines where the include
13851 files and libraries are. It also determines what the name of the
13852 library is. This code sets the following variables:
13853 TCL_FOUND = Tcl was found
13855 TK_FOUND = Tk was found
13856 TCLTK_FOUND = Tcl and Tk were found
13857 TCL_LIBRARY = path to Tcl library (tcl tcl80)
13858 TCL_INCLUDE_PATH = path to where tcl.h can be found
13859 TCL_TCLSH = path to tclsh binary (tcl tcl80)
13860 TK_LIBRARY = path to Tk library (tk tk80 etc)
13861 TK_INCLUDE_PATH = path to where tk.h can be found
13862 TK_WISH = full path to the wish executable
13863 In an effort to remove some clutter and clear up some issues for people
13865 who are not necessarily Tcl/Tk gurus/developers, some variables were
13866 moved or removed. Changes compared to CMake 2.4 are:
13867 => they were only useful for people writing Tcl/Tk extensions.
13869 => these libs are not packaged by default with Tcl/Tk distributions.
13870 Even when Tcl/Tk is built from source, several flavors of debug libs
13871 are created and there is no real reason to pick a single one
13872 specifically (say, amongst tcl84g, tcl84gs, or tcl84sgx).
13873 Let's leave that choice to the user by allowing him to assign
13874 TCL_LIBRARY to any Tcl library, debug or not.
13875 => this ended up being only a Win32 variable, and there is a lot of
13876 confusion regarding the location of this file in an installed Tcl/Tk
13877 tree anyway (see 8.5 for example). If you need the internal path at
13878 this point it is safer you ask directly where the *source* tree is
13879 and dig from there.
13880 FindTclsh
13882 Find tclsh
13883 This module finds if TCL is installed and determines where the include
13885 files and libraries are. It also determines what the name of the
13886 library is. This code sets the following variables:
13887 TCLSH_FOUND = TRUE if tclsh has been found
13889 TCL_TCLSH = the path to the tclsh executable
13890 In cygwin, look for the cygwin version first. Don’t look for it later
13892 to avoid finding the cygwin version on a Win32 build.
13893 FindTclStub
13895 TCL_STUB_LIBRARY_DEBUG and TK_STUB_LIBRARY_DEBUG were removed.
13896 This module finds Tcl stub libraries. It first finds Tcl include files
13898 and libraries by calling FindTCL.cmake. How to Use the Tcl Stubs
13899 Library:
13900 http://tcl.activestate.com/doc/howto/stubs.html
13902 Using Stub Libraries:
13904 http://safari.oreilly.com/0130385603/ch48lev1sec3
13906 This code sets the following variables:
13908 TCL_STUB_LIBRARY = path to Tcl stub library
13910 TK_STUB_LIBRARY = path to Tk stub library
13911 TTK_STUB_LIBRARY = path to ttk stub library
13912 In an effort to remove some clutter and clear up some issues for people
13914 who are not necessarily Tcl/Tk gurus/developers, some variables were
13915 moved or removed. Changes compared to CMake 2.4 are:
13916 => these libs are not packaged by default with Tcl/Tk distributions.
13918 Even when Tcl/Tk is built from source, several flavors of debug libs
13919 are created and there is no real reason to pick a single one
13920 specifically (say, amongst tclstub84g, tclstub84gs, or tclstub84sgx).
13921 Let's leave that choice to the user by allowing him to assign
13922 TCL_STUB_LIBRARY to any Tcl library, debug or not.
13923 FindThreads
13925 This module determines the thread library of the system.
13926 The following variables are set
13928 CMAKE_THREAD_LIBS_INIT - the thread library
13930 CMAKE_USE_WIN32_THREADS_INIT - using WIN32 threads?
13931 CMAKE_USE_PTHREADS_INIT - are we using pthreads
13932 CMAKE_HP_PTHREADS_INIT - are we using hp pthreads
13933 The following import target is created
13935 Threads::Threads
13937 If the use of the -pthread compiler and linker flag is preferred then
13939 the caller can set
13940 THREADS_PREFER_PTHREAD_FLAG
13942 The compiler flag can only be used with the imported target. Use of
13944 both the imported target as well as this switch is highly recommended
13945 for new code.
13946 FindTIFF
13948 Find the TIFF library (libtiff).
13949 Imported targets
13951 This module defines the following IMPORTED targets:
13952 TIFF::TIFF
13954 The TIFF library, if found.
13955 Result variables
13957 This module will set the following variables in your project:
13958 TIFF_FOUND
13960 true if the TIFF headers and libraries were found
13961 TIFF_INCLUDE_DIR
13963 the directory containing the TIFF headers
13964 TIFF_INCLUDE_DIRS
13966 the directory containing the TIFF headers
13967 TIFF_LIBRARIES
13969 TIFF libraries to be linked
13970 Cache variables
13972 The following cache variables may also be set:
13973 TIFF_INCLUDE_DIR
13975 the directory containing the TIFF headers
13976 TIFF_LIBRARY
13978 the path to the TIFF library
13979 FindUnixCommands
13981 Find Unix commands, including the ones from Cygwin
13982 This module looks for the Unix commands bash, cp, gzip, mv, rm, and tar
13984 and stores the result in the variables BASH, CP, GZIP, MV, RM, and TAR.
13985 FindVTK
13987 This module no longer exists.
13988 This module existed in versions of CMake prior to 3.1, but became only
13990 a thin wrapper around find_package(VTK NO_MODULE) to provide compati‐
13991 bility for projects using long-outdated conventions. Now find_pack‐
13992 age(VTK) will search for VTKConfig.cmake directly.
13993 FindVulkan
13995 Try to find Vulkan
13996 IMPORTED Targets
13998 This module defines IMPORTED target Vulkan::Vulkan, if Vulkan has been
13999 found.
14000 Result Variables
14002 This module defines the following variables:
14003 Vulkan_FOUND - True if Vulkan was found
14005 Vulkan_INCLUDE_DIRS - include directories for Vulkan
14006 Vulkan_LIBRARIES - link against this library to use Vulkan
14007 The module will also define two cache variables:
14009 Vulkan_INCLUDE_DIR - the Vulkan include directory
14011 Vulkan_LIBRARY - the path to the Vulkan library
14012 FindWget
14014 Find wget
14015 This module looks for wget. This module defines the following values:
14017 WGET_EXECUTABLE: the full path to the wget tool.
14019 WGET_FOUND: True if wget has been found.
14020 FindWish
14022 Find wish installation
14023 This module finds if TCL is installed and determines where the include
14025 files and libraries are. It also determines what the name of the
14026 library is. This code sets the following variables:
14027 TK_WISH = the path to the wish executable
14029 if UNIX is defined, then it will look for the cygwin version first
14031 FindwxWidgets
14033 Find a wxWidgets (a.k.a., wxWindows) installation.
14034 This module finds if wxWidgets is installed and selects a default con‐
14036 figuration to use. wxWidgets is a modular library. To specify the
14037 modules that you will use, you need to name them as components to the
14038 package:
14039 find_package(wxWidgets COMPONENTS core base … OPTIONAL_COMPONENTS net
14041 …)
14042 There are two search branches: a windows style and a unix style. For
14044 windows, the following variables are searched for and set to defaults
14045 in case of multiple choices. Change them if the defaults are not
14046 desired (i.e., these are the only variables you should change to select
14047 a configuration):
14048 wxWidgets_ROOT_DIR - Base wxWidgets directory
14050 (e.g., C:/wxWidgets-2.6.3).
14051 wxWidgets_LIB_DIR - Path to wxWidgets libraries
14052 (e.g., C:/wxWidgets-2.6.3/lib/vc_lib).
14053 wxWidgets_CONFIGURATION - Configuration to use
14054 (e.g., msw, mswd, mswu, mswunivud, etc.)
14055 wxWidgets_EXCLUDE_COMMON_LIBRARIES
14056 - Set to TRUE to exclude linking of
14057 commonly required libs (e.g., png tiff
14058 jpeg zlib regex expat).
14059 For unix style it uses the wx-config utility. You can select between
14061 debug/release, unicode/ansi, universal/non-universal, and static/shared
14062 in the QtDialog or ccmake interfaces by turning ON/OFF the following
14063 variables:
14064 wxWidgets_USE_DEBUG
14066 wxWidgets_USE_UNICODE
14067 wxWidgets_USE_UNIVERSAL
14068 wxWidgets_USE_STATIC
14069 There is also a wxWidgets_CONFIG_OPTIONS variable for all other options
14071 that need to be passed to the wx-config utility. For example, to use
14072 the base toolkit found in the /usr/local path, set the variable (before
14073 calling the FIND_PACKAGE command) as such:
14074 set(wxWidgets_CONFIG_OPTIONS --toolkit=base --prefix=/usr)
14076 The following are set after the configuration is done for both windows
14078 and unix style:
14079 wxWidgets_FOUND - Set to TRUE if wxWidgets was found.
14081 wxWidgets_INCLUDE_DIRS - Include directories for WIN32
14082 i.e., where to find "wx/wx.h" and
14083 "wx/setup.h"; possibly empty for unices.
14084 wxWidgets_LIBRARIES - Path to the wxWidgets libraries.
14085 wxWidgets_LIBRARY_DIRS - compile time link dirs, useful for
14086 rpath on UNIX. Typically an empty string
14087 in WIN32 environment.
14088 wxWidgets_DEFINITIONS - Contains defines required to compile/link
14089 against WX, e.g. WXUSINGDLL
14090 wxWidgets_DEFINITIONS_DEBUG- Contains defines required to compile/link
14091 against WX debug builds, e.g. __WXDEBUG__
14092 wxWidgets_CXX_FLAGS - Include dirs and compiler flags for
14093 unices, empty on WIN32. Essentially
14094 "`wx-config --cxxflags`".
14095 wxWidgets_USE_FILE - Convenience include file.
14096 Sample usage:
14098 # Note that for MinGW users the order of libs is important!
14100 find_package(wxWidgets COMPONENTS gl core base OPTIONAL_COMPONENTS net)
14101 if(wxWidgets_FOUND)
14102 include(${wxWidgets_USE_FILE})
14103 # and for each of your dependent executable/library targets:
14104 target_link_libraries(<YourTarget> ${wxWidgets_LIBRARIES})
14105 endif()
14106 If wxWidgets is required (i.e., not an optional part):
14108 find_package(wxWidgets REQUIRED gl core base OPTIONAL_COMPONENTS net)
14110 include(${wxWidgets_USE_FILE})
14111 # and for each of your dependent executable/library targets:
14112 target_link_libraries(<YourTarget> ${wxWidgets_LIBRARIES})
14113 FindXCTest
14115 Functions to help creating and executing XCTest bundles.
14116 An XCTest bundle is a CFBundle with a special product-type and bundle
14118 extension. The Mac Developer Library provides more information in the
14119 Testing with Xcode document.
14120 Module Functions
14122 xctest_add_bundle
14123 The xctest_add_bundle function creates a XCTest bundle named
14124 <target> which will test the target <testee>. Supported target
14125 types for testee are Frameworks and App Bundles:
14126 xctest_add_bundle(
14128 <target> # Name of the XCTest bundle
14129 <testee> # Target name of the testee
14130 )
14131 xctest_add_test
14133 The xctest_add_test function adds an XCTest bundle to the
14134 project to be run by ctest(1). The test will be named <name> and
14135 tests <bundle>:
14136 xctest_add_test(
14138 <name> # Test name
14139 <bundle> # Target name of XCTest bundle
14140 )
14141 Module Variables
14143 The following variables are set by including this module:
14144 XCTest_FOUND
14146 True if the XCTest Framework and executable were found.
14147 XCTest_EXECUTABLE
14149 The path to the xctest command line tool used to execute XCTest
14150 bundles.
14151 XCTest_INCLUDE_DIRS
14153 The directory containing the XCTest Framework headers.
14154 XCTest_LIBRARIES
14156 The location of the XCTest Framework.
14157 FindXalanC
14159 Find the Apache Xalan-C++ XSL transform processor headers and
14160 libraries.
14161 Imported targets
14163 This module defines the following IMPORTED targets:
14164 XalanC::XalanC
14166 The Xalan-C++ xalan-c library, if found.
14167 Result variables
14169 This module will set the following variables in your project:
14170 XalanC_FOUND
14172 true if the Xalan headers and libraries were found
14173 XalanC_VERSION
14175 Xalan release version
14176 XalanC_INCLUDE_DIRS
14178 the directory containing the Xalan headers; note
14179 XercesC_INCLUDE_DIRS is also required
14180 XalanC_LIBRARIES
14182 Xalan libraries to be linked; note XercesC_LIBRARIES is also
14183 required
14184 Cache variables
14186 The following cache variables may also be set:
14187 XalanC_INCLUDE_DIR
14189 the directory containing the Xalan headers
14190 XalanC_LIBRARY
14192 the Xalan library
14193 FindXercesC
14195 Find the Apache Xerces-C++ validating XML parser headers and libraries.
14196 Imported targets
14198 This module defines the following IMPORTED targets:
14199 XercesC::XercesC
14201 The Xerces-C++ xerces-c library, if found.
14202 Result variables
14204 This module will set the following variables in your project:
14205 XercesC_FOUND
14207 true if the Xerces headers and libraries were found
14208 XercesC_VERSION
14210 Xerces release version
14211 XercesC_INCLUDE_DIRS
14213 the directory containing the Xerces headers
14214 XercesC_LIBRARIES
14216 Xerces libraries to be linked
14217 Cache variables
14219 The following cache variables may also be set:
14220 XercesC_INCLUDE_DIR
14222 the directory containing the Xerces headers
14223 XercesC_LIBRARY
14225 the Xerces library
14226 FindX11
14228 Find X11 installation
14229 Try to find X11 on UNIX systems. The following values are defined
14231 X11_FOUND - True if X11 is available
14233 X11_INCLUDE_DIR - include directories to use X11
14234 X11_LIBRARIES - link against these to use X11
14235 and also the following more fine grained variables and targets:
14237 X11_ICE_INCLUDE_PATH, X11_ICE_LIB, X11_ICE_FOUND, X11::ICE
14239 X11_SM_INCLUDE_PATH, X11_SM_LIB, X11_SM_FOUND, X11::SM
14240 X11_X11_INCLUDE_PATH, X11_X11_LIB, X11::X11
14241 X11_Xaccessrules_INCLUDE_PATH,
14242 X11_Xaccessstr_INCLUDE_PATH, X11_Xaccess_FOUND
14243 X11_Xau_INCLUDE_PATH, X11_Xau_LIB, X11_Xau_FOUND, X11::Xau
14244 X11_Xcomposite_INCLUDE_PATH, X11_Xcomposite_LIB, X11_Xcomposite_FOUND, X11::Xcomposite
14245 X11_Xcursor_INCLUDE_PATH, X11_Xcursor_LIB, X11_Xcursor_FOUND, X11::Xcursor
14246 X11_Xdamage_INCLUDE_PATH, X11_Xdamage_LIB, X11_Xdamage_FOUND, X11::Xdamage
14247 X11_Xdmcp_INCLUDE_PATH, X11_Xdmcp_LIB, X11_Xdmcp_FOUND, X11::Xdmcp
14248 X11_Xext_INCLUDE_PATH, X11_Xext_LIB, X11_Xext_FOUND, X11::Xext
14249 X11_Xxf86misc_INCLUDE_PATH, X11_Xxf86misc_LIB, X11_Xxf86misc_FOUND, X11::Xxf86misc
14250 X11_Xxf86vm_INCLUDE_PATH, X11_Xxf86vm_LIB X11_Xxf86vm_FOUND, X11::Xxf86vm
14251 X11_Xfixes_INCLUDE_PATH, X11_Xfixes_LIB, X11_Xfixes_FOUND, X11::Xfixes
14252 X11_Xft_INCLUDE_PATH, X11_Xft_LIB, X11_Xft_FOUND, X11::Xft
14253 X11_Xi_INCLUDE_PATH, X11_Xi_LIB, X11_Xi_FOUND, X11::Xi
14254 X11_Xinerama_INCLUDE_PATH, X11_Xinerama_LIB, X11_Xinerama_FOUND, X11::Xinerama
14255 X11_Xkb_INCLUDE_PATH,
14256 X11_Xkblib_INCLUDE_PATH, X11_Xkb_FOUND, X11::Xkb
14257 X11_xkbfile_INCLUDE_PATH, X11_xkbfile_LIB, X11_xkbfile_FOUND, X11::xkbfile
14258 X11_Xmu_INCLUDE_PATH, X11_Xmu_LIB, X11_Xmu_FOUND, X11::Xmu
14259 X11_Xpm_INCLUDE_PATH, X11_Xpm_LIB, X11_Xpm_FOUND, X11::Xpm
14260 X11_Xtst_INCLUDE_PATH, X11_Xtst_LIB, X11_Xtst_FOUND, X11::Xtst
14261 X11_Xrandr_INCLUDE_PATH, X11_Xrandr_LIB, X11_Xrandr_FOUND, X11::Xrandr
14262 X11_Xrender_INCLUDE_PATH, X11_Xrender_LIB, X11_Xrender_FOUND, X11::Xrender
14263 X11_XRes_INCLUDE_PATH, X11_XRes_LIB, X11_XRes_FOUND, X11::XRes
14264 X11_Xss_INCLUDE_PATH, X11_Xss_LIB, X11_Xss_FOUND, X11::Xss
14265 X11_Xt_INCLUDE_PATH, X11_Xt_LIB, X11_Xt_FOUND, X11::Xt
14266 X11_Xutil_INCLUDE_PATH, X11_Xutil_FOUND, X11::Xutil
14267 X11_Xv_INCLUDE_PATH, X11_Xv_LIB, X11_Xv_FOUND, X11::Xv
14268 X11_dpms_INCLUDE_PATH, (in X11_Xext_LIB), X11_dpms_FOUND
14269 X11_XShm_INCLUDE_PATH, (in X11_Xext_LIB), X11_XShm_FOUND
14270 X11_Xshape_INCLUDE_PATH, (in X11_Xext_LIB), X11_Xshape_FOUND
14271 X11_XSync_INCLUDE_PATH, (in X11_Xext_LIB), X11_XSync_FOUND
14272 FindXMLRPC
14274 Find xmlrpc
14275 Find the native XMLRPC headers and libraries.
14277 XMLRPC_INCLUDE_DIRS - where to find xmlrpc.h, etc.
14279 XMLRPC_LIBRARIES - List of libraries when using xmlrpc.
14280 XMLRPC_FOUND - True if xmlrpc found.
14281 XMLRPC modules may be specified as components for this find module.
14283 Modules may be listed by running “xmlrpc-c-config”. Modules include:
14284 c++ C++ wrapper code
14286 libwww-client libwww-based client
14287 cgi-server CGI-based server
14288 abyss-server ABYSS-based server
14289 Typical usage:
14291 find_package(XMLRPC REQUIRED libwww-client)
14293 FindZLIB
14295 Find the native ZLIB includes and library.
14296 IMPORTED Targets
14298 This module defines IMPORTED target ZLIB::ZLIB, if ZLIB has been found.
14299 Result Variables
14301 This module defines the following variables:
14302 ZLIB_INCLUDE_DIRS - where to find zlib.h, etc.
14304 ZLIB_LIBRARIES - List of libraries when using zlib.
14305 ZLIB_FOUND - True if zlib found.
14306 ZLIB_VERSION_STRING - The version of zlib found (x.y.z)
14308 ZLIB_VERSION_MAJOR - The major version of zlib
14309 ZLIB_VERSION_MINOR - The minor version of zlib
14310 ZLIB_VERSION_PATCH - The patch version of zlib
14311 ZLIB_VERSION_TWEAK - The tweak version of zlib
14312 Backward Compatibility
14314 The following variable are provided for backward compatibility
14315 ZLIB_MAJOR_VERSION - The major version of zlib
14317 ZLIB_MINOR_VERSION - The minor version of zlib
14318 ZLIB_PATCH_VERSION - The patch version of zlib
14319 Hints
14321 A user may set ZLIB_ROOT to a zlib installation root to tell this mod‐
14322 ule where to look.
14323
14325 Deprecated Utility Modules
14326 CMakeDetermineVSServicePack
14327 Deprecated since version 3.0: Do not use.
14328 The functionality of this module has been superseded by the
14331 CMAKE_<LANG>_COMPILER_VERSION variable that contains the compiler ver‐
14332 sion number.
14333 Determine the Visual Studio service pack of the ‘cl’ in use.
14335 Usage:
14337 if(MSVC)
14339 include(CMakeDetermineVSServicePack)
14340 DetermineVSServicePack( my_service_pack )
14341 if( my_service_pack )
14342 message(STATUS "Detected: ${my_service_pack}")
14343 endif()
14344 endif()
14345 Function DetermineVSServicePack sets the given variable to one of the
14347 following values or an empty string if unknown:
14348 vc80, vc80sp1
14350 vc90, vc90sp1
14351 vc100, vc100sp1
14352 vc110, vc110sp1, vc110sp2, vc110sp3, vc110sp4
14353 CMakeExpandImportedTargets
14355 Deprecated since version 3.4: Do not use.
14356 This module was once needed to expand imported targets to the underly‐
14359 ing libraries they reference on disk for use with the try_compile() and
14360 try_run() commands. These commands now support imported libraries in
14361 their LINK_LIBRARIES options (since CMake 2.8.11 for try_compile() and
14362 since CMake 3.2 for try_run()).
14363 This module does not support the policy CMP0022 NEW behavior or use of
14365 the INTERFACE_LINK_LIBRARIES property because generator expressions
14366 cannot be evaluated during configuration.
14367 CMAKE_EXPAND_IMPORTED_TARGETS(<var> LIBRARIES lib1 lib2...libN
14369 [CONFIGURATION <config>])
14370 CMAKE_EXPAND_IMPORTED_TARGETS() takes a list of libraries and replaces
14372 all imported targets contained in this list with their actual file
14373 paths of the referenced libraries on disk, including the libraries from
14374 their link interfaces. If a CONFIGURATION is given, it uses the
14375 respective configuration of the imported targets if it exists. If no
14376 CONFIGURATION is given, it uses the first configuration from
14377 ${CMAKE_CONFIGURATION_TYPES} if set, otherwise ${CMAKE_BUILD_TYPE}.
14378 cmake_expand_imported_targets(expandedLibs
14380 LIBRARIES ${CMAKE_REQUIRED_LIBRARIES}
14381 CONFIGURATION "${CMAKE_TRY_COMPILE_CONFIGURATION}" )
14382 CMakeForceCompiler
14384 Deprecated since version 3.6: Do not use.
14385 The macros provided by this module were once intended for use by
14388 cross-compiling toolchain files when CMake was not able to automati‐
14389 cally detect the compiler identification. Since the introduction of
14390 this module, CMake’s compiler identification capabilities have improved
14391 and can now be taught to recognize any compiler. Furthermore, the
14392 suite of information CMake detects from a compiler is now too extensive
14393 to be provided by toolchain files using these macros.
14394 One common use case for this module was to skip CMake’s checks for a
14396 working compiler when using a cross-compiler that cannot link binaries
14397 without special flags or custom linker scripts. This case is now sup‐
14398 ported by setting the CMAKE_TRY_COMPILE_TARGET_TYPE variable in the
14399 toolchain file instead.
14400 ----
14403 Macro CMAKE_FORCE_C_COMPILER has the following signature:
14407 CMAKE_FORCE_C_COMPILER(<compiler> <compiler-id>)
14409 It sets CMAKE_C_COMPILER to the given compiler and the cmake internal
14411 variable CMAKE_C_COMPILER_ID to the given compiler-id. It also
14412 bypasses the check for working compiler and basic compiler information
14413 tests.
14414 Macro CMAKE_FORCE_CXX_COMPILER has the following signature:
14416 CMAKE_FORCE_CXX_COMPILER(<compiler> <compiler-id>)
14418 It sets CMAKE_CXX_COMPILER to the given compiler and the cmake internal
14420 variable CMAKE_CXX_COMPILER_ID to the given compiler-id. It also
14421 bypasses the check for working compiler and basic compiler information
14422 tests.
14423 Macro CMAKE_FORCE_Fortran_COMPILER has the following signature:
14425 CMAKE_FORCE_Fortran_COMPILER(<compiler> <compiler-id>)
14427 It sets CMAKE_Fortran_COMPILER to the given compiler and the cmake
14429 internal variable CMAKE_Fortran_COMPILER_ID to the given compiler-id.
14430 It also bypasses the check for working compiler and basic compiler
14431 information tests.
14432 So a simple toolchain file could look like this:
14434 include (CMakeForceCompiler)
14436 set(CMAKE_SYSTEM_NAME Generic)
14437 CMAKE_FORCE_C_COMPILER (chc12 MetrowerksHicross)
14438 CMAKE_FORCE_CXX_COMPILER (chc12 MetrowerksHicross)
14439 CMakeParseArguments
14441 This module once implemented the cmake_parse_arguments() command that
14442 is now implemented natively by CMake. It is now an empty placeholder
14443 for compatibility with projects that include it to get the command from
14444 CMake 3.4 and lower.
14445 MacroAddFileDependencies
14447 MACRO_ADD_FILE_DEPENDENCIES(<_file> depend_files…)
14448 Using the macro MACRO_ADD_FILE_DEPENDENCIES() is discouraged. There
14450 are usually better ways to specify the correct dependencies.
14451 MACRO_ADD_FILE_DEPENDENCIES(<_file> depend_files…) is just a conve‐
14453 nience wrapper around the OBJECT_DEPENDS source file property. You can
14454 just use set_property(SOURCE <file> APPEND PROPERTY OBJECT_DEPENDS
14455 depend_files) instead.
14456 TestCXXAcceptsFlag
14458 Deprecated since version 3.0: See CheckCXXCompilerFlag.
14459 Check if the CXX compiler accepts a flag.
14462 CHECK_CXX_ACCEPTS_FLAG(<flags> <variable>)
14464 <flags>
14466 the flags to try
14467 <variable>
14469 variable to store the result
14470 UsePkgConfig
14472 Obsolete pkg-config module for CMake, use FindPkgConfig instead.
14473 This module defines the following macro:
14475 PKGCONFIG(package includedir libdir linkflags cflags)
14477 Calling PKGCONFIG will fill the desired information into the 4 given
14479 arguments, e.g. PKGCONFIG(libart-2.0 LIBART_INCLUDE_DIR
14480 LIBART_LINK_DIR LIBART_LINK_FLAGS LIBART_CFLAGS) if pkg-config was NOT
14481 found or the specified software package doesn’t exist, the variable
14482 will be empty when the function returns, otherwise they will contain
14483 the respective information
14484 Use_wxWindows
14486 Deprecated since version 2.8.10: Use find_package(wxWidgets) and
14487 include(${wxWidgets_USE_FILE}) instead.
14488 This convenience include finds if wxWindows is installed and set the
14491 appropriate libs, incdirs, flags etc. author Jan Woetzel <jw -at-
14492 mip.informatik.uni-kiel.de> (07/2003)
14493 USAGE:
14495 just include Use_wxWindows.cmake
14497 in your projects CMakeLists.txt
14498 include( ${CMAKE_MODULE_PATH}/Use_wxWindows.cmake)
14500 if you are sure you need GL then
14502 set(WXWINDOWS_USE_GL 1)
14504 *before* you include this file.
14506 WriteBasicConfigVersionFile
14508 Deprecated since version 3.0: Use the identical command
14509 write_basic_package_version_file() from module CMakePackageCon‐
14510 figHelpers.
14511 WRITE_BASIC_CONFIG_VERSION_FILE( filename
14514 [VERSION major.minor.patch]
14515 COMPATIBILITY (AnyNewerVersion|SameMajorVersion|SameMinorVersion|ExactVersion)
14516 [ARCH_INDEPENDENT]
14517 )
14518 Deprecated Find Modules
14520 FindCUDA
14521 Deprecated since version 3.10: Superseded by first-class support for
14522 the CUDA language in CMake.
14523 Replacement
14526 It is no longer necessary to use this module or call find_pack‐
14527 age(CUDA). Instead, list CUDA among the languages named in the
14528 top-level call to the project() command, or call the enable_language()
14529 command with CUDA. Then one can add CUDA (.cu) sources to programs
14530 directly in calls to add_library() and add_executable().
14531 Documentation of Deprecated Usage
14533 Tools for building CUDA C files: libraries and build dependencies.
14534 This script locates the NVIDIA CUDA C tools. It should work on Linux,
14536 Windows, and macOS and should be reasonably up to date with CUDA C
14537 releases.
14538 This script makes use of the standard find_package() arguments of <VER‐
14540 SION>, REQUIRED and QUIET. CUDA_FOUND will report if an acceptable
14541 version of CUDA was found.
14542 The script will prompt the user to specify CUDA_TOOLKIT_ROOT_DIR if the
14544 prefix cannot be determined by the location of nvcc in the system path
14545 and REQUIRED is specified to find_package(). To use a different
14546 installed version of the toolkit set the environment variable
14547 CUDA_BIN_PATH before running cmake (e.g.
14548 CUDA_BIN_PATH=/usr/local/cuda1.0 instead of the default
14549 /usr/local/cuda) or set CUDA_TOOLKIT_ROOT_DIR after configuring. If
14550 you change the value of CUDA_TOOLKIT_ROOT_DIR, various components that
14551 depend on the path will be relocated.
14552 It might be necessary to set CUDA_TOOLKIT_ROOT_DIR manually on certain
14554 platforms, or to use a CUDA runtime not installed in the default loca‐
14555 tion. In newer versions of the toolkit the CUDA library is included
14556 with the graphics driver – be sure that the driver version matches what
14557 is needed by the CUDA runtime version.
14558 The following variables affect the behavior of the macros in the script
14560 (in alphabetical order). Note that any of these flags can be changed
14561 multiple times in the same directory before calling CUDA_ADD_EXE‐
14562 CUTABLE, CUDA_ADD_LIBRARY, CUDA_COMPILE, CUDA_COMPILE_PTX, CUDA_COM‐
14563 PILE_FATBIN, CUDA_COMPILE_CUBIN or CUDA_WRAP_SRCS:
14564 CUDA_64_BIT_DEVICE_CODE (Default matches host bit size)
14566 -- Set to ON to compile for 64 bit device code, OFF for 32 bit device code.
14567 Note that making this different from the host code when generating object
14568 or C files from CUDA code just won't work, because size_t gets defined by
14569 nvcc in the generated source. If you compile to PTX and then load the
14570 file yourself, you can mix bit sizes between device and host.
14571 CUDA_ATTACH_VS_BUILD_RULE_TO_CUDA_FILE (Default ON)
14573 -- Set to ON if you want the custom build rule to be attached to the source
14574 file in Visual Studio. Turn OFF if you add the same cuda file to multiple
14575 targets.
14576 This allows the user to build the target from the CUDA file; however, bad
14578 things can happen if the CUDA source file is added to multiple targets.
14579 When performing parallel builds it is possible for the custom build
14580 command to be run more than once and in parallel causing cryptic build
14581 errors. VS runs the rules for every source file in the target, and a
14582 source can have only one rule no matter how many projects it is added to.
14583 When the rule is run from multiple targets race conditions can occur on
14584 the generated file. Eventually everything will get built, but if the user
14585 is unaware of this behavior, there may be confusion. It would be nice if
14586 this script could detect the reuse of source files across multiple targets
14587 and turn the option off for the user, but no good solution could be found.
14588 CUDA_BUILD_CUBIN (Default OFF)
14590 -- Set to ON to enable and extra compilation pass with the -cubin option in
14591 Device mode. The output is parsed and register, shared memory usage is
14592 printed during build.
14593 CUDA_BUILD_EMULATION (Default OFF for device mode)
14595 -- Set to ON for Emulation mode. -D_DEVICEEMU is defined for CUDA C files
14596 when CUDA_BUILD_EMULATION is TRUE.
14597 CUDA_LINK_LIBRARIES_KEYWORD (Default "")
14599 -- The <PRIVATE|PUBLIC|INTERFACE> keyword to use for internal
14600 target_link_libraries calls. The default is to use no keyword which
14601 uses the old "plain" form of target_link_libraries. Note that is matters
14602 because whatever is used inside the FindCUDA module must also be used
14603 outside - the two forms of target_link_libraries cannot be mixed.
14604 CUDA_GENERATED_OUTPUT_DIR (Default CMAKE_CURRENT_BINARY_DIR)
14606 -- Set to the path you wish to have the generated files placed. If it is
14607 blank output files will be placed in CMAKE_CURRENT_BINARY_DIR.
14608 Intermediate files will always be placed in
14609 CMAKE_CURRENT_BINARY_DIR/CMakeFiles.
14610 CUDA_HOST_COMPILATION_CPP (Default ON)
14612 -- Set to OFF for C compilation of host code.
14613 CUDA_HOST_COMPILER (Default CMAKE_C_COMPILER)
14615 -- Set the host compiler to be used by nvcc. Ignored if -ccbin or
14616 --compiler-bindir is already present in the CUDA_NVCC_FLAGS or
14617 CUDA_NVCC_FLAGS_<CONFIG> variables. For Visual Studio targets,
14618 the host compiler is constructed with one or more visual studio macros
14619 such as $(VCInstallDir), that expands out to the path when
14620 the command is run from within VS.
14621 If the CUDAHOSTCXX environment variable is set it will
14622 be used as the default.
14623 CUDA_NVCC_FLAGS
14625 CUDA_NVCC_FLAGS_<CONFIG>
14626 -- Additional NVCC command line arguments. NOTE: multiple arguments must be
14627 semi-colon delimited (e.g. --compiler-options;-Wall)
14628 CUDA_PROPAGATE_HOST_FLAGS (Default ON)
14630 -- Set to ON to propagate CMAKE_{C,CXX}_FLAGS and their configuration
14631 dependent counterparts (e.g. CMAKE_C_FLAGS_DEBUG) automatically to the
14632 host compiler through nvcc's -Xcompiler flag. This helps make the
14633 generated host code match the rest of the system better. Sometimes
14634 certain flags give nvcc problems, and this will help you turn the flag
14635 propagation off. This does not affect the flags supplied directly to nvcc
14636 via CUDA_NVCC_FLAGS or through the OPTION flags specified through
14637 CUDA_ADD_LIBRARY, CUDA_ADD_EXECUTABLE, or CUDA_WRAP_SRCS. Flags used for
14638 shared library compilation are not affected by this flag.
14639 CUDA_SEPARABLE_COMPILATION (Default OFF)
14641 -- If set this will enable separable compilation for all CUDA runtime object
14642 files. If used outside of CUDA_ADD_EXECUTABLE and CUDA_ADD_LIBRARY
14643 (e.g. calling CUDA_WRAP_SRCS directly),
14644 CUDA_COMPUTE_SEPARABLE_COMPILATION_OBJECT_FILE_NAME and
14645 CUDA_LINK_SEPARABLE_COMPILATION_OBJECTS should be called.
14646 CUDA_SOURCE_PROPERTY_FORMAT
14648 -- If this source file property is set, it can override the format specified
14649 to CUDA_WRAP_SRCS (OBJ, PTX, CUBIN, or FATBIN). If an input source file
14650 is not a .cu file, setting this file will cause it to be treated as a .cu
14651 file. See documentation for set_source_files_properties on how to set
14652 this property.
14653 CUDA_USE_STATIC_CUDA_RUNTIME (Default ON)
14655 -- When enabled the static version of the CUDA runtime library will be used
14656 in CUDA_LIBRARIES. If the version of CUDA configured doesn't support
14657 this option, then it will be silently disabled.
14658 CUDA_VERBOSE_BUILD (Default OFF)
14660 -- Set to ON to see all the commands used when building the CUDA file. When
14661 using a Makefile generator the value defaults to VERBOSE (run make
14662 VERBOSE=1 to see output), although setting CUDA_VERBOSE_BUILD to ON will
14663 always print the output.
14664 The script creates the following macros (in alphabetical order):
14666 CUDA_ADD_CUFFT_TO_TARGET( cuda_target )
14668 -- Adds the cufft library to the target (can be any target). Handles whether
14669 you are in emulation mode or not.
14670 CUDA_ADD_CUBLAS_TO_TARGET( cuda_target )
14672 -- Adds the cublas library to the target (can be any target). Handles
14673 whether you are in emulation mode or not.
14674 CUDA_ADD_EXECUTABLE( cuda_target file0 file1 ...
14676 [WIN32] [MACOSX_BUNDLE] [EXCLUDE_FROM_ALL] [OPTIONS ...] )
14677 -- Creates an executable "cuda_target" which is made up of the files
14678 specified. All of the non CUDA C files are compiled using the standard
14679 build rules specified by CMAKE and the cuda files are compiled to object
14680 files using nvcc and the host compiler. In addition CUDA_INCLUDE_DIRS is
14681 added automatically to include_directories(). Some standard CMake target
14682 calls can be used on the target after calling this macro
14683 (e.g. set_target_properties and target_link_libraries), but setting
14684 properties that adjust compilation flags will not affect code compiled by
14685 nvcc. Such flags should be modified before calling CUDA_ADD_EXECUTABLE,
14686 CUDA_ADD_LIBRARY or CUDA_WRAP_SRCS.
14687 CUDA_ADD_LIBRARY( cuda_target file0 file1 ...
14689 [STATIC | SHARED | MODULE] [EXCLUDE_FROM_ALL] [OPTIONS ...] )
14690 -- Same as CUDA_ADD_EXECUTABLE except that a library is created.
14691 CUDA_BUILD_CLEAN_TARGET()
14693 -- Creates a convenience target that deletes all the dependency files
14694 generated. You should make clean after running this target to ensure the
14695 dependency files get regenerated.
14696 CUDA_COMPILE( generated_files file0 file1 ... [STATIC | SHARED | MODULE]
14698 [OPTIONS ...] )
14699 -- Returns a list of generated files from the input source files to be used
14700 with ADD_LIBRARY or ADD_EXECUTABLE.
14701 CUDA_COMPILE_PTX( generated_files file0 file1 ... [OPTIONS ...] )
14703 -- Returns a list of PTX files generated from the input source files.
14704 CUDA_COMPILE_FATBIN( generated_files file0 file1 ... [OPTIONS ...] )
14706 -- Returns a list of FATBIN files generated from the input source files.
14707 CUDA_COMPILE_CUBIN( generated_files file0 file1 ... [OPTIONS ...] )
14709 -- Returns a list of CUBIN files generated from the input source files.
14710 CUDA_COMPUTE_SEPARABLE_COMPILATION_OBJECT_FILE_NAME( output_file_var
14712 cuda_target
14713 object_files )
14714 -- Compute the name of the intermediate link file used for separable
14715 compilation. This file name is typically passed into
14716 CUDA_LINK_SEPARABLE_COMPILATION_OBJECTS. output_file_var is produced
14717 based on cuda_target the list of objects files that need separable
14718 compilation as specified by object_files. If the object_files list is
14719 empty, then output_file_var will be empty. This function is called
14720 automatically for CUDA_ADD_LIBRARY and CUDA_ADD_EXECUTABLE. Note that
14721 this is a function and not a macro.
14722 CUDA_INCLUDE_DIRECTORIES( path0 path1 ... )
14724 -- Sets the directories that should be passed to nvcc
14725 (e.g. nvcc -Ipath0 -Ipath1 ... ). These paths usually contain other .cu
14726 files.
14727 CUDA_LINK_SEPARABLE_COMPILATION_OBJECTS( output_file_var cuda_target
14730 nvcc_flags object_files)
14731 -- Generates the link object required by separable compilation from the given
14732 object files. This is called automatically for CUDA_ADD_EXECUTABLE and
14733 CUDA_ADD_LIBRARY, but can be called manually when using CUDA_WRAP_SRCS
14734 directly. When called from CUDA_ADD_LIBRARY or CUDA_ADD_EXECUTABLE the
14735 nvcc_flags passed in are the same as the flags passed in via the OPTIONS
14736 argument. The only nvcc flag added automatically is the bitness flag as
14737 specified by CUDA_64_BIT_DEVICE_CODE. Note that this is a function
14738 instead of a macro.
14739 CUDA_SELECT_NVCC_ARCH_FLAGS(out_variable [target_CUDA_architectures])
14741 -- Selects GPU arch flags for nvcc based on target_CUDA_architectures
14742 target_CUDA_architectures : Auto | Common | All | LIST(ARCH_AND_PTX ...)
14743 - "Auto" detects local machine GPU compute arch at runtime.
14744 - "Common" and "All" cover common and entire subsets of architectures
14745 ARCH_AND_PTX : NAME | NUM.NUM | NUM.NUM(NUM.NUM) | NUM.NUM+PTX
14746 NAME: Fermi Kepler Maxwell Kepler+Tegra Kepler+Tesla Maxwell+Tegra Pascal
14747 NUM: Any number. Only those pairs are currently accepted by NVCC though:
14748 2.0 2.1 3.0 3.2 3.5 3.7 5.0 5.2 5.3 6.0 6.2
14749 Returns LIST of flags to be added to CUDA_NVCC_FLAGS in ${out_variable}
14750 Additionally, sets ${out_variable}_readable to the resulting numeric list
14751 Example:
14752 CUDA_SELECT_NVCC_ARCH_FLAGS(ARCH_FLAGS 3.0 3.5+PTX 5.2(5.0) Maxwell)
14753 LIST(APPEND CUDA_NVCC_FLAGS ${ARCH_FLAGS})
14754 More info on CUDA architectures: https://en.wikipedia.org/wiki/CUDA
14756 Note that this is a function instead of a macro.
14757 CUDA_WRAP_SRCS ( cuda_target format generated_files file0 file1 ...
14759 [STATIC | SHARED | MODULE] [OPTIONS ...] )
14760 -- This is where all the magic happens. CUDA_ADD_EXECUTABLE,
14761 CUDA_ADD_LIBRARY, CUDA_COMPILE, and CUDA_COMPILE_PTX all call this
14762 function under the hood.
14763 Given the list of files (file0 file1 ... fileN) this macro generates
14765 custom commands that generate either PTX or linkable objects (use "PTX" or
14766 "OBJ" for the format argument to switch). Files that don't end with .cu
14767 or have the HEADER_FILE_ONLY property are ignored.
14768 The arguments passed in after OPTIONS are extra command line options to
14770 give to nvcc. You can also specify per configuration options by
14771 specifying the name of the configuration followed by the options. General
14772 options must precede configuration specific options. Not all
14773 configurations need to be specified, only the ones provided will be used.
14774 OPTIONS -DFLAG=2 "-DFLAG_OTHER=space in flag"
14776 DEBUG -g
14777 RELEASE --use_fast_math
14778 RELWITHDEBINFO --use_fast_math;-g
14779 MINSIZEREL --use_fast_math
14780 For certain configurations (namely VS generating object files with
14782 CUDA_ATTACH_VS_BUILD_RULE_TO_CUDA_FILE set to ON), no generated file will
14783 be produced for the given cuda file. This is because when you add the
14784 cuda file to Visual Studio it knows that this file produces an object file
14785 and will link in the resulting object file automatically.
14786 This script will also generate a separate cmake script that is used at
14788 build time to invoke nvcc. This is for several reasons.
14789 1. nvcc can return negative numbers as return values which confuses
14791 Visual Studio into thinking that the command succeeded. The script now
14792 checks the error codes and produces errors when there was a problem.
14793 2. nvcc has been known to not delete incomplete results when it
14795 encounters problems. This confuses build systems into thinking the
14796 target was generated when in fact an unusable file exists. The script
14797 now deletes the output files if there was an error.
14798 3. By putting all the options that affect the build into a file and then
14800 make the build rule dependent on the file, the output files will be
14801 regenerated when the options change.
14802 This script also looks at optional arguments STATIC, SHARED, or MODULE to
14804 determine when to target the object compilation for a shared library.
14805 BUILD_SHARED_LIBS is ignored in CUDA_WRAP_SRCS, but it is respected in
14806 CUDA_ADD_LIBRARY. On some systems special flags are added for building
14807 objects intended for shared libraries. A preprocessor macro,
14808 <target_name>_EXPORTS is defined when a shared library compilation is
14809 detected.
14810 Flags passed into add_definitions with -D or /D are passed along to nvcc.
14812 The script defines the following variables:
14814 CUDA_VERSION_MAJOR -- The major version of cuda as reported by nvcc.
14816 CUDA_VERSION_MINOR -- The minor version.
14817 CUDA_VERSION
14818 CUDA_VERSION_STRING -- CUDA_VERSION_MAJOR.CUDA_VERSION_MINOR
14819 CUDA_HAS_FP16 -- Whether a short float (float16,fp16) is supported.
14820 CUDA_TOOLKIT_ROOT_DIR -- Path to the CUDA Toolkit (defined if not set).
14822 CUDA_SDK_ROOT_DIR -- Path to the CUDA SDK. Use this to find files in the
14823 SDK. This script will not directly support finding
14824 specific libraries or headers, as that isn't
14825 supported by NVIDIA. If you want to change
14826 libraries when the path changes see the
14827 FindCUDA.cmake script for an example of how to clear
14828 these variables. There are also examples of how to
14829 use the CUDA_SDK_ROOT_DIR to locate headers or
14830 libraries, if you so choose (at your own risk).
14831 CUDA_INCLUDE_DIRS -- Include directory for cuda headers. Added automatically
14832 for CUDA_ADD_EXECUTABLE and CUDA_ADD_LIBRARY.
14833 CUDA_LIBRARIES -- Cuda RT library.
14834 CUDA_CUFFT_LIBRARIES -- Device or emulation library for the Cuda FFT
14835 implementation (alternative to:
14836 CUDA_ADD_CUFFT_TO_TARGET macro)
14837 CUDA_CUBLAS_LIBRARIES -- Device or emulation library for the Cuda BLAS
14838 implementation (alternative to:
14839 CUDA_ADD_CUBLAS_TO_TARGET macro).
14840 CUDA_cudart_static_LIBRARY -- Statically linkable cuda runtime library.
14841 Only available for CUDA version 5.5+
14842 CUDA_cudadevrt_LIBRARY -- Device runtime library.
14843 Required for separable compilation.
14844 CUDA_cupti_LIBRARY -- CUDA Profiling Tools Interface library.
14845 Only available for CUDA version 4.0+.
14846 CUDA_curand_LIBRARY -- CUDA Random Number Generation library.
14847 Only available for CUDA version 3.2+.
14848 CUDA_cusolver_LIBRARY -- CUDA Direct Solver library.
14849 Only available for CUDA version 7.0+.
14850 CUDA_cusparse_LIBRARY -- CUDA Sparse Matrix library.
14851 Only available for CUDA version 3.2+.
14852 CUDA_npp_LIBRARY -- NVIDIA Performance Primitives lib.
14853 Only available for CUDA version 4.0+.
14854 CUDA_nppc_LIBRARY -- NVIDIA Performance Primitives lib (core).
14855 Only available for CUDA version 5.5+.
14856 CUDA_nppi_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
14857 Only available for CUDA version 5.5 - 8.0.
14858 CUDA_nppial_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
14859 Only available for CUDA version 9.0.
14860 CUDA_nppicc_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
14861 Only available for CUDA version 9.0.
14862 CUDA_nppicom_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
14863 Only available for CUDA version 9.0.
14864 CUDA_nppidei_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
14865 Only available for CUDA version 9.0.
14866 CUDA_nppif_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
14867 Only available for CUDA version 9.0.
14868 CUDA_nppig_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
14869 Only available for CUDA version 9.0.
14870 CUDA_nppim_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
14871 Only available for CUDA version 9.0.
14872 CUDA_nppist_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
14873 Only available for CUDA version 9.0.
14874 CUDA_nppisu_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
14875 Only available for CUDA version 9.0.
14876 CUDA_nppitc_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
14877 Only available for CUDA version 9.0.
14878 CUDA_npps_LIBRARY -- NVIDIA Performance Primitives lib (signal processing).
14879 Only available for CUDA version 5.5+.
14880 CUDA_nvcuvenc_LIBRARY -- CUDA Video Encoder library.
14881 Only available for CUDA version 3.2+.
14882 Windows only.
14883 CUDA_nvcuvid_LIBRARY -- CUDA Video Decoder library.
14884 Only available for CUDA version 3.2+.
14885 Windows only.
14886 FindPythonInterp
14888 Deprecated since version 3.12: Use FindPython3, FindPython2 or Find‐
14889 Python instead.
14890 Find python interpreter
14893 This module finds if Python interpreter is installed and determines
14895 where the executables are. This code sets the following variables:
14896 PYTHONINTERP_FOUND - Was the Python executable found
14898 PYTHON_EXECUTABLE - path to the Python interpreter
14899 PYTHON_VERSION_STRING - Python version found e.g. 2.5.2
14901 PYTHON_VERSION_MAJOR - Python major version found e.g. 2
14902 PYTHON_VERSION_MINOR - Python minor version found e.g. 5
14903 PYTHON_VERSION_PATCH - Python patch version found e.g. 2
14904 The Python_ADDITIONAL_VERSIONS variable can be used to specify a list
14906 of version numbers that should be taken into account when searching for
14907 Python. You need to set this variable before calling find_pack‐
14908 age(PythonInterp).
14909 If calling both find_package(PythonInterp) and find_package(Python‐
14911 Libs), call find_package(PythonInterp) first to get the currently
14912 active Python version by default with a consistent version of
14913 PYTHON_LIBRARIES.
14914 FindPythonLibs
14916 Deprecated since version 3.12: Use FindPython3, FindPython2 or Find‐
14917 Python instead.
14918 Find python libraries
14921 This module finds if Python is installed and determines where the
14923 include files and libraries are. It also determines what the name of
14924 the library is. This code sets the following variables:
14925 PYTHONLIBS_FOUND - have the Python libs been found
14927 PYTHON_LIBRARIES - path to the python library
14928 PYTHON_INCLUDE_PATH - path to where Python.h is found (deprecated)
14929 PYTHON_INCLUDE_DIRS - path to where Python.h is found
14930 PYTHON_DEBUG_LIBRARIES - path to the debug library (deprecated)
14931 PYTHONLIBS_VERSION_STRING - version of the Python libs found (since CMake 2.8.8)
14932 The Python_ADDITIONAL_VERSIONS variable can be used to specify a list
14934 of version numbers that should be taken into account when searching for
14935 Python. You need to set this variable before calling find_pack‐
14936 age(PythonLibs).
14937 If you’d like to specify the installation of Python to use, you should
14939 modify the following cache variables:
14940 PYTHON_LIBRARY - path to the python library
14942 PYTHON_INCLUDE_DIR - path to where Python.h is found
14943 If calling both find_package(PythonInterp) and find_package(Python‐
14945 Libs), call find_package(PythonInterp) first to get the currently
14946 active Python version by default with a consistent version of
14947 PYTHON_LIBRARIES.
14948 FindQt
14950 Searches for all installed versions of Qt3 or Qt4.
14951 This module cannot handle Qt5 or any later versions. For those, see
14953 cmake-qt(7).
14954 This module exists for the find_package() command only if policy
14956 CMP0084 is not set to NEW.
14957 This module should only be used if your project can work with multiple
14959 versions of Qt. If not, you should just directly use FindQt4 or
14960 FindQt3. If multiple versions of Qt are found on the machine, then The
14961 user must set the option DESIRED_QT_VERSION to the version they want to
14962 use. If only one version of qt is found on the machine, then the
14963 DESIRED_QT_VERSION is set to that version and the matching FindQt3 or
14964 FindQt4 module is included. Once the user sets DESIRED_QT_VERSION,
14965 then the FindQt3 or FindQt4 module is included.
14966 QT_REQUIRED if this is set to TRUE then if CMake can
14968 not find Qt4 or Qt3 an error is raised
14969 and a message is sent to the user.
14970 DESIRED_QT_VERSION OPTION is created
14972 QT4_INSTALLED is set to TRUE if qt4 is found.
14973 QT3_INSTALLED is set to TRUE if qt3 is found.
14974 FindwxWindows
14976 Deprecated since version 3.0: Replaced by FindwxWidgets.
14977 Find wxWindows (wxWidgets) installation
14980 This module finds if wxWindows/wxWidgets is installed and determines
14982 where the include files and libraries are. It also determines what the
14983 name of the library is. This code sets the following variables:
14984 WXWINDOWS_FOUND = system has WxWindows
14986 WXWINDOWS_LIBRARIES = path to the wxWindows libraries
14987 on Unix/Linux with additional
14988 linker flags from
14989 "wx-config --libs"
14990 CMAKE_WXWINDOWS_CXX_FLAGS = Compiler flags for wxWindows,
14991 essentially "`wx-config --cxxflags`"
14992 on Linux
14993 WXWINDOWS_INCLUDE_DIR = where to find "wx/wx.h" and "wx/setup.h"
14994 WXWINDOWS_LINK_DIRECTORIES = link directories, useful for rpath on
14995 Unix
14996 WXWINDOWS_DEFINITIONS = extra defines
14997 OPTIONS If you need OpenGL support please
14999 set(WXWINDOWS_USE_GL 1)
15001 in your CMakeLists.txt before you include this file.
15003 HAVE_ISYSTEM - true required to replace -I by -isystem on g++
15005 For convenience include Use_wxWindows.cmake in your project’s CMake‐
15007 Lists.txt using include(${CMAKE_CURRENT_LIST_DIR}/Use_wxWindows.cmake).
15008 USAGE
15010 set(WXWINDOWS_USE_GL 1)
15012 find_package(wxWindows)
15013 NOTES wxWidgets 2.6.x is supported for monolithic builds e.g. compiled
15015 in wx/build/msw dir as:
15016 nmake -f makefile.vc BUILD=debug SHARED=0 USE_OPENGL=1 MONOLITHIC=1
15018 DEPRECATED
15020 CMAKE_WX_CAN_COMPILE
15022 WXWINDOWS_LIBRARY
15023 CMAKE_WX_CXX_FLAGS
15024 WXWINDOWS_INCLUDE_PATH
15025 AUTHOR Jan Woetzel <http://www.mip.informatik.uni-kiel.de/~jw>
15027 (07/2003-01/2006)
15028 Legacy CPack Modules
15030 These modules used to be mistakenly exposed to the user, and have been
15031 moved out of user visibility. They are for CPack internal use, and
15032 should never be used directly.
15033 CPackArchive
15035 The documentation for the CPack Archive generator has moved here: CPack
15036 Archive Generator
15037 CPackBundle
15039 The documentation for the CPack Bundle generator has moved here: CPack
15040 Bundle Generator
15041 CPackCygwin
15043 The documentation for the CPack Cygwin generator has moved here: CPack
15044 Cygwin Generator
15045 CPackDeb
15047 The documentation for the CPack DEB generator has moved here: CPack DEB
15048 Generator
15049 CPackDMG
15051 The documentation for the CPack DragNDrop generator has moved here:
15052 CPack DragNDrop Generator
15053 CPackFreeBSD
15055 The documentation for the CPack FreeBSD generator has moved here: CPack
15056 FreeBSD Generator
15057 CPackNSIS
15059 The documentation for the CPack NSIS generator has moved here: CPack
15060 NSIS Generator
15061 CPackNuGet
15063 The documentation for the CPack NuGet generator has moved here: CPack
15064 NuGet Generator
15065 CPackPackageMaker
15067 The documentation for the CPack PackageMaker generator has moved here:
15068 CPack PackageMaker Generator
15069 CPackProductBuild
15071 The documentation for the CPack productbuild generator has moved here:
15072 CPack productbuild Generator
15073 CPackRPM
15075 The documentation for the CPack RPM generator has moved here: CPack RPM
15076 Generator
15077 CPackWIX
15079 The documentation for the CPack WIX generator has moved here: CPack WIX
15080 Generator
15081
15083 2000-2019 Kitware, Inc. and Contributors
150843.14.5 Jun 01, 2019 CMAKE-MODULES(7)