1CMAKE-MODULES(7) CMake CMAKE-MODULES(7)
2
6 cmake-modules - CMake Modules Reference
7 The modules listed here are part of the CMake distribution. Projects
9 may provide further modules; their location(s) can be specified in the
10 CMAKE_MODULE_PATH variable.
11
13 These modules are loaded using the include() command.
14 AddFileDependencies
16 Add dependencies to a source file.
17 ADD_FILE_DEPENDENCIES(<source> <files>)
19 Adds the given <files> to the dependencies of file <source>.
21 AndroidTestUtilities
23 Create a test that automatically loads specified data onto an Android
24 device.
25 Introduction
27 Use this module to push data needed for testing an Android device
28 behavior onto a connected Android device. The module will accept files
29 and libraries as well as separate destinations for each. It will create
30 a test that loads the files into a device object store and link to them
31 from the specified destination. The files are only uploaded if they are
32 not already in the object store.
33 For example:
35 include(AndroidTestUtilities)
37 android_add_test_data(
38 example_setup_test
39 FILES <files>...
40 LIBS <libs>...
41 DEVICE_TEST_DIR "/data/local/tests/example"
42 DEVICE_OBJECT_STORE "/sdcard/.ExternalData/SHA"
43 )
44 At build time a test named “example_setup_test” will be created. Run
46 this test on the command line with ctest(1) to load the data onto the
47 Android device.
48 Module Functions
50 android_add_test_data
51 android_add_test_data(<test-name>
53 [FILES <files>...] [FILES_DEST <device-dir>]
54 [LIBS <libs>...] [LIBS_DEST <device-dir>]
55 [DEVICE_OBJECT_STORE <device-dir>]
56 [DEVICE_TEST_DIR <device-dir>]
57 [NO_LINK_REGEX <strings>...]
58 )
59 The android_add_test_data function is used to copy files and
61 libraries needed to run project-specific tests. On the host
62 operating system, this is done at build time. For on-device
63 testing, the files are loaded onto the device by the manufac‐
64 tured test at run time.
65 This function accepts the following named parameters:
67 FILES <files>...
69 zero or more files needed for testing
70 LIBS <libs>...
72 zero or more libraries needed for testing
73 FILES_DEST <device-dir>
75 absolute path where the data files are expected to be
76 LIBS_DEST <device-dir>
78 absolute path where the libraries are expected to be
79 DEVICE_OBJECT_STORE <device-dir>
81 absolute path to the location where the data is stored
82 on-device
83 DEVICE_TEST_DIR <device-dir>
85 absolute path to the root directory of the on-device test
86 location
87 NO_LINK_REGEX <strings>...
89 list of regex strings matching the names of files that
90 should be copied from the object store to the testing
91 directory
92 BundleUtilities
94 Functions to help assemble a standalone bundle application.
95 A collection of CMake utility functions useful for dealing with .app
97 bundles on the Mac and bundle-like directories on any OS.
98 The following functions are provided by this module:
100 fixup_bundle
102 copy_and_fixup_bundle
103 verify_app
104 get_bundle_main_executable
105 get_dotapp_dir
106 get_bundle_and_executable
107 get_bundle_all_executables
108 get_item_key
109 get_item_rpaths
110 clear_bundle_keys
111 set_bundle_key_values
112 get_bundle_keys
113 copy_resolved_item_into_bundle
114 copy_resolved_framework_into_bundle
115 fixup_bundle_item
116 verify_bundle_prerequisites
117 verify_bundle_symlinks
118 Requires CMake 2.6 or greater because it uses function, break and PAR‐
120 ENT_SCOPE. Also depends on GetPrerequisites.cmake.
121 DO NOT USE THESE FUNCTIONS AT CONFIGURE TIME (from CMakeLists.txt)!
123 Instead, invoke them from an install(CODE) or install(SCRIPT) rule.
124 fixup_bundle(<app> <libs> <dirs>)
126 Fix up <app> bundle in-place and make it standalone, such that it can
128 be drag-n-drop copied to another machine and run on that machine as
129 long as all of the system libraries are compatible.
130 If you pass plugins to fixup_bundle as the libs parameter, you should
132 install them or copy them into the bundle before calling fixup_bundle.
133 The <libs> parameter is a list of libraries that must be fixed up, but
134 that cannot be determined by otool output analysis (i.e. plugins).
135 Gather all the keys for all the executables and libraries in a bundle,
137 and then, for each key, copy each prerequisite into the bundle. Then
138 fix each one up according to its own list of prerequisites.
139 Then clear all the keys and call verify_app on the final bundle to
141 ensure that it is truly standalone.
142 As an optional parameter (IGNORE_ITEM) a list of file names can be
144 passed, which are then ignored (e.g. IGNORE_ITEM "vcre‐
145 dist_x86.exe;vcredist_x64.exe").
146 copy_and_fixup_bundle(<src> <dst> <libs> <dirs>)
148 Makes a copy of the bundle <src> at location <dst> and then fixes up
150 the new copied bundle in-place at <dst>.
151 verify_app(<app>)
153 Verifies that an application <app> appears valid based on running anal‐
155 ysis tools on it. Calls message(FATAL_ERROR) if the application is not
156 verified.
157 As an optional parameter (IGNORE_ITEM) a list of file names can be
159 passed, which are then ignored (e.g. IGNORE_ITEM "vcre‐
160 dist_x86.exe;vcredist_x64.exe")
161 get_bundle_main_executable(<bundle> <result_var>)
163 The result will be the full path name of the bundle’s main executable
165 file or an error: prefixed string if it could not be determined.
166 get_dotapp_dir(<exe> <dotapp_dir_var>)
168 Returns the nearest parent dir whose name ends with .app given the full
170 path to an executable. If there is no such parent dir, then simply
171 return the dir containing the executable.
172 The returned directory may or may not exist.
174 get_bundle_and_executable(<app> <bundle_var> <executable_var> <valid_var>)
176 Takes either a .app directory name or the name of an executable nested
178 inside a .app directory and returns the path to the .app directory in
179 <bundle_var> and the path to its main executable in <executable_var>.
180 get_bundle_all_executables(<bundle> <exes_var>)
182 Scans <bundle> bundle recursively for all <exes_var> executable files
184 and accumulates them into a variable.
185 get_item_key(<item> <key_var>)
187 Given <item> file name, generate <key_var> key that should be unique
189 considering the set of libraries that need copying or fixing up to make
190 a bundle standalone. This is essentially the file name including
191 extension with . replaced by _
192 This key is used as a prefix for CMake variables so that we can asso‐
194 ciate a set of variables with a given item based on its key.
195 clear_bundle_keys(<keys_var>)
197 Loop over the <keys_var> list of keys, clearing all the variables asso‐
199 ciated with each key. After the loop, clear the list of keys itself.
200 Caller of get_bundle_keys should call clear_bundle_keys when done with
202 list of keys.
203 set_bundle_key_values(<keys_var> <context> <item> <exepath> <dirs>
205 <copyflag> [<rpaths>])
206 Add <keys_var> key to the list (if necessary) for the given item. If
208 added, also set all the variables associated with that key.
209 get_bundle_keys(<app> <libs> <dirs> <keys_var>)
211 Loop over all the executable and library files within <app> bundle (and
213 given as extra <libs>) and accumulate a list of keys representing them.
214 Set values associated with each key such that we can loop over all of
215 them and copy prerequisite libs into the bundle and then do appropriate
216 install_name_tool fixups.
217 As an optional parameter (IGNORE_ITEM) a list of file names can be
219 passed, which are then ignored (e.g. IGNORE_ITEM "vcre‐
220 dist_x86.exe;vcredist_x64.exe")
221 copy_resolved_item_into_bundle(<resolved_item> <resolved_embedded_item>)
223 Copy a resolved item into the bundle if necessary. Copy is not neces‐
225 sary, if the <resolved_item> is “the same as” the <resolved_embed‐
226 ded_item>.
227 copy_resolved_framework_into_bundle(<resolved_item> <resolved_embedded_item>)
229 Copy a resolved framework into the bundle if necessary. Copy is not
231 necessary, if the <resolved_item> is “the same as” the <resolved_embed‐
232 ded_item>.
233 By default, BU_COPY_FULL_FRAMEWORK_CONTENTS is not set. If you want
235 full frameworks embedded in your bundles, set BU_COPY_FULL_FRAME‐
236 WORK_CONTENTS to ON before calling fixup_bundle. By default,
237 COPY_RESOLVED_FRAMEWORK_INTO_BUNDLE copies the framework dylib itself
238 plus the framework Resources directory.
239 fixup_bundle_item(<resolved_embedded_item> <exepath> <dirs>)
241 Get the direct/non-system prerequisites of the <resolved_embed‐
243 ded_item>. For each prerequisite, change the way it is referenced to
244 the value of the _EMBEDDED_ITEM keyed variable for that prerequisite.
245 (Most likely changing to an @executable_path style reference.)
246 This function requires that the <resolved_embedded_item> be inside the
248 bundle already. In other words, if you pass plugins to fixup_bundle as
249 the libs parameter, you should install them or copy them into the bun‐
250 dle before calling fixup_bundle. The libs parameter is a list of
251 libraries that must be fixed up, but that cannot be determined by otool
252 output analysis. (i.e., plugins)
253 Also, change the id of the item being fixed up to its own _EMBED‐
255 DED_ITEM value.
256 Accumulate changes in a local variable and make one call to
258 install_name_tool at the end of the function with all the changes at
259 once.
260 If the BU_CHMOD_BUNDLE_ITEMS variable is set then bundle items will be
262 marked writable before install_name_tool tries to change them.
263 verify_bundle_prerequisites(<bundle> <result_var> <info_var>)
265 Verifies that the sum of all prerequisites of all files inside the bun‐
267 dle are contained within the bundle or are system libraries, presumed
268 to exist everywhere.
269 As an optional parameter (IGNORE_ITEM) a list of file names can be
271 passed, which are then ignored (e.g. IGNORE_ITEM "vcre‐
272 dist_x86.exe;vcredist_x64.exe")
273 verify_bundle_symlinks(<bundle> <result_var> <info_var>)
275 Verifies that any symlinks found in the <bundle> bundle point to other
277 files that are already also in the bundle… Anything that points to an
278 external file causes this function to fail the verification.
279 CheckCCompilerFlag
281 Check whether the C compiler supports a given flag.
282 check_c_compiler_flag
284 check_c_compiler_flag(<flag> <var>)
286 Check that the <flag> is accepted by the compiler without a
288 diagnostic. Stores the result in an internal cache entry named
289 <var>.
290 This command temporarily sets the CMAKE_REQUIRED_DEFINITIONS variable
292 and calls the check_c_source_compiles macro from the CheckCSourceCom‐
293 piles module. See documentation of that module for a listing of vari‐
294 ables that can otherwise modify the build.
295 A positive result from this check indicates only that the compiler did
297 not issue a diagnostic message when given the flag. Whether the flag
298 has any effect or even a specific one is beyond the scope of this mod‐
299 ule.
300 NOTE:
302 Since the try_compile() command forwards flags from variables like
303 CMAKE_C_FLAGS, unknown flags in such variables may cause a false
304 negative for this check.
305 CheckCSourceCompiles
307 Check if given C source compiles and links into an executable.
308 check_c_source_compiles
310 check_c_source_compiles(<code> <resultVar>
312 [FAIL_REGEX <regex1> [<regex2>...]])
313 Check that the source supplied in <code> can be compiled as a C
315 source file and linked as an executable (so it must contain at
316 least a main() function). The result will be stored in the
317 internal cache variable specified by <resultVar>, with a boolean
318 true value for success and boolean false for failure. If
319 FAIL_REGEX is provided, then failure is determined by checking
320 if anything in the output matches any of the specified regular
321 expressions.
322 The underlying check is performed by the try_compile() command.
324 The compile and link commands can be influenced by setting any
325 of the following variables prior to calling check_c_source_com‐
326 piles():
327 CMAKE_REQUIRED_FLAGS
329 Additional flags to pass to the compiler. Note that the
330 contents of CMAKE_C_FLAGS and its associated configura‐
331 tion-specific variable are automatically added to the
332 compiler command before the contents of
333 CMAKE_REQUIRED_FLAGS.
334 CMAKE_REQUIRED_DEFINITIONS
336 A ;-list of compiler definitions of the form -DFOO or
337 -DFOO=bar. A definition for the name specified by
338 <resultVar> will also be added automatically.
339 CMAKE_REQUIRED_INCLUDES
341 A ;-list of header search paths to pass to the compiler.
342 These will be the only header search paths used by
343 try_compile(), i.e. the contents of the INCLUDE_DIRECTO‐
344 RIES directory property will be ignored.
345 CMAKE_REQUIRED_LINK_OPTIONS
347 A ;-list of options to add to the link command (see
348 try_compile() for further details).
349 CMAKE_REQUIRED_LIBRARIES
351 A ;-list of libraries to add to the link command. These
352 can be the name of system libraries or they can be
353 Imported Targets (see try_compile() for further details).
354 CMAKE_REQUIRED_QUIET
356 If this variable evaluates to a boolean true value, all
357 status messages associated with the check will be sup‐
358 pressed.
359 The check is only performed once, with the result cached in the
361 variable named by <resultVar>. Every subsequent CMake run will
362 re-use this cached value rather than performing the check again,
363 even if the <code> changes. In order to force the check to be
364 re-evaluated, the variable named by <resultVar> must be manually
365 removed from the cache.
366 CheckCSourceRuns
368 Check if given C source compiles and links into an executable and can
369 subsequently be run.
370 check_c_source_runs
372 check_c_source_runs(<code> <resultVar>)
374 Check that the source supplied in <code> can be compiled as a C
376 source file, linked as an executable and then run. The <code>
377 must contain at least a main() function. If the <code> could be
378 built and run successfully, the internal cache variable speci‐
379 fied by <resultVar> will be set to 1, otherwise it will be set
380 to an value that evaluates to boolean false (e.g. an empty
381 string or an error message).
382 The underlying check is performed by the try_run() command. The
384 compile and link commands can be influenced by setting any of
385 the following variables prior to calling check_c_source_runs():
386 CMAKE_REQUIRED_FLAGS
388 Additional flags to pass to the compiler. Note that the
389 contents of CMAKE_C_FLAGS and its associated configura‐
390 tion-specific variable are automatically added to the
391 compiler command before the contents of
392 CMAKE_REQUIRED_FLAGS.
393 CMAKE_REQUIRED_DEFINITIONS
395 A ;-list of compiler definitions of the form -DFOO or
396 -DFOO=bar. A definition for the name specified by
397 <resultVar> will also be added automatically.
398 CMAKE_REQUIRED_INCLUDES
400 A ;-list of header search paths to pass to the compiler.
401 These will be the only header search paths used by
402 try_run(), i.e. the contents of the INCLUDE_DIRECTORIES
403 directory property will be ignored.
404 CMAKE_REQUIRED_LINK_OPTIONS
406 A ;-list of options to add to the link command (see
407 try_run() for further details).
408 CMAKE_REQUIRED_LIBRARIES
410 A ;-list of libraries to add to the link command. These
411 can be the name of system libraries or they can be
412 Imported Targets (see try_run() for further details).
413 CMAKE_REQUIRED_QUIET
415 If this variable evaluates to a boolean true value, all
416 status messages associated with the check will be sup‐
417 pressed.
418 The check is only performed once, with the result cached in the
420 variable named by <resultVar>. Every subsequent CMake run will
421 re-use this cached value rather than performing the check again,
422 even if the <code> changes. In order to force the check to be
423 re-evaluated, the variable named by <resultVar> must be manually
424 removed from the cache.
425 CheckCXXCompilerFlag
427 Check whether the CXX compiler supports a given flag.
428 check_cxx_compiler_flag
430 check_cxx_compiler_flag(<flag> <var>)
432 Check that the <flag> is accepted by the compiler without a
434 diagnostic. Stores the result in an internal cache entry named
435 <var>.
436 This command temporarily sets the CMAKE_REQUIRED_DEFINITIONS variable
438 and calls the check_cxx_source_compiles macro from the CheckCXXSource‐
439 Compiles module. See documentation of that module for a listing of
440 variables that can otherwise modify the build.
441 A positive result from this check indicates only that the compiler did
443 not issue a diagnostic message when given the flag. Whether the flag
444 has any effect or even a specific one is beyond the scope of this mod‐
445 ule.
446 NOTE:
448 Since the try_compile() command forwards flags from variables like
449 CMAKE_CXX_FLAGS, unknown flags in such variables may cause a false
450 negative for this check.
451 CheckCXXSourceCompiles
453 Check if given C++ source compiles and links into an executable.
454 check_cxx_source_compiles
456 check_cxx_source_compiles(<code> <resultVar>
458 [FAIL_REGEX <regex1> [<regex2>...]])
459 Check that the source supplied in <code> can be compiled as a
461 C++ source file and linked as an executable (so it must contain
462 at least a main() function). The result will be stored in the
463 internal cache variable specified by <resultVar>, with a boolean
464 true value for success and boolean false for failure. If
465 FAIL_REGEX is provided, then failure is determined by checking
466 if anything in the output matches any of the specified regular
467 expressions.
468 The underlying check is performed by the try_compile() command.
470 The compile and link commands can be influenced by setting any
471 of the following variables prior to calling
472 check_cxx_source_compiles():
473 CMAKE_REQUIRED_FLAGS
475 Additional flags to pass to the compiler. Note that the
476 contents of CMAKE_CXX_FLAGS and its associated configura‐
477 tion-specific variable are automatically added to the
478 compiler command before the contents of
479 CMAKE_REQUIRED_FLAGS.
480 CMAKE_REQUIRED_DEFINITIONS
482 A ;-list of compiler definitions of the form -DFOO or
483 -DFOO=bar. A definition for the name specified by
484 <resultVar> will also be added automatically.
485 CMAKE_REQUIRED_INCLUDES
487 A ;-list of header search paths to pass to the compiler.
488 These will be the only header search paths used by
489 try_compile(), i.e. the contents of the INCLUDE_DIRECTO‐
490 RIES directory property will be ignored.
491 CMAKE_REQUIRED_LINK_OPTIONS
493 A ;-list of options to add to the link command (see
494 try_compile() for further details).
495 CMAKE_REQUIRED_LIBRARIES
497 A ;-list of libraries to add to the link command. These
498 can be the name of system libraries or they can be
499 Imported Targets (see try_compile() for further details).
500 CMAKE_REQUIRED_QUIET
502 If this variable evaluates to a boolean true value, all
503 status messages associated with the check will be sup‐
504 pressed.
505 The check is only performed once, with the result cached in the
507 variable named by <resultVar>. Every subsequent CMake run will
508 re-use this cached value rather than performing the check again,
509 even if the <code> changes. In order to force the check to be
510 re-evaluated, the variable named by <resultVar> must be manually
511 removed from the cache.
512 CheckCXXSourceRuns
514 Check if given C++ source compiles and links into an executable and can
515 subsequently be run.
516 check_cxx_source_runs
518 check_cxx_source_runs(<code> <resultVar>)
520 Check that the source supplied in <code> can be compiled as a
522 C++ source file, linked as an executable and then run. The
523 <code> must contain at least a main() function. If the <code>
524 could be built and run successfully, the internal cache variable
525 specified by <resultVar> will be set to 1, otherwise it will be
526 set to an value that evaluates to boolean false (e.g. an empty
527 string or an error message).
528 The underlying check is performed by the try_run() command. The
530 compile and link commands can be influenced by setting any of
531 the following variables prior to calling
532 check_cxx_source_runs():
533 CMAKE_REQUIRED_FLAGS
535 Additional flags to pass to the compiler. Note that the
536 contents of CMAKE_CXX_FLAGS and its associated configura‐
537 tion-specific variable are automatically added to the
538 compiler command before the contents of
539 CMAKE_REQUIRED_FLAGS.
540 CMAKE_REQUIRED_DEFINITIONS
542 A ;-list of compiler definitions of the form -DFOO or
543 -DFOO=bar. A definition for the name specified by
544 <resultVar> will also be added automatically.
545 CMAKE_REQUIRED_INCLUDES
547 A ;-list of header search paths to pass to the compiler.
548 These will be the only header search paths used by
549 try_run(), i.e. the contents of the INCLUDE_DIRECTORIES
550 directory property will be ignored.
551 CMAKE_REQUIRED_LINK_OPTIONS
553 A ;-list of options to add to the link command (see
554 try_run() for further details).
555 CMAKE_REQUIRED_LIBRARIES
557 A ;-list of libraries to add to the link command. These
558 can be the name of system libraries or they can be
559 Imported Targets (see try_run() for further details).
560 CMAKE_REQUIRED_QUIET
562 If this variable evaluates to a boolean true value, all
563 status messages associated with the check will be sup‐
564 pressed.
565 The check is only performed once, with the result cached in the
567 variable named by <resultVar>. Every subsequent CMake run will
568 re-use this cached value rather than performing the check again,
569 even if the <code> changes. In order to force the check to be
570 re-evaluated, the variable named by <resultVar> must be manually
571 removed from the cache.
572 CheckCXXSymbolExists
574 Check if a symbol exists as a function, variable, or macro in C++.
575 check_cxx_symbol_exists
577 check_cxx_symbol_exists(<symbol> <files> <variable>)
579 Check that the <symbol> is available after including given
581 header <files> and store the result in a <variable>. Specify
582 the list of files in one argument as a semicolon-separated list.
583 check_cxx_symbol_exists() can be used to check for symbols as
584 seen by the C++ compiler, as opposed to check_symbol_exists(),
585 which always uses the C compiler.
586 If the header files define the symbol as a macro it is consid‐
588 ered available and assumed to work. If the header files declare
589 the symbol as a function or variable then the symbol must also
590 be available for linking. If the symbol is a type, enum value,
591 or C++ template it will not be recognized: consider using the
592 CheckTypeSize or CheckCXXSourceCompiles module instead.
593 NOTE:
595 This command is unreliable when <symbol> is (potentially) an over‐
596 loaded function. Since there is no reliable way to predict whether a
597 given function in the system environment may be defined as an over‐
598 loaded function or may be an overloaded function on other systems or
599 will become so in the future, it is generally advised to use the
600 CheckCXXSourceCompiles module for checking any function symbol
601 (unless somehow you surely know the checked function is not over‐
602 loaded on other systems or will not be so in the future).
603 The following variables may be set before calling this macro to modify
605 the way the check is run:
606 CMAKE_REQUIRED_FLAGS
608 string of compile command line flags.
609 CMAKE_REQUIRED_DEFINITIONS
611 a ;-list of macros to define (-DFOO=bar).
612 CMAKE_REQUIRED_INCLUDES
614 a ;-list of header search paths to pass to the compiler.
615 CMAKE_REQUIRED_LINK_OPTIONS
617 a ;-list of options to add to the link command.
618 CMAKE_REQUIRED_LIBRARIES
620 a ;-list of libraries to add to the link command. See policy
621 CMP0075.
622 CMAKE_REQUIRED_QUIET
624 execute quietly without messages.
625 For example:
627 include(CheckCXXSymbolExists)
629 # Check for macro SEEK_SET
631 check_cxx_symbol_exists(SEEK_SET "cstdio" HAVE_SEEK_SET)
632 # Check for function std::fopen
633 check_cxx_symbol_exists(std::fopen "cstdio" HAVE_STD_FOPEN)
634 CheckFortranCompilerFlag
636 Check whether the Fortran compiler supports a given flag.
637 check_fortran_compiler_flag
639 check_fortran_compiler_flag(<flag> <var>)
641 Check that the <flag> is accepted by the compiler without a
643 diagnostic. Stores the result in an internal cache entry named
644 <var>.
645 This command temporarily sets the CMAKE_REQUIRED_DEFINITIONS variable
647 and calls the check_fortran_source_compiles macro from the CheckFor‐
648 tranSourceCompiles module. See documentation of that module for a
649 listing of variables that can otherwise modify the build.
650 A positive result from this check indicates only that the compiler did
652 not issue a diagnostic message when given the flag. Whether the flag
653 has any effect or even a specific one is beyond the scope of this mod‐
654 ule.
655 NOTE:
657 Since the try_compile() command forwards flags from variables like
658 CMAKE_Fortran_FLAGS, unknown flags in such variables may cause a
659 false negative for this check.
660 CheckFortranFunctionExists
662 Check if a Fortran function exists.
663 CHECK_FORTRAN_FUNCTION_EXISTS
665 CHECK_FORTRAN_FUNCTION_EXISTS(<function> <result>)
667 where
669 <function>
671 the name of the Fortran function
672 <result>
674 variable to store the result; will be created as an
675 internal cache variable.
676 The following variables may be set before calling this macro to modify
678 the way the check is run:
679 CMAKE_REQUIRED_LINK_OPTIONS
681 A ;-list of options to add to the link command (see try_com‐
682 pile() for further details).
683 CMAKE_REQUIRED_LIBRARIES
685 A ;-list of libraries to add to the link command. These can be
686 the name of system libraries or they can be Imported Targets
687 (see try_compile() for further details).
688 CheckFortranSourceCompiles
690 Check if given Fortran source compiles and links into an executable.
691 check_fortran_source_compiles
693 check_fortran_source_compiles(<code> <resultVar>
695 [FAIL_REGEX <regex>...]
696 [SRC_EXT <extension>]
697 )
698 Checks that the source supplied in <code> can be compiled as a
700 Fortran source file and linked as an executable. The <code> must
701 be a Fortran program containing at least an end statement–for
702 example:
703 check_fortran_source_compiles("character :: b; error stop b; end" F2018ESTOPOK SRC_EXT F90)
705 This command can help avoid costly build processes when a com‐
707 piler lacks support for a necessary feature, or a particular
708 vendor library is not compatible with the Fortran compiler ver‐
709 sion being used. This generate-time check may advise the user of
710 such before the main build process. See also the check_for‐
711 tran_source_runs() command to actually run the compiled code.
712 The result will be stored in the internal cache variable
714 <resultVar>, with a boolean true value for success and boolean
715 false for failure.
716 If FAIL_REGEX is provided, then failure is determined by check‐
718 ing if anything in the output matches any of the specified regu‐
719 lar expressions.
720 By default, the test source file will be given a .F file exten‐
722 sion. The SRC_EXT option can be used to override this with
723 .<extension> instead– .F90 is a typical choice.
724 The underlying check is performed by the try_compile() command.
726 The compile and link commands can be influenced by setting any
727 of the following variables prior to calling check_for‐
728 tran_source_compiles():
729 CMAKE_REQUIRED_FLAGS
731 Additional flags to pass to the compiler. Note that the
732 contents of CMAKE_Fortran_FLAGS and its associated con‐
733 figuration-specific variable are automatically added to
734 the compiler command before the contents of
735 CMAKE_REQUIRED_FLAGS.
736 CMAKE_REQUIRED_DEFINITIONS
738 A ;-list of compiler definitions of the form -DFOO or
739 -DFOO=bar. A definition for the name specified by
740 <resultVar> will also be added automatically.
741 CMAKE_REQUIRED_INCLUDES
743 A ;-list of header search paths to pass to the compiler.
744 These will be the only header search paths used by
745 try_compile(), i.e. the contents of the INCLUDE_DIRECTO‐
746 RIES directory property will be ignored.
747 CMAKE_REQUIRED_LINK_OPTIONS
749 A ;-list of options to add to the link command (see
750 try_compile() for further details).
751 CMAKE_REQUIRED_LIBRARIES
753 A ;-list of libraries to add to the link command. These
754 can be the name of system libraries or they can be
755 Imported Targets (see try_compile() for further details).
756 CMAKE_REQUIRED_QUIET
758 If this variable evaluates to a boolean true value, all
759 status messages associated with the check will be sup‐
760 pressed.
761 The check is only performed once, with the result cached in the
763 variable named by <resultVar>. Every subsequent CMake run will
764 re-use this cached value rather than performing the check again,
765 even if the <code> changes. In order to force the check to be
766 re-evaluated, the variable named by <resultVar> must be manually
767 removed from the cache.
768 CheckFortranSourceRuns
770 Check if given Fortran source compiles and links into an executable and
771 can subsequently be run.
772 check_fortran_source_runs
774 check_fortran_source_runs(<code> <resultVar>
776 [SRC_EXT <extension>])
777 Check that the source supplied in <code> can be compiled as a
779 Fortran source file, linked as an executable and then run. The
780 <code> must be a Fortran program containing at least an end
781 statement–for example:
782 check_fortran_source_runs("real :: x[*]; call co_sum(x); end" F2018coarrayOK)
784 This command can help avoid costly build processes when a com‐
786 piler lacks support for a necessary feature, or a particular
787 vendor library is not compatible with the Fortran compiler ver‐
788 sion being used. Some of these failures only occur at runtime
789 instead of linktime, and a trivial runtime example can catch the
790 issue before the main build process.
791 If the <code> could be built and run successfully, the internal
793 cache variable specified by <resultVar> will be set to 1, other‐
794 wise it will be set to an value that evaluates to boolean false
795 (e.g. an empty string or an error message).
796 By default, the test source file will be given a .F90 file
798 extension. The SRC_EXT option can be used to override this with
799 .<extension> instead.
800 The underlying check is performed by the try_run() command. The
802 compile and link commands can be influenced by setting any of
803 the following variables prior to calling check_for‐
804 tran_source_runs():
805 CMAKE_REQUIRED_FLAGS
807 Additional flags to pass to the compiler. Note that the
808 contents of CMAKE_Fortran_FLAGS and its associated con‐
809 figuration-specific variable are automatically added to
810 the compiler command before the contents of
811 CMAKE_REQUIRED_FLAGS.
812 CMAKE_REQUIRED_DEFINITIONS
814 A ;-list of compiler definitions of the form -DFOO or
815 -DFOO=bar. A definition for the name specified by
816 <resultVar> will also be added automatically.
817 CMAKE_REQUIRED_INCLUDES
819 A ;-list of header search paths to pass to the compiler.
820 These will be the only header search paths used by
821 try_run(), i.e. the contents of the INCLUDE_DIRECTORIES
822 directory property will be ignored.
823 CMAKE_REQUIRED_LINK_OPTIONS
825 A ;-list of options to add to the link command (see
826 try_run() for further details).
827 CMAKE_REQUIRED_LIBRARIES
829 A ;-list of libraries to add to the link command. These
830 can be the name of system libraries or they can be
831 Imported Targets (see try_run() for further details).
832 CMAKE_REQUIRED_QUIET
834 If this variable evaluates to a boolean true value, all
835 status messages associated with the check will be sup‐
836 pressed.
837 The check is only performed once, with the result cached in the
839 variable named by <resultVar>. Every subsequent CMake run will
840 re-use this cached value rather than performing the check again,
841 even if the <code> changes. In order to force the check to be
842 re-evaluated, the variable named by <resultVar> must be manually
843 removed from the cache.
844 CheckFunctionExists
846 Check if a C function can be linked
847 check_function_exists
849 check_function_exists(<function> <variable>)
851 Checks that the <function> is provided by libraries on the sys‐
853 tem and store the result in a <variable>, which will be created
854 as an internal cache variable.
855 The following variables may be set before calling this macro to modify
857 the way the check is run:
858 CMAKE_REQUIRED_FLAGS
860 string of compile command line flags.
861 CMAKE_REQUIRED_DEFINITIONS
863 a ;-list of macros to define (-DFOO=bar).
864 CMAKE_REQUIRED_INCLUDES
866 a ;-list of header search paths to pass to the compiler.
867 CMAKE_REQUIRED_LINK_OPTIONS
869 a ;-list of options to add to the link command.
870 CMAKE_REQUIRED_LIBRARIES
872 a ;-list of libraries to add to the link command. See policy
873 CMP0075.
874 CMAKE_REQUIRED_QUIET
876 execute quietly without messages.
877 NOTE:
879 Prefer using CheckSymbolExists instead of this module, for the fol‐
880 lowing reasons:
881 · check_function_exists() can’t detect functions that are inlined in
883 headers or specified as a macro.
884 · check_function_exists() can’t detect anything in the 32-bit ver‐
886 sions of the Win32 API, because of a mismatch in calling conven‐
887 tions.
888 · check_function_exists() only verifies linking, it does not verify
890 that the function is declared in system headers.
891 CheckIPOSupported
893 Check whether the compiler supports an interprocedural optimization
894 (IPO/LTO). Use this before enabling the INTERPROCEDURAL_OPTIMIZATION
895 target property.
896 check_ipo_supported
898 check_ipo_supported([RESULT <result>] [OUTPUT <output>]
900 [LANGUAGES <lang>...])
901 Options are:
903 RESULT <result>
905 Set <result> variable to YES if IPO is supported by the
906 compiler and NO otherwise. If this option is not given
907 then the command will issue a fatal error if IPO is not
908 supported.
909 OUTPUT <output>
911 Set <output> variable with details about any error.
912 LANGUAGES <lang>...
914 Specify languages whose compilers to check. Languages C,
915 CXX, and Fortran are supported.
916 It makes no sense to use this module when CMP0069 is set to OLD so mod‐
918 ule will return error in this case. See policy CMP0069 for details.
919 Examples
921 check_ipo_supported() # fatal error if IPO is not supported
922 set_property(TARGET foo PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
923 # Optional IPO. Do not use IPO if it's not supported by compiler.
925 check_ipo_supported(RESULT result OUTPUT output)
926 if(result)
927 set_property(TARGET foo PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
928 else()
929 message(WARNING "IPO is not supported: ${output}")
930 endif()
931 CheckIncludeFileCXX
933 Provides a macro to check if a header file can be included in CXX.
934 CHECK_INCLUDE_FILE_CXX
936 CHECK_INCLUDE_FILE_CXX(<include> <variable> [<flags>])
938 Check if the given <include> file may be included in a CXX
940 source file and store the result in an internal cache entry
941 named <variable>. The optional third argument may be used to
942 add compilation flags to the check (or use CMAKE_REQUIRED_FLAGS
943 below).
944 The following variables may be set before calling this macro to modify
946 the way the check is run:
947 CMAKE_REQUIRED_FLAGS
949 string of compile command line flags.
950 CMAKE_REQUIRED_DEFINITIONS
952 a ;-list of macros to define (-DFOO=bar).
953 CMAKE_REQUIRED_INCLUDES
955 a ;-list of header search paths to pass to the compiler.
956 CMAKE_REQUIRED_LINK_OPTIONS
958 a ;-list of options to add to the link command.
959 CMAKE_REQUIRED_LIBRARIES
961 a ;-list of libraries to add to the link command. See policy
962 CMP0075.
963 CMAKE_REQUIRED_QUIET
965 execute quietly without messages.
966 See modules CheckIncludeFile and CheckIncludeFiles to check for one or
968 more C headers.
969 CheckIncludeFile
971 Provides a macro to check if a header file can be included in C.
972 CHECK_INCLUDE_FILE
974 CHECK_INCLUDE_FILE(<include> <variable> [<flags>])
976 Check if the given <include> file may be included in a C source
978 file and store the result in an internal cache entry named
979 <variable>. The optional third argument may be used to add com‐
980 pilation flags to the check (or use CMAKE_REQUIRED_FLAGS below).
981 The following variables may be set before calling this macro to modify
983 the way the check is run:
984 CMAKE_REQUIRED_FLAGS
986 string of compile command line flags.
987 CMAKE_REQUIRED_DEFINITIONS
989 a ;-list of macros to define (-DFOO=bar).
990 CMAKE_REQUIRED_INCLUDES
992 a ;-list of header search paths to pass to the compiler.
993 CMAKE_REQUIRED_LINK_OPTIONS
995 a ;-list of options to add to the link command.
996 CMAKE_REQUIRED_LIBRARIES
998 a ;-list of libraries to add to the link command. See policy
999 CMP0075.
1000 CMAKE_REQUIRED_QUIET
1002 execute quietly without messages.
1003 See the CheckIncludeFiles module to check for multiple headers at once.
1005 See the CheckIncludeFileCXX module to check for headers using the CXX
1006 language.
1007 CheckIncludeFiles
1009 Provides a macro to check if a list of one or more header files can be
1010 included together.
1011 CHECK_INCLUDE_FILES
1013 CHECK_INCLUDE_FILES("<includes>" <variable> [LANGUAGE <language>])
1015 Check if the given <includes> list may be included together in a
1017 source file and store the result in an internal cache entry
1018 named <variable>. Specify the <includes> argument as a ;-list
1019 of header file names.
1020 If LANGUAGE is set, the specified compiler will be used to per‐
1022 form the check. Acceptable values are C and CXX. If not set, the
1023 C compiler will be used if enabled. If the C compiler is not
1024 enabled, the C++ compiler will be used if enabled.
1025 The following variables may be set before calling this macro to modify
1027 the way the check is run:
1028 CMAKE_REQUIRED_FLAGS
1030 string of compile command line flags.
1031 CMAKE_REQUIRED_DEFINITIONS
1033 a ;-list of macros to define (-DFOO=bar).
1034 CMAKE_REQUIRED_INCLUDES
1036 a ;-list of header search paths to pass to the compiler.
1037 CMAKE_REQUIRED_LINK_OPTIONS
1039 a ;-list of options to add to the link command.
1040 CMAKE_REQUIRED_LIBRARIES
1042 a ;-list of libraries to add to the link command. See policy
1043 CMP0075.
1044 CMAKE_REQUIRED_QUIET
1046 execute quietly without messages.
1047 See modules CheckIncludeFile and CheckIncludeFileCXX to check for a
1049 single header file in C or CXX languages.
1050 CheckLanguage
1052 Check if a language can be enabled
1053 Usage:
1055 check_language(<lang>)
1057 where <lang> is a language that may be passed to enable_language() such
1059 as Fortran. If CMAKE_<LANG>_COMPILER is already defined the check does
1060 nothing. Otherwise it tries enabling the language in a test project.
1061 The result is cached in CMAKE_<LANG>_COMPILER as the compiler that was
1062 found, or NOTFOUND if the language cannot be enabled. For CUDA which
1063 can have an explicit host compiler, the cache CMAKE_CUDA_HOST_COMPILER
1064 variable will be set if it was required for compilation.
1065 Example:
1067 check_language(Fortran)
1069 if(CMAKE_Fortran_COMPILER)
1070 enable_language(Fortran)
1071 else()
1072 message(STATUS "No Fortran support")
1073 endif()
1074 CheckLibraryExists
1076 Check if the function exists.
1077 CHECK_LIBRARY_EXISTS
1079 CHECK_LIBRARY_EXISTS(LIBRARY FUNCTION LOCATION VARIABLE)
1081 LIBRARY - the name of the library you are looking for
1083 FUNCTION - the name of the function
1084 LOCATION - location where the library should be found
1085 VARIABLE - variable to store the result
1086 Will be created as an internal cache variable.
1087 The following variables may be set before calling this macro to modify
1089 the way the check is run:
1090 CMAKE_REQUIRED_FLAGS = string of compile command line flags
1092 CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
1093 CMAKE_REQUIRED_LINK_OPTIONS = list of options to pass to link command
1094 CMAKE_REQUIRED_LIBRARIES = list of libraries to link
1095 CMAKE_REQUIRED_QUIET = execute quietly without messages
1096 CheckOBJCCompilerFlag
1098 Check whether the Objective-C compiler supports a given flag.
1099 check_objc_compiler_flag
1101 check_objc_compiler_flag(<flag> <var>)
1103 Check that the <flag> is accepted by the compiler without a
1105 diagnostic. Stores the result in an internal cache entry named
1106 <var>.
1107 This command temporarily sets the CMAKE_REQUIRED_DEFINITIONS variable
1109 and calls the check_objc_source_compiles macro from the CheckOBJC‐
1110 SourceCompiles module. See documentation of that module for a listing
1111 of variables that can otherwise modify the build.
1112 A positive result from this check indicates only that the compiler did
1114 not issue a diagnostic message when given the flag. Whether the flag
1115 has any effect or even a specific one is beyond the scope of this mod‐
1116 ule.
1117 NOTE:
1119 Since the try_compile() command forwards flags from variables like
1120 CMAKE_OBJC_FLAGS, unknown flags in such variables may cause a false
1121 negative for this check.
1122 CheckOBJCSourceCompiles
1124 Check if given Objective-C source compiles and links into an exe‐
1125 cutable.
1126 check_objc_source_compiles
1128 check_objc_source_compiles(<code> <resultVar>
1130 [FAIL_REGEX <regex1> [<regex2>...]])
1131 Check that the source supplied in <code> can be compiled as a
1133 Objectie-C source file and linked as an executable (so it must
1134 contain at least a main() function). The result will be stored
1135 in the internal cache variable specified by <resultVar>, with a
1136 boolean true value for success and boolean false for failure. If
1137 FAIL_REGEX is provided, then failure is determined by checking
1138 if anything in the output matches any of the specified regular
1139 expressions.
1140 The underlying check is performed by the try_compile() command.
1142 The compile and link commands can be influenced by setting any
1143 of the following variables prior to calling
1144 check_objc_source_compiles():
1145 CMAKE_REQUIRED_FLAGS
1147 Additional flags to pass to the compiler. Note that the
1148 contents of CMAKE_OBJC_FLAGS and its associated configu‐
1149 ration-specific variable are automatically added to the
1150 compiler command before the contents of
1151 CMAKE_REQUIRED_FLAGS.
1152 CMAKE_REQUIRED_DEFINITIONS
1154 A ;-list of compiler definitions of the form -DFOO or
1155 -DFOO=bar. A definition for the name specified by
1156 <resultVar> will also be added automatically.
1157 CMAKE_REQUIRED_INCLUDES
1159 A ;-list of header search paths to pass to the compiler.
1160 These will be the only header search paths used by
1161 try_compile(), i.e. the contents of the INCLUDE_DIRECTO‐
1162 RIES directory property will be ignored.
1163 CMAKE_REQUIRED_LINK_OPTIONS
1165 A ;-list of options to add to the link command (see
1166 try_compile() for further details).
1167 CMAKE_REQUIRED_LIBRARIES
1169 A ;-list of libraries to add to the link command. These
1170 can be the name of system libraries or they can be
1171 Imported Targets (see try_compile() for further details).
1172 CMAKE_REQUIRED_QUIET
1174 If this variable evaluates to a boolean true value, all
1175 status messages associated with the check will be sup‐
1176 pressed.
1177 The check is only performed once, with the result cached in the
1179 variable named by <resultVar>. Every subsequent CMake run will
1180 re-use this cached value rather than performing the check again,
1181 even if the <code> changes. In order to force the check to be
1182 re-evaluated, the variable named by <resultVar> must be manually
1183 removed from the cache.
1184 CheckOBJCSourceRuns
1186 Check if given Objective-C source compiles and links into an executable
1187 and can subsequently be run.
1188 check_objc_source_runs
1190 check_objc_source_runs(<code> <resultVar>)
1192 Check that the source supplied in <code> can be compiled as a
1194 Objective-C source file, linked as an executable and then run.
1195 The <code> must contain at least a main() function. If the
1196 <code> could be built and run successfully, the internal cache
1197 variable specified by <resultVar> will be set to 1, otherwise it
1198 will be set to an value that evaluates to boolean false (e.g. an
1199 empty string or an error message).
1200 The underlying check is performed by the try_run() command. The
1202 compile and link commands can be influenced by setting any of
1203 the following variables prior to calling
1204 check_objc_source_runs():
1205 CMAKE_REQUIRED_FLAGS
1207 Additional flags to pass to the compiler. Note that the
1208 contents of CMAKE_OBJC_FLAGS and its associated configu‐
1209 ration-specific variable are automatically added to the
1210 compiler command before the contents of
1211 CMAKE_REQUIRED_FLAGS.
1212 CMAKE_REQUIRED_DEFINITIONS
1214 A ;-list of compiler definitions of the form -DFOO or
1215 -DFOO=bar. A definition for the name specified by
1216 <resultVar> will also be added automatically.
1217 CMAKE_REQUIRED_INCLUDES
1219 A ;-list of header search paths to pass to the compiler.
1220 These will be the only header search paths used by
1221 try_run(), i.e. the contents of the INCLUDE_DIRECTORIES
1222 directory property will be ignored.
1223 CMAKE_REQUIRED_LINK_OPTIONS
1225 A ;-list of options to add to the link command (see
1226 try_run() for further details).
1227 CMAKE_REQUIRED_LIBRARIES
1229 A ;-list of libraries to add to the link command. These
1230 can be the name of system libraries or they can be
1231 Imported Targets (see try_run() for further details).
1232 CMAKE_REQUIRED_QUIET
1234 If this variable evaluates to a boolean true value, all
1235 status messages associated with the check will be sup‐
1236 pressed.
1237 The check is only performed once, with the result cached in the
1239 variable named by <resultVar>. Every subsequent CMake run will
1240 re-use this cached value rather than performing the check again,
1241 even if the <code> changes. In order to force the check to be
1242 re-evaluated, the variable named by <resultVar> must be manually
1243 removed from the cache.
1244 CheckOBJCXXCompilerFlag
1246 Check whether the Objective-C++ compiler supports a given flag.
1247 check_objcxx_compiler_flag
1249 check_objcxx_compiler_flag(<flag> <var>)
1251 Check that the <flag> is accepted by the compiler without a
1253 diagnostic. Stores the result in an internal cache entry named
1254 <var>.
1255 This command temporarily sets the CMAKE_REQUIRED_DEFINITIONS variable
1257 and calls the check_objcxx_source_compiles macro from the CheckOB‐
1258 JCXXSourceCompiles module. See documentation of that module for a
1259 listing of variables that can otherwise modify the build.
1260 A positive result from this check indicates only that the compiler did
1262 not issue a diagnostic message when given the flag. Whether the flag
1263 has any effect or even a specific one is beyond the scope of this mod‐
1264 ule.
1265 NOTE:
1267 Since the try_compile() command forwards flags from variables like
1268 CMAKE_OBJCXX_FLAGS, unknown flags in such variables may cause a
1269 false negative for this check.
1270 CheckOBJCXXSourceCompiles
1272 Check if given Objective-C++ source compiles and links into an exe‐
1273 cutable.
1274 check_objcxx_source_compiles
1276 check_objcxx_source_compiles(<code> <resultVar>
1278 [FAIL_REGEX <regex1> [<regex2>...]])
1279 Check that the source supplied in <code> can be compiled as a
1281 Objective-C++ source file and linked as an executable (so it
1282 must contain at least a main() function). The result will be
1283 stored in the internal cache variable specified by <resultVar>,
1284 with a boolean true value for success and boolean false for
1285 failure. If FAIL_REGEX is provided, then failure is determined
1286 by checking if anything in the output matches any of the speci‐
1287 fied regular expressions.
1288 The underlying check is performed by the try_compile() command.
1290 The compile and link commands can be influenced by setting any
1291 of the following variables prior to calling
1292 check_objcxx_source_compiles():
1293 CMAKE_REQUIRED_FLAGS
1295 Additional flags to pass to the compiler. Note that the
1296 contents of CMAKE_OBJCXX_FLAGS and its associated config‐
1297 uration-specific variable are automatically added to the
1298 compiler command before the contents of
1299 CMAKE_REQUIRED_FLAGS.
1300 CMAKE_REQUIRED_DEFINITIONS
1302 A ;-list of compiler definitions of the form -DFOO or
1303 -DFOO=bar. A definition for the name specified by
1304 <resultVar> will also be added automatically.
1305 CMAKE_REQUIRED_INCLUDES
1307 A ;-list of header search paths to pass to the compiler.
1308 These will be the only header search paths used by
1309 try_compile(), i.e. the contents of the INCLUDE_DIRECTO‐
1310 RIES directory property will be ignored.
1311 CMAKE_REQUIRED_LINK_OPTIONS
1313 A ;-list of options to add to the link command (see
1314 try_compile() for further details).
1315 CMAKE_REQUIRED_LIBRARIES
1317 A ;-list of libraries to add to the link command. These
1318 can be the name of system libraries or they can be
1319 Imported Targets (see try_compile() for further details).
1320 CMAKE_REQUIRED_QUIET
1322 If this variable evaluates to a boolean true value, all
1323 status messages associated with the check will be sup‐
1324 pressed.
1325 The check is only performed once, with the result cached in the
1327 variable named by <resultVar>. Every subsequent CMake run will
1328 re-use this cached value rather than performing the check again,
1329 even if the <code> changes. In order to force the check to be
1330 re-evaluated, the variable named by <resultVar> must be manually
1331 removed from the cache.
1332 CheckOBJCXXSourceRuns
1334 Check if given Objective-C++ source compiles and links into an exe‐
1335 cutable and can subsequently be run.
1336 check_objcxx_source_runs
1338 check_objcxx_source_runs(<code> <resultVar>)
1340 Check that the source supplied in <code> can be compiled as a
1342 Objective-C++ source file, linked as an executable and then run.
1343 The <code> must contain at least a main() function. If the
1344 <code> could be built and run successfully, the internal cache
1345 variable specified by <resultVar> will be set to 1, otherwise it
1346 will be set to an value that evaluates to boolean false (e.g. an
1347 empty string or an error message).
1348 The underlying check is performed by the try_run() command. The
1350 compile and link commands can be influenced by setting any of
1351 the following variables prior to calling
1352 check_objcxx_source_runs():
1353 CMAKE_REQUIRED_FLAGS
1355 Additional flags to pass to the compiler. Note that the
1356 contents of CMAKE_OBJCXX_FLAGS and its associated config‐
1357 uration-specific variable are automatically added to the
1358 compiler command before the contents of
1359 CMAKE_REQUIRED_FLAGS.
1360 CMAKE_REQUIRED_DEFINITIONS
1362 A ;-list of compiler definitions of the form -DFOO or
1363 -DFOO=bar. A definition for the name specified by
1364 <resultVar> will also be added automatically.
1365 CMAKE_REQUIRED_INCLUDES
1367 A ;-list of header search paths to pass to the compiler.
1368 These will be the only header search paths used by
1369 try_run(), i.e. the contents of the INCLUDE_DIRECTORIES
1370 directory property will be ignored.
1371 CMAKE_REQUIRED_LINK_OPTIONS
1373 A ;-list of options to add to the link command (see
1374 try_run() for further details).
1375 CMAKE_REQUIRED_LIBRARIES
1377 A ;-list of libraries to add to the link command. These
1378 can be the name of system libraries or they can be
1379 Imported Targets (see try_run() for further details).
1380 CMAKE_REQUIRED_QUIET
1382 If this variable evaluates to a boolean true value, all
1383 status messages associated with the check will be sup‐
1384 pressed.
1385 The check is only performed once, with the result cached in the
1387 variable named by <resultVar>. Every subsequent CMake run will
1388 re-use this cached value rather than performing the check again,
1389 even if the <code> changes. In order to force the check to be
1390 re-evaluated, the variable named by <resultVar> must be manually
1391 removed from the cache.
1392 CheckPIESupported
1394 Check whether the linker supports Position Independent Code (PIE) or No
1395 Position Independent Code (NO_PIE) for executables. Use this to ensure
1396 that the POSITION_INDEPENDENT_CODE target property for executables will
1397 be honored at link time.
1398 check_pie_supported
1400 check_pie_supported([OUTPUT_VARIABLE <output>]
1402 [LANGUAGES <lang>...])
1403 Options are:
1405 OUTPUT_VARIABLE <output>
1407 Set <output> variable with details about any error.
1408 LANGUAGES <lang>...
1410 Check the linkers used for each of the specified lan‐
1411 guages. Supported languages are C, CXX, and Fortran.
1412 It makes no sense to use this module when CMP0083 is set to OLD, so the
1414 command will return an error in this case. See policy CMP0083 for
1415 details.
1416 Variables
1418 For each language checked, two boolean cache variables are defined.
1419 CMAKE_<lang>_LINK_PIE_SUPPORTED
1421 Set to YES if PIE is supported by the linker and NO other‐
1422 wise.
1423 CMAKE_<lang>_LINK_NO_PIE_SUPPORTED
1425 Set to YES if NO_PIE is supported by the linker and NO other‐
1426 wise.
1427 Examples
1429 check_pie_supported()
1430 set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE)
1431 # Retrieve any error message.
1433 check_pie_supported(OUTPUT_VARIABLE output LANGUAGES C)
1434 set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE)
1435 if(NOT CMAKE_C_LINK_PIE_SUPPORTED)
1436 message(WARNING "PIE is not supported at link time: ${output}.\n"
1437 "PIE link options will not be passed to linker.")
1438 endif()
1439 CheckPrototypeDefinition
1441 Check if the prototype we expect is correct.
1442 check_prototype_definition
1444 check_prototype_definition(FUNCTION PROTOTYPE RETURN HEADER VARIABLE)
1446 FUNCTION - The name of the function (used to check if prototype exists)
1448 PROTOTYPE- The prototype to check.
1449 RETURN - The return value of the function.
1450 HEADER - The header files required.
1451 VARIABLE - The variable to store the result.
1452 Will be created as an internal cache variable.
1453 Example:
1455 check_prototype_definition(getpwent_r
1457 "struct passwd *getpwent_r(struct passwd *src, char *buf, int buflen)"
1458 "NULL"
1459 "unistd.h;pwd.h"
1460 SOLARIS_GETPWENT_R)
1461 The following variables may be set before calling this function to mod‐
1463 ify the way the check is run:
1464 CMAKE_REQUIRED_FLAGS = string of compile command line flags
1466 CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
1467 CMAKE_REQUIRED_INCLUDES = list of include directories
1468 CMAKE_REQUIRED_LINK_OPTIONS = list of options to pass to link command
1469 CMAKE_REQUIRED_LIBRARIES = list of libraries to link
1470 CMAKE_REQUIRED_QUIET = execute quietly without messages
1471 CheckStructHasMember
1473 Check if the given struct or class has the specified member variable
1474 CHECK_STRUCT_HAS_MEMBER
1476 CHECK_STRUCT_HAS_MEMBER(<struct> <member> <header> <variable>
1478 [LANGUAGE <language>])
1479 <struct> - the name of the struct or class you are interested in
1481 <member> - the member which existence you want to check
1482 <header> - the header(s) where the prototype should be declared
1483 <variable> - variable to store the result
1484 <language> - the compiler to use (C or CXX)
1485 The following variables may be set before calling this macro to modify
1487 the way the check is run:
1488 CMAKE_REQUIRED_FLAGS = string of compile command line flags
1490 CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
1491 CMAKE_REQUIRED_INCLUDES = list of include directories
1492 CMAKE_REQUIRED_LINK_OPTIONS = list of options to pass to link command
1493 CMAKE_REQUIRED_LIBRARIES = list of libraries to link
1494 CMAKE_REQUIRED_QUIET = execute quietly without messages
1495 Example:
1497 CHECK_STRUCT_HAS_MEMBER("struct timeval" tv_sec sys/select.h
1499 HAVE_TIMEVAL_TV_SEC LANGUAGE C)
1500 CheckSymbolExists
1502 Provides a macro to check if a symbol exists as a function, variable,
1503 or macro in C.
1504 check_symbol_exists
1506 check_symbol_exists(<symbol> <files> <variable>)
1508 Check that the <symbol> is available after including given
1510 header <files> and store the result in a <variable>. Specify
1511 the list of files in one argument as a semicolon-separated list.
1512 <variable> will be created as an internal cache variable.
1513 If the header files define the symbol as a macro it is considered
1515 available and assumed to work. If the header files declare the symbol
1516 as a function or variable then the symbol must also be available for
1517 linking (so intrinsics may not be detected). If the symbol is a type,
1518 enum value, or intrinsic it will not be recognized (consider using
1519 CheckTypeSize or CheckCSourceCompiles). If the check needs to be done
1520 in C++, consider using CheckCXXSymbolExists instead.
1521 The following variables may be set before calling this macro to modify
1523 the way the check is run:
1524 CMAKE_REQUIRED_FLAGS
1526 string of compile command line flags.
1527 CMAKE_REQUIRED_DEFINITIONS
1529 a ;-list of macros to define (-DFOO=bar).
1530 CMAKE_REQUIRED_INCLUDES
1532 a ;-list of header search paths to pass to the compiler.
1533 CMAKE_REQUIRED_LINK_OPTIONS
1535 a ;-list of options to add to the link command.
1536 CMAKE_REQUIRED_LIBRARIES
1538 a ;-list of libraries to add to the link command. See policy
1539 CMP0075.
1540 CMAKE_REQUIRED_QUIET
1542 execute quietly without messages.
1543 For example:
1545 include(CheckSymbolExists)
1547 # Check for macro SEEK_SET
1549 check_symbol_exists(SEEK_SET "stdio.h" HAVE_SEEK_SET)
1550 # Check for function fopen
1551 check_symbol_exists(fopen "stdio.h" HAVE_FOPEN)
1552 CheckTypeSize
1554 Check sizeof a type
1555 CHECK_TYPE_SIZE
1557 CHECK_TYPE_SIZE(TYPE VARIABLE [BUILTIN_TYPES_ONLY]
1559 [LANGUAGE <language>])
1560 Check if the type exists and determine its size. On return,
1562 HAVE_${VARIABLE} holds the existence of the type, and ${VARI‐
1563 ABLE} holds one of the following:
1564 <size> = type has non-zero size <size>
1566 "0" = type has arch-dependent size (see below)
1567 "" = type does not exist
1568 Both HAVE_${VARIABLE} and ${VARIABLE} will be created as inter‐
1570 nal cache variables.
1571 Furthermore, the variable ${VARIABLE}_CODE holds C preprocessor
1573 code to define the macro ${VARIABLE} to the size of the type, or
1574 leave the macro undefined if the type does not exist.
1575 The variable ${VARIABLE} may be 0 when CMAKE_OSX_ARCHITECTURES
1577 has multiple architectures for building OS X universal binaries.
1578 This indicates that the type size varies across architectures.
1579 In this case ${VARIABLE}_CODE contains C preprocessor tests map‐
1580 ping from each architecture macro to the corresponding type
1581 size. The list of architecture macros is stored in ${VARI‐
1582 ABLE}_KEYS, and the value for each key is stored in ${VARI‐
1583 ABLE}-${KEY}.
1584 If the BUILTIN_TYPES_ONLY option is not given, the macro checks
1586 for headers <sys/types.h>, <stdint.h>, and <stddef.h>, and saves
1587 results in HAVE_SYS_TYPES_H, HAVE_STDINT_H, and HAVE_STDDEF_H.
1588 The type size check automatically includes the available head‐
1589 ers, thus supporting checks of types defined in the headers.
1590 If LANGUAGE is set, the specified compiler will be used to per‐
1592 form the check. Acceptable values are C and CXX.
1593 Despite the name of the macro you may use it to check the size of more
1595 complex expressions, too. To check e.g. for the size of a struct mem‐
1596 ber you can do something like this:
1597 check_type_size("((struct something*)0)->member" SIZEOF_MEMBER)
1599 The following variables may be set before calling this macro to modify
1601 the way the check is run:
1602 CMAKE_REQUIRED_FLAGS = string of compile command line flags
1604 CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
1605 CMAKE_REQUIRED_INCLUDES = list of include directories
1606 CMAKE_REQUIRED_LINK_OPTIONS = list of options to pass to link command
1607 CMAKE_REQUIRED_LIBRARIES = list of libraries to link
1608 CMAKE_REQUIRED_QUIET = execute quietly without messages
1609 CMAKE_EXTRA_INCLUDE_FILES = list of extra headers to include
1610 CheckVariableExists
1612 Check if the variable exists.
1613 CHECK_VARIABLE_EXISTS
1615 CHECK_VARIABLE_EXISTS(VAR VARIABLE)
1617 VAR - the name of the variable
1619 VARIABLE - variable to store the result
1620 Will be created as an internal cache variable.
1621 This macro is only for C variables.
1623 The following variables may be set before calling this macro to modify
1625 the way the check is run:
1626 CMAKE_REQUIRED_FLAGS = string of compile command line flags
1628 CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
1629 CMAKE_REQUIRED_LINK_OPTIONS = list of options to pass to link command
1630 CMAKE_REQUIRED_LIBRARIES = list of libraries to link
1631 CMAKE_REQUIRED_QUIET = execute quietly without messages
1632 CMakeAddFortranSubdirectory
1634 Add a fortran-only subdirectory, find a fortran compiler, and build.
1635 The cmake_add_fortran_subdirectory function adds a subdirectory to a
1637 project that contains a fortran-only subproject. The module will check
1638 the current compiler and see if it can support fortran. If no fortran
1639 compiler is found and the compiler is MSVC, then this module will find
1640 the MinGW gfortran. It will then use an external project to build with
1641 the MinGW tools. It will also create imported targets for the
1642 libraries created. This will only work if the fortran code is built
1643 into a dll, so BUILD_SHARED_LIBS is turned on in the project. In addi‐
1644 tion the CMAKE_GNUtoMS option is set to on, so that Microsoft .lib
1645 files are created. Usage is as follows:
1646 cmake_add_fortran_subdirectory(
1648 <subdir> # name of subdirectory
1649 PROJECT <project_name> # project name in subdir top CMakeLists.txt
1650 ARCHIVE_DIR <dir> # dir where project places .lib files
1651 RUNTIME_DIR <dir> # dir where project places .dll files
1652 LIBRARIES <lib>... # names of library targets to import
1653 LINK_LIBRARIES # link interface libraries for LIBRARIES
1654 [LINK_LIBS <lib> <dep>...]...
1655 CMAKE_COMMAND_LINE ... # extra command line flags to pass to cmake
1656 NO_EXTERNAL_INSTALL # skip installation of external project
1657 )
1658 Relative paths in ARCHIVE_DIR and RUNTIME_DIR are interpreted with
1660 respect to the build directory corresponding to the source directory in
1661 which the function is invoked.
1662 Limitations:
1664 NO_EXTERNAL_INSTALL is required for forward compatibility with a future
1666 version that supports installation of the external project binaries
1667 during make install.
1668 CMakeBackwardCompatibilityCXX
1670 define a bunch of backwards compatibility variables
1671 CMAKE_ANSI_CXXFLAGS - flag for ansi c++
1673 CMAKE_HAS_ANSI_STRING_STREAM - has <strstream>
1674 include(TestForANSIStreamHeaders)
1675 include(CheckIncludeFileCXX)
1676 include(TestForSTDNamespace)
1677 include(TestForANSIForScope)
1678 CMakeDependentOption
1680 Macro to provide an option dependent on other options.
1681 This macro presents an option to the user only if a set of other condi‐
1683 tions are true. When the option is not presented a default value is
1684 used, but any value set by the user is preserved for when the option is
1685 presented again. Example invocation:
1686 CMAKE_DEPENDENT_OPTION(USE_FOO "Use Foo" ON
1688 "USE_BAR;NOT USE_ZOT" OFF)
1689 If USE_BAR is true and USE_ZOT is false, this provides an option called
1691 USE_FOO that defaults to ON. Otherwise, it sets USE_FOO to OFF. If
1692 the status of USE_BAR or USE_ZOT ever changes, any value for the
1693 USE_FOO option is saved so that when the option is re-enabled it
1694 retains its old value. Each element in the fourth parameter is evalu‐
1695 ated as an if-condition, so Condition Syntax can be used.
1696 CMakeFindDependencyMacro
1698 find_dependency
1699 The find_dependency() macro wraps a find_package() call for a
1700 package dependency:
1701 find_dependency(<dep> [...])
1703 It is designed to be used in a Package Configuration File
1705 (<PackageName>Config.cmake). find_dependency forwards the cor‐
1706 rect parameters for QUIET and REQUIRED which were passed to the
1707 original find_package() call. Any additional arguments speci‐
1708 fied are forwarded to find_package().
1709 If the dependency could not be found it sets an informative
1711 diagnostic message and calls return() to end processing of the
1712 calling package configuration file and return to the find_pack‐
1713 age() command that loaded it.
1714 NOTE:
1716 The call to return() makes this macro unsuitable to call from
1717 Find Modules.
1718 CMakeFindFrameworks
1720 helper module to find OSX frameworks
1721 This module reads hints about search locations from variables:
1723 CMAKE_FIND_FRAMEWORK_EXTRA_LOCATIONS - Extra directories
1725 CMakeFindPackageMode
1727 This file is executed by cmake when invoked with –find-package. It
1728 expects that the following variables are set using -D:
1729 NAME name of the package
1731 COMPILER_ID
1733 the CMake compiler ID for which the result is, i.e.
1734 GNU/Intel/Clang/MSVC, etc.
1735 LANGUAGE
1737 language for which the result will be used, i.e. C/CXX/For‐
1738 tran/ASM
1739 MODE
1741 EXIST only check for existence of the given package
1743 COMPILE
1745 print the flags needed for compiling an object file which
1746 uses the given package
1747 LINK print the flags needed for linking when using the given
1749 package
1750 QUIET if TRUE, don’t print anything
1752 CMakeGraphVizOptions
1754 The builtin Graphviz support of CMake.
1755 Generating Graphviz files
1757 CMake can generate Graphviz files showing the dependencies between the
1758 targets in a project, as well as external libraries which are linked
1759 against.
1760 When running CMake with the --graphviz=foo.dot option, it produces:
1762 · a foo.dot file, showing all dependencies in the project
1764 · a foo.dot.<target> file for each target, showing on which other tar‐
1766 gets it depends
1767 · a foo.dot.<target>.dependers file for each target, showing which
1769 other targets depend on it
1770 Those .dot files can be converted to images using the dot command from
1772 the Graphviz package:
1773 dot -Tpng -o foo.png foo.dot
1775 The different dependency types PUBLIC, INTERFACE and PRIVATE are repre‐
1777 sented as solid, dashed and dotted edges.
1778 Variables specific to the Graphviz support
1780 The resulting graphs can be huge. The look and content of the gener‐
1781 ated graphs can be controlled using the file CMakeGraphVizOp‐
1782 tions.cmake. This file is first searched in CMAKE_BINARY_DIR, and then
1783 in CMAKE_SOURCE_DIR. If found, the variables set in it are used to
1784 adjust options for the generated Graphviz files.
1785 GRAPHVIZ_GRAPH_NAME
1787 The graph name.
1788 · Mandatory: NO
1790 · Default: value of CMAKE_PROJECT_NAME
1792 GRAPHVIZ_GRAPH_HEADER
1794 The header written at the top of the Graphviz files.
1795 · Mandatory: NO
1797 · Default: “node [ fontsize = “12” ];”
1799 GRAPHVIZ_NODE_PREFIX
1801 The prefix for each node in the Graphviz files.
1802 · Mandatory: NO
1804 · Default: “node”
1806 GRAPHVIZ_EXECUTABLES
1808 Set to FALSE to exclude executables from the generated graphs.
1809 · Mandatory: NO
1811 · Default: TRUE
1813 GRAPHVIZ_STATIC_LIBS
1815 Set to FALSE to exclude static libraries from the generated
1816 graphs.
1817 · Mandatory: NO
1819 · Default: TRUE
1821 GRAPHVIZ_SHARED_LIBS
1823 Set to FALSE to exclude shared libraries from the generated
1824 graphs.
1825 · Mandatory: NO
1827 · Default: TRUE
1829 GRAPHVIZ_MODULE_LIBS
1831 Set to FALSE to exclude module libraries from the generated
1832 graphs.
1833 · Mandatory: NO
1835 · Default: TRUE
1837 GRAPHVIZ_INTERFACE_LIBS
1839 Set to FALSE to exclude interface libraries from the generated
1840 graphs.
1841 · Mandatory: NO
1843 · Default: TRUE
1845 GRAPHVIZ_OBJECT_LIBS
1847 Set to FALSE to exclude object libraries from the generated
1848 graphs.
1849 · Mandatory: NO
1851 · Default: TRUE
1853 GRAPHVIZ_UNKNOWN_LIBS
1855 Set to FALSE to exclude unknown libraries from the generated
1856 graphs.
1857 · Mandatory: NO
1859 · Default: TRUE
1861 GRAPHVIZ_EXTERNAL_LIBS
1863 Set to FALSE to exclude external libraries from the generated
1864 graphs.
1865 · Mandatory: NO
1867 · Default: TRUE
1869 GRAPHVIZ_CUSTOM_TARGETS
1871 Set to TRUE to include custom targets in the generated graphs.
1872 · Mandatory: NO
1874 · Default: FALSE
1876 GRAPHVIZ_IGNORE_TARGETS
1878 A list of regular expressions for names of targets to exclude
1879 from the generated graphs.
1880 · Mandatory: NO
1882 · Default: empty
1884 GRAPHVIZ_GENERATE_PER_TARGET
1886 Set to FALSE to not generate per-target graphs foo.dot.<target>.
1887 · Mandatory: NO
1889 · Default: TRUE
1891 GRAPHVIZ_GENERATE_DEPENDERS
1893 Set to FALSE to not generate depender graphs foo.dot.<tar‐
1894 get>.dependers.
1895 · Mandatory: NO
1897 · Default: TRUE
1899 CMakePackageConfigHelpers
1901 Helpers functions for creating config files that can be included by
1902 other projects to find and use a package.
1903 Adds the configure_package_config_file() and
1905 write_basic_package_version_file() commands.
1906 Generating a Package Configuration File
1908 configure_package_config_file
1909 Create a config file for a project:
1910 configure_package_config_file(<input> <output>
1912 INSTALL_DESTINATION <path>
1913 [PATH_VARS <var1> <var2> ... <varN>]
1914 [NO_SET_AND_CHECK_MACRO]
1915 [NO_CHECK_REQUIRED_COMPONENTS_MACRO]
1916 [INSTALL_PREFIX <path>]
1917 )
1918 configure_package_config_file() should be used instead of the plain
1920 configure_file() command when creating the <PackageName>Config.cmake or
1921 <PackageName>-config.cmake file for installing a project or library.
1922 It helps making the resulting package relocatable by avoiding hardcoded
1923 paths in the installed Config.cmake file.
1924 In a FooConfig.cmake file there may be code like this to make the
1926 install destinations know to the using project:
1927 set(FOO_INCLUDE_DIR "@CMAKE_INSTALL_FULL_INCLUDEDIR@" )
1929 set(FOO_DATA_DIR "@CMAKE_INSTALL_PREFIX@/@RELATIVE_DATA_INSTALL_DIR@" )
1930 set(FOO_ICONS_DIR "@CMAKE_INSTALL_PREFIX@/share/icons" )
1931 #...logic to determine installedPrefix from the own location...
1932 set(FOO_CONFIG_DIR "${installedPrefix}/@CONFIG_INSTALL_DIR@" )
1933 All 4 options shown above are not sufficient, since the first 3 hard‐
1935 code the absolute directory locations, and the 4th case works only if
1936 the logic to determine the installedPrefix is correct, and if CON‐
1937 FIG_INSTALL_DIR contains a relative path, which in general cannot be
1938 guaranteed. This has the effect that the resulting FooConfig.cmake
1939 file would work poorly under Windows and OSX, where users are used to
1940 choose the install location of a binary package at install time, inde‐
1941 pendent from how CMAKE_INSTALL_PREFIX was set at build/cmake time.
1942 Using configure_package_config_file helps. If used correctly, it makes
1944 the resulting FooConfig.cmake file relocatable. Usage:
1945 1. write a FooConfig.cmake.in file as you are used to
1947 2. insert a line containing only the string @PACKAGE_INIT@
1949 3. instead of set(FOO_DIR "@SOME_INSTALL_DIR@"), use set(FOO_DIR
1951 "@PACKAGE_SOME_INSTALL_DIR@") (this must be after the @PACKAGE_INIT@
1952 line)
1953 4. instead of using the normal configure_file(), use configure_pack‐
1955 age_config_file()
1956 The <input> and <output> arguments are the input and output file, the
1958 same way as in configure_file().
1959 The <path> given to INSTALL_DESTINATION must be the destination where
1961 the FooConfig.cmake file will be installed to. This path can either be
1962 absolute, or relative to the INSTALL_PREFIX path.
1963 The variables <var1> to <varN> given as PATH_VARS are the variables
1965 which contain install destinations. For each of them the macro will
1966 create a helper variable PACKAGE_<var...>. These helper variables must
1967 be used in the FooConfig.cmake.in file for setting the installed loca‐
1968 tion. They are calculated by configure_package_config_file so that
1969 they are always relative to the installed location of the package.
1970 This works both for relative and also for absolute locations. For
1971 absolute locations it works only if the absolute location is a subdi‐
1972 rectory of INSTALL_PREFIX.
1973 If the INSTALL_PREFIX argument is passed, this is used as base path to
1975 calculate all the relative paths. The <path> argument must be an abso‐
1976 lute path. If this argument is not passed, the CMAKE_INSTALL_PREFIX
1977 variable will be used instead. The default value is good when generat‐
1978 ing a FooConfig.cmake file to use your package from the install tree.
1979 When generating a FooConfig.cmake file to use your package from the
1980 build tree this option should be used.
1981 By default configure_package_config_file also generates two helper
1983 macros, set_and_check() and check_required_components() into the
1984 FooConfig.cmake file.
1985 set_and_check() should be used instead of the normal set() command for
1987 setting directories and file locations. Additionally to setting the
1988 variable it also checks that the referenced file or directory actually
1989 exists and fails with a FATAL_ERROR otherwise. This makes sure that
1990 the created FooConfig.cmake file does not contain wrong references.
1991 When using the NO_SET_AND_CHECK_MACRO, this macro is not generated into
1992 the FooConfig.cmake file.
1993 check_required_components(<PackageName>) should be called at the end of
1995 the FooConfig.cmake file. This macro checks whether all requested,
1996 non-optional components have been found, and if this is not the case,
1997 sets the Foo_FOUND variable to FALSE, so that the package is considered
1998 to be not found. It does that by testing the Foo_<Component>_FOUND
1999 variables for all requested required components. This macro should be
2000 called even if the package doesn’t provide any components to make sure
2001 users are not specifying components erroneously. When using the
2002 NO_CHECK_REQUIRED_COMPONENTS_MACRO option, this macro is not generated
2003 into the FooConfig.cmake file.
2004 For an example see below the documentation for
2006 write_basic_package_version_file().
2007 Generating a Package Version File
2009 write_basic_package_version_file
2010 Create a version file for a project:
2011 write_basic_package_version_file(<filename>
2013 [VERSION <major.minor.patch>]
2014 COMPATIBILITY <AnyNewerVersion|SameMajorVersion|SameMinorVersion|ExactVersion>
2015 [ARCH_INDEPENDENT] )
2016 Writes a file for use as <PackageName>ConfigVersion.cmake file to
2018 <filename>. See the documentation of find_package() for details on
2019 this.
2020 <filename> is the output filename, it should be in the build tree.
2022 <major.minor.patch> is the version number of the project to be
2023 installed.
2024 If no VERSION is given, the PROJECT_VERSION variable is used. If this
2026 hasn’t been set, it errors out.
2027 The COMPATIBILITY mode AnyNewerVersion means that the installed package
2029 version will be considered compatible if it is newer or exactly the
2030 same as the requested version. This mode should be used for packages
2031 which are fully backward compatible, also across major versions. If
2032 SameMajorVersion is used instead, then the behaviour differs from
2033 AnyNewerVersion in that the major version number must be the same as
2034 requested, e.g. version 2.0 will not be considered compatible if 1.0
2035 is requested. This mode should be used for packages which guarantee
2036 backward compatibility within the same major version. If SameMinorVer‐
2037 sion is used, the behaviour is the same as SameMajorVersion, but both
2038 major and minor version must be the same as requested, e.g version 0.2
2039 will not be compatible if 0.1 is requested. If ExactVersion is used,
2040 then the package is only considered compatible if the requested version
2041 matches exactly its own version number (not considering the tweak ver‐
2042 sion). For example, version 1.2.3 of a package is only considered com‐
2043 patible to requested version 1.2.3. This mode is for packages without
2044 compatibility guarantees. If your project has more elaborated version
2045 matching rules, you will need to write your own custom ConfigVer‐
2046 sion.cmake file instead of using this macro.
2047 If ARCH_INDEPENDENT is given, the installed package version will be
2049 considered compatible even if it was built for a different architecture
2050 than the requested architecture. Otherwise, an architecture check will
2051 be performed, and the package will be considered compatible only if the
2052 architecture matches exactly. For example, if the package is built for
2053 a 32-bit architecture, the package is only considered compatible if it
2054 is used on a 32-bit architecture, unless ARCH_INDEPENDENT is given, in
2055 which case the package is considered compatible on any architecture.
2056 NOTE:
2058 ARCH_INDEPENDENT is intended for header-only libraries or similar
2059 packages with no binaries.
2060 Internally, this macro executes configure_file() to create the result‐
2062 ing version file. Depending on the COMPATIBILITY, the corresponding
2063 BasicConfigVersion-<COMPATIBILITY>.cmake.in file is used. Please note
2064 that these files are internal to CMake and you should not call config‐
2065 ure_file() on them yourself, but they can be used as starting point to
2066 create more sophisticted custom ConfigVersion.cmake files.
2067 Example Generating Package Files
2069 Example using both configure_package_config_file() and
2070 write_basic_package_version_file():
2071 CMakeLists.txt:
2073 set(INCLUDE_INSTALL_DIR include/ ... CACHE )
2075 set(LIB_INSTALL_DIR lib/ ... CACHE )
2076 set(SYSCONFIG_INSTALL_DIR etc/foo/ ... CACHE )
2077 #...
2078 include(CMakePackageConfigHelpers)
2079 configure_package_config_file(FooConfig.cmake.in
2080 ${CMAKE_CURRENT_BINARY_DIR}/FooConfig.cmake
2081 INSTALL_DESTINATION ${LIB_INSTALL_DIR}/Foo/cmake
2082 PATH_VARS INCLUDE_INSTALL_DIR SYSCONFIG_INSTALL_DIR)
2083 write_basic_package_version_file(
2084 ${CMAKE_CURRENT_BINARY_DIR}/FooConfigVersion.cmake
2085 VERSION 1.2.3
2086 COMPATIBILITY SameMajorVersion )
2087 install(FILES ${CMAKE_CURRENT_BINARY_DIR}/FooConfig.cmake
2088 ${CMAKE_CURRENT_BINARY_DIR}/FooConfigVersion.cmake
2089 DESTINATION ${LIB_INSTALL_DIR}/Foo/cmake )
2090 FooConfig.cmake.in:
2092 set(FOO_VERSION x.y.z)
2094 ...
2095 @PACKAGE_INIT@
2096 ...
2097 set_and_check(FOO_INCLUDE_DIR "@PACKAGE_INCLUDE_INSTALL_DIR@")
2098 set_and_check(FOO_SYSCONFIG_DIR "@PACKAGE_SYSCONFIG_INSTALL_DIR@")
2099 check_required_components(Foo)
2101 CMakePrintHelpers
2103 Convenience functions for printing properties and variables, useful
2104 e.g. for debugging.
2105 cmake_print_properties([TARGETS target1 .. targetN]
2107 [SOURCES source1 .. sourceN]
2108 [DIRECTORIES dir1 .. dirN]
2109 [TESTS test1 .. testN]
2110 [CACHE_ENTRIES entry1 .. entryN]
2111 PROPERTIES prop1 .. propN )
2112 This function prints the values of the properties of the given targets,
2114 source files, directories, tests or cache entries. Exactly one of the
2115 scope keywords must be used. Example:
2116 cmake_print_properties(TARGETS foo bar PROPERTIES
2118 LOCATION INTERFACE_INCLUDE_DIRECTORIES)
2119 This will print the LOCATION and INTERFACE_INCLUDE_DIRECTORIES proper‐
2121 ties for both targets foo and bar.
2122 cmake_print_variables(var1 var2 .. varN)
2124 This function will print the name of each variable followed by its
2126 value. Example:
2127 cmake_print_variables(CMAKE_C_COMPILER CMAKE_MAJOR_VERSION DOES_NOT_EXIST)
2129 Gives:
2131 -- CMAKE_C_COMPILER="/usr/bin/gcc" ; CMAKE_MAJOR_VERSION="2" ; DOES_NOT_EXIST=""
2133 CMakePrintSystemInformation
2135 Print system information.
2136 This module serves diagnostic purposes. Just include it in a project to
2138 see various internal CMake variables.
2139 CMakePushCheckState
2141 This module defines three macros: CMAKE_PUSH_CHECK_STATE()
2142 CMAKE_POP_CHECK_STATE() and CMAKE_RESET_CHECK_STATE() These macros can
2143 be used to save, restore and reset (i.e., clear contents) the state of
2144 the variables CMAKE_REQUIRED_FLAGS, CMAKE_REQUIRED_DEFINITIONS,
2145 CMAKE_REQUIRED_LINK_OPTIONS, CMAKE_REQUIRED_LIBRARIES,
2146 CMAKE_REQUIRED_INCLUDES and CMAKE_EXTRA_INCLUDE_FILES used by the vari‐
2147 ous Check-files coming with CMake, like e.g. check_function_exists()
2148 etc. The variable contents are pushed on a stack, pushing multiple
2149 times is supported. This is useful e.g. when executing such tests in
2150 a Find-module, where they have to be set, but after the Find-module has
2151 been executed they should have the same value as they had before.
2152 CMAKE_PUSH_CHECK_STATE() macro receives optional argument RESET.
2154 Whether it’s specified, CMAKE_PUSH_CHECK_STATE() will set all
2155 CMAKE_REQUIRED_* variables to empty values, same as
2156 CMAKE_RESET_CHECK_STATE() call will do.
2157 Usage:
2159 cmake_push_check_state(RESET)
2161 set(CMAKE_REQUIRED_DEFINITIONS -DSOME_MORE_DEF)
2162 check_function_exists(...)
2163 cmake_reset_check_state()
2164 set(CMAKE_REQUIRED_DEFINITIONS -DANOTHER_DEF)
2165 check_function_exists(...)
2166 cmake_pop_check_state()
2167 CMakeVerifyManifest
2169 CMakeVerifyManifest.cmake
2170 This script is used to verify that embedded manifests and side by side
2172 manifests for a project match. To run this script, cd to a directory
2173 and run the script with cmake -P. On the command line you can pass in
2174 versions that are OK even if not found in the .manifest files. For
2175 example, cmake -Dallow_versions=8.0.50608.0 -PCmakeVerifyManifest.cmake
2176 could be used to allow an embedded manifest of 8.0.50608.0 to be used
2177 in a project even if that version was not found in the .manifest file.
2178 CPackComponent
2180 Build binary and source package installers
2181 Variables concerning CPack Components
2183 The CPackComponent module is the module which handles the component
2184 part of CPack. See CPack module for general information about CPack.
2185 For certain kinds of binary installers (including the graphical in‐
2187 stallers on macOS and Windows), CPack generates installers that allow
2188 users to select individual application components to install. The con‐
2189 tents of each of the components are identified by the COMPONENT argu‐
2190 ment of CMake’s INSTALL command. These components can be annotated
2191 with user-friendly names and descriptions, inter-component dependen‐
2192 cies, etc., and grouped in various ways to customize the resulting in‐
2193 staller. See the cpack_add_* commands, described below, for more
2194 information about component-specific installations.
2195 Component-specific installation allows users to select specific sets of
2197 components to install during the install process. Installation compo‐
2198 nents are identified by the COMPONENT argument of CMake’s INSTALL com‐
2199 mands, and should be further described by the following CPack commands:
2200 CPACK_COMPONENTS_ALL
2202 The list of component to install.
2203 The default value of this variable is computed by CPack and con‐
2205 tains all components defined by the project. The user may set
2206 it to only include the specified components.
2207 Instead of specifying all the desired components, it is possible
2209 to obtain a list of all defined components and then remove the
2210 unwanted ones from the list. The get_cmake_property() command
2211 can be used to obtain the COMPONENTS property, then the
2212 list(REMOVE_ITEM) command can be used to remove the unwanted
2213 ones. For example, to use all defined components except foo and
2214 bar:
2215 get_cmake_property(CPACK_COMPONENTS_ALL COMPONENTS)
2217 list(REMOVE_ITEM CPACK_COMPONENTS_ALL "foo" "bar")
2218 CPACK_<GENNAME>_COMPONENT_INSTALL
2220 Enable/Disable component install for CPack generator <GENNAME>.
2221 Each CPack Generator (RPM, DEB, ARCHIVE, NSIS, DMG, etc…) has a
2223 legacy default behavior. e.g. RPM builds monolithic whereas
2224 NSIS builds component. One can change the default behavior by
2225 setting this variable to 0/1 or OFF/ON.
2226 CPACK_COMPONENTS_GROUPING
2228 Specify how components are grouped for multi-package compo‐
2229 nent-aware CPack generators.
2230 Some generators like RPM or ARCHIVE family (TGZ, ZIP, …) gener‐
2232 ates several packages files when asked for component packaging.
2233 They group the component differently depending on the value of
2234 this variable:
2235 · ONE_PER_GROUP (default): creates one package file per compo‐
2237 nent group
2238 · ALL_COMPONENTS_IN_ONE : creates a single package with all
2240 (requested) components
2241 · IGNORE : creates one package per component, i.e. IGNORE compo‐
2243 nent group
2244 One can specify different grouping for different CPack generator
2246 by using a CPACK_PROJECT_CONFIG_FILE.
2247 CPACK_COMPONENT_<compName>_DISPLAY_NAME
2249 The name to be displayed for a component.
2250 CPACK_COMPONENT_<compName>_DESCRIPTION
2252 The description of a component.
2253 CPACK_COMPONENT_<compName>_GROUP
2255 The group of a component.
2256 CPACK_COMPONENT_<compName>_DEPENDS
2258 The dependencies (list of components) on which this component
2259 depends.
2260 CPACK_COMPONENT_<compName>_HIDDEN
2262 True if this component is hidden from the user.
2263 CPACK_COMPONENT_<compName>_REQUIRED
2265 True if this component is required.
2266 CPACK_COMPONENT_<compName>_DISABLED
2268 True if this component is not selected to be installed by
2269 default.
2270 cpack_add_component
2272 Describes a CPack installation component named by the COMPONENT argu‐
2274 ment to a CMake INSTALL command.
2275 cpack_add_component(compname
2277 [DISPLAY_NAME name]
2278 [DESCRIPTION description]
2279 [HIDDEN | REQUIRED | DISABLED ]
2280 [GROUP group]
2281 [DEPENDS comp1 comp2 ... ]
2282 [INSTALL_TYPES type1 type2 ... ]
2283 [DOWNLOADED]
2284 [ARCHIVE_FILE filename]
2285 [PLIST filename])
2286 The cmake_add_component command describes an installation component,
2288 which the user can opt to install or remove as part of the graphical
2289 installation process. compname is the name of the component, as pro‐
2290 vided to the COMPONENT argument of one or more CMake INSTALL commands.
2291 DISPLAY_NAME is the displayed name of the component, used in graphical
2293 installers to display the component name. This value can be any
2294 string.
2295 DESCRIPTION is an extended description of the component, used in graph‐
2297 ical installers to give the user additional information about the com‐
2298 ponent. Descriptions can span multiple lines using \n as the line sep‐
2299 arator. Typically, these descriptions should be no more than a few
2300 lines long.
2301 HIDDEN indicates that this component will be hidden in the graphical
2303 installer, so that the user cannot directly change whether it is
2304 installed or not.
2305 REQUIRED indicates that this component is required, and therefore will
2307 always be installed. It will be visible in the graphical installer,
2308 but it cannot be unselected. (Typically, required components are shown
2309 greyed out).
2310 DISABLED indicates that this component should be disabled (unselected)
2312 by default. The user is free to select this component for installa‐
2313 tion, unless it is also HIDDEN.
2314 DEPENDS lists the components on which this component depends. If this
2316 component is selected, then each of the components listed must also be
2317 selected. The dependency information is encoded within the installer
2318 itself, so that users cannot install inconsistent sets of components.
2319 GROUP names the component group of which this component is a part. If
2321 not provided, the component will be a standalone component, not part of
2322 any component group. Component groups are described with the
2323 cpack_add_component_group command, detailed below.
2324 INSTALL_TYPES lists the installation types of which this component is a
2326 part. When one of these installations types is selected, this compo‐
2327 nent will automatically be selected. Installation types are described
2328 with the cpack_add_install_type command, detailed below.
2329 DOWNLOADED indicates that this component should be downloaded
2331 on-the-fly by the installer, rather than packaged in with the installer
2332 itself. For more information, see the cpack_configure_downloads com‐
2333 mand.
2334 ARCHIVE_FILE provides a name for the archive file created by CPack to
2336 be used for downloaded components. If not supplied, CPack will create
2337 a file with some name based on CPACK_PACKAGE_FILE_NAME and the name of
2338 the component. See cpack_configure_downloads for more information.
2339 PLIST gives a filename that is passed to pkgbuild with the --compo‐
2341 nent-plist argument when using the productbuild generator.
2342 cpack_add_component_group
2344 Describes a group of related CPack installation components.
2346 cpack_add_component_group(groupname
2348 [DISPLAY_NAME name]
2349 [DESCRIPTION description]
2350 [PARENT_GROUP parent]
2351 [EXPANDED]
2352 [BOLD_TITLE])
2353 The cpack_add_component_group describes a group of installation compo‐
2355 nents, which will be placed together within the listing of options.
2356 Typically, component groups allow the user to select/deselect all of
2357 the components within a single group via a single group-level option.
2358 Use component groups to reduce the complexity of installers with many
2359 options. groupname is an arbitrary name used to identify the group in
2360 the GROUP argument of the cpack_add_component command, which is used to
2361 place a component in a group. The name of the group must not conflict
2362 with the name of any component.
2363 DISPLAY_NAME is the displayed name of the component group, used in
2365 graphical installers to display the component group name. This value
2366 can be any string.
2367 DESCRIPTION is an extended description of the component group, used in
2369 graphical installers to give the user additional information about the
2370 components within that group. Descriptions can span multiple lines
2371 using \n as the line separator. Typically, these descriptions should
2372 be no more than a few lines long.
2373 PARENT_GROUP, if supplied, names the parent group of this group. Par‐
2375 ent groups are used to establish a hierarchy of groups, providing an
2376 arbitrary hierarchy of groups.
2377 EXPANDED indicates that, by default, the group should show up as
2379 “expanded”, so that the user immediately sees all of the components
2380 within the group. Otherwise, the group will initially show up as a
2381 single entry.
2382 BOLD_TITLE indicates that the group title should appear in bold, to
2384 call the user’s attention to the group.
2385 cpack_add_install_type
2387 Add a new installation type containing a set of predefined component
2389 selections to the graphical installer.
2390 cpack_add_install_type(typename
2392 [DISPLAY_NAME name])
2393 The cpack_add_install_type command identifies a set of preselected com‐
2395 ponents that represents a common use case for an application. For
2396 example, a “Developer” install type might include an application along
2397 with its header and library files, while an “End user” install type
2398 might just include the application’s executable. Each component iden‐
2399 tifies itself with one or more install types via the INSTALL_TYPES
2400 argument to cpack_add_component.
2401 DISPLAY_NAME is the displayed name of the install type, which will typ‐
2403 ically show up in a drop-down box within a graphical installer. This
2404 value can be any string.
2405 cpack_configure_downloads
2407 Configure CPack to download selected components on-the-fly as part of
2409 the installation process.
2410 cpack_configure_downloads(site
2412 [UPLOAD_DIRECTORY dirname]
2413 [ALL]
2414 [ADD_REMOVE|NO_ADD_REMOVE])
2415 The cpack_configure_downloads command configures installation-time
2417 downloads of selected components. For each downloadable component,
2418 CPack will create an archive containing the contents of that component,
2419 which should be uploaded to the given site. When the user selects that
2420 component for installation, the installer will download and extract the
2421 component in place. This feature is useful for creating small install‐
2422 ers that only download the requested components, saving bandwidth.
2423 Additionally, the installers are small enough that they will be
2424 installed as part of the normal installation process, and the “Change”
2425 button in Windows Add/Remove Programs control panel will allow one to
2426 add or remove parts of the application after the original installation.
2427 On Windows, the downloaded-components functionality requires the ZipDLL
2428 plug-in for NSIS, available at:
2429 http://nsis.sourceforge.net/ZipDLL_plug-in
2431 On macOS, installers that download components on-the-fly can only be
2433 built and installed on system using macOS 10.5 or later.
2434 The site argument is a URL where the archives for downloadable compo‐
2436 nents will reside, e.g., https://cmake.org/files/2.6.1/installer/ All
2437 of the archives produced by CPack should be uploaded to that location.
2438 UPLOAD_DIRECTORY is the local directory where CPack will create the
2440 various archives for each of the components. The contents of this
2441 directory should be uploaded to a location accessible by the URL given
2442 in the site argument. If omitted, CPack will use the directory CPackU‐
2443 ploads inside the CMake binary directory to store the generated ar‐
2444 chives.
2445 The ALL flag indicates that all components be downloaded. Otherwise,
2447 only those components explicitly marked as DOWNLOADED or that have a
2448 specified ARCHIVE_FILE will be downloaded. Additionally, the ALL
2449 option implies ADD_REMOVE (unless NO_ADD_REMOVE is specified).
2450 ADD_REMOVE indicates that CPack should install a copy of the installer
2452 that can be called from Windows’ Add/Remove Programs dialog (via the
2453 “Modify” button) to change the set of installed components.
2454 NO_ADD_REMOVE turns off this behavior. This option is ignored on Mac
2455 OS X.
2456 CPackIFW
2458 This module looks for the location of the command-line utilities sup‐
2459 plied with the Qt Installer Framework (QtIFW).
2460 The module also defines several commands to control the behavior of the
2462 CPack IFW Generator.
2463 Commands
2465 The module defines the following commands:
2466 cpack_ifw_configure_component
2468 Sets the arguments specific to the CPack IFW generator.
2469 cpack_ifw_configure_component(<compname> [COMMON] [ESSENTIAL] [VIRTUAL]
2471 [FORCED_INSTALLATION] [REQUIRES_ADMIN_RIGHTS]
2472 [NAME <name>]
2473 [DISPLAY_NAME <display_name>] # Note: Internationalization supported
2474 [DESCRIPTION <description>] # Note: Internationalization supported
2475 [UPDATE_TEXT <update_text>]
2476 [VERSION <version>]
2477 [RELEASE_DATE <release_date>]
2478 [SCRIPT <script>]
2479 [PRIORITY|SORTING_PRIORITY <sorting_priority>] # Note: PRIORITY is deprecated
2480 [DEPENDS|DEPENDENCIES <com_id> ...]
2481 [AUTO_DEPEND_ON <comp_id> ...]
2482 [LICENSES <display_name> <file_path> ...]
2483 [DEFAULT <value>]
2484 [USER_INTERFACES <file_path> <file_path> ...]
2485 [TRANSLATIONS <file_path> <file_path> ...]
2486 [REPLACES <comp_id> ...]
2487 [CHECKABLE <value>])
2488 This command should be called after cpack_add_component() com‐
2490 mand.
2491 COMMON if set, then the component will be packaged and installed
2493 as part of a group to which it belongs.
2494 ESSENTIAL
2496 if set, then the package manager stays disabled until
2497 that component is updated.
2498 VIRTUAL
2500 if set, then the component will be hidden from the in‐
2501 staller. It is a equivalent of the HIDDEN option from
2502 the cpack_add_component() command.
2503 FORCED_INSTALLATION
2505 if set, then the component must always be installed. It
2506 is a equivalent of the REQUARED option from the
2507 cpack_add_component() command.
2508 REQUIRES_ADMIN_RIGHTS
2510 set it if the component needs to be installed with ele‐
2511 vated permissions.
2512 NAME is used to create domain-like identification for this
2514 component. By default used origin component name.
2515 DISPLAY_NAME
2517 set to rewrite original name configured by cpack_add_com‐
2518 ponent() command.
2519 DESCRIPTION
2521 set to rewrite original description configured by
2522 cpack_add_component() command.
2523 UPDATE_TEXT
2525 will be added to the component description if this is an
2526 update to the component.
2527 VERSION
2529 is version of component. By default used CPACK_PACK‐
2530 AGE_VERSION.
2531 RELEASE_DATE
2533 keep empty to auto generate.
2534 SCRIPT is a relative or absolute path to operations script for
2536 this component.
2537 PRIORITY | SORTING_PRIORITY
2539 is priority of the component in the tree. The PRIORITY
2540 option is deprecated and will be removed in a future ver‐
2541 sion of CMake. Please use SORTING_PRIORITY option
2542 instead.
2543 DEPENDS | DEPENDENCIES
2545 list of dependency component or component group identi‐
2546 fiers in QtIFW style.
2547 AUTO_DEPEND_ON
2549 list of identifiers of component or component group in
2550 QtIFW style that this component has an automatic depen‐
2551 dency on.
2552 LICENSES
2554 pair of <display_name> and <file_path> of license text
2555 for this component. You can specify more then one
2556 license.
2557 DEFAULT
2559 Possible values are: TRUE, FALSE, and SCRIPT. Set to
2560 FALSE to disable the component in the installer or to
2561 SCRIPT to resolved during runtime (don’t forget add the
2562 file of the script as a value of the SCRIPT option).
2563 USER_INTERFACES
2565 is a list of <file_path> (‘.ui’ files) representing pages
2566 to load.
2567 TRANSLATIONS
2569 is a list of <file_path> (‘.qm’ files) representing
2570 translations to load.
2571 REPLACES
2573 list of identifiers of component or component group to
2574 replace.
2575 CHECKABLE
2577 Possible values are: TRUE, FALSE. Set to FALSE if you
2578 want to hide the checkbox for an item. This is useful
2579 when only a few subcomponents should be selected instead
2580 of all.
2581 cpack_ifw_configure_component_group
2583 Sets the arguments specific to the CPack IFW generator.
2584 cpack_ifw_configure_component_group(<groupname> [VIRTUAL]
2586 [FORCED_INSTALLATION] [REQUIRES_ADMIN_RIGHTS]
2587 [NAME <name>]
2588 [DISPLAY_NAME <display_name>] # Note: Internationalization supported
2589 [DESCRIPTION <description>] # Note: Internationalization supported
2590 [UPDATE_TEXT <update_text>]
2591 [VERSION <version>]
2592 [RELEASE_DATE <release_date>]
2593 [SCRIPT <script>]
2594 [PRIORITY|SORTING_PRIORITY <sorting_priority>] # Note: PRIORITY is deprecated
2595 [DEPENDS|DEPENDENCIES <com_id> ...]
2596 [AUTO_DEPEND_ON <comp_id> ...]
2597 [LICENSES <display_name> <file_path> ...]
2598 [DEFAULT <value>]
2599 [USER_INTERFACES <file_path> <file_path> ...]
2600 [TRANSLATIONS <file_path> <file_path> ...]
2601 [REPLACES <comp_id> ...]
2602 [CHECKABLE <value>])
2603 This command should be called after cpack_add_component_group()
2605 command.
2606 VIRTUAL
2608 if set, then the group will be hidden from the installer.
2609 Note that setting this on a root component does not work.
2610 FORCED_INSTALLATION
2612 if set, then the group must always be installed.
2613 REQUIRES_ADMIN_RIGHTS
2615 set it if the component group needs to be installed with
2616 elevated permissions.
2617 NAME is used to create domain-like identification for this
2619 component group. By default used origin component group
2620 name.
2621 DISPLAY_NAME
2623 set to rewrite original name configured by cpack_add_com‐
2624 ponent_group() command.
2625 DESCRIPTION
2627 set to rewrite original description configured by
2628 cpack_add_component_group() command.
2629 UPDATE_TEXT
2631 will be added to the component group description if this
2632 is an update to the component group.
2633 VERSION
2635 is version of component group. By default used
2636 CPACK_PACKAGE_VERSION.
2637 RELEASE_DATE
2639 keep empty to auto generate.
2640 SCRIPT is a relative or absolute path to operations script for
2642 this component group.
2643 PRIORITY | SORTING_PRIORITY
2645 is priority of the component group in the tree. The PRI‐
2646 ORITY option is deprecated and will be removed in a
2647 future version of CMake. Please use SORTING_PRIORITY
2648 option instead.
2649 DEPENDS | DEPENDENCIES
2651 list of dependency component or component group identi‐
2652 fiers in QtIFW style.
2653 AUTO_DEPEND_ON
2655 list of identifiers of component or component group in
2656 QtIFW style that this component group has an automatic
2657 dependency on.
2658 LICENSES
2660 pair of <display_name> and <file_path> of license text
2661 for this component group. You can specify more then one
2662 license.
2663 DEFAULT
2665 Possible values are: TRUE, FALSE, and SCRIPT. Set to
2666 TRUE to preselect the group in the installer (this takes
2667 effect only on groups that have no visible child compo‐
2668 nents) or to SCRIPT to resolved during runtime (don’t
2669 forget add the file of the script as a value of the
2670 SCRIPT option).
2671 USER_INTERFACES
2673 is a list of <file_path> (‘.ui’ files) representing pages
2674 to load.
2675 TRANSLATIONS
2677 is a list of <file_path> (‘.qm’ files) representing
2678 translations to load.
2679 REPLACES
2681 list of identifiers of component or component group to
2682 replace.
2683 CHECKABLE
2685 Possible values are: TRUE, FALSE. Set to FALSE if you
2686 want to hide the checkbox for an item. This is useful
2687 when only a few subcomponents should be selected instead
2688 of all.
2689 cpack_ifw_add_repository
2691 Add QtIFW specific remote repository to binary installer.
2692 cpack_ifw_add_repository(<reponame> [DISABLED]
2694 URL <url>
2695 [USERNAME <username>]
2696 [PASSWORD <password>]
2697 [DISPLAY_NAME <display_name>])
2698 This command will also add the <reponame> repository to a vari‐
2700 able CPACK_IFW_REPOSITORIES_ALL.
2701 DISABLED
2703 if set, then the repository will be disabled by default.
2704 URL is points to a list of available components.
2706 USERNAME
2708 is used as user on a protected repository.
2709 PASSWORD
2711 is password to use on a protected repository.
2712 DISPLAY_NAME
2714 is string to display instead of the URL.
2715 cpack_ifw_update_repository
2717 Update QtIFW specific repository from remote repository.
2718 cpack_ifw_update_repository(<reponame>
2720 [[ADD|REMOVE] URL <url>]|
2721 [REPLACE OLD_URL <old_url> NEW_URL <new_url>]]
2722 [USERNAME <username>]
2723 [PASSWORD <password>]
2724 [DISPLAY_NAME <display_name>])
2725 This command will also add the <reponame> repository to a vari‐
2727 able CPACK_IFW_REPOSITORIES_ALL.
2728 URL is points to a list of available components.
2730 OLD_URL
2732 is points to a list that will replaced.
2733 NEW_URL
2735 is points to a list that will replace to.
2736 USERNAME
2738 is used as user on a protected repository.
2739 PASSWORD
2741 is password to use on a protected repository.
2742 DISPLAY_NAME
2744 is string to display instead of the URL.
2745 cpack_ifw_add_package_resources
2747 Add additional resources in the installer binary.
2748 cpack_ifw_add_package_resources(<file_path> <file_path> ...)
2750 This command will also add the specified files to a variable
2752 CPACK_IFW_PACKAGE_RESOURCES.
2753 CPackIFWConfigureFile
2755 The module defines configure_file() similar command to configure file
2756 templates prepared in QtIFW/SDK/Creator style.
2757 Commands
2759 The module defines the following commands:
2760 cpack_ifw_configure_file
2762 Copy a file to another location and modify its contents.
2763 cpack_ifw_configure_file(<input> <output>)
2765 Copies an <input> file to an <output> file and substitutes vari‐
2767 able values referenced as %{VAR} or %VAR% in the input file con‐
2768 tent. Each variable reference will be replaced with the current
2769 value of the variable, or the empty string if the variable is
2770 not defined.
2771 CPack
2773 Configure the binary and source package installers.
2774 Introduction
2776 The CPack module generates the configuration files CPackConfig.cmake
2777 and CPackSourceConfig.cmake. They are intended for use in a subsequent
2778 run of the cpack program where they steer the generation of installers
2779 or/and source packages.
2780 Depending on the CMake generator, the CPack module may also add two new
2782 build targets, package and package_source. See the packaging targets
2783 section below for details.
2784 The generated binary installers contain everything installed via
2786 CMake’s install() command (and the deprecated commands install_files(),
2787 install_programs(), and install_targets()). For certain kinds of
2788 binary installers (including the graphical installers on macOS and Win‐
2789 dows), CPack generates installers that allow users to select individual
2790 application components to install. See CPackComponent module for fur‐
2791 ther details.
2792 CPack Generators
2794 The CPACK_GENERATOR variable has different meanings in different con‐
2795 texts. In a CMakeLists.txt file, CPACK_GENERATOR is a list of genera‐
2796 tors: and when cpack is run with no other arguments, it will iterate
2797 over that list and produce one package for each generator. In a
2798 CPACK_PROJECT_CONFIG_FILE, CPACK_GENERATOR is a string naming a single
2799 generator. If you need per-cpack-generator logic to control other
2800 cpack settings, then you need a CPACK_PROJECT_CONFIG_FILE.
2801 The CMake source tree itself contains a CPACK_PROJECT_CONFIG_FILE. See
2803 the top level file CMakeCPackOptions.cmake.in for an example.
2804 If set, the CPACK_PROJECT_CONFIG_FILE is included automatically on a
2806 per-generator basis. It only need contain overrides.
2807 Here’s how it works:
2809 · cpack runs
2811 · it includes CPackConfig.cmake
2813 · it iterates over the generators given by the -G command line option,
2815 or if no such option was specified, over the list of generators given
2816 by the CPACK_GENERATOR variable set in the CPackConfig.cmake input
2817 file.
2818 · foreach generator, it then
2820 · sets CPACK_GENERATOR to the one currently being iterated
2822 · includes the CPACK_PROJECT_CONFIG_FILE
2824 · produces the package for that generator
2826 This is the key: For each generator listed in CPACK_GENERATOR in CPack‐
2828 Config.cmake, cpack will reset CPACK_GENERATOR internally to the one
2829 currently being used and then include the CPACK_PROJECT_CONFIG_FILE.
2830 For a list of available generators, see cpack-generators(7).
2832 Targets package and package_source
2834 If CMake is run with the Makefile, Ninja, or Xcode generator, then
2835 include(CPack) generates a target package. This makes it possible to
2836 build a binary installer from CMake, Make, or Ninja: Instead of cpack,
2837 one may call cmake --build . --target package or make package or ninja
2838 package. The VS generator creates an uppercase target PACKAGE.
2839 If CMake is run with the Makefile or Ninja generator, then
2841 include(CPack) also generates a target package_source. To build a
2842 source package, instead of cpack -G TGZ --config CPackConfig.cmake one
2843 may call cmake --build . --target package_source, make package_source,
2844 or ninja package_source.
2845 Variables common to all CPack Generators
2847 Before including this CPack module in your CMakeLists.txt file, there
2848 are a variety of variables that can be set to customize the resulting
2849 installers. The most commonly-used variables are:
2850 CPACK_PACKAGE_NAME
2852 The name of the package (or application). If not specified, it
2853 defaults to the project name.
2854 CPACK_PACKAGE_VENDOR
2856 The name of the package vendor. (e.g., “Kitware”). The default
2857 is “Humanity”.
2858 CPACK_PACKAGE_DIRECTORY
2860 The directory in which CPack is doing its packaging. If it is
2861 not set then this will default (internally) to the build dir.
2862 This variable may be defined in a CPack config file or from the
2863 cpack command line option -B. If set, the command line option
2864 overrides the value found in the config file.
2865 CPACK_PACKAGE_VERSION_MAJOR
2867 Package major version. This variable will always be set, but
2868 its default value depends on whether or not version details were
2869 given to the project() command in the top level CMakeLists.txt
2870 file. If version details were given, the default value will be
2871 CMAKE_PROJECT_VERSION_MAJOR. If no version details were given,
2872 a default version of 0.1.1 will be assumed, leading to
2873 CPACK_PACKAGE_VERSION_MAJOR having a default value of 0.
2874 CPACK_PACKAGE_VERSION_MINOR
2876 Package minor version. The default value is determined based on
2877 whether or not version details were given to the project() com‐
2878 mand in the top level CMakeLists.txt file. If version details
2879 were given, the default value will be CMAKE_PROJECT_VER‐
2880 SION_MINOR, but if no minor version component was specified then
2881 CPACK_PACKAGE_VERSION_MINOR will be left unset. If no project
2882 version was given at all, a default version of 0.1.1 will be
2883 assumed, leading to CPACK_PACKAGE_VERSION_MINOR having a default
2884 value of 1.
2885 CPACK_PACKAGE_VERSION_PATCH
2887 Package patch version. The default value is determined based on
2888 whether or not version details were given to the project() com‐
2889 mand in the top level CMakeLists.txt file. If version details
2890 were given, the default value will be CMAKE_PROJECT_VER‐
2891 SION_PATCH, but if no patch version component was specified then
2892 CPACK_PACKAGE_VERSION_PATCH will be left unset. If no project
2893 version was given at all, a default version of 0.1.1 will be
2894 assumed, leading to CPACK_PACKAGE_VERSION_PATCH having a default
2895 value of 1.
2896 CPACK_PACKAGE_DESCRIPTION
2898 A description of the project, used in places such as the intro‐
2899 duction screen of CPack-generated Windows installers. If not
2900 set, the value of this variable is populated from the file named
2901 by CPACK_PACKAGE_DESCRIPTION_FILE.
2902 CPACK_PACKAGE_DESCRIPTION_FILE
2904 A text file used to describe the project when
2905 CPACK_PACKAGE_DESCRIPTION is not explicitly set. The default
2906 value for CPACK_PACKAGE_DESCRIPTION_FILE points to a built-in
2907 template file Templates/CPack.GenericDescription.txt.
2908 CPACK_PACKAGE_DESCRIPTION_SUMMARY
2910 Short description of the project (only a few words). If the
2911 CMAKE_PROJECT_DESCRIPTION variable is set, it is used as the
2912 default value, otherwise the default will be a string generated
2913 by CMake based on CMAKE_PROJECT_NAME.
2914 CPACK_PACKAGE_HOMEPAGE_URL
2916 Project homepage URL. The default value is taken from the
2917 CMAKE_PROJECT_HOMEPAGE_URL variable, which is set by the top
2918 level project() command, or else the default will be empty if no
2919 URL was provided to project().
2920 CPACK_PACKAGE_FILE_NAME
2922 The name of the package file to generate, not including the
2923 extension. For example, cmake-2.6.1-Linux-i686. The default
2924 value is:
2925 ${CPACK_PACKAGE_NAME}-${CPACK_PACKAGE_VERSION}-${CPACK_SYSTEM_NAME}
2927 CPACK_PACKAGE_INSTALL_DIRECTORY
2929 Installation directory on the target system. This may be used by
2930 some CPack generators like NSIS to create an installation direc‐
2931 tory e.g., “CMake 2.5” below the installation prefix. All
2932 installed elements will be put inside this directory.
2933 CPACK_PACKAGE_ICON
2935 A branding image that will be displayed inside the installer
2936 (used by GUI installers).
2937 CPACK_PACKAGE_CHECKSUM
2939 An algorithm that will be used to generate an additional file
2940 with the checksum of the package. The output file name will be:
2941 ${CPACK_PACKAGE_FILE_NAME}.${CPACK_PACKAGE_CHECKSUM}
2943 Supported algorithms are those listed by the string(<HASH>) com‐
2945 mand.
2946 CPACK_PROJECT_CONFIG_FILE
2948 CPack-time project CPack configuration file. This file is
2949 included at cpack time, once per generator after CPack has set
2950 CPACK_GENERATOR to the actual generator being used. It allows
2951 per-generator setting of CPACK_* variables at cpack time.
2952 CPACK_RESOURCE_FILE_LICENSE
2954 License to be embedded in the installer. It will typically be
2955 displayed to the user by the produced installer (often with an
2956 explicit “Accept” button, for graphical installers) prior to
2957 installation. This license file is NOT added to the installed
2958 files but is used by some CPack generators like NSIS. If you
2959 want to install a license file (may be the same as this one)
2960 along with your project, you must add an appropriate CMake
2961 install() command in your CMakeLists.txt.
2962 CPACK_RESOURCE_FILE_README
2964 ReadMe file to be embedded in the installer. It typically
2965 describes in some detail the purpose of the project during the
2966 installation. Not all CPack generators use this file.
2967 CPACK_RESOURCE_FILE_WELCOME
2969 Welcome file to be embedded in the installer. It welcomes users
2970 to this installer. Typically used in the graphical installers
2971 on Windows and Mac OS X.
2972 CPACK_MONOLITHIC_INSTALL
2974 Disables the component-based installation mechanism. When set,
2975 the component specification is ignored and all installed items
2976 are put in a single “MONOLITHIC” package. Some CPack generators
2977 do monolithic packaging by default and may be asked to do compo‐
2978 nent packaging by setting CPACK_<GENNAME>_COMPONENT_INSTALL to
2979 TRUE.
2980 CPACK_GENERATOR
2982 List of CPack generators to use. If not specified, CPack will
2983 create a set of options following the naming pattern
2984 CPACK_BINARY_<GENNAME> (e.g. CPACK_BINARY_NSIS) allowing the
2985 user to enable/disable individual generators. If the -G option
2986 is given on the cpack command line, it will override this vari‐
2987 able and any CPACK_BINARY_<GENNAME> options.
2988 CPACK_OUTPUT_CONFIG_FILE
2990 The name of the CPack binary configuration file. This file is
2991 the CPack configuration generated by the CPack module for binary
2992 installers. Defaults to CPackConfig.cmake.
2993 CPACK_PACKAGE_EXECUTABLES
2995 Lists each of the executables and associated text label to be
2996 used to create Start Menu shortcuts. For example, setting this
2997 to the list ccmake;CMake will create a shortcut named “CMake”
2998 that will execute the installed executable ccmake. Not all
2999 CPack generators use it (at least NSIS, WIX and OSXX11 do).
3000 CPACK_STRIP_FILES
3002 List of files to be stripped. Starting with CMake 2.6.0,
3003 CPACK_STRIP_FILES will be a boolean variable which enables
3004 stripping of all files (a list of files evaluates to TRUE in
3005 CMake, so this change is compatible).
3006 CPACK_VERBATIM_VARIABLES
3008 If set to TRUE, values of variables prefixed with CPACK_ will be
3009 escaped before being written to the configuration files, so that
3010 the cpack program receives them exactly as they were specified.
3011 If not, characters like quotes and backslashes can cause parsing
3012 errors or alter the value received by the cpack program.
3013 Defaults to FALSE for backwards compatibility.
3014 Variables for Source Package Generators
3016 The following CPack variables are specific to source packages, and will
3017 not affect binary packages:
3018 CPACK_SOURCE_PACKAGE_FILE_NAME
3020 The name of the source package. For example cmake-2.6.1.
3021 CPACK_SOURCE_STRIP_FILES
3023 List of files in the source tree that will be stripped. Start‐
3024 ing with CMake 2.6.0, CPACK_SOURCE_STRIP_FILES will be a boolean
3025 variable which enables stripping of all files (a list of files
3026 evaluates to TRUE in CMake, so this change is compatible).
3027 CPACK_SOURCE_GENERATOR
3029 List of generators used for the source packages. As with
3030 CPACK_GENERATOR, if this is not specified then CPack will create
3031 a set of options (e.g. CPACK_SOURCE_ZIP) allowing users to
3032 select which packages will be generated.
3033 CPACK_SOURCE_OUTPUT_CONFIG_FILE
3035 The name of the CPack source configuration file. This file is
3036 the CPack configuration generated by the CPack module for source
3037 installers. Defaults to CPackSourceConfig.cmake.
3038 CPACK_SOURCE_IGNORE_FILES
3040 Pattern of files in the source tree that won’t be packaged when
3041 building a source package. This is a list of regular expression
3042 patterns (that must be properly escaped), e.g.,
3043 /CVS/;/\\.svn/;\\.swp$;\\.#;/#;.*~;cscope.*
3044 Variables for Advanced Use
3046 The following variables are for advanced uses of CPack:
3047 CPACK_CMAKE_GENERATOR
3049 What CMake generator should be used if the project is a CMake
3050 project. Defaults to the value of CMAKE_GENERATOR. Few users
3051 will want to change this setting.
3052 CPACK_INSTALL_CMAKE_PROJECTS
3054 List of four values that specify what project to install. The
3055 four values are: Build directory, Project Name, Project Compo‐
3056 nent, Directory. If omitted, CPack will build an installer that
3057 installs everything.
3058 CPACK_SYSTEM_NAME
3060 System name, defaults to the value of CMAKE_SYSTEM_NAME, except
3061 on Windows where it will be win32 or win64.
3062 CPACK_PACKAGE_VERSION
3064 Package full version, used internally. By default, this is
3065 built from CPACK_PACKAGE_VERSION_MAJOR,
3066 CPACK_PACKAGE_VERSION_MINOR, and CPACK_PACKAGE_VERSION_PATCH.
3067 CPACK_TOPLEVEL_TAG
3069 Directory for the installed files.
3070 CPACK_INSTALL_COMMANDS
3072 Extra commands to install components. The environment variable
3073 CMAKE_INSTALL_PREFIX is set to the temporary install directory
3074 during execution.
3075 CPACK_INSTALL_SCRIPTS
3077 Extra CMake scripts executed by CPack during its local staging
3078 installation, which is done right before packaging the files.
3079 The scripts are not called by a standalone install (e.g.: make
3080 install). For every script, the following variables will be
3081 set: CMAKE_CURRENT_SOURCE_DIR, CMAKE_CURRENT_BINARY_DIR and
3082 CMAKE_INSTALL_PREFIX (which is set to the staging install direc‐
3083 tory). The singular form CMAKE_INSTALL_SCRIPT is supported as
3084 an alternative variable for historical reasons, but its value is
3085 ignored if CMAKE_INSTALL_SCRIPTS is set and a warning will be
3086 issued.
3087 CPACK_INSTALLED_DIRECTORIES
3089 Extra directories to install.
3090 CPACK_PACKAGE_INSTALL_REGISTRY_KEY
3092 Registry key used when installing this project. This is only
3093 used by installers for Windows. The default value is based on
3094 the installation directory.
3095 CPACK_CREATE_DESKTOP_LINKS
3097 List of desktop links to create. Each desktop link requires a
3098 corresponding start menu shortcut as created by
3099 CPACK_PACKAGE_EXECUTABLES.
3100 CPACK_BINARY_<GENNAME>
3102 CPack generated options for binary generators. The CPack.cmake
3103 module generates (when CPACK_GENERATOR is not set) a set of
3104 CMake options (see CMake option() command) which may then be
3105 used to select the CPack generator(s) to be used when building
3106 the package target or when running cpack without the -G option.
3107 CSharpUtilities
3109 Functions to make configuration of CSharp/.NET targets easier.
3110 A collection of CMake utility functions useful for dealing with CSharp
3112 targets for Visual Studio generators from version 2010 and later.
3113 The following functions are provided by this module:
3115 Main functions
3117 · csharp_set_windows_forms_properties()
3119 · csharp_set_designer_cs_properties()
3121 · csharp_set_xaml_cs_properties()
3123 Helper functions
3125 · csharp_get_filename_keys()
3127 · csharp_get_filename_key_base()
3129 · csharp_get_dependentupon_name()
3131 Main functions provided by the module
3133 csharp_set_windows_forms_properties
3134 Sets source file properties for use of Windows Forms. Use this,
3135 if your CSharp target uses Windows Forms:
3136 csharp_set_windows_forms_properties([<file1> [<file2> [...]]])
3138 <fileN>
3140 List of all source files which are relevant for setting
3141 the VS_CSHARP_<tagname> properties (including .cs, .resx
3142 and .Designer.cs extensions).
3143 In the list of all given files for all files ending with
3145 .Designer.cs and .resx is searched. For every designer or
3146 resource file a file with the same base name but only .cs as
3147 extension is searched. If this is found, the VS_CSHARP_<tag‐
3148 name> properties are set as follows:
3149 for the .cs file:
3151 · VS_CSHARP_SubType “Form”
3153 for the .Designer.cs file (if it exists):
3155 · VS_CSHARP_DependentUpon <cs-filename>
3157 · VS_CSHARP_DesignTime “” (delete tag if previously
3159 defined)
3160 · VS_CSHARP_AutoGen “”(delete tag if previously defined)
3162 for the .resx file (if it exists):
3164 · VS_RESOURCE_GENERATOR “” (delete tag if previously
3166 defined)
3167 · VS_CSHARP_DependentUpon <cs-filename>
3169 · VS_CSHARP_SubType “Designer”
3171 csharp_set_designer_cs_properties
3173 Sets source file properties of .Designer.cs files depending on
3174 sibling filenames. Use this, if your CSharp target does not use
3175 Windows Forms (for Windows Forms use
3176 csharp_set_designer_cs_properties() instead):
3177 csharp_set_designer_cs_properties([<file1> [<file2> [...]]])
3179 <fileN>
3181 List of all source files which are relevant for setting
3182 the VS_CSHARP_<tagname> properties (including .cs, .resx,
3183 .settings and .Designer.cs extensions).
3184 In the list of all given files for all files ending with
3186 .Designer.cs is searched. For every designer file all files with
3187 the same base name but different extensions are searched. If a
3188 match is found, the source file properties of the designer file
3189 are set depending on the extension of the matched file:
3190 if match is .resx file:
3192 · VS_CSHARP_AutoGen “True”
3194 · VS_CSHARP_DesignTime “True”
3196 · VS_CSHARP_DependentUpon <resx-filename>
3198 if match is .cs file:
3200 · VS_CSHARP_DependentUpon <cs-filename>
3202 if match is .settings file:
3204 · VS_CSHARP_AutoGen “True”
3206 · VS_CSHARP_DesignTimeSharedInput “True”
3208 · VS_CSHARP_DependentUpon <settings-filename>
3210 NOTE:
3212 Because the source file properties of the .Designer.cs file are set
3213 according to the found matches and every match sets the
3214 VS_CSHARP_DependentUpon property, there should only be one match for
3215 each Designer.cs file.
3216 csharp_set_xaml_cs_properties
3218 Sets source file properties for use of Windows Presentation
3219 Foundation (WPF) and XAML. Use this, if your CSharp target uses
3220 WPF/XAML:
3221 csharp_set_xaml_cs_properties([<file1> [<file2> [...]]])
3223 <fileN>
3225 List of all source files which are relevant for setting
3226 the VS_CSHARP_<tagname> properties (including .cs, .xaml,
3227 and .xaml.cs extensions).
3228 In the list of all given files for all files ending with
3230 .xaml.cs is searched. For every xaml-cs file, a file with the
3231 same base name but extension .xaml is searched. If a match is
3232 found, the source file properties of the .xaml.cs file are set:
3233 · VS_CSHARP_DependentUpon <xaml-filename>
3235 Helper functions which are used by the above ones
3237 csharp_get_filename_keys
3238 Helper function which computes a list of key values to identify
3239 source files independently of relative/absolute paths given in
3240 cmake and eliminates case sensitivity:
3241 csharp_get_filename_keys(OUT [<file1> [<file2> [...]]])
3243 OUT Name of the variable in which the list of keys is stored
3245 <fileN>
3247 filename(s) as given to to CSharp target using
3248 add_library() or add_executable()
3249 In some way the function applies a canonicalization to the
3251 source names. This is necessary to find file matches if the
3252 files have been added to the target with different directory
3253 prefixes:
3254 add_library(lib
3256 myfile.cs
3257 ${CMAKE_CURRENT_SOURCE_DIR}/myfile.Designer.cs)
3258 set_source_files_properties(myfile.Designer.cs PROPERTIES
3260 VS_CSHARP_DependentUpon myfile.cs)
3261 # this will fail, because in cmake
3263 # - ${CMAKE_CURRENT_SOURCE_DIR}/myfile.Designer.cs
3264 # - myfile.Designer.cs
3265 # are not the same source file. The source file property is not set.
3266 csharp_get_filename_key_base
3268 Returns the full filepath and name without extension of a key.
3269 KEY is expected to be a key from csharp_get_filename_keys. In
3270 BASE the value of KEY without the file extension is returned:
3271 csharp_get_filename_key_base(BASE KEY)
3273 BASE Name of the variable with the computed “base” of KEY.
3275 KEY The key of which the base will be computed. Expected to
3277 be a upper case full filename.
3278 csharp_get_dependentupon_name
3280 Computes a string which can be used as value for the source file
3281 property VS_CSHARP_<tagname> with target being DependentUpon:
3282 csharp_get_dependentupon_name(NAME FILE)
3284 NAME Name of the variable with the result value
3286 FILE Filename to convert to <DependentUpon> value
3288 Actually this is only the filename without any path given at the
3290 moment.
3291 CTest
3293 Configure a project for testing with CTest/CDash
3294 Include this module in the top CMakeLists.txt file of a project to
3296 enable testing with CTest and dashboard submissions to CDash:
3297 project(MyProject)
3299 ...
3300 include(CTest)
3301 The module automatically creates a BUILD_TESTING option that selects
3303 whether to enable testing support (ON by default). After including the
3304 module, use code like:
3305 if(BUILD_TESTING)
3307 # ... CMake code to create tests ...
3308 endif()
3309 to creating tests when testing is enabled.
3311 To enable submissions to a CDash server, create a CTestConfig.cmake
3313 file at the top of the project with content such as:
3314 set(CTEST_NIGHTLY_START_TIME "01:00:00 UTC")
3316 set(CTEST_SUBMIT_URL "http://my.cdash.org/submit.php?project=MyProject")
3317 (the CDash server can provide the file to a project administrator who
3319 configures MyProject). Settings in the config file are shared by both
3320 this CTest module and the ctest(1) command-line Dashboard Client mode
3321 (ctest -S).
3322 While building a project for submission to CDash, CTest scans the build
3324 output for errors and warnings and reports them with surrounding con‐
3325 text from the build log. This generic approach works for all build
3326 tools, but does not give details about the command invocation that pro‐
3327 duced a given problem. One may get more detailed reports by setting
3328 the CTEST_USE_LAUNCHERS variable:
3329 set(CTEST_USE_LAUNCHERS 1)
3331 in the CTestConfig.cmake file.
3333 CTestCoverageCollectGCOV
3335 This module provides the ctest_coverage_collect_gcov function.
3336 This function runs gcov on all .gcda files found in the binary tree and
3338 packages the resulting .gcov files into a tar file. This tarball also
3339 contains the following:
3340 · data.json defines the source and build directories for use by CDash.
3342 · Labels.json indicates any LABELS that have been set on the source
3344 files.
3345 · The uncovered directory holds any uncovered files found by
3347 CTEST_EXTRA_COVERAGE_GLOB.
3348 After generating this tar file, it can be sent to CDash for display
3350 with the ctest_submit(CDASH_UPLOAD) command.
3351 ctest_coverage_collect_gcov
3353 ctest_coverage_collect_gcov(TARBALL <tarfile>
3355 [SOURCE <source_dir>][BUILD <build_dir>]
3356 [GCOV_COMMAND <gcov_command>]
3357 [GCOV_OPTIONS <options>...]
3358 )
3359 Run gcov and package a tar file for CDash. The options are:
3361 TARBALL <tarfile>
3363 Specify the location of the .tar file to be created for
3364 later upload to CDash. Relative paths will be inter‐
3365 preted with respect to the top-level build directory.
3366 SOURCE <source_dir>
3368 Specify the top-level source directory for the build.
3369 Default is the value of CTEST_SOURCE_DIRECTORY.
3370 BUILD <build_dir>
3372 Specify the top-level build directory for the build.
3373 Default is the value of CTEST_BINARY_DIRECTORY.
3374 GCOV_COMMAND <gcov_command>
3376 Specify the full path to the gcov command on the machine.
3377 Default is the value of CTEST_COVERAGE_COMMAND.
3378 GCOV_OPTIONS <options>...
3380 Specify options to be passed to gcov. The gcov command
3381 is run as gcov <options>... -o <gcov-dir> <file>.gcda.
3382 If not specified, the default option is just -b -x.
3383 GLOB Recursively search for .gcda files in build_dir rather
3385 than determining search locations by reading TargetDirec‐
3386 tories.txt.
3387 DELETE Delete coverage files after they’ve been packaged into
3389 the .tar.
3390 QUIET Suppress non-error messages that otherwise would have
3392 been printed out by this function.
3393 CTestScriptMode
3395 This file is read by ctest in script mode (-S)
3396 CTestUseLaunchers
3398 Set the RULE_LAUNCH_* global properties when CTEST_USE_LAUNCHERS is on.
3399 CTestUseLaunchers is automatically included when you include(CTest).
3401 However, it is split out into its own module file so projects can use
3402 the CTEST_USE_LAUNCHERS functionality independently.
3403 To use launchers, set CTEST_USE_LAUNCHERS to ON in a ctest -S dashboard
3405 script, and then also set it in the cache of the configured project.
3406 Both cmake and ctest need to know the value of it for the launchers to
3407 work properly. CMake needs to know in order to generate proper build
3408 rules, and ctest, in order to produce the proper error and warning
3409 analysis.
3410 For convenience, you may set the ENV variable CTEST_USE_LAUNCH‐
3412 ERS_DEFAULT in your ctest -S script, too. Then, as long as your CMake‐
3413 Lists uses include(CTest) or include(CTestUseLaunchers), it will use
3414 the value of the ENV variable to initialize a CTEST_USE_LAUNCHERS cache
3415 variable. This cache variable initialization only occurs if
3416 CTEST_USE_LAUNCHERS is not already defined. If CTEST_USE_LAUNCHERS is
3417 on in a ctest -S script the ctest_configure command will add
3418 -DCTEST_USE_LAUNCHERS:BOOL=TRUE to the cmake command used to configure
3419 the project.
3420 Dart
3422 Configure a project for testing with CTest or old Dart Tcl Client
3423 This file is the backwards-compatibility version of the CTest module.
3425 It supports using the old Dart 1 Tcl client for driving dashboard sub‐
3426 missions as well as testing with CTest. This module should be included
3427 in the CMakeLists.txt file at the top of a project. Typical usage:
3428 include(Dart)
3430 if(BUILD_TESTING)
3431 # ... testing related CMake code ...
3432 endif()
3433 The BUILD_TESTING option is created by the Dart module to determine
3435 whether testing support should be enabled. The default is ON.
3436 DeployQt4
3438 Functions to help assemble a standalone Qt4 executable.
3439 A collection of CMake utility functions useful for deploying Qt4 exe‐
3441 cutables.
3442 The following functions are provided by this module:
3444 write_qt4_conf
3446 resolve_qt4_paths
3447 fixup_qt4_executable
3448 install_qt4_plugin_path
3449 install_qt4_plugin
3450 install_qt4_executable
3451 Requires CMake 2.6 or greater because it uses function and PAR‐
3453 ENT_SCOPE. Also depends on BundleUtilities.cmake.
3454 write_qt4_conf(<qt_conf_dir> <qt_conf_contents>)
3456 Writes a qt.conf file with the <qt_conf_contents> into <qt_conf_dir>.
3458 resolve_qt4_paths(<paths_var> [<executable_path>])
3460 Loop through <paths_var> list and if any don’t exist resolve them rela‐
3462 tive to the <executable_path> (if supplied) or the CMAKE_INSTALL_PRE‐
3463 FIX.
3464 fixup_qt4_executable(<executable>
3466 [<qtplugins> <libs> <dirs> <plugins_dir> <request_qt_conf>])
3467 Copies Qt plugins, writes a Qt configuration file (if needed) and fixes
3469 up a Qt4 executable using BundleUtilities so it is standalone and can
3470 be drag-and-drop copied to another machine as long as all of the system
3471 libraries are compatible.
3472 <executable> should point to the executable to be fixed-up.
3474 <qtplugins> should contain a list of the names or paths of any Qt plug‐
3476 ins to be installed.
3477 <libs> will be passed to BundleUtilities and should be a list of any
3479 already installed plugins, libraries or executables to also be
3480 fixed-up.
3481 <dirs> will be passed to BundleUtilities and should contain and direc‐
3483 tories to be searched to find library dependencies.
3484 <plugins_dir> allows an custom plugins directory to be used.
3486 <request_qt_conf> will force a qt.conf file to be written even if not
3488 needed.
3489 install_qt4_plugin_path(plugin executable copy installed_plugin_path_var
3491 <plugins_dir> <component> <configurations>)
3492 Install (or copy) a resolved <plugin> to the default plugins directory
3494 (or <plugins_dir>) relative to <executable> and store the result in
3495 <installed_plugin_path_var>.
3496 If <copy> is set to TRUE then the plugins will be copied rather than
3498 installed. This is to allow this module to be used at CMake time
3499 rather than install time.
3500 If <component> is set then anything installed will use this COMPONENT.
3502 install_qt4_plugin(plugin executable copy installed_plugin_path_var
3504 <plugins_dir> <component>)
3505 Install (or copy) an unresolved <plugin> to the default plugins direc‐
3507 tory (or <plugins_dir>) relative to <executable> and store the result
3508 in <installed_plugin_path_var>. See documentation of INSTALL_QT4_PLUG‐
3509 IN_PATH.
3510 install_qt4_executable(<executable>
3512 [<qtplugins> <libs> <dirs> <plugins_dir> <request_qt_conf> <component>])
3513 Installs Qt plugins, writes a Qt configuration file (if needed) and
3515 fixes up a Qt4 executable using BundleUtilities so it is standalone and
3516 can be drag-and-drop copied to another machine as long as all of the
3517 system libraries are compatible. The executable will be fixed-up at
3518 install time. <component> is the COMPONENT used for bundle fixup and
3519 plugin installation. See documentation of FIXUP_QT4_BUNDLE.
3520 Documentation
3522 This module provides support for the VTK documentation framework. It
3523 relies on several tools (Doxygen, Perl, etc).
3524 ExternalData
3526 Manage data files stored outside source tree
3527 Introduction
3529 Use this module to unambiguously reference data files stored outside
3530 the source tree and fetch them at build time from arbitrary local and
3531 remote content-addressed locations. Functions provided by this module
3532 recognize arguments with the syntax DATA{<name>} as references to
3533 external data, replace them with full paths to local copies of those
3534 data, and create build rules to fetch and update the local copies.
3535 For example:
3537 include(ExternalData)
3539 set(ExternalData_URL_TEMPLATES "file:///local/%(algo)/%(hash)"
3540 "file:////host/share/%(algo)/%(hash)"
3541 "http://data.org/%(algo)/%(hash)")
3542 ExternalData_Add_Test(MyData
3543 NAME MyTest
3544 COMMAND MyExe DATA{MyInput.png}
3545 )
3546 ExternalData_Add_Target(MyData)
3547 When test MyTest runs the DATA{MyInput.png} argument will be replaced
3549 by the full path to a real instance of the data file MyInput.png on
3550 disk. If the source tree contains a content link such as MyIn‐
3551 put.png.md5 then the MyData target creates a real MyInput.png in the
3552 build tree.
3553 Module Functions
3555 ExternalData_Expand_Arguments
3556 The ExternalData_Expand_Arguments function evaluates DATA{} ref‐
3557 erences in its arguments and constructs a new list of arguments:
3558 ExternalData_Expand_Arguments(
3560 <target> # Name of data management target
3561 <outVar> # Output variable
3562 [args...] # Input arguments, DATA{} allowed
3563 )
3564 It replaces each DATA{} reference in an argument with the full
3566 path of a real data file on disk that will exist after the <tar‐
3567 get> builds.
3568 ExternalData_Add_Test
3570 The ExternalData_Add_Test function wraps around the CMake
3571 add_test() command but supports DATA{} references in its argu‐
3572 ments:
3573 ExternalData_Add_Test(
3575 <target> # Name of data management target
3576 ... # Arguments of add_test(), DATA{} allowed
3577 )
3578 It passes its arguments through ExternalData_Expand_Arguments
3580 and then invokes the add_test() command using the results.
3581 ExternalData_Add_Target
3583 The ExternalData_Add_Target function creates a custom target to
3584 manage local instances of data files stored externally:
3585 ExternalData_Add_Target(
3587 <target> # Name of data management target
3588 )
3589 It creates custom commands in the target as necessary to make
3591 data files available for each DATA{} reference previously evalu‐
3592 ated by other functions provided by this module. Data files may
3593 be fetched from one of the URL templates specified in the Exter‐
3594 nalData_URL_TEMPLATES variable, or may be found locally in one
3595 of the paths specified in the ExternalData_OBJECT_STORES vari‐
3596 able.
3597 Typically only one target is needed to manage all external data
3599 within a project. Call this function once at the end of config‐
3600 uration after all data references have been processed.
3601 Module Variables
3603 The following variables configure behavior. They should be set before
3604 calling any of the functions provided by this module.
3605 ExternalData_BINARY_ROOT
3607 The ExternalData_BINARY_ROOT variable may be set to the direc‐
3608 tory to hold the real data files named by expanded DATA{} refer‐
3609 ences. The default is CMAKE_BINARY_DIR. The directory layout
3610 will mirror that of content links under External‐
3611 Data_SOURCE_ROOT.
3612 ExternalData_CUSTOM_SCRIPT_<key>
3614 Specify a full path to a .cmake custom fetch script identified
3615 by <key> in entries of the ExternalData_URL_TEMPLATES list. See
3616 Custom Fetch Scripts.
3617 ExternalData_LINK_CONTENT
3619 The ExternalData_LINK_CONTENT variable may be set to the name of
3620 a supported hash algorithm to enable automatic conversion of
3621 real data files referenced by the DATA{} syntax into content
3622 links. For each such <file> a content link named <file><ext> is
3623 created. The original file is renamed to the form .External‐
3624 Data_<algo>_<hash> to stage it for future transmission to one of
3625 the locations in the list of URL templates (by means outside the
3626 scope of this module). The data fetch rule created for the con‐
3627 tent link will use the staged object if it cannot be found using
3628 any URL template.
3629 ExternalData_NO_SYMLINKS
3631 The real data files named by expanded DATA{} references may be
3632 made available under ExternalData_BINARY_ROOT using symbolic
3633 links on some platforms. The ExternalData_NO_SYMLINKS variable
3634 may be set to disable use of symbolic links and enable use of
3635 copies instead.
3636 ExternalData_OBJECT_STORES
3638 The ExternalData_OBJECT_STORES variable may be set to a list of
3639 local directories that store objects using the layout
3640 <dir>/%(algo)/%(hash). These directories will be searched first
3641 for a needed object. If the object is not available in any
3642 store then it will be fetched remotely using the URL templates
3643 and added to the first local store listed. If no stores are
3644 specified the default is a location inside the build tree.
3645 ExternalData_SERIES_PARSE
3647 ExternalData_SERIES_PARSE_PREFIX
3649 ExternalData_SERIES_PARSE_NUMBER
3651 ExternalData_SERIES_PARSE_SUFFIX
3653 ExternalData_SERIES_MATCH
3655 See Referencing File Series.
3656 ExternalData_SOURCE_ROOT
3658 The ExternalData_SOURCE_ROOT variable may be set to the highest
3659 source directory containing any path named by a DATA{} refer‐
3660 ence. The default is CMAKE_SOURCE_DIR. External‐
3661 Data_SOURCE_ROOT and CMAKE_SOURCE_DIR must refer to directories
3662 within a single source distribution (e.g. they come together in
3663 one tarball).
3664 ExternalData_TIMEOUT_ABSOLUTE
3666 The ExternalData_TIMEOUT_ABSOLUTE variable sets the download
3667 absolute timeout, in seconds, with a default of 300 seconds.
3668 Set to 0 to disable enforcement.
3669 ExternalData_TIMEOUT_INACTIVITY
3671 The ExternalData_TIMEOUT_INACTIVITY variable sets the download
3672 inactivity timeout, in seconds, with a default of 60 seconds.
3673 Set to 0 to disable enforcement.
3674 ExternalData_URL_ALGO_<algo>_<key>
3676 Specify a custom URL component to be substituted for URL tem‐
3677 plate placeholders of the form %(algo:<key>), where <key> is a
3678 valid C identifier, when fetching an object referenced via hash
3679 algorithm <algo>. If not defined, the default URL component is
3680 just <algo> for any <key>.
3681 ExternalData_URL_TEMPLATES
3683 The ExternalData_URL_TEMPLATES may be set to provide a list of
3684 of URL templates using the placeholders %(algo) and %(hash) in
3685 each template. Data fetch rules try each URL template in order
3686 by substituting the hash algorithm name for %(algo) and the hash
3687 value for %(hash). Alternatively one may use %(algo:<key>) with
3688 ExternalData_URL_ALGO_<algo>_<key> variables to gain more flexi‐
3689 bility in remote URLs.
3690 Referencing Files
3692 Referencing Single Files
3693 The DATA{} syntax is literal and the <name> is a full or relative path
3694 within the source tree. The source tree must contain either a real
3695 data file at <name> or a “content link” at <name><ext> containing a
3696 hash of the real file using a hash algorithm corresponding to <ext>.
3697 For example, the argument DATA{img.png} may be satisfied by either a
3698 real img.png file in the current source directory or a img.png.md5 file
3699 containing its MD5 sum.
3700 Multiple content links of the same name with different hash algorithms
3702 are supported (e.g. img.png.sha256 and img.png.sha1) so long as they
3703 all correspond to the same real file. This allows objects to be
3704 fetched from sources indexed by different hash algorithms.
3705 Referencing File Series
3707 The DATA{} syntax can be told to fetch a file series using the form
3708 DATA{<name>,:}, where the : is literal. If the source tree contains a
3709 group of files or content links named like a series then a reference to
3710 one member adds rules to fetch all of them. Although all members of a
3711 series are fetched, only the file originally named by the DATA{} argu‐
3712 ment is substituted for it. The default configuration recognizes file
3713 series names ending with #.ext, _#.ext, .#.ext, or -#.ext where # is a
3714 sequence of decimal digits and .ext is any single extension. Configure
3715 it with a regex that parses <number> and <suffix> parts from the end of
3716 <name>:
3717 ExternalData_SERIES_PARSE = regex of the form (<number>)(<suffix>)$
3719 For more complicated cases set:
3721 ExternalData_SERIES_PARSE = regex with at least two () groups
3723 ExternalData_SERIES_PARSE_PREFIX = <prefix> regex group number, if any
3724 ExternalData_SERIES_PARSE_NUMBER = <number> regex group number
3725 ExternalData_SERIES_PARSE_SUFFIX = <suffix> regex group number
3726 Configure series number matching with a regex that matches the <number>
3728 part of series members named <prefix><number><suffix>:
3729 ExternalData_SERIES_MATCH = regex matching <number> in all series members
3731 Note that the <suffix> of a series does not include a hash-algorithm
3733 extension.
3734 Referencing Associated Files
3736 The DATA{} syntax can alternatively match files associated with the
3737 named file and contained in the same directory. Associated files may
3738 be specified by options using the syntax
3739 DATA{<name>,<opt1>,<opt2>,...}. Each option may specify one file by
3740 name or specify a regular expression to match file names using the syn‐
3741 tax REGEX:<regex>. For example, the arguments:
3742 DATA{MyData/MyInput.mhd,MyInput.img} # File pair
3744 DATA{MyData/MyFrames00.png,REGEX:MyFrames[0-9]+\\.png} # Series
3745 will pass MyInput.mha and MyFrames00.png on the command line but ensure
3747 that the associated files are present next to them.
3748 Referencing Directories
3750 The DATA{} syntax may reference a directory using a trailing slash and
3751 a list of associated files. The form DATA{<name>/,<opt1>,<opt2>,...}
3752 adds rules to fetch any files in the directory that match one of the
3753 associated file options. For example, the argument
3754 DATA{MyDataDir/,REGEX:.*} will pass the full path to a MyDataDir direc‐
3755 tory on the command line and ensure that the directory contains files
3756 corresponding to every file or content link in the MyDataDir source
3757 directory. In order to match associated files in subdirectories, spec‐
3758 ify a RECURSE: option, e.g. DATA{MyDataDir/,RECURSE:,REGEX:.*}.
3759 Hash Algorithms
3761 The following hash algorithms are supported:
3762 %(algo) <ext> Description
3764 ------- ----- -----------
3765 MD5 .md5 Message-Digest Algorithm 5, RFC 1321
3766 SHA1 .sha1 US Secure Hash Algorithm 1, RFC 3174
3767 SHA224 .sha224 US Secure Hash Algorithms, RFC 4634
3768 SHA256 .sha256 US Secure Hash Algorithms, RFC 4634
3769 SHA384 .sha384 US Secure Hash Algorithms, RFC 4634
3770 SHA512 .sha512 US Secure Hash Algorithms, RFC 4634
3771 SHA3_224 .sha3-224 Keccak SHA-3
3772 SHA3_256 .sha3-256 Keccak SHA-3
3773 SHA3_384 .sha3-384 Keccak SHA-3
3774 SHA3_512 .sha3-512 Keccak SHA-3
3775 Note that the hashes are used only for unique data identification and
3777 download verification.
3778 Custom Fetch Scripts
3780 When a data file must be fetched from one of the URL templates speci‐
3781 fied in the ExternalData_URL_TEMPLATES variable, it is normally down‐
3782 loaded using the file(DOWNLOAD) command. One may specify usage of a
3783 custom fetch script by using a URL template of the form ExternalData‐
3784 CustomScript://<key>/<loc>. The <key> must be a C identifier, and the
3785 <loc> must contain the %(algo) and %(hash) placeholders. A variable
3786 corresponding to the key, ExternalData_CUSTOM_SCRIPT_<key>, must be set
3787 to the full path to a .cmake script file. The script will be included
3788 to perform the actual fetch, and provided with the following variables:
3789 ExternalData_CUSTOM_LOCATION
3791 When a custom fetch script is loaded, this variable is set to
3792 the location part of the URL, which will contain the substituted
3793 hash algorithm name and content hash value.
3794 ExternalData_CUSTOM_FILE
3796 When a custom fetch script is loaded, this variable is set to
3797 the full path to a file in which the script must store the
3798 fetched content. The name of the file is unspecified and should
3799 not be interpreted in any way.
3800 The custom fetch script is expected to store fetched content in the
3802 file or set a variable:
3803 ExternalData_CUSTOM_ERROR
3805 When a custom fetch script fails to fetch the requested content,
3806 it must set this variable to a short one-line message describing
3807 the reason for failure.
3808 ExternalProject
3810 External Project Definition
3811 ExternalProject_Add
3812 The ExternalProject_Add() function creates a custom target to
3813 drive download, update/patch, configure, build, install and test
3814 steps of an external project:
3815 ExternalProject_Add(<name> [<option>...])
3817 The individual steps within the process can be driven indepen‐
3819 dently if required (e.g. for CDash submission) and extra custom
3820 steps can be defined, along with the ability to control the step
3821 dependencies. The directory structure used for the management of
3822 the external project can also be customized. The function sup‐
3823 ports a large number of options which can be used to tailor the
3824 external project behavior.
3825 Directory Options:
3827 Most of the time, the default directory layout is suffi‐
3828 cient. It is largely an implementation detail that the
3829 main project usually doesn’t need to change. In some cir‐
3830 cumstances, however, control over the directory layout
3831 can be useful or necessary. The directory options are
3832 potentially more useful from the point of view that the
3833 main build can use the ExternalProject_Get_Property()
3834 command to retrieve their values, thereby allowing the
3835 main project to refer to build artifacts of the external
3836 project.
3837 PREFIX <dir>
3839 Root directory for the external project. Unless
3840 otherwise noted below, all other directories asso‐
3841 ciated with the external project will be created
3842 under here.
3843 TMP_DIR <dir>
3845 Directory in which to store temporary files.
3846 STAMP_DIR <dir>
3848 Directory in which to store the timestamps of each
3849 step. Log files from individual steps are also
3850 created in here unless overridden by LOG_DIR (see
3851 Logging Options below).
3852 LOG_DIR <dir>
3854 Directory in which to store the logs of each step.
3855 DOWNLOAD_DIR <dir>
3857 Directory in which to store downloaded files
3858 before unpacking them. This directory is only used
3859 by the URL download method, all other download
3860 methods use SOURCE_DIR directly instead.
3861 SOURCE_DIR <dir>
3863 Source directory into which downloaded contents
3864 will be unpacked, or for non-URL download methods,
3865 the directory in which the repository should be
3866 checked out, cloned, etc. If no download method is
3867 specified, this must point to an existing direc‐
3868 tory where the external project has already been
3869 unpacked or cloned/checked out.
3870 NOTE:
3872 If a download method is specified, any existing
3873 contents of the source directory may be
3874 deleted. Only the URL download method checks
3875 whether this directory is either missing or
3876 empty before initiating the download, stopping
3877 with an error if it is not empty. All other
3878 download methods silently discard any previous
3879 contents of the source directory.
3880 BINARY_DIR <dir>
3882 Specify the build directory location. This option
3883 is ignored if BUILD_IN_SOURCE is enabled.
3884 INSTALL_DIR <dir>
3886 Installation prefix to be placed in the
3887 <INSTALL_DIR> placeholder. This does not actually
3888 configure the external project to install to the
3889 given prefix. That must be done by passing appro‐
3890 priate arguments to the external project configu‐
3891 ration step, e.g. using <INSTALL_DIR>.
3892 If any of the above ..._DIR options are not specified,
3894 their defaults are computed as follows. If the PREFIX
3895 option is given or the EP_PREFIX directory property is
3896 set, then an external project is built and installed
3897 under the specified prefix:
3898 TMP_DIR = <prefix>/tmp
3900 STAMP_DIR = <prefix>/src/<name>-stamp
3901 DOWNLOAD_DIR = <prefix>/src
3902 SOURCE_DIR = <prefix>/src/<name>
3903 BINARY_DIR = <prefix>/src/<name>-build
3904 INSTALL_DIR = <prefix>
3905 LOG_DIR = <STAMP_DIR>
3906 Otherwise, if the EP_BASE directory property is set then
3908 components of an external project are stored under the
3909 specified base:
3910 TMP_DIR = <base>/tmp/<name>
3912 STAMP_DIR = <base>/Stamp/<name>
3913 DOWNLOAD_DIR = <base>/Download/<name>
3914 SOURCE_DIR = <base>/Source/<name>
3915 BINARY_DIR = <base>/Build/<name>
3916 INSTALL_DIR = <base>/Install/<name>
3917 LOG_DIR = <STAMP_DIR>
3918 If no PREFIX, EP_PREFIX, or EP_BASE is specified, then
3920 the default is to set PREFIX to <name>-prefix. Relative
3921 paths are interpreted with respect to CMAKE_CUR‐
3922 RENT_BINARY_DIR at the point where ExternalProject_Add()
3923 is called.
3924 Download Step Options:
3926 A download method can be omitted if the SOURCE_DIR option
3927 is used to point to an existing non-empty directory. Oth‐
3928 erwise, one of the download methods below must be speci‐
3929 fied (multiple download methods should not be given) or a
3930 custom DOWNLOAD_COMMAND provided.
3931 DOWNLOAD_COMMAND <cmd>...
3933 Overrides the command used for the download step
3934 (generator expressions are supported). If this
3935 option is specified, all other download options
3936 will be ignored. Providing an empty string for
3937 <cmd> effectively disables the download step.
3938 URL Download
3940 URL <url1> [<url2>...]
3942 List of paths and/or URL(s) of the external
3943 project’s source. When more than one URL is
3944 given, they are tried in turn until one
3945 succeeds. A URL may be an ordinary path in
3946 the local file system (in which case it
3947 must be the only URL provided) or any down‐
3948 loadable URL supported by the file(DOWN‐
3949 LOAD) command. A local filesystem path may
3950 refer to either an existing directory or to
3951 an archive file, whereas a URL is expected
3952 to point to a file which can be treated as
3953 an archive. When an archive is used, it
3954 will be unpacked automatically unless the
3955 DOWNLOAD_NO_EXTRACT option is set to pre‐
3956 vent it. The archive type is determined by
3957 inspecting the actual content rather than
3958 using logic based on the file extension.
3959 URL_HASH <algo>=<hashValue>
3961 Hash of the archive file to be downloaded.
3962 The argument should be of the form
3963 <algo>=<hashValue> where algo can be any of
3964 the hashing algorithms supported by the
3965 file() command. Specifying this option is
3966 strongly recommended for URL downloads, as
3967 it ensures the integrity of the downloaded
3968 content. It is also used as a check for a
3969 previously downloaded file, allowing con‐
3970 nection to the remote location to be
3971 avoided altogether if the local directory
3972 already has a file from an earlier download
3973 that matches the specified hash.
3974 URL_MD5 <md5>
3976 Equivalent to URL_HASH MD5=<md5>.
3977 DOWNLOAD_NAME <fname>
3979 File name to use for the downloaded file.
3980 If not given, the end of the URL is used to
3981 determine the file name. This option is
3982 rarely needed, the default name is gener‐
3983 ally suitable and is not normally used out‐
3984 side of code internal to the ExternalPro‐
3985 ject module.
3986 DOWNLOAD_NO_EXTRACT <bool>
3988 Allows the extraction part of the download
3989 step to be disabled by passing a boolean
3990 true value for this option. If this option
3991 is not given, the downloaded contents will
3992 be unpacked automatically if required. If
3993 extraction has been disabled, the full path
3994 to the downloaded file is available as
3995 <DOWNLOADED_FILE> in subsequent steps or as
3996 the property DOWNLOADED_FILE with the
3997 ExternalProject_Get_Property() command.
3998 DOWNLOAD_NO_PROGRESS <bool>
4000 Can be used to disable logging the download
4001 progress. If this option is not given,
4002 download progress messages will be logged.
4003 TIMEOUT <seconds>
4005 Maximum time allowed for file download
4006 operations.
4007 HTTP_USERNAME <username>
4009 Username for the download operation if
4010 authentication is required.
4011 HTTP_PASSWORD <password>
4013 Password for the download operation if
4014 authentication is required.
4015 HTTP_HEADER <header1> [<header2>...]
4017 Provides an arbitrary list of HTTP headers
4018 for the download operation. This can be
4019 useful for accessing content in systems
4020 like AWS, etc.
4021 TLS_VERIFY <bool>
4023 Specifies whether certificate verification
4024 should be performed for https URLs. If this
4025 option is not provided, the default behav‐
4026 ior is determined by the CMAKE_TLS_VERIFY
4027 variable (see file(DOWNLOAD)). If that is
4028 also not set, certificate verification will
4029 not be performed. In situations where
4030 URL_HASH cannot be provided, this option
4031 can be an alternative verification measure.
4032 TLS_CAINFO <file>
4034 Specify a custom certificate authority file
4035 to use if TLS_VERIFY is enabled. If this
4036 option is not specified, the value of the
4037 CMAKE_TLS_CAINFO variable will be used
4038 instead (see file(DOWNLOAD))
4039 NETRC <level>
4041 Specify whether the .netrc file is to be
4042 used for operation. If this option is not
4043 specified, the value of the CMAKE_NETRC
4044 variable will be used instead (see
4045 file(DOWNLOAD)) Valid levels are:
4046 IGNORED
4048 The .netrc file is ignored. This is
4049 the default.
4050 OPTIONAL
4052 The .netrc file is optional, and
4053 information in the URL is preferred.
4054 The file will be scanned to find
4055 which ever information is not speci‐
4056 fied in the URL.
4057 REQUIRED
4059 The .netrc file is required, and
4060 information in the URL is ignored.
4061 NETRC_FILE <file>
4063 Specify an alternative .netrc file to the
4064 one in your home directory if the NETRC
4065 level is OPTIONAL or REQUIRED. If this
4066 option is not specified, the value of the
4067 CMAKE_NETRC_FILE variable will be used
4068 instead (see file(DOWNLOAD))
4069 Git NOTE: A git version of 1.6.5 or later is required
4071 if this download method is used.
4072 GIT_REPOSITORY <url>
4074 URL of the git repository. Any URL under‐
4075 stood by the git command may be used.
4076 GIT_TAG <tag>
4078 Git branch name, tag or commit hash. Note
4079 that branch names and tags should generally
4080 be specified as remote names (i.e. ori‐
4081 gin/myBranch rather than simply myBranch).
4082 This ensures that if the remote end has its
4083 tag moved or branch rebased or history
4084 rewritten, the local clone will still be
4085 updated correctly. In general, however,
4086 specifying a commit hash should be pre‐
4087 ferred for a number of reasons:
4088 · If the local clone already has the commit
4090 corresponding to the hash, no git fetch
4091 needs to be performed to check for
4092 changes each time CMake is re-run. This
4093 can result in a significant speed up if
4094 many external projects are being used.
4095 · Using a specific git hash ensures that
4097 the main project’s own history is fully
4098 traceable to a specific point in the
4099 external project’s evolution. If a branch
4100 or tag name is used instead, then check‐
4101 ing out a specific commit of the main
4102 project doesn’t necessarily pin the whole
4103 build to a specific point in the life of
4104 the external project. The lack of such
4105 deterministic behavior makes the main
4106 project lose traceability and repeatabil‐
4107 ity.
4108 If GIT_SHALLOW is enabled then GIT_TAG
4110 works only with branch names and tags. A
4111 commit hash is not allowed.
4112 GIT_REMOTE_NAME <name>
4114 The optional name of the remote. If this
4115 option is not specified, it defaults to
4116 origin.
4117 GIT_SUBMODULES <module>...
4119 Specific git submodules that should also be
4120 updated. If this option is not provided,
4121 all git submodules will be updated. When
4122 CMP0097 is set to NEW if this value is set
4123 to an empty string then no submodules are
4124 initialized or updated.
4125 GIT_SUBMODULES_RECURSE <bool>
4127 Specify whether git submodules (if any)
4128 should update recursively by passing the
4129 --recursive flag to git submodule update.
4130 If not specified, the default is on.
4131 GIT_SHALLOW <bool>
4133 When this option is enabled, the git clone
4134 operation will be given the --depth 1
4135 option. This performs a shallow clone,
4136 which avoids downloading the whole history
4137 and instead retrieves just the commit
4138 denoted by the GIT_TAG option.
4139 GIT_PROGRESS <bool>
4141 When enabled, this option instructs the git
4142 clone operation to report its progress by
4143 passing it the --progress option. Without
4144 this option, the clone step for large
4145 projects may appear to make the build
4146 stall, since nothing will be logged until
4147 the clone operation finishes. While this
4148 option can be used to provide progress to
4149 prevent the appearance of the build having
4150 stalled, it may also make the build overly
4151 noisy if lots of external projects are
4152 used.
4153 GIT_CONFIG <option1> [<option2>...]
4155 Specify a list of config options to pass to
4156 git clone. Each option listed will be
4157 transformed into its own --config <option>
4158 on the git clone command line, with each
4159 option required to be in the form
4160 key=value.
4161 Subversion
4163 SVN_REPOSITORY <url>
4165 URL of the Subversion repository.
4166 SVN_REVISION -r<rev>
4168 Revision to checkout from the Subversion
4169 repository.
4170 SVN_USERNAME <username>
4172 Username for the Subversion checkout and
4173 update.
4174 SVN_PASSWORD <password>
4176 Password for the Subversion checkout and
4177 update.
4178 SVN_TRUST_CERT <bool>
4180 Specifies whether to trust the Subversion
4181 server site certificate. If enabled, the
4182 --trust-server-cert option is passed to the
4183 svn checkout and update commands.
4184 Mercurial
4186 HG_REPOSITORY <url>
4188 URL of the mercurial repository.
4189 HG_TAG <tag>
4191 Mercurial branch name, tag or commit id.
4192 CVS
4194 CVS_REPOSITORY <cvsroot>
4196 CVSROOT of the CVS repository.
4197 CVS_MODULE <mod>
4199 Module to checkout from the CVS repository.
4200 CVS_TAG <tag>
4202 Tag to checkout from the CVS repository.
4203 Update/Patch Step Options:
4205 Whenever CMake is re-run, by default the external
4206 project’s sources will be updated if the download method
4207 supports updates (e.g. a git repository would be checked
4208 if the GIT_TAG does not refer to a specific commit).
4209 UPDATE_COMMAND <cmd>...
4211 Overrides the download method’s update step with a
4212 custom command. The command may use generator
4213 expressions.
4214 UPDATE_DISCONNECTED <bool>
4216 When enabled, this option causes the update step
4217 to be skipped. It does not, however, prevent the
4218 download step. The update step can still be added
4219 as a step target (see
4220 ExternalProject_Add_StepTargets()) and called man‐
4221 ually. This is useful if you want to allow devel‐
4222 opers to build the project when disconnected from
4223 the network (the network may still be needed for
4224 the download step though).
4225 When this option is present, it is generally
4227 advisable to make the value a cache variable under
4228 the developer’s control rather than hard-coding
4229 it. If this option is not present, the default
4230 value is taken from the EP_UPDATE_DISCONNECTED
4231 directory property. If that is also not defined,
4232 updates are performed as normal. The
4233 EP_UPDATE_DISCONNECTED directory property is
4234 intended as a convenience for controlling the
4235 UPDATE_DISCONNECTED behavior for an entire section
4236 of a project’s directory hierarchy and may be a
4237 more convenient method of giving developers con‐
4238 trol over whether or not to perform updates
4239 (assuming the project also provides a cache vari‐
4240 able or some other convenient method for setting
4241 the directory property).
4242 PATCH_COMMAND <cmd>...
4244 Specifies a custom command to patch the sources
4245 after an update. By default, no patch command is
4246 defined. Note that it can be quite difficult to
4247 define an appropriate patch command that performs
4248 robustly, especially for download methods such as
4249 git where changing the GIT_TAG will not discard
4250 changes from a previous patch, but the patch com‐
4251 mand will be called again after updating to the
4252 new tag.
4253 Configure Step Options:
4255 The configure step is run after the download and update
4256 steps. By default, the external project is assumed to be
4257 a CMake project, but this can be overridden if required.
4258 CONFIGURE_COMMAND <cmd>...
4260 The default configure command runs CMake with
4261 options based on the main project. For non-CMake
4262 external projects, the CONFIGURE_COMMAND option
4263 must be used to override this behavior (generator
4264 expressions are supported). For projects that
4265 require no configure step, specify this option
4266 with an empty string as the command to execute.
4267 CMAKE_COMMAND /.../cmake
4269 Specify an alternative cmake executable for the
4270 configure step (use an absolute path). This is
4271 generally not recommended, since it is usually
4272 desirable to use the same CMake version throughout
4273 the whole build. This option is ignored if a cus‐
4274 tom configure command has been specified with CON‐
4275 FIGURE_COMMAND.
4276 CMAKE_GENERATOR <gen>
4278 Override the CMake generator used for the config‐
4279 ure step. Without this option, the same generator
4280 as the main build will be used. This option is
4281 ignored if a custom configure command has been
4282 specified with the CONFIGURE_COMMAND option.
4283 CMAKE_GENERATOR_PLATFORM <platform>
4285 Pass a generator-specific platform name to the
4286 CMake command (see CMAKE_GENERATOR_PLATFORM). It
4287 is an error to provide this option without the
4288 CMAKE_GENERATOR option.
4289 CMAKE_GENERATOR_TOOLSET <toolset>
4291 Pass a generator-specific toolset name to the
4292 CMake command (see CMAKE_GENERATOR_TOOLSET). It is
4293 an error to provide this option without the
4294 CMAKE_GENERATOR option.
4295 CMAKE_GENERATOR_INSTANCE <instance>
4297 Pass a generator-specific instance selection to
4298 the CMake command (see CMAKE_GENERATOR_INSTANCE).
4299 It is an error to provide this option without the
4300 CMAKE_GENERATOR option.
4301 CMAKE_ARGS <arg>...
4303 The specified arguments are passed to the cmake
4304 command line. They can be any argument the cmake
4305 command understands, not just cache values defined
4306 by -D... arguments (see also CMake Options). In
4307 addition, arguments may use generator expressions.
4308 CMAKE_CACHE_ARGS <arg>...
4310 This is an alternate way of specifying cache vari‐
4311 ables where command line length issues may become
4312 a problem. The arguments are expected to be in the
4313 form -Dvar:STRING=value, which are then trans‐
4314 formed into CMake set() commands with the FORCE
4315 option used. These set() commands are written to a
4316 pre-load script which is then applied using the
4317 cmake -C command line option. Arguments may use
4318 generator expressions.
4319 CMAKE_CACHE_DEFAULT_ARGS <arg>...
4321 This is the same as the CMAKE_CACHE_ARGS option
4322 except the set() commands do not include the FORCE
4323 keyword. This means the values act as initial
4324 defaults only and will not override any variables
4325 already set from a previous run. Use this option
4326 with care, as it can lead to different behavior
4327 depending on whether the build starts from a fresh
4328 build directory or re-uses previous build con‐
4329 tents.
4330 If the CMake generator is the Green Hills MULTI
4332 and not overridden then the original project’s
4333 settings for the GHS toolset and target system
4334 customization cache variables are propagated into
4335 the external project.
4336 SOURCE_SUBDIR <dir>
4338 When no CONFIGURE_COMMAND option is specified, the
4339 configure step assumes the external project has a
4340 CMakeLists.txt file at the top of its source tree
4341 (i.e. in SOURCE_DIR). The SOURCE_SUBDIR option can
4342 be used to point to an alternative directory
4343 within the source tree to use as the top of the
4344 CMake source tree instead. This must be a relative
4345 path and it will be interpreted as being relative
4346 to SOURCE_DIR. When BUILD_IN_SOURCE 1 is speci‐
4347 fied, the BUILD_COMMAND is used to point to an
4348 alternative directory within the source tree.
4349 Build Step Options:
4351 If the configure step assumed the external project uses
4352 CMake as its build system, the build step will also. Oth‐
4353 erwise, the build step will assume a Makefile-based build
4354 and simply run make with no arguments as the default
4355 build step. This can be overridden with custom build com‐
4356 mands if required.
4357 BUILD_COMMAND <cmd>...
4359 Overrides the default build command (generator
4360 expressions are supported). If this option is not
4361 given, the default build command will be chosen to
4362 integrate with the main build in the most appro‐
4363 priate way (e.g. using recursive make for Makefile
4364 generators or cmake --build if the project uses a
4365 CMake build). This option can be specified with an
4366 empty string as the command to make the build step
4367 do nothing.
4368 BUILD_IN_SOURCE <bool>
4370 When this option is enabled, the build will be
4371 done directly within the external project’s source
4372 tree. This should generally be avoided, the use of
4373 a separate build directory is usually preferred,
4374 but it can be useful when the external project
4375 assumes an in-source build. The BINARY_DIR option
4376 should not be specified if building in-source.
4377 BUILD_ALWAYS <bool>
4379 Enabling this option forces the build step to
4380 always be run. This can be the easiest way to
4381 robustly ensure that the external project’s own
4382 build dependencies are evaluated rather than rely‐
4383 ing on the default success timestamp-based method.
4384 This option is not normally needed unless develop‐
4385 ers are expected to modify something the external
4386 project’s build depends on in a way that is not
4387 detectable via the step target dependencies (e.g.
4388 SOURCE_DIR is used without a download method and
4389 developers might modify the sources in
4390 SOURCE_DIR).
4391 BUILD_BYPRODUCTS <file>...
4393 Specifies files that will be generated by the
4394 build command but which might or might not have
4395 their modification time updated by subsequent
4396 builds. These ultimately get passed through as
4397 BYPRODUCTS to the build step’s own underlying call
4398 to add_custom_command().
4399 Install Step Options:
4401 If the configure step assumed the external project uses
4402 CMake as its build system, the install step will also.
4403 Otherwise, the install step will assume a Makefile-based
4404 build and simply run make install as the default build
4405 step. This can be overridden with custom install commands
4406 if required.
4407 INSTALL_COMMAND <cmd>...
4409 The external project’s own install step is invoked
4410 as part of the main project’s build. It is done
4411 after the external project’s build step and may be
4412 before or after the external project’s test step
4413 (see the TEST_BEFORE_INSTALL option below). The
4414 external project’s install rules are not part of
4415 the main project’s install rules, so if anything
4416 from the external project should be installed as
4417 part of the main build, these need to be specified
4418 in the main build as additional install() com‐
4419 mands. The default install step builds the install
4420 target of the external project, but this can be
4421 overridden with a custom command using this option
4422 (generator expressions are supported). Passing an
4423 empty string as the <cmd> makes the install step
4424 do nothing.
4425 Test Step Options:
4427 The test step is only defined if at least one of the fol‐
4428 lowing TEST_... options are provided.
4429 TEST_COMMAND <cmd>...
4431 Overrides the default test command (generator
4432 expressions are supported). If this option is not
4433 given, the default behavior of the test step is to
4434 build the external project’s own test target. This
4435 option can be specified with <cmd> as an empty
4436 string, which allows the test step to still be
4437 defined, but it will do nothing. Do not specify
4438 any of the other TEST_... options if providing an
4439 empty string as the test command, but prefer to
4440 omit all TEST_... options altogether if the test
4441 step target is not needed.
4442 TEST_BEFORE_INSTALL <bool>
4444 When this option is enabled, the test step will be
4445 executed before the install step. The default
4446 behavior is for the test step to run after the
4447 install step.
4448 TEST_AFTER_INSTALL <bool>
4450 This option is mainly useful as a way to indicate
4451 that the test step is desired but all default
4452 behavior is sufficient. Specifying this option
4453 with a boolean true value ensures the test step is
4454 defined and that it comes after the install step.
4455 If both TEST_BEFORE_INSTALL and TEST_AFTER_INSTALL
4456 are enabled, the latter is silently ignored.
4457 TEST_EXCLUDE_FROM_MAIN <bool>
4459 If enabled, the main build’s default ALL target
4460 will not depend on the test step. This can be a
4461 useful way of ensuring the test step is defined
4462 but only gets invoked when manually requested.
4463 Output Logging Options:
4465 Each of the following LOG_... options can be used to wrap
4466 the relevant step in a script to capture its output to
4467 files. The log files will be created in LOG_DIR if sup‐
4468 plied or otherwise the STAMP_DIR directory with step-spe‐
4469 cific file names.
4470 LOG_DOWNLOAD <bool>
4472 When enabled, the output of the download step is
4473 logged to files.
4474 LOG_UPDATE <bool>
4476 When enabled, the output of the update step is
4477 logged to files.
4478 LOG_PATCH <bool>
4480 When enabled, the output of the patch step is
4481 logged to files.
4482 LOG_CONFIGURE <bool>
4484 When enabled, the output of the configure step is
4485 logged to files.
4486 LOG_BUILD <bool>
4488 When enabled, the output of the build step is
4489 logged to files.
4490 LOG_INSTALL <bool>
4492 When enabled, the output of the install step is
4493 logged to files.
4494 LOG_TEST <bool>
4496 When enabled, the output of the test step is
4497 logged to files.
4498 LOG_MERGED_STDOUTERR <bool>
4500 When enabled, stdout and stderr will be merged for
4501 any step whose output is being logged to files.
4502 LOG_OUTPUT_ON_FAILURE <bool>
4504 This option only has an effect if at least one of
4505 the other LOG_<step> options is enabled. If an
4506 error occurs for a step which has logging to file
4507 enabled, that step’s output will be printed to the
4508 console if LOG_OUTPUT_ON_FAILURE is set to true.
4509 For cases where a large amount of output is
4510 recorded, just the end of that output may be
4511 printed to the console.
4512 Terminal Access Options:
4514 Steps can be given direct access to the terminal in some
4515 cases. Giving a step access to the terminal may allow it
4516 to receive terminal input if required, such as for
4517 authentication details not provided by other options.
4518 With the Ninja generator, these options place the steps
4519 in the console job pool. Each step can be given access to
4520 the terminal individually via the following options:
4521 USES_TERMINAL_DOWNLOAD <bool>
4523 Give the download step access to the terminal.
4524 USES_TERMINAL_UPDATE <bool>
4526 Give the update step access to the terminal.
4527 USES_TERMINAL_CONFIGURE <bool>
4529 Give the configure step access to the terminal.
4530 USES_TERMINAL_BUILD <bool>
4532 Give the build step access to the terminal.
4533 USES_TERMINAL_INSTALL <bool>
4535 Give the install step access to the terminal.
4536 USES_TERMINAL_TEST <bool>
4538 Give the test step access to the terminal.
4539 Target Options:
4541 DEPENDS <targets>...
4543 Specify other targets on which the external
4544 project depends. The other targets will be brought
4545 up to date before any of the external project’s
4546 steps are executed. Because the external project
4547 uses additional custom targets internally for each
4548 step, the DEPENDS option is the most convenient
4549 way to ensure all of those steps depend on the
4550 other targets. Simply doing add_dependen‐
4551 cies(<name> <targets>) will not make any of the
4552 steps dependent on <targets>.
4553 EXCLUDE_FROM_ALL <bool>
4555 When enabled, this option excludes the external
4556 project from the default ALL target of the main
4557 build.
4558 STEP_TARGETS <step-target>...
4560 Generate custom targets for the specified steps.
4561 This is required if the steps need to be triggered
4562 manually or if they need to be used as dependen‐
4563 cies of other targets. If this option is not spec‐
4564 ified, the default value is taken from the
4565 EP_STEP_TARGETS directory property. See
4566 ExternalProject_Add_Step() below for further dis‐
4567 cussion of the effects of this option.
4568 INDEPENDENT_STEP_TARGETS <step-target>...
4570 Generate custom targets for the specified steps
4571 and prevent these targets from having the usual
4572 dependencies applied to them. If this option is
4573 not specified, the default value is taken from the
4574 EP_INDEPENDENT_STEP_TARGETS directory property.
4575 This option is mostly useful for allowing individ‐
4576 ual steps to be driven independently, such as for
4577 a CDash setup where each step should be initiated
4578 and reported individually rather than as one whole
4579 build. See ExternalProject_Add_Step() below for
4580 further discussion of the effects of this option.
4581 Miscellaneous Options:
4583 LIST_SEPARATOR <sep>
4585 For any of the various ..._COMMAND options,
4586 replace ; with <sep> in the specified command
4587 lines. This can be useful where list variables may
4588 be given in commands where they should end up as
4589 space-separated arguments (<sep> would be a single
4590 space character string in this case).
4591 COMMAND <cmd>...
4593 Any of the other ..._COMMAND options can have
4594 additional commands appended to them by following
4595 them with as many COMMAND ... options as needed
4596 (generator expressions are supported). For exam‐
4597 ple:
4598 ExternalProject_Add(example
4600 ... # Download options, etc.
4601 BUILD_COMMAND ${CMAKE_COMMAND} -E echo "Starting $<CONFIG> build"
4602 COMMAND ${CMAKE_COMMAND} --build <BINARY_DIR> --config $<CONFIG>
4603 COMMAND ${CMAKE_COMMAND} -E echo "$<CONFIG> build complete"
4604 )
4605 It should also be noted that each build step is created via a
4607 call to ExternalProject_Add_Step(). See that command’s documen‐
4608 tation for the automatic substitutions that are supported for
4609 some options.
4610 Obtaining Project Properties
4612 ExternalProject_Get_Property
4613 The ExternalProject_Get_Property() function retrieves external
4614 project target properties:
4615 ExternalProject_Get_Property(<name> <prop1> [<prop2>...])
4617 The function stores property values in variables of the same
4619 name. Property names correspond to the keyword argument names of
4620 ExternalProject_Add(). For example, the source directory might
4621 be retrieved like so:
4622 ExternalProject_Get_property(myExtProj SOURCE_DIR)
4624 message("Source dir of myExtProj = ${SOURCE_DIR}")
4625 Explicit Step Management
4627 The ExternalProject_Add() function on its own is often sufficient for
4628 incorporating an external project into the main build. Certain scenar‐
4629 ios require additional work to implement desired behavior, such as
4630 adding in a custom step or making steps available as manually trigger‐
4631 able targets. The ExternalProject_Add_Step(), ExternalProject_Add_Step‐
4632 Targets() and ExternalProject_Add_StepDependencies functions provide
4633 the lower level control needed to implement such step-level capabili‐
4634 ties.
4635 ExternalProject_Add_Step
4637 The ExternalProject_Add_Step() function specifies an additional
4638 custom step for an external project defined by an earlier call
4639 to ExternalProject_Add():
4640 ExternalProject_Add_Step(<name> <step> [<option>...])
4642 <name> is the same as the name passed to the original call to
4644 ExternalProject_Add(). The specified <step> must not be one of
4645 the pre-defined steps (mkdir, download, update, skip-update,
4646 patch, configure, build, install or test). The supported options
4647 are:
4648 COMMAND <cmd>...
4650 The command line to be executed by this custom step (gen‐
4651 erator expressions are supported). This option can be
4652 repeated multiple times to specify multiple commands to
4653 be executed in order.
4654 COMMENT <text>...
4656 Text to be printed when the custom step executes.
4657 DEPENDEES <step>...
4659 Other steps (custom or pre-defined) on which this step
4660 depends.
4661 DEPENDERS <step>...
4663 Other steps (custom or pre-defined) that depend on this
4664 new custom step.
4665 DEPENDS <file>...
4667 Files on which this custom step depends.
4668 BYPRODUCTS <file>...
4670 Files that will be generated by this custom step but
4671 which might or might not have their modification time
4672 updated by subsequent builds. This list of files will
4673 ultimately be passed through as the BYPRODUCTS option to
4674 the add_custom_command() used to implement the custom
4675 step internally.
4676 ALWAYS <bool>
4678 When enabled, this option specifies that the custom step
4679 should always be run (i.e. that it is always considered
4680 out of date).
4681 EXCLUDE_FROM_MAIN <bool>
4683 When enabled, this option specifies that the external
4684 project’s main target does not depend on the custom step.
4685 WORKING_DIRECTORY <dir>
4687 Specifies the working directory to set before running the
4688 custom step’s command. If this option is not specified,
4689 the directory will be the value of the CMAKE_CUR‐
4690 RENT_BINARY_DIR at the point where ExternalPro‐
4691 ject_Add_Step() was called.
4692 LOG <bool>
4694 If set, this causes the output from the custom step to be
4695 captured to files in the external project’s LOG_DIR if
4696 supplied or STAMP_DIR.
4697 USES_TERMINAL <bool>
4699 If enabled, this gives the custom step direct access to
4700 the terminal if possible.
4701 The command line, comment, working directory and byproducts of
4703 every standard and custom step are processed to replace the
4704 tokens <SOURCE_DIR>, <SOURCE_SUBDIR>, <BINARY_DIR>,
4705 <INSTALL_DIR> <TMP_DIR>, <DOWNLOAD_DIR> and <DOWNLOADED_FILE>
4706 with their corresponding property values defined in the original
4707 call to ExternalProject_Add().
4708 ExternalProject_Add_StepTargets
4710 The ExternalProject_Add_StepTargets() function generates targets
4711 for the steps listed. The name of each created target will be of
4712 the form <name>-<step>:
4713 ExternalProject_Add_StepTargets(<name> [NO_DEPENDS] <step1> [<step2>...])
4715 Creating a target for a step allows it to be used as a depen‐
4717 dency of another target or to be triggered manually. Having tar‐
4718 gets for specific steps also allows them to be driven indepen‐
4719 dently of each other by specifying targets on build command
4720 lines. For example, you may be submitting to a sub-project based
4721 dashboard where you want to drive the configure portion of the
4722 build, then submit to the dashboard, followed by the build por‐
4723 tion, followed by tests. If you invoke a custom target that
4724 depends on a step halfway through the step dependency chain,
4725 then all the previous steps will also run to ensure everything
4726 is up to date.
4727 If the NO_DEPENDS option is specified, the step target will not
4729 depend on the dependencies of the external project (i.e. on any
4730 dependencies of the <name> custom target created by
4731 ExternalProject_Add()). This is usually safe for the download,
4732 update and patch steps, since they do not typically require that
4733 the dependencies are updated and built. Using NO_DEPENDS for any
4734 of the other pre-defined steps, however, may break parallel
4735 builds. Only use NO_DEPENDS where it is certain that the named
4736 steps genuinely do not have dependencies. For custom steps, con‐
4737 sider whether or not the custom commands require the dependen‐
4738 cies to be configured, built and installed.
4739 Internally, ExternalProject_Add() calls
4741 ExternalProject_Add_Step() to create each step. If any STEP_TAR‐
4742 GETS or INDEPENDENT_STEP_TARGETS were specified, then External‐
4743 Project_Add_StepTargets() will also be called after
4744 ExternalProject_Add_Step(). INDEPENDENT_STEP_TARGETS have the
4745 NO_DEPENDS option set, whereas STEP_TARGETS do not. Other than
4746 that, the two options result in ExternalProject_Add_StepTar‐
4747 gets() being called in the same way. Even if a step is not men‐
4748 tioned in either of those two options, ExternalProject_Add_Step‐
4749 Targets() can still be called later to manually define a target
4750 for the step.
4751 The STEP_TARGETS and INDEPENDENT_STEP_TARGETS options for
4753 ExternalProject_Add() are generally the easiest way to ensure
4754 targets are created for specific steps of interest. For custom
4755 steps, ExternalProject_Add_StepTargets() must be called explic‐
4756 itly if a target should also be created for that custom step. An
4757 alternative to these two options is to populate the EP_STEP_TAR‐
4758 GETS and EP_INDEPENDENT_STEP_TARGETS directory properties. These
4759 act as defaults for the step target options and can save having
4760 to repeatedly specify the same set of step targets when multiple
4761 external projects are being defined.
4762 ExternalProject_Add_StepDependencies
4764 The ExternalProject_Add_StepDependencies() function can be used
4765 to add dependencies to a step. The dependencies added must be
4766 targets CMake already knows about (these can be ordinary exe‐
4767 cutable or library targets, custom targets or even step targets
4768 of another external project):
4769 ExternalProject_Add_StepDependencies(<name> <step> <target1> [<target2>...])
4771 This function takes care to set both target and file level
4773 dependencies and will ensure that parallel builds will not
4774 break. It should be used instead of add_dependencies() whenever
4775 adding a dependency for some of the step targets generated by
4776 the ExternalProject module.
4777 Examples
4779 The following example shows how to download and build a hypothetical
4780 project called FooBar from github:
4781 include(ExternalProject)
4783 ExternalProject_Add(foobar
4784 GIT_REPOSITORY git@github.com:FooCo/FooBar.git
4785 GIT_TAG origin/release/1.2.3
4786 )
4787 For the sake of the example, also define a second hypothetical external
4789 project called SecretSauce, which is downloaded from a web server. Two
4790 URLs are given to take advantage of a faster internal network if avail‐
4791 able, with a fallback to a slower external server. The project is a
4792 typical Makefile project with no configure step, so some of the default
4793 commands are overridden. The build is only required to build the sauce
4794 target:
4795 find_program(MAKE_EXE NAMES gmake nmake make)
4797 ExternalProject_Add(secretsauce
4798 URL http://intranet.somecompany.com/artifacts/sauce-2.7.tgz
4799 https://www.somecompany.com/downloads/sauce-2.7.zip
4800 URL_HASH MD5=d41d8cd98f00b204e9800998ecf8427e
4801 CONFIGURE_COMMAND ""
4802 BUILD_COMMAND ${MAKE_EXE} sauce
4803 )
4804 Suppose the build step of secretsauce requires that foobar must already
4806 be built. This could be enforced like so:
4807 ExternalProject_Add_StepDependencies(secretsauce build foobar)
4809 Another alternative would be to create a custom target for foobar’s
4811 build step and make secretsauce depend on that rather than the whole
4812 foobar project. This would mean foobar only needs to be built, it
4813 doesn’t need to run its install or test steps before secretsauce can be
4814 built. The dependency can also be defined along with the secretsauce
4815 project:
4816 ExternalProject_Add_StepTargets(foobar build)
4818 ExternalProject_Add(secretsauce
4819 URL http://intranet.somecompany.com/artifacts/sauce-2.7.tgz
4820 https://www.somecompany.com/downloads/sauce-2.7.zip
4821 URL_HASH MD5=d41d8cd98f00b204e9800998ecf8427e
4822 CONFIGURE_COMMAND ""
4823 BUILD_COMMAND ${MAKE_EXE} sauce
4824 DEPENDS foobar-build
4825 )
4826 Instead of calling ExternalProject_Add_StepTargets(), the target could
4828 be defined along with the foobar project itself:
4829 ExternalProject_Add(foobar
4831 GIT_REPOSITORY git@github.com:FooCo/FooBar.git
4832 GIT_TAG origin/release/1.2.3
4833 STEP_TARGETS build
4834 )
4835 If many external projects should have the same set of step targets,
4837 setting a directory property may be more convenient. The build step
4838 target could be created automatically by setting the EP_STEP_TARGETS
4839 directory property before creating the external projects with
4840 ExternalProject_Add():
4841 set_property(DIRECTORY PROPERTY EP_STEP_TARGETS build)
4843 Lastly, suppose that secretsauce provides a script called makedoc which
4845 can be used to generate its own documentation. Further suppose that the
4846 script expects the output directory to be provided as the only parame‐
4847 ter and that it should be run from the secretsauce source directory. A
4848 custom step and a custom target to trigger the script can be defined
4849 like so:
4850 ExternalProject_Add_Step(secretsauce docs
4852 COMMAND <SOURCE_DIR>/makedoc <BINARY_DIR>
4853 WORKING_DIRECTORY <SOURCE_DIR>
4854 COMMENT "Building secretsauce docs"
4855 ALWAYS TRUE
4856 EXCLUDE_FROM_MAIN TRUE
4857 )
4858 ExternalProject_Add_StepTargets(secretsauce docs)
4859 The custom step could then be triggered from the main build like so:
4861 cmake --build . --target secretsauce-docs
4863 FeatureSummary
4865 Functions for generating a summary of enabled/disabled features.
4866 These functions can be used to generate a summary of enabled and dis‐
4868 abled packages and/or feature for a build tree such as:
4869 -- The following OPTIONAL packages have been found:
4871 LibXml2 (required version >= 2.4), XML processing lib, <http://xmlsoft.org>
4872 * Enables HTML-import in MyWordProcessor
4873 * Enables odt-export in MyWordProcessor
4874 PNG, A PNG image library., <http://www.libpng.org/pub/png/>
4875 * Enables saving screenshots
4876 -- The following OPTIONAL packages have not been found:
4877 Lua51, The Lua scripting language., <http://www.lua.org>
4878 * Enables macros in MyWordProcessor
4879 Foo, Foo provides cool stuff.
4880 Global Properties
4882 FeatureSummary_PKG_TYPES
4883 The global property FeatureSummary_PKG_TYPES defines the type of pack‐
4885 ages used by FeatureSummary.
4886 The order in this list is important, the first package type in the list
4888 is the least important, the last is the most important. the of a pack‐
4889 age can only be changed to higher types.
4890 The default package types are , RUNTIME, OPTIONAL, RECOMMENDED and
4892 REQUIRED, and their importance is RUNTIME < OPTIONAL < RECOMMENDED <
4893 REQUIRED.
4894 FeatureSummary_REQUIRED_PKG_TYPES
4896 The global property FeatureSummary_REQUIRED_PKG_TYPES defines which
4898 package types are required.
4899 If one or more package in this categories has not been found, CMake
4901 will abort when calling feature_summary() with the ‘FATAL_ON_MISS‐
4902 ING_REQUIRED_PACKAGES’ option enabled.
4903 The default value for this global property is REQUIRED.
4905 FeatureSummary_DEFAULT_PKG_TYPE
4907 The global property FeatureSummary_DEFAULT_PKG_TYPE defines which pack‐
4909 age type is the default one. When calling feature_summary(), if the
4910 user did not set the package type explicitly, the package will be
4911 assigned to this category.
4912 This value must be one of the types defined in the
4914 FeatureSummary_PKG_TYPES global property unless the package type is set
4915 for all the packages.
4916 The default value for this global property is OPTIONAL.
4918 FeatureSummary_<TYPE>_DESCRIPTION
4920 The global property FeatureSummary_<TYPE>_DESCRIPTION can be defined
4922 for each type to replace the type name with the specified string when‐
4923 ever the package type is used in an output string.
4924 If not set, the string “<TYPE> packages” is used.
4926 Functions
4928 feature_summary
4929 feature_summary( [FILENAME <file>]
4931 [APPEND]
4932 [VAR <variable_name>]
4933 [INCLUDE_QUIET_PACKAGES]
4934 [FATAL_ON_MISSING_REQUIRED_PACKAGES]
4935 [DESCRIPTION "<description>" | DEFAULT_DESCRIPTION]
4936 [QUIET_ON_EMPTY]
4937 WHAT (ALL
4938 | PACKAGES_FOUND | PACKAGES_NOT_FOUND
4939 | <TYPE>_PACKAGES_FOUND | <TYPE>_PACKAGES_NOT_FOUND
4940 | ENABLED_FEATURES | DISABLED_FEATURES)
4941 )
4942 The feature_summary() macro can be used to print information
4944 about enabled or disabled packages or features of a project. By
4945 default, only the names of the features/packages will be printed
4946 and their required version when one was specified. Use
4947 set_package_properties() to add more useful information, like
4948 e.g. a download URL for the respective package or their purpose
4949 in the project.
4950 The WHAT option is the only mandatory option. Here you specify
4952 what information will be printed:
4953 ALL print everything
4955 ENABLED_FEATURES
4957 the list of all features which are enabled
4958 DISABLED_FEATURES
4960 the list of all features which are disabled
4961 PACKAGES_FOUND
4963 the list of all packages which have been found
4964 PACKAGES_NOT_FOUND
4966 the list of all packages which have not been found
4967 For each package type <TYPE> defined by the
4969 FeatureSummary_PKG_TYPES global property, the following informa‐
4970 tion can also be used:
4971 <TYPE>_PACKAGES_FOUND
4973 only those packages which have been found which have the
4974 type <TYPE>
4975 <TYPE>_PACKAGES_NOT_FOUND
4977 only those packages which have not been found which have
4978 the type <TYPE>
4979 With the exception of the ALL value, these values can be com‐
4981 bined in order to customize the output. For example:
4982 feature_summary(WHAT ENABLED_FEATURES DISABLED_FEATURES)
4984 If a FILENAME is given, the information is printed into this
4986 file. If APPEND is used, it is appended to this file, otherwise
4987 the file is overwritten if it already existed. If the VAR
4988 option is used, the information is “printed” into the specified
4989 variable. If FILENAME is not used, the information is printed
4990 to the terminal. Using the DESCRIPTION option a description or
4991 headline can be set which will be printed above the actual con‐
4992 tent. If only one type of package was requested, no title is
4993 printed, unless it is explicitly set using either DESCRIPTION to
4994 use a custom string, or DEFAULT_DESCRIPTION to use a default
4995 title for the requested type. If INCLUDE_QUIET_PACKAGES is
4996 given, packages which have been searched with find_package(...
4997 QUIET) will also be listed. By default they are skipped. If
4998 FATAL_ON_MISSING_REQUIRED_PACKAGES is given, CMake will abort if
4999 a package which is marked as one of the package types listed in
5000 the FeatureSummary_REQUIRED_PKG_TYPES global property has not
5001 been found. The default value for the
5002 FeatureSummary_REQUIRED_PKG_TYPES global property is REQUIRED.
5003 The FeatureSummary_DEFAULT_PKG_TYPE global property can be modi‐
5005 fied to change the default package type assigned when not
5006 explicitly assigned by the user.
5007 If the QUIET_ON_EMPTY option is used, if only one type of pack‐
5009 age was requested, and no packages belonging to that category
5010 were found, then no output (including the DESCRIPTION) is
5011 printed or added to the VAR variable.
5012 Example 1, append everything to a file:
5014 include(FeatureSummary)
5016 feature_summary(WHAT ALL
5017 FILENAME ${CMAKE_BINARY_DIR}/all.log APPEND)
5018 Example 2, print the enabled features into the variable enabled‐
5020 FeaturesText, including QUIET packages:
5021 include(FeatureSummary)
5023 feature_summary(WHAT ENABLED_FEATURES
5024 INCLUDE_QUIET_PACKAGES
5025 DESCRIPTION "Enabled Features:"
5026 VAR enabledFeaturesText)
5027 message(STATUS "${enabledFeaturesText}")
5028 Example 3, change default package types and print only the cate‐
5030 gories that are not empty:
5031 include(FeatureSummary)
5033 set_property(GLOBAL APPEND PROPERTY FeatureSummary_PKG_TYPES BUILD)
5034 find_package(FOO)
5035 set_package_properties(FOO PROPERTIES TYPE BUILD)
5036 feature_summary(WHAT BUILD_PACKAGES_FOUND
5037 Description "Build tools found:"
5038 QUIET_ON_EMPTY)
5039 feature_summary(WHAT BUILD_PACKAGES_NOT_FOUND
5040 Description "Build tools not found:"
5041 QUIET_ON_EMPTY)
5042 set_package_properties
5044 set_package_properties(<name> PROPERTIES
5046 [ URL <url> ]
5047 [ DESCRIPTION <description> ]
5048 [ TYPE (RUNTIME|OPTIONAL|RECOMMENDED|REQUIRED) ]
5049 [ PURPOSE <purpose> ]
5050 )
5051 Use this macro to set up information about the named package,
5053 which can then be displayed via FEATURE_SUMMARY(). This can be
5054 done either directly in the Find-module or in the project which
5055 uses the module after the find_package() call. The features for
5056 which information can be set are added automatically by the
5057 find_package() command.
5058 URL <url>
5060 This should be the homepage of the package, or something
5061 similar. Ideally this is set already directly in the
5062 Find-module.
5063 DESCRIPTION <description>
5065 A short description what that package is, at most one
5066 sentence. Ideally this is set already directly in the
5067 Find-module.
5068 TYPE <type>
5070 What type of dependency has the using project on that
5071 package. Default is OPTIONAL. In this case it is a
5072 package which can be used by the project when available
5073 at buildtime, but it also work without. RECOMMENDED is
5074 similar to OPTIONAL, i.e. the project will build if the
5075 package is not present, but the functionality of the
5076 resulting binaries will be severely limited. If a
5077 REQUIRED package is not available at buildtime, the
5078 project may not even build. This can be combined with
5079 the FATAL_ON_MISSING_REQUIRED_PACKAGES argument for fea‐
5080 ture_summary(). Last, a RUNTIME package is a package
5081 which is actually not used at all during the build, but
5082 which is required for actually running the resulting
5083 binaries. So if such a package is missing, the project
5084 can still be built, but it may not work later on. If
5085 set_package_properties() is called multiple times for the
5086 same package with different TYPEs, the TYPE is only
5087 changed to higher TYPEs (RUNTIME < OPTIONAL < RECOMMENDED
5088 < REQUIRED), lower TYPEs are ignored. The TYPE property
5089 is project-specific, so it cannot be set by the Find-mod‐
5090 ule, but must be set in the project. Type accepted can
5091 be changed by setting the FeatureSummary_PKG_TYPES global
5092 property.
5093 PURPOSE <purpose>
5095 This describes which features this package enables in the
5096 project, i.e. it tells the user what functionality he
5097 gets in the resulting binaries. If set_package_proper‐
5098 ties() is called multiple times for a package, all PUR‐
5099 POSE properties are appended to a list of purposes of the
5100 package in the project. As the TYPE property, also the
5101 PURPOSE property is project-specific, so it cannot be set
5102 by the Find-module, but must be set in the project.
5103 Example for setting the info for a package:
5105 find_package(LibXml2)
5107 set_package_properties(LibXml2 PROPERTIES
5108 DESCRIPTION "A XML processing library."
5109 URL "http://xmlsoft.org/")
5110 # or
5111 set_package_properties(LibXml2 PROPERTIES
5112 TYPE RECOMMENDED
5113 PURPOSE "Enables HTML-import in MyWordProcessor")
5114 # or
5115 set_package_properties(LibXml2 PROPERTIES
5116 TYPE OPTIONAL
5117 PURPOSE "Enables odt-export in MyWordProcessor")
5118 find_package(DBUS)
5120 set_package_properties(DBUS PROPERTIES
5121 TYPE RUNTIME
5122 PURPOSE "Necessary to disable the screensaver during a presentation")
5123 add_feature_info
5125 add_feature_info(<name> <enabled> <description>)
5127 Use this macro to add information about a feature with the given
5129 <name>. <enabled> contains whether this feature is enabled or
5130 not. It can be a variable or a list of conditions. <descrip‐
5131 tion> is a text describing the feature. The information can be
5132 displayed using feature_summary() for ENABLED_FEATURES and DIS‐
5133 ABLED_FEATURES respectively.
5134 Example for setting the info for a feature:
5136 option(WITH_FOO "Help for foo" ON)
5138 add_feature_info(Foo WITH_FOO "The Foo feature provides very cool stuff.")
5139 Legacy Macros
5141 The following macros are provided for compatibility with previous CMake
5142 versions:
5143 set_package_info
5145 set_package_info(<name> <description> [ <url> [<purpose>] ])
5147 Use this macro to set up information about the named package,
5149 which can then be displayed via feature_summary(). This can be
5150 done either directly in the Find-module or in the project which
5151 uses the module after the find_package() call. The features for
5152 which information can be set are added automatically by the
5153 find_package() command.
5154 set_feature_info
5156 set_feature_info(<name> <description> [<url>])
5158 Does the same as:
5160 set_package_info(<name> <description> <url>)
5162 print_enabled_features
5164 print_enabled_features()
5166 Does the same as
5168 feature_summary(WHAT ENABLED_FEATURES DESCRIPTION "Enabled features:")
5170 print_disabled_features
5172 print_disabled_features()
5174 Does the same as
5176 feature_summary(WHAT DISABLED_FEATURES DESCRIPTION "Disabled features:")
5178 FetchContent
5180 Overview
5181 This module enables populating content at configure time via any method
5182 supported by the ExternalProject module. Whereas ExternalProject_Add()
5183 downloads at build time, the FetchContent module makes content avail‐
5184 able immediately, allowing the configure step to use the content in
5185 commands like add_subdirectory(), include() or file() operations.
5186 Content population details would normally be defined separately from
5188 the command that performs the actual population. This separation
5189 ensures that all of the dependency details are defined before anything
5190 may try to use those details to populate content. This is particularly
5191 important in more complex project hierarchies where dependencies may be
5192 shared between multiple projects.
5193 The following shows a typical example of declaring content details:
5195 FetchContent_Declare(
5197 googletest
5198 GIT_REPOSITORY https://github.com/google/googletest.git
5199 GIT_TAG release-1.8.0
5200 )
5201 For most typical cases, populating the content can then be done with a
5203 single command like so:
5204 FetchContent_MakeAvailable(googletest)
5206 The above command not only populates the content, it also adds it to
5208 the main build (if possible) so that the main build can use the popu‐
5209 lated project’s targets, etc. In some cases, the main project may need
5210 to have more precise control over the population or may be required to
5211 explicitly define the population steps (e.g. if CMake versions earlier
5212 than 3.14 need to be supported). The typical pattern of such custom
5213 steps looks like this:
5214 FetchContent_GetProperties(googletest)
5216 if(NOT googletest_POPULATED)
5217 FetchContent_Populate(googletest)
5218 add_subdirectory(${googletest_SOURCE_DIR} ${googletest_BINARY_DIR})
5219 endif()
5220 Regardless of which population method is used, when using the
5222 declare-populate pattern with a hierarchical project arrangement,
5223 projects at higher levels in the hierarchy are able to override the
5224 population details of content specified anywhere lower in the project
5225 hierarchy. The ability to detect whether content has already been pop‐
5226 ulated ensures that even if multiple child projects want certain con‐
5227 tent to be available, the first one to populate it wins. The other
5228 child project can simply make use of the already available content
5229 instead of repeating the population for itself. See the Examples sec‐
5230 tion which demonstrates this scenario.
5231 The FetchContent module also supports defining and populating content
5233 in a single call, with no check for whether the content has been popu‐
5234 lated elsewhere in the project already. This is a more low level oper‐
5235 ation and would not normally be the way the module is used, but it is
5236 sometimes useful as part of implementing some higher level feature or
5237 to populate some content in CMake’s script mode.
5238 Declaring Content Details
5240 FetchContent_Declare
5241 FetchContent_Declare(<name> <contentOptions>...)
5243 The FetchContent_Declare() function records the options that
5245 describe how to populate the specified content, but if such
5246 details have already been recorded earlier in this project
5247 (regardless of where in the project hierarchy), this and all
5248 later calls for the same content <name> are ignored. This
5249 “first to record, wins” approach is what allows hierarchical
5250 projects to have parent projects override content details of
5251 child projects.
5252 The content <name> can be any string without spaces, but good
5254 practice would be to use only letters, numbers and underscores.
5255 The name will be treated case-insensitively and it should be
5256 obvious for the content it represents, often being the name of
5257 the child project or the value given to its top level project()
5258 command (if it is a CMake project). For well-known public
5259 projects, the name should generally be the official name of the
5260 project. Choosing an unusual name makes it unlikely that other
5261 projects needing that same content will use the same name, lead‐
5262 ing to the content being populated multiple times.
5263 The <contentOptions> can be any of the download or update/patch
5265 options that the ExternalProject_Add() command understands. The
5266 configure, build, install and test steps are explicitly disabled
5267 and therefore options related to them will be ignored. In most
5268 cases, <contentOptions> will just be a couple of options defin‐
5269 ing the download method and method-specific details like a com‐
5270 mit tag or archive hash. For example:
5271 FetchContent_Declare(
5273 googletest
5274 GIT_REPOSITORY https://github.com/google/googletest.git
5275 GIT_TAG release-1.8.0
5276 )
5277 FetchContent_Declare(
5279 myCompanyIcons
5280 URL https://intranet.mycompany.com/assets/iconset_1.12.tar.gz
5281 URL_HASH 5588a7b18261c20068beabfb4f530b87
5282 )
5283 FetchContent_Declare(
5285 myCompanyCertificates
5286 SVN_REPOSITORY svn+ssh://svn.mycompany.com/srv/svn/trunk/certs
5287 SVN_REVISION -r12345
5288 )
5289 Populating The Content
5291 For most common scenarios, population means making content available to
5292 the main build according to previously declared details for that depen‐
5293 dency. There are two main patterns for populating content, one based
5294 on calling FetchContent_GetProperties() and FetchContent_Populate() for
5295 more precise control and the other on calling
5296 FetchContent_MakeAvailable() for a simpler, more automated approach.
5297 The former generally follows this canonical pattern:
5298 # Check if population has already been performed
5300 FetchContent_GetProperties(<name>)
5301 string(TOLOWER "<name>" lcName)
5302 if(NOT ${lcName}_POPULATED)
5303 # Fetch the content using previously declared details
5304 FetchContent_Populate(<name>)
5305 # Set custom variables, policies, etc.
5307 # ...
5308 # Bring the populated content into the build
5310 add_subdirectory(${${lcName}_SOURCE_DIR} ${${lcName}_BINARY_DIR})
5311 endif()
5312 The above is such a common pattern that, where no custom steps are
5314 needed between the calls to FetchContent_Populate() and add_subdirec‐
5315 tory(), equivalent logic can be obtained by calling
5316 FetchContent_MakeAvailable() instead (and should be preferred where it
5317 meets the needs of the project).
5318 FetchContent_Populate
5320 FetchContent_Populate( <name> )
5322 In most cases, the only argument given to FetchContent_Popu‐
5324 late() is the <name>. When used this way, the command assumes
5325 the content details have been recorded by an earlier call to
5326 FetchContent_Declare(). The details are stored in a global
5327 property, so they are unaffected by things like variable or
5328 directory scope. Therefore, it doesn’t matter where in the
5329 project the details were previously declared, as long as they
5330 have been declared before the call to FetchContent_Populate().
5331 Those saved details are then used to construct a call to Exter‐
5332 nalProject_Add() in a private sub-build to perform the content
5333 population immediately. The implementation of ExternalPro‐
5334 ject_Add() ensures that if the content has already been popu‐
5335 lated in a previous CMake run, that content will be reused
5336 rather than repopulating them again. For the common case where
5337 population involves downloading content, the cost of the down‐
5338 load is only paid once.
5339 An internal global property records when a particular content
5341 population request has been processed. If FetchContent_Popu‐
5342 late() is called more than once for the same content name within
5343 a configure run, the second call will halt with an error.
5344 Projects can and should check whether content population has
5345 already been processed with the FetchContent_GetProperties()
5346 command before calling FetchContent_Populate().
5347 FetchContent_Populate() will set three variables in the scope of
5349 the caller; <lcName>_POPULATED, <lcName>_SOURCE_DIR and
5350 <lcName>_BINARY_DIR, where <lcName> is the lowercased <name>.
5351 <lcName>_POPULATED will always be set to True by the call.
5352 <lcName>_SOURCE_DIR is the location where the content can be
5353 found upon return (it will have already been populated), while
5354 <lcName>_BINARY_DIR is a directory intended for use as a corre‐
5355 sponding build directory. The main use case for the two direc‐
5356 tory variables is to call add_subdirectory() immediately after
5357 population, i.e.:
5358 FetchContent_Populate(FooBar ...)
5360 add_subdirectory(${foobar_SOURCE_DIR} ${foobar_BINARY_DIR})
5361 The values of the three variables can also be retrieved from
5363 anywhere in the project hierarchy using the
5364 FetchContent_GetProperties() command.
5365 A number of cache variables influence the behavior of all con‐
5367 tent population performed using details saved from a
5368 FetchContent_Declare() call:
5369 FETCHCONTENT_BASE_DIR
5371 In most cases, the saved details do not specify any
5372 options relating to the directories to use for the inter‐
5373 nal sub-build, final source and build areas. It is gen‐
5374 erally best to leave these decisions up to the FetchCon‐
5375 tent module to handle on the project’s behalf. The
5376 FETCHCONTENT_BASE_DIR cache variable controls the point
5377 under which all content population directories are col‐
5378 lected, but in most cases developers would not need to
5379 change this. The default location is
5380 ${CMAKE_BINARY_DIR}/_deps, but if developers change this
5381 value, they should aim to keep the path short and just
5382 below the top level of the build tree to avoid running
5383 into path length problems on Windows.
5384 FETCHCONTENT_QUIET
5386 The logging output during population can be quite ver‐
5387 bose, making the configure stage quite noisy. This cache
5388 option (ON by default) hides all population output unless
5389 an error is encountered. If experiencing problems with
5390 hung downloads, temporarily switching this option off may
5391 help diagnose which content population is causing the
5392 issue.
5393 FETCHCONTENT_FULLY_DISCONNECTED
5395 When this option is enabled, no attempt is made to down‐
5396 load or update any content. It is assumed that all con‐
5397 tent has already been populated in a previous run or the
5398 source directories have been pointed at existing contents
5399 the developer has provided manually (using options
5400 described further below). When the developer knows that
5401 no changes have been made to any content details, turning
5402 this option ON can significantly speed up the configure
5403 stage. It is OFF by default.
5404 FETCHCONTENT_UPDATES_DISCONNECTED
5406 This is a less severe download/update control compared to
5407 FETCHCONTENT_FULLY_DISCONNECTED. Instead of bypassing
5408 all download and update logic, the FETCHCON‐
5409 TENT_UPDATES_DISCONNECTED only disables the update stage.
5410 Therefore, if content has not been downloaded previously,
5411 it will still be downloaded when this option is enabled.
5412 This can speed up the configure stage, but not as much as
5413 FETCHCONTENT_FULLY_DISCONNECTED. It is OFF by default.
5414 In addition to the above cache variables, the following cache
5416 variables are also defined for each content name (<ucName> is
5417 the uppercased value of <name>):
5418 FETCHCONTENT_SOURCE_DIR_<ucName>
5420 If this is set, no download or update steps are performed
5421 for the specified content and the <lcName>_SOURCE_DIR
5422 variable returned to the caller is pointed at this loca‐
5423 tion. This gives developers a way to have a separate
5424 checkout of the content that they can modify freely with‐
5425 out interference from the build. The build simply uses
5426 that existing source, but it still defines
5427 <lcName>_BINARY_DIR to point inside its own build area.
5428 Developers are strongly encouraged to use this mechanism
5429 rather than editing the sources populated in the default
5430 location, as changes to sources in the default location
5431 can be lost when content population details are changed
5432 by the project.
5433 FETCHCONTENT_UPDATES_DISCONNECTED_<ucName>
5435 This is the per-content equivalent of FETCHCON‐
5436 TENT_UPDATES_DISCONNECTED. If the global option or this
5437 option is ON, then updates will be disabled for the named
5438 content. Disabling updates for individual content can be
5439 useful for content whose details rarely change, while
5440 still leaving other frequently changing content with
5441 updates enabled.
5442 The FetchContent_Populate() command also supports a syntax
5444 allowing the content details to be specified directly rather
5445 than using any saved details. This is more low-level and use of
5446 this form is generally to be avoided in favour of using saved
5447 content details as outlined above. Nevertheless, in certain
5448 situations it can be useful to invoke the content population as
5449 an isolated operation (typically as part of implementing some
5450 other higher level feature or when using CMake in script mode):
5451 FetchContent_Populate( <name>
5453 [QUIET]
5454 [SUBBUILD_DIR <subBuildDir>]
5455 [SOURCE_DIR <srcDir>]
5456 [BINARY_DIR <binDir>]
5457 ...
5458 )
5459 This form has a number of key differences to that where only
5461 <name> is provided:
5462 · All required population details are assumed to have been pro‐
5464 vided directly in the call to FetchContent_Populate(). Any
5465 saved details for <name> are ignored.
5466 · No check is made for whether content for <name> has already
5468 been populated.
5469 · No global property is set to record that the population has
5471 occurred.
5472 · No global properties record the source or binary directories
5474 used for the populated content.
5475 · The FETCHCONTENT_FULLY_DISCONNECTED and FETCHCON‐
5477 TENT_UPDATES_DISCONNECTED cache variables are ignored.
5478 The <lcName>_SOURCE_DIR and <lcName>_BINARY_DIR variables are
5480 still returned to the caller, but since these locations are not
5481 stored as global properties when this form is used, they are
5482 only available to the calling scope and below rather than the
5483 entire project hierarchy. No <lcName>_POPULATED variable is set
5484 in the caller’s scope with this form.
5485 The supported options for FetchContent_Populate() are the same
5487 as those for FetchContent_Declare(). Those few options shown
5488 just above are either specific to FetchContent_Populate() or
5489 their behavior is slightly modified from how ExternalPro‐
5490 ject_Add() treats them.
5491 QUIET The QUIET option can be given to hide the output associ‐
5493 ated with populating the specified content. If the popu‐
5494 lation fails, the output will be shown regardless of
5495 whether this option was given or not so that the cause of
5496 the failure can be diagnosed. The global FETCHCON‐
5497 TENT_QUIET cache variable has no effect on FetchCon‐
5498 tent_Populate() calls where the content details are pro‐
5499 vided directly.
5500 SUBBUILD_DIR
5502 The SUBBUILD_DIR argument can be provided to change the
5503 location of the sub-build created to perform the popula‐
5504 tion. The default value is ${CMAKE_CUR‐
5505 RENT_BINARY_DIR}/<lcName>-subbuild and it would be
5506 unusual to need to override this default. If a relative
5507 path is specified, it will be interpreted as relative to
5508 CMAKE_CURRENT_BINARY_DIR.
5509 SOURCE_DIR, BINARY_DIR
5511 The SOURCE_DIR and BINARY_DIR arguments are supported by
5512 ExternalProject_Add(), but different default values are
5513 used by FetchContent_Populate(). SOURCE_DIR defaults to
5514 ${CMAKE_CURRENT_BINARY_DIR}/<lcName>-src and BINARY_DIR
5515 defaults to ${CMAKE_CURRENT_BINARY_DIR}/<lcName>-build.
5516 If a relative path is specified, it will be interpreted
5517 as relative to CMAKE_CURRENT_BINARY_DIR.
5518 In addition to the above explicit options, any other unrecog‐
5520 nized options are passed through unmodified to ExternalPro‐
5521 ject_Add() to perform the download, patch and update steps. The
5522 following options are explicitly prohibited (they are disabled
5523 by the FetchContent_Populate() command):
5524 · CONFIGURE_COMMAND
5526 · BUILD_COMMAND
5528 · INSTALL_COMMAND
5530 · TEST_COMMAND
5532 If using FetchContent_Populate() within CMake’s script mode, be
5534 aware that the implementation sets up a sub-build which there‐
5535 fore requires a CMake generator and build tool to be available.
5536 If these cannot be found by default, then the CMAKE_GENERATOR
5537 and/or CMAKE_MAKE_PROGRAM variables will need to be set appro‐
5538 priately on the command line invoking the script.
5539 FetchContent_GetProperties
5541 When using saved content details, a call to
5542 FetchContent_Populate() records information in global properties
5543 which can be queried at any time. This information includes the
5544 source and binary directories associated with the content and
5545 also whether or not the content population has been processed
5546 during the current configure run.
5547 FetchContent_GetProperties( <name>
5549 [SOURCE_DIR <srcDirVar>]
5550 [BINARY_DIR <binDirVar>]
5551 [POPULATED <doneVar>]
5552 )
5553 The SOURCE_DIR, BINARY_DIR and POPULATED options can be used to
5555 specify which properties should be retrieved. Each option
5556 accepts a value which is the name of the variable in which to
5557 store that property. Most of the time though, only <name> is
5558 given, in which case the call will then set the same variables
5559 as a call to FetchContent_Populate(name). This allows the fol‐
5560 lowing canonical pattern to be used, which ensures that the rel‐
5561 evant variables will always be defined regardless of whether or
5562 not the population has been performed elsewhere in the project
5563 already:
5564 FetchContent_GetProperties(foobar)
5566 if(NOT foobar_POPULATED)
5567 FetchContent_Populate(foobar)
5568 ...
5569 endif()
5570 The above pattern allows other parts of the overall project
5572 hierarchy to re-use the same content and ensure that it is only
5573 populated once.
5574 FetchContent_MakeAvailable
5576 FetchContent_MakeAvailable( <name1> [<name2>...] )
5578 This command implements the common pattern typically needed for
5580 most dependencies. It iterates over each of the named dependen‐
5581 cies in turn and for each one it loosely follows the same
5582 canonical pattern as presented at the beginning of this section.
5583 One small difference to that pattern is that it will only call
5584 add_subdirectory() on the populated content if there is a CMake‐
5585 Lists.txt file in its top level source directory. This allows
5586 the command to be used for dependencies that make downloaded
5587 content available at a known location but which do not need or
5588 support being added directly to the build.
5589 Examples
5591 This first fairly straightforward example ensures that some popular
5592 testing frameworks are available to the main build:
5593 include(FetchContent)
5595 FetchContent_Declare(
5596 googletest
5597 GIT_REPOSITORY https://github.com/google/googletest.git
5598 GIT_TAG release-1.8.0
5599 )
5600 FetchContent_Declare(
5601 Catch2
5602 GIT_REPOSITORY https://github.com/catchorg/Catch2.git
5603 GIT_TAG v2.5.0
5604 )
5605 # After the following call, the CMake targets defined by googletest and
5607 # Catch2 will be defined and available to the rest of the build
5608 FetchContent_MakeAvailable(googletest Catch2)
5609 In more complex project hierarchies, the dependency relationships can
5611 be more complicated. Consider a hierarchy where projA is the top level
5612 project and it depends directly on projects projB and projC. Both
5613 projB and projC can be built standalone and they also both depend on
5614 another project projD. projB additionally depends on projE. This
5615 example assumes that all five projects are available on a company git
5616 server. The CMakeLists.txt of each project might have sections like
5617 the following:
5618 projA:
5620 include(FetchContent)
5622 FetchContent_Declare(
5623 projB
5624 GIT_REPOSITORY git@mycompany.com:git/projB.git
5625 GIT_TAG 4a89dc7e24ff212a7b5167bef7ab079d
5626 )
5627 FetchContent_Declare(
5628 projC
5629 GIT_REPOSITORY git@mycompany.com:git/projC.git
5630 GIT_TAG 4ad4016bd1d8d5412d135cf8ceea1bb9
5631 )
5632 FetchContent_Declare(
5633 projD
5634 GIT_REPOSITORY git@mycompany.com:git/projD.git
5635 GIT_TAG origin/integrationBranch
5636 )
5637 FetchContent_Declare(
5638 projE
5639 GIT_REPOSITORY git@mycompany.com:git/projE.git
5640 GIT_TAG origin/release/2.3-rc1
5641 )
5642 # Order is important, see notes in the discussion further below
5644 FetchContent_MakeAvailable(projD projB projC)
5645 projB:
5647 include(FetchContent)
5649 FetchContent_Declare(
5650 projD
5651 GIT_REPOSITORY git@mycompany.com:git/projD.git
5652 GIT_TAG 20b415f9034bbd2a2e8216e9a5c9e632
5653 )
5654 FetchContent_Declare(
5655 projE
5656 GIT_REPOSITORY git@mycompany.com:git/projE.git
5657 GIT_TAG 68e20f674a48be38d60e129f600faf7d
5658 )
5659 FetchContent_MakeAvailable(projD projE)
5661 projC:
5663 include(FetchContent)
5665 FetchContent_Declare(
5666 projD
5667 GIT_REPOSITORY git@mycompany.com:git/projD.git
5668 GIT_TAG 7d9a17ad2c962aa13e2fbb8043fb6b8a
5669 )
5670 # This particular version of projD requires workarounds
5672 FetchContent_GetProperties(projD)
5673 if(NOT projd_POPULATED)
5674 FetchContent_Populate(projD)
5675 # Copy an additional/replacement file into the populated source
5677 file(COPY someFile.c DESTINATION ${projd_SOURCE_DIR}/src)
5678 add_subdirectory(${projd_SOURCE_DIR} ${projd_BINARY_DIR})
5680 endif()
5681 A few key points should be noted in the above:
5683 · projB and projC define different content details for projD, but projA
5685 also defines a set of content details for projD. Because projA will
5686 define them first, the details from projB and projC will not be used.
5687 The override details defined by projA are not required to match
5688 either of those from projB or projC, but it is up to the higher level
5689 project to ensure that the details it does define still make sense
5690 for the child projects.
5691 · In the projA call to FetchContent_MakeAvailable(), projD is listed
5693 ahead of projB and projC to ensure that projA is in control of how
5694 projD is populated.
5695 · While projA defines content details for projE, it does not need to
5697 explicitly call FetchContent_MakeAvailable(projE) or FetchCon‐
5698 tent_Populate(projD) itself. Instead, it leaves that to the child
5699 projB. For higher level projects, it is often enough to just define
5700 the override content details and leave the actual population to the
5701 child projects. This saves repeating the same thing at each level of
5702 the project hierarchy unnecessarily.
5703 Projects don’t always need to add the populated content to the build.
5705 Sometimes the project just wants to make the downloaded content avail‐
5706 able at a predictable location. The next example ensures that a set of
5707 standard company toolchain files (and potentially even the toolchain
5708 binaries themselves) is available early enough to be used for that same
5709 build.
5710 cmake_minimum_required(VERSION 3.14)
5712 include(FetchContent)
5714 FetchContent_Declare(
5715 mycom_toolchains
5716 URL https://intranet.mycompany.com//toolchains_1.3.2.tar.gz
5717 )
5718 FetchContent_MakeAvailable(mycom_toolchains)
5719 project(CrossCompileExample)
5721 The project could be configured to use one of the downloaded toolchains
5723 like so:
5724 cmake -DCMAKE_TOOLCHAIN_FILE=_deps/mycom_toolchains-src/toolchain_arm.cmake /path/to/src
5726 When CMake processes the CMakeLists.txt file, it will download and
5728 unpack the tarball into _deps/mycompany_toolchains-src relative to the
5729 build directory. The CMAKE_TOOLCHAIN_FILE variable is not used until
5730 the project() command is reached, at which point CMake looks for the
5731 named toolchain file relative to the build directory. Because the tar‐
5732 ball has already been downloaded and unpacked by then, the toolchain
5733 file will be in place, even the very first time that cmake is run in
5734 the build directory.
5735 Lastly, the following example demonstrates how one might download and
5737 unpack a firmware tarball using CMake’s script mode. The call to
5738 FetchContent_Populate() specifies all the content details and the
5739 unpacked firmware will be placed in a firmware directory below the cur‐
5740 rent working directory.
5741 getFirmware.cmake:
5743 # NOTE: Intended to be run in script mode with cmake -P
5745 include(FetchContent)
5746 FetchContent_Populate(
5747 firmware
5748 URL https://mycompany.com/assets/firmware-1.23-arm.tar.gz
5749 URL_HASH MD5=68247684da89b608d466253762b0ff11
5750 SOURCE_DIR firmware
5751 )
5752 FindPackageHandleStandardArgs
5754 This module provides a function intended to be used in Find Modules
5755 implementing find_package(<PackageName>) calls. It handles the
5756 REQUIRED, QUIET and version-related arguments of find_package. It also
5757 sets the <PackageName>_FOUND variable. The package is considered found
5758 if all variables listed contain valid results, e.g. valid filepaths.
5759 find_package_handle_standard_args
5761 There are two signatures:
5762 find_package_handle_standard_args(<PackageName>
5764 (DEFAULT_MSG|<custom-failure-message>)
5765 <required-var>...
5766 )
5767 find_package_handle_standard_args(<PackageName>
5769 [FOUND_VAR <result-var>]
5770 [REQUIRED_VARS <required-var>...]
5771 [VERSION_VAR <version-var>]
5772 [HANDLE_COMPONENTS]
5773 [CONFIG_MODE]
5774 [NAME_MISMATCHED]
5775 [REASON_FAILURE_MESSAGE <reason-failure-message>]
5776 [FAIL_MESSAGE <custom-failure-message>]
5777 )
5778 The <PackageName>_FOUND variable will be set to TRUE if all the
5780 variables <required-var>... are valid and any optional con‐
5781 straints are satisfied, and FALSE otherwise. A success or fail‐
5782 ure message may be displayed based on the results and on whether
5783 the REQUIRED and/or QUIET option was given to the find_package()
5784 call.
5785 The options are:
5787 (DEFAULT_MSG|<custom-failure-message>)
5789 In the simple signature this specifies the failure mes‐
5790 sage. Use DEFAULT_MSG to ask for a default message to be
5791 computed (recommended). Not valid in the full signature.
5792 FOUND_VAR <result-var>
5794 Obsolete. Specifies either <PackageName>_FOUND or <PACK‐
5795 AGENAME>_FOUND as the result variable. This exists only
5796 for compatibility with older versions of CMake and is now
5797 ignored. Result variables of both names are always set
5798 for compatibility.
5799 REQUIRED_VARS <required-var>...
5801 Specify the variables which are required for this pack‐
5802 age. These may be named in the generated failure message
5803 asking the user to set the missing variable values.
5804 Therefore these should typically be cache entries such as
5805 FOO_LIBRARY and not output variables like FOO_LIBRARIES.
5806 VERSION_VAR <version-var>
5808 Specify the name of a variable that holds the version of
5809 the package that has been found. This version will be
5810 checked against the (potentially) specified required ver‐
5811 sion given to the find_package() call, including its
5812 EXACT option. The default messages include information
5813 about the required version and the version which has been
5814 actually found, both if the version is ok or not.
5815 HANDLE_COMPONENTS
5817 Enable handling of package components. In this case, the
5818 command will report which components have been found and
5819 which are missing, and the <PackageName>_FOUND variable
5820 will be set to FALSE if any of the required components
5821 (i.e. not the ones listed after the OPTIONAL_COMPONENTS
5822 option of find_package()) are missing.
5823 CONFIG_MODE
5825 Specify that the calling find module is a wrapper around
5826 a call to find_package(<PackageName> NO_MODULE). This
5827 implies a VERSION_VAR value of <PackageName>_VERSION.
5828 The command will automatically check whether the package
5829 configuration file was found.
5830 REASON_FAILURE_MESSAGE <reason-failure-message>
5832 Specify a custom message of the reason for the failure
5833 which will be appended to the default generated message.
5834 FAIL_MESSAGE <custom-failure-message>
5836 Specify a custom failure message instead of using the
5837 default generated message. Not recommended.
5838 NAME_MISMATCHED
5840 Indicate that the <PackageName> does not match
5841 ${CMAKE_FIND_PACKAGE_NAME}. This is usually a mistake and
5842 raises a warning, but it may be intentional for usage of
5843 the command for components of a larger package.
5844 Example for the simple signature:
5846 find_package_handle_standard_args(LibXml2 DEFAULT_MSG
5848 LIBXML2_LIBRARY LIBXML2_INCLUDE_DIR)
5849 The LibXml2 package is considered to be found if both LIBXML2_LIBRARY
5851 and LIBXML2_INCLUDE_DIR are valid. Then also LibXml2_FOUND is set to
5852 TRUE. If it is not found and REQUIRED was used, it fails with a mes‐
5853 sage(FATAL_ERROR), independent whether QUIET was used or not. If it is
5854 found, success will be reported, including the content of the first
5855 <required-var>. On repeated CMake runs, the same message will not be
5856 printed again.
5857 NOTE:
5859 If <PackageName> does not match CMAKE_FIND_PACKAGE_NAME for the
5860 calling module, a warning that there is a mismatch is given. The
5861 FPHSA_NAME_MISMATCHED variable may be set to bypass the warning if
5862 using the old signature and the NAME_MISMATCHED argument using the
5863 new signature. To avoid forcing the caller to require newer versions
5864 of CMake for usage, the variable’s value will be used if defined
5865 when the NAME_MISMATCHED argument is not passed for the new signa‐
5866 ture (but using both is an error)..
5867 Example for the full signature:
5869 find_package_handle_standard_args(LibArchive
5871 REQUIRED_VARS LibArchive_LIBRARY LibArchive_INCLUDE_DIR
5872 VERSION_VAR LibArchive_VERSION)
5873 In this case, the LibArchive package is considered to be found if both
5875 LibArchive_LIBRARY and LibArchive_INCLUDE_DIR are valid. Also the ver‐
5876 sion of LibArchive will be checked by using the version contained in
5877 LibArchive_VERSION. Since no FAIL_MESSAGE is given, the default mes‐
5878 sages will be printed.
5879 Another example for the full signature:
5881 find_package(Automoc4 QUIET NO_MODULE HINTS /opt/automoc4)
5883 find_package_handle_standard_args(Automoc4 CONFIG_MODE)
5884 In this case, a FindAutmoc4.cmake module wraps a call to find_pack‐
5886 age(Automoc4 NO_MODULE) and adds an additional search directory for
5887 automoc4. Then the call to find_package_handle_standard_args produces
5888 a proper success/failure message.
5889 FindPackageMessage
5891 find_package_message(<name> "message for user" "find result details")
5892 This function is intended to be used in FindXXX.cmake modules files.
5894 It will print a message once for each unique find result. This is use‐
5895 ful for telling the user where a package was found. The first argument
5896 specifies the name (XXX) of the package. The second argument specifies
5897 the message to display. The third argument lists details about the
5898 find result so that if they change the message will be displayed again.
5899 The macro also obeys the QUIET argument to the find_package command.
5900 Example:
5902 if(X11_FOUND)
5904 find_package_message(X11 "Found X11: ${X11_X11_LIB}"
5905 "[${X11_X11_LIB}][${X11_INCLUDE_DIR}]")
5906 else()
5907 ...
5908 endif()
5909 FortranCInterface
5911 Fortran/C Interface Detection
5912 This module automatically detects the API by which C and Fortran lan‐
5914 guages interact.
5915 Module Variables
5917 Variables that indicate if the mangling is found:
5918 FortranCInterface_GLOBAL_FOUND
5920 Global subroutines and functions.
5921 FortranCInterface_MODULE_FOUND
5923 Module subroutines and functions (declared by “MODULE PROCE‐
5924 DURE”).
5925 This module also provides the following variables to specify the
5927 detected mangling, though a typical use case does not need to reference
5928 them and can use the Module Functions below.
5929 FortranCInterface_GLOBAL_PREFIX
5931 Prefix for a global symbol without an underscore.
5932 FortranCInterface_GLOBAL_SUFFIX
5934 Suffix for a global symbol without an underscore.
5935 FortranCInterface_GLOBAL_CASE
5937 The case for a global symbol without an underscore, either UPPER
5938 or LOWER.
5939 FortranCInterface_GLOBAL__PREFIX
5941 Prefix for a global symbol with an underscore.
5942 FortranCInterface_GLOBAL__SUFFIX
5944 Suffix for a global symbol with an underscore.
5945 FortranCInterface_GLOBAL__CASE
5947 The case for a global symbol with an underscore, either UPPER or
5948 LOWER.
5949 FortranCInterface_MODULE_PREFIX
5951 Prefix for a module symbol without an underscore.
5952 FortranCInterface_MODULE_MIDDLE
5954 Middle of a module symbol without an underscore that appears
5955 between the name of the module and the name of the symbol.
5956 FortranCInterface_MODULE_SUFFIX
5958 Suffix for a module symbol without an underscore.
5959 FortranCInterface_MODULE_CASE
5961 The case for a module symbol without an underscore, either UPPER
5962 or LOWER.
5963 FortranCInterface_MODULE__PREFIX
5965 Prefix for a module symbol with an underscore.
5966 FortranCInterface_MODULE__MIDDLE
5968 Middle of a module symbol with an underscore that appears
5969 between the name of the module and the name of the symbol.
5970 FortranCInterface_MODULE__SUFFIX
5972 Suffix for a module symbol with an underscore.
5973 FortranCInterface_MODULE__CASE
5975 The case for a module symbol with an underscore, either UPPER or
5976 LOWER.
5977 Module Functions
5979 FortranCInterface_HEADER
5980 The FortranCInterface_HEADER function is provided to generate a
5981 C header file containing macros to mangle symbol names:
5982 FortranCInterface_HEADER(<file>
5984 [MACRO_NAMESPACE <macro-ns>]
5985 [SYMBOL_NAMESPACE <ns>]
5986 [SYMBOLS [<module>:]<function> ...])
5987 It generates in <file> definitions of the following macros:
5989 #define FortranCInterface_GLOBAL (name,NAME) ...
5991 #define FortranCInterface_GLOBAL_(name,NAME) ...
5992 #define FortranCInterface_MODULE (mod,name, MOD,NAME) ...
5993 #define FortranCInterface_MODULE_(mod,name, MOD,NAME) ...
5994 These macros mangle four categories of Fortran symbols, respec‐
5996 tively:
5997 · Global symbols without ‘_’: call mysub()
5999 · Global symbols with ‘_’ : call my_sub()
6001 · Module symbols without ‘_’: use mymod; call mysub()
6003 · Module symbols with ‘_’ : use mymod; call my_sub()
6005 If mangling for a category is not known, its macro is left unde‐
6007 fined. All macros require raw names in both lower case and
6008 upper case.
6009 The options are:
6011 MACRO_NAMESPACE
6013 Replace the default FortranCInterface_ prefix with a
6014 given namespace <macro-ns>.
6015 SYMBOLS
6017 List symbols to mangle automatically with C preprocessor
6018 definitions:
6019 <function> ==> #define <ns><function> ...
6021 <module>:<function> ==> #define <ns><module>_<function> ...
6022 If the mangling for some symbol is not known then no pre‐
6024 processor definition is created, and a warning is dis‐
6025 played.
6026 SYMBOL_NAMESPACE
6028 Prefix all preprocessor definitions generated by the SYM‐
6029 BOLS option with a given namespace <ns>.
6030 FortranCInterface_VERIFY
6032 The FortranCInterface_VERIFY function is provided to verify that
6033 the Fortran and C/C++ compilers work together:
6034 FortranCInterface_VERIFY([CXX] [QUIET])
6036 It tests whether a simple test executable using Fortran and C
6038 (and C++ when the CXX option is given) compiles and links suc‐
6039 cessfully. The result is stored in the cache entry FortranCIn‐
6040 terface_VERIFIED_C (or FortranCInterface_VERIFIED_CXX if CXX is
6041 given) as a boolean. If the check fails and QUIET is not given
6042 the function terminates with a fatal error message describing
6043 the problem. The purpose of this check is to stop a build early
6044 for incompatible compiler combinations. The test is built in
6045 the Release configuration.
6046 Example Usage
6048 include(FortranCInterface)
6049 FortranCInterface_HEADER(FC.h MACRO_NAMESPACE "FC_")
6050 This creates a “FC.h” header that defines mangling macros FC_GLOBAL(),
6052 FC_GLOBAL_(), FC_MODULE(), and FC_MODULE_().
6053 include(FortranCInterface)
6055 FortranCInterface_HEADER(FCMangle.h
6056 MACRO_NAMESPACE "FC_"
6057 SYMBOL_NAMESPACE "FC_"
6058 SYMBOLS mysub mymod:my_sub)
6059 This creates a “FCMangle.h” header that defines the same FC_*() man‐
6061 gling macros as the previous example plus preprocessor symbols FC_mysub
6062 and FC_mymod_my_sub.
6063 Additional Manglings
6065 FortranCInterface is aware of possible GLOBAL and MODULE manglings for
6066 many Fortran compilers, but it also provides an interface to specify
6067 new possible manglings. Set the variables:
6068 FortranCInterface_GLOBAL_SYMBOLS
6070 FortranCInterface_MODULE_SYMBOLS
6071 before including FortranCInterface to specify manglings of the symbols
6073 MySub, My_Sub, MyModule:MySub, and My_Module:My_Sub. For example, the
6074 code:
6075 set(FortranCInterface_GLOBAL_SYMBOLS mysub_ my_sub__ MYSUB_)
6077 # ^^^^^ ^^^^^^ ^^^^^
6078 set(FortranCInterface_MODULE_SYMBOLS
6079 __mymodule_MOD_mysub __my_module_MOD_my_sub)
6080 # ^^^^^^^^ ^^^^^ ^^^^^^^^^ ^^^^^^
6081 include(FortranCInterface)
6082 tells FortranCInterface to try given GLOBAL and MODULE manglings. (The
6084 carets point at raw symbol names for clarity in this example but are
6085 not needed.)
6086 GenerateExportHeader
6088 Function for generation of export macros for libraries
6089 This module provides the function GENERATE_EXPORT_HEADER().
6091 The GENERATE_EXPORT_HEADER function can be used to generate a file
6093 suitable for preprocessor inclusion which contains EXPORT macros to be
6094 used in library classes:
6095 GENERATE_EXPORT_HEADER( LIBRARY_TARGET
6097 [BASE_NAME <base_name>]
6098 [EXPORT_MACRO_NAME <export_macro_name>]
6099 [EXPORT_FILE_NAME <export_file_name>]
6100 [DEPRECATED_MACRO_NAME <deprecated_macro_name>]
6101 [NO_EXPORT_MACRO_NAME <no_export_macro_name>]
6102 [INCLUDE_GUARD_NAME <include_guard_name>]
6103 [STATIC_DEFINE <static_define>]
6104 [NO_DEPRECATED_MACRO_NAME <no_deprecated_macro_name>]
6105 [DEFINE_NO_DEPRECATED]
6106 [PREFIX_NAME <prefix_name>]
6107 [CUSTOM_CONTENT_FROM_VARIABLE <variable>]
6108 )
6109 The target properties CXX_VISIBILITY_PRESET and VISIBILITY_INLINES_HID‐
6111 DEN can be used to add the appropriate compile flags for targets. See
6112 the documentation of those target properties, and the convenience vari‐
6113 ables CMAKE_CXX_VISIBILITY_PRESET and CMAKE_VISIBILITY_INLINES_HIDDEN.
6114 By default GENERATE_EXPORT_HEADER() generates macro names in a file
6116 name determined by the name of the library. This means that in the
6117 simplest case, users of GenerateExportHeader will be equivalent to:
6118 set(CMAKE_CXX_VISIBILITY_PRESET hidden)
6120 set(CMAKE_VISIBILITY_INLINES_HIDDEN 1)
6121 add_library(somelib someclass.cpp)
6122 generate_export_header(somelib)
6123 install(TARGETS somelib DESTINATION ${LIBRARY_INSTALL_DIR})
6124 install(FILES
6125 someclass.h
6126 ${PROJECT_BINARY_DIR}/somelib_export.h DESTINATION ${INCLUDE_INSTALL_DIR}
6127 )
6128 And in the ABI header files:
6130 #include "somelib_export.h"
6132 class SOMELIB_EXPORT SomeClass {
6133 ...
6134 };
6135 The CMake fragment will generate a file in the ${CMAKE_CUR‐
6137 RENT_BINARY_DIR} called somelib_export.h containing the macros
6138 SOMELIB_EXPORT, SOMELIB_NO_EXPORT, SOMELIB_DEPRECATED, SOMELIB_DEPRE‐
6139 CATED_EXPORT and SOMELIB_DEPRECATED_NO_EXPORT. They will be followed
6140 by content taken from the variable specified by the CUSTOM_CON‐
6141 TENT_FROM_VARIABLE option, if any. The resulting file should be
6142 installed with other headers in the library.
6143 The BASE_NAME argument can be used to override the file name and the
6145 names used for the macros:
6146 add_library(somelib someclass.cpp)
6148 generate_export_header(somelib
6149 BASE_NAME other_name
6150 )
6151 Generates a file called other_name_export.h containing the macros
6153 OTHER_NAME_EXPORT, OTHER_NAME_NO_EXPORT and OTHER_NAME_DEPRECATED etc.
6154 The BASE_NAME may be overridden by specifying other options in the
6156 function. For example:
6157 add_library(somelib someclass.cpp)
6159 generate_export_header(somelib
6160 EXPORT_MACRO_NAME OTHER_NAME_EXPORT
6161 )
6162 creates the macro OTHER_NAME_EXPORT instead of SOMELIB_EXPORT, but
6164 other macros and the generated file name is as default:
6165 add_library(somelib someclass.cpp)
6167 generate_export_header(somelib
6168 DEPRECATED_MACRO_NAME KDE_DEPRECATED
6169 )
6170 creates the macro KDE_DEPRECATED instead of SOMELIB_DEPRECATED.
6172 If LIBRARY_TARGET is a static library, macros are defined without val‐
6174 ues.
6175 If the same sources are used to create both a shared and a static
6177 library, the uppercased symbol ${BASE_NAME}_STATIC_DEFINE should be
6178 used when building the static library:
6179 add_library(shared_variant SHARED ${lib_SRCS})
6181 add_library(static_variant ${lib_SRCS})
6182 generate_export_header(shared_variant BASE_NAME libshared_and_static)
6183 set_target_properties(static_variant PROPERTIES
6184 COMPILE_FLAGS -DLIBSHARED_AND_STATIC_STATIC_DEFINE)
6185 This will cause the export macros to expand to nothing when building
6187 the static library.
6188 If DEFINE_NO_DEPRECATED is specified, then a macro ${BASE_NAME}_NO_DEP‐
6190 RECATED will be defined This macro can be used to remove deprecated
6191 code from preprocessor output:
6192 option(EXCLUDE_DEPRECATED "Exclude deprecated parts of the library" FALSE)
6194 if (EXCLUDE_DEPRECATED)
6195 set(NO_BUILD_DEPRECATED DEFINE_NO_DEPRECATED)
6196 endif()
6197 generate_export_header(somelib ${NO_BUILD_DEPRECATED})
6198 And then in somelib:
6200 class SOMELIB_EXPORT SomeClass
6202 {
6203 public:
6204 #ifndef SOMELIB_NO_DEPRECATED
6205 SOMELIB_DEPRECATED void oldMethod();
6206 #endif
6207 };
6208 #ifndef SOMELIB_NO_DEPRECATED
6210 void SomeClass::oldMethod() { }
6211 #endif
6212 If PREFIX_NAME is specified, the argument will be used as a prefix to
6214 all generated macros.
6215 For example:
6217 generate_export_header(somelib PREFIX_NAME VTK_)
6219 Generates the macros VTK_SOMELIB_EXPORT etc.
6221 ADD_COMPILER_EXPORT_FLAGS( [<output_variable>] )
6223 The ADD_COMPILER_EXPORT_FLAGS function adds -fvisibility=hidden to
6225 CMAKE_CXX_FLAGS if supported, and is a no-op on Windows which does not
6226 need extra compiler flags for exporting support. You may optionally
6227 pass a single argument to ADD_COMPILER_EXPORT_FLAGS that will be popu‐
6228 lated with the CXX_FLAGS required to enable visibility support for the
6229 compiler/architecture in use.
6230 This function is deprecated. Set the target properties CXX_VISIBIL‐
6232 ITY_PRESET and VISIBILITY_INLINES_HIDDEN instead.
6233 GetPrerequisites
6235 Deprecated since version 3.16: Use file(GET_RUNTIME_DEPENDENCIES)
6236 instead.
6237 Functions to analyze and list executable file prerequisites.
6240 This module provides functions to list the .dll, .dylib or .so files
6242 that an executable or shared library file depends on. (Its prerequi‐
6243 sites.)
6244 It uses various tools to obtain the list of required shared library
6246 files:
6247 dumpbin (Windows)
6249 objdump (MinGW on Windows)
6250 ldd (Linux/Unix)
6251 otool (Mac OSX)
6252 The following functions are provided by this module:
6254 get_prerequisites
6256 list_prerequisites
6257 list_prerequisites_by_glob
6258 gp_append_unique
6259 is_file_executable
6260 gp_item_default_embedded_path
6261 (projects can override with gp_item_default_embedded_path_override)
6262 gp_resolve_item
6263 (projects can override with gp_resolve_item_override)
6264 gp_resolved_file_type
6265 (projects can override with gp_resolved_file_type_override)
6266 gp_file_type
6267 Requires CMake 2.6 or greater because it uses function, break, return
6269 and PARENT_SCOPE.
6270 GET_PREREQUISITES(<target> <prerequisites_var> <exclude_system> <recurse>
6272 <exepath> <dirs> [<rpaths>])
6273 Get the list of shared library files required by <target>. The list in
6275 the variable named <prerequisites_var> should be empty on first entry
6276 to this function. On exit, <prerequisites_var> will contain the list
6277 of required shared library files.
6278 <target> is the full path to an executable file. <prerequisites_var>
6280 is the name of a CMake variable to contain the results. <exclude_sys‐
6281 tem> must be 0 or 1 indicating whether to include or exclude “system”
6282 prerequisites. If <recurse> is set to 1 all prerequisites will be
6283 found recursively, if set to 0 only direct prerequisites are listed.
6284 <exepath> is the path to the top level executable used for @exe‐
6285 cutable_path replacment on the Mac. <dirs> is a list of paths where
6286 libraries might be found: these paths are searched first when a target
6287 without any path info is given. Then standard system locations are
6288 also searched: PATH, Framework locations, /usr/lib…
6289 The variable GET_PREREQUISITES_VERBOSE can be set to true to enable
6291 verbose output.
6292 LIST_PREREQUISITES(<target> [<recurse> [<exclude_system> [<verbose>]]])
6294 Print a message listing the prerequisites of <target>.
6296 <target> is the name of a shared library or executable target or the
6298 full path to a shared library or executable file. If <recurse> is set
6299 to 1 all prerequisites will be found recursively, if set to 0 only
6300 direct prerequisites are listed. <exclude_system> must be 0 or 1 indi‐
6301 cating whether to include or exclude “system” prerequisites. With
6302 <verbose> set to 0 only the full path names of the prerequisites are
6303 printed, set to 1 extra informatin will be displayed.
6304 LIST_PREREQUISITES_BY_GLOB(<glob_arg> <glob_exp>)
6306 Print the prerequisites of shared library and executable files matching
6308 a globbing pattern. <glob_arg> is GLOB or GLOB_RECURSE and <glob_exp>
6309 is a globbing expression used with “file(GLOB” or “file(GLOB_RECURSE”
6310 to retrieve a list of matching files. If a matching file is exe‐
6311 cutable, its prerequisites are listed.
6312 Any additional (optional) arguments provided are passed along as the
6314 optional arguments to the list_prerequisites calls.
6315 GP_APPEND_UNIQUE(<list_var> <value>)
6317 Append <value> to the list variable <list_var> only if the value is not
6319 already in the list.
6320 IS_FILE_EXECUTABLE(<file> <result_var>)
6322 Return 1 in <result_var> if <file> is a binary executable, 0 otherwise.
6324 GP_ITEM_DEFAULT_EMBEDDED_PATH(<item> <default_embedded_path_var>)
6326 Return the path that others should refer to the item by when the item
6328 is embedded inside a bundle.
6329 Override on a per-project basis by providing a project-specific
6331 gp_item_default_embedded_path_override function.
6332 GP_RESOLVE_ITEM(<context> <item> <exepath> <dirs> <resolved_item_var>
6334 [<rpaths>])
6335 Resolve an item into an existing full path file.
6337 Override on a per-project basis by providing a project-specific
6339 gp_resolve_item_override function.
6340 GP_RESOLVED_FILE_TYPE(<original_file> <file> <exepath> <dirs> <type_var>
6342 [<rpaths>])
6343 Return the type of <file> with respect to <original_file>. String
6345 describing type of prerequisite is returned in variable named
6346 <type_var>.
6347 Use <exepath> and <dirs> if necessary to resolve non-absolute <file>
6349 values – but only for non-embedded items.
6350 Possible types are:
6352 system
6354 local
6355 embedded
6356 other
6357 Override on a per-project basis by providing a project-specific
6359 gp_resolved_file_type_override function.
6360 GP_FILE_TYPE(<original_file> <file> <type_var>)
6362 Return the type of <file> with respect to <original_file>. String
6364 describing type of prerequisite is returned in variable named
6365 <type_var>.
6366 Possible types are:
6368 system
6370 local
6371 embedded
6372 other
6373 GNUInstallDirs
6375 Define GNU standard installation directories
6376 Provides install directory variables as defined by the GNU Coding Stan‐
6378 dards.
6379 Result Variables
6381 Inclusion of this module defines the following variables:
6382 CMAKE_INSTALL_<dir>
6384 Destination for files of a given type. This value may be passed to
6385 the DESTINATION options of install() commands for the corresponding
6386 file type.
6387 CMAKE_INSTALL_FULL_<dir>
6389 The absolute path generated from the corresponding
6390 CMAKE_INSTALL_<dir> value. If the value is not already an absolute
6391 path, an absolute path is constructed typically by prepending the
6392 value of the CMAKE_INSTALL_PREFIX variable. However, there are some
6393 special cases as documented below.
6394 where <dir> is one of:
6396 BINDIR user executables (bin)
6398 SBINDIR
6400 system admin executables (sbin)
6401 LIBEXECDIR
6403 program executables (libexec)
6404 SYSCONFDIR
6406 read-only single-machine data (etc)
6407 SHAREDSTATEDIR
6409 modifiable architecture-independent data (com)
6410 LOCALSTATEDIR
6412 modifiable single-machine data (var)
6413 RUNSTATEDIR
6415 run-time variable data (LOCALSTATEDIR/run)
6416 LIBDIR object code libraries (lib or lib64 or lib/<multiarch-tuple> on
6418 Debian)
6419 INCLUDEDIR
6421 C header files (include)
6422 OLDINCLUDEDIR
6424 C header files for non-gcc (/usr/include)
6425 DATAROOTDIR
6427 read-only architecture-independent data root (share)
6428 DATADIR
6430 read-only architecture-independent data (DATAROOTDIR)
6431 INFODIR
6433 info documentation (DATAROOTDIR/info)
6434 LOCALEDIR
6436 locale-dependent data (DATAROOTDIR/locale)
6437 MANDIR man documentation (DATAROOTDIR/man)
6439 DOCDIR documentation root (DATAROOTDIR/doc/PROJECT_NAME)
6441 If the includer does not define a value the above-shown default will be
6443 used and the value will appear in the cache for editing by the user.
6444 Special Cases
6446 The following values of CMAKE_INSTALL_PREFIX are special:
6447 /
6449 For <dir> other than the SYSCONFDIR, LOCALSTATEDIR and RUNSTATEDIR,
6450 the value of CMAKE_INSTALL_<dir> is prefixed with usr/ if it is not
6451 user-specified as an absolute path. For example, the INCLUDEDIR
6452 value include becomes usr/include. This is required by the GNU Cod‐
6453 ing Standards, which state:
6454 When building the complete GNU system, the prefix will be empty
6455 and /usr will be a symbolic link to /.
6456 /usr
6458 For <dir> equal to SYSCONFDIR, LOCALSTATEDIR or RUNSTATEDIR, the
6459 CMAKE_INSTALL_FULL_<dir> is computed by prepending just / to the
6460 value of CMAKE_INSTALL_<dir> if it is not user-specified as an abso‐
6461 lute path. For example, the SYSCONFDIR value etc becomes /etc.
6462 This is required by the GNU Coding Standards.
6463 /opt/...
6465 For <dir> equal to SYSCONFDIR, LOCALSTATEDIR or RUNSTATEDIR, the
6466 CMAKE_INSTALL_FULL_<dir> is computed by appending the prefix to the
6467 value of CMAKE_INSTALL_<dir> if it is not user-specified as an abso‐
6468 lute path. For example, the SYSCONFDIR value etc becomes
6469 /etc/opt/.... This is defined by the Filesystem Hierarchy Standard.
6470 Macros
6472 GNUInstallDirs_get_absolute_install_dir
6473 GNUInstallDirs_get_absolute_install_dir(absvar var)
6475 Set the given variable absvar to the absolute path contained
6477 within the variable var. This is to allow the computation of an
6478 absolute path, accounting for all the special cases documented
6479 above. While this macro is used to compute the various
6480 CMAKE_INSTALL_FULL_<dir> variables, it is exposed publicly to
6481 allow users who create additional path variables to also compute
6482 absolute paths where necessary, using the same logic.
6483 GoogleTest
6485 This module defines functions to help use the Google Test infrastruc‐
6486 ture. Two mechanisms for adding tests are provided. gtest_add_tests()
6487 has been around for some time, originally via find_package(GTest).
6488 gtest_discover_tests() was introduced in CMake 3.10.
6489 The (older) gtest_add_tests() scans source files to identify tests.
6491 This is usually effective, with some caveats, including in cross-com‐
6492 piling environments, and makes setting additional properties on tests
6493 more convenient. However, its handling of parameterized tests is less
6494 comprehensive, and it requires re-running CMake to detect changes to
6495 the list of tests.
6496 The (newer) gtest_discover_tests() discovers tests by asking the com‐
6498 piled test executable to enumerate its tests. This is more robust and
6499 provides better handling of parameterized tests, and does not require
6500 CMake to be re-run when tests change. However, it may not work in a
6501 cross-compiling environment, and setting test properties is less conve‐
6502 nient.
6503 More details can be found in the documentation of the respective func‐
6505 tions.
6506 Both commands are intended to replace use of add_test() to register
6508 tests, and will create a separate CTest test for each Google Test test
6509 case. Note that this is in some cases less efficient, as common set-up
6510 and tear-down logic cannot be shared by multiple test cases executing
6511 in the same instance. However, it provides more fine-grained pass/fail
6512 information to CTest, which is usually considered as more beneficial.
6513 By default, the CTest test name is the same as the Google Test name
6514 (i.e. suite.testcase); see also TEST_PREFIX and TEST_SUFFIX.
6515 gtest_add_tests
6517 Automatically add tests with CTest by scanning source code for
6518 Google Test macros:
6519 gtest_add_tests(TARGET target
6521 [SOURCES src1...]
6522 [EXTRA_ARGS arg1...]
6523 [WORKING_DIRECTORY dir]
6524 [TEST_PREFIX prefix]
6525 [TEST_SUFFIX suffix]
6526 [SKIP_DEPENDENCY]
6527 [TEST_LIST outVar]
6528 )
6529 gtest_add_tests attempts to identify tests by scanning source
6531 files. Although this is generally effective, it uses only a
6532 basic regular expression match, which can be defeated by atypi‐
6533 cal test declarations, and is unable to fully “split” parameter‐
6534 ized tests. Additionally, it requires that CMake be re-run to
6535 discover any newly added, removed or renamed tests (by default,
6536 this means that CMake is re-run when any test source file is
6537 changed, but see SKIP_DEPENDENCY). However, it has the advan‐
6538 tage of declaring tests at CMake time, which somewhat simplifies
6539 setting additional properties on tests, and always works in a
6540 cross-compiling environment.
6541 The options are:
6543 TARGET target
6545 Specifies the Google Test executable, which must be a
6546 known CMake executable target. CMake will substitute the
6547 location of the built executable when running the test.
6548 SOURCES src1...
6550 When provided, only the listed files will be scanned for
6551 test cases. If this option is not given, the SOURCES
6552 property of the specified target will be used to obtain
6553 the list of sources.
6554 EXTRA_ARGS arg1...
6556 Any extra arguments to pass on the command line to each
6557 test case.
6558 WORKING_DIRECTORY dir
6560 Specifies the directory in which to run the discovered
6561 test cases. If this option is not provided, the current
6562 binary directory is used.
6563 TEST_PREFIX prefix
6565 Specifies a prefix to be prepended to the name of each
6566 discovered test case. This can be useful when the same
6567 source files are being used in multiple calls to
6568 gtest_add_test() but with different EXTRA_ARGS.
6569 TEST_SUFFIX suffix
6571 Similar to TEST_PREFIX except the suffix is appended to
6572 the name of every discovered test case. Both TEST_PREFIX
6573 and TEST_SUFFIX may be specified.
6574 SKIP_DEPENDENCY
6576 Normally, the function creates a dependency which will
6577 cause CMake to be re-run if any of the sources being
6578 scanned are changed. This is to ensure that the list of
6579 discovered tests is updated. If this behavior is not
6580 desired (as may be the case while actually writing the
6581 test cases), this option can be used to prevent the
6582 dependency from being added.
6583 TEST_LIST outVar
6585 The variable named by outVar will be populated in the
6586 calling scope with the list of discovered test cases.
6587 This allows the caller to do things like manipulate test
6588 properties of the discovered tests.
6589 include(GoogleTest)
6591 add_executable(FooTest FooUnitTest.cxx)
6592 gtest_add_tests(TARGET FooTest
6593 TEST_SUFFIX .noArgs
6594 TEST_LIST noArgsTests
6595 )
6596 gtest_add_tests(TARGET FooTest
6597 EXTRA_ARGS --someArg someValue
6598 TEST_SUFFIX .withArgs
6599 TEST_LIST withArgsTests
6600 )
6601 set_tests_properties(${noArgsTests} PROPERTIES TIMEOUT 10)
6602 set_tests_properties(${withArgsTests} PROPERTIES TIMEOUT 20)
6603 For backward compatibility, the following form is also sup‐
6605 ported:
6606 gtest_add_tests(exe args files...)
6608 exe The path to the test executable or the name of a CMake
6610 target.
6611 args A ;-list of extra arguments to be passed to executable.
6613 The entire list must be passed as a single argument.
6614 Enclose it in quotes, or pass "" for no arguments.
6615 files...
6617 A list of source files to search for tests and test fix‐
6618 tures. Alternatively, use AUTO to specify that exe is
6619 the name of a CMake executable target whose sources
6620 should be scanned.
6621 include(GoogleTest)
6623 set(FooTestArgs --foo 1 --bar 2)
6624 add_executable(FooTest FooUnitTest.cxx)
6625 gtest_add_tests(FooTest "${FooTestArgs}" AUTO)
6626 gtest_discover_tests
6628 Automatically add tests with CTest by querying the compiled test
6629 executable for available tests:
6630 gtest_discover_tests(target
6632 [EXTRA_ARGS arg1...]
6633 [WORKING_DIRECTORY dir]
6634 [TEST_PREFIX prefix]
6635 [TEST_SUFFIX suffix]
6636 [NO_PRETTY_TYPES] [NO_PRETTY_VALUES]
6637 [PROPERTIES name1 value1...]
6638 [TEST_LIST var]
6639 [DISCOVERY_TIMEOUT seconds]
6640 )
6641 gtest_discover_tests sets up a post-build command on the test
6643 executable that generates the list of tests by parsing the out‐
6644 put from running the test with the --gtest_list_tests argument.
6645 Compared to the source parsing approach of gtest_add_tests(),
6646 this ensures that the full list of tests, including instantia‐
6647 tions of parameterized tests, is obtained. Since test discovery
6648 occurs at build time, it is not necessary to re-run CMake when
6649 the list of tests changes. However, it requires that CROSSCOM‐
6650 PILING_EMULATOR is properly set in order to function in a
6651 cross-compiling environment.
6652 Additionally, setting properties on tests is somewhat less con‐
6654 venient, since the tests are not available at CMake time. Addi‐
6655 tional test properties may be assigned to the set of tests as a
6656 whole using the PROPERTIES option. If more fine-grained test
6657 control is needed, custom content may be provided through an
6658 external CTest script using the TEST_INCLUDE_FILES directory
6659 property. The set of discovered tests is made accessible to
6660 such a script via the <target>_TESTS variable.
6661 The options are:
6663 target Specifies the Google Test executable, which must be a
6665 known CMake executable target. CMake will substitute the
6666 location of the built executable when running the test.
6667 EXTRA_ARGS arg1...
6669 Any extra arguments to pass on the command line to each
6670 test case.
6671 WORKING_DIRECTORY dir
6673 Specifies the directory in which to run the discovered
6674 test cases. If this option is not provided, the current
6675 binary directory is used.
6676 TEST_PREFIX prefix
6678 Specifies a prefix to be prepended to the name of each
6679 discovered test case. This can be useful when the same
6680 test executable is being used in multiple calls to
6681 gtest_discover_tests() but with different EXTRA_ARGS.
6682 TEST_SUFFIX suffix
6684 Similar to TEST_PREFIX except the suffix is appended to
6685 the name of every discovered test case. Both TEST_PREFIX
6686 and TEST_SUFFIX may be specified.
6687 NO_PRETTY_TYPES
6689 By default, the type index of type-parameterized tests is
6690 replaced by the actual type name in the CTest test name.
6691 If this behavior is undesirable (e.g. because the type
6692 names are unwieldy), this option will suppress this
6693 behavior.
6694 NO_PRETTY_VALUES
6696 By default, the value index of value-parameterized tests
6697 is replaced by the actual value in the CTest test name.
6698 If this behavior is undesirable (e.g. because the value
6699 strings are unwieldy), this option will suppress this
6700 behavior.
6701 PROPERTIES name1 value1...
6703 Specifies additional properties to be set on all tests
6704 discovered by this invocation of gtest_discover_tests.
6705 TEST_LIST var
6707 Make the list of tests available in the variable var,
6708 rather than the default <target>_TESTS. This can be use‐
6709 ful when the same test executable is being used in multi‐
6710 ple calls to gtest_discover_tests(). Note that this
6711 variable is only available in CTest.
6712 DISCOVERY_TIMEOUT num
6714 Specifies how long (in seconds) CMake will wait for the
6715 test to enumerate available tests. If the test takes
6716 longer than this, discovery (and your build) will fail.
6717 Most test executables will enumerate their tests very
6718 quickly, but under some exceptional circumstances, a test
6719 may require a longer timeout. The default is 5. See
6720 also the TIMEOUT option of execute_process().
6721 NOTE:
6723 In CMake versions 3.10.1 and 3.10.2, this option was
6724 called TIMEOUT. This clashed with the TIMEOUT test
6725 property, which is one of the common properties that
6726 would be set with the PROPERTIES keyword, usually
6727 leading to legal but unintended behavior. The keyword
6728 was changed to DISCOVERY_TIMEOUT in CMake 3.10.3 to
6729 address this problem. The ambiguous behavior of the
6730 TIMEOUT keyword in 3.10.1 and 3.10.2 has not been pre‐
6731 served.
6732 InstallRequiredSystemLibraries
6734 Include this module to search for compiler-provided system runtime
6735 libraries and add install rules for them. Some optional variables may
6736 be set prior to including the module to adjust behavior:
6737 CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS
6739 Specify additional runtime libraries that may not be detected.
6740 After inclusion any detected libraries will be appended to this.
6741 CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS_SKIP
6743 Set to TRUE to skip calling the install(PROGRAMS) command to
6744 allow the includer to specify its own install rule, using the
6745 value of CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS to get the list of
6746 libraries.
6747 CMAKE_INSTALL_DEBUG_LIBRARIES
6749 Set to TRUE to install the debug runtime libraries when avail‐
6750 able with MSVC tools.
6751 CMAKE_INSTALL_DEBUG_LIBRARIES_ONLY
6753 Set to TRUE to install only the debug runtime libraries with
6754 MSVC tools even if the release runtime libraries are also avail‐
6755 able.
6756 CMAKE_INSTALL_UCRT_LIBRARIES
6758 Set to TRUE to install the Windows Universal CRT libraries for
6759 app-local deployment (e.g. to Windows XP). This is meaningful
6760 only with MSVC from Visual Studio 2015 or higher.
6761 One may set a CMAKE_WINDOWS_KITS_10_DIR environment variable to
6763 an absolute path to tell CMake to look for Windows 10 SDKs in a
6764 custom location. The specified directory is expected to contain
6765 Redist/ucrt/DLLs/* directories.
6766 CMAKE_INSTALL_MFC_LIBRARIES
6768 Set to TRUE to install the MSVC MFC runtime libraries.
6769 CMAKE_INSTALL_OPENMP_LIBRARIES
6771 Set to TRUE to install the MSVC OpenMP runtime libraries
6772 CMAKE_INSTALL_SYSTEM_RUNTIME_DESTINATION
6774 Specify the install(PROGRAMS) command DESTINATION option. If
6775 not specified, the default is bin on Windows and lib elsewhere.
6776 CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS_NO_WARNINGS
6778 Set to TRUE to disable warnings about required library files
6779 that do not exist. (For example, Visual Studio Express editions
6780 may not provide the redistributable files.)
6781 CMAKE_INSTALL_SYSTEM_RUNTIME_COMPONENT
6783 Specify the install(PROGRAMS) command COMPONENT option. If not
6784 specified, no such option will be used.
6785 ProcessorCount
6787 ProcessorCount(var)
6788 Determine the number of processors/cores and save value in ${var}
6790 Sets the variable named ${var} to the number of physical cores avail‐
6792 able on the machine if the information can be determined. Otherwise it
6793 is set to 0. Currently this functionality is implemented for AIX, cyg‐
6794 win, FreeBSD, HPUX, Linux, macOS, QNX, Sun and Windows.
6795 This function is guaranteed to return a positive integer (>=1) if it
6797 succeeds. It returns 0 if there’s a problem determining the processor
6798 count.
6799 Example use, in a ctest -S dashboard script:
6801 include(ProcessorCount)
6803 ProcessorCount(N)
6804 if(NOT N EQUAL 0)
6805 set(CTEST_BUILD_FLAGS -j${N})
6806 set(ctest_test_args ${ctest_test_args} PARALLEL_LEVEL ${N})
6807 endif()
6808 This function is intended to offer an approximation of the value of the
6810 number of compute cores available on the current machine, such that you
6811 may use that value for parallel building and parallel testing. It is
6812 meant to help utilize as much of the machine as seems reasonable. Of
6813 course, knowledge of what else might be running on the machine simulta‐
6814 neously should be used when deciding whether to request a machine’s
6815 full capacity all for yourself.
6816 SelectLibraryConfigurations
6818 select_library_configurations(basename)
6819 This macro takes a library base name as an argument, and will choose
6821 good values for the variables
6822 basename_LIBRARY
6824 basename_LIBRARIES
6825 basename_LIBRARY_DEBUG
6826 basename_LIBRARY_RELEASE
6827 depending on what has been found and set.
6829 If only basename_LIBRARY_RELEASE is defined, basename_LIBRARY will be
6831 set to the release value, and basename_LIBRARY_DEBUG will be set to
6832 basename_LIBRARY_DEBUG-NOTFOUND. If only basename_LIBRARY_DEBUG is
6833 defined, then basename_LIBRARY will take the debug value, and base‐
6834 name_LIBRARY_RELEASE will be set to basename_LIBRARY_RELEASE-NOTFOUND.
6835 If the generator supports configuration types, then basename_LIBRARY
6837 and basename_LIBRARIES will be set with debug and optimized flags spec‐
6838 ifying the library to be used for the given configuration. If no build
6839 type has been set or the generator in use does not support configura‐
6840 tion types, then basename_LIBRARY and basename_LIBRARIES will take only
6841 the release value, or the debug value if the release one is not set.
6842 SquishTestScript
6844 This script launches a GUI test using Squish. You should not call the
6845 script directly; instead, you should access it via the SQUISH_ADD_TEST
6846 macro that is defined in FindSquish.cmake.
6847 This script starts the Squish server, launches the test on the client,
6849 and finally stops the squish server. If any of these steps fail
6850 (including if the tests do not pass) then a fatal error is raised.
6851 TestBigEndian
6853 Define macro to determine endian type
6854 Check if the system is big endian or little endian
6856 TEST_BIG_ENDIAN(VARIABLE)
6858 VARIABLE - variable to store the result to
6859 TestForANSIForScope
6861 Check for ANSI for scope support
6862 Check if the compiler restricts the scope of variables declared in a
6864 for-init-statement to the loop body.
6865 CMAKE_NO_ANSI_FOR_SCOPE - holds result
6867 TestForANSIStreamHeaders
6869 Test for compiler support of ANSI stream headers iostream, etc.
6870 check if the compiler supports the standard ANSI iostream header (with‐
6872 out the .h)
6873 CMAKE_NO_ANSI_STREAM_HEADERS - defined by the results
6875 TestForSSTREAM
6877 Test for compiler support of ANSI sstream header
6878 check if the compiler supports the standard ANSI sstream header
6880 CMAKE_NO_ANSI_STRING_STREAM - defined by the results
6882 TestForSTDNamespace
6884 Test for std:: namespace support
6885 check if the compiler supports std:: on stl classes
6887 CMAKE_NO_STD_NAMESPACE - defined by the results
6889 UseEcos
6891 This module defines variables and macros required to build eCos appli‐
6892 cation.
6893 This file contains the following macros: ECOS_ADD_INCLUDE_DIRECTORIES()
6895 - add the eCos include dirs ECOS_ADD_EXECUTABLE(name source1 … sourceN
6896 ) - create an eCos executable ECOS_ADJUST_DIRECTORY(VAR source1 …
6897 sourceN ) - adjusts the path of the source files and puts the result
6898 into VAR
6899 Macros for selecting the toolchain: ECOS_USE_ARM_ELF_TOOLS() - enable
6901 the ARM ELF toolchain for the directory where it is called
6902 ECOS_USE_I386_ELF_TOOLS() - enable the i386 ELF toolchain for the
6903 directory where it is called ECOS_USE_PPC_EABI_TOOLS() - enable the
6904 PowerPC toolchain for the directory where it is called
6905 It contains the following variables: ECOS_DEFINITIONS ECOSCONFIG_EXE‐
6907 CUTABLE ECOS_CONFIG_FILE - defaults to ecos.ecc, if your eCos configu‐
6908 ration file has a different name, adjust this variable for internal use
6909 only:
6910 ECOS_ADD_TARGET_LIB
6912 UseJavaClassFilelist
6914 This script create a list of compiled Java class files to be added to a
6915 jar file. This avoids including cmake files which get created in the
6916 binary directory.
6917 UseJava
6919 Use Module for Java
6920 This file provides functions for Java. It is assumed that FindJava has
6922 already been loaded. See FindJava for information on how to load Java
6923 into your CMake project.
6924 Creating And Installing JARs
6926 add_jar(<target_name>
6927 [SOURCES] <source1> [<source2>...] [<resource1>...]
6928 [INCLUDE_JARS <jar1> [<jar2>...]]
6929 [ENTRY_POINT <entry>]
6930 [VERSION <version>]
6931 [OUTPUT_NAME <name>]
6932 [OUTPUT_DIR <dir>]
6933 [GENERATE_NATIVE_HEADERS <target> [DESTINATION <dir>]]
6934 )
6935 This command creates a <target_name>.jar. It compiles the given
6937 <source> files and adds the given <resource> files to the jar file.
6938 Source files can be java files or listing files (prefixed by @). If
6939 only resource files are given then just a jar file is created. The
6940 list of INCLUDE_JARS are added to the classpath when compiling the java
6941 sources and also to the dependencies of the target. INCLUDE_JARS also
6942 accepts other target names created by add_jar(). For backwards compat‐
6943 ibility, jar files listed as sources are ignored (as they have been
6944 since the first version of this module).
6945 The default OUTPUT_DIR can also be changed by setting the variable
6947 CMAKE_JAVA_TARGET_OUTPUT_DIR.
6948 Optionally, using option GENERATE_NATIVE_HEADERS, native header files
6950 can be generated for methods declared as native. These files provide
6951 the connective glue that allow your Java and C code to interact. An
6952 INTERFACE target will be created for an easy usage of generated files.
6953 Sub-option DESTINATION can be used to specify the output directory for
6954 generated header files.
6955 GENERATE_NATIVE_HEADERS option requires, at least, version 1.8 of the
6957 JDK.
6958 The add_jar() function sets the following target properties on <tar‐
6960 get_name>:
6961 INSTALL_FILES
6963 The files which should be installed. This is used by
6964 install_jar().
6965 JNI_SYMLINK
6967 The JNI symlink which should be installed. This is used by
6968 install_jni_symlink().
6969 JAR_FILE
6971 The location of the jar file so that you can include it.
6972 CLASSDIR
6974 The directory where the class files can be found. For example
6975 to use them with javah.
6976 install_jar(<target_name> <destination>)
6978 install_jar(<target_name> DESTINATION <destination> [COMPONENT <component>])
6979 This command installs the <target_name> files to the given <destina‐
6981 tion>. It should be called in the same scope as add_jar() or it will
6982 fail.
6983 The install_jar() function sets the INSTALL_DESTINATION target property
6985 on jars so installed. This property holds the <destination> as
6986 described above, and is used by install_jar_exports(). You can get
6987 this information with get_property() and the INSTALL_DESTINATION prop‐
6988 erty key.
6989 install_jni_symlink(<target_name> <destination>)
6991 install_jni_symlink(<target_name> DESTINATION <destination> [COMPONENT <component>])
6992 This command installs the <target_name> JNI symlinks to the given <des‐
6994 tination>. It should be called in the same scope as add_jar() or it
6995 will fail.
6996 install_jar_exports(TARGETS <jars>...
6998 [NAMESPACE <namespace>]
6999 FILE <filename>
7000 DESTINATION <destination> [COMPONENT <component>])
7001 This command installs a target export file <filename> for the named jar
7003 targets to the given <destination> directory. Its function is similar
7004 to that of install(EXPORTS).
7005 export_jars(TARGETS <jars>...
7007 [NAMESPACE <namespace>]
7008 FILE <filename>)
7009 This command writes a target export file <filename> for the named
7011 <jars> targets. Its function is similar to that of export().
7012 Examples
7014 To add compile flags to the target you can set these flags with the
7015 following variable:
7016 set(CMAKE_JAVA_COMPILE_FLAGS -nowarn)
7018 To add a path or a jar file to the class path you can do this with the
7020 CMAKE_JAVA_INCLUDE_PATH variable.
7021 set(CMAKE_JAVA_INCLUDE_PATH /usr/share/java/shibboleet.jar)
7023 To use a different output name for the target you can set it with:
7025 add_jar(foobar foobar.java OUTPUT_NAME shibboleet.jar)
7027 To use a different output directory than CMAKE_CURRENT_BINARY_DIR you
7029 can set it with:
7030 add_jar(foobar foobar.java OUTPUT_DIR ${PROJECT_BINARY_DIR}/bin)
7032 To define an entry point in your jar you can set it with the
7034 ENTRY_POINT named argument:
7035 add_jar(example ENTRY_POINT com/examples/MyProject/Main)
7037 To define a custom manifest for the jar, you can set it with the MANI‐
7039 FEST named argument:
7040 add_jar(example MANIFEST /path/to/manifest)
7042 To add a version to the target output name you can set it using the
7044 VERSION named argument to add_jar(). The following example will create
7045 a jar file with the name shibboleet-1.0.0.jar and will create a symlink
7046 shibboleet.jar pointing to the jar with the version information.
7047 add_jar(shibboleet shibbotleet.java VERSION 1.2.0)
7049 If the target is a JNI library, utilize the following commands to cre‐
7051 ate a JNI symbolic link:
7052 set(CMAKE_JNI_TARGET TRUE)
7054 add_jar(shibboleet shibbotleet.java VERSION 1.2.0)
7055 install_jar(shibboleet ${LIB_INSTALL_DIR}/shibboleet)
7056 install_jni_symlink(shibboleet ${JAVA_LIB_INSTALL_DIR})
7057 If a single target needs to produce more than one jar from its java
7059 source code, to prevent the accumulation of duplicate class files in
7060 subsequent jars, set/reset CMAKE_JAR_CLASSES_PREFIX prior to calling
7061 the add_jar() function:
7062 set(CMAKE_JAR_CLASSES_PREFIX com/redhat/foo)
7064 add_jar(foo foo.java)
7065 set(CMAKE_JAR_CLASSES_PREFIX com/redhat/bar)
7067 add_jar(bar bar.java)
7068 For an optimum usage of option GENERATE_NATIVE_HEADERS, it is recom‐
7070 mended to include module JNI before any call to add_jar(). The produced
7071 target for native headers can then be used to compile C/C++ sources
7072 with the target_link_libraries() command.
7073 find_package(JNI)
7075 add_jar(foo foo.java GENERATE_NATIVE_HEADERS foo-native)
7076 add_library(bar bar.cpp)
7077 target_link_libraries(bar PRIVATE foo-native)
7078 Finding JARs
7080 find_jar(<VAR>
7081 <name> | NAMES <name1> [<name2>...]
7082 [PATHS <path1> [<path2>... ENV <var>]]
7083 [VERSIONS <version1> [<version2>]]
7084 [DOC "cache documentation string"]
7085 )
7086 This command is used to find a full path to the named jar. A cache
7088 entry named by <VAR> is created to store the result of this command.
7089 If the full path to a jar is found the result is stored in the variable
7090 and the search will not repeated unless the variable is cleared. If
7091 nothing is found, the result will be <VAR>-NOTFOUND, and the search
7092 will be attempted again next time find_jar() is invoked with the same
7093 variable. The name of the full path to a file that is searched for is
7094 specified by the names listed after NAMES argument. Additional search
7095 locations can be specified after the PATHS argument. If you require
7096 special a version of a jar file you can specify it with the VERSIONS
7097 argument. The argument after DOC will be used for the documentation
7098 string in the cache.
7099 Javadoc
7101 The create_javadoc() command can be used to create java documentation
7102 based on files or packages. For more details please read the javadoc
7103 manpage.
7104 There are two main signatures for create_javadoc(). The first signa‐
7106 ture works with package names on a path with source files.
7107 create_javadoc(<VAR>
7109 PACKAGES <pkg1> [<pkg2>...]
7110 [SOURCEPATH <sourcepath>]
7111 [CLASSPATH <classpath>]
7112 [INSTALLPATH <install path>]
7113 [DOCTITLE "the documentation title"]
7114 [WINDOWTITLE "the title of the document"]
7115 [AUTHOR TRUE|FALSE]
7116 [USE TRUE|FALSE]
7117 [VERSION TRUE|FALSE]
7118 )
7119 For example:
7121 create_javadoc(my_example_doc
7123 PACKAGES com.example.foo com.example.bar
7124 SOURCEPATH "${CMAKE_CURRENT_SOURCE_DIR}"
7125 CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH}
7126 WINDOWTITLE "My example"
7127 DOCTITLE "<h1>My example</h1>"
7128 AUTHOR TRUE
7129 USE TRUE
7130 VERSION TRUE
7131 )
7132 The second signature for create_javadoc() works on a given list of
7134 files.
7135 create_javadoc(<VAR>
7137 FILES <file1> [<file2>...]
7138 [CLASSPATH <classpath>]
7139 [INSTALLPATH <install path>]
7140 [DOCTITLE "the documentation title"]
7141 [WINDOWTITLE "the title of the document"]
7142 [AUTHOR TRUE|FALSE]
7143 [USE TRUE|FALSE]
7144 [VERSION TRUE|FALSE]
7145 )
7146 For example:
7148 create_javadoc(my_example_doc
7150 FILES ${example_SRCS}
7151 CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH}
7152 WINDOWTITLE "My example"
7153 DOCTITLE "<h1>My example</h1>"
7154 AUTHOR TRUE
7155 USE TRUE
7156 VERSION TRUE
7157 )
7158 Both signatures share most of the options. These options are the same
7160 as what you can find in the javadoc manpage. Please look at the man‐
7161 page for CLASSPATH, DOCTITLE, WINDOWTITLE, AUTHOR, USE and VERSION.
7162 If you don’t set the INSTALLPATH, then by default the documentation
7164 will be installed to :
7165 ${CMAKE_INSTALL_PREFIX}/share/javadoc/<VAR>
7167 Header Generation
7169 create_javah(TARGET <target> | GENERATED_FILES <VAR>
7170 CLASSES <class>...
7171 [CLASSPATH <classpath>...]
7172 [DEPENDS <depend>...]
7173 [OUTPUT_NAME <path>|OUTPUT_DIR <path>]
7174 )
7175 Create C header files from java classes. These files provide the con‐
7177 nective glue that allow your Java and C code to interact.
7178 Deprecated since version 3.11.
7180 NOTE:
7183 This command will no longer be supported starting with version 10 of
7184 the JDK due to the suppression of javah tool. The add_jar(GENER‐
7185 ATE_NATIVE_HEADERS) command should be used instead.
7186 There are two main signatures for create_javah(). The first signature
7188 returns generated files through variable specified by the GENER‐
7189 ATED_FILES option. For example:
7190 create_javah(GENERATED_FILES files_headers
7192 CLASSES org.cmake.HelloWorld
7193 CLASSPATH hello.jar
7194 )
7195 The second signature for create_javah() creates a target which encapsu‐
7197 lates header files generation. E.g.
7198 create_javah(TARGET target_headers
7200 CLASSES org.cmake.HelloWorld
7201 CLASSPATH hello.jar
7202 )
7203 Both signatures share same options.
7205 CLASSES <class>...
7207 Specifies Java classes used to generate headers.
7208 CLASSPATH <classpath>...
7210 Specifies various paths to look up classes. Here .class files,
7211 jar files or targets created by command add_jar can be used.
7212 DEPENDS <depend>...
7214 Targets on which the javah target depends.
7215 OUTPUT_NAME <path>
7217 Concatenates the resulting header files for all the classes
7218 listed by option CLASSES into <path>. Same behavior as option
7219 -o of javah tool.
7220 OUTPUT_DIR <path>
7222 Sets the directory where the header files will be generated.
7223 Same behavior as option -d of javah tool. If not specified,
7224 CMAKE_CURRENT_BINARY_DIR is used as the output directory.
7225 UseJavaSymlinks
7227 Helper script for UseJava.cmake
7228 UseSWIG
7230 This file provides support for SWIG. It is assumed that FindSWIG module
7231 has already been loaded.
7232 Defines the following command for use with SWIG:
7234 swig_add_library
7236 Define swig module with given name and specified language:
7237 swig_add_library(<name>
7239 [TYPE <SHARED|MODULE|STATIC|USE_BUILD_SHARED_LIBS>]
7240 LANGUAGE <language>
7241 [NO_PROXY]
7242 [OUTPUT_DIR <directory>]
7243 [OUTFILE_DIR <directory>]
7244 SOURCES <file>...
7245 )
7246 Targets created with the swig_add_library command have the same
7248 capabilities as targets created with the add_library() command,
7249 so those targets can be used with any command expecting a target
7250 (e.g. target_link_libraries()).
7251 NOTE:
7253 This command creates a target with the specified <name> when
7254 policy CMP0078 is set to NEW. Otherwise, the legacy behavior
7255 will choose a different target name and store it in the
7256 SWIG_MODULE_<name>_REAL_NAME variable.
7257 NOTE:
7259 For multi-config generators, this module does not support
7260 configuration-specific files generated by SWIG. All build
7261 configurations must result in the same generated source file.
7262 TYPE SHARED, MODULE and STATIC have the same semantic as for
7264 the add_library() command. If USE_BUILD_SHARED_LIBS is
7265 specified, the library type will be STATIC or SHARED
7266 based on whether the current value of the
7267 BUILD_SHARED_LIBS variable is ON. If no type is speci‐
7268 fied, MODULE will be used.
7269 LANGUAGE
7271 Specify the target language.
7272 NO_PROXY
7274 Prevent the generation of the wrapper layer (swig
7275 -noproxy option).
7276 OUTPUT_DIR
7278 Specify where to write the language specific files (swig
7279 -outdir option). If not given, the CMAKE_SWIG_OUTDIR
7280 variable will be used. If neither is specified, the
7281 default depends on the value of the UseSWIG_MODULE_VER‐
7282 SION variable as follows:
7283 · If UseSWIG_MODULE_VERSION is 1 or is undefined, output
7285 is written to the CMAKE_CURRENT_BINARY_DIR directory.
7286 · If UseSWIG_MODULE_VERSION is 2, a dedicated directory
7288 will be used. The path of this directory can be
7289 retrieved from the SWIG_SUPPORT_FILES_DIRECTORY target
7290 property.
7291 OUTFILE_DIR
7293 Specify an output directory name where the generated
7294 source file will be placed (swig -o option). If not spec‐
7295 ified, the SWIG_OUTFILE_DIR variable will be used. If
7296 neither is specified, OUTPUT_DIR or CMAKE_SWIG_OUTDIR is
7297 used instead.
7298 SOURCES
7300 List of sources for the library. Files with extension .i
7301 will be identified as sources for the SWIG tool. Other
7302 files will be handled in the standard way. This behavior
7303 can be overriden by specifying the variable
7304 SWIG_SOURCE_FILE_EXTENSIONS.
7305 NOTE:
7307 If UseSWIG_MODULE_VERSION is set to 2, it is strongly recom‐
7308 mended to use a dedicated directory unique to the target when
7309 either the OUTPUT_DIR option or the CMAKE_SWIG_OUTDIR vari‐
7310 able are specified. The output directory contents are erased
7311 as part of the target build, so to prevent interference
7312 between targets or losing other important files, each target
7313 should have its own dedicated output directory.
7314 swig_link_libraries
7316 Link libraries to swig module:
7317 swig_link_libraries(<name> <item>...)
7319 This command has same capabilities as target_link_libraries()
7321 command.
7322 NOTE:
7324 If variable UseSWIG_TARGET_NAME_PREFERENCE is set to STAN‐
7325 DARD, this command is deprecated and target_link_libraries()
7326 command must be used instead.
7327 Source file properties on module files must be set before the invoca‐
7329 tion of the swig_add_library command to specify special behavior of
7330 SWIG and ensure generated files will receive the required settings.
7331 CPLUSPLUS
7333 Call SWIG in c++ mode. For example:
7334 set_property(SOURCE mymod.i PROPERTY CPLUSPLUS ON)
7336 swig_add_library(mymod LANGUAGE python SOURCES mymod.i)
7337 INCLUDE_DIRECTORIES, COMPILE_DEFINITIONS and COMPILE_OPTIONS
7339 Add custom flags to SWIG compiler and have same semantic as
7340 properties INCLUDE_DIRECTORIES, COMPILE_DEFINITIONS and COM‐
7341 PILE_OPTIONS.
7342 USE_TARGET_INCLUDE_DIRECTORIES
7344 If set to TRUE, contents of target property INCLUDE_DIRECTORIES
7345 will be forwarded to SWIG compiler. If set to FALSE target
7346 property INCLUDE_DIRECTORIES will be ignored. If not set, target
7347 property SWIG_USE_TARGET_INCLUDE_DIRECTORIES will be considered.
7348 GENERATED_INCLUDE_DIRECTORIES, GENERATED_COMPILE_DEFINITIONS and GENER‐
7350 ATED_COMPILE_OPTIONS
7351 Add custom flags to the C/C++ generated source. They will fill,
7352 respectively, properties INCLUDE_DIRECTORIES, COMPILE_DEFINI‐
7353 TIONS and COMPILE_OPTIONS of generated C/C++ file.
7354 DEPENDS
7356 Specify additional dependencies to the source file.
7357 SWIG_MODULE_NAME
7359 Specify the actual import name of the module in the target lan‐
7360 guage. This is required if it cannot be scanned automatically
7361 from source or different from the module file basename. For
7362 example:
7363 set_property(SOURCE mymod.i PROPERTY SWIG_MODULE_NAME mymod_realname)
7365 NOTE:
7367 If policy CMP0086 is set to NEW, -module <module_name> is
7368 passed to SWIG compiler.
7369 Target library properties can be set to apply same configuration to all
7371 SWIG input files.
7372 SWIG_INCLUDE_DIRECTORIES, SWIG_COMPILE_DEFINITIONS and SWIG_COM‐
7374 PILE_OPTIONS
7375 These properties will be applied to all SWIG input files and
7376 have same semantic as target properties INCLUDE_DIRECTORIES,
7377 COMPILE_DEFINITIONS and COMPILE_OPTIONS.
7378 set (UseSWIG_TARGET_NAME_PREFERENCE STANDARD)
7380 swig_add_library(mymod LANGUAGE python SOURCES mymod.i)
7381 set_property(TARGET mymod PROPERTY SWIG_COMPILE_DEFINITIONS MY_DEF1 MY_DEF2)
7382 set_property(TARGET mymod PROPERTY SWIG_COMPILE_OPTIONS -bla -blb)
7383 SWIG_USE_TARGET_INCLUDE_DIRECTORIES
7385 If set to TRUE, contents of target property INCLUDE_DIRECTORIES
7386 will be forwarded to SWIG compiler. If set to FALSE or not
7387 defined, target property INCLUDE_DIRECTORIES will be ignored.
7388 This behavior can be overridden by specifying source property
7389 USE_TARGET_INCLUDE_DIRECTORIES.
7390 SWIG_GENERATED_INCLUDE_DIRECTORIES, SWIG_GENERATED_COMPILE_DEFINITIONS
7392 and SWIG_GENERATED_COMPILE_OPTIONS
7393 These properties will populate, respectively, properties
7394 INCLUDE_DIRECTORIES, COMPILE_DEFINITIONS and COMPILE_FLAGS of
7395 all generated C/C++ files.
7396 SWIG_DEPENDS
7398 Add dependencies to all SWIG input files.
7399 The following target properties are output properties and can be used
7401 to get information about support files generated by SWIG interface com‐
7402 pilation.
7403 SWIG_SUPPORT_FILES
7405 This output property list of wrapper files generated during SWIG
7406 compilation.
7407 set (UseSWIG_TARGET_NAME_PREFERENCE STANDARD)
7409 swig_add_library(mymod LANGUAGE python SOURCES mymod.i)
7410 get_property(support_files TARGET mymod PROPERTY SWIG_SUPPORT_FILES)
7411 NOTE:
7413 Only most principal support files are listed. In case some
7414 advanced features of SWIG are used (for example %template),
7415 associated support files may not be listed. Prefer to use the
7416 SWIG_SUPPORT_FILES_DIRECTORY property to handle support
7417 files.
7418 SWIG_SUPPORT_FILES_DIRECTORY
7420 This output property specifies the directory where support files
7421 will be generated.
7422 Some variables can be set to customize the behavior of swig_add_library
7424 as well as SWIG:
7425 UseSWIG_MODULE_VERSION
7427 Specify different behaviors for UseSWIG module.
7428 · Set to 1 or undefined: Legacy behavior is applied.
7430 · Set to 2: A new strategy is applied regarding support files:
7432 the output directory of support files is erased before SWIG
7433 interface compilation.
7434 CMAKE_SWIG_FLAGS
7436 Add flags to all swig calls.
7437 CMAKE_SWIG_OUTDIR
7439 Specify where to write the language specific files (swig -outdir
7440 option).
7441 SWIG_OUTFILE_DIR
7443 Specify an output directory name where the generated source file
7444 will be placed. If not specified, CMAKE_SWIG_OUTDIR is used.
7445 SWIG_MODULE_<name>_EXTRA_DEPS
7447 Specify extra dependencies for the generated module for <name>.
7448 SWIG_SOURCE_FILE_EXTENSIONS
7450 Specify a list of source file extensions to override the default
7451 behavior of considering only .i files as sources for the SWIG
7452 tool. For example:
7453 set(SWIG_SOURCE_FILE_EXTENSIONS ".i" ".swg")
7455 UsewxWidgets
7457 Convenience include for using wxWidgets library.
7458 Determines if wxWidgets was FOUND and sets the appropriate libs,
7460 incdirs, flags, etc. INCLUDE_DIRECTORIES and LINK_DIRECTORIES are
7461 called.
7462 USAGE
7464 # Note that for MinGW users the order of libs is important!
7466 find_package(wxWidgets REQUIRED net gl core base)
7467 include(${wxWidgets_USE_FILE})
7468 # and for each of your dependent executable/library targets:
7469 target_link_libraries(<YourTarget> ${wxWidgets_LIBRARIES})
7470 DEPRECATED
7472 LINK_LIBRARIES is not called in favor of adding dependencies per target.
7474 AUTHOR
7476 Jan Woetzel <jw -at- mip.informatik.uni-kiel.de>
7478 WriteCompilerDetectionHeader
7480 This module provides the function write_compiler_detection_header().
7481 This function can be used to generate a file suitable for preprocessor
7483 inclusion which contains macros to be used in source code:
7484 write_compiler_detection_header(
7486 FILE <file>
7487 PREFIX <prefix>
7488 [OUTPUT_FILES_VAR <output_files_var> OUTPUT_DIR <output_dir>]
7489 COMPILERS <compiler> [...]
7490 FEATURES <feature> [...]
7491 [BARE_FEATURES <feature> [...]]
7492 [VERSION <version>]
7493 [PROLOG <prolog>]
7494 [EPILOG <epilog>]
7495 [ALLOW_UNKNOWN_COMPILERS]
7496 [ALLOW_UNKNOWN_COMPILER_VERSIONS]
7497 )
7498 This generates the file <file> with macros which all have the prefix
7500 <prefix>.
7501 By default, all content is written directly to the <file>. The OUT‐
7503 PUT_FILES_VAR may be specified to cause the compiler-specific content
7504 to be written to separate files. The separate files are then available
7505 in the <output_files_var> and may be consumed by the caller for instal‐
7506 lation for example. The OUTPUT_DIR specifies a relative path from the
7507 main <file> to the compiler-specific files. For example:
7508 write_compiler_detection_header(
7510 FILE climbingstats_compiler_detection.h
7511 PREFIX ClimbingStats
7512 OUTPUT_FILES_VAR support_files
7513 OUTPUT_DIR compilers
7514 COMPILERS GNU Clang MSVC Intel
7515 FEATURES cxx_variadic_templates
7516 )
7517 install(FILES
7518 ${CMAKE_CURRENT_BINARY_DIR}/climbingstats_compiler_detection.h
7519 DESTINATION include
7520 )
7521 install(FILES
7522 ${support_files}
7523 DESTINATION include/compilers
7524 )
7525 VERSION may be used to specify the API version to be generated. Future
7527 versions of CMake may introduce alternative APIs. A given API is
7528 selected by any <version> value greater than or equal to the version of
7529 CMake that introduced the given API and less than the version of CMake
7530 that introduced its succeeding API. The value of the CMAKE_MINI‐
7531 MUM_REQUIRED_VERSION variable is used if no explicit version is speci‐
7532 fied. (As of CMake version 3.17.2 there is only one API version.)
7533 PROLOG may be specified as text content to write at the start of the
7535 header. EPILOG may be specified as text content to write at the end of
7536 the header
7537 At least one <compiler> and one <feature> must be listed. Compilers
7539 which are known to CMake, but not specified are detected and a pre‐
7540 processor #error is generated for them. A preprocessor macro matching
7541 <PREFIX>_COMPILER_IS_<compiler> is generated for each compiler known to
7542 CMake to contain the value 0 or 1.
7543 Possible compiler identifiers are documented with the CMAKE_<LANG>_COM‐
7545 PILER_ID variable. Available features in this version of CMake are
7546 listed in the CMAKE_C_KNOWN_FEATURES and CMAKE_CXX_KNOWN_FEATURES
7547 global properties. The {c,cxx}_std_* meta-features are ignored if
7548 requested.
7549 See the cmake-compile-features(7) manual for information on compile
7551 features.
7552 BARE_FEATURES will define the compatibility macros with the name used
7554 in newer versions of the language standard, so the code can use the new
7555 feature name unconditionally.
7556 ALLOW_UNKNOWN_COMPILERS and ALLOW_UNKNOWN_COMPILER_VERSIONS cause the
7558 module to generate conditions that treat unknown compilers as simply
7559 lacking all features. Without these options the default behavior is to
7560 generate a #error for unknown compilers and versions.
7561 Feature Test Macros
7563 For each compiler, a preprocessor macro is generated matching <PRE‐
7564 FIX>_COMPILER_IS_<compiler> which has the content either 0 or 1,
7565 depending on the compiler in use. Preprocessor macros for compiler ver‐
7566 sion components are generated matching <PREFIX>_COMPILER_VERSION_MAJOR
7567 <PREFIX>_COMPILER_VERSION_MINOR and <PREFIX>_COMPILER_VERSION_PATCH
7568 containing decimal values for the corresponding compiler version compo‐
7569 nents, if defined.
7570 A preprocessor test is generated based on the compiler version denoting
7572 whether each feature is enabled. A preprocessor macro matching <PRE‐
7573 FIX>_COMPILER_<FEATURE>, where <FEATURE> is the upper-case <feature>
7574 name, is generated to contain the value 0 or 1 depending on whether the
7575 compiler in use supports the feature:
7576 write_compiler_detection_header(
7578 FILE climbingstats_compiler_detection.h
7579 PREFIX ClimbingStats
7580 COMPILERS GNU Clang AppleClang MSVC Intel
7581 FEATURES cxx_variadic_templates
7582 )
7583 #if ClimbingStats_COMPILER_CXX_VARIADIC_TEMPLATES
7585 template<typename... T>
7586 void someInterface(T t...) { /* ... */ }
7587 #else
7588 // Compatibility versions
7589 template<typename T1>
7590 void someInterface(T1 t1) { /* ... */ }
7591 template<typename T1, typename T2>
7592 void someInterface(T1 t1, T2 t2) { /* ... */ }
7593 template<typename T1, typename T2, typename T3>
7594 void someInterface(T1 t1, T2 t2, T3 t3) { /* ... */ }
7595 #endif
7596 Symbol Macros
7598 Some additional symbol-defines are created for particular features for
7599 use as symbols which may be conditionally defined empty:
7600 class MyClass ClimbingStats_FINAL
7602 {
7603 ClimbingStats_CONSTEXPR int someInterface() { return 42; }
7604 };
7605 The ClimbingStats_FINAL macro will expand to final if the compiler (and
7607 its flags) support the cxx_final feature, and the ClimbingStats_CONST‐
7608 EXPR macro will expand to constexpr if cxx_constexpr is supported.
7609 If BARE_FEATURES cxx_final was given as argument the final keyword will
7611 be defined for old compilers, too.
7612 The following features generate corresponding symbol defines and if
7614 they are available as BARE_FEATURES:
7615 ┌──────────────────┬────────────────────┬─────────────┬──────┐
7617 │Feature │ Define │ Symbol │ bare │
7618 ├──────────────────┼────────────────────┼─────────────┼──────┤
7619 │c_restrict │ <PRE‐ │ restrict │ yes │
7620 │ │ FIX>_RESTRICT │ │ │
7621 ├──────────────────┼────────────────────┼─────────────┼──────┤
7622 │cxx_constexpr │ <PREFIX>_CONST‐ │ constexpr │ yes │
7623 │ │ EXPR │ │ │
7624 ├──────────────────┼────────────────────┼─────────────┼──────┤
7625 │cxx_deleted_func‐ │ <PRE‐ │ = delete │ │
7626 │tions │ FIX>_DELETED_FUNC‐ │ │ │
7627 │ │ TION │ │ │
7628 ├──────────────────┼────────────────────┼─────────────┼──────┤
7629 │cxx_extern_tem‐ │ <PRE‐ │ extern │ │
7630 │plates │ FIX>_EXTERN_TEM‐ │ │ │
7631 │ │ PLATE │ │ │
7632 ├──────────────────┼────────────────────┼─────────────┼──────┤
7633 │cxx_final │ <PREFIX>_FINAL │ final │ yes │
7634 └──────────────────┴────────────────────┴─────────────┴──────┘
7635 │cxx_noexcept │ <PREFIX>_NOEXCEPT │ noexcept │ yes │
7638 ├──────────────────┼────────────────────┼─────────────┼──────┤
7639 │cxx_noexcept │ <PREFIX>_NOEX‐ │ noexcept(X) │ │
7640 │ │ CEPT_EXPR(X) │ │ │
7641 ├──────────────────┼────────────────────┼─────────────┼──────┤
7642 │cxx_override │ <PREFIX>_OVERRIDE │ override │ yes │
7643 └──────────────────┴────────────────────┴─────────────┴──────┘
7644 Compatibility Implementation Macros
7646 Some features are suitable for wrapping in a macro with a backward com‐
7647 patibility implementation if the compiler does not support the feature.
7648 When the cxx_static_assert feature is not provided by the compiler, a
7650 compatibility implementation is available via the <PRE‐
7651 FIX>_STATIC_ASSERT(COND) and <PREFIX>_STATIC_ASSERT_MSG(COND, MSG)
7652 function-like macros. The macros expand to static_assert where that
7653 compiler feature is available, and to a compatibility implementation
7654 otherwise. In the first form, the condition is stringified in the mes‐
7655 sage field of static_assert. In the second form, the message MSG is
7656 passed to the message field of static_assert, or ignored if using the
7657 backward compatibility implementation.
7658 The cxx_attribute_deprecated feature provides a macro definition <PRE‐
7660 FIX>_DEPRECATED, which expands to either the standard [[deprecated]]
7661 attribute or a compiler-specific decorator such as
7662 __attribute__((__deprecated__)) used by GNU compilers.
7663 The cxx_alignas feature provides a macro definition <PREFIX>_ALIGNAS
7665 which expands to either the standard alignas decorator or a com‐
7666 piler-specific decorator such as __attribute__ ((__aligned__)) used by
7667 GNU compilers.
7668 The cxx_alignof feature provides a macro definition <PREFIX>_ALIGNOF
7670 which expands to either the standard alignof decorator or a com‐
7671 piler-specific decorator such as __alignof__ used by GNU compilers.
7672 ┌───────────────────┬────────────────────────┬────────────────┬──────┐
7674 │Feature │ Define │ Symbol │ bare │
7675 ├───────────────────┼────────────────────────┼────────────────┼──────┤
7676 │cxx_alignas │ <PREFIX>_ALIGNAS │ alignas │ │
7677 ├───────────────────┼────────────────────────┼────────────────┼──────┤
7678 │cxx_alignof │ <PREFIX>_ALIGNOF │ alignof │ │
7679 ├───────────────────┼────────────────────────┼────────────────┼──────┤
7680 │cxx_nullptr │ <PREFIX>_NULLPTR │ nullptr │ yes │
7681 ├───────────────────┼────────────────────────┼────────────────┼──────┤
7682 │cxx_static_assert │ <PRE‐ │ static_assert │ │
7683 │ │ FIX>_STATIC_ASSERT │ │ │
7684 ├───────────────────┼────────────────────────┼────────────────┼──────┤
7685 │cxx_static_assert │ <PRE‐ │ static_assert │ │
7686 │ │ FIX>_STATIC_ASSERT_MSG │ │ │
7687 ├───────────────────┼────────────────────────┼────────────────┼──────┤
7688 │cxx_attribute_dep‐ │ <PREFIX>_DEPRECATED │ [[deprecated]] │ │
7689 │recated │ │ │ │
7690 ├───────────────────┼────────────────────────┼────────────────┼──────┤
7691 │cxx_attribute_dep‐ │ <PREFIX>_DEPRE‐ │ [[deprecated]] │ │
7692 │recated │ CATED_MSG │ │ │
7693 ├───────────────────┼────────────────────────┼────────────────┼──────┤
7694 │cxx_thread_local │ <PREFIX>_THREAD_LOCAL │ thread_local │ │
7695 └───────────────────┴────────────────────────┴────────────────┴──────┘
7696 A use-case which arises with such deprecation macros is the deprecation
7698 of an entire library. In that case, all public API in the library may
7699 be decorated with the <PREFIX>_DEPRECATED macro. This results in very
7700 noisy build output when building the library itself, so the macro may
7701 be may be defined to empty in that case when building the deprecated
7702 library:
7703 add_library(compat_support ${srcs})
7705 target_compile_definitions(compat_support
7706 PRIVATE
7707 CompatSupport_DEPRECATED=
7708 )
7709
7711 These modules search for third-party software. They are normally
7712 called through the find_package() command.
7713 FindALSA
7715 Find Advanced Linux Sound Architecture (ALSA)
7716 Find the alsa libraries (asound)
7718 IMPORTED Targets
7720 This module defines IMPORTED target ALSA::ALSA, if ALSA has been found.
7721 Result Variables
7723 This module defines the following variables:
7724 ALSA_FOUND
7726 True if ALSA_INCLUDE_DIR & ALSA_LIBRARY are found
7727 ALSA_LIBRARIES
7729 List of libraries when using ALSA.
7730 ALSA_INCLUDE_DIRS
7732 Where to find the ALSA headers.
7733 Cache variables
7735 The following cache variables may also be set:
7736 ALSA_INCLUDE_DIR
7738 the ALSA include directory
7739 ALSA_LIBRARY
7741 the absolute path of the asound library
7742 FindArmadillo
7744 Find the Armadillo C++ library. Armadillo is library for linear alge‐
7745 bra & scientific computing.
7746 Using Armadillo:
7748 find_package(Armadillo REQUIRED)
7750 include_directories(${ARMADILLO_INCLUDE_DIRS})
7751 add_executable(foo foo.cc)
7752 target_link_libraries(foo ${ARMADILLO_LIBRARIES})
7753 This module sets the following variables:
7755 ARMADILLO_FOUND - set to true if the library is found
7757 ARMADILLO_INCLUDE_DIRS - list of required include directories
7758 ARMADILLO_LIBRARIES - list of libraries to be linked
7759 ARMADILLO_VERSION_MAJOR - major version number
7760 ARMADILLO_VERSION_MINOR - minor version number
7761 ARMADILLO_VERSION_PATCH - patch version number
7762 ARMADILLO_VERSION_STRING - version number as a string (ex: "1.0.4")
7763 ARMADILLO_VERSION_NAME - name of the version (ex: "Antipodean Antileech")
7764 FindASPELL
7766 Try to find ASPELL
7767 Once done this will define
7769 ASPELL_FOUND - system has ASPELL
7771 ASPELL_EXECUTABLE - the ASPELL executable
7772 ASPELL_INCLUDE_DIR - the ASPELL include directory
7773 ASPELL_LIBRARIES - The libraries needed to use ASPELL
7774 ASPELL_DEFINITIONS - Compiler switches required for using ASPELL
7775 FindAVIFile
7777 Locate AVIFILE library and include paths
7778 AVIFILE (http://avifile.sourceforge.net/) is a set of libraries for
7780 i386 machines to use various AVI codecs. Support is limited beyond
7781 Linux. Windows provides native AVI support, and so doesn’t need this
7782 library. This module defines
7783 AVIFILE_INCLUDE_DIR, where to find avifile.h , etc.
7785 AVIFILE_LIBRARIES, the libraries to link against
7786 AVIFILE_DEFINITIONS, definitions to use when compiling
7787 AVIFILE_FOUND, If false, don't try to use AVIFILE
7788 FindBISON
7790 Find bison executable and provide a macro to generate custom build
7791 rules.
7792 The module defines the following variables:
7794 BISON_EXECUTABLE
7796 path to the bison program
7797 BISON_VERSION
7799 version of bison
7800 BISON_FOUND
7802 “True” if the program was found
7803 The minimum required version of bison can be specified using the stan‐
7805 dard CMake syntax, e.g. find_package(BISON 2.1.3).
7806 If bison is found, the module defines the macro:
7808 BISON_TARGET(<Name> <YaccInput> <CodeOutput>
7810 [COMPILE_FLAGS <flags>]
7811 [DEFINES_FILE <file>]
7812 [VERBOSE [<file>]]
7813 [REPORT_FILE <file>]
7814 )
7815 which will create a custom rule to generate a parser. <YaccInput> is
7817 the path to a yacc file. <CodeOutput> is the name of the source file
7818 generated by bison. A header file is also be generated, and contains
7819 the token list.
7820 The options are:
7822 COMPILE_FLAGS <flags>
7824 Specify flags to be added to the bison command line.
7825 DEFINES_FILE <file>
7827 Specify a non-default header <file> to be generated by bison.
7828 VERBOSE [<file>]
7830 Tell bison to write a report file of the grammar and parser. If
7831 <file> is given, it specifies path the report file is copied to.
7832 [<file>] is left for backward compatibility of this module. Use
7833 VERBOSE REPORT_FILE <file>.
7834 REPORT_FILE <file>
7836 Specify a non-default report <file>, if generated.
7837 The macro defines the following variables:
7839 BISON_<Name>_DEFINED
7841 True is the macro ran successfully
7842 BISON_<Name>_INPUT
7844 The input source file, an alias for <YaccInput>
7845 BISON_<Name>_OUTPUT_SOURCE
7847 The source file generated by bison
7848 BISON_<Name>_OUTPUT_HEADER
7850 The header file generated by bison
7851 BISON_<Name>_OUTPUTS
7853 All files generated by bison including the source, the header
7854 and the report
7855 BISON_<Name>_COMPILE_FLAGS
7857 Options used in the bison command line
7858 Example usage:
7860 find_package(BISON)
7862 BISON_TARGET(MyParser parser.y ${CMAKE_CURRENT_BINARY_DIR}/parser.cpp
7863 DEFINES_FILE ${CMAKE_CURRENT_BINARY_DIR}/parser.h)
7864 add_executable(Foo main.cpp ${BISON_MyParser_OUTPUTS})
7865 FindBLAS
7867 Find Basic Linear Algebra Subprograms (BLAS) library
7868 This module finds an installed Fortran library that implements the BLAS
7870 linear-algebra interface (see http://www.netlib.org/blas/).
7871 The approach follows that taken for the autoconf macro file,
7873 acx_blas.m4 (distributed at
7874 http://ac-archive.sourceforge.net/ac-archive/acx_blas.html).
7875 Input Variables
7877 The following variables may be set to influence this module’s behavior:
7878 BLA_STATIC
7880 if ON use static linkage
7881 BLA_VENDOR
7883 If set, checks only the specified vendor, if not set checks all
7884 the possibilities. List of vendors valid in this module:
7885 · Goto
7887 · OpenBLAS
7889 · FLAME
7891 · ATLAS PhiPACK
7893 · CXML
7895 · DXML
7897 · SunPerf
7899 · SCSL
7901 · SGIMATH
7903 · IBMESSL
7905 · Intel10_32 (intel mkl v10 32 bit)
7907 · Intel10_64lp (intel mkl v10+ 64 bit, threaded code, lp64
7909 model)
7910 · Intel10_64lp_seq (intel mkl v10+ 64 bit, sequential code, lp64
7912 model)
7913 · Intel10_64ilp (intel mkl v10+ 64 bit, threaded code, ilp64
7915 model)
7916 · Intel10_64ilp_seq (intel mkl v10+ 64 bit, sequential code,
7918 ilp64 model)
7919 · Intel10_64_dyn (intel mkl v10+ 64 bit, single dynamic library)
7921 · Intel (obsolete versions of mkl 32 and 64 bit)
7923 · ACML
7925 · ACML_MP
7927 · ACML_GPU
7929 · Apple
7931 · NAS
7933 · Generic
7935 BLA_F95
7937 if ON tries to find the BLAS95 interfaces
7938 BLA_PREFER_PKGCONFIG
7940 if set pkg-config will be used to search for a BLAS library
7941 first and if one is found that is preferred
7942 Result Variables
7944 This module defines the following variables:
7945 BLAS_FOUND
7947 library implementing the BLAS interface is found
7948 BLAS_LINKER_FLAGS
7950 uncached list of required linker flags (excluding -l and -L).
7951 BLAS_LIBRARIES
7953 uncached list of libraries (using full path name) to link
7954 against to use BLAS (may be empty if compiler implicitly links
7955 BLAS)
7956 BLAS95_LIBRARIES
7958 uncached list of libraries (using full path name) to link
7959 against to use BLAS95 interface
7960 BLAS95_FOUND
7962 library implementing the BLAS95 interface is found
7963 NOTE:
7965 C, CXX or Fortran must be enabled to detect a BLAS library. C or
7966 CXX must be enabled to use Intel Math Kernel Library (MKL).
7967 For example, to use Intel MKL libraries and/or Intel compiler:
7969 set(BLA_VENDOR Intel10_64lp)
7971 find_package(BLAS)
7972 Hints
7974 Set the MKLROOT environment variable to a directory that contains an
7975 MKL installation, or add the directory to the dynamic library loader
7976 environment variable for your platform (LIB, DYLD_LIBRARY_PATH or
7977 LD_LIBRARY_PATH).
7978 FindBacktrace
7980 Find provider for backtrace(3).
7981 Checks if OS supports backtrace(3) via either libc or custom library.
7983 This module defines the following variables:
7984 Backtrace_HEADER
7986 The header file needed for backtrace(3). Cached. Could be
7987 forcibly set by user.
7988 Backtrace_INCLUDE_DIRS
7990 The include directories needed to use backtrace(3) header.
7991 Backtrace_LIBRARIES
7993 The libraries (linker flags) needed to use backtrace(3), if any.
7994 Backtrace_FOUND
7996 Is set if and only if backtrace(3) support detected.
7997 The following cache variables are also available to set or use:
7999 Backtrace_LIBRARY
8001 The external library providing backtrace, if any.
8002 Backtrace_INCLUDE_DIR
8004 The directory holding the backtrace(3) header.
8005 Typical usage is to generate of header file using configure_file() with
8007 the contents like the following:
8008 #cmakedefine01 Backtrace_FOUND
8010 #if Backtrace_FOUND
8011 # include <${Backtrace_HEADER}>
8012 #endif
8013 And then reference that generated header file in actual source.
8015 FindBoost
8017 Find Boost include dirs and libraries
8018 Use this module by invoking find_package with the form:
8020 find_package(Boost
8022 [version] [EXACT] # Minimum or EXACT version e.g. 1.67.0
8023 [REQUIRED] # Fail with error if Boost is not found
8024 [COMPONENTS <libs>...] # Boost libraries by their canonical name
8025 # e.g. "date_time" for "libboost_date_time"
8026 [OPTIONAL_COMPONENTS <libs>...]
8027 # Optional Boost libraries by their canonical name)
8028 ) # e.g. "date_time" for "libboost_date_time"
8029 This module finds headers and requested component libraries OR a CMake
8031 package configuration file provided by a “Boost CMake” build. For the
8032 latter case skip to the “Boost CMake” section below. For the former
8033 case results are reported in variables:
8034 Boost_FOUND - True if headers and requested libraries were found
8036 Boost_INCLUDE_DIRS - Boost include directories
8037 Boost_LIBRARY_DIRS - Link directories for Boost libraries
8038 Boost_LIBRARIES - Boost component libraries to be linked
8039 Boost_<C>_FOUND - True if component <C> was found (<C> is upper-case)
8040 Boost_<C>_LIBRARY - Libraries to link for component <C> (may include
8041 target_link_libraries debug/optimized keywords)
8042 Boost_VERSION_MACRO - BOOST_VERSION value from boost/version.hpp
8043 Boost_VERSION_STRING - Boost version number in x.y.z format
8044 Boost_VERSION - if CMP0093 NEW => same as Boost_VERSION_STRING
8045 if CMP0093 OLD or unset => same as Boost_VERSION_MACRO
8046 Boost_LIB_VERSION - Version string appended to library filenames
8047 Boost_VERSION_MAJOR - Boost major version number (X in X.y.z)
8048 alias: Boost_MAJOR_VERSION
8049 Boost_VERSION_MINOR - Boost minor version number (Y in x.Y.z)
8050 alias: Boost_MINOR_VERSION
8051 Boost_VERSION_PATCH - Boost subminor version number (Z in x.y.Z)
8052 alias: Boost_SUBMINOR_VERSION
8053 Boost_VERSION_COUNT - Amount of version components (3)
8054 Boost_LIB_DIAGNOSTIC_DEFINITIONS (Windows)
8055 - Pass to add_definitions() to have diagnostic
8056 information about Boost's automatic linking
8057 displayed during compilation
8058 Note that Boost Python components require a Python version suffix
8060 (Boost 1.67 and later), e.g. python36 or python27 for the versions
8061 built against Python 3.6 and 2.7, respectively. This also applies to
8062 additional components using Python including mpi_python and numpy.
8063 Earlier Boost releases may use distribution-specific suffixes such as
8064 2, 3 or 2.7. These may also be used as suffixes, but note that they
8065 are not portable.
8066 This module reads hints about search locations from variables:
8068 BOOST_ROOT - Preferred installation prefix
8070 (or BOOSTROOT)
8071 BOOST_INCLUDEDIR - Preferred include directory e.g. <prefix>/include
8072 BOOST_LIBRARYDIR - Preferred library directory e.g. <prefix>/lib
8073 Boost_NO_SYSTEM_PATHS - Set to ON to disable searching in locations not
8074 specified by these hint variables. Default is OFF.
8075 Boost_ADDITIONAL_VERSIONS
8076 - List of Boost versions not known to this module
8077 (Boost install locations may contain the version)
8078 and saves search results persistently in CMake cache entries:
8080 Boost_INCLUDE_DIR - Directory containing Boost headers
8082 Boost_LIBRARY_DIR_RELEASE - Directory containing release Boost libraries
8083 Boost_LIBRARY_DIR_DEBUG - Directory containing debug Boost libraries
8084 Boost_<C>_LIBRARY_DEBUG - Component <C> library debug variant
8085 Boost_<C>_LIBRARY_RELEASE - Component <C> library release variant
8086 The following IMPORTED targets are also defined:
8088 Boost::headers - Target for header-only dependencies
8090 (Boost include directory)
8091 alias: Boost::boost
8092 Boost::<C> - Target for specific component dependency
8093 (shared or static library); <C> is lower-
8094 case
8095 Boost::diagnostic_definitions - interface target to enable diagnostic
8096 information about Boost's automatic linking
8097 during compilation (adds BOOST_LIB_DIAGNOSTIC)
8098 Boost::disable_autolinking - interface target to disable automatic
8099 linking with MSVC (adds BOOST_ALL_NO_LIB)
8100 Boost::dynamic_linking - interface target to enable dynamic linking
8101 linking with MSVC (adds BOOST_ALL_DYN_LINK)
8102 Implicit dependencies such as Boost::filesystem requiring Boost::system
8104 will be automatically detected and satisfied, even if system is not
8105 specified when using find_package() and if Boost::system is not added
8106 to target_link_libraries(). If using Boost::thread, then
8107 Threads::Threads will also be added automatically.
8108 It is important to note that the imported targets behave differently
8110 than variables created by this module: multiple calls to find_pack‐
8111 age(Boost) in the same directory or sub-directories with different
8112 options (e.g. static or shared) will not override the values of the
8113 targets created by the first call.
8114 Users may set these hints or results as CACHE entries. Projects should
8116 not read these entries directly but instead use the above result vari‐
8117 ables. Note that some hint names start in upper-case “BOOST”. One may
8118 specify these as environment variables if they are not specified as
8119 CMake variables or cache entries.
8120 This module first searches for the Boost header files using the above
8122 hint variables (excluding BOOST_LIBRARYDIR) and saves the result in
8123 Boost_INCLUDE_DIR. Then it searches for requested component libraries
8124 using the above hints (excluding BOOST_INCLUDEDIR and Boost_ADDI‐
8125 TIONAL_VERSIONS), “lib” directories near Boost_INCLUDE_DIR, and the
8126 library name configuration settings below. It saves the library direc‐
8127 tories in Boost_LIBRARY_DIR_DEBUG and Boost_LIBRARY_DIR_RELEASE and
8128 individual library locations in Boost_<C>_LIBRARY_DEBUG and
8129 Boost_<C>_LIBRARY_RELEASE. When one changes settings used by previous
8130 searches in the same build tree (excluding environment variables) this
8131 module discards previous search results affected by the changes and
8132 searches again.
8133 Boost libraries come in many variants encoded in their file name.
8135 Users or projects may tell this module which variant to find by setting
8136 variables:
8137 Boost_USE_DEBUG_LIBS - Set to ON or OFF to specify whether to search
8139 and use the debug libraries. Default is ON.
8140 Boost_USE_RELEASE_LIBS - Set to ON or OFF to specify whether to search
8141 and use the release libraries. Default is ON.
8142 Boost_USE_MULTITHREADED - Set to OFF to use the non-multithreaded
8143 libraries ('mt' tag). Default is ON.
8144 Boost_USE_STATIC_LIBS - Set to ON to force the use of the static
8145 libraries. Default is OFF.
8146 Boost_USE_STATIC_RUNTIME - Set to ON or OFF to specify whether to use
8147 libraries linked statically to the C++ runtime
8148 ('s' tag). Default is platform dependent.
8149 Boost_USE_DEBUG_RUNTIME - Set to ON or OFF to specify whether to use
8150 libraries linked to the MS debug C++ runtime
8151 ('g' tag). Default is ON.
8152 Boost_USE_DEBUG_PYTHON - Set to ON to use libraries compiled with a
8153 debug Python build ('y' tag). Default is OFF.
8154 Boost_USE_STLPORT - Set to ON to use libraries compiled with
8155 STLPort ('p' tag). Default is OFF.
8156 Boost_USE_STLPORT_DEPRECATED_NATIVE_IOSTREAMS
8157 - Set to ON to use libraries compiled with
8158 STLPort deprecated "native iostreams"
8159 ('n' tag). Default is OFF.
8160 Boost_COMPILER - Set to the compiler-specific library suffix
8161 (e.g. "-gcc43"). Default is auto-computed
8162 for the C++ compiler in use. A list may be
8163 used if multiple compatible suffixes should
8164 be tested for, in decreasing order of
8165 preference.
8166 Boost_ARCHITECTURE - Set to the architecture-specific library suffix
8167 (e.g. "-x64"). Default is auto-computed for the
8168 C++ compiler in use.
8169 Boost_THREADAPI - Suffix for "thread" component library name,
8170 such as "pthread" or "win32". Names with
8171 and without this suffix will both be tried.
8172 Boost_NAMESPACE - Alternate namespace used to build boost with
8173 e.g. if set to "myboost", will search for
8174 myboost_thread instead of boost_thread.
8175 Other variables one may set to control this module are:
8177 Boost_DEBUG - Set to ON to enable debug output from FindBoost.
8179 Please enable this before filing any bug report.
8180 Boost_REALPATH - Set to ON to resolve symlinks for discovered
8181 libraries to assist with packaging. For example,
8182 the "system" component library may be resolved to
8183 "/usr/lib/libboost_system.so.1.67.0" instead of
8184 "/usr/lib/libboost_system.so". This does not
8185 affect linking and should not be enabled unless
8186 the user needs this information.
8187 Boost_LIBRARY_DIR - Default value for Boost_LIBRARY_DIR_RELEASE and
8188 Boost_LIBRARY_DIR_DEBUG.
8189 On Visual Studio and Borland compilers Boost headers request automatic
8191 linking to corresponding libraries. This requires matching libraries
8192 to be linked explicitly or available in the link library search path.
8193 In this case setting Boost_USE_STATIC_LIBS to OFF may not achieve
8194 dynamic linking. Boost automatic linking typically requests static
8195 libraries with a few exceptions (such as Boost.Python). Use:
8196 add_definitions(${Boost_LIB_DIAGNOSTIC_DEFINITIONS})
8198 to ask Boost to report information about automatic linking requests.
8200 Example to find Boost headers only:
8202 find_package(Boost 1.36.0)
8204 if(Boost_FOUND)
8205 include_directories(${Boost_INCLUDE_DIRS})
8206 add_executable(foo foo.cc)
8207 endif()
8208 Example to find Boost libraries and use imported targets:
8210 find_package(Boost 1.56 REQUIRED COMPONENTS
8212 date_time filesystem iostreams)
8213 add_executable(foo foo.cc)
8214 target_link_libraries(foo Boost::date_time Boost::filesystem
8215 Boost::iostreams)
8216 Example to find Boost Python 3.6 libraries and use imported targets:
8218 find_package(Boost 1.67 REQUIRED COMPONENTS
8220 python36 numpy36)
8221 add_executable(foo foo.cc)
8222 target_link_libraries(foo Boost::python36 Boost::numpy36)
8223 Example to find Boost headers and some static (release only) libraries:
8225 set(Boost_USE_STATIC_LIBS ON) # only find static libs
8227 set(Boost_USE_DEBUG_LIBS OFF) # ignore debug libs and
8228 set(Boost_USE_RELEASE_LIBS ON) # only find release libs
8229 set(Boost_USE_MULTITHREADED ON)
8230 set(Boost_USE_STATIC_RUNTIME OFF)
8231 find_package(Boost 1.66.0 COMPONENTS date_time filesystem system ...)
8232 if(Boost_FOUND)
8233 include_directories(${Boost_INCLUDE_DIRS})
8234 add_executable(foo foo.cc)
8235 target_link_libraries(foo ${Boost_LIBRARIES})
8236 endif()
8237 Boost CMake
8239 If Boost was built using the boost-cmake project or from Boost 1.70.0
8240 on it provides a package configuration file for use with find_package’s
8241 config mode. This module looks for the package configuration file
8242 called BoostConfig.cmake or boost-config.cmake and stores the result in
8243 CACHE entry “Boost_DIR”. If found, the package configuration file is
8244 loaded and this module returns with no further action. See documenta‐
8245 tion of the Boost CMake package configuration for details on what it
8246 provides.
8247 Set Boost_NO_BOOST_CMAKE to ON, to disable the search for boost-cmake.
8249 FindBullet
8251 Try to find the Bullet physics engine
8252 This module defines the following variables
8254 BULLET_FOUND - Was bullet found
8256 BULLET_INCLUDE_DIRS - the Bullet include directories
8257 BULLET_LIBRARIES - Link to this, by default it includes
8258 all bullet components (Dynamics,
8259 Collision, LinearMath, & SoftBody)
8260 This module accepts the following variables
8262 BULLET_ROOT - Can be set to bullet install path or Windows build path
8264 FindBZip2
8266 Try to find BZip2
8267 IMPORTED Targets
8269 This module defines IMPORTED target BZip2::BZip2, if BZip2 has been
8270 found.
8271 Result Variables
8273 This module defines the following variables:
8274 BZIP2_FOUND
8276 system has BZip2
8277 BZIP2_INCLUDE_DIRS
8279 the BZip2 include directories
8280 BZIP2_LIBRARIES
8282 Link these to use BZip2
8283 BZIP2_NEED_PREFIX
8285 this is set if the functions are prefixed with BZ2_
8286 BZIP2_VERSION_STRING
8288 the version of BZip2 found
8289 Cache variables
8291 The following cache variables may also be set:
8292 BZIP2_INCLUDE_DIR
8294 the BZip2 include directory
8295 FindCABLE
8297 Find CABLE
8298 This module finds if CABLE is installed and determines where the
8300 include files and libraries are. This code sets the following vari‐
8301 ables:
8302 CABLE the path to the cable executable
8304 CABLE_TCL_LIBRARY the path to the Tcl wrapper library
8305 CABLE_INCLUDE_DIR the path to the include directory
8306 To build Tcl wrappers, you should add shared library and link it to
8308 ${CABLE_TCL_LIBRARY}. You should also add ${CABLE_INCLUDE_DIR} as an
8309 include directory.
8310 FindCoin3D
8312 Find Coin3D (Open Inventor)
8313 Coin3D is an implementation of the Open Inventor API. It provides data
8315 structures and algorithms for 3D visualization.
8316 This module defines the following variables
8318 COIN3D_FOUND - system has Coin3D - Open Inventor
8320 COIN3D_INCLUDE_DIRS - where the Inventor include directory can be found
8321 COIN3D_LIBRARIES - Link to this to use Coin3D
8322 FindCups
8324 Find the Common UNIX Printing System (CUPS).
8325 Set CUPS_REQUIRE_IPP_DELETE_ATTRIBUTE to TRUE if you need a version
8327 which features this function (i.e. at least 1.1.19)
8328 Imported targets
8330 This module defines IMPORTED target Cups::Cups, if Cups has been found.
8331 Result variables
8333 This module will set the following variables in your project:
8334 CUPS_FOUND
8336 true if CUPS headers and libraries were found
8337 CUPS_INCLUDE_DIRS
8339 the directory containing the Cups headers
8340 CUPS_LIBRARIES
8342 the libraries to link against to use CUPS.
8343 CUPS_VERSION_STRING
8345 the version of CUPS found (since CMake 2.8.8)
8346 Cache variables
8348 The following cache variables may also be set:
8349 CUPS_INCLUDE_DIR
8351 the directory containing the Cups headers
8352 FindCUDAToolkit
8354 This script locates the NVIDIA CUDA toolkit and the associated
8355 libraries, but does not require the CUDA language be enabled for a
8356 given project. This module does not search for the NVIDIA CUDA Samples.
8357 Search Behavior
8359 Finding the CUDA Toolkit requires finding the nvcc executable, which is
8360 searched for in the following order:
8361 1. If the CUDA language has been enabled we will use the directory con‐
8363 taining the compiler as the first search location for nvcc.
8364 2. If the CUDAToolkit_ROOT cmake configuration variable (e.g., -DCUDA‐
8366 Toolkit_ROOT=/some/path) or environment variable is defined, it will
8367 be searched. If both an environment variable and a configuration
8368 variable are specified, the configuration variable takes precedence.
8369 The directory specified here must be such that the executable nvcc
8371 can be found underneath the directory specified by CUDAToolkit_ROOT.
8372 If CUDAToolkit_ROOT is specified, but no nvcc is found underneath,
8373 this package is marked as not found. No subsequent search attempts
8374 are performed.
8375 3. If the CUDA_PATH environment variable is defined, it will be
8377 searched.
8378 4. The user’s path is searched for nvcc using find_program(). If this
8380 is found, no subsequent search attempts are performed. Users are
8381 responsible for ensuring that the first nvcc to show up in the path
8382 is the desired path in the event that multiple CUDA Toolkits are
8383 installed.
8384 5. On Unix systems, if the symbolic link /usr/local/cuda exists, this
8386 is used. No subsequent search attempts are performed. No default
8387 symbolic link location exists for the Windows platform.
8388 6. The platform specific default install locations are searched. If
8390 exactly one candidate is found, this is used. The default CUDA
8391 Toolkit install locations searched are:
8392 ┌───────────┬────────────────────────────┐
8394 │Platform │ Search Pattern │
8395 ├───────────┼────────────────────────────┤
8396 │macOS │ /Developer/NVIDIA/CUDA-X.Y │
8397 ├───────────┼────────────────────────────┤
8398 │Other Unix │ /usr/local/cuda-X.Y │
8399 ├───────────┼────────────────────────────┤
8400 │Windows │ C:\Program Files\NVIDIA │
8401 │ │ GPU Computing Tool‐ │
8402 │ │ kit\CUDA\vX.Y │
8403 └───────────┴────────────────────────────┘
8404 Where X.Y would be a specific version of the CUDA Toolkit, such as
8406 /usr/local/cuda-9.0 or C:\Program Files\NVIDIA GPU Computing Tool‐
8407 kit\CUDA\v9.0
8408 NOTE:
8410 When multiple CUDA Toolkits are installed in the default location
8411 of a system (e.g., both /usr/local/cuda-9.0 and
8412 /usr/local/cuda-10.0 exist but the /usr/local/cuda symbolic link
8413 does not exist), this package is marked as not found.
8414 There are too many factors involved in making an automatic deci‐
8416 sion in the presence of multiple CUDA Toolkits being installed.
8417 In this situation, users are encouraged to either (1) set CUDA‐
8418 Toolkit_ROOT [22mor (2) ensure that the correct nvcc executable shows
8419 up in $PATH for find_program() to find.
8420 Options
8422 VERSION
8423 If specified, describes the version of the CUDA Toolkit to
8424 search for.
8425 REQUIRED
8427 If specified, configuration will error if a suitable CUDA Tool‐
8428 kit is not found.
8429 QUIET If specified, the search for a suitable CUDA Toolkit will not
8431 produce any messages.
8432 EXACT If specified, the CUDA Toolkit is considered found only if the
8434 exact VERSION specified is recovered.
8435 Imported targets
8437 An imported target named CUDA::toolkit is provided.
8438 This module defines IMPORTED targets for each of the following
8440 libraries that are part of the CUDAToolkit:
8441 · CUDA Runtime Library
8443 · CUDA Driver Library
8445 · cuBLAS
8447 · cuFFT
8449 · cuRAND
8451 · cuSOLVER
8453 · cuSPARSE
8455 · cuPTI
8457 · NPP
8459 · nvBLAS
8461 · nvGRAPH
8463 · nvJPEG
8465 · nvidia-ML
8467 · nvRTC
8469 · nvToolsExt
8471 · OpenCL
8473 · cuLIBOS
8475 CUDA Runtime Library
8477 The CUDA Runtime library (cudart) are what most applications will typi‐
8478 cally need to link against to make any calls such as cudaMalloc, and
8479 cudaFree.
8480 Targets Created:
8482 · CUDA::cudart
8484 · CUDA::cudart_static
8486 CUDA Driver Library
8488 The CUDA Driver library (cuda) are used by applications that use calls
8489 such as cuMemAlloc, and cuMemFree. This is generally used by advanced
8490 Targets Created:
8492 · CUDA::cuda_driver
8494 · CUDA::cuda_driver
8496 cuBLAS
8498 The cuBLAS library.
8499 Targets Created:
8501 · CUDA::cublas
8503 · CUDA::cublas_static
8505 cuFFT
8507 The cuFFT library.
8508 Targets Created:
8510 · CUDA::cufft
8512 · CUDA::cufftw
8514 · CUDA::cufft_static
8516 · CUDA::cufftw_static
8518 cuRAND
8520 The cuRAND library.
8521 Targets Created:
8523 · CUDA::curand
8525 · CUDA::curand_static
8527 cuSOLVER
8529 The cuSOLVER library.
8530 Targets Created:
8532 · CUDA::cusolver
8534 · CUDA::cusolver_static
8536 cuSPARSE
8538 The cuSPARSE library.
8539 Targets Created:
8541 · CUDA::cusparse
8543 · CUDA::cusparse_static
8545 cupti
8547 The NVIDIA CUDA Profiling Tools Interface.
8548 Targets Created:
8550 · CUDA::cupti
8552 · CUDA::cupti_static
8554 NPP
8556 The NPP libraries.
8557 Targets Created:
8559 · nppc:
8561 · CUDA::nppc
8563 · CUDA::nppc_static
8565 · nppial: Arithmetic and logical operation functions in nppi_arith‐
8567 metic_and_logical_operations.h
8568 · CUDA::nppial
8570 · CUDA::nppial_static
8572 · nppicc: Color conversion and sampling functions in nppi_color_conver‐
8574 sion.h
8575 · CUDA::nppicc
8577 · CUDA::nppicc_static
8579 · nppicom: JPEG compression and decompression functions in nppi_com‐
8581 pression_functions.h
8582 · CUDA::nppicom
8584 · CUDA::nppicom_static
8586 · nppidei: Data exchange and initialization functions in
8588 nppi_data_exchange_and_initialization.h
8589 · CUDA::nppidei
8591 · CUDA::nppidei_static
8593 · nppif: Filtering and computer vision functions in nppi_filter_func‐
8595 tions.h
8596 · CUDA::nppif
8598 · CUDA::nppif_static
8600 · nppig: Geometry transformation functions found in nppi_geome‐
8602 try_transforms.h
8603 · CUDA::nppig
8605 · CUDA::nppig_static
8607 · nppim: Morphological operation functions found in nppi_morphologi‐
8609 cal_operations.h
8610 · CUDA::nppim
8612 · CUDA::nppim_static
8614 · nppist: Statistics and linear transform in nppi_statistics_func‐
8616 tions.h and nppi_linear_transforms.h
8617 · CUDA::nppist
8619 · CUDA::nppist_static
8621 · nppisu: Memory support functions in nppi_support_functions.h
8623 · CUDA::nppisu
8625 · CUDA::nppisu_static
8627 · nppitc: Threshold and compare operation functions in nppi_thresh‐
8629 old_and_compare_operations.h
8630 · CUDA::nppitc
8632 · CUDA::nppitc_static
8634 · npps:
8636 · CUDA::npps
8638 · CUDA::npps_static
8640 nvBLAS
8642 The nvBLAS libraries. This is a shared library only.
8643 Targets Created:
8645 · CUDA::nvblas
8647 nvGRAPH
8649 The nvGRAPH library.
8650 Targets Created:
8652 · CUDA::nvgraph
8654 · CUDA::nvgraph_static
8656 nvJPEG
8658 The nvJPEG library. Introduced in CUDA 10.
8659 Targets Created:
8661 · CUDA::nvjpeg
8663 · CUDA::nvjpeg_static
8665 nvRTC
8667 The nvRTC (Runtime Compilation) library. This is a shared library
8668 only.
8669 Targets Created:
8671 · CUDA::nvrtc
8673 nvidia-ML
8675 The NVIDIA Management Library. This is a shared library only.
8676 Targets Created:
8678 · CUDA::nvml
8680 nvToolsExt
8682 The NVIDIA Tools Extension. This is a shared library only.
8683 Targets Created:
8685 · CUDA::nvToolsExt
8687 OpenCL
8689 The NVIDIA OpenCL Library. This is a shared library only.
8690 Targets Created:
8692 · CUDA::OpenCL
8694 cuLIBOS
8696 The cuLIBOS library is a backend thread abstraction layer library which
8697 is static only. The CUDA::cublas_static, CUDA::cusparse_static,
8698 CUDA::cufft_static, CUDA::curand_static, and (when implemented) NPP
8699 libraries all automatically have this dependency linked.
8700 Target Created:
8702 · CUDA::culibos
8704 Note: direct usage of this target by consumers should not be necessary.
8706 Result variables
8708 CUDAToolkit_FOUND
8709 A boolean specifying whether or not the CUDA Toolkit was found.
8710 CUDAToolkit_VERSION
8712 The exact version of the CUDA Toolkit found (as reported by nvcc
8713 --version).
8714 CUDAToolkit_VERSION_MAJOR
8716 The major version of the CUDA Toolkit.
8717 CUDAToolkit_VERSION_MAJOR
8719 The minor version of the CUDA Toolkit.
8720 CUDAToolkit_VERSION_PATCH
8722 The patch version of the CUDA Toolkit.
8723 CUDAToolkit_BIN_DIR
8725 The path to the CUDA Toolkit library directory that contains the
8726 CUDA executable nvcc.
8727 CUDAToolkit_INCLUDE_DIRS
8729 The path to the CUDA Toolkit include folder containing the
8730 header files required to compile a project linking against CUDA.
8731 CUDAToolkit_LIBRARY_DIR
8733 The path to the CUDA Toolkit library directory that contains the
8734 CUDA Runtime library cudart.
8735 CUDAToolkit_TARGET_DIR
8737 The path to the CUDA Toolkit directory including the target
8738 architecture when cross-compiling. When not cross-compiling this
8739 will be equivalant to CUDAToolkit_ROOT_DIR.
8740 CUDAToolkit_NVCC_EXECUTABLE
8742 The path to the NVIDIA CUDA compiler nvcc. Note that this path
8743 may not be the same as CMAKE_CUDA_COMPILER. nvcc must be found
8744 to determine the CUDA Toolkit version as well as determining
8745 other features of the Toolkit. This variable is set for the
8746 convenience of modules that depend on this one.
8747 FindCURL
8749 Find the native CURL headers and libraries.
8750 This module accept optional COMPONENTS to check supported features and
8752 protocols:
8753 PROTOCOLS: ICT FILE FTP FTPS GOPHER HTTP HTTPS IMAP IMAPS LDAP LDAPS POP3
8755 POP3S RTMP RTSP SCP SFTP SMB SMBS SMTP SMTPS TELNET TFTP
8756 FEATURES: SSL IPv6 UnixSockets libz AsynchDNS IDN GSS-API PSL SPNEGO
8757 Kerberos NTLM NTLM_WB TLS-SRP HTTP2 HTTPS-proxy
8758 IMPORTED Targets
8760 This module defines IMPORTED target CURL::libcurl, if curl has been
8761 found.
8762 Result Variables
8764 This module defines the following variables:
8765 CURL_FOUND
8767 “True” if curl found.
8768 CURL_INCLUDE_DIRS
8770 where to find curl/curl.h, etc.
8771 CURL_LIBRARIES
8773 List of libraries when using curl.
8774 CURL_VERSION_STRING
8776 The version of curl found.
8777 CURL CMake
8779 If CURL was built using the CMake buildsystem then it provides its own
8780 CURLConfig.cmake file for use with the find_package() command’s config
8781 mode. This module looks for this file and, if found, returns its
8782 results with no further action.
8783 Set CURL_NO_CURL_CMAKE to ON to disable this search.
8785 FindCurses
8787 Find the curses or ncurses include file and library.
8788 Result Variables
8790 This module defines the following variables:
8791 CURSES_FOUND
8793 True if Curses is found.
8794 CURSES_INCLUDE_DIRS
8796 The include directories needed to use Curses.
8797 CURSES_LIBRARIES
8799 The libraries needed to use Curses.
8800 CURSES_CFLAGS
8802 Parameters which ought be given to C/C++ compilers when using
8803 Curses.
8804 CURSES_HAVE_CURSES_H
8806 True if curses.h is available.
8807 CURSES_HAVE_NCURSES_H
8809 True if ncurses.h is available.
8810 CURSES_HAVE_NCURSES_NCURSES_H
8812 True if ncurses/ncurses.h is available.
8813 CURSES_HAVE_NCURSES_CURSES_H
8815 True if ncurses/curses.h is available.
8816 Set CURSES_NEED_NCURSES to TRUE before the find_package(Curses) call if
8818 NCurses functionality is required. Set CURSES_NEED_WIDE to TRUE before
8819 the find_package(Curses) call if unicode functionality is required.
8820 Backward Compatibility
8822 The following variable are provided for backward compatibility:
8823 CURSES_INCLUDE_DIR
8825 Path to Curses include. Use CURSES_INCLUDE_DIRS instead.
8826 CURSES_LIBRARY
8828 Path to Curses library. Use CURSES_LIBRARIES instead.
8829 FindCVS
8831 Find the Concurrent Versions System (CVS).
8832 The module defines the following variables:
8834 CVS_EXECUTABLE - path to cvs command line client
8836 CVS_FOUND - true if the command line client was found
8837 Example usage:
8839 find_package(CVS)
8841 if(CVS_FOUND)
8842 message("CVS found: ${CVS_EXECUTABLE}")
8843 endif()
8844 FindCxxTest
8846 Find CxxTest unit testing framework.
8847 Find the CxxTest suite and declare a helper macro for creating unit
8849 tests and integrating them with CTest. For more details on CxxTest see
8850 http://cxxtest.tigris.org
8851 INPUT Variables
8853 CXXTEST_USE_PYTHON [deprecated since 1.3]
8855 Only used in the case both Python & Perl
8856 are detected on the system to control
8857 which CxxTest code generator is used.
8858 Valid only for CxxTest version 3.
8859 NOTE: In older versions of this Find Module,
8861 this variable controlled if the Python test
8862 generator was used instead of the Perl one,
8863 regardless of which scripting language the
8864 user had installed.
8865 CXXTEST_TESTGEN_ARGS (since CMake 2.8.3)
8867 Specify a list of options to pass to the CxxTest code
8868 generator. If not defined, --error-printer is
8869 passed.
8870 OUTPUT Variables
8872 CXXTEST_FOUND
8874 True if the CxxTest framework was found
8875 CXXTEST_INCLUDE_DIRS
8876 Where to find the CxxTest include directory
8877 CXXTEST_PERL_TESTGEN_EXECUTABLE
8878 The perl-based test generator
8879 CXXTEST_PYTHON_TESTGEN_EXECUTABLE
8880 The python-based test generator
8881 CXXTEST_TESTGEN_EXECUTABLE (since CMake 2.8.3)
8882 The test generator that is actually used (chosen using user preferences
8883 and interpreters found in the system)
8884 CXXTEST_TESTGEN_INTERPRETER (since CMake 2.8.3)
8885 The full path to the Perl or Python executable on the system, on
8886 platforms where the script cannot be executed using its shebang line.
8887 MACROS for optional use by CMake users:
8889 CXXTEST_ADD_TEST(<test_name> <gen_source_file> <input_files_to_testgen...>)
8891 Creates a CxxTest runner and adds it to the CTest testing suite
8892 Parameters:
8893 test_name The name of the test
8894 gen_source_file The generated source filename to be
8895 generated by CxxTest
8896 input_files_to_testgen The list of header files containing the
8897 CxxTest::TestSuite's to be included in
8898 this runner
8899 #==============
8901 Example Usage:
8902 find_package(CxxTest)
8904 if(CXXTEST_FOUND)
8905 include_directories(${CXXTEST_INCLUDE_DIR})
8906 enable_testing()
8907 CXXTEST_ADD_TEST(unittest_foo foo_test.cc
8909 ${CMAKE_CURRENT_SOURCE_DIR}/foo_test.h)
8910 target_link_libraries(unittest_foo foo) # as needed
8911 endif()
8912 This will (if CxxTest is found):
8914 1. Invoke the testgen executable to autogenerate foo_test.cc in the
8915 binary tree from "foo_test.h" in the current source directory.
8916 2. Create an executable and test called unittest_foo.
8917 #=============
8919 Example foo_test.h:
8920 #include <cxxtest/TestSuite.h>
8922 class MyTestSuite : public CxxTest::TestSuite
8924 {
8925 public:
8926 void testAddition( void )
8927 {
8928 TS_ASSERT( 1 + 1 > 1 );
8929 TS_ASSERT_EQUALS( 1 + 1, 2 );
8930 }
8931 };
8932 FindCygwin
8934 Find Cygwin, a POSIX-compatible environment that runs natively on Mi‐
8935 crosoft Windows
8936 FindDart
8938 Find DART
8939 This module looks for the dart testing software and sets DART_ROOT to
8941 point to where it found it.
8942 FindDCMTK
8944 Find DICOM ToolKit (DCMTK) libraries and applications
8945 The module defines the following variables:
8947 DCMTK_INCLUDE_DIRS - Directories to include to use DCMTK
8949 DCMTK_LIBRARIES - Files to link against to use DCMTK
8950 DCMTK_FOUND - If false, don't try to use DCMTK
8951 DCMTK_DIR - (optional) Source directory for DCMTK
8952 Compatibility
8954 This module is able to find a version of DCMTK that does or does not
8955 export a DCMTKConfig.cmake file. It applies a two step process:
8956 · Step 1: Attempt to find DCMTK version providing a DCMTKConfig.cmake
8958 file.
8959 · Step 2: If step 1 failed, rely on FindDCMTK.cmake to set DCMTK_*
8961 variables details below.
8962 Recent DCMTK provides a DCMTKConfig.cmake package configuration file.
8964 To exclusively use the package configuration file (recommended when
8965 possible), pass the NO_MODULE option to find_package(). For example,
8966 find_package(DCMTK NO_MODULE). This requires official DCMTK snapshot
8967 3.6.1_20140617 or newer.
8968 Until all clients update to the more recent DCMTK, build systems will
8970 need to support different versions of DCMTK.
8971 On any given system, the following combinations of DCMTK versions could
8973 be considered:
8974 ┌───────┬─────────────────┬─────────────────┬─────────────┐
8976 │ │ SYSTEM DCMTK │ LOCAL DCMTK │ Supported ? │
8977 ├───────┼─────────────────┼─────────────────┼─────────────┤
8978 │Case A │ NA │ [ ] DCMTKConfig │ YES │
8979 ├───────┼─────────────────┼─────────────────┼─────────────┤
8980 │Case B │ NA │ [X] DCMTKConfig │ YES │
8981 ├───────┼─────────────────┼─────────────────┼─────────────┤
8982 │Case C │ [ ] DCMTKConfig │ NA │ YES │
8983 ├───────┼─────────────────┼─────────────────┼─────────────┤
8984 │Case D │ [X] DCMTKConfig │ NA │ YES │
8985 ├───────┼─────────────────┼─────────────────┼─────────────┤
8986 │Case E │ [ ] DCMTKConfig │ [ ] DCMTKConfig │ YES (*) │
8987 ├───────┼─────────────────┼─────────────────┼─────────────┤
8988 │Case F │ [X] DCMTKConfig │ [ ] DCMTKConfig │ NO │
8989 ├───────┼─────────────────┼─────────────────┼─────────────┤
8990 │Case G │ [ ] DCMTKConfig │ [X] DCMTKConfig │ YES │
8991 ├───────┼─────────────────┼─────────────────┼─────────────┤
8992 │Case H │ [X] DCMTKConfig │ [X] DCMTKConfig │ YES │
8993 └───────┴─────────────────┴─────────────────┴─────────────┘
8994 (*) See Troubleshooting section.
8995 Legend:
8997 NA ……………: Means that no System or Local DCMTK is available
8998 [ ] DCMTKConfig ..: Means that the version of DCMTK does NOT export
9000 a DCMTKConfig.cmake file.
9001 [X] DCMTKConfig ..: Means that the version of DCMTK exports a DCMTK‐
9003 Config.cmake file.
9004 Troubleshooting
9006 What to do if my project finds a different version of DCMTK?
9007 Remove DCMTK entry from the CMake cache per find_package() documenta‐
9009 tion.
9010 FindDevIL
9012 This module locates the developer’s image library.
9013 http://openil.sourceforge.net/
9014 This module sets:
9016 IL_LIBRARIES - the name of the IL library. These include the full path to
9018 the core DevIL library. This one has to be linked into the
9019 application.
9020 ILU_LIBRARIES - the name of the ILU library. Again, the full path. This
9021 library is for filters and effects, not actual loading. It
9022 doesn't have to be linked if the functionality it provides
9023 is not used.
9024 ILUT_LIBRARIES - the name of the ILUT library. Full path. This part of the
9025 library interfaces with OpenGL. It is not strictly needed
9026 in applications.
9027 IL_INCLUDE_DIR - where to find the il.h, ilu.h and ilut.h files.
9028 DevIL_FOUND - this is set to TRUE if all the above variables were set.
9029 This will be set to false if ILU or ILUT are not found,
9030 even if they are not needed. In most systems, if one
9031 library is found all the others are as well. That's the
9032 way the DevIL developers release it.
9033 FindDoxygen
9035 Doxygen is a documentation generation tool (see
9036 http://www.doxygen.org). This module looks for Doxygen and some
9037 optional tools it supports. These tools are enabled as components in
9038 the find_package() command:
9039 dot Graphviz dot utility used to render various graphs.
9041 mscgen Message Chart Generator utility used by Doxygen’s \msc and \msc‐
9043 file commands.
9044 dia Dia the diagram editor used by Doxygen’s \diafile command.
9046 Examples:
9048 # Require dot, treat the other components as optional
9050 find_package(Doxygen
9051 REQUIRED dot
9052 OPTIONAL_COMPONENTS mscgen dia)
9053 The following variables are defined by this module:
9055 DOXYGEN_FOUND
9057 True if the doxygen executable was found.
9058 DOXYGEN_VERSION
9060 The version reported by doxygen --version.
9061 The module defines IMPORTED targets for Doxygen and each component
9063 found. These can be used as part of custom commands, etc. and should
9064 be preferred over old-style (and now deprecated) variables like DOXY‐
9065 GEN_EXECUTABLE. The following import targets are defined if their cor‐
9066 responding executable could be found (the component import targets will
9067 only be defined if that component was requested):
9068 Doxygen::doxygen
9070 Doxygen::dot
9071 Doxygen::mscgen
9072 Doxygen::dia
9073 Functions
9075 doxygen_add_docs
9076 This function is intended as a convenience for adding a target
9077 for generating documentation with Doxygen. It aims to provide
9078 sensible defaults so that projects can generally just provide
9079 the input files and directories and that will be sufficient to
9080 give sensible results. The function supports the ability to cus‐
9081 tomize the Doxygen configuration used to build the documenta‐
9082 tion.
9083 doxygen_add_docs(targetName
9085 [filesOrDirs...]
9086 [ALL]
9087 [USE_STAMP_FILE]
9088 [WORKING_DIRECTORY dir]
9089 [COMMENT comment])
9090 The function constructs a Doxyfile and defines a custom target
9092 that runs Doxygen on that generated file. The listed files and
9093 directories are used as the INPUT of the generated Doxyfile and
9094 they can contain wildcards. Any files that are listed explic‐
9095 itly will also be added as SOURCES of the custom target so they
9096 will show up in an IDE project’s source list.
9097 So that relative input paths work as expected, by default the
9099 working directory of the Doxygen command will be the current
9100 source directory (i.e. CMAKE_CURRENT_SOURCE_DIR). This can be
9101 overridden with the WORKING_DIRECTORY option to change the
9102 directory used as the relative base point. Note also that Doxy‐
9103 gen’s default behavior is to strip the working directory from
9104 relative paths in the generated documentation (see the
9105 STRIP_FROM_PATH Doxygen config option for details).
9106 If provided, the optional comment will be passed as the COMMENT
9108 for the add_custom_target() command used to create the custom
9109 target internally.
9110 If ALL is set, the target will be added to the default build
9112 target.
9113 If USE_STAMP_FILE is set, the custom command defined by this
9115 function will create a stamp file with the name <target‐
9116 Name>.stamp in the current binary directory whenever doxygen is
9117 re-run. With this option present, all items in <filesOrDirs>
9118 must be files (i.e. no directories, symlinks or wildcards) and
9119 each of the files must exist at the time doxygen_add_docs() is
9120 called. An error will be raised if any of the items listed is
9121 missing or is not a file when USE_STAMP_FILE is given. A depen‐
9122 dency will be created on each of the files so that doxygen will
9123 only be re-run if one of the files is updated. Without the
9124 USE_STAMP_FILE option, doxygen will always be re-run if the
9125 <targetName> target is built regardless of whether anything
9126 listed in <filesOrDirs> has changed.
9127 The contents of the generated Doxyfile can be customized by set‐
9129 ting CMake variables before calling doxygen_add_docs(). Any
9130 variable with a name of the form DOXYGEN_<tag> will have its
9131 value substituted for the corresponding <tag> configuration
9132 option in the Doxyfile. See the Doxygen documentation for the
9133 full list of supported configuration options.
9134 Some of Doxygen’s defaults are overridden to provide more appro‐
9136 priate behavior for a CMake project. Each of the following will
9137 be explicitly set unless the variable already has a value before
9138 doxygen_add_docs() is called (with some exceptions noted):
9139 DOXYGEN_HAVE_DOT
9141 Set to YES if the dot component was requested and it was
9142 found, NO otherwise. Any existing value of DOXY‐
9143 GEN_HAVE_DOT is ignored.
9144 DOXYGEN_DOT_MULTI_TARGETS
9146 Set to YES by this module (note that this requires a dot
9147 version newer than 1.8.10). This option is only meaning‐
9148 ful if DOXYGEN_HAVE_DOT is also set to YES.
9149 DOXYGEN_GENERATE_LATEX
9151 Set to NO by this module.
9152 DOXYGEN_WARN_FORMAT
9154 For Visual Studio based generators, this is set to the
9155 form recognized by the Visual Studio IDE: $file($line) :
9156 $text. For all other generators, Doxygen’s default value
9157 is not overridden.
9158 DOXYGEN_PROJECT_NAME
9160 Populated with the name of the current project (i.e.
9161 PROJECT_NAME).
9162 DOXYGEN_PROJECT_NUMBER
9164 Populated with the version of the current project (i.e.
9165 PROJECT_VERSION).
9166 DOXYGEN_PROJECT_BRIEF
9168 Populated with the description of the current project
9169 (i.e. PROJECT_DESCRIPTION).
9170 DOXYGEN_INPUT
9172 Projects should not set this variable. It will be popu‐
9173 lated with the set of files and directories passed to
9174 doxygen_add_docs(), thereby providing consistent behavior
9175 with the other built-in commands like add_executable(),
9176 add_library() and add_custom_target(). If a variable
9177 named DOXYGEN_INPUT is set by the project, it will be
9178 ignored and a warning will be issued.
9179 DOXYGEN_RECURSIVE
9181 Set to YES by this module.
9182 DOXYGEN_EXCLUDE_PATTERNS
9184 If the set of inputs includes directories, this variable
9185 will specify patterns used to exclude files from them.
9186 The following patterns are added by doxygen_add_docs() to
9187 ensure CMake-specific files and directories are not
9188 included in the input. If the project sets DOXY‐
9189 GEN_EXCLUDE_PATTERNS, those contents are merged with
9190 these additional patterns rather than replacing them:
9191 */.git/*
9193 */.svn/*
9194 */.hg/*
9195 */CMakeFiles/*
9196 */_CPack_Packages/*
9197 DartConfiguration.tcl
9198 CMakeLists.txt
9199 CMakeCache.txt
9200 DOXYGEN_OUTPUT_DIRECTORY
9202 Set to CMAKE_CURRENT_BINARY_DIR by this module. Note that
9203 if the project provides its own value for this and it is
9204 a relative path, it will be converted to an absolute path
9205 relative to the current binary directory. This is neces‐
9206 sary because doxygen will normally be run from a direc‐
9207 tory within the source tree so that relative source paths
9208 work as expected. If this directory does not exist, it
9209 will be recursively created prior to executing the doxy‐
9210 gen commands.
9211 To change any of these defaults or override any other Doxygen config
9213 option, set relevant variables before calling doxygen_add_docs(). For
9214 example:
9215 set(DOXYGEN_GENERATE_HTML NO)
9217 set(DOXYGEN_GENERATE_MAN YES)
9218 doxygen_add_docs(
9220 doxygen
9221 ${PROJECT_SOURCE_DIR}
9222 COMMENT "Generate man pages"
9223 )
9224 A number of Doxygen config options accept lists of values, but Doxygen
9226 requires them to be separated by whitespace. CMake variables hold lists
9227 as a string with items separated by semi-colons, so a conversion needs
9228 to be performed. The doxygen_add_docs() command specifically checks the
9229 following Doxygen config options and will convert their associated
9230 CMake variable’s contents into the required form if set.
9231 ABBREVIATE_BRIEF
9233 ALIASES
9234 CITE_BIB_FILES
9235 DIAFILE_DIRS
9236 DOTFILE_DIRS
9237 DOT_FONTPATH
9238 ENABLED_SECTIONS
9239 EXAMPLE_PATH
9240 EXAMPLE_PATTERNS
9241 EXCLUDE
9242 EXCLUDE_PATTERNS
9243 EXCLUDE_SYMBOLS
9244 EXPAND_AS_DEFINED
9245 EXTENSION_MAPPING
9246 EXTRA_PACKAGES
9247 EXTRA_SEARCH_MAPPINGS
9248 FILE_PATTERNS
9249 FILTER_PATTERNS
9250 FILTER_SOURCE_PATTERNS
9251 HTML_EXTRA_FILES
9252 HTML_EXTRA_STYLESHEET
9253 IGNORE_PREFIX
9254 IMAGE_PATH
9255 INCLUDE_FILE_PATTERNS
9256 INCLUDE_PATH
9257 INPUT
9258 LATEX_EXTRA_FILES
9259 LATEX_EXTRA_STYLESHEET
9260 MATHJAX_EXTENSIONS
9261 MSCFILE_DIRS
9262 PLANTUML_INCLUDE_PATH
9263 PREDEFINED
9264 QHP_CUST_FILTER_ATTRS
9265 QHP_SECT_FILTER_ATTRS
9266 STRIP_FROM_INC_PATH
9267 STRIP_FROM_PATH
9268 TAGFILES
9269 TCL_SUBST
9270 The following single value Doxygen options will be quoted automatically
9272 if they contain at least one space:
9273 CHM_FILE
9275 DIA_PATH
9276 DOCBOOK_OUTPUT
9277 DOCSET_FEEDNAME
9278 DOCSET_PUBLISHER_NAME
9279 DOT_FONTNAME
9280 DOT_PATH
9281 EXTERNAL_SEARCH_ID
9282 FILE_VERSION_FILTER
9283 GENERATE_TAGFILE
9284 HHC_LOCATION
9285 HTML_FOOTER
9286 HTML_HEADER
9287 HTML_OUTPUT
9288 HTML_STYLESHEET
9289 INPUT_FILTER
9290 LATEX_FOOTER
9291 LATEX_HEADER
9292 LATEX_OUTPUT
9293 LAYOUT_FILE
9294 MAN_OUTPUT
9295 MAN_SUBDIR
9296 MATHJAX_CODEFILE
9297 MSCGEN_PATH
9298 OUTPUT_DIRECTORY
9299 PERL_PATH
9300 PLANTUML_JAR_PATH
9301 PROJECT_BRIEF
9302 PROJECT_LOGO
9303 PROJECT_NAME
9304 QCH_FILE
9305 QHG_LOCATION
9306 QHP_CUST_FILTER_NAME
9307 QHP_VIRTUAL_FOLDER
9308 RTF_EXTENSIONS_FILE
9309 RTF_OUTPUT
9310 RTF_STYLESHEET_FILE
9311 SEARCHDATA_FILE
9312 USE_MDFILE_AS_MAINPAGE
9313 WARN_FORMAT
9314 WARN_LOGFILE
9315 XML_OUTPUT
9316 There are situations where it may be undesirable for a particular con‐
9318 fig option to be automatically quoted by doxygen_add_docs(), such as
9319 ALIASES which may need to include its own embedded quoting. The DOXY‐
9320 GEN_VERBATIM_VARS variable can be used to specify a list of Doxygen
9321 variables (including the leading DOXYGEN_ prefix) which should not be
9322 quoted. The project is then responsible for ensuring that those vari‐
9323 ables’ values make sense when placed directly in the Doxygen input
9324 file. In the case of list variables, list items are still separated by
9325 spaces, it is only the automatic quoting that is skipped. For example,
9326 the following allows doxygen_add_docs() to apply quoting to DOXY‐
9327 GEN_PROJECT_BRIEF, but not each item in the DOXYGEN_ALIASES list
9328 (bracket syntax can also be used to make working with embedded quotes
9329 easier):
9330 set(DOXYGEN_PROJECT_BRIEF "String with spaces")
9332 set(DOXYGEN_ALIASES
9333 [[somealias="@some_command param"]]
9334 "anotherAlias=@foobar"
9335 )
9336 set(DOXYGEN_VERBATIM_VARS DOXYGEN_ALIASES)
9337 The resultant Doxyfile will contain the following lines:
9339 PROJECT_BRIEF = "String with spaces"
9341 ALIASES = somealias="@some_command param" anotherAlias=@foobar
9342 Deprecated Result Variables
9344 For compatibility with previous versions of CMake, the following vari‐
9345 ables are also defined but they are deprecated and should no longer be
9346 used:
9347 DOXYGEN_EXECUTABLE
9349 The path to the doxygen command. If projects need to refer to
9350 the doxygen executable directly, they should use the Doxy‐
9351 gen::doxygen import target instead.
9352 DOXYGEN_DOT_FOUND
9354 True if the dot executable was found.
9355 DOXYGEN_DOT_EXECUTABLE
9357 The path to the dot command. If projects need to refer to the
9358 dot executable directly, they should use the Doxygen::dot import
9359 target instead.
9360 DOXYGEN_DOT_PATH
9362 The path to the directory containing the dot executable as
9363 reported in DOXYGEN_DOT_EXECUTABLE. The path may have forward
9364 slashes even on Windows and is not suitable for direct substitu‐
9365 tion into a Doxyfile.in template. If you need this value, get
9366 the IMPORTED_LOCATION property of the Doxygen::dot target and
9367 use get_filename_component() to extract the directory part of
9368 that path. You may also want to consider using
9369 file(TO_NATIVE_PATH) to prepare the path for a Doxygen configu‐
9370 ration file.
9371 Deprecated Hint Variables
9373 DOXYGEN_SKIP_DOT
9374 This variable has no effect for the component form of find_pack‐
9375 age. In backward compatibility mode (i.e. without components
9376 list) it prevents the finder module from searching for
9377 Graphviz’s dot utility.
9378 FindEnvModules
9380 Locate an environment module implementation and make commands available
9381 to CMake scripts to use them. This is compatible with both Lua-based
9382 Lmod and TCL-based EnvironmentModules.
9383 This module is intended for the use case of setting up the compiler and
9385 library environment within a CTest Script (ctest -S). It can also be
9386 used in a CMake Script (cmake -P).
9387 NOTE:
9389 The loaded environment will not survive past the end of the calling
9390 process. Do not use this module in project code (CMakeLists.txt
9391 files) to load a compiler environment; it will not be available dur‐
9392 ing the build. Instead load the environment manually before running
9393 CMake or using the generated build system.
9394 Example Usage
9396 set(CTEST_BUILD_NAME "CrayLinux-CrayPE-Cray-dynamic")
9397 set(CTEST_BUILD_CONFIGURATION Release)
9398 set(CTEST_BUILD_FLAGS "-k -j8")
9399 set(CTEST_CMAKE_GENERATOR "Unix Makefiles")
9400 ...
9402 find_package(EnvModules REQUIRED)
9404 env_module(purge)
9406 env_module(load modules)
9407 env_module(load craype)
9408 env_module(load PrgEnv-cray)
9409 env_module(load craype-knl)
9410 env_module(load cray-mpich)
9411 env_module(load cray-libsci)
9412 set(ENV{CRAYPE_LINK_TYPE} dynamic)
9414 ...
9416 Result Variables
9418 This module will set the following variables in your project:
9419 EnvModules_FOUND
9421 True if a compatible environment modules framework was found.
9422 Cache Variables
9424 The following cache variable will be set:
9425 EnvModules_COMMAND
9427 The low level module command to use. Currently supported imple‐
9428 mentations are the Lua based Lmod and TCL based EnvironmentMod‐
9429 ules.
9430 Environment Variables
9432 ENV{MODULESHOME}
9433 Usually set by the module environment implementation, used as a
9434 hint to locate the module command to execute.
9435 Provided Functions
9437 This defines the following CMake functions for interacting with envi‐
9438 ronment modules:
9439 env_module
9441 Execute an aribitrary module command:
9442 env_module(cmd arg1 ... argN)
9444 env_module(
9445 COMMAND cmd arg1 ... argN
9446 [OUTPUT_VARIABLE <out-var>]
9447 [RESULT_VARIABLE <ret-var>]
9448 )
9449 The options are:
9451 cmd arg1 ... argN
9453 The module sub-command and arguments to execute as if
9454 they were passed directly to the module command in your
9455 shell environment.
9456 OUTPUT_VARIABLE <out-var>
9458 The standard output from executing the module command.
9459 RESULT_VARIABLE <ret-var>
9461 The return code from executing the module command.
9462 env_module_swap
9464 Swap one module for another:
9465 env_module_swap(out_mod in_mod
9467 [OUTPUT_VARIABLE <out-var>]
9468 [RESULT_VARIABLE <ret-var>]
9469 )
9470 This is functionally equivalent to the module swap out_mod
9472 in_mod shell command. The options are:
9473 OUTPUT_VARIABLE <out-var>
9475 The standard output from executing the module command.
9476 RESULT_VARIABLE <ret-var>
9478 The return code from executing the module command.
9479 env_module_list
9481 Retrieve the list of currently loaded modules:
9482 env_module_list(<out-var>)
9484 This is functionally equivalent to the module list shell com‐
9486 mand. The result is stored in <out-var> as a properly formatted
9487 CMake semicolon-separated list variable.
9488 env_module_avail
9490 Retrieve the list of available modules:
9491 env_module_avail([<mod-prefix>] <out-var>)
9493 This is functionally equivalent to the module avail <mod-prefix>
9495 shell command. The result is stored in <out-var> as a properly
9496 formatted CMake semicolon-separated list variable.
9497 FindEXPAT
9499 Find the native Expat headers and library. Expat is a stream-oriented
9500 XML parser library written in C.
9501 Imported Targets
9503 This module defines the following IMPORTED targets:
9504 EXPAT::EXPAT
9506 The Expat expat library, if found.
9507 Result Variables
9509 This module will set the following variables in your project:
9510 EXPAT_INCLUDE_DIRS
9512 where to find expat.h, etc.
9513 EXPAT_LIBRARIES
9515 the libraries to link against to use Expat.
9516 EXPAT_FOUND
9518 true if the Expat headers and libraries were found.
9519 FindFLEX
9521 Find Fast Lexical Analyzer (Flex) executable and provides a macro to
9522 generate custom build rules
9523 The module defines the following variables:
9525 FLEX_FOUND - True is flex executable is found
9527 FLEX_EXECUTABLE - the path to the flex executable
9528 FLEX_VERSION - the version of flex
9529 FLEX_LIBRARIES - The flex libraries
9530 FLEX_INCLUDE_DIRS - The path to the flex headers
9531 The minimum required version of flex can be specified using the stan‐
9533 dard syntax, e.g. find_package(FLEX 2.5.13)
9534 If flex is found on the system, the module provides the macro:
9536 FLEX_TARGET(Name FlexInput FlexOutput
9538 [COMPILE_FLAGS <string>]
9539 [DEFINES_FILE <string>]
9540 )
9541 which creates a custom command to generate the FlexOutput file from the
9543 FlexInput file. If COMPILE_FLAGS option is specified, the next parame‐
9544 ter is added to the flex command line. If flex is configured to output
9545 a header file, the DEFINES_FILE option may be used to specify its name.
9546 Name is an alias used to get details of this custom command. Indeed
9547 the macro defines the following variables:
9548 FLEX_${Name}_DEFINED - true is the macro ran successfully
9550 FLEX_${Name}_OUTPUTS - the source file generated by the custom rule, an
9551 alias for FlexOutput
9552 FLEX_${Name}_INPUT - the flex source file, an alias for ${FlexInput}
9553 FLEX_${Name}_OUTPUT_HEADER - the header flex output, if any.
9554 Flex scanners often use tokens defined by Bison: the code generated by
9556 Flex depends of the header generated by Bison. This module also
9557 defines a macro:
9558 ADD_FLEX_BISON_DEPENDENCY(FlexTarget BisonTarget)
9560 which adds the required dependency between a scanner and a parser where
9562 FlexTarget and BisonTarget are the first parameters of respectively
9563 FLEX_TARGET and BISON_TARGET macros.
9564 ====================================================================
9566 Example:
9567 find_package(BISON)
9569 find_package(FLEX)
9570 BISON_TARGET(MyParser parser.y ${CMAKE_CURRENT_BINARY_DIR}/parser.cpp)
9572 FLEX_TARGET(MyScanner lexer.l ${CMAKE_CURRENT_BINARY_DIR}/lexer.cpp)
9573 ADD_FLEX_BISON_DEPENDENCY(MyScanner MyParser)
9574 include_directories(${CMAKE_CURRENT_BINARY_DIR})
9576 add_executable(Foo
9577 Foo.cc
9578 ${BISON_MyParser_OUTPUTS}
9579 ${FLEX_MyScanner_OUTPUTS}
9580 )
9581 target_link_libraries(Foo ${FLEX_LIBRARIES})
9582 ====================================================================
9583 FindFLTK2
9585 Find the native FLTK 2.0 includes and library
9586 The following settings are defined
9588 FLTK2_FLUID_EXECUTABLE, where to find the Fluid tool
9590 FLTK2_WRAP_UI, This enables the FLTK2_WRAP_UI command
9591 FLTK2_INCLUDE_DIR, where to find include files
9592 FLTK2_LIBRARIES, list of fltk2 libraries
9593 FLTK2_FOUND, Don't use FLTK2 if false.
9594 The following settings should not be used in general.
9596 FLTK2_BASE_LIBRARY = the full path to fltk2.lib
9598 FLTK2_GL_LIBRARY = the full path to fltk2_gl.lib
9599 FLTK2_IMAGES_LIBRARY = the full path to fltk2_images.lib
9600 FindFLTK
9602 Find the Fast Light Toolkit (FLTK) library
9603 Input Variables
9605 By default this module will search for all of the FLTK components and
9606 add them to the FLTK_LIBRARIES variable. You can limit the components
9607 which get placed in FLTK_LIBRARIES by defining one or more of the fol‐
9608 lowing three options:
9609 FLTK_SKIP_OPENGL
9611 Set to true to disable searching for the FLTK GL library
9612 FLTK_SKIP_FORMS
9614 Set to true to disable searching for the FLTK Forms library
9615 FLTK_SKIP_IMAGES
9617 Set to true to disable searching for the FLTK Images library
9618 FLTK is composed also by a binary tool. You can set the following
9620 option:
9621 FLTK_SKIP_FLUID
9623 Set to true to not look for the FLUID binary
9624 Result Variables
9626 The following variables will be defined:
9627 FLTK_FOUND
9629 True if all components not skipped were found
9630 FLTK_INCLUDE_DIR
9632 Path to the include directory for FLTK header files
9633 FLTK_LIBRARIES
9635 List of the FLTK libraries found
9636 FLTK_FLUID_EXECUTABLE
9638 Path to the FLUID binary tool
9639 FLTK_WRAP_UI
9641 True if FLUID is found, used to enable the FLTK_WRAP_UI command
9642 Cache Variables
9644 The following cache variables are also available to set or use:
9645 FLTK_BASE_LIBRARY_RELEASE
9647 The FLTK base library (optimized)
9648 FLTK_BASE_LIBRARY_DEBUG
9650 The FLTK base library (debug)
9651 FLTK_GL_LIBRARY_RELEASE
9653 The FLTK GL library (optimized)
9654 FLTK_GL_LIBRARY_DEBUG
9656 The FLTK GL library (debug)
9657 FLTK_FORMS_LIBRARY_RELEASE
9659 The FLTK Forms library (optimized)
9660 FLTK_FORMS_LIBRARY_DEBUG
9662 The FLTK Forms library (debug)
9663 FLTK_IMAGES_LIBRARY_RELEASE
9665 The FLTK Images protobuf library (optimized)
9666 FLTK_IMAGES_LIBRARY_DEBUG
9668 The FLTK Images library (debug)
9669 FindFontconfig
9671 Find Fontconfig headers and library.
9672 Imported Targets
9674 Fontconfig::Fontconfig
9675 The Fontconfig library, if found.
9676 Result Variables
9678 This will define the following variables in your project:
9679 Fontconfig_FOUND
9681 true if (the requested version of) Fontconfig is available.
9682 Fontconfig_VERSION
9684 the version of Fontconfig.
9685 Fontconfig_LIBRARIES
9687 the libraries to link against to use Fontconfig.
9688 Fontconfig_INCLUDE_DIRS
9690 where to find the Fontconfig headers.
9691 Fontconfig_COMPILE_OPTIONS
9693 this should be passed to target_compile_options(), if the target
9694 is not used for linking
9695 FindFreetype
9697 Find the FreeType font renderer includes and library.
9698 Imported Targets
9700 This module defines the following IMPORTED target:
9701 Freetype::Freetype
9703 The Freetype freetype library, if found
9704 Result Variables
9706 This module will set the following variables in your project:
9707 FREETYPE_FOUND
9709 true if the Freetype headers and libraries were found
9710 FREETYPE_INCLUDE_DIRS
9712 directories containing the Freetype headers. This is the con‐
9713 catenation of the variables:
9714 FREETYPE_INCLUDE_DIR_ft2build
9716 directory holding the main Freetype API configuration
9717 header
9718 FREETYPE_INCLUDE_DIR_freetype2
9720 directory holding Freetype public headers
9721 FREETYPE_LIBRARIES
9723 the library to link against
9724 FREETYPE_VERSION_STRING
9726 the version of freetype found (since CMake 2.8.8)
9727 Hints
9729 The user may set the environment variable FREETYPE_DIR to the root
9730 directory of a Freetype installation.
9731 FindGCCXML
9733 Find the GCC-XML front-end executable.
9734 This module will define the following variables:
9736 GCCXML - the GCC-XML front-end executable.
9738 FindGDAL
9740 Find Geospatial Data Abstraction Library (GDAL).
9741 IMPORTED Targets
9743 This module defines IMPORTED target GDAL::GDAL if GDAL has been found.
9744 Result Variables
9746 This module will set the following variables in your project:
9747 GDAL_FOUND
9749 True if GDAL is found.
9750 GDAL_INCLUDE_DIRS
9752 Include directories for GDAL headers.
9753 GDAL_LIBRARIES
9755 Libraries to link to GDAL.
9756 GDAL_VERSION
9758 The version of GDAL found.
9759 Cache variables
9761 The following cache variables may also be set:
9762 GDAL_LIBRARY
9764 The libgdal library file.
9765 GDAL_INCLUDE_DIR
9767 The directory containing gdal.h.
9768 Hints
9770 Set GDAL_DIR or GDAL_ROOT in the environment to specify the GDAL
9771 installation prefix.
9772 FindGettext
9774 Find GNU gettext tools
9775 This module looks for the GNU gettext tools. This module defines the
9777 following values:
9778 GETTEXT_MSGMERGE_EXECUTABLE: the full path to the msgmerge tool.
9780 GETTEXT_MSGFMT_EXECUTABLE: the full path to the msgfmt tool.
9781 GETTEXT_FOUND: True if gettext has been found.
9782 GETTEXT_VERSION_STRING: the version of gettext found (since CMake 2.8.8)
9783 Additionally it provides the following macros:
9785 GETTEXT_CREATE_TRANSLATIONS ( outputFile [ALL] file1 … fileN )
9787 This will create a target "translations" which will convert the
9789 given input po files into the binary output mo file. If the
9790 ALL option is used, the translations will also be created when
9791 building the default target.
9792 GETTEXT_PROCESS_POT_FILE( <potfile> [ALL] [INSTALL_DESTINATION <dest‐
9794 dir>] LANGUAGES <lang1> <lang2> … )
9795 Process the given pot file to mo files.
9797 If INSTALL_DESTINATION is given then automatically install rules will
9798 be created, the language subdirectory will be taken into account
9799 (by default use share/locale/).
9800 If ALL is specified, the pot file is processed when building the all traget.
9801 It creates a custom target "potfile".
9802 GETTEXT_PROCESS_PO_FILES( <lang> [ALL] [INSTALL_DESTINATION <dir>]
9804 PO_FILES <po1> <po2> … )
9805 Process the given po files to mo files for the given language.
9807 If INSTALL_DESTINATION is given then automatically install rules will
9808 be created, the language subdirectory will be taken into account
9809 (by default use share/locale/).
9810 If ALL is specified, the po files are processed when building the all traget.
9811 It creates a custom target "pofiles".
9812 NOTE:
9814 If you wish to use the Gettext library (libintl), use FindIntl.
9815 FindGIF
9817 This finds the Graphics Interchange Format (GIF) library (giflib)
9818 Imported targets
9820 This module defines the following IMPORTED target:
9821 GIF::GIF
9823 The giflib library, if found.
9824 Result variables
9826 This module will set the following variables in your project:
9827 GIF_FOUND
9829 If false, do not try to use GIF.
9830 GIF_INCLUDE_DIRS
9832 where to find gif_lib.h, etc.
9833 GIF_LIBRARIES
9835 the libraries needed to use GIF.
9836 GIF_VERSION
9838 3, 4 or a full version string (eg 5.1.4) for versions >= 4.1.6.
9839 Cache variables
9841 The following cache variables may also be set:
9842 GIF_INCLUDE_DIR
9844 where to find the GIF headers.
9845 GIF_LIBRARY
9847 where to find the GIF library.
9848 Hints
9850 GIF_DIR is an environment variable that would correspond to the ./con‐
9851 figure --prefix=$GIF_DIR.
9852 FindGit
9854 The module defines the following IMPORTED targets (when CMAKE_ROLE is
9855 PROJECT):
9856 Git::Git
9858 Executable of the Git command-line client.
9859 The module defines the following variables:
9861 GIT_EXECUTABLE
9863 Path to Git command-line client.
9864 Git_FOUND, GIT_FOUND
9866 True if the Git command-line client was found.
9867 GIT_VERSION_STRING
9869 The version of Git found.
9870 Example usage:
9872 find_package(Git)
9874 if(Git_FOUND)
9875 message("Git found: ${GIT_EXECUTABLE}")
9876 endif()
9877 FindGLEW
9879 Find the OpenGL Extension Wrangler Library (GLEW)
9880 Input Variables
9882 The following variables may be set to influence this module’s behavior:
9883 GLEW_USE_STATIC_LIBS
9885 to find and create IMPORTED target for static linkage.
9886 GLEW_VERBOSE
9888 to output a detailed log of this module.
9889 Imported Targets
9891 This module defines the following Imported Targets:
9892 GLEW::glew
9894 The GLEW shared library.
9895 GLEW::glew_s
9897 The GLEW static library, if GLEW_USE_STATIC_LIBS is set to TRUE.
9898 GLEW::GLEW
9900 Duplicates either GLEW::glew or GLEW::glew_s based on availabil‐
9901 ity.
9902 Result Variables
9904 This module defines the following variables:
9905 GLEW_INCLUDE_DIRS
9907 include directories for GLEW
9908 GLEW_LIBRARIES
9910 libraries to link against GLEW
9911 GLEW_SHARED_LIBRARIES
9913 libraries to link against shared GLEW
9914 GLEW_STATIC_LIBRARIES
9916 libraries to link against static GLEW
9917 GLEW_FOUND
9919 true if GLEW has been found and can be used
9920 GLEW_VERSION
9922 GLEW version
9923 GLEW_VERSION_MAJOR
9925 GLEW major version
9926 GLEW_VERSION_MINOR
9928 GLEW minor version
9929 GLEW_VERSION_MICRO
9931 GLEW micro version
9932 FindGLUT
9934 Find OpenGL Utility Toolkit (GLUT) library and include files.
9935 IMPORTED Targets
9937 This module defines the IMPORTED targets:
9938 GLUT::GLUT
9940 Defined if the system has GLUT.
9941 Result Variables
9943 This module sets the following variables:
9944 GLUT_INCLUDE_DIR, where to find GL/glut.h, etc.
9946 GLUT_LIBRARIES, the libraries to link against
9947 GLUT_FOUND, If false, do not try to use GLUT.
9948 Also defined, but not for general use are:
9950 GLUT_glut_LIBRARY = the full path to the glut library.
9952 GLUT_Xmu_LIBRARY = the full path to the Xmu library.
9953 GLUT_Xi_LIBRARY = the full path to the Xi Library.
9954 FindGnuplot
9956 this module looks for gnuplot
9957 Once done this will define
9959 GNUPLOT_FOUND - system has Gnuplot
9961 GNUPLOT_EXECUTABLE - the Gnuplot executable
9962 GNUPLOT_VERSION_STRING - the version of Gnuplot found (since CMake 2.8.8)
9963 GNUPLOT_VERSION_STRING will not work for old versions like 3.7.1.
9965 FindGnuTLS
9967 Find the GNU Transport Layer Security library (gnutls)
9968 IMPORTED Targets
9970 This module defines IMPORTED target GnuTLS::GnuTLS, if gnutls has been
9971 found.
9972 Result Variables
9974 GNUTLS_FOUND
9975 System has gnutls
9976 GNUTLS_INCLUDE_DIR
9978 The gnutls include directory
9979 GNUTLS_LIBRARIES
9981 The libraries needed to use gnutls
9982 GNUTLS_DEFINITIONS
9984 Compiler switches required for using gnutls
9985 GNUTLS_VERSION
9987 version of gnutls.
9988 FindGSL
9990 Find the native GNU Scientific Library (GSL) includes and libraries.
9991 The GNU Scientific Library (GSL) is a numerical library for C and C++
9993 programmers. It is free software under the GNU General Public License.
9994 Imported Targets
9996 If GSL is found, this module defines the following IMPORTED targets:
9997 GSL::gsl - The main GSL library.
9999 GSL::gslcblas - The CBLAS support library used by GSL.
10000 Result Variables
10002 This module will set the following variables in your project:
10003 GSL_FOUND - True if GSL found on the local system
10005 GSL_INCLUDE_DIRS - Location of GSL header files.
10006 GSL_LIBRARIES - The GSL libraries.
10007 GSL_VERSION - The version of the discovered GSL install.
10008 Hints
10010 Set GSL_ROOT_DIR to a directory that contains a GSL installation.
10011 This script expects to find libraries at $GSL_ROOT_DIR/lib and the GSL
10013 headers at $GSL_ROOT_DIR/include/gsl. The library directory may
10014 optionally provide Release and Debug folders. If available, the
10015 libraries named gsld, gslblasd or cblasd are recognized as debug
10016 libraries. For Unix-like systems, this script will use
10017 $GSL_ROOT_DIR/bin/gsl-config (if found) to aid in the discovery of GSL.
10018 Cache Variables
10020 This module may set the following variables depending on platform and
10021 type of GSL installation discovered. These variables may optionally be
10022 set to help this module find the correct files:
10023 GSL_CBLAS_LIBRARY - Location of the GSL CBLAS library.
10025 GSL_CBLAS_LIBRARY_DEBUG - Location of the debug GSL CBLAS library (if any).
10026 GSL_CONFIG_EXECUTABLE - Location of the ``gsl-config`` script (if any).
10027 GSL_LIBRARY - Location of the GSL library.
10028 GSL_LIBRARY_DEBUG - Location of the debug GSL library (if any).
10029 FindGTest
10031 Locate the Google C++ Testing Framework.
10032 Imported targets
10034 This module defines the following IMPORTED targets:
10035 GTest::GTest
10037 The Google Test gtest library, if found; adds Thread::Thread
10038 automatically
10039 GTest::Main
10041 The Google Test gtest_main library, if found
10042 Result variables
10044 This module will set the following variables in your project:
10045 GTEST_FOUND
10047 Found the Google Testing framework
10048 GTEST_INCLUDE_DIRS
10050 the directory containing the Google Test headers
10051 The library variables below are set as normal variables. These contain
10053 debug/optimized keywords when a debugging library is found.
10054 GTEST_LIBRARIES
10056 The Google Test gtest library; note it also requires linking
10057 with an appropriate thread library
10058 GTEST_MAIN_LIBRARIES
10060 The Google Test gtest_main library
10061 GTEST_BOTH_LIBRARIES
10063 Both gtest and gtest_main
10064 Cache variables
10066 The following cache variables may also be set:
10067 GTEST_ROOT
10069 The root directory of the Google Test installation (may also be
10070 set as an environment variable)
10071 GTEST_MSVC_SEARCH
10073 If compiling with MSVC, this variable can be set to MT or MD
10074 (the default) to enable searching a GTest build tree
10075 Example usage
10077 enable_testing()
10078 find_package(GTest REQUIRED)
10079 add_executable(foo foo.cc)
10081 target_link_libraries(foo GTest::GTest GTest::Main)
10082 add_test(AllTestsInFoo foo)
10084 Deeper integration with CTest
10086 See GoogleTest for information on the gtest_add_tests() and gtest_dis‐
10087 cover_tests() commands.
10088 FindGTK2
10090 Find the GTK2 widget libraries and several of its other optional compo‐
10091 nents like gtkmm, glade, and glademm.
10092 Specify one or more of the following components as you call this find
10094 module. See example below.
10095 · gtk
10097 · gtkmm
10099 · glade
10101 · glademm
10103 Result Variables
10105 The following variables will be defined for your use
10106 GTK2_FOUND
10108 Were all of your specified components found?
10109 GTK2_INCLUDE_DIRS
10111 All include directories
10112 GTK2_LIBRARIES
10114 All libraries
10115 GTK2_TARGETS
10117 All imported targets
10118 GTK2_DEFINITIONS
10120 Additional compiler flags
10121 GTK2_VERSION
10123 The version of GTK2 found (x.y.z)
10124 GTK2_MAJOR_VERSION
10126 The major version of GTK2
10127 GTK2_MINOR_VERSION
10129 The minor version of GTK2
10130 GTK2_PATCH_VERSION
10132 The patch version of GTK2
10133 Input Variables
10135 Optional variables you can define prior to calling this module:
10136 GTK2_DEBUG
10138 Enables verbose debugging of the module
10139 GTK2_ADDITIONAL_SUFFIXES
10141 Allows defining additional directories to search for include
10142 files
10143 Example Usage
10145 Call find_package() once. Here are some examples to pick from:
10146 Require GTK 2.6 or later:
10148 find_package(GTK2 2.6 REQUIRED gtk)
10150 Require GTK 2.10 or later and Glade:
10152 find_package(GTK2 2.10 REQUIRED gtk glade)
10154 Search for GTK/GTKMM 2.8 or later:
10156 find_package(GTK2 2.8 COMPONENTS gtk gtkmm)
10158 Use the results:
10160 if(GTK2_FOUND)
10162 include_directories(${GTK2_INCLUDE_DIRS})
10163 add_executable(mygui mygui.cc)
10164 target_link_libraries(mygui ${GTK2_LIBRARIES})
10165 endif()
10166 FindGTK
10168 Find GTK, glib and GTKGLArea
10169 GTK_INCLUDE_DIR - Directories to include to use GTK
10171 GTK_LIBRARIES - Files to link against to use GTK
10172 GTK_FOUND - GTK was found
10173 GTK_GL_FOUND - GTK's GL features were found
10174 FindHDF5
10176 Find Hierarchical Data Format (HDF5), a library for reading and writing
10177 self describing array data.
10178 This module invokes the HDF5 wrapper compiler that should be installed
10180 alongside HDF5. Depending upon the HDF5 Configuration, the wrapper
10181 compiler is called either h5cc or h5pcc. If this succeeds, the module
10182 will then call the compiler with the show argument to see what flags
10183 are used when compiling an HDF5 client application.
10184 The module will optionally accept the COMPONENTS argument. If no COM‐
10186 PONENTS are specified, then the find module will default to finding
10187 only the HDF5 C library. If one or more COMPONENTS are specified, the
10188 module will attempt to find the language bindings for the specified
10189 components. The only valid components are C, CXX, Fortran, HL, and
10190 Fortran_HL. If the COMPONENTS argument is not given, the module will
10191 attempt to find only the C bindings.
10192 This module will read the variable HDF5_USE_STATIC_LIBRARIES to deter‐
10194 mine whether or not to prefer a static link to a dynamic link for HDF5
10195 and all of it’s dependencies. To use this feature, make sure that the
10196 HDF5_USE_STATIC_LIBRARIES variable is set before the call to find_pack‐
10197 age.
10198 To provide the module with a hint about where to find your HDF5 instal‐
10200 lation, you can set the environment variable HDF5_ROOT. The Find mod‐
10201 ule will then look in this path when searching for HDF5 executables,
10202 paths, and libraries.
10203 Both the serial and parallel HDF5 wrappers are considered and the first
10205 directory to contain either one will be used. In the event that both
10206 appear in the same directory the serial version is preferentially
10207 selected. This behavior can be reversed by setting the variable
10208 HDF5_PREFER_PARALLEL to True.
10209 In addition to finding the includes and libraries required to compile
10211 an HDF5 client application, this module also makes an effort to find
10212 tools that come with the HDF5 distribution that may be useful for
10213 regression testing.
10214 Result Variables
10216 This module will set the following variables in your project:
10217 HDF5_FOUND
10219 HDF5 was found on the system
10220 HDF5_VERSION
10222 HDF5 library version
10223 HDF5_INCLUDE_DIRS
10225 Location of the HDF5 header files
10226 HDF5_DEFINITIONS
10228 Required compiler definitions for HDF5
10229 HDF5_LIBRARIES
10231 Required libraries for all requested bindings
10232 HDF5_HL_LIBRARIES
10234 Required libraries for the HDF5 high level API for all bindings,
10235 if the HL component is enabled
10236 Available components are: C CXX Fortran and HL. For each enabled lan‐
10238 guage binding, a corresponding HDF5_${LANG}_LIBRARIES variable, and
10239 potentially HDF5_${LANG}_DEFINITIONS, will be defined. If the HL com‐
10240 ponent is enabled, then an HDF5_${LANG}_HL_LIBRARIES will also be
10241 defined. With all components enabled, the following variables will be
10242 defined:
10243 HDF5_C_DEFINITIONS
10245 Required compiler definitions for HDF5 C bindings
10246 HDF5_CXX_DEFINITIONS
10248 Required compiler definitions for HDF5 C++ bindings
10249 HDF5_Fortran_DEFINITIONS
10251 Required compiler definitions for HDF5 Fortran bindings
10252 HDF5_C_INCLUDE_DIRS
10254 Required include directories for HDF5 C bindings
10255 HDF5_CXX_INCLUDE_DIRS
10257 Required include directories for HDF5 C++ bindings
10258 HDF5_Fortran_INCLUDE_DIRS
10260 Required include directories for HDF5 Fortran bindings
10261 HDF5_C_LIBRARIES
10263 Required libraries for the HDF5 C bindings
10264 HDF5_CXX_LIBRARIES
10266 Required libraries for the HDF5 C++ bindings
10267 HDF5_Fortran_LIBRARIES
10269 Required libraries for the HDF5 Fortran bindings
10270 HDF5_C_HL_LIBRARIES
10272 Required libraries for the high level C bindings
10273 HDF5_CXX_HL_LIBRARIES
10275 Required libraries for the high level C++ bindings
10276 HDF5_Fortran_HL_LIBRARIES
10278 Required libraries for the high level Fortran bindings.
10279 HDF5_IS_PARALLEL
10281 HDF5 library has parallel IO support
10282 HDF5_C_COMPILER_EXECUTABLE
10284 path to the HDF5 C wrapper compiler
10285 HDF5_CXX_COMPILER_EXECUTABLE
10287 path to the HDF5 C++ wrapper compiler
10288 HDF5_Fortran_COMPILER_EXECUTABLE
10290 path to the HDF5 Fortran wrapper compiler
10291 HDF5_C_COMPILER_EXECUTABLE_NO_INTERROGATE
10293 path to the primary C compiler which is also the HDF5 wrapper
10294 HDF5_CXX_COMPILER_EXECUTABLE_NO_INTERROGATE
10296 path to the primary C++ compiler which is also the HDF5 wrapper
10297 HDF5_Fortran_COMPILER_EXECUTABLE_NO_INTERROGATE
10299 path to the primary Fortran compiler which is also the HDF5
10300 wrapper
10301 HDF5_DIFF_EXECUTABLE
10303 path to the HDF5 dataset comparison tool
10304 Hints
10306 The following variable can be set to guide the search for HDF5
10307 libraries and includes:
10308 HDF5_ROOT
10310 Specify the path to the HDF5 installation to use.
10311 HDF5_FIND_DEBUG
10313 Set true to get extra debugging output.
10314 HDF5_NO_FIND_PACKAGE_CONFIG_FILE
10316 Set true to skip trying to find hdf5-config.cmake.
10317 FindHg
10319 Extract information from a mercurial working copy.
10320 The module defines the following variables:
10322 HG_EXECUTABLE - path to mercurial command line client (hg)
10324 HG_FOUND - true if the command line client was found
10325 HG_VERSION_STRING - the version of mercurial found
10326 If the command line client executable is found the following macro is
10328 defined:
10329 HG_WC_INFO(<dir> <var-prefix>)
10331 Hg_WC_INFO extracts information of a mercurial working copy at a given
10333 location. This macro defines the following variables:
10334 <var-prefix>_WC_CHANGESET - current changeset
10336 <var-prefix>_WC_REVISION - current revision
10337 Example usage:
10339 find_package(Hg)
10341 if(HG_FOUND)
10342 message("hg found: ${HG_EXECUTABLE}")
10343 HG_WC_INFO(${PROJECT_SOURCE_DIR} Project)
10344 message("Current revision is ${Project_WC_REVISION}")
10345 message("Current changeset is ${Project_WC_CHANGESET}")
10346 endif()
10347 FindHSPELL
10349 Try to find Hebrew spell-checker (Hspell) and morphology engine.
10350 Once done this will define
10352 HSPELL_FOUND - system has Hspell
10354 HSPELL_INCLUDE_DIR - the Hspell include directory
10355 HSPELL_LIBRARIES - The libraries needed to use Hspell
10356 HSPELL_DEFINITIONS - Compiler switches required for using Hspell
10357 HSPELL_VERSION_STRING - The version of Hspell found (x.y)
10359 HSPELL_MAJOR_VERSION - the major version of Hspell
10360 HSPELL_MINOR_VERSION - The minor version of Hspell
10361 FindHTMLHelp
10363 This module looks for Microsoft HTML Help Compiler
10364 It defines:
10366 HTML_HELP_COMPILER : full path to the Compiler (hhc.exe)
10368 HTML_HELP_INCLUDE_PATH : include path to the API (htmlhelp.h)
10369 HTML_HELP_LIBRARY : full path to the library (htmlhelp.lib)
10370 FindIce
10372 Find the ZeroC Internet Communication Engine (ICE) programs, libraries
10373 and datafiles.
10374 This module supports multiple components. Components can include any
10376 of: Freeze, Glacier2, Ice, IceBox, IceDB, IceDiscovery, IceGrid, IceLo‐
10377 catorDiscovery, IcePatch, IceSSL, IceStorm, IceUtil, IceXML, or Slice.
10378 Ice 3.7 and later also include C++11-specific components: Glacier2++11,
10380 Ice++11, IceBox++11, IceDiscovery++11 IceGrid, IceLocatorDiscovery++11,
10381 IceSSL++11, IceStorm++11
10382 Note that the set of supported components is Ice version-specific.
10384 This module reports information about the Ice installation in several
10386 variables. General variables:
10387 Ice_VERSION - Ice release version
10389 Ice_FOUND - true if the main programs and libraries were found
10390 Ice_LIBRARIES - component libraries to be linked
10391 Ice_INCLUDE_DIRS - the directories containing the Ice headers
10392 Ice_SLICE_DIRS - the directories containing the Ice slice interface
10393 definitions
10394 Imported targets:
10396 Ice::<C>
10398 Where <C> is the name of an Ice component, for example Ice::Glacier2 or
10400 Ice++11.
10401 Ice slice programs are reported in:
10403 Ice_SLICE2CONFLUENCE_EXECUTABLE - path to slice2confluence executable
10405 Ice_SLICE2CPP_EXECUTABLE - path to slice2cpp executable
10406 Ice_SLICE2CS_EXECUTABLE - path to slice2cs executable
10407 Ice_SLICE2FREEZEJ_EXECUTABLE - path to slice2freezej executable
10408 Ice_SLICE2FREEZE_EXECUTABLE - path to slice2freeze executable
10409 Ice_SLICE2HTML_EXECUTABLE - path to slice2html executable
10410 Ice_SLICE2JAVA_EXECUTABLE - path to slice2java executable
10411 Ice_SLICE2JS_EXECUTABLE - path to slice2js executable
10412 Ice_SLICE2MATLAB_EXECUTABLE - path to slice2matlab executable
10413 Ice_SLICE2OBJC_EXECUTABLE - path to slice2objc executable
10414 Ice_SLICE2PHP_EXECUTABLE - path to slice2php executable
10415 Ice_SLICE2PY_EXECUTABLE - path to slice2py executable
10416 Ice_SLICE2RB_EXECUTABLE - path to slice2rb executable
10417 Ice programs are reported in:
10419 Ice_GLACIER2ROUTER_EXECUTABLE - path to glacier2router executable
10421 Ice_ICEBOX_EXECUTABLE - path to icebox executable
10422 Ice_ICEBOXXX11_EXECUTABLE - path to icebox++11 executable
10423 Ice_ICEBOXADMIN_EXECUTABLE - path to iceboxadmin executable
10424 Ice_ICEBOXD_EXECUTABLE - path to iceboxd executable
10425 Ice_ICEBOXNET_EXECUTABLE - path to iceboxnet executable
10426 Ice_ICEBRIDGE_EXECUTABLE - path to icebridge executable
10427 Ice_ICEGRIDADMIN_EXECUTABLE - path to icegridadmin executable
10428 Ice_ICEGRIDDB_EXECUTABLE - path to icegriddb executable
10429 Ice_ICEGRIDNODE_EXECUTABLE - path to icegridnode executable
10430 Ice_ICEGRIDNODED_EXECUTABLE - path to icegridnoded executable
10431 Ice_ICEGRIDREGISTRY_EXECUTABLE - path to icegridregistry executable
10432 Ice_ICEGRIDREGISTRYD_EXECUTABLE - path to icegridregistryd executable
10433 Ice_ICEPATCH2CALC_EXECUTABLE - path to icepatch2calc executable
10434 Ice_ICEPATCH2CLIENT_EXECUTABLE - path to icepatch2client executable
10435 Ice_ICEPATCH2SERVER_EXECUTABLE - path to icepatch2server executable
10436 Ice_ICESERVICEINSTALL_EXECUTABLE - path to iceserviceinstall executable
10437 Ice_ICESTORMADMIN_EXECUTABLE - path to icestormadmin executable
10438 Ice_ICESTORMDB_EXECUTABLE - path to icestormdb executable
10439 Ice_ICESTORMMIGRATE_EXECUTABLE - path to icestormmigrate executable
10440 Ice db programs (Windows only; standard system versions on all other
10442 platforms) are reported in:
10443 Ice_DB_ARCHIVE_EXECUTABLE - path to db_archive executable
10445 Ice_DB_CHECKPOINT_EXECUTABLE - path to db_checkpoint executable
10446 Ice_DB_DEADLOCK_EXECUTABLE - path to db_deadlock executable
10447 Ice_DB_DUMP_EXECUTABLE - path to db_dump executable
10448 Ice_DB_HOTBACKUP_EXECUTABLE - path to db_hotbackup executable
10449 Ice_DB_LOAD_EXECUTABLE - path to db_load executable
10450 Ice_DB_LOG_VERIFY_EXECUTABLE - path to db_log_verify executable
10451 Ice_DB_PRINTLOG_EXECUTABLE - path to db_printlog executable
10452 Ice_DB_RECOVER_EXECUTABLE - path to db_recover executable
10453 Ice_DB_STAT_EXECUTABLE - path to db_stat executable
10454 Ice_DB_TUNER_EXECUTABLE - path to db_tuner executable
10455 Ice_DB_UPGRADE_EXECUTABLE - path to db_upgrade executable
10456 Ice_DB_VERIFY_EXECUTABLE - path to db_verify executable
10457 Ice_DUMPDB_EXECUTABLE - path to dumpdb executable
10458 Ice_TRANSFORMDB_EXECUTABLE - path to transformdb executable
10459 Ice component libraries are reported in:
10461 Ice_<C>_FOUND - ON if component was found
10463 Ice_<C>_LIBRARIES - libraries for component
10464 Note that <C> is the uppercased name of the component.
10466 This module reads hints about search results from:
10468 Ice_HOME - the root of the Ice installation
10470 The environment variable ICE_HOME may also be used; the Ice_HOME vari‐
10472 able takes precedence.
10473 NOTE:
10475 On Windows, Ice 3.7.0 and later provide libraries via the NuGet
10476 package manager. Appropriate NuGet packages will be searched for
10477 using CMAKE_PREFIX_PATH, or alternatively Ice_HOME may be set to the
10478 location of a specific NuGet package to restrict the search.
10479 The following cache variables may also be set:
10481 Ice_<P>_EXECUTABLE - the path to executable <P>
10483 Ice_INCLUDE_DIR - the directory containing the Ice headers
10484 Ice_SLICE_DIR - the directory containing the Ice slice interface
10485 definitions
10486 Ice_<C>_LIBRARY - the library for component <C>
10487 NOTE:
10489 In most cases none of the above variables will require setting,
10490 unless multiple Ice versions are available and a specific version is
10491 required. On Windows, the most recent version of Ice will be found
10492 through the registry. On Unix, the programs, headers and libraries
10493 will usually be in standard locations, but Ice_SLICE_DIRS might not
10494 be automatically detected (commonly known locations are searched).
10495 All the other variables are defaulted using Ice_HOME, if set. It’s
10496 possible to set Ice_HOME and selectively specify alternative loca‐
10497 tions for the other components; this might be required for e.g.
10498 newer versions of Visual Studio if the heuristics are not sufficient
10499 to identify the correct programs and libraries for the specific Vis‐
10500 ual Studio version.
10501 Other variables one may set to control this module are:
10503 Ice_DEBUG - Set to ON to enable debug output from FindIce.
10505 FindIcotool
10507 Find icotool
10508 This module looks for icotool. Convert and create Win32 icon and cursor
10510 files. This module defines the following values:
10511 ICOTOOL_EXECUTABLE: the full path to the icotool tool.
10513 ICOTOOL_FOUND: True if icotool has been found.
10514 ICOTOOL_VERSION_STRING: the version of icotool found.
10515 FindICU
10517 Find the International Components for Unicode (ICU) libraries and pro‐
10518 grams.
10519 This module supports multiple components. Components can include any
10521 of: data, i18n, io, le, lx, test, tu and uc.
10522 Note that on Windows data is named dt and i18n is named in; any of the
10524 names may be used, and the appropriate platform-specific library name
10525 will be automatically selected.
10526 This module reports information about the ICU installation in several
10528 variables. General variables:
10529 ICU_VERSION - ICU release version
10531 ICU_FOUND - true if the main programs and libraries were found
10532 ICU_LIBRARIES - component libraries to be linked
10533 ICU_INCLUDE_DIRS - the directories containing the ICU headers
10534 Imported targets:
10536 ICU::<C>
10538 Where <C> is the name of an ICU component, for example ICU::i18n.
10540 ICU programs are reported in:
10542 ICU_GENCNVAL_EXECUTABLE - path to gencnval executable
10544 ICU_ICUINFO_EXECUTABLE - path to icuinfo executable
10545 ICU_GENBRK_EXECUTABLE - path to genbrk executable
10546 ICU_ICU-CONFIG_EXECUTABLE - path to icu-config executable
10547 ICU_GENRB_EXECUTABLE - path to genrb executable
10548 ICU_GENDICT_EXECUTABLE - path to gendict executable
10549 ICU_DERB_EXECUTABLE - path to derb executable
10550 ICU_PKGDATA_EXECUTABLE - path to pkgdata executable
10551 ICU_UCONV_EXECUTABLE - path to uconv executable
10552 ICU_GENCFU_EXECUTABLE - path to gencfu executable
10553 ICU_MAKECONV_EXECUTABLE - path to makeconv executable
10554 ICU_GENNORM2_EXECUTABLE - path to gennorm2 executable
10555 ICU_GENCCODE_EXECUTABLE - path to genccode executable
10556 ICU_GENSPREP_EXECUTABLE - path to gensprep executable
10557 ICU_ICUPKG_EXECUTABLE - path to icupkg executable
10558 ICU_GENCMN_EXECUTABLE - path to gencmn executable
10559 ICU component libraries are reported in:
10561 ICU_<C>_FOUND - ON if component was found
10563 ICU_<C>_LIBRARIES - libraries for component
10564 ICU datafiles are reported in:
10566 ICU_MAKEFILE_INC - Makefile.inc
10568 ICU_PKGDATA_INC - pkgdata.inc
10569 Note that <C> is the uppercased name of the component.
10571 This module reads hints about search results from:
10573 ICU_ROOT - the root of the ICU installation
10575 The environment variable ICU_ROOT may also be used; the ICU_ROOT vari‐
10577 able takes precedence.
10578 The following cache variables may also be set:
10580 ICU_<P>_EXECUTABLE - the path to executable <P>
10582 ICU_INCLUDE_DIR - the directory containing the ICU headers
10583 ICU_<C>_LIBRARY - the library for component <C>
10584 NOTE:
10586 In most cases none of the above variables will require setting,
10587 unless multiple ICU versions are available and a specific version is
10588 required.
10589 Other variables one may set to control this module are:
10591 ICU_DEBUG - Set to ON to enable debug output from FindICU.
10593 FindImageMagick
10595 Find ImageMagick binary suite.
10596 This module will search for a set of ImageMagick tools specified as
10598 components in the find_package() call. Typical components include, but
10599 are not limited to (future versions of ImageMagick might have addi‐
10600 tional components not listed here):
10601 animate
10603 compare
10604 composite
10605 conjure
10606 convert
10607 display
10608 identify
10609 import
10610 mogrify
10611 montage
10612 stream
10613 If no component is specified in the find_package() call, then it only
10615 searches for the ImageMagick executable directory. This code defines
10616 the following variables:
10617 ImageMagick_FOUND - TRUE if all components are found.
10619 ImageMagick_EXECUTABLE_DIR - Full path to executables directory.
10620 ImageMagick_<component>_FOUND - TRUE if <component> is found.
10621 ImageMagick_<component>_EXECUTABLE - Full path to <component> executable.
10622 ImageMagick_VERSION_STRING - the version of ImageMagick found
10623 (since CMake 2.8.8)
10624 ImageMagick_VERSION_STRING will not work for old versions like 5.2.3.
10626 There are also components for the following ImageMagick APIs:
10628 Magick++
10630 MagickWand
10631 MagickCore
10632 For these components the following variables are set:
10634 ImageMagick_FOUND - TRUE if all components are found.
10636 ImageMagick_INCLUDE_DIRS - Full paths to all include dirs.
10637 ImageMagick_LIBRARIES - Full paths to all libraries.
10638 ImageMagick_<component>_FOUND - TRUE if <component> is found.
10639 ImageMagick_<component>_INCLUDE_DIRS - Full path to <component> include dirs.
10640 ImageMagick_<component>_LIBRARIES - Full path to <component> libraries.
10641 Example Usages:
10643 find_package(ImageMagick)
10645 find_package(ImageMagick COMPONENTS convert)
10646 find_package(ImageMagick COMPONENTS convert mogrify display)
10647 find_package(ImageMagick COMPONENTS Magick++)
10648 find_package(ImageMagick COMPONENTS Magick++ convert)
10649 Note that the standard find_package() features are supported (i.e.,
10651 QUIET, REQUIRED, etc.).
10652 FindIconv
10654 This module finds the iconv() POSIX.1 functions on the system. These
10655 functions might be provided in the regular C library or externally in
10656 the form of an additional library.
10657 The following variables are provided to indicate iconv support:
10659 Iconv_FOUND
10661 Variable indicating if the iconv support was found.
10662 Iconv_INCLUDE_DIRS
10664 The directories containing the iconv headers.
10665 Iconv_LIBRARIES
10667 The iconv libraries to be linked.
10668 Iconv_IS_BUILT_IN
10670 A variable indicating whether iconv support is stemming from the
10671 C library or not. Even if the C library provides iconv(), the
10672 presence of an external libiconv implementation might lead to
10673 this being false.
10674 Additionally, the following IMPORTED target is being provided:
10676 Iconv::Iconv
10678 Imported target for using iconv.
10679 The following cache variables may also be set:
10681 Iconv_INCLUDE_DIR
10683 The directory containing the iconv headers.
10684 Iconv_LIBRARY
10686 The iconv library (if not implicitly given in the C library).
10687 NOTE:
10689 On POSIX platforms, iconv might be part of the C library and the
10690 cache variables Iconv_INCLUDE_DIR and Iconv_LIBRARY might be empty.
10691 FindIntl
10693 Find the Gettext libintl headers and libraries.
10694 This module reports information about the Gettext libintl installation
10696 in several variables. General variables:
10697 Intl_FOUND - true if the libintl headers and libraries were found
10699 Intl_INCLUDE_DIRS - the directory containing the libintl headers
10700 Intl_LIBRARIES - libintl libraries to be linked
10701 The following cache variables may also be set:
10703 Intl_INCLUDE_DIR - the directory containing the libintl headers
10705 Intl_LIBRARY - the libintl library (if any)
10706 NOTE:
10708 On some platforms, such as Linux with GNU libc, the gettext func‐
10709 tions are present in the C standard library and libintl is not
10710 required. Intl_LIBRARIES will be empty in this case.
10711 NOTE:
10713 If you wish to use the Gettext tools (msgmerge, msgfmt, etc.), use
10714 FindGettext.
10715 FindITK
10717 This module no longer exists.
10718 This module existed in versions of CMake prior to 3.1, but became only
10720 a thin wrapper around find_package(ITK NO_MODULE) to provide compati‐
10721 bility for projects using long-outdated conventions. Now find_pack‐
10722 age(ITK) will search for ITKConfig.cmake directly.
10723 FindJasper
10725 Try to find the Jasper JPEG2000 library
10726 Once done this will define
10728 JASPER_FOUND - system has Jasper
10730 JASPER_INCLUDE_DIR - the Jasper include directory
10731 JASPER_LIBRARIES - the libraries needed to use Jasper
10732 JASPER_VERSION_STRING - the version of Jasper found (since CMake 2.8.8)
10733 FindJava
10735 Find Java
10736 This module finds if Java is installed and determines where the include
10738 files and libraries are. The caller may set variable JAVA_HOME to
10739 specify a Java installation prefix explicitly.
10740 See also the FindJNI module to find Java Native Interface (JNI).
10742 Specify one or more of the following components as you call this find
10744 module. See example below.
10745 Runtime = Java Runtime Environment used to execute Java byte-compiled applications
10747 Development = Development tools (java, javac, javah, jar and javadoc), includes Runtime component
10748 IdlJ = Interface Description Language (IDL) to Java compiler
10749 JarSigner = Signer and verifier tool for Java Archive (JAR) files
10750 This module sets the following result variables:
10752 Java_JAVA_EXECUTABLE = the full path to the Java runtime
10754 Java_JAVAC_EXECUTABLE = the full path to the Java compiler
10755 Java_JAVAH_EXECUTABLE = the full path to the Java header generator
10756 Java_JAVADOC_EXECUTABLE = the full path to the Java documentation generator
10757 Java_IDLJ_EXECUTABLE = the full path to the Java idl compiler
10758 Java_JAR_EXECUTABLE = the full path to the Java archiver
10759 Java_JARSIGNER_EXECUTABLE = the full path to the Java jar signer
10760 Java_VERSION_STRING = Version of java found, eg. 1.6.0_12
10761 Java_VERSION_MAJOR = The major version of the package found.
10762 Java_VERSION_MINOR = The minor version of the package found.
10763 Java_VERSION_PATCH = The patch version of the package found.
10764 Java_VERSION_TWEAK = The tweak version of the package found (after '_')
10765 Java_VERSION = This is set to: $major[.$minor[.$patch[.$tweak]]]
10766 The minimum required version of Java can be specified using the
10768 find_package() syntax, e.g.
10769 find_package(Java 1.8)
10771 NOTE: ${Java_VERSION} and ${Java_VERSION_STRING} are not guaranteed to
10773 be identical. For example some java version may return: Java_VER‐
10774 SION_STRING = 1.8.0_17 and Java_VERSION = 1.8.0.17
10775 another example is the Java OEM, with: Java_VERSION_STRING = 1.8.0-oem
10777 and Java_VERSION = 1.8.0
10778 For these components the following variables are set:
10780 Java_FOUND - TRUE if all components are found.
10782 Java_<component>_FOUND - TRUE if <component> is found.
10783 Example Usages:
10785 find_package(Java)
10787 find_package(Java 1.8 REQUIRED)
10788 find_package(Java COMPONENTS Runtime)
10789 find_package(Java COMPONENTS Development)
10790 FindJNI
10792 Find Java Native Interface (JNI) libraries.
10793 JNI enables Java code running in a Java Virtual Machine (JVM) to call
10795 and be called by native applications and libraries written in other
10796 languages such as C, C++.
10797 This module finds if Java is installed and determines where the include
10799 files and libraries are. It also determines what the name of the
10800 library is. The caller may set variable JAVA_HOME to specify a Java
10801 installation prefix explicitly.
10802 Result Variables
10804 This module sets the following result variables:
10805 JNI_INCLUDE_DIRS
10807 the include dirs to use
10808 JNI_LIBRARIES
10810 the libraries to use (JAWT and JVM)
10811 JNI_FOUND
10813 TRUE if JNI headers and libraries were found.
10814 Cache Variables
10816 The following cache variables are also available to set or use:
10817 JAVA_AWT_LIBRARY
10819 the path to the Java AWT Native Interface (JAWT) library
10820 JAVA_JVM_LIBRARY
10822 the path to the Java Virtual Machine (JVM) library
10823 JAVA_INCLUDE_PATH
10825 the include path to jni.h
10826 JAVA_INCLUDE_PATH2
10828 the include path to jni_md.h and jniport.h
10829 JAVA_AWT_INCLUDE_PATH
10831 the include path to jawt.h
10832 FindJPEG
10834 Find the Joint Photographic Experts Group (JPEG) library (libjpeg)
10835 Imported targets
10837 This module defines the following IMPORTED targets:
10838 JPEG::JPEG
10840 The JPEG library, if found.
10841 Result variables
10843 This module will set the following variables in your project:
10844 JPEG_FOUND
10846 If false, do not try to use JPEG.
10847 JPEG_INCLUDE_DIRS
10849 where to find jpeglib.h, etc.
10850 JPEG_LIBRARIES
10852 the libraries needed to use JPEG.
10853 JPEG_VERSION
10855 the version of the JPEG library found
10856 Cache variables
10858 The following cache variables may also be set:
10859 JPEG_INCLUDE_DIRS
10861 where to find jpeglib.h, etc.
10862 JPEG_LIBRARY_RELEASE
10864 where to find the JPEG library (optimized).
10865 JPEG_LIBRARY_DEBUG
10867 where to find the JPEG library (debug).
10868 Obsolete variables
10870 JPEG_INCLUDE_DIR
10871 where to find jpeglib.h, etc. (same as JPEG_INCLUDE_DIRS)
10872 JPEG_LIBRARY
10874 where to find the JPEG library.
10875 FindKDE3
10877 Find the KDE3 include and library dirs, KDE preprocessors and define a
10878 some macros
10879 This module defines the following variables:
10881 KDE3_DEFINITIONS
10883 compiler definitions required for compiling KDE software
10884 KDE3_INCLUDE_DIR
10886 the KDE include directory
10887 KDE3_INCLUDE_DIRS
10889 the KDE and the Qt include directory, for use with
10890 include_directories()
10891 KDE3_LIB_DIR
10893 the directory where the KDE libraries are installed, for use
10894 with link_directories()
10895 QT_AND_KDECORE_LIBS
10897 this contains both the Qt and the kdecore library
10898 KDE3_DCOPIDL_EXECUTABLE
10900 the dcopidl executable
10901 KDE3_DCOPIDL2CPP_EXECUTABLE
10903 the dcopidl2cpp executable
10904 KDE3_KCFGC_EXECUTABLE
10906 the kconfig_compiler executable
10907 KDE3_FOUND
10909 set to TRUE if all of the above has been found
10910 The following user adjustable options are provided:
10912 KDE3_BUILD_TESTS
10914 enable this to build KDE testcases
10915 It also adds the following macros (from KDE3Macros.cmake) SRCS_VAR is
10917 always the variable which contains the list of source files for your
10918 application or library.
10919 KDE3_AUTOMOC(file1 … fileN)
10921 Call this if you want to have automatic moc file handling.
10923 This means if you include "foo.moc" in the source file foo.cpp
10924 a moc file for the header foo.h will be created automatically.
10925 You can set the property SKIP_AUTOMAKE using set_source_files_properties()
10926 to exclude some files in the list from being processed.
10927 KDE3_ADD_MOC_FILES(SRCS_VAR file1 … fileN )
10929 If you don't use the KDE3_AUTOMOC() macro, for the files
10931 listed here moc files will be created (named "foo.moc.cpp")
10932 KDE3_ADD_DCOP_SKELS(SRCS_VAR header1.h … headerN.h )
10934 Use this to generate DCOP skeletions from the listed headers.
10936 KDE3_ADD_DCOP_STUBS(SRCS_VAR header1.h … headerN.h )
10938 Use this to generate DCOP stubs from the listed headers.
10940 KDE3_ADD_UI_FILES(SRCS_VAR file1.ui … fileN.ui )
10942 Use this to add the Qt designer ui files to your application/library.
10944 KDE3_ADD_KCFG_FILES(SRCS_VAR file1.kcfgc … fileN.kcfgc )
10946 Use this to add KDE kconfig compiler files to your application/library.
10948 KDE3_INSTALL_LIBTOOL_FILE(target)
10950 This will create and install a simple libtool file for the given target.
10952 KDE3_ADD_EXECUTABLE(name file1 … fileN )
10954 Currently identical to add_executable(), may provide some advanced
10956 features in the future.
10957 KDE3_ADD_KPART(name [WITH_PREFIX] file1 … fileN )
10959 Create a KDE plugin (KPart, kioslave, etc.) from the given source files.
10961 If WITH_PREFIX is given, the resulting plugin will have the prefix "lib",
10962 otherwise it won't.
10963 It creates and installs an appropriate libtool la-file.
10964 KDE3_ADD_KDEINIT_EXECUTABLE(name file1 … fileN )
10966 Create a KDE application in the form of a module loadable via kdeinit.
10968 A library named kdeinit_<name> will be created and a small executable
10969 which links to it.
10970 The option KDE3_ENABLE_FINAL to enable all-in-one compilation is no
10972 longer supported.
10973 Author: Alexander Neundorf <neundorf@kde.org>
10975 FindKDE4
10977 Find KDE4 and provide all necessary variables and macros to compile
10978 software for it. It looks for KDE 4 in the following directories in
10979 the given order:
10980 CMAKE_INSTALL_PREFIX
10982 KDEDIRS
10983 /opt/kde4
10984 Please look in FindKDE4Internal.cmake and KDE4Macros.cmake for more
10986 information. They are installed with the KDE 4 libraries in
10987 $KDEDIRS/share/apps/cmake/modules/.
10988 Author: Alexander Neundorf <neundorf@kde.org>
10990 FindLAPACK
10992 Find Linear Algebra PACKage (LAPACK) library
10993 This module finds an installed Fortran library that implements the
10995 LAPACK linear-algebra interface (see http://www.netlib.org/lapack/).
10996 The approach follows that taken for the autoconf macro file,
10998 acx_lapack.m4 (distributed at
10999 http://ac-archive.sourceforge.net/ac-archive/acx_lapack.html).
11000 Input Variables
11002 The following variables may be set to influence this module’s behavior:
11003 BLA_STATIC
11005 if ON use static linkage
11006 BLA_VENDOR
11008 If set, checks only the specified vendor, if not set checks all
11009 the possibilities. List of vendors valid in this module:
11010 · OpenBLAS
11012 · FLAME
11014 · Intel10_32 (intel mkl v10 32 bit)
11016 · Intel10_64lp (intel mkl v10+ 64 bit, threaded code, lp64
11018 model)
11019 · Intel10_64lp_seq (intel mkl v10+ 64 bit, sequential code, lp64
11021 model)
11022 · Intel10_64ilp (intel mkl v10+ 64 bit, threaded code, ilp64
11024 model)
11025 · Intel10_64ilp_seq (intel mkl v10+ 64 bit, sequential code,
11027 ilp64 model)
11028 · Intel10_64_dyn (intel mkl v10+ 64 bit, single dynamic library)
11030 · Intel (obsolete versions of mkl 32 and 64 bit)
11032 · ACML
11034 · Apple
11036 · NAS
11038 · Generic
11040 BLA_F95
11042 if ON tries to find the BLAS95/LAPACK95 interfaces
11043 Result Variables
11045 This module defines the following variables:
11046 LAPACK_FOUND
11048 library implementing the LAPACK interface is found
11049 LAPACK_LINKER_FLAGS
11051 uncached list of required linker flags (excluding -l and -L).
11052 LAPACK_LIBRARIES
11054 uncached list of libraries (using full path name) to link
11055 against to use LAPACK
11056 LAPACK95_LIBRARIES
11058 uncached list of libraries (using full path name) to link
11059 against to use LAPACK95
11060 LAPACK95_FOUND
11062 library implementing the LAPACK95 interface is found
11063 NOTE:
11065 C, CXX or Fortran must be enabled to detect a BLAS/LAPACK library.
11066 C or CXX must be enabled to use Intel Math Kernel Library (MKL).
11067 For example, to use Intel MKL libraries and/or Intel compiler:
11069 set(BLA_VENDOR Intel10_64lp)
11071 find_package(LAPACK)
11072 FindLATEX
11074 Find LaTeX
11075 This module finds an installed LaTeX and determines the location of the
11077 compiler. Additionally the module looks for Latex-related software
11078 like BibTeX.
11079 This module sets the following result variables:
11081 LATEX_FOUND: whether found Latex and requested components
11083 LATEX_<component>_FOUND: whether found <component>
11084 LATEX_COMPILER: path to the LaTeX compiler
11085 PDFLATEX_COMPILER: path to the PdfLaTeX compiler
11086 XELATEX_COMPILER: path to the XeLaTeX compiler
11087 LUALATEX_COMPILER: path to the LuaLaTeX compiler
11088 BIBTEX_COMPILER: path to the BibTeX compiler
11089 BIBER_COMPILER: path to the Biber compiler
11090 MAKEINDEX_COMPILER: path to the MakeIndex compiler
11091 XINDY_COMPILER: path to the xindy compiler
11092 DVIPS_CONVERTER: path to the DVIPS converter
11093 DVIPDF_CONVERTER: path to the DVIPDF converter
11094 PS2PDF_CONVERTER: path to the PS2PDF converter
11095 PDFTOPS_CONVERTER: path to the pdftops converter
11096 LATEX2HTML_CONVERTER: path to the LaTeX2Html converter
11097 HTLATEX_COMPILER: path to the htlatex compiler
11098 Possible components are:
11100 PDFLATEX
11102 XELATEX
11103 LUALATEX
11104 BIBTEX
11105 BIBER
11106 MAKEINDEX
11107 XINDY
11108 DVIPS
11109 DVIPDF
11110 PS2PDF
11111 PDFTOPS
11112 LATEX2HTML
11113 HTLATEX
11114 Example Usages:
11116 find_package(LATEX)
11118 find_package(LATEX COMPONENTS PDFLATEX)
11119 find_package(LATEX COMPONENTS BIBTEX PS2PDF)
11120 FindLibArchive
11122 Find libarchive library and headers. Libarchive is multi-format ar‐
11123 chive and compression library.
11124 The module defines the following variables:
11126 LibArchive_FOUND - true if libarchive was found
11128 LibArchive_INCLUDE_DIRS - include search path
11129 LibArchive_LIBRARIES - libraries to link
11130 LibArchive_VERSION - libarchive 3-component version number
11131 The module defines the following IMPORTED targets:
11133 LibArchive::LibArchive - target for linking against libarchive
11135 FindLibinput
11137 Find libinput headers and library.
11138 Imported Targets
11140 Libinput::Libinput
11141 The libinput library, if found.
11142 Result Variables
11144 This will define the following variables in your project:
11145 Libinput_FOUND
11147 true if (the requested version of) libinput is available.
11148 Libinput_VERSION
11150 the version of libinput.
11151 Libinput_LIBRARIES
11153 the libraries to link against to use libinput.
11154 Libinput_INCLUDE_DIRS
11156 where to find the libinput headers.
11157 Libinput_COMPILE_OPTIONS
11159 this should be passed to target_compile_options(), if the target
11160 is not used for linking
11161 FindLibLZMA
11163 Find LZMA compression algorithm headers and library.
11164 Imported Targets
11166 This module defines IMPORTED target LibLZMA::LibLZMA, if liblzma has
11167 been found.
11168 Result variables
11170 This module will set the following variables in your project:
11171 LIBLZMA_FOUND
11173 True if liblzma headers and library were found.
11174 LIBLZMA_INCLUDE_DIRS
11176 Directory where liblzma headers are located.
11177 LIBLZMA_LIBRARIES
11179 Lzma libraries to link against.
11180 LIBLZMA_HAS_AUTO_DECODER
11182 True if lzma_auto_decoder() is found (required).
11183 LIBLZMA_HAS_EASY_ENCODER
11185 True if lzma_easy_encoder() is found (required).
11186 LIBLZMA_HAS_LZMA_PRESET
11188 True if lzma_lzma_preset() is found (required).
11189 LIBLZMA_VERSION_MAJOR
11191 The major version of lzma
11192 LIBLZMA_VERSION_MINOR
11194 The minor version of lzma
11195 LIBLZMA_VERSION_PATCH
11197 The patch version of lzma
11198 LIBLZMA_VERSION_STRING
11200 version number as a string (ex: “5.0.3”)
11201 FindLibXml2
11203 Find the XML processing library (libxml2).
11204 IMPORTED Targets
11206 The following IMPORTED targets may be defined:
11207 LibXml2::LibXml2
11209 If the libxml2 library has been found
11210 LibXml2::xmllint
11212 If the xmllint command-line executable has been found
11213 Result variables
11215 This module will set the following variables in your project:
11216 LibXml2_FOUND
11218 true if libxml2 headers and libraries were found
11219 LIBXML2_INCLUDE_DIR
11221 the directory containing LibXml2 headers
11222 LIBXML2_INCLUDE_DIRS
11224 list of the include directories needed to use LibXml2
11225 LIBXML2_LIBRARIES
11227 LibXml2 libraries to be linked
11228 LIBXML2_DEFINITIONS
11230 the compiler switches required for using LibXml2
11231 LIBXML2_XMLLINT_EXECUTABLE
11233 path to the XML checking tool xmllint coming with LibXml2
11234 LIBXML2_VERSION_STRING
11236 the version of LibXml2 found (since CMake 2.8.8)
11237 Cache variables
11239 The following cache variables may also be set:
11240 LIBXML2_INCLUDE_DIR
11242 the directory containing LibXml2 headers
11243 LIBXML2_LIBRARY
11245 path to the LibXml2 library
11246 FindLibXslt
11248 Find the XSL Transformations, Extensible Stylesheet Language Transfor‐
11249 mations (XSLT) library (LibXslt)
11250 Once done this will define
11252 LIBXSLT_FOUND - system has LibXslt
11254 LIBXSLT_INCLUDE_DIR - the LibXslt include directory
11255 LIBXSLT_LIBRARIES - Link these to LibXslt
11256 LIBXSLT_DEFINITIONS - Compiler switches required for using LibXslt
11257 LIBXSLT_VERSION_STRING - version of LibXslt found (since CMake 2.8.8)
11258 Additionally, the following two variables are set (but not required for
11260 using xslt):
11261 LIBXSLT_EXSLT_LIBRARIES
11263 Link to these if you need to link against the exslt library.
11264 LIBXSLT_XSLTPROC_EXECUTABLE
11266 Contains the full path to the xsltproc executable if found.
11267 FindLTTngUST
11269 Find Linux Trace Toolkit Next Generation (LTTng-UST) library.
11270 Imported target
11272 This module defines the following IMPORTED target:
11273 LTTng::UST
11275 The LTTng-UST library, if found
11276 Result variables
11278 This module sets the following
11279 LTTNGUST_FOUND
11281 TRUE if system has LTTng-UST
11282 LTTNGUST_INCLUDE_DIRS
11284 The LTTng-UST include directories
11285 LTTNGUST_LIBRARIES
11287 The libraries needed to use LTTng-UST
11288 LTTNGUST_VERSION_STRING
11290 The LTTng-UST version
11291 LTTNGUST_HAS_TRACEF
11293 TRUE if the tracef() API is available in the system’s LTTng-UST
11294 LTTNGUST_HAS_TRACELOG
11296 TRUE if the tracelog() API is available in the system’s
11297 LTTng-UST
11298 FindLua50
11300 Locate Lua library. This module defines:
11301 ::
11303 LUA50_FOUND, if false, do not try to link to Lua LUA_LIBRARIES, both
11304 lua and lualib LUA_INCLUDE_DIR, where to find lua.h and lualib.h
11305 (and probably lauxlib.h)
11306 Note that the expected include convention is
11308 #include "lua.h"
11310 and not
11312 #include <lua/lua.h>
11314 This is because, the lua location is not standardized and may exist in
11316 locations other than lua/
11317 FindLua51
11319 Locate Lua library. This module defines:
11320 ::
11322 LUA51_FOUND, if false, do not try to link to Lua LUA_LIBRARIES
11323 LUA_INCLUDE_DIR, where to find lua.h LUA_VERSION_STRING, the version
11324 of Lua found (since CMake 2.8.8)
11325 Note that the expected include convention is
11327 #include "lua.h"
11329 and not
11331 #include <lua/lua.h>
11333 This is because, the lua location is not standardized and may exist in
11335 locations other than lua/
11336 FindLua
11338 Locate Lua library.
11339 This module defines:
11341 ::
11343 LUA_FOUND - if false, do not try to link to Lua
11344 LUA_LIBRARIES - both lua and lualib LUA_INCLUDE_DIR - where
11345 to find lua.h LUA_VERSION_STRING - the version of Lua found LUA_VER‐
11346 SION_MAJOR - the major version of Lua LUA_VERSION_MINOR - the
11347 minor version of Lua LUA_VERSION_PATCH - the patch version of Lua
11348 Note that the expected include convention is
11350 #include "lua.h"
11352 and not
11354 #include <lua/lua.h>
11356 This is because, the lua location is not standardized and may exist in
11358 locations other than lua/
11359 FindMatlab
11361 Finds Matlab or Matlab Compiler Runtime (MCR) and provides Matlab
11362 tools, libraries and compilers to CMake.
11363 This package primary purpose is to find the libraries associated with
11365 Matlab or the MCR in order to be able to build Matlab extensions (mex
11366 files). It can also be used:
11367 · to run specific commands in Matlab in case Matlab is available
11369 · for declaring Matlab unit test
11371 · to retrieve various information from Matlab (mex extensions, versions
11373 and release queries, …)
11374 The module supports the following components:
11376 · ENG_LIBRARY and MAT_LIBRARY: respectively the ENG and MAT libraries
11378 of Matlab
11379 · MAIN_PROGRAM the Matlab binary program. Note that this component is
11381 not available on the MCR version, and will yield an error if the MCR
11382 is found instead of the regular Matlab installation.
11383 · MEX_COMPILER the MEX compiler.
11385 · MCC_COMPILER the MCC compiler, included with the Matlab Compiler
11387 add-on.
11388 · SIMULINK the Simulink environment.
11390 NOTE:
11392 The version given to the find_package() directive is the Matlab ver‐
11393 sion, which should not be confused with the Matlab release name (eg.
11394 R2014). The matlab_get_version_from_release_name() and
11395 matlab_get_release_name_from_version() provide a mapping between the
11396 release name and the version.
11397 The variable Matlab_ROOT_DIR may be specified in order to give the path
11399 of the desired Matlab version. Otherwise, the behaviour is platform
11400 specific:
11401 · Windows: The installed versions of Matlab/MCR are retrieved from the
11403 Windows registry
11404 · OS X: The installed versions of Matlab/MCR are given by the MATLAB
11406 default installation paths in /Application. If no such application is
11407 found, it falls back to the one that might be accessible from the
11408 PATH.
11409 · Unix: The desired Matlab should be accessible from the PATH. This
11411 does not work for MCR installation and Matlab_ROOT_DIR should be
11412 specified on this platform.
11413 Additional information is provided when MATLAB_FIND_DEBUG is set. When
11415 a Matlab/MCR installation is found automatically and the MATLAB_VERSION
11416 is not given, the version is queried from Matlab directly (on Windows
11417 this may pop up a Matlab window) or from the MCR installation.
11418 The mapping of the release names and the version of Matlab is performed
11420 by defining pairs (name, version). The variable
11421 MATLAB_ADDITIONAL_VERSIONS may be provided before the call to the
11422 find_package() in order to handle additional versions.
11423 A Matlab scripts can be added to the set of tests using the
11425 matlab_add_unit_test(). By default, the Matlab unit test framework will
11426 be used (>= 2013a) to run this script, but regular .m files returning
11427 an exit code can be used as well (0 indicating a success).
11428 Module Input Variables
11430 Users or projects may set the following variables to configure the mod‐
11431 ule behaviour:
11432 Matlab_ROOT_DIR
11434 the root of the Matlab installation.
11435 MATLAB_FIND_DEBUG
11437 outputs debug information
11438 MATLAB_ADDITIONAL_VERSIONS
11440 additional versions of Matlab for the automatic retrieval of the
11441 installed versions.
11442 Variables defined by the module
11444 Result variables
11445 Matlab_FOUND
11446 TRUE if the Matlab installation is found, FALSE otherwise. All
11447 variable below are defined if Matlab is found.
11448 Matlab_ROOT_DIR
11450 the final root of the Matlab installation determined by the
11451 FindMatlab module.
11452 Matlab_MAIN_PROGRAM
11454 the Matlab binary program. Available only if the component
11455 MAIN_PROGRAM is given in the find_package() directive.
11456 Matlab_INCLUDE_DIRS
11458 the path of the Matlab libraries headers
11459 Matlab_MEX_LIBRARY
11461 library for mex, always available.
11462 Matlab_MX_LIBRARY
11464 mx library of Matlab (arrays), always available.
11465 Matlab_ENG_LIBRARY
11467 Matlab engine library. Available only if the component
11468 ENG_LIBRARY is requested.
11469 Matlab_MAT_LIBRARY
11471 Matlab matrix library. Available only if the component
11472 MAT_LIBRARY is requested.
11473 Matlab_ENGINE_LIBRARY
11475 Matlab C++ engine library, always available for R2018a and
11476 newer.
11477 Matlab_DATAARRAY_LIBRARY
11479 Matlab C++ data array library, always available for R2018a and
11480 newer.
11481 Matlab_LIBRARIES
11483 the whole set of libraries of Matlab
11484 Matlab_MEX_COMPILER
11486 the mex compiler of Matlab. Currently not used. Available only
11487 if the component MEX_COMPILER is requested.
11488 Matlab_MCC_COMPILER
11490 the mcc compiler of Matlab. Included with the Matlab Compiler
11491 add-on. Available only if the component MCC_COMPILER is
11492 requested.
11493 Cached variables
11495 Matlab_MEX_EXTENSION
11496 the extension of the mex files for the current platform (given
11497 by Matlab).
11498 Matlab_ROOT_DIR
11500 the location of the root of the Matlab installation found. If
11501 this value is changed by the user, the result variables are
11502 recomputed.
11503 Provided macros
11505 matlab_get_version_from_release_name()
11506 returns the version from the release name
11507 matlab_get_release_name_from_version()
11509 returns the release name from the Matlab version
11510 Provided functions
11512 matlab_add_mex()
11513 adds a target compiling a MEX file.
11514 matlab_add_unit_test()
11516 adds a Matlab unit test file as a test to the project.
11517 matlab_extract_all_installed_versions_from_registry()
11519 parses the registry for all Matlab versions. Available on Win‐
11520 dows only. The part of the registry parsed is dependent on the
11521 host processor
11522 matlab_get_all_valid_matlab_roots_from_registry()
11524 returns all the possible Matlab or MCR paths, according to a
11525 previously given list. Only the existing/accessible paths are
11526 kept. This is mainly useful for the searching all possible Mat‐
11527 lab installation.
11528 matlab_get_mex_suffix()
11530 returns the suffix to be used for the mex files (platform/archi‐
11531 tecture dependent)
11532 matlab_get_version_from_matlab_run()
11534 returns the version of Matlab/MCR, given the full directory of
11535 the Matlab/MCR installation path.
11536 Known issues
11538 Symbol clash in a MEX target
11539 By default, every symbols inside a MEX file defined with the
11540 command matlab_add_mex() have hidden visibility, except for the
11541 entry point. This is the default behaviour of the MEX compiler,
11542 which lowers the risk of symbol collision between the libraries
11543 shipped with Matlab, and the libraries to which the MEX file is
11544 linking to. This is also the default on Windows platforms.
11545 However, this is not sufficient in certain case, where for
11547 instance your MEX file is linking against libraries that are
11548 already loaded by Matlab, even if those libraries have different
11549 SONAMES. A possible solution is to hide the symbols of the
11550 libraries to which the MEX target is linking to. This can be
11551 achieved in GNU GCC compilers with the linker option
11552 -Wl,--exclude-libs,ALL.
11553 Tests using GPU resources
11555 in case your MEX file is using the GPU and in order to be able
11556 to run unit tests on this MEX file, the GPU resources should be
11557 properly released by Matlab. A possible solution is to make Mat‐
11558 lab aware of the use of the GPU resources in the session, which
11559 can be performed by a command such as D = gpuDevice() at the
11560 beginning of the test script (or via a fixture).
11561 Reference
11563 Matlab_ROOT_DIR
11564 The root folder of the Matlab installation. If set before the
11565 call to find_package(), the module will look for the components
11566 in that path. If not set, then an automatic search of Matlab
11567 will be performed. If set, it should point to a valid version of
11568 Matlab.
11569 MATLAB_FIND_DEBUG
11571 If set, the lookup of Matlab and the intermediate configuration
11572 steps are outputted to the console.
11573 MATLAB_ADDITIONAL_VERSIONS
11575 If set, specifies additional versions of Matlab that may be
11576 looked for. The variable should be a list of strings, organised
11577 by pairs of release name and versions, such as follows:
11578 set(MATLAB_ADDITIONAL_VERSIONS
11580 "release_name1=corresponding_version1"
11581 "release_name2=corresponding_version2"
11582 ...
11583 )
11584 Example:
11586 set(MATLAB_ADDITIONAL_VERSIONS
11588 "R2013b=8.2"
11589 "R2013a=8.1"
11590 "R2012b=8.0")
11591 The order of entries in this list matters when several versions
11593 of Matlab are installed. The priority is set according to the
11594 ordering in this list.
11595 matlab_get_version_from_release_name
11597 Returns the version of Matlab (17.58) from a release name
11598 (R2017k)
11599 matlab_get_release_name_from_version
11601 Returns the release name (R2017k) from the version of Matlab
11602 (17.58)
11603 matlab_extract_all_installed_versions_from_registry
11605 This function parses the registry and founds the Matlab versions
11606 that are installed. The found versions are returned in mat‐
11607 lab_versions. Set win64 to TRUE if the 64 bit version of Matlab
11608 should be looked for The returned list contains all versions
11609 under HKLM\\SOFTWARE\\Mathworks\\MATLAB and HKLM\\SOFT‐
11610 WARE\\Mathworks\\MATLAB Runtime or an empty list in case an
11611 error occurred (or nothing found).
11612 NOTE:
11614 Only the versions are provided. No check is made over the
11615 existence of the installation referenced in the registry,
11616 matlab_get_all_valid_matlab_roots_from_registry
11618 Populates the Matlab root with valid versions of Matlab or Mat‐
11619 lab Runtime (MCR). The returned matlab_roots is organized in
11620 triplets (type,version_number,matlab_root_path), where type
11621 indicates either MATLAB or MCR.
11622 matlab_get_all_valid_matlab_roots_from_registry(
11624 matlab_versions
11625 matlab_roots)
11626 matlab_versions
11628 the versions of each of the Matlab or MCR installations
11629 matlab_roots
11631 the location of each of the Matlab or MCR installations
11632 matlab_get_mex_suffix
11634 Returns the extension of the mex files (the suffixes). This
11635 function should not be called before the appropriate Matlab root
11636 has been found.
11637 matlab_get_mex_suffix(
11639 matlab_root
11640 mex_suffix)
11641 matlab_root
11643 the root of the Matlab/MCR installation
11644 mex_suffix
11646 the variable name in which the suffix will be returned.
11647 matlab_get_version_from_matlab_run
11649 This function runs Matlab program specified on arguments and
11650 extracts its version. If the path provided for the Matlab
11651 installation points to an MCR installation, the version is
11652 extracted from the installed files.
11653 matlab_get_version_from_matlab_run(
11655 matlab_binary_path
11656 matlab_list_versions)
11657 matlab_binary_path
11659 the location of the matlab binary executable
11660 matlab_list_versions
11662 the version extracted from Matlab
11663 matlab_add_unit_test
11665 Adds a Matlab unit test to the test set of cmake/ctest. This
11666 command requires the component MAIN_PROGRAM and hence is not
11667 available for an MCR installation.
11668 The unit test uses the Matlab unittest framework (default,
11670 available starting Matlab 2013b+) except if the option
11671 NO_UNITTEST_FRAMEWORK is given.
11672 The function expects one Matlab test script file to be given.
11674 In the case NO_UNITTEST_FRAMEWORK is given, the unittest script
11675 file should contain the script to be run, plus an exit command
11676 with the exit value. This exit value will be passed to the ctest
11677 framework (0 success, non 0 failure). Additional arguments
11678 accepted by add_test() can be passed through TEST_ARGS (eg. CON‐
11679 FIGURATION <config> ...).
11680 matlab_add_unit_test(
11682 NAME <name>
11683 UNITTEST_FILE matlab_file_containing_unittest.m
11684 [CUSTOM_TEST_COMMAND matlab_command_to_run_as_test]
11685 [UNITTEST_PRECOMMAND matlab_command_to_run]
11686 [TIMEOUT timeout]
11687 [ADDITIONAL_PATH path1 [path2 ...]]
11688 [MATLAB_ADDITIONAL_STARTUP_OPTIONS option1 [option2 ...]]
11689 [TEST_ARGS arg1 [arg2 ...]]
11690 [NO_UNITTEST_FRAMEWORK]
11691 )
11692 The function arguments are:
11694 NAME name of the unittest in ctest.
11696 UNITTEST_FILE
11698 the matlab unittest file. Its path will be automatically
11699 added to the Matlab path.
11700 CUSTOM_TEST_COMMAND
11702 Matlab script command to run as the test. If this is not
11703 set, then the following is run: runtests('mat‐
11704 lab_file_name'), exit(max([ans(1,:).Failed])) where mat‐
11705 lab_file_name is the UNITTEST_FILE without the extension.
11706 UNITTEST_PRECOMMAND
11708 Matlab script command to be ran before the file contain‐
11709 ing the test (eg. GPU device initialisation based on
11710 CMake variables).
11711 TIMEOUT
11713 the test timeout in seconds. Defaults to 180 seconds as
11714 the Matlab unit test may hang.
11715 ADDITIONAL_PATH
11717 a list of paths to add to the Matlab path prior to run‐
11718 ning the unit test.
11719 MATLAB_ADDITIONAL_STARTUP_OPTIONS
11721 a list of additional option in order to run Matlab from
11722 the command line. -nosplash -nodesktop -nodisplay are
11723 always added.
11724 TEST_ARGS
11726 Additional options provided to the add_test command.
11727 These options are added to the default options (eg. “CON‐
11728 FIGURATIONS Release”)
11729 NO_UNITTEST_FRAMEWORK
11731 when set, indicates that the test should not use the
11732 unittest framework of Matlab (available for versions >=
11733 R2013a).
11734 WORKING_DIRECTORY
11736 This will be the working directory for the test. If spec‐
11737 ified it will also be the output directory used for the
11738 log file of the test run. If not specified the temporary
11739 directory ${CMAKE_BINARY_DIR}/Matlab will be used as the
11740 working directory and the log location.
11741 matlab_add_mex
11743 Adds a Matlab MEX target. This commands compiles the given
11744 sources with the current tool-chain in order to produce a MEX
11745 file. The final name of the produced output may be specified, as
11746 well as additional link libraries, and a documentation entry for
11747 the MEX file. Remaining arguments of the call are passed to the
11748 add_library() or add_executable() command.
11749 matlab_add_mex(
11751 NAME <name>
11752 [EXECUTABLE | MODULE | SHARED]
11753 SRC src1 [src2 ...]
11754 [OUTPUT_NAME output_name]
11755 [DOCUMENTATION file.txt]
11756 [LINK_TO target1 target2 ...]
11757 [R2017b | R2018a]
11758 [EXCLUDE_FROM_ALL]
11759 [...]
11760 )
11761 NAME name of the target.
11763 SRC list of source files.
11765 LINK_TO
11767 a list of additional link dependencies. The target links
11768 to libmex and libmx by default.
11769 OUTPUT_NAME
11771 if given, overrides the default name. The default name is
11772 the name of the target without any prefix and with Mat‐
11773 lab_MEX_EXTENSION suffix.
11774 DOCUMENTATION
11776 if given, the file file.txt will be considered as being
11777 the documentation file for the MEX file. This file is
11778 copied into the same folder without any processing, with
11779 the same name as the final mex file, and with extension
11780 .m. In that case, typing help <name> in Matlab prints the
11781 documentation contained in this file.
11782 R2017b or R2018a may be given to specify the version of the C
11784 API
11785 to use: R2017b specifies the traditional (separate com‐
11786 plex) C API, and corresponds to the -R2017b flag for the
11787 mex command. R2018a specifies the new interleaved complex
11788 C API, and corresponds to the -R2018a flag for the mex
11789 command. Ignored if MATLAB version prior to R2018a.
11790 Defaults to R2017b.
11791 MODULE or SHARED may be given to specify the type of library to
11793 be
11794 created. EXECUTABLE may be given to create an executable
11795 instead of a library. If no type is given explicitly, the
11796 type is SHARED.
11797 EXCLUDE_FROM_ALL
11799 This option has the same meaning as for EXCLUDE_FROM_ALL
11800 and is forwarded to add_library() or add_executable()
11801 commands.
11802 The documentation file is not processed and should be in the
11804 following format:
11805 % This is the documentation
11807 function ret = mex_target_output_name(input1)
11808 FindMFC
11810 Find Microsoft Foundation Class Library (MFC) on Windows
11811 Find the native MFC - i.e. decide if an application can link to the
11813 MFC libraries.
11814 MFC_FOUND - Was MFC support found
11816 You don’t need to include anything or link anything to use it.
11818 FindMotif
11820 Try to find Motif (or lesstif)
11821 Once done this will define:
11823 MOTIF_FOUND - system has MOTIF
11825 MOTIF_INCLUDE_DIR - include paths to use Motif
11826 MOTIF_LIBRARIES - Link these to use Motif
11827 FindMPEG2
11829 Find the native MPEG2 includes and library
11830 This module defines
11832 MPEG2_INCLUDE_DIR, path to mpeg2dec/mpeg2.h, etc.
11834 MPEG2_LIBRARIES, the libraries required to use MPEG2.
11835 MPEG2_FOUND, If false, do not try to use MPEG2.
11836 also defined, but not for general use are
11838 MPEG2_mpeg2_LIBRARY, where to find the MPEG2 library.
11840 MPEG2_vo_LIBRARY, where to find the vo library.
11841 FindMPEG
11843 Find the native MPEG includes and library
11844 This module defines
11846 MPEG_INCLUDE_DIR, where to find MPEG.h, etc.
11848 MPEG_LIBRARIES, the libraries required to use MPEG.
11849 MPEG_FOUND, If false, do not try to use MPEG.
11850 also defined, but not for general use are
11852 MPEG_mpeg2_LIBRARY, where to find the MPEG library.
11854 MPEG_vo_LIBRARY, where to find the vo library.
11855 FindMPI
11857 Find a Message Passing Interface (MPI) implementation.
11858 The Message Passing Interface (MPI) is a library used to write
11860 high-performance distributed-memory parallel applications, and is typi‐
11861 cally deployed on a cluster. MPI is a standard interface (defined by
11862 the MPI forum) for which many implementations are available.
11863 Variables for using MPI
11865 The module exposes the components C, CXX, MPICXX and Fortran. Each of
11866 these controls the various MPI languages to search for. The difference
11867 between CXX and MPICXX is that CXX refers to the MPI C API being usable
11868 from C++, whereas MPICXX refers to the MPI-2 C++ API that was removed
11869 again in MPI-3.
11870 Depending on the enabled components the following variables will be
11872 set:
11873 MPI_FOUND
11875 Variable indicating that MPI settings for all requested lan‐
11876 guages have been found. If no components are specified, this is
11877 true if MPI settings for all enabled languages were detected.
11878 Note that the MPICXX component does not affect this variable.
11879 MPI_VERSION
11881 Minimal version of MPI detected among the requested languages,
11882 or all enabled languages if no components were specified.
11883 This module will set the following variables per language in your
11885 project, where <lang> is one of C, CXX, or Fortran:
11886 MPI_<lang>_FOUND
11888 Variable indicating the MPI settings for <lang> were found and
11889 that simple MPI test programs compile with the provided set‐
11890 tings.
11891 MPI_<lang>_COMPILER
11893 MPI compiler for <lang> if such a program exists.
11894 MPI_<lang>_COMPILE_OPTIONS
11896 Compilation options for MPI programs in <lang>, given as a
11897 ;-list.
11898 MPI_<lang>_COMPILE_DEFINITIONS
11900 Compilation definitions for MPI programs in <lang>, given as a
11901 ;-list.
11902 MPI_<lang>_INCLUDE_DIRS
11904 Include path(s) for MPI header.
11905 MPI_<lang>_LINK_FLAGS
11907 Linker flags for MPI programs.
11908 MPI_<lang>_LIBRARIES
11910 All libraries to link MPI programs against.
11911 Additionally, the following IMPORTED targets are defined:
11913 MPI::MPI_<lang>
11915 Target for using MPI from <lang>.
11916 The following variables indicating which bindings are present will be
11918 defined:
11919 MPI_MPICXX_FOUND
11921 Variable indicating whether the MPI-2 C++ bindings are present
11922 (introduced in MPI-2, removed with MPI-3).
11923 MPI_Fortran_HAVE_F77_HEADER
11925 True if the Fortran 77 header mpif.h is available.
11926 MPI_Fortran_HAVE_F90_MODULE
11928 True if the Fortran 90 module mpi can be used for accessing MPI
11929 (MPI-2 and higher only).
11930 MPI_Fortran_HAVE_F08_MODULE
11932 True if the Fortran 2008 mpi_f08 is available to MPI programs
11933 (MPI-3 and higher only).
11934 If possible, the MPI version will be determined by this module. The
11936 facilities to detect the MPI version were introduced with MPI-1.2, and
11937 therefore cannot be found for older MPI versions.
11938 MPI_<lang>_VERSION_MAJOR
11940 Major version of MPI implemented for <lang> by the MPI distribu‐
11941 tion.
11942 MPI_<lang>_VERSION_MINOR
11944 Minor version of MPI implemented for <lang> by the MPI distribu‐
11945 tion.
11946 MPI_<lang>_VERSION
11948 MPI version implemented for <lang> by the MPI distribution.
11949 Note that there’s no variable for the C bindings being accessible
11951 through mpi.h, since the MPI standards always have required this bind‐
11952 ing to work in both C and C++ code.
11953 For running MPI programs, the module sets the following variables
11955 MPIEXEC_EXECUTABLE
11957 Executable for running MPI programs, if such exists.
11958 MPIEXEC_NUMPROC_FLAG
11960 Flag to pass to mpiexec before giving it the number of proces‐
11961 sors to run on.
11962 MPIEXEC_MAX_NUMPROCS
11964 Number of MPI processors to utilize. Defaults to the number of
11965 processors detected on the host system.
11966 MPIEXEC_PREFLAGS
11968 Flags to pass to mpiexec directly before the executable to run.
11969 MPIEXEC_POSTFLAGS
11971 Flags to pass to mpiexec after other flags.
11972 Variables for locating MPI
11974 This module performs a four step search for an MPI implementation:
11975 1. Search for MPIEXEC_EXECUTABLE and, if found, use its base directory.
11977 2. Check if the compiler has MPI support built-in. This is the case if
11979 the user passed a compiler wrapper as CMAKE_<LANG>_COMPILER or if
11980 they’re on a Cray system.
11981 3. Attempt to find an MPI compiler wrapper and determine the compiler
11983 information from it.
11984 4. Try to find an MPI implementation that does not ship such a wrapper
11986 by guessing settings. Currently, only Microsoft MPI and MPICH2 on
11987 Windows are supported.
11988 For controlling the MPIEXEC_EXECUTABLE step, the following variables
11990 may be set:
11991 MPIEXEC_EXECUTABLE
11993 Manually specify the location of mpiexec.
11994 MPI_HOME
11996 Specify the base directory of the MPI installation.
11997 ENV{MPI_HOME}
11999 Environment variable to specify the base directory of the MPI
12000 installation.
12001 ENV{I_MPI_ROOT}
12003 Environment variable to specify the base directory of the MPI
12004 installation.
12005 For controlling the compiler wrapper step, the following variables may
12007 be set:
12008 MPI_<lang>_COMPILER
12010 Search for the specified compiler wrapper and use it.
12011 MPI_<lang>_COMPILER_FLAGS
12013 Flags to pass to the MPI compiler wrapper during interrogation.
12014 Some compiler wrappers support linking debug or tracing
12015 libraries if a specific flag is passed and this variable may be
12016 used to obtain them.
12017 MPI_COMPILER_FLAGS
12019 Used to initialize MPI_<lang>_COMPILER_FLAGS if no language spe‐
12020 cific flag has been given. Empty by default.
12021 MPI_EXECUTABLE_SUFFIX
12023 A suffix which is appended to all names that are being looked
12024 for. For instance you may set this to .mpich or .openmpi to pre‐
12025 fer the one or the other on Debian and its derivatives.
12026 In order to control the guessing step, the following variable may be
12028 set:
12029 MPI_GUESS_LIBRARY_NAME
12031 Valid values are MSMPI and MPICH2. If set, only the given
12032 library will be searched for. By default, MSMPI will be pre‐
12033 ferred over MPICH2 if both are available. This also sets
12034 MPI_SKIP_COMPILER_WRAPPER to true, which may be overridden.
12035 Each of the search steps may be skipped with the following control
12037 variables:
12038 MPI_ASSUME_NO_BUILTIN_MPI
12040 If true, the module assumes that the compiler itself does not
12041 provide an MPI implementation and skips to step 2.
12042 MPI_SKIP_COMPILER_WRAPPER
12044 If true, no compiler wrapper will be searched for.
12045 MPI_SKIP_GUESSING
12047 If true, the guessing step will be skipped.
12048 Additionally, the following control variable is available to change
12050 search behavior:
12051 MPI_CXX_SKIP_MPICXX
12053 Add some definitions that will disable the MPI-2 C++ bindings.
12054 Currently supported are MPICH, Open MPI, Platform MPI and deriv‐
12055 atives thereof, for example MVAPICH or Intel MPI.
12056 If the find procedure fails for a variable MPI_<lang>_WORKS, then the
12058 settings detected by or passed to the module did not work and even a
12059 simple MPI test program failed to compile.
12060 If all of these parameters were not sufficient to find the right MPI
12062 implementation, a user may disable the entire autodetection process by
12063 specifying both a list of libraries in MPI_<lang>_LIBRARIES and a list
12064 of include directories in MPI_<lang>_ADDITIONAL_INCLUDE_DIRS. Any
12065 other variable may be set in addition to these two. The module will
12066 then validate the MPI settings and store the settings in the cache.
12067 Cache variables for MPI
12069 The variable MPI_<lang>_INCLUDE_DIRS will be assembled from the follow‐
12070 ing variables. For C and CXX:
12071 MPI_<lang>_HEADER_DIR
12073 Location of the mpi.h header on disk.
12074 For Fortran:
12076 MPI_Fortran_F77_HEADER_DIR
12078 Location of the Fortran 77 header mpif.h, if it exists.
12079 MPI_Fortran_MODULE_DIR
12081 Location of the mpi or mpi_f08 modules, if available.
12082 For all languages the following variables are additionally considered:
12084 MPI_<lang>_ADDITIONAL_INCLUDE_DIRS
12086 A ;-list of paths needed in addition to the normal include
12087 directories.
12088 MPI_<include_name>_INCLUDE_DIR
12090 Path variables for include folders referred to by
12091 <include_name>.
12092 MPI_<lang>_ADDITIONAL_INCLUDE_VARS
12094 A ;-list of <include_name> that will be added to the include
12095 locations of <lang>.
12096 The variable MPI_<lang>_LIBRARIES will be assembled from the following
12098 variables:
12099 MPI_<lib_name>_LIBRARY
12101 The location of a library called <lib_name> for use with MPI.
12102 MPI_<lang>_LIB_NAMES
12104 A ;-list of <lib_name> that will be added to the include loca‐
12105 tions of <lang>.
12106 Usage of mpiexec
12108 When using MPIEXEC_EXECUTABLE to execute MPI applications, you should
12109 typically use all of the MPIEXEC_EXECUTABLE flags as follows:
12110 ${MPIEXEC_EXECUTABLE} ${MPIEXEC_NUMPROC_FLAG} ${MPIEXEC_MAX_NUMPROCS}
12112 ${MPIEXEC_PREFLAGS} EXECUTABLE ${MPIEXEC_POSTFLAGS} ARGS
12113 where EXECUTABLE is the MPI program, and ARGS are the arguments to pass
12115 to the MPI program.
12116 Advanced variables for using MPI
12118 The module can perform some advanced feature detections upon explicit
12119 request.
12120 Important notice: The following checks cannot be performed without exe‐
12122 cuting an MPI test program. Consider the special considerations for
12123 the behavior of try_run() during cross compilation. Moreover, running
12124 an MPI program can cause additional issues, like a firewall notifica‐
12125 tion on some systems. You should only enable these detections if you
12126 absolutely need the information.
12127 If the following variables are set to true, the respective search will
12129 be performed:
12130 MPI_DETERMINE_Fortran_CAPABILITIES
12132 Determine for all available Fortran bindings what the values of
12133 MPI_SUBARRAYS_SUPPORTED and MPI_ASYNC_PROTECTS_NONBLOCKING are
12134 and make their values available as MPI_Fortran_<binding>_SUBAR‐
12135 RAYS and MPI_Fortran_<binding>_ASYNCPROT, where <binding> is one
12136 of F77_HEADER, F90_MODULE and F08_MODULE.
12137 MPI_DETERMINE_LIBRARY_VERSION
12139 For each language, find the output of MPI_Get_library_version
12140 and make it available as MPI_<lang>_LIBRARY_VERSION_STRING.
12141 This information is usually tied to the runtime component of an
12142 MPI implementation and might differ depending on <lang>. Note
12143 that the return value is entirely implementation defined. This
12144 information might be used to identify the MPI vendor and for
12145 example pick the correct one of multiple third party binaries
12146 that matches the MPI vendor.
12147 Backward Compatibility
12149 For backward compatibility with older versions of FindMPI, these vari‐
12150 ables are set, but deprecated:
12151 MPI_COMPILER MPI_LIBRARY MPI_EXTRA_LIBRARY
12153 MPI_COMPILE_FLAGS MPI_INCLUDE_PATH MPI_LINK_FLAGS
12154 MPI_LIBRARIES
12155 In new projects, please use the MPI_<lang>_XXX equivalents. Addition‐
12157 ally, the following variables are deprecated:
12158 MPI_<lang>_COMPILE_FLAGS
12160 Use MPI_<lang>_COMPILE_OPTIONS and MPI_<lang>_COMPILE_DEFINI‐
12161 TIONS instead.
12162 MPI_<lang>_INCLUDE_PATH
12164 For consumption use MPI_<lang>_INCLUDE_DIRS and for specifying
12165 folders use MPI_<lang>_ADDITIONAL_INCLUDE_DIRS instead.
12166 MPIEXEC
12168 Use MPIEXEC_EXECUTABLE instead.
12169 FindODBC
12171 Find an Open Database Connectivity (ODBC) include directory and
12172 library.
12173 On Windows, when building with Visual Studio, this module assumes the
12175 ODBC library is provided by the available Windows SDK.
12176 On Unix, this module allows to search for ODBC library provided by
12178 unixODBC or iODBC implementations of ODBC API. This module reads hint
12179 about location of the config program:
12180 ODBC_CONFIG
12182 Location of odbc_config or iodbc-config program
12183 Otherwise, this module tries to find the config program, first from
12185 unixODBC, then from iODBC. If no config program found, this module
12186 searches for ODBC header and library in list of known locations.
12187 Imported targets
12189 This module defines the following IMPORTED targets:
12190 ODBC::ODBC
12192 Imported target for using the ODBC library, if found.
12193 Result variables
12195 ODBC_FOUND
12196 Set to true if ODBC library found, otherwise false or undefined.
12197 ODBC_INCLUDE_DIRS
12199 Paths to include directories listed in one variable for use by
12200 ODBC client. May be empty on Windows, where the include direc‐
12201 tory corresponding to the expected Windows SDK is already avail‐
12202 able in the compilation environment.
12203 ODBC_LIBRARIES
12205 Paths to libraries to linked against to use ODBC. May just a
12206 library name on Windows, where the library directory correspond‐
12207 ing to the expected Windows SDK is already available in the com‐
12208 pilation environment.
12209 ODBC_CONFIG
12211 Path to unixODBC or iODBC config program, if found or specified.
12212 Cache variables
12214 For users who wish to edit and control the module behavior, this module
12215 reads hints about search locations from the following variables:
12216 ODBC_INCLUDE_DIR
12218 Path to ODBC include directory with sql.h header.
12219 ODBC_LIBRARY
12221 Path to ODBC library to be linked.
12222 These variables should not be used directly by project code.
12224 Limitations
12226 On Windows, this module does not search for iODBC. On Unix, there is
12227 no way to prefer unixODBC over iODBC, or vice versa, other than provid‐
12228 ing the config program location using the ODBC_CONFIG. This module
12229 does not allow to search for a specific ODBC driver.
12230 FindOpenACC
12232 Detect OpenACC support by the compiler.
12233 This module can be used to detect OpenACC support in a compiler. If
12235 the compiler supports OpenACC, the flags required to compile with Ope‐
12236 nACC support are returned in variables for the different languages.
12237 Currently, only PGI, GNU and Cray compilers are supported.
12238 Variables
12240 This module will set the following variables per language in your
12241 project, where <lang> is one of C, CXX, or Fortran:
12242 OpenACC_<lang>_FOUND
12244 Variable indicating if OpenACC support for <lang> was detected.
12245 OpenACC_<lang>_FLAGS
12247 OpenACC compiler flags for <lang>, separated by spaces.
12248 OpenACC_<lang>_OPTIONS
12250 OpenACC compiler flags for <lang>, as a list. Suitable for usage
12251 with target_compile_options or target_link_options.
12252 Additionally, the module provides IMPORTED targets:
12254 OpenACC::OpenACC_<lang>
12256 Target for using OpenACC from <lang>.
12257 The module will also try to provide the OpenACC version variables:
12259 OpenACC_<lang>_SPEC_DATE
12261 Date of the OpenACC specification implemented by the <lang> com‐
12262 piler.
12263 OpenACC_<lang>_VERSION_MAJOR
12265 Major version of OpenACC implemented by the <lang> compiler.
12266 OpenACC_<lang>_VERSION_MINOR
12268 Minor version of OpenACC implemented by the <lang> compiler.
12269 OpenACC_<lang>_VERSION
12271 OpenACC version implemented by the <lang> compiler.
12272 The specification date is formatted as given in the OpenACC standard:
12274 yyyymm where yyyy and mm represents the year and month of the OpenACC
12275 specification implemented by the <lang> compiler.
12276 Input Variables
12278 OpenACC_ACCEL_TARGET=<target> If set, will the correct target accelera‐
12279 tor flag set to the <target> will be returned with Ope‐
12280 nACC_<lang>_FLAGS.
12281 FindOpenAL
12283 Finds Open Audio Library (OpenAL). This module defines OPENAL_LIBRARY
12284 OPENAL_FOUND, if false, do not try to link to OpenAL OPE‐
12285 NAL_INCLUDE_DIR, where to find the headers.
12286 $OPENALDIR is an environment variable that would correspond to the
12288 ./configure --prefix=$OPENALDIR used in building OpenAL.
12289 Created by Eric Wing. This was influenced by the FindSDL.cmake module.
12291 FindOpenCL
12293 Finds Open Computing Language (OpenCL)
12294 IMPORTED Targets
12296 This module defines IMPORTED target OpenCL::OpenCL, if OpenCL has been
12297 found.
12298 Result Variables
12300 This module defines the following variables:
12301 OpenCL_FOUND - True if OpenCL was found
12303 OpenCL_INCLUDE_DIRS - include directories for OpenCL
12304 OpenCL_LIBRARIES - link against this library to use OpenCL
12305 OpenCL_VERSION_STRING - Highest supported OpenCL version (eg. 1.2)
12306 OpenCL_VERSION_MAJOR - The major version of the OpenCL implementation
12307 OpenCL_VERSION_MINOR - The minor version of the OpenCL implementation
12308 The module will also define two cache variables:
12310 OpenCL_INCLUDE_DIR - the OpenCL include directory
12312 OpenCL_LIBRARY - the path to the OpenCL library
12313 FindOpenGL
12315 FindModule for OpenGL and OpenGL Utility Library (GLU).
12316 Optional COMPONENTS
12318 This module respects several optional COMPONENTS: EGL, GLX, and OpenGL.
12319 There are corresponding import targets for each of these flags.
12320 IMPORTED Targets
12322 This module defines the IMPORTED targets:
12323 OpenGL::GL
12325 Defined to the platform-specific OpenGL libraries if the system
12326 has OpenGL.
12327 OpenGL::OpenGL
12329 Defined to libOpenGL if the system is GLVND-based.
12330 OpenGL::GLU
12332 Defined if the system has OpenGL Utility Library (GLU).
12333 OpenGL::GLX
12335 Defined if the system has OpenGL Extension to the X Window Sys‐
12336 tem (GLX).
12337 OpenGL::EGL
12339 Defined if the system has EGL.
12340 Result Variables
12342 This module sets the following variables:
12343 OPENGL_FOUND
12345 True, if the system has OpenGL and all components are found.
12346 OPENGL_XMESA_FOUND
12348 True, if the system has XMESA.
12349 OPENGL_GLU_FOUND
12351 True, if the system has GLU.
12352 OpenGL_OpenGL_FOUND
12354 True, if the system has an OpenGL library.
12355 OpenGL_GLX_FOUND
12357 True, if the system has GLX.
12358 OpenGL_EGL_FOUND
12360 True, if the system has EGL.
12361 OPENGL_INCLUDE_DIR
12363 Path to the OpenGL include directory.
12364 OPENGL_EGL_INCLUDE_DIRS
12366 Path to the EGL include directory.
12367 OPENGL_LIBRARIES
12369 Paths to the OpenGL library, windowing system libraries, and GLU
12370 libraries. On Linux, this assumes GLX and is never correct for
12371 EGL-based targets. Clients are encouraged to use the OpenGL::*
12372 import targets instead.
12373 Cache variables
12375 The following cache variables may also be set:
12376 OPENGL_egl_LIBRARY
12378 Path to the EGL library.
12379 OPENGL_glu_LIBRARY
12381 Path to the GLU library.
12382 OPENGL_glx_LIBRARY
12384 Path to the GLVND ‘GLX’ library.
12385 OPENGL_opengl_LIBRARY
12387 Path to the GLVND ‘OpenGL’ library
12388 OPENGL_gl_LIBRARY
12390 Path to the OpenGL library. New code should prefer the
12391 OpenGL::* import targets.
12392 Linux-specific
12394 Some Linux systems utilize GLVND as a new ABI for OpenGL. GLVND sepa‐
12395 rates context libraries from OpenGL itself; OpenGL lives in
12396 “libOpenGL”, and contexts are defined in “libGLX” or “libEGL”. GLVND
12397 is currently the only way to get OpenGL 3+ functionality via EGL in a
12398 manner portable across vendors. Projects may use GLVND explicitly with
12399 target OpenGL::OpenGL and either OpenGL::GLX or OpenGL::EGL.
12400 Projects may use the OpenGL::GL target (or OPENGL_LIBRARIES variable)
12402 to use legacy GL interfaces. These will use the legacy GL library
12403 located by OPENGL_gl_LIBRARY, if available. If OPENGL_gl_LIBRARY is
12404 empty or not found and GLVND is available, the OpenGL::GL target will
12405 use GLVND OpenGL::OpenGL and OpenGL::GLX (and the OPENGL_LIBRARIES
12406 variable will use the corresponding libraries). Thus, for
12407 non-EGL-based Linux targets, the OpenGL::GL target is most portable.
12408 A OpenGL_GL_PREFERENCE variable may be set to specify the preferred way
12410 to provide legacy GL interfaces in case multiple choices are available.
12411 The value may be one of:
12412 GLVND If the GLVND OpenGL and GLX libraries are available, prefer
12414 them. This forces OPENGL_gl_LIBRARY to be empty. This is the
12415 default if components were requested (since components corre‐
12416 spond to GLVND libraries) or if policy CMP0072 is set to NEW.
12417 LEGACY Prefer to use the legacy libGL library, if available. This is
12419 the default if no components were requested and policy CMP0072
12420 is not set to NEW.
12421 For EGL targets the client must rely on GLVND support on the user’s
12423 system. Linking should use the OpenGL::OpenGL OpenGL::EGL targets.
12424 Using GLES* libraries is theoretically possible in place of
12425 OpenGL::OpenGL, but this module does not currently support that; con‐
12426 tributions welcome.
12427 OPENGL_egl_LIBRARY and OPENGL_EGL_INCLUDE_DIRS are defined in the case
12429 of GLVND. For non-GLVND Linux and other systems these are left unde‐
12430 fined.
12431 macOS-Specific
12433 On OSX FindOpenGL defaults to using the framework version of OpenGL.
12434 People will have to change the cache values of OPENGL_glu_LIBRARY and
12435 OPENGL_gl_LIBRARY to use OpenGL with X11 on OSX.
12436 FindOpenMP
12438 Finds Open Multi-Processing (OpenMP) support.
12439 This module can be used to detect OpenMP support in a compiler. If the
12441 compiler supports OpenMP, the flags required to compile with OpenMP
12442 support are returned in variables for the different languages. The
12443 variables may be empty if the compiler does not need a special flag to
12444 support OpenMP.
12445 Variables
12447 The module exposes the components C, CXX, and Fortran. Each of these
12448 controls the various languages to search OpenMP support for.
12449 Depending on the enabled components the following variables will be
12451 set:
12452 OpenMP_FOUND
12454 Variable indicating that OpenMP flags for all requested lan‐
12455 guages have been found. If no components are specified, this is
12456 true if OpenMP settings for all enabled languages were detected.
12457 OpenMP_VERSION
12459 Minimal version of the OpenMP standard detected among the
12460 requested languages, or all enabled languages if no components
12461 were specified.
12462 This module will set the following variables per language in your
12464 project, where <lang> is one of C, CXX, or Fortran:
12465 OpenMP_<lang>_FOUND
12467 Variable indicating if OpenMP support for <lang> was detected.
12468 OpenMP_<lang>_FLAGS
12470 OpenMP compiler flags for <lang>, separated by spaces.
12471 OpenMP_<lang>_INCLUDE_DIRS
12473 Directories that must be added to the header search path for
12474 <lang> when using OpenMP.
12475 For linking with OpenMP code written in <lang>, the following variables
12477 are provided:
12478 OpenMP_<lang>_LIB_NAMES
12480 ;-list of libraries for OpenMP programs for <lang>.
12481 OpenMP_<libname>_LIBRARY
12483 Location of the individual libraries needed for OpenMP support
12484 in <lang>.
12485 OpenMP_<lang>_LIBRARIES
12487 A list of libraries needed to link with OpenMP code written in
12488 <lang>.
12489 Additionally, the module provides IMPORTED targets:
12491 OpenMP::OpenMP_<lang>
12493 Target for using OpenMP from <lang>.
12494 Specifically for Fortran, the module sets the following variables:
12496 OpenMP_Fortran_HAVE_OMPLIB_HEADER
12498 Boolean indicating if OpenMP is accessible through omp_lib.h.
12499 OpenMP_Fortran_HAVE_OMPLIB_MODULE
12501 Boolean indicating if OpenMP is accessible through the omp_lib
12502 Fortran module.
12503 The module will also try to provide the OpenMP version variables:
12505 OpenMP_<lang>_SPEC_DATE
12507 Date of the OpenMP specification implemented by the <lang> com‐
12508 piler.
12509 OpenMP_<lang>_VERSION_MAJOR
12511 Major version of OpenMP implemented by the <lang> compiler.
12512 OpenMP_<lang>_VERSION_MINOR
12514 Minor version of OpenMP implemented by the <lang> compiler.
12515 OpenMP_<lang>_VERSION
12517 OpenMP version implemented by the <lang> compiler.
12518 The specification date is formatted as given in the OpenMP standard:
12520 yyyymm where yyyy and mm represents the year and month of the OpenMP
12521 specification implemented by the <lang> compiler.
12522 For some compilers, it may be necessary to add a header search path to
12524 find the relevant OpenMP headers. This location may be language-spe‐
12525 cific. Where this is needed, the module may attempt to find the loca‐
12526 tion, but it can be provided directly by setting the
12527 OpenMP_<lang>_INCLUDE_DIR cache variable. Note that this variable is
12528 an _input_ control to the module. Project code should use the
12529 OpenMP_<lang>_INCLUDE_DIRS _output_ variable if it needs to know what
12530 include directories are needed.
12531 FindOpenSceneGraph
12533 Find OpenSceneGraph (3D graphics application programming interface)
12534 This module searches for the OpenSceneGraph core “osg” library as well
12536 as FindOpenThreads, and whatever additional COMPONENTS (nodekits) that
12537 you specify.
12538 See http://www.openscenegraph.org
12540 NOTE: To use this module effectively you must either require CMake >=
12542 2.6.3 with cmake_minimum_required(VERSION 2.6.3) or download and place
12543 FindOpenThreads, Findosg functions, Findosg and Find<etc>.cmake files
12544 into your CMAKE_MODULE_PATH.
12545 ----
12548 This module accepts the following variables (note mixed case)
12552 OpenSceneGraph_DEBUG - Enable debugging output
12554 OpenSceneGraph_MARK_AS_ADVANCED - Mark cache variables as advanced
12556 automatically
12557 The following environment variables are also respected for finding the
12559 OSG and it’s various components. CMAKE_PREFIX_PATH can also be used
12560 for this (see find_library() CMake documentation).
12561 <MODULE>_DIR
12563 (where MODULE is of the form “OSGVOLUME” and there is a Findos‐
12564 gVolume.cmake` file)
12565 OSG_DIR
12567 OSGDIR
12569 OSG_ROOT
12571 [CMake 2.8.10]: The CMake variable OSG_DIR can now be used as well to
12573 influence detection, instead of needing to specify an environment vari‐
12574 able.
12575 This module defines the following output variables:
12577 OPENSCENEGRAPH_FOUND - Was the OSG and all of the specified components found?
12579 OPENSCENEGRAPH_VERSION - The version of the OSG which was found
12581 OPENSCENEGRAPH_INCLUDE_DIRS - Where to find the headers
12583 OPENSCENEGRAPH_LIBRARIES - The OSG libraries
12585 ================================== Example Usage:
12587 find_package(OpenSceneGraph 2.0.0 REQUIRED osgDB osgUtil)
12589 # libOpenThreads & libosg automatically searched
12590 include_directories(${OPENSCENEGRAPH_INCLUDE_DIRS})
12591 add_executable(foo foo.cc)
12593 target_link_libraries(foo ${OPENSCENEGRAPH_LIBRARIES})
12594 FindOpenSSL
12596 Find the OpenSSL encryption library.
12597 Optional COMPONENTS
12599 This module supports two optional COMPONENTS: Crypto and SSL. Both
12600 components have associated imported targets, as described below.
12601 Imported Targets
12603 This module defines the following IMPORTED targets:
12604 OpenSSL::SSL
12606 The OpenSSL ssl library, if found.
12607 OpenSSL::Crypto
12609 The OpenSSL crypto library, if found.
12610 Result Variables
12612 This module will set the following variables in your project:
12613 OPENSSL_FOUND
12615 System has the OpenSSL library. If no components are requested
12616 it only requires the crypto library.
12617 OPENSSL_INCLUDE_DIR
12619 The OpenSSL include directory.
12620 OPENSSL_CRYPTO_LIBRARY
12622 The OpenSSL crypto library.
12623 OPENSSL_CRYPTO_LIBRARIES
12625 The OpenSSL crypto library and its dependencies.
12626 OPENSSL_SSL_LIBRARY
12628 The OpenSSL SSL library.
12629 OPENSSL_SSL_LIBRARIES
12631 The OpenSSL SSL library and its dependencies.
12632 OPENSSL_LIBRARIES
12634 All OpenSSL libraries and their dependencies.
12635 OPENSSL_VERSION
12637 This is set to $major.$minor.$revision$patch (e.g. 0.9.8s).
12638 Hints
12640 Set OPENSSL_ROOT_DIR to the root directory of an OpenSSL installation.
12641 Set OPENSSL_USE_STATIC_LIBS to TRUE to look for static libraries. Set
12642 OPENSSL_MSVC_STATIC_RT set TRUE to choose the MT version of the lib.
12643 FindOpenThreads
12645 OpenThreads is a C++ based threading library. Its largest userbase
12646 seems to OpenSceneGraph so you might notice I accept OSGDIR as an envi‐
12647 ronment path. I consider this part of the Findosg* suite used to find
12648 OpenSceneGraph components. Each component is separate and you must opt
12649 in to each module.
12650 Locate OpenThreads This module defines OPENTHREADS_LIBRARY
12652 OPENTHREADS_FOUND, if false, do not try to link to OpenThreads
12653 OPENTHREADS_INCLUDE_DIR, where to find the headers
12654 $OPENTHREADS_DIR is an environment variable that would correspond to
12656 the ./configure –prefix=$OPENTHREADS_DIR used in building osg.
12657 [CMake 2.8.10]: The CMake variables OPENTHREADS_DIR or OSG_DIR can now
12659 be used as well to influence detection, instead of needing to specify
12660 an environment variable.
12661 Created by Eric Wing.
12663 FindosgAnimation
12665 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12666 nents. Each component is separate and you must opt in to each module.
12667 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12668 as these modules won’t do it for you. This is to allow you control
12669 over your own system piece by piece in case you need to opt out of cer‐
12670 tain components or change the Find behavior for a particular module
12671 (perhaps because the default FindOpenGL.cmake module doesn’t work with
12672 your system as an example). If you want to use a more convenient mod‐
12673 ule that includes everything, use the FindOpenSceneGraph.cmake instead
12674 of the Findosg*.cmake modules.
12675 Locate osgAnimation This module defines
12677 OSGANIMATION_FOUND - Was osgAnimation found? OSGANIMATION_INCLUDE_DIR -
12679 Where to find the headers OSGANIMATION_LIBRARIES - The libraries to
12680 link against for the OSG (use this)
12681 OSGANIMATION_LIBRARY - The OSG library OSGANIMATION_LIBRARY_DEBUG - The
12683 OSG debug library
12684 $OSGDIR is an environment variable that would correspond to the
12686 Created by Eric Wing.
12688 FindosgDB
12690 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12691 nents. Each component is separate and you must opt in to each module.
12692 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12693 as these modules won’t do it for you. This is to allow you control
12694 over your own system piece by piece in case you need to opt out of cer‐
12695 tain components or change the Find behavior for a particular module
12696 (perhaps because the default FindOpenGL module doesn’t work with your
12697 system as an example). If you want to use a more convenient module
12698 that includes everything, use the FindOpenSceneGraph instead of the
12699 Findosg*.cmake modules.
12700 Locate osgDB This module defines:
12702 OSGDB_FOUND
12704 Was osgDB found?
12705 OSGDB_INCLUDE_DIR
12707 Where to find the headers
12708 OSGDB_LIBRARIES
12710 The libraries to link against for the osgDB
12711 OSGDB_LIBRARY
12713 The osgDB library
12714 OSGDB_LIBRARY_DEBUG
12716 The osgDB debug library
12717 $OSGDIR is an environment variable that would correspond to:
12719 ./configure --prefix=$OSGDIR used in building osg.
12721 Findosg_functions
12723 This CMake file contains two macros to assist with searching for OSG
12724 libraries and nodekits. Please see FindOpenSceneGraph.cmake for full
12725 documentation.
12726 FindosgFX
12728 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12729 nents. Each component is separate and you must opt in to each module.
12730 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12731 as these modules won’t do it for you. This is to allow you control
12732 over your own system piece by piece in case you need to opt out of cer‐
12733 tain components or change the Find behavior for a particular module
12734 (perhaps because the default FindOpenGL.cmake module doesn’t work with
12735 your system as an example). If you want to use a more convenient mod‐
12736 ule that includes everything, use the FindOpenSceneGraph.cmake instead
12737 of the Findosg*.cmake modules.
12738 Locate osgFX This module defines
12740 OSGFX_FOUND - Was osgFX found? OSGFX_INCLUDE_DIR - Where to find the
12742 headers OSGFX_LIBRARIES - The libraries to link against for the osgFX
12743 (use this)
12744 OSGFX_LIBRARY - The osgFX library OSGFX_LIBRARY_DEBUG - The osgFX debug
12746 library
12747 $OSGDIR is an environment variable that would correspond to the
12749 Created by Eric Wing.
12751 FindosgGA
12753 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12754 nents. Each component is separate and you must opt in to each module.
12755 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12756 as these modules won’t do it for you. This is to allow you control
12757 over your own system piece by piece in case you need to opt out of cer‐
12758 tain components or change the Find behavior for a particular module
12759 (perhaps because the default FindOpenGL.cmake module doesn’t work with
12760 your system as an example). If you want to use a more convenient mod‐
12761 ule that includes everything, use the FindOpenSceneGraph.cmake instead
12762 of the Findosg*.cmake modules.
12763 Locate osgGA This module defines
12765 OSGGA_FOUND - Was osgGA found? OSGGA_INCLUDE_DIR - Where to find the
12767 headers OSGGA_LIBRARIES - The libraries to link against for the osgGA
12768 (use this)
12769 OSGGA_LIBRARY - The osgGA library OSGGA_LIBRARY_DEBUG - The osgGA debug
12771 library
12772 $OSGDIR is an environment variable that would correspond to the
12774 Created by Eric Wing.
12776 FindosgIntrospection
12778 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12779 nents. Each component is separate and you must opt in to each module.
12780 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12781 as these modules won’t do it for you. This is to allow you control
12782 over your own system piece by piece in case you need to opt out of cer‐
12783 tain components or change the Find behavior for a particular module
12784 (perhaps because the default FindOpenGL.cmake module doesn’t work with
12785 your system as an example). If you want to use a more convenient mod‐
12786 ule that includes everything, use the FindOpenSceneGraph.cmake instead
12787 of the Findosg*.cmake modules.
12788 Locate osgINTROSPECTION This module defines
12790 OSGINTROSPECTION_FOUND - Was osgIntrospection found? OSGINTROSPEC‐
12792 TION_INCLUDE_DIR - Where to find the headers OSGINTROSPECTION_LIBRARIES
12793 - The libraries to link for osgIntrospection (use this)
12794 OSGINTROSPECTION_LIBRARY - The osgIntrospection library OSGINTROSPEC‐
12796 TION_LIBRARY_DEBUG - The osgIntrospection debug library
12797 $OSGDIR is an environment variable that would correspond to the
12799 Created by Eric Wing.
12801 FindosgManipulator
12803 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12804 nents. Each component is separate and you must opt in to each module.
12805 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12806 as these modules won’t do it for you. This is to allow you control
12807 over your own system piece by piece in case you need to opt out of cer‐
12808 tain components or change the Find behavior for a particular module
12809 (perhaps because the default FindOpenGL.cmake module doesn’t work with
12810 your system as an example). If you want to use a more convenient mod‐
12811 ule that includes everything, use the FindOpenSceneGraph.cmake instead
12812 of the Findosg*.cmake modules.
12813 Locate osgManipulator This module defines
12815 OSGMANIPULATOR_FOUND - Was osgManipulator found? OSGMANIPULA‐
12817 TOR_INCLUDE_DIR - Where to find the headers OSGMANIPULATOR_LIBRARIES -
12818 The libraries to link for osgManipulator (use this)
12819 OSGMANIPULATOR_LIBRARY - The osgManipulator library OSGMANIPULA‐
12821 TOR_LIBRARY_DEBUG - The osgManipulator debug library
12822 $OSGDIR is an environment variable that would correspond to the
12824 Created by Eric Wing.
12826 FindosgParticle
12828 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12829 nents. Each component is separate and you must opt in to each module.
12830 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12831 as these modules won’t do it for you. This is to allow you control
12832 over your own system piece by piece in case you need to opt out of cer‐
12833 tain components or change the Find behavior for a particular module
12834 (perhaps because the default FindOpenGL.cmake module doesn’t work with
12835 your system as an example). If you want to use a more convenient mod‐
12836 ule that includes everything, use the FindOpenSceneGraph.cmake instead
12837 of the Findosg*.cmake modules.
12838 Locate osgParticle This module defines
12840 OSGPARTICLE_FOUND - Was osgParticle found? OSGPARTICLE_INCLUDE_DIR -
12842 Where to find the headers OSGPARTICLE_LIBRARIES - The libraries to link
12843 for osgParticle (use this)
12844 OSGPARTICLE_LIBRARY - The osgParticle library OSGPARTICLE_LIBRARY_DEBUG
12846 - The osgParticle debug library
12847 $OSGDIR is an environment variable that would correspond to the
12849 Created by Eric Wing.
12851 FindosgPresentation
12853 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12854 nents. Each component is separate and you must opt in to each module.
12855 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12856 as these modules won’t do it for you. This is to allow you control
12857 over your own system piece by piece in case you need to opt out of cer‐
12858 tain components or change the Find behavior for a particular module
12859 (perhaps because the default FindOpenGL.cmake module doesn’t work with
12860 your system as an example). If you want to use a more convenient mod‐
12861 ule that includes everything, use the FindOpenSceneGraph.cmake instead
12862 of the Findosg*.cmake modules.
12863 Locate osgPresentation This module defines
12865 OSGPRESENTATION_FOUND - Was osgPresentation found? OSGPRESENTA‐
12867 TION_INCLUDE_DIR - Where to find the headers OSGPRESENTATION_LIBRARIES
12868 - The libraries to link for osgPresentation (use this)
12869 OSGPRESENTATION_LIBRARY - The osgPresentation library OSGPRESENTA‐
12871 TION_LIBRARY_DEBUG - The osgPresentation debug library
12872 $OSGDIR is an environment variable that would correspond to the
12874 Created by Eric Wing. Modified to work with osgPresentation by Robert
12876 Osfield, January 2012.
12877 FindosgProducer
12879 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12880 nents. Each component is separate and you must opt in to each module.
12881 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12882 as these modules won’t do it for you. This is to allow you control
12883 over your own system piece by piece in case you need to opt out of cer‐
12884 tain components or change the Find behavior for a particular module
12885 (perhaps because the default FindOpenGL.cmake module doesn’t work with
12886 your system as an example). If you want to use a more convenient mod‐
12887 ule that includes everything, use the FindOpenSceneGraph.cmake instead
12888 of the Findosg*.cmake modules.
12889 Locate osgProducer This module defines
12891 OSGPRODUCER_FOUND - Was osgProducer found? OSGPRODUCER_INCLUDE_DIR -
12893 Where to find the headers OSGPRODUCER_LIBRARIES - The libraries to link
12894 for osgProducer (use this)
12895 OSGPRODUCER_LIBRARY - The osgProducer library OSGPRODUCER_LIBRARY_DEBUG
12897 - The osgProducer debug library
12898 $OSGDIR is an environment variable that would correspond to the
12900 Created by Eric Wing.
12902 FindosgQt
12904 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12905 nents. Each component is separate and you must opt in to each module.
12906 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12907 as these modules won’t do it for you. This is to allow you control
12908 over your own system piece by piece in case you need to opt out of cer‐
12909 tain components or change the Find behavior for a particular module
12910 (perhaps because the default FindOpenGL.cmake module doesn’t work with
12911 your system as an example). If you want to use a more convenient mod‐
12912 ule that includes everything, use the FindOpenSceneGraph.cmake instead
12913 of the Findosg*.cmake modules.
12914 Locate osgQt This module defines
12916 OSGQT_FOUND - Was osgQt found? OSGQT_INCLUDE_DIR - Where to find the
12918 headers OSGQT_LIBRARIES - The libraries to link for osgQt (use this)
12919 OSGQT_LIBRARY - The osgQt library OSGQT_LIBRARY_DEBUG - The osgQt debug
12921 library
12922 $OSGDIR is an environment variable that would correspond to the
12924 Created by Eric Wing. Modified to work with osgQt by Robert Osfield,
12926 January 2012.
12927 Findosg
12929 NOTE: It is highly recommended that you use the new FindOpenScene‐
12930 Graph.cmake introduced in CMake 2.6.3 and not use this Find module
12931 directly.
12932 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12934 nents. Each component is separate and you must opt in to each module.
12935 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12936 as these modules won’t do it for you. This is to allow you control
12937 over your own system piece by piece in case you need to opt out of cer‐
12938 tain components or change the Find behavior for a particular module
12939 (perhaps because the default FindOpenGL.cmake module doesn’t work with
12940 your system as an example). If you want to use a more convenient mod‐
12941 ule that includes everything, use the FindOpenSceneGraph.cmake instead
12942 of the Findosg*.cmake modules.
12943 Locate osg This module defines
12945 OSG_FOUND - Was the Osg found? OSG_INCLUDE_DIR - Where to find the
12947 headers OSG_LIBRARIES - The libraries to link against for the OSG (use
12948 this)
12949 OSG_LIBRARY - The OSG library OSG_LIBRARY_DEBUG - The OSG debug library
12951 $OSGDIR is an environment variable that would correspond to the
12953 Created by Eric Wing.
12955 FindosgShadow
12957 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12958 nents. Each component is separate and you must opt in to each module.
12959 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12960 as these modules won’t do it for you. This is to allow you control
12961 over your own system piece by piece in case you need to opt out of cer‐
12962 tain components or change the Find behavior for a particular module
12963 (perhaps because the default FindOpenGL.cmake module doesn’t work with
12964 your system as an example). If you want to use a more convenient mod‐
12965 ule that includes everything, use the FindOpenSceneGraph.cmake instead
12966 of the Findosg*.cmake modules.
12967 Locate osgShadow This module defines
12969 OSGSHADOW_FOUND - Was osgShadow found? OSGSHADOW_INCLUDE_DIR - Where to
12971 find the headers OSGSHADOW_LIBRARIES - The libraries to link for
12972 osgShadow (use this)
12973 OSGSHADOW_LIBRARY - The osgShadow library OSGSHADOW_LIBRARY_DEBUG - The
12975 osgShadow debug library
12976 $OSGDIR is an environment variable that would correspond to the
12978 Created by Eric Wing.
12980 FindosgSim
12982 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12983 nents. Each component is separate and you must opt in to each module.
12984 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12985 as these modules won’t do it for you. This is to allow you control
12986 over your own system piece by piece in case you need to opt out of cer‐
12987 tain components or change the Find behavior for a particular module
12988 (perhaps because the default FindOpenGL.cmake module doesn’t work with
12989 your system as an example). If you want to use a more convenient mod‐
12990 ule that includes everything, use the FindOpenSceneGraph.cmake instead
12991 of the Findosg*.cmake modules.
12992 Locate osgSim This module defines
12994 OSGSIM_FOUND - Was osgSim found? OSGSIM_INCLUDE_DIR - Where to find the
12996 headers OSGSIM_LIBRARIES - The libraries to link for osgSim (use this)
12997 OSGSIM_LIBRARY - The osgSim library OSGSIM_LIBRARY_DEBUG - The osgSim
12999 debug library
13000 $OSGDIR is an environment variable that would correspond to the
13002 Created by Eric Wing.
13004 FindosgTerrain
13006 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
13007 nents. Each component is separate and you must opt in to each module.
13008 You must also opt into OpenGL and OpenThreads (and Producer if needed)
13009 as these modules won’t do it for you. This is to allow you control
13010 over your own system piece by piece in case you need to opt out of cer‐
13011 tain components or change the Find behavior for a particular module
13012 (perhaps because the default FindOpenGL.cmake module doesn’t work with
13013 your system as an example). If you want to use a more convenient mod‐
13014 ule that includes everything, use the FindOpenSceneGraph.cmake instead
13015 of the Findosg*.cmake modules.
13016 Locate osgTerrain This module defines
13018 OSGTERRAIN_FOUND - Was osgTerrain found? OSGTERRAIN_INCLUDE_DIR - Where
13020 to find the headers OSGTERRAIN_LIBRARIES - The libraries to link for
13021 osgTerrain (use this)
13022 OSGTERRAIN_LIBRARY - The osgTerrain library OSGTERRAIN_LIBRARY_DEBUG -
13024 The osgTerrain debug library
13025 $OSGDIR is an environment variable that would correspond to the
13027 Created by Eric Wing.
13029 FindosgText
13031 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
13032 nents. Each component is separate and you must opt in to each module.
13033 You must also opt into OpenGL and OpenThreads (and Producer if needed)
13034 as these modules won’t do it for you. This is to allow you control
13035 over your own system piece by piece in case you need to opt out of cer‐
13036 tain components or change the Find behavior for a particular module
13037 (perhaps because the default FindOpenGL.cmake module doesn’t work with
13038 your system as an example). If you want to use a more convenient mod‐
13039 ule that includes everything, use the FindOpenSceneGraph.cmake instead
13040 of the Findosg*.cmake modules.
13041 Locate osgText This module defines
13043 OSGTEXT_FOUND - Was osgText found? OSGTEXT_INCLUDE_DIR - Where to find
13045 the headers OSGTEXT_LIBRARIES - The libraries to link for osgText (use
13046 this)
13047 OSGTEXT_LIBRARY - The osgText library OSGTEXT_LIBRARY_DEBUG - The osg‐
13049 Text debug library
13050 $OSGDIR is an environment variable that would correspond to the
13052 Created by Eric Wing.
13054 FindosgUtil
13056 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
13057 nents. Each component is separate and you must opt in to each module.
13058 You must also opt into OpenGL and OpenThreads (and Producer if needed)
13059 as these modules won’t do it for you. This is to allow you control
13060 over your own system piece by piece in case you need to opt out of cer‐
13061 tain components or change the Find behavior for a particular module
13062 (perhaps because the default FindOpenGL.cmake module doesn’t work with
13063 your system as an example). If you want to use a more convenient mod‐
13064 ule that includes everything, use the FindOpenSceneGraph.cmake instead
13065 of the Findosg*.cmake modules.
13066 Locate osgUtil This module defines
13068 OSGUTIL_FOUND - Was osgUtil found? OSGUTIL_INCLUDE_DIR - Where to find
13070 the headers OSGUTIL_LIBRARIES - The libraries to link for osgUtil (use
13071 this)
13072 OSGUTIL_LIBRARY - The osgUtil library OSGUTIL_LIBRARY_DEBUG - The
13074 osgUtil debug library
13075 $OSGDIR is an environment variable that would correspond to the
13077 Created by Eric Wing.
13079 FindosgViewer
13081 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
13082 nents. Each component is separate and you must opt in to each module.
13083 You must also opt into OpenGL and OpenThreads (and Producer if needed)
13084 as these modules won’t do it for you. This is to allow you control
13085 over your own system piece by piece in case you need to opt out of cer‐
13086 tain components or change the Find behavior for a particular module
13087 (perhaps because the default FindOpenGL.cmake module doesn’t work with
13088 your system as an example). If you want to use a more convenient mod‐
13089 ule that includes everything, use the FindOpenSceneGraph.cmake instead
13090 of the Findosg*.cmake modules.
13091 Locate osgViewer This module defines
13093 OSGVIEWER_FOUND - Was osgViewer found? OSGVIEWER_INCLUDE_DIR - Where to
13095 find the headers OSGVIEWER_LIBRARIES - The libraries to link for
13096 osgViewer (use this)
13097 OSGVIEWER_LIBRARY - The osgViewer library OSGVIEWER_LIBRARY_DEBUG - The
13099 osgViewer debug library
13100 $OSGDIR is an environment variable that would correspond to the
13102 Created by Eric Wing.
13104 FindosgVolume
13106 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
13107 nents. Each component is separate and you must opt in to each module.
13108 You must also opt into OpenGL and OpenThreads (and Producer if needed)
13109 as these modules won’t do it for you. This is to allow you control
13110 over your own system piece by piece in case you need to opt out of cer‐
13111 tain components or change the Find behavior for a particular module
13112 (perhaps because the default FindOpenGL.cmake module doesn’t work with
13113 your system as an example). If you want to use a more convenient mod‐
13114 ule that includes everything, use the FindOpenSceneGraph.cmake instead
13115 of the Findosg*.cmake modules.
13116 Locate osgVolume This module defines
13118 OSGVOLUME_FOUND - Was osgVolume found? OSGVOLUME_INCLUDE_DIR - Where to
13120 find the headers OSGVOLUME_LIBRARIES - The libraries to link for
13121 osgVolume (use this)
13122 OSGVOLUME_LIBRARY - The osgVolume library OSGVOLUME_LIBRARY_DEBUG - The
13124 osgVolume debug library
13125 $OSGDIR is an environment variable that would correspond to the
13127 Created by Eric Wing.
13129 FindosgWidget
13131 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
13132 nents. Each component is separate and you must opt in to each module.
13133 You must also opt into OpenGL and OpenThreads (and Producer if needed)
13134 as these modules won’t do it for you. This is to allow you control
13135 over your own system piece by piece in case you need to opt out of cer‐
13136 tain components or change the Find behavior for a particular module
13137 (perhaps because the default FindOpenGL.cmake module doesn’t work with
13138 your system as an example). If you want to use a more convenient mod‐
13139 ule that includes everything, use the FindOpenSceneGraph.cmake instead
13140 of the Findosg*.cmake modules.
13141 Locate osgWidget This module defines
13143 OSGWIDGET_FOUND - Was osgWidget found? OSGWIDGET_INCLUDE_DIR - Where to
13145 find the headers OSGWIDGET_LIBRARIES - The libraries to link for osg‐
13146 Widget (use this)
13147 OSGWIDGET_LIBRARY - The osgWidget library OSGWIDGET_LIBRARY_DEBUG - The
13149 osgWidget debug library
13150 $OSGDIR is an environment variable that would correspond to the
13152 FindosgWidget.cmake tweaked from Findosg* suite as created by Eric
13154 Wing.
13155 FindPatch
13157 The module defines the following variables:
13158 Patch_EXECUTABLE
13160 Path to patch command-line executable.
13161 Patch_FOUND
13163 True if the patch command-line executable was found.
13164 The following IMPORTED targets are also defined:
13166 Patch::patch
13168 The command-line executable.
13169 Example usage:
13171 find_package(Patch)
13173 if(Patch_FOUND)
13174 message("Patch found: ${Patch_EXECUTABLE}")
13175 endif()
13176 FindPerlLibs
13178 Find Perl libraries
13179 This module finds if PERL is installed and determines where the include
13181 files and libraries are. It also determines what the name of the
13182 library is. This code sets the following variables:
13183 PERLLIBS_FOUND = True if perl.h & libperl were found
13185 PERL_INCLUDE_PATH = path to where perl.h is found
13186 PERL_LIBRARY = path to libperl
13187 PERL_EXECUTABLE = full path to the perl binary
13188 The minimum required version of Perl can be specified using the stan‐
13190 dard syntax, e.g. find_package(PerlLibs 6.0)
13191 The following variables are also available if needed
13193 (introduced after CMake 2.6.4)
13194 PERL_SITESEARCH = path to the sitesearch install dir (-V:installsitesearch)
13196 PERL_SITEARCH = path to the sitelib install directory (-V:installsitearch)
13197 PERL_SITELIB = path to the sitelib install directory (-V:installsitelib)
13198 PERL_VENDORARCH = path to the vendor arch install directory (-V:installvendorarch)
13199 PERL_VENDORLIB = path to the vendor lib install directory (-V:installvendorlib)
13200 PERL_ARCHLIB = path to the core arch lib install directory (-V:archlib)
13201 PERL_PRIVLIB = path to the core priv lib install directory (-V:privlib)
13202 PERL_UPDATE_ARCHLIB = path to the update arch lib install directory (-V:installarchlib)
13203 PERL_UPDATE_PRIVLIB = path to the update priv lib install directory (-V:installprivlib)
13204 PERL_EXTRA_C_FLAGS = Compilation flags used to build perl
13205 FindPerl
13207 Find perl
13208 this module looks for Perl
13210 PERL_EXECUTABLE - the full path to perl
13212 PERL_FOUND - If false, don't attempt to use perl.
13213 PERL_VERSION_STRING - version of perl found (since CMake 2.8.8)
13214 FindPHP4
13216 Find PHP4
13217 This module finds if PHP4 is installed and determines where the include
13219 files and libraries are. It also determines what the name of the
13220 library is. This code sets the following variables:
13221 PHP4_INCLUDE_PATH = path to where php.h can be found
13223 PHP4_EXECUTABLE = full path to the php4 binary
13224 FindPhysFS
13226 Locate PhysFS library This module defines PHYSFS_LIBRARY, the name of
13227 the library to link against PHYSFS_FOUND, if false, do not try to link
13228 to PHYSFS PHYSFS_INCLUDE_DIR, where to find physfs.h
13229 $PHYSFSDIR is an environment variable that would correspond to the
13231 Created by Eric Wing.
13233 FindPike
13235 Find Pike
13236 This module finds if PIKE is installed and determines where the include
13238 files and libraries are. It also determines what the name of the
13239 library is. This code sets the following variables:
13240 PIKE_INCLUDE_PATH = path to where program.h is found
13242 PIKE_EXECUTABLE = full path to the pike binary
13243 FindPkgConfig
13245 A pkg-config module for CMake.
13246 Finds the pkg-config executable and adds the pkg_get_variable(),
13248 pkg_check_modules() and pkg_search_module() commands. The following
13249 variables will also be set:
13250 PKG_CONFIG_FOUND
13252 if pkg-config executable was found
13253 PKG_CONFIG_EXECUTABLE
13255 pathname of the pkg-config program
13256 PKG_CONFIG_VERSION_STRING
13258 version of pkg-config (since CMake 2.8.8)
13259 pkg_check_modules
13261 Checks for all the given modules, setting a variety of result
13262 variables in the calling scope.
13263 pkg_check_modules(<prefix>
13265 [REQUIRED] [QUIET]
13266 [NO_CMAKE_PATH]
13267 [NO_CMAKE_ENVIRONMENT_PATH]
13268 [IMPORTED_TARGET [GLOBAL]]
13269 <moduleSpec> [<moduleSpec>...])
13270 When the REQUIRED argument is given, the command will fail with
13272 an error if module(s) could not be found.
13273 When the QUIET argument is given, no status messages will be
13275 printed.
13276 By default, if CMAKE_MINIMUM_REQUIRED_VERSION is 3.1 or later,
13278 or if PKG_CONFIG_USE_CMAKE_PREFIX_PATH is set to a boolean True
13279 value, then the CMAKE_PREFIX_PATH, CMAKE_FRAMEWORK_PATH, and
13280 CMAKE_APPBUNDLE_PATH cache and environment variables will be
13281 added to the pkg-config search path. The NO_CMAKE_PATH and
13282 NO_CMAKE_ENVIRONMENT_PATH arguments disable this behavior for
13283 the cache variables and environment variables respectively.
13284 The IMPORTED_TARGET argument will create an imported target
13286 named PkgConfig::<prefix> that can be passed directly as an
13287 argument to target_link_libraries(). The GLOBAL argument will
13288 make the imported target available in global scope.
13289 Each <moduleSpec> can be either a bare module name or it can be
13291 a module name with a version constraint (operators =, <, >, <=
13292 and >= are supported). The following are examples for a module
13293 named foo with various constraints:
13294 · foo matches any version.
13296 · foo<2 only matches versions before 2.
13298 · foo>=3.1 matches any version from 3.1 or later.
13300 · foo=1.2.3 requires that foo must be exactly version 1.2.3.
13302 The following variables may be set upon return. Two sets of
13304 values exist: One for the common case (<XXX> = <prefix>) and
13305 another for the information pkg-config provides when called with
13306 the --static option (<XXX> = <prefix>_STATIC).
13307 <XXX>_FOUND
13309 set to 1 if module(s) exist
13310 <XXX>_LIBRARIES
13312 only the libraries (without the ‘-l’)
13313 <XXX>_LINK_LIBRARIES
13315 the libraries and their absolute paths
13316 <XXX>_LIBRARY_DIRS
13318 the paths of the libraries (without the ‘-L’)
13319 <XXX>_LDFLAGS
13321 all required linker flags
13322 <XXX>_LDFLAGS_OTHER
13324 all other linker flags
13325 <XXX>_INCLUDE_DIRS
13327 the ‘-I’ preprocessor flags (without the ‘-I’)
13328 <XXX>_CFLAGS
13330 all required cflags
13331 <XXX>_CFLAGS_OTHER
13333 the other compiler flags
13334 All but <XXX>_FOUND may be a ;-list if the associated variable
13336 returned from pkg-config has multiple values.
13337 There are some special variables whose prefix depends on the
13339 number of <moduleSpec> given. When there is only one <module‐
13340 Spec>, <YYY> will simply be <prefix>, but if two or more <mod‐
13341 uleSpec> items are given, <YYY> will be <prefix>_<moduleName>.
13342 <YYY>_VERSION
13344 version of the module
13345 <YYY>_PREFIX
13347 prefix directory of the module
13348 <YYY>_INCLUDEDIR
13350 include directory of the module
13351 <YYY>_LIBDIR
13353 lib directory of the module
13354 Examples:
13356 pkg_check_modules (GLIB2 glib-2.0)
13358 Looks for any version of glib2. If found, the output variable
13360 GLIB2_VERSION will hold the actual version found.
13361 pkg_check_modules (GLIB2 glib-2.0>=2.10)
13363 Looks for at least version 2.10 of glib2. If found, the output
13365 variable GLIB2_VERSION will hold the actual version found.
13366 pkg_check_modules (FOO glib-2.0>=2.10 gtk+-2.0)
13368 Looks for both glib2-2.0 (at least version 2.10) and any version
13370 of gtk2+-2.0. Only if both are found will FOO be considered
13371 found. The FOO_glib-2.0_VERSION and FOO_gtk+-2.0_VERSION vari‐
13372 ables will be set to their respective found module versions.
13373 pkg_check_modules (XRENDER REQUIRED xrender)
13375 Requires any version of xrender. Example output variables set
13377 by a successful call:
13378 XRENDER_LIBRARIES=Xrender;X11
13380 XRENDER_STATIC_LIBRARIES=Xrender;X11;pthread;Xau;Xdmcp
13381 pkg_search_module
13383 The behavior of this command is the same as pkg_check_modules(),
13384 except that rather than checking for all the specified modules,
13385 it searches for just the first successful match.
13386 pkg_search_module(<prefix>
13388 [REQUIRED] [QUIET]
13389 [NO_CMAKE_PATH]
13390 [NO_CMAKE_ENVIRONMENT_PATH]
13391 [IMPORTED_TARGET [GLOBAL]]
13392 <moduleSpec> [<moduleSpec>...])
13393 If a module is found, the <prefix>_MODULE_NAME variable will
13395 contain the name of the matching module. This variable can be
13396 used if you need to run pkg_get_variable().
13397 Example:
13399 pkg_search_module (BAR libxml-2.0 libxml2 libxml>=2)
13401 pkg_get_variable
13403 Retrieves the value of a pkg-config variable varName and stores
13404 it in the result variable resultVar in the calling scope.
13405 pkg_get_variable(<resultVar> <moduleName> <varName>)
13407 If pkg-config returns multiple values for the specified vari‐
13409 able, resultVar will contain a ;-list.
13410 For example:
13412 pkg_get_variable(GI_GIRDIR gobject-introspection-1.0 girdir)
13414 Variables Affecting Behavior
13416 PKG_CONFIG_EXECUTABLE
13417 This can be set to the path of the pkg-config executable. If
13418 not provided, it will be set by the module as a result of call‐
13419 ing find_program() internally. The PKG_CONFIG environment vari‐
13420 able can be used as a hint.
13421 PKG_CONFIG_USE_CMAKE_PREFIX_PATH
13423 Specifies whether pkg_check_modules() and pkg_search_module()
13424 should add the paths in the CMAKE_PREFIX_PATH, CMAKE_FRAME‐
13425 WORK_PATH and CMAKE_APPBUNDLE_PATH cache and environment vari‐
13426 ables to the pkg-config search path.
13427 If this variable is not set, this behavior is enabled by default
13429 if CMAKE_MINIMUM_REQUIRED_VERSION is 3.1 or later, disabled oth‐
13430 erwise.
13431 FindPNG
13433 Find libpng, the official reference library for the PNG image format.
13434 Imported targets
13436 This module defines the following IMPORTED target:
13437 PNG::PNG
13439 The libpng library, if found.
13440 Result variables
13442 This module will set the following variables in your project:
13443 PNG_INCLUDE_DIRS
13445 where to find png.h, etc.
13446 PNG_LIBRARIES
13448 the libraries to link against to use PNG.
13449 PNG_DEFINITIONS
13451 You should add_definitions(${PNG_DEFINITIONS}) before compiling
13452 code that includes png library files.
13453 PNG_FOUND
13455 If false, do not try to use PNG.
13456 PNG_VERSION_STRING
13458 the version of the PNG library found (since CMake 2.8.8)
13459 Obsolete variables
13461 The following variables may also be set, for backwards compatibility:
13462 PNG_LIBRARY
13464 where to find the PNG library.
13465 PNG_INCLUDE_DIR
13467 where to find the PNG headers (same as PNG_INCLUDE_DIRS)
13468 Since PNG depends on the ZLib compression library, none of the above
13470 will be defined unless ZLib can be found.
13471 FindPostgreSQL
13473 Find the PostgreSQL installation.
13474 IMPORTED Targets
13476 This module defines IMPORTED target PostgreSQL::PostgreSQL if Post‐
13477 greSQL has been found.
13478 Result Variables
13480 This module will set the following variables in your project:
13481 PostgreSQL_FOUND
13483 True if PostgreSQL is found.
13484 PostgreSQL_LIBRARIES
13486 the PostgreSQL libraries needed for linking
13487 PostgreSQL_INCLUDE_DIRS
13489 the directories of the PostgreSQL headers
13490 PostgreSQL_LIBRARY_DIRS
13492 the link directories for PostgreSQL libraries
13493 PostgreSQL_VERSION_STRING
13495 the version of PostgreSQL found
13496 FindProducer
13498 Though Producer isn’t directly part of OpenSceneGraph, its primary user
13499 is OSG so I consider this part of the Findosg* suite used to find Open‐
13500 SceneGraph components. You’ll notice that I accept OSGDIR as an envi‐
13501 ronment path.
13502 Each component is separate and you must opt in to each module. You
13504 must also opt into OpenGL (and OpenThreads?) as these modules won’t do
13505 it for you. This is to allow you control over your own system piece by
13506 piece in case you need to opt out of certain components or change the
13507 Find behavior for a particular module (perhaps because the default
13508 FindOpenGL.cmake module doesn’t work with your system as an example).
13509 If you want to use a more convenient module that includes everything,
13510 use the FindOpenSceneGraph.cmake instead of the Findosg*.cmake modules.
13511 Locate Producer This module defines PRODUCER_LIBRARY PRODUCER_FOUND, if
13513 false, do not try to link to Producer PRODUCER_INCLUDE_DIR, where to
13514 find the headers
13515 $PRODUCER_DIR is an environment variable that would correspond to the
13517 Created by Eric Wing.
13519 FindProtobuf
13521 Locate and configure the Google Protocol Buffers library.
13522 The following variables can be set and are optional:
13524 Protobuf_SRC_ROOT_FOLDER
13526 When compiling with MSVC, if this cache variable is set the pro‐
13527 tobuf-default VS project build locations (vsprojects/Debug and
13528 vsprojects/Release or vsprojects/x64/Debug and vspro‐
13529 jects/x64/Release) will be searched for libraries and binaries.
13530 Protobuf_IMPORT_DIRS
13532 List of additional directories to be searched for imported
13533 .proto files.
13534 Protobuf_DEBUG
13536 Show debug messages.
13537 Protobuf_USE_STATIC_LIBS
13539 Set to ON to force the use of the static libraries. Default is
13540 OFF.
13541 Defines the following variables:
13543 Protobuf_FOUND
13545 Found the Google Protocol Buffers library (libprotobuf & header
13546 files)
13547 Protobuf_VERSION
13549 Version of package found.
13550 Protobuf_INCLUDE_DIRS
13552 Include directories for Google Protocol Buffers
13553 Protobuf_LIBRARIES
13555 The protobuf libraries
13556 Protobuf_PROTOC_LIBRARIES
13558 The protoc libraries
13559 Protobuf_LITE_LIBRARIES
13561 The protobuf-lite libraries
13562 The following IMPORTED targets are also defined:
13564 protobuf::libprotobuf
13566 The protobuf library.
13567 protobuf::libprotobuf-lite
13569 The protobuf lite library.
13570 protobuf::libprotoc
13572 The protoc library.
13573 protobuf::protoc
13575 The protoc compiler.
13576 The following cache variables are also available to set or use:
13578 Protobuf_LIBRARY
13580 The protobuf library
13581 Protobuf_PROTOC_LIBRARY
13583 The protoc library
13584 Protobuf_INCLUDE_DIR
13586 The include directory for protocol buffers
13587 Protobuf_PROTOC_EXECUTABLE
13589 The protoc compiler
13590 Protobuf_LIBRARY_DEBUG
13592 The protobuf library (debug)
13593 Protobuf_PROTOC_LIBRARY_DEBUG
13595 The protoc library (debug)
13596 Protobuf_LITE_LIBRARY
13598 The protobuf lite library
13599 Protobuf_LITE_LIBRARY_DEBUG
13601 The protobuf lite library (debug)
13602 Example:
13604 find_package(Protobuf REQUIRED)
13606 include_directories(${Protobuf_INCLUDE_DIRS})
13607 include_directories(${CMAKE_CURRENT_BINARY_DIR})
13608 protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS foo.proto)
13609 protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS EXPORT_MACRO DLL_EXPORT foo.proto)
13610 protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS DESCRIPTORS PROTO_DESCS foo.proto)
13611 protobuf_generate_python(PROTO_PY foo.proto)
13612 add_executable(bar bar.cc ${PROTO_SRCS} ${PROTO_HDRS})
13613 target_link_libraries(bar ${Protobuf_LIBRARIES})
13614 NOTE:
13616 The protobuf_generate_cpp and protobuf_generate_python functions and
13617 add_executable() or add_library() calls only work properly within
13618 the same directory.
13619 protobuf_generate_cpp
13621 Add custom commands to process .proto files to C++:
13622 protobuf_generate_cpp (<SRCS> <HDRS>
13624 [DESCRIPTORS <DESC>] [EXPORT_MACRO <MACRO>] [<ARGN>...])
13625 SRCS Variable to define with autogenerated source files
13627 HDRS Variable to define with autogenerated header files
13629 DESCRIPTORS
13631 Variable to define with autogenerated descriptor files,
13632 if requested.
13633 EXPORT_MACRO
13635 is a macro which should expand to __declspec(dllexport)
13636 or __declspec(dllimport) depending on what is being com‐
13637 piled.
13638 ARGN .proto files
13640 protobuf_generate_python
13642 Add custom commands to process .proto files to Python:
13643 protobuf_generate_python (<PY> [<ARGN>...])
13645 PY Variable to define with autogenerated Python files
13647 ARGN .proto filess
13649 FindPython
13651 Find Python interpreter, compiler and development environment (include
13652 directories and libraries).
13653 The following components are supported:
13655 · Interpreter: search for Python interpreter.
13657 · Compiler: search for Python compiler. Only offered by IronPython.
13659 · Development: search for development artifacts (include directories
13661 and libraries).
13662 · NumPy: search for NumPy include directories.
13664 If no COMPONENTS are specified, Interpreter is assumed.
13666 To ensure consistent versions between components Interpreter, Compiler,
13668 Development and NumPy, specify all components at the same time:
13669 find_package (Python COMPONENTS Interpreter Development)
13671 This module looks preferably for version 3 of Python. If not found,
13673 version 2 is searched. To manage concurrent versions 3 and 2 of
13674 Python, use FindPython3 and FindPython2 modules rather than this one.
13675 NOTE:
13677 If components Interpreter and Development are both specified, this
13678 module search only for interpreter with same platform architecture
13679 as the one defined by CMake configuration. This contraint does not
13680 apply if only Interpreter component is specified.
13681 Imported Targets
13683 This module defines the following Imported Targets (when CMAKE_ROLE is
13684 PROJECT):
13685 Python::Interpreter
13687 Python interpreter. Target defined if component Interpreter is
13688 found.
13689 Python::Compiler
13691 Python compiler. Target defined if component Compiler is found.
13692 Python::Python
13694 Python library for Python embedding. Target defined if component
13695 Development is found.
13696 Python::Module
13698 Python library for Python module. Target defined if component
13699 Development is found.
13700 Python::NumPy
13702 NumPy Python library. Target defined if component NumPy is
13703 found.
13704 Result Variables
13706 This module will set the following variables in your project (see Stan‐
13707 dard Variable Names):
13708 Python_FOUND
13710 System has the Python requested components.
13711 Python_Interpreter_FOUND
13713 System has the Python interpreter.
13714 Python_EXECUTABLE
13716 Path to the Python interpreter.
13717 Python_INTERPRETER_ID
13719 A short string unique to the interpreter. Possible values
13721 include:
13722 · Python
13724 · ActivePython
13726 · Anaconda
13728 · Canopy
13730 · IronPython
13732 Python_STDLIB
13734 Standard platform independent installation directory.
13735 Information returned by distutils.syscon‐
13737 fig.get_python_lib(plat_specific=False,standard_lib=True).
13738 Python_STDARCH
13740 Standard platform dependent installation directory.
13741 Information returned by distutils.syscon‐
13743 fig.get_python_lib(plat_specific=True,standard_lib=True).
13744 Python_SITELIB
13746 Third-party platform independent installation directory.
13747 Information returned by distutils.syscon‐
13749 fig.get_python_lib(plat_specific=False,standard_lib=False).
13750 Python_SITEARCH
13752 Third-party platform dependent installation directory.
13753 Information returned by distutils.syscon‐
13755 fig.get_python_lib(plat_specific=True,standard_lib=False).
13756 Python_SOABI
13758 Extension suffix for modules.
13759 Information returned by distutils.sysconfig.get_con‐
13761 fig_flag('SOABI') or computed from distutils.sysconfig.get_con‐
13762 fig_flag('EXT_SUFFIX') or python-config --extension-suffix.
13763 Python_Compiler_FOUND
13765 System has the Python compiler.
13766 Python_COMPILER
13768 Path to the Python compiler. Only offered by IronPython.
13769 Python_COMPILER_ID
13771 A short string unique to the compiler. Possible values include:
13773 · IronPython
13775 Python_Development_FOUND
13777 System has the Python development artifacts.
13778 Python_INCLUDE_DIRS
13780 The Python include directories.
13781 Python_LIBRARIES
13783 The Python libraries.
13784 Python_LIBRARY_DIRS
13786 The Python library directories.
13787 Python_RUNTIME_LIBRARY_DIRS
13789 The Python runtime library directories.
13790 Python_VERSION
13792 Python version.
13793 Python_VERSION_MAJOR
13795 Python major version.
13796 Python_VERSION_MINOR
13798 Python minor version.
13799 Python_VERSION_PATCH
13801 Python patch version.
13802 Python_NumPy_FOUND
13804 System has the NumPy.
13805 Python_NumPy_INCLUDE_DIRS
13807 The NumPy include directries.
13808 Python_NumPy_VERSION
13810 The NumPy version.
13811 Hints
13813 Python_ROOT_DIR
13814 Define the root directory of a Python installation.
13815 Python_USE_STATIC_LIBS
13817 · If not defined, search for shared libraries and static
13819 libraries in that order.
13820 · If set to TRUE, search only for static libraries.
13822 · If set to FALSE, search only for shared libraries.
13824 Python_FIND_ABI
13826 This variable defines which ABIs, as defined in PEP 3149, should
13827 be searched.
13828 NOTE:
13830 This hint will be honored only when searched for Python ver‐
13831 sion 3.
13832 NOTE:
13834 If Python_FIND_ABI is not defined, any ABI will be searched.
13835 The Python_FIND_ABI variable is a 3-tuple specifying, in that
13837 order, pydebug (d), pymalloc (m) and unicode (u) flags. Each
13838 element can be set to one of the following:
13839 · ON: Corresponding flag is selected.
13841 · OFF: Corresponding flag is not selected.
13843 · ANY: The two posibilties (ON and OFF) will be searched.
13845 From this 3-tuple, various ABIs will be searched starting from
13847 the most specialized to the most general. Moreover, debug ver‐
13848 sions will be searched after non-debug ones.
13849 For example, if we have:
13851 set (Python_FIND_ABI "ON" "ANY" "ANY")
13853 The following flags combinations will be appended, in that
13855 order, to the artifact names: dmu, dm, du, and d.
13856 And to search any possible ABIs:
13858 set (Python_FIND_ABI "ANY" "ANY" "ANY")
13860 The following combinations, in that order, will be used: mu, m,
13862 u, <empty>, dmu, dm, du and d.
13863 NOTE:
13865 This hint is useful only on POSIX systems. So, on Windows
13866 systems, when Python_FIND_ABI is defined, Python distribu‐
13867 tions from python.org will be found only if value for each
13868 flag is OFF or ANY.
13869 Python_FIND_STRATEGY
13871 This variable defines how lookup will be done. The
13872 Python_FIND_STRATEGY variable can be set to one of the follow‐
13873 ing:
13874 · VERSION: Try to find the most recent version in all specified
13876 locations. This is the default if policy CMP0094 is undefined
13877 or set to OLD.
13878 · LOCATION: Stops lookup as soon as a version satisfying version
13880 constraints is founded. This is the default if policy CMP0094
13881 is set to NEW.
13882 Python_FIND_REGISTRY
13884 On Windows the Python_FIND_REGISTRY variable determine the order
13885 of preference between registry and environment variables. the
13886 Python_FIND_REGISTRY variable can be set to one of the follow‐
13887 ing:
13888 · FIRST: Try to use registry before environment variables. This
13890 is the default.
13891 · LAST: Try to use registry after environment variables.
13893 · NEVER: Never try to use registry.
13895 Python_FIND_FRAMEWORK
13897 On macOS the Python_FIND_FRAMEWORK variable determine the order
13898 of preference between Apple-style and unix-style package compo‐
13899 nents. This variable can take same values as CMAKE_FIND_FRAME‐
13900 WORK variable.
13901 NOTE:
13903 Value ONLY is not supported so FIRST will be used instead.
13904 If Python_FIND_FRAMEWORK is not defined, CMAKE_FIND_FRAMEWORK
13906 variable will be used, if any.
13907 Python_FIND_VIRTUALENV
13909 This variable defines the handling of virtual environments man‐
13910 aged by virtualenv or conda. It is meaningful only when a vir‐
13911 tual environment is active (i.e. the activate script has been
13912 evaluated). In this case, it takes precedence over
13913 Python_FIND_REGISTRY and CMAKE_FIND_FRAMEWORK variables. The
13914 Python_FIND_VIRTUALENV variable can be set to one of the follow‐
13915 ing:
13916 · FIRST: The virtual environment is used before any other stan‐
13918 dard paths to look-up for the interpreter. This is the
13919 default.
13920 · ONLY: Only the virtual environment is used to look-up for the
13922 interpreter.
13923 · STANDARD: The virtual environment is not used to look-up for
13925 the interpreter. In this case, variable Python_FIND_REGISTRY
13926 (Windows) or CMAKE_FIND_FRAMEWORK (macOS) can be set with
13927 value LAST or NEVER to select preferably the interpreter from
13928 the virtual environment.
13929 NOTE:
13931 If the component Development is requested, it is strongly
13932 recommended to also include the component Interpreter to get
13933 expected result.
13934 Artifacts Specification
13936 To solve special cases, it is possible to specify directly the arti‐
13937 facts by setting the following variables:
13938 Python_EXECUTABLE
13940 The path to the interpreter.
13941 Python_COMPILER
13943 The path to the compiler.
13944 Python_LIBRARY
13946 The path to the library. It will be used to compute the vari‐
13947 ables Python_LIBRARIES, Python_LIBRAY_DIRS and Python_RUN‐
13948 TIME_LIBRARY_DIRS.
13949 Python_INCLUDE_DIR
13951 The path to the directory of the Python headers. It will be used
13952 to compute the variable Python_INCLUDE_DIRS.
13953 Python_NumPy_INCLUDE_DIR
13955 The path to the directory of the NumPy headers. It will be used
13956 to compute the variable Python_NumPy_INCLUDE_DIRS.
13957 NOTE:
13959 All paths must be absolute. Any artifact specified with a relative
13960 path will be ignored.
13961 NOTE:
13963 When an artifact is specified, all HINTS will be ignored and no
13964 search will be performed for this artifact.
13965 If more than one artifact is specified, it is the user’s respons‐
13967 ability to ensure the consistency of the various artifacts.
13968 Commands
13970 This module defines the command Python_add_library (when CMAKE_ROLE is
13971 PROJECT), which has the same semantics as add_library() and adds a
13972 dependency to target Python::Python or, when library type is MODULE, to
13973 target Python::Module and takes care of Python module naming rules:
13974 Python_add_library (<name> [STATIC | SHARED | MODULE [WITH_SOABI]]
13976 <source1> [<source2> ...])
13977 If the library type is not specified, MODULE is assumed.
13979 For MODULE library type, if option WITH_SOABI is specified, the module
13981 suffix will include the Python_SOABI value, if any.
13982 FindPython2
13984 Find Python 2 interpreter, compiler and development environment
13985 (include directories and libraries).
13986 The following components are supported:
13988 · Interpreter: search for Python 2 interpreter
13990 · Compiler: search for Python 2 compiler. Only offered by IronPython.
13992 · Development: search for development artifacts (include directories
13994 and libraries)
13995 · NumPy: search for NumPy include directories.
13997 If no COMPONENTS are specified, Interpreter is assumed.
13999 To ensure consistent versions between components Interpreter, Compiler,
14001 Development and NumPy, specify all components at the same time:
14002 find_package (Python2 COMPONENTS Interpreter Development)
14004 This module looks only for version 2 of Python. This module can be used
14006 concurrently with FindPython3 module to use both Python versions.
14007 The FindPython module can be used if Python version does not matter for
14009 you.
14010 NOTE:
14012 If components Interpreter and Development are both specified, this
14013 module search only for interpreter with same platform architecture
14014 as the one defined by CMake configuration. This contraint does not
14015 apply if only Interpreter component is specified.
14016 Imported Targets
14018 This module defines the following Imported Targets (when CMAKE_ROLE is
14019 PROJECT):
14020 Python2::Interpreter
14022 Python 2 interpreter. Target defined if component Interpreter is
14023 found.
14024 Python2::Compiler
14026 Python 2 compiler. Target defined if component Compiler is
14027 found.
14028 Python2::Python
14030 Python 2 library for Python embedding. Target defined if compo‐
14031 nent Development is found.
14032 Python2::Module
14034 Python 2 library for Python module. Target defined if component
14035 Development is found.
14036 Python2::NumPy
14038 NumPy library for Python 2. Target defined if component NumPy is
14039 found.
14040 Result Variables
14042 This module will set the following variables in your project (see Stan‐
14043 dard Variable Names):
14044 Python2_FOUND
14046 System has the Python 2 requested components.
14047 Python2_Interpreter_FOUND
14049 System has the Python 2 interpreter.
14050 Python2_EXECUTABLE
14052 Path to the Python 2 interpreter.
14053 Python2_INTERPRETER_ID
14055 A short string unique to the interpreter. Possible values
14057 include:
14058 · Python
14060 · ActivePython
14062 · Anaconda
14064 · Canopy
14066 · IronPython
14068 Python2_STDLIB
14070 Standard platform independent installation directory.
14071 Information returned by distutils.syscon‐
14073 fig.get_python_lib(plat_specific=False,standard_lib=True).
14074 Python2_STDARCH
14076 Standard platform dependent installation directory.
14077 Information returned by distutils.syscon‐
14079 fig.get_python_lib(plat_specific=True,standard_lib=True).
14080 Python2_SITELIB
14082 Third-party platform independent installation directory.
14083 Information returned by distutils.syscon‐
14085 fig.get_python_lib(plat_specific=False,standard_lib=False).
14086 Python2_SITEARCH
14088 Third-party platform dependent installation directory.
14089 Information returned by distutils.syscon‐
14091 fig.get_python_lib(plat_specific=True,standard_lib=False).
14092 Python2_Compiler_FOUND
14094 System has the Python 2 compiler.
14095 Python2_COMPILER
14097 Path to the Python 2 compiler. Only offered by IronPython.
14098 Python2_COMPILER_ID
14100 A short string unique to the compiler. Possible values include:
14102 · IronPython
14104 Python2_Development_FOUND
14106 System has the Python 2 development artifacts.
14107 Python2_INCLUDE_DIRS
14109 The Python 2 include directories.
14110 Python2_LIBRARIES
14112 The Python 2 libraries.
14113 Python2_LIBRARY_DIRS
14115 The Python 2 library directories.
14116 Python2_RUNTIME_LIBRARY_DIRS
14118 The Python 2 runtime library directories.
14119 Python2_VERSION
14121 Python 2 version.
14122 Python2_VERSION_MAJOR
14124 Python 2 major version.
14125 Python2_VERSION_MINOR
14127 Python 2 minor version.
14128 Python2_VERSION_PATCH
14130 Python 2 patch version.
14131 Python2_NumPy_FOUND
14133 System has the NumPy.
14134 Python2_NumPy_INCLUDE_DIRS
14136 The NumPy include directries.
14137 Python2_NumPy_VERSION
14139 The NumPy version.
14140 Hints
14142 Python2_ROOT_DIR
14143 Define the root directory of a Python 2 installation.
14144 Python2_USE_STATIC_LIBS
14146 · If not defined, search for shared libraries and static
14148 libraries in that order.
14149 · If set to TRUE, search only for static libraries.
14151 · If set to FALSE, search only for shared libraries.
14153 Python2_FIND_STRATEGY
14155 This variable defines how lookup will be done. The
14156 Python2_FIND_STRATEGY variable can be set to one of the follow‐
14157 ing:
14158 · VERSION: Try to find the most recent version in all specified
14160 locations. This is the default if policy CMP0094 is undefined
14161 or set to OLD.
14162 · LOCATION: Stops lookup as soon as a version satisfying version
14164 constraints is founded. This is the default if policy CMP0094
14165 is set to NEW.
14166 Python2_FIND_REGISTRY
14168 On Windows the Python2_FIND_REGISTRY variable determine the
14169 order of preference between registry and environment variables.
14170 the Python2_FIND_REGISTRY variable can be set to one of the fol‐
14171 lowing:
14172 · FIRST: Try to use registry before environment variables. This
14174 is the default.
14175 · LAST: Try to use registry after environment variables.
14177 · NEVER: Never try to use registry.
14179 Python2_FIND_FRAMEWORK
14181 On macOS the Python2_FIND_FRAMEWORK variable determine the order
14182 of preference between Apple-style and unix-style package compo‐
14183 nents. This variable can take same values as CMAKE_FIND_FRAME‐
14184 WORK variable.
14185 NOTE:
14187 Value ONLY is not supported so FIRST will be used instead.
14188 If Python2_FIND_FRAMEWORK is not defined, CMAKE_FIND_FRAMEWORK
14190 variable will be used, if any.
14191 Python2_FIND_VIRTUALENV
14193 This variable defines the handling of virtual environments man‐
14194 aged by virtualenv or conda. It is meaningful only when a vir‐
14195 tual environment is active (i.e. the activate script has been
14196 evaluated). In this case, it takes precedence over
14197 Python2_FIND_REGISTRY and CMAKE_FIND_FRAMEWORK variables. The
14198 Python2_FIND_VIRTUALENV variable can be set to one of the fol‐
14199 lowing:
14200 · FIRST: The virtual environment is used before any other stan‐
14202 dard paths to look-up for the interpreter. This is the
14203 default.
14204 · ONLY: Only the virtual environment is used to look-up for the
14206 interpreter.
14207 · STANDARD: The virtual environment is not used to look-up for
14209 the interpreter. In this case, variable Python2_FIND_REGISTRY
14210 (Windows) or CMAKE_FIND_FRAMEWORK (macOS) can be set with
14211 value LAST or NEVER to select preferably the interpreter from
14212 the virtual environment.
14213 NOTE:
14215 If the component Development is requested, it is strongly
14216 recommended to also include the component Interpreter to get
14217 expected result.
14218 Artifacts Specification
14220 To solve special cases, it is possible to specify directly the arti‐
14221 facts by setting the following variables:
14222 Python2_EXECUTABLE
14224 The path to the interpreter.
14225 Python2_COMPILER
14227 The path to the compiler.
14228 Python2_LIBRARY
14230 The path to the library. It will be used to compute the vari‐
14231 ables Python2_LIBRARIES, Python2_LIBRAY_DIRS and Python2_RUN‐
14232 TIME_LIBRARY_DIRS.
14233 Python2_INCLUDE_DIR
14235 The path to the directory of the Python headers. It will be used
14236 to compute the variable Python2_INCLUDE_DIRS.
14237 Python2_NumPy_INCLUDE_DIR
14239 The path to the directory of the NumPy headers. It will be used
14240 to compute the variable Python2_NumPy_INCLUDE_DIRS.
14241 NOTE:
14243 All paths must be absolute. Any artifact specified with a relative
14244 path will be ignored.
14245 NOTE:
14247 When an artifact is specified, all HINTS will be ignored and no
14248 search will be performed for this artifact.
14249 If more than one artifact is specified, it is the user’s respons‐
14251 ability to ensure the consistency of the various artifacts.
14252 Commands
14254 This module defines the command Python2_add_library (when CMAKE_ROLE is
14255 PROJECT), which has the same semantics as add_library() and adds a
14256 dependency to target Python2::Python or, when library type is MODULE,
14257 to target Python2::Module and takes care of Python module naming rules:
14258 Python2_add_library (<name> [STATIC | SHARED | MODULE]
14260 <source1> [<source2> ...])
14261 If library type is not specified, MODULE is assumed.
14263 FindPython3
14265 Find Python 3 interpreter, compiler and development environment
14266 (include directories and libraries).
14267 The following components are supported:
14269 · Interpreter: search for Python 3 interpreter
14271 · Compiler: search for Python 3 compiler. Only offered by IronPython.
14273 · Development: search for development artifacts (include directories
14275 and libraries)
14276 · NumPy: search for NumPy include directories.
14278 If no COMPONENTS are specified, Interpreter is assumed.
14280 To ensure consistent versions between components Interpreter, Compiler,
14282 Development and NumPy, specify all components at the same time:
14283 find_package (Python3 COMPONENTS Interpreter Development)
14285 This module looks only for version 3 of Python. This module can be used
14287 concurrently with FindPython2 module to use both Python versions.
14288 The FindPython module can be used if Python version does not matter for
14290 you.
14291 NOTE:
14293 If components Interpreter and Development are both specified, this
14294 module search only for interpreter with same platform architecture
14295 as the one defined by CMake configuration. This contraint does not
14296 apply if only Interpreter component is specified.
14297 Imported Targets
14299 This module defines the following Imported Targets (when CMAKE_ROLE is
14300 PROJECT):
14301 Python3::Interpreter
14303 Python 3 interpreter. Target defined if component Interpreter is
14304 found.
14305 Python3::Compiler
14307 Python 3 compiler. Target defined if component Compiler is
14308 found.
14309 Python3::Python
14311 Python 3 library for Python embedding. Target defined if compo‐
14312 nent Development is found.
14313 Python3::Module
14315 Python 3 library for Python module. Target defined if component
14316 Development is found.
14317 Python3::NumPy
14319 NumPy library for Python 3. Target defined if component NumPy is
14320 found.
14321 Result Variables
14323 This module will set the following variables in your project (see Stan‐
14324 dard Variable Names):
14325 Python3_FOUND
14327 System has the Python 3 requested components.
14328 Python3_Interpreter_FOUND
14330 System has the Python 3 interpreter.
14331 Python3_EXECUTABLE
14333 Path to the Python 3 interpreter.
14334 Python3_INTERPRETER_ID
14336 A short string unique to the interpreter. Possible values
14338 include:
14339 · Python
14341 · ActivePython
14343 · Anaconda
14345 · Canopy
14347 · IronPython
14349 Python3_STDLIB
14351 Standard platform independent installation directory.
14352 Information returned by distutils.syscon‐
14354 fig.get_python_lib(plat_specific=False,standard_lib=True).
14355 Python3_STDARCH
14357 Standard platform dependent installation directory.
14358 Information returned by distutils.syscon‐
14360 fig.get_python_lib(plat_specific=True,standard_lib=True).
14361 Python3_SITELIB
14363 Third-party platform independent installation directory.
14364 Information returned by distutils.syscon‐
14366 fig.get_python_lib(plat_specific=False,standard_lib=False).
14367 Python3_SITEARCH
14369 Third-party platform dependent installation directory.
14370 Information returned by distutils.syscon‐
14372 fig.get_python_lib(plat_specific=True,standard_lib=False).
14373 Python3_SOABI
14375 Extension suffix for modules.
14376 Information returned by distutils.sysconfig.get_con‐
14378 fig_flag('SOABI') or computed from distutils.sysconfig.get_con‐
14379 fig_flag('EXT_SUFFIX') or python3-config --extension-suffix.
14380 Python3_Compiler_FOUND
14382 System has the Python 3 compiler.
14383 Python3_COMPILER
14385 Path to the Python 3 compiler. Only offered by IronPython.
14386 Python3_COMPILER_ID
14388 A short string unique to the compiler. Possible values include:
14390 · IronPython
14392 Python3_Development_FOUND
14394 System has the Python 3 development artifacts.
14395 Python3_INCLUDE_DIRS
14397 The Python 3 include directories.
14398 Python3_LIBRARIES
14400 The Python 3 libraries.
14401 Python3_LIBRARY_DIRS
14403 The Python 3 library directories.
14404 Python3_RUNTIME_LIBRARY_DIRS
14406 The Python 3 runtime library directories.
14407 Python3_VERSION
14409 Python 3 version.
14410 Python3_VERSION_MAJOR
14412 Python 3 major version.
14413 Python3_VERSION_MINOR
14415 Python 3 minor version.
14416 Python3_VERSION_PATCH
14418 Python 3 patch version.
14419 Python3_NumPy_FOUND
14421 System has the NumPy.
14422 Python3_NumPy_INCLUDE_DIRS
14424 The NumPy include directries.
14425 Python3_NumPy_VERSION
14427 The NumPy version.
14428 Hints
14430 Python3_ROOT_DIR
14431 Define the root directory of a Python 3 installation.
14432 Python3_USE_STATIC_LIBS
14434 · If not defined, search for shared libraries and static
14436 libraries in that order.
14437 · If set to TRUE, search only for static libraries.
14439 · If set to FALSE, search only for shared libraries.
14441 Python3_FIND_ABI
14443 This variable defines which ABIs, as defined in PEP 3149, should
14444 be searched.
14445 NOTE:
14447 If Python3_FIND_ABI is not defined, any ABI will be searched.
14448 The Python3_FIND_ABI variable is a 3-tuple specifying, in that
14450 order, pydebug (d), pymalloc (m) and unicode (u) flags. Each
14451 element can be set to one of the following:
14452 · ON: Corresponding flag is selected.
14454 · OFF: Corresponding flag is not selected.
14456 · ANY: The two posibilties (ON and OFF) will be searched.
14458 From this 3-tuple, various ABIs will be searched starting from
14460 the most specialized to the most general. Moreover, debug ver‐
14461 sions will be searched after non-debug ones.
14462 For example, if we have:
14464 set (Python3_FIND_ABI "ON" "ANY" "ANY")
14466 The following flags combinations will be appended, in that
14468 order, to the artifact names: dmu, dm, du, and d.
14469 And to search any possible ABIs:
14471 set (Python3_FIND_ABI "ANY" "ANY" "ANY")
14473 The following combinations, in that order, will be used: mu, m,
14475 u, <empty>, dmu, dm, du and d.
14476 NOTE:
14478 This hint is useful only on POSIX systems. So, on Windows
14479 systems, when Python3_FIND_ABI is defined, Python distribu‐
14480 tions from python.org will be found only if value for each
14481 flag is OFF or ANY.
14482 Python3_FIND_STRATEGY
14484 This variable defines how lookup will be done. The
14485 Python3_FIND_STRATEGY variable can be set to one of the follow‐
14486 ing:
14487 · VERSION: Try to find the most recent version in all specified
14489 locations. This is the default if policy CMP0094 is undefined
14490 or set to OLD.
14491 · LOCATION: Stops lookup as soon as a version satisfying version
14493 constraints is founded. This is the default if policy CMP0094
14494 is set to NEW.
14495 Python3_FIND_REGISTRY
14497 On Windows the Python3_FIND_REGISTRY variable determine the
14498 order of preference between registry and environment variables.
14499 The Python3_FIND_REGISTRY variable can be set to one of the fol‐
14500 lowing:
14501 · FIRST: Try to use registry before environment variables. This
14503 is the default.
14504 · LAST: Try to use registry after environment variables.
14506 · NEVER: Never try to use registry.
14508 Python3_FIND_FRAMEWORK
14510 On macOS the Python3_FIND_FRAMEWORK variable determine the order
14511 of preference between Apple-style and unix-style package compo‐
14512 nents. This variable can take same values as CMAKE_FIND_FRAME‐
14513 WORK variable.
14514 NOTE:
14516 Value ONLY is not supported so FIRST will be used instead.
14517 If Python3_FIND_FRAMEWORK is not defined, CMAKE_FIND_FRAMEWORK
14519 variable will be used, if any.
14520 Python3_FIND_VIRTUALENV
14522 This variable defines the handling of virtual environments man‐
14523 aged by virtualenv or conda. It is meaningful only when a vir‐
14524 tual environment is active (i.e. the activate script has been
14525 evaluated). In this case, it takes precedence over
14526 Python3_FIND_REGISTRY and CMAKE_FIND_FRAMEWORK variables. The
14527 Python3_FIND_VIRTUALENV variable can be set to one of the fol‐
14528 lowing:
14529 · FIRST: The virtual environment is used before any other stan‐
14531 dard paths to look-up for the interpreter. This is the
14532 default.
14533 · ONLY: Only the virtual environment is used to look-up for the
14535 interpreter.
14536 · STANDARD: The virtual environment is not used to look-up for
14538 the interpreter. In this case, variable Python3_FIND_REGISTRY
14539 (Windows) or CMAKE_FIND_FRAMEWORK (macOS) can be set with
14540 value LAST or NEVER to select preferably the interpreter from
14541 the virtual environment.
14542 NOTE:
14544 If the component Development is requested, it is strongly
14545 recommended to also include the component Interpreter to get
14546 expected result.
14547 Artifacts Specification
14549 To solve special cases, it is possible to specify directly the arti‐
14550 facts by setting the following variables:
14551 Python3_EXECUTABLE
14553 The path to the interpreter.
14554 Python3_COMPILER
14556 The path to the compiler.
14557 Python3_LIBRARY
14559 The path to the library. It will be used to compute the vari‐
14560 ables Python3_LIBRARIES, Python3_LIBRAY_DIRS and Python3_RUN‐
14561 TIME_LIBRARY_DIRS.
14562 Python3_INCLUDE_DIR
14564 The path to the directory of the Python headers. It will be used
14565 to compute the variable Python3_INCLUDE_DIRS.
14566 Python3_NumPy_INCLUDE_DIR
14568 The path to the directory of the NumPy headers. It will be used
14569 to compute the variable Python3_NumPy_INCLUDE_DIRS.
14570 NOTE:
14572 All paths must be absolute. Any artifact specified with a relative
14573 path will be ignored.
14574 NOTE:
14576 When an artifact is specified, all HINTS will be ignored and no
14577 search will be performed for this artifact.
14578 If more than one artifact is specified, it is the user’s respons‐
14580 ability to ensure the consistency of the various artifacts.
14581 Commands
14583 This module defines the command Python3_add_library (when CMAKE_ROLE is
14584 PROJECT), which has the same semantics as add_library() and adds a
14585 dependency to target Python3::Python or, when library type is MODULE,
14586 to target Python3::Module and takes care of Python module naming rules:
14587 Python3_add_library (<name> [STATIC | SHARED | MODULE [WITH_SOABI]]
14589 <source1> [<source2> ...])
14590 If the library type is not specified, MODULE is assumed.
14592 For MODULE library type, if option WITH_SOABI is specified, the module
14594 suffix will include the Python3_SOABI value, if any.
14595 FindQt3
14597 Locate Qt include paths and libraries
14598 This module defines:
14600 QT_INCLUDE_DIR - where to find qt.h, etc.
14602 QT_LIBRARIES - the libraries to link against to use Qt.
14603 QT_DEFINITIONS - definitions to use when
14604 compiling code that uses Qt.
14605 QT_FOUND - If false, don't try to use Qt.
14606 QT_VERSION_STRING - the version of Qt found
14607 If you need the multithreaded version of Qt, set QT_MT_REQUIRED to TRUE
14609 Also defined, but not for general use are:
14611 QT_MOC_EXECUTABLE, where to find the moc tool.
14613 QT_UIC_EXECUTABLE, where to find the uic tool.
14614 QT_QT_LIBRARY, where to find the Qt library.
14615 QT_QTMAIN_LIBRARY, where to find the qtmain
14616 library. This is only required by Qt3 on Windows.
14617 FindQt4
14619 Finding and Using Qt4
14620 This module can be used to find Qt4. The most important issue is that
14621 the Qt4 qmake is available via the system path. This qmake is then
14622 used to detect basically everything else. This module defines a number
14623 of IMPORTED targets, macros and variables.
14624 Typical usage could be something like:
14626 set(CMAKE_AUTOMOC ON)
14628 set(CMAKE_INCLUDE_CURRENT_DIR ON)
14629 find_package(Qt4 4.4.3 REQUIRED QtGui QtXml)
14630 add_executable(myexe main.cpp)
14631 target_link_libraries(myexe Qt4::QtGui Qt4::QtXml)
14632 NOTE:
14634 When using IMPORTED targets, the qtmain.lib static library is auto‐
14635 matically linked on Windows for WIN32 executables. To disable that
14636 globally, set the QT4_NO_LINK_QTMAIN variable before finding Qt4. To
14637 disable that for a particular executable, set the QT4_NO_LINK_QTMAIN
14638 target property to TRUE on the executable.
14639 Qt Build Tools
14641 Qt relies on some bundled tools for code generation, such as moc for
14642 meta-object code generation,``uic`` for widget layout and population,
14643 and rcc for virtual filesystem content generation. These tools may be
14644 automatically invoked by cmake(1) if the appropriate conditions are
14645 met. See cmake-qt(7) for more.
14646 Qt Macros
14648 In some cases it can be necessary or useful to invoke the Qt build
14649 tools in a more-manual way. Several macros are available to add targets
14650 for such uses.
14651 macro QT4_WRAP_CPP(outfiles inputfile ... [TARGET tgt] OPTIONS ...)
14653 create moc code from a list of files containing Qt class with
14654 the Q_OBJECT declaration. Per-directory preprocessor definitions
14655 are also added. If the <tgt> is specified, the
14656 INTERFACE_INCLUDE_DIRECTORIES and INTERFACE_COMPILE_DEFINITIONS from
14657 the <tgt> are passed to moc. Options may be given to moc, such as
14658 those found when executing "moc -help".
14659 macro QT4_WRAP_UI(outfiles inputfile ... OPTIONS ...)
14661 create code from a list of Qt designer ui files.
14662 Options may be given to uic, such as those found
14663 when executing "uic -help"
14664 macro QT4_ADD_RESOURCES(outfiles inputfile ... OPTIONS ...)
14666 create code from a list of Qt resource files.
14667 Options may be given to rcc, such as those found
14668 when executing "rcc -help"
14669 macro QT4_GENERATE_MOC(inputfile outputfile [TARGET tgt])
14671 creates a rule to run moc on infile and create outfile.
14672 Use this if for some reason QT4_WRAP_CPP() isn't appropriate, e.g.
14673 because you need a custom filename for the moc file or something
14674 similar. If the <tgt> is specified, the
14675 INTERFACE_INCLUDE_DIRECTORIES and INTERFACE_COMPILE_DEFINITIONS from
14676 the <tgt> are passed to moc.
14677 macro QT4_ADD_DBUS_INTERFACE(outfiles interface basename)
14679 Create the interface header and implementation files with the
14680 given basename from the given interface xml file and add it to
14681 the list of sources.
14682 You can pass additional parameters to the qdbusxml2cpp call by setting
14684 properties on the input file:
14685 INCLUDE the given file will be included in the generate interface header
14687 CLASSNAME the generated class is named accordingly
14689 NO_NAMESPACE the generated class is not wrapped in a namespace
14691 macro QT4_ADD_DBUS_INTERFACES(outfiles inputfile ... )
14693 Create the interface header and implementation files
14694 for all listed interface xml files.
14695 The basename will be automatically determined from the name
14696 of the xml file.
14697 The source file properties described for
14699 QT4_ADD_DBUS_INTERFACE also apply here.
14700 macro QT4_ADD_DBUS_ADAPTOR(outfiles xmlfile parentheader parentclassname
14702 [basename] [classname])
14703 create a dbus adaptor (header and implementation file) from the xml file
14704 describing the interface, and add it to the list of sources. The adaptor
14705 forwards the calls to a parent class, defined in parentheader and named
14706 parentclassname. The name of the generated files will be
14707 <basename>adaptor.{cpp,h} where basename defaults to the basename of the
14708 xml file.
14709 If <classname> is provided, then it will be used as the classname of the
14710 adaptor itself.
14711 macro QT4_GENERATE_DBUS_INTERFACE( header [interfacename] OPTIONS ...)
14713 generate the xml interface file from the given header.
14714 If the optional argument interfacename is omitted, the name of the
14715 interface file is constructed from the basename of the header with
14716 the suffix .xml appended.
14717 Options may be given to qdbuscpp2xml, such as those found when
14718 executing "qdbuscpp2xml --help"
14719 macro QT4_CREATE_TRANSLATION( qm_files directories ... sources ...
14721 ts_files ... OPTIONS ...)
14722 out: qm_files
14723 in: directories sources ts_files
14724 options: flags to pass to lupdate, such as -extensions to specify
14725 extensions for a directory scan.
14726 generates commands to create .ts (vie lupdate) and .qm
14727 (via lrelease) - files from directories and/or sources. The ts files are
14728 created and/or updated in the source tree (unless given with full paths).
14729 The qm files are generated in the build tree.
14730 Updating the translations can be done by adding the qm_files
14731 to the source list of your library/executable, so they are
14732 always updated, or by adding a custom target to control when
14733 they get updated/generated.
14734 macro QT4_ADD_TRANSLATION( qm_files ts_files ... )
14736 out: qm_files
14737 in: ts_files
14738 generates commands to create .qm from .ts - files. The generated
14739 filenames can be found in qm_files. The ts_files
14740 must exist and are not updated in any way.
14741 macro QT4_AUTOMOC(sourcefile1 sourcefile2 ... [TARGET tgt])
14743 The qt4_automoc macro is obsolete. Use the CMAKE_AUTOMOC feature instead.
14744 This macro is still experimental.
14745 It can be used to have moc automatically handled.
14746 So if you have the files foo.h and foo.cpp, and in foo.h a
14747 a class uses the Q_OBJECT macro, moc has to run on it. If you don't
14748 want to use QT4_WRAP_CPP() (which is reliable and mature), you can insert
14749 #include "foo.moc"
14750 in foo.cpp and then give foo.cpp as argument to QT4_AUTOMOC(). This will
14751 scan all listed files at cmake-time for such included moc files and if it
14752 finds them cause a rule to be generated to run moc at build time on the
14753 accompanying header file foo.h.
14754 If a source file has the SKIP_AUTOMOC property set it will be ignored by
14755 this macro.
14756 If the <tgt> is specified, the INTERFACE_INCLUDE_DIRECTORIES and
14757 INTERFACE_COMPILE_DEFINITIONS from the <tgt> are passed to moc.
14758 function QT4_USE_MODULES( target [link_type] modules...)
14760 This function is obsolete. Use target_link_libraries with IMPORTED targets
14761 instead.
14762 Make <target> use the <modules> from Qt. Using a Qt module means
14763 to link to the library, add the relevant include directories for the
14764 module, and add the relevant compiler defines for using the module.
14765 Modules are roughly equivalent to components of Qt4, so usage would be
14766 something like:
14767 qt4_use_modules(myexe Core Gui Declarative)
14768 to use QtCore, QtGui and QtDeclarative. The optional <link_type> argument
14769 can be specified as either LINK_PUBLIC or LINK_PRIVATE to specify the
14770 same argument to the target_link_libraries call.
14771 IMPORTED Targets
14773 A particular Qt library may be used by using the corresponding IMPORTED
14774 target with the target_link_libraries() command:
14775 target_link_libraries(myexe Qt4::QtGui Qt4::QtXml)
14777 Using a target in this way causes :cmake(1)` to use the appropriate
14779 include directories and compile definitions for the target when compil‐
14780 ing myexe.
14781 Targets are aware of their dependencies, so for example it is not nec‐
14783 essary to list Qt4::QtCore if another Qt library is listed, and it is
14784 not necessary to list Qt4::QtGui if Qt4::QtDeclarative is listed. Tar‐
14785 gets may be tested for existence in the usual way with the if(TARGET)
14786 command.
14787 The Qt toolkit may contain both debug and release libraries. cmake(1)
14789 will choose the appropriate version based on the build configuration.
14790 Qt4::QtCore
14792 The QtCore target
14793 Qt4::QtGui
14795 The QtGui target
14796 Qt4::Qt3Support
14798 The Qt3Support target
14799 Qt4::QtAssistant
14801 The QtAssistant target
14802 Qt4::QtAssistantClient
14804 The QtAssistantClient target
14805 Qt4::QAxContainer
14807 The QAxContainer target (Windows only)
14808 Qt4::QAxServer
14810 The QAxServer target (Windows only)
14811 Qt4::QtDBus
14813 The QtDBus target
14814 Qt4::QtDeclarative
14816 The QtDeclarative target
14817 Qt4::QtDesigner
14819 The QtDesigner target
14820 Qt4::QtDesignerComponents
14822 The QtDesignerComponents target
14823 Qt4::QtHelp
14825 The QtHelp target
14826 Qt4::QtMotif
14828 The QtMotif target
14829 Qt4::QtMultimedia
14831 The QtMultimedia target
14832 Qt4::QtNetwork
14834 The QtNetwork target
14835 Qt4::QtNsPLugin
14837 The QtNsPLugin target
14838 Qt4::QtOpenGL
14840 The QtOpenGL target
14841 Qt4::QtScript
14843 The QtScript target
14844 Qt4::QtScriptTools
14846 The QtScriptTools target
14847 Qt4::QtSql
14849 The QtSql target
14850 Qt4::QtSvg
14852 The QtSvg target
14853 Qt4::QtTest
14855 The QtTest target
14856 Qt4::QtUiTools
14858 The QtUiTools target
14859 Qt4::QtWebKit
14861 The QtWebKit target
14862 Qt4::QtXml
14864 The QtXml target
14865 Qt4::QtXmlPatterns
14867 The QtXmlPatterns target
14868 Qt4::phonon
14870 The phonon target
14871 Result Variables
14873 Below is a detailed list of variables that FindQt4.cmake sets.
14874 Qt4_FOUND
14876 If false, don’t try to use Qt 4.
14877 QT_FOUND
14879 If false, don’t try to use Qt. This variable is for compatibil‐
14880 ity only.
14881 QT4_FOUND
14883 If false, don’t try to use Qt 4. This variable is for compati‐
14884 bility only.
14885 QT_VERSION_MAJOR
14887 The major version of Qt found.
14888 QT_VERSION_MINOR
14890 The minor version of Qt found.
14891 QT_VERSION_PATCH
14893 The patch version of Qt found.
14894 FindQuickTime
14896 Locate QuickTime This module defines QUICKTIME_LIBRARY QUICKTIME_FOUND,
14897 if false, do not try to link to gdal QUICKTIME_INCLUDE_DIR, where to
14898 find the headers
14899 $QUICKTIME_DIR is an environment variable that would correspond to the
14901 Created by Eric Wing.
14903 FindRTI
14905 Try to find M&S HLA RTI libraries
14906 This module finds if any HLA RTI is installed and locates the standard
14908 RTI include files and libraries.
14909 RTI is a simulation infrastructure standardized by IEEE and SISO. It
14911 has a well defined C++ API that assures that simulation applications
14912 are independent on a particular RTI implementation.
14913 http://en.wikipedia.org/wiki/Run-Time_Infrastructure_(simulation)
14915 This code sets the following variables:
14917 RTI_INCLUDE_DIR = the directory where RTI includes file are found
14919 RTI_LIBRARIES = The libraries to link against to use RTI
14920 RTI_DEFINITIONS = -DRTI_USES_STD_FSTREAM
14921 RTI_FOUND = Set to FALSE if any HLA RTI was not found
14922 Report problems to <certi-devel@nongnu.org>
14924 FindRuby
14926 Find Ruby
14927 This module finds if Ruby is installed and determines where the include
14929 files and libraries are. Ruby 1.8, 1.9, 2.0 and 2.1 are supported.
14930 The minimum required version of Ruby can be specified using the stan‐
14932 dard syntax, e.g. find_package(Ruby 1.8)
14933 It also determines what the name of the library is. This code sets the
14935 following variables:
14936 RUBY_EXECUTABLE
14938 full path to the ruby binary
14939 RUBY_INCLUDE_DIRS
14941 include dirs to be used when using the ruby library
14942 RUBY_LIBRARY
14944 full path to the ruby library
14945 RUBY_VERSION
14947 the version of ruby which was found, e.g. “1.8.7”
14948 RUBY_FOUND
14950 set to true if ruby ws found successfully
14951 Also:
14953 RUBY_INCLUDE_PATH
14955 same as RUBY_INCLUDE_DIRS, only provided for compatibility rea‐
14956 sons, don’t use it
14957 FindSDL_image
14959 Locate SDL_image library
14960 This module defines:
14962 SDL_IMAGE_LIBRARIES, the name of the library to link against
14964 SDL_IMAGE_INCLUDE_DIRS, where to find the headers
14965 SDL_IMAGE_FOUND, if false, do not try to link against
14966 SDL_IMAGE_VERSION_STRING - human-readable string containing the
14967 version of SDL_image
14968 For backward compatibility the following variables are also set:
14970 SDLIMAGE_LIBRARY (same value as SDL_IMAGE_LIBRARIES)
14972 SDLIMAGE_INCLUDE_DIR (same value as SDL_IMAGE_INCLUDE_DIRS)
14973 SDLIMAGE_FOUND (same value as SDL_IMAGE_FOUND)
14974 $SDLDIR is an environment variable that would correspond to the
14976 Created by Eric Wing. This was influenced by the FindSDL.cmake module,
14978 but with modifications to recognize OS X frameworks and additional Unix
14979 paths (FreeBSD, etc).
14980 FindSDL_mixer
14982 Locate SDL_mixer library
14983 This module defines:
14985 SDL_MIXER_LIBRARIES, the name of the library to link against
14987 SDL_MIXER_INCLUDE_DIRS, where to find the headers
14988 SDL_MIXER_FOUND, if false, do not try to link against
14989 SDL_MIXER_VERSION_STRING - human-readable string containing the
14990 version of SDL_mixer
14991 For backward compatibility the following variables are also set:
14993 SDLMIXER_LIBRARY (same value as SDL_MIXER_LIBRARIES)
14995 SDLMIXER_INCLUDE_DIR (same value as SDL_MIXER_INCLUDE_DIRS)
14996 SDLMIXER_FOUND (same value as SDL_MIXER_FOUND)
14997 $SDLDIR is an environment variable that would correspond to the
14999 Created by Eric Wing. This was influenced by the FindSDL.cmake module,
15001 but with modifications to recognize OS X frameworks and additional Unix
15002 paths (FreeBSD, etc).
15003 FindSDL_net
15005 Locate SDL_net library
15006 This module defines:
15008 SDL_NET_LIBRARIES, the name of the library to link against
15010 SDL_NET_INCLUDE_DIRS, where to find the headers
15011 SDL_NET_FOUND, if false, do not try to link against
15012 SDL_NET_VERSION_STRING - human-readable string containing the version of SDL_net
15013 For backward compatibility the following variables are also set:
15015 SDLNET_LIBRARY (same value as SDL_NET_LIBRARIES)
15017 SDLNET_INCLUDE_DIR (same value as SDL_NET_INCLUDE_DIRS)
15018 SDLNET_FOUND (same value as SDL_NET_FOUND)
15019 $SDLDIR is an environment variable that would correspond to the
15021 Created by Eric Wing. This was influenced by the FindSDL.cmake module,
15023 but with modifications to recognize OS X frameworks and additional Unix
15024 paths (FreeBSD, etc).
15025 FindSDL
15027 Locate SDL library
15028 This module defines
15030 SDL_LIBRARY, the name of the library to link against
15032 SDL_FOUND, if false, do not try to link to SDL
15033 SDL_INCLUDE_DIR, where to find SDL.h
15034 SDL_VERSION_STRING, human-readable string containing the version of SDL
15035 This module responds to the flag:
15037 SDL_BUILDING_LIBRARY
15039 If this is defined, then no SDL_main will be linked in because
15040 only applications need main().
15041 Otherwise, it is assumed you are building an application and this
15042 module will attempt to locate and set the proper link flags
15043 as part of the returned SDL_LIBRARY variable.
15044 Don’t forget to include SDLmain.h and SDLmain.m your project for the OS
15046 X framework based version. (Other versions link to -lSDLmain which
15047 this module will try to find on your behalf.) Also for OS X, this mod‐
15048 ule will automatically add the -framework Cocoa on your behalf.
15049 Additional Note: If you see an empty SDL_LIBRARY_TEMP in your configu‐
15051 ration and no SDL_LIBRARY, it means CMake did not find your SDL library
15052 (SDL.dll, libsdl.so, SDL.framework, etc). Set SDL_LIBRARY_TEMP to
15053 point to your SDL library, and configure again. Similarly, if you see
15054 an empty SDLMAIN_LIBRARY, you should set this value as appropriate.
15055 These values are used to generate the final SDL_LIBRARY variable, but
15056 when these values are unset, SDL_LIBRARY does not get created.
15057 $SDLDIR is an environment variable that would correspond to the
15059 Modified by Eric Wing. Added code to assist with automated building by
15061 using environmental variables and providing a more controlled/consis‐
15062 tent search behavior. Added new modifications to recognize OS X frame‐
15063 works and additional Unix paths (FreeBSD, etc). Also corrected the
15064 header search path to follow “proper” SDL guidelines. Added a search
15065 for SDLmain which is needed by some platforms. Added a search for
15066 threads which is needed by some platforms. Added needed compile
15067 switches for MinGW.
15068 On OSX, this will prefer the Framework version (if found) over others.
15070 People will have to manually change the cache values of SDL_LIBRARY to
15071 override this selection or set the CMake environment CMAKE_INCLUDE_PATH
15072 to modify the search paths.
15073 Note that the header path has changed from SDL/SDL.h to just SDL.h This
15075 needed to change because “proper” SDL convention is #include “SDL.h”,
15076 not <SDL/SDL.h>. This is done for portability reasons because not all
15077 systems place things in SDL/ (see FreeBSD).
15078 FindSDL_sound
15080 Locates the SDL_sound library
15081 This module depends on SDL being found and must be called AFTER Find‐
15083 SDL.cmake is called.
15084 This module defines
15086 SDL_SOUND_INCLUDE_DIR, where to find SDL_sound.h
15088 SDL_SOUND_FOUND, if false, do not try to link to SDL_sound
15089 SDL_SOUND_LIBRARIES, this contains the list of libraries that you need
15090 to link against.
15091 SDL_SOUND_EXTRAS, this is an optional variable for you to add your own
15092 flags to SDL_SOUND_LIBRARIES. This is prepended to SDL_SOUND_LIBRARIES.
15093 This is available mostly for cases this module failed to anticipate for
15094 and you must add additional flags. This is marked as ADVANCED.
15095 SDL_SOUND_VERSION_STRING, human-readable string containing the
15096 version of SDL_sound
15097 This module also defines (but you shouldn’t need to use directly)
15099 SDL_SOUND_LIBRARY, the name of just the SDL_sound library you would link
15101 against. Use SDL_SOUND_LIBRARIES for you link instructions and not this one.
15102 And might define the following as needed
15104 MIKMOD_LIBRARY
15106 MODPLUG_LIBRARY
15107 OGG_LIBRARY
15108 VORBIS_LIBRARY
15109 SMPEG_LIBRARY
15110 FLAC_LIBRARY
15111 SPEEX_LIBRARY
15112 Typically, you should not use these variables directly, and you should
15114 use SDL_SOUND_LIBRARIES which contains SDL_SOUND_LIBRARY and the other
15115 audio libraries (if needed) to successfully compile on your system.
15116 Created by Eric Wing. This module is a bit more complicated than the
15118 other FindSDL* family modules. The reason is that SDL_sound can be
15119 compiled in a large variety of different ways which are independent of
15120 platform. SDL_sound may dynamically link against other 3rd party
15121 libraries to get additional codec support, such as Ogg Vorbis, SMPEG,
15122 ModPlug, MikMod, FLAC, Speex, and potentially others. Under some cir‐
15123 cumstances which I don’t fully understand, there seems to be a require‐
15124 ment that dependent libraries of libraries you use must also be explic‐
15125 itly linked against in order to successfully compile. SDL_sound does
15126 not currently have any system in place to know how it was compiled. So
15127 this CMake module does the hard work in trying to discover which 3rd
15128 party libraries are required for building (if any). This module uses a
15129 brute force approach to create a test program that uses SDL_sound, and
15130 then tries to build it. If the build fails, it parses the error output
15131 for known symbol names to figure out which libraries are needed.
15132 Responds to the $SDLDIR and $SDLSOUNDDIR environmental variable that
15134 would correspond to the ./configure –prefix=$SDLDIR used in building
15135 SDL.
15136 On OSX, this will prefer the Framework version (if found) over others.
15138 People will have to manually change the cache values of SDL_LIBRARY to
15139 override this selectionor set the CMake environment CMAKE_INCLUDE_PATH
15140 to modify the search paths.
15141 FindSDL_ttf
15143 Locate SDL_ttf library
15144 This module defines:
15146 SDL_TTF_LIBRARIES, the name of the library to link against
15148 SDL_TTF_INCLUDE_DIRS, where to find the headers
15149 SDL_TTF_FOUND, if false, do not try to link against
15150 SDL_TTF_VERSION_STRING - human-readable string containing the version of SDL_ttf
15151 For backward compatibility the following variables are also set:
15153 SDLTTF_LIBRARY (same value as SDL_TTF_LIBRARIES)
15155 SDLTTF_INCLUDE_DIR (same value as SDL_TTF_INCLUDE_DIRS)
15156 SDLTTF_FOUND (same value as SDL_TTF_FOUND)
15157 $SDLDIR is an environment variable that would correspond to the
15159 Created by Eric Wing. This was influenced by the FindSDL.cmake module,
15161 but with modifications to recognize OS X frameworks and additional Unix
15162 paths (FreeBSD, etc).
15163 FindSelfPackers
15165 Find upx
15166 This module looks for some executable packers (i.e. software that com‐
15168 press executables or shared libs into on-the-fly self-extracting exe‐
15169 cutables or shared libs. Examples:
15170 UPX: http://wildsau.idv.uni-linz.ac.at/mfx/upx.html
15172 FindSquish
15174 – Typical Use
15175 This module can be used to find Squish. Currently Squish versions 3
15177 and 4 are supported.
15178 SQUISH_FOUND If false, don't try to use Squish
15180 SQUISH_VERSION The full version of Squish found
15181 SQUISH_VERSION_MAJOR The major version of Squish found
15182 SQUISH_VERSION_MINOR The minor version of Squish found
15183 SQUISH_VERSION_PATCH The patch version of Squish found
15184 SQUISH_INSTALL_DIR The Squish installation directory
15186 (containing bin, lib, etc)
15187 SQUISH_SERVER_EXECUTABLE The squishserver executable
15188 SQUISH_CLIENT_EXECUTABLE The squishrunner executable
15189 SQUISH_INSTALL_DIR_FOUND Was the install directory found?
15191 SQUISH_SERVER_EXECUTABLE_FOUND Was the server executable found?
15192 SQUISH_CLIENT_EXECUTABLE_FOUND Was the client executable found?
15193 It provides the function squish_v4_add_test() for adding a squish test
15195 to cmake using Squish 4.x:
15196 squish_v4_add_test(cmakeTestName
15198 AUT targetName SUITE suiteName TEST squishTestName
15199 [SETTINGSGROUP group] [PRE_COMMAND command] [POST_COMMAND command] )
15200 The arguments have the following meaning:
15202 cmakeTestName
15204 this will be used as the first argument for add_test()
15205 AUT targetName
15207 the name of the cmake target which will be used as AUT, i.e. the
15208 executable which will be tested.
15209 SUITE suiteName
15211 this is either the full path to the squish suite, or just the
15212 last directory of the suite, i.e. the suite name. In this case
15213 the CMakeLists.txt which calls squish_add_test() must be located
15214 in the parent directory of the suite directory.
15215 TEST squishTestName
15217 the name of the squish test, i.e. the name of the subdirectory
15218 of the test inside the suite directory.
15219 SETTINGSGROUP group
15221 if specified, the given settings group will be used for execut‐
15222 ing the test. If not specified, the groupname will be
15223 “CTest_<username>”
15224 PRE_COMMAND command
15226 if specified, the given command will be executed before starting
15227 the squish test.
15228 POST_COMMAND command
15230 same as PRE_COMMAND, but after the squish test has been exe‐
15231 cuted.
15232 enable_testing()
15234 find_package(Squish 4.0)
15235 if (SQUISH_FOUND)
15236 squish_v4_add_test(myTestName
15237 AUT myApp
15238 SUITE ${CMAKE_SOURCE_DIR}/tests/mySuite
15239 TEST someSquishTest
15240 SETTINGSGROUP myGroup
15241 )
15242 endif ()
15243 For users of Squish version 3.x the macro squish_v3_add_test() is pro‐
15245 vided:
15246 squish_v3_add_test(testName applicationUnderTest testCase envVars testWrapper)
15248 Use this macro to add a test using Squish 3.x.
15249 enable_testing()
15251 find_package(Squish)
15252 if (SQUISH_FOUND)
15253 squish_v3_add_test(myTestName myApplication testCase envVars testWrapper)
15254 endif ()
15255 macro SQUISH_ADD_TEST(testName applicationUnderTest testCase envVars
15257 testWrapper)
15258 This is deprecated. Use SQUISH_V3_ADD_TEST() if you are using Squish 3.x instead.
15260 FindSQLite3
15262 Find the SQLite libraries, v3
15263 IMPORTED targets
15265 This module defines the following IMPORTED target:
15266 SQLite::SQLite3
15268 Result variables
15270 This module will set the following variables if found:
15271 SQLite3_INCLUDE_DIRS
15273 where to find sqlite3.h, etc.
15274 SQLite3_LIBRARIES
15276 the libraries to link against to use SQLite3.
15277 SQLite3_VERSION
15279 version of the SQLite3 library found
15280 SQLite3_FOUND
15282 TRUE if found
15283 FindSubversion
15285 Extract information from a subversion working copy
15286 The module defines the following variables:
15288 Subversion_SVN_EXECUTABLE - path to svn command line client
15290 Subversion_VERSION_SVN - version of svn command line client
15291 Subversion_FOUND - true if the command line client was found
15292 SUBVERSION_FOUND - same as Subversion_FOUND, set for compatibility reasons
15293 The minimum required version of Subversion can be specified using the
15295 standard syntax, e.g. find_package(Subversion 1.4).
15296 If the command line client executable is found two macros are defined:
15298 Subversion_WC_INFO(<dir> <var-prefix> [IGNORE_SVN_FAILURE])
15300 Subversion_WC_LOG(<dir> <var-prefix>)
15301 Subversion_WC_INFO extracts information of a subversion working copy at
15303 a given location. This macro defines the following variables if run‐
15304 ning Subversion’s info command on <dir> succeeds; otherwise a
15305 SEND_ERROR message is generated. The error can be ignored by providing
15306 the IGNORE_SVN_FAILURE option, which causes these variables to remain
15307 undefined.
15308 <var-prefix>_WC_URL - url of the repository (at <dir>)
15310 <var-prefix>_WC_ROOT - root url of the repository
15311 <var-prefix>_WC_REVISION - current revision
15312 <var-prefix>_WC_LAST_CHANGED_AUTHOR - author of last commit
15313 <var-prefix>_WC_LAST_CHANGED_DATE - date of last commit
15314 <var-prefix>_WC_LAST_CHANGED_REV - revision of last commit
15315 <var-prefix>_WC_INFO - output of command `svn info <dir>'
15316 Subversion_WC_LOG retrieves the log message of the base revision of a
15318 subversion working copy at a given location. This macro defines the
15319 variable:
15320 <var-prefix>_LAST_CHANGED_LOG - last log of base revision
15322 Example usage:
15324 find_package(Subversion)
15326 if(SUBVERSION_FOUND)
15327 Subversion_WC_INFO(${PROJECT_SOURCE_DIR} Project)
15328 message("Current revision is ${Project_WC_REVISION}")
15329 Subversion_WC_LOG(${PROJECT_SOURCE_DIR} Project)
15330 message("Last changed log is ${Project_LAST_CHANGED_LOG}")
15331 endif()
15332 FindSWIG
15334 Find Simplified Wrapper and Interface Generator (SWIG)
15335 This module finds an installed SWIG. It sets the following variables:
15337 SWIG_FOUND - set to "True" if SWIG is found
15339 SWIG_DIR - the directory where swig is installed
15340 SWIG_EXECUTABLE - the path to the swig executable
15341 SWIG_VERSION - the version number of the swig executable
15342 The minimum required version of SWIG can be specified using the stan‐
15344 dard syntax, e.g. find_package(SWIG 1.1)
15345 All information is collected from the SWIG_EXECUTABLE, so the version
15347 to be found can be changed from the command line by means of setting
15348 SWIG_EXECUTABLE
15349 FindTCL
15351 TK_INTERNAL_PATH was removed.
15352 This module finds if Tcl is installed and determines where the include
15354 files and libraries are. It also determines what the name of the
15355 library is. This code sets the following variables:
15356 TCL_FOUND = Tcl was found
15358 TK_FOUND = Tk was found
15359 TCLTK_FOUND = Tcl and Tk were found
15360 TCL_LIBRARY = path to Tcl library (tcl tcl80)
15361 TCL_INCLUDE_PATH = path to where tcl.h can be found
15362 TCL_TCLSH = path to tclsh binary (tcl tcl80)
15363 TK_LIBRARY = path to Tk library (tk tk80 etc)
15364 TK_INCLUDE_PATH = path to where tk.h can be found
15365 TK_WISH = full path to the wish executable
15366 In an effort to remove some clutter and clear up some issues for people
15368 who are not necessarily Tcl/Tk gurus/developers, some variables were
15369 moved or removed. Changes compared to CMake 2.4 are:
15370 => they were only useful for people writing Tcl/Tk extensions.
15372 => these libs are not packaged by default with Tcl/Tk distributions.
15373 Even when Tcl/Tk is built from source, several flavors of debug libs
15374 are created and there is no real reason to pick a single one
15375 specifically (say, amongst tcl84g, tcl84gs, or tcl84sgx).
15376 Let's leave that choice to the user by allowing him to assign
15377 TCL_LIBRARY to any Tcl library, debug or not.
15378 => this ended up being only a Win32 variable, and there is a lot of
15379 confusion regarding the location of this file in an installed Tcl/Tk
15380 tree anyway (see 8.5 for example). If you need the internal path at
15381 this point it is safer you ask directly where the *source* tree is
15382 and dig from there.
15383 FindTclsh
15385 Find tclsh
15386 This module finds if TCL is installed and determines where the include
15388 files and libraries are. It also determines what the name of the
15389 library is. This code sets the following variables:
15390 TCLSH_FOUND = TRUE if tclsh has been found
15392 TCL_TCLSH = the path to the tclsh executable
15393 In cygwin, look for the cygwin version first. Don’t look for it later
15395 to avoid finding the cygwin version on a Win32 build.
15396 FindTclStub
15398 TCL_STUB_LIBRARY_DEBUG and TK_STUB_LIBRARY_DEBUG were removed.
15399 This module finds Tcl stub libraries. It first finds Tcl include files
15401 and libraries by calling FindTCL.cmake. How to Use the Tcl Stubs
15402 Library:
15403 http://tcl.activestate.com/doc/howto/stubs.html
15405 Using Stub Libraries:
15407 http://safari.oreilly.com/0130385603/ch48lev1sec3
15409 This code sets the following variables:
15411 TCL_STUB_LIBRARY = path to Tcl stub library
15413 TK_STUB_LIBRARY = path to Tk stub library
15414 TTK_STUB_LIBRARY = path to ttk stub library
15415 In an effort to remove some clutter and clear up some issues for people
15417 who are not necessarily Tcl/Tk gurus/developers, some variables were
15418 moved or removed. Changes compared to CMake 2.4 are:
15419 => these libs are not packaged by default with Tcl/Tk distributions.
15421 Even when Tcl/Tk is built from source, several flavors of debug libs
15422 are created and there is no real reason to pick a single one
15423 specifically (say, amongst tclstub84g, tclstub84gs, or tclstub84sgx).
15424 Let's leave that choice to the user by allowing him to assign
15425 TCL_STUB_LIBRARY to any Tcl library, debug or not.
15426 FindThreads
15428 This module determines the thread library of the system.
15429 Imported Targets
15431 This module defines the following IMPORTED target:
15432 Threads::Threads
15434 The thread library, if found.
15435 Result Variables
15437 The following variables are set:
15438 Threads_FOUND
15440 If a supported thread library was found.
15441 CMAKE_THREAD_LIBS_INIT
15443 The thread library to use. This may be empty if the thread func‐
15444 tions are provided by the system libraries and no special flags
15445 are needed to use them.
15446 CMAKE_USE_WIN32_THREADS_INIT
15448 If the found thread library is the win32 one.
15449 CMAKE_USE_PTHREADS_INIT
15451 If the found thread library is pthread compatible.
15452 CMAKE_HP_PTHREADS_INIT
15454 If the found thread library is the HP thread library.
15455 Variables Affecting Behavior
15457 THREADS_PREFER_PTHREAD_FLAG
15458 If the use of the -pthread compiler and linker flag is preferred
15459 then the caller can set this variable to TRUE. The compiler flag
15460 can only be used with the imported target. Use of both the
15461 imported target as well as this switch is highly recommended for
15462 new code.
15463 This variable has no effect if the system libraries provide the
15465 thread functions, i.e. when CMAKE_THREAD_LIBS_INIT will be
15466 empty.
15467 FindTIFF
15469 Find the TIFF library (libtiff).
15470 Imported targets
15472 This module defines the following IMPORTED targets:
15473 TIFF::TIFF
15475 The TIFF library, if found.
15476 Result variables
15478 This module will set the following variables in your project:
15479 TIFF_FOUND
15481 true if the TIFF headers and libraries were found
15482 TIFF_INCLUDE_DIR
15484 the directory containing the TIFF headers
15485 TIFF_INCLUDE_DIRS
15487 the directory containing the TIFF headers
15488 TIFF_LIBRARIES
15490 TIFF libraries to be linked
15491 Cache variables
15493 The following cache variables may also be set:
15494 TIFF_INCLUDE_DIR
15496 the directory containing the TIFF headers
15497 TIFF_LIBRARY
15499 the path to the TIFF library
15500 FindUnixCommands
15502 Find Unix commands, including the ones from Cygwin
15503 This module looks for the Unix commands bash, cp, gzip, mv, rm, and tar
15505 and stores the result in the variables BASH, CP, GZIP, MV, RM, and TAR.
15506 FindVTK
15508 This module no longer exists.
15509 This module existed in versions of CMake prior to 3.1, but became only
15511 a thin wrapper around find_package(VTK NO_MODULE) to provide compati‐
15512 bility for projects using long-outdated conventions. Now find_pack‐
15513 age(VTK) will search for VTKConfig.cmake directly.
15514 FindVulkan
15516 Find Vulkan, which is a low-overhead, cross-platform 3D graphics and
15517 computing API.
15518 IMPORTED Targets
15520 This module defines IMPORTED target Vulkan::Vulkan, if Vulkan has been
15521 found.
15522 Result Variables
15524 This module defines the following variables:
15525 Vulkan_FOUND - "True" if Vulkan was found
15527 Vulkan_INCLUDE_DIRS - include directories for Vulkan
15528 Vulkan_LIBRARIES - link against this library to use Vulkan
15529 The module will also define two cache variables:
15531 Vulkan_INCLUDE_DIR - the Vulkan include directory
15533 Vulkan_LIBRARY - the path to the Vulkan library
15534 FindWget
15536 Find wget
15537 This module looks for wget. This module defines the following values:
15539 WGET_EXECUTABLE: the full path to the wget tool.
15541 WGET_FOUND: True if wget has been found.
15542 FindWish
15544 Find wish installation
15545 This module finds if TCL is installed and determines where the include
15547 files and libraries are. It also determines what the name of the
15548 library is. This code sets the following variables:
15549 TK_WISH = the path to the wish executable
15551 if UNIX is defined, then it will look for the cygwin version first
15553 FindwxWidgets
15555 Find a wxWidgets (a.k.a., wxWindows) installation.
15556 This module finds if wxWidgets is installed and selects a default con‐
15558 figuration to use. wxWidgets is a modular library. To specify the
15559 modules that you will use, you need to name them as components to the
15560 package:
15561 find_package(wxWidgets COMPONENTS core base … OPTIONAL_COMPONENTS net
15563 …)
15564 There are two search branches: a windows style and a unix style. For
15566 windows, the following variables are searched for and set to defaults
15567 in case of multiple choices. Change them if the defaults are not
15568 desired (i.e., these are the only variables you should change to select
15569 a configuration):
15570 wxWidgets_ROOT_DIR - Base wxWidgets directory
15572 (e.g., C:/wxWidgets-2.6.3).
15573 wxWidgets_LIB_DIR - Path to wxWidgets libraries
15574 (e.g., C:/wxWidgets-2.6.3/lib/vc_lib).
15575 wxWidgets_CONFIGURATION - Configuration to use
15576 (e.g., msw, mswd, mswu, mswunivud, etc.)
15577 wxWidgets_EXCLUDE_COMMON_LIBRARIES
15578 - Set to TRUE to exclude linking of
15579 commonly required libs (e.g., png tiff
15580 jpeg zlib regex expat).
15581 For unix style it uses the wx-config utility. You can select between
15583 debug/release, unicode/ansi, universal/non-universal, and static/shared
15584 in the QtDialog or ccmake interfaces by turning ON/OFF the following
15585 variables:
15586 wxWidgets_USE_DEBUG
15588 wxWidgets_USE_UNICODE
15589 wxWidgets_USE_UNIVERSAL
15590 wxWidgets_USE_STATIC
15591 There is also a wxWidgets_CONFIG_OPTIONS variable for all other options
15593 that need to be passed to the wx-config utility. For example, to use
15594 the base toolkit found in the /usr/local path, set the variable (before
15595 calling the FIND_PACKAGE command) as such:
15596 set(wxWidgets_CONFIG_OPTIONS --toolkit=base --prefix=/usr)
15598 The following are set after the configuration is done for both windows
15600 and unix style:
15601 wxWidgets_FOUND - Set to TRUE if wxWidgets was found.
15603 wxWidgets_INCLUDE_DIRS - Include directories for WIN32
15604 i.e., where to find "wx/wx.h" and
15605 "wx/setup.h"; possibly empty for unices.
15606 wxWidgets_LIBRARIES - Path to the wxWidgets libraries.
15607 wxWidgets_LIBRARY_DIRS - compile time link dirs, useful for
15608 rpath on UNIX. Typically an empty string
15609 in WIN32 environment.
15610 wxWidgets_DEFINITIONS - Contains defines required to compile/link
15611 against WX, e.g. WXUSINGDLL
15612 wxWidgets_DEFINITIONS_DEBUG- Contains defines required to compile/link
15613 against WX debug builds, e.g. __WXDEBUG__
15614 wxWidgets_CXX_FLAGS - Include dirs and compiler flags for
15615 unices, empty on WIN32. Essentially
15616 "`wx-config --cxxflags`".
15617 wxWidgets_USE_FILE - Convenience include file.
15618 Sample usage:
15620 # Note that for MinGW users the order of libs is important!
15622 find_package(wxWidgets COMPONENTS gl core base OPTIONAL_COMPONENTS net)
15623 if(wxWidgets_FOUND)
15624 include(${wxWidgets_USE_FILE})
15625 # and for each of your dependent executable/library targets:
15626 target_link_libraries(<YourTarget> ${wxWidgets_LIBRARIES})
15627 endif()
15628 If wxWidgets is required (i.e., not an optional part):
15630 find_package(wxWidgets REQUIRED gl core base OPTIONAL_COMPONENTS net)
15632 include(${wxWidgets_USE_FILE})
15633 # and for each of your dependent executable/library targets:
15634 target_link_libraries(<YourTarget> ${wxWidgets_LIBRARIES})
15635 FindXCTest
15637 Functions to help creating and executing XCTest bundles.
15638 An XCTest bundle is a CFBundle with a special product-type and bundle
15640 extension. The Mac Developer Library provides more information in the
15641 Testing with Xcode document.
15642 Module Functions
15644 xctest_add_bundle
15645 The xctest_add_bundle function creates a XCTest bundle named
15646 <target> which will test the target <testee>. Supported target
15647 types for testee are Frameworks and App Bundles:
15648 xctest_add_bundle(
15650 <target> # Name of the XCTest bundle
15651 <testee> # Target name of the testee
15652 )
15653 xctest_add_test
15655 The xctest_add_test function adds an XCTest bundle to the
15656 project to be run by ctest(1). The test will be named <name> and
15657 tests <bundle>:
15658 xctest_add_test(
15660 <name> # Test name
15661 <bundle> # Target name of XCTest bundle
15662 )
15663 Module Variables
15665 The following variables are set by including this module:
15666 XCTest_FOUND
15668 True if the XCTest Framework and executable were found.
15669 XCTest_EXECUTABLE
15671 The path to the xctest command line tool used to execute XCTest
15672 bundles.
15673 XCTest_INCLUDE_DIRS
15675 The directory containing the XCTest Framework headers.
15676 XCTest_LIBRARIES
15678 The location of the XCTest Framework.
15679 FindXalanC
15681 Find the Apache Xalan-C++ XSL transform processor headers and
15682 libraries.
15683 Imported targets
15685 This module defines the following IMPORTED targets:
15686 XalanC::XalanC
15688 The Xalan-C++ xalan-c library, if found.
15689 Result variables
15691 This module will set the following variables in your project:
15692 XalanC_FOUND
15694 true if the Xalan headers and libraries were found
15695 XalanC_VERSION
15697 Xalan release version
15698 XalanC_INCLUDE_DIRS
15700 the directory containing the Xalan headers; note
15701 XercesC_INCLUDE_DIRS is also required
15702 XalanC_LIBRARIES
15704 Xalan libraries to be linked; note XercesC_LIBRARIES is also
15705 required
15706 Cache variables
15708 The following cache variables may also be set:
15709 XalanC_INCLUDE_DIR
15711 the directory containing the Xalan headers
15712 XalanC_LIBRARY
15714 the Xalan library
15715 FindXercesC
15717 Find the Apache Xerces-C++ validating XML parser headers and libraries.
15718 Imported targets
15720 This module defines the following IMPORTED targets:
15721 XercesC::XercesC
15723 The Xerces-C++ xerces-c library, if found.
15724 Result variables
15726 This module will set the following variables in your project:
15727 XercesC_FOUND
15729 true if the Xerces headers and libraries were found
15730 XercesC_VERSION
15732 Xerces release version
15733 XercesC_INCLUDE_DIRS
15735 the directory containing the Xerces headers
15736 XercesC_LIBRARIES
15738 Xerces libraries to be linked
15739 Cache variables
15741 The following cache variables may also be set:
15742 XercesC_INCLUDE_DIR
15744 the directory containing the Xerces headers
15745 XercesC_LIBRARY
15747 the Xerces library
15748 FindX11
15750 Find X11 installation
15751 Try to find X11 on UNIX systems. The following values are defined
15753 X11_FOUND - True if X11 is available
15755 X11_INCLUDE_DIR - include directories to use X11
15756 X11_LIBRARIES - link against these to use X11
15757 and also the following more fine grained variables and targets:
15759 X11_ICE_INCLUDE_PATH, X11_ICE_LIB, X11_ICE_FOUND, X11::ICE
15761 X11_SM_INCLUDE_PATH, X11_SM_LIB, X11_SM_FOUND, X11::SM
15762 X11_X11_INCLUDE_PATH, X11_X11_LIB, X11::X11
15763 X11_Xaccessrules_INCLUDE_PATH,
15764 X11_Xaccessstr_INCLUDE_PATH, X11_Xaccess_FOUND
15765 X11_Xau_INCLUDE_PATH, X11_Xau_LIB, X11_Xau_FOUND, X11::Xau
15766 X11_Xcomposite_INCLUDE_PATH, X11_Xcomposite_LIB, X11_Xcomposite_FOUND, X11::Xcomposite
15767 X11_Xcursor_INCLUDE_PATH, X11_Xcursor_LIB, X11_Xcursor_FOUND, X11::Xcursor
15768 X11_Xdamage_INCLUDE_PATH, X11_Xdamage_LIB, X11_Xdamage_FOUND, X11::Xdamage
15769 X11_Xdmcp_INCLUDE_PATH, X11_Xdmcp_LIB, X11_Xdmcp_FOUND, X11::Xdmcp
15770 X11_Xext_INCLUDE_PATH, X11_Xext_LIB, X11_Xext_FOUND, X11::Xext
15771 X11_Xxf86misc_INCLUDE_PATH, X11_Xxf86misc_LIB, X11_Xxf86misc_FOUND, X11::Xxf86misc
15772 X11_Xxf86vm_INCLUDE_PATH, X11_Xxf86vm_LIB X11_Xxf86vm_FOUND, X11::Xxf86vm
15773 X11_Xfixes_INCLUDE_PATH, X11_Xfixes_LIB, X11_Xfixes_FOUND, X11::Xfixes
15774 X11_Xft_INCLUDE_PATH, X11_Xft_LIB, X11_Xft_FOUND, X11::Xft
15775 X11_Xi_INCLUDE_PATH, X11_Xi_LIB, X11_Xi_FOUND, X11::Xi
15776 X11_Xinerama_INCLUDE_PATH, X11_Xinerama_LIB, X11_Xinerama_FOUND, X11::Xinerama
15777 X11_Xkb_INCLUDE_PATH,
15778 X11_Xkblib_INCLUDE_PATH, X11_Xkb_FOUND, X11::Xkb
15779 X11_xkbfile_INCLUDE_PATH, X11_xkbfile_LIB, X11_xkbfile_FOUND, X11::xkbfile
15780 X11_Xmu_INCLUDE_PATH, X11_Xmu_LIB, X11_Xmu_FOUND, X11::Xmu
15781 X11_Xpm_INCLUDE_PATH, X11_Xpm_LIB, X11_Xpm_FOUND, X11::Xpm
15782 X11_Xtst_INCLUDE_PATH, X11_Xtst_LIB, X11_Xtst_FOUND, X11::Xtst
15783 X11_Xrandr_INCLUDE_PATH, X11_Xrandr_LIB, X11_Xrandr_FOUND, X11::Xrandr
15784 X11_Xrender_INCLUDE_PATH, X11_Xrender_LIB, X11_Xrender_FOUND, X11::Xrender
15785 X11_XRes_INCLUDE_PATH, X11_XRes_LIB, X11_XRes_FOUND, X11::XRes
15786 X11_Xss_INCLUDE_PATH, X11_Xss_LIB, X11_Xss_FOUND, X11::Xss
15787 X11_Xt_INCLUDE_PATH, X11_Xt_LIB, X11_Xt_FOUND, X11::Xt
15788 X11_Xutil_INCLUDE_PATH, X11_Xutil_FOUND, X11::Xutil
15789 X11_Xv_INCLUDE_PATH, X11_Xv_LIB, X11_Xv_FOUND, X11::Xv
15790 X11_dpms_INCLUDE_PATH, (in X11_Xext_LIB), X11_dpms_FOUND
15791 X11_XShm_INCLUDE_PATH, (in X11_Xext_LIB), X11_XShm_FOUND
15792 X11_Xshape_INCLUDE_PATH, (in X11_Xext_LIB), X11_Xshape_FOUND
15793 X11_XSync_INCLUDE_PATH, (in X11_Xext_LIB), X11_XSync_FOUND
15794 FindXMLRPC
15796 Find xmlrpc
15797 Find the native XMLRPC headers and libraries.
15799 XMLRPC_INCLUDE_DIRS - where to find xmlrpc.h, etc.
15801 XMLRPC_LIBRARIES - List of libraries when using xmlrpc.
15802 XMLRPC_FOUND - True if xmlrpc found.
15803 XMLRPC modules may be specified as components for this find module.
15805 Modules may be listed by running “xmlrpc-c-config”. Modules include:
15806 c++ C++ wrapper code
15808 libwww-client libwww-based client
15809 cgi-server CGI-based server
15810 abyss-server ABYSS-based server
15811 Typical usage:
15813 find_package(XMLRPC REQUIRED libwww-client)
15815 FindZLIB
15817 Find the native ZLIB includes and library.
15818 IMPORTED Targets
15820 This module defines IMPORTED target ZLIB::ZLIB, if ZLIB has been found.
15821 Result Variables
15823 This module defines the following variables:
15824 ZLIB_INCLUDE_DIRS - where to find zlib.h, etc.
15826 ZLIB_LIBRARIES - List of libraries when using zlib.
15827 ZLIB_FOUND - True if zlib found.
15828 ZLIB_VERSION_STRING - The version of zlib found (x.y.z)
15830 ZLIB_VERSION_MAJOR - The major version of zlib
15831 ZLIB_VERSION_MINOR - The minor version of zlib
15832 ZLIB_VERSION_PATCH - The patch version of zlib
15833 ZLIB_VERSION_TWEAK - The tweak version of zlib
15834 Backward Compatibility
15836 The following variable are provided for backward compatibility
15837 ZLIB_MAJOR_VERSION - The major version of zlib
15839 ZLIB_MINOR_VERSION - The minor version of zlib
15840 ZLIB_PATCH_VERSION - The patch version of zlib
15841 Hints
15843 A user may set ZLIB_ROOT to a zlib installation root to tell this mod‐
15844 ule where to look.
15845
15847 Deprecated Utility Modules
15848 CMakeDetermineVSServicePack
15849 Deprecated since version 3.0: Do not use.
15850 The functionality of this module has been superseded by the
15853 CMAKE_<LANG>_COMPILER_VERSION variable that contains the compiler ver‐
15854 sion number.
15855 Determine the Visual Studio service pack of the ‘cl’ in use.
15857 Usage:
15859 if(MSVC)
15861 include(CMakeDetermineVSServicePack)
15862 DetermineVSServicePack( my_service_pack )
15863 if( my_service_pack )
15864 message(STATUS "Detected: ${my_service_pack}")
15865 endif()
15866 endif()
15867 Function DetermineVSServicePack sets the given variable to one of the
15869 following values or an empty string if unknown:
15870 vc80, vc80sp1
15872 vc90, vc90sp1
15873 vc100, vc100sp1
15874 vc110, vc110sp1, vc110sp2, vc110sp3, vc110sp4
15875 CMakeExpandImportedTargets
15877 Deprecated since version 3.4: Do not use.
15878 This module was once needed to expand imported targets to the underly‐
15881 ing libraries they reference on disk for use with the try_compile() and
15882 try_run() commands. These commands now support imported libraries in
15883 their LINK_LIBRARIES options (since CMake 2.8.11 for try_compile() and
15884 since CMake 3.2 for try_run()).
15885 This module does not support the policy CMP0022 NEW behavior or use of
15887 the INTERFACE_LINK_LIBRARIES property because generator expressions
15888 cannot be evaluated during configuration.
15889 CMAKE_EXPAND_IMPORTED_TARGETS(<var> LIBRARIES lib1 lib2...libN
15891 [CONFIGURATION <config>])
15892 CMAKE_EXPAND_IMPORTED_TARGETS() takes a list of libraries and replaces
15894 all imported targets contained in this list with their actual file
15895 paths of the referenced libraries on disk, including the libraries from
15896 their link interfaces. If a CONFIGURATION is given, it uses the
15897 respective configuration of the imported targets if it exists. If no
15898 CONFIGURATION is given, it uses the first configuration from
15899 ${CMAKE_CONFIGURATION_TYPES} if set, otherwise ${CMAKE_BUILD_TYPE}.
15900 cmake_expand_imported_targets(expandedLibs
15902 LIBRARIES ${CMAKE_REQUIRED_LIBRARIES}
15903 CONFIGURATION "${CMAKE_TRY_COMPILE_CONFIGURATION}" )
15904 CMakeForceCompiler
15906 Deprecated since version 3.6: Do not use.
15907 The macros provided by this module were once intended for use by
15910 cross-compiling toolchain files when CMake was not able to automati‐
15911 cally detect the compiler identification. Since the introduction of
15912 this module, CMake’s compiler identification capabilities have improved
15913 and can now be taught to recognize any compiler. Furthermore, the
15914 suite of information CMake detects from a compiler is now too extensive
15915 to be provided by toolchain files using these macros.
15916 One common use case for this module was to skip CMake’s checks for a
15918 working compiler when using a cross-compiler that cannot link binaries
15919 without special flags or custom linker scripts. This case is now sup‐
15920 ported by setting the CMAKE_TRY_COMPILE_TARGET_TYPE variable in the
15921 toolchain file instead.
15922 ----
15925 Macro CMAKE_FORCE_C_COMPILER has the following signature:
15929 CMAKE_FORCE_C_COMPILER(<compiler> <compiler-id>)
15931 It sets CMAKE_C_COMPILER to the given compiler and the cmake internal
15933 variable CMAKE_C_COMPILER_ID to the given compiler-id. It also
15934 bypasses the check for working compiler and basic compiler information
15935 tests.
15936 Macro CMAKE_FORCE_CXX_COMPILER has the following signature:
15938 CMAKE_FORCE_CXX_COMPILER(<compiler> <compiler-id>)
15940 It sets CMAKE_CXX_COMPILER to the given compiler and the cmake internal
15942 variable CMAKE_CXX_COMPILER_ID to the given compiler-id. It also
15943 bypasses the check for working compiler and basic compiler information
15944 tests.
15945 Macro CMAKE_FORCE_Fortran_COMPILER has the following signature:
15947 CMAKE_FORCE_Fortran_COMPILER(<compiler> <compiler-id>)
15949 It sets CMAKE_Fortran_COMPILER to the given compiler and the cmake
15951 internal variable CMAKE_Fortran_COMPILER_ID to the given compiler-id.
15952 It also bypasses the check for working compiler and basic compiler
15953 information tests.
15954 So a simple toolchain file could look like this:
15956 include (CMakeForceCompiler)
15958 set(CMAKE_SYSTEM_NAME Generic)
15959 CMAKE_FORCE_C_COMPILER (chc12 MetrowerksHicross)
15960 CMAKE_FORCE_CXX_COMPILER (chc12 MetrowerksHicross)
15961 CMakeParseArguments
15963 This module once implemented the cmake_parse_arguments() command that
15964 is now implemented natively by CMake. It is now an empty placeholder
15965 for compatibility with projects that include it to get the command from
15966 CMake 3.4 and lower.
15967 MacroAddFileDependencies
15969 MACRO_ADD_FILE_DEPENDENCIES(<_file> depend_files…)
15970 Using the macro MACRO_ADD_FILE_DEPENDENCIES() is discouraged. There
15972 are usually better ways to specify the correct dependencies.
15973 MACRO_ADD_FILE_DEPENDENCIES(<_file> depend_files…) is just a conve‐
15975 nience wrapper around the OBJECT_DEPENDS source file property. You can
15976 just use set_property(SOURCE <file> APPEND PROPERTY OBJECT_DEPENDS
15977 depend_files) instead.
15978 TestCXXAcceptsFlag
15980 Deprecated since version 3.0: See CheckCXXCompilerFlag.
15981 Check if the CXX compiler accepts a flag.
15984 CHECK_CXX_ACCEPTS_FLAG(<flags> <variable>)
15986 <flags>
15988 the flags to try
15989 <variable>
15991 variable to store the result
15992 UsePkgConfig
15994 Obsolete pkg-config module for CMake, use FindPkgConfig instead.
15995 This module defines the following macro:
15997 PKGCONFIG(package includedir libdir linkflags cflags)
15999 Calling PKGCONFIG will fill the desired information into the 4 given
16001 arguments, e.g. PKGCONFIG(libart-2.0 LIBART_INCLUDE_DIR
16002 LIBART_LINK_DIR LIBART_LINK_FLAGS LIBART_CFLAGS) if pkg-config was NOT
16003 found or the specified software package doesn’t exist, the variable
16004 will be empty when the function returns, otherwise they will contain
16005 the respective information
16006 Use_wxWindows
16008 Deprecated since version 2.8.10: Use find_package(wxWidgets) and
16009 include(${wxWidgets_USE_FILE}) instead.
16010 This convenience include finds if wxWindows is installed and set the
16013 appropriate libs, incdirs, flags etc. author Jan Woetzel <jw -at-
16014 mip.informatik.uni-kiel.de> (07/2003)
16015 USAGE:
16017 just include Use_wxWindows.cmake
16019 in your projects CMakeLists.txt
16020 include( ${CMAKE_MODULE_PATH}/Use_wxWindows.cmake)
16022 if you are sure you need GL then
16024 set(WXWINDOWS_USE_GL 1)
16026 *before* you include this file.
16028 WriteBasicConfigVersionFile
16030 Deprecated since version 3.0: Use the identical command
16031 write_basic_package_version_file() from module CMakePackageCon‐
16032 figHelpers.
16033 WRITE_BASIC_CONFIG_VERSION_FILE( filename
16036 [VERSION major.minor.patch]
16037 COMPATIBILITY (AnyNewerVersion|SameMajorVersion|SameMinorVersion|ExactVersion)
16038 [ARCH_INDEPENDENT]
16039 )
16040 Deprecated Find Modules
16042 FindCUDA
16043 Deprecated since version 3.10: Superseded by first-class support for
16044 the CUDA language in CMake. Superseded by the FindCUDAToolkit for CUDA
16045 toolkit libraries.
16046 Replacement
16049 It is no longer necessary to use this module or call find_package(CUDA)
16050 for compiling CUDA code. Instead, list CUDA among the languages named
16051 in the top-level call to the project() command, or call the enable_lan‐
16052 guage() command with CUDA. Then one can add CUDA (.cu) sources to pro‐
16053 grams directly in calls to add_library() and add_executable().
16054 To find and use the CUDA toolkit libraries the FindCUDAToolkit module
16056 has superseded this module. It works whether or not the CUDA language
16057 is enabled.
16058 Documentation of Deprecated Usage
16060 Tools for building CUDA C files: libraries and build dependencies.
16061 This script locates the NVIDIA CUDA C tools. It should work on Linux,
16063 Windows, and macOS and should be reasonably up to date with CUDA C
16064 releases.
16065 This script makes use of the standard find_package() arguments of <VER‐
16067 SION>, REQUIRED and QUIET. CUDA_FOUND will report if an acceptable
16068 version of CUDA was found.
16069 The script will prompt the user to specify CUDA_TOOLKIT_ROOT_DIR if the
16071 prefix cannot be determined by the location of nvcc in the system path
16072 and REQUIRED is specified to find_package(). To use a different
16073 installed version of the toolkit set the environment variable
16074 CUDA_BIN_PATH before running cmake (e.g.
16075 CUDA_BIN_PATH=/usr/local/cuda1.0 instead of the default
16076 /usr/local/cuda) or set CUDA_TOOLKIT_ROOT_DIR after configuring. If
16077 you change the value of CUDA_TOOLKIT_ROOT_DIR, various components that
16078 depend on the path will be relocated.
16079 It might be necessary to set CUDA_TOOLKIT_ROOT_DIR manually on certain
16081 platforms, or to use a CUDA runtime not installed in the default loca‐
16082 tion. In newer versions of the toolkit the CUDA library is included
16083 with the graphics driver – be sure that the driver version matches what
16084 is needed by the CUDA runtime version.
16085 The following variables affect the behavior of the macros in the script
16087 (in alphabetical order). Note that any of these flags can be changed
16088 multiple times in the same directory before calling CUDA_ADD_EXE‐
16089 CUTABLE, CUDA_ADD_LIBRARY, CUDA_COMPILE, CUDA_COMPILE_PTX, CUDA_COM‐
16090 PILE_FATBIN, CUDA_COMPILE_CUBIN or CUDA_WRAP_SRCS:
16091 CUDA_64_BIT_DEVICE_CODE (Default matches host bit size)
16093 -- Set to ON to compile for 64 bit device code, OFF for 32 bit device code.
16094 Note that making this different from the host code when generating object
16095 or C files from CUDA code just won't work, because size_t gets defined by
16096 nvcc in the generated source. If you compile to PTX and then load the
16097 file yourself, you can mix bit sizes between device and host.
16098 CUDA_ATTACH_VS_BUILD_RULE_TO_CUDA_FILE (Default ON)
16100 -- Set to ON if you want the custom build rule to be attached to the source
16101 file in Visual Studio. Turn OFF if you add the same cuda file to multiple
16102 targets.
16103 This allows the user to build the target from the CUDA file; however, bad
16105 things can happen if the CUDA source file is added to multiple targets.
16106 When performing parallel builds it is possible for the custom build
16107 command to be run more than once and in parallel causing cryptic build
16108 errors. VS runs the rules for every source file in the target, and a
16109 source can have only one rule no matter how many projects it is added to.
16110 When the rule is run from multiple targets race conditions can occur on
16111 the generated file. Eventually everything will get built, but if the user
16112 is unaware of this behavior, there may be confusion. It would be nice if
16113 this script could detect the reuse of source files across multiple targets
16114 and turn the option off for the user, but no good solution could be found.
16115 CUDA_BUILD_CUBIN (Default OFF)
16117 -- Set to ON to enable and extra compilation pass with the -cubin option in
16118 Device mode. The output is parsed and register, shared memory usage is
16119 printed during build.
16120 CUDA_BUILD_EMULATION (Default OFF for device mode)
16122 -- Set to ON for Emulation mode. -D_DEVICEEMU is defined for CUDA C files
16123 when CUDA_BUILD_EMULATION is TRUE.
16124 CUDA_LINK_LIBRARIES_KEYWORD (Default "")
16126 -- The <PRIVATE|PUBLIC|INTERFACE> keyword to use for internal
16127 target_link_libraries calls. The default is to use no keyword which
16128 uses the old "plain" form of target_link_libraries. Note that is matters
16129 because whatever is used inside the FindCUDA module must also be used
16130 outside - the two forms of target_link_libraries cannot be mixed.
16131 CUDA_GENERATED_OUTPUT_DIR (Default CMAKE_CURRENT_BINARY_DIR)
16133 -- Set to the path you wish to have the generated files placed. If it is
16134 blank output files will be placed in CMAKE_CURRENT_BINARY_DIR.
16135 Intermediate files will always be placed in
16136 CMAKE_CURRENT_BINARY_DIR/CMakeFiles.
16137 CUDA_HOST_COMPILATION_CPP (Default ON)
16139 -- Set to OFF for C compilation of host code.
16140 CUDA_HOST_COMPILER (Default CMAKE_C_COMPILER)
16142 -- Set the host compiler to be used by nvcc. Ignored if -ccbin or
16143 --compiler-bindir is already present in the CUDA_NVCC_FLAGS or
16144 CUDA_NVCC_FLAGS_<CONFIG> variables. For Visual Studio targets,
16145 the host compiler is constructed with one or more visual studio macros
16146 such as $(VCInstallDir), that expands out to the path when
16147 the command is run from within VS.
16148 If the CUDAHOSTCXX environment variable is set it will
16149 be used as the default.
16150 CUDA_NVCC_FLAGS
16152 CUDA_NVCC_FLAGS_<CONFIG>
16153 -- Additional NVCC command line arguments. NOTE: multiple arguments must be
16154 semi-colon delimited (e.g. --compiler-options;-Wall)
16155 CUDA_PROPAGATE_HOST_FLAGS (Default ON)
16157 -- Set to ON to propagate CMAKE_{C,CXX}_FLAGS and their configuration
16158 dependent counterparts (e.g. CMAKE_C_FLAGS_DEBUG) automatically to the
16159 host compiler through nvcc's -Xcompiler flag. This helps make the
16160 generated host code match the rest of the system better. Sometimes
16161 certain flags give nvcc problems, and this will help you turn the flag
16162 propagation off. This does not affect the flags supplied directly to nvcc
16163 via CUDA_NVCC_FLAGS or through the OPTION flags specified through
16164 CUDA_ADD_LIBRARY, CUDA_ADD_EXECUTABLE, or CUDA_WRAP_SRCS. Flags used for
16165 shared library compilation are not affected by this flag.
16166 CUDA_SEPARABLE_COMPILATION (Default OFF)
16168 -- If set this will enable separable compilation for all CUDA runtime object
16169 files. If used outside of CUDA_ADD_EXECUTABLE and CUDA_ADD_LIBRARY
16170 (e.g. calling CUDA_WRAP_SRCS directly),
16171 CUDA_COMPUTE_SEPARABLE_COMPILATION_OBJECT_FILE_NAME and
16172 CUDA_LINK_SEPARABLE_COMPILATION_OBJECTS should be called.
16173 CUDA_SOURCE_PROPERTY_FORMAT
16175 -- If this source file property is set, it can override the format specified
16176 to CUDA_WRAP_SRCS (OBJ, PTX, CUBIN, or FATBIN). If an input source file
16177 is not a .cu file, setting this file will cause it to be treated as a .cu
16178 file. See documentation for set_source_files_properties on how to set
16179 this property.
16180 CUDA_USE_STATIC_CUDA_RUNTIME (Default ON)
16182 -- When enabled the static version of the CUDA runtime library will be used
16183 in CUDA_LIBRARIES. If the version of CUDA configured doesn't support
16184 this option, then it will be silently disabled.
16185 CUDA_VERBOSE_BUILD (Default OFF)
16187 -- Set to ON to see all the commands used when building the CUDA file. When
16188 using a Makefile generator the value defaults to VERBOSE (run make
16189 VERBOSE=1 to see output), although setting CUDA_VERBOSE_BUILD to ON will
16190 always print the output.
16191 The script creates the following macros (in alphabetical order):
16193 CUDA_ADD_CUFFT_TO_TARGET( cuda_target )
16195 -- Adds the cufft library to the target (can be any target). Handles whether
16196 you are in emulation mode or not.
16197 CUDA_ADD_CUBLAS_TO_TARGET( cuda_target )
16199 -- Adds the cublas library to the target (can be any target). Handles
16200 whether you are in emulation mode or not.
16201 CUDA_ADD_EXECUTABLE( cuda_target file0 file1 ...
16203 [WIN32] [MACOSX_BUNDLE] [EXCLUDE_FROM_ALL] [OPTIONS ...] )
16204 -- Creates an executable "cuda_target" which is made up of the files
16205 specified. All of the non CUDA C files are compiled using the standard
16206 build rules specified by CMAKE and the cuda files are compiled to object
16207 files using nvcc and the host compiler. In addition CUDA_INCLUDE_DIRS is
16208 added automatically to include_directories(). Some standard CMake target
16209 calls can be used on the target after calling this macro
16210 (e.g. set_target_properties and target_link_libraries), but setting
16211 properties that adjust compilation flags will not affect code compiled by
16212 nvcc. Such flags should be modified before calling CUDA_ADD_EXECUTABLE,
16213 CUDA_ADD_LIBRARY or CUDA_WRAP_SRCS.
16214 CUDA_ADD_LIBRARY( cuda_target file0 file1 ...
16216 [STATIC | SHARED | MODULE] [EXCLUDE_FROM_ALL] [OPTIONS ...] )
16217 -- Same as CUDA_ADD_EXECUTABLE except that a library is created.
16218 CUDA_BUILD_CLEAN_TARGET()
16220 -- Creates a convenience target that deletes all the dependency files
16221 generated. You should make clean after running this target to ensure the
16222 dependency files get regenerated.
16223 CUDA_COMPILE( generated_files file0 file1 ... [STATIC | SHARED | MODULE]
16225 [OPTIONS ...] )
16226 -- Returns a list of generated files from the input source files to be used
16227 with ADD_LIBRARY or ADD_EXECUTABLE.
16228 CUDA_COMPILE_PTX( generated_files file0 file1 ... [OPTIONS ...] )
16230 -- Returns a list of PTX files generated from the input source files.
16231 CUDA_COMPILE_FATBIN( generated_files file0 file1 ... [OPTIONS ...] )
16233 -- Returns a list of FATBIN files generated from the input source files.
16234 CUDA_COMPILE_CUBIN( generated_files file0 file1 ... [OPTIONS ...] )
16236 -- Returns a list of CUBIN files generated from the input source files.
16237 CUDA_COMPUTE_SEPARABLE_COMPILATION_OBJECT_FILE_NAME( output_file_var
16239 cuda_target
16240 object_files )
16241 -- Compute the name of the intermediate link file used for separable
16242 compilation. This file name is typically passed into
16243 CUDA_LINK_SEPARABLE_COMPILATION_OBJECTS. output_file_var is produced
16244 based on cuda_target the list of objects files that need separable
16245 compilation as specified by object_files. If the object_files list is
16246 empty, then output_file_var will be empty. This function is called
16247 automatically for CUDA_ADD_LIBRARY and CUDA_ADD_EXECUTABLE. Note that
16248 this is a function and not a macro.
16249 CUDA_INCLUDE_DIRECTORIES( path0 path1 ... )
16251 -- Sets the directories that should be passed to nvcc
16252 (e.g. nvcc -Ipath0 -Ipath1 ... ). These paths usually contain other .cu
16253 files.
16254 CUDA_LINK_SEPARABLE_COMPILATION_OBJECTS( output_file_var cuda_target
16257 nvcc_flags object_files)
16258 -- Generates the link object required by separable compilation from the given
16259 object files. This is called automatically for CUDA_ADD_EXECUTABLE and
16260 CUDA_ADD_LIBRARY, but can be called manually when using CUDA_WRAP_SRCS
16261 directly. When called from CUDA_ADD_LIBRARY or CUDA_ADD_EXECUTABLE the
16262 nvcc_flags passed in are the same as the flags passed in via the OPTIONS
16263 argument. The only nvcc flag added automatically is the bitness flag as
16264 specified by CUDA_64_BIT_DEVICE_CODE. Note that this is a function
16265 instead of a macro.
16266 CUDA_SELECT_NVCC_ARCH_FLAGS(out_variable [target_CUDA_architectures])
16268 -- Selects GPU arch flags for nvcc based on target_CUDA_architectures
16269 target_CUDA_architectures : Auto | Common | All | LIST(ARCH_AND_PTX ...)
16270 - "Auto" detects local machine GPU compute arch at runtime.
16271 - "Common" and "All" cover common and entire subsets of architectures
16272 ARCH_AND_PTX : NAME | NUM.NUM | NUM.NUM(NUM.NUM) | NUM.NUM+PTX
16273 NAME: Fermi Kepler Maxwell Kepler+Tegra Kepler+Tesla Maxwell+Tegra Pascal
16274 NUM: Any number. Only those pairs are currently accepted by NVCC though:
16275 2.0 2.1 3.0 3.2 3.5 3.7 5.0 5.2 5.3 6.0 6.2
16276 Returns LIST of flags to be added to CUDA_NVCC_FLAGS in ${out_variable}
16277 Additionally, sets ${out_variable}_readable to the resulting numeric list
16278 Example:
16279 CUDA_SELECT_NVCC_ARCH_FLAGS(ARCH_FLAGS 3.0 3.5+PTX 5.2(5.0) Maxwell)
16280 LIST(APPEND CUDA_NVCC_FLAGS ${ARCH_FLAGS})
16281 More info on CUDA architectures: https://en.wikipedia.org/wiki/CUDA
16283 Note that this is a function instead of a macro.
16284 CUDA_WRAP_SRCS ( cuda_target format generated_files file0 file1 ...
16286 [STATIC | SHARED | MODULE] [OPTIONS ...] )
16287 -- This is where all the magic happens. CUDA_ADD_EXECUTABLE,
16288 CUDA_ADD_LIBRARY, CUDA_COMPILE, and CUDA_COMPILE_PTX all call this
16289 function under the hood.
16290 Given the list of files (file0 file1 ... fileN) this macro generates
16292 custom commands that generate either PTX or linkable objects (use "PTX" or
16293 "OBJ" for the format argument to switch). Files that don't end with .cu
16294 or have the HEADER_FILE_ONLY property are ignored.
16295 The arguments passed in after OPTIONS are extra command line options to
16297 give to nvcc. You can also specify per configuration options by
16298 specifying the name of the configuration followed by the options. General
16299 options must precede configuration specific options. Not all
16300 configurations need to be specified, only the ones provided will be used.
16301 OPTIONS -DFLAG=2 "-DFLAG_OTHER=space in flag"
16303 DEBUG -g
16304 RELEASE --use_fast_math
16305 RELWITHDEBINFO --use_fast_math;-g
16306 MINSIZEREL --use_fast_math
16307 For certain configurations (namely VS generating object files with
16309 CUDA_ATTACH_VS_BUILD_RULE_TO_CUDA_FILE set to ON), no generated file will
16310 be produced for the given cuda file. This is because when you add the
16311 cuda file to Visual Studio it knows that this file produces an object file
16312 and will link in the resulting object file automatically.
16313 This script will also generate a separate cmake script that is used at
16315 build time to invoke nvcc. This is for several reasons.
16316 1. nvcc can return negative numbers as return values which confuses
16318 Visual Studio into thinking that the command succeeded. The script now
16319 checks the error codes and produces errors when there was a problem.
16320 2. nvcc has been known to not delete incomplete results when it
16322 encounters problems. This confuses build systems into thinking the
16323 target was generated when in fact an unusable file exists. The script
16324 now deletes the output files if there was an error.
16325 3. By putting all the options that affect the build into a file and then
16327 make the build rule dependent on the file, the output files will be
16328 regenerated when the options change.
16329 This script also looks at optional arguments STATIC, SHARED, or MODULE to
16331 determine when to target the object compilation for a shared library.
16332 BUILD_SHARED_LIBS is ignored in CUDA_WRAP_SRCS, but it is respected in
16333 CUDA_ADD_LIBRARY. On some systems special flags are added for building
16334 objects intended for shared libraries. A preprocessor macro,
16335 <target_name>_EXPORTS is defined when a shared library compilation is
16336 detected.
16337 Flags passed into add_definitions with -D or /D are passed along to nvcc.
16339 The script defines the following variables:
16341 CUDA_VERSION_MAJOR -- The major version of cuda as reported by nvcc.
16343 CUDA_VERSION_MINOR -- The minor version.
16344 CUDA_VERSION
16345 CUDA_VERSION_STRING -- CUDA_VERSION_MAJOR.CUDA_VERSION_MINOR
16346 CUDA_HAS_FP16 -- Whether a short float (float16,fp16) is supported.
16347 CUDA_TOOLKIT_ROOT_DIR -- Path to the CUDA Toolkit (defined if not set).
16349 CUDA_SDK_ROOT_DIR -- Path to the CUDA SDK. Use this to find files in the
16350 SDK. This script will not directly support finding
16351 specific libraries or headers, as that isn't
16352 supported by NVIDIA. If you want to change
16353 libraries when the path changes see the
16354 FindCUDA.cmake script for an example of how to clear
16355 these variables. There are also examples of how to
16356 use the CUDA_SDK_ROOT_DIR to locate headers or
16357 libraries, if you so choose (at your own risk).
16358 CUDA_INCLUDE_DIRS -- Include directory for cuda headers. Added automatically
16359 for CUDA_ADD_EXECUTABLE and CUDA_ADD_LIBRARY.
16360 CUDA_LIBRARIES -- Cuda RT library.
16361 CUDA_CUFFT_LIBRARIES -- Device or emulation library for the Cuda FFT
16362 implementation (alternative to:
16363 CUDA_ADD_CUFFT_TO_TARGET macro)
16364 CUDA_CUBLAS_LIBRARIES -- Device or emulation library for the Cuda BLAS
16365 implementation (alternative to:
16366 CUDA_ADD_CUBLAS_TO_TARGET macro).
16367 CUDA_cudart_static_LIBRARY -- Statically linkable cuda runtime library.
16368 Only available for CUDA version 5.5+
16369 CUDA_cudadevrt_LIBRARY -- Device runtime library.
16370 Required for separable compilation.
16371 CUDA_cupti_LIBRARY -- CUDA Profiling Tools Interface library.
16372 Only available for CUDA version 4.0+.
16373 CUDA_curand_LIBRARY -- CUDA Random Number Generation library.
16374 Only available for CUDA version 3.2+.
16375 CUDA_cusolver_LIBRARY -- CUDA Direct Solver library.
16376 Only available for CUDA version 7.0+.
16377 CUDA_cusparse_LIBRARY -- CUDA Sparse Matrix library.
16378 Only available for CUDA version 3.2+.
16379 CUDA_npp_LIBRARY -- NVIDIA Performance Primitives lib.
16380 Only available for CUDA version 4.0+.
16381 CUDA_nppc_LIBRARY -- NVIDIA Performance Primitives lib (core).
16382 Only available for CUDA version 5.5+.
16383 CUDA_nppi_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
16384 Only available for CUDA version 5.5 - 8.0.
16385 CUDA_nppial_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
16386 Only available for CUDA version 9.0.
16387 CUDA_nppicc_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
16388 Only available for CUDA version 9.0.
16389 CUDA_nppicom_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
16390 Only available for CUDA version 9.0.
16391 CUDA_nppidei_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
16392 Only available for CUDA version 9.0.
16393 CUDA_nppif_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
16394 Only available for CUDA version 9.0.
16395 CUDA_nppig_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
16396 Only available for CUDA version 9.0.
16397 CUDA_nppim_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
16398 Only available for CUDA version 9.0.
16399 CUDA_nppist_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
16400 Only available for CUDA version 9.0.
16401 CUDA_nppisu_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
16402 Only available for CUDA version 9.0.
16403 CUDA_nppitc_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
16404 Only available for CUDA version 9.0.
16405 CUDA_npps_LIBRARY -- NVIDIA Performance Primitives lib (signal processing).
16406 Only available for CUDA version 5.5+.
16407 CUDA_nvcuvenc_LIBRARY -- CUDA Video Encoder library.
16408 Only available for CUDA version 3.2+.
16409 Windows only.
16410 CUDA_nvcuvid_LIBRARY -- CUDA Video Decoder library.
16411 Only available for CUDA version 3.2+.
16412 Windows only.
16413 CUDA_nvToolsExt_LIBRARY
16414 -- NVIDA CUDA Tools Extension library.
16415 Available for CUDA version 5+.
16416 CUDA_OpenCL_LIBRARY -- NVIDA CUDA OpenCL library.
16417 Available for CUDA version 5+.
16418 FindPythonInterp
16420 Deprecated since version 3.12: Use FindPython3, FindPython2 or Find‐
16421 Python instead.
16422 Find python interpreter
16425 This module finds if Python interpreter is installed and determines
16427 where the executables are. This code sets the following variables:
16428 PYTHONINTERP_FOUND - Was the Python executable found
16430 PYTHON_EXECUTABLE - path to the Python interpreter
16431 PYTHON_VERSION_STRING - Python version found e.g. 2.5.2
16433 PYTHON_VERSION_MAJOR - Python major version found e.g. 2
16434 PYTHON_VERSION_MINOR - Python minor version found e.g. 5
16435 PYTHON_VERSION_PATCH - Python patch version found e.g. 2
16436 The Python_ADDITIONAL_VERSIONS variable can be used to specify a list
16438 of version numbers that should be taken into account when searching for
16439 Python. You need to set this variable before calling find_pack‐
16440 age(PythonInterp).
16441 If calling both find_package(PythonInterp) and find_package(Python‐
16443 Libs), call find_package(PythonInterp) first to get the currently
16444 active Python version by default with a consistent version of
16445 PYTHON_LIBRARIES.
16446 NOTE:
16448 A call to find_package(PythonInterp ${V}) for python version V may
16449 find a python executable with no version suffix. In this case no
16450 attempt is made to avoid python executables from other versions.
16451 Use FindPython3, FindPython2 or FindPython instead.
16452 FindPythonLibs
16454 Deprecated since version 3.12: Use FindPython3, FindPython2 or Find‐
16455 Python instead.
16456 Find python libraries
16459 This module finds if Python is installed and determines where the
16461 include files and libraries are. It also determines what the name of
16462 the library is. This code sets the following variables:
16463 PYTHONLIBS_FOUND - have the Python libs been found
16465 PYTHON_LIBRARIES - path to the python library
16466 PYTHON_INCLUDE_PATH - path to where Python.h is found (deprecated)
16467 PYTHON_INCLUDE_DIRS - path to where Python.h is found
16468 PYTHON_DEBUG_LIBRARIES - path to the debug library (deprecated)
16469 PYTHONLIBS_VERSION_STRING - version of the Python libs found (since CMake 2.8.8)
16470 The Python_ADDITIONAL_VERSIONS variable can be used to specify a list
16472 of version numbers that should be taken into account when searching for
16473 Python. You need to set this variable before calling find_pack‐
16474 age(PythonLibs).
16475 If you’d like to specify the installation of Python to use, you should
16477 modify the following cache variables:
16478 PYTHON_LIBRARY - path to the python library
16480 PYTHON_INCLUDE_DIR - path to where Python.h is found
16481 If calling both find_package(PythonInterp) and find_package(Python‐
16483 Libs), call find_package(PythonInterp) first to get the currently
16484 active Python version by default with a consistent version of
16485 PYTHON_LIBRARIES.
16486 FindQt
16488 Searches for all installed versions of Qt3 or Qt4.
16489 This module cannot handle Qt5 or any later versions. For those, see
16491 cmake-qt(7).
16492 This module exists for the find_package() command only if policy
16494 CMP0084 is not set to NEW.
16495 This module should only be used if your project can work with multiple
16497 versions of Qt. If not, you should just directly use FindQt4 or
16498 FindQt3. If multiple versions of Qt are found on the machine, then The
16499 user must set the option DESIRED_QT_VERSION to the version they want to
16500 use. If only one version of qt is found on the machine, then the
16501 DESIRED_QT_VERSION is set to that version and the matching FindQt3 or
16502 FindQt4 module is included. Once the user sets DESIRED_QT_VERSION,
16503 then the FindQt3 or FindQt4 module is included.
16504 QT_REQUIRED if this is set to TRUE then if CMake can
16506 not find Qt4 or Qt3 an error is raised
16507 and a message is sent to the user.
16508 DESIRED_QT_VERSION OPTION is created
16510 QT4_INSTALLED is set to TRUE if qt4 is found.
16511 QT3_INSTALLED is set to TRUE if qt3 is found.
16512 FindwxWindows
16514 Deprecated since version 3.0: Replaced by FindwxWidgets.
16515 Find wxWindows (wxWidgets) installation
16518 This module finds if wxWindows/wxWidgets is installed and determines
16520 where the include files and libraries are. It also determines what the
16521 name of the library is. This code sets the following variables:
16522 WXWINDOWS_FOUND = system has WxWindows
16524 WXWINDOWS_LIBRARIES = path to the wxWindows libraries
16525 on Unix/Linux with additional
16526 linker flags from
16527 "wx-config --libs"
16528 CMAKE_WXWINDOWS_CXX_FLAGS = Compiler flags for wxWindows,
16529 essentially "`wx-config --cxxflags`"
16530 on Linux
16531 WXWINDOWS_INCLUDE_DIR = where to find "wx/wx.h" and "wx/setup.h"
16532 WXWINDOWS_LINK_DIRECTORIES = link directories, useful for rpath on
16533 Unix
16534 WXWINDOWS_DEFINITIONS = extra defines
16535 OPTIONS If you need OpenGL support please
16537 set(WXWINDOWS_USE_GL 1)
16539 in your CMakeLists.txt before you include this file.
16541 HAVE_ISYSTEM - true required to replace -I by -isystem on g++
16543 For convenience include Use_wxWindows.cmake in your project’s CMake‐
16545 Lists.txt using include(${CMAKE_CURRENT_LIST_DIR}/Use_wxWindows.cmake).
16546 USAGE
16548 set(WXWINDOWS_USE_GL 1)
16550 find_package(wxWindows)
16551 NOTES wxWidgets 2.6.x is supported for monolithic builds e.g. compiled
16553 in wx/build/msw dir as:
16554 nmake -f makefile.vc BUILD=debug SHARED=0 USE_OPENGL=1 MONOLITHIC=1
16556 DEPRECATED
16558 CMAKE_WX_CAN_COMPILE
16560 WXWINDOWS_LIBRARY
16561 CMAKE_WX_CXX_FLAGS
16562 WXWINDOWS_INCLUDE_PATH
16563 AUTHOR Jan Woetzel <http://www.mip.informatik.uni-kiel.de/~jw>
16565 (07/2003-01/2006)
16566 Legacy CPack Modules
16568 These modules used to be mistakenly exposed to the user, and have been
16569 moved out of user visibility. They are for CPack internal use, and
16570 should never be used directly.
16571 CPackArchive
16573 The documentation for the CPack Archive generator has moved here: CPack
16574 Archive Generator
16575 CPackBundle
16577 The documentation for the CPack Bundle generator has moved here: CPack
16578 Bundle Generator
16579 CPackCygwin
16581 The documentation for the CPack Cygwin generator has moved here: CPack
16582 Cygwin Generator
16583 CPackDeb
16585 The documentation for the CPack DEB generator has moved here: CPack DEB
16586 Generator
16587 CPackDMG
16589 The documentation for the CPack DragNDrop generator has moved here:
16590 CPack DragNDrop Generator
16591 CPackFreeBSD
16593 The documentation for the CPack FreeBSD generator has moved here: CPack
16594 FreeBSD Generator
16595 CPackNSIS
16597 The documentation for the CPack NSIS generator has moved here: CPack
16598 NSIS Generator
16599 CPackNuGet
16601 The documentation for the CPack NuGet generator has moved here: CPack
16602 NuGet Generator
16603 CPackPackageMaker
16605 The documentation for the CPack PackageMaker generator has moved here:
16606 CPack PackageMaker Generator
16607 CPackProductBuild
16609 The documentation for the CPack productbuild generator has moved here:
16610 CPack productbuild Generator
16611 CPackRPM
16613 The documentation for the CPack RPM generator has moved here: CPack RPM
16614 Generator
16615 CPackWIX
16617 The documentation for the CPack WIX generator has moved here: CPack WIX
16618 Generator
16619
16621 2000-2020 Kitware, Inc. and Contributors
166223.17.2 Apr 28, 2020 CMAKE-MODULES(7)