1CMAKE-MODULES(7) CMake CMAKE-MODULES(7)
2
6 cmake-modules - CMake Modules Reference
7
9 AddFileDependencies
10 ADD_FILE_DEPENDENCIES(source_file depend_files…)
11 Adds the given files as dependencies to source_file
13 AndroidTestUtilities
15 Create a test that automatically loads specified data onto an Android
16 device.
17 Introduction
19 Use this module to push data needed for testing an Android device
20 behavior onto a connected Android device. The module will accept files
21 and libraries as well as separate destinations for each. It will create
22 a test that loads the files into a device object store and link to them
23 from the specified destination. The files are only uploaded if they are
24 not already in the object store.
25 For example:
27 include(AndroidTestUtilities)
29 android_add_test_data(
30 example_setup_test
31 FILES <files>...
32 LIBS <libs>...
33 DEVICE_TEST_DIR "/data/local/tests/example"
34 DEVICE_OBJECT_STORE "/sdcard/.ExternalData/SHA"
35 )
36 At build time a test named “example_setup_test” will be created. Run
38 this test on the command line with ctest(1) to load the data onto the
39 Android device.
40 Module Functions
42 android_add_test_data
43 android_add_test_data(<test-name>
45 [FILES <files>...] [FILES_DEST <device-dir>]
46 [LIBS <libs>...] [LIBS_DEST <device-dir>]
47 [DEVICE_OBJECT_STORE <device-dir>]
48 [DEVICE_TEST_DIR <device-dir>]
49 [NO_LINK_REGEX <strings>...]
50 )
51 The android_add_test_data function is used to copy files and
53 libraries needed to run project-specific tests. On the host
54 operating system, this is done at build time. For on-device
55 testing, the files are loaded onto the device by the manufac‐
56 tured test at run time.
57 This function accepts the following named parameters:
59 FILES <files>...
61 zero or more files needed for testing
62 LIBS <libs>...
64 zero or more libraries needed for testing
65 FILES_DEST <device-dir>
67 absolute path where the data files are expected to be
68 LIBS_DEST <device-dir>
70 absolute path where the libraries are expected to be
71 DEVICE_OBJECT_STORE <device-dir>
73 absolute path to the location where the data is stored
74 on-device
75 DEVICE_TEST_DIR <device-dir>
77 absolute path to the root directory of the on-device test
78 location
79 NO_LINK_REGEX <strings>...
81 list of regex strings matching the names of files that
82 should be copied from the object store to the testing
83 directory
84 BundleUtilities
86 Functions to help assemble a standalone bundle application.
87 A collection of CMake utility functions useful for dealing with .app
89 bundles on the Mac and bundle-like directories on any OS.
90 The following functions are provided by this module:
92 fixup_bundle
94 copy_and_fixup_bundle
95 verify_app
96 get_bundle_main_executable
97 get_dotapp_dir
98 get_bundle_and_executable
99 get_bundle_all_executables
100 get_item_key
101 get_item_rpaths
102 clear_bundle_keys
103 set_bundle_key_values
104 get_bundle_keys
105 copy_resolved_item_into_bundle
106 copy_resolved_framework_into_bundle
107 fixup_bundle_item
108 verify_bundle_prerequisites
109 verify_bundle_symlinks
110 Requires CMake 2.6 or greater because it uses function, break and PAR‐
112 ENT_SCOPE. Also depends on GetPrerequisites.cmake.
113 FIXUP_BUNDLE(<app> <libs> <dirs>)
115 Fix up a bundle in-place and make it standalone, such that it can be
117 drag-n-drop copied to another machine and run on that machine as long
118 as all of the system libraries are compatible.
119 If you pass plugins to fixup_bundle as the libs parameter, you should
121 install them or copy them into the bundle before calling fixup_bundle.
122 The “libs” parameter is a list of libraries that must be fixed up, but
123 that cannot be determined by otool output analysis. (i.e., plugins)
124 Gather all the keys for all the executables and libraries in a bundle,
126 and then, for each key, copy each prerequisite into the bundle. Then
127 fix each one up according to its own list of prerequisites.
128 Then clear all the keys and call verify_app on the final bundle to
130 ensure that it is truly standalone.
131 As an optional parameter (IGNORE_ITEM) a list of file names can be
133 passed, which are then ignored (e.g. IGNORE_ITEM “vcre‐
134 dist_x86.exe;vcredist_x64.exe”)
135 COPY_AND_FIXUP_BUNDLE(<src> <dst> <libs> <dirs>)
137 Makes a copy of the bundle <src> at location <dst> and then fixes up
139 the new copied bundle in-place at <dst>…
140 VERIFY_APP(<app>)
142 Verifies that an application <app> appears valid based on running anal‐
144 ysis tools on it. Calls “message(FATAL_ERROR” if the application is
145 not verified.
146 As an optional parameter (IGNORE_ITEM) a list of file names can be
148 passed, which are then ignored (e.g. IGNORE_ITEM “vcre‐
149 dist_x86.exe;vcredist_x64.exe”)
150 GET_BUNDLE_MAIN_EXECUTABLE(<bundle> <result_var>)
152 The result will be the full path name of the bundle’s main executable
154 file or an “error:” prefixed string if it could not be determined.
155 GET_DOTAPP_DIR(<exe> <dotapp_dir_var>)
157 Returns the nearest parent dir whose name ends with “.app” given the
159 full path to an executable. If there is no such parent dir, then sim‐
160 ply return the dir containing the executable.
161 The returned directory may or may not exist.
163 GET_BUNDLE_AND_EXECUTABLE(<app> <bundle_var> <executable_var> <valid_var>)
165 Takes either a “.app” directory name or the name of an executable
167 nested inside a “.app” directory and returns the path to the “.app”
168 directory in <bundle_var> and the path to its main executable in <exe‐
169 cutable_var>
170 GET_BUNDLE_ALL_EXECUTABLES(<bundle> <exes_var>)
172 Scans the given bundle recursively for all executable files and accumu‐
174 lates them into a variable.
175 GET_ITEM_KEY(<item> <key_var>)
177 Given a file (item) name, generate a key that should be unique consid‐
179 ering the set of libraries that need copying or fixing up to make a
180 bundle standalone. This is essentially the file name including exten‐
181 sion with “.” replaced by “_”
182 This key is used as a prefix for CMake variables so that we can asso‐
184 ciate a set of variables with a given item based on its key.
185 CLEAR_BUNDLE_KEYS(<keys_var>)
187 Loop over the list of keys, clearing all the variables associated with
189 each key. After the loop, clear the list of keys itself.
190 Caller of get_bundle_keys should call clear_bundle_keys when done with
192 list of keys.
193 SET_BUNDLE_KEY_VALUES(<keys_var> <context> <item> <exepath> <dirs>
195 <copyflag> [<rpaths>])
196 Add a key to the list (if necessary) for the given item. If added,
198 also set all the variables associated with that key.
199 GET_BUNDLE_KEYS(<app> <libs> <dirs> <keys_var>)
201 Loop over all the executable and library files within the bundle (and
203 given as extra <libs>) and accumulate a list of keys representing them.
204 Set values associated with each key such that we can loop over all of
205 them and copy prerequisite libs into the bundle and then do appropriate
206 install_name_tool fixups.
207 As an optional parameter (IGNORE_ITEM) a list of file names can be
209 passed, which are then ignored (e.g. IGNORE_ITEM “vcre‐
210 dist_x86.exe;vcredist_x64.exe”)
211 COPY_RESOLVED_ITEM_INTO_BUNDLE(<resolved_item> <resolved_embedded_item>)
213 Copy a resolved item into the bundle if necessary. Copy is not neces‐
215 sary if the resolved_item is “the same as” the resolved_embedded_item.
216 COPY_RESOLVED_FRAMEWORK_INTO_BUNDLE(<resolved_item> <resolved_embedded_item>)
218 Copy a resolved framework into the bundle if necessary. Copy is not
220 necessary if the resolved_item is “the same as” the resolved_embed‐
221 ded_item.
222 By default, BU_COPY_FULL_FRAMEWORK_CONTENTS is not set. If you want
224 full frameworks embedded in your bundles, set BU_COPY_FULL_FRAME‐
225 WORK_CONTENTS to ON before calling fixup_bundle. By default,
226 COPY_RESOLVED_FRAMEWORK_INTO_BUNDLE copies the framework dylib itself
227 plus the framework Resources directory.
228 FIXUP_BUNDLE_ITEM(<resolved_embedded_item> <exepath> <dirs>)
230 Get the direct/non-system prerequisites of the resolved embedded item.
232 For each prerequisite, change the way it is referenced to the value of
233 the _EMBEDDED_ITEM keyed variable for that prerequisite. (Most likely
234 changing to an “@executable_path” style reference.)
235 This function requires that the resolved_embedded_item be “inside” the
237 bundle already. In other words, if you pass plugins to fixup_bundle as
238 the libs parameter, you should install them or copy them into the bun‐
239 dle before calling fixup_bundle. The “libs” parameter is a list of
240 libraries that must be fixed up, but that cannot be determined by otool
241 output analysis. (i.e., plugins)
242 Also, change the id of the item being fixed up to its own _EMBED‐
244 DED_ITEM value.
245 Accumulate changes in a local variable and make one call to
247 install_name_tool at the end of the function with all the changes at
248 once.
249 If the BU_CHMOD_BUNDLE_ITEMS variable is set then bundle items will be
251 marked writable before install_name_tool tries to change them.
252 VERIFY_BUNDLE_PREREQUISITES(<bundle> <result_var> <info_var>)
254 Verifies that the sum of all prerequisites of all files inside the bun‐
256 dle are contained within the bundle or are “system” libraries, presumed
257 to exist everywhere.
258 As an optional parameter (IGNORE_ITEM) a list of file names can be
260 passed, which are then ignored (e.g. IGNORE_ITEM “vcre‐
261 dist_x86.exe;vcredist_x64.exe”)
262 VERIFY_BUNDLE_SYMLINKS(<bundle> <result_var> <info_var>)
264 Verifies that any symlinks found in the bundle point to other files
266 that are already also in the bundle… Anything that points to an exter‐
267 nal file causes this function to fail the verification.
268 CheckCCompilerFlag
270 Check whether the C compiler supports a given flag.
271 check_c_compiler_flag
273 check_c_compiler_flag(<flag> <var>)
275 Check that the <flag> is accepted by the compiler without a
277 diagnostic. Stores the result in an internal cache entry named
278 <var>.
279 This command temporarily sets the CMAKE_REQUIRED_DEFINITIONS variable
281 and calls the check_c_source_compiles macro from the CheckCSourceCom‐
282 piles module. See documentation of that module for a listing of vari‐
283 ables that can otherwise modify the build.
284 A positive result from this check indicates only that the compiler did
286 not issue a diagnostic message when given the flag. Whether the flag
287 has any effect or even a specific one is beyond the scope of this mod‐
288 ule.
289 NOTE:
291 Since the try_compile() command forwards flags from variables like
292 CMAKE_C_FLAGS, unknown flags in such variables may cause a false
293 negative for this check.
294 CheckCSourceCompiles
296 Check if given C source compiles and links into an executable.
297 check_c_source_compiles
299 check_c_source_compiles(code resultVar [FAIL_REGEX regex1 [regex2...]])
301 Check that the source supplied in code can be compiled as a C
303 source file and linked as an executable (so it must contain at
304 least a main() function). The result will be stored in the
305 internal cache variable specified by resultVar, with a boolean
306 true value for success and boolean false for failure. If
307 FAIL_REGEX is provided, then failure is determined by checking
308 if anything in the output matches any of the specified regular
309 expressions.
310 The underlying check is performed by the try_compile() command.
312 The compile and link commands can be influenced by setting any
313 of the following variables prior to calling check_c_source_com‐
314 piles():
315 CMAKE_REQUIRED_FLAGS
317 Additional flags to pass to the compiler. Note that the
318 contents of CMAKE_C_FLAGS and its associated configura‐
319 tion-specific variable are automatically added to the
320 compiler command before the contents of
321 CMAKE_REQUIRED_FLAGS.
322 CMAKE_REQUIRED_DEFINITIONS
324 A ;-list of compiler definitions of the form -DFOO or
325 -DFOO=bar. A definition for the name specified by result‐
326 Var will also be added automatically.
327 CMAKE_REQUIRED_INCLUDES
329 A ;-list of header search paths to pass to the compiler.
330 These will be the only header search paths used by
331 try_compile(), i.e. the contents of the INCLUDE_DIRECTO‐
332 RIES directory property will be ignored.
333 CMAKE_REQUIRED_LIBRARIES
335 A ;-list of libraries to add to the link command. These
336 can be the name of system libraries or they can be
337 Imported Targets (see try_compile() for further details).
338 CMAKE_REQUIRED_QUIET
340 If this variable evaluates to a boolean true value, all
341 status messages associated with the check will be sup‐
342 pressed.
343 The check is only performed once, with the result cached in the
345 variable named by resultVar. Every subsequent CMake run will
346 re-use this cached value rather than performing the check again,
347 even if the code changes. In order to force the check to be
348 re-evaluated, the variable named by resultVar must be manually
349 removed from the cache.
350 CheckCSourceRuns
352 Check if given C source compiles and links into an executable and can
353 subsequently be run.
354 check_c_source_runs
356 check_c_source_runs(code resultVar)
358 Check that the source supplied in code can be compiled as a C
360 source file, linked as an executable and then run. The code must
361 contain at least a main() function. If the code could be built
362 and run successfully, the internal cache variable specified by
363 resultVar will be set to 1, otherwise it will be set to an value
364 that evaluates to boolean false (e.g. an empty string or an
365 error message).
366 The underlying check is performed by the try_run() command. The
368 compile and link commands can be influenced by setting any of
369 the following variables prior to calling check_c_source_runs():
370 CMAKE_REQUIRED_FLAGS
372 Additional flags to pass to the compiler. Note that the
373 contents of CMAKE_C_FLAGS and its associated configura‐
374 tion-specific variable are automatically added to the
375 compiler command before the contents of
376 CMAKE_REQUIRED_FLAGS.
377 CMAKE_REQUIRED_DEFINITIONS
379 A ;-list of compiler definitions of the form -DFOO or
380 -DFOO=bar. A definition for the name specified by result‐
381 Var will also be added automatically.
382 CMAKE_REQUIRED_INCLUDES
384 A ;-list of header search paths to pass to the compiler.
385 These will be the only header search paths used by
386 try_run(), i.e. the contents of the INCLUDE_DIRECTORIES
387 directory property will be ignored.
388 CMAKE_REQUIRED_LIBRARIES
390 A ;-list of libraries to add to the link command. These
391 can be the name of system libraries or they can be
392 Imported Targets (see try_run() for further details).
393 CMAKE_REQUIRED_QUIET
395 If this variable evaluates to a boolean true value, all
396 status messages associated with the check will be sup‐
397 pressed.
398 The check is only performed once, with the result cached in the
400 variable named by resultVar. Every subsequent CMake run will
401 re-use this cached value rather than performing the check again,
402 even if the code changes. In order to force the check to be
403 re-evaluated, the variable named by resultVar must be manually
404 removed from the cache.
405 CheckCXXCompilerFlag
407 Check whether the CXX compiler supports a given flag.
408 check_cxx_compiler_flag
410 check_cxx_compiler_flag(<flag> <var>)
412 Check that the <flag> is accepted by the compiler without a
414 diagnostic. Stores the result in an internal cache entry named
415 <var>.
416 This command temporarily sets the CMAKE_REQUIRED_DEFINITIONS variable
418 and calls the check_cxx_source_compiles macro from the CheckCXXSource‐
419 Compiles module. See documentation of that module for a listing of
420 variables that can otherwise modify the build.
421 A positive result from this check indicates only that the compiler did
423 not issue a diagnostic message when given the flag. Whether the flag
424 has any effect or even a specific one is beyond the scope of this mod‐
425 ule.
426 NOTE:
428 Since the try_compile() command forwards flags from variables like
429 CMAKE_CXX_FLAGS, unknown flags in such variables may cause a false
430 negative for this check.
431 CheckCXXSourceCompiles
433 Check if given C++ source compiles and links into an executable.
434 check_cxx_source_compiles
436 check_cxx_source_compiles(code resultVar [FAIL_REGEX regex1 [regex2...]])
438 Check that the source supplied in code can be compiled as a C++
440 source file and linked as an executable (so it must contain at
441 least a main() function). The result will be stored in the
442 internal cache variable specified by resultVar, with a boolean
443 true value for success and boolean false for failure. If
444 FAIL_REGEX is provided, then failure is determined by checking
445 if anything in the output matches any of the specified regular
446 expressions.
447 The underlying check is performed by the try_compile() command.
449 The compile and link commands can be influenced by setting any
450 of the following variables prior to calling
451 check_cxx_source_compiles():
452 CMAKE_REQUIRED_FLAGS
454 Additional flags to pass to the compiler. Note that the
455 contents of CMAKE_CXX_FLAGS and its associated configura‐
456 tion-specific variable are automatically added to the
457 compiler command before the contents of
458 CMAKE_REQUIRED_FLAGS.
459 CMAKE_REQUIRED_DEFINITIONS
461 A ;-list of compiler definitions of the form -DFOO or
462 -DFOO=bar. A definition for the name specified by result‐
463 Var will also be added automatically.
464 CMAKE_REQUIRED_INCLUDES
466 A ;-list of header search paths to pass to the compiler.
467 These will be the only header search paths used by
468 try_compile(), i.e. the contents of the INCLUDE_DIRECTO‐
469 RIES directory property will be ignored.
470 CMAKE_REQUIRED_LIBRARIES
472 A ;-list of libraries to add to the link command. These
473 can be the name of system libraries or they can be
474 Imported Targets (see try_compile() for further details).
475 CMAKE_REQUIRED_QUIET
477 If this variable evaluates to a boolean true value, all
478 status messages associated with the check will be sup‐
479 pressed.
480 The check is only performed once, with the result cached in the
482 variable named by resultVar. Every subsequent CMake run will
483 re-use this cached value rather than performing the check again,
484 even if the code changes. In order to force the check to be
485 re-evaluated, the variable named by resultVar must be manually
486 removed from the cache.
487 CheckCXXSourceRuns
489 Check if given C++ source compiles and links into an executable and can
490 subsequently be run.
491 check_cxx_source_runs
493 check_cxx_source_runs(code resultVar)
495 Check that the source supplied in code can be compiled as a C++
497 source file, linked as an executable and then run. The code must
498 contain at least a main() function. If the code could be built
499 and run successfully, the internal cache variable specified by
500 resultVar will be set to 1, otherwise it will be set to an value
501 that evaluates to boolean false (e.g. an empty string or an
502 error message).
503 The underlying check is performed by the try_run() command. The
505 compile and link commands can be influenced by setting any of
506 the following variables prior to calling
507 check_cxx_source_runs():
508 CMAKE_REQUIRED_FLAGS
510 Additional flags to pass to the compiler. Note that the
511 contents of CMAKE_CXX_FLAGS and its associated configura‐
512 tion-specific variable are automatically added to the
513 compiler command before the contents of
514 CMAKE_REQUIRED_FLAGS.
515 CMAKE_REQUIRED_DEFINITIONS
517 A ;-list of compiler definitions of the form -DFOO or
518 -DFOO=bar. A definition for the name specified by result‐
519 Var will also be added automatically.
520 CMAKE_REQUIRED_INCLUDES
522 A ;-list of header search paths to pass to the compiler.
523 These will be the only header search paths used by
524 try_run(), i.e. the contents of the INCLUDE_DIRECTORIES
525 directory property will be ignored.
526 CMAKE_REQUIRED_LIBRARIES
528 A ;-list of libraries to add to the link command. These
529 can be the name of system libraries or they can be
530 Imported Targets (see try_run() for further details).
531 CMAKE_REQUIRED_QUIET
533 If this variable evaluates to a boolean true value, all
534 status messages associated with the check will be sup‐
535 pressed.
536 The check is only performed once, with the result cached in the
538 variable named by resultVar. Every subsequent CMake run will
539 re-use this cached value rather than performing the check again,
540 even if the code changes. In order to force the check to be
541 re-evaluated, the variable named by resultVar must be manually
542 removed from the cache.
543 CheckCXXSymbolExists
545 Check if a symbol exists as a function, variable, or macro in C++
546 CHECK_CXX_SYMBOL_EXISTS(<symbol> <files> <variable>)
548 Check that the <symbol> is available after including given header
550 <files> and store the result in a <variable>. Specify the list of
551 files in one argument as a semicolon-separated list. CHECK_CXX_SYM‐
552 BOL_EXISTS() can be used to check in C++ files, as opposed to
553 CHECK_SYMBOL_EXISTS(), which works only for C.
554 If the header files define the symbol as a macro it is considered
556 available and assumed to work. If the header files declare the symbol
557 as a function or variable then the symbol must also be available for
558 linking. If the symbol is a type or enum value it will not be recog‐
559 nized (consider using CheckTypeSize or CheckCSourceCompiles).
560 The following variables may be set before calling this macro to modify
562 the way the check is run:
563 CMAKE_REQUIRED_FLAGS = string of compile command line flags
565 CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
566 CMAKE_REQUIRED_INCLUDES = list of include directories
567 CMAKE_REQUIRED_LIBRARIES = list of libraries to link
568 CMAKE_REQUIRED_QUIET = execute quietly without messages
569 CheckFortranCompilerFlag
571 Check whether the Fortran compiler supports a given flag.
572 check_fortran_compiler_flag
574 check_fortran_compiler_flag(<flag> <var>)
576 Check that the <flag> is accepted by the compiler without a
578 diagnostic. Stores the result in an internal cache entry named
579 <var>.
580 This command temporarily sets the CMAKE_REQUIRED_DEFINITIONS variable
582 and calls the check_fortran_source_compiles macro from the CheckFor‐
583 tranSourceCompiles module. See documentation of that module for a
584 listing of variables that can otherwise modify the build.
585 A positive result from this check indicates only that the compiler did
587 not issue a diagnostic message when given the flag. Whether the flag
588 has any effect or even a specific one is beyond the scope of this mod‐
589 ule.
590 NOTE:
592 Since the try_compile() command forwards flags from variables like
593 CMAKE_Fortran_FLAGS, unknown flags in such variables may cause a
594 false negative for this check.
595 CheckFortranFunctionExists
597 macro which checks if the Fortran function exists
598 CHECK_FORTRAN_FUNCTION_EXISTS(FUNCTION VARIABLE)
600 FUNCTION - the name of the Fortran function
602 VARIABLE - variable to store the result
603 Will be created as an internal cache variable.
604 The following variables may be set before calling this macro to modify
606 the way the check is run:
607 CMAKE_REQUIRED_LIBRARIES = list of libraries to link
609 CheckFortranSourceCompiles
611 Check if given Fortran source compiles and links into an executable.
612 check_fortran_source_compiles
614 check_fortran_source_compiles(code resultVar
616 [FAIL_REGEX regex1 [regex2...]]
617 [SRC_EXT ext]
618 )
619 Check that the source supplied in code can be compiled as a For‐
621 tran source file and linked as an executable (so it must contain
622 at least a PROGRAM entry point). The result will be stored in
623 the internal cache variable specified by resultVar, with a bool‐
624 ean true value for success and boolean false for failure. If
625 FAIL_REGEX is provided, then failure is determined by checking
626 if anything in the output matches any of the specified regular
627 expressions.
628 By default, the test source file will be given a .F file exten‐
630 sion. The SRC_EXT option can be used to override this with .ext
631 instead.
632 The underlying check is performed by the try_compile() command.
634 The compile and link commands can be influenced by setting any
635 of the following variables prior to calling check_for‐
636 tran_source_compiles():
637 CMAKE_REQUIRED_FLAGS
639 Additional flags to pass to the compiler. Note that the
640 contents of CMAKE_Fortran_FLAGS and its associated con‐
641 figuration-specific variable are automatically added to
642 the compiler command before the contents of
643 CMAKE_REQUIRED_FLAGS.
644 CMAKE_REQUIRED_DEFINITIONS
646 A ;-list of compiler definitions of the form -DFOO or
647 -DFOO=bar. A definition for the name specified by result‐
648 Var will also be added automatically.
649 CMAKE_REQUIRED_INCLUDES
651 A ;-list of header search paths to pass to the compiler.
652 These will be the only header search paths used by
653 try_compile(), i.e. the contents of the INCLUDE_DIRECTO‐
654 RIES directory property will be ignored.
655 CMAKE_REQUIRED_LIBRARIES
657 A ;-list of libraries to add to the link command. These
658 can be the name of system libraries or they can be
659 Imported Targets (see try_compile() for further details).
660 CMAKE_REQUIRED_QUIET
662 If this variable evaluates to a boolean true value, all
663 status messages associated with the check will be sup‐
664 pressed.
665 The check is only performed once, with the result cached in the
667 variable named by resultVar. Every subsequent CMake run will
668 re-use this cached value rather than performing the check again,
669 even if the code changes. In order to force the check to be
670 re-evaluated, the variable named by resultVar must be manually
671 removed from the cache.
672 CheckFunctionExists
674 Check if a C function can be linked:
675 check_function_exists(<function> <variable>)
677 Check that the <function> is provided by libraries on the system and
679 store the result in a <variable>. <variable> will be created as an
680 internal cache variable.
681 The following variables may be set before calling this macro to modify
683 the way the check is run:
684 CMAKE_REQUIRED_FLAGS = string of compile command line flags
686 CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
687 CMAKE_REQUIRED_INCLUDES = list of include directories
688 CMAKE_REQUIRED_LIBRARIES = list of libraries to link
689 CMAKE_REQUIRED_QUIET = execute quietly without messages
690 NOTE:
692 Prefer using CheckSymbolExists instead of this module, for the fol‐
693 lowing reasons:
694 · check_function_exists() can’t detect functions that are inlined in
696 headers or specified as a macro.
697 · check_function_exists() can’t detect anything in the 32-bit ver‐
699 sions of the Win32 API, because of a mismatch in calling conven‐
700 tions.
701 · check_function_exists() only verifies linking, it does not verify
703 that the function is declared in system headers.
704 CheckIPOSupported
706 Check whether the compiler supports an interprocedural optimization
707 (IPO/LTO). Use this before enabling the INTERPROCEDURAL_OPTIMIZATION
708 target property.
709 check_ipo_supported
711 check_ipo_supported([RESULT <result>] [OUTPUT <output>]
713 [LANGUAGES <lang>...])
714 Options are:
716 RESULT <result>
718 Set <result> variable to YES if IPO is supported by the
719 compiler and NO otherwise. If this option is not given
720 then the command will issue a fatal error if IPO is not
721 supported.
722 OUTPUT <output>
724 Set <output> variable with details about any error.
725 LANGUAGES <lang>...
727 Specify languages whose compilers to check. Languages C,
728 CXX, and Fortran are supported.
729 It makes no sense to use this module when CMP0069 is set to OLD so mod‐
731 ule will return error in this case. See policy CMP0069 for details.
732 Examples
734 check_ipo_supported() # fatal error if IPO is not supported
735 set_property(TARGET foo PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
736 # Optional IPO. Do not use IPO if it's not supported by compiler.
738 check_ipo_supported(RESULT result OUTPUT output)
739 if(result)
740 set_property(TARGET foo PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
741 else()
742 message(WARNING "IPO is not supported: ${output}")
743 endif()
744 CheckIncludeFileCXX
746 Provides a macro to check if a header file can be included in CXX.
747 CHECK_INCLUDE_FILE_CXX
749 CHECK_INCLUDE_FILE_CXX(<include> <variable> [<flags>])
751 Check if the given <include> file may be included in a CXX
753 source file and store the result in an internal cache entry
754 named <variable>. The optional third argument may be used to
755 add compilation flags to the check (or use CMAKE_REQUIRED_FLAGS
756 below).
757 The following variables may be set before calling this macro to modify
759 the way the check is run:
760 CMAKE_REQUIRED_FLAGS
762 string of compile command line flags
763 CMAKE_REQUIRED_DEFINITIONS
765 list of macros to define (-DFOO=bar)
766 CMAKE_REQUIRED_INCLUDES
768 list of include directories
769 CMAKE_REQUIRED_QUIET
771 execute quietly without messages
772 See modules CheckIncludeFile and CheckIncludeFiles to check for one or
774 more C headers.
775 CheckIncludeFile
777 Provides a macro to check if a header file can be included in C.
778 CHECK_INCLUDE_FILE
780 CHECK_INCLUDE_FILE(<include> <variable> [<flags>])
782 Check if the given <include> file may be included in a C source
784 file and store the result in an internal cache entry named
785 <variable>. The optional third argument may be used to add com‐
786 pilation flags to the check (or use CMAKE_REQUIRED_FLAGS below).
787 The following variables may be set before calling this macro to modify
789 the way the check is run:
790 CMAKE_REQUIRED_FLAGS
792 string of compile command line flags
793 CMAKE_REQUIRED_DEFINITIONS
795 list of macros to define (-DFOO=bar)
796 CMAKE_REQUIRED_INCLUDES
798 list of include directories
799 CMAKE_REQUIRED_QUIET
801 execute quietly without messages
802 See the CheckIncludeFiles module to check for multiple headers at once.
804 See the CheckIncludeFileCXX module to check for headers using the CXX
805 language.
806 CheckIncludeFiles
808 Provides a macro to check if a list of one or more header files can be
809 included together.
810 CHECK_INCLUDE_FILES
812 CHECK_INCLUDE_FILES("<includes>" <variable> [LANGUAGE <language>])
814 Check if the given <includes> list may be included together in a
816 source file and store the result in an internal cache entry
817 named <variable>. Specify the <includes> argument as a ;-list
818 of header file names.
819 If LANGUAGE is set, the specified compiler will be used to perform the
821 check. Acceptable values are C and CXX. If not set, the C compiler will
822 be used if enabled. If the C compiler is not enabled, the C++ compiler
823 will be used if enabled.
824 The following variables may be set before calling this macro to modify
826 the way the check is run:
827 CMAKE_REQUIRED_FLAGS
829 string of compile command line flags
830 CMAKE_REQUIRED_DEFINITIONS
832 list of macros to define (-DFOO=bar)
833 CMAKE_REQUIRED_INCLUDES
835 list of include directories
836 CMAKE_REQUIRED_QUIET
838 execute quietly without messages
839 See modules CheckIncludeFile and CheckIncludeFileCXX to check for a
841 single header file in C or CXX languages.
842 CheckLanguage
844 Check if a language can be enabled
845 Usage:
847 check_language(<lang>)
849 where <lang> is a language that may be passed to enable_language() such
851 as “Fortran”. If CMAKE_<lang>_COMPILER is already defined the check
852 does nothing. Otherwise it tries enabling the language in a test
853 project. The result is cached in CMAKE_<lang>_COMPILER as the compiler
854 that was found, or NOTFOUND if the language cannot be enabled.
855 Example:
857 check_language(Fortran)
859 if(CMAKE_Fortran_COMPILER)
860 enable_language(Fortran)
861 else()
862 message(STATUS "No Fortran support")
863 endif()
864 CheckLibraryExists
866 Check if the function exists.
867 CHECK_LIBRARY_EXISTS (LIBRARY FUNCTION LOCATION VARIABLE)
869 LIBRARY - the name of the library you are looking for
871 FUNCTION - the name of the function
872 LOCATION - location where the library should be found
873 VARIABLE - variable to store the result
874 Will be created as an internal cache variable.
875 The following variables may be set before calling this macro to modify
877 the way the check is run:
878 CMAKE_REQUIRED_FLAGS = string of compile command line flags
880 CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
881 CMAKE_REQUIRED_LIBRARIES = list of libraries to link
882 CMAKE_REQUIRED_QUIET = execute quietly without messages
883 CheckPrototypeDefinition
885 Check if the prototype we expect is correct.
886 check_prototype_definition(FUNCTION PROTOTYPE RETURN HEADER VARIABLE)
888 FUNCTION - The name of the function (used to check if prototype exists)
890 PROTOTYPE- The prototype to check.
891 RETURN - The return value of the function.
892 HEADER - The header files required.
893 VARIABLE - The variable to store the result.
894 Will be created as an internal cache variable.
895 Example:
897 check_prototype_definition(getpwent_r
899 "struct passwd *getpwent_r(struct passwd *src, char *buf, int buflen)"
900 "NULL"
901 "unistd.h;pwd.h"
902 SOLARIS_GETPWENT_R)
903 The following variables may be set before calling this macro to modify
905 the way the check is run:
906 CMAKE_REQUIRED_FLAGS = string of compile command line flags
908 CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
909 CMAKE_REQUIRED_INCLUDES = list of include directories
910 CMAKE_REQUIRED_LIBRARIES = list of libraries to link
911 CMAKE_REQUIRED_QUIET = execute quietly without messages
912 CheckStructHasMember
914 Check if the given struct or class has the specified member variable
915 CHECK_STRUCT_HAS_MEMBER(<struct> <member> <header> <variable>
917 [LANGUAGE <language>])
918 <struct> - the name of the struct or class you are interested in
920 <member> - the member which existence you want to check
921 <header> - the header(s) where the prototype should be declared
922 <variable> - variable to store the result
923 <language> - the compiler to use (C or CXX)
924 The following variables may be set before calling this macro to modify
926 the way the check is run:
927 CMAKE_REQUIRED_FLAGS = string of compile command line flags
929 CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
930 CMAKE_REQUIRED_INCLUDES = list of include directories
931 CMAKE_REQUIRED_LIBRARIES = list of libraries to link
932 CMAKE_REQUIRED_QUIET = execute quietly without messages
933 Example: CHECK_STRUCT_HAS_MEMBER(“struct timeval” tv_sec sys/select.h
935 HAVE_TIMEVAL_TV_SEC LANGUAGE C)
936 CheckSymbolExists
938 Provides a macro to check if a symbol exists as a function, variable,
939 or macro in C.
940 check_symbol_exists
942 check_symbol_exists(<symbol> <files> <variable>)
944 Check that the <symbol> is available after including given
946 header <files> and store the result in a <variable>. Specify
947 the list of files in one argument as a semicolon-separated list.
948 <variable> will be created as an internal cache variable.
949 If the header files define the symbol as a macro it is considered
951 available and assumed to work. If the header files declare the symbol
952 as a function or variable then the symbol must also be available for
953 linking (so intrinsics may not be detected). If the symbol is a type,
954 enum value, or intrinsic it will not be recognized (consider using
955 CheckTypeSize or CheckCSourceCompiles). If the check needs to be done
956 in C++, consider using CheckCXXSymbolExists instead.
957 The following variables may be set before calling this macro to modify
959 the way the check is run:
960 CMAKE_REQUIRED_FLAGS
962 string of compile command line flags
963 CMAKE_REQUIRED_DEFINITIONS
965 list of macros to define (-DFOO=bar)
966 CMAKE_REQUIRED_INCLUDES
968 list of include directories
969 CMAKE_REQUIRED_LIBRARIES
971 list of libraries to link
972 CMAKE_REQUIRED_QUIET
974 execute quietly without messages
975 CheckTypeSize
977 Check sizeof a type
978 CHECK_TYPE_SIZE(TYPE VARIABLE [BUILTIN_TYPES_ONLY]
980 [LANGUAGE <language>])
981 Check if the type exists and determine its size. On return,
983 “HAVE_${VARIABLE}” holds the existence of the type, and “${VARIABLE}”
984 holds one of the following:
985 <size> = type has non-zero size <size>
987 "0" = type has arch-dependent size (see below)
988 "" = type does not exist
989 Both HAVE_${VARIABLE} and ${VARIABLE} will be created as internal cache
991 variables.
992 Furthermore, the variable “${VARIABLE}_CODE” holds C preprocessor code
994 to define the macro “${VARIABLE}” to the size of the type, or leave the
995 macro undefined if the type does not exist.
996 The variable “${VARIABLE}” may be “0” when CMAKE_OSX_ARCHITECTURES has
998 multiple architectures for building OS X universal binaries. This
999 indicates that the type size varies across architectures. In this case
1000 “${VARIABLE}_CODE” contains C preprocessor tests mapping from each
1001 architecture macro to the corresponding type size. The list of archi‐
1002 tecture macros is stored in “${VARIABLE}_KEYS”, and the value for each
1003 key is stored in “${VARIABLE}-${KEY}”.
1004 If the BUILTIN_TYPES_ONLY option is not given, the macro checks for
1006 headers <sys/types.h>, <stdint.h>, and <stddef.h>, and saves results in
1007 HAVE_SYS_TYPES_H, HAVE_STDINT_H, and HAVE_STDDEF_H. The type size
1008 check automatically includes the available headers, thus supporting
1009 checks of types defined in the headers.
1010 If LANGUAGE is set, the specified compiler will be used to perform the
1012 check. Acceptable values are C and CXX
1013 Despite the name of the macro you may use it to check the size of more
1015 complex expressions, too. To check e.g. for the size of a struct mem‐
1016 ber you can do something like this:
1017 check_type_size("((struct something*)0)->member" SIZEOF_MEMBER)
1019 The following variables may be set before calling this macro to modify
1021 the way the check is run:
1022 CMAKE_REQUIRED_FLAGS = string of compile command line flags
1024 CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
1025 CMAKE_REQUIRED_INCLUDES = list of include directories
1026 CMAKE_REQUIRED_LIBRARIES = list of libraries to link
1027 CMAKE_REQUIRED_QUIET = execute quietly without messages
1028 CMAKE_EXTRA_INCLUDE_FILES = list of extra headers to include
1029 CheckVariableExists
1031 Check if the variable exists.
1032 CHECK_VARIABLE_EXISTS(VAR VARIABLE)
1034 VAR - the name of the variable
1036 VARIABLE - variable to store the result
1037 Will be created as an internal cache variable.
1038 This macro is only for C variables.
1040 The following variables may be set before calling this macro to modify
1042 the way the check is run:
1043 CMAKE_REQUIRED_FLAGS = string of compile command line flags
1045 CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
1046 CMAKE_REQUIRED_LIBRARIES = list of libraries to link
1047 CMAKE_REQUIRED_QUIET = execute quietly without messages
1048 CMakeAddFortranSubdirectory
1050 Use MinGW gfortran from VS if a fortran compiler is not found.
1051 The ‘add_fortran_subdirectory’ function adds a subdirectory to a
1053 project that contains a fortran only sub-project. The module will
1054 check the current compiler and see if it can support fortran. If no
1055 fortran compiler is found and the compiler is MSVC, then this module
1056 will find the MinGW gfortran. It will then use an external project to
1057 build with the MinGW tools. It will also create imported targets for
1058 the libraries created. This will only work if the fortran code is
1059 built into a dll, so BUILD_SHARED_LIBS is turned on in the project. In
1060 addition the CMAKE_GNUtoMS option is set to on, so that the MS .lib
1061 files are created. Usage is as follows:
1062 cmake_add_fortran_subdirectory(
1064 <subdir> # name of subdirectory
1065 PROJECT <project_name> # project name in subdir top CMakeLists.txt
1066 ARCHIVE_DIR <dir> # dir where project places .lib files
1067 RUNTIME_DIR <dir> # dir where project places .dll files
1068 LIBRARIES <lib>... # names of library targets to import
1069 LINK_LIBRARIES # link interface libraries for LIBRARIES
1070 [LINK_LIBS <lib> <dep>...]...
1071 CMAKE_COMMAND_LINE ... # extra command line flags to pass to cmake
1072 NO_EXTERNAL_INSTALL # skip installation of external project
1073 )
1074 Relative paths in ARCHIVE_DIR and RUNTIME_DIR are interpreted with
1076 respect to the build directory corresponding to the source directory in
1077 which the function is invoked.
1078 Limitations:
1080 NO_EXTERNAL_INSTALL is required for forward compatibility with a future
1082 version that supports installation of the external project binaries
1083 during “make install”.
1084 CMakeBackwardCompatibilityCXX
1086 define a bunch of backwards compatibility variables
1087 CMAKE_ANSI_CXXFLAGS - flag for ansi c++
1089 CMAKE_HAS_ANSI_STRING_STREAM - has <strstream>
1090 include(TestForANSIStreamHeaders)
1091 include(CheckIncludeFileCXX)
1092 include(TestForSTDNamespace)
1093 include(TestForANSIForScope)
1094 CMakeDependentOption
1096 Macro to provide an option dependent on other options.
1097 This macro presents an option to the user only if a set of other condi‐
1099 tions are true. When the option is not presented a default value is
1100 used, but any value set by the user is preserved for when the option is
1101 presented again. Example invocation:
1102 CMAKE_DEPENDENT_OPTION(USE_FOO "Use Foo" ON
1104 "USE_BAR;NOT USE_ZOT" OFF)
1105 If USE_BAR is true and USE_ZOT is false, this provides an option called
1107 USE_FOO that defaults to ON. Otherwise, it sets USE_FOO to OFF. If
1108 the status of USE_BAR or USE_ZOT ever changes, any value for the
1109 USE_FOO option is saved so that when the option is re-enabled it
1110 retains its old value.
1111 CMakeDetermineVSServicePack
1113 Deprecated. Do not use.
1114 The functionality of this module has been superseded by the
1116 CMAKE_<LANG>_COMPILER_VERSION variable that contains the compiler ver‐
1117 sion number.
1118 Determine the Visual Studio service pack of the ‘cl’ in use.
1120 Usage:
1122 if(MSVC)
1124 include(CMakeDetermineVSServicePack)
1125 DetermineVSServicePack( my_service_pack )
1126 if( my_service_pack )
1127 message(STATUS "Detected: ${my_service_pack}")
1128 endif()
1129 endif()
1130 Function DetermineVSServicePack sets the given variable to one of the
1132 following values or an empty string if unknown:
1133 vc80, vc80sp1
1135 vc90, vc90sp1
1136 vc100, vc100sp1
1137 vc110, vc110sp1, vc110sp2, vc110sp3, vc110sp4
1138 CMakeExpandImportedTargets
1140 Deprecated. Do not use.
1141 This module was once needed to expand imported targets to the underly‐
1143 ing libraries they reference on disk for use with the try_compile() and
1144 try_run() commands. These commands now support imported libraries in
1145 their LINK_LIBRARIES options (since CMake 2.8.11 for try_compile() and
1146 since CMake 3.2 for try_run()).
1147 This module does not support the policy CMP0022 NEW behavior or use of
1149 the INTERFACE_LINK_LIBRARIES property because generator expressions
1150 cannot be evaluated during configuration.
1151 CMAKE_EXPAND_IMPORTED_TARGETS(<var> LIBRARIES lib1 lib2...libN
1153 [CONFIGURATION <config>])
1154 CMAKE_EXPAND_IMPORTED_TARGETS() takes a list of libraries and replaces
1156 all imported targets contained in this list with their actual file
1157 paths of the referenced libraries on disk, including the libraries from
1158 their link interfaces. If a CONFIGURATION is given, it uses the
1159 respective configuration of the imported targets if it exists. If no
1160 CONFIGURATION is given, it uses the first configuration from
1161 ${CMAKE_CONFIGURATION_TYPES} if set, otherwise ${CMAKE_BUILD_TYPE}.
1162 cmake_expand_imported_targets(expandedLibs
1164 LIBRARIES ${CMAKE_REQUIRED_LIBRARIES}
1165 CONFIGURATION "${CMAKE_TRY_COMPILE_CONFIGURATION}" )
1166 CMakeFindDependencyMacro
1168 find_dependency
1169 The find_dependency() macro wraps a find_package() call for a
1170 package dependency:
1171 find_dependency(<dep> [...])
1173 It is designed to be used in a Package Configuration File
1175 (<package>Config.cmake). find_dependency forwards the correct
1176 parameters for QUIET and REQUIRED which were passed to the orig‐
1177 inal find_package() call. Any additional arguments specified
1178 are forwarded to find_package().
1179 If the dependency could not be found it sets an informative
1181 diagnostic message and calls return() to end processing of the
1182 calling package configuration file and return to the find_pack‐
1183 age() command that loaded it.
1184 NOTE:
1186 The call to return() makes this macro unsuitable to call from
1187 Find Modules.
1188 CMakeFindFrameworks
1190 helper module to find OSX frameworks
1191 This module reads hints about search locations from variables:
1193 CMAKE_FIND_FRAMEWORK_EXTRA_LOCATIONS - Extra directories
1195 CMakeFindPackageMode
1197 This file is executed by cmake when invoked with –find-package. It
1198 expects that the following variables are set using -D:
1199 NAME name of the package
1201 COMPILER_ID
1203 the CMake compiler ID for which the result is, i.e.
1204 GNU/Intel/Clang/MSVC, etc.
1205 LANGUAGE
1207 language for which the result will be used, i.e. C/CXX/For‐
1208 tran/ASM
1209 MODE
1211 EXIST only check for existence of the given package
1213 COMPILE
1215 print the flags needed for compiling an object file which
1216 uses the given package
1217 LINK print the flags needed for linking when using the given
1219 package
1220 QUIET if TRUE, don’t print anything
1222 CMakeForceCompiler
1224 Deprecated. Do not use.
1225 The macros provided by this module were once intended for use by
1227 cross-compiling toolchain files when CMake was not able to automati‐
1228 cally detect the compiler identification. Since the introduction of
1229 this module, CMake’s compiler identification capabilities have improved
1230 and can now be taught to recognize any compiler. Furthermore, the
1231 suite of information CMake detects from a compiler is now too extensive
1232 to be provided by toolchain files using these macros.
1233 One common use case for this module was to skip CMake’s checks for a
1235 working compiler when using a cross-compiler that cannot link binaries
1236 without special flags or custom linker scripts. This case is now sup‐
1237 ported by setting the CMAKE_TRY_COMPILE_TARGET_TYPE variable in the
1238 toolchain file instead.
1239 ----
1242 Macro CMAKE_FORCE_C_COMPILER has the following signature:
1246 CMAKE_FORCE_C_COMPILER(<compiler> <compiler-id>)
1248 It sets CMAKE_C_COMPILER to the given compiler and the cmake internal
1250 variable CMAKE_C_COMPILER_ID to the given compiler-id. It also
1251 bypasses the check for working compiler and basic compiler information
1252 tests.
1253 Macro CMAKE_FORCE_CXX_COMPILER has the following signature:
1255 CMAKE_FORCE_CXX_COMPILER(<compiler> <compiler-id>)
1257 It sets CMAKE_CXX_COMPILER to the given compiler and the cmake internal
1259 variable CMAKE_CXX_COMPILER_ID to the given compiler-id. It also
1260 bypasses the check for working compiler and basic compiler information
1261 tests.
1262 Macro CMAKE_FORCE_Fortran_COMPILER has the following signature:
1264 CMAKE_FORCE_Fortran_COMPILER(<compiler> <compiler-id>)
1266 It sets CMAKE_Fortran_COMPILER to the given compiler and the cmake
1268 internal variable CMAKE_Fortran_COMPILER_ID to the given compiler-id.
1269 It also bypasses the check for working compiler and basic compiler
1270 information tests.
1271 So a simple toolchain file could look like this:
1273 include (CMakeForceCompiler)
1275 set(CMAKE_SYSTEM_NAME Generic)
1276 CMAKE_FORCE_C_COMPILER (chc12 MetrowerksHicross)
1277 CMAKE_FORCE_CXX_COMPILER (chc12 MetrowerksHicross)
1278 CMakeGraphVizOptions
1280 The builtin graphviz support of CMake.
1281 Variables specific to the graphviz support
1283 CMake can generate graphviz files, showing the dependencies between the
1284 targets in a project and also external libraries which are linked
1285 against. When CMake is run with the --graphviz=foo.dot option, it will
1286 produce:
1287 · a foo.dot file showing all dependencies in the project
1289 · a foo.dot.<target> file for each target, file showing on which other
1291 targets the respective target depends
1292 · a foo.dot.<target>.dependers file, showing which other targets depend
1294 on the respective target
1295 The different dependency types PUBLIC, PRIVATE and INTERFACE are repre‐
1297 sented as solid, dashed and dotted edges.
1298 This can result in huge graphs. Using the file CMakeGraphVizOp‐
1300 tions.cmake the look and content of the generated graphs can be influ‐
1301 enced. This file is searched first in CMAKE_BINARY_DIR and then in
1302 CMAKE_SOURCE_DIR. If found, it is read and the variables set in it are
1303 used to adjust options for the generated graphviz files.
1304 GRAPHVIZ_GRAPH_TYPE
1306 The graph type.
1307 · Mandatory : NO
1309 · Default : “digraph”
1311 Valid graph types are:
1313 · “graph” : Nodes are joined with lines
1315 · “digraph” : Nodes are joined with arrows showing direction
1317 · “strict graph” : Like “graph” but max one line between each
1319 node
1320 · “strict digraph” : Like “graph” but max one line between each
1322 node in each direction
1323 GRAPHVIZ_GRAPH_NAME
1325 The graph name.
1326 · Mandatory : NO
1328 · Default : “GG”
1330 GRAPHVIZ_GRAPH_HEADER
1332 The header written at the top of the graphviz file.
1333 · Mandatory : NO
1335 · Default : “node [n fontsize = “12”];”
1337 GRAPHVIZ_NODE_PREFIX
1339 The prefix for each node in the graphviz file.
1340 · Mandatory : NO
1342 · Default : “node”
1344 GRAPHVIZ_EXECUTABLES
1346 Set this to FALSE to exclude executables from the generated
1347 graphs.
1348 · Mandatory : NO
1350 · Default : TRUE
1352 GRAPHVIZ_STATIC_LIBS
1354 Set this to FALSE to exclude static libraries from the generated
1355 graphs.
1356 · Mandatory : NO
1358 · Default : TRUE
1360 GRAPHVIZ_SHARED_LIBS
1362 Set this to FALSE to exclude shared libraries from the generated
1363 graphs.
1364 · Mandatory : NO
1366 · Default : TRUE
1368 GRAPHVIZ_MODULE_LIBS
1370 Set this to FALSE to exclude module libraries from the generated
1371 graphs.
1372 · Mandatory : NO
1374 · Default : TRUE
1376 GRAPHVIZ_EXTERNAL_LIBS
1378 Set this to FALSE to exclude external libraries from the gener‐
1379 ated graphs.
1380 · Mandatory : NO
1382 · Default : TRUE
1384 GRAPHVIZ_IGNORE_TARGETS
1386 A list of regular expressions for ignoring targets.
1387 · Mandatory : NO
1389 · Default : empty
1391 GRAPHVIZ_GENERATE_PER_TARGET
1393 Set this to FALSE to exclude per target graphs foo.dot.<target>.
1394 · Mandatory : NO
1396 · Default : TRUE
1398 GRAPHVIZ_GENERATE_DEPENDERS
1400 Set this to FALSE to exclude depender graphs foo.dot.<tar‐
1401 get>.dependers.
1402 · Mandatory : NO
1404 · Default : TRUE
1406 CMakePackageConfigHelpers
1408 Helpers functions for creating config files that can be included by
1409 other projects to find and use a package.
1410 Adds the configure_package_config_file() and
1412 write_basic_package_version_file() commands.
1413 Generating a Package Configuration File
1415 configure_package_config_file
1416 Create a config file for a project:
1417 configure_package_config_file(<input> <output>
1419 INSTALL_DESTINATION <path>
1420 [PATH_VARS <var1> <var2> ... <varN>]
1421 [NO_SET_AND_CHECK_MACRO]
1422 [NO_CHECK_REQUIRED_COMPONENTS_MACRO]
1423 [INSTALL_PREFIX <path>]
1424 )
1425 configure_package_config_file() should be used instead of the plain
1427 configure_file() command when creating the <Name>Config.cmake or
1428 <Name>-config.cmake file for installing a project or library. It helps
1429 making the resulting package relocatable by avoiding hardcoded paths in
1430 the installed Config.cmake file.
1431 In a FooConfig.cmake file there may be code like this to make the
1433 install destinations know to the using project:
1434 set(FOO_INCLUDE_DIR "@CMAKE_INSTALL_FULL_INCLUDEDIR@" )
1436 set(FOO_DATA_DIR "@CMAKE_INSTALL_PREFIX@/@RELATIVE_DATA_INSTALL_DIR@" )
1437 set(FOO_ICONS_DIR "@CMAKE_INSTALL_PREFIX@/share/icons" )
1438 #...logic to determine installedPrefix from the own location...
1439 set(FOO_CONFIG_DIR "${installedPrefix}/@CONFIG_INSTALL_DIR@" )
1440 All 4 options shown above are not sufficient, since the first 3 hard‐
1442 code the absolute directory locations, and the 4th case works only if
1443 the logic to determine the installedPrefix is correct, and if CON‐
1444 FIG_INSTALL_DIR contains a relative path, which in general cannot be
1445 guaranteed. This has the effect that the resulting FooConfig.cmake
1446 file would work poorly under Windows and OSX, where users are used to
1447 choose the install location of a binary package at install time, inde‐
1448 pendent from how CMAKE_INSTALL_PREFIX was set at build/cmake time.
1449 Using configure_package_config_file helps. If used correctly, it makes
1451 the resulting FooConfig.cmake file relocatable. Usage:
1452 1. write a FooConfig.cmake.in file as you are used to
1454 2. insert a line containing only the string @PACKAGE_INIT@
1456 3. instead of set(FOO_DIR "@SOME_INSTALL_DIR@"), use set(FOO_DIR
1458 "@PACKAGE_SOME_INSTALL_DIR@") (this must be after the @PACKAGE_INIT@
1459 line)
1460 4. instead of using the normal configure_file(), use configure_pack‐
1462 age_config_file()
1463 The <input> and <output> arguments are the input and output file, the
1465 same way as in configure_file().
1466 The <path> given to INSTALL_DESTINATION must be the destination where
1468 the FooConfig.cmake file will be installed to. This path can either be
1469 absolute, or relative to the INSTALL_PREFIX path.
1470 The variables <var1> to <varN> given as PATH_VARS are the variables
1472 which contain install destinations. For each of them the macro will
1473 create a helper variable PACKAGE_<var...>. These helper variables must
1474 be used in the FooConfig.cmake.in file for setting the installed loca‐
1475 tion. They are calculated by configure_package_config_file so that
1476 they are always relative to the installed location of the package.
1477 This works both for relative and also for absolute locations. For
1478 absolute locations it works only if the absolute location is a subdi‐
1479 rectory of INSTALL_PREFIX.
1480 If the INSTALL_PREFIX argument is passed, this is used as base path to
1482 calculate all the relative paths. The <path> argument must be an abso‐
1483 lute path. If this argument is not passed, the CMAKE_INSTALL_PREFIX
1484 variable will be used instead. The default value is good when generat‐
1485 ing a FooConfig.cmake file to use your package from the install tree.
1486 When generating a FooConfig.cmake file to use your package from the
1487 build tree this option should be used.
1488 By default configure_package_config_file also generates two helper
1490 macros, set_and_check() and check_required_components() into the
1491 FooConfig.cmake file.
1492 set_and_check() should be used instead of the normal set() command for
1494 setting directories and file locations. Additionally to setting the
1495 variable it also checks that the referenced file or directory actually
1496 exists and fails with a FATAL_ERROR otherwise. This makes sure that
1497 the created FooConfig.cmake file does not contain wrong references.
1498 When using the NO_SET_AND_CHECK_MACRO, this macro is not generated into
1499 the FooConfig.cmake file.
1500 check_required_components(<package_name>) should be called at the end
1502 of the FooConfig.cmake file if the package supports components. This
1503 macro checks whether all requested, non-optional components have been
1504 found, and if this is not the case, sets the Foo_FOUND variable to
1505 FALSE, so that the package is considered to be not found. It does that
1506 by testing the Foo_<Component>_FOUND variables for all requested
1507 required components. When using the NO_CHECK_REQUIRED_COMPONENTS_MACRO
1508 option, this macro is not generated into the FooConfig.cmake file.
1509 For an example see below the documentation for
1511 write_basic_package_version_file().
1512 Generating a Package Version File
1514 write_basic_package_version_file
1515 Create a version file for a project:
1516 write_basic_package_version_file(<filename>
1518 [VERSION <major.minor.patch>]
1519 COMPATIBILITY <AnyNewerVersion|SameMajorVersion|SameMinorVersion|ExactVersion> )
1520 Writes a file for use as <package>ConfigVersion.cmake file to <file‐
1522 name>. See the documentation of find_package() for details on this.
1523 <filename> is the output filename, it should be in the build tree.
1525 <major.minor.patch> is the version number of the project to be
1526 installed.
1527 If no VERSION is given, the PROJECT_VERSION variable is used. If this
1529 hasn’t been set, it errors out.
1530 The COMPATIBILITY mode AnyNewerVersion means that the installed package
1532 version will be considered compatible if it is newer or exactly the
1533 same as the requested version. This mode should be used for packages
1534 which are fully backward compatible, also across major versions. If
1535 SameMajorVersion is used instead, then the behaviour differs from
1536 AnyNewerVersion in that the major version number must be the same as
1537 requested, e.g. version 2.0 will not be considered compatible if 1.0
1538 is requested. This mode should be used for packages which guarantee
1539 backward compatibility within the same major version. If SameMinorVer‐
1540 sion is used, the behaviour is the same as SameMajorVersion, but both
1541 major and minor version must be the same as requested, e.g version 0.2
1542 will not be compatible if 0.1 is requested. If ExactVersion is used,
1543 then the package is only considered compatible if the requested version
1544 matches exactly its own version number (not considering the tweak ver‐
1545 sion). For example, version 1.2.3 of a package is only considered com‐
1546 patible to requested version 1.2.3. This mode is for packages without
1547 compatibility guarantees. If your project has more elaborated version
1548 matching rules, you will need to write your own custom ConfigVer‐
1549 sion.cmake file instead of using this macro.
1550 Internally, this macro executes configure_file() to create the result‐
1552 ing version file. Depending on the COMPATIBILITY, the corresponding
1553 BasicConfigVersion-<COMPATIBILITY>.cmake.in file is used. Please note
1554 that these files are internal to CMake and you should not call config‐
1555 ure_file() on them yourself, but they can be used as starting point to
1556 create more sophisticted custom ConfigVersion.cmake files.
1557 Example Generating Package Files
1559 Example using both configure_package_config_file() and
1560 write_basic_package_version_file():
1561 CMakeLists.txt:
1563 set(INCLUDE_INSTALL_DIR include/ ... CACHE )
1565 set(LIB_INSTALL_DIR lib/ ... CACHE )
1566 set(SYSCONFIG_INSTALL_DIR etc/foo/ ... CACHE )
1567 #...
1568 include(CMakePackageConfigHelpers)
1569 configure_package_config_file(FooConfig.cmake.in
1570 ${CMAKE_CURRENT_BINARY_DIR}/FooConfig.cmake
1571 INSTALL_DESTINATION ${LIB_INSTALL_DIR}/Foo/cmake
1572 PATH_VARS INCLUDE_INSTALL_DIR SYSCONFIG_INSTALL_DIR)
1573 write_basic_package_version_file(
1574 ${CMAKE_CURRENT_BINARY_DIR}/FooConfigVersion.cmake
1575 VERSION 1.2.3
1576 COMPATIBILITY SameMajorVersion )
1577 install(FILES ${CMAKE_CURRENT_BINARY_DIR}/FooConfig.cmake
1578 ${CMAKE_CURRENT_BINARY_DIR}/FooConfigVersion.cmake
1579 DESTINATION ${LIB_INSTALL_DIR}/Foo/cmake )
1580 FooConfig.cmake.in:
1582 set(FOO_VERSION x.y.z)
1584 ...
1585 @PACKAGE_INIT@
1586 ...
1587 set_and_check(FOO_INCLUDE_DIR "@PACKAGE_INCLUDE_INSTALL_DIR@")
1588 set_and_check(FOO_SYSCONFIG_DIR "@PACKAGE_SYSCONFIG_INSTALL_DIR@")
1589 check_required_components(Foo)
1591 CMakeParseArguments
1593 This module once implemented the cmake_parse_arguments() command that
1594 is now implemented natively by CMake. It is now an empty placeholder
1595 for compatibility with projects that include it to get the command from
1596 CMake 3.4 and lower.
1597 CMakePrintHelpers
1599 Convenience macros for printing properties and variables, useful e.g.
1600 for debugging.
1601 CMAKE_PRINT_PROPERTIES([TARGETS target1 .. targetN]
1603 [SOURCES source1 .. sourceN]
1604 [DIRECTORIES dir1 .. dirN]
1605 [TESTS test1 .. testN]
1606 [CACHE_ENTRIES entry1 .. entryN]
1607 PROPERTIES prop1 .. propN )
1608 This macro prints the values of the properties of the given targets,
1610 source files, directories, tests or cache entries. Exactly one of the
1611 scope keywords must be used. Example:
1612 cmake_print_properties(TARGETS foo bar PROPERTIES
1614 LOCATION INTERFACE_INCLUDE_DIRS)
1615 This will print the LOCATION and INTERFACE_INCLUDE_DIRS properties for
1617 both targets foo and bar.
1618 CMAKE_PRINT_VARIABLES(var1 var2 .. varN)
1620 This macro will print the name of each variable followed by its value.
1622 Example:
1623 cmake_print_variables(CMAKE_C_COMPILER CMAKE_MAJOR_VERSION DOES_NOT_EXIST)
1625 Gives:
1627 -- CMAKE_C_COMPILER="/usr/bin/gcc" ; CMAKE_MAJOR_VERSION="2" ; DOES_NOT_EXIST=""
1629 CMakePrintSystemInformation
1631 print system information
1632 This file can be used for diagnostic purposes just include it in a
1634 project to see various internal CMake variables.
1635 CMakePushCheckState
1637 This module defines three macros: CMAKE_PUSH_CHECK_STATE()
1638 CMAKE_POP_CHECK_STATE() and CMAKE_RESET_CHECK_STATE() These macros can
1639 be used to save, restore and reset (i.e., clear contents) the state of
1640 the variables CMAKE_REQUIRED_FLAGS, CMAKE_REQUIRED_DEFINITIONS,
1641 CMAKE_REQUIRED_LIBRARIES, CMAKE_REQUIRED_INCLUDES and
1642 CMAKE_EXTRA_INCLUDE_FILES used by the various Check-files coming with
1643 CMake, like e.g. check_function_exists() etc. The variable contents
1644 are pushed on a stack, pushing multiple times is supported. This is
1645 useful e.g. when executing such tests in a Find-module, where they
1646 have to be set, but after the Find-module has been executed they should
1647 have the same value as they had before.
1648 CMAKE_PUSH_CHECK_STATE() macro receives optional argument RESET.
1650 Whether it’s specified, CMAKE_PUSH_CHECK_STATE() will set all
1651 CMAKE_REQUIRED_* variables to empty values, same as
1652 CMAKE_RESET_CHECK_STATE() call will do.
1653 Usage:
1655 cmake_push_check_state(RESET)
1657 set(CMAKE_REQUIRED_DEFINITIONS -DSOME_MORE_DEF)
1658 check_function_exists(...)
1659 cmake_reset_check_state()
1660 set(CMAKE_REQUIRED_DEFINITIONS -DANOTHER_DEF)
1661 check_function_exists(...)
1662 cmake_pop_check_state()
1663 CMakeVerifyManifest
1665 CMakeVerifyManifest.cmake
1666 This script is used to verify that embedded manifests and side by side
1668 manifests for a project match. To run this script, cd to a directory
1669 and run the script with cmake -P. On the command line you can pass in
1670 versions that are OK even if not found in the .manifest files. For
1671 example, cmake -Dallow_versions=8.0.50608.0 -PCmakeVerifyManifest.cmake
1672 could be used to allow an embedded manifest of 8.0.50608.0 to be used
1673 in a project even if that version was not found in the .manifest file.
1674 CPackArchive
1676 Archive CPack generator that supports packaging of sources and binaries
1677 in different formats:
1678 · 7Z - 7zip - (.7z)
1680 · TBZ2 (.tar.bz2)
1682 · TGZ (.tar.gz)
1684 · TXZ (.tar.xz)
1686 · TZ (.tar.Z)
1688 · ZIP (.zip)
1690 Variables specific to CPack Archive generator
1692 CPACK_ARCHIVE_FILE_NAME
1693 CPACK_ARCHIVE_<component>_FILE_NAME
1695 Package file name without extension which is added automatically
1696 depending on the archive format.
1697 · Mandatory : YES
1699 ·
1701 Default
1703 <CPACK_PACKAGE_FILE_NAME>[-<component>].<extension>
1704 with spaces replaced by ‘-‘
1705 CPACK_ARCHIVE_COMPONENT_INSTALL
1707 Enable component packaging for CPackArchive
1708 · Mandatory : NO
1710 · Default : OFF
1712 If enabled (ON) multiple packages are generated. By default a
1714 single package containing files of all components is generated.
1715 CPackBundle
1717 CPack Bundle generator (Mac OS X) specific options
1718 Variables specific to CPack Bundle generator
1720 Installers built on Mac OS X using the Bundle generator use the afore‐
1721 mentioned DragNDrop (CPACK_DMG_xxx) variables, plus the following Bun‐
1722 dle-specific parameters (CPACK_BUNDLE_xxx).
1723 CPACK_BUNDLE_NAME
1725 The name of the generated bundle. This appears in the OSX finder
1726 as the bundle name. Required.
1727 CPACK_BUNDLE_PLIST
1729 Path to an OSX plist file that will be used for the generated
1730 bundle. This assumes that the caller has generated or specified
1731 their own Info.plist file. Required.
1732 CPACK_BUNDLE_ICON
1734 Path to an OSX icon file that will be used as the icon for the
1735 generated bundle. This is the icon that appears in the OSX
1736 finder for the bundle, and in the OSX dock when the bundle is
1737 opened. Required.
1738 CPACK_BUNDLE_STARTUP_COMMAND
1740 Path to a startup script. This is a path to an executable or
1741 script that will be run whenever an end-user double-clicks the
1742 generated bundle in the OSX Finder. Optional.
1743 CPACK_BUNDLE_APPLE_CERT_APP
1745 The name of your Apple supplied code signing certificate for the
1746 application. The name usually takes the form “Developer ID
1747 Application: [Name]” or “3rd Party Mac Developer Application:
1748 [Name]”. If this variable is not set the application will not be
1749 signed.
1750 CPACK_BUNDLE_APPLE_ENTITLEMENTS
1752 The name of the plist file that contains your apple entitlements
1753 for sandboxing your application. This file is required for sub‐
1754 mission to the Mac App Store.
1755 CPACK_BUNDLE_APPLE_CODESIGN_FILES
1757 A list of additional files that you wish to be signed. You do
1758 not need to list the main application folder, or the main exe‐
1759 cutable. You should list any frameworks and plugins that are
1760 included in your app bundle.
1761 CPACK_BUNDLE_APPLE_CODESIGN_PARAMETER
1763 Additional parameter that will passed to codesign. Default
1764 value: “–deep -f”
1765 CPACK_COMMAND_CODESIGN
1767 Path to the codesign(1) command used to sign applications with
1768 an Apple cert. This variable can be used to override the auto‐
1769 matically detected command (or specify its location if the
1770 auto-detection fails to find it.)
1771 CPackComponent
1773 Build binary and source package installers
1774 Variables concerning CPack Components
1776 The CPackComponent module is the module which handles the component
1777 part of CPack. See CPack module for general information about CPack.
1778 For certain kinds of binary installers (including the graphical in‐
1780 stallers on Mac OS X and Windows), CPack generates installers that
1781 allow users to select individual application components to install.
1782 The contents of each of the components are identified by the COMPONENT
1783 argument of CMake’s INSTALL command. These components can be annotated
1784 with user-friendly names and descriptions, inter-component dependen‐
1785 cies, etc., and grouped in various ways to customize the resulting in‐
1786 staller. See the cpack_add_* commands, described below, for more
1787 information about component-specific installations.
1788 Component-specific installation allows users to select specific sets of
1790 components to install during the install process. Installation compo‐
1791 nents are identified by the COMPONENT argument of CMake’s INSTALL com‐
1792 mands, and should be further described by the following CPack commands:
1793 CPACK_COMPONENTS_ALL
1795 The list of component to install.
1796 The default value of this variable is computed by CPack and con‐
1798 tains all components defined by the project. The user may set
1799 it to only include the specified components.
1800 Instead of specifying all the desired components, it is possible
1802 to obtain a list of all defined components and then remove the
1803 unwanted ones from the list. The get_cmake_property() command
1804 can be used to obtain the COMPONENTS property, then the
1805 list(REMOVE_ITEM) command can be used to remove the unwanted
1806 ones. For example, to use all defined components except foo and
1807 bar:
1808 get_cmake_property(CPACK_COMPONENTS_ALL COMPONENTS)
1810 list(REMOVE_ITEM CPACK_COMPONENTS_ALL "foo" "bar")
1811 CPACK_<GENNAME>_COMPONENT_INSTALL
1813 Enable/Disable component install for CPack generator <GENNAME>.
1814 Each CPack Generator (RPM, DEB, ARCHIVE, NSIS, DMG, etc…) has a
1816 legacy default behavior. e.g. RPM builds monolithic whereas
1817 NSIS builds component. One can change the default behavior by
1818 setting this variable to 0/1 or OFF/ON.
1819 CPACK_COMPONENTS_GROUPING
1821 Specify how components are grouped for multi-package compo‐
1822 nent-aware CPack generators.
1823 Some generators like RPM or ARCHIVE family (TGZ, ZIP, …) gener‐
1825 ates several packages files when asked for component packaging.
1826 They group the component differently depending on the value of
1827 this variable:
1828 · ONE_PER_GROUP (default): creates one package file per compo‐
1830 nent group
1831 · ALL_COMPONENTS_IN_ONE : creates a single package with all
1833 (requested) components
1834 · IGNORE : creates one package per component, i.e. IGNORE compo‐
1836 nent group
1837 One can specify different grouping for different CPack generator
1839 by using a CPACK_PROJECT_CONFIG_FILE.
1840 CPACK_COMPONENT_<compName>_DISPLAY_NAME
1842 The name to be displayed for a component.
1843 CPACK_COMPONENT_<compName>_DESCRIPTION
1845 The description of a component.
1846 CPACK_COMPONENT_<compName>_GROUP
1848 The group of a component.
1849 CPACK_COMPONENT_<compName>_DEPENDS
1851 The dependencies (list of components) on which this component
1852 depends.
1853 CPACK_COMPONENT_<compName>_HIDDEN
1855 True if this component is hidden from the user.
1856 CPACK_COMPONENT_<compName>_REQUIRED
1858 True if this component is required.
1859 CPACK_COMPONENT_<compName>_DISABLED
1861 True if this component is not selected to be installed by
1862 default.
1863 cpack_add_component
1865 Describes a CPack installation component named by the COMPONENT argu‐
1867 ment to a CMake INSTALL command.
1868 cpack_add_component(compname
1870 [DISPLAY_NAME name]
1871 [DESCRIPTION description]
1872 [HIDDEN | REQUIRED | DISABLED ]
1873 [GROUP group]
1874 [DEPENDS comp1 comp2 ... ]
1875 [INSTALL_TYPES type1 type2 ... ]
1876 [DOWNLOADED]
1877 [ARCHIVE_FILE filename]
1878 [PLIST filename])
1879 The cmake_add_component command describes an installation component,
1881 which the user can opt to install or remove as part of the graphical
1882 installation process. compname is the name of the component, as pro‐
1883 vided to the COMPONENT argument of one or more CMake INSTALL commands.
1884 DISPLAY_NAME is the displayed name of the component, used in graphical
1886 installers to display the component name. This value can be any
1887 string.
1888 DESCRIPTION is an extended description of the component, used in graph‐
1890 ical installers to give the user additional information about the com‐
1891 ponent. Descriptions can span multiple lines using \n as the line sep‐
1892 arator. Typically, these descriptions should be no more than a few
1893 lines long.
1894 HIDDEN indicates that this component will be hidden in the graphical
1896 installer, so that the user cannot directly change whether it is
1897 installed or not.
1898 REQUIRED indicates that this component is required, and therefore will
1900 always be installed. It will be visible in the graphical installer,
1901 but it cannot be unselected. (Typically, required components are shown
1902 greyed out).
1903 DISABLED indicates that this component should be disabled (unselected)
1905 by default. The user is free to select this component for installa‐
1906 tion, unless it is also HIDDEN.
1907 DEPENDS lists the components on which this component depends. If this
1909 component is selected, then each of the components listed must also be
1910 selected. The dependency information is encoded within the installer
1911 itself, so that users cannot install inconsistent sets of components.
1912 GROUP names the component group of which this component is a part. If
1914 not provided, the component will be a standalone component, not part of
1915 any component group. Component groups are described with the
1916 cpack_add_component_group command, detailed below.
1917 INSTALL_TYPES lists the installation types of which this component is a
1919 part. When one of these installations types is selected, this compo‐
1920 nent will automatically be selected. Installation types are described
1921 with the cpack_add_install_type command, detailed below.
1922 DOWNLOADED indicates that this component should be downloaded
1924 on-the-fly by the installer, rather than packaged in with the installer
1925 itself. For more information, see the cpack_configure_downloads com‐
1926 mand.
1927 ARCHIVE_FILE provides a name for the archive file created by CPack to
1929 be used for downloaded components. If not supplied, CPack will create
1930 a file with some name based on CPACK_PACKAGE_FILE_NAME and the name of
1931 the component. See cpack_configure_downloads for more information.
1932 PLIST gives a filename that is passed to pkgbuild with the --compo‐
1934 nent-plist argument when using the productbuild generator.
1935 cpack_add_component_group
1937 Describes a group of related CPack installation components.
1939 cpack_add_component_group(groupname
1941 [DISPLAY_NAME name]
1942 [DESCRIPTION description]
1943 [PARENT_GROUP parent]
1944 [EXPANDED]
1945 [BOLD_TITLE])
1946 The cpack_add_component_group describes a group of installation compo‐
1948 nents, which will be placed together within the listing of options.
1949 Typically, component groups allow the user to select/deselect all of
1950 the components within a single group via a single group-level option.
1951 Use component groups to reduce the complexity of installers with many
1952 options. groupname is an arbitrary name used to identify the group in
1953 the GROUP argument of the cpack_add_component command, which is used to
1954 place a component in a group. The name of the group must not conflict
1955 with the name of any component.
1956 DISPLAY_NAME is the displayed name of the component group, used in
1958 graphical installers to display the component group name. This value
1959 can be any string.
1960 DESCRIPTION is an extended description of the component group, used in
1962 graphical installers to give the user additional information about the
1963 components within that group. Descriptions can span multiple lines
1964 using \n as the line separator. Typically, these descriptions should
1965 be no more than a few lines long.
1966 PARENT_GROUP, if supplied, names the parent group of this group. Par‐
1968 ent groups are used to establish a hierarchy of groups, providing an
1969 arbitrary hierarchy of groups.
1970 EXPANDED indicates that, by default, the group should show up as
1972 “expanded”, so that the user immediately sees all of the components
1973 within the group. Otherwise, the group will initially show up as a
1974 single entry.
1975 BOLD_TITLE indicates that the group title should appear in bold, to
1977 call the user’s attention to the group.
1978 cpack_add_install_type
1980 Add a new installation type containing a set of predefined component
1982 selections to the graphical installer.
1983 cpack_add_install_type(typename
1985 [DISPLAY_NAME name])
1986 The cpack_add_install_type command identifies a set of preselected com‐
1988 ponents that represents a common use case for an application. For
1989 example, a “Developer” install type might include an application along
1990 with its header and library files, while an “End user” install type
1991 might just include the application’s executable. Each component iden‐
1992 tifies itself with one or more install types via the INSTALL_TYPES
1993 argument to cpack_add_component.
1994 DISPLAY_NAME is the displayed name of the install type, which will typ‐
1996 ically show up in a drop-down box within a graphical installer. This
1997 value can be any string.
1998 cpack_configure_downloads
2000 Configure CPack to download selected components on-the-fly as part of
2002 the installation process.
2003 cpack_configure_downloads(site
2005 [UPLOAD_DIRECTORY dirname]
2006 [ALL]
2007 [ADD_REMOVE|NO_ADD_REMOVE])
2008 The cpack_configure_downloads command configures installation-time
2010 downloads of selected components. For each downloadable component,
2011 CPack will create an archive containing the contents of that component,
2012 which should be uploaded to the given site. When the user selects that
2013 component for installation, the installer will download and extract the
2014 component in place. This feature is useful for creating small install‐
2015 ers that only download the requested components, saving bandwidth.
2016 Additionally, the installers are small enough that they will be
2017 installed as part of the normal installation process, and the “Change”
2018 button in Windows Add/Remove Programs control panel will allow one to
2019 add or remove parts of the application after the original installation.
2020 On Windows, the downloaded-components functionality requires the ZipDLL
2021 plug-in for NSIS, available at:
2022 http://nsis.sourceforge.net/ZipDLL_plug-in
2024 On Mac OS X, installers that download components on-the-fly can only be
2026 built and installed on system using Mac OS X 10.5 or later.
2027 The site argument is a URL where the archives for downloadable compo‐
2029 nents will reside, e.g., https://cmake.org/files/2.6.1/installer/ All
2030 of the archives produced by CPack should be uploaded to that location.
2031 UPLOAD_DIRECTORY is the local directory where CPack will create the
2033 various archives for each of the components. The contents of this
2034 directory should be uploaded to a location accessible by the URL given
2035 in the site argument. If omitted, CPack will use the directory CPackU‐
2036 ploads inside the CMake binary directory to store the generated ar‐
2037 chives.
2038 The ALL flag indicates that all components be downloaded. Otherwise,
2040 only those components explicitly marked as DOWNLOADED or that have a
2041 specified ARCHIVE_FILE will be downloaded. Additionally, the ALL
2042 option implies ADD_REMOVE (unless NO_ADD_REMOVE is specified).
2043 ADD_REMOVE indicates that CPack should install a copy of the installer
2045 that can be called from Windows’ Add/Remove Programs dialog (via the
2046 “Modify” button) to change the set of installed components.
2047 NO_ADD_REMOVE turns off this behavior. This option is ignored on Mac
2048 OS X.
2049 CPackCygwin
2051 Cygwin CPack generator (Cygwin).
2052 Variables specific to CPack Cygwin generator
2054 The following variable is specific to installers build on and/or for
2055 Cygwin:
2056 CPACK_CYGWIN_PATCH_NUMBER
2058 The Cygwin patch number. FIXME: This documentation is incom‐
2059 plete.
2060 CPACK_CYGWIN_PATCH_FILE
2062 The Cygwin patch file. FIXME: This documentation is incomplete.
2063 CPACK_CYGWIN_BUILD_SCRIPT
2065 The Cygwin build script. FIXME: This documentation is incom‐
2066 plete.
2067 CPackDeb
2069 The built in (binary) CPack Deb generator (Unix only)
2070 Variables specific to CPack Debian (DEB) generator
2072 CPackDeb may be used to create Deb package using CPack. CPackDeb is a
2073 CPack generator thus it uses the CPACK_XXX variables used by CPack.
2074 CPackDeb generator should work on any Linux host but it will produce
2076 better deb package when Debian specific tools dpkg-xxx are usable on
2077 the build system.
2078 CPackDeb has specific features which are controlled by the specifics
2080 CPACK_DEBIAN_XXX variables.
2081 CPACK_DEBIAN_<COMPONENT>_XXXX variables may be used in order to have
2083 component specific values. Note however that <COMPONENT> refers to the
2084 grouping name written in upper case. It may be either a component name
2085 or a component GROUP name.
2086 Here are some CPackDeb wiki resources that are here for historic rea‐
2088 sons and are no longer maintained but may still prove useful:
2089 · https://cmake.org/Wiki/CMake:CPackConfiguration
2091 · https://cmake.org/Wiki/CMake:CPackPackageGenerators#DEB_.28UNIX_only.29
2093 List of CPackDEB specific variables:
2095 CPACK_DEB_COMPONENT_INSTALL
2097 Enable component packaging for CPackDEB
2098 · Mandatory : NO
2100 · Default : OFF
2102 If enabled (ON) multiple packages are generated. By default a
2104 single package containing files of all components is generated.
2105 CPACK_DEBIAN_PACKAGE_NAME
2107 CPACK_DEBIAN_<COMPONENT>_PACKAGE_NAME
2109 Set Package control field (variable is automatically transformed
2110 to lower case).
2111 · Mandatory : YES
2113 · Default :
2115 · CPACK_PACKAGE_NAME for non-component based installations
2117 · CPACK_DEBIAN_PACKAGE_NAME suffixed with -<COMPONENT> for
2119 component-based installations.
2120 See
2122 https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Source
2123 CPACK_DEBIAN_FILE_NAME
2125 CPACK_DEBIAN_<COMPONENT>_FILE_NAME
2127 Package file name.
2128 · Mandatory : YES
2130 · Default : <CPACK_PACKAGE_FILE_NAME>[-<component>].deb
2132 This may be set to DEB-DEFAULT to allow CPackDeb to generate
2134 package file name by itself in deb format:
2135 <PackageName>_<VersionNumber>-<DebianRevisionNumber>_<DebianArchitecture>.deb
2137 Alternatively provided package file name must end with either
2139 .deb or .ipk suffix.
2140 NOTE:
2142 Preferred setting of this variable is DEB-DEFAULT but for
2143 backward compatibility with CPackDeb in CMake prior to ver‐
2144 sion 3.6 this feature is disabled by default.
2145 NOTE:
2147 By using non default filenames duplicate names may occur.
2148 Duplicate files get overwritten and it is up to the packager
2149 to set the variables in a manner that will prevent such
2150 errors.
2151 CPACK_DEBIAN_PACKAGE_EPOCH
2153 The Debian package epoch
2154 · Mandatory : No
2156 · Default : -
2158 Optional number that should be incremented when changing ver‐
2160 sioning schemas or fixing mistakes in the version numbers of
2161 older packages.
2162 CPACK_DEBIAN_PACKAGE_VERSION
2164 The Debian package version
2165 · Mandatory : YES
2167 · Default : CPACK_PACKAGE_VERSION
2169 This variable may contain only alphanumerics (A-Za-z0-9) and the
2171 characters CPACK_DEBIAN_PACKAGE_RELEASE is not set then hyphens
2172 are not allowed.
2173 NOTE:
2175 For backward compatibility with CMake 3.9 and lower a failed
2176 test of this variable’s content is not a hard error when both
2177 CPACK_DEBIAN_PACKAGE_RELEASE and CPACK_DEBIAN_PACKAGE_EPOCH
2178 variables are not set. An author warning is reported instead.
2179 CPACK_DEBIAN_PACKAGE_RELEASE
2181 The Debian package release - Debian revision number.
2182 · Mandatory : No
2184 · Default : -
2186 This is the numbering of the DEB package itself, i.e. the ver‐
2188 sion of the packaging and not the version of the content (see
2189 CPACK_DEBIAN_PACKAGE_VERSION). One may change the default value
2190 if the previous packaging was buggy and/or you want to put here
2191 a fancy Linux distro specific numbering.
2192 CPACK_DEBIAN_PACKAGE_ARCHITECTURE
2194 CPACK_DEBIAN_<COMPONENT>_PACKAGE_ARCHITECTURE
2196 The Debian package architecture
2197 · Mandatory : YES
2199 · Default : Output of dpkg --print-architecture (or i386 if
2201 dpkg is not found)
2202 CPACK_DEBIAN_PACKAGE_DEPENDS
2204 CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS
2206 Sets the Debian dependencies of this package.
2207 · Mandatory : NO
2209 · Default :
2211 · An empty string for non-component based installations
2213 · CPACK_DEBIAN_PACKAGE_DEPENDS for component-based installa‐
2215 tions.
2216 NOTE:
2218 If CPACK_DEBIAN_PACKAGE_SHLIBDEPS or more specifically
2219 CPACK_DEBIAN_<COMPONENT>_PACKAGE_SHLIBDEPS is set for this
2220 component, the discovered dependencies will be appended to
2221 CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS instead of
2222 CPACK_DEBIAN_PACKAGE_DEPENDS. If
2223 CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS is an empty string,
2224 only the automatically discovered dependencies will be set
2225 for this component.
2226 Example:
2228 set(CPACK_DEBIAN_PACKAGE_DEPENDS "libc6 (>= 2.3.1-6), libc6 (< 2.4)")
2230 CPACK_DEBIAN_ENABLE_COMPONENT_DEPENDS
2232 Sets inter component dependencies if listed with CPACK_COMPO‐
2233 NENT_<compName>_DEPENDS variables.
2234 · Mandatory : NO
2236 · Default : -
2238 CPACK_DEBIAN_PACKAGE_MAINTAINER
2240 The Debian package maintainer
2241 · Mandatory : YES
2243 · Default : CPACK_PACKAGE_CONTACT
2245 CPACK_DEBIAN_PACKAGE_DESCRIPTION
2247 CPACK_COMPONENT_<COMPONENT>_DESCRIPTION
2249 The Debian package description
2250 · Mandatory : YES
2252 · Default :
2254 · CPACK_DEBIAN_PACKAGE_DESCRIPTION if set or
2256 · CPACK_PACKAGE_DESCRIPTION_SUMMARY
2258 CPACK_DEBIAN_PACKAGE_SECTION
2260 CPACK_DEBIAN_<COMPONENT>_PACKAGE_SECTION
2262 Set Section control field e.g. admin, devel, doc, …
2263 · Mandatory : YES
2265 · Default : “devel”
2267 See
2269 https://www.debian.org/doc/debian-policy/ch-archive.html#s-subsections
2270 CPACK_DEBIAN_ARCHIVE_TYPE
2272 The archive format used for creating the Debian package.
2273 · Mandatory : YES
2275 · Default : “paxr”
2277 Possible values are:
2279 · paxr
2281 · gnutar
2283 NOTE:
2285 Default pax archive format is the most portable format and
2286 generates packages that do not treat sparse files specially.
2287 GNU tar format on the other hand supports longer filenames.
2288 CPACK_DEBIAN_COMPRESSION_TYPE
2290 The compression used for creating the Debian package.
2291 · Mandatory : YES
2293 · Default : “gzip”
2295 Possible values are:
2297 · lzma
2299 · xz
2301 · bzip2
2303 · gzip
2305 CPACK_DEBIAN_PACKAGE_PRIORITY
2307 CPACK_DEBIAN_<COMPONENT>_PACKAGE_PRIORITY
2309 Set Priority control field e.g. required, important, standard,
2310 optional, extra
2311 · Mandatory : YES
2313 · Default : “optional”
2315 See
2317 https://www.debian.org/doc/debian-policy/ch-archive.html#s-priorities
2318 CPACK_DEBIAN_PACKAGE_HOMEPAGE
2320 The URL of the web site for this package, preferably (when
2321 applicable) the site from which the original source can be
2322 obtained and any additional upstream documentation or informa‐
2323 tion may be found.
2324 · Mandatory : NO
2326 · Default : -
2328 NOTE:
2330 The content of this field is a simple URL without any sur‐
2331 rounding characters such as <>.
2332 CPACK_DEBIAN_PACKAGE_SHLIBDEPS
2334 CPACK_DEBIAN_<COMPONENT>_PACKAGE_SHLIBDEPS
2336 May be set to ON in order to use dpkg-shlibdeps to generate bet‐
2337 ter package dependency list.
2338 · Mandatory : NO
2340 · Default :
2342 · CPACK_DEBIAN_PACKAGE_SHLIBDEPS if set or
2344 · OFF
2346 NOTE:
2348 You may need set CMAKE_INSTALL_RPATH to an appropriate value
2349 if you use this feature, because if you don’t dpkg-shlibdeps
2350 may fail to find your own shared libs. See
2351 https://cmake.org/Wiki/CMake_RPATH_handling.
2352 CPACK_DEBIAN_PACKAGE_DEBUG
2354 May be set when invoking cpack in order to trace debug informa‐
2355 tion during CPackDeb run.
2356 · Mandatory : NO
2358 · Default : -
2360 CPACK_DEBIAN_PACKAGE_PREDEPENDS
2362 CPACK_DEBIAN_<COMPONENT>_PACKAGE_PREDEPENDS
2364 Sets the Pre-Depends field of the Debian package. Like Depends,
2365 except that it also forces dpkg to complete installation of the
2366 packages named before even starting the installation of the
2367 package which declares the pre-dependency.
2368 · Mandatory : NO
2370 · Default :
2372 · An empty string for non-component based installations
2374 · CPACK_DEBIAN_PACKAGE_PREDEPENDS for component-based instal‐
2376 lations.
2377 See
2379 http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
2380 CPACK_DEBIAN_PACKAGE_ENHANCES
2382 CPACK_DEBIAN_<COMPONENT>_PACKAGE_ENHANCES
2384 Sets the Enhances field of the Debian package. Similar to
2385 Suggests but works in the opposite direction: declares that a
2386 package can enhance the functionality of another package.
2387 · Mandatory : NO
2389 · Default :
2391 · An empty string for non-component based installations
2393 · CPACK_DEBIAN_PACKAGE_ENHANCES for component-based installa‐
2395 tions.
2396 See
2398 http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
2399 CPACK_DEBIAN_PACKAGE_BREAKS
2401 CPACK_DEBIAN_<COMPONENT>_PACKAGE_BREAKS
2403 Sets the Breaks field of the Debian package. When a binary
2404 package (P) declares that it breaks other packages (B), dpkg
2405 will not allow the package (P) which declares Breaks be unpacked
2406 unless the packages that will be broken (B) are deconfigured
2407 first. As long as the package (P) is configured, the previously
2408 deconfigured packages (B) cannot be reconfigured again.
2409 · Mandatory : NO
2411 · Default :
2413 · An empty string for non-component based installations
2415 · CPACK_DEBIAN_PACKAGE_BREAKS for component-based installa‐
2417 tions.
2418 See
2420 https://www.debian.org/doc/debian-policy/ch-relationships.html#s-breaks
2421 CPACK_DEBIAN_PACKAGE_CONFLICTS
2423 CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONFLICTS
2425 Sets the Conflicts field of the Debian package. When one binary
2426 package declares a conflict with another using a Conflicts
2427 field, dpkg will not allow them to be unpacked on the system at
2428 the same time.
2429 · Mandatory : NO
2431 · Default :
2433 · An empty string for non-component based installations
2435 · CPACK_DEBIAN_PACKAGE_CONFLICTS for component-based installa‐
2437 tions.
2438 See
2440 https://www.debian.org/doc/debian-policy/ch-relationships.html#s-conflicts
2441 NOTE:
2443 This is a stronger restriction than Breaks, which prevents
2444 the broken package from being configured while the breaking
2445 package is in the “Unpacked” state but allows both packages
2446 to be unpacked at the same time.
2447 CPACK_DEBIAN_PACKAGE_PROVIDES
2449 CPACK_DEBIAN_<COMPONENT>_PACKAGE_PROVIDES
2451 Sets the Provides field of the Debian package. A virtual pack‐
2452 age is one which appears in the Provides control field of
2453 another package.
2454 · Mandatory : NO
2456 · Default :
2458 · An empty string for non-component based installations
2460 · CPACK_DEBIAN_PACKAGE_PROVIDES for component-based installa‐
2462 tions.
2463 See
2465 https://www.debian.org/doc/debian-policy/ch-relationships.html#s-virtual
2466 CPACK_DEBIAN_PACKAGE_REPLACES
2468 CPACK_DEBIAN_<COMPONENT>_PACKAGE_REPLACES
2470 Sets the Replaces field of the Debian package. Packages can
2471 declare in their control file that they should overwrite files
2472 in certain other packages, or completely replace other packages.
2473 · Mandatory : NO
2475 · Default :
2477 · An empty string for non-component based installations
2479 · CPACK_DEBIAN_PACKAGE_REPLACES for component-based installa‐
2481 tions.
2482 See
2484 http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
2485 CPACK_DEBIAN_PACKAGE_RECOMMENDS
2487 CPACK_DEBIAN_<COMPONENT>_PACKAGE_RECOMMENDS
2489 Sets the Recommends field of the Debian package. Allows pack‐
2490 ages to declare a strong, but not absolute, dependency on other
2491 packages.
2492 · Mandatory : NO
2494 · Default :
2496 · An empty string for non-component based installations
2498 · CPACK_DEBIAN_PACKAGE_RECOMMENDS for component-based instal‐
2500 lations.
2501 See
2503 http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
2504 CPACK_DEBIAN_PACKAGE_SUGGESTS
2506 CPACK_DEBIAN_<COMPONENT>_PACKAGE_SUGGESTS
2508 Sets the Suggests field of the Debian package. Allows packages
2509 to declare a suggested package install grouping.
2510 · Mandatory : NO
2512 · Default :
2514 · An empty string for non-component based installations
2516 · CPACK_DEBIAN_PACKAGE_SUGGESTS for component-based installa‐
2518 tions.
2519 See
2521 http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
2522 CPACK_DEBIAN_PACKAGE_GENERATE_SHLIBS
2524 · Mandatory : NO
2526 · Default : OFF
2528 Allows to generate shlibs control file automatically. Compati‐
2530 bility is defined by CPACK_DEBIAN_PACKAGE_GENERATE_SHLIBS_POLICY
2531 variable value.
2532 NOTE:
2534 Libraries are only considered if they have both library name
2535 and version set. This can be done by setting SOVERSION prop‐
2536 erty with set_target_properties() command.
2537 CPACK_DEBIAN_PACKAGE_GENERATE_SHLIBS_POLICY
2539 Compatibility policy for auto-generated shlibs control file.
2540 · Mandatory : NO
2542 · Default : “=”
2544 Defines compatibility policy for auto-generated shlibs control
2546 file. Possible values: “=”, “>=”
2547 See
2549 https://www.debian.org/doc/debian-policy/ch-sharedlibs.html#s-sharedlibs-shlibdeps
2550 CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA
2552 CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONTROL_EXTRA
2554 This variable allow advanced user to add custom script to the
2555 control.tar.gz. Typical usage is for conffiles, postinst,
2556 postrm, prerm.
2557 · Mandatory : NO
2559 · Default : -
2561 Usage:
2563 set(CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA
2565 "${CMAKE_CURRENT_SOURCE_DIR}/prerm;${CMAKE_CURRENT_SOURCE_DIR}/postrm")
2566 NOTE:
2568 The original permissions of the files will be used in the
2569 final package unless the variable
2570 CPACK_DEBIAN_PACKAGE_CONTROL_STRICT_PERMISSION is set. In
2571 particular, the scripts should have the proper executable
2572 flag prior to the generation of the package.
2573 CPACK_DEBIAN_PACKAGE_CONTROL_STRICT_PERMISSION
2575 CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONTROL_STRICT_PERMISSION
2577 This variable indicates if the Debian policy on control files
2578 should be strictly followed.
2579 · Mandatory : NO
2581 · Default : FALSE
2583 Usage:
2585 set(CPACK_DEBIAN_PACKAGE_CONTROL_STRICT_PERMISSION TRUE)
2587 NOTE:
2589 This overrides the permissions on the original files, follow‐
2590 ing the rules set by Debian policy
2591 https://www.debian.org/doc/debian-policy/ch-files.html#s-permissions-owners
2592 CPACK_DEBIAN_PACKAGE_SOURCE
2594 CPACK_DEBIAN_<COMPONENT>_PACKAGE_SOURCE
2596 Sets the Source field of the binary Debian package. When the
2597 binary package name is not the same as the source package name
2598 (in particular when several components/binaries are generated
2599 from one source) the source from which the binary has been gen‐
2600 erated should be indicated with the field Source.
2601 · Mandatory : NO
2603 · Default :
2605 · An empty string for non-component based installations
2607 · CPACK_DEBIAN_PACKAGE_SOURCE for component-based installa‐
2609 tions.
2610 See
2612 https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Source
2613 NOTE:
2615 This value is not interpreted. It is possible to pass an
2616 optional revision number of the referenced source package as
2617 well.
2618 Building Debian packages on Windows
2620 To communicate UNIX file permissions from the install stage to the
2621 CPack DEB generator the “cmake_mode_t” NTFS alternate data stream (ADT)
2622 is used.
2623 When a filesystem without ADT support is used only owner read/write
2625 permissions can be preserved.
2626 CPackDMG
2628 DragNDrop CPack generator (Mac OS X).
2629 Variables specific to CPack DragNDrop generator
2631 The following variables are specific to the DragNDrop installers built
2632 on Mac OS X:
2633 CPACK_DMG_VOLUME_NAME
2635 The volume name of the generated disk image. Defaults to
2636 CPACK_PACKAGE_FILE_NAME.
2637 CPACK_DMG_FORMAT
2639 The disk image format. Common values are UDRO (UDIF read-only),
2640 UDZO (UDIF zlib-compressed) or UDBZ (UDIF bzip2-compressed).
2641 Refer to hdiutil(1) for more information on other available for‐
2642 mats. Defaults to UDZO.
2643 CPACK_DMG_DS_STORE
2645 Path to a custom DS_Store file. This .DS_Store file e.g. can be
2646 used to specify the Finder window position/geometry and layout
2647 (such as hidden toolbars, placement of the icons etc.). This
2648 file has to be generated by the Finder (either manually or
2649 through AppleScript) using a normal folder from which the
2650 .DS_Store file can then be extracted.
2651 CPACK_DMG_DS_STORE_SETUP_SCRIPT
2653 Path to a custom AppleScript file. This AppleScript is used to
2654 generate a .DS_Store file which specifies the Finder window
2655 position/geometry and layout (such as hidden toolbars, placement
2656 of the icons etc.). By specifying a custom AppleScript there is
2657 no need to use CPACK_DMG_DS_STORE, as the .DS_Store that is gen‐
2658 erated by the AppleScript will be packaged.
2659 CPACK_DMG_BACKGROUND_IMAGE
2661 Path to an image file to be used as the background. This file
2662 will be copied to .background/background.<ext>, where ext is the
2663 original image file extension. The background image is
2664 installed into the image before CPACK_DMG_DS_STORE_SETUP_SCRIPT
2665 is executed or CPACK_DMG_DS_STORE is installed. By default no
2666 background image is set.
2667 CPACK_DMG_DISABLE_APPLICATIONS_SYMLINK
2669 Default behaviour is to include a symlink to /Applications in
2670 the DMG. Set this option to ON to avoid adding the symlink.
2671 CPACK_DMG_SLA_DIR
2673 Directory where license and menu files for different languages
2674 are stored. Setting this causes CPack to look for a <lan‐
2675 guage>.menu.txt and <language>.license.txt file for every lan‐
2676 guage defined in CPACK_DMG_SLA_LANGUAGES. If both this variable
2677 and CPACK_RESOURCE_FILE_LICENSE are set, CPack will only look
2678 for the menu files and use the same license file for all lan‐
2679 guages.
2680 CPACK_DMG_SLA_LANGUAGES
2682 Languages for which a license agreement is provided when mount‐
2683 ing the generated DMG. A menu file consists of 9 lines of text.
2684 The first line is is the name of the language itself, uppercase,
2685 in English (e.g. German). The other lines are translations of
2686 the following strings:
2687 · Agree
2689 · Disagree
2691 · Print
2693 · Save…
2695 · You agree to the terms of the License Agreement when you click
2697 the “Agree” button.
2698 · Software License Agreement
2700 · This text cannot be saved. The disk may be full or locked, or
2702 the file may be locked.
2703 · Unable to print. Make sure you have selected a printer.
2705 For every language in this list, CPack will try to find files
2707 <language>.menu.txt and <language>.license.txt in the directory
2708 specified by the CPACK_DMG_SLA_DIR variable.
2709 CPACK_COMMAND_HDIUTIL
2711 Path to the hdiutil(1) command used to operate on disk image
2712 files on Mac OS X. This variable can be used to override the
2713 automatically detected command (or specify its location if the
2714 auto-detection fails to find it.)
2715 CPACK_COMMAND_SETFILE
2717 Path to the SetFile(1) command used to set extended attributes
2718 on files and directories on Mac OS X. This variable can be used
2719 to override the automatically detected command (or specify its
2720 location if the auto-detection fails to find it.)
2721 CPACK_COMMAND_REZ
2723 Path to the Rez(1) command used to compile resources on Mac OS
2724 X. This variable can be used to override the automatically
2725 detected command (or specify its location if the auto-detection
2726 fails to find it.)
2727 CPackFreeBSD
2729 The built in (binary) CPack FreeBSD (pkg) generator (Unix only)
2730 Variables specific to CPack FreeBSD (pkg) generator
2732 CPackFreeBSD may be used to create pkg(8) packages – these may be used
2733 on FreeBSD, DragonflyBSD, NetBSD, OpenBSD, but also on Linux or OSX,
2734 depending on the installed package-management tools – using CPack.
2735 CPackFreeBSD is a CPack generator and uses the CPACK_XXX variables used
2737 by CPack. It tries to re-use packaging information that may already be
2738 specified for Debian packages for the CPackDeb generator. it also tries
2739 to re-use RPM packaging information when Debian does not specify.
2740 CPackFreeBSD generator should work on any host with libpkg installed.
2742 The packages it produces are specific to the host architecture and ABI.
2743 CPackFreeBSD sets package-metadata through CPACK_FREEBSD_XXX variables.
2745 CPackFreeBSD, unlike CPackDeb, does not specially support componentized
2746 packages; a single package is created from all the software artifacts
2747 created through CMake.
2748 All of the variables can be set specifically for FreeBSD packaging in
2750 the CPackConfig file or in CMakeLists.txt, but most of them have
2751 defaults that use general settings (e.g. CMAKE_PROJECT_NAME) or
2752 Debian-specific variables when those make sense (e.g. the homepage of
2753 an upstream project is usually unchanged by the flavor of packaging).
2754 When there is no Debian information to fall back on, but the RPM pack‐
2755 aging has it, fall back to the RPM information (e.g. package license).
2756 CPACK_FREEBSD_PACKAGE_NAME
2758 Sets the package name (in the package manifest, but also affects
2759 the output filename).
2760 · Mandatory: YES
2762 · Default:
2764 · CPACK_PACKAGE_NAME (this is always set by CPack itself,
2766 based on CMAKE_PROJECT_NAME).
2767 CPACK_FREEBSD_PACKAGE_COMMENT
2769 Sets the package comment. This is the short description dis‐
2770 played by pkg(8) in standard “pkg info” output.
2771 · Mandatory: YES
2773 · Default:
2775 · CPACK_PACKAGE_DESCRIPTION_SUMMARY (this is always set by
2777 CPack itself, if nothing else sets it explicitly).
2778 · PROJECT_DESCRIPTION (this can be set with the DESCRIPTION
2780 parameter for project()).
2781 CPACK_FREEBSD_PACKAGE_DESCRIPTION
2783 Sets the package description. This is the long description of
2784 the package, given by “pkg info” with a specific package as
2785 argument.
2786 · Mandatory: YES
2788 · Default:
2790 · CPACK_DEBIAN_PACKAGE_DESCRIPTION (this may be set already
2792 for Debian packaging, so we may as well re-use it).
2793 CPACK_FREEBSD_PACKAGE_WWW
2795 The URL of the web site for this package, preferably (when
2796 applicable) the site from which the original source can be
2797 obtained and any additional upstream documentation or informa‐
2798 tion may be found.
2799 · Mandatory: YES
2801 · Default:
2803 · CPACK_DEBIAN_PACKAGE_HOMEPAGE (this may be set already for
2805 Debian packaging, so we may as well re-use it).
2806 CPACK_FREEBSD_PACKAGE_LICENSE
2808 The license, or licenses, which apply to this software package.
2809 This must be one or more license-identifiers that pkg recognizes
2810 as acceptable license identifiers (e.g. “GPLv2”).
2811 · Mandatory: YES
2813 · Default:
2815 · CPACK_RPM_PACKAGE_LICENSE
2817 CPACK_FREEBSD_PACKAGE_LICENSE_LOGIC
2819 This variable is only of importance if there is more than one
2820 license. The default is “single”, which is only applicable to a
2821 single license. Other acceptable values are determined by pkg –
2822 those are “dual” or “multi” – meaning choice (OR) or simultane‐
2823 ous (AND) application of the licenses.
2824 · Mandatory: NO
2826 · Default: single
2828 CPACK_FREEBSD_PACKAGE_MAINTAINER
2830 The FreeBSD maintainer (e.g. kde@freebsd.org) of this package.
2831 · Mandatory: YES
2833 · Default: none
2835 CPACK_FREEBSD_PACKAGE_ORIGIN
2837 The origin (ports label) of this package; for packages built by
2838 CPack outside of the ports system this is of less importance.
2839 The default puts the package somewhere under misc/, as a stop‐
2840 gap.
2841 · Mandatory: YES
2843 · Default: misc/<package name>
2845 CPACK_FREEBSD_PACKAGE_CATEGORIES
2847 The ports categories where this package lives (if it were to be
2848 built from ports). If none is set a single category is deter‐
2849 mined based on the package origin.
2850 · Mandatory: YES
2852 · Default: derived from ORIGIN
2854 CPACK_FREEBSD_PACKAGE_DEPS
2856 A list of package origins that should be added as package depen‐
2857 dencies. These are in the form <category>/<packagename>, e.g.
2858 x11/libkonq. No version information needs to be provided (this
2859 is not included in the manifest).
2860 · Mandatory: NO
2862 · Default: empty
2864 CPackIFW
2866 This module looks for the location of the command line utilities sup‐
2867 plied with the Qt Installer Framework (QtIFW).
2868 The module also defines several commands to control the behavior of the
2870 CPack IFW generator.
2871 Overview
2873 CPack IFW generator helps you to create online and offline binary
2874 cross-platform installers with a graphical user interface.
2875 CPack IFW generator prepares project installation and generates config‐
2877 uration and meta information for QtIFW tools.
2878 The QtIFW provides a set of tools and utilities to create installers
2880 for the supported desktop Qt platforms: Linux, Microsoft Windows, and
2881 Mac OS X.
2882 You should also install QtIFW to use CPack IFW generator.
2884 Hints
2886 Generally, the CPack IFW generator automatically finds QtIFW tools, but
2887 if you don’t use a default path for installation of the QtIFW tools,
2888 the path may be specified in either a CMake or an environment variable:
2889 CPACK_IFW_ROOT
2891 An CMake variable which specifies the location of the QtIFW tool
2892 suite.
2893 The variable will be cached in the CPackConfig.cmake file and
2895 used at CPack runtime.
2896 QTIFWDIR
2898 An environment variable which specifies the location of the
2899 QtIFW tool suite.
2900 NOTE:
2902 The specified path should not contain “bin” at the end (for example:
2903 “D:\DevTools\QtIFW2.0.5”).
2904 The CPACK_IFW_ROOT variable has a higher priority and overrides the
2906 value of the QTIFWDIR variable.
2907 Internationalization
2909 Some variables and command arguments support internationalization via
2910 CMake script. This is an optional feature.
2911 Installers created by QtIFW tools have built-in support for interna‐
2913 tionalization and many phrases are localized to many languages, but
2914 this does not apply to the description of the your components and
2915 groups that will be distributed.
2916 Localization of the description of your components and groups is useful
2918 for users of your installers.
2919 A localized variable or argument can contain a single default value,
2921 and a set of pairs the name of the locale and the localized value.
2922 For example:
2924 set(LOCALIZABLE_VARIABLE "Default value"
2926 en "English value"
2927 en_US "American value"
2928 en_GB "Great Britain value"
2929 )
2930 Variables
2932 You can use the following variables to change behavior of CPack IFW
2933 generator.
2934 Debug
2936 CPACK_IFW_VERBOSE
2937 Set to ON to enable addition debug output. By default is OFF.
2938 Package
2940 CPACK_IFW_PACKAGE_TITLE
2941 Name of the installer as displayed on the title bar. By default
2942 used CPACK_PACKAGE_DESCRIPTION_SUMMARY.
2943 CPACK_IFW_PACKAGE_PUBLISHER
2945 Publisher of the software (as shown in the Windows Control
2946 Panel). By default used CPACK_PACKAGE_VENDOR.
2947 CPACK_IFW_PRODUCT_URL
2949 URL to a page that contains product information on your web
2950 site.
2951 CPACK_IFW_PACKAGE_ICON
2953 Filename for a custom installer icon. The actual file is ‘.icns’
2954 (Mac OS X), ‘.ico’ (Windows). No functionality on Unix.
2955 CPACK_IFW_PACKAGE_WINDOW_ICON
2957 Filename for a custom window icon in PNG format for the Install‐
2958 er application.
2959 CPACK_IFW_PACKAGE_LOGO
2961 Filename for a logo is used as QWizard::LogoPixmap.
2962 CPACK_IFW_PACKAGE_WATERMARK
2964 Filename for a watermark is used as QWizard::WatermarkPixmap.
2965 CPACK_IFW_PACKAGE_BANNER
2967 Filename for a banner is used as QWizard::BannerPixmap.
2968 CPACK_IFW_PACKAGE_BACKGROUND
2970 Filename for an image used as QWizard::BackgroundPixmap (only
2971 used by MacStyle).
2972 CPACK_IFW_PACKAGE_WIZARD_STYLE
2974 Wizard style to be used (“Modern”, “Mac”, “Aero” or “Classic”).
2975 CPACK_IFW_PACKAGE_WIZARD_DEFAULT_WIDTH
2977 Default width of the wizard in pixels. Setting a banner image
2978 will override this.
2979 CPACK_IFW_PACKAGE_WIZARD_DEFAULT_HEIGHT
2981 Default height of the wizard in pixels. Setting a watermark
2982 image will override this.
2983 CPACK_IFW_PACKAGE_TITLE_COLOR
2985 Color of the titles and subtitles (takes an HTML color code,
2986 such as “#88FF33”).
2987 CPACK_IFW_PACKAGE_START_MENU_DIRECTORY
2989 Name of the default program group for the product in the Windows
2990 Start menu.
2991 By default used CPACK_IFW_PACKAGE_NAME.
2993 CPACK_IFW_TARGET_DIRECTORY
2995 Default target directory for installation. By default used
2996 “@ApplicationsDir@/CPACK_PACKAGE_INSTALL_DIRECTORY”
2997 You can use predefined variables.
2999 CPACK_IFW_ADMIN_TARGET_DIRECTORY
3001 Default target directory for installation with administrator
3002 rights.
3003 You can use predefined variables.
3005 CPACK_IFW_PACKAGE_GROUP
3007 The group, which will be used to configure the root package
3008 CPACK_IFW_PACKAGE_NAME
3010 The root package name, which will be used if configuration group
3011 is not specified
3012 CPACK_IFW_PACKAGE_MAINTENANCE_TOOL_NAME
3014 Filename of the generated maintenance tool. The platform-spe‐
3015 cific executable file extension is appended.
3016 By default used QtIFW defaults (maintenancetool).
3018 CPACK_IFW_PACKAGE_REMOVE_TARGET_DIR
3020 Set to OFF if the target directory should not be deleted when
3021 uninstalling.
3022 Is ON by default
3024 CPACK_IFW_PACKAGE_MAINTENANCE_TOOL_INI_FILE
3026 Filename for the configuration of the generated maintenance
3027 tool.
3028 By default used QtIFW defaults (maintenancetool.ini).
3030 CPACK_IFW_PACKAGE_ALLOW_NON_ASCII_CHARACTERS
3032 Set to ON if the installation path can contain non-ASCII charac‐
3033 ters.
3034 Is ON for QtIFW less 2.0 tools.
3036 CPACK_IFW_PACKAGE_ALLOW_SPACE_IN_PATH
3038 Set to OFF if the installation path cannot contain space charac‐
3039 ters.
3040 Is ON for QtIFW less 2.0 tools.
3042 CPACK_IFW_PACKAGE_CONTROL_SCRIPT
3044 Filename for a custom installer control script.
3045 CPACK_IFW_PACKAGE_RESOURCES
3047 List of additional resources (‘.qrc’ files) to include in the
3048 installer binary.
3049 You can use cpack_ifw_add_package_resources() command to resolve
3051 relative paths.
3052 CPACK_IFW_PACKAGE_FILE_EXTENSION
3054 The target binary extension.
3055 On Linux, the name of the target binary is automatically
3057 extended with ‘.run’, if you do not specify the extension.
3058 On Windows, the target is created as an application with the
3060 extension ‘.exe’, which is automatically added, if not supplied.
3061 On Mac, the target is created as an DMG disk image with the
3063 extension ‘.dmg’, which is automatically added, if not supplied.
3064 CPACK_IFW_REPOSITORIES_ALL
3066 The list of remote repositories.
3067 The default value of this variable is computed by CPack and con‐
3069 tains all repositories added with command
3070 cpack_ifw_add_repository() or updated with command
3071 cpack_ifw_update_repository().
3072 CPACK_IFW_DOWNLOAD_ALL
3074 If this is ON all components will be downloaded. By default is
3075 OFF or used value from CPACK_DOWNLOAD_ALL if set
3076 Components
3078 CPACK_IFW_RESOLVE_DUPLICATE_NAMES
3079 Resolve duplicate names when installing components with groups.
3080 CPACK_IFW_PACKAGES_DIRECTORIES
3082 Additional prepared packages dirs that will be used to resolve
3083 dependent components.
3084 CPACK_IFW_REPOSITORIES_DIRECTORIES
3086 Additional prepared repository dirs that will be used to resolve
3087 and repack dependent components. This feature available only
3088 since QtIFW 3.1.
3089 Tools
3091 CPACK_IFW_FRAMEWORK_VERSION
3092 The version of used QtIFW tools.
3093 CPACK_IFW_BINARYCREATOR_EXECUTABLE
3095 The path to “binarycreator” command line client.
3096 This variable is cached and may be configured if needed.
3098 CPACK_IFW_REPOGEN_EXECUTABLE
3100 The path to “repogen” command line client.
3101 This variable is cached and may be configured if needed.
3103 CPACK_IFW_INSTALLERBASE_EXECUTABLE
3105 The path to “installerbase” installer executable base.
3106 This variable is cached and may be configured if needed.
3108 CPACK_IFW_DEVTOOL_EXECUTABLE
3110 The path to “devtool” command line client.
3111 This variable is cached and may be configured if needed.
3113 Commands
3115 The module defines the following commands:
3116 cpack_ifw_configure_component
3118 Sets the arguments specific to the CPack IFW generator.
3119 cpack_ifw_configure_component(<compname> [COMMON] [ESSENTIAL] [VIRTUAL]
3121 [FORCED_INSTALLATION] [REQUIRES_ADMIN_RIGHTS]
3122 [NAME <name>]
3123 [DISPLAY_NAME <display_name>] # Note: Internationalization supported
3124 [DESCRIPTION <description>] # Note: Internationalization supported
3125 [UPDATE_TEXT <update_text>]
3126 [VERSION <version>]
3127 [RELEASE_DATE <release_date>]
3128 [SCRIPT <script>]
3129 [PRIORITY|SORTING_PRIORITY <sorting_priority>] # Note: PRIORITY is deprecated
3130 [DEPENDS|DEPENDENCIES <com_id> ...]
3131 [AUTO_DEPEND_ON <comp_id> ...]
3132 [LICENSES <display_name> <file_path> ...]
3133 [DEFAULT <value>]
3134 [USER_INTERFACES <file_path> <file_path> ...]
3135 [TRANSLATIONS <file_path> <file_path> ...]
3136 [REPLACES <comp_id> ...]
3137 [CHECKABLE <value>])
3138 This command should be called after cpack_add_component() com‐
3140 mand.
3141 COMMON if set, then the component will be packaged and installed
3143 as part of a group to which it belongs.
3144 ESSENTIAL
3146 if set, then the package manager stays disabled until
3147 that component is updated.
3148 VIRTUAL
3150 if set, then the component will be hidden from the in‐
3151 staller. It is a equivalent of the HIDDEN option from
3152 the cpack_add_component() command.
3153 FORCED_INSTALLATION
3155 if set, then the component must always be installed. It
3156 is a equivalent of the REQUARED option from the
3157 cpack_add_component() command.
3158 REQUIRES_ADMIN_RIGHTS
3160 set it if the component needs to be installed with ele‐
3161 vated permissions.
3162 NAME is used to create domain-like identification for this
3164 component. By default used origin component name.
3165 DISPLAY_NAME
3167 set to rewrite original name configured by cpack_add_com‐
3168 ponent() command.
3169 DESCRIPTION
3171 set to rewrite original description configured by
3172 cpack_add_component() command.
3173 UPDATE_TEXT
3175 will be added to the component description if this is an
3176 update to the component.
3177 VERSION
3179 is version of component. By default used CPACK_PACK‐
3180 AGE_VERSION.
3181 RELEASE_DATE
3183 keep empty to auto generate.
3184 SCRIPT is a relative or absolute path to operations script for
3186 this component.
3187 PRIORITY | SORTING_PRIORITY
3189 is priority of the component in the tree. The PRIORITY
3190 option is deprecated and will be removed in a future ver‐
3191 sion of CMake. Please use SORTING_PRIORITY option
3192 instead.
3193 DEPENDS | DEPENDENCIES
3195 list of dependency component or component group identi‐
3196 fiers in QtIFW style.
3197 AUTO_DEPEND_ON
3199 list of identifiers of component or component group in
3200 QtIFW style that this component has an automatic depen‐
3201 dency on.
3202 LICENSES
3204 pair of <display_name> and <file_path> of license text
3205 for this component. You can specify more then one
3206 license.
3207 DEFAULT
3209 Possible values are: TRUE, FALSE, and SCRIPT. Set to
3210 FALSE to disable the component in the installer or to
3211 SCRIPT to resolved during runtime (don’t forget add the
3212 file of the script as a value of the SCRIPT option).
3213 USER_INTERFACES
3215 is a list of <file_path> (‘.ui’ files) representing pages
3216 to load.
3217 TRANSLATIONS
3219 is a list of <file_path> (‘.qm’ files) representing
3220 translations to load.
3221 REPLACES
3223 list of identifiers of component or component group to
3224 replace.
3225 CHECKABLE
3227 Possible values are: TRUE, FALSE. Set to FALSE if you
3228 want to hide the checkbox for an item. This is useful
3229 when only a few subcomponents should be selected instead
3230 of all.
3231 cpack_ifw_configure_component_group
3233 Sets the arguments specific to the CPack IFW generator.
3234 cpack_ifw_configure_component_group(<groupname> [VIRTUAL]
3236 [FORCED_INSTALLATION] [REQUIRES_ADMIN_RIGHTS]
3237 [NAME <name>]
3238 [DISPLAY_NAME <display_name>] # Note: Internationalization supported
3239 [DESCRIPTION <description>] # Note: Internationalization supported
3240 [UPDATE_TEXT <update_text>]
3241 [VERSION <version>]
3242 [RELEASE_DATE <release_date>]
3243 [SCRIPT <script>]
3244 [PRIORITY|SORTING_PRIORITY <sorting_priority>] # Note: PRIORITY is deprecated
3245 [DEPENDS|DEPENDENCIES <com_id> ...]
3246 [AUTO_DEPEND_ON <comp_id> ...]
3247 [LICENSES <display_name> <file_path> ...]
3248 [DEFAULT <value>]
3249 [USER_INTERFACES <file_path> <file_path> ...]
3250 [TRANSLATIONS <file_path> <file_path> ...]
3251 [REPLACES <comp_id> ...]
3252 [CHECKABLE <value>])
3253 This command should be called after cpack_add_component_group()
3255 command.
3256 VIRTUAL
3258 if set, then the group will be hidden from the installer.
3259 Note that setting this on a root component does not work.
3260 FORCED_INSTALLATION
3262 if set, then the group must always be installed.
3263 REQUIRES_ADMIN_RIGHTS
3265 set it if the component group needs to be installed with
3266 elevated permissions.
3267 NAME is used to create domain-like identification for this
3269 component group. By default used origin component group
3270 name.
3271 DISPLAY_NAME
3273 set to rewrite original name configured by cpack_add_com‐
3274 ponent_group() command.
3275 DESCRIPTION
3277 set to rewrite original description configured by
3278 cpack_add_component_group() command.
3279 UPDATE_TEXT
3281 will be added to the component group description if this
3282 is an update to the component group.
3283 VERSION
3285 is version of component group. By default used
3286 CPACK_PACKAGE_VERSION.
3287 RELEASE_DATE
3289 keep empty to auto generate.
3290 SCRIPT is a relative or absolute path to operations script for
3292 this component group.
3293 PRIORITY | SORTING_PRIORITY
3295 is priority of the component group in the tree. The PRI‐
3296 ORITY option is deprecated and will be removed in a
3297 future version of CMake. Please use SORTING_PRIORITY
3298 option instead.
3299 DEPENDS | DEPENDENCIES
3301 list of dependency component or component group identi‐
3302 fiers in QtIFW style.
3303 AUTO_DEPEND_ON
3305 list of identifiers of component or component group in
3306 QtIFW style that this component group has an automatic
3307 dependency on.
3308 LICENSES
3310 pair of <display_name> and <file_path> of license text
3311 for this component group. You can specify more then one
3312 license.
3313 DEFAULT
3315 Possible values are: TRUE, FALSE, and SCRIPT. Set to
3316 TRUE to preselect the group in the installer (this takes
3317 effect only on groups that have no visible child compo‐
3318 nents) or to SCRIPT to resolved during runtime (don’t
3319 forget add the file of the script as a value of the
3320 SCRIPT option).
3321 USER_INTERFACES
3323 is a list of <file_path> (‘.ui’ files) representing pages
3324 to load.
3325 TRANSLATIONS
3327 is a list of <file_path> (‘.qm’ files) representing
3328 translations to load.
3329 REPLACES
3331 list of identifiers of component or component group to
3332 replace.
3333 CHECKABLE
3335 Possible values are: TRUE, FALSE. Set to FALSE if you
3336 want to hide the checkbox for an item. This is useful
3337 when only a few subcomponents should be selected instead
3338 of all.
3339 cpack_ifw_add_repository
3341 Add QtIFW specific remote repository to binary installer.
3342 cpack_ifw_add_repository(<reponame> [DISABLED]
3344 URL <url>
3345 [USERNAME <username>]
3346 [PASSWORD <password>]
3347 [DISPLAY_NAME <display_name>])
3348 This command will also add the <reponame> repository to a vari‐
3350 able CPACK_IFW_REPOSITORIES_ALL.
3351 DISABLED
3353 if set, then the repository will be disabled by default.
3354 URL is points to a list of available components.
3356 USERNAME
3358 is used as user on a protected repository.
3359 PASSWORD
3361 is password to use on a protected repository.
3362 DISPLAY_NAME
3364 is string to display instead of the URL.
3365 cpack_ifw_update_repository
3367 Update QtIFW specific repository from remote repository.
3368 cpack_ifw_update_repository(<reponame>
3370 [[ADD|REMOVE] URL <url>]|
3371 [REPLACE OLD_URL <old_url> NEW_URL <new_url>]]
3372 [USERNAME <username>]
3373 [PASSWORD <password>]
3374 [DISPLAY_NAME <display_name>])
3375 This command will also add the <reponame> repository to a vari‐
3377 able CPACK_IFW_REPOSITORIES_ALL.
3378 URL is points to a list of available components.
3380 OLD_URL
3382 is points to a list that will replaced.
3383 NEW_URL
3385 is points to a list that will replace to.
3386 USERNAME
3388 is used as user on a protected repository.
3389 PASSWORD
3391 is password to use on a protected repository.
3392 DISPLAY_NAME
3394 is string to display instead of the URL.
3395 cpack_ifw_add_package_resources
3397 Add additional resources in the installer binary.
3398 cpack_ifw_add_package_resources(<file_path> <file_path> ...)
3400 This command will also add the specified files to a variable
3402 CPACK_IFW_PACKAGE_RESOURCES.
3403 Example usage
3405 set(CPACK_PACKAGE_NAME "MyPackage")
3406 set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "MyPackage Installation Example")
3407 set(CPACK_PACKAGE_VERSION "1.0.0") # Version of installer
3408 include(CPack)
3410 include(CPackIFW)
3411 cpack_add_component(myapp
3413 DISPLAY_NAME "MyApp"
3414 DESCRIPTION "My Application") # Default description
3415 cpack_ifw_configure_component(myapp
3416 DESCRIPTION ru_RU "Мое Приложение" # Localized description
3417 VERSION "1.2.3" # Version of component
3418 SCRIPT "operations.qs")
3419 cpack_add_component(mybigplugin
3420 DISPLAY_NAME "MyBigPlugin"
3421 DESCRIPTION "My Big Downloadable Plugin"
3422 DOWNLOADED)
3423 cpack_ifw_add_repository(myrepo
3424 URL "http://example.com/ifw/repo/myapp"
3425 DISPLAY_NAME "My Application Repository")
3426 Online installer
3428 By default CPack IFW generator makes offline installer. This means that
3429 all components will be packaged into a binary file.
3430 To make a component downloaded, you must set the DOWNLOADED option in
3432 cpack_add_component().
3433 Then you would use the command cpack_configure_downloads(). If you set
3435 ALL option all components will be downloaded.
3436 You also can use command cpack_ifw_add_repository() and variable
3438 CPACK_IFW_DOWNLOAD_ALL for more specific configuration.
3439 CPack IFW generator creates “repository” dir in current binary dir. You
3441 would copy content of this dir to specified site (url).
3442 See Also
3444 Qt Installer Framework Manual:
3445 · Index page: http://doc.qt.io/qtinstallerframework/index.html
3447 · Component Scripting:
3449 http://doc.qt.io/qtinstallerframework/scripting.html
3450 · Predefined Variables:
3452 http://doc.qt.io/qtinstallerframework/scripting.html#predefined-variables
3453 · Promoting Updates:
3455 http://doc.qt.io/qtinstallerframework/ifw-updates.html
3456 Download Qt Installer Framework for you platform from Qt site:
3458 http://download.qt.io/official_releases/qt-installer-framework
3459 CPackIFWConfigureFile
3461 The module defines configure_file() similar command to configure file
3462 templates prepared in QtIFW/SDK/Creator style.
3463 Commands
3465 The module defines the following commands:
3466 cpack_ifw_configure_file
3468 Copy a file to another location and modify its contents.
3469 cpack_ifw_configure_file(<input> <output>)
3471 Copies an <input> file to an <output> file and substitutes vari‐
3473 able values referenced as %{VAR} or %VAR% in the input file con‐
3474 tent. Each variable reference will be replaced with the current
3475 value of the variable, or the empty string if the variable is
3476 not defined.
3477 CPackNSIS
3479 CPack NSIS generator specific options
3480 Variables specific to CPack NSIS generator
3482 The following variables are specific to the graphical installers built
3483 on Windows using the Nullsoft Installation System.
3484 CPACK_NSIS_INSTALL_ROOT
3486 The default installation directory presented to the end user by
3487 the NSIS installer is under this root dir. The full directory
3488 presented to the end user is:
3489 ${CPACK_NSIS_INSTALL_ROOT}/${CPACK_PACKAGE_INSTALL_DIRECTORY}
3490 CPACK_NSIS_MUI_ICON
3492 An icon filename. The name of a *.ico file used as the main
3493 icon for the generated install program.
3494 CPACK_NSIS_MUI_UNIICON
3496 An icon filename. The name of a *.ico file used as the main
3497 icon for the generated uninstall program.
3498 CPACK_NSIS_INSTALLER_MUI_ICON_CODE
3500 undocumented.
3501 CPACK_NSIS_MUI_WELCOMEFINISHPAGE_BITMAP
3503 The filename of a bitmap to use as the NSIS MUI_WELCOMEFINISH‐
3504 PAGE_BITMAP.
3505 CPACK_NSIS_MUI_UNWELCOMEFINISHPAGE_BITMAP
3507 The filename of a bitmap to use as the NSIS MUI_UNWELCOMEFINISH‐
3508 PAGE_BITMAP.
3509 CPACK_NSIS_EXTRA_PREINSTALL_COMMANDS
3511 Extra NSIS commands that will be added to the beginning of the
3512 install Section, before your install tree is available on the
3513 target system.
3514 CPACK_NSIS_EXTRA_INSTALL_COMMANDS
3516 Extra NSIS commands that will be added to the end of the install
3517 Section, after your install tree is available on the target sys‐
3518 tem.
3519 CPACK_NSIS_EXTRA_UNINSTALL_COMMANDS
3521 Extra NSIS commands that will be added to the uninstall Section,
3522 before your install tree is removed from the target system.
3523 CPACK_NSIS_COMPRESSOR
3525 The arguments that will be passed to the NSIS SetCompressor com‐
3526 mand.
3527 CPACK_NSIS_ENABLE_UNINSTALL_BEFORE_INSTALL
3529 Ask about uninstalling previous versions first. If this is set
3530 to “ON”, then an installer will look for previous installed ver‐
3531 sions and if one is found, ask the user whether to uninstall it
3532 before proceeding with the install.
3533 CPACK_NSIS_MODIFY_PATH
3535 Modify PATH toggle. If this is set to “ON”, then an extra page
3536 will appear in the installer that will allow the user to choose
3537 whether the program directory should be added to the system PATH
3538 variable.
3539 CPACK_NSIS_DISPLAY_NAME
3541 The display name string that appears in the Windows Add/Remove
3542 Program control panel
3543 CPACK_NSIS_PACKAGE_NAME
3545 The title displayed at the top of the installer.
3546 CPACK_NSIS_INSTALLED_ICON_NAME
3548 A path to the executable that contains the installer icon.
3549 CPACK_NSIS_HELP_LINK
3551 URL to a web site providing assistance in installing your appli‐
3552 cation.
3553 CPACK_NSIS_URL_INFO_ABOUT
3555 URL to a web site providing more information about your applica‐
3556 tion.
3557 CPACK_NSIS_CONTACT
3559 Contact information for questions and comments about the instal‐
3560 lation process.
3561 CPACK_NSIS_<compName>_INSTALL_DIRECTORY
3563 Custom install directory for the specified component <compName>
3564 instead of $INSTDIR.
3565 CPACK_NSIS_CREATE_ICONS_EXTRA
3567 Additional NSIS commands for creating start menu shortcuts.
3568 CPACK_NSIS_DELETE_ICONS_EXTRA
3570 Additional NSIS commands to uninstall start menu shortcuts.
3571 CPACK_NSIS_EXECUTABLES_DIRECTORY
3573 Creating NSIS start menu links assumes that they are in ‘bin’
3574 unless this variable is set. For example, you would set this to
3575 ‘exec’ if your executables are in an exec directory.
3576 CPACK_NSIS_MUI_FINISHPAGE_RUN
3578 Specify an executable to add an option to run on the finish page
3579 of the NSIS installer.
3580 CPACK_NSIS_MENU_LINKS
3582 Specify links in [application] menu. This should contain a list
3583 of pair “link” “link name”. The link may be an URL or a path
3584 relative to installation prefix. Like:
3585 set(CPACK_NSIS_MENU_LINKS
3587 "doc/cmake-@CMake_VERSION_MAJOR@.@CMake_VERSION_MINOR@/cmake.html"
3588 "CMake Help" "https://cmake.org" "CMake Web Site")
3589 CPackPackageMaker
3591 PackageMaker CPack generator (Mac OS X).
3592 Variables specific to CPack PackageMaker generator
3594 The following variable is specific to installers built on Mac OS X
3595 using PackageMaker:
3596 CPACK_OSX_PACKAGE_VERSION
3598 The version of Mac OS X that the resulting PackageMaker archive
3599 should be compatible with. Different versions of Mac OS X sup‐
3600 port different features. For example, CPack can only build com‐
3601 ponent-based installers for Mac OS X 10.4 or newer, and can only
3602 build installers that download component son-the-fly for Mac OS
3603 X 10.5 or newer. If left blank, this value will be set to the
3604 minimum version of Mac OS X that supports the requested fea‐
3605 tures. Set this variable to some value (e.g., 10.4) only if you
3606 want to guarantee that your installer will work on that version
3607 of Mac OS X, and don’t mind missing extra features available in
3608 the installer shipping with later versions of Mac OS X.
3609 CPackProductBuild
3611 productbuild CPack generator (Mac OS X).
3612 Variables specific to CPack productbuild generator
3614 The following variable is specific to installers built on Mac OS X
3615 using productbuild:
3616 CPACK_COMMAND_PRODUCTBUILD
3618 Path to the productbuild(1) command used to generate a product
3619 archive for the OS X Installer or Mac App Store. This variable
3620 can be used to override the automatically detected command (or
3621 specify its location if the auto-detection fails to find it.)
3622 CPACK_PRODUCTBUILD_IDENTITY_NAME
3624 Adds a digital signature to the resulting package.
3625 CPACK_PRODUCTBUILD_KEYCHAIN_PATH
3627 Specify a specific keychain to search for the signing identity.
3628 CPACK_COMMAND_PKGBUILD
3630 Path to the pkgbuild(1) command used to generate an OS X compo‐
3631 nent package on OS X. This variable can be used to override the
3632 automatically detected command (or specify its location if the
3633 auto-detection fails to find it.)
3634 CPACK_PKGBUILD_IDENTITY_NAME
3636 Adds a digital signature to the resulting package.
3637 CPACK_PKGBUILD_KEYCHAIN_PATH
3639 Specify a specific keychain to search for the signing identity.
3640 CPACK_PRODUCTBUILD_RESOURCES_DIR
3642 If specified the productbuild generator copies files from this
3643 directory (including subdirectories) to the Resources directory.
3644 This is done before the CPACK_RESOURCE_FILE_WELCOME,
3645 CPACK_RESOURCE_FILE_README, and CPACK_RESOURCE_FILE_LICENSE
3646 files are copied.
3647 CPackRPM
3649 The built in (binary) CPack RPM generator (Unix only)
3650 Variables specific to CPack RPM generator
3652 CPackRPM may be used to create RPM packages using CPack. CPackRPM is a
3653 CPack generator thus it uses the CPACK_XXX variables used by CPack.
3654 CPackRPM has specific features which are controlled by the specifics
3656 CPACK_RPM_XXX variables.
3657 CPACK_RPM_<COMPONENT>_XXXX variables may be used in order to have com‐
3659 ponent specific values. Note however that <COMPONENT> refers to the
3660 grouping name written in upper case. It may be either a component name
3661 or a component GROUP name. Usually those variables correspond to RPM
3662 spec file entities. One may find information about spec files here
3663 http://www.rpm.org/wiki/Docs
3664 NOTE:
3666 <COMPONENT> part of variables is preferred to be in upper case (for
3667 e.g. if component is named foo then use CPACK_RPM_FOO_XXXX variable
3668 name format) as is with other CPACK_<COMPONENT>_XXXX variables. For
3669 the purposes of back compatibility (CMake/CPack version 3.5 and
3670 lower) support for same cased component (e.g. fOo would be used as
3671 CPACK_RPM_fOo_XXXX) is still supported for variables defined in
3672 older versions of CMake/CPack but is not guaranteed for variables
3673 that will be added in the future. For the sake of back compatibility
3674 same cased component variables also override upper cased versions
3675 where both are present.
3676 Here are some CPackRPM wiki resources that are here for historic rea‐
3678 sons and are no longer maintained but may still prove useful:
3679 · https://cmake.org/Wiki/CMake:CPackConfiguration
3681 · https://cmake.org/Wiki/CMake:CPackPackageGenerators#RPM_.28Unix_Only.29
3683 List of CPackRPM specific variables:
3685 CPACK_RPM_COMPONENT_INSTALL
3687 Enable component packaging for CPackRPM
3688 · Mandatory : NO
3690 · Default : OFF
3692 If enabled (ON) multiple packages are generated. By default a
3694 single package containing files of all components is generated.
3695 CPACK_RPM_PACKAGE_SUMMARY
3697 CPACK_RPM_<component>_PACKAGE_SUMMARY
3699 The RPM package summary.
3700 · Mandatory : YES
3702 · Default : CPACK_PACKAGE_DESCRIPTION_SUMMARY
3704 CPACK_RPM_PACKAGE_NAME
3706 CPACK_RPM_<component>_PACKAGE_NAME
3708 The RPM package name.
3709 · Mandatory : YES
3711 · Default : CPACK_PACKAGE_NAME
3713 CPACK_RPM_FILE_NAME
3715 CPACK_RPM_<component>_FILE_NAME
3717 Package file name.
3718 · Mandatory : YES
3720 ·
3722 Default
3724 <CPACK_PACKAGE_FILE_NAME>[-<component>].rpm with spaces
3725 replaced by ‘-‘
3726 This may be set to RPM-DEFAULT to allow rpmbuild tool to gener‐
3728 ate package file name by itself. Alternatively provided package
3729 file name must end with .rpm suffix.
3730 NOTE:
3732 By using user provided spec file, rpm macro extensions such
3733 as for generating debuginfo packages or by simply using mul‐
3734 tiple components more than one rpm file may be generated,
3735 either from a single spec file or from multiple spec files
3736 (each component execution produces it’s own spec file). In
3737 such cases duplicate file names may occur as a result of this
3738 variable setting or spec file content structure. Duplicate
3739 files get overwritten and it is up to the packager to set the
3740 variables in a manner that will prevent such errors.
3741 CPACK_RPM_MAIN_COMPONENT
3743 Main component that is packaged without component suffix.
3744 · Mandatory : NO
3746 · Default : -
3748 This variable can be set to any component or group name so that
3750 component or group rpm package is generated without component
3751 suffix in filename and package name.
3752 CPACK_RPM_PACKAGE_EPOCH
3754 The RPM package epoch
3755 · Mandatory : No
3757 · Default : -
3759 Optional number that should be incremented when changing ver‐
3761 sioning schemas or fixing mistakes in the version numbers of
3762 older packages.
3763 CPACK_RPM_PACKAGE_VERSION
3765 The RPM package version.
3766 · Mandatory : YES
3768 · Default : CPACK_PACKAGE_VERSION
3770 CPACK_RPM_PACKAGE_ARCHITECTURE
3772 CPACK_RPM_<component>_PACKAGE_ARCHITECTURE
3774 The RPM package architecture.
3775 · Mandatory : YES
3777 · Default : Native architecture output by uname -m
3779 This may be set to noarch if you know you are building a noarch
3781 package.
3782 CPACK_RPM_PACKAGE_RELEASE
3784 The RPM package release.
3785 · Mandatory : YES
3787 · Default : 1
3789 This is the numbering of the RPM package itself, i.e. the ver‐
3791 sion of the packaging and not the version of the content (see
3792 CPACK_RPM_PACKAGE_VERSION). One may change the default value if
3793 the previous packaging was buggy and/or you want to put here a
3794 fancy Linux distro specific numbering.
3795 NOTE:
3797 This is the string that goes into the RPM Release: field. Some dis‐
3798 tros (e.g. Fedora, CentOS) require 1%{?dist} format and not just a
3799 number. %{?dist} part can be added by setting
3800 CPACK_RPM_PACKAGE_RELEASE_DIST.
3801 CPACK_RPM_PACKAGE_RELEASE_DIST
3803 The dist tag that is added RPM Release: field.
3804 · Mandatory : NO
3806 · Default : OFF
3808 This is the reported %{dist} tag from the current distribution
3810 or empty %{dist} if RPM macro is not set. If this variable is
3811 set then RPM Release: field value is set to ${CPACK_RPM_PACK‐
3812 AGE_RELEASE}%{?dist}.
3813 CPACK_RPM_PACKAGE_LICENSE
3815 The RPM package license policy.
3816 · Mandatory : YES
3818 · Default : “unknown”
3820 CPACK_RPM_PACKAGE_GROUP
3822 CPACK_RPM_<component>_PACKAGE_GROUP
3824 The RPM package group.
3825 · Mandatory : YES
3827 · Default : “unknown”
3829 CPACK_RPM_PACKAGE_VENDOR
3831 The RPM package vendor.
3832 · Mandatory : YES
3834 · Default : CPACK_PACKAGE_VENDOR if set or “unknown”
3836 CPACK_RPM_PACKAGE_URL
3838 CPACK_RPM_<component>_PACKAGE_URL
3840 The projects URL.
3841 · Mandatory : NO
3843 · Default : -
3845 CPACK_RPM_PACKAGE_DESCRIPTION
3847 CPACK_RPM_<component>_PACKAGE_DESCRIPTION
3849 RPM package description.
3850 · Mandatory : YES
3852 · Default : CPACK_COMPONENT_<compName>_DESCRIPTION (component
3854 based installers only) if set, CPACK_PACKAGE_DESCRIPTION_FILE
3855 if set or “no package description available”
3856 CPACK_RPM_COMPRESSION_TYPE
3858 RPM compression type.
3859 · Mandatory : NO
3861 · Default : -
3863 May be used to override RPM compression type to be used to build
3865 the RPM. For example some Linux distribution now default to lzma
3866 or xz compression whereas older cannot use such RPM. Using this
3867 one can enforce compression type to be used.
3868 Possible values are:
3870 · lzma
3872 · xz
3874 · bzip2
3876 · gzip
3878 CPACK_RPM_PACKAGE_AUTOREQ
3880 CPACK_RPM_<component>_PACKAGE_AUTOREQ
3882 RPM spec autoreq field.
3883 · Mandatory : NO
3885 · Default : -
3887 May be used to enable (1, yes) or disable (0, no) automatic
3889 shared libraries dependency detection. Dependencies are added to
3890 requires list.
3891 NOTE:
3893 By default automatic dependency detection is enabled by rpm
3894 generator.
3895 CPACK_RPM_PACKAGE_AUTOPROV
3897 CPACK_RPM_<component>_PACKAGE_AUTOPROV
3899 RPM spec autoprov field.
3900 · Mandatory : NO
3902 · Default : -
3904 May be used to enable (1, yes) or disable (0, no) automatic
3906 listing of shared libraries that are provided by the package.
3907 Shared libraries are added to provides list.
3908 NOTE:
3910 By default automatic provides detection is enabled by rpm
3911 generator.
3912 CPACK_RPM_PACKAGE_AUTOREQPROV
3914 CPACK_RPM_<component>_PACKAGE_AUTOREQPROV
3916 RPM spec autoreqprov field.
3917 · Mandatory : NO
3919 · Default : -
3921 Variable enables/disables autoreq and autoprov at the same time.
3923 See CPACK_RPM_PACKAGE_AUTOREQ and CPACK_RPM_PACKAGE_AUTOPROV for
3924 more details.
3925 NOTE:
3927 By default automatic detection feature is enabled by rpm.
3928 CPACK_RPM_PACKAGE_REQUIRES
3930 CPACK_RPM_<component>_PACKAGE_REQUIRES
3932 RPM spec requires field.
3933 · Mandatory : NO
3935 · Default : -
3937 May be used to set RPM dependencies (requires). Note that you
3939 must enclose the complete requires string between quotes, for
3940 example:
3941 set(CPACK_RPM_PACKAGE_REQUIRES "python >= 2.5.0, cmake >= 2.8")
3943 The required package list of an RPM file could be printed with:
3945 rpm -qp --requires file.rpm
3947 CPACK_RPM_PACKAGE_CONFLICTS
3949 CPACK_RPM_<component>_PACKAGE_CONFLICTS
3951 RPM spec conflicts field.
3952 · Mandatory : NO
3954 · Default : -
3956 May be used to set negative RPM dependencies (conflicts). Note
3958 that you must enclose the complete requires string between
3959 quotes, for example:
3960 set(CPACK_RPM_PACKAGE_CONFLICTS "libxml2")
3962 The conflicting package list of an RPM file could be printed
3964 with:
3965 rpm -qp --conflicts file.rpm
3967 CPACK_RPM_PACKAGE_REQUIRES_PRE
3969 CPACK_RPM_<component>_PACKAGE_REQUIRES_PRE
3971 RPM spec requires(pre) field.
3972 · Mandatory : NO
3974 · Default : -
3976 May be used to set RPM preinstall dependencies (requires(pre)).
3978 Note that you must enclose the complete requires string between
3979 quotes, for example:
3980 set(CPACK_RPM_PACKAGE_REQUIRES_PRE "shadow-utils, initscripts")
3982 CPACK_RPM_PACKAGE_REQUIRES_POST
3984 CPACK_RPM_<component>_PACKAGE_REQUIRES_POST
3986 RPM spec requires(post) field.
3987 · Mandatory : NO
3989 · Default : -
3991 May be used to set RPM postinstall dependencies
3993 (requires(post)). Note that you must enclose the complete
3994 requires string between quotes, for example:
3995 set(CPACK_RPM_PACKAGE_REQUIRES_POST "shadow-utils, initscripts")
3997 CPACK_RPM_PACKAGE_REQUIRES_POSTUN
3999 CPACK_RPM_<component>_PACKAGE_REQUIRES_POSTUN
4001 RPM spec requires(postun) field.
4002 · Mandatory : NO
4004 · Default : -
4006 May be used to set RPM postuninstall dependencies (requires(pos‐
4008 tun)). Note that you must enclose the complete requires string
4009 between quotes, for example:
4010 set(CPACK_RPM_PACKAGE_REQUIRES_POSTUN "shadow-utils, initscripts")
4012 CPACK_RPM_PACKAGE_REQUIRES_PREUN
4014 CPACK_RPM_<component>_PACKAGE_REQUIRES_PREUN
4016 RPM spec requires(preun) field.
4017 · Mandatory : NO
4019 · Default : -
4021 May be used to set RPM preuninstall dependencies
4023 (requires(preun)). Note that you must enclose the complete
4024 requires string between quotes, for example:
4025 set(CPACK_RPM_PACKAGE_REQUIRES_PREUN "shadow-utils, initscripts")
4027 CPACK_RPM_PACKAGE_SUGGESTS
4029 CPACK_RPM_<component>_PACKAGE_SUGGESTS
4031 RPM spec suggest field.
4032 · Mandatory : NO
4034 · Default : -
4036 May be used to set weak RPM dependencies (suggests). Note that
4038 you must enclose the complete requires string between quotes.
4039 CPACK_RPM_PACKAGE_PROVIDES
4041 CPACK_RPM_<component>_PACKAGE_PROVIDES
4043 RPM spec provides field.
4044 · Mandatory : NO
4046 · Default : -
4048 May be used to set RPM dependencies (provides). The provided
4050 package list of an RPM file could be printed with:
4051 rpm -qp --provides file.rpm
4053 CPACK_RPM_PACKAGE_OBSOLETES
4055 CPACK_RPM_<component>_PACKAGE_OBSOLETES
4057 RPM spec obsoletes field.
4058 · Mandatory : NO
4060 · Default : -
4062 May be used to set RPM packages that are obsoleted by this one.
4064 CPACK_RPM_PACKAGE_RELOCATABLE
4066 build a relocatable RPM.
4067 · Mandatory : NO
4069 · Default : CPACK_PACKAGE_RELOCATABLE
4071 If this variable is set to TRUE or ON CPackRPM will try to build
4073 a relocatable RPM package. A relocatable RPM may be installed
4074 using:
4075 rpm --prefix or --relocate
4077 in order to install it at an alternate place see rpm(8). Note
4079 that currently this may fail if CPACK_SET_DESTDIR is set to ON.
4080 If CPACK_SET_DESTDIR is set then you will get a warning message
4081 but if there is file installed with absolute path you’ll get
4082 unexpected behavior.
4083 CPACK_RPM_SPEC_INSTALL_POST
4085 Deprecated - use CPACK_RPM_POST_INSTALL_SCRIPT_FILE instead.
4086 · Mandatory : NO
4088 · Default : -
4090 · Deprecated: YES
4092 This way of specifying post-install script is deprecated, use
4094 CPACK_RPM_POST_INSTALL_SCRIPT_FILE. May be used to set an RPM
4095 post-install command inside the spec file. For example setting
4096 it to /bin/true may be used to prevent rpmbuild to strip bina‐
4097 ries.
4098 CPACK_RPM_SPEC_MORE_DEFINE
4100 RPM extended spec definitions lines.
4101 · Mandatory : NO
4103 · Default : -
4105 May be used to add any %define lines to the generated spec file.
4107 CPACK_RPM_PACKAGE_DEBUG
4109 Toggle CPackRPM debug output.
4110 · Mandatory : NO
4112 · Default : -
4114 May be set when invoking cpack in order to trace debug informa‐
4116 tion during CPack RPM run. For example you may launch CPack like
4117 this:
4118 cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -G RPM
4120 CPACK_RPM_USER_BINARY_SPECFILE
4122 CPACK_RPM_<componentName>_USER_BINARY_SPECFILE
4124 A user provided spec file.
4125 · Mandatory : NO
4127 · Default : -
4129 May be set by the user in order to specify a USER binary spec
4131 file to be used by CPackRPM instead of generating the file. The
4132 specified file will be processed by configure_file( @ONLY).
4133 CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE
4135 Spec file template.
4136 · Mandatory : NO
4138 · Default : -
4140 If set CPack will generate a template for USER specified binary
4142 spec file and stop with an error. For example launch CPack like
4143 this:
4144 cpack -D CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE=1 -G RPM
4146 The user may then use this file in order to hand-craft is own
4148 binary spec file which may be used with
4149 CPACK_RPM_USER_BINARY_SPECFILE.
4150 CPACK_RPM_PRE_INSTALL_SCRIPT_FILE
4152 CPACK_RPM_PRE_UNINSTALL_SCRIPT_FILE
4154 Path to file containing pre (un)install script.
4155 · Mandatory : NO
4157 · Default : -
4159 May be used to embed a pre (un)installation script in the spec
4161 file. The referred script file (or both) will be read and
4162 directly put after the %pre or %preun section If
4163 CPACK_RPM_COMPONENT_INSTALL is set to ON the (un)install script
4164 for each component can be overridden with CPACK_RPM_<COMPO‐
4165 NENT>_PRE_INSTALL_SCRIPT_FILE and CPACK_RPM_<COMPO‐
4166 NENT>_PRE_UNINSTALL_SCRIPT_FILE. One may verify which scriptlet
4167 has been included with:
4168 rpm -qp --scripts package.rpm
4170 CPACK_RPM_POST_INSTALL_SCRIPT_FILE
4172 CPACK_RPM_POST_UNINSTALL_SCRIPT_FILE
4174 Path to file containing post (un)install script.
4175 · Mandatory : NO
4177 · Default : -
4179 May be used to embed a post (un)installation script in the spec
4181 file. The referred script file (or both) will be read and
4182 directly put after the %post or %postun section. If
4183 CPACK_RPM_COMPONENT_INSTALL is set to ON the (un)install script
4184 for each component can be overridden with CPACK_RPM_<COMPO‐
4185 NENT>_POST_INSTALL_SCRIPT_FILE and CPACK_RPM_<COMPO‐
4186 NENT>_POST_UNINSTALL_SCRIPT_FILE. One may verify which script‐
4187 let has been included with:
4188 rpm -qp --scripts package.rpm
4190 CPACK_RPM_USER_FILELIST
4192 CPACK_RPM_<COMPONENT>_USER_FILELIST
4194 · Mandatory : NO
4196 · Default : -
4198 May be used to explicitly specify %(<directive>) file line in
4200 the spec file. Like %config(noreplace) or any other directive
4201 that be found in the %files section. You can have multiple
4202 directives per line, as in %attr(600,root,root) %config(nore‐
4203 place). Since CPackRPM is generating the list of files (and
4204 directories) the user specified files of the CPACK_RPM_<COMPO‐
4205 NENT>_USER_FILELIST list will be removed from the generated
4206 list. If referring to directories do not add a trailing slash.
4207 CPACK_RPM_CHANGELOG_FILE
4209 RPM changelog file.
4210 · Mandatory : NO
4212 · Default : -
4214 May be used to embed a changelog in the spec file. The referred
4216 file will be read and directly put after the %changelog section.
4217 CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST
4219 list of path to be excluded.
4220 · Mandatory : NO
4222 ·
4224 Default
4226 /etc /etc/init.d /usr /usr/bin /usr/include /usr/lib
4227 /usr/libx32 /usr/lib64 /usr/share /usr/share/aclocal
4228 /usr/share/doc
4229 May be used to exclude path (directories or files) from the
4231 auto-generated list of paths discovered by CPack RPM. The
4232 default value contains a reasonable set of values if the vari‐
4233 able is not defined by the user. If the variable is defined by
4234 the user then CPackRPM will NOT any of the default path. If you
4235 want to add some path to the default list then you can use
4236 CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST_ADDITION variable.
4237 CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST_ADDITION
4239 additional list of path to be excluded.
4240 · Mandatory : NO
4242 · Default : -
4244 May be used to add more exclude path (directories or files) from
4246 the initial default list of excluded paths. See
4247 CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST.
4248 CPACK_RPM_RELOCATION_PATHS
4250 Packages relocation paths list.
4251 · Mandatory : NO
4253 · Default : -
4255 May be used to specify more than one relocation path per relo‐
4257 catable RPM. Variable contains a list of relocation paths that
4258 if relative are prefixed by the value of
4259 CPACK_RPM_<COMPONENT>_PACKAGE_PREFIX or by the value of
4260 CPACK_PACKAGING_INSTALL_PREFIX if the component version is not
4261 provided. Variable is not component based as its content can be
4262 used to set a different path prefix for e.g. binary dir and doc‐
4263 umentation dir at the same time. Only prefixes that are
4264 required by a certain component are added to that component -
4265 component must contain at least one file/directory/symbolic link
4266 with CPACK_RPM_RELOCATION_PATHS prefix for a certain relocation
4267 path to be added. Package will not contain any relocation paths
4268 if there are no files/directories/symbolic links on any of the
4269 provided prefix locations. Packages that either do not contain
4270 any relocation paths or contain files/directories/symbolic links
4271 that are outside relocation paths print out an AUTHOR_WARNING
4272 that RPM will be partially relocatable.
4273 CPACK_RPM_<COMPONENT>_PACKAGE_PREFIX
4275 Per component relocation path install prefix.
4276 · Mandatory : NO
4278 · Default : CPACK_PACKAGING_INSTALL_PREFIX
4280 May be used to set per component CPACK_PACKAGING_INSTALL_PREFIX
4282 for relocatable RPM packages.
4283 CPACK_RPM_NO_INSTALL_PREFIX_RELOCATION
4285 CPACK_RPM_NO_<COMPONENT>_INSTALL_PREFIX_RELOCATION
4287 Removal of default install prefix from relocation paths list.
4288 · Mandatory : NO
4290 ·
4292 Default
4294 CPACK_PACKAGING_INSTALL_PREFIX or CPACK_RPM_<COMPO‐
4295 NENT>_PACKAGE_PREFIX are treated as one of relocation
4296 paths
4297 May be used to remove CPACK_PACKAGING_INSTALL_PREFIX and
4299 CPACK_RPM_<COMPONENT>_PACKAGE_PREFIX from relocatable RPM prefix
4300 paths.
4301 CPACK_RPM_ADDITIONAL_MAN_DIRS
4303 · Mandatory : NO
4305 · Default : -
4307 May be used to set additional man dirs that could potentially be
4309 compressed by brp-compress RPM macro. Variable content must be a
4310 list of regular expressions that point to directories containing
4311 man files or to man files directly. Note that in order to com‐
4312 press man pages a path must also be present in brp-compress RPM
4313 script and that brp-compress script must be added to RPM config‐
4314 uration by the operating system.
4315 Regular expressions that are added by default were taken from
4317 brp-compress RPM macro:
4318 · /usr/man/man.*
4320 · /usr/man/.*/man.*
4322 · /usr/info.*
4324 · /usr/share/man/man.*
4326 · /usr/share/man/.*/man.*
4328 · /usr/share/info.*
4330 · /usr/kerberos/man.*
4332 · /usr/X11R6/man/man.*
4334 · /usr/lib/perl5/man/man.*
4336 · /usr/share/doc/.*/man/man.*
4338 · /usr/lib/.*/man/man.*
4340 CPACK_RPM_DEFAULT_USER
4342 CPACK_RPM_<compName>_DEFAULT_USER
4344 default user ownership of RPM content
4345 · Mandatory : NO
4347 · Default : root
4349 Value should be user name and not UID. Note that <compName>
4351 must be in upper-case.
4352 CPACK_RPM_DEFAULT_GROUP
4354 CPACK_RPM_<compName>_DEFAULT_GROUP
4356 default group ownership of RPM content
4357 · Mandatory : NO
4359 · Default : root
4361 Value should be group name and not GID. Note that <compName>
4363 must be in upper-case.
4364 CPACK_RPM_DEFAULT_FILE_PERMISSIONS
4366 CPACK_RPM_<compName>_DEFAULT_FILE_PERMISSIONS
4368 default permissions used for packaged files
4369 · Mandatory : NO
4371 · Default : - (system default)
4373 Accepted values are lists with PERMISSIONS. Valid permissions
4375 are:
4376 · OWNER_READ
4378 · OWNER_WRITE
4380 · OWNER_EXECUTE
4382 · GROUP_READ
4384 · GROUP_WRITE
4386 · GROUP_EXECUTE
4388 · WORLD_READ
4390 · WORLD_WRITE
4392 · WORLD_EXECUTE
4394 Note that <compName> must be in upper-case.
4396 CPACK_RPM_DEFAULT_DIR_PERMISSIONS
4398 CPACK_RPM_<compName>_DEFAULT_DIR_PERMISSIONS
4400 default permissions used for packaged directories
4401 · Mandatory : NO
4403 · Default : - (system default)
4405 Accepted values are lists with PERMISSIONS. Valid permissions
4407 are the same as for CPACK_RPM_DEFAULT_FILE_PERMISSIONS. Note
4408 that <compName> must be in upper-case.
4409 CPACK_RPM_INSTALL_WITH_EXEC
4411 force execute permissions on programs and shared libraries
4412 · Mandatory : NO
4414 · Default : - (system default)
4416 Force set owner, group and world execute permissions on programs
4418 and shared libraries. This can be used for creating valid rpm
4419 packages on systems such as Debian where shared libraries do not
4420 have execute permissions set.
4421 NOTE:
4423 Programs and shared libraries without execute permissions are
4424 ignored during separation of debug symbols from the binary for
4425 debuginfo packages.
4426 Packaging of Symbolic Links
4428 CPackRPM supports packaging of symbolic links:
4429 execute_process(COMMAND ${CMAKE_COMMAND}
4431 -E create_symlink <relative_path_location> <symlink_name>)
4432 install(FILES ${CMAKE_CURRENT_BINARY_DIR}/<symlink_name>
4433 DESTINATION <symlink_location> COMPONENT libraries)
4434 Symbolic links will be optimized (paths will be shortened if possible)
4436 before being added to the package or if multiple relocation paths are
4437 detected, a post install symlink relocation script will be generated.
4438 Symbolic links may point to locations that are not packaged by the same
4440 package (either a different component or even not packaged at all) but
4441 those locations will be treated as if they were a part of the package
4442 while determining if symlink should be either created or present in a
4443 post install script - depending on relocation paths.
4444 Symbolic links that point to locations outside packaging path produce a
4446 warning and are treated as non relocatable permanent symbolic links.
4447 Currently there are a few limitations though:
4449 · For component based packaging component interdependency is not
4451 checked when processing symbolic links. Symbolic links pointing to
4452 content of a different component are treated the same way as if
4453 pointing to location that will not be packaged.
4454 · Symbolic links pointing to a location through one or more intermedi‐
4456 ate symbolic links will not be handled differently - if the interme‐
4457 diate symbolic link(s) is also on a relocatable path, relocating it
4458 during package installation may cause initial symbolic link to point
4459 to an invalid location.
4460 Packaging of debug information
4462 Debuginfo packages contain debug symbols and sources for debugging
4463 packaged binaries.
4464 Debuginfo RPM packaging has it’s own set of variables:
4466 CPACK_RPM_DEBUGINFO_PACKAGE
4468 CPACK_RPM_<component>_DEBUGINFO_PACKAGE
4470 Enable generation of debuginfo RPM package(s).
4471 · Mandatory : NO
4473 · Default : OFF
4475 NOTE:
4477 Binaries must contain debug symbols before packaging so use either
4478 Debug or RelWithDebInfo for CMAKE_BUILD_TYPE variable value.
4479 NOTE:
4481 Packages generated from packages without binary files, with binary
4482 files but without execute permissions or without debug symbols will
4483 cause packaging termination.
4484 CPACK_BUILD_SOURCE_DIRS
4486 Provides locations of root directories of source files from
4487 which binaries were built.
4488 · Mandatory : YES if CPACK_RPM_DEBUGINFO_PACKAGE is set
4490 · Default : -
4492 NOTE:
4494 For CMake project CPACK_BUILD_SOURCE_DIRS is set by default to point
4495 to CMAKE_SOURCE_DIR and CMAKE_BINARY_DIR paths.
4496 NOTE:
4498 Sources with path prefixes that do not fall under any location pro‐
4499 vided with CPACK_BUILD_SOURCE_DIRS will not be present in debuginfo
4500 package.
4501 CPACK_RPM_BUILD_SOURCE_DIRS_PREFIX
4503 CPACK_RPM_<component>_BUILD_SOURCE_DIRS_PREFIX
4505 Prefix of location where sources will be placed during package
4506 installation.
4507 · Mandatory : YES if CPACK_RPM_DEBUGINFO_PACKAGE is set
4509 ·
4511 Default
4513 “/usr/src/debug/<CPACK_PACKAGE_FILE_NAME>” and for com‐
4514 ponent packaging “/usr/src/debug/<CPACK_PACK‐
4515 AGE_FILE_NAME>-<component>”
4516 NOTE:
4518 Each source path prefix is additionally suffixed by src_<index>
4519 where index is index of the path used from CPACK_BUILD_SOURCE_DIRS
4520 variable. This produces <CPACK_RPM_BUILD_SOURCE_DIRS_PRE‐
4521 FIX>/src_<index> replacement path. Limitation is that replaced path
4522 part must be shorter or of equal length than the length of its
4523 replacement. If that is not the case either
4524 CPACK_RPM_BUILD_SOURCE_DIRS_PREFIX variable has to be set to a
4525 shorter path or source directories must be placed on a longer path.
4526 CPACK_RPM_DEBUGINFO_EXCLUDE_DIRS
4528 Directories containing sources that should be excluded from
4529 debuginfo packages.
4530 · Mandatory : NO
4532 · Default : “/usr /usr/src /usr/src/debug”
4534 Listed paths are owned by other RPM packages and should there‐
4536 fore not be deleted on debuginfo package uninstallation.
4537 CPACK_RPM_DEBUGINFO_EXCLUDE_DIRS_ADDITION
4539 Paths that should be appended to
4540 CPACK_RPM_DEBUGINFO_EXCLUDE_DIRS for exclusion.
4541 · Mandatory : NO
4543 · Default : -
4545 CPACK_RPM_DEBUGINFO_SINGLE_PACKAGE
4547 Create a single debuginfo package even if components packaging
4548 is set.
4549 · Mandatory : NO
4551 · Default : OFF
4553 When this variable is enabled it produces a single debuginfo
4555 package even if component packaging is enabled.
4556 When using this feature in combination with components packaging
4558 and there is more than one component this variable requires
4559 CPACK_RPM_MAIN_COMPONENT to be set.
4560 NOTE:
4562 If none of the CPACK_RPM_<component>_DEBUGINFO_PACKAGE variables is
4563 set then CPACK_RPM_DEBUGINFO_PACKAGE is automatically set to ON when
4564 CPACK_RPM_DEBUGINFO_SINGLE_PACKAGE is set.
4565 CPACK_RPM_DEBUGINFO_FILE_NAME
4567 CPACK_RPM_<component>_DEBUGINFO_FILE_NAME
4569 Debuginfo package file name.
4570 · Mandatory : NO
4572 · Default : rpmbuild tool generated package file name
4574 Alternatively provided debuginfo package file name must end with
4576 .rpm suffix and should differ from file names of other generated
4577 packages.
4578 Variable may contain @cpack_component@ placeholder which will be
4580 replaced by component name if component packaging is enabled
4581 otherwise it deletes the placeholder.
4582 Setting the variable to RPM-DEFAULT may be used to explicitly
4584 set filename generation to default.
4585 NOTE:
4587 CPACK_RPM_FILE_NAME also supports rpmbuild tool generated package
4588 file name - disabled by default but can be enabled by setting the
4589 variable to RPM-DEFAULT.
4590 Packaging of sources (SRPM)
4592 SRPM packaging is enabled by setting CPACK_RPM_PACKAGE_SOURCES variable
4593 while usually using CPACK_INSTALLED_DIRECTORIES variable to provide
4594 directory containing CMakeLists.txt and source files.
4595 For CMake projects SRPM package would be product by executing:
4597 cpack -G RPM --config ./CPackSourceConfig.cmake
4599 NOTE:
4601 Produced SRPM package is expected to be built with cmake(1) exe‐
4602 cutable and packaged with cpack(1) executable so CMakeLists.txt has
4603 to be located in root source directory and must be able to generate
4604 binary rpm packages by executing cpack -G command. The two executa‐
4605 bles as well as rpmbuild must also be present when generating binary
4606 rpm packages from the produced SRPM package.
4607 Once the SRPM package is generated it can be used to generate binary
4609 packages by creating a directory structure for rpm generation and exe‐
4610 cuting rpmbuild tool:
4611 mkdir -p build_dir/{BUILD,BUILDROOT,RPMS,SOURCES,SPECS,SRPMS} rpmbuild
4613 --define "_topdir <path_to_build_dir>" --rebuild <SRPM_file_name>
4614 Generated packages will be located in build_dir/RPMS directory or its
4616 sub directories.
4617 NOTE:
4619 SRPM package internally uses CPack/RPM generator to generate binary
4620 packages so CMakeScripts.txt can decide during the SRPM to binary
4621 rpm generation step what content the package(s) should have as well
4622 as how they should be packaged (monolithic or components). CMake can
4623 decide this for e.g. by reading environment variables set by the
4624 package manager before starting the process of generating binary rpm
4625 packages. This way a single SRPM package can be used to produce dif‐
4626 ferent binary rpm packages on different platforms depending on the
4627 platform’s packaging rules.
4628 Source RPM packaging has it’s own set of variables:
4630 CPACK_RPM_PACKAGE_SOURCES
4632 Should the content be packaged as a source rpm (default is
4633 binary rpm).
4634 · Mandatory : NO
4636 · Default : OFF
4638 NOTE:
4640 For cmake projects CPACK_RPM_PACKAGE_SOURCES variable is set to OFF
4641 in CPackConfig.cmake and ON in CPackSourceConfig.cmake generated
4642 files.
4643 CPACK_RPM_SOURCE_PKG_BUILD_PARAMS
4645 Additional command-line parameters provided to cmake(1) exe‐
4646 cutable.
4647 · Mandatory : NO
4649 · Default : -
4651 CPACK_RPM_SOURCE_PKG_PACKAGING_INSTALL_PREFIX
4653 Packaging install prefix that would be provided in CPACK_PACKAG‐
4654 ING_INSTALL_PREFIX variable for producing binary RPM packages.
4655 · Mandatory : YES
4657 · Default : “/”
4659 CPACK_RPM_BUILDREQUIRES
4661 List of source rpm build dependencies.
4662 · Mandatory : NO
4664 · Default : -
4666 May be used to set source RPM build dependencies (Buil‐
4668 dRequires). Note that you must enclose the complete build
4669 requirements string between quotes, for example:
4670 set(CPACK_RPM_BUILDREQUIRES "python >= 2.5.0, cmake >= 2.8")
4672 CPack
4674 Build binary and source package installers.
4675 Variables common to all CPack generators
4677 The CPack module generates binary and source installers in a variety of
4678 formats using the cpack program. Inclusion of the CPack module adds
4679 two new targets to the resulting makefiles, package and package_source,
4680 which build the binary and source installers, respectively. The gener‐
4681 ated binary installers contain everything installed via CMake’s INSTALL
4682 command (and the deprecated INSTALL_FILES, INSTALL_PROGRAMS, and
4683 INSTALL_TARGETS commands).
4684 For certain kinds of binary installers (including the graphical in‐
4686 stallers on Mac OS X and Windows), CPack generates installers that
4687 allow users to select individual application components to install.
4688 See CPackComponent module for that.
4689 The CPACK_GENERATOR variable has different meanings in different con‐
4691 texts. In your CMakeLists.txt file, CPACK_GENERATOR is a list of gen‐
4692 erators: when run with no other arguments, CPack will iterate over that
4693 list and produce one package for each generator. In a
4694 CPACK_PROJECT_CONFIG_FILE, though, CPACK_GENERATOR is a string naming a
4695 single generator. If you need per-cpack- generator logic to control
4696 other cpack settings, then you need a CPACK_PROJECT_CONFIG_FILE.
4697 The CMake source tree itself contains a CPACK_PROJECT_CONFIG_FILE. See
4699 the top level file CMakeCPackOptions.cmake.in for an example.
4700 If set, the CPACK_PROJECT_CONFIG_FILE is included automatically on a
4702 per-generator basis. It only need contain overrides.
4703 Here’s how it works:
4705 · cpack runs
4707 · it includes CPackConfig.cmake
4709 · it iterates over the generators listed in that file’s CPACK_GENERATOR
4711 list variable (unless told to use just a specific one via -G on the
4712 command line…)
4713 · foreach generator, it then
4715 · sets CPACK_GENERATOR to the one currently being iterated
4717 · includes the CPACK_PROJECT_CONFIG_FILE
4719 · produces the package for that generator
4721 This is the key: For each generator listed in CPACK_GENERATOR in CPack‐
4723 Config.cmake, cpack will reset CPACK_GENERATOR internally to the one
4724 currently being used and then include the CPACK_PROJECT_CONFIG_FILE.
4725 Before including this CPack module in your CMakeLists.txt file, there
4727 are a variety of variables that can be set to customize the resulting
4728 installers. The most commonly-used variables are:
4729 CPACK_PACKAGE_NAME
4731 The name of the package (or application). If not specified,
4732 defaults to the project name.
4733 CPACK_PACKAGE_VENDOR
4735 The name of the package vendor. (e.g., “Kitware”). Default is
4736 “Humanity”.
4737 CPACK_PACKAGE_DIRECTORY
4739 The directory in which CPack is doing its packaging. If it is
4740 not set then this will default (internally) to the build dir.
4741 This variable may be defined in CPack config file or from the
4742 cpack command line option “-B”. If set the command line option
4743 override the value found in the config file.
4744 CPACK_PACKAGE_VERSION_MAJOR
4746 Package major Version. Default value is 0.
4747 CPACK_PACKAGE_VERSION_MINOR
4749 Package minor Version. Default value is 1.
4750 CPACK_PACKAGE_VERSION_PATCH
4752 Package patch Version. Default value is 1.
4753 CPACK_PACKAGE_DESCRIPTION_FILE
4755 A text file used to describe the project. Used, for example, the
4756 introduction screen of a CPack-generated Windows installer to
4757 describe the project.
4758 CPACK_PACKAGE_DESCRIPTION_SUMMARY
4760 Short description of the project (only a few words). Default
4761 value is:
4762 ${PROJECT_DESCRIPTION}
4764 if DESCRIPTION has given to the project() call or CMake gener‐
4766 ated string with PROJECT_NAME otherwise.
4767 CPACK_PACKAGE_FILE_NAME
4769 The name of the package file to generate, not including the
4770 extension. For example, cmake-2.6.1-Linux-i686. The default
4771 value is:
4772 ${CPACK_PACKAGE_NAME}-${CPACK_PACKAGE_VERSION}-${CPACK_SYSTEM_NAME}.
4774 CPACK_PACKAGE_INSTALL_DIRECTORY
4776 Installation directory on the target system. This may be used by
4777 some CPack generators like NSIS to create an installation direc‐
4778 tory e.g., “CMake 2.5” below the installation prefix. All
4779 installed element will be put inside this directory.
4780 CPACK_PACKAGE_ICON
4782 A branding image that will be displayed inside the installer
4783 (used by GUI installers).
4784 CPACK_PACKAGE_CHECKSUM
4786 An algorithm that will be used to generate additional file with
4787 checksum of the package. Output file name will be:
4788 ${CPACK_PACKAGE_FILE_NAME}.${CPACK_PACKAGE_CHECKSUM}
4790 Supported algorithms are those listed by the string(<HASH>) com‐
4792 mand.
4793 CPACK_PROJECT_CONFIG_FILE
4795 CPack-time project CPack configuration file. This file included
4796 at cpack time, once per generator after CPack has set CPACK_GEN‐
4797 ERATOR to the actual generator being used. It allows per-genera‐
4798 tor setting of CPACK_* variables at cpack time.
4799 CPACK_RESOURCE_FILE_LICENSE
4801 License to be embedded in the installer. It will typically be
4802 displayed to the user by the produced installer (often with an
4803 explicit “Accept” button, for graphical installers) prior to
4804 installation. This license file is NOT added to installed file
4805 but is used by some CPack generators like NSIS. If you want to
4806 install a license file (may be the same as this one) along with
4807 your project you must add an appropriate CMake INSTALL command
4808 in your CMakeLists.txt.
4809 CPACK_RESOURCE_FILE_README
4811 ReadMe file to be embedded in the installer. It typically
4812 describes in some detail the purpose of the project during the
4813 installation. Not all CPack generators uses this file.
4814 CPACK_RESOURCE_FILE_WELCOME
4816 Welcome file to be embedded in the installer. It welcomes users
4817 to this installer. Typically used in the graphical installers
4818 on Windows and Mac OS X.
4819 CPACK_MONOLITHIC_INSTALL
4821 Disables the component-based installation mechanism. When set
4822 the component specification is ignored and all installed items
4823 are put in a single “MONOLITHIC” package. Some CPack generators
4824 do monolithic packaging by default and may be asked to do compo‐
4825 nent packaging by setting CPACK_<GENNAME>_COMPONENT_INSTALL to
4826 1/TRUE.
4827 CPACK_GENERATOR
4829 List of CPack generators to use. If not specified, CPack will
4830 create a set of options CPACK_BINARY_<GENNAME> (e.g.,
4831 CPACK_BINARY_NSIS) allowing the user to enable/disable individ‐
4832 ual generators. This variable may be used on the command line as
4833 well as in:
4834 cpack -D CPACK_GENERATOR="ZIP;TGZ" /path/to/build/tree
4836 CPACK_OUTPUT_CONFIG_FILE
4838 The name of the CPack binary configuration file. This file is
4839 the CPack configuration generated by the CPack module for binary
4840 installers. Defaults to CPackConfig.cmake.
4841 CPACK_PACKAGE_EXECUTABLES
4843 Lists each of the executables and associated text label to be
4844 used to create Start Menu shortcuts. For example, setting this
4845 to the list ccmake;CMake will create a shortcut named “CMake”
4846 that will execute the installed executable ccmake. Not all CPack
4847 generators use it (at least NSIS, WIX and OSXX11 do).
4848 CPACK_STRIP_FILES
4850 List of files to be stripped. Starting with CMake 2.6.0
4851 CPACK_STRIP_FILES will be a boolean variable which enables
4852 stripping of all files (a list of files evaluates to TRUE in
4853 CMake, so this change is compatible).
4854 CPACK_VERBATIM_VARIABLES
4856 If set to TRUE, values of variables prefixed with CPACK will be
4857 escaped before being written to the configuration files, so that
4858 the cpack program receives them exactly as they were specified.
4859 If not, characters like quotes and backslashes can cause parsing
4860 errors or alter the value received by the cpack program.
4861 Defaults to FALSE for backwards compatibility.
4862 · Mandatory : NO
4864 · Default : FALSE
4866 The following CPack variables are specific to source packages, and will
4868 not affect binary packages:
4869 CPACK_SOURCE_PACKAGE_FILE_NAME
4871 The name of the source package. For example cmake-2.6.1.
4872 CPACK_SOURCE_STRIP_FILES
4874 List of files in the source tree that will be stripped. Starting
4875 with CMake 2.6.0 CPACK_SOURCE_STRIP_FILES will be a boolean
4876 variable which enables stripping of all files (a list of files
4877 evaluates to TRUE in CMake, so this change is compatible).
4878 CPACK_SOURCE_GENERATOR
4880 List of generators used for the source packages. As with
4881 CPACK_GENERATOR, if this is not specified then CPack will create
4882 a set of options (e.g., CPACK_SOURCE_ZIP) allowing users to
4883 select which packages will be generated.
4884 CPACK_SOURCE_OUTPUT_CONFIG_FILE
4886 The name of the CPack source configuration file. This file is
4887 the CPack configuration generated by the CPack module for source
4888 installers. Defaults to CPackSourceConfig.cmake.
4889 CPACK_SOURCE_IGNORE_FILES
4891 Pattern of files in the source tree that won’t be packaged when
4892 building a source package. This is a list of regular expression
4893 patterns (that must be properly escaped), e.g.,
4894 /CVS/;/.svn/;.swp$;.#;/#;.*~;cscope.*
4895 The following variables are for advanced uses of CPack:
4897 CPACK_CMAKE_GENERATOR
4899 What CMake generator should be used if the project is CMake
4900 project. Defaults to the value of CMAKE_GENERATOR few users will
4901 want to change this setting.
4902 CPACK_INSTALL_CMAKE_PROJECTS
4904 List of four values that specify what project to install. The
4905 four values are: Build directory, Project Name, Project Compo‐
4906 nent, Directory. If omitted, CPack will build an installer that
4907 installs everything.
4908 CPACK_SYSTEM_NAME
4910 System name, defaults to the value of ${CMAKE_SYSTEM_NAME},
4911 except on Windows where it will be “win32” or “win64”.
4912 CPACK_PACKAGE_VERSION
4914 Package full version, used internally. By default, this is built
4915 from CPACK_PACKAGE_VERSION_MAJOR, CPACK_PACKAGE_VERSION_MINOR,
4916 and CPACK_PACKAGE_VERSION_PATCH.
4917 CPACK_TOPLEVEL_TAG
4919 Directory for the installed files.
4920 CPACK_INSTALL_COMMANDS
4922 Extra commands to install components.
4923 CPACK_INSTALLED_DIRECTORIES
4925 Extra directories to install.
4926 CPACK_PACKAGE_INSTALL_REGISTRY_KEY
4928 Registry key used when installing this project. This is only
4929 used by installer for Windows. The default value is based on
4930 the installation directory.
4931 CPACK_CREATE_DESKTOP_LINKS
4933 List of desktop links to create. Each desktop link requires a
4934 corresponding start menu shortcut as created by
4935 CPACK_PACKAGE_EXECUTABLES.
4936 CPACK_BINARY_<GENNAME>
4938 CPack generated options for binary generators. The CPack.cmake
4939 module generates (when CPACK_GENERATOR is not set) a set of
4940 CMake options (see CMake option command) which may then be used
4941 to select the CPack generator(s) to be used when launching the
4942 package target.
4943 Provide options to choose generators we might check here if the
4945 required tools for the generates exist and set the defaults
4946 according to the results
4947 CPackWIX
4949 CPack WiX generator specific options
4950 Variables specific to CPack WiX generator
4952 The following variables are specific to the installers built on Windows
4953 using WiX.
4954 CPACK_WIX_UPGRADE_GUID
4956 Upgrade GUID (Product/@UpgradeCode)
4957 Will be automatically generated unless explicitly provided.
4959 It should be explicitly set to a constant generated globally
4961 unique identifier (GUID) to allow your installers to replace
4962 existing installations that use the same GUID.
4963 You may for example explicitly set this variable in your CMake‐
4965 Lists.txt to the value that has been generated per default. You
4966 should not use GUIDs that you did not generate yourself or which
4967 may belong to other projects.
4968 A GUID shall have the following fixed length syntax:
4970 XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
4972 (each X represents an uppercase hexadecimal digit)
4974 CPACK_WIX_PRODUCT_GUID
4976 Product GUID (Product/@Id)
4977 Will be automatically generated unless explicitly provided.
4979 If explicitly provided this will set the Product Id of your in‐
4981 staller.
4982 The installer will abort if it detects a pre-existing installa‐
4984 tion that uses the same GUID.
4985 The GUID shall use the syntax described for
4987 CPACK_WIX_UPGRADE_GUID.
4988 CPACK_WIX_LICENSE_RTF
4990 RTF License File
4991 If CPACK_RESOURCE_FILE_LICENSE has an .rtf extension it is used
4993 as-is.
4994 If CPACK_RESOURCE_FILE_LICENSE has an .txt extension it is
4996 implicitly converted to RTF by the WiX Generator. The expected
4997 encoding of the .txt file is UTF-8.
4998 With CPACK_WIX_LICENSE_RTF you can override the license file
5000 used by the WiX Generator in case CPACK_RESOURCE_FILE_LICENSE is
5001 in an unsupported format or the .txt -> .rtf conversion does not
5002 work as expected.
5003 CPACK_WIX_PRODUCT_ICON
5005 The Icon shown next to the program name in Add/Remove programs.
5006 If set, this icon is used in place of the default icon.
5008 CPACK_WIX_UI_REF
5010 This variable allows you to override the Id of the <UIRef> ele‐
5011 ment in the WiX template.
5012 The default is WixUI_InstallDir in case no CPack components have
5014 been defined and WixUI_FeatureTree otherwise.
5015 CPACK_WIX_UI_BANNER
5017 The bitmap will appear at the top of all installer pages other
5018 than the welcome and completion dialogs.
5019 If set, this image will replace the default banner image.
5021 This image must be 493 by 58 pixels.
5023 CPACK_WIX_UI_DIALOG
5025 Background bitmap used on the welcome and completion dialogs.
5026 If this variable is set, the installer will replace the default
5028 dialog image.
5029 This image must be 493 by 312 pixels.
5031 CPACK_WIX_PROGRAM_MENU_FOLDER
5033 Start menu folder name for launcher.
5034 If this variable is not set, it will be initialized with
5036 CPACK_PACKAGE_NAME
5037 CPACK_WIX_CULTURES
5039 Language(s) of the installer
5040 Languages are compiled into the WixUI extension library. To use
5042 them, simply provide the name of the culture. If you specify
5043 more than one culture identifier in a comma or semicolon delim‐
5044 ited list, the first one that is found will be used. You can
5045 find a list of supported languages at:
5046 http://wix.sourceforge.net/manual-wix3/WixUI_localization.htm
5047 CPACK_WIX_TEMPLATE
5049 Template file for WiX generation
5050 If this variable is set, the specified template will be used to
5052 generate the WiX wxs file. This should be used if further cus‐
5053 tomization of the output is required.
5054 If this variable is not set, the default MSI template included
5056 with CMake will be used.
5057 CPACK_WIX_PATCH_FILE
5059 Optional list of XML files with fragments to be inserted into
5060 generated WiX sources
5061 This optional variable can be used to specify an XML file that
5063 the WiX generator will use to inject fragments into its gener‐
5064 ated source files.
5065 Patch files understood by the CPack WiX generator roughly follow
5067 this RELAX NG compact schema:
5068 start = CPackWiXPatch
5070 CPackWiXPatch = element CPackWiXPatch { CPackWiXFragment* }
5072 CPackWiXFragment = element CPackWiXFragment
5074 {
5075 attribute Id { string },
5076 fragmentContent*
5077 }
5078 fragmentContent = element * - CPackWiXFragment
5080 {
5081 (attribute * { text } | text | fragmentContent)*
5082 }
5083 Currently fragments can be injected into most Component, File,
5085 Directory and Feature elements.
5086 The following additional special Ids can be used:
5088 · #PRODUCT for the <Product> element.
5090 · #PRODUCTFEATURE for the root <Feature> element.
5092 The following example illustrates how this works.
5094 Given that the WiX generator creates the following XML element:
5096 <Component Id="CM_CP_applications.bin.my_libapp.exe" Guid="*"/>
5098 The following XML patch file may be used to inject an Environ‐
5100 ment element into it:
5101 <CPackWiXPatch>
5103 <CPackWiXFragment Id="CM_CP_applications.bin.my_libapp.exe">
5104 <Environment Id="MyEnvironment" Action="set"
5105 Name="MyVariableName" Value="MyVariableValue"/>
5106 </CPackWiXFragment>
5107 </CPackWiXPatch>
5108 CPACK_WIX_EXTRA_SOURCES
5110 Extra WiX source files
5111 This variable provides an optional list of extra WiX source
5113 files (.wxs) that should be compiled and linked. The full path
5114 to source files is required.
5115 CPACK_WIX_EXTRA_OBJECTS
5117 Extra WiX object files or libraries
5118 This variable provides an optional list of extra WiX object
5120 (.wixobj) and/or WiX library (.wixlib) files. The full path to
5121 objects and libraries is required.
5122 CPACK_WIX_EXTENSIONS
5124 This variable provides a list of additional extensions for the
5125 WiX tools light and candle.
5126 CPACK_WIX_<TOOL>_EXTENSIONS
5128 This is the tool specific version of CPACK_WIX_EXTENSIONS.
5129 <TOOL> can be either LIGHT or CANDLE.
5130 CPACK_WIX_<TOOL>_EXTRA_FLAGS
5132 This list variable allows you to pass additional flags to the
5133 WiX tool <TOOL>.
5134 Use it at your own risk. Future versions of CPack may generate
5136 flags which may be in conflict with your own flags.
5137 <TOOL> can be either LIGHT or CANDLE.
5139 CPACK_WIX_CMAKE_PACKAGE_REGISTRY
5141 If this variable is set the generated installer will create an
5142 entry in the windows registry key HKEY_LOCAL_MACHINE\Soft‐
5143 ware\Kitware\CMake\Packages\<package> The value for <package> is
5144 provided by this variable.
5145 Assuming you also install a CMake configuration file this will
5147 allow other CMake projects to find your package with the
5148 find_package() command.
5149 CPACK_WIX_PROPERTY_<PROPERTY>
5151 This variable can be used to provide a value for the Windows In‐
5152 staller property <PROPERTY>
5153 The following list contains some example properties that can be
5155 used to customize information under “Programs and Features”
5156 (also known as “Add or Remove Programs”)
5157 · ARPCOMMENTS - Comments
5159 · ARPHELPLINK - Help and support information URL
5161 · ARPURLINFOABOUT - General information URL
5163 · ARPURLUPDATEINFO - Update information URL
5165 · ARPHELPTELEPHONE - Help and support telephone number
5167 · ARPSIZE - Size (in kilobytes) of the application
5169 CPACK_WIX_ROOT_FEATURE_TITLE
5171 Sets the name of the root install feature in the WIX installer.
5172 Same as CPACK_COMPONENT_<compName>_DISPLAY_NAME for components.
5173 CPACK_WIX_ROOT_FEATURE_DESCRIPTION
5175 Sets the description of the root install feature in the WIX in‐
5176 staller. Same as CPACK_COMPONENT_<compName>_DESCRIPTION for com‐
5177 ponents.
5178 CPACK_WIX_SKIP_PROGRAM_FOLDER
5180 If this variable is set to true, the default install location of
5181 the generated package will be CPACK_PACKAGE_INSTALL_DIRECTORY
5182 directly. The install location will not be located relatively
5183 below ProgramFiles or ProgramFiles64.
5184 NOTE:
5186 Installers created with this feature do not take differ‐
5187 ences between the system on which the installer is cre‐
5188 ated and the system on which the installer might be used
5189 into account.
5190 It is therefore possible that the installer e.g. might
5192 try to install onto a drive that is unavailable or unin‐
5193 tended or a path that does not follow the localization or
5194 convention of the system on which the installation is
5195 performed.
5196 CPACK_WIX_ROOT_FOLDER_ID
5198 This variable allows specification of a custom root folder ID.
5199 The generator specific <64> token can be used for folder IDs
5200 that come in 32-bit and 64-bit variants. In 32-bit builds the
5201 token will expand empty while in 64-bit builds it will expand to
5202 64.
5203 When unset generated installers will default installing to Pro‐
5205 gramFiles<64>Folder.
5206 CPACK_WIX_ROOT
5208 This variable can optionally be set to the root directory of a
5209 custom WiX Toolset installation.
5210 When unspecified CPack will try to locate a WiX Toolset instal‐
5212 lation via the WIX environment variable instead.
5213 CSharpUtilities
5215 Functions to make configuration of CSharp/.NET targets easier.
5216 A collection of CMake utility functions useful for dealing with CSharp
5218 targets for Visual Studio generators from version 2010 and later.
5219 The following functions are provided by this module:
5221 Main functions
5223 · csharp_set_windows_forms_properties()
5225 · csharp_set_designer_cs_properties()
5227 · csharp_set_xaml_cs_properties()
5229 Helper functions
5231 · csharp_get_filename_keys()
5233 · csharp_get_filename_key_base()
5235 · csharp_get_dependentupon_name()
5237 Main functions provided by the module
5239 csharp_set_windows_forms_properties
5240 Sets source file properties for use of Windows Forms. Use this,
5241 if your CSharp target uses Windows Forms:
5242 csharp_set_windows_forms_properties([<file1> [<file2> [...]]])
5244 <fileN>
5246 List of all source files which are relevant for setting
5247 the VS_CSHARP_<tagname> properties (including .cs, .resx
5248 and .Designer.cs extensions).
5249 In the list of all given files for all files ending with
5251 .Designer.cs and .resx is searched. For every designer or
5252 resource file a file with the same base name but only .cs as
5253 extension is searched. If this is found, the VS_CSHARP_<tag‐
5254 name> properties are set as follows:
5255 for the .cs file:
5257 · VS_CSHARP_SubType “Form”
5259 for the .Designer.cs file (if it exists):
5261 · VS_CSHARP_DependentUpon <cs-filename>
5263 · VS_CSHARP_DesignTime “” (delete tag if previously
5265 defined)
5266 · VS_CSHARP_AutoGen “”(delete tag if previously defined)
5268 for the .resx file (if it exists):
5270 · VS_RESOURCE_GENERATOR “” (delete tag if previously
5272 defined)
5273 · VS_CSHARP_DependentUpon <cs-filename>
5275 · VS_CSHARP_SubType “Designer”
5277 csharp_set_designer_cs_properties
5279 Sets source file properties of .Designer.cs files depending on
5280 sibling filenames. Use this, if your CSharp target does not use
5281 Windows Forms (for Windows Forms use
5282 csharp_set_designer_cs_properties() instead):
5283 csharp_set_designer_cs_properties([<file1> [<file2> [...]]])
5285 <fileN>
5287 List of all source files which are relevant for setting
5288 the VS_CSHARP_<tagname> properties (including .cs, .resx,
5289 .settings and .Designer.cs extensions).
5290 In the list of all given files for all files ending with
5292 .Designer.cs is searched. For every designer file all files with
5293 the same base name but different extensions are searched. If a
5294 match is found, the source file properties of the designer file
5295 are set depending on the extension of the matched file:
5296 if match is .resx file:
5298 · VS_CSHARP_AutoGen “True”
5300 · VS_CSHARP_DesignTime “True”
5302 · VS_CSHARP_DependentUpon <resx-filename>
5304 if match is .cs file:
5306 · VS_CSHARP_DependentUpon <cs-filename>
5308 if match is .settings file:
5310 · VS_CSHARP_AutoGen “True”
5312 · VS_CSHARP_DesignTimeSharedInput “True”
5314 · VS_CSHARP_DependentUpon <settings-filename>
5316 NOTE:
5318 Because the source file properties of the .Designer.cs file are set
5319 according to the found matches and every match sets the
5320 VS_CSHARP_DependentUpon property, there should only be one match for
5321 each Designer.cs file.
5322 csharp_set_xaml_cs_properties
5324 Sets source file properties for use of Windows Presentation
5325 Foundation (WPF) and XAML. Use this, if your CSharp target uses
5326 WPF/XAML:
5327 csharp_set_xaml_cs_properties([<file1> [<file2> [...]]])
5329 <fileN>
5331 List of all source files which are relevant for setting
5332 the VS_CSHARP_<tagname> properties (including .cs, .xaml,
5333 and .xaml.cs extensions).
5334 In the list of all given files for all files ending with
5336 .xaml.cs is searched. For every xaml-cs file, a file with the
5337 same base name but extension .xaml is searched. If a match is
5338 found, the source file properties of the .xaml.cs file are set:
5339 · VS_CSHARP_DependentUpon <xaml-filename>
5341 Helper functions which are used by the above ones
5343 csharp_get_filename_keys
5344 Helper function which computes a list of key values to identify
5345 source files independently of relative/absolute paths given in
5346 cmake and eliminates case sensitivity:
5347 csharp_get_filename_keys(OUT [<file1> [<file2> [...]]])
5349 OUT Name of the variable in which the list of keys is stored
5351 <fileN>
5353 filename(s) as given to to CSharp target using
5354 add_library() or add_executable()
5355 In some way the function applies a canonicalization to the
5357 source names. This is necessary to find file matches if the
5358 files have been added to the target with different directory
5359 prefixes:
5360 add_library(lib
5362 myfile.cs
5363 ${CMAKE_CURRENT_SOURCE_DIR}/myfile.Designer.cs)
5364 set_source_files_properties(myfile.Designer.cs PROPERTIES
5366 VS_CSHARP_DependentUpon myfile.cs)
5367 # this will fail, because in cmake
5369 # - ${CMAKE_CURRENT_SOURCE_DIR}/myfile.Designer.cs
5370 # - myfile.Designer.cs
5371 # are not the same source file. The source file property is not set.
5372 csharp_get_filename_key_base
5374 Returns the full filepath and name without extension of a key.
5375 KEY is expected to be a key from csharp_get_filename_keys. In
5376 BASE the value of KEY without the file extension is returned:
5377 csharp_get_filename_key_base(BASE KEY)
5379 BASE Name of the variable with the computed “base” of KEY.
5381 KEY The key of which the base will be computed. Expected to
5383 be a upper case full filename.
5384 csharp_get_dependentupon_name
5386 Computes a string which can be used as value for the source file
5387 property VS_CSHARP_<tagname> with target being DependentUpon:
5388 csharp_get_dependentupon_name(NAME FILE)
5390 NAME Name of the variable with the result value
5392 FILE Filename to convert to <DependentUpon> value
5394 Actually this is only the filename without any path given at the
5396 moment.
5397 CTest
5399 Configure a project for testing with CTest/CDash
5400 Include this module in the top CMakeLists.txt file of a project to
5402 enable testing with CTest and dashboard submissions to CDash:
5403 project(MyProject)
5405 ...
5406 include(CTest)
5407 The module automatically creates a BUILD_TESTING option that selects
5409 whether to enable testing support (ON by default). After including the
5410 module, use code like:
5411 if(BUILD_TESTING)
5413 # ... CMake code to create tests ...
5414 endif()
5415 to creating tests when testing is enabled.
5417 To enable submissions to a CDash server, create a CTestConfig.cmake
5419 file at the top of the project with content such as:
5420 set(CTEST_PROJECT_NAME "MyProject")
5422 set(CTEST_NIGHTLY_START_TIME "01:00:00 UTC")
5423 set(CTEST_DROP_METHOD "http")
5424 set(CTEST_DROP_SITE "my.cdash.org")
5425 set(CTEST_DROP_LOCATION "/submit.php?project=MyProject")
5426 set(CTEST_DROP_SITE_CDASH TRUE)
5427 (the CDash server can provide the file to a project administrator who
5429 configures MyProject). Settings in the config file are shared by both
5430 this CTest module and the ctest(1) command-line Dashboard Client mode
5431 (ctest -S).
5432 While building a project for submission to CDash, CTest scans the build
5434 output for errors and warnings and reports them with surrounding con‐
5435 text from the build log. This generic approach works for all build
5436 tools, but does not give details about the command invocation that pro‐
5437 duced a given problem. One may get more detailed reports by setting
5438 the CTEST_USE_LAUNCHERS variable:
5439 set(CTEST_USE_LAUNCHERS 1)
5441 in the CTestConfig.cmake file.
5443 CTestCoverageCollectGCOV
5445 This module provides the ctest_coverage_collect_gcov function.
5446 This function runs gcov on all .gcda files found in the binary tree and
5448 packages the resulting .gcov files into a tar file. This tarball also
5449 contains the following:
5450 · data.json defines the source and build directories for use by CDash.
5452 · Labels.json indicates any LABELS that have been set on the source
5454 files.
5455 · The uncovered directory holds any uncovered files found by
5457 CTEST_EXTRA_COVERAGE_GLOB.
5458 After generating this tar file, it can be sent to CDash for display
5460 with the ctest_submit(CDASH_UPLOAD) command.
5461 cdash_coverage_collect_gcov
5463 ctest_coverage_collect_gcov(TARBALL <tarfile>
5465 [SOURCE <source_dir>][BUILD <build_dir>]
5466 [GCOV_COMMAND <gcov_command>]
5467 [GCOV_OPTIONS <options>...]
5468 )
5469 Run gcov and package a tar file for CDash. The options are:
5471 TARBALL <tarfile>
5473 Specify the location of the .tar file to be created for
5474 later upload to CDash. Relative paths will be inter‐
5475 preted with respect to the top-level build directory.
5476 SOURCE <source_dir>
5478 Specify the top-level source directory for the build.
5479 Default is the value of CTEST_SOURCE_DIRECTORY.
5480 BUILD <build_dir>
5482 Specify the top-level build directory for the build.
5483 Default is the value of CTEST_BINARY_DIRECTORY.
5484 GCOV_COMMAND <gcov_command>
5486 Specify the full path to the gcov command on the machine.
5487 Default is the value of CTEST_COVERAGE_COMMAND.
5488 GCOV_OPTIONS <options>...
5490 Specify options to be passed to gcov. The gcov command
5491 is run as gcov <options>... -o <gcov-dir> <file>.gcda.
5492 If not specified, the default option is just -b.
5493 GLOB Recursively search for .gcda files in build_dir rather
5495 than determining search locations by reading TargetDirec‐
5496 tories.txt.
5497 DELETE Delete coverage files after they’ve been packaged into
5499 the .tar.
5500 QUIET Suppress non-error messages that otherwise would have
5502 been printed out by this function.
5503 CTestScriptMode
5505 This file is read by ctest in script mode (-S)
5506 CTestUseLaunchers
5508 Set the RULE_LAUNCH_* global properties when CTEST_USE_LAUNCHERS is on.
5509 CTestUseLaunchers is automatically included when you include(CTest).
5511 However, it is split out into its own module file so projects can use
5512 the CTEST_USE_LAUNCHERS functionality independently.
5513 To use launchers, set CTEST_USE_LAUNCHERS to ON in a ctest -S dashboard
5515 script, and then also set it in the cache of the configured project.
5516 Both cmake and ctest need to know the value of it for the launchers to
5517 work properly. CMake needs to know in order to generate proper build
5518 rules, and ctest, in order to produce the proper error and warning
5519 analysis.
5520 For convenience, you may set the ENV variable CTEST_USE_LAUNCH‐
5522 ERS_DEFAULT in your ctest -S script, too. Then, as long as your CMake‐
5523 Lists uses include(CTest) or include(CTestUseLaunchers), it will use
5524 the value of the ENV variable to initialize a CTEST_USE_LAUNCHERS cache
5525 variable. This cache variable initialization only occurs if
5526 CTEST_USE_LAUNCHERS is not already defined. If CTEST_USE_LAUNCHERS is
5527 on in a ctest -S script the ctest_configure command will add
5528 -DCTEST_USE_LAUNCHERS:BOOL=TRUE to the cmake command used to configure
5529 the project.
5530 Dart
5532 Configure a project for testing with CTest or old Dart Tcl Client
5533 This file is the backwards-compatibility version of the CTest module.
5535 It supports using the old Dart 1 Tcl client for driving dashboard sub‐
5536 missions as well as testing with CTest. This module should be included
5537 in the CMakeLists.txt file at the top of a project. Typical usage:
5538 include(Dart)
5540 if(BUILD_TESTING)
5541 # ... testing related CMake code ...
5542 endif()
5543 The BUILD_TESTING option is created by the Dart module to determine
5545 whether testing support should be enabled. The default is ON.
5546 DeployQt4
5548 Functions to help assemble a standalone Qt4 executable.
5549 A collection of CMake utility functions useful for deploying Qt4 exe‐
5551 cutables.
5552 The following functions are provided by this module:
5554 write_qt4_conf
5556 resolve_qt4_paths
5557 fixup_qt4_executable
5558 install_qt4_plugin_path
5559 install_qt4_plugin
5560 install_qt4_executable
5561 Requires CMake 2.6 or greater because it uses function and PAR‐
5563 ENT_SCOPE. Also depends on BundleUtilities.cmake.
5564 WRITE_QT4_CONF(<qt_conf_dir> <qt_conf_contents>)
5566 Writes a qt.conf file with the <qt_conf_contents> into <qt_conf_dir>.
5568 RESOLVE_QT4_PATHS(<paths_var> [<executable_path>])
5570 Loop through <paths_var> list and if any don’t exist resolve them rela‐
5572 tive to the <executable_path> (if supplied) or the CMAKE_INSTALL_PRE‐
5573 FIX.
5574 FIXUP_QT4_EXECUTABLE(<executable>
5576 [<qtplugins> <libs> <dirs> <plugins_dir> <request_qt_conf>])
5577 Copies Qt plugins, writes a Qt configuration file (if needed) and fixes
5579 up a Qt4 executable using BundleUtilities so it is standalone and can
5580 be drag-and-drop copied to another machine as long as all of the system
5581 libraries are compatible.
5582 <executable> should point to the executable to be fixed-up.
5584 <qtplugins> should contain a list of the names or paths of any Qt plug‐
5586 ins to be installed.
5587 <libs> will be passed to BundleUtilities and should be a list of any
5589 already installed plugins, libraries or executables to also be
5590 fixed-up.
5591 <dirs> will be passed to BundleUtilities and should contain and direc‐
5593 tories to be searched to find library dependencies.
5594 <plugins_dir> allows an custom plugins directory to be used.
5596 <request_qt_conf> will force a qt.conf file to be written even if not
5598 needed.
5599 INSTALL_QT4_PLUGIN_PATH(plugin executable copy installed_plugin_path_var
5601 <plugins_dir> <component> <configurations>)
5602 Install (or copy) a resolved <plugin> to the default plugins directory
5604 (or <plugins_dir>) relative to <executable> and store the result in
5605 <installed_plugin_path_var>.
5606 If <copy> is set to TRUE then the plugins will be copied rather than
5608 installed. This is to allow this module to be used at CMake time
5609 rather than install time.
5610 If <component> is set then anything installed will use this COMPONENT.
5612 INSTALL_QT4_PLUGIN(plugin executable copy installed_plugin_path_var
5614 <plugins_dir> <component>)
5615 Install (or copy) an unresolved <plugin> to the default plugins direc‐
5617 tory (or <plugins_dir>) relative to <executable> and store the result
5618 in <installed_plugin_path_var>. See documentation of INSTALL_QT4_PLUG‐
5619 IN_PATH.
5620 INSTALL_QT4_EXECUTABLE(<executable>
5622 [<qtplugins> <libs> <dirs> <plugins_dir> <request_qt_conf> <component>])
5623 Installs Qt plugins, writes a Qt configuration file (if needed) and
5625 fixes up a Qt4 executable using BundleUtilities so it is standalone and
5626 can be drag-and-drop copied to another machine as long as all of the
5627 system libraries are compatible. The executable will be fixed-up at
5628 install time. <component> is the COMPONENT used for bundle fixup and
5629 plugin installation. See documentation of FIXUP_QT4_BUNDLE.
5630 Documentation
5632 DocumentationVTK.cmake
5633 This file provides support for the VTK documentation framework. It
5635 relies on several tools (Doxygen, Perl, etc).
5636 ExternalData
5638 Manage data files stored outside source tree
5639 Introduction
5641 Use this module to unambiguously reference data files stored outside
5642 the source tree and fetch them at build time from arbitrary local and
5643 remote content-addressed locations. Functions provided by this module
5644 recognize arguments with the syntax DATA{<name>} as references to
5645 external data, replace them with full paths to local copies of those
5646 data, and create build rules to fetch and update the local copies.
5647 For example:
5649 include(ExternalData)
5651 set(ExternalData_URL_TEMPLATES "file:///local/%(algo)/%(hash)"
5652 "file:////host/share/%(algo)/%(hash)"
5653 "http://data.org/%(algo)/%(hash)")
5654 ExternalData_Add_Test(MyData
5655 NAME MyTest
5656 COMMAND MyExe DATA{MyInput.png}
5657 )
5658 ExternalData_Add_Target(MyData)
5659 When test MyTest runs the DATA{MyInput.png} argument will be replaced
5661 by the full path to a real instance of the data file MyInput.png on
5662 disk. If the source tree contains a content link such as MyIn‐
5663 put.png.md5 then the MyData target creates a real MyInput.png in the
5664 build tree.
5665 Module Functions
5667 ExternalData_Expand_Arguments
5668 The ExternalData_Expand_Arguments function evaluates DATA{} ref‐
5669 erences in its arguments and constructs a new list of arguments:
5670 ExternalData_Expand_Arguments(
5672 <target> # Name of data management target
5673 <outVar> # Output variable
5674 [args...] # Input arguments, DATA{} allowed
5675 )
5676 It replaces each DATA{} reference in an argument with the full
5678 path of a real data file on disk that will exist after the <tar‐
5679 get> builds.
5680 ExternalData_Add_Test
5682 The ExternalData_Add_Test function wraps around the CMake
5683 add_test() command but supports DATA{} references in its argu‐
5684 ments:
5685 ExternalData_Add_Test(
5687 <target> # Name of data management target
5688 ... # Arguments of add_test(), DATA{} allowed
5689 )
5690 It passes its arguments through ExternalData_Expand_Arguments
5692 and then invokes the add_test() command using the results.
5693 ExternalData_Add_Target
5695 The ExternalData_Add_Target function creates a custom target to
5696 manage local instances of data files stored externally:
5697 ExternalData_Add_Target(
5699 <target> # Name of data management target
5700 )
5701 It creates custom commands in the target as necessary to make
5703 data files available for each DATA{} reference previously evalu‐
5704 ated by other functions provided by this module. Data files may
5705 be fetched from one of the URL templates specified in the Exter‐
5706 nalData_URL_TEMPLATES variable, or may be found locally in one
5707 of the paths specified in the ExternalData_OBJECT_STORES vari‐
5708 able.
5709 Typically only one target is needed to manage all external data
5711 within a project. Call this function once at the end of config‐
5712 uration after all data references have been processed.
5713 Module Variables
5715 The following variables configure behavior. They should be set before
5716 calling any of the functions provided by this module.
5717 ExternalData_BINARY_ROOT
5719 The ExternalData_BINARY_ROOT variable may be set to the direc‐
5720 tory to hold the real data files named by expanded DATA{} refer‐
5721 ences. The default is CMAKE_BINARY_DIR. The directory layout
5722 will mirror that of content links under External‐
5723 Data_SOURCE_ROOT.
5724 ExternalData_CUSTOM_SCRIPT_<key>
5726 Specify a full path to a .cmake custom fetch script identified
5727 by <key> in entries of the ExternalData_URL_TEMPLATES list. See
5728 Custom Fetch Scripts.
5729 ExternalData_LINK_CONTENT
5731 The ExternalData_LINK_CONTENT variable may be set to the name of
5732 a supported hash algorithm to enable automatic conversion of
5733 real data files referenced by the DATA{} syntax into content
5734 links. For each such <file> a content link named <file><ext> is
5735 created. The original file is renamed to the form .External‐
5736 Data_<algo>_<hash> to stage it for future transmission to one of
5737 the locations in the list of URL templates (by means outside the
5738 scope of this module). The data fetch rule created for the con‐
5739 tent link will use the staged object if it cannot be found using
5740 any URL template.
5741 ExternalData_NO_SYMLINKS
5743 The real data files named by expanded DATA{} references may be
5744 made available under ExternalData_BINARY_ROOT using symbolic
5745 links on some platforms. The ExternalData_NO_SYMLINKS variable
5746 may be set to disable use of symbolic links and enable use of
5747 copies instead.
5748 ExternalData_OBJECT_STORES
5750 The ExternalData_OBJECT_STORES variable may be set to a list of
5751 local directories that store objects using the layout
5752 <dir>/%(algo)/%(hash). These directories will be searched first
5753 for a needed object. If the object is not available in any
5754 store then it will be fetched remotely using the URL templates
5755 and added to the first local store listed. If no stores are
5756 specified the default is a location inside the build tree.
5757 ExternalData_SERIES_PARSE
5759 ExternalData_SERIES_PARSE_PREFIX
5761 ExternalData_SERIES_PARSE_NUMBER
5763 ExternalData_SERIES_PARSE_SUFFIX
5765 ExternalData_SERIES_MATCH
5767 See Referencing File Series.
5768 ExternalData_SOURCE_ROOT
5770 The ExternalData_SOURCE_ROOT variable may be set to the highest
5771 source directory containing any path named by a DATA{} refer‐
5772 ence. The default is CMAKE_SOURCE_DIR. External‐
5773 Data_SOURCE_ROOT and CMAKE_SOURCE_DIR must refer to directories
5774 within a single source distribution (e.g. they come together in
5775 one tarball).
5776 ExternalData_TIMEOUT_ABSOLUTE
5778 The ExternalData_TIMEOUT_ABSOLUTE variable sets the download
5779 absolute timeout, in seconds, with a default of 300 seconds.
5780 Set to 0 to disable enforcement.
5781 ExternalData_TIMEOUT_INACTIVITY
5783 The ExternalData_TIMEOUT_INACTIVITY variable sets the download
5784 inactivity timeout, in seconds, with a default of 60 seconds.
5785 Set to 0 to disable enforcement.
5786 ExternalData_URL_ALGO_<algo>_<key>
5788 Specify a custom URL component to be substituted for URL tem‐
5789 plate placeholders of the form %(algo:<key>), where <key> is a
5790 valid C identifier, when fetching an object referenced via hash
5791 algorithm <algo>. If not defined, the default URL component is
5792 just <algo> for any <key>.
5793 ExternalData_URL_TEMPLATES
5795 The ExternalData_URL_TEMPLATES may be set to provide a list of
5796 of URL templates using the placeholders %(algo) and %(hash) in
5797 each template. Data fetch rules try each URL template in order
5798 by substituting the hash algorithm name for %(algo) and the hash
5799 value for %(hash). Alternatively one may use %(algo:<key>) with
5800 ExternalData_URL_ALGO_<algo>_<key> variables to gain more flexi‐
5801 bility in remote URLs.
5802 Referencing Files
5804 Referencing Single Files
5805 The DATA{} syntax is literal and the <name> is a full or relative path
5806 within the source tree. The source tree must contain either a real
5807 data file at <name> or a “content link” at <name><ext> containing a
5808 hash of the real file using a hash algorithm corresponding to <ext>.
5809 For example, the argument DATA{img.png} may be satisfied by either a
5810 real img.png file in the current source directory or a img.png.md5 file
5811 containing its MD5 sum.
5812 Multiple content links of the same name with different hash algorithms
5814 are supported (e.g. img.png.sha256 and img.png.sha1) so long as they
5815 all correspond to the same real file. This allows objects to be
5816 fetched from sources indexed by different hash algorithms.
5817 Referencing File Series
5819 The DATA{} syntax can be told to fetch a file series using the form
5820 DATA{<name>,:}, where the : is literal. If the source tree contains a
5821 group of files or content links named like a series then a reference to
5822 one member adds rules to fetch all of them. Although all members of a
5823 series are fetched, only the file originally named by the DATA{} argu‐
5824 ment is substituted for it. The default configuration recognizes file
5825 series names ending with #.ext, _#.ext, .#.ext, or -#.ext where # is a
5826 sequence of decimal digits and .ext is any single extension. Configure
5827 it with a regex that parses <number> and <suffix> parts from the end of
5828 <name>:
5829 ExternalData_SERIES_PARSE = regex of the form (<number>)(<suffix>)$
5831 For more complicated cases set:
5833 ExternalData_SERIES_PARSE = regex with at least two () groups
5835 ExternalData_SERIES_PARSE_PREFIX = <prefix> regex group number, if any
5836 ExternalData_SERIES_PARSE_NUMBER = <number> regex group number
5837 ExternalData_SERIES_PARSE_SUFFIX = <suffix> regex group number
5838 Configure series number matching with a regex that matches the <number>
5840 part of series members named <prefix><number><suffix>:
5841 ExternalData_SERIES_MATCH = regex matching <number> in all series members
5843 Note that the <suffix> of a series does not include a hash-algorithm
5845 extension.
5846 Referencing Associated Files
5848 The DATA{} syntax can alternatively match files associated with the
5849 named file and contained in the same directory. Associated files may
5850 be specified by options using the syntax
5851 DATA{<name>,<opt1>,<opt2>,...}. Each option may specify one file by
5852 name or specify a regular expression to match file names using the syn‐
5853 tax REGEX:<regex>. For example, the arguments:
5854 DATA{MyData/MyInput.mhd,MyInput.img} # File pair
5856 DATA{MyData/MyFrames00.png,REGEX:MyFrames[0-9]+\\.png} # Series
5857 will pass MyInput.mha and MyFrames00.png on the command line but ensure
5859 that the associated files are present next to them.
5860 Referencing Directories
5862 The DATA{} syntax may reference a directory using a trailing slash and
5863 a list of associated files. The form DATA{<name>/,<opt1>,<opt2>,...}
5864 adds rules to fetch any files in the directory that match one of the
5865 associated file options. For example, the argument
5866 DATA{MyDataDir/,REGEX:.*} will pass the full path to a MyDataDir direc‐
5867 tory on the command line and ensure that the directory contains files
5868 corresponding to every file or content link in the MyDataDir source
5869 directory. In order to match associated files in subdirectories, spec‐
5870 ify a RECURSE: option, e.g. DATA{MyDataDir/,RECURSE:,REGEX:.*}.
5871 Hash Algorithms
5873 The following hash algorithms are supported:
5874 %(algo) <ext> Description
5876 ------- ----- -----------
5877 MD5 .md5 Message-Digest Algorithm 5, RFC 1321
5878 SHA1 .sha1 US Secure Hash Algorithm 1, RFC 3174
5879 SHA224 .sha224 US Secure Hash Algorithms, RFC 4634
5880 SHA256 .sha256 US Secure Hash Algorithms, RFC 4634
5881 SHA384 .sha384 US Secure Hash Algorithms, RFC 4634
5882 SHA512 .sha512 US Secure Hash Algorithms, RFC 4634
5883 SHA3_224 .sha3-224 Keccak SHA-3
5884 SHA3_256 .sha3-256 Keccak SHA-3
5885 SHA3_384 .sha3-384 Keccak SHA-3
5886 SHA3_512 .sha3-512 Keccak SHA-3
5887 Note that the hashes are used only for unique data identification and
5889 download verification.
5890 Custom Fetch Scripts
5892 When a data file must be fetched from one of the URL templates speci‐
5893 fied in the ExternalData_URL_TEMPLATES variable, it is normally down‐
5894 loaded using the file(DOWNLOAD) command. One may specify usage of a
5895 custom fetch script by using a URL template of the form ExternalData‐
5896 CustomScript://<key>/<loc>. The <key> must be a C identifier, and the
5897 <loc> must contain the %(algo) and %(hash) placeholders. A variable
5898 corresponding to the key, ExternalData_CUSTOM_SCRIPT_<key>, must be set
5899 to the full path to a .cmake script file. The script will be included
5900 to perform the actual fetch, and provided with the following variables:
5901 ExternalData_CUSTOM_LOCATION
5903 When a custom fetch script is loaded, this variable is set to
5904 the location part of the URL, which will contain the substituted
5905 hash algorithm name and content hash value.
5906 ExternalData_CUSTOM_FILE
5908 When a custom fetch script is loaded, this variable is set to
5909 the full path to a file in which the script must store the
5910 fetched content. The name of the file is unspecified and should
5911 not be interpreted in any way.
5912 The custom fetch script is expected to store fetched content in the
5914 file or set a variable:
5915 ExternalData_CUSTOM_ERROR
5917 When a custom fetch script fails to fetch the requested content,
5918 it must set this variable to a short one-line message describing
5919 the reason for failure.
5920 ExternalProject
5922 External Project Definition
5923 ExternalProject_Add
5924 The ExternalProject_Add() function creates a custom target to
5925 drive download, update/patch, configure, build, install and test
5926 steps of an external project:
5927 ExternalProject_Add(<name> [<option>...])
5929 The individual steps within the process can be driven indepen‐
5931 dently if required (e.g. for CDash submission) and extra custom
5932 steps can be defined, along with the ability to control the step
5933 dependencies. The directory structure used for the management of
5934 the external project can also be customized. The function sup‐
5935 ports a large number of options which can be used to tailor the
5936 external project behavior.
5937 Directory Options:
5939 Most of the time, the default directory layout is suffi‐
5940 cient. It is largely an implementation detail that the
5941 main project usually doesn’t need to change. In some cir‐
5942 cumstances, however, control over the directory layout
5943 can be useful or necessary. The directory options are
5944 potentially more useful from the point of view that the
5945 main build can use the ExternalProject_Get_Property()
5946 command to retrieve their values, thereby allowing the
5947 main project to refer to build artifacts of the external
5948 project.
5949 PREFIX <dir>
5951 Root directory for the external project. Unless
5952 otherwise noted below, all other directories asso‐
5953 ciated with the external project will be created
5954 under here.
5955 TMP_DIR <dir>
5957 Directory in which to store temporary files.
5958 STAMP_DIR <dir>
5960 Directory in which to store the timestamps of each
5961 step. Log files from individual steps are also
5962 created in here (see Logging Options below).
5963 DOWNLOAD_DIR <dir>
5965 Directory in which to store downloaded files
5966 before unpacking them. This directory is only used
5967 by the URL download method, all other download
5968 methods use SOURCE_DIR directly instead.
5969 SOURCE_DIR <dir>
5971 Source directory into which downloaded contents
5972 will be unpacked, or for non-URL download methods,
5973 the directory in which the repository should be
5974 checked out, cloned, etc. If no download method is
5975 specified, this must point to an existing direc‐
5976 tory where the external project has already been
5977 unpacked or cloned/checked out.
5978 NOTE:
5980 If a download method is specified, any existing
5981 contents of the source directory may be
5982 deleted. Only the URL download method checks
5983 whether this directory is either missing or
5984 empty before initiating the download, stopping
5985 with an error if it is not empty. All other
5986 download methods silently discard any previous
5987 contents of the source directory.
5988 BINARY_DIR <dir>
5990 Specify the build directory location. This option
5991 is ignored if BUILD_IN_SOURCE is enabled.
5992 INSTALL_DIR <dir>
5994 Installation prefix to be placed in the
5995 <INSTALL_DIR> placeholder. This does not actually
5996 configure the external project to install to the
5997 given prefix. That must be done by passing appro‐
5998 priate arguments to the external project configu‐
5999 ration step, e.g. using <INSTALL_DIR>.
6000 If any of the above ..._DIR options are not specified,
6002 their defaults are computed as follows. If the PREFIX
6003 option is given or the EP_PREFIX directory property is
6004 set, then an external project is built and installed
6005 under the specified prefix:
6006 TMP_DIR = <prefix>/tmp
6008 STAMP_DIR = <prefix>/src/<name>-stamp
6009 DOWNLOAD_DIR = <prefix>/src
6010 SOURCE_DIR = <prefix>/src/<name>
6011 BINARY_DIR = <prefix>/src/<name>-build
6012 INSTALL_DIR = <prefix>
6013 Otherwise, if the EP_BASE directory property is set then
6015 components of an external project are stored under the
6016 specified base:
6017 TMP_DIR = <base>/tmp/<name>
6019 STAMP_DIR = <base>/Stamp/<name>
6020 DOWNLOAD_DIR = <base>/Download/<name>
6021 SOURCE_DIR = <base>/Source/<name>
6022 BINARY_DIR = <base>/Build/<name>
6023 INSTALL_DIR = <base>/Install/<name>
6024 If no PREFIX, EP_PREFIX, or EP_BASE is specified, then
6026 the default is to set PREFIX to <name>-prefix. Relative
6027 paths are interpreted with respect to CMAKE_CUR‐
6028 RENT_BINARY_DIR at the point where ExternalProject_Add()
6029 is called.
6030 Download Step Options:
6032 A download method can be omitted if the SOURCE_DIR option
6033 is used to point to an existing non-empty directory. Oth‐
6034 erwise, one of the download methods below must be speci‐
6035 fied (multiple download methods should not be given) or a
6036 custom DOWNLOAD_COMMAND provided.
6037 DOWNLOAD_COMMAND <cmd>...
6039 Overrides the command used for the download step
6040 (generator expressions are supported). If this
6041 option is specified, all other download options
6042 will be ignored. Providing an empty string for
6043 <cmd> effectively disables the download step.
6044 URL Download
6046 URL <url1> [<url2>...]
6048 List of paths and/or URL(s) of the external
6049 project’s source. When more than one URL is
6050 given, they are tried in turn until one
6051 succeeds. A URL may be an ordinary path in
6052 the local file system (in which case it
6053 must be the only URL provided) or any down‐
6054 loadable URL supported by the file(DOWN‐
6055 LOAD) command. A local filesystem path may
6056 refer to either an existing directory or to
6057 an archive file, whereas a URL is expected
6058 to point to a file which can be treated as
6059 an archive. When an archive is used, it
6060 will be unpacked automatically unless the
6061 DOWNLOAD_NO_EXTRACT option is set to pre‐
6062 vent it. The archive type is determined by
6063 inspecting the actual content rather than
6064 using logic based on the file extension.
6065 URL_HASH <algo>=<hashValue>
6067 Hash of the archive file to be downloaded.
6068 The argument should be of the form
6069 <algo>=<hashValue> where algo can be any of
6070 the hashing algorithms supported by the
6071 file() command. Specifying this option is
6072 strongly recommended for URL downloads, as
6073 it ensures the integrity of the downloaded
6074 content. It is also used as a check for a
6075 previously downloaded file, allowing con‐
6076 nection to the remote location to be
6077 avoided altogether if the local directory
6078 already has a file from an earlier download
6079 that matches the specified hash.
6080 URL_MD5 <md5>
6082 Equivalent to URL_HASH MD5=<md5>.
6083 DOWNLOAD_NAME <fname>
6085 File name to use for the downloaded file.
6086 If not given, the end of the URL is used to
6087 determine the file name. This option is
6088 rarely needed, the default name is gener‐
6089 ally suitable and is not normally used out‐
6090 side of code internal to the ExternalPro‐
6091 ject module.
6092 DOWNLOAD_NO_EXTRACT <bool>
6094 Allows the extraction part of the download
6095 step to be disabled by passing a boolean
6096 true value for this option. If this option
6097 is not given, the downloaded contents will
6098 be unpacked automatically if required. If
6099 extraction has been disabled, the full path
6100 to the downloaded file is available as
6101 <DOWNLOADED_FILE> in subsequent steps or as
6102 the property DOWNLOADED_FILE with the
6103 ExternalProject_Get_Property() command.
6104 DOWNLOAD_NO_PROGRESS <bool>
6106 Can be used to disable logging the download
6107 progress. If this option is not given,
6108 download progress messages will be logged.
6109 TIMEOUT <seconds>
6111 Maximum time allowed for file download
6112 operations.
6113 HTTP_USERNAME <username>
6115 Username for the download operation if
6116 authentication is required.
6117 HTTP_PASSWORD <password>
6119 Password for the download operation if
6120 authentication is required.
6121 HTTP_HEADER <header1> [<header2>...]
6123 Provides an arbitrary list of HTTP headers
6124 for the download operation. This can be
6125 useful for accessing content in systems
6126 like AWS, etc.
6127 TLS_VERIFY <bool>
6129 Specifies whether certificate verification
6130 should be performed for https URLs. If this
6131 option is not provided, the default behav‐
6132 ior is determined by the CMAKE_TLS_VERIFY
6133 variable (see file(DOWNLOAD)). If that is
6134 also not set, certificate verification will
6135 not be performed. In situations where
6136 URL_HASH cannot be provided, this option
6137 can be an alternative verification measure.
6138 TLS_CAINFO <file>
6140 Specify a custom certificate authority file
6141 to use if TLS_VERIFY is enabled. If this
6142 option is not specified, the value of the
6143 CMAKE_TLS_CAINFO variable will be used
6144 instead (see file(DOWNLOAD))
6145 NETRC <level>
6147 Specify whether the .netrc file is to be
6148 used for operation. If this option is not
6149 specified, the value of the CMAKE_NETRC
6150 variable will be used instead (see
6151 file(DOWNLOAD)) Valid levels are:
6152 IGNORED
6154 The .netrc file is ignored. This is
6155 the default.
6156 OPTIONAL
6158 The .netrc file is optional, and
6159 information in the URL is preferred.
6160 The file will be scanned to find
6161 which ever information is not speci‐
6162 fied in the URL.
6163 REQUIRED
6165 The .netrc file is required, and
6166 information in the URL is ignored.
6167 NETRC_FILE <file>
6169 Specify an alternative .netrc file to the
6170 one in your home directory if the NETRC
6171 level is OPTIONAL or REQUIRED. If this
6172 option is not specified, the value of the
6173 CMAKE_NETRC_FILE variable will be used
6174 instead (see file(DOWNLOAD))
6175 Git NOTE: A git version of 1.6.5 or later is required
6177 if this download method is used.
6178 GIT_REPOSITORY <url>
6180 URL of the git repository. Any URL under‐
6181 stood by the git command may be used.
6182 GIT_TAG <tag>
6184 Git branch name, tag or commit hash. Note
6185 that branch names and tags should generally
6186 be specified as remote names (i.e. ori‐
6187 gin/myBranch rather than simply myBranch).
6188 This ensures that if the remote end has its
6189 tag moved or branch rebased or history
6190 rewritten, the local clone will still be
6191 updated correctly. In general, however,
6192 specifying a commit hash should be pre‐
6193 ferred for a number of reasons:
6194 · If the local clone already has the commit
6196 corresponding to the hash, no git fetch
6197 needs to be performed to check for
6198 changes each time CMake is re-run. This
6199 can result in a significant speed up if
6200 many external projects are being used.
6201 · Using a specific git hash ensures that
6203 the main project’s own history is fully
6204 traceable to a specific point in the
6205 external project’s evolution. If a branch
6206 or tag name is used instead, then check‐
6207 ing out a specific commit of the main
6208 project doesn’t necessarily pin the whole
6209 build to a specific point in the life of
6210 the external project. The lack of such
6211 deterministic behavior makes the main
6212 project lose traceability and repeatabil‐
6213 ity.
6214 GIT_REMOTE_NAME <name>
6216 The optional name of the remote. If this
6217 option is not specified, it defaults to
6218 origin.
6219 GIT_SUBMODULES <module>...
6221 Specific git submodules that should also be
6222 updated. If this option is not provided,
6223 all git submodules will be updated.
6224 GIT_SHALLOW <bool>
6226 When this option is enabled, the git clone
6227 operation will be given the --depth 1
6228 option. This performs a shallow clone,
6229 which avoids downloading the whole history
6230 and instead retrieves just the commit
6231 denoted by the GIT_TAG option.
6232 GIT_PROGRESS <bool>
6234 When enabled, this option instructs the git
6235 clone operation to report its progress by
6236 passing it the --progress option. Without
6237 this option, the clone step for large
6238 projects may appear to make the build
6239 stall, since nothing will be logged until
6240 the clone operation finishes. While this
6241 option can be used to provide progress to
6242 prevent the appearance of the build having
6243 stalled, it may also make the build overly
6244 noisy if lots of external projects are
6245 used.
6246 GIT_CONFIG <option1> [<option2>...]
6248 Specify a list of config options to pass to
6249 git clone. Each option listed will be
6250 transformed into its own --config <option>
6251 on the git clone command line, with each
6252 option required to be in the form
6253 key=value.
6254 Subversion
6256 SVN_REPOSITORY <url>
6258 URL of the Subversion repository.
6259 SVN_REVISION -r<rev>
6261 Revision to checkout from the Subversion
6262 repository.
6263 SVN_USERNAME <username>
6265 Username for the Subversion checkout and
6266 update.
6267 SVN_PASSWORD <password>
6269 Password for the Subversion checkout and
6270 update.
6271 SVN_TRUST_CERT <bool>
6273 Specifies whether to trust the Subversion
6274 server site certificate. If enabled, the
6275 --trust-server-cert option is passed to the
6276 svn checkout and update commands.
6277 Mercurial
6279 HG_REPOSITORY <url>
6281 URL of the mercurial repository.
6282 HG_TAG <tag>
6284 Mercurial branch name, tag or commit id.
6285 CVS
6287 CVS_REPOSITORY <cvsroot>
6289 CVSROOT of the CVS repository.
6290 CVS_MODULE <mod>
6292 Module to checkout from the CVS repository.
6293 CVS_TAG <tag>
6295 Tag to checkout from the CVS repository.
6296 Update/Patch Step Options:
6298 Whenever CMake is re-run, by default the external
6299 project’s sources will be updated if the download method
6300 supports updates (e.g. a git repository would be checked
6301 if the GIT_TAG does not refer to a specific commit).
6302 UPDATE_COMMAND <cmd>...
6304 Overrides the download method’s update step with a
6305 custom command. The command may use generator
6306 expressions.
6307 UPDATE_DISCONNECTED <bool>
6309 When enabled, this option causes the update step
6310 to be skipped. It does not, however, prevent the
6311 download step. The update step can still be added
6312 as a step target (see
6313 ExternalProject_Add_StepTargets()) and called man‐
6314 ually. This is useful if you want to allow devel‐
6315 opers to build the project when disconnected from
6316 the network (the network may still be needed for
6317 the download step though).
6318 When this option is present, it is generally
6320 advisable to make the value a cache variable under
6321 the developer’s control rather than hard-coding
6322 it. If this option is not present, the default
6323 value is taken from the EP_UPDATE_DISCONNECTED
6324 directory property. If that is also not defined,
6325 updates are performed as normal. The
6326 EP_UPDATE_DISCONNECTED directory property is
6327 intended as a convenience for controlling the
6328 UPDATE_DISCONNECTED behavior for an entire section
6329 of a project’s directory hierarchy and may be a
6330 more convenient method of giving developers con‐
6331 trol over whether or not to perform updates
6332 (assuming the project also provides a cache vari‐
6333 able or some other convenient method for setting
6334 the directory property).
6335 PATCH_COMMAND <cmd>...
6337 Specifies a custom command to patch the sources
6338 after an update. By default, no patch command is
6339 defined. Note that it can be quite difficult to
6340 define an appropriate patch command that performs
6341 robustly, especially for download methods such as
6342 git where changing the GIT_TAG will not discard
6343 changes from a previous patch, but the patch com‐
6344 mand will be called again after updating to the
6345 new tag.
6346 Configure Step Options:
6348 The configure step is run after the download and update
6349 steps. By default, the external project is assumed to be
6350 a CMake project, but this can be overridden if required.
6351 CONFIGURE_COMMAND <cmd>...
6353 The default configure command runs CMake with
6354 options based on the main project. For non-CMake
6355 external projects, the CONFIGURE_COMMAND option
6356 must be used to override this behavior (generator
6357 expressions are supported). For projects that
6358 require no configure step, specify this option
6359 with an empty string as the command to execute.
6360 CMAKE_COMMAND /.../cmake
6362 Specify an alternative cmake executable for the
6363 configure step (use an absolute path). This is
6364 generally not recommended, since it is usually
6365 desirable to use the same CMake version throughout
6366 the whole build. This option is ignored if a cus‐
6367 tom configure command has been specified with CON‐
6368 FIGURE_COMMAND.
6369 CMAKE_GENERATOR <gen>
6371 Override the CMake generator used for the config‐
6372 ure step. Without this option, the same generator
6373 as the main build will be used. This option is
6374 ignored if a custom configure command has been
6375 specified with the CONFIGURE_COMMAND option.
6376 CMAKE_GENERATOR_PLATFORM <platform>
6378 Pass a generator-specific platform name to the
6379 CMake command (see CMAKE_GENERATOR_PLATFORM). It
6380 is an error to provide this option without the
6381 CMAKE_GENERATOR option.
6382 CMAKE_GENERATOR_TOOLSET <toolset>
6384 Pass a generator-specific toolset name to the
6385 CMake command (see CMAKE_GENERATOR_TOOLSET). It is
6386 an error to provide this option without the
6387 CMAKE_GENERATOR option.
6388 CMAKE_GENERATOR_INSTANCE <instance>
6390 Pass a generator-specific instance selection to
6391 the CMake command (see CMAKE_GENERATOR_INSTANCE).
6392 It is an error to provide this option without the
6393 CMAKE_GENERATOR option.
6394 CMAKE_ARGS <arg>...
6396 The specified arguments are passed to the cmake
6397 command line. They can be any argument the cmake
6398 command understands, not just cache values defined
6399 by -D... arguments (see also CMake Options). In
6400 addition, arguments may use generator expressions.
6401 CMAKE_CACHE_ARGS <arg>...
6403 This is an alternate way of specifying cache vari‐
6404 ables where command line length issues may become
6405 a problem. The arguments are expected to be in the
6406 form -Dvar:STRING=value, which are then trans‐
6407 formed into CMake set() commands with the FORCE
6408 option used. These set() commands are written to a
6409 pre-load script which is then applied using the
6410 cmake -C command line option. Arguments may use
6411 generator expressions.
6412 CMAKE_CACHE_DEFAULT_ARGS <arg>...
6414 This is the same as the CMAKE_CACHE_ARGS option
6415 except the set() commands do not include the FORCE
6416 keyword. This means the values act as initial
6417 defaults only and will not override any variables
6418 already set from a previous run. Use this option
6419 with care, as it can lead to different behavior
6420 depending on whether the build starts from a fresh
6421 build directory or re-uses previous build con‐
6422 tents.
6423 SOURCE_SUBDIR <dir>
6425 When no CONFIGURE_COMMAND option is specified, the
6426 configure step assumes the external project has a
6427 CMakeLists.txt file at the top of its source tree
6428 (i.e. in SOURCE_DIR). The SOURCE_SUBDIR option can
6429 be used to point to an alternative directory
6430 within the source tree to use as the top of the
6431 CMake source tree instead. This must be a relative
6432 path and it will be interpreted as being relative
6433 to SOURCE_DIR.
6434 Build Step Options:
6436 If the configure step assumed the external project uses
6437 CMake as its build system, the build step will also. Oth‐
6438 erwise, the build step will assume a Makefile-based build
6439 and simply run make with no arguments as the default
6440 build step. This can be overridden with custom build com‐
6441 mands if required.
6442 BUILD_COMMAND <cmd>...
6444 Overrides the default build command (generator
6445 expressions are supported). If this option is not
6446 given, the default build command will be chosen to
6447 integrate with the main build in the most appro‐
6448 priate way (e.g. using recursive make for Makefile
6449 generators or cmake --build if the project uses a
6450 CMake build). This option can be specified with an
6451 empty string as the command to make the build step
6452 do nothing.
6453 BUILD_IN_SOURCE <bool>
6455 When this option is enabled, the build will be
6456 done directly within the external project’s source
6457 tree. This should generally be avoided, the use of
6458 a separate build directory is usually preferred,
6459 but it can be useful when the external project
6460 assumes an in-source build. The BINARY_DIR option
6461 should not be specified if building in-source.
6462 BUILD_ALWAYS <bool>
6464 Enabling this option forces the build step to
6465 always be run. This can be the easiest way to
6466 robustly ensure that the external project’s own
6467 build dependencies are evaluated rather than rely‐
6468 ing on the default success timestamp-based method.
6469 This option is not normally needed unless develop‐
6470 ers are expected to modify something the external
6471 project’s build depends on in a way that is not
6472 detectable via the step target dependencies (e.g.
6473 SOURCE_DIR is used without a download method and
6474 developers might modify the sources in
6475 SOURCE_DIR).
6476 BUILD_BYPRODUCTS <file>...
6478 Specifies files that will be generated by the
6479 build command but which might or might not have
6480 their modification time updated by subsequent
6481 builds. These ultimately get passed through as
6482 BYPRODUCTS to the build step’s own underlying call
6483 to add_custom_command().
6484 Install Step Options:
6486 If the configure step assumed the external project uses
6487 CMake as its build system, the install step will also.
6488 Otherwise, the install step will assume a Makefile-based
6489 build and simply run make install as the default build
6490 step. This can be overridden with custom install commands
6491 if required.
6492 INSTALL_COMMAND <cmd>...
6494 The external project’s own install step is invoked
6495 as part of the main project’s build. It is done
6496 after the external project’s build step and may be
6497 before or after the external project’s test step
6498 (see the TEST_BEFORE_INSTALL option below). The
6499 external project’s install rules are not part of
6500 the main project’s install rules, so if anything
6501 from the external project should be installed as
6502 part of the main build, these need to be specified
6503 in the main build as additional install() com‐
6504 mands. The default install step builds the install
6505 target of the external project, but this can be
6506 overridden with a custom command using this option
6507 (generator expressions are supported). Passing an
6508 empty string as the <cmd> makes the install step
6509 do nothing.
6510 Test Step Options:
6512 The test step is only defined if at least one of the fol‐
6513 lowing TEST_... options are provided.
6514 TEST_COMMAND <cmd>...
6516 Overrides the default test command (generator
6517 expressions are supported). If this option is not
6518 given, the default behavior of the test step is to
6519 build the external project’s own test target. This
6520 option can be specified with <cmd> as an empty
6521 string, which allows the test step to still be
6522 defined, but it will do nothing. Do not specify
6523 any of the other TEST_... options if providing an
6524 empty string as the test command, but prefer to
6525 omit all TEST_... options altogether if the test
6526 step target is not needed.
6527 TEST_BEFORE_INSTALL <bool>
6529 When this option is enabled, the test step will be
6530 executed before the install step. The default
6531 behavior is for the test step to run after the
6532 install step.
6533 TEST_AFTER_INSTALL <bool>
6535 This option is mainly useful as a way to indicate
6536 that the test step is desired but all default
6537 behavior is sufficient. Specifying this option
6538 with a boolean true value ensures the test step is
6539 defined and that it comes after the install step.
6540 If both TEST_BEFORE_INSTALL and TEST_AFTER_INSTALL
6541 are enabled, the latter is silently ignored.
6542 TEST_EXCLUDE_FROM_MAIN <bool>
6544 If enabled, the main build’s default ALL target
6545 will not depend on the test step. This can be a
6546 useful way of ensuring the test step is defined
6547 but only gets invoked when manually requested.
6548 Output Logging Options:
6550 Each of the following LOG_... options can be used to wrap
6551 the relevant step in a script to capture its output to
6552 files. The log files will be created in the STAMP_DIR
6553 directory with step-specific file names.
6554 LOG_DOWNLOAD <bool>
6556 When enabled, the output of the download step is
6557 logged to files.
6558 LOG_UPDATE <bool>
6560 When enabled, the output of the update step is
6561 logged to files.
6562 LOG_CONFIGURE <bool>
6564 When enabled, the output of the configure step is
6565 logged to files.
6566 LOG_BUILD <bool>
6568 When enabled, the output of the build step is
6569 logged to files.
6570 LOG_INSTALL <bool>
6572 When enabled, the output of the install step is
6573 logged to files.
6574 LOG_TEST <bool>
6576 When enabled, the output of the test step is
6577 logged to files.
6578 Terminal Access Options:
6580 Steps can be given direct access to the terminal in some
6581 cases. Giving a step access to the terminal may allow it
6582 to receive terminal input if required, such as for
6583 authentication details not provided by other options.
6584 With the Ninja generator, these options place the steps
6585 in the console job pool. Each step can be given access to
6586 the terminal individually via the following options:
6587 USES_TERMINAL_DOWNLOAD <bool>
6589 Give the download step access to the terminal.
6590 USES_TERMINAL_UPDATE <bool>
6592 Give the update step access to the terminal.
6593 USES_TERMINAL_CONFIGURE <bool>
6595 Give the configure step access to the terminal.
6596 USES_TERMINAL_BUILD <bool>
6598 Give the build step access to the terminal.
6599 USES_TERMINAL_INSTALL <bool>
6601 Give the install step access to the terminal.
6602 USES_TERMINAL_TEST <bool>
6604 Give the test step access to the terminal.
6605 Target Options:
6607 DEPENDS <targets>...
6609 Specify other targets on which the external
6610 project depends. The other targets will be brought
6611 up to date before any of the external project’s
6612 steps are executed. Because the external project
6613 uses additional custom targets internally for each
6614 step, the DEPENDS option is the most convenient
6615 way to ensure all of those steps depend on the
6616 other targets. Simply doing add_dependen‐
6617 cies(<name> <targets>) will not make any of the
6618 steps dependent on <targets>.
6619 EXCLUDE_FROM_ALL <bool>
6621 When enabled, this option excludes the external
6622 project from the default ALL target of the main
6623 build.
6624 STEP_TARGETS <step-target>...
6626 Generate custom targets for the specified steps.
6627 This is required if the steps need to be triggered
6628 manually or if they need to be used as dependen‐
6629 cies of other targets. If this option is not spec‐
6630 ified, the default value is taken from the
6631 EP_STEP_TARGETS directory property. See
6632 ExternalProject_Add_Step() below for further dis‐
6633 cussion of the effects of this option.
6634 INDEPENDENT_STEP_TARGETS <step-target>...
6636 Generate custom targets for the specified steps
6637 and prevent these targets from having the usual
6638 dependencies applied to them. If this option is
6639 not specified, the default value is taken from the
6640 EP_INDEPENDENT_STEP_TARGETS directory property.
6641 This option is mostly useful for allowing individ‐
6642 ual steps to be driven independently, such as for
6643 a CDash setup where each step should be initiated
6644 and reported individually rather than as one whole
6645 build. See ExternalProject_Add_Step() below for
6646 further discussion of the effects of this option.
6647 Miscellaneous Options:
6649 LIST_SEPARATOR <sep>
6651 For any of the various ..._COMMAND options,
6652 replace ; with <sep> in the specified command
6653 lines. This can be useful where list variables may
6654 be given in commands where they should end up as
6655 space-separated arguments (<sep> would be a single
6656 space character string in this case).
6657 COMMAND <cmd>...
6659 Any of the other ..._COMMAND options can have
6660 additional commands appended to them by following
6661 them with as many COMMAND ... options as needed
6662 (generator expressions are supported). For exam‐
6663 ple:
6664 ExternalProject_Add(example
6666 ... # Download options, etc.
6667 BUILD_COMMAND ${CMAKE_COMMAND} -E echo "Starting $<CONFIG> build"
6668 COMMAND ${CMAKE_COMMAND} --build <BINARY_DIR> --config $<CONFIG>
6669 COMMAND ${CMAKE_COMMAND} -E echo "$<CONFIG> build complete"
6670 )
6671 It should also be noted that each build step is created via a
6673 call to ExternalProject_Add_Step(). See that command’s documen‐
6674 tation for the automatic substitutions that are supported for
6675 some options.
6676 Obtaining Project Properties
6678 ExternalProject_Get_Property
6679 The ExternalProject_Get_Property() function retrieves external
6680 project target properties:
6681 ExternalProject_Get_Property(<name> <prop1> [<prop2>...])
6683 The function stores property values in variables of the same
6685 name. Property names correspond to the keyword argument names of
6686 ExternalProject_Add(). For example, the source directory might
6687 be retrieved like so:
6688 ExternalProject_Get_property(myExtProj SOURCE_DIR)
6690 message("Source dir of myExtProj = ${SOURCE_DIR}")
6691 Explicit Step Management
6693 The ExternalProject_Add() function on its own is often sufficient for
6694 incorporating an external project into the main build. Certain scenar‐
6695 ios require additional work to implement desired behavior, such as
6696 adding in a custom step or making steps available as manually trigger‐
6697 able targets. The ExternalProject_Add_Step(), ExternalProject_Add_Step‐
6698 Targets() and ExternalProject_Add_StepDependencies functions provide
6699 the lower level control needed to implement such step-level capabili‐
6700 ties.
6701 ExternalProject_Add_Step
6703 The ExternalProject_Add_Step() function specifies an additional
6704 custom step for an external project defined by an earlier call
6705 to ExternalProject_Add():
6706 ExternalProject_Add_Step(<name> <step> [<option>...])
6708 <name> is the same as the name passed to the original call to
6710 ExternalProject_Add(). The specified <step> must not be one of
6711 the pre-defined steps (mkdir, download, update, skip-update,
6712 patch, configure, build, install or test). The supported options
6713 are:
6714 COMMAND <cmd>...
6716 The command line to be executed by this custom step (gen‐
6717 erator expressions are supported). This option can be
6718 repeated multiple times to specify multiple commands to
6719 be executed in order.
6720 COMMENT <text>...
6722 Text to be printed when the custom step executes.
6723 DEPENDEES <step>...
6725 Other steps (custom or pre-defined) on which this step
6726 depends.
6727 DEPENDERS <step>...
6729 Other steps (custom or pre-defined) that depend on this
6730 new custom step.
6731 DEPENDS <file>...
6733 Files on which this custom step depends.
6734 BYPRODUCTS <file>...
6736 Files that will be generated by this custom step but
6737 which might or might not have their modification time
6738 updated by subsequent builds. This list of files will
6739 ultimately be passed through as the BYPRODUCTS option to
6740 the add_custom_command() used to implement the custom
6741 step internally.
6742 ALWAYS <bool>
6744 When enabled, this option specifies that the custom step
6745 should always be run (i.e. that it is always considered
6746 out of date).
6747 EXCLUDE_FROM_MAIN <bool>
6749 When enabled, this option specifies that the external
6750 project’s main target does not depend on the custom step.
6751 WORKING_DIRECTORY <dir>
6753 Specifies the working directory to set before running the
6754 custom step’s command. If this option is not specified,
6755 the directory will be the value of the CMAKE_CUR‐
6756 RENT_BINARY_DIR at the point where ExternalPro‐
6757 ject_Add_Step() was called.
6758 LOG <bool>
6760 If set, this causes the output from the custom step to be
6761 captured to files in the external project’s STAMP_DIR.
6762 USES_TERMINAL <bool>
6764 If enabled, this gives the custom step direct access to
6765 the terminal if possible.
6766 The command line, comment, working directory and byproducts of
6768 every standard and custom step are processed to replace the
6769 tokens <SOURCE_DIR>, <SOURCE_SUBDIR>, <BINARY_DIR>,
6770 <INSTALL_DIR> <TMP_DIR>, <DOWNLOAD_DIR> and <DOWNLOADED_FILE>
6771 with their corresponding property values defined in the original
6772 call to ExternalProject_Add().
6773 ExternalProject_Add_StepTargets
6775 The ExternalProject_Add_StepTargets() function generates targets
6776 for the steps listed. The name of each created target will be of
6777 the form <name>-<step>:
6778 ExternalProject_Add_StepTargets(<name> [NO_DEPENDS] <step1> [<step2>...])
6780 Creating a target for a step allows it to be used as a depen‐
6782 dency of another target or to be triggered manually. Having tar‐
6783 gets for specific steps also allows them to be driven indepen‐
6784 dently of each other by specifying targets on build command
6785 lines. For example, you may be submitting to a sub-project based
6786 dashboard where you want to drive the configure portion of the
6787 build, then submit to the dashboard, followed by the build por‐
6788 tion, followed by tests. If you invoke a custom target that
6789 depends on a step halfway through the step dependency chain,
6790 then all the previous steps will also run to ensure everything
6791 is up to date.
6792 If the NO_DEPENDS option is specified, the step target will not
6794 depend on the dependencies of the external project (i.e. on any
6795 dependencies of the <name> custom target created by
6796 ExternalProject_Add()). This is usually safe for the download,
6797 update and patch steps, since they do not typically require that
6798 the dependencies are updated and built. Using NO_DEPENDS for any
6799 of the other pre-defined steps, however, may break parallel
6800 builds. Only use NO_DEPENDS where it is certain that the named
6801 steps genuinely do not have dependencies. For custom steps, con‐
6802 sider whether or not the custom commands require the dependen‐
6803 cies to be configured, built and installed.
6804 Internally, ExternalProject_Add() calls
6806 ExternalProject_Add_Step() to create each step. If any STEP_TAR‐
6807 GETS or INDEPENDENT_STEP_TARGETS were specified, then External‐
6808 Project_Add_StepTargets() will also be called after
6809 ExternalProject_Add_Step(). INDEPENDENT_STEP_TARGETS have the
6810 NO_DEPENDS option set, whereas STEP_TARGETS do not. Other than
6811 that, the two options result in ExternalProject_Add_StepTar‐
6812 gets() being called in the same way. Even if a step is not men‐
6813 tioned in either of those two options, ExternalProject_Add_Step‐
6814 Targets() can still be called later to manually define a target
6815 for the step.
6816 The STEP_TARGETS and INDEPENDENT_STEP_TARGETS options for
6818 ExternalProject_Add() are generally the easiest way to ensure
6819 targets are created for specific steps of interest. For custom
6820 steps, ExternalProject_Add_StepTargets() must be called explic‐
6821 itly if a target should also be created for that custom step. An
6822 alternative to these two options is to populate the EP_STEP_TAR‐
6823 GETS and EP_INDEPENDENT_STEP_TARGETS directory properties. These
6824 act as defaults for the step target options and can save having
6825 to repeatedly specify the same set of step targets when multiple
6826 external projects are being defined.
6827 ExternalProject_Add_StepDependencies
6829 The ExternalProject_Add_StepDependencies() function can be used
6830 to add dependencies to a step. The dependencies added must be
6831 targets CMake already knows about (these can be ordinary exe‐
6832 cutable or library targets, custom targets or even step targets
6833 of another external project):
6834 ExternalProject_Add_StepDependencies(<name> <step> <target1> [<target2>...])
6836 This function takes care to set both target and file level
6838 dependencies and will ensure that parallel builds will not
6839 break. It should be used instead of add_dependencies() whenever
6840 adding a dependency for some of the step targets generated by
6841 the ExternalProject module.
6842 Examples
6844 The following example shows how to download and build a hypothetical
6845 project called FooBar from github:
6846 include(ExternalProject)
6848 ExternalProject_Add(foobar
6849 GIT_REPOSITORY git@github.com:FooCo/FooBar.git
6850 GIT_TAG origin/release/1.2.3
6851 )
6852 For the sake of the example, also define a second hypothetical external
6854 project called SecretSauce, which is downloaded from a web server. Two
6855 URLs are given to take advantage of a faster internal network if avail‐
6856 able, with a fallback to a slower external server. The project is a
6857 typical Makefile project with no configure step, so some of the default
6858 commands are overridden. The build is only required to build the sauce
6859 target:
6860 find_program(MAKE_EXE NAMES gmake nmake make)
6862 ExternalProject_Add(secretsauce
6863 URL http://intranet.somecompany.com/artifacts/sauce-2.7.tgz
6864 https://www.somecompany.com/downloads/sauce-2.7.zip
6865 URL_HASH MD5=d41d8cd98f00b204e9800998ecf8427e
6866 CONFIGURE_COMMAND ""
6867 BUILD_COMMAND ${MAKE_EXE} sauce
6868 )
6869 Suppose the build step of secretsauce requires that foobar must already
6871 be built. This could be enforced like so:
6872 ExternalProject_Add_StepDependencies(secretsauce build foobar)
6874 Another alternative would be to create a custom target for foobar’s
6876 build step and make secretsauce depend on that rather than the whole
6877 foobar project. This would mean foobar only needs to be built, it
6878 doesn’t need to run its install or test steps before secretsauce can be
6879 built. The dependency can also be defined along with the secretsauce
6880 project:
6881 ExternalProject_Add_StepTargets(foobar build)
6883 ExternalProject_Add(secretsauce
6884 URL http://intranet.somecompany.com/artifacts/sauce-2.7.tgz
6885 https://www.somecompany.com/downloads/sauce-2.7.zip
6886 URL_HASH MD5=d41d8cd98f00b204e9800998ecf8427e
6887 CONFIGURE_COMMAND ""
6888 BUILD_COMMAND ${MAKE_EXE} sauce
6889 DEPENDS foobar-build
6890 )
6891 Instead of calling ExternalProject_Add_StepTargets(), the target could
6893 be defined along with the foobar project itself:
6894 ExternalProject_Add(foobar
6896 GIT_REPOSITORY git@github.com:FooCo/FooBar.git
6897 GIT_TAG origin/release/1.2.3
6898 STEP_TARGETS build
6899 )
6900 If many external projects should have the same set of step targets,
6902 setting a directory property may be more convenient. The build step
6903 target could be created automatically by setting the EP_STEP_TARGETS
6904 directory property before creating the external projects with
6905 ExternalProject_Add():
6906 set_property(DIRECTORY PROPERTY EP_STEP_TARGETS build)
6908 Lastly, suppose that secretsauce provides a script called makedoc which
6910 can be used to generate its own documentation. Further suppose that the
6911 script expects the output directory to be provided as the only parame‐
6912 ter and that it should be run from the secretsauce source directory. A
6913 custom step and a custom target to trigger the script can be defined
6914 like so:
6915 ExternalProject_Add_Step(secretsauce docs
6917 COMMAND <SOURCE_DIR>/makedoc <BINARY_DIR>
6918 WORKING_DIRECTORY <SOURCE_DIR>
6919 COMMENT "Building secretsauce docs"
6920 ALWAYS TRUE
6921 EXCLUDE_FROM_MAIN TRUE
6922 )
6923 ExternalProject_Add_StepTargets(secretsauce docs)
6924 The custom step could then be triggered from the main build like so:
6926 cmake --build . --target secretsauce-docs
6928 FeatureSummary
6930 Functions for generating a summary of enabled/disabled features.
6931 These functions can be used to generate a summary of enabled and dis‐
6933 abled packages and/or feature for a build tree such as:
6934 -- The following OPTIONAL packages have been found:
6936 LibXml2 (required version >= 2.4), XML processing lib, <http://xmlsoft.org>
6937 * Enables HTML-import in MyWordProcessor
6938 * Enables odt-export in MyWordProcessor
6939 PNG, A PNG image library., <http://www.libpng.org/pub/png/>
6940 * Enables saving screenshots
6941 -- The following OPTIONAL packages have not been found:
6942 Lua51, The Lua scripting language., <http://www.lua.org>
6943 * Enables macros in MyWordProcessor
6944 Foo, Foo provides cool stuff.
6945 Global Properties
6947 FeatureSummary_PKG_TYPES
6948 The global property FeatureSummary_PKG_TYPES defines the type of pack‐
6950 ages used by FeatureSummary.
6951 The order in this list is important, the first package type in the list
6953 is the least important, the last is the most important. the of a pack‐
6954 age can only be changed to higher types.
6955 The default package types are , RUNTIME, OPTIONAL, RECOMMENDED and
6957 REQUIRED, and their importance is RUNTIME < OPTIONAL < RECOMMENDED <
6958 REQUIRED.
6959 FeatureSummary_REQUIRED_PKG_TYPES
6961 The global property FeatureSummary_REQUIRED_PKG_TYPES defines which
6963 package types are required.
6964 If one or more package in this categories has not been found, CMake
6966 will abort when calling feature_summary() with the ‘FATAL_ON_MISS‐
6967 ING_REQUIRED_PACKAGES’ option enabled.
6968 The default value for this global property is REQUIRED.
6970 FeatureSummary_DEFAULT_PKG_TYPE
6972 The global property FeatureSummary_DEFAULT_PKG_TYPE defines which pack‐
6974 age type is the default one. When calling feature_summary(), if the
6975 user did not set the package type explicitly, the package will be
6976 assigned to this category.
6977 This value must be one of the types defined in the
6979 FeatureSummary_PKG_TYPES global property unless the package type is set
6980 for all the packages.
6981 The default value for this global property is OPTIONAL.
6983 FeatureSummary_<TYPE>_DESCRIPTION
6985 The global property FeatureSummary_<TYPE>_DESCRIPTION can be defined
6987 for each type to replace the type name with the specified string when‐
6988 ever the package type is used in an output string.
6989 If not set, the string “<TYPE> packages” is used.
6991 Functions
6993 feature_summary
6994 feature_summary( [FILENAME <file>]
6996 [APPEND]
6997 [VAR <variable_name>]
6998 [INCLUDE_QUIET_PACKAGES]
6999 [FATAL_ON_MISSING_REQUIRED_PACKAGES]
7000 [DESCRIPTION "<description>" | DEFAULT_DESCRIPTION]
7001 [QUIET_ON_EMPTY]
7002 WHAT (ALL
7003 | PACKAGES_FOUND | PACKAGES_NOT_FOUND
7004 | <TYPE>_PACKAGES_FOUND | <TYPE>_PACKAGES_NOT_FOUND
7005 | ENABLED_FEATURES | DISABLED_FEATURES)
7006 )
7007 The feature_summary() macro can be used to print information
7009 about enabled or disabled packages or features of a project. By
7010 default, only the names of the features/packages will be printed
7011 and their required version when one was specified. Use
7012 set_package_properties() to add more useful information, like
7013 e.g. a download URL for the respective package or their purpose
7014 in the project.
7015 The WHAT option is the only mandatory option. Here you specify
7017 what information will be printed:
7018 ALL print everything
7020 ENABLED_FEATURES
7022 the list of all features which are enabled
7023 DISABLED_FEATURES
7025 the list of all features which are disabled
7026 PACKAGES_FOUND
7028 the list of all packages which have been found
7029 PACKAGES_NOT_FOUND
7031 the list of all packages which have not been found
7032 For each package type <TYPE> defined by the
7034 FeatureSummary_PKG_TYPES global property, the following informa‐
7035 tion can also be used:
7036 <TYPE>_PACKAGES_FOUND
7038 only those packages which have been found which have the
7039 type <TYPE>
7040 <TYPE>_PACKAGES_NOT_FOUND
7042 only those packages which have not been found which have
7043 the type <TYPE>
7044 With the exception of the ALL value, these values can be com‐
7046 bined in order to customize the output. For example:
7047 feature_summary(WHAT ENABLED_FEATURES DISABLED_FEATURES)
7049 If a FILENAME is given, the information is printed into this
7051 file. If APPEND is used, it is appended to this file, otherwise
7052 the file is overwritten if it already existed. If the VAR
7053 option is used, the information is “printed” into the specified
7054 variable. If FILENAME is not used, the information is printed
7055 to the terminal. Using the DESCRIPTION option a description or
7056 headline can be set which will be printed above the actual con‐
7057 tent. If only one type of package was requested, no title is
7058 printed, unless it is explicitly set using either DESCRIPTION to
7059 use a custom string, or DEFAULT_DESCRIPTION to use a default
7060 title for the requested type. If INCLUDE_QUIET_PACKAGES is
7061 given, packages which have been searched with find_package(...
7062 QUIET) will also be listed. By default they are skipped. If
7063 FATAL_ON_MISSING_REQUIRED_PACKAGES is given, CMake will abort if
7064 a package which is marked as one of the package types listed in
7065 the FeatureSummary_REQUIRED_PKG_TYPES global property has not
7066 been found. The default value for the
7067 FeatureSummary_REQUIRED_PKG_TYPES global property is REQUIRED.
7068 The FeatureSummary_DEFAULT_PKG_TYPE global property can be modi‐
7070 fied to change the default package type assigned when not
7071 explicitly assigned by the user.
7072 If the QUIET_ON_EMPTY option is used, if only one type of pack‐
7074 age was requested, and no packages belonging to that category
7075 were found, then no output (including the DESCRIPTION) is
7076 printed or added to the VAR variable.
7077 Example 1, append everything to a file:
7079 include(FeatureSummary)
7081 feature_summary(WHAT ALL
7082 FILENAME ${CMAKE_BINARY_DIR}/all.log APPEND)
7083 Example 2, print the enabled features into the variable enabled‐
7085 FeaturesText, including QUIET packages:
7086 include(FeatureSummary)
7088 feature_summary(WHAT ENABLED_FEATURES
7089 INCLUDE_QUIET_PACKAGES
7090 DESCRIPTION "Enabled Features:"
7091 VAR enabledFeaturesText)
7092 message(STATUS "${enabledFeaturesText}")
7093 Example 3, change default package types and print only the cate‐
7095 gories that are not empty:
7096 include(FeatureSummary)
7098 set_property(GLOBAL APPEND PROPERTY FeatureSummary_PKG_TYPES BUILD)
7099 find_package(FOO)
7100 set_package_properties(FOO PROPERTIES TYPE BUILD)
7101 feature_summary(WHAT BUILD_PACKAGES_FOUND
7102 Description "Build tools found:"
7103 QUIET_ON_EMPTY)
7104 feature_summary(WHAT BUILD_PACKAGES_NOT_FOUND
7105 Description "Build tools not found:"
7106 QUIET_ON_EMPTY)
7107 set_package_properties
7109 set_package_properties(<name> PROPERTIES
7111 [ URL <url> ]
7112 [ DESCRIPTION <description> ]
7113 [ TYPE (RUNTIME|OPTIONAL|RECOMMENDED|REQUIRED) ]
7114 [ PURPOSE <purpose> ]
7115 )
7116 Use this macro to set up information about the named package,
7118 which can then be displayed via FEATURE_SUMMARY(). This can be
7119 done either directly in the Find-module or in the project which
7120 uses the module after the find_package() call. The features for
7121 which information can be set are added automatically by the
7122 find_package() command.
7123 URL <url>
7125 This should be the homepage of the package, or something
7126 similar. Ideally this is set already directly in the
7127 Find-module.
7128 DESCRIPTION <description>
7130 A short description what that package is, at most one
7131 sentence. Ideally this is set already directly in the
7132 Find-module.
7133 TYPE <type>
7135 What type of dependency has the using project on that
7136 package. Default is OPTIONAL. In this case it is a
7137 package which can be used by the project when available
7138 at buildtime, but it also work without. RECOMMENDED is
7139 similar to OPTIONAL, i.e. the project will build if the
7140 package is not present, but the functionality of the
7141 resulting binaries will be severely limited. If a
7142 REQUIRED package is not available at buildtime, the
7143 project may not even build. This can be combined with
7144 the FATAL_ON_MISSING_REQUIRED_PACKAGES argument for fea‐
7145 ture_summary(). Last, a RUNTIME package is a package
7146 which is actually not used at all during the build, but
7147 which is required for actually running the resulting
7148 binaries. So if such a package is missing, the project
7149 can still be built, but it may not work later on. If
7150 set_package_properties() is called multiple times for the
7151 same package with different TYPEs, the TYPE is only
7152 changed to higher TYPEs (RUNTIME < OPTIONAL < RECOMMENDED
7153 < REQUIRED), lower TYPEs are ignored. The TYPE property
7154 is project-specific, so it cannot be set by the Find-mod‐
7155 ule, but must be set in the project. Type accepted can
7156 be changed by setting the FeatureSummary_PKG_TYPES global
7157 property.
7158 PURPOSE <purpose>
7160 This describes which features this package enables in the
7161 project, i.e. it tells the user what functionality he
7162 gets in the resulting binaries. If set_package_proper‐
7163 ties() is called multiple times for a package, all PUR‐
7164 POSE properties are appended to a list of purposes of the
7165 package in the project. As the TYPE property, also the
7166 PURPOSE property is project-specific, so it cannot be set
7167 by the Find-module, but must be set in the project.
7168 Example for setting the info for a package:
7170 find_package(LibXml2)
7172 set_package_properties(LibXml2 PROPERTIES
7173 DESCRIPTION "A XML processing library."
7174 URL "http://xmlsoft.org/")
7175 # or
7176 set_package_properties(LibXml2 PROPERTIES
7177 TYPE RECOMMENDED
7178 PURPOSE "Enables HTML-import in MyWordProcessor")
7179 # or
7180 set_package_properties(LibXml2 PROPERTIES
7181 TYPE OPTIONAL
7182 PURPOSE "Enables odt-export in MyWordProcessor")
7183 find_package(DBUS)
7185 set_package_properties(DBUS PROPERTIES
7186 TYPE RUNTIME
7187 PURPOSE "Necessary to disable the screensaver during a presentation")
7188 add_feature_info
7190 add_feature_info(<name> <enabled> <description>)
7192 Use this macro to add information about a feature with the given
7194 <name>. <enabled> contains whether this feature is enabled or
7195 not. It can be a variable or a list of conditions. <descrip‐
7196 tion> is a text describing the feature. The information can be
7197 displayed using feature_summary() for ENABLED_FEATURES and DIS‐
7198 ABLED_FEATURES respectively.
7199 Example for setting the info for a feature:
7201 option(WITH_FOO "Help for foo" ON)
7203 add_feature_info(Foo WITH_FOO "The Foo feature provides very cool stuff.")
7204 Legacy Macros
7206 The following macros are provided for compatibility with previous CMake
7207 versions:
7208 set_package_info
7210 set_package_info(<name> <description> [ <url> [<purpose>] ])
7212 Use this macro to set up information about the named package,
7214 which can then be displayed via feature_summary(). This can be
7215 done either directly in the Find-module or in the project which
7216 uses the module after the find_package() call. The features for
7217 which information can be set are added automatically by the
7218 find_package() command.
7219 set_feature_info
7221 set_feature_info(<name> <description> [<url>])
7223 Does the same as:
7225 set_package_info(<name> <description> <url>)
7227 print_enabled_features
7229 print_enabled_features()
7231 Does the same as
7233 feature_summary(WHAT ENABLED_FEATURES DESCRIPTION "Enabled features:")
7235 print_disabled_features
7237 print_disabled_features()
7239 Does the same as
7241 feature_summary(WHAT DISABLED_FEATURES DESCRIPTION "Disabled features:")
7243 FetchContent
7245 Overview
7246 This module enables populating content at configure time via any method
7247 supported by the ExternalProject module. Whereas ExternalProject_Add()
7248 downloads at build time, the FetchContent module makes content avail‐
7249 able immediately, allowing the configure step to use the content in
7250 commands like add_subdirectory(), include() or file() operations.
7251 Content population details would normally be defined separately from
7253 the command that performs the actual population. Projects should also
7254 check whether the content has already been populated somewhere else in
7255 the project hierarchy. Typical usage would look something like this:
7256 FetchContent_Declare(
7258 googletest
7259 GIT_REPOSITORY https://github.com/google/googletest.git
7260 GIT_TAG release-1.8.0
7261 )
7262 FetchContent_GetProperties(googletest)
7264 if(NOT googletest_POPULATED)
7265 FetchContent_Populate(googletest)
7266 add_subdirectory(${googletest_SOURCE_DIR} ${googletest_BINARY_DIR})
7267 endif()
7268 When using the above pattern with a hierarchical project arrangement,
7270 projects at higher levels in the hierarchy are able to define or over‐
7271 ride the population details of content specified anywhere lower in the
7272 project hierarchy. The ability to detect whether content has already
7273 been populated ensures that even if multiple child projects want cer‐
7274 tain content to be available, the first one to populate it wins. The
7275 other child project can simply make use of the already available con‐
7276 tent instead of repeating the population for itself. See the Examples
7277 section which demonstrates this scenario.
7278 The FetchContent module also supports defining and populating content
7280 in a single call, with no check for whether the content has been popu‐
7281 lated elsewhere in the project already. This is a more low level oper‐
7282 ation and would not normally be the way the module is used, but it is
7283 sometimes useful as part of implementing some higher level feature or
7284 to populate some content in CMake’s script mode.
7285 Declaring Content Details
7287 FetchContent_Declare
7288 FetchContent_Declare(<name> <contentOptions>...)
7290 The FetchContent_Declare() function records the options that
7292 describe how to populate the specified content, but if such
7293 details have already been recorded earlier in this project
7294 (regardless of where in the project hierarchy), this and all
7295 later calls for the same content <name> are ignored. This
7296 “first to record, wins” approach is what allows hierarchical
7297 projects to have parent projects override content details of
7298 child projects.
7299 The content <name> can be any string without spaces, but good
7301 practice would be to use only letters, numbers and underscores.
7302 The name will be treated case-insensitively and it should be
7303 obvious for the content it represents, often being the name of
7304 the child project or the value given to its top level project()
7305 command (if it is a CMake project). For well-known public
7306 projects, the name should generally be the official name of the
7307 project. Choosing an unusual name makes it unlikely that other
7308 projects needing that same content will use the same name, lead‐
7309 ing to the content being populated multiple times.
7310 The <contentOptions> can be any of the download or update/patch
7312 options that the ExternalProject_Add() command understands. The
7313 configure, build, install and test steps are explicitly disabled
7314 and therefore options related to them will be ignored. In most
7315 cases, <contentOptions> will just be a couple of options defin‐
7316 ing the download method and method-specific details like a com‐
7317 mit tag or archive hash. For example:
7318 FetchContent_Declare(
7320 googletest
7321 GIT_REPOSITORY https://github.com/google/googletest.git
7322 GIT_TAG release-1.8.0
7323 )
7324 FetchContent_Declare(
7326 myCompanyIcons
7327 URL https://intranet.mycompany.com/assets/iconset_1.12.tar.gz
7328 URL_HASH 5588a7b18261c20068beabfb4f530b87
7329 )
7330 FetchContent_Declare(
7332 myCompanyCertificates
7333 SVN_REPOSITORY svn+ssh://svn.mycompany.com/srv/svn/trunk/certs
7334 SVN_REVISION -r12345
7335 )
7336 Populating The Content
7338 FetchContent_Populate
7339 FetchContent_Populate( <name> )
7341 In most cases, the only argument given to FetchContent_Popu‐
7343 late() is the <name>. When used this way, the command assumes
7344 the content details have been recorded by an earlier call to
7345 FetchContent_Declare(). The details are stored in a global
7346 property, so they are unaffected by things like variable or
7347 directory scope. Therefore, it doesn’t matter where in the
7348 project the details were previously declared, as long as they
7349 have been declared before the call to FetchContent_Populate().
7350 Those saved details are then used to construct a call to Exter‐
7351 nalProject_Add() in a private sub-build to perform the content
7352 population immediately. The implementation of ExternalPro‐
7353 ject_Add() ensures that if the content has already been popu‐
7354 lated in a previous CMake run, that content will be reused
7355 rather than repopulating them again. For the common case where
7356 population involves downloading content, the cost of the down‐
7357 load is only paid once.
7358 An internal global property records when a particular content
7360 population request has been processed. If FetchContent_Popu‐
7361 late() is called more than once for the same content name within
7362 a configure run, the second call will halt with an error.
7363 Projects can and should check whether content population has
7364 already been processed with the FetchContent_GetProperties()
7365 command before calling FetchContent_Populate().
7366 FetchContent_Populate() will set three variables in the scope of
7368 the caller; <lcName>_POPULATED, <lcName>_SOURCE_DIR and
7369 <lcName>_BINARY_DIR, where <lcName> is the lowercased <name>.
7370 <lcName>_POPULATED will always be set to True by the call.
7371 <lcName>_SOURCE_DIR is the location where the content can be
7372 found upon return (it will have already been populated), while
7373 <lcName>_BINARY_DIR is a directory intended for use as a corre‐
7374 sponding build directory. The main use case for the two direc‐
7375 tory variables is to call add_subdirectory() immediately after
7376 population, i.e.:
7377 FetchContent_Populate(FooBar ...)
7379 add_subdirectory(${foobar_SOURCE_DIR} ${foobar_BINARY_DIR})
7380 The values of the three variables can also be retrieved from
7382 anywhere in the project hierarchy using the
7383 FetchContent_GetProperties() command.
7384 A number of cache variables influence the behavior of all con‐
7386 tent population performed using details saved from a
7387 FetchContent_Declare() call:
7388 FETCHCONTENT_BASE_DIR
7390 In most cases, the saved details do not specify any
7391 options relating to the directories to use for the inter‐
7392 nal sub-build, final source and build areas. It is gen‐
7393 erally best to leave these decisions up to the FetchCon‐
7394 tent module to handle on the project’s behalf. The
7395 FETCHCONTENT_BASE_DIR cache variable controls the point
7396 under which all content population directories are col‐
7397 lected, but in most cases developers would not need to
7398 change this. The default location is
7399 ${CMAKE_BINARY_DIR}/_deps, but if developers change this
7400 value, they should aim to keep the path short and just
7401 below the top level of the build tree to avoid running
7402 into path length problems on Windows.
7403 FETCHCONTENT_QUIET
7405 The logging output during population can be quite ver‐
7406 bose, making the configure stage quite noisy. This cache
7407 option (ON by default) hides all population output unless
7408 an error is encountered. If experiencing problems with
7409 hung downloads, temporarily switching this option off may
7410 help diagnose which content population is causing the
7411 issue.
7412 FETCHCONTENT_FULLY_DISCONNECTED
7414 When this option is enabled, no attempt is made to down‐
7415 load or update any content. It is assumed that all con‐
7416 tent has already been populated in a previous run or the
7417 source directories have been pointed at existing contents
7418 the developer has provided manually (using options
7419 described further below). When the developer knows that
7420 no changes have been made to any content details, turning
7421 this option ON can significantly speed up the configure
7422 stage. It is OFF by default.
7423 FETCHCONTENT_UPDATES_DISCONNECTED
7425 This is a less severe download/update control compared to
7426 FETCHCONTENT_FULLY_DISCONNECTED. Instead of bypassing
7427 all download and update logic, the FETCHCON‐
7428 TENT_UPDATES_DISCONNECTED only disables the update stage.
7429 Therefore, if content has not been downloaded previously,
7430 it will still be downloaded when this option is enabled.
7431 This can speed up the configure stage, but not as much as
7432 FETCHCONTENT_FULLY_DISCONNECTED. It is OFF by default.
7433 In addition to the above cache variables, the following cache
7435 variables are also defined for each content name (<ucName> is
7436 the uppercased value of <name>):
7437 FETCHCONTENT_SOURCE_DIR_<ucName>
7439 If this is set, no download or update steps are performed
7440 for the specified content and the <lcName>_SOURCE_DIR
7441 variable returned to the caller is pointed at this loca‐
7442 tion. This gives developers a way to have a separate
7443 checkout of the content that they can modify freely with‐
7444 out interference from the build. The build simply uses
7445 that existing source, but it still defines
7446 <lcName>_BINARY_DIR to point inside its own build area.
7447 Developers are strongly encouraged to use this mechanism
7448 rather than editing the sources populated in the default
7449 location, as changes to sources in the default location
7450 can be lost when content population details are changed
7451 by the project.
7452 FETCHCONTENT_UPDATES_DISCONNECTED_<ucName>
7454 This is the per-content equivalent of FETCHCON‐
7455 TENT_UPDATES_DISCONNECTED. If the global option or this
7456 option is ON, then updates will be disabled for the named
7457 content. Disabling updates for individual content can be
7458 useful for content whose details rarely change, while
7459 still leaving other frequently changing content with
7460 updates enabled.
7461 The FetchContent_Populate() command also supports a syntax
7463 allowing the content details to be specified directly rather
7464 than using any saved details. This is more low-level and use of
7465 this form is generally to be avoided in favour of using saved
7466 content details as outlined above. Nevertheless, in certain
7467 situations it can be useful to invoke the content population as
7468 an isolated operation (typically as part of implementing some
7469 other higher level feature or when using CMake in script mode):
7470 FetchContent_Populate( <name>
7472 [QUIET]
7473 [SUBBUILD_DIR <subBuildDir>]
7474 [SOURCE_DIR <srcDir>]
7475 [BINARY_DIR <binDir>]
7476 ...
7477 )
7478 This form has a number of key differences to that where only
7480 <name> is provided:
7481 · All required population details are assumed to have been pro‐
7483 vided directly in the call to FetchContent_Populate(). Any
7484 saved details for <name> are ignored.
7485 · No check is made for whether content for <name> has already
7487 been populated.
7488 · No global property is set to record that the population has
7490 occurred.
7491 · No global properties record the source or binary directories
7493 used for the populated content.
7494 · The FETCHCONTENT_FULLY_DISCONNECTED and FETCHCON‐
7496 TENT_UPDATES_DISCONNECTED cache variables are ignored.
7497 The <lcName>_SOURCE_DIR and <lcName>_BINARY_DIR variables are
7499 still returned to the caller, but since these locations are not
7500 stored as global properties when this form is used, they are
7501 only available to the calling scope and below rather than the
7502 entire project hierarchy. No <lcName>_POPULATED variable is set
7503 in the caller’s scope with this form.
7504 The supported options for FetchContent_Populate() are the same
7506 as those for FetchContent_Declare(). Those few options shown
7507 just above are either specific to FetchContent_Populate() or
7508 their behavior is slightly modified from how ExternalPro‐
7509 ject_Add() treats them.
7510 QUIET The QUIET option can be given to hide the output associ‐
7512 ated with populating the specified content. If the popu‐
7513 lation fails, the output will be shown regardless of
7514 whether this option was given or not so that the cause of
7515 the failure can be diagnosed. The global FETCHCON‐
7516 TENT_QUIET cache variable has no effect on FetchCon‐
7517 tent_Populate() calls where the content details are pro‐
7518 vided directly.
7519 SUBBUILD_DIR
7521 The SUBBUILD_DIR argument can be provided to change the
7522 location of the sub-build created to perform the popula‐
7523 tion. The default value is ${CMAKE_CUR‐
7524 RENT_BINARY_DIR}/<lcName>-subbuild and it would be
7525 unusual to need to override this default. If a relative
7526 path is specified, it will be interpreted as relative to
7527 CMAKE_CURRENT_BINARY_DIR.
7528 SOURCE_DIR, BINARY_DIR
7530 The SOURCE_DIR and BINARY_DIR arguments are supported by
7531 ExternalProject_Add(), but different default values are
7532 used by FetchContent_Populate(). SOURCE_DIR defaults to
7533 ${CMAKE_CURRENT_BINARY_DIR}/<lcName>-src and BINARY_DIR
7534 defaults to ${CMAKE_CURRENT_BINARY_DIR}/<lcName>-build.
7535 If a relative path is specified, it will be interpreted
7536 as relative to CMAKE_CURRENT_BINARY_DIR.
7537 In addition to the above explicit options, any other unrecog‐
7539 nized options are passed through unmodified to ExternalPro‐
7540 ject_Add() to perform the download, patch and update steps. The
7541 following options are explicitly prohibited (they are disabled
7542 by the FetchContent_Populate() command):
7543 · CONFIGURE_COMMAND
7545 · BUILD_COMMAND
7547 · INSTALL_COMMAND
7549 · TEST_COMMAND
7551 If using FetchContent_Populate() within CMake’s script mode, be
7553 aware that the implementation sets up a sub-build which there‐
7554 fore requires a CMake generator and build tool to be available.
7555 If these cannot be found by default, then the CMAKE_GENERATOR
7556 and/or CMAKE_MAKE_PROGRAM variables will need to be set appro‐
7557 priately on the command line invoking the script.
7558 Retrieve Population Properties
7560 FetchContent_GetProperties
7561 When using saved content details, a call to
7562 FetchContent_Populate() records information in global properties
7563 which can be queried at any time. This information includes the
7564 source and binary directories associated with the content and
7565 also whether or not the content population has been processed
7566 during the current configure run.
7567 FetchContent_GetProperties( <name>
7569 [SOURCE_DIR <srcDirVar>]
7570 [BINARY_DIR <binDirVar>]
7571 [POPULATED <doneVar>]
7572 )
7573 The SOURCE_DIR, BINARY_DIR and POPULATED options can be used to
7575 specify which properties should be retrieved. Each option
7576 accepts a value which is the name of the variable in which to
7577 store that property. Most of the time though, only <name> is
7578 given, in which case the call will then set the same variables
7579 as a call to FetchContent_Populate(name). This allows the fol‐
7580 lowing canonical pattern to be used, which ensures that the rel‐
7581 evant variables will always be defined regardless of whether or
7582 not the population has been performed elsewhere in the project
7583 already:
7584 FetchContent_GetProperties(foobar)
7586 if(NOT foobar_POPULATED)
7587 FetchContent_Populate(foobar)
7588 # Set any custom variables, etc. here, then
7590 # populate the content as part of this build
7591 add_subdirectory(${foobar_SOURCE_DIR} ${foobar_BINARY_DIR})
7593 endif()
7594 The above pattern allows other parts of the overall project
7596 hierarchy to re-use the same content and ensure that it is only
7597 populated once.
7598 Examples
7600 Consider a project hierarchy where projA is the top level project and
7601 it depends on projects projB and projC. Both projB and projC can be
7602 built standalone and they also both depend on another project projD.
7603 For simplicity, this example will assume that all four projects are
7604 available on a company git server. The CMakeLists.txt of each project
7605 might have sections like the following:
7606 projA:
7608 include(FetchContent)
7610 FetchContent_Declare(
7611 projB
7612 GIT_REPOSITORY git@mycompany.com/git/projB.git
7613 GIT_TAG 4a89dc7e24ff212a7b5167bef7ab079d
7614 )
7615 FetchContent_Declare(
7616 projC
7617 GIT_REPOSITORY git@mycompany.com/git/projC.git
7618 GIT_TAG 4ad4016bd1d8d5412d135cf8ceea1bb9
7619 )
7620 FetchContent_Declare(
7621 projD
7622 GIT_REPOSITORY git@mycompany.com/git/projD.git
7623 GIT_TAG origin/integrationBranch
7624 )
7625 FetchContent_GetProperties(projB)
7627 if(NOT projb_POPULATED)
7628 FetchContent_Populate(projB)
7629 add_subdirectory(${projb_SOURCE_DIR} ${projb_BINARY_DIR})
7630 endif()
7631 FetchContent_GetProperties(projC)
7633 if(NOT projc_POPULATED)
7634 FetchContent_Populate(projC)
7635 add_subdirectory(${projc_SOURCE_DIR} ${projc_BINARY_DIR})
7636 endif()
7637 projB:
7639 include(FetchContent)
7641 FetchContent_Declare(
7642 projD
7643 GIT_REPOSITORY git@mycompany.com/git/projD.git
7644 GIT_TAG 20b415f9034bbd2a2e8216e9a5c9e632
7645 )
7646 FetchContent_GetProperties(projD)
7648 if(NOT projd_POPULATED)
7649 FetchContent_Populate(projD)
7650 add_subdirectory(${projd_SOURCE_DIR} ${projd_BINARY_DIR})
7651 endif()
7652 projC:
7654 include(FetchContent)
7656 FetchContent_Declare(
7657 projD
7658 GIT_REPOSITORY git@mycompany.com/git/projD.git
7659 GIT_TAG 7d9a17ad2c962aa13e2fbb8043fb6b8a
7660 )
7661 FetchContent_GetProperties(projD)
7663 if(NOT projd_POPULATED)
7664 FetchContent_Populate(projD)
7665 add_subdirectory(${projd_SOURCE_DIR} ${projd_BINARY_DIR})
7666 endif()
7667 A few key points should be noted in the above:
7669 · projB and projC define different content details for projD, but projA
7671 also defines a set of content details for projD and because projA
7672 will define them first, the details from projB and projC will not be
7673 used. The override details defined by projA are not required to
7674 match either of those from projB or projC, but it is up to the higher
7675 level project to ensure that the details it does define still make
7676 sense for the child projects.
7677 · While projA defined content details for projD, it did not need to
7679 explicitly call FetchContent_Populate(projD) itself. Instead, it
7680 leaves that to a child project to do (in this case it will be projB
7681 since it is added to the build ahead of projC). If projA needed to
7682 customize how the projD content was brought into the build as well
7683 (e.g. define some CMake variables before calling add_subdirectory()
7684 after populating), it would do the call to FetchContent_Populate(),
7685 etc. just as it did for the projB and projC content. For higher
7686 level projects, it is usually enough to just define the override con‐
7687 tent details and leave the actual population to the child projects.
7688 This saves repeating the same thing at each level of the project
7689 hierarchy unnecessarily.
7690 · Even though projA is the top level project in this example, it still
7692 checks whether projB and projC have already been populated before
7693 going ahead to do those populations. This makes projA able to be
7694 more easily incorporated as a child of some other higher level
7695 project in the future if required. Always protect a call to
7696 FetchContent_Populate() with a check to FetchContent_GetProperties(),
7697 even in what may be considered a top level project at the time.
7698 The following example demonstrates how one might download and unpack a
7700 firmware tarball using CMake’s script mode. The call to
7701 FetchContent_Populate() specifies all the content details and the
7702 unpacked firmware will be placed in a firmware directory below the cur‐
7703 rent working directory.
7704 getFirmware.cmake:
7706 # NOTE: Intended to be run in script mode with cmake -P
7708 include(FetchContent)
7709 FetchContent_Populate(
7710 firmware
7711 URL https://mycompany.com/assets/firmware-1.23-arm.tar.gz
7712 URL_HASH MD5=68247684da89b608d466253762b0ff11
7713 SOURCE_DIR firmware
7714 )
7715 FindALSA
7717 Find alsa
7718 Find the alsa libraries (asound)
7720 This module defines the following variables:
7722 ALSA_FOUND - True if ALSA_INCLUDE_DIR & ALSA_LIBRARY are found
7723 ALSA_LIBRARIES - Set when ALSA_LIBRARY is found
7724 ALSA_INCLUDE_DIRS - Set when ALSA_INCLUDE_DIR is found
7725 ALSA_INCLUDE_DIR - where to find asoundlib.h, etc.
7727 ALSA_LIBRARY - the asound library
7728 ALSA_VERSION_STRING - the version of alsa found (since CMake 2.8.8)
7729 FindArmadillo
7731 Find Armadillo
7732 Find the Armadillo C++ library
7734 Using Armadillo:
7736 find_package(Armadillo REQUIRED)
7738 include_directories(${ARMADILLO_INCLUDE_DIRS})
7739 add_executable(foo foo.cc)
7740 target_link_libraries(foo ${ARMADILLO_LIBRARIES})
7741 This module sets the following variables:
7743 ARMADILLO_FOUND - set to true if the library is found
7745 ARMADILLO_INCLUDE_DIRS - list of required include directories
7746 ARMADILLO_LIBRARIES - list of libraries to be linked
7747 ARMADILLO_VERSION_MAJOR - major version number
7748 ARMADILLO_VERSION_MINOR - minor version number
7749 ARMADILLO_VERSION_PATCH - patch version number
7750 ARMADILLO_VERSION_STRING - version number as a string (ex: "1.0.4")
7751 ARMADILLO_VERSION_NAME - name of the version (ex: "Antipodean Antileech")
7752 FindASPELL
7754 Try to find ASPELL
7755 Once done this will define
7757 ASPELL_FOUND - system has ASPELL
7759 ASPELL_EXECUTABLE - the ASPELL executable
7760 ASPELL_INCLUDE_DIR - the ASPELL include directory
7761 ASPELL_LIBRARIES - The libraries needed to use ASPELL
7762 ASPELL_DEFINITIONS - Compiler switches required for using ASPELL
7763 FindAVIFile
7765 Locate AVIFILE library and include paths
7766 AVIFILE (http://avifile.sourceforge.net/)is a set of libraries for i386
7768 machines to use various AVI codecs. Support is limited beyond Linux.
7769 Windows provides native AVI support, and so doesn’t need this library.
7770 This module defines
7771 AVIFILE_INCLUDE_DIR, where to find avifile.h , etc.
7773 AVIFILE_LIBRARIES, the libraries to link against
7774 AVIFILE_DEFINITIONS, definitions to use when compiling
7775 AVIFILE_FOUND, If false, don't try to use AVIFILE
7776 FindBISON
7778 Find bison executable and provide a macro to generate custom build
7779 rules.
7780 The module defines the following variables:
7782 BISON_EXECUTABLE
7784 path to the bison program
7785 BISON_VERSION
7787 version of bison
7788 BISON_FOUND
7790 true if the program was found
7791 The minimum required version of bison can be specified using the stan‐
7793 dard CMake syntax, e.g. find_package(BISON 2.1.3).
7794 If bison is found, the module defines the macro:
7796 BISON_TARGET(<Name> <YaccInput> <CodeOutput>
7798 [COMPILE_FLAGS <flags>]
7799 [DEFINES_FILE <file>]
7800 [VERBOSE [<file>]]
7801 [REPORT_FILE <file>]
7802 )
7803 which will create a custom rule to generate a parser. <YaccInput> is
7805 the path to a yacc file. <CodeOutput> is the name of the source file
7806 generated by bison. A header file is also be generated, and contains
7807 the token list.
7808 The options are:
7810 COMPILE_FLAGS <flags>
7812 Specify flags to be added to the bison command line.
7813 DEFINES_FILE <file>
7815 Specify a non-default header <file> to be generated by bison.
7816 VERBOSE [<file>]
7818 Tell bison to write a report file of the grammar and parser. If
7819 <file> is given, it specifies path the report file is copied to.
7820 [<file>] is left for backward compatibility of this module. Use
7821 VERBOSE REPORT_FILE <file>.
7822 REPORT_FILE <file>
7824 Specify a non-default report <file>, if generated.
7825 The macro defines the following variables:
7827 BISON_<Name>_DEFINED
7829 true is the macro ran successfully
7830 BISON_<Name>_INPUT
7832 The input source file, an alias for <YaccInput>
7833 BISON_<Name>_OUTPUT_SOURCE
7835 The source file generated by bison
7836 BISON_<Name>_OUTPUT_HEADER
7838 The header file generated by bison
7839 BISON_<Name>_OUTPUTS
7841 All files generated by bison including the source, the header
7842 and the report
7843 BISON_<Name>_COMPILE_FLAGS
7845 Options used in the bison command line
7846 Example usage:
7848 find_package(BISON)
7850 BISON_TARGET(MyParser parser.y ${CMAKE_CURRENT_BINARY_DIR}/parser.cpp
7851 DEFINES_FILE ${CMAKE_CURRENT_BINARY_DIR}/parser.h)
7852 add_executable(Foo main.cpp ${BISON_MyParser_OUTPUTS})
7853 FindBLAS
7855 Find BLAS library
7856 This module finds an installed fortran library that implements the BLAS
7858 linear-algebra interface (see http://www.netlib.org/blas/). The list
7859 of libraries searched for is taken from the autoconf macro file,
7860 acx_blas.m4 (distributed at
7861 http://ac-archive.sourceforge.net/ac-archive/acx_blas.html).
7862 This module sets the following variables:
7864 BLAS_FOUND - set to true if a library implementing the BLAS interface
7866 is found
7867 BLAS_LINKER_FLAGS - uncached list of required linker flags (excluding -l
7868 and -L).
7869 BLAS_LIBRARIES - uncached list of libraries (using full path name) to
7870 link against to use BLAS
7871 BLAS95_LIBRARIES - uncached list of libraries (using full path name)
7872 to link against to use BLAS95 interface
7873 BLAS95_FOUND - set to true if a library implementing the BLAS f95 interface
7874 is found
7875 The following variables can be used to control this module:
7877 BLA_STATIC if set on this determines what kind of linkage we do (static)
7879 BLA_VENDOR if set checks only the specified vendor, if not set checks
7880 all the possibilities
7881 BLA_F95 if set on tries to find the f95 interfaces for BLAS/LAPACK
7882 BLA_PREFER_PKGCONFIG if set pkg-config will be used to search for a BLAS
7883 library first and if one is found that is preferred
7884 List of vendors (BLA_VENDOR) valid in this module:
7886 · Goto
7888 · OpenBLAS
7890 · FLAME
7892 · ATLAS PhiPACK
7894 · CXML
7896 · DXML
7898 · SunPerf
7900 · SCSL
7902 · SGIMATH
7904 · IBMESSL
7906 · Intel10_32 (intel mkl v10 32 bit)
7908 · Intel10_64lp (intel mkl v10 64 bit, lp thread model, lp64 model)
7910 · Intel10_64lp_seq (intel mkl v10 64 bit, sequential code, lp64 model)
7912 · Intel (older versions of mkl 32 and 64 bit)
7914 · ACML
7916 · ACML_MP
7918 · ACML_GPU
7920 · Apple
7922 · NAS
7924 · Generic
7926 NOTE:
7928 C/CXX should be enabled to use Intel mkl
7929 FindBacktrace
7931 Find provider for backtrace(3).
7932 Checks if OS supports backtrace(3) via either libc or custom library.
7934 This module defines the following variables:
7935 Backtrace_HEADER
7937 The header file needed for backtrace(3). Cached. Could be
7938 forcibly set by user.
7939 Backtrace_INCLUDE_DIRS
7941 The include directories needed to use backtrace(3) header.
7942 Backtrace_LIBRARIES
7944 The libraries (linker flags) needed to use backtrace(3), if any.
7945 Backtrace_FOUND
7947 Is set if and only if backtrace(3) support detected.
7948 The following cache variables are also available to set or use:
7950 Backtrace_LIBRARY
7952 The external library providing backtrace, if any.
7953 Backtrace_INCLUDE_DIR
7955 The directory holding the backtrace(3) header.
7956 Typical usage is to generate of header file using configure_file() with
7958 the contents like the following:
7959 #cmakedefine01 Backtrace_FOUND
7961 #if Backtrace_FOUND
7962 # include <${Backtrace_HEADER}>
7963 #endif
7964 And then reference that generated header file in actual source.
7966 FindBoost
7968 Find Boost include dirs and libraries
7969 Use this module by invoking find_package with the form:
7971 find_package(Boost
7973 [version] [EXACT] # Minimum or EXACT version e.g. 1.67.0
7974 [REQUIRED] # Fail with error if Boost is not found
7975 [COMPONENTS <libs>...] # Boost libraries by their canonical name
7976 # e.g. "date_time" for "libboost_date_time"
7977 [OPTIONAL_COMPONENTS <libs>...]
7978 # Optional Boost libraries by their canonical name)
7979 ) # e.g. "date_time" for "libboost_date_time"
7980 This module finds headers and requested component libraries OR a CMake
7982 package configuration file provided by a “Boost CMake” build. For the
7983 latter case skip to the “Boost CMake” section below. For the former
7984 case results are reported in variables:
7985 Boost_FOUND - True if headers and requested libraries were found
7987 Boost_INCLUDE_DIRS - Boost include directories
7988 Boost_LIBRARY_DIRS - Link directories for Boost libraries
7989 Boost_LIBRARIES - Boost component libraries to be linked
7990 Boost_<C>_FOUND - True if component <C> was found (<C> is upper-case)
7991 Boost_<C>_LIBRARY - Libraries to link for component <C> (may include
7992 target_link_libraries debug/optimized keywords)
7993 Boost_VERSION - BOOST_VERSION value from boost/version.hpp
7994 Boost_LIB_VERSION - Version string appended to library filenames
7995 Boost_MAJOR_VERSION - Boost major version number (X in X.y.z)
7996 Boost_MINOR_VERSION - Boost minor version number (Y in x.Y.z)
7997 Boost_SUBMINOR_VERSION - Boost subminor version number (Z in x.y.Z)
7998 Boost_LIB_DIAGNOSTIC_DEFINITIONS (Windows)
7999 - Pass to add_definitions() to have diagnostic
8000 information about Boost's automatic linking
8001 displayed during compilation
8002 Note that Boost Python components require a Python version suffix
8004 (Boost 1.67 and later), e.g. python36 or python27 for the versions
8005 built against Python 3.6 and 2.7, respectively. This also applies to
8006 additional components using Python including mpi_python and numpy.
8007 Earlier Boost releases may use distribution-specific suffixes such as
8008 2, 3 or 2.7. These may also be used as suffixes, but note that they
8009 are not portable.
8010 This module reads hints about search locations from variables:
8012 BOOST_ROOT - Preferred installation prefix
8014 (or BOOSTROOT)
8015 BOOST_INCLUDEDIR - Preferred include directory e.g. <prefix>/include
8016 BOOST_LIBRARYDIR - Preferred library directory e.g. <prefix>/lib
8017 Boost_NO_SYSTEM_PATHS - Set to ON to disable searching in locations not
8018 specified by these hint variables. Default is OFF.
8019 Boost_ADDITIONAL_VERSIONS
8020 - List of Boost versions not known to this module
8021 (Boost install locations may contain the version)
8022 and saves search results persistently in CMake cache entries:
8024 Boost_INCLUDE_DIR - Directory containing Boost headers
8026 Boost_LIBRARY_DIR_RELEASE - Directory containing release Boost libraries
8027 Boost_LIBRARY_DIR_DEBUG - Directory containing debug Boost libraries
8028 Boost_<C>_LIBRARY_DEBUG - Component <C> library debug variant
8029 Boost_<C>_LIBRARY_RELEASE - Component <C> library release variant
8030 The following IMPORTED targets are also defined:
8032 Boost::boost - Target for header-only dependencies
8034 (Boost include directory)
8035 Boost::<C> - Target for specific component dependency
8036 (shared or static library); <C> is lower-
8037 case
8038 Boost::diagnostic_definitions - interface target to enable diagnostic
8039 information about Boost's automatic linking
8040 during compilation (adds BOOST_LIB_DIAGNOSTIC)
8041 Boost::disable_autolinking - interface target to disable automatic
8042 linking with MSVC (adds BOOST_ALL_NO_LIB)
8043 Boost::dynamic_linking - interface target to enable dynamic linking
8044 linking with MSVC (adds BOOST_ALL_DYN_LINK)
8045 Implicit dependencies such as Boost::filesystem requiring Boost::system
8047 will be automatically detected and satisfied, even if system is not
8048 specified when using find_package and if Boost::system is not added to
8049 target_link_libraries. If using Boost::thread, then Threads::Threads
8050 will also be added automatically.
8051 It is important to note that the imported targets behave differently
8053 than variables created by this module: multiple calls to find_pack‐
8054 age(Boost) in the same directory or sub-directories with different
8055 options (e.g. static or shared) will not override the values of the
8056 targets created by the first call.
8057 Users may set these hints or results as cache entries. Projects should
8059 not read these entries directly but instead use the above result vari‐
8060 ables. Note that some hint names start in upper-case “BOOST”. One may
8061 specify these as environment variables if they are not specified as
8062 CMake variables or cache entries.
8063 This module first searches for the Boost header files using the above
8065 hint variables (excluding BOOST_LIBRARYDIR) and saves the result in
8066 Boost_INCLUDE_DIR. Then it searches for requested component libraries
8067 using the above hints (excluding BOOST_INCLUDEDIR and Boost_ADDI‐
8068 TIONAL_VERSIONS), “lib” directories near Boost_INCLUDE_DIR, and the
8069 library name configuration settings below. It saves the library direc‐
8070 tories in Boost_LIBRARY_DIR_DEBUG and Boost_LIBRARY_DIR_RELEASE and
8071 individual library locations in Boost_<C>_LIBRARY_DEBUG and
8072 Boost_<C>_LIBRARY_RELEASE. When one changes settings used by previous
8073 searches in the same build tree (excluding environment variables) this
8074 module discards previous search results affected by the changes and
8075 searches again.
8076 Boost libraries come in many variants encoded in their file name.
8078 Users or projects may tell this module which variant to find by setting
8079 variables:
8080 Boost_USE_DEBUG_LIBS - Set to ON or OFF to specify whether to search
8082 and use the debug libraries. Default is ON.
8083 Boost_USE_RELEASE_LIBS - Set to ON or OFF to specify whether to search
8084 and use the release libraries. Default is ON.
8085 Boost_USE_MULTITHREADED - Set to OFF to use the non-multithreaded
8086 libraries ('mt' tag). Default is ON.
8087 Boost_USE_STATIC_LIBS - Set to ON to force the use of the static
8088 libraries. Default is OFF.
8089 Boost_USE_STATIC_RUNTIME - Set to ON or OFF to specify whether to use
8090 libraries linked statically to the C++ runtime
8091 ('s' tag). Default is platform dependent.
8092 Boost_USE_DEBUG_RUNTIME - Set to ON or OFF to specify whether to use
8093 libraries linked to the MS debug C++ runtime
8094 ('g' tag). Default is ON.
8095 Boost_USE_DEBUG_PYTHON - Set to ON to use libraries compiled with a
8096 debug Python build ('y' tag). Default is OFF.
8097 Boost_USE_STLPORT - Set to ON to use libraries compiled with
8098 STLPort ('p' tag). Default is OFF.
8099 Boost_USE_STLPORT_DEPRECATED_NATIVE_IOSTREAMS
8100 - Set to ON to use libraries compiled with
8101 STLPort deprecated "native iostreams"
8102 ('n' tag). Default is OFF.
8103 Boost_COMPILER - Set to the compiler-specific library suffix
8104 (e.g. "-gcc43"). Default is auto-computed
8105 for the C++ compiler in use. A list may be
8106 used if multiple compatible suffixes should
8107 be tested for, in decreasing order of
8108 preference.
8109 Boost_THREADAPI - Suffix for "thread" component library name,
8110 such as "pthread" or "win32". Names with
8111 and without this suffix will both be tried.
8112 Boost_NAMESPACE - Alternate namespace used to build boost with
8113 e.g. if set to "myboost", will search for
8114 myboost_thread instead of boost_thread.
8115 Other variables one may set to control this module are:
8117 Boost_DEBUG - Set to ON to enable debug output from FindBoost.
8119 Please enable this before filing any bug report.
8120 Boost_DETAILED_FAILURE_MSG
8121 - Set to ON to add detailed information to the
8122 failure message even when the REQUIRED option
8123 is not given to the find_package call.
8124 Boost_REALPATH - Set to ON to resolve symlinks for discovered
8125 libraries to assist with packaging. For example,
8126 the "system" component library may be resolved to
8127 "/usr/lib/libboost_system.so.1.67.0" instead of
8128 "/usr/lib/libboost_system.so". This does not
8129 affect linking and should not be enabled unless
8130 the user needs this information.
8131 Boost_LIBRARY_DIR - Default value for Boost_LIBRARY_DIR_RELEASE and
8132 Boost_LIBRARY_DIR_DEBUG.
8133 On Visual Studio and Borland compilers Boost headers request automatic
8135 linking to corresponding libraries. This requires matching libraries
8136 to be linked explicitly or available in the link library search path.
8137 In this case setting Boost_USE_STATIC_LIBS to OFF may not achieve
8138 dynamic linking. Boost automatic linking typically requests static
8139 libraries with a few exceptions (such as Boost.Python). Use:
8140 add_definitions(${Boost_LIB_DIAGNOSTIC_DEFINITIONS})
8142 to ask Boost to report information about automatic linking requests.
8144 Example to find Boost headers only:
8146 find_package(Boost 1.36.0)
8148 if(Boost_FOUND)
8149 include_directories(${Boost_INCLUDE_DIRS})
8150 add_executable(foo foo.cc)
8151 endif()
8152 Example to find Boost libraries and use imported targets:
8154 find_package(Boost 1.56 REQUIRED COMPONENTS
8156 date_time filesystem iostreams)
8157 add_executable(foo foo.cc)
8158 target_link_libraries(foo Boost::date_time Boost::filesystem
8159 Boost::iostreams)
8160 Example to find Boost Python 3.6 libraries and use imported targets:
8162 find_package(Boost 1.67 REQUIRED COMPONENTS
8164 python36 numpy36)
8165 add_executable(foo foo.cc)
8166 target_link_libraries(foo Boost::python36 Boost::numpy36)
8167 Example to find Boost headers and some static (release only) libraries:
8169 set(Boost_USE_STATIC_LIBS ON) # only find static libs
8171 set(Boost_USE_DEBUG_LIBS OFF) # ignore debug libs and
8172 set(Boost_USE_RELEASE_LIBS ON) # only find release libs
8173 set(Boost_USE_MULTITHREADED ON)
8174 set(Boost_USE_STATIC_RUNTIME OFF)
8175 find_package(Boost 1.66.0 COMPONENTS date_time filesystem system ...)
8176 if(Boost_FOUND)
8177 include_directories(${Boost_INCLUDE_DIRS})
8178 add_executable(foo foo.cc)
8179 target_link_libraries(foo ${Boost_LIBRARIES})
8180 endif()
8181 Boost CMake
8183 If Boost was built using the boost-cmake project it provides a package
8184 configuration file for use with find_package’s Config mode. This mod‐
8185 ule looks for the package configuration file called BoostConfig.cmake
8186 or boost-config.cmake and stores the result in cache entry “Boost_DIR”.
8187 If found, the package configuration file is loaded and this module
8188 returns with no further action. See documentation of the Boost CMake
8189 package configuration for details on what it provides.
8190 Set Boost_NO_BOOST_CMAKE to ON to disable the search for boost-cmake.
8192 FindBullet
8194 Try to find the Bullet physics engine
8195 This module defines the following variables
8197 BULLET_FOUND - Was bullet found
8199 BULLET_INCLUDE_DIRS - the Bullet include directories
8200 BULLET_LIBRARIES - Link to this, by default it includes
8201 all bullet components (Dynamics,
8202 Collision, LinearMath, & SoftBody)
8203 This module accepts the following variables
8205 BULLET_ROOT - Can be set to bullet install path or Windows build path
8207 FindBZip2
8209 Try to find BZip2
8210 IMPORTED Targets
8212 This module defines IMPORTED target BZip2::BZip2, if BZip2 has been
8213 found.
8214 Result Variables
8216 This module defines the following variables:
8217 BZIP2_FOUND - system has BZip2
8219 BZIP2_INCLUDE_DIR - the BZip2 include directory
8220 BZIP2_LIBRARIES - Link these to use BZip2
8221 BZIP2_NEED_PREFIX - this is set if the functions are prefixed with BZ2_
8222 BZIP2_VERSION_STRING - the version of BZip2 found (since CMake 2.8.8)
8223 FindCABLE
8225 Find CABLE
8226 This module finds if CABLE is installed and determines where the
8228 include files and libraries are. This code sets the following vari‐
8229 ables:
8230 CABLE the path to the cable executable
8232 CABLE_TCL_LIBRARY the path to the Tcl wrapper library
8233 CABLE_INCLUDE_DIR the path to the include directory
8234 To build Tcl wrappers, you should add shared library and link it to
8236 ${CABLE_TCL_LIBRARY}. You should also add ${CABLE_INCLUDE_DIR} as an
8237 include directory.
8238 FindCoin3D
8240 Find Coin3D (Open Inventor)
8241 Coin3D is an implementation of the Open Inventor API. It provides data
8243 structures and algorithms for 3D visualization.
8244 This module defines the following variables
8246 COIN3D_FOUND - system has Coin3D - Open Inventor
8248 COIN3D_INCLUDE_DIRS - where the Inventor include directory can be found
8249 COIN3D_LIBRARIES - Link to this to use Coin3D
8250 FindCUDA
8252 NOTE:
8253 The FindCUDA module has been superseded by first-class support for
8254 the CUDA language in CMake. It is no longer necessary to use this
8255 module or call find_package(CUDA). This module now exists only for
8256 compatibility with projects that have not been ported.
8257 Instead, list CUDA among the languages named in the top-level call
8259 to the project() command, or call the enable_language() command with
8260 CUDA. Then one can add CUDA (.cu) sources to programs directly in
8261 calls to add_library() and add_executable().
8262 Tools for building CUDA C files: libraries and build dependencies.
8264 This script locates the NVIDIA CUDA C tools. It should work on Linux,
8266 Windows, and macOS and should be reasonably up to date with CUDA C
8267 releases.
8268 This script makes use of the standard find_package() arguments of <VER‐
8270 SION>, REQUIRED and QUIET. CUDA_FOUND will report if an acceptable
8271 version of CUDA was found.
8272 The script will prompt the user to specify CUDA_TOOLKIT_ROOT_DIR if the
8274 prefix cannot be determined by the location of nvcc in the system path
8275 and REQUIRED is specified to find_package(). To use a different
8276 installed version of the toolkit set the environment variable
8277 CUDA_BIN_PATH before running cmake (e.g.
8278 CUDA_BIN_PATH=/usr/local/cuda1.0 instead of the default
8279 /usr/local/cuda) or set CUDA_TOOLKIT_ROOT_DIR after configuring. If
8280 you change the value of CUDA_TOOLKIT_ROOT_DIR, various components that
8281 depend on the path will be relocated.
8282 It might be necessary to set CUDA_TOOLKIT_ROOT_DIR manually on certain
8284 platforms, or to use a CUDA runtime not installed in the default loca‐
8285 tion. In newer versions of the toolkit the CUDA library is included
8286 with the graphics driver – be sure that the driver version matches what
8287 is needed by the CUDA runtime version.
8288 The following variables affect the behavior of the macros in the script
8290 (in alphebetical order). Note that any of these flags can be changed
8291 multiple times in the same directory before calling CUDA_ADD_EXE‐
8292 CUTABLE, CUDA_ADD_LIBRARY, CUDA_COMPILE, CUDA_COMPILE_PTX, CUDA_COM‐
8293 PILE_FATBIN, CUDA_COMPILE_CUBIN or CUDA_WRAP_SRCS:
8294 CUDA_64_BIT_DEVICE_CODE (Default matches host bit size)
8296 -- Set to ON to compile for 64 bit device code, OFF for 32 bit device code.
8297 Note that making this different from the host code when generating object
8298 or C files from CUDA code just won't work, because size_t gets defined by
8299 nvcc in the generated source. If you compile to PTX and then load the
8300 file yourself, you can mix bit sizes between device and host.
8301 CUDA_ATTACH_VS_BUILD_RULE_TO_CUDA_FILE (Default ON)
8303 -- Set to ON if you want the custom build rule to be attached to the source
8304 file in Visual Studio. Turn OFF if you add the same cuda file to multiple
8305 targets.
8306 This allows the user to build the target from the CUDA file; however, bad
8308 things can happen if the CUDA source file is added to multiple targets.
8309 When performing parallel builds it is possible for the custom build
8310 command to be run more than once and in parallel causing cryptic build
8311 errors. VS runs the rules for every source file in the target, and a
8312 source can have only one rule no matter how many projects it is added to.
8313 When the rule is run from multiple targets race conditions can occur on
8314 the generated file. Eventually everything will get built, but if the user
8315 is unaware of this behavior, there may be confusion. It would be nice if
8316 this script could detect the reuse of source files across multiple targets
8317 and turn the option off for the user, but no good solution could be found.
8318 CUDA_BUILD_CUBIN (Default OFF)
8320 -- Set to ON to enable and extra compilation pass with the -cubin option in
8321 Device mode. The output is parsed and register, shared memory usage is
8322 printed during build.
8323 CUDA_BUILD_EMULATION (Default OFF for device mode)
8325 -- Set to ON for Emulation mode. -D_DEVICEEMU is defined for CUDA C files
8326 when CUDA_BUILD_EMULATION is TRUE.
8327 CUDA_LINK_LIBRARIES_KEYWORD (Default "")
8329 -- The <PRIVATE|PUBLIC|INTERFACE> keyword to use for internal
8330 target_link_libraries calls. The default is to use no keyword which
8331 uses the old "plain" form of target_link_libraries. Note that is matters
8332 because whatever is used inside the FindCUDA module must also be used
8333 outside - the two forms of target_link_libraries cannot be mixed.
8334 CUDA_GENERATED_OUTPUT_DIR (Default CMAKE_CURRENT_BINARY_DIR)
8336 -- Set to the path you wish to have the generated files placed. If it is
8337 blank output files will be placed in CMAKE_CURRENT_BINARY_DIR.
8338 Intermediate files will always be placed in
8339 CMAKE_CURRENT_BINARY_DIR/CMakeFiles.
8340 CUDA_HOST_COMPILATION_CPP (Default ON)
8342 -- Set to OFF for C compilation of host code.
8343 CUDA_HOST_COMPILER (Default CMAKE_C_COMPILER)
8345 -- Set the host compiler to be used by nvcc. Ignored if -ccbin or
8346 --compiler-bindir is already present in the CUDA_NVCC_FLAGS or
8347 CUDA_NVCC_FLAGS_<CONFIG> variables. For Visual Studio targets,
8348 the host compiler is constructed with one or more visual studio macros
8349 such as $(VCInstallDir), that expands out to the path when
8350 the command is run from within VS.
8351 CUDA_NVCC_FLAGS
8353 CUDA_NVCC_FLAGS_<CONFIG>
8354 -- Additional NVCC command line arguments. NOTE: multiple arguments must be
8355 semi-colon delimited (e.g. --compiler-options;-Wall)
8356 CUDA_PROPAGATE_HOST_FLAGS (Default ON)
8358 -- Set to ON to propagate CMAKE_{C,CXX}_FLAGS and their configuration
8359 dependent counterparts (e.g. CMAKE_C_FLAGS_DEBUG) automatically to the
8360 host compiler through nvcc's -Xcompiler flag. This helps make the
8361 generated host code match the rest of the system better. Sometimes
8362 certain flags give nvcc problems, and this will help you turn the flag
8363 propagation off. This does not affect the flags supplied directly to nvcc
8364 via CUDA_NVCC_FLAGS or through the OPTION flags specified through
8365 CUDA_ADD_LIBRARY, CUDA_ADD_EXECUTABLE, or CUDA_WRAP_SRCS. Flags used for
8366 shared library compilation are not affected by this flag.
8367 CUDA_SEPARABLE_COMPILATION (Default OFF)
8369 -- If set this will enable separable compilation for all CUDA runtime object
8370 files. If used outside of CUDA_ADD_EXECUTABLE and CUDA_ADD_LIBRARY
8371 (e.g. calling CUDA_WRAP_SRCS directly),
8372 CUDA_COMPUTE_SEPARABLE_COMPILATION_OBJECT_FILE_NAME and
8373 CUDA_LINK_SEPARABLE_COMPILATION_OBJECTS should be called.
8374 CUDA_SOURCE_PROPERTY_FORMAT
8376 -- If this source file property is set, it can override the format specified
8377 to CUDA_WRAP_SRCS (OBJ, PTX, CUBIN, or FATBIN). If an input source file
8378 is not a .cu file, setting this file will cause it to be treated as a .cu
8379 file. See documentation for set_source_files_properties on how to set
8380 this property.
8381 CUDA_USE_STATIC_CUDA_RUNTIME (Default ON)
8383 -- When enabled the static version of the CUDA runtime library will be used
8384 in CUDA_LIBRARIES. If the version of CUDA configured doesn't support
8385 this option, then it will be silently disabled.
8386 CUDA_VERBOSE_BUILD (Default OFF)
8388 -- Set to ON to see all the commands used when building the CUDA file. When
8389 using a Makefile generator the value defaults to VERBOSE (run make
8390 VERBOSE=1 to see output), although setting CUDA_VERBOSE_BUILD to ON will
8391 always print the output.
8392 The script creates the following macros (in alphebetical order):
8394 CUDA_ADD_CUFFT_TO_TARGET( cuda_target )
8396 -- Adds the cufft library to the target (can be any target). Handles whether
8397 you are in emulation mode or not.
8398 CUDA_ADD_CUBLAS_TO_TARGET( cuda_target )
8400 -- Adds the cublas library to the target (can be any target). Handles
8401 whether you are in emulation mode or not.
8402 CUDA_ADD_EXECUTABLE( cuda_target file0 file1 ...
8404 [WIN32] [MACOSX_BUNDLE] [EXCLUDE_FROM_ALL] [OPTIONS ...] )
8405 -- Creates an executable "cuda_target" which is made up of the files
8406 specified. All of the non CUDA C files are compiled using the standard
8407 build rules specified by CMAKE and the cuda files are compiled to object
8408 files using nvcc and the host compiler. In addition CUDA_INCLUDE_DIRS is
8409 added automatically to include_directories(). Some standard CMake target
8410 calls can be used on the target after calling this macro
8411 (e.g. set_target_properties and target_link_libraries), but setting
8412 properties that adjust compilation flags will not affect code compiled by
8413 nvcc. Such flags should be modified before calling CUDA_ADD_EXECUTABLE,
8414 CUDA_ADD_LIBRARY or CUDA_WRAP_SRCS.
8415 CUDA_ADD_LIBRARY( cuda_target file0 file1 ...
8417 [STATIC | SHARED | MODULE] [EXCLUDE_FROM_ALL] [OPTIONS ...] )
8418 -- Same as CUDA_ADD_EXECUTABLE except that a library is created.
8419 CUDA_BUILD_CLEAN_TARGET()
8421 -- Creates a convience target that deletes all the dependency files
8422 generated. You should make clean after running this target to ensure the
8423 dependency files get regenerated.
8424 CUDA_COMPILE( generated_files file0 file1 ... [STATIC | SHARED | MODULE]
8426 [OPTIONS ...] )
8427 -- Returns a list of generated files from the input source files to be used
8428 with ADD_LIBRARY or ADD_EXECUTABLE.
8429 CUDA_COMPILE_PTX( generated_files file0 file1 ... [OPTIONS ...] )
8431 -- Returns a list of PTX files generated from the input source files.
8432 CUDA_COMPILE_FATBIN( generated_files file0 file1 ... [OPTIONS ...] )
8434 -- Returns a list of FATBIN files generated from the input source files.
8435 CUDA_COMPILE_CUBIN( generated_files file0 file1 ... [OPTIONS ...] )
8437 -- Returns a list of CUBIN files generated from the input source files.
8438 CUDA_COMPUTE_SEPARABLE_COMPILATION_OBJECT_FILE_NAME( output_file_var
8440 cuda_target
8441 object_files )
8442 -- Compute the name of the intermediate link file used for separable
8443 compilation. This file name is typically passed into
8444 CUDA_LINK_SEPARABLE_COMPILATION_OBJECTS. output_file_var is produced
8445 based on cuda_target the list of objects files that need separable
8446 compilation as specified by object_files. If the object_files list is
8447 empty, then output_file_var will be empty. This function is called
8448 automatically for CUDA_ADD_LIBRARY and CUDA_ADD_EXECUTABLE. Note that
8449 this is a function and not a macro.
8450 CUDA_INCLUDE_DIRECTORIES( path0 path1 ... )
8452 -- Sets the directories that should be passed to nvcc
8453 (e.g. nvcc -Ipath0 -Ipath1 ... ). These paths usually contain other .cu
8454 files.
8455 CUDA_LINK_SEPARABLE_COMPILATION_OBJECTS( output_file_var cuda_target
8458 nvcc_flags object_files)
8459 -- Generates the link object required by separable compilation from the given
8460 object files. This is called automatically for CUDA_ADD_EXECUTABLE and
8461 CUDA_ADD_LIBRARY, but can be called manually when using CUDA_WRAP_SRCS
8462 directly. When called from CUDA_ADD_LIBRARY or CUDA_ADD_EXECUTABLE the
8463 nvcc_flags passed in are the same as the flags passed in via the OPTIONS
8464 argument. The only nvcc flag added automatically is the bitness flag as
8465 specified by CUDA_64_BIT_DEVICE_CODE. Note that this is a function
8466 instead of a macro.
8467 CUDA_SELECT_NVCC_ARCH_FLAGS(out_variable [target_CUDA_architectures])
8469 -- Selects GPU arch flags for nvcc based on target_CUDA_architectures
8470 target_CUDA_architectures : Auto | Common | All | LIST(ARCH_AND_PTX ...)
8471 - "Auto" detects local machine GPU compute arch at runtime.
8472 - "Common" and "All" cover common and entire subsets of architectures
8473 ARCH_AND_PTX : NAME | NUM.NUM | NUM.NUM(NUM.NUM) | NUM.NUM+PTX
8474 NAME: Fermi Kepler Maxwell Kepler+Tegra Kepler+Tesla Maxwell+Tegra Pascal
8475 NUM: Any number. Only those pairs are currently accepted by NVCC though:
8476 2.0 2.1 3.0 3.2 3.5 3.7 5.0 5.2 5.3 6.0 6.2
8477 Returns LIST of flags to be added to CUDA_NVCC_FLAGS in ${out_variable}
8478 Additionally, sets ${out_variable}_readable to the resulting numeric list
8479 Example:
8480 CUDA_SELECT_NVCC_ARCH_FLAGS(ARCH_FLAGS 3.0 3.5+PTX 5.2(5.0) Maxwell)
8481 LIST(APPEND CUDA_NVCC_FLAGS ${ARCH_FLAGS})
8482 More info on CUDA architectures: https://en.wikipedia.org/wiki/CUDA
8484 Note that this is a function instead of a macro.
8485 CUDA_WRAP_SRCS ( cuda_target format generated_files file0 file1 ...
8487 [STATIC | SHARED | MODULE] [OPTIONS ...] )
8488 -- This is where all the magic happens. CUDA_ADD_EXECUTABLE,
8489 CUDA_ADD_LIBRARY, CUDA_COMPILE, and CUDA_COMPILE_PTX all call this
8490 function under the hood.
8491 Given the list of files (file0 file1 ... fileN) this macro generates
8493 custom commands that generate either PTX or linkable objects (use "PTX" or
8494 "OBJ" for the format argument to switch). Files that don't end with .cu
8495 or have the HEADER_FILE_ONLY property are ignored.
8496 The arguments passed in after OPTIONS are extra command line options to
8498 give to nvcc. You can also specify per configuration options by
8499 specifying the name of the configuration followed by the options. General
8500 options must precede configuration specific options. Not all
8501 configurations need to be specified, only the ones provided will be used.
8502 OPTIONS -DFLAG=2 "-DFLAG_OTHER=space in flag"
8504 DEBUG -g
8505 RELEASE --use_fast_math
8506 RELWITHDEBINFO --use_fast_math;-g
8507 MINSIZEREL --use_fast_math
8508 For certain configurations (namely VS generating object files with
8510 CUDA_ATTACH_VS_BUILD_RULE_TO_CUDA_FILE set to ON), no generated file will
8511 be produced for the given cuda file. This is because when you add the
8512 cuda file to Visual Studio it knows that this file produces an object file
8513 and will link in the resulting object file automatically.
8514 This script will also generate a separate cmake script that is used at
8516 build time to invoke nvcc. This is for several reasons.
8517 1. nvcc can return negative numbers as return values which confuses
8519 Visual Studio into thinking that the command succeeded. The script now
8520 checks the error codes and produces errors when there was a problem.
8521 2. nvcc has been known to not delete incomplete results when it
8523 encounters problems. This confuses build systems into thinking the
8524 target was generated when in fact an unusable file exists. The script
8525 now deletes the output files if there was an error.
8526 3. By putting all the options that affect the build into a file and then
8528 make the build rule dependent on the file, the output files will be
8529 regenerated when the options change.
8530 This script also looks at optional arguments STATIC, SHARED, or MODULE to
8532 determine when to target the object compilation for a shared library.
8533 BUILD_SHARED_LIBS is ignored in CUDA_WRAP_SRCS, but it is respected in
8534 CUDA_ADD_LIBRARY. On some systems special flags are added for building
8535 objects intended for shared libraries. A preprocessor macro,
8536 <target_name>_EXPORTS is defined when a shared library compilation is
8537 detected.
8538 Flags passed into add_definitions with -D or /D are passed along to nvcc.
8540 The script defines the following variables:
8542 CUDA_VERSION_MAJOR -- The major version of cuda as reported by nvcc.
8544 CUDA_VERSION_MINOR -- The minor version.
8545 CUDA_VERSION
8546 CUDA_VERSION_STRING -- CUDA_VERSION_MAJOR.CUDA_VERSION_MINOR
8547 CUDA_HAS_FP16 -- Whether a short float (float16,fp16) is supported.
8548 CUDA_TOOLKIT_ROOT_DIR -- Path to the CUDA Toolkit (defined if not set).
8550 CUDA_SDK_ROOT_DIR -- Path to the CUDA SDK. Use this to find files in the
8551 SDK. This script will not directly support finding
8552 specific libraries or headers, as that isn't
8553 supported by NVIDIA. If you want to change
8554 libraries when the path changes see the
8555 FindCUDA.cmake script for an example of how to clear
8556 these variables. There are also examples of how to
8557 use the CUDA_SDK_ROOT_DIR to locate headers or
8558 libraries, if you so choose (at your own risk).
8559 CUDA_INCLUDE_DIRS -- Include directory for cuda headers. Added automatically
8560 for CUDA_ADD_EXECUTABLE and CUDA_ADD_LIBRARY.
8561 CUDA_LIBRARIES -- Cuda RT library.
8562 CUDA_CUFFT_LIBRARIES -- Device or emulation library for the Cuda FFT
8563 implementation (alternative to:
8564 CUDA_ADD_CUFFT_TO_TARGET macro)
8565 CUDA_CUBLAS_LIBRARIES -- Device or emulation library for the Cuda BLAS
8566 implementation (alternative to:
8567 CUDA_ADD_CUBLAS_TO_TARGET macro).
8568 CUDA_cudart_static_LIBRARY -- Statically linkable cuda runtime library.
8569 Only available for CUDA version 5.5+
8570 CUDA_cudadevrt_LIBRARY -- Device runtime library.
8571 Required for separable compilation.
8572 CUDA_cupti_LIBRARY -- CUDA Profiling Tools Interface library.
8573 Only available for CUDA version 4.0+.
8574 CUDA_curand_LIBRARY -- CUDA Random Number Generation library.
8575 Only available for CUDA version 3.2+.
8576 CUDA_cusolver_LIBRARY -- CUDA Direct Solver library.
8577 Only available for CUDA version 7.0+.
8578 CUDA_cusparse_LIBRARY -- CUDA Sparse Matrix library.
8579 Only available for CUDA version 3.2+.
8580 CUDA_npp_LIBRARY -- NVIDIA Performance Primitives lib.
8581 Only available for CUDA version 4.0+.
8582 CUDA_nppc_LIBRARY -- NVIDIA Performance Primitives lib (core).
8583 Only available for CUDA version 5.5+.
8584 CUDA_nppi_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
8585 Only available for CUDA version 5.5 - 8.0.
8586 CUDA_nppial_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
8587 Only available for CUDA version 9.0.
8588 CUDA_nppicc_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
8589 Only available for CUDA version 9.0.
8590 CUDA_nppicom_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
8591 Only available for CUDA version 9.0.
8592 CUDA_nppidei_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
8593 Only available for CUDA version 9.0.
8594 CUDA_nppif_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
8595 Only available for CUDA version 9.0.
8596 CUDA_nppig_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
8597 Only available for CUDA version 9.0.
8598 CUDA_nppim_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
8599 Only available for CUDA version 9.0.
8600 CUDA_nppist_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
8601 Only available for CUDA version 9.0.
8602 CUDA_nppisu_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
8603 Only available for CUDA version 9.0.
8604 CUDA_nppitc_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
8605 Only available for CUDA version 9.0.
8606 CUDA_npps_LIBRARY -- NVIDIA Performance Primitives lib (signal processing).
8607 Only available for CUDA version 5.5+.
8608 CUDA_nvcuvenc_LIBRARY -- CUDA Video Encoder library.
8609 Only available for CUDA version 3.2+.
8610 Windows only.
8611 CUDA_nvcuvid_LIBRARY -- CUDA Video Decoder library.
8612 Only available for CUDA version 3.2+.
8613 Windows only.
8614 FindCups
8616 Try to find the Cups printing system
8617 Once done this will define
8619 CUPS_FOUND - system has Cups
8621 CUPS_INCLUDE_DIR - the Cups include directory
8622 CUPS_LIBRARIES - Libraries needed to use Cups
8623 CUPS_VERSION_STRING - version of Cups found (since CMake 2.8.8)
8624 Set CUPS_REQUIRE_IPP_DELETE_ATTRIBUTE to TRUE if you need a version which
8625 features this function (i.e. at least 1.1.19)
8626 FindCURL
8628 Find curl
8629 Find the native CURL headers and libraries.
8631 CURL_INCLUDE_DIRS - where to find curl/curl.h, etc.
8633 CURL_LIBRARIES - List of libraries when using curl.
8634 CURL_FOUND - True if curl found.
8635 CURL_VERSION_STRING - the version of curl found (since CMake 2.8.8)
8636 FindCurses
8638 Find the curses or ncurses include file and library.
8639 Result Variables
8641 This module defines the following variables:
8642 CURSES_FOUND
8644 True if Curses is found.
8645 CURSES_INCLUDE_DIRS
8647 The include directories needed to use Curses.
8648 CURSES_LIBRARIES
8650 The libraries needed to use Curses.
8651 CURSES_HAVE_CURSES_H
8653 True if curses.h is available.
8654 CURSES_HAVE_NCURSES_H
8656 True if ncurses.h is available.
8657 CURSES_HAVE_NCURSES_NCURSES_H
8659 True if ncurses/ncurses.h is available.
8660 CURSES_HAVE_NCURSES_CURSES_H
8662 True if ncurses/curses.h is available.
8663 Set CURSES_NEED_NCURSES to TRUE before the find_package(Curses) call if
8665 NCurses functionality is required. Set CURSES_NEED_WIDE to TRUE before
8666 the find_package(Curses) call if unicode functionality is required.
8667 Backward Compatibility
8669 The following variable are provided for backward compatibility:
8670 CURSES_INCLUDE_DIR
8672 Path to Curses include. Use CURSES_INCLUDE_DIRS instead.
8673 CURSES_LIBRARY
8675 Path to Curses library. Use CURSES_LIBRARIES instead.
8676 FindCVS
8678 The module defines the following variables:
8679 CVS_EXECUTABLE - path to cvs command line client
8681 CVS_FOUND - true if the command line client was found
8682 Example usage:
8684 find_package(CVS)
8686 if(CVS_FOUND)
8687 message("CVS found: ${CVS_EXECUTABLE}")
8688 endif()
8689 FindCxxTest
8691 Find CxxTest
8692 Find the CxxTest suite and declare a helper macro for creating unit
8694 tests and integrating them with CTest. For more details on CxxTest see
8695 http://cxxtest.tigris.org
8696 INPUT Variables
8698 CXXTEST_USE_PYTHON [deprecated since 1.3]
8700 Only used in the case both Python & Perl
8701 are detected on the system to control
8702 which CxxTest code generator is used.
8703 Valid only for CxxTest version 3.
8704 NOTE: In older versions of this Find Module,
8706 this variable controlled if the Python test
8707 generator was used instead of the Perl one,
8708 regardless of which scripting language the
8709 user had installed.
8710 CXXTEST_TESTGEN_ARGS (since CMake 2.8.3)
8712 Specify a list of options to pass to the CxxTest code
8713 generator. If not defined, --error-printer is
8714 passed.
8715 OUTPUT Variables
8717 CXXTEST_FOUND
8719 True if the CxxTest framework was found
8720 CXXTEST_INCLUDE_DIRS
8721 Where to find the CxxTest include directory
8722 CXXTEST_PERL_TESTGEN_EXECUTABLE
8723 The perl-based test generator
8724 CXXTEST_PYTHON_TESTGEN_EXECUTABLE
8725 The python-based test generator
8726 CXXTEST_TESTGEN_EXECUTABLE (since CMake 2.8.3)
8727 The test generator that is actually used (chosen using user preferences
8728 and interpreters found in the system)
8729 CXXTEST_TESTGEN_INTERPRETER (since CMake 2.8.3)
8730 The full path to the Perl or Python executable on the system, on
8731 platforms where the script cannot be executed using its shebang line.
8732 MACROS for optional use by CMake users:
8734 CXXTEST_ADD_TEST(<test_name> <gen_source_file> <input_files_to_testgen...>)
8736 Creates a CxxTest runner and adds it to the CTest testing suite
8737 Parameters:
8738 test_name The name of the test
8739 gen_source_file The generated source filename to be
8740 generated by CxxTest
8741 input_files_to_testgen The list of header files containing the
8742 CxxTest::TestSuite's to be included in
8743 this runner
8744 #==============
8746 Example Usage:
8747 find_package(CxxTest)
8749 if(CXXTEST_FOUND)
8750 include_directories(${CXXTEST_INCLUDE_DIR})
8751 enable_testing()
8752 CXXTEST_ADD_TEST(unittest_foo foo_test.cc
8754 ${CMAKE_CURRENT_SOURCE_DIR}/foo_test.h)
8755 target_link_libraries(unittest_foo foo) # as needed
8756 endif()
8757 This will (if CxxTest is found):
8759 1. Invoke the testgen executable to autogenerate foo_test.cc in the
8760 binary tree from "foo_test.h" in the current source directory.
8761 2. Create an executable and test called unittest_foo.
8762 #=============
8764 Example foo_test.h:
8765 #include <cxxtest/TestSuite.h>
8767 class MyTestSuite : public CxxTest::TestSuite
8769 {
8770 public:
8771 void testAddition( void )
8772 {
8773 TS_ASSERT( 1 + 1 > 1 );
8774 TS_ASSERT_EQUALS( 1 + 1, 2 );
8775 }
8776 };
8777 FindCygwin
8779 this module looks for Cygwin
8780 FindDart
8782 Find DART
8783 This module looks for the dart testing software and sets DART_ROOT to
8785 point to where it found it.
8786 FindDCMTK
8788 Find DCMTK libraries and applications
8789 The module defines the following variables:
8791 DCMTK_INCLUDE_DIRS - Directories to include to use DCMTK
8793 DCMTK_LIBRARIES - Files to link against to use DCMTK
8794 DCMTK_FOUND - If false, don't try to use DCMTK
8795 DCMTK_DIR - (optional) Source directory for DCMTK
8796 Compatibility
8798 This module is able to find a version of DCMTK that does or does not
8799 export a DCMTKConfig.cmake file. It applies a two step process:
8800 · Step 1: Attempt to find DCMTK version providing a DCMTKConfig.cmake
8802 file.
8803 · Step 2: If step 1 failed, rely on FindDCMTK.cmake to set DCMTK_*
8805 variables details below.
8806 Recent DCMTK provides a DCMTKConfig.cmake package configuration file.
8808 To exclusively use the package configuration file (recommended when
8809 possible), pass the NO_MODULE option to find_package(). For example,
8810 find_package(DCMTK NO_MODULE). This requires official DCMTK snapshot
8811 3.6.1_20140617 or newer.
8812 Until all clients update to the more recent DCMTK, build systems will
8814 need to support different versions of DCMTK.
8815 On any given system, the following combinations of DCMTK versions could
8817 be considered:
8818 ┌───────┬─────────────────┬─────────────────┬─────────────┐
8820 │ │ SYSTEM DCMTK │ LOCAL DCMTK │ Supported ? │
8821 ├───────┼─────────────────┼─────────────────┼─────────────┤
8822 │Case A │ NA │ [ ] DCMTKConfig │ YES │
8823 ├───────┼─────────────────┼─────────────────┼─────────────┤
8824 │Case B │ NA │ [X] DCMTKConfig │ YES │
8825 ├───────┼─────────────────┼─────────────────┼─────────────┤
8826 │Case C │ [ ] DCMTKConfig │ NA │ YES │
8827 ├───────┼─────────────────┼─────────────────┼─────────────┤
8828 │Case D │ [X] DCMTKConfig │ NA │ YES │
8829 ├───────┼─────────────────┼─────────────────┼─────────────┤
8830 │Case E │ [ ] DCMTKConfig │ [ ] DCMTKConfig │ YES (*) │
8831 ├───────┼─────────────────┼─────────────────┼─────────────┤
8832 │Case F │ [X] DCMTKConfig │ [ ] DCMTKConfig │ NO │
8833 ├───────┼─────────────────┼─────────────────┼─────────────┤
8834 │Case G │ [ ] DCMTKConfig │ [X] DCMTKConfig │ YES │
8835 ├───────┼─────────────────┼─────────────────┼─────────────┤
8836 │Case H │ [X] DCMTKConfig │ [X] DCMTKConfig │ YES │
8837 └───────┴─────────────────┴─────────────────┴─────────────┘
8838 (*) See Troubleshooting section.
8839 Legend:
8841 NA ……………: Means that no System or Local DCMTK is available
8842 [ ] DCMTKConfig ..: Means that the version of DCMTK does NOT export
8844 a DCMTKConfig.cmake file.
8845 [X] DCMTKConfig ..: Means that the version of DCMTK exports a DCMTK‐
8847 Config.cmake file.
8848 Troubleshooting
8850 What to do if my project finds a different version of DCMTK?
8851 Remove DCMTK entry from the CMake cache per find_package() documenta‐
8853 tion.
8854 FindDevIL
8856 This module locates the developer’s image library.
8857 http://openil.sourceforge.net/
8858 This module sets:
8860 IL_LIBRARIES - the name of the IL library. These include the full path to
8862 the core DevIL library. This one has to be linked into the
8863 application.
8864 ILU_LIBRARIES - the name of the ILU library. Again, the full path. This
8865 library is for filters and effects, not actual loading. It
8866 doesn't have to be linked if the functionality it provides
8867 is not used.
8868 ILUT_LIBRARIES - the name of the ILUT library. Full path. This part of the
8869 library interfaces with OpenGL. It is not strictly needed
8870 in applications.
8871 IL_INCLUDE_DIR - where to find the il.h, ilu.h and ilut.h files.
8872 DevIL_FOUND - this is set to TRUE if all the above variables were set.
8873 This will be set to false if ILU or ILUT are not found,
8874 even if they are not needed. In most systems, if one
8875 library is found all the others are as well. That's the
8876 way the DevIL developers release it.
8877 FindDoxygen
8879 Doxygen is a documentation generation tool (see
8880 http://www.doxygen.org). This module looks for Doxygen and some
8881 optional tools it supports. These tools are enabled as components in
8882 the find_package() command:
8883 dot Graphviz dot utility used to render various graphs.
8885 mscgen Message Chart Generator utility used by Doxygen’s \msc and \msc‐
8887 file commands.
8888 dia Dia the diagram editor used by Doxygen’s \diafile command.
8890 Examples:
8892 # Require dot, treat the other components as optional
8894 find_package(Doxygen
8895 REQUIRED dot
8896 OPTIONAL_COMPONENTS mscgen dia)
8897 The following variables are defined by this module:
8899 DOXYGEN_FOUND
8901 True if the doxygen executable was found.
8902 DOXYGEN_VERSION
8904 The version reported by doxygen --version.
8905 The module defines IMPORTED targets for Doxygen and each component
8907 found. These can be used as part of custom commands, etc. and should
8908 be preferred over old-style (and now deprecated) variables like DOXY‐
8909 GEN_EXECUTABLE. The following import targets are defined if their cor‐
8910 responding executable could be found (the component import targets will
8911 only be defined if that component was requested):
8912 Doxygen::doxygen
8914 Doxygen::dot
8915 Doxygen::mscgen
8916 Doxygen::dia
8917 Functions
8919 doxygen_add_docs
8920 This function is intended as a convenience for adding a target
8921 for generating documentation with Doxygen. It aims to provide
8922 sensible defaults so that projects can generally just provide
8923 the input files and directories and that will be sufficient to
8924 give sensible results. The function supports the ability to cus‐
8925 tomize the Doxygen configuration used to build the documenta‐
8926 tion.
8927 doxygen_add_docs(targetName
8929 [filesOrDirs...]
8930 [WORKING_DIRECTORY dir]
8931 [COMMENT comment])
8932 The function constructs a Doxyfile and defines a custom target
8934 that runs Doxygen on that generated file. The listed files and
8935 directories are used as the INPUT of the generated Doxyfile and
8936 they can contain wildcards. Any files that are listed explic‐
8937 itly will also be added as SOURCES of the custom target so they
8938 will show up in an IDE project’s source list.
8939 So that relative input paths work as expected, by default the
8941 working directory of the Doxygen command will be the current
8942 source directory (i.e. CMAKE_CURRENT_SOURCE_DIR). This can be
8943 overridden with the WORKING_DIRECTORY option to change the
8944 directory used as the relative base point. Note also that Doxy‐
8945 gen’s default behavior is to strip the working directory from
8946 relative paths in the generated documentation (see the
8947 STRIP_FROM_PATH Doxygen config option for details).
8948 If provided, the optional comment will be passed as the COMMENT
8950 for the add_custom_target() command used to create the custom
8951 target internally.
8952 The contents of the generated Doxyfile can be customized by set‐
8954 ting CMake variables before calling doxygen_add_docs(). Any
8955 variable with a name of the form DOXYGEN_<tag> will have its
8956 value substituted for the corresponding <tag> configuration
8957 option in the Doxyfile. See the Doxygen documentation for the
8958 full list of supported configuration options.
8959 Some of Doxygen’s defaults are overridden to provide more appro‐
8961 priate behavior for a CMake project. Each of the following will
8962 be explicitly set unless the variable already has a value before
8963 doxygen_add_docs() is called (with some exceptions noted):
8964 DOXYGEN_HAVE_DOT
8966 Set to YES if the dot component was requested and it was
8967 found, NO otherwise. Any existing value of DOXY‐
8968 GEN_HAVE_DOT is ignored.
8969 DOXYGEN_DOT_MULTI_TARGETS
8971 Set to YES by this module (note that this requires a dot
8972 version newer than 1.8.10). This option is only meaning‐
8973 ful if DOXYGEN_HAVE_DOT is also set to YES.
8974 DOXYGEN_GENERATE_LATEX
8976 Set to NO by this module.
8977 DOXYGEN_WARN_FORMAT
8979 For Visual Studio based generators, this is set to the
8980 form recognized by the Visual Studio IDE: $file($line) :
8981 $text. For all other generators, Doxygen’s default value
8982 is not overridden.
8983 DOXYGEN_PROJECT_NAME
8985 Populated with the name of the current project (i.e.
8986 PROJECT_NAME).
8987 DOXYGEN_PROJECT_NUMBER
8989 Populated with the version of the current project (i.e.
8990 PROJECT_VERSION).
8991 DOXYGEN_PROJECT_BRIEF
8993 Populated with the description of the current project
8994 (i.e. PROJECT_DESCRIPTION).
8995 DOXYGEN_INPUT
8997 Projects should not set this variable. It will be popu‐
8998 lated with the set of files and directories passed to
8999 doxygen_add_docs(), thereby providing consistent behavior
9000 with the other built-in commands like add_executable(),
9001 add_library() and add_custom_target(). If a variable
9002 named DOXYGEN_INPUT is set by the project, it will be
9003 ignored and a warning will be issued.
9004 DOXYGEN_RECURSIVE
9006 Set to YES by this module.
9007 DOXYGEN_EXCLUDE_PATTERNS
9009 If the set of inputs includes directories, this variable
9010 will specify patterns used to exclude files from them.
9011 The following patterns are added by doxygen_add_docs() to
9012 ensure CMake-specific files and directories are not
9013 included in the input. If the project sets DOXY‐
9014 GEN_EXCLUDE_PATTERNS, those contents are merged with
9015 these additional patterns rather than replacing them:
9016 */.git/*
9018 */.svn/*
9019 */.hg/*
9020 */CMakeFiles/*
9021 */_CPack_Packages/*
9022 DartConfiguration.tcl
9023 CMakeLists.txt
9024 CMakeCache.txt
9025 DOXYGEN_OUTPUT_DIRECTORY
9027 Set to CMAKE_CURRENT_BINARY_DIR by this module. Note that
9028 if the project provides its own value for this and it is
9029 a relative path, it will be converted to an absolute path
9030 relative to the current binary directory. This is neces‐
9031 sary because doxygen will normally be run from a direc‐
9032 tory within the source tree so that relative source paths
9033 work as expected. If this directory does not exist, it
9034 will be recursively created prior to executing the doxy‐
9035 gen commands.
9036 To change any of these defaults or override any other Doxygen config
9038 option, set relevant variables before calling doxygen_add_docs(). For
9039 example:
9040 set(DOXYGEN_GENERATE_HTML NO)
9042 set(DOXYGEN_GENERATE_MAN YES)
9043 doxygen_add_docs(
9045 doxygen
9046 ${PROJECT_SOURCE_DIR}
9047 COMMENT "Generate man pages"
9048 )
9049 A number of Doxygen config options accept lists of values, but Doxygen
9051 requires them to be separated by whitespace. CMake variables hold lists
9052 as a string with items separated by semi-colons, so a conversion needs
9053 to be performed. The doxygen_add_docs() command specifically checks the
9054 following Doxygen config options and will convert their associated
9055 CMake variable’s contents into the required form if set.
9056 ABBREVIATE_BRIEF
9058 ALIASES
9059 CITE_BIB_FILES
9060 DIAFILE_DIRS
9061 DOTFILE_DIRS
9062 DOT_FONTPATH
9063 ENABLED_SECTIONS
9064 EXAMPLE_PATH
9065 EXAMPLE_PATTERNS
9066 EXCLUDE
9067 EXCLUDE_PATTERNS
9068 EXCLUDE_SYMBOLS
9069 EXPAND_AS_DEFINED
9070 EXTENSION_MAPPING
9071 EXTRA_PACKAGES
9072 EXTRA_SEARCH_MAPPINGS
9073 FILE_PATTERNS
9074 FILTER_PATTERNS
9075 FILTER_SOURCE_PATTERNS
9076 HTML_EXTRA_FILES
9077 HTML_EXTRA_STYLESHEET
9078 IGNORE_PREFIX
9079 IMAGE_PATH
9080 INCLUDE_FILE_PATTERNS
9081 INCLUDE_PATH
9082 INPUT
9083 LATEX_EXTRA_FILES
9084 LATEX_EXTRA_STYLESHEET
9085 MATHJAX_EXTENSIONS
9086 MSCFILE_DIRS
9087 PLANTUML_INCLUDE_PATH
9088 PREDEFINED
9089 QHP_CUST_FILTER_ATTRS
9090 QHP_SECT_FILTER_ATTRS
9091 STRIP_FROM_INC_PATH
9092 STRIP_FROM_PATH
9093 TAGFILES
9094 TCL_SUBST
9095 The following single value Doxygen options will be quoted automatically
9097 if they contain at least one space:
9098 CHM_FILE
9100 DIA_PATH
9101 DOCBOOK_OUTPUT
9102 DOCSET_FEEDNAME
9103 DOCSET_PUBLISHER_NAME
9104 DOT_FONTNAME
9105 DOT_PATH
9106 EXTERNAL_SEARCH_ID
9107 FILE_VERSION_FILTER
9108 GENERATE_TAGFILE
9109 HHC_LOCATION
9110 HTML_FOOTER
9111 HTML_HEADER
9112 HTML_OUTPUT
9113 HTML_STYLESHEET
9114 INPUT_FILTER
9115 LATEX_FOOTER
9116 LATEX_HEADER
9117 LATEX_OUTPUT
9118 LAYOUT_FILE
9119 MAN_OUTPUT
9120 MAN_SUBDIR
9121 MATHJAX_CODEFILE
9122 MSCGEN_PATH
9123 OUTPUT_DIRECTORY
9124 PERL_PATH
9125 PLANTUML_JAR_PATH
9126 PROJECT_BRIEF
9127 PROJECT_LOGO
9128 PROJECT_NAME
9129 QCH_FILE
9130 QHG_LOCATION
9131 QHP_CUST_FILTER_NAME
9132 QHP_VIRTUAL_FOLDER
9133 RTF_EXTENSIONS_FILE
9134 RTF_OUTPUT
9135 RTF_STYLESHEET_FILE
9136 SEARCHDATA_FILE
9137 USE_MDFILE_AS_MAINPAGE
9138 WARN_FORMAT
9139 WARN_LOGFILE
9140 XML_OUTPUT
9141 There are situations where it may be undesirable for a particular con‐
9143 fig option to be automatically quoted by doxygen_add_docs(), such as
9144 ALIASES which may need to include its own embedded quoting. The DOXY‐
9145 GEN_VERBATIM_VARS variable can be used to specify a list of Doxygen
9146 variables (including the leading DOXYGEN_ prefix) which should not be
9147 quoted. The project is then responsible for ensuring that those vari‐
9148 ables’ values make sense when placed directly in the Doxygen input
9149 file. In the case of list variables, list items are still separated by
9150 spaces, it is only the automatic quoting that is skipped. For example,
9151 the following allows doxygen_add_docs() to apply quoting to DOXY‐
9152 GEN_PROJECT_BRIEF, but not each item in the DOXYGEN_ALIASES list
9153 (bracket syntax can also be used to make working with embedded quotes
9154 easier):
9155 set(DOXYGEN_PROJECT_BRIEF "String with spaces")
9157 set(DOXYGEN_ALIASES
9158 [[somealias="@some_command param"]]
9159 "anotherAlias=@foobar"
9160 )
9161 set(DOXYGEN_VERBATIM_VARS DOXYGEN_ALIASES)
9162 The resultant Doxyfile will contain the following lines:
9164 PROJECT_BRIEF = "String with spaces"
9166 ALIASES = somealias="@some_command param" anotherAlias=@foobar
9167 Deprecated Result Variables
9169 For compatibility with previous versions of CMake, the following vari‐
9170 ables are also defined but they are deprecated and should no longer be
9171 used:
9172 DOXYGEN_EXECUTABLE
9174 The path to the doxygen command. If projects need to refer to
9175 the doxygen executable directly, they should use the Doxy‐
9176 gen::doxygen import target instead.
9177 DOXYGEN_DOT_FOUND
9179 True if the dot executable was found.
9180 DOXYGEN_DOT_EXECUTABLE
9182 The path to the dot command. If projects need to refer to the
9183 dot executable directly, they should use the Doxygen::dot import
9184 target instead.
9185 DOXYGEN_DOT_PATH
9187 The path to the directory containing the dot executable as
9188 reported in DOXYGEN_DOT_EXECUTABLE. The path may have forward
9189 slashes even on Windows and is not suitable for direct substitu‐
9190 tion into a Doxyfile.in template. If you need this value, get
9191 the IMPORTED_LOCATION property of the Doxygen::dot target and
9192 use get_filename_component() to extract the directory part of
9193 that path. You may also want to consider using
9194 file(TO_NATIVE_PATH) to prepare the path for a Doxygen configu‐
9195 ration file.
9196 Deprecated Hint Variables
9198 DOXYGEN_SKIP_DOT
9199 This variable has no effect for the component form of find_pack‐
9200 age. In backward compatibility mode (i.e. without components
9201 list) it prevents the finder module from searching for
9202 Graphviz’s dot utility.
9203 FindEXPAT
9205 Find the native Expat headers and library.
9206 Imported Targets
9208 This module defines the following IMPORTED targets:
9209 EXPAT::EXPAT
9211 The Expat expat library, if found.
9212 Result Variables
9214 This module will set the following variables in your project:
9215 EXPAT_INCLUDE_DIRS
9217 where to find expat.h, etc.
9218 EXPAT_LIBRARIES
9220 the libraries to link against to use Expat.
9221 EXPAT_FOUND
9223 true if the Expat headers and libraries were found.
9224 FindFLEX
9226 Find flex executable and provides a macro to generate custom build
9227 rules
9228 The module defines the following variables:
9230 FLEX_FOUND - true is flex executable is found
9232 FLEX_EXECUTABLE - the path to the flex executable
9233 FLEX_VERSION - the version of flex
9234 FLEX_LIBRARIES - The flex libraries
9235 FLEX_INCLUDE_DIRS - The path to the flex headers
9236 The minimum required version of flex can be specified using the stan‐
9238 dard syntax, e.g. find_package(FLEX 2.5.13)
9239 If flex is found on the system, the module provides the macro:
9241 FLEX_TARGET(Name FlexInput FlexOutput
9243 [COMPILE_FLAGS <string>]
9244 [DEFINES_FILE <string>]
9245 )
9246 which creates a custom command to generate the <FlexOutput> file from
9248 the <FlexInput> file. If COMPILE_FLAGS option is specified, the next
9249 parameter is added to the flex command line. If flex is configured to
9250 output a header file, the DEFINES_FILE option may be used to specify
9251 its name. Name is an alias used to get details of this custom command.
9252 Indeed the macro defines the following variables:
9253 FLEX_${Name}_DEFINED - true is the macro ran successfully
9255 FLEX_${Name}_OUTPUTS - the source file generated by the custom rule, an
9256 alias for FlexOutput
9257 FLEX_${Name}_INPUT - the flex source file, an alias for ${FlexInput}
9258 FLEX_${Name}_OUTPUT_HEADER - the header flex output, if any.
9259 Flex scanners often use tokens defined by Bison: the code generated by
9261 Flex depends of the header generated by Bison. This module also
9262 defines a macro:
9263 ADD_FLEX_BISON_DEPENDENCY(FlexTarget BisonTarget)
9265 which adds the required dependency between a scanner and a parser where
9267 <FlexTarget> and <BisonTarget> are the first parameters of respectively
9268 FLEX_TARGET and BISON_TARGET macros.
9269 ====================================================================
9271 Example:
9272 find_package(BISON)
9274 find_package(FLEX)
9275 BISON_TARGET(MyParser parser.y ${CMAKE_CURRENT_BINARY_DIR}/parser.cpp)
9277 FLEX_TARGET(MyScanner lexer.l ${CMAKE_CURRENT_BINARY_DIR}/lexer.cpp)
9278 ADD_FLEX_BISON_DEPENDENCY(MyScanner MyParser)
9279 include_directories(${CMAKE_CURRENT_BINARY_DIR})
9281 add_executable(Foo
9282 Foo.cc
9283 ${BISON_MyParser_OUTPUTS}
9284 ${FLEX_MyScanner_OUTPUTS}
9285 )
9286 ====================================================================
9287 FindFLTK2
9289 Find the native FLTK2 includes and library
9290 The following settings are defined
9292 FLTK2_FLUID_EXECUTABLE, where to find the Fluid tool
9294 FLTK2_WRAP_UI, This enables the FLTK2_WRAP_UI command
9295 FLTK2_INCLUDE_DIR, where to find include files
9296 FLTK2_LIBRARIES, list of fltk2 libraries
9297 FLTK2_FOUND, Don't use FLTK2 if false.
9298 The following settings should not be used in general.
9300 FLTK2_BASE_LIBRARY = the full path to fltk2.lib
9302 FLTK2_GL_LIBRARY = the full path to fltk2_gl.lib
9303 FLTK2_IMAGES_LIBRARY = the full path to fltk2_images.lib
9304 FindFLTK
9306 Find the FLTK library
9307 Input Variables
9309 By default this module will search for all of the FLTK components and
9310 add them to the FLTK_LIBRARIES variable. You can limit the components
9311 which get placed in FLTK_LIBRARIES by defining one or more of the fol‐
9312 lowing three options:
9313 FLTK_SKIP_OPENGL
9315 Set to true to disable searching for the FLTK GL library
9316 FLTK_SKIP_FORMS
9318 Set to true to disable searching for the FLTK Forms library
9319 FLTK_SKIP_IMAGES
9321 Set to true to disable searching for the FLTK Images library
9322 FLTK is composed also by a binary tool. You can set the following
9324 option:
9325 FLTK_SKIP_FLUID
9327 Set to true to not look for the FLUID binary
9328 Result Variables
9330 The following variables will be defined:
9331 FLTK_FOUND
9333 True if all components not skipped were found
9334 FLTK_INCLUDE_DIR
9336 Path to the include directory for FLTK header files
9337 FLTK_LIBRARIES
9339 List of the FLTK libraries found
9340 FLTK_FLUID_EXECUTABLE
9342 Path to the FLUID binary tool
9343 FLTK_WRAP_UI
9345 True if FLUID is found, used to enable the FLTK_WRAP_UI command
9346 Cache Variables
9348 The following cache variables are also available to set or use:
9349 FLTK_BASE_LIBRARY_RELEASE
9351 The FLTK base library (optimized)
9352 FLTK_BASE_LIBRARY_DEBUG
9354 The FLTK base library (debug)
9355 FLTK_GL_LIBRARY_RELEASE
9357 The FLTK GL library (optimized)
9358 FLTK_GL_LIBRARY_DEBUG
9360 The FLTK GL library (debug)
9361 FLTK_FORMS_LIBRARY_RELEASE
9363 The FLTK Forms library (optimized)
9364 FLTK_FORMS_LIBRARY_DEBUG
9366 The FLTK Forms library (debug)
9367 FLTK_IMAGES_LIBRARY_RELEASE
9369 The FLTK Images protobuf library (optimized)
9370 FLTK_IMAGES_LIBRARY_DEBUG
9372 The FLTK Images library (debug)
9373 FindFreetype
9375 Find the FreeType font renderer includes and library.
9376 Imported Targets
9378 This module defines the following IMPORTED target:
9379 Freetype::Freetype
9381 The Freetype freetype library, if found
9382 Result Variables
9384 This module will set the following variables in your project:
9385 FREETYPE_FOUND
9387 true if the Freetype headers and libraries were found
9388 FREETYPE_INCLUDE_DIRS
9390 directories containing the Freetype headers. This is the con‐
9391 catenation of the variables:
9392 FREETYPE_INCLUDE_DIR_ft2build
9394 directory holding the main Freetype API configuration
9395 header
9396 FREETYPE_INCLUDE_DIR_freetype2
9398 directory holding Freetype public headers
9399 FREETYPE_LIBRARIES
9401 the library to link against
9402 FREETYPE_VERSION_STRING
9404 the version of freetype found (since CMake 2.8.8)
9405 Hints
9407 The user may set the environment variable FREETYPE_DIR to the root
9408 directory of a Freetype installation.
9409 FindGCCXML
9411 Find the GCC-XML front-end executable.
9412 This module will define the following variables:
9414 GCCXML - the GCC-XML front-end executable.
9416 FindGDAL
9418 Locate gdal
9419 This module accepts the following environment variables:
9421 GDAL_DIR or GDAL_ROOT - Specify the location of GDAL
9423 This module defines the following CMake variables:
9425 GDAL_FOUND - True if libgdal is found
9427 GDAL_LIBRARY - A variable pointing to the GDAL library
9428 GDAL_INCLUDE_DIR - Where to find the headers
9429 FindGettext
9431 Find GNU gettext tools
9432 This module looks for the GNU gettext tools. This module defines the
9434 following values:
9435 GETTEXT_MSGMERGE_EXECUTABLE: the full path to the msgmerge tool.
9437 GETTEXT_MSGFMT_EXECUTABLE: the full path to the msgfmt tool.
9438 GETTEXT_FOUND: True if gettext has been found.
9439 GETTEXT_VERSION_STRING: the version of gettext found (since CMake 2.8.8)
9440 Additionally it provides the following macros:
9442 GETTEXT_CREATE_TRANSLATIONS ( outputFile [ALL] file1 … fileN )
9444 This will create a target "translations" which will convert the
9446 given input po files into the binary output mo file. If the
9447 ALL option is used, the translations will also be created when
9448 building the default target.
9449 GETTEXT_PROCESS_POT_FILE( <potfile> [ALL] [INSTALL_DESTINATION <dest‐
9451 dir>] LANGUAGES <lang1> <lang2> … )
9452 Process the given pot file to mo files.
9454 If INSTALL_DESTINATION is given then automatically install rules will
9455 be created, the language subdirectory will be taken into account
9456 (by default use share/locale/).
9457 If ALL is specified, the pot file is processed when building the all traget.
9458 It creates a custom target "potfile".
9459 GETTEXT_PROCESS_PO_FILES( <lang> [ALL] [INSTALL_DESTINATION <dir>]
9461 PO_FILES <po1> <po2> … )
9462 Process the given po files to mo files for the given language.
9464 If INSTALL_DESTINATION is given then automatically install rules will
9465 be created, the language subdirectory will be taken into account
9466 (by default use share/locale/).
9467 If ALL is specified, the po files are processed when building the all traget.
9468 It creates a custom target "pofiles".
9469 NOTE:
9471 If you wish to use the Gettext library (libintl), use FindIntl.
9472 FindGIF
9474 This finds the GIF library (giflib)
9475 The module defines the following variables:
9477 GIF_FOUND
9479 True if giflib was found
9480 GIF_LIBRARIES
9482 Libraries to link to in order to use giflib
9483 GIF_INCLUDE_DIR
9485 where to find the headers
9486 GIF_VERSION
9488 3, 4 or a full version string (eg 5.1.4) for versions >= 4.1.6
9489 The minimum required version of giflib can be specified using the stan‐
9491 dard syntax, e.g. find_package(GIF 4)
9492 $GIF_DIR is an environment variable that would correspond to the
9494 FindGit
9496 The module defines the following variables:
9497 GIT_EXECUTABLE
9499 Path to Git command-line client.
9500 Git_FOUND, GIT_FOUND
9502 True if the Git command-line client was found.
9503 GIT_VERSION_STRING
9505 The version of Git found.
9506 Example usage:
9508 find_package(Git)
9510 if(Git_FOUND)
9511 message("Git found: ${GIT_EXECUTABLE}")
9512 endif()
9513 FindGLEW
9515 Find the OpenGL Extension Wrangler Library (GLEW)
9516 IMPORTED Targets
9518 This module defines the IMPORTED target GLEW::GLEW, if GLEW has been
9519 found.
9520 Result Variables
9522 This module defines the following variables:
9523 GLEW_INCLUDE_DIRS - include directories for GLEW
9525 GLEW_LIBRARIES - libraries to link against GLEW
9526 GLEW_FOUND - true if GLEW has been found and can be used
9527 FindGLUT
9529 try to find glut library and include files.
9530 IMPORTED Targets
9532 This module defines the IMPORTED targets:
9533 GLUT::GLUT
9535 Defined if the system has GLUT.
9536 Result Variables
9538 This module sets the following variables:
9539 GLUT_INCLUDE_DIR, where to find GL/glut.h, etc.
9541 GLUT_LIBRARIES, the libraries to link against
9542 GLUT_FOUND, If false, do not try to use GLUT.
9543 Also defined, but not for general use are:
9545 GLUT_glut_LIBRARY = the full path to the glut library.
9547 GLUT_Xmu_LIBRARY = the full path to the Xmu library.
9548 GLUT_Xi_LIBRARY = the full path to the Xi Library.
9549 FindGnuplot
9551 this module looks for gnuplot
9552 Once done this will define
9554 GNUPLOT_FOUND - system has Gnuplot
9556 GNUPLOT_EXECUTABLE - the Gnuplot executable
9557 GNUPLOT_VERSION_STRING - the version of Gnuplot found (since CMake 2.8.8)
9558 GNUPLOT_VERSION_STRING will not work for old versions like 3.7.1.
9560 FindGnuTLS
9562 Try to find the GNU Transport Layer Security library (gnutls)
9563 Once done this will define
9565 GNUTLS_FOUND - System has gnutls
9567 GNUTLS_INCLUDE_DIR - The gnutls include directory
9568 GNUTLS_LIBRARIES - The libraries needed to use gnutls
9569 GNUTLS_DEFINITIONS - Compiler switches required for using gnutls
9570 FindGSL
9572 Find the native GSL includes and libraries.
9573 The GNU Scientific Library (GSL) is a numerical library for C and C++
9575 programmers. It is free software under the GNU General Public License.
9576 Imported Targets
9578 If GSL is found, this module defines the following IMPORTED targets:
9579 GSL::gsl - The main GSL library.
9581 GSL::gslcblas - The CBLAS support library used by GSL.
9582 Result Variables
9584 This module will set the following variables in your project:
9585 GSL_FOUND - True if GSL found on the local system
9587 GSL_INCLUDE_DIRS - Location of GSL header files.
9588 GSL_LIBRARIES - The GSL libraries.
9589 GSL_VERSION - The version of the discovered GSL install.
9590 Hints
9592 Set GSL_ROOT_DIR to a directory that contains a GSL installation.
9593 This script expects to find libraries at $GSL_ROOT_DIR/lib and the GSL
9595 headers at $GSL_ROOT_DIR/include/gsl. The library directory may
9596 optionally provide Release and Debug folders. If available, the
9597 libraries named gsld, gslblasd or cblasd are recognized as debug
9598 libraries. For Unix-like systems, this script will use
9599 $GSL_ROOT_DIR/bin/gsl-config (if found) to aid in the discovery of GSL.
9600 Cache Variables
9602 This module may set the following variables depending on platform and
9603 type of GSL installation discovered. These variables may optionally be
9604 set to help this module find the correct files:
9605 GSL_CBLAS_LIBRARY - Location of the GSL CBLAS library.
9607 GSL_CBLAS_LIBRARY_DEBUG - Location of the debug GSL CBLAS library (if any).
9608 GSL_CONFIG_EXECUTABLE - Location of the ``gsl-config`` script (if any).
9609 GSL_LIBRARY - Location of the GSL library.
9610 GSL_LIBRARY_DEBUG - Location of the debug GSL library (if any).
9611 FindGTest
9613 Locate the Google C++ Testing Framework.
9614 Imported targets
9616 This module defines the following IMPORTED targets:
9617 GTest::GTest
9619 The Google Test gtest library, if found; adds Thread::Thread
9620 automatically
9621 GTest::Main
9623 The Google Test gtest_main library, if found
9624 Result variables
9626 This module will set the following variables in your project:
9627 GTEST_FOUND
9629 Found the Google Testing framework
9630 GTEST_INCLUDE_DIRS
9632 the directory containing the Google Test headers
9633 The library variables below are set as normal variables. These contain
9635 debug/optimized keywords when a debugging library is found.
9636 GTEST_LIBRARIES
9638 The Google Test gtest library; note it also requires linking
9639 with an appropriate thread library
9640 GTEST_MAIN_LIBRARIES
9642 The Google Test gtest_main library
9643 GTEST_BOTH_LIBRARIES
9645 Both gtest and gtest_main
9646 Cache variables
9648 The following cache variables may also be set:
9649 GTEST_ROOT
9651 The root directory of the Google Test installation (may also be
9652 set as an environment variable)
9653 GTEST_MSVC_SEARCH
9655 If compiling with MSVC, this variable can be set to MT or MD
9656 (the default) to enable searching a GTest build tree
9657 Example usage
9659 enable_testing()
9660 find_package(GTest REQUIRED)
9661 add_executable(foo foo.cc)
9663 target_link_libraries(foo GTest::GTest GTest::Main)
9664 add_test(AllTestsInFoo foo)
9666 Deeper integration with CTest
9668 See GoogleTest for information on the gtest_add_tests() and gtest_dis‐
9669 cover_tests() commands.
9670 FindGTK2
9672 FindGTK2.cmake
9673 This module can find the GTK2 widget libraries and several of its other
9675 optional components like gtkmm, glade, and glademm.
9676 NOTE: If you intend to use version checking, CMake 2.6.2 or later is
9678 required.
9680 Specify one or more of the following components as you call this find
9682 module. See example below.
9683 gtk
9685 gtkmm
9686 glade
9687 glademm
9688 The following variables will be defined for your use
9690 GTK2_FOUND - Were all of your specified components found?
9692 GTK2_INCLUDE_DIRS - All include directories
9693 GTK2_LIBRARIES - All libraries
9694 GTK2_TARGETS - All imported targets
9695 GTK2_DEFINITIONS - Additional compiler flags
9696 GTK2_VERSION - The version of GTK2 found (x.y.z)
9698 GTK2_MAJOR_VERSION - The major version of GTK2
9699 GTK2_MINOR_VERSION - The minor version of GTK2
9700 GTK2_PATCH_VERSION - The patch version of GTK2
9701 Optional variables you can define prior to calling this module:
9703 GTK2_DEBUG - Enables verbose debugging of the module
9705 GTK2_ADDITIONAL_SUFFIXES - Allows defining additional directories to
9706 search for include files
9707 ================= Example Usage:
9709 Call find_package() once, here are some examples to pick from:
9711 Require GTK 2.6 or later
9713 find_package(GTK2 2.6 REQUIRED gtk)
9714 Require GTK 2.10 or later and Glade
9716 find_package(GTK2 2.10 REQUIRED gtk glade)
9717 Search for GTK/GTKMM 2.8 or later
9719 find_package(GTK2 2.8 COMPONENTS gtk gtkmm)
9720 if(GTK2_FOUND)
9722 include_directories(${GTK2_INCLUDE_DIRS})
9723 add_executable(mygui mygui.cc)
9724 target_link_libraries(mygui ${GTK2_LIBRARIES})
9725 endif()
9726 FindGTK
9728 try to find GTK (and glib) and GTKGLArea
9729 GTK_INCLUDE_DIR - Directories to include to use GTK
9731 GTK_LIBRARIES - Files to link against to use GTK
9732 GTK_FOUND - GTK was found
9733 GTK_GL_FOUND - GTK's GL features were found
9734 FindHDF5
9736 Find HDF5, a library for reading and writing self describing array
9737 data.
9738 This module invokes the HDF5 wrapper compiler that should be installed
9740 alongside HDF5. Depending upon the HDF5 Configuration, the wrapper
9741 compiler is called either h5cc or h5pcc. If this succeeds, the module
9742 will then call the compiler with the -show argument to see what flags
9743 are used when compiling an HDF5 client application.
9744 The module will optionally accept the COMPONENTS argument. If no COM‐
9746 PONENTS are specified, then the find module will default to finding
9747 only the HDF5 C library. If one or more COMPONENTS are specified, the
9748 module will attempt to find the language bindings for the specified
9749 components. The only valid components are C, CXX, Fortran, HL, and
9750 Fortran_HL. If the COMPONENTS argument is not given, the module will
9751 attempt to find only the C bindings.
9752 This module will read the variable HDF5_USE_STATIC_LIBRARIES to deter‐
9754 mine whether or not to prefer a static link to a dynamic link for HDF5
9755 and all of it’s dependencies. To use this feature, make sure that the
9756 HDF5_USE_STATIC_LIBRARIES variable is set before the call to find_pack‐
9757 age.
9758 To provide the module with a hint about where to find your HDF5 instal‐
9760 lation, you can set the environment variable HDF5_ROOT. The Find mod‐
9761 ule will then look in this path when searching for HDF5 executables,
9762 paths, and libraries.
9763 Both the serial and parallel HDF5 wrappers are considered and the first
9765 directory to contain either one will be used. In the event that both
9766 appear in the same directory the serial version is preferentially
9767 selected. This behavior can be reversed by setting the variable
9768 HDF5_PREFER_PARALLEL to true.
9769 In addition to finding the includes and libraries required to compile
9771 an HDF5 client application, this module also makes an effort to find
9772 tools that come with the HDF5 distribution that may be useful for
9773 regression testing.
9774 This module will define the following variables:
9776 HDF5_FOUND - true if HDF5 was found on the system
9778 HDF5_VERSION - HDF5 version in format Major.Minor.Release
9779 HDF5_INCLUDE_DIRS - Location of the hdf5 includes
9780 HDF5_INCLUDE_DIR - Location of the hdf5 includes (deprecated)
9781 HDF5_DEFINITIONS - Required compiler definitions for HDF5
9782 HDF5_LIBRARIES - Required libraries for all requested bindings
9783 HDF5_HL_LIBRARIES - Required libraries for the HDF5 high level API for all
9784 bindings, if the HL component is enabled
9785 Available components are: C CXX Fortran and HL. For each enabled lan‐
9787 guage binding, a corresponding HDF5_${LANG}_LIBRARIES variable, and
9788 potentially HDF5_${LANG}_DEFINITIONS, will be defined. If the HL com‐
9789 ponent is enabled, then an HDF5_${LANG}_HL_LIBRARIES will also be
9790 defined. With all components enabled, the following variables will be
9791 defined:
9792 HDF5_C_DEFINITIONS -- Required compiler definitions for HDF5 C bindings
9794 HDF5_CXX_DEFINITIONS -- Required compiler definitions for HDF5 C++ bindings
9795 HDF5_Fortran_DEFINITIONS -- Required compiler definitions for HDF5 Fortran bindings
9796 HDF5_C_INCLUDE_DIRS -- Required include directories for HDF5 C bindings
9797 HDF5_CXX_INCLUDE_DIRS -- Required include directories for HDF5 C++ bindings
9798 HDF5_Fortran_INCLUDE_DIRS -- Required include directories for HDF5 Fortran bindings
9799 HDF5_C_LIBRARIES - Required libraries for the HDF5 C bindings
9800 HDF5_CXX_LIBRARIES - Required libraries for the HDF5 C++ bindings
9801 HDF5_Fortran_LIBRARIES - Required libraries for the HDF5 Fortran bindings
9802 HDF5_C_HL_LIBRARIES - Required libraries for the high level C bindings
9803 HDF5_CXX_HL_LIBRARIES - Required libraries for the high level C++ bindings
9804 HDF5_Fortran_HL_LIBRARIES - Required libraries for the high level Fortran
9805 bindings.
9806 HDF5_IS_PARALLEL - Whether or not HDF5 was found with parallel IO support
9808 HDF5_C_COMPILER_EXECUTABLE - the path to the HDF5 C wrapper compiler
9809 HDF5_CXX_COMPILER_EXECUTABLE - the path to the HDF5 C++ wrapper compiler
9810 HDF5_Fortran_COMPILER_EXECUTABLE - the path to the HDF5 Fortran wrapper compiler
9811 HDF5_C_COMPILER_EXECUTABLE_NO_INTERROGATE - path to the primary C compiler
9812 which is also the HDF5 wrapper
9813 HDF5_CXX_COMPILER_EXECUTABLE_NO_INTERROGATE - path to the primary C++
9814 compiler which is also
9815 the HDF5 wrapper
9816 HDF5_Fortran_COMPILER_EXECUTABLE_NO_INTERROGATE - path to the primary
9817 Fortran compiler which
9818 is also the HDF5 wrapper
9819 HDF5_DIFF_EXECUTABLE - the path to the HDF5 dataset comparison tool
9820 The following variable can be set to guide the search for HDF5
9822 libraries and includes:
9823 HDF5_ROOT
9825 Specify the path to the HDF5 installation to use.
9826 HDF5_FIND_DEBUG
9828 Set to a true value to get some extra debugging output.
9829 HDF5_NO_FIND_PACKAGE_CONFIG_FILE
9831 Set to a true value to skip trying to find hdf5-config.cmake.
9832 FindHg
9834 Extract information from a mercurial working copy.
9835 The module defines the following variables:
9837 HG_EXECUTABLE - path to mercurial command line client (hg)
9839 HG_FOUND - true if the command line client was found
9840 HG_VERSION_STRING - the version of mercurial found
9841 If the command line client executable is found the following macro is
9843 defined:
9844 HG_WC_INFO(<dir> <var-prefix>)
9846 Hg_WC_INFO extracts information of a mercurial working copy at a given
9848 location. This macro defines the following variables:
9849 <var-prefix>_WC_CHANGESET - current changeset
9851 <var-prefix>_WC_REVISION - current revision
9852 Example usage:
9854 find_package(Hg)
9856 if(HG_FOUND)
9857 message("hg found: ${HG_EXECUTABLE}")
9858 HG_WC_INFO(${PROJECT_SOURCE_DIR} Project)
9859 message("Current revision is ${Project_WC_REVISION}")
9860 message("Current changeset is ${Project_WC_CHANGESET}")
9861 endif()
9862 FindHSPELL
9864 Try to find Hspell
9865 Once done this will define
9867 HSPELL_FOUND - system has Hspell
9869 HSPELL_INCLUDE_DIR - the Hspell include directory
9870 HSPELL_LIBRARIES - The libraries needed to use Hspell
9871 HSPELL_DEFINITIONS - Compiler switches required for using Hspell
9872 HSPELL_VERSION_STRING - The version of Hspell found (x.y)
9874 HSPELL_MAJOR_VERSION - the major version of Hspell
9875 HSPELL_MINOR_VERSION - The minor version of Hspell
9876 FindHTMLHelp
9878 This module looks for Microsoft HTML Help Compiler
9879 It defines:
9881 HTML_HELP_COMPILER : full path to the Compiler (hhc.exe)
9883 HTML_HELP_INCLUDE_PATH : include path to the API (htmlhelp.h)
9884 HTML_HELP_LIBRARY : full path to the library (htmlhelp.lib)
9885 FindIce
9887 Find the ZeroC Internet Communication Engine (ICE) programs, libraries
9888 and datafiles.
9889 This module supports multiple components. Components can include any
9891 of: Freeze, Glacier2, Ice, IceBox, IceDB, IceDiscovery, IceGrid, IceLo‐
9892 catorDiscovery, IcePatch, IceSSL, IceStorm, IceUtil, IceXML, or Slice.
9893 Ice 3.7 and later also include C++11-specific components: Glacier2++11,
9895 Ice++11, IceBox++11, IceDiscovery++11 IceGrid, IceLocatorDiscovery++11,
9896 IceSSL++11, IceStorm++11
9897 Note that the set of supported components is Ice version-specific.
9899 This module reports information about the Ice installation in several
9901 variables. General variables:
9902 Ice_VERSION - Ice release version
9904 Ice_FOUND - true if the main programs and libraries were found
9905 Ice_LIBRARIES - component libraries to be linked
9906 Ice_INCLUDE_DIRS - the directories containing the Ice headers
9907 Ice_SLICE_DIRS - the directories containing the Ice slice interface
9908 definitions
9909 Imported targets:
9911 Ice::<C>
9913 Where <C> is the name of an Ice component, for example Ice::Glacier2 or
9915 Ice++11.
9916 Ice slice programs are reported in:
9918 Ice_SLICE2CPP_EXECUTABLE - path to slice2cpp executable
9920 Ice_SLICE2CS_EXECUTABLE - path to slice2cs executable
9921 Ice_SLICE2FREEZEJ_EXECUTABLE - path to slice2freezej executable
9922 Ice_SLICE2FREEZE_EXECUTABLE - path to slice2freeze executable
9923 Ice_SLICE2HTML_EXECUTABLE - path to slice2html executable
9924 Ice_SLICE2JAVA_EXECUTABLE - path to slice2java executable
9925 Ice_SLICE2JS_EXECUTABLE - path to slice2js executable
9926 Ice_SLICE2OBJC_EXECUTABLE - path to slice2objc executable
9927 Ice_SLICE2PHP_EXECUTABLE - path to slice2php executable
9928 Ice_SLICE2PY_EXECUTABLE - path to slice2py executable
9929 Ice_SLICE2RB_EXECUTABLE - path to slice2rb executable
9930 Ice programs are reported in:
9932 Ice_GLACIER2ROUTER_EXECUTABLE - path to glacier2router executable
9934 Ice_ICEBOX_EXECUTABLE - path to icebox executable
9935 Ice_ICEBOXXX11_EXECUTABLE - path to icebox++11 executable
9936 Ice_ICEBOXADMIN_EXECUTABLE - path to iceboxadmin executable
9937 Ice_ICEBOXD_EXECUTABLE - path to iceboxd executable
9938 Ice_ICEBOXNET_EXECUTABLE - path to iceboxnet executable
9939 Ice_ICEBRIDGE_EXECUTABLE - path to icebridge executable
9940 Ice_ICEGRIDADMIN_EXECUTABLE - path to icegridadmin executable
9941 Ice_ICEGRIDDB_EXECUTABLE - path to icegriddb executable
9942 Ice_ICEGRIDNODE_EXECUTABLE - path to icegridnode executable
9943 Ice_ICEGRIDNODED_EXECUTABLE - path to icegridnoded executable
9944 Ice_ICEGRIDREGISTRY_EXECUTABLE - path to icegridregistry executable
9945 Ice_ICEGRIDREGISTRYD_EXECUTABLE - path to icegridregistryd executable
9946 Ice_ICEPATCH2CALC_EXECUTABLE - path to icepatch2calc executable
9947 Ice_ICEPATCH2CLIENT_EXECUTABLE - path to icepatch2client executable
9948 Ice_ICEPATCH2SERVER_EXECUTABLE - path to icepatch2server executable
9949 Ice_ICESERVICEINSTALL_EXECUTABLE - path to iceserviceinstall executable
9950 Ice_ICESTORMADMIN_EXECUTABLE - path to icestormadmin executable
9951 Ice_ICESTORMDB_EXECUTABLE - path to icestormdb executable
9952 Ice_ICESTORMMIGRATE_EXECUTABLE - path to icestormmigrate executable
9953 Ice db programs (Windows only; standard system versions on all other
9955 platforms) are reported in:
9956 Ice_DB_ARCHIVE_EXECUTABLE - path to db_archive executable
9958 Ice_DB_CHECKPOINT_EXECUTABLE - path to db_checkpoint executable
9959 Ice_DB_DEADLOCK_EXECUTABLE - path to db_deadlock executable
9960 Ice_DB_DUMP_EXECUTABLE - path to db_dump executable
9961 Ice_DB_HOTBACKUP_EXECUTABLE - path to db_hotbackup executable
9962 Ice_DB_LOAD_EXECUTABLE - path to db_load executable
9963 Ice_DB_LOG_VERIFY_EXECUTABLE - path to db_log_verify executable
9964 Ice_DB_PRINTLOG_EXECUTABLE - path to db_printlog executable
9965 Ice_DB_RECOVER_EXECUTABLE - path to db_recover executable
9966 Ice_DB_STAT_EXECUTABLE - path to db_stat executable
9967 Ice_DB_TUNER_EXECUTABLE - path to db_tuner executable
9968 Ice_DB_UPGRADE_EXECUTABLE - path to db_upgrade executable
9969 Ice_DB_VERIFY_EXECUTABLE - path to db_verify executable
9970 Ice_DUMPDB_EXECUTABLE - path to dumpdb executable
9971 Ice_TRANSFORMDB_EXECUTABLE - path to transformdb executable
9972 Ice component libraries are reported in:
9974 Ice_<C>_FOUND - ON if component was found
9976 Ice_<C>_LIBRARIES - libraries for component
9977 Note that <C> is the uppercased name of the component.
9979 This module reads hints about search results from:
9981 Ice_HOME - the root of the Ice installation
9983 The environment variable ICE_HOME may also be used; the Ice_HOME vari‐
9985 able takes precedence.
9986 NOTE:
9988 On Windows, Ice 3.7.0 and later provide libraries via the NuGet
9989 package manager. Appropriate NuGet packages will be searched for
9990 using CMAKE_PREFIX_PATH, or alternatively Ice_HOME may be set to the
9991 location of a specific NuGet package to restrict the search.
9992 The following cache variables may also be set:
9994 Ice_<P>_EXECUTABLE - the path to executable <P>
9996 Ice_INCLUDE_DIR - the directory containing the Ice headers
9997 Ice_SLICE_DIR - the directory containing the Ice slice interface
9998 definitions
9999 Ice_<C>_LIBRARY - the library for component <C>
10000 NOTE:
10002 In most cases none of the above variables will require setting,
10003 unless multiple Ice versions are available and a specific version is
10004 required. On Windows, the most recent version of Ice will be found
10005 through the registry. On Unix, the programs, headers and libraries
10006 will usually be in standard locations, but Ice_SLICE_DIRS might not
10007 be automatically detected (commonly known locations are searched).
10008 All the other variables are defaulted using Ice_HOME, if set. It’s
10009 possible to set Ice_HOME and selectively specify alternative loca‐
10010 tions for the other components; this might be required for e.g.
10011 newer versions of Visual Studio if the heuristics are not sufficient
10012 to identify the correct programs and libraries for the specific Vis‐
10013 ual Studio version.
10014 Other variables one may set to control this module are:
10016 Ice_DEBUG - Set to ON to enable debug output from FindIce.
10018 FindIcotool
10020 Find icotool
10021 This module looks for icotool. This module defines the following val‐
10023 ues:
10024 ICOTOOL_EXECUTABLE: the full path to the icotool tool.
10026 ICOTOOL_FOUND: True if icotool has been found.
10027 ICOTOOL_VERSION_STRING: the version of icotool found.
10028 FindICU
10030 Find the International Components for Unicode (ICU) libraries and pro‐
10031 grams.
10032 This module supports multiple components. Components can include any
10034 of: data, i18n, io, le, lx, test, tu and uc.
10035 Note that on Windows data is named dt and i18n is named in; any of the
10037 names may be used, and the appropriate platform-specific library name
10038 will be automatically selected.
10039 This module reports information about the ICU installation in several
10041 variables. General variables:
10042 ICU_VERSION - ICU release version
10044 ICU_FOUND - true if the main programs and libraries were found
10045 ICU_LIBRARIES - component libraries to be linked
10046 ICU_INCLUDE_DIRS - the directories containing the ICU headers
10047 Imported targets:
10049 ICU::<C>
10051 Where <C> is the name of an ICU component, for example ICU::i18n.
10053 ICU programs are reported in:
10055 ICU_GENCNVAL_EXECUTABLE - path to gencnval executable
10057 ICU_ICUINFO_EXECUTABLE - path to icuinfo executable
10058 ICU_GENBRK_EXECUTABLE - path to genbrk executable
10059 ICU_ICU-CONFIG_EXECUTABLE - path to icu-config executable
10060 ICU_GENRB_EXECUTABLE - path to genrb executable
10061 ICU_GENDICT_EXECUTABLE - path to gendict executable
10062 ICU_DERB_EXECUTABLE - path to derb executable
10063 ICU_PKGDATA_EXECUTABLE - path to pkgdata executable
10064 ICU_UCONV_EXECUTABLE - path to uconv executable
10065 ICU_GENCFU_EXECUTABLE - path to gencfu executable
10066 ICU_MAKECONV_EXECUTABLE - path to makeconv executable
10067 ICU_GENNORM2_EXECUTABLE - path to gennorm2 executable
10068 ICU_GENCCODE_EXECUTABLE - path to genccode executable
10069 ICU_GENSPREP_EXECUTABLE - path to gensprep executable
10070 ICU_ICUPKG_EXECUTABLE - path to icupkg executable
10071 ICU_GENCMN_EXECUTABLE - path to gencmn executable
10072 ICU component libraries are reported in:
10074 ICU_<C>_FOUND - ON if component was found
10076 ICU_<C>_LIBRARIES - libraries for component
10077 ICU datafiles are reported in:
10079 ICU_MAKEFILE_INC - Makefile.inc
10081 ICU_PKGDATA_INC - pkgdata.inc
10082 Note that <C> is the uppercased name of the component.
10084 This module reads hints about search results from:
10086 ICU_ROOT - the root of the ICU installation
10088 The environment variable ICU_ROOT may also be used; the ICU_ROOT vari‐
10090 able takes precedence.
10091 The following cache variables may also be set:
10093 ICU_<P>_EXECUTABLE - the path to executable <P>
10095 ICU_INCLUDE_DIR - the directory containing the ICU headers
10096 ICU_<C>_LIBRARY - the library for component <C>
10097 NOTE:
10099 In most cases none of the above variables will require setting,
10100 unless multiple ICU versions are available and a specific version is
10101 required.
10102 Other variables one may set to control this module are:
10104 ICU_DEBUG - Set to ON to enable debug output from FindICU.
10106 FindImageMagick
10108 Find the ImageMagick binary suite.
10109 This module will search for a set of ImageMagick tools specified as
10111 components in the FIND_PACKAGE call. Typical components include, but
10112 are not limited to (future versions of ImageMagick might have addi‐
10113 tional components not listed here):
10114 animate
10116 compare
10117 composite
10118 conjure
10119 convert
10120 display
10121 identify
10122 import
10123 mogrify
10124 montage
10125 stream
10126 If no component is specified in the FIND_PACKAGE call, then it only
10128 searches for the ImageMagick executable directory. This code defines
10129 the following variables:
10130 ImageMagick_FOUND - TRUE if all components are found.
10132 ImageMagick_EXECUTABLE_DIR - Full path to executables directory.
10133 ImageMagick_<component>_FOUND - TRUE if <component> is found.
10134 ImageMagick_<component>_EXECUTABLE - Full path to <component> executable.
10135 ImageMagick_VERSION_STRING - the version of ImageMagick found
10136 (since CMake 2.8.8)
10137 ImageMagick_VERSION_STRING will not work for old versions like 5.2.3.
10139 There are also components for the following ImageMagick APIs:
10141 Magick++
10143 MagickWand
10144 MagickCore
10145 For these components the following variables are set:
10147 ImageMagick_FOUND - TRUE if all components are found.
10149 ImageMagick_INCLUDE_DIRS - Full paths to all include dirs.
10150 ImageMagick_LIBRARIES - Full paths to all libraries.
10151 ImageMagick_<component>_FOUND - TRUE if <component> is found.
10152 ImageMagick_<component>_INCLUDE_DIRS - Full path to <component> include dirs.
10153 ImageMagick_<component>_LIBRARIES - Full path to <component> libraries.
10154 Example Usages:
10156 find_package(ImageMagick)
10158 find_package(ImageMagick COMPONENTS convert)
10159 find_package(ImageMagick COMPONENTS convert mogrify display)
10160 find_package(ImageMagick COMPONENTS Magick++)
10161 find_package(ImageMagick COMPONENTS Magick++ convert)
10162 Note that the standard FIND_PACKAGE features are supported (i.e.,
10164 QUIET, REQUIRED, etc.).
10165 FindIconv
10167 This module finds the iconv() POSIX.1 functions on the system. These
10168 functions might be provided in the regular C library or externally in
10169 the form of an additional library.
10170 The following variables are provided to indicate iconv support:
10172 Iconv_FOUND
10174 Variable indicating if the iconv support was found.
10175 Iconv_INCLUDE_DIRS
10177 The directories containing the iconv headers.
10178 Iconv_LIBRARIES
10180 The iconv libraries to be linked.
10181 Iconv_IS_BUILT_IN
10183 A variable indicating whether iconv support is stemming from the
10184 C library or not. Even if the C library provides iconv(), the
10185 presence of an external libiconv implementation might lead to
10186 this being false.
10187 Additionally, the following IMPORTED target is being provided:
10189 Iconv::Iconv
10191 Imported target for using iconv.
10192 The following cache variables may also be set:
10194 Iconv_INCLUDE_DIR
10196 The directory containing the iconv headers.
10197 Iconv_LIBRARY
10199 The iconv library (if not implicitly given in the C library).
10200 NOTE:
10202 On POSIX platforms, iconv might be part of the C library and the
10203 cache variables Iconv_INCLUDE_DIR and Iconv_LIBRARY might be empty.
10204 FindIntl
10206 Find the Gettext libintl headers and libraries.
10207 This module reports information about the Gettext libintl installation
10209 in several variables. General variables:
10210 Intl_FOUND - true if the libintl headers and libraries were found
10212 Intl_INCLUDE_DIRS - the directory containing the libintl headers
10213 Intl_LIBRARIES - libintl libraries to be linked
10214 The following cache variables may also be set:
10216 Intl_INCLUDE_DIR - the directory containing the libintl headers
10218 Intl_LIBRARY - the libintl library (if any)
10219 NOTE:
10221 On some platforms, such as Linux with GNU libc, the gettext func‐
10222 tions are present in the C standard library and libintl is not
10223 required. Intl_LIBRARIES will be empty in this case.
10224 NOTE:
10226 If you wish to use the Gettext tools (msgmerge, msgfmt, etc.), use
10227 FindGettext.
10228 FindITK
10230 This module no longer exists.
10231 This module existed in versions of CMake prior to 3.1, but became only
10233 a thin wrapper around find_package(ITK NO_MODULE) to provide compati‐
10234 bility for projects using long-outdated conventions. Now find_pack‐
10235 age(ITK) will search for ITKConfig.cmake directly.
10236 FindJasper
10238 Try to find the Jasper JPEG2000 library
10239 Once done this will define
10241 JASPER_FOUND - system has Jasper
10243 JASPER_INCLUDE_DIR - the Jasper include directory
10244 JASPER_LIBRARIES - the libraries needed to use Jasper
10245 JASPER_VERSION_STRING - the version of Jasper found (since CMake 2.8.8)
10246 FindJava
10248 Find Java
10249 This module finds if Java is installed and determines where the include
10251 files and libraries are. The caller may set variable JAVA_HOME to
10252 specify a Java installation prefix explicitly.
10253 See also the FindJNI module to find Java development tools.
10255 Specify one or more of the following components as you call this find
10257 module. See example below.
10258 Runtime = User just want to execute some Java byte-compiled
10260 Development = Development tools (java, javac, javah and javadoc), includes Runtime component
10261 IdlJ = idl compiler for Java
10262 JarSigner = signer tool for jar
10263 This module sets the following result variables:
10265 Java_JAVA_EXECUTABLE = the full path to the Java runtime
10267 Java_JAVAC_EXECUTABLE = the full path to the Java compiler
10268 Java_JAVAH_EXECUTABLE = the full path to the Java header generator
10269 Java_JAVADOC_EXECUTABLE = the full path to the Java documentation generator
10270 Java_IDLJ_EXECUTABLE = the full path to the Java idl compiler
10271 Java_JAR_EXECUTABLE = the full path to the Java archiver
10272 Java_JARSIGNER_EXECUTABLE = the full path to the Java jar signer
10273 Java_VERSION_STRING = Version of java found, eg. 1.6.0_12
10274 Java_VERSION_MAJOR = The major version of the package found.
10275 Java_VERSION_MINOR = The minor version of the package found.
10276 Java_VERSION_PATCH = The patch version of the package found.
10277 Java_VERSION_TWEAK = The tweak version of the package found (after '_')
10278 Java_VERSION = This is set to: $major[.$minor[.$patch[.$tweak]]]
10279 The minimum required version of Java can be specified using the stan‐
10281 dard CMake syntax, e.g. find_package(Java 1.5)
10282 NOTE: ${Java_VERSION} and ${Java_VERSION_STRING} are not guaranteed to
10284 be identical. For example some java version may return: Java_VER‐
10285 SION_STRING = 1.5.0_17 and Java_VERSION = 1.5.0.17
10286 another example is the Java OEM, with: Java_VERSION_STRING = 1.6.0-oem
10288 and Java_VERSION = 1.6.0
10289 For these components the following variables are set:
10291 Java_FOUND - TRUE if all components are found.
10293 Java_<component>_FOUND - TRUE if <component> is found.
10294 Example Usages:
10296 find_package(Java)
10298 find_package(Java COMPONENTS Runtime)
10299 find_package(Java COMPONENTS Development)
10300 FindJNI
10302 Find JNI java libraries.
10303 This module finds if Java is installed and determines where the include
10305 files and libraries are. It also determines what the name of the
10306 library is. The caller may set variable JAVA_HOME to specify a Java
10307 installation prefix explicitly.
10308 This module sets the following result variables:
10310 JNI_INCLUDE_DIRS = the include dirs to use
10312 JNI_LIBRARIES = the libraries to use
10313 JNI_FOUND = TRUE if JNI headers and libraries were found.
10314 JAVA_AWT_LIBRARY = the path to the jawt library
10315 JAVA_JVM_LIBRARY = the path to the jvm library
10316 JAVA_INCLUDE_PATH = the include path to jni.h
10317 JAVA_INCLUDE_PATH2 = the include path to jni_md.h
10318 JAVA_AWT_INCLUDE_PATH = the include path to jawt.h
10319 FindJPEG
10321 Find JPEG
10322 Find the native JPEG includes and library This module defines
10324 JPEG_INCLUDE_DIR, where to find jpeglib.h, etc.
10326 JPEG_LIBRARIES, the libraries needed to use JPEG.
10327 JPEG_FOUND, If false, do not try to use JPEG.
10328 also defined, but not for general use are
10330 JPEG_LIBRARY, where to find the JPEG library.
10332 FindKDE3
10334 Find the KDE3 include and library dirs, KDE preprocessors and define a
10335 some macros
10336 This module defines the following variables:
10338 KDE3_DEFINITIONS
10340 compiler definitions required for compiling KDE software
10341 KDE3_INCLUDE_DIR
10343 the KDE include directory
10344 KDE3_INCLUDE_DIRS
10346 the KDE and the Qt include directory, for use with
10347 include_directories()
10348 KDE3_LIB_DIR
10350 the directory where the KDE libraries are installed, for use
10351 with link_directories()
10352 QT_AND_KDECORE_LIBS
10354 this contains both the Qt and the kdecore library
10355 KDE3_DCOPIDL_EXECUTABLE
10357 the dcopidl executable
10358 KDE3_DCOPIDL2CPP_EXECUTABLE
10360 the dcopidl2cpp executable
10361 KDE3_KCFGC_EXECUTABLE
10363 the kconfig_compiler executable
10364 KDE3_FOUND
10366 set to TRUE if all of the above has been found
10367 The following user adjustable options are provided:
10369 KDE3_BUILD_TESTS
10371 enable this to build KDE testcases
10372 It also adds the following macros (from KDE3Macros.cmake) SRCS_VAR is
10374 always the variable which contains the list of source files for your
10375 application or library.
10376 KDE3_AUTOMOC(file1 … fileN)
10378 Call this if you want to have automatic moc file handling.
10380 This means if you include "foo.moc" in the source file foo.cpp
10381 a moc file for the header foo.h will be created automatically.
10382 You can set the property SKIP_AUTOMAKE using set_source_files_properties()
10383 to exclude some files in the list from being processed.
10384 KDE3_ADD_MOC_FILES(SRCS_VAR file1 … fileN )
10386 If you don't use the KDE3_AUTOMOC() macro, for the files
10388 listed here moc files will be created (named "foo.moc.cpp")
10389 KDE3_ADD_DCOP_SKELS(SRCS_VAR header1.h … headerN.h )
10391 Use this to generate DCOP skeletions from the listed headers.
10393 KDE3_ADD_DCOP_STUBS(SRCS_VAR header1.h … headerN.h )
10395 Use this to generate DCOP stubs from the listed headers.
10397 KDE3_ADD_UI_FILES(SRCS_VAR file1.ui … fileN.ui )
10399 Use this to add the Qt designer ui files to your application/library.
10401 KDE3_ADD_KCFG_FILES(SRCS_VAR file1.kcfgc … fileN.kcfgc )
10403 Use this to add KDE kconfig compiler files to your application/library.
10405 KDE3_INSTALL_LIBTOOL_FILE(target)
10407 This will create and install a simple libtool file for the given target.
10409 KDE3_ADD_EXECUTABLE(name file1 … fileN )
10411 Currently identical to add_executable(), may provide some advanced
10413 features in the future.
10414 KDE3_ADD_KPART(name [WITH_PREFIX] file1 … fileN )
10416 Create a KDE plugin (KPart, kioslave, etc.) from the given source files.
10418 If WITH_PREFIX is given, the resulting plugin will have the prefix "lib",
10419 otherwise it won't.
10420 It creates and installs an appropriate libtool la-file.
10421 KDE3_ADD_KDEINIT_EXECUTABLE(name file1 … fileN )
10423 Create a KDE application in the form of a module loadable via kdeinit.
10425 A library named kdeinit_<name> will be created and a small executable
10426 which links to it.
10427 The option KDE3_ENABLE_FINAL to enable all-in-one compilation is no
10429 longer supported.
10430 Author: Alexander Neundorf <neundorf@kde.org>
10432 FindKDE4
10434 Find KDE4 and provide all necessary variables and macros to compile
10435 software for it. It looks for KDE 4 in the following directories in
10436 the given order:
10437 CMAKE_INSTALL_PREFIX
10439 KDEDIRS
10440 /opt/kde4
10441 Please look in FindKDE4Internal.cmake and KDE4Macros.cmake for more
10443 information. They are installed with the KDE 4 libraries in
10444 $KDEDIRS/share/apps/cmake/modules/.
10445 Author: Alexander Neundorf <neundorf@kde.org>
10447 FindLAPACK
10449 Find LAPACK library
10450 This module finds an installed fortran library that implements the
10452 LAPACK linear-algebra interface (see http://www.netlib.org/lapack/).
10453 The approach follows that taken for the autoconf macro file,
10455 acx_lapack.m4 (distributed at
10456 http://ac-archive.sourceforge.net/ac-archive/acx_lapack.html).
10457 This module sets the following variables:
10459 LAPACK_FOUND - set to true if a library implementing the LAPACK interface
10461 is found
10462 LAPACK_LINKER_FLAGS - uncached list of required linker flags (excluding -l
10463 and -L).
10464 LAPACK_LIBRARIES - uncached list of libraries (using full path name) to
10465 link against to use LAPACK
10466 LAPACK95_LIBRARIES - uncached list of libraries (using full path name) to
10467 link against to use LAPACK95
10468 LAPACK95_FOUND - set to true if a library implementing the LAPACK f95
10469 interface is found
10470 BLA_STATIC if set on this determines what kind of linkage we do (static)
10471 BLA_VENDOR if set checks only the specified vendor, if not set checks
10472 all the possibilities
10473 BLA_F95 if set on tries to find the f95 interfaces for BLAS/LAPACK
10474 List of vendors (BLA_VENDOR) valid in this module:
10476 · Intel(mkl)
10478 · OpenBLAS
10480 · FLAME
10482 · ACML
10484 · Apple
10486 · NAS
10488 · Generic
10490 FindLATEX
10492 Find Latex
10493 This module finds an installed Latex and determines the location of the
10495 compiler. Additionally the module looks for Latex-related software
10496 like BibTeX.
10497 This module sets the following result variables:
10499 LATEX_FOUND: whether found Latex and requested components
10501 LATEX_<component>_FOUND: whether found <component>
10502 LATEX_COMPILER: path to the LaTeX compiler
10503 PDFLATEX_COMPILER: path to the PdfLaTeX compiler
10504 XELATEX_COMPILER: path to the XeLaTeX compiler
10505 LUALATEX_COMPILER: path to the LuaLaTeX compiler
10506 BIBTEX_COMPILER: path to the BibTeX compiler
10507 BIBER_COMPILER: path to the Biber compiler
10508 MAKEINDEX_COMPILER: path to the MakeIndex compiler
10509 XINDY_COMPILER: path to the xindy compiler
10510 DVIPS_CONVERTER: path to the DVIPS converter
10511 DVIPDF_CONVERTER: path to the DVIPDF converter
10512 PS2PDF_CONVERTER: path to the PS2PDF converter
10513 PDFTOPS_CONVERTER: path to the pdftops converter
10514 LATEX2HTML_CONVERTER: path to the LaTeX2Html converter
10515 HTLATEX_COMPILER: path to the htlatex compiler
10516 Possible components are:
10518 PDFLATEX
10520 XELATEX
10521 LUALATEX
10522 BIBTEX
10523 BIBER
10524 MAKEINDEX
10525 XINDY
10526 DVIPS
10527 DVIPDF
10528 PS2PDF
10529 PDFTOPS
10530 LATEX2HTML
10531 HTLATEX
10532 Example Usages:
10534 find_package(LATEX)
10536 find_package(LATEX COMPONENTS PDFLATEX)
10537 find_package(LATEX COMPONENTS BIBTEX PS2PDF)
10538 FindLibArchive
10540 Find libarchive library and headers
10541 The module defines the following variables:
10543 LibArchive_FOUND - true if libarchive was found
10545 LibArchive_INCLUDE_DIRS - include search path
10546 LibArchive_LIBRARIES - libraries to link
10547 LibArchive_VERSION - libarchive 3-component version number
10548 FindLibLZMA
10550 Find LibLZMA
10551 Find LibLZMA headers and library
10553 LIBLZMA_FOUND - True if liblzma is found.
10555 LIBLZMA_INCLUDE_DIRS - Directory where liblzma headers are located.
10556 LIBLZMA_LIBRARIES - Lzma libraries to link against.
10557 LIBLZMA_HAS_AUTO_DECODER - True if lzma_auto_decoder() is found (required).
10558 LIBLZMA_HAS_EASY_ENCODER - True if lzma_easy_encoder() is found (required).
10559 LIBLZMA_HAS_LZMA_PRESET - True if lzma_lzma_preset() is found (required).
10560 LIBLZMA_VERSION_MAJOR - The major version of lzma
10561 LIBLZMA_VERSION_MINOR - The minor version of lzma
10562 LIBLZMA_VERSION_PATCH - The patch version of lzma
10563 LIBLZMA_VERSION_STRING - version number as a string (ex: "5.0.3")
10564 FindLibXml2
10566 Find the XML processing library (libxml2).
10567 Result variables
10569 This module will set the following variables in your project:
10570 LIBXML2_FOUND
10572 true if libxml2 headers and libraries were found
10573 LIBXML2_INCLUDE_DIR
10575 the directory containing LibXml2 headers
10576 LIBXML2_INCLUDE_DIRS
10578 list of the include directories needed to use LibXml2
10579 LIBXML2_LIBRARIES
10581 LibXml2 libraries to be linked
10582 LIBXML2_DEFINITIONS
10584 the compiler switches required for using LibXml2
10585 LIBXML2_XMLLINT_EXECUTABLE
10587 path to the XML checking tool xmllint coming with LibXml2
10588 LIBXML2_VERSION_STRING
10590 the version of LibXml2 found (since CMake 2.8.8)
10591 Cache variables
10593 The following cache variables may also be set:
10594 LIBXML2_INCLUDE_DIR
10596 the directory containing LibXml2 headers
10597 LIBXML2_LIBRARY
10599 path to the LibXml2 library
10600 FindLibXslt
10602 Try to find the LibXslt library
10603 Once done this will define
10605 LIBXSLT_FOUND - system has LibXslt
10607 LIBXSLT_INCLUDE_DIR - the LibXslt include directory
10608 LIBXSLT_LIBRARIES - Link these to LibXslt
10609 LIBXSLT_DEFINITIONS - Compiler switches required for using LibXslt
10610 LIBXSLT_VERSION_STRING - version of LibXslt found (since CMake 2.8.8)
10611 Additionally, the following two variables are set (but not required for
10613 using xslt):
10614 LIBXSLT_EXSLT_LIBRARIES
10616 Link to these if you need to link against the exslt library.
10617 LIBXSLT_XSLTPROC_EXECUTABLE
10619 Contains the full path to the xsltproc executable if found.
10620 FindLTTngUST
10622 This module finds the LTTng-UST library.
10623 Imported target
10625 This module defines the following IMPORTED target:
10626 LTTng::UST
10628 The LTTng-UST library, if found
10629 Result variables
10631 This module sets the following
10632 LTTNGUST_FOUND
10634 TRUE if system has LTTng-UST
10635 LTTNGUST_INCLUDE_DIRS
10637 The LTTng-UST include directories
10638 LTTNGUST_LIBRARIES
10640 The libraries needed to use LTTng-UST
10641 LTTNGUST_VERSION_STRING
10643 The LTTng-UST version
10644 LTTNGUST_HAS_TRACEF
10646 TRUE if the tracef() API is available in the system’s LTTng-UST
10647 LTTNGUST_HAS_TRACELOG
10649 TRUE if the tracelog() API is available in the system’s
10650 LTTng-UST
10651 FindLua50
10653 Locate Lua library This module defines
10654 LUA50_FOUND, if false, do not try to link to Lua
10656 LUA_LIBRARIES, both lua and lualib
10657 LUA_INCLUDE_DIR, where to find lua.h and lualib.h (and probably lauxlib.h)
10658 Note that the expected include convention is
10660 #include "lua.h"
10662 and not
10664 #include <lua/lua.h>
10666 This is because, the lua location is not standardized and may exist in
10668 locations other than lua/
10669 FindLua51
10671 Locate Lua library This module defines
10672 LUA51_FOUND, if false, do not try to link to Lua
10674 LUA_LIBRARIES
10675 LUA_INCLUDE_DIR, where to find lua.h
10676 LUA_VERSION_STRING, the version of Lua found (since CMake 2.8.8)
10677 Note that the expected include convention is
10679 #include "lua.h"
10681 and not
10683 #include <lua/lua.h>
10685 This is because, the lua location is not standardized and may exist in
10687 locations other than lua/
10688 FindLua
10690 Locate Lua library This module defines
10691 LUA_FOUND - if false, do not try to link to Lua
10693 LUA_LIBRARIES - both lua and lualib
10694 LUA_INCLUDE_DIR - where to find lua.h
10695 LUA_VERSION_STRING - the version of Lua found
10696 LUA_VERSION_MAJOR - the major version of Lua
10697 LUA_VERSION_MINOR - the minor version of Lua
10698 LUA_VERSION_PATCH - the patch version of Lua
10699 Note that the expected include convention is
10701 #include "lua.h"
10703 and not
10705 #include <lua/lua.h>
10707 This is because, the lua location is not standardized and may exist in
10709 locations other than lua/
10710 FindMatlab
10712 Finds Matlab installations and provides Matlab tools and libraries to
10713 cmake.
10714 This package first intention is to find the libraries associated with
10716 Matlab in order to be able to build Matlab extensions (mex files). It
10717 can also be used:
10718 · run specific commands in Matlab
10720 · declare Matlab unit test
10722 · retrieve various information from Matlab (mex extensions, versions
10724 and release queries, …)
10725 The module supports the following components:
10727 · MX_LIBRARY, ENG_LIBRARY and MAT_LIBRARY: respectively the MX, ENG and
10729 MAT libraries of Matlab
10730 · MAIN_PROGRAM the Matlab binary program.
10732 · MEX_COMPILER the MEX compiler.
10734 · SIMULINK the Simulink environment.
10736 NOTE:
10738 The version given to the find_package() directive is the Matlab ver‐
10739 sion, which should not be confused with the Matlab release name (eg.
10740 R2014). The matlab_get_version_from_release_name() and
10741 matlab_get_release_name_from_version() allow a mapping from the
10742 release name to the version.
10743 The variable Matlab_ROOT_DIR may be specified in order to give the path
10745 of the desired Matlab version. Otherwise, the behaviour is platform
10746 specific:
10747 · Windows: The installed versions of Matlab are retrieved from the Win‐
10749 dows registry
10750 · OS X: The installed versions of Matlab are given by the MATLAB paths
10752 in /Application. If no such application is found, it falls back to
10753 the one that might be accessible from the PATH.
10754 · Unix: The desired Matlab should be accessible from the PATH.
10756 Additional information is provided when MATLAB_FIND_DEBUG is set. When
10758 a Matlab binary is found automatically and the MATLAB_VERSION is not
10759 given, the version is queried from Matlab directly. On Windows, it can
10760 make a window running Matlab appear.
10761 The mapping of the release names and the version of Matlab is performed
10763 by defining pairs (name, version). The variable
10764 MATLAB_ADDITIONAL_VERSIONS may be provided before the call to the
10765 find_package() in order to handle additional versions.
10766 A Matlab scripts can be added to the set of tests using the
10768 matlab_add_unit_test(). By default, the Matlab unit test framework will
10769 be used (>= 2013a) to run this script, but regular .m files returning
10770 an exit code can be used as well (0 indicating a success).
10771 Module Input Variables
10773 Users or projects may set the following variables to configure the mod‐
10774 ule behaviour:
10775 Matlab_ROOT_DIR
10777 the root of the Matlab installation.
10778 MATLAB_FIND_DEBUG
10780 outputs debug information
10781 MATLAB_ADDITIONAL_VERSIONS
10783 additional versions of Matlab for the automatic retrieval of the
10784 installed versions.
10785 Variables defined by the module
10787 Result variables
10788 Matlab_FOUND
10789 TRUE if the Matlab installation is found, FALSE otherwise. All
10790 variable below are defined if Matlab is found.
10791 Matlab_ROOT_DIR
10793 the final root of the Matlab installation determined by the
10794 FindMatlab module.
10795 Matlab_MAIN_PROGRAM
10797 the Matlab binary program. Available only if the component
10798 MAIN_PROGRAM is given in the find_package() directive.
10799 Matlab_INCLUDE_DIRS
10801 the path of the Matlab libraries headers
10802 Matlab_MEX_LIBRARY
10804 library for mex, always available.
10805 Matlab_MX_LIBRARY
10807 mx library of Matlab (arrays). Available only if the component
10808 MX_LIBRARY has been requested.
10809 Matlab_ENG_LIBRARY
10811 Matlab engine library. Available only if the component
10812 ENG_LIBRARY is requested.
10813 Matlab_MAT_LIBRARY
10815 Matlab matrix library. Available only if the component
10816 MAT_LIBRARY is requested.
10817 Matlab_LIBRARIES
10819 the whole set of libraries of Matlab
10820 Matlab_MEX_COMPILER
10822 the mex compiler of Matlab. Currently not used. Available only
10823 if the component MEX_COMPILER is asked
10824 Cached variables
10826 Matlab_MEX_EXTENSION
10827 the extension of the mex files for the current platform (given
10828 by Matlab).
10829 Matlab_ROOT_DIR
10831 the location of the root of the Matlab installation found. If
10832 this value is changed by the user, the result variables are
10833 recomputed.
10834 Provided macros
10836 matlab_get_version_from_release_name()
10837 returns the version from the release name
10838 matlab_get_release_name_from_version()
10840 returns the release name from the Matlab version
10841 Provided functions
10843 matlab_add_mex()
10844 adds a target compiling a MEX file.
10845 matlab_add_unit_test()
10847 adds a Matlab unit test file as a test to the project.
10848 matlab_extract_all_installed_versions_from_registry()
10850 parses the registry for all Matlab versions. Available on Win‐
10851 dows only. The part of the registry parsed is dependent on the
10852 host processor
10853 matlab_get_all_valid_matlab_roots_from_registry()
10855 returns all the possible Matlab paths, according to a previously
10856 given list. Only the existing/accessible paths are kept. This is
10857 mainly useful for the searching all possible Matlab installa‐
10858 tion.
10859 matlab_get_mex_suffix()
10861 returns the suffix to be used for the mex files (platform/archi‐
10862 tecture dependent)
10863 matlab_get_version_from_matlab_run()
10865 returns the version of Matlab, given the full directory of the
10866 Matlab program.
10867 Known issues
10869 Symbol clash in a MEX target
10870 By default, every symbols inside a MEX file defined with the
10871 command matlab_add_mex() have hidden visibility, except for the
10872 entry point. This is the default behaviour of the MEX compiler,
10873 which lowers the risk of symbol collision between the libraries
10874 shipped with Matlab, and the libraries to which the MEX file is
10875 linking to. This is also the default on Windows platforms.
10876 However, this is not sufficient in certain case, where for
10878 instance your MEX file is linking against libraries that are
10879 already loaded by Matlab, even if those libraries have different
10880 SONAMES. A possible solution is to hide the symbols of the
10881 libraries to which the MEX target is linking to. This can be
10882 achieved in GNU GCC compilers with the linker option
10883 -Wl,--exclude-libs,ALL.
10884 Tests using GPU resources
10886 in case your MEX file is using the GPU and in order to be able
10887 to run unit tests on this MEX file, the GPU resources should be
10888 properly released by Matlab. A possible solution is to make Mat‐
10889 lab aware of the use of the GPU resources in the session, which
10890 can be performed by a command such as D = gpuDevice() at the
10891 beginning of the test script (or via a fixture).
10892 Reference
10894 Matlab_ROOT_DIR
10895 The root folder of the Matlab installation. If set before the
10896 call to find_package(), the module will look for the components
10897 in that path. If not set, then an automatic search of Matlab
10898 will be performed. If set, it should point to a valid version of
10899 Matlab.
10900 MATLAB_FIND_DEBUG
10902 If set, the lookup of Matlab and the intermediate configuration
10903 steps are outputted to the console.
10904 MATLAB_ADDITIONAL_VERSIONS
10906 If set, specifies additional versions of Matlab that may be
10907 looked for. The variable should be a list of strings, organised
10908 by pairs of release name and versions, such as follows:
10909 set(MATLAB_ADDITIONAL_VERSIONS
10911 "release_name1=corresponding_version1"
10912 "release_name2=corresponding_version2"
10913 ...
10914 )
10915 Example:
10917 set(MATLAB_ADDITIONAL_VERSIONS
10919 "R2013b=8.2"
10920 "R2013a=8.1"
10921 "R2012b=8.0")
10922 The order of entries in this list matters when several versions
10924 of Matlab are installed. The priority is set according to the
10925 ordering in this list.
10926 matlab_get_version_from_release_name
10928 Returns the version of Matlab (17.58) from a release name
10929 (R2017k)
10930 matlab_get_release_name_from_version
10932 Returns the release name (R2017k) from the version of Matlab
10933 (17.58)
10934 matlab_extract_all_installed_versions_from_registry
10936 This function parses the registry and founds the Matlab versions
10937 that are installed. The found versions are returned in mat‐
10938 lab_versions. Set win64 to TRUE if the 64 bit version of Matlab
10939 should be looked for The returned list contains all versions
10940 under HKLM\\SOFTWARE\\Mathworks\\MATLAB or an empty list in case
10941 an error occurred (or nothing found).
10942 NOTE:
10944 Only the versions are provided. No check is made over the
10945 existence of the installation referenced in the registry,
10946 matlab_get_all_valid_matlab_roots_from_registry
10948 Populates the Matlab root with valid versions of Matlab. The
10949 returned matlab_roots is organized in pairs (version_number,mat‐
10950 lab_root_path).
10951 matlab_get_all_valid_matlab_roots_from_registry(
10953 matlab_versions
10954 matlab_roots)
10955 matlab_versions
10957 the versions of each of the Matlab installations
10958 matlab_roots
10960 the location of each of the Matlab installations
10961 matlab_get_mex_suffix
10963 Returns the extension of the mex files (the suffixes). This
10964 function should not be called before the appropriate Matlab root
10965 has been found.
10966 matlab_get_mex_suffix(
10968 matlab_root
10969 mex_suffix)
10970 matlab_root
10972 the root of the Matlab installation
10973 mex_suffix
10975 the variable name in which the suffix will be returned.
10976 matlab_get_version_from_matlab_run
10978 This function runs Matlab program specified on arguments and
10979 extracts its version.
10980 matlab_get_version_from_matlab_run(
10982 matlab_binary_path
10983 matlab_list_versions)
10984 matlab_binary_path
10986 the location of the matlab binary executable
10987 matlab_list_versions
10989 the version extracted from Matlab
10990 matlab_add_unit_test
10992 Adds a Matlab unit test to the test set of cmake/ctest. This
10993 command requires the component MAIN_PROGRAM. The unit test uses
10994 the Matlab unittest framework (default, available starting Mat‐
10995 lab 2013b+) except if the option NO_UNITTEST_FRAMEWORK is given.
10996 The function expects one Matlab test script file to be given.
10998 In the case NO_UNITTEST_FRAMEWORK is given, the unittest script
10999 file should contain the script to be run, plus an exit command
11000 with the exit value. This exit value will be passed to the ctest
11001 framework (0 success, non 0 failure). Additional arguments
11002 accepted by add_test() can be passed through TEST_ARGS (eg. CON‐
11003 FIGURATION <config> ...).
11004 matlab_add_unit_test(
11006 NAME <name>
11007 UNITTEST_FILE matlab_file_containing_unittest.m
11008 [CUSTOM_TEST_COMMAND matlab_command_to_run_as_test]
11009 [UNITTEST_PRECOMMAND matlab_command_to_run]
11010 [TIMEOUT timeout]
11011 [ADDITIONAL_PATH path1 [path2 ...]]
11012 [MATLAB_ADDITIONAL_STARTUP_OPTIONS option1 [option2 ...]]
11013 [TEST_ARGS arg1 [arg2 ...]]
11014 [NO_UNITTEST_FRAMEWORK]
11015 )
11016 The function arguments are:
11018 NAME name of the unittest in ctest.
11020 UNITTEST_FILE
11022 the matlab unittest file. Its path will be automatically
11023 added to the Matlab path.
11024 CUSTOM_TEST_COMMAND
11026 Matlab script command to run as the test. If this is not
11027 set, then the following is run: runtests('mat‐
11028 lab_file_name'), exit(max([ans(1,:).Failed])) where mat‐
11029 lab_file_name is the UNITTEST_FILE without the extension.
11030 UNITTEST_PRECOMMAND
11032 Matlab script command to be ran before the file contain‐
11033 ing the test (eg. GPU device initialisation based on
11034 CMake variables).
11035 TIMEOUT
11037 the test timeout in seconds. Defaults to 180 seconds as
11038 the Matlab unit test may hang.
11039 ADDITIONAL_PATH
11041 a list of paths to add to the Matlab path prior to run‐
11042 ning the unit test.
11043 MATLAB_ADDITIONAL_STARTUP_OPTIONS
11045 a list of additional option in order to run Matlab from
11046 the command line. -nosplash -nodesktop -nodisplay are
11047 always added.
11048 TEST_ARGS
11050 Additional options provided to the add_test command.
11051 These options are added to the default options (eg. “CON‐
11052 FIGURATIONS Release”)
11053 NO_UNITTEST_FRAMEWORK
11055 when set, indicates that the test should not use the
11056 unittest framework of Matlab (available for versions >=
11057 R2013a).
11058 WORKING_DIRECTORY
11060 This will be the working directory for the test. If spec‐
11061 ified it will also be the output directory used for the
11062 log file of the test run. If not specified the temporary
11063 directory ${CMAKE_BINARY_DIR}/Matlab will be used as the
11064 working directory and the log location.
11065 matlab_add_mex
11067 Adds a Matlab MEX target. This commands compiles the given
11068 sources with the current tool-chain in order to produce a MEX
11069 file. The final name of the produced output may be specified, as
11070 well as additional link libraries, and a documentation entry for
11071 the MEX file. Remaining arguments of the call are passed to the
11072 add_library() or add_executable() command.
11073 matlab_add_mex(
11075 NAME <name>
11076 [EXECUTABLE | MODULE | SHARED]
11077 SRC src1 [src2 ...]
11078 [OUTPUT_NAME output_name]
11079 [DOCUMENTATION file.txt]
11080 [LINK_TO target1 target2 ...]
11081 [...]
11082 )
11083 NAME name of the target.
11085 SRC list of source files.
11087 LINK_TO
11089 a list of additional link dependencies. The target links
11090 to libmex by default. If Matlab_MX_LIBRARY is defined, it
11091 also links to libmx.
11092 OUTPUT_NAME
11094 if given, overrides the default name. The default name is
11095 the name of the target without any prefix and with Mat‐
11096 lab_MEX_EXTENSION suffix.
11097 DOCUMENTATION
11099 if given, the file file.txt will be considered as being
11100 the documentation file for the MEX file. This file is
11101 copied into the same folder without any processing, with
11102 the same name as the final mex file, and with extension
11103 .m. In that case, typing help <name> in Matlab prints the
11104 documentation contained in this file.
11105 MODULE or SHARED may be given to specify the type of library to
11107 be
11108 created. EXECUTABLE may be given to create an executable
11109 instead of a library. If no type is given explicitly, the
11110 type is SHARED.
11111 The documentation file is not processed and should be in the
11113 following format:
11114 % This is the documentation
11116 function ret = mex_target_output_name(input1)
11117 FindMFC
11119 Find MFC on Windows
11120 Find the native MFC - i.e. decide if an application can link to the
11122 MFC libraries.
11123 MFC_FOUND - Was MFC support found
11125 You don’t need to include anything or link anything to use it.
11127 FindMotif
11129 Try to find Motif (or lesstif)
11130 Once done this will define:
11132 MOTIF_FOUND - system has MOTIF
11134 MOTIF_INCLUDE_DIR - include paths to use Motif
11135 MOTIF_LIBRARIES - Link these to use Motif
11136 FindMPEG2
11138 Find the native MPEG2 includes and library
11139 This module defines
11141 MPEG2_INCLUDE_DIR, path to mpeg2dec/mpeg2.h, etc.
11143 MPEG2_LIBRARIES, the libraries required to use MPEG2.
11144 MPEG2_FOUND, If false, do not try to use MPEG2.
11145 also defined, but not for general use are
11147 MPEG2_mpeg2_LIBRARY, where to find the MPEG2 library.
11149 MPEG2_vo_LIBRARY, where to find the vo library.
11150 FindMPEG
11152 Find the native MPEG includes and library
11153 This module defines
11155 MPEG_INCLUDE_DIR, where to find MPEG.h, etc.
11157 MPEG_LIBRARIES, the libraries required to use MPEG.
11158 MPEG_FOUND, If false, do not try to use MPEG.
11159 also defined, but not for general use are
11161 MPEG_mpeg2_LIBRARY, where to find the MPEG library.
11163 MPEG_vo_LIBRARY, where to find the vo library.
11164 FindMPI
11166 Find a Message Passing Interface (MPI) implementation.
11167 The Message Passing Interface (MPI) is a library used to write
11169 high-performance distributed-memory parallel applications, and is typi‐
11170 cally deployed on a cluster. MPI is a standard interface (defined by
11171 the MPI forum) for which many implementations are available.
11172 Variables for using MPI
11174 The module exposes the components C, CXX, MPICXX and Fortran. Each of
11175 these controls the various MPI languages to search for. The difference
11176 between CXX and MPICXX is that CXX refers to the MPI C API being usable
11177 from C++, whereas MPICXX refers to the MPI-2 C++ API that was removed
11178 again in MPI-3.
11179 Depending on the enabled components the following variables will be
11181 set:
11182 MPI_FOUND
11184 Variable indicating that MPI settings for all requested lan‐
11185 guages have been found. If no components are specified, this is
11186 true if MPI settings for all enabled languages were detected.
11187 Note that the MPICXX component does not affect this variable.
11188 MPI_VERSION
11190 Minimal version of MPI detected among the requested languages,
11191 or all enabled languages if no components were specified.
11192 This module will set the following variables per language in your
11194 project, where <lang> is one of C, CXX, or Fortran:
11195 MPI_<lang>_FOUND
11197 Variable indicating the MPI settings for <lang> were found and
11198 that simple MPI test programs compile with the provided set‐
11199 tings.
11200 MPI_<lang>_COMPILER
11202 MPI compiler for <lang> if such a program exists.
11203 MPI_<lang>_COMPILE_OPTIONS
11205 Compilation options for MPI programs in <lang>, given as a
11206 ;-list.
11207 MPI_<lang>_COMPILE_DEFINITIONS
11209 Compilation definitions for MPI programs in <lang>, given as a
11210 ;-list.
11211 MPI_<lang>_INCLUDE_DIRS
11213 Include path(s) for MPI header.
11214 MPI_<lang>_LINK_FLAGS
11216 Linker flags for MPI programs.
11217 MPI_<lang>_LIBRARIES
11219 All libraries to link MPI programs against.
11220 Additionally, the following IMPORTED targets are defined:
11222 MPI::MPI_<lang>
11224 Target for using MPI from <lang>.
11225 The following variables indicating which bindings are present will be
11227 defined:
11228 MPI_MPICXX_FOUND
11230 Variable indicating whether the MPI-2 C++ bindings are present
11231 (introduced in MPI-2, removed with MPI-3).
11232 MPI_Fortran_HAVE_F77_HEADER
11234 True if the Fortran 77 header mpif.h is available.
11235 MPI_Fortran_HAVE_F90_MODULE
11237 True if the Fortran 90 module mpi can be used for accessing MPI
11238 (MPI-2 and higher only).
11239 MPI_Fortran_HAVE_F08_MODULE
11241 True if the Fortran 2008 mpi_f08 is available to MPI programs
11242 (MPI-3 and higher only).
11243 If possible, the MPI version will be determined by this module. The
11245 facilities to detect the MPI version were introduced with MPI-1.2, and
11246 therefore cannot be found for older MPI versions.
11247 MPI_<lang>_VERSION_MAJOR
11249 Major version of MPI implemented for <lang> by the MPI distribu‐
11250 tion.
11251 MPI_<lang>_VERSION_MINOR
11253 Minor version of MPI implemented for <lang> by the MPI distribu‐
11254 tion.
11255 MPI_<lang>_VERSION
11257 MPI version implemented for <lang> by the MPI distribution.
11258 Note that there’s no variable for the C bindings being accessible
11260 through mpi.h, since the MPI standards always have required this bind‐
11261 ing to work in both C and C++ code.
11262 For running MPI programs, the module sets the following variables
11264 MPIEXEC_EXECUTABLE
11266 Executable for running MPI programs, if such exists.
11267 MPIEXEC_NUMPROC_FLAG
11269 Flag to pass to mpiexec before giving it the number of proces‐
11270 sors to run on.
11271 MPIEXEC_MAX_NUMPROCS
11273 Number of MPI processors to utilize. Defaults to the number of
11274 processors detected on the host system.
11275 MPIEXEC_PREFLAGS
11277 Flags to pass to mpiexec directly before the executable to run.
11278 MPIEXEC_POSTFLAGS
11280 Flags to pass to mpiexec after other flags.
11281 Variables for locating MPI
11283 This module performs a three step search for an MPI implementation:
11284 1. Check if the compiler has MPI support built-in. This is the case if
11286 the user passed a compiler wrapper as CMAKE_<LANG>_COMPILER or if
11287 they’re on a Cray system.
11288 2. Attempt to find an MPI compiler wrapper and determine the compiler
11290 information from it.
11291 3. Try to find an MPI implementation that does not ship such a wrapper
11293 by guessing settings. Currently, only Microsoft MPI and MPICH2 on
11294 Windows are supported.
11295 For controlling the second step, the following variables may be set:
11297 MPI_<lang>_COMPILER
11299 Search for the specified compiler wrapper and use it.
11300 MPI_<lang>_COMPILER_FLAGS
11302 Flags to pass to the MPI compiler wrapper during interrogation.
11303 Some compiler wrappers support linking debug or tracing
11304 libraries if a specific flag is passed and this variable may be
11305 used to obtain them.
11306 MPI_COMPILER_FLAGS
11308 Used to initialize MPI_<lang>_COMPILER_FLAGS if no language spe‐
11309 cific flag has been given. Empty by default.
11310 MPI_EXECUTABLE_SUFFIX
11312 A suffix which is appended to all names that are being looked
11313 for. For instance you may set this to .mpich or .openmpi to pre‐
11314 fer the one or the other on Debian and its derivatives.
11315 In order to control the guessing step, the following variable may be
11317 set:
11318 MPI_GUESS_LIBRARY_NAME
11320 Valid values are MSMPI and MPICH2. If set, only the given
11321 library will be searched for. By default, MSMPI will be pre‐
11322 ferred over MPICH2 if both are available. This also sets
11323 MPI_SKIP_COMPILER_WRAPPER to true, which may be overridden.
11324 Each of the search steps may be skipped with the following control
11326 variables:
11327 MPI_ASSUME_NO_BUILTIN_MPI
11329 If true, the module assumes that the compiler itself does not
11330 provide an MPI implementation and skips to step 2.
11331 MPI_SKIP_COMPILER_WRAPPER
11333 If true, no compiler wrapper will be searched for.
11334 MPI_SKIP_GUESSING
11336 If true, the guessing step will be skipped.
11337 Additionally, the following control variable is available to change
11339 search behavior:
11340 MPI_CXX_SKIP_MPICXX
11342 Add some definitions that will disable the MPI-2 C++ bindings.
11343 Currently supported are MPICH, Open MPI, Platform MPI and deriv‐
11344 atives thereof, for example MVAPICH or Intel MPI.
11345 If the find procedure fails for a variable MPI_<lang>_WORKS, then the
11347 settings detected by or passed to the module did not work and even a
11348 simple MPI test program failed to compile.
11349 If all of these parameters were not sufficient to find the right MPI
11351 implementation, a user may disable the entire autodetection process by
11352 specifying both a list of libraries in MPI_<lang>_LIBRARIES and a list
11353 of include directories in MPI_<lang>_ADDITIONAL_INCLUDE_DIRS. Any
11354 other variable may be set in addition to these two. The module will
11355 then validate the MPI settings and store the settings in the cache.
11356 Cache variables for MPI
11358 The variable MPI_<lang>_INCLUDE_DIRS will be assembled from the follow‐
11359 ing variables. For C and CXX:
11360 MPI_<lang>_HEADER_DIR
11362 Location of the mpi.h header on disk.
11363 For Fortran:
11365 MPI_Fortran_F77_HEADER_DIR
11367 Location of the Fortran 77 header mpif.h, if it exists.
11368 MPI_Fortran_MODULE_DIR
11370 Location of the mpi or mpi_f08 modules, if available.
11371 For all languages the following variables are additionally considered:
11373 MPI_<lang>_ADDITIONAL_INCLUDE_DIRS
11375 A ;-list of paths needed in addition to the normal include
11376 directories.
11377 MPI_<include_name>_INCLUDE_DIR
11379 Path variables for include folders referred to by
11380 <include_name>.
11381 MPI_<lang>_ADDITIONAL_INCLUDE_VARS
11383 A ;-list of <include_name> that will be added to the include
11384 locations of <lang>.
11385 The variable MPI_<lang>_LIBRARIES will be assembled from the following
11387 variables:
11388 MPI_<lib_name>_LIBRARY
11390 The location of a library called <lib_name> for use with MPI.
11391 MPI_<lang>_LIB_NAMES
11393 A ;-list of <lib_name> that will be added to the include loca‐
11394 tions of <lang>.
11395 Usage of mpiexec
11397 When using MPIEXEC_EXECUTABLE to execute MPI applications, you should
11398 typically use all of the MPIEXEC_EXECUTABLE flags as follows:
11399 ${MPIEXEC_EXECUTABLE} ${MPIEXEC_NUMPROC_FLAG} ${MPIEXEC_MAX_NUMPROCS}
11401 ${MPIEXEC_PREFLAGS} EXECUTABLE ${MPIEXEC_POSTFLAGS} ARGS
11402 where EXECUTABLE is the MPI program, and ARGS are the arguments to pass
11404 to the MPI program.
11405 Advanced variables for using MPI
11407 The module can perform some advanced feature detections upon explicit
11408 request.
11409 Important notice: The following checks cannot be performed without exe‐
11411 cuting an MPI test program. Consider the special considerations for
11412 the behavior of try_run() during cross compilation. Moreover, running
11413 an MPI program can cause additional issues, like a firewall notifica‐
11414 tion on some systems. You should only enable these detections if you
11415 absolutely need the information.
11416 If the following variables are set to true, the respective search will
11418 be performed:
11419 MPI_DETERMINE_Fortran_CAPABILITIES
11421 Determine for all available Fortran bindings what the values of
11422 MPI_SUBARRAYS_SUPPORTED and MPI_ASYNC_PROTECTS_NONBLOCKING are
11423 and make their values available as MPI_Fortran_<binding>_SUBAR‐
11424 RAYS and MPI_Fortran_<binding>_ASYNCPROT, where <binding> is one
11425 of F77_HEADER, F90_MODULE and F08_MODULE.
11426 MPI_DETERMINE_LIBRARY_VERSION
11428 For each language, find the output of MPI_Get_library_version
11429 and make it available as MPI_<lang>_LIBRARY_VERSION. This
11430 information is usually tied to the runtime component of an MPI
11431 implementation and might differ depending on <lang>. Note that
11432 the return value is entirely implementation defined. This infor‐
11433 mation might be used to identify the MPI vendor and for example
11434 pick the correct one of multiple third party binaries that
11435 matches the MPI vendor.
11436 Backward Compatibility
11438 For backward compatibility with older versions of FindMPI, these vari‐
11439 ables are set, but deprecated:
11440 MPI_COMPILER MPI_LIBRARY MPI_EXTRA_LIBRARY
11442 MPI_COMPILE_FLAGS MPI_INCLUDE_PATH MPI_LINK_FLAGS
11443 MPI_LIBRARIES
11444 In new projects, please use the MPI_<lang>_XXX equivalents. Addition‐
11446 ally, the following variables are deprecated:
11447 MPI_<lang>_COMPILE_FLAGS
11449 Use MPI_<lang>_COMPILE_OPTIONS and MPI_<lang>_COMPILE_DEFINI‐
11450 TIONS instead.
11451 MPI_<lang>_INCLUDE_PATH
11453 For consumption use MPI_<lang>_INCLUDE_DIRS and for specifying
11454 folders use MPI_<lang>_ADDITIONAL_INCLUDE_DIRS instead.
11455 MPIEXEC
11457 Use MPIEXEC_EXECUTABLE instead.
11458 FindOpenACC
11460 Detect OpenACC support by the compiler.
11461 This module can be used to detect OpenACC support in a compiler. If
11463 the compiler supports OpenACC, the flags required to compile with Ope‐
11464 nACC support are returned in variables for the different languages.
11465 Currently, only PGI, GNU and Cray compilers are supported.
11466 Variables
11468 This module will set the following variables per language in your
11469 project, where <lang> is one of C, CXX, or Fortran:
11470 OpenACC_<lang>_FOUND
11472 Variable indicating if OpenACC support for <lang> was detected.
11473 OpenACC_<lang>_FLAGS
11475 OpenACC compiler flags for <lang>, separated by spaces.
11476 The module will also try to provide the OpenACC version variables:
11478 OpenACC_<lang>_SPEC_DATE
11480 Date of the OpenACC specification implemented by the <lang> com‐
11481 piler.
11482 OpenACC_<lang>_VERSION_MAJOR
11484 Major version of OpenACC implemented by the <lang> compiler.
11485 OpenACC_<lang>_VERSION_MINOR
11487 Minor version of OpenACC implemented by the <lang> compiler.
11488 OpenACC_<lang>_VERSION
11490 OpenACC version implemented by the <lang> compiler.
11491 The specification date is formatted as given in the OpenACC standard:
11493 yyyymm where yyyy and mm represents the year and month of the OpenACC
11494 specification implemented by the <lang> compiler.
11495 Input Variables
11497 OpenACC_ACCEL_TARGET=<target> If set, will the correct target accelera‐
11498 tor flag set to the <target> will be returned with Ope‐
11499 nACC_<lang>_FLAGS.
11500 FindOpenAL
11502 Locate OpenAL This module defines OPENAL_LIBRARY OPENAL_FOUND, if
11503 false, do not try to link to OpenAL OPENAL_INCLUDE_DIR, where to find
11504 the headers
11505 $OPENALDIR is an environment variable that would correspond to the
11507 Created by Eric Wing. This was influenced by the FindSDL.cmake module.
11509 FindOpenCL
11511 Try to find OpenCL
11512 IMPORTED Targets
11514 This module defines IMPORTED target OpenCL::OpenCL, if OpenCL has been
11515 found.
11516 Result Variables
11518 This module defines the following variables:
11519 OpenCL_FOUND - True if OpenCL was found
11521 OpenCL_INCLUDE_DIRS - include directories for OpenCL
11522 OpenCL_LIBRARIES - link against this library to use OpenCL
11523 OpenCL_VERSION_STRING - Highest supported OpenCL version (eg. 1.2)
11524 OpenCL_VERSION_MAJOR - The major version of the OpenCL implementation
11525 OpenCL_VERSION_MINOR - The minor version of the OpenCL implementation
11526 The module will also define two cache variables:
11528 OpenCL_INCLUDE_DIR - the OpenCL include directory
11530 OpenCL_LIBRARY - the path to the OpenCL library
11531 FindOpenGL
11533 FindModule for OpenGL and GLU.
11534 Optional COMPONENTS
11536 This module respects several optional COMPONENTS: EGL, GLX, and OpenGL.
11537 There are corresponding import targets for each of these flags.
11538 IMPORTED Targets
11540 This module defines the IMPORTED targets:
11541 OpenGL::GL
11543 Defined to the platform-specific OpenGL libraries if the system
11544 has OpenGL.
11545 OpenGL::OpenGL
11547 Defined to libOpenGL if the system is GLVND-based.
11548 OpenGL::GLU
11550 Defined if the system has GLU.
11551 OpenGL::GLX
11553 Defined if the system has GLX.
11554 OpenGL::EGL
11556 Defined if the system has EGL.
11557 Result Variables
11559 This module sets the following variables:
11560 OPENGL_FOUND
11562 True, if the system has OpenGL and all components are found.
11563 OPENGL_XMESA_FOUND
11565 True, if the system has XMESA.
11566 OPENGL_GLU_FOUND
11568 True, if the system has GLU.
11569 OpenGL_OpenGL_FOUND
11571 True, if the system has an OpenGL library.
11572 OpenGL_GLX_FOUND
11574 True, if the system has GLX.
11575 OpenGL_EGL_FOUND
11577 True, if the system has EGL.
11578 OPENGL_INCLUDE_DIR
11580 Path to the OpenGL include directory.
11581 OPENGL_EGL_INCLUDE_DIRS
11583 Path to the EGL include directory.
11584 OPENGL_LIBRARIES
11586 Paths to the OpenGL library, windowing system libraries, and GLU
11587 libraries. On Linux, this assumes GLX and is never correct for
11588 EGL-based targets. Clients are encouraged to use the OpenGL::*
11589 import targets instead.
11590 Cache variables
11592 The following cache variables may also be set:
11593 OPENGL_egl_LIBRARY
11595 Path to the EGL library.
11596 OPENGL_glu_LIBRARY
11598 Path to the GLU library.
11599 OPENGL_glx_LIBRARY
11601 Path to the GLVND ‘GLX’ library.
11602 OPENGL_opengl_LIBRARY
11604 Path to the GLVND ‘OpenGL’ library
11605 OPENGL_gl_LIBRARY
11607 Path to the OpenGL library. New code should prefer the
11608 OpenGL::* import targets.
11609 Linux-specific
11611 Some Linux systems utilize GLVND as a new ABI for OpenGL. GLVND sepa‐
11612 rates context libraries from OpenGL itself; OpenGL lives in
11613 “libOpenGL”, and contexts are defined in “libGLX” or “libEGL”. GLVND
11614 is currently the only way to get OpenGL 3+ functionality via EGL in a
11615 manner portable across vendors. Projects may use GLVND explicitly with
11616 target OpenGL::OpenGL and either OpenGL::GLX or OpenGL::EGL.
11617 Projects may use the OpenGL::GL target (or OPENGL_LIBRARIES variable)
11619 to use legacy GL interfaces. These will use the legacy GL library
11620 located by OPENGL_gl_LIBRARY, if available. If OPENGL_gl_LIBRARY is
11621 empty or not found and GLVND is available, the OpenGL::GL target will
11622 use GLVND OpenGL::OpenGL and OpenGL::GLX (and the OPENGL_LIBRARIES
11623 variable will use the corresponding libraries). Thus, for
11624 non-EGL-based Linux targets, the OpenGL::GL target is most portable.
11625 A OpenGL_GL_PREFERENCE variable may be set to specify the preferred way
11627 to provide legacy GL interfaces in case multiple choices are available.
11628 The value may be one of:
11629 GLVND If the GLVND OpenGL and GLX libraries are available, prefer
11631 them. This forces OPENGL_gl_LIBRARY to be empty. This is the
11632 default if components were requested (since components corre‐
11633 spond to GLVND libraries) or if policy CMP0072 is set to NEW.
11634 LEGACY Prefer to use the legacy libGL library, if available. This is
11636 the default if no components were requested and policy CMP0072
11637 is not set to NEW.
11638 For EGL targets the client must rely on GLVND support on the user’s
11640 system. Linking should use the OpenGL::OpenGL OpenGL::EGL targets.
11641 Using GLES* libraries is theoretically possible in place of
11642 OpenGL::OpenGL, but this module does not currently support that; con‐
11643 tributions welcome.
11644 OPENGL_egl_LIBRARY and OPENGL_EGL_INCLUDE_DIRS are defined in the case
11646 of GLVND. For non-GLVND Linux and other systems these are left unde‐
11647 fined.
11648 macOS-Specific
11650 On OSX FindOpenGL defaults to using the framework version of OpenGL.
11651 People will have to change the cache values of OPENGL_glu_LIBRARY and
11652 OPENGL_gl_LIBRARY to use OpenGL with X11 on OSX.
11653 FindOpenMP
11655 Finds OpenMP support
11656 This module can be used to detect OpenMP support in a compiler. If the
11658 compiler supports OpenMP, the flags required to compile with OpenMP
11659 support are returned in variables for the different languages. The
11660 variables may be empty if the compiler does not need a special flag to
11661 support OpenMP.
11662 Variables
11664 The module exposes the components C, CXX, and Fortran. Each of these
11665 controls the various languages to search OpenMP support for.
11666 Depending on the enabled components the following variables will be
11668 set:
11669 OpenMP_FOUND
11671 Variable indicating that OpenMP flags for all requested lan‐
11672 guages have been found. If no components are specified, this is
11673 true if OpenMP settings for all enabled languages were detected.
11674 OpenMP_VERSION
11676 Minimal version of the OpenMP standard detected among the
11677 requested languages, or all enabled languages if no components
11678 were specified.
11679 This module will set the following variables per language in your
11681 project, where <lang> is one of C, CXX, or Fortran:
11682 OpenMP_<lang>_FOUND
11684 Variable indicating if OpenMP support for <lang> was detected.
11685 OpenMP_<lang>_FLAGS
11687 OpenMP compiler flags for <lang>, separated by spaces.
11688 For linking with OpenMP code written in <lang>, the following variables
11690 are provided:
11691 OpenMP_<lang>_LIB_NAMES
11693 ;-list of libraries for OpenMP programs for <lang>.
11694 OpenMP_<libname>_LIBRARY
11696 Location of the individual libraries needed for OpenMP support
11697 in <lang>.
11698 OpenMP_<lang>_LIBRARIES
11700 A list of libraries needed to link with OpenMP code written in
11701 <lang>.
11702 Additionally, the module provides IMPORTED targets:
11704 OpenMP::OpenMP_<lang>
11706 Target for using OpenMP from <lang>.
11707 Specifically for Fortran, the module sets the following variables:
11709 OpenMP_Fortran_HAVE_OMPLIB_HEADER
11711 Boolean indicating if OpenMP is accessible through omp_lib.h.
11712 OpenMP_Fortran_HAVE_OMPLIB_MODULE
11714 Boolean indicating if OpenMP is accessible through the omp_lib
11715 Fortran module.
11716 The module will also try to provide the OpenMP version variables:
11718 OpenMP_<lang>_SPEC_DATE
11720 Date of the OpenMP specification implemented by the <lang> com‐
11721 piler.
11722 OpenMP_<lang>_VERSION_MAJOR
11724 Major version of OpenMP implemented by the <lang> compiler.
11725 OpenMP_<lang>_VERSION_MINOR
11727 Minor version of OpenMP implemented by the <lang> compiler.
11728 OpenMP_<lang>_VERSION
11730 OpenMP version implemented by the <lang> compiler.
11731 The specification date is formatted as given in the OpenMP standard:
11733 yyyymm where yyyy and mm represents the year and month of the OpenMP
11734 specification implemented by the <lang> compiler.
11735 FindOpenSceneGraph
11737 Find OpenSceneGraph
11738 This module searches for the OpenSceneGraph core “osg” library as well
11740 as OpenThreads, and whatever additional COMPONENTS (nodekits) that you
11741 specify.
11742 See http://www.openscenegraph.org
11744 NOTE: To use this module effectively you must either require CMake >=
11746 2.6.3 with cmake_minimum_required(VERSION 2.6.3) or download and place
11747 FindOpenThreads.cmake, Findosg_functions.cmake, Findosg.cmake, and
11748 Find<etc>.cmake files into your CMAKE_MODULE_PATH.
11749 ----
11752 This module accepts the following variables (note mixed case)
11756 OpenSceneGraph_DEBUG - Enable debugging output
11758 OpenSceneGraph_MARK_AS_ADVANCED - Mark cache variables as advanced
11760 automatically
11761 The following environment variables are also respected for finding the
11763 OSG and it’s various components. CMAKE_PREFIX_PATH can also be used
11764 for this (see find_library() CMake documentation).
11765 <MODULE>_DIR
11767 (where MODULE is of the form “OSGVOLUME” and there is a Findos‐
11768 gVolume.cmake file)
11769 OSG_DIR
11771 OSGDIR
11773 OSG_ROOT
11775 [CMake 2.8.10]: The CMake variable OSG_DIR can now be used as well to
11777 influence detection, instead of needing to specify an environment vari‐
11778 able.
11779 This module defines the following output variables:
11781 OPENSCENEGRAPH_FOUND - Was the OSG and all of the specified components found?
11783 OPENSCENEGRAPH_VERSION - The version of the OSG which was found
11785 OPENSCENEGRAPH_INCLUDE_DIRS - Where to find the headers
11787 OPENSCENEGRAPH_LIBRARIES - The OSG libraries
11789 ================================== Example Usage:
11791 find_package(OpenSceneGraph 2.0.0 REQUIRED osgDB osgUtil)
11793 # libOpenThreads & libosg automatically searched
11794 include_directories(${OPENSCENEGRAPH_INCLUDE_DIRS})
11795 add_executable(foo foo.cc)
11797 target_link_libraries(foo ${OPENSCENEGRAPH_LIBRARIES})
11798 FindOpenSSL
11800 Find the OpenSSL encryption library.
11801 Imported Targets
11803 This module defines the following IMPORTED targets:
11804 OpenSSL::SSL
11806 The OpenSSL ssl library, if found.
11807 OpenSSL::Crypto
11809 The OpenSSL crypto library, if found.
11810 Result Variables
11812 This module will set the following variables in your project:
11813 OPENSSL_FOUND
11815 System has the OpenSSL library.
11816 OPENSSL_INCLUDE_DIR
11818 The OpenSSL include directory.
11819 OPENSSL_CRYPTO_LIBRARY
11821 The OpenSSL crypto library.
11822 OPENSSL_SSL_LIBRARY
11824 The OpenSSL SSL library.
11825 OPENSSL_LIBRARIES
11827 All OpenSSL libraries.
11828 OPENSSL_VERSION
11830 This is set to $major.$minor.$revision$patch (e.g. 0.9.8s).
11831 Hints
11833 Set OPENSSL_ROOT_DIR to the root directory of an OpenSSL installation.
11834 Set OPENSSL_USE_STATIC_LIBS to TRUE to look for static libraries. Set
11835 OPENSSL_MSVC_STATIC_RT set TRUE to choose the MT version of the lib.
11836 FindOpenThreads
11838 OpenThreads is a C++ based threading library. Its largest userbase
11839 seems to OpenSceneGraph so you might notice I accept OSGDIR as an envi‐
11840 ronment path. I consider this part of the Findosg* suite used to find
11841 OpenSceneGraph components. Each component is separate and you must opt
11842 in to each module.
11843 Locate OpenThreads This module defines OPENTHREADS_LIBRARY
11845 OPENTHREADS_FOUND, if false, do not try to link to OpenThreads
11846 OPENTHREADS_INCLUDE_DIR, where to find the headers
11847 $OPENTHREADS_DIR is an environment variable that would correspond to
11849 the ./configure –prefix=$OPENTHREADS_DIR used in building osg.
11850 [CMake 2.8.10]: The CMake variables OPENTHREADS_DIR or OSG_DIR can now
11852 be used as well to influence detection, instead of needing to specify
11853 an environment variable.
11854 Created by Eric Wing.
11856 FindosgAnimation
11858 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
11859 nents. Each component is separate and you must opt in to each module.
11860 You must also opt into OpenGL and OpenThreads (and Producer if needed)
11861 as these modules won’t do it for you. This is to allow you control
11862 over your own system piece by piece in case you need to opt out of cer‐
11863 tain components or change the Find behavior for a particular module
11864 (perhaps because the default FindOpenGL.cmake module doesn’t work with
11865 your system as an example). If you want to use a more convenient mod‐
11866 ule that includes everything, use the FindOpenSceneGraph.cmake instead
11867 of the Findosg*.cmake modules.
11868 Locate osgAnimation This module defines
11870 OSGANIMATION_FOUND - Was osgAnimation found? OSGANIMATION_INCLUDE_DIR -
11872 Where to find the headers OSGANIMATION_LIBRARIES - The libraries to
11873 link against for the OSG (use this)
11874 OSGANIMATION_LIBRARY - The OSG library OSGANIMATION_LIBRARY_DEBUG - The
11876 OSG debug library
11877 $OSGDIR is an environment variable that would correspond to the
11879 Created by Eric Wing.
11881 FindosgDB
11883 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
11884 nents. Each component is separate and you must opt in to each module.
11885 You must also opt into OpenGL and OpenThreads (and Producer if needed)
11886 as these modules won’t do it for you. This is to allow you control
11887 over your own system piece by piece in case you need to opt out of cer‐
11888 tain components or change the Find behavior for a particular module
11889 (perhaps because the default FindOpenGL.cmake module doesn’t work with
11890 your system as an example). If you want to use a more convenient mod‐
11891 ule that includes everything, use the FindOpenSceneGraph.cmake instead
11892 of the Findosg*.cmake modules.
11893 Locate osgDB This module defines
11895 OSGDB_FOUND - Was osgDB found? OSGDB_INCLUDE_DIR - Where to find the
11897 headers OSGDB_LIBRARIES - The libraries to link against for the osgDB
11898 (use this)
11899 OSGDB_LIBRARY - The osgDB library OSGDB_LIBRARY_DEBUG - The osgDB debug
11901 library
11902 $OSGDIR is an environment variable that would correspond to the
11904 Created by Eric Wing.
11906 Findosg_functions
11908 This CMake file contains two macros to assist with searching for OSG
11909 libraries and nodekits. Please see FindOpenSceneGraph.cmake for full
11910 documentation.
11911 FindosgFX
11913 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
11914 nents. Each component is separate and you must opt in to each module.
11915 You must also opt into OpenGL and OpenThreads (and Producer if needed)
11916 as these modules won’t do it for you. This is to allow you control
11917 over your own system piece by piece in case you need to opt out of cer‐
11918 tain components or change the Find behavior for a particular module
11919 (perhaps because the default FindOpenGL.cmake module doesn’t work with
11920 your system as an example). If you want to use a more convenient mod‐
11921 ule that includes everything, use the FindOpenSceneGraph.cmake instead
11922 of the Findosg*.cmake modules.
11923 Locate osgFX This module defines
11925 OSGFX_FOUND - Was osgFX found? OSGFX_INCLUDE_DIR - Where to find the
11927 headers OSGFX_LIBRARIES - The libraries to link against for the osgFX
11928 (use this)
11929 OSGFX_LIBRARY - The osgFX library OSGFX_LIBRARY_DEBUG - The osgFX debug
11931 library
11932 $OSGDIR is an environment variable that would correspond to the
11934 Created by Eric Wing.
11936 FindosgGA
11938 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
11939 nents. Each component is separate and you must opt in to each module.
11940 You must also opt into OpenGL and OpenThreads (and Producer if needed)
11941 as these modules won’t do it for you. This is to allow you control
11942 over your own system piece by piece in case you need to opt out of cer‐
11943 tain components or change the Find behavior for a particular module
11944 (perhaps because the default FindOpenGL.cmake module doesn’t work with
11945 your system as an example). If you want to use a more convenient mod‐
11946 ule that includes everything, use the FindOpenSceneGraph.cmake instead
11947 of the Findosg*.cmake modules.
11948 Locate osgGA This module defines
11950 OSGGA_FOUND - Was osgGA found? OSGGA_INCLUDE_DIR - Where to find the
11952 headers OSGGA_LIBRARIES - The libraries to link against for the osgGA
11953 (use this)
11954 OSGGA_LIBRARY - The osgGA library OSGGA_LIBRARY_DEBUG - The osgGA debug
11956 library
11957 $OSGDIR is an environment variable that would correspond to the
11959 Created by Eric Wing.
11961 FindosgIntrospection
11963 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
11964 nents. Each component is separate and you must opt in to each module.
11965 You must also opt into OpenGL and OpenThreads (and Producer if needed)
11966 as these modules won’t do it for you. This is to allow you control
11967 over your own system piece by piece in case you need to opt out of cer‐
11968 tain components or change the Find behavior for a particular module
11969 (perhaps because the default FindOpenGL.cmake module doesn’t work with
11970 your system as an example). If you want to use a more convenient mod‐
11971 ule that includes everything, use the FindOpenSceneGraph.cmake instead
11972 of the Findosg*.cmake modules.
11973 Locate osgINTROSPECTION This module defines
11975 OSGINTROSPECTION_FOUND - Was osgIntrospection found? OSGINTROSPEC‐
11977 TION_INCLUDE_DIR - Where to find the headers OSGINTROSPECTION_LIBRARIES
11978 - The libraries to link for osgIntrospection (use this)
11979 OSGINTROSPECTION_LIBRARY - The osgIntrospection library OSGINTROSPEC‐
11981 TION_LIBRARY_DEBUG - The osgIntrospection debug library
11982 $OSGDIR is an environment variable that would correspond to the
11984 Created by Eric Wing.
11986 FindosgManipulator
11988 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
11989 nents. Each component is separate and you must opt in to each module.
11990 You must also opt into OpenGL and OpenThreads (and Producer if needed)
11991 as these modules won’t do it for you. This is to allow you control
11992 over your own system piece by piece in case you need to opt out of cer‐
11993 tain components or change the Find behavior for a particular module
11994 (perhaps because the default FindOpenGL.cmake module doesn’t work with
11995 your system as an example). If you want to use a more convenient mod‐
11996 ule that includes everything, use the FindOpenSceneGraph.cmake instead
11997 of the Findosg*.cmake modules.
11998 Locate osgManipulator This module defines
12000 OSGMANIPULATOR_FOUND - Was osgManipulator found? OSGMANIPULA‐
12002 TOR_INCLUDE_DIR - Where to find the headers OSGMANIPULATOR_LIBRARIES -
12003 The libraries to link for osgManipulator (use this)
12004 OSGMANIPULATOR_LIBRARY - The osgManipulator library OSGMANIPULA‐
12006 TOR_LIBRARY_DEBUG - The osgManipulator debug library
12007 $OSGDIR is an environment variable that would correspond to the
12009 Created by Eric Wing.
12011 FindosgParticle
12013 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12014 nents. Each component is separate and you must opt in to each module.
12015 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12016 as these modules won’t do it for you. This is to allow you control
12017 over your own system piece by piece in case you need to opt out of cer‐
12018 tain components or change the Find behavior for a particular module
12019 (perhaps because the default FindOpenGL.cmake module doesn’t work with
12020 your system as an example). If you want to use a more convenient mod‐
12021 ule that includes everything, use the FindOpenSceneGraph.cmake instead
12022 of the Findosg*.cmake modules.
12023 Locate osgParticle This module defines
12025 OSGPARTICLE_FOUND - Was osgParticle found? OSGPARTICLE_INCLUDE_DIR -
12027 Where to find the headers OSGPARTICLE_LIBRARIES - The libraries to link
12028 for osgParticle (use this)
12029 OSGPARTICLE_LIBRARY - The osgParticle library OSGPARTICLE_LIBRARY_DEBUG
12031 - The osgParticle debug library
12032 $OSGDIR is an environment variable that would correspond to the
12034 Created by Eric Wing.
12036 FindosgPresentation
12038 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12039 nents. Each component is separate and you must opt in to each module.
12040 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12041 as these modules won’t do it for you. This is to allow you control
12042 over your own system piece by piece in case you need to opt out of cer‐
12043 tain components or change the Find behavior for a particular module
12044 (perhaps because the default FindOpenGL.cmake module doesn’t work with
12045 your system as an example). If you want to use a more convenient mod‐
12046 ule that includes everything, use the FindOpenSceneGraph.cmake instead
12047 of the Findosg*.cmake modules.
12048 Locate osgPresentation This module defines
12050 OSGPRESENTATION_FOUND - Was osgPresentation found? OSGPRESENTA‐
12052 TION_INCLUDE_DIR - Where to find the headers OSGPRESENTATION_LIBRARIES
12053 - The libraries to link for osgPresentation (use this)
12054 OSGPRESENTATION_LIBRARY - The osgPresentation library OSGPRESENTA‐
12056 TION_LIBRARY_DEBUG - The osgPresentation debug library
12057 $OSGDIR is an environment variable that would correspond to the
12059 Created by Eric Wing. Modified to work with osgPresentation by Robert
12061 Osfield, January 2012.
12062 FindosgProducer
12064 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12065 nents. Each component is separate and you must opt in to each module.
12066 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12067 as these modules won’t do it for you. This is to allow you control
12068 over your own system piece by piece in case you need to opt out of cer‐
12069 tain components or change the Find behavior for a particular module
12070 (perhaps because the default FindOpenGL.cmake module doesn’t work with
12071 your system as an example). If you want to use a more convenient mod‐
12072 ule that includes everything, use the FindOpenSceneGraph.cmake instead
12073 of the Findosg*.cmake modules.
12074 Locate osgProducer This module defines
12076 OSGPRODUCER_FOUND - Was osgProducer found? OSGPRODUCER_INCLUDE_DIR -
12078 Where to find the headers OSGPRODUCER_LIBRARIES - The libraries to link
12079 for osgProducer (use this)
12080 OSGPRODUCER_LIBRARY - The osgProducer library OSGPRODUCER_LIBRARY_DEBUG
12082 - The osgProducer debug library
12083 $OSGDIR is an environment variable that would correspond to the
12085 Created by Eric Wing.
12087 FindosgQt
12089 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12090 nents. Each component is separate and you must opt in to each module.
12091 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12092 as these modules won’t do it for you. This is to allow you control
12093 over your own system piece by piece in case you need to opt out of cer‐
12094 tain components or change the Find behavior for a particular module
12095 (perhaps because the default FindOpenGL.cmake module doesn’t work with
12096 your system as an example). If you want to use a more convenient mod‐
12097 ule that includes everything, use the FindOpenSceneGraph.cmake instead
12098 of the Findosg*.cmake modules.
12099 Locate osgQt This module defines
12101 OSGQT_FOUND - Was osgQt found? OSGQT_INCLUDE_DIR - Where to find the
12103 headers OSGQT_LIBRARIES - The libraries to link for osgQt (use this)
12104 OSGQT_LIBRARY - The osgQt library OSGQT_LIBRARY_DEBUG - The osgQt debug
12106 library
12107 $OSGDIR is an environment variable that would correspond to the
12109 Created by Eric Wing. Modified to work with osgQt by Robert Osfield,
12111 January 2012.
12112 Findosg
12114 NOTE: It is highly recommended that you use the new FindOpenScene‐
12115 Graph.cmake introduced in CMake 2.6.3 and not use this Find module
12116 directly.
12117 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12119 nents. Each component is separate and you must opt in to each module.
12120 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12121 as these modules won’t do it for you. This is to allow you control
12122 over your own system piece by piece in case you need to opt out of cer‐
12123 tain components or change the Find behavior for a particular module
12124 (perhaps because the default FindOpenGL.cmake module doesn’t work with
12125 your system as an example). If you want to use a more convenient mod‐
12126 ule that includes everything, use the FindOpenSceneGraph.cmake instead
12127 of the Findosg*.cmake modules.
12128 Locate osg This module defines
12130 OSG_FOUND - Was the Osg found? OSG_INCLUDE_DIR - Where to find the
12132 headers OSG_LIBRARIES - The libraries to link against for the OSG (use
12133 this)
12134 OSG_LIBRARY - The OSG library OSG_LIBRARY_DEBUG - The OSG debug library
12136 $OSGDIR is an environment variable that would correspond to the
12138 Created by Eric Wing.
12140 FindosgShadow
12142 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12143 nents. Each component is separate and you must opt in to each module.
12144 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12145 as these modules won’t do it for you. This is to allow you control
12146 over your own system piece by piece in case you need to opt out of cer‐
12147 tain components or change the Find behavior for a particular module
12148 (perhaps because the default FindOpenGL.cmake module doesn’t work with
12149 your system as an example). If you want to use a more convenient mod‐
12150 ule that includes everything, use the FindOpenSceneGraph.cmake instead
12151 of the Findosg*.cmake modules.
12152 Locate osgShadow This module defines
12154 OSGSHADOW_FOUND - Was osgShadow found? OSGSHADOW_INCLUDE_DIR - Where to
12156 find the headers OSGSHADOW_LIBRARIES - The libraries to link for
12157 osgShadow (use this)
12158 OSGSHADOW_LIBRARY - The osgShadow library OSGSHADOW_LIBRARY_DEBUG - The
12160 osgShadow debug library
12161 $OSGDIR is an environment variable that would correspond to the
12163 Created by Eric Wing.
12165 FindosgSim
12167 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12168 nents. Each component is separate and you must opt in to each module.
12169 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12170 as these modules won’t do it for you. This is to allow you control
12171 over your own system piece by piece in case you need to opt out of cer‐
12172 tain components or change the Find behavior for a particular module
12173 (perhaps because the default FindOpenGL.cmake module doesn’t work with
12174 your system as an example). If you want to use a more convenient mod‐
12175 ule that includes everything, use the FindOpenSceneGraph.cmake instead
12176 of the Findosg*.cmake modules.
12177 Locate osgSim This module defines
12179 OSGSIM_FOUND - Was osgSim found? OSGSIM_INCLUDE_DIR - Where to find the
12181 headers OSGSIM_LIBRARIES - The libraries to link for osgSim (use this)
12182 OSGSIM_LIBRARY - The osgSim library OSGSIM_LIBRARY_DEBUG - The osgSim
12184 debug library
12185 $OSGDIR is an environment variable that would correspond to the
12187 Created by Eric Wing.
12189 FindosgTerrain
12191 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12192 nents. Each component is separate and you must opt in to each module.
12193 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12194 as these modules won’t do it for you. This is to allow you control
12195 over your own system piece by piece in case you need to opt out of cer‐
12196 tain components or change the Find behavior for a particular module
12197 (perhaps because the default FindOpenGL.cmake module doesn’t work with
12198 your system as an example). If you want to use a more convenient mod‐
12199 ule that includes everything, use the FindOpenSceneGraph.cmake instead
12200 of the Findosg*.cmake modules.
12201 Locate osgTerrain This module defines
12203 OSGTERRAIN_FOUND - Was osgTerrain found? OSGTERRAIN_INCLUDE_DIR - Where
12205 to find the headers OSGTERRAIN_LIBRARIES - The libraries to link for
12206 osgTerrain (use this)
12207 OSGTERRAIN_LIBRARY - The osgTerrain library OSGTERRAIN_LIBRARY_DEBUG -
12209 The osgTerrain debug library
12210 $OSGDIR is an environment variable that would correspond to the
12212 Created by Eric Wing.
12214 FindosgText
12216 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12217 nents. Each component is separate and you must opt in to each module.
12218 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12219 as these modules won’t do it for you. This is to allow you control
12220 over your own system piece by piece in case you need to opt out of cer‐
12221 tain components or change the Find behavior for a particular module
12222 (perhaps because the default FindOpenGL.cmake module doesn’t work with
12223 your system as an example). If you want to use a more convenient mod‐
12224 ule that includes everything, use the FindOpenSceneGraph.cmake instead
12225 of the Findosg*.cmake modules.
12226 Locate osgText This module defines
12228 OSGTEXT_FOUND - Was osgText found? OSGTEXT_INCLUDE_DIR - Where to find
12230 the headers OSGTEXT_LIBRARIES - The libraries to link for osgText (use
12231 this)
12232 OSGTEXT_LIBRARY - The osgText library OSGTEXT_LIBRARY_DEBUG - The osg‐
12234 Text debug library
12235 $OSGDIR is an environment variable that would correspond to the
12237 Created by Eric Wing.
12239 FindosgUtil
12241 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12242 nents. Each component is separate and you must opt in to each module.
12243 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12244 as these modules won’t do it for you. This is to allow you control
12245 over your own system piece by piece in case you need to opt out of cer‐
12246 tain components or change the Find behavior for a particular module
12247 (perhaps because the default FindOpenGL.cmake module doesn’t work with
12248 your system as an example). If you want to use a more convenient mod‐
12249 ule that includes everything, use the FindOpenSceneGraph.cmake instead
12250 of the Findosg*.cmake modules.
12251 Locate osgUtil This module defines
12253 OSGUTIL_FOUND - Was osgUtil found? OSGUTIL_INCLUDE_DIR - Where to find
12255 the headers OSGUTIL_LIBRARIES - The libraries to link for osgUtil (use
12256 this)
12257 OSGUTIL_LIBRARY - The osgUtil library OSGUTIL_LIBRARY_DEBUG - The
12259 osgUtil debug library
12260 $OSGDIR is an environment variable that would correspond to the
12262 Created by Eric Wing.
12264 FindosgViewer
12266 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12267 nents. Each component is separate and you must opt in to each module.
12268 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12269 as these modules won’t do it for you. This is to allow you control
12270 over your own system piece by piece in case you need to opt out of cer‐
12271 tain components or change the Find behavior for a particular module
12272 (perhaps because the default FindOpenGL.cmake module doesn’t work with
12273 your system as an example). If you want to use a more convenient mod‐
12274 ule that includes everything, use the FindOpenSceneGraph.cmake instead
12275 of the Findosg*.cmake modules.
12276 Locate osgViewer This module defines
12278 OSGVIEWER_FOUND - Was osgViewer found? OSGVIEWER_INCLUDE_DIR - Where to
12280 find the headers OSGVIEWER_LIBRARIES - The libraries to link for
12281 osgViewer (use this)
12282 OSGVIEWER_LIBRARY - The osgViewer library OSGVIEWER_LIBRARY_DEBUG - The
12284 osgViewer debug library
12285 $OSGDIR is an environment variable that would correspond to the
12287 Created by Eric Wing.
12289 FindosgVolume
12291 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12292 nents. Each component is separate and you must opt in to each module.
12293 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12294 as these modules won’t do it for you. This is to allow you control
12295 over your own system piece by piece in case you need to opt out of cer‐
12296 tain components or change the Find behavior for a particular module
12297 (perhaps because the default FindOpenGL.cmake module doesn’t work with
12298 your system as an example). If you want to use a more convenient mod‐
12299 ule that includes everything, use the FindOpenSceneGraph.cmake instead
12300 of the Findosg*.cmake modules.
12301 Locate osgVolume This module defines
12303 OSGVOLUME_FOUND - Was osgVolume found? OSGVOLUME_INCLUDE_DIR - Where to
12305 find the headers OSGVOLUME_LIBRARIES - The libraries to link for
12306 osgVolume (use this)
12307 OSGVOLUME_LIBRARY - The osgVolume library OSGVOLUME_LIBRARY_DEBUG - The
12309 osgVolume debug library
12310 $OSGDIR is an environment variable that would correspond to the
12312 Created by Eric Wing.
12314 FindosgWidget
12316 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
12317 nents. Each component is separate and you must opt in to each module.
12318 You must also opt into OpenGL and OpenThreads (and Producer if needed)
12319 as these modules won’t do it for you. This is to allow you control
12320 over your own system piece by piece in case you need to opt out of cer‐
12321 tain components or change the Find behavior for a particular module
12322 (perhaps because the default FindOpenGL.cmake module doesn’t work with
12323 your system as an example). If you want to use a more convenient mod‐
12324 ule that includes everything, use the FindOpenSceneGraph.cmake instead
12325 of the Findosg*.cmake modules.
12326 Locate osgWidget This module defines
12328 OSGWIDGET_FOUND - Was osgWidget found? OSGWIDGET_INCLUDE_DIR - Where to
12330 find the headers OSGWIDGET_LIBRARIES - The libraries to link for osg‐
12331 Widget (use this)
12332 OSGWIDGET_LIBRARY - The osgWidget library OSGWIDGET_LIBRARY_DEBUG - The
12334 osgWidget debug library
12335 $OSGDIR is an environment variable that would correspond to the
12337 FindosgWidget.cmake tweaked from Findosg* suite as created by Eric
12339 Wing.
12340 FindPackageHandleStandardArgs
12342 This module provides a function intended to be used in Find Modules
12343 implementing find_package(<PackageName>) calls. It handles the
12344 REQUIRED, QUIET and version-related arguments of find_package. It also
12345 sets the <PackageName>_FOUND variable. The package is considered found
12346 if all variables listed contain valid results, e.g. valid filepaths.
12347 find_package_handle_standard_args
12349 There are two signatures:
12350 find_package_handle_standard_args(<PackageName>
12352 (DEFAULT_MSG|<custom-failure-message>)
12353 <required-var>...
12354 )
12355 find_package_handle_standard_args(<PackageName>
12357 [FOUND_VAR <result-var>]
12358 [REQUIRED_VARS <required-var>...]
12359 [VERSION_VAR <version-var>]
12360 [HANDLE_COMPONENTS]
12361 [CONFIG_MODE]
12362 [FAIL_MESSAGE <custom-failure-message>]
12363 )
12364 The <PackageName>_FOUND variable will be set to TRUE if all the
12366 variables <required-var>... are valid and any optional con‐
12367 straints are satisfied, and FALSE otherwise. A success or fail‐
12368 ure message may be displayed based on the results and on whether
12369 the REQUIRED and/or QUIET option was given to the find_package()
12370 call.
12371 The options are:
12373 (DEFAULT_MSG|<custom-failure-message>)
12375 In the simple signature this specifies the failure mes‐
12376 sage. Use DEFAULT_MSG to ask for a default message to be
12377 computed (recommended). Not valid in the full signature.
12378 FOUND_VAR <result-var>
12380 Obsolete. Specifies either <PackageName>_FOUND or <PACK‐
12381 AGENAME>_FOUND as the result variable. This exists only
12382 for compatibility with older versions of CMake and is now
12383 ignored. Result variables of both names are always set
12384 for compatibility.
12385 REQUIRED_VARS <required-var>...
12387 Specify the variables which are required for this pack‐
12388 age. These may be named in the generated failure message
12389 asking the user to set the missing variable values.
12390 Therefore these should typically be cache entries such as
12391 FOO_LIBRARY and not output variables like FOO_LIBRARIES.
12392 VERSION_VAR <version-var>
12394 Specify the name of a variable that holds the version of
12395 the package that has been found. This version will be
12396 checked against the (potentially) specified required ver‐
12397 sion given to the find_package() call, including its
12398 EXACT option. The default messages include information
12399 about the required version and the version which has been
12400 actually found, both if the version is ok or not.
12401 HANDLE_COMPONENTS
12403 Enable handling of package components. In this case, the
12404 command will report which components have been found and
12405 which are missing, and the <PackageName>_FOUND variable
12406 will be set to FALSE if any of the required components
12407 (i.e. not the ones listed after the OPTIONAL_COMPONENTS
12408 option of find_package()) are missing.
12409 CONFIG_MODE
12411 Specify that the calling find module is a wrapper around
12412 a call to find_package(<PackageName> NO_MODULE). This
12413 implies a VERSION_VAR value of <PackageName>_VERSION.
12414 The command will automatically check whether the package
12415 configuration file was found.
12416 FAIL_MESSAGE <custom-failure-message>
12418 Specify a custom failure message instead of using the
12419 default generated message. Not recommended.
12420 Example for the simple signature:
12422 find_package_handle_standard_args(LibXml2 DEFAULT_MSG
12424 LIBXML2_LIBRARY LIBXML2_INCLUDE_DIR)
12425 The LibXml2 package is considered to be found if both LIBXML2_LIBRARY
12427 and LIBXML2_INCLUDE_DIR are valid. Then also LibXml2_FOUND is set to
12428 TRUE. If it is not found and REQUIRED was used, it fails with a mes‐
12429 sage(FATAL_ERROR), independent whether QUIET was used or not. If it is
12430 found, success will be reported, including the content of the first
12431 <required-var>. On repeated CMake runs, the same message will not be
12432 printed again.
12433 Example for the full signature:
12435 find_package_handle_standard_args(LibArchive
12437 REQUIRED_VARS LibArchive_LIBRARY LibArchive_INCLUDE_DIR
12438 VERSION_VAR LibArchive_VERSION)
12439 In this case, the LibArchive package is considered to be found if both
12441 LibArchive_LIBRARY and LibArchive_INCLUDE_DIR are valid. Also the ver‐
12442 sion of LibArchive will be checked by using the version contained in
12443 LibArchive_VERSION. Since no FAIL_MESSAGE is given, the default mes‐
12444 sages will be printed.
12445 Another example for the full signature:
12447 find_package(Automoc4 QUIET NO_MODULE HINTS /opt/automoc4)
12449 find_package_handle_standard_args(Automoc4 CONFIG_MODE)
12450 In this case, a FindAutmoc4.cmake module wraps a call to find_pack‐
12452 age(Automoc4 NO_MODULE) and adds an additional search directory for
12453 automoc4. Then the call to find_package_handle_standard_args produces
12454 a proper success/failure message.
12455 FindPackageMessage
12457 FIND_PACKAGE_MESSAGE(<name> “message for user” “find result details”)
12458 This macro is intended to be used in FindXXX.cmake modules files. It
12460 will print a message once for each unique find result. This is useful
12461 for telling the user where a package was found. The first argument
12462 specifies the name (XXX) of the package. The second argument specifies
12463 the message to display. The third argument lists details about the
12464 find result so that if they change the message will be displayed again.
12465 The macro also obeys the QUIET argument to the find_package command.
12466 Example:
12468 if(X11_FOUND)
12470 FIND_PACKAGE_MESSAGE(X11 "Found X11: ${X11_X11_LIB}"
12471 "[${X11_X11_LIB}][${X11_INCLUDE_DIR}]")
12472 else()
12473 ...
12474 endif()
12475 FindPatch
12477 The module defines the following variables:
12478 Patch_EXECUTABLE
12480 Path to patch command-line executable.
12481 Patch_FOUND
12483 True if the patch command-line executable was found.
12484 The following IMPORTED targets are also defined:
12486 Patch::patch
12488 The command-line executable.
12489 Example usage:
12491 find_package(Patch)
12493 if(Patch_FOUND)
12494 message("Patch found: ${Patch_EXECUTABLE}")
12495 endif()
12496 FindPerlLibs
12498 Find Perl libraries
12499 This module finds if PERL is installed and determines where the include
12501 files and libraries are. It also determines what the name of the
12502 library is. This code sets the following variables:
12503 PERLLIBS_FOUND = True if perl.h & libperl were found
12505 PERL_INCLUDE_PATH = path to where perl.h is found
12506 PERL_LIBRARY = path to libperl
12507 PERL_EXECUTABLE = full path to the perl binary
12508 The minimum required version of Perl can be specified using the stan‐
12510 dard syntax, e.g. find_package(PerlLibs 6.0)
12511 The following variables are also available if needed
12513 (introduced after CMake 2.6.4)
12514 PERL_SITESEARCH = path to the sitesearch install dir (-V:installsitesearch)
12516 PERL_SITEARCH = path to the sitelib install directory (-V:installsitearch)
12517 PERL_SITELIB = path to the sitelib install directory (-V:installsitelib)
12518 PERL_VENDORARCH = path to the vendor arch install directory (-V:installvendorarch)
12519 PERL_VENDORLIB = path to the vendor lib install directory (-V:installvendorlib)
12520 PERL_ARCHLIB = path to the core arch lib install directory (-V:archlib)
12521 PERL_PRIVLIB = path to the core priv lib install directory (-V:privlib)
12522 PERL_UPDATE_ARCHLIB = path to the update arch lib install directory (-V:installarchlib)
12523 PERL_UPDATE_PRIVLIB = path to the update priv lib install directory (-V:installprivlib)
12524 PERL_EXTRA_C_FLAGS = Compilation flags used to build perl
12525 FindPerl
12527 Find perl
12528 this module looks for Perl
12530 PERL_EXECUTABLE - the full path to perl
12532 PERL_FOUND - If false, don't attempt to use perl.
12533 PERL_VERSION_STRING - version of perl found (since CMake 2.8.8)
12534 FindPHP4
12536 Find PHP4
12537 This module finds if PHP4 is installed and determines where the include
12539 files and libraries are. It also determines what the name of the
12540 library is. This code sets the following variables:
12541 PHP4_INCLUDE_PATH = path to where php.h can be found
12543 PHP4_EXECUTABLE = full path to the php4 binary
12544 FindPhysFS
12546 Locate PhysFS library This module defines PHYSFS_LIBRARY, the name of
12547 the library to link against PHYSFS_FOUND, if false, do not try to link
12548 to PHYSFS PHYSFS_INCLUDE_DIR, where to find physfs.h
12549 $PHYSFSDIR is an environment variable that would correspond to the
12551 Created by Eric Wing.
12553 FindPike
12555 Find Pike
12556 This module finds if PIKE is installed and determines where the include
12558 files and libraries are. It also determines what the name of the
12559 library is. This code sets the following variables:
12560 PIKE_INCLUDE_PATH = path to where program.h is found
12562 PIKE_EXECUTABLE = full path to the pike binary
12563 FindPkgConfig
12565 A pkg-config module for CMake.
12566 Finds the pkg-config executable and adds the pkg_get_variable(),
12568 pkg_check_modules() and pkg_search_module() commands. The following
12569 variables will also be set:
12570 PKG_CONFIG_FOUND ... if pkg-config executable was found
12572 PKG_CONFIG_EXECUTABLE ... pathname of the pkg-config program
12573 PKG_CONFIG_VERSION_STRING ... the version of the pkg-config program found
12574 (since CMake 2.8.8)
12575 pkg_get_variable
12577 Retrieves the value of a pkg-config variable varName and stores
12578 it in the result variable resultVar in the calling scope.
12579 pkg_get_variable(<resultVar> <moduleName> <varName>)
12581 If pkg-config returns multiple values for the specified vari‐
12583 able, resultVar will contain a ;-list.
12584 For example:
12586 pkg_get_variable(GI_GIRDIR gobject-introspection-1.0 girdir)
12588 pkg_check_modules
12590 Checks for all the given modules, setting a variety of result
12591 variables in the calling scope.
12592 pkg_check_modules(<prefix>
12594 [REQUIRED] [QUIET]
12595 [NO_CMAKE_PATH]
12596 [NO_CMAKE_ENVIRONMENT_PATH]
12597 [IMPORTED_TARGET]
12598 <moduleSpec> [<moduleSpec>...])
12599 When the REQUIRED argument is given, the command will fail with
12601 an error if module(s) could not be found.
12602 When the QUIET argument is given, no status messages will be
12604 printed.
12605 By default, if CMAKE_MINIMUM_REQUIRED_VERSION is 3.1 or later,
12607 or if PKG_CONFIG_USE_CMAKE_PREFIX_PATH is set to a boolean True
12608 value, then the CMAKE_PREFIX_PATH, CMAKE_FRAMEWORK_PATH, and
12609 CMAKE_APPBUNDLE_PATH cache and environment variables will be
12610 added to the pkg-config search path. The NO_CMAKE_PATH and
12611 NO_CMAKE_ENVIRONMENT_PATH arguments disable this behavior for
12612 the cache variables and environment variables respectively.
12613 The IMPORTED_TARGET argument will create an imported target
12615 named PkgConfig::<prefix> that can be passed directly as an
12616 argument to target_link_libraries().
12617 Each <moduleSpec> must be in one of the following formats:
12619 {moduleName} ... matches any version
12621 {moduleName}>={version} ... at least version <version> is required
12622 {moduleName}={version} ... exactly version <version> is required
12623 {moduleName}<={version} ... modules must not be newer than <version>
12624 The following variables may be set upon return. Two sets of
12626 values exist, one for the common case (<XXX> = <prefix>) and
12627 another for the information pkg-config provides when it is
12628 called with the --static option (<XXX> = <prefix>_STATIC):
12629 <XXX>_FOUND ... set to 1 if module(s) exist
12631 <XXX>_LIBRARIES ... only the libraries (without the '-l')
12632 <XXX>_LIBRARY_DIRS ... the paths of the libraries (without the '-L')
12633 <XXX>_LDFLAGS ... all required linker flags
12634 <XXX>_LDFLAGS_OTHER ... all other linker flags
12635 <XXX>_INCLUDE_DIRS ... the '-I' preprocessor flags (without the '-I')
12636 <XXX>_CFLAGS ... all required cflags
12637 <XXX>_CFLAGS_OTHER ... the other compiler flags
12638 All but <XXX>_FOUND may be a ;-list if the associated variable
12640 returned from pkg-config has multiple values.
12641 There are some special variables whose prefix depends on the
12643 number of <moduleSpec> given. When there is only one <module‐
12644 Spec>, <YYY> will simply be <prefix>, but if two or more <mod‐
12645 uleSpec> items are given, <YYY> will be <prefix>_<moduleName>:
12646 <YYY>_VERSION ... version of the module
12648 <YYY>_PREFIX ... prefix directory of the module
12649 <YYY>_INCLUDEDIR ... include directory of the module
12650 <YYY>_LIBDIR ... lib directory of the module
12651 Examples
12653 pkg_check_modules (GLIB2 glib-2.0)
12655 Looks for any version of glib2. If found, the output variable
12657 GLIB2_VERSION will hold the actual version found.
12658 pkg_check_modules (GLIB2 glib-2.0>=2.10)
12660 Looks for at least version 2.10 of glib2. If found, the output
12662 variable GLIB2_VERSION will hold the actual version found.
12663 pkg_check_modules (FOO glib-2.0>=2.10 gtk+-2.0)
12665 Looks for both glib2-2.0 (at least version 2.10) and any version
12667 of gtk2+-2.0. Only if both are found will FOO be considered
12668 found. The FOO_glib-2.0_VERSION and FOO_gtk+-2.0_VERSION vari‐
12669 ables will be set to their respective found module versions.
12670 pkg_check_modules (XRENDER REQUIRED xrender)
12672 Requires any version of xrender. Example output variables set
12674 by a successful call:
12675 XRENDER_LIBRARIES=Xrender;X11
12677 XRENDER_STATIC_LIBRARIES=Xrender;X11;pthread;Xau;Xdmcp
12678 pkg_search_module
12680 The behavior of this command is the same as pkg_check_modules(),
12681 except that rather than checking for all the specified modules,
12682 it searches for just the first successful match.
12683 pkg_search_module(<prefix>
12685 [REQUIRED] [QUIET]
12686 [NO_CMAKE_PATH]
12687 [NO_CMAKE_ENVIRONMENT_PATH]
12688 [IMPORTED_TARGET]
12689 <moduleSpec> [<moduleSpec>...])
12690 Examples
12692 pkg_search_module (BAR libxml-2.0 libxml2 libxml>=2)
12694 Variables Affecting Behavior
12696 PKG_CONFIG_EXECUTABLE
12697 This can be set to the path of the pkg-config executable. If
12698 not provided, it will be set by the module as a result of call‐
12699 ing find_program() internally. The PKG_CONFIG environment vari‐
12700 able can be used as a hint.
12701 PKG_CONFIG_USE_CMAKE_PREFIX_PATH
12703 Specifies whether pkg_check_modules() and pkg_search_module()
12704 should add the paths in the CMAKE_PREFIX_PATH, CMAKE_FRAME‐
12705 WORK_PATH and CMAKE_APPBUNDLE_PATH cache and environment vari‐
12706 ables to the pkg-config search path.
12707 If this variable is not set, this behavior is enabled by default
12709 if CMAKE_MINIMUM_REQUIRED_VERSION is 3.1 or later, disabled oth‐
12710 erwise.
12711 FindPNG
12713 Find libpng, the official reference library for the PNG image format.
12714 Imported targets
12716 This module defines the following IMPORTED target:
12717 PNG::PNG
12719 The libpng library, if found.
12720 Result variables
12722 This module will set the following variables in your project:
12723 PNG_INCLUDE_DIRS
12725 where to find png.h, etc.
12726 PNG_LIBRARIES
12728 the libraries to link against to use PNG.
12729 PNG_DEFINITIONS
12731 You should add_definitions(${PNG_DEFINITIONS}) before compiling
12732 code that includes png library files.
12733 PNG_FOUND
12735 If false, do not try to use PNG.
12736 PNG_VERSION_STRING
12738 the version of the PNG library found (since CMake 2.8.8)
12739 Obsolete variables
12741 The following variables may also be set, for backwards compatibility:
12742 PNG_LIBRARY
12744 where to find the PNG library.
12745 PNG_INCLUDE_DIR
12747 where to find the PNG headers (same as PNG_INCLUDE_DIRS)
12748 Since PNG depends on the ZLib compression library, none of the above
12750 will be defined unless ZLib can be found.
12751 FindPostgreSQL
12753 Find the PostgreSQL installation.
12754 This module defines
12756 PostgreSQL_LIBRARIES - the PostgreSQL libraries needed for linking
12758 PostgreSQL_INCLUDE_DIRS - the directories of the PostgreSQL headers
12759 PostgreSQL_LIBRARY_DIRS - the link directories for PostgreSQL libraries
12760 PostgreSQL_VERSION_STRING - the version of PostgreSQL found (since CMake 2.8.8)
12761 FindProducer
12763 Though Producer isn’t directly part of OpenSceneGraph, its primary user
12764 is OSG so I consider this part of the Findosg* suite used to find Open‐
12765 SceneGraph components. You’ll notice that I accept OSGDIR as an envi‐
12766 ronment path.
12767 Each component is separate and you must opt in to each module. You
12769 must also opt into OpenGL (and OpenThreads?) as these modules won’t do
12770 it for you. This is to allow you control over your own system piece by
12771 piece in case you need to opt out of certain components or change the
12772 Find behavior for a particular module (perhaps because the default
12773 FindOpenGL.cmake module doesn’t work with your system as an example).
12774 If you want to use a more convenient module that includes everything,
12775 use the FindOpenSceneGraph.cmake instead of the Findosg*.cmake modules.
12776 Locate Producer This module defines PRODUCER_LIBRARY PRODUCER_FOUND, if
12778 false, do not try to link to Producer PRODUCER_INCLUDE_DIR, where to
12779 find the headers
12780 $PRODUCER_DIR is an environment variable that would correspond to the
12782 Created by Eric Wing.
12784 FindProtobuf
12786 Locate and configure the Google Protocol Buffers library.
12787 The following variables can be set and are optional:
12789 Protobuf_SRC_ROOT_FOLDER
12791 When compiling with MSVC, if this cache variable is set the pro‐
12792 tobuf-default VS project build locations (vsprojects/Debug and
12793 vsprojects/Release or vsprojects/x64/Debug and vspro‐
12794 jects/x64/Release) will be searched for libraries and binaries.
12795 Protobuf_IMPORT_DIRS
12797 List of additional directories to be searched for imported
12798 .proto files.
12799 Protobuf_DEBUG
12801 Show debug messages.
12802 Protobuf_USE_STATIC_LIBS
12804 Set to ON to force the use of the static libraries. Default is
12805 OFF.
12806 Defines the following variables:
12808 Protobuf_FOUND
12810 Found the Google Protocol Buffers library (libprotobuf & header
12811 files)
12812 Protobuf_VERSION
12814 Version of package found.
12815 Protobuf_INCLUDE_DIRS
12817 Include directories for Google Protocol Buffers
12818 Protobuf_LIBRARIES
12820 The protobuf libraries
12821 Protobuf_PROTOC_LIBRARIES
12823 The protoc libraries
12824 Protobuf_LITE_LIBRARIES
12826 The protobuf-lite libraries
12827 The following IMPORTED targets are also defined:
12829 protobuf::libprotobuf
12831 The protobuf library.
12832 protobuf::libprotobuf-lite
12834 The protobuf lite library.
12835 protobuf::libprotoc
12837 The protoc library.
12838 protobuf::protoc
12840 The protoc compiler.
12841 The following cache variables are also available to set or use:
12843 Protobuf_LIBRARY
12845 The protobuf library
12846 Protobuf_PROTOC_LIBRARY
12848 The protoc library
12849 Protobuf_INCLUDE_DIR
12851 The include directory for protocol buffers
12852 Protobuf_PROTOC_EXECUTABLE
12854 The protoc compiler
12855 Protobuf_LIBRARY_DEBUG
12857 The protobuf library (debug)
12858 Protobuf_PROTOC_LIBRARY_DEBUG
12860 The protoc library (debug)
12861 Protobuf_LITE_LIBRARY
12863 The protobuf lite library
12864 Protobuf_LITE_LIBRARY_DEBUG
12866 The protobuf lite library (debug)
12867 Example:
12869 find_package(Protobuf REQUIRED)
12871 include_directories(${Protobuf_INCLUDE_DIRS})
12872 include_directories(${CMAKE_CURRENT_BINARY_DIR})
12873 protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS foo.proto)
12874 protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS EXPORT_MACRO DLL_EXPORT foo.proto)
12875 protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS DESCRIPTORS PROTO_DESCS foo.proto)
12876 protobuf_generate_python(PROTO_PY foo.proto)
12877 add_executable(bar bar.cc ${PROTO_SRCS} ${PROTO_HDRS})
12878 target_link_libraries(bar ${Protobuf_LIBRARIES})
12879 NOTE:
12881 The protobuf_generate_cpp and protobuf_generate_python functions and
12882 add_executable() or add_library() calls only work properly within
12883 the same directory.
12884 protobuf_generate_cpp
12886 Add custom commands to process .proto files to C++:
12887 protobuf_generate_cpp (<SRCS> <HDRS>
12889 [DESCRIPTORS <DESC>] [EXPORT_MACRO <MACRO>] [<ARGN>...])
12890 SRCS Variable to define with autogenerated source files
12892 HDRS Variable to define with autogenerated header files
12894 DESCRIPTORS
12896 Variable to define with autogenerated descriptor files,
12897 if requested.
12898 EXPORT_MACRO
12900 is a macro which should expand to __declspec(dllexport)
12901 or __declspec(dllimport) depending on what is being com‐
12902 piled.
12903 ARGN .proto files
12905 protobuf_generate_python
12907 Add custom commands to process .proto files to Python:
12908 protobuf_generate_python (<PY> [<ARGN>...])
12910 PY Variable to define with autogenerated Python files
12912 ARGN .proto filess
12914 FindPythonInterp
12916 Find python interpreter
12917 This module finds if Python interpreter is installed and determines
12919 where the executables are. This code sets the following variables:
12920 PYTHONINTERP_FOUND - Was the Python executable found
12922 PYTHON_EXECUTABLE - path to the Python interpreter
12923 PYTHON_VERSION_STRING - Python version found e.g. 2.5.2
12925 PYTHON_VERSION_MAJOR - Python major version found e.g. 2
12926 PYTHON_VERSION_MINOR - Python minor version found e.g. 5
12927 PYTHON_VERSION_PATCH - Python patch version found e.g. 2
12928 The Python_ADDITIONAL_VERSIONS variable can be used to specify a list
12930 of version numbers that should be taken into account when searching for
12931 Python. You need to set this variable before calling find_pack‐
12932 age(PythonInterp).
12933 If calling both find_package(PythonInterp) and find_package(Python‐
12935 Libs), call find_package(PythonInterp) first to get the currently
12936 active Python version by default with a consistent version of
12937 PYTHON_LIBRARIES.
12938 FindPythonLibs
12940 Find python libraries
12941 This module finds if Python is installed and determines where the
12943 include files and libraries are. It also determines what the name of
12944 the library is. This code sets the following variables:
12945 PYTHONLIBS_FOUND - have the Python libs been found
12947 PYTHON_LIBRARIES - path to the python library
12948 PYTHON_INCLUDE_PATH - path to where Python.h is found (deprecated)
12949 PYTHON_INCLUDE_DIRS - path to where Python.h is found
12950 PYTHON_DEBUG_LIBRARIES - path to the debug library (deprecated)
12951 PYTHONLIBS_VERSION_STRING - version of the Python libs found (since CMake 2.8.8)
12952 The Python_ADDITIONAL_VERSIONS variable can be used to specify a list
12954 of version numbers that should be taken into account when searching for
12955 Python. You need to set this variable before calling find_pack‐
12956 age(PythonLibs).
12957 If you’d like to specify the installation of Python to use, you should
12959 modify the following cache variables:
12960 PYTHON_LIBRARY - path to the python library
12962 PYTHON_INCLUDE_DIR - path to where Python.h is found
12963 If calling both find_package(PythonInterp) and find_package(Python‐
12965 Libs), call find_package(PythonInterp) first to get the currently
12966 active Python version by default with a consistent version of
12967 PYTHON_LIBRARIES.
12968 FindQt3
12970 Locate Qt include paths and libraries
12971 This module defines:
12973 QT_INCLUDE_DIR - where to find qt.h, etc.
12975 QT_LIBRARIES - the libraries to link against to use Qt.
12976 QT_DEFINITIONS - definitions to use when
12977 compiling code that uses Qt.
12978 QT_FOUND - If false, don't try to use Qt.
12979 QT_VERSION_STRING - the version of Qt found
12980 If you need the multithreaded version of Qt, set QT_MT_REQUIRED to TRUE
12982 Also defined, but not for general use are:
12984 QT_MOC_EXECUTABLE, where to find the moc tool.
12986 QT_UIC_EXECUTABLE, where to find the uic tool.
12987 QT_QT_LIBRARY, where to find the Qt library.
12988 QT_QTMAIN_LIBRARY, where to find the qtmain
12989 library. This is only required by Qt3 on Windows.
12990 FindQt4
12992 Finding and Using Qt4
12993 This module can be used to find Qt4. The most important issue is that
12994 the Qt4 qmake is available via the system path. This qmake is then
12995 used to detect basically everything else. This module defines a number
12996 of IMPORTED targets, macros and variables.
12997 Typical usage could be something like:
12999 set(CMAKE_AUTOMOC ON)
13001 set(CMAKE_INCLUDE_CURRENT_DIR ON)
13002 find_package(Qt4 4.4.3 REQUIRED QtGui QtXml)
13003 add_executable(myexe main.cpp)
13004 target_link_libraries(myexe Qt4::QtGui Qt4::QtXml)
13005 NOTE:
13007 When using IMPORTED targets, the qtmain.lib static library is auto‐
13008 matically linked on Windows for WIN32 executables. To disable that
13009 globally, set the QT4_NO_LINK_QTMAIN variable before finding Qt4. To
13010 disable that for a particular executable, set the QT4_NO_LINK_QTMAIN
13011 target property to TRUE on the executable.
13012 Qt Build Tools
13014 Qt relies on some bundled tools for code generation, such as moc for
13015 meta-object code generation,``uic`` for widget layout and population,
13016 and rcc for virtual filesystem content generation. These tools may be
13017 automatically invoked by cmake(1) if the appropriate conditions are
13018 met. See cmake-qt(7) for more.
13019 Qt Macros
13021 In some cases it can be necessary or useful to invoke the Qt build
13022 tools in a more-manual way. Several macros are available to add targets
13023 for such uses.
13024 macro QT4_WRAP_CPP(outfiles inputfile ... [TARGET tgt] OPTIONS ...)
13026 create moc code from a list of files containing Qt class with
13027 the Q_OBJECT declaration. Per-directory preprocessor definitions
13028 are also added. If the <tgt> is specified, the
13029 INTERFACE_INCLUDE_DIRECTORIES and INTERFACE_COMPILE_DEFINITIONS from
13030 the <tgt> are passed to moc. Options may be given to moc, such as
13031 those found when executing "moc -help".
13032 macro QT4_WRAP_UI(outfiles inputfile ... OPTIONS ...)
13034 create code from a list of Qt designer ui files.
13035 Options may be given to uic, such as those found
13036 when executing "uic -help"
13037 macro QT4_ADD_RESOURCES(outfiles inputfile ... OPTIONS ...)
13039 create code from a list of Qt resource files.
13040 Options may be given to rcc, such as those found
13041 when executing "rcc -help"
13042 macro QT4_GENERATE_MOC(inputfile outputfile [TARGET tgt])
13044 creates a rule to run moc on infile and create outfile.
13045 Use this if for some reason QT4_WRAP_CPP() isn't appropriate, e.g.
13046 because you need a custom filename for the moc file or something
13047 similar. If the <tgt> is specified, the
13048 INTERFACE_INCLUDE_DIRECTORIES and INTERFACE_COMPILE_DEFINITIONS from
13049 the <tgt> are passed to moc.
13050 macro QT4_ADD_DBUS_INTERFACE(outfiles interface basename)
13052 Create the interface header and implementation files with the
13053 given basename from the given interface xml file and add it to
13054 the list of sources.
13055 You can pass additional parameters to the qdbusxml2cpp call by setting
13057 properties on the input file:
13058 INCLUDE the given file will be included in the generate interface header
13060 CLASSNAME the generated class is named accordingly
13062 NO_NAMESPACE the generated class is not wrapped in a namespace
13064 macro QT4_ADD_DBUS_INTERFACES(outfiles inputfile ... )
13066 Create the interface header and implementation files
13067 for all listed interface xml files.
13068 The basename will be automatically determined from the name
13069 of the xml file.
13070 The source file properties described for
13072 QT4_ADD_DBUS_INTERFACE also apply here.
13073 macro QT4_ADD_DBUS_ADAPTOR(outfiles xmlfile parentheader parentclassname
13075 [basename] [classname])
13076 create a dbus adaptor (header and implementation file) from the xml file
13077 describing the interface, and add it to the list of sources. The adaptor
13078 forwards the calls to a parent class, defined in parentheader and named
13079 parentclassname. The name of the generated files will be
13080 <basename>adaptor.{cpp,h} where basename defaults to the basename of the
13081 xml file.
13082 If <classname> is provided, then it will be used as the classname of the
13083 adaptor itself.
13084 macro QT4_GENERATE_DBUS_INTERFACE( header [interfacename] OPTIONS ...)
13086 generate the xml interface file from the given header.
13087 If the optional argument interfacename is omitted, the name of the
13088 interface file is constructed from the basename of the header with
13089 the suffix .xml appended.
13090 Options may be given to qdbuscpp2xml, such as those found when
13091 executing "qdbuscpp2xml --help"
13092 macro QT4_CREATE_TRANSLATION( qm_files directories ... sources ...
13094 ts_files ... OPTIONS ...)
13095 out: qm_files
13096 in: directories sources ts_files
13097 options: flags to pass to lupdate, such as -extensions to specify
13098 extensions for a directory scan.
13099 generates commands to create .ts (vie lupdate) and .qm
13100 (via lrelease) - files from directories and/or sources. The ts files are
13101 created and/or updated in the source tree (unless given with full paths).
13102 The qm files are generated in the build tree.
13103 Updating the translations can be done by adding the qm_files
13104 to the source list of your library/executable, so they are
13105 always updated, or by adding a custom target to control when
13106 they get updated/generated.
13107 macro QT4_ADD_TRANSLATION( qm_files ts_files ... )
13109 out: qm_files
13110 in: ts_files
13111 generates commands to create .qm from .ts - files. The generated
13112 filenames can be found in qm_files. The ts_files
13113 must exist and are not updated in any way.
13114 macro QT4_AUTOMOC(sourcefile1 sourcefile2 ... [TARGET tgt])
13116 The qt4_automoc macro is obsolete. Use the CMAKE_AUTOMOC feature instead.
13117 This macro is still experimental.
13118 It can be used to have moc automatically handled.
13119 So if you have the files foo.h and foo.cpp, and in foo.h a
13120 a class uses the Q_OBJECT macro, moc has to run on it. If you don't
13121 want to use QT4_WRAP_CPP() (which is reliable and mature), you can insert
13122 #include "foo.moc"
13123 in foo.cpp and then give foo.cpp as argument to QT4_AUTOMOC(). This will
13124 scan all listed files at cmake-time for such included moc files and if it
13125 finds them cause a rule to be generated to run moc at build time on the
13126 accompanying header file foo.h.
13127 If a source file has the SKIP_AUTOMOC property set it will be ignored by
13128 this macro.
13129 If the <tgt> is specified, the INTERFACE_INCLUDE_DIRECTORIES and
13130 INTERFACE_COMPILE_DEFINITIONS from the <tgt> are passed to moc.
13131 function QT4_USE_MODULES( target [link_type] modules...)
13133 This function is obsolete. Use target_link_libraries with IMPORTED targets
13134 instead.
13135 Make <target> use the <modules> from Qt. Using a Qt module means
13136 to link to the library, add the relevant include directories for the
13137 module, and add the relevant compiler defines for using the module.
13138 Modules are roughly equivalent to components of Qt4, so usage would be
13139 something like:
13140 qt4_use_modules(myexe Core Gui Declarative)
13141 to use QtCore, QtGui and QtDeclarative. The optional <link_type> argument
13142 can be specified as either LINK_PUBLIC or LINK_PRIVATE to specify the
13143 same argument to the target_link_libraries call.
13144 IMPORTED Targets
13146 A particular Qt library may be used by using the corresponding IMPORTED
13147 target with the target_link_libraries() command:
13148 target_link_libraries(myexe Qt4::QtGui Qt4::QtXml)
13150 Using a target in this way causes :cmake(1)` to use the appropriate
13152 include directories and compile definitions for the target when compil‐
13153 ing myexe.
13154 Targets are aware of their dependencies, so for example it is not nec‐
13156 essary to list Qt4::QtCore if another Qt library is listed, and it is
13157 not necessary to list Qt4::QtGui if Qt4::QtDeclarative is listed. Tar‐
13158 gets may be tested for existence in the usual way with the if(TARGET)
13159 command.
13160 The Qt toolkit may contain both debug and release libraries. cmake(1)
13162 will choose the appropriate version based on the build configuration.
13163 Qt4::QtCore
13165 The QtCore target
13166 Qt4::QtGui
13168 The QtGui target
13169 Qt4::Qt3Support
13171 The Qt3Support target
13172 Qt4::QtAssistant
13174 The QtAssistant target
13175 Qt4::QtAssistantClient
13177 The QtAssistantClient target
13178 Qt4::QAxContainer
13180 The QAxContainer target (Windows only)
13181 Qt4::QAxServer
13183 The QAxServer target (Windows only)
13184 Qt4::QtDBus
13186 The QtDBus target
13187 Qt4::QtDeclarative
13189 The QtDeclarative target
13190 Qt4::QtDesigner
13192 The QtDesigner target
13193 Qt4::QtDesignerComponents
13195 The QtDesignerComponents target
13196 Qt4::QtHelp
13198 The QtHelp target
13199 Qt4::QtMotif
13201 The QtMotif target
13202 Qt4::QtMultimedia
13204 The QtMultimedia target
13205 Qt4::QtNetwork
13207 The QtNetwork target
13208 Qt4::QtNsPLugin
13210 The QtNsPLugin target
13211 Qt4::QtOpenGL
13213 The QtOpenGL target
13214 Qt4::QtScript
13216 The QtScript target
13217 Qt4::QtScriptTools
13219 The QtScriptTools target
13220 Qt4::QtSql
13222 The QtSql target
13223 Qt4::QtSvg
13225 The QtSvg target
13226 Qt4::QtTest
13228 The QtTest target
13229 Qt4::QtUiTools
13231 The QtUiTools target
13232 Qt4::QtWebKit
13234 The QtWebKit target
13235 Qt4::QtXml
13237 The QtXml target
13238 Qt4::QtXmlPatterns
13240 The QtXmlPatterns target
13241 Qt4::phonon
13243 The phonon target
13244 Result Variables
13246 Below is a detailed list of variables that FindQt4.cmake sets.
13247 Qt4_FOUND
13249 If false, don’t try to use Qt 4.
13250 QT_FOUND
13252 If false, don’t try to use Qt. This variable is for compatibil‐
13253 ity only.
13254 QT4_FOUND
13256 If false, don’t try to use Qt 4. This variable is for compati‐
13257 bility only.
13258 QT_VERSION_MAJOR
13260 The major version of Qt found.
13261 QT_VERSION_MINOR
13263 The minor version of Qt found.
13264 QT_VERSION_PATCH
13266 The patch version of Qt found.
13267 FindQt
13269 Searches for all installed versions of Qt.
13270 This should only be used if your project can work with multiple ver‐
13272 sions of Qt. If not, you should just directly use FindQt4 or FindQt3.
13273 If multiple versions of Qt are found on the machine, then The user must
13274 set the option DESIRED_QT_VERSION to the version they want to use. If
13275 only one version of qt is found on the machine, then the
13276 DESIRED_QT_VERSION is set to that version and the matching FindQt3 or
13277 FindQt4 module is included. Once the user sets DESIRED_QT_VERSION,
13278 then the FindQt3 or FindQt4 module is included.
13279 This module can only detect and switch between Qt versions 3 and 4. It
13281 cannot handle Qt5 or any later versions.
13282 QT_REQUIRED if this is set to TRUE then if CMake can
13284 not find Qt4 or Qt3 an error is raised
13285 and a message is sent to the user.
13286 DESIRED_QT_VERSION OPTION is created
13288 QT4_INSTALLED is set to TRUE if qt4 is found.
13289 QT3_INSTALLED is set to TRUE if qt3 is found.
13290 FindQuickTime
13292 Locate QuickTime This module defines QUICKTIME_LIBRARY QUICKTIME_FOUND,
13293 if false, do not try to link to gdal QUICKTIME_INCLUDE_DIR, where to
13294 find the headers
13295 $QUICKTIME_DIR is an environment variable that would correspond to the
13297 Created by Eric Wing.
13299 FindRTI
13301 Try to find M&S HLA RTI libraries
13302 This module finds if any HLA RTI is installed and locates the standard
13304 RTI include files and libraries.
13305 RTI is a simulation infrastructure standardized by IEEE and SISO. It
13307 has a well defined C++ API that assures that simulation applications
13308 are independent on a particular RTI implementation.
13309 http://en.wikipedia.org/wiki/Run-Time_Infrastructure_(simulation)
13311 This code sets the following variables:
13313 RTI_INCLUDE_DIR = the directory where RTI includes file are found
13315 RTI_LIBRARIES = The libraries to link against to use RTI
13316 RTI_DEFINITIONS = -DRTI_USES_STD_FSTREAM
13317 RTI_FOUND = Set to FALSE if any HLA RTI was not found
13318 Report problems to <certi-devel@nongnu.org>
13320 FindRuby
13322 Find Ruby
13323 This module finds if Ruby is installed and determines where the include
13325 files and libraries are. Ruby 1.8, 1.9, 2.0 and 2.1 are supported.
13326 The minimum required version of Ruby can be specified using the stan‐
13328 dard syntax, e.g. find_package(Ruby 1.8)
13329 It also determines what the name of the library is. This code sets the
13331 following variables:
13332 RUBY_EXECUTABLE
13334 full path to the ruby binary
13335 RUBY_INCLUDE_DIRS
13337 include dirs to be used when using the ruby library
13338 RUBY_LIBRARY
13340 full path to the ruby library
13341 RUBY_VERSION
13343 the version of ruby which was found, e.g. “1.8.7”
13344 RUBY_FOUND
13346 set to true if ruby ws found successfully
13347 Also:
13349 RUBY_INCLUDE_PATH
13351 same as RUBY_INCLUDE_DIRS, only provided for compatibility rea‐
13352 sons, don’t use it
13353 FindSDL_image
13355 Locate SDL_image library
13356 This module defines:
13358 SDL_IMAGE_LIBRARIES, the name of the library to link against
13360 SDL_IMAGE_INCLUDE_DIRS, where to find the headers
13361 SDL_IMAGE_FOUND, if false, do not try to link against
13362 SDL_IMAGE_VERSION_STRING - human-readable string containing the
13363 version of SDL_image
13364 For backward compatibility the following variables are also set:
13366 SDLIMAGE_LIBRARY (same value as SDL_IMAGE_LIBRARIES)
13368 SDLIMAGE_INCLUDE_DIR (same value as SDL_IMAGE_INCLUDE_DIRS)
13369 SDLIMAGE_FOUND (same value as SDL_IMAGE_FOUND)
13370 $SDLDIR is an environment variable that would correspond to the
13372 Created by Eric Wing. This was influenced by the FindSDL.cmake module,
13374 but with modifications to recognize OS X frameworks and additional Unix
13375 paths (FreeBSD, etc).
13376 FindSDL_mixer
13378 Locate SDL_mixer library
13379 This module defines:
13381 SDL_MIXER_LIBRARIES, the name of the library to link against
13383 SDL_MIXER_INCLUDE_DIRS, where to find the headers
13384 SDL_MIXER_FOUND, if false, do not try to link against
13385 SDL_MIXER_VERSION_STRING - human-readable string containing the
13386 version of SDL_mixer
13387 For backward compatibility the following variables are also set:
13389 SDLMIXER_LIBRARY (same value as SDL_MIXER_LIBRARIES)
13391 SDLMIXER_INCLUDE_DIR (same value as SDL_MIXER_INCLUDE_DIRS)
13392 SDLMIXER_FOUND (same value as SDL_MIXER_FOUND)
13393 $SDLDIR is an environment variable that would correspond to the
13395 Created by Eric Wing. This was influenced by the FindSDL.cmake module,
13397 but with modifications to recognize OS X frameworks and additional Unix
13398 paths (FreeBSD, etc).
13399 FindSDL_net
13401 Locate SDL_net library
13402 This module defines:
13404 SDL_NET_LIBRARIES, the name of the library to link against
13406 SDL_NET_INCLUDE_DIRS, where to find the headers
13407 SDL_NET_FOUND, if false, do not try to link against
13408 SDL_NET_VERSION_STRING - human-readable string containing the version of SDL_net
13409 For backward compatibility the following variables are also set:
13411 SDLNET_LIBRARY (same value as SDL_NET_LIBRARIES)
13413 SDLNET_INCLUDE_DIR (same value as SDL_NET_INCLUDE_DIRS)
13414 SDLNET_FOUND (same value as SDL_NET_FOUND)
13415 $SDLDIR is an environment variable that would correspond to the
13417 Created by Eric Wing. This was influenced by the FindSDL.cmake module,
13419 but with modifications to recognize OS X frameworks and additional Unix
13420 paths (FreeBSD, etc).
13421 FindSDL
13423 Locate SDL library
13424 This module defines
13426 SDL_LIBRARY, the name of the library to link against
13428 SDL_FOUND, if false, do not try to link to SDL
13429 SDL_INCLUDE_DIR, where to find SDL.h
13430 SDL_VERSION_STRING, human-readable string containing the version of SDL
13431 This module responds to the flag:
13433 SDL_BUILDING_LIBRARY
13435 If this is defined, then no SDL_main will be linked in because
13436 only applications need main().
13437 Otherwise, it is assumed you are building an application and this
13438 module will attempt to locate and set the proper link flags
13439 as part of the returned SDL_LIBRARY variable.
13440 Don’t forget to include SDLmain.h and SDLmain.m your project for the OS
13442 X framework based version. (Other versions link to -lSDLmain which
13443 this module will try to find on your behalf.) Also for OS X, this mod‐
13444 ule will automatically add the -framework Cocoa on your behalf.
13445 Additional Note: If you see an empty SDL_LIBRARY_TEMP in your configu‐
13447 ration and no SDL_LIBRARY, it means CMake did not find your SDL library
13448 (SDL.dll, libsdl.so, SDL.framework, etc). Set SDL_LIBRARY_TEMP to
13449 point to your SDL library, and configure again. Similarly, if you see
13450 an empty SDLMAIN_LIBRARY, you should set this value as appropriate.
13451 These values are used to generate the final SDL_LIBRARY variable, but
13452 when these values are unset, SDL_LIBRARY does not get created.
13453 $SDLDIR is an environment variable that would correspond to the
13455 Modified by Eric Wing. Added code to assist with automated building by
13457 using environmental variables and providing a more controlled/consis‐
13458 tent search behavior. Added new modifications to recognize OS X frame‐
13459 works and additional Unix paths (FreeBSD, etc). Also corrected the
13460 header search path to follow “proper” SDL guidelines. Added a search
13461 for SDLmain which is needed by some platforms. Added a search for
13462 threads which is needed by some platforms. Added needed compile
13463 switches for MinGW.
13464 On OSX, this will prefer the Framework version (if found) over others.
13466 People will have to manually change the cache values of SDL_LIBRARY to
13467 override this selection or set the CMake environment CMAKE_INCLUDE_PATH
13468 to modify the search paths.
13469 Note that the header path has changed from SDL/SDL.h to just SDL.h This
13471 needed to change because “proper” SDL convention is #include “SDL.h”,
13472 not <SDL/SDL.h>. This is done for portability reasons because not all
13473 systems place things in SDL/ (see FreeBSD).
13474 FindSDL_sound
13476 Locates the SDL_sound library
13477 This module depends on SDL being found and must be called AFTER Find‐
13479 SDL.cmake is called.
13480 This module defines
13482 SDL_SOUND_INCLUDE_DIR, where to find SDL_sound.h
13484 SDL_SOUND_FOUND, if false, do not try to link to SDL_sound
13485 SDL_SOUND_LIBRARIES, this contains the list of libraries that you need
13486 to link against.
13487 SDL_SOUND_EXTRAS, this is an optional variable for you to add your own
13488 flags to SDL_SOUND_LIBRARIES. This is prepended to SDL_SOUND_LIBRARIES.
13489 This is available mostly for cases this module failed to anticipate for
13490 and you must add additional flags. This is marked as ADVANCED.
13491 SDL_SOUND_VERSION_STRING, human-readable string containing the
13492 version of SDL_sound
13493 This module also defines (but you shouldn’t need to use directly)
13495 SDL_SOUND_LIBRARY, the name of just the SDL_sound library you would link
13497 against. Use SDL_SOUND_LIBRARIES for you link instructions and not this one.
13498 And might define the following as needed
13500 MIKMOD_LIBRARY
13502 MODPLUG_LIBRARY
13503 OGG_LIBRARY
13504 VORBIS_LIBRARY
13505 SMPEG_LIBRARY
13506 FLAC_LIBRARY
13507 SPEEX_LIBRARY
13508 Typically, you should not use these variables directly, and you should
13510 use SDL_SOUND_LIBRARIES which contains SDL_SOUND_LIBRARY and the other
13511 audio libraries (if needed) to successfully compile on your system.
13512 Created by Eric Wing. This module is a bit more complicated than the
13514 other FindSDL* family modules. The reason is that SDL_sound can be
13515 compiled in a large variety of different ways which are independent of
13516 platform. SDL_sound may dynamically link against other 3rd party
13517 libraries to get additional codec support, such as Ogg Vorbis, SMPEG,
13518 ModPlug, MikMod, FLAC, Speex, and potentially others. Under some cir‐
13519 cumstances which I don’t fully understand, there seems to be a require‐
13520 ment that dependent libraries of libraries you use must also be explic‐
13521 itly linked against in order to successfully compile. SDL_sound does
13522 not currently have any system in place to know how it was compiled. So
13523 this CMake module does the hard work in trying to discover which 3rd
13524 party libraries are required for building (if any). This module uses a
13525 brute force approach to create a test program that uses SDL_sound, and
13526 then tries to build it. If the build fails, it parses the error output
13527 for known symbol names to figure out which libraries are needed.
13528 Responds to the $SDLDIR and $SDLSOUNDDIR environmental variable that
13530 would correspond to the ./configure –prefix=$SDLDIR used in building
13531 SDL.
13532 On OSX, this will prefer the Framework version (if found) over others.
13534 People will have to manually change the cache values of SDL_LIBRARY to
13535 override this selectionor set the CMake environment CMAKE_INCLUDE_PATH
13536 to modify the search paths.
13537 FindSDL_ttf
13539 Locate SDL_ttf library
13540 This module defines:
13542 SDL_TTF_LIBRARIES, the name of the library to link against
13544 SDL_TTF_INCLUDE_DIRS, where to find the headers
13545 SDL_TTF_FOUND, if false, do not try to link against
13546 SDL_TTF_VERSION_STRING - human-readable string containing the version of SDL_ttf
13547 For backward compatibility the following variables are also set:
13549 SDLTTF_LIBRARY (same value as SDL_TTF_LIBRARIES)
13551 SDLTTF_INCLUDE_DIR (same value as SDL_TTF_INCLUDE_DIRS)
13552 SDLTTF_FOUND (same value as SDL_TTF_FOUND)
13553 $SDLDIR is an environment variable that would correspond to the
13555 Created by Eric Wing. This was influenced by the FindSDL.cmake module,
13557 but with modifications to recognize OS X frameworks and additional Unix
13558 paths (FreeBSD, etc).
13559 FindSelfPackers
13561 Find upx
13562 This module looks for some executable packers (i.e. software that com‐
13564 press executables or shared libs into on-the-fly self-extracting exe‐
13565 cutables or shared libs. Examples:
13566 UPX: http://wildsau.idv.uni-linz.ac.at/mfx/upx.html
13568 FindSquish
13570 – Typical Use
13571 This module can be used to find Squish. Currently Squish versions 3
13573 and 4 are supported.
13574 SQUISH_FOUND If false, don't try to use Squish
13576 SQUISH_VERSION The full version of Squish found
13577 SQUISH_VERSION_MAJOR The major version of Squish found
13578 SQUISH_VERSION_MINOR The minor version of Squish found
13579 SQUISH_VERSION_PATCH The patch version of Squish found
13580 SQUISH_INSTALL_DIR The Squish installation directory
13582 (containing bin, lib, etc)
13583 SQUISH_SERVER_EXECUTABLE The squishserver executable
13584 SQUISH_CLIENT_EXECUTABLE The squishrunner executable
13585 SQUISH_INSTALL_DIR_FOUND Was the install directory found?
13587 SQUISH_SERVER_EXECUTABLE_FOUND Was the server executable found?
13588 SQUISH_CLIENT_EXECUTABLE_FOUND Was the client executable found?
13589 It provides the function squish_v4_add_test() for adding a squish test
13591 to cmake using Squish 4.x:
13592 squish_v4_add_test(cmakeTestName
13594 AUT targetName SUITE suiteName TEST squishTestName
13595 [SETTINGSGROUP group] [PRE_COMMAND command] [POST_COMMAND command] )
13596 The arguments have the following meaning:
13598 cmakeTestName
13600 this will be used as the first argument for add_test()
13601 AUT targetName
13603 the name of the cmake target which will be used as AUT, i.e. the
13604 executable which will be tested.
13605 SUITE suiteName
13607 this is either the full path to the squish suite, or just the
13608 last directory of the suite, i.e. the suite name. In this case
13609 the CMakeLists.txt which calls squish_add_test() must be located
13610 in the parent directory of the suite directory.
13611 TEST squishTestName
13613 the name of the squish test, i.e. the name of the subdirectory
13614 of the test inside the suite directory.
13615 SETTINGSGROUP group
13617 if specified, the given settings group will be used for execut‐
13618 ing the test. If not specified, the groupname will be
13619 “CTest_<username>”
13620 PRE_COMMAND command
13622 if specified, the given command will be executed before starting
13623 the squish test.
13624 POST_COMMAND command
13626 same as PRE_COMMAND, but after the squish test has been exe‐
13627 cuted.
13628 enable_testing()
13630 find_package(Squish 4.0)
13631 if (SQUISH_FOUND)
13632 squish_v4_add_test(myTestName
13633 AUT myApp
13634 SUITE ${CMAKE_SOURCE_DIR}/tests/mySuite
13635 TEST someSquishTest
13636 SETTINGSGROUP myGroup
13637 )
13638 endif ()
13639 For users of Squish version 3.x the macro squish_v3_add_test() is pro‐
13641 vided:
13642 squish_v3_add_test(testName applicationUnderTest testCase envVars testWrapper)
13644 Use this macro to add a test using Squish 3.x.
13645 enable_testing()
13647 find_package(Squish)
13648 if (SQUISH_FOUND)
13649 squish_v3_add_test(myTestName myApplication testCase envVars testWrapper)
13650 endif ()
13651 macro SQUISH_ADD_TEST(testName applicationUnderTest testCase envVars
13653 testWrapper)
13654 This is deprecated. Use SQUISH_V3_ADD_TEST() if you are using Squish 3.x instead.
13656 FindSubversion
13658 Extract information from a subversion working copy
13659 The module defines the following variables:
13661 Subversion_SVN_EXECUTABLE - path to svn command line client
13663 Subversion_VERSION_SVN - version of svn command line client
13664 Subversion_FOUND - true if the command line client was found
13665 SUBVERSION_FOUND - same as Subversion_FOUND, set for compatibility reasons
13666 The minimum required version of Subversion can be specified using the
13668 standard syntax, e.g. find_package(Subversion 1.4)
13669 If the command line client executable is found two macros are defined:
13671 Subversion_WC_INFO(<dir> <var-prefix>)
13673 Subversion_WC_LOG(<dir> <var-prefix>)
13674 Subversion_WC_INFO extracts information of a subversion working copy at
13676 a given location. This macro defines the following variables:
13677 <var-prefix>_WC_URL - url of the repository (at <dir>)
13679 <var-prefix>_WC_ROOT - root url of the repository
13680 <var-prefix>_WC_REVISION - current revision
13681 <var-prefix>_WC_LAST_CHANGED_AUTHOR - author of last commit
13682 <var-prefix>_WC_LAST_CHANGED_DATE - date of last commit
13683 <var-prefix>_WC_LAST_CHANGED_REV - revision of last commit
13684 <var-prefix>_WC_INFO - output of command `svn info <dir>'
13685 Subversion_WC_LOG retrieves the log message of the base revision of a
13687 subversion working copy at a given location. This macro defines the
13688 variable:
13689 <var-prefix>_LAST_CHANGED_LOG - last log of base revision
13691 Example usage:
13693 find_package(Subversion)
13695 if(SUBVERSION_FOUND)
13696 Subversion_WC_INFO(${PROJECT_SOURCE_DIR} Project)
13697 message("Current revision is ${Project_WC_REVISION}")
13698 Subversion_WC_LOG(${PROJECT_SOURCE_DIR} Project)
13699 message("Last changed log is ${Project_LAST_CHANGED_LOG}")
13700 endif()
13701 FindSWIG
13703 Find SWIG
13704 This module finds an installed SWIG. It sets the following variables:
13706 SWIG_FOUND - set to true if SWIG is found
13708 SWIG_DIR - the directory where swig is installed
13709 SWIG_EXECUTABLE - the path to the swig executable
13710 SWIG_VERSION - the version number of the swig executable
13711 The minimum required version of SWIG can be specified using the stan‐
13713 dard syntax, e.g. find_package(SWIG 1.1)
13714 All information is collected from the SWIG_EXECUTABLE so the version to
13716 be found can be changed from the command line by means of setting
13717 SWIG_EXECUTABLE
13718 FindTCL
13720 TK_INTERNAL_PATH was removed.
13721 This module finds if Tcl is installed and determines where the include
13723 files and libraries are. It also determines what the name of the
13724 library is. This code sets the following variables:
13725 TCL_FOUND = Tcl was found
13727 TK_FOUND = Tk was found
13728 TCLTK_FOUND = Tcl and Tk were found
13729 TCL_LIBRARY = path to Tcl library (tcl tcl80)
13730 TCL_INCLUDE_PATH = path to where tcl.h can be found
13731 TCL_TCLSH = path to tclsh binary (tcl tcl80)
13732 TK_LIBRARY = path to Tk library (tk tk80 etc)
13733 TK_INCLUDE_PATH = path to where tk.h can be found
13734 TK_WISH = full path to the wish executable
13735 In an effort to remove some clutter and clear up some issues for people
13737 who are not necessarily Tcl/Tk gurus/developers, some variables were
13738 moved or removed. Changes compared to CMake 2.4 are:
13739 => they were only useful for people writing Tcl/Tk extensions.
13741 => these libs are not packaged by default with Tcl/Tk distributions.
13742 Even when Tcl/Tk is built from source, several flavors of debug libs
13743 are created and there is no real reason to pick a single one
13744 specifically (say, amongst tcl84g, tcl84gs, or tcl84sgx).
13745 Let's leave that choice to the user by allowing him to assign
13746 TCL_LIBRARY to any Tcl library, debug or not.
13747 => this ended up being only a Win32 variable, and there is a lot of
13748 confusion regarding the location of this file in an installed Tcl/Tk
13749 tree anyway (see 8.5 for example). If you need the internal path at
13750 this point it is safer you ask directly where the *source* tree is
13751 and dig from there.
13752 FindTclsh
13754 Find tclsh
13755 This module finds if TCL is installed and determines where the include
13757 files and libraries are. It also determines what the name of the
13758 library is. This code sets the following variables:
13759 TCLSH_FOUND = TRUE if tclsh has been found
13761 TCL_TCLSH = the path to the tclsh executable
13762 In cygwin, look for the cygwin version first. Don’t look for it later
13764 to avoid finding the cygwin version on a Win32 build.
13765 FindTclStub
13767 TCL_STUB_LIBRARY_DEBUG and TK_STUB_LIBRARY_DEBUG were removed.
13768 This module finds Tcl stub libraries. It first finds Tcl include files
13770 and libraries by calling FindTCL.cmake. How to Use the Tcl Stubs
13771 Library:
13772 http://tcl.activestate.com/doc/howto/stubs.html
13774 Using Stub Libraries:
13776 http://safari.oreilly.com/0130385603/ch48lev1sec3
13778 This code sets the following variables:
13780 TCL_STUB_LIBRARY = path to Tcl stub library
13782 TK_STUB_LIBRARY = path to Tk stub library
13783 TTK_STUB_LIBRARY = path to ttk stub library
13784 In an effort to remove some clutter and clear up some issues for people
13786 who are not necessarily Tcl/Tk gurus/developers, some variables were
13787 moved or removed. Changes compared to CMake 2.4 are:
13788 => these libs are not packaged by default with Tcl/Tk distributions.
13790 Even when Tcl/Tk is built from source, several flavors of debug libs
13791 are created and there is no real reason to pick a single one
13792 specifically (say, amongst tclstub84g, tclstub84gs, or tclstub84sgx).
13793 Let's leave that choice to the user by allowing him to assign
13794 TCL_STUB_LIBRARY to any Tcl library, debug or not.
13795 FindThreads
13797 This module determines the thread library of the system.
13798 The following variables are set
13800 CMAKE_THREAD_LIBS_INIT - the thread library
13802 CMAKE_USE_SPROC_INIT - are we using sproc?
13803 CMAKE_USE_WIN32_THREADS_INIT - using WIN32 threads?
13804 CMAKE_USE_PTHREADS_INIT - are we using pthreads
13805 CMAKE_HP_PTHREADS_INIT - are we using hp pthreads
13806 The following import target is created
13808 Threads::Threads
13810 For systems with multiple thread libraries, caller can set
13812 CMAKE_THREAD_PREFER_PTHREAD
13814 If the use of the -pthread compiler and linker flag is preferred then
13816 the caller can set
13817 THREADS_PREFER_PTHREAD_FLAG
13819 Please note that the compiler flag can only be used with the imported
13821 target. Use of both the imported target as well as this switch is
13822 highly recommended for new code.
13823 FindTIFF
13825 Find the TIFF library (libtiff).
13826 Imported targets
13828 This module defines the following IMPORTED targets:
13829 TIFF::TIFF
13831 The TIFF library, if found.
13832 Result variables
13834 This module will set the following variables in your project:
13835 TIFF_FOUND
13837 true if the TIFF headers and libraries were found
13838 TIFF_INCLUDE_DIR
13840 the directory containing the TIFF headers
13841 TIFF_INCLUDE_DIRS
13843 the directory containing the TIFF headers
13844 TIFF_LIBRARIES
13846 TIFF libraries to be linked
13847 Cache variables
13849 The following cache variables may also be set:
13850 TIFF_INCLUDE_DIR
13852 the directory containing the TIFF headers
13853 TIFF_LIBRARY
13855 the path to the TIFF library
13856 FindUnixCommands
13858 Find Unix commands, including the ones from Cygwin
13859 This module looks for the Unix commands bash, cp, gzip, mv, rm, and tar
13861 and stores the result in the variables BASH, CP, GZIP, MV, RM, and TAR.
13862 FindVTK
13864 This module no longer exists.
13865 This module existed in versions of CMake prior to 3.1, but became only
13867 a thin wrapper around find_package(VTK NO_MODULE) to provide compati‐
13868 bility for projects using long-outdated conventions. Now find_pack‐
13869 age(VTK) will search for VTKConfig.cmake directly.
13870 FindVulkan
13872 Try to find Vulkan
13873 IMPORTED Targets
13875 This module defines IMPORTED target Vulkan::Vulkan, if Vulkan has been
13876 found.
13877 Result Variables
13879 This module defines the following variables:
13880 Vulkan_FOUND - True if Vulkan was found
13882 Vulkan_INCLUDE_DIRS - include directories for Vulkan
13883 Vulkan_LIBRARIES - link against this library to use Vulkan
13884 The module will also define two cache variables:
13886 Vulkan_INCLUDE_DIR - the Vulkan include directory
13888 Vulkan_LIBRARY - the path to the Vulkan library
13889 FindWget
13891 Find wget
13892 This module looks for wget. This module defines the following values:
13894 WGET_EXECUTABLE: the full path to the wget tool.
13896 WGET_FOUND: True if wget has been found.
13897 FindWish
13899 Find wish installation
13900 This module finds if TCL is installed and determines where the include
13902 files and libraries are. It also determines what the name of the
13903 library is. This code sets the following variables:
13904 TK_WISH = the path to the wish executable
13906 if UNIX is defined, then it will look for the cygwin version first
13908 FindwxWidgets
13910 Find a wxWidgets (a.k.a., wxWindows) installation.
13911 This module finds if wxWidgets is installed and selects a default con‐
13913 figuration to use. wxWidgets is a modular library. To specify the
13914 modules that you will use, you need to name them as components to the
13915 package:
13916 find_package(wxWidgets COMPONENTS core base …)
13918 There are two search branches: a windows style and a unix style. For
13920 windows, the following variables are searched for and set to defaults
13921 in case of multiple choices. Change them if the defaults are not
13922 desired (i.e., these are the only variables you should change to select
13923 a configuration):
13924 wxWidgets_ROOT_DIR - Base wxWidgets directory
13926 (e.g., C:/wxWidgets-2.6.3).
13927 wxWidgets_LIB_DIR - Path to wxWidgets libraries
13928 (e.g., C:/wxWidgets-2.6.3/lib/vc_lib).
13929 wxWidgets_CONFIGURATION - Configuration to use
13930 (e.g., msw, mswd, mswu, mswunivud, etc.)
13931 wxWidgets_EXCLUDE_COMMON_LIBRARIES
13932 - Set to TRUE to exclude linking of
13933 commonly required libs (e.g., png tiff
13934 jpeg zlib regex expat).
13935 For unix style it uses the wx-config utility. You can select between
13937 debug/release, unicode/ansi, universal/non-universal, and static/shared
13938 in the QtDialog or ccmake interfaces by turning ON/OFF the following
13939 variables:
13940 wxWidgets_USE_DEBUG
13942 wxWidgets_USE_UNICODE
13943 wxWidgets_USE_UNIVERSAL
13944 wxWidgets_USE_STATIC
13945 There is also a wxWidgets_CONFIG_OPTIONS variable for all other options
13947 that need to be passed to the wx-config utility. For example, to use
13948 the base toolkit found in the /usr/local path, set the variable (before
13949 calling the FIND_PACKAGE command) as such:
13950 set(wxWidgets_CONFIG_OPTIONS --toolkit=base --prefix=/usr)
13952 The following are set after the configuration is done for both windows
13954 and unix style:
13955 wxWidgets_FOUND - Set to TRUE if wxWidgets was found.
13957 wxWidgets_INCLUDE_DIRS - Include directories for WIN32
13958 i.e., where to find "wx/wx.h" and
13959 "wx/setup.h"; possibly empty for unices.
13960 wxWidgets_LIBRARIES - Path to the wxWidgets libraries.
13961 wxWidgets_LIBRARY_DIRS - compile time link dirs, useful for
13962 rpath on UNIX. Typically an empty string
13963 in WIN32 environment.
13964 wxWidgets_DEFINITIONS - Contains defines required to compile/link
13965 against WX, e.g. WXUSINGDLL
13966 wxWidgets_DEFINITIONS_DEBUG- Contains defines required to compile/link
13967 against WX debug builds, e.g. __WXDEBUG__
13968 wxWidgets_CXX_FLAGS - Include dirs and compiler flags for
13969 unices, empty on WIN32. Essentially
13970 "`wx-config --cxxflags`".
13971 wxWidgets_USE_FILE - Convenience include file.
13972 Sample usage:
13974 # Note that for MinGW users the order of libs is important!
13976 find_package(wxWidgets COMPONENTS net gl core base)
13977 if(wxWidgets_FOUND)
13978 include(${wxWidgets_USE_FILE})
13979 # and for each of your dependent executable/library targets:
13980 target_link_libraries(<YourTarget> ${wxWidgets_LIBRARIES})
13981 endif()
13982 If wxWidgets is required (i.e., not an optional part):
13984 find_package(wxWidgets REQUIRED net gl core base)
13986 include(${wxWidgets_USE_FILE})
13987 # and for each of your dependent executable/library targets:
13988 target_link_libraries(<YourTarget> ${wxWidgets_LIBRARIES})
13989 FindwxWindows
13991 Find wxWindows (wxWidgets) installation
13992 This module finds if wxWindows/wxWidgets is installed and determines
13994 where the include files and libraries are. It also determines what the
13995 name of the library is. Please note this file is DEPRECATED and
13996 replaced by FindwxWidgets.cmake. This code sets the following vari‐
13997 ables:
13998 WXWINDOWS_FOUND = system has WxWindows
14000 WXWINDOWS_LIBRARIES = path to the wxWindows libraries
14001 on Unix/Linux with additional
14002 linker flags from
14003 "wx-config --libs"
14004 CMAKE_WXWINDOWS_CXX_FLAGS = Compiler flags for wxWindows,
14005 essentially "`wx-config --cxxflags`"
14006 on Linux
14007 WXWINDOWS_INCLUDE_DIR = where to find "wx/wx.h" and "wx/setup.h"
14008 WXWINDOWS_LINK_DIRECTORIES = link directories, useful for rpath on
14009 Unix
14010 WXWINDOWS_DEFINITIONS = extra defines
14011 OPTIONS If you need OpenGL support please
14013 set(WXWINDOWS_USE_GL 1)
14015 in your CMakeLists.txt before you include this file.
14017 HAVE_ISYSTEM - true required to replace -I by -isystem on g++
14019 For convenience include Use_wxWindows.cmake in your project’s CMake‐
14021 Lists.txt using include(${CMAKE_CURRENT_LIST_DIR}/Use_wxWindows.cmake).
14022 USAGE
14024 set(WXWINDOWS_USE_GL 1)
14026 find_package(wxWindows)
14027 NOTES wxWidgets 2.6.x is supported for monolithic builds e.g. compiled
14029 in wx/build/msw dir as:
14030 nmake -f makefile.vc BUILD=debug SHARED=0 USE_OPENGL=1 MONOLITHIC=1
14032 DEPRECATED
14034 CMAKE_WX_CAN_COMPILE
14036 WXWINDOWS_LIBRARY
14037 CMAKE_WX_CXX_FLAGS
14038 WXWINDOWS_INCLUDE_PATH
14039 AUTHOR Jan Woetzel <http://www.mip.informatik.uni-kiel.de/~jw>
14041 (07/2003-01/2006)
14042 FindXCTest
14044 Functions to help creating and executing XCTest bundles.
14045 An XCTest bundle is a CFBundle with a special product-type and bundle
14047 extension. The Mac Developer Library provides more information in the
14048 Testing with Xcode document.
14049 Module Functions
14051 xctest_add_bundle
14052 The xctest_add_bundle function creates a XCTest bundle named
14053 <target> which will test the target <testee>. Supported target
14054 types for testee are Frameworks and App Bundles:
14055 xctest_add_bundle(
14057 <target> # Name of the XCTest bundle
14058 <testee> # Target name of the testee
14059 )
14060 xctest_add_test
14062 The xctest_add_test function adds an XCTest bundle to the
14063 project to be run by ctest(1). The test will be named <name> and
14064 tests <bundle>:
14065 xctest_add_test(
14067 <name> # Test name
14068 <bundle> # Target name of XCTest bundle
14069 )
14070 Module Variables
14072 The following variables are set by including this module:
14073 XCTest_FOUND
14075 True if the XCTest Framework and executable were found.
14076 XCTest_EXECUTABLE
14078 The path to the xctest command line tool used to execute XCTest
14079 bundles.
14080 XCTest_INCLUDE_DIRS
14082 The directory containing the XCTest Framework headers.
14083 XCTest_LIBRARIES
14085 The location of the XCTest Framework.
14086 FindXalanC
14088 Find the Apache Xalan-C++ XSL transform processor headers and
14089 libraries.
14090 Imported targets
14092 This module defines the following IMPORTED targets:
14093 XalanC::XalanC
14095 The Xalan-C++ xalan-c library, if found.
14096 Result variables
14098 This module will set the following variables in your project:
14099 XalanC_FOUND
14101 true if the Xalan headers and libraries were found
14102 XalanC_VERSION
14104 Xalan release version
14105 XalanC_INCLUDE_DIRS
14107 the directory containing the Xalan headers; note
14108 XercesC_INCLUDE_DIRS is also required
14109 XalanC_LIBRARIES
14111 Xalan libraries to be linked; note XercesC_LIBRARIES is also
14112 required
14113 Cache variables
14115 The following cache variables may also be set:
14116 XalanC_INCLUDE_DIR
14118 the directory containing the Xalan headers
14119 XalanC_LIBRARY
14121 the Xalan library
14122 FindXercesC
14124 Find the Apache Xerces-C++ validating XML parser headers and libraries.
14125 Imported targets
14127 This module defines the following IMPORTED targets:
14128 XercesC::XercesC
14130 The Xerces-C++ xerces-c library, if found.
14131 Result variables
14133 This module will set the following variables in your project:
14134 XercesC_FOUND
14136 true if the Xerces headers and libraries were found
14137 XercesC_VERSION
14139 Xerces release version
14140 XercesC_INCLUDE_DIRS
14142 the directory containing the Xerces headers
14143 XercesC_LIBRARIES
14145 Xerces libraries to be linked
14146 Cache variables
14148 The following cache variables may also be set:
14149 XercesC_INCLUDE_DIR
14151 the directory containing the Xerces headers
14152 XercesC_LIBRARY
14154 the Xerces library
14155 FindX11
14157 Find X11 installation
14158 Try to find X11 on UNIX systems. The following values are defined
14160 X11_FOUND - True if X11 is available
14162 X11_INCLUDE_DIR - include directories to use X11
14163 X11_LIBRARIES - link against these to use X11
14164 and also the following more fine grained variables:
14166 X11_ICE_INCLUDE_PATH, X11_ICE_LIB, X11_ICE_FOUND
14168 X11_SM_INCLUDE_PATH, X11_SM_LIB, X11_SM_FOUND
14169 X11_X11_INCLUDE_PATH, X11_X11_LIB
14170 X11_Xaccessrules_INCLUDE_PATH, X11_Xaccess_FOUND
14171 X11_Xaccessstr_INCLUDE_PATH, X11_Xaccess_FOUND
14172 X11_Xau_INCLUDE_PATH, X11_Xau_LIB, X11_Xau_FOUND
14173 X11_Xcomposite_INCLUDE_PATH, X11_Xcomposite_LIB, X11_Xcomposite_FOUND
14174 X11_Xcursor_INCLUDE_PATH, X11_Xcursor_LIB, X11_Xcursor_FOUND
14175 X11_Xdamage_INCLUDE_PATH, X11_Xdamage_LIB, X11_Xdamage_FOUND
14176 X11_Xdmcp_INCLUDE_PATH, X11_Xdmcp_LIB, X11_Xdmcp_FOUND
14177 X11_Xext_LIB, X11_Xext_FOUND
14178 X11_dpms_INCLUDE_PATH, (in X11_Xext_LIB), X11_dpms_FOUND
14179 X11_XShm_INCLUDE_PATH, (in X11_Xext_LIB), X11_XShm_FOUND
14180 X11_Xshape_INCLUDE_PATH, (in X11_Xext_LIB), X11_Xshape_FOUND
14181 X11_xf86misc_INCLUDE_PATH, X11_Xxf86misc_LIB, X11_xf86misc_FOUND
14182 X11_xf86vmode_INCLUDE_PATH, X11_Xxf86vm_LIB X11_xf86vmode_FOUND
14183 X11_Xfixes_INCLUDE_PATH, X11_Xfixes_LIB, X11_Xfixes_FOUND
14184 X11_Xft_INCLUDE_PATH, X11_Xft_LIB, X11_Xft_FOUND
14185 X11_Xi_INCLUDE_PATH, X11_Xi_LIB, X11_Xi_FOUND
14186 X11_Xinerama_INCLUDE_PATH, X11_Xinerama_LIB, X11_Xinerama_FOUND
14187 X11_Xinput_INCLUDE_PATH, X11_Xinput_LIB, X11_Xinput_FOUND
14188 X11_Xkb_INCLUDE_PATH, X11_Xkb_FOUND
14189 X11_Xkblib_INCLUDE_PATH, X11_Xkb_FOUND
14190 X11_Xkbfile_INCLUDE_PATH, X11_Xkbfile_LIB, X11_Xkbfile_FOUND
14191 X11_Xmu_INCLUDE_PATH, X11_Xmu_LIB, X11_Xmu_FOUND
14192 X11_Xpm_INCLUDE_PATH, X11_Xpm_LIB, X11_Xpm_FOUND
14193 X11_XTest_INCLUDE_PATH, X11_XTest_LIB, X11_XTest_FOUND
14194 X11_Xrandr_INCLUDE_PATH, X11_Xrandr_LIB, X11_Xrandr_FOUND
14195 X11_Xrender_INCLUDE_PATH, X11_Xrender_LIB, X11_Xrender_FOUND
14196 X11_Xscreensaver_INCLUDE_PATH, X11_Xscreensaver_LIB, X11_Xscreensaver_FOUND
14197 X11_Xt_INCLUDE_PATH, X11_Xt_LIB, X11_Xt_FOUND
14198 X11_Xutil_INCLUDE_PATH, X11_Xutil_FOUND
14199 X11_Xv_INCLUDE_PATH, X11_Xv_LIB, X11_Xv_FOUND
14200 X11_XSync_INCLUDE_PATH, (in X11_Xext_LIB), X11_XSync_FOUND
14201 FindXMLRPC
14203 Find xmlrpc
14204 Find the native XMLRPC headers and libraries.
14206 XMLRPC_INCLUDE_DIRS - where to find xmlrpc.h, etc.
14208 XMLRPC_LIBRARIES - List of libraries when using xmlrpc.
14209 XMLRPC_FOUND - True if xmlrpc found.
14210 XMLRPC modules may be specified as components for this find module.
14212 Modules may be listed by running “xmlrpc-c-config”. Modules include:
14213 c++ C++ wrapper code
14215 libwww-client libwww-based client
14216 cgi-server CGI-based server
14217 abyss-server ABYSS-based server
14218 Typical usage:
14220 find_package(XMLRPC REQUIRED libwww-client)
14222 FindZLIB
14224 Find the native ZLIB includes and library.
14225 IMPORTED Targets
14227 This module defines IMPORTED target ZLIB::ZLIB, if ZLIB has been found.
14228 Result Variables
14230 This module defines the following variables:
14231 ZLIB_INCLUDE_DIRS - where to find zlib.h, etc.
14233 ZLIB_LIBRARIES - List of libraries when using zlib.
14234 ZLIB_FOUND - True if zlib found.
14235 ZLIB_VERSION_STRING - The version of zlib found (x.y.z)
14237 ZLIB_VERSION_MAJOR - The major version of zlib
14238 ZLIB_VERSION_MINOR - The minor version of zlib
14239 ZLIB_VERSION_PATCH - The patch version of zlib
14240 ZLIB_VERSION_TWEAK - The tweak version of zlib
14241 Backward Compatibility
14243 The following variable are provided for backward compatibility
14244 ZLIB_MAJOR_VERSION - The major version of zlib
14246 ZLIB_MINOR_VERSION - The minor version of zlib
14247 ZLIB_PATCH_VERSION - The patch version of zlib
14248 Hints
14250 A user may set ZLIB_ROOT to a zlib installation root to tell this mod‐
14251 ule where to look.
14252 FortranCInterface
14254 Fortran/C Interface Detection
14255 This module automatically detects the API by which C and Fortran lan‐
14257 guages interact.
14258 Module Variables
14260 Variables that indicate if the mangling is found:
14261 FortranCInterface_GLOBAL_FOUND
14263 Global subroutines and functions.
14264 FortranCInterface_MODULE_FOUND
14266 Module subroutines and functions (declared by “MODULE PROCE‐
14267 DURE”).
14268 This module also provides the following variables to specify the
14270 detected mangling, though a typical use case does not need to reference
14271 them and can use the Module Functions below.
14272 FortranCInterface_GLOBAL_PREFIX
14274 Prefix for a global symbol without an underscore.
14275 FortranCInterface_GLOBAL_SUFFIX
14277 Suffix for a global symbol without an underscore.
14278 FortranCInterface_GLOBAL_CASE
14280 The case for a global symbol without an underscore, either UPPER
14281 or LOWER.
14282 FortranCInterface_GLOBAL__PREFIX
14284 Prefix for a global symbol with an underscore.
14285 FortranCInterface_GLOBAL__SUFFIX
14287 Suffix for a global symbol with an underscore.
14288 FortranCInterface_GLOBAL__CASE
14290 The case for a global symbol with an underscore, either UPPER or
14291 LOWER.
14292 FortranCInterface_MODULE_PREFIX
14294 Prefix for a module symbol without an underscore.
14295 FortranCInterface_MODULE_MIDDLE
14297 Middle of a module symbol without an underscore that appears
14298 between the name of the module and the name of the symbol.
14299 FortranCInterface_MODULE_SUFFIX
14301 Suffix for a module symbol without an underscore.
14302 FortranCInterface_MODULE_CASE
14304 The case for a module symbol without an underscore, either UPPER
14305 or LOWER.
14306 FortranCInterface_MODULE__PREFIX
14308 Prefix for a module symbol with an underscore.
14309 FortranCInterface_MODULE__MIDDLE
14311 Middle of a module symbol with an underscore that appears
14312 between the name of the module and the name of the symbol.
14313 FortranCInterface_MODULE__SUFFIX
14315 Suffix for a module symbol with an underscore.
14316 FortranCInterface_MODULE__CASE
14318 The case for a module symbol with an underscore, either UPPER or
14319 LOWER.
14320 Module Functions
14322 FortranCInterface_HEADER
14323 The FortranCInterface_HEADER function is provided to generate a
14324 C header file containing macros to mangle symbol names:
14325 FortranCInterface_HEADER(<file>
14327 [MACRO_NAMESPACE <macro-ns>]
14328 [SYMBOL_NAMESPACE <ns>]
14329 [SYMBOLS [<module>:]<function> ...])
14330 It generates in <file> definitions of the following macros:
14332 #define FortranCInterface_GLOBAL (name,NAME) ...
14334 #define FortranCInterface_GLOBAL_(name,NAME) ...
14335 #define FortranCInterface_MODULE (mod,name, MOD,NAME) ...
14336 #define FortranCInterface_MODULE_(mod,name, MOD,NAME) ...
14337 These macros mangle four categories of Fortran symbols, respec‐
14339 tively:
14340 · Global symbols without ‘_’: call mysub()
14342 · Global symbols with ‘_’ : call my_sub()
14344 · Module symbols without ‘_’: use mymod; call mysub()
14346 · Module symbols with ‘_’ : use mymod; call my_sub()
14348 If mangling for a category is not known, its macro is left unde‐
14350 fined. All macros require raw names in both lower case and
14351 upper case.
14352 The options are:
14354 MACRO_NAMESPACE
14356 Replace the default FortranCInterface_ prefix with a
14357 given namespace <macro-ns>.
14358 SYMBOLS
14360 List symbols to mangle automatically with C preprocessor
14361 definitions:
14362 <function> ==> #define <ns><function> ...
14364 <module>:<function> ==> #define <ns><module>_<function> ...
14365 If the mangling for some symbol is not known then no pre‐
14367 processor definition is created, and a warning is dis‐
14368 played.
14369 SYMBOL_NAMESPACE
14371 Prefix all preprocessor definitions generated by the SYM‐
14372 BOLS option with a given namespace <ns>.
14373 FortranCInterface_VERIFY
14375 The FortranCInterface_VERIFY function is provided to verify that
14376 the Fortran and C/C++ compilers work together:
14377 FortranCInterface_VERIFY([CXX] [QUIET])
14379 It tests whether a simple test executable using Fortran and C
14381 (and C++ when the CXX option is given) compiles and links suc‐
14382 cessfully. The result is stored in the cache entry FortranCIn‐
14383 terface_VERIFIED_C (or FortranCInterface_VERIFIED_CXX if CXX is
14384 given) as a boolean. If the check fails and QUIET is not given
14385 the function terminates with a fatal error message describing
14386 the problem. The purpose of this check is to stop a build early
14387 for incompatible compiler combinations. The test is built in
14388 the Release configuration.
14389 Example Usage
14391 include(FortranCInterface)
14392 FortranCInterface_HEADER(FC.h MACRO_NAMESPACE "FC_")
14393 This creates a “FC.h” header that defines mangling macros FC_GLOBAL(),
14395 FC_GLOBAL_(), FC_MODULE(), and FC_MODULE_().
14396 include(FortranCInterface)
14398 FortranCInterface_HEADER(FCMangle.h
14399 MACRO_NAMESPACE "FC_"
14400 SYMBOL_NAMESPACE "FC_"
14401 SYMBOLS mysub mymod:my_sub)
14402 This creates a “FCMangle.h” header that defines the same FC_*() man‐
14404 gling macros as the previous example plus preprocessor symbols FC_mysub
14405 and FC_mymod_my_sub.
14406 Additional Manglings
14408 FortranCInterface is aware of possible GLOBAL and MODULE manglings for
14409 many Fortran compilers, but it also provides an interface to specify
14410 new possible manglings. Set the variables:
14411 FortranCInterface_GLOBAL_SYMBOLS
14413 FortranCInterface_MODULE_SYMBOLS
14414 before including FortranCInterface to specify manglings of the symbols
14416 MySub, My_Sub, MyModule:MySub, and My_Module:My_Sub. For example, the
14417 code:
14418 set(FortranCInterface_GLOBAL_SYMBOLS mysub_ my_sub__ MYSUB_)
14420 # ^^^^^ ^^^^^^ ^^^^^
14421 set(FortranCInterface_MODULE_SYMBOLS
14422 __mymodule_MOD_mysub __my_module_MOD_my_sub)
14423 # ^^^^^^^^ ^^^^^ ^^^^^^^^^ ^^^^^^
14424 include(FortranCInterface)
14425 tells FortranCInterface to try given GLOBAL and MODULE manglings. (The
14427 carets point at raw symbol names for clarity in this example but are
14428 not needed.)
14429 GenerateExportHeader
14431 Function for generation of export macros for libraries
14432 This module provides the function GENERATE_EXPORT_HEADER().
14434 The GENERATE_EXPORT_HEADER function can be used to generate a file
14436 suitable for preprocessor inclusion which contains EXPORT macros to be
14437 used in library classes:
14438 GENERATE_EXPORT_HEADER( LIBRARY_TARGET
14440 [BASE_NAME <base_name>]
14441 [EXPORT_MACRO_NAME <export_macro_name>]
14442 [EXPORT_FILE_NAME <export_file_name>]
14443 [DEPRECATED_MACRO_NAME <deprecated_macro_name>]
14444 [NO_EXPORT_MACRO_NAME <no_export_macro_name>]
14445 [INCLUDE_GUARD_NAME <include_guard_name>]
14446 [STATIC_DEFINE <static_define>]
14447 [NO_DEPRECATED_MACRO_NAME <no_deprecated_macro_name>]
14448 [DEFINE_NO_DEPRECATED]
14449 [PREFIX_NAME <prefix_name>]
14450 [CUSTOM_CONTENT_FROM_VARIABLE <variable>]
14451 )
14452 The target properties CXX_VISIBILITY_PRESET and VISIBILITY_INLINES_HID‐
14454 DEN can be used to add the appropriate compile flags for targets. See
14455 the documentation of those target properties, and the convenience vari‐
14456 ables CMAKE_CXX_VISIBILITY_PRESET and CMAKE_VISIBILITY_INLINES_HIDDEN.
14457 By default GENERATE_EXPORT_HEADER() generates macro names in a file
14459 name determined by the name of the library. This means that in the
14460 simplest case, users of GenerateExportHeader will be equivalent to:
14461 set(CMAKE_CXX_VISIBILITY_PRESET hidden)
14463 set(CMAKE_VISIBILITY_INLINES_HIDDEN 1)
14464 add_library(somelib someclass.cpp)
14465 generate_export_header(somelib)
14466 install(TARGETS somelib DESTINATION ${LIBRARY_INSTALL_DIR})
14467 install(FILES
14468 someclass.h
14469 ${PROJECT_BINARY_DIR}/somelib_export.h DESTINATION ${INCLUDE_INSTALL_DIR}
14470 )
14471 And in the ABI header files:
14473 #include "somelib_export.h"
14475 class SOMELIB_EXPORT SomeClass {
14476 ...
14477 };
14478 The CMake fragment will generate a file in the ${CMAKE_CUR‐
14480 RENT_BINARY_DIR} called somelib_export.h containing the macros
14481 SOMELIB_EXPORT, SOMELIB_NO_EXPORT, SOMELIB_DEPRECATED, SOMELIB_DEPRE‐
14482 CATED_EXPORT and SOMELIB_DEPRECATED_NO_EXPORT. They will be followed
14483 by content taken from the variable specified by the CUSTOM_CON‐
14484 TENT_FROM_VARIABLE option, if any. The resulting file should be
14485 installed with other headers in the library.
14486 The BASE_NAME argument can be used to override the file name and the
14488 names used for the macros:
14489 add_library(somelib someclass.cpp)
14491 generate_export_header(somelib
14492 BASE_NAME other_name
14493 )
14494 Generates a file called other_name_export.h containing the macros
14496 OTHER_NAME_EXPORT, OTHER_NAME_NO_EXPORT and OTHER_NAME_DEPRECATED etc.
14497 The BASE_NAME may be overridden by specifying other options in the
14499 function. For example:
14500 add_library(somelib someclass.cpp)
14502 generate_export_header(somelib
14503 EXPORT_MACRO_NAME OTHER_NAME_EXPORT
14504 )
14505 creates the macro OTHER_NAME_EXPORT instead of SOMELIB_EXPORT, but
14507 other macros and the generated file name is as default:
14508 add_library(somelib someclass.cpp)
14510 generate_export_header(somelib
14511 DEPRECATED_MACRO_NAME KDE_DEPRECATED
14512 )
14513 creates the macro KDE_DEPRECATED instead of SOMELIB_DEPRECATED.
14515 If LIBRARY_TARGET is a static library, macros are defined without val‐
14517 ues.
14518 If the same sources are used to create both a shared and a static
14520 library, the uppercased symbol ${BASE_NAME}_STATIC_DEFINE should be
14521 used when building the static library:
14522 add_library(shared_variant SHARED ${lib_SRCS})
14524 add_library(static_variant ${lib_SRCS})
14525 generate_export_header(shared_variant BASE_NAME libshared_and_static)
14526 set_target_properties(static_variant PROPERTIES
14527 COMPILE_FLAGS -DLIBSHARED_AND_STATIC_STATIC_DEFINE)
14528 This will cause the export macros to expand to nothing when building
14530 the static library.
14531 If DEFINE_NO_DEPRECATED is specified, then a macro ${BASE_NAME}_NO_DEP‐
14533 RECATED will be defined This macro can be used to remove deprecated
14534 code from preprocessor output:
14535 option(EXCLUDE_DEPRECATED "Exclude deprecated parts of the library" FALSE)
14537 if (EXCLUDE_DEPRECATED)
14538 set(NO_BUILD_DEPRECATED DEFINE_NO_DEPRECATED)
14539 endif()
14540 generate_export_header(somelib ${NO_BUILD_DEPRECATED})
14541 And then in somelib:
14543 class SOMELIB_EXPORT SomeClass
14545 {
14546 public:
14547 #ifndef SOMELIB_NO_DEPRECATED
14548 SOMELIB_DEPRECATED void oldMethod();
14549 #endif
14550 };
14551 #ifndef SOMELIB_NO_DEPRECATED
14553 void SomeClass::oldMethod() { }
14554 #endif
14555 If PREFIX_NAME is specified, the argument will be used as a prefix to
14557 all generated macros.
14558 For example:
14560 generate_export_header(somelib PREFIX_NAME VTK_)
14562 Generates the macros VTK_SOMELIB_EXPORT etc.
14564 ADD_COMPILER_EXPORT_FLAGS( [<output_variable>] )
14566 The ADD_COMPILER_EXPORT_FLAGS function adds -fvisibility=hidden to
14568 CMAKE_CXX_FLAGS if supported, and is a no-op on Windows which does not
14569 need extra compiler flags for exporting support. You may optionally
14570 pass a single argument to ADD_COMPILER_EXPORT_FLAGS that will be popu‐
14571 lated with the CXX_FLAGS required to enable visibility support for the
14572 compiler/architecture in use.
14573 This function is deprecated. Set the target properties CXX_VISIBIL‐
14575 ITY_PRESET and VISIBILITY_INLINES_HIDDEN instead.
14576 GetPrerequisites
14578 Functions to analyze and list executable file prerequisites.
14579 This module provides functions to list the .dll, .dylib or .so files
14581 that an executable or shared library file depends on. (Its prerequi‐
14582 sites.)
14583 It uses various tools to obtain the list of required shared library
14585 files:
14586 dumpbin (Windows)
14588 objdump (MinGW on Windows)
14589 ldd (Linux/Unix)
14590 otool (Mac OSX)
14591 The following functions are provided by this module:
14593 get_prerequisites
14595 list_prerequisites
14596 list_prerequisites_by_glob
14597 gp_append_unique
14598 is_file_executable
14599 gp_item_default_embedded_path
14600 (projects can override with gp_item_default_embedded_path_override)
14601 gp_resolve_item
14602 (projects can override with gp_resolve_item_override)
14603 gp_resolved_file_type
14604 (projects can override with gp_resolved_file_type_override)
14605 gp_file_type
14606 Requires CMake 2.6 or greater because it uses function, break, return
14608 and PARENT_SCOPE.
14609 GET_PREREQUISITES(<target> <prerequisites_var> <exclude_system> <recurse>
14611 <exepath> <dirs> [<rpaths>])
14612 Get the list of shared library files required by <target>. The list in
14614 the variable named <prerequisites_var> should be empty on first entry
14615 to this function. On exit, <prerequisites_var> will contain the list
14616 of required shared library files.
14617 <target> is the full path to an executable file. <prerequisites_var>
14619 is the name of a CMake variable to contain the results. <exclude_sys‐
14620 tem> must be 0 or 1 indicating whether to include or exclude “system”
14621 prerequisites. If <recurse> is set to 1 all prerequisites will be
14622 found recursively, if set to 0 only direct prerequisites are listed.
14623 <exepath> is the path to the top level executable used for @exe‐
14624 cutable_path replacment on the Mac. <dirs> is a list of paths where
14625 libraries might be found: these paths are searched first when a target
14626 without any path info is given. Then standard system locations are
14627 also searched: PATH, Framework locations, /usr/lib…
14628 LIST_PREREQUISITES(<target> [<recurse> [<exclude_system> [<verbose>]]])
14630 Print a message listing the prerequisites of <target>.
14632 <target> is the name of a shared library or executable target or the
14634 full path to a shared library or executable file. If <recurse> is set
14635 to 1 all prerequisites will be found recursively, if set to 0 only
14636 direct prerequisites are listed. <exclude_system> must be 0 or 1 indi‐
14637 cating whether to include or exclude “system” prerequisites. With
14638 <verbose> set to 0 only the full path names of the prerequisites are
14639 printed, set to 1 extra informatin will be displayed.
14640 LIST_PREREQUISITES_BY_GLOB(<glob_arg> <glob_exp>)
14642 Print the prerequisites of shared library and executable files matching
14644 a globbing pattern. <glob_arg> is GLOB or GLOB_RECURSE and <glob_exp>
14645 is a globbing expression used with “file(GLOB” or “file(GLOB_RECURSE”
14646 to retrieve a list of matching files. If a matching file is exe‐
14647 cutable, its prerequisites are listed.
14648 Any additional (optional) arguments provided are passed along as the
14650 optional arguments to the list_prerequisites calls.
14651 GP_APPEND_UNIQUE(<list_var> <value>)
14653 Append <value> to the list variable <list_var> only if the value is not
14655 already in the list.
14656 IS_FILE_EXECUTABLE(<file> <result_var>)
14658 Return 1 in <result_var> if <file> is a binary executable, 0 otherwise.
14660 GP_ITEM_DEFAULT_EMBEDDED_PATH(<item> <default_embedded_path_var>)
14662 Return the path that others should refer to the item by when the item
14664 is embedded inside a bundle.
14665 Override on a per-project basis by providing a project-specific
14667 gp_item_default_embedded_path_override function.
14668 GP_RESOLVE_ITEM(<context> <item> <exepath> <dirs> <resolved_item_var>
14670 [<rpaths>])
14671 Resolve an item into an existing full path file.
14673 Override on a per-project basis by providing a project-specific
14675 gp_resolve_item_override function.
14676 GP_RESOLVED_FILE_TYPE(<original_file> <file> <exepath> <dirs> <type_var>
14678 [<rpaths>])
14679 Return the type of <file> with respect to <original_file>. String
14681 describing type of prerequisite is returned in variable named
14682 <type_var>.
14683 Use <exepath> and <dirs> if necessary to resolve non-absolute <file>
14685 values – but only for non-embedded items.
14686 Possible types are:
14688 system
14690 local
14691 embedded
14692 other
14693 Override on a per-project basis by providing a project-specific
14695 gp_resolved_file_type_override function.
14696 GP_FILE_TYPE(<original_file> <file> <type_var>)
14698 Return the type of <file> with respect to <original_file>. String
14700 describing type of prerequisite is returned in variable named
14701 <type_var>.
14702 Possible types are:
14704 system
14706 local
14707 embedded
14708 other
14709 GNUInstallDirs
14711 Define GNU standard installation directories
14712 Provides install directory variables as defined by the GNU Coding Stan‐
14714 dards.
14715 Result Variables
14717 Inclusion of this module defines the following variables:
14718 CMAKE_INSTALL_<dir>
14720 Destination for files of a given type. This value may be passed to
14721 the DESTINATION options of install() commands for the corresponding
14722 file type.
14723 CMAKE_INSTALL_FULL_<dir>
14725 The absolute path generated from the corresponding
14726 CMAKE_INSTALL_<dir> value. If the value is not already an absolute
14727 path, an absolute path is constructed typically by prepending the
14728 value of the CMAKE_INSTALL_PREFIX variable. However, there are some
14729 special cases as documented below.
14730 where <dir> is one of:
14732 BINDIR user executables (bin)
14734 SBINDIR
14736 system admin executables (sbin)
14737 LIBEXECDIR
14739 program executables (libexec)
14740 SYSCONFDIR
14742 read-only single-machine data (etc)
14743 SHAREDSTATEDIR
14745 modifiable architecture-independent data (com)
14746 LOCALSTATEDIR
14748 modifiable single-machine data (var)
14749 RUNSTATEDIR
14751 run-time variable data (LOCALSTATEDIR/run)
14752 LIBDIR object code libraries (lib or lib64 or lib/<multiarch-tuple> on
14754 Debian)
14755 INCLUDEDIR
14757 C header files (include)
14758 OLDINCLUDEDIR
14760 C header files for non-gcc (/usr/include)
14761 DATAROOTDIR
14763 read-only architecture-independent data root (share)
14764 DATADIR
14766 read-only architecture-independent data (DATAROOTDIR)
14767 INFODIR
14769 info documentation (DATAROOTDIR/info)
14770 LOCALEDIR
14772 locale-dependent data (DATAROOTDIR/locale)
14773 MANDIR man documentation (DATAROOTDIR/man)
14775 DOCDIR documentation root (DATAROOTDIR/doc/PROJECT_NAME)
14777 If the includer does not define a value the above-shown default will be
14779 used and the value will appear in the cache for editing by the user.
14780 Special Cases
14782 The following values of CMAKE_INSTALL_PREFIX are special:
14783 /
14785 For <dir> other than the SYSCONFDIR, LOCALSTATEDIR and RUNSTATEDIR,
14786 the value of CMAKE_INSTALL_<dir> is prefixed with usr/ if it is not
14787 user-specified as an absolute path. For example, the INCLUDEDIR
14788 value include becomes usr/include. This is required by the GNU Cod‐
14789 ing Standards, which state:
14790 When building the complete GNU system, the prefix will be empty
14791 and /usr will be a symbolic link to /.
14792 /usr
14794 For <dir> equal to SYSCONFDIR, LOCALSTATEDIR or RUNSTATEDIR, the
14795 CMAKE_INSTALL_FULL_<dir> is computed by prepending just / to the
14796 value of CMAKE_INSTALL_<dir> if it is not user-specified as an abso‐
14797 lute path. For example, the SYSCONFDIR value etc becomes /etc.
14798 This is required by the GNU Coding Standards.
14799 /opt/...
14801 For <dir> equal to SYSCONFDIR, LOCALSTATEDIR or RUNSTATEDIR, the
14802 CMAKE_INSTALL_FULL_<dir> is computed by appending the prefix to the
14803 value of CMAKE_INSTALL_<dir> if it is not user-specified as an abso‐
14804 lute path. For example, the SYSCONFDIR value etc becomes
14805 /etc/opt/.... This is defined by the Filesystem Hierarchy Standard.
14806 Macros
14808 GNUInstallDirs_get_absolute_install_dir
14809 GNUInstallDirs_get_absolute_install_dir(absvar var)
14811 Set the given variable absvar to the absolute path contained
14813 within the variable var. This is to allow the computation of an
14814 absolute path, accounting for all the special cases documented
14815 above. While this macro is used to compute the various
14816 CMAKE_INSTALL_FULL_<dir> variables, it is exposed publicly to
14817 allow users who create additional path variables to also compute
14818 absolute paths where necessary, using the same logic.
14819 GoogleTest
14821 This module defines functions to help use the Google Test infrastruc‐
14822 ture. Two mechanisms for adding tests are provided. gtest_add_tests()
14823 has been around for some time, originally via find_package(GTest).
14824 gtest_discover_tests() was introduced in CMake 3.10.
14825 The (older) gtest_add_tests() scans source files to identify tests.
14827 This is usually effective, with some caveats, including in cross-com‐
14828 piling environments, and makes setting additional properties on tests
14829 more convenient. However, its handling of parameterized tests is less
14830 comprehensive, and it requires re-running CMake to detect changes to
14831 the list of tests.
14832 The (newer) gtest_discover_tests() discovers tests by asking the com‐
14834 piled test executable to enumerate its tests. This is more robust and
14835 provides better handling of parameterized tests, and does not require
14836 CMake to be re-run when tests change. However, it may not work in a
14837 cross-compiling environment, and setting test properties is less conve‐
14838 nient.
14839 More details can be found in the documentation of the respective func‐
14841 tions.
14842 Both commands are intended to replace use of add_test() to register
14844 tests, and will create a separate CTest test for each Google Test test
14845 case. Note that this is in some cases less efficient, as common set-up
14846 and tear-down logic cannot be shared by multiple test cases executing
14847 in the same instance. However, it provides more fine-grained pass/fail
14848 information to CTest, which is usually considered as more beneficial.
14849 By default, the CTest test name is the same as the Google Test name
14850 (i.e. suite.testcase); see also TEST_PREFIX and TEST_SUFFIX.
14851 gtest_add_tests
14853 Automatically add tests with CTest by scanning source code for
14854 Google Test macros:
14855 gtest_add_tests(TARGET target
14857 [SOURCES src1...]
14858 [EXTRA_ARGS arg1...]
14859 [WORKING_DIRECTORY dir]
14860 [TEST_PREFIX prefix]
14861 [TEST_SUFFIX suffix]
14862 [SKIP_DEPENDENCY]
14863 [TEST_LIST outVar]
14864 )
14865 gtest_add_tests attempts to identify tests by scanning source
14867 files. Although this is generally effective, it uses only a
14868 basic regular expression match, which can be defeated by atypi‐
14869 cal test declarations, and is unable to fully “split” parameter‐
14870 ized tests. Additionally, it requires that CMake be re-run to
14871 discover any newly added, removed or renamed tests (by default,
14872 this means that CMake is re-run when any test source file is
14873 changed, but see SKIP_DEPENDENCY). However, it has the advan‐
14874 tage of declaring tests at CMake time, which somewhat simplifies
14875 setting additional properties on tests, and always works in a
14876 cross-compiling environment.
14877 The options are:
14879 TARGET target
14881 Specifies the Google Test executable, which must be a
14882 known CMake executable target. CMake will substitute the
14883 location of the built executable when running the test.
14884 SOURCES src1...
14886 When provided, only the listed files will be scanned for
14887 test cases. If this option is not given, the SOURCES
14888 property of the specified target will be used to obtain
14889 the list of sources.
14890 EXTRA_ARGS arg1...
14892 Any extra arguments to pass on the command line to each
14893 test case.
14894 WORKING_DIRECTORY dir
14896 Specifies the directory in which to run the discovered
14897 test cases. If this option is not provided, the current
14898 binary directory is used.
14899 TEST_PREFIX prefix
14901 Specifies a prefix to be prepended to the name of each
14902 discovered test case. This can be useful when the same
14903 source files are being used in multiple calls to
14904 gtest_add_test() but with different EXTRA_ARGS.
14905 TEST_SUFFIX suffix
14907 Similar to TEST_PREFIX except the suffix is appended to
14908 the name of every discovered test case. Both TEST_PREFIX
14909 and TEST_SUFFIX may be specified.
14910 SKIP_DEPENDENCY
14912 Normally, the function creates a dependency which will
14913 cause CMake to be re-run if any of the sources being
14914 scanned are changed. This is to ensure that the list of
14915 discovered tests is updated. If this behavior is not
14916 desired (as may be the case while actually writing the
14917 test cases), this option can be used to prevent the
14918 dependency from being added.
14919 TEST_LIST outVar
14921 The variable named by outVar will be populated in the
14922 calling scope with the list of discovered test cases.
14923 This allows the caller to do things like manipulate test
14924 properties of the discovered tests.
14925 include(GoogleTest)
14927 add_executable(FooTest FooUnitTest.cxx)
14928 gtest_add_tests(TARGET FooTest
14929 TEST_SUFFIX .noArgs
14930 TEST_LIST noArgsTests
14931 )
14932 gtest_add_tests(TARGET FooTest
14933 EXTRA_ARGS --someArg someValue
14934 TEST_SUFFIX .withArgs
14935 TEST_LIST withArgsTests
14936 )
14937 set_tests_properties(${noArgsTests} PROPERTIES TIMEOUT 10)
14938 set_tests_properties(${withArgsTests} PROPERTIES TIMEOUT 20)
14939 For backward compatibility, the following form is also sup‐
14941 ported:
14942 gtest_add_tests(exe args files...)
14944 exe The path to the test executable or the name of a CMake
14946 target.
14947 args A ;-list of extra arguments to be passed to executable.
14949 The entire list must be passed as a single argument.
14950 Enclose it in quotes, or pass "" for no arguments.
14951 files...
14953 A list of source files to search for tests and test fix‐
14954 tures. Alternatively, use AUTO to specify that exe is
14955 the name of a CMake executable target whose sources
14956 should be scanned.
14957 include(GoogleTest)
14959 set(FooTestArgs --foo 1 --bar 2)
14960 add_executable(FooTest FooUnitTest.cxx)
14961 gtest_add_tests(FooTest "${FooTestArgs}" AUTO)
14962 gtest_discover_tests
14964 Automatically add tests with CTest by querying the compiled test
14965 executable for available tests:
14966 gtest_discover_tests(target
14968 [EXTRA_ARGS arg1...]
14969 [WORKING_DIRECTORY dir]
14970 [TEST_PREFIX prefix]
14971 [TEST_SUFFIX suffix]
14972 [NO_PRETTY_TYPES] [NO_PRETTY_VALUES]
14973 [PROPERTIES name1 value1...]
14974 [TEST_LIST var]
14975 [DISCOVERY_TIMEOUT seconds]
14976 )
14977 gtest_discover_tests sets up a post-build command on the test
14979 executable that generates the list of tests by parsing the out‐
14980 put from running the test with the --gtest_list_tests argument.
14981 Compared to the source parsing approach of gtest_add_tests(),
14982 this ensures that the full list of tests, including instantia‐
14983 tions of parameterized tests, is obtained. Since test discovery
14984 occurs at build time, it is not necessary to re-run CMake when
14985 the list of tests changes. However, it requires that CROSSCOM‐
14986 PILING_EMULATOR is properly set in order to function in a
14987 cross-compiling environment.
14988 Additionally, setting properties on tests is somewhat less con‐
14990 venient, since the tests are not available at CMake time. Addi‐
14991 tional test properties may be assigned to the set of tests as a
14992 whole using the PROPERTIES option. If more fine-grained test
14993 control is needed, custom content may be provided through an
14994 external CTest script using the TEST_INCLUDE_FILES directory
14995 property. The set of discovered tests is made accessible to
14996 such a script via the <target>_TESTS variable.
14997 The options are:
14999 target Specifies the Google Test executable, which must be a
15001 known CMake executable target. CMake will substitute the
15002 location of the built executable when running the test.
15003 EXTRA_ARGS arg1...
15005 Any extra arguments to pass on the command line to each
15006 test case.
15007 WORKING_DIRECTORY dir
15009 Specifies the directory in which to run the discovered
15010 test cases. If this option is not provided, the current
15011 binary directory is used.
15012 TEST_PREFIX prefix
15014 Specifies a prefix to be prepended to the name of each
15015 discovered test case. This can be useful when the same
15016 test executable is being used in multiple calls to
15017 gtest_discover_tests() but with different EXTRA_ARGS.
15018 TEST_SUFFIX suffix
15020 Similar to TEST_PREFIX except the suffix is appended to
15021 the name of every discovered test case. Both TEST_PREFIX
15022 and TEST_SUFFIX may be specified.
15023 NO_PRETTY_TYPES
15025 By default, the type index of type-parameterized tests is
15026 replaced by the actual type name in the CTest test name.
15027 If this behavior is undesirable (e.g. because the type
15028 names are unwieldy), this option will suppress this
15029 behavior.
15030 NO_PRETTY_VALUES
15032 By default, the value index of value-parameterized tests
15033 is replaced by the actual value in the CTest test name.
15034 If this behavior is undesirable (e.g. because the value
15035 strings are unwieldy), this option will suppress this
15036 behavior.
15037 PROPERTIES name1 value1...
15039 Specifies additional properties to be set on all tests
15040 discovered by this invocation of gtest_discover_tests.
15041 TEST_LIST var
15043 Make the list of tests available in the variable var,
15044 rather than the default <target>_TESTS. This can be use‐
15045 ful when the same test executable is being used in multi‐
15046 ple calls to gtest_discover_tests(). Note that this
15047 variable is only available in CTest.
15048 DISCOVERY_TIMEOUT num
15050 Specifies how long (in seconds) CMake will wait for the
15051 test to enumerate available tests. If the test takes
15052 longer than this, discovery (and your build) will fail.
15053 Most test executables will enumerate their tests very
15054 quickly, but under some exceptional circumstances, a test
15055 may require a longer timeout. The default is 5. See
15056 also the TIMEOUT option of execute_process().
15057 NOTE:
15059 In CMake versions 3.10.1 and 3.10.2, this option was
15060 called TIMEOUT. This clashed with the TIMEOUT test
15061 property, which is one of the common properties that
15062 would be set with the PROPERTIES keyword, usually
15063 leading to legal but unintended behavior. The keyword
15064 was changed to DISCOVERY_TIMEOUT in CMake 3.10.3 to
15065 address this problem. The ambiguous behavior of the
15066 TIMEOUT keyword in 3.10.1 and 3.10.2 has not been pre‐
15067 served.
15068 InstallRequiredSystemLibraries
15070 Include this module to search for compiler-provided system runtime
15071 libraries and add install rules for them. Some optional variables may
15072 be set prior to including the module to adjust behavior:
15073 CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS
15075 Specify additional runtime libraries that may not be detected.
15076 After inclusion any detected libraries will be appended to this.
15077 CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS_SKIP
15079 Set to TRUE to skip calling the install(PROGRAMS) command to
15080 allow the includer to specify its own install rule, using the
15081 value of CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS to get the list of
15082 libraries.
15083 CMAKE_INSTALL_DEBUG_LIBRARIES
15085 Set to TRUE to install the debug runtime libraries when avail‐
15086 able with MSVC tools.
15087 CMAKE_INSTALL_DEBUG_LIBRARIES_ONLY
15089 Set to TRUE to install only the debug runtime libraries with
15090 MSVC tools even if the release runtime libraries are also avail‐
15091 able.
15092 CMAKE_INSTALL_UCRT_LIBRARIES
15094 Set to TRUE to install the Windows Universal CRT libraries for
15095 app-local deployment (e.g. to Windows XP). This is meaningful
15096 only with MSVC from Visual Studio 2015 or higher.
15097 One may set a CMAKE_WINDOWS_KITS_10_DIR environment variable to
15099 an absolute path to tell CMake to look for Windows 10 SDKs in a
15100 custom location. The specified directory is expected to contain
15101 Redist/ucrt/DLLs/* directories.
15102 CMAKE_INSTALL_MFC_LIBRARIES
15104 Set to TRUE to install the MSVC MFC runtime libraries.
15105 CMAKE_INSTALL_OPENMP_LIBRARIES
15107 Set to TRUE to install the MSVC OpenMP runtime libraries
15108 CMAKE_INSTALL_SYSTEM_RUNTIME_DESTINATION
15110 Specify the install(PROGRAMS) command DESTINATION option. If
15111 not specified, the default is bin on Windows and lib elsewhere.
15112 CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS_NO_WARNINGS
15114 Set to TRUE to disable warnings about required library files
15115 that do not exist. (For example, Visual Studio Express editions
15116 may not provide the redistributable files.)
15117 CMAKE_INSTALL_SYSTEM_RUNTIME_COMPONENT
15119 Specify the install(PROGRAMS) command COMPONENT option. If not
15120 specified, no such option will be used.
15121 MacroAddFileDependencies
15123 MACRO_ADD_FILE_DEPENDENCIES(<_file> depend_files…)
15124 Using the macro MACRO_ADD_FILE_DEPENDENCIES() is discouraged. There
15126 are usually better ways to specify the correct dependencies.
15127 MACRO_ADD_FILE_DEPENDENCIES(<_file> depend_files…) is just a conve‐
15129 nience wrapper around the OBJECT_DEPENDS source file property. You can
15130 just use set_property(SOURCE <file> APPEND PROPERTY OBJECT_DEPENDS
15131 depend_files) instead.
15132 ProcessorCount
15134 ProcessorCount(var)
15135 Determine the number of processors/cores and save value in ${var}
15137 Sets the variable named ${var} to the number of physical cores avail‐
15139 able on the machine if the information can be determined. Otherwise it
15140 is set to 0. Currently this functionality is implemented for AIX, cyg‐
15141 win, FreeBSD, HPUX, IRIX, Linux, Mac OS X, QNX, Sun and Windows.
15142 This function is guaranteed to return a positive integer (>=1) if it
15144 succeeds. It returns 0 if there’s a problem determining the processor
15145 count.
15146 Example use, in a ctest -S dashboard script:
15148 include(ProcessorCount)
15150 ProcessorCount(N)
15151 if(NOT N EQUAL 0)
15152 set(CTEST_BUILD_FLAGS -j${N})
15153 set(ctest_test_args ${ctest_test_args} PARALLEL_LEVEL ${N})
15154 endif()
15155 This function is intended to offer an approximation of the value of the
15157 number of compute cores available on the current machine, such that you
15158 may use that value for parallel building and parallel testing. It is
15159 meant to help utilize as much of the machine as seems reasonable. Of
15160 course, knowledge of what else might be running on the machine simulta‐
15161 neously should be used when deciding whether to request a machine’s
15162 full capacity all for yourself.
15163 SelectLibraryConfigurations
15165 select_library_configurations( basename )
15166 This macro takes a library base name as an argument, and will choose
15168 good values for basename_LIBRARY, basename_LIBRARIES, base‐
15169 name_LIBRARY_DEBUG, and basename_LIBRARY_RELEASE depending on what has
15170 been found and set. If only basename_LIBRARY_RELEASE is defined, base‐
15171 name_LIBRARY will be set to the release value, and base‐
15172 name_LIBRARY_DEBUG will be set to basename_LIBRARY_DEBUG-NOTFOUND. If
15173 only basename_LIBRARY_DEBUG is defined, then basename_LIBRARY will take
15174 the debug value, and basename_LIBRARY_RELEASE will be set to base‐
15175 name_LIBRARY_RELEASE-NOTFOUND.
15176 If the generator supports configuration types, then basename_LIBRARY
15178 and basename_LIBRARIES will be set with debug and optimized flags spec‐
15179 ifying the library to be used for the given configuration. If no build
15180 type has been set or the generator in use does not support configura‐
15181 tion types, then basename_LIBRARY and basename_LIBRARIES will take only
15182 the release value, or the debug value if the release one is not set.
15183 SquishTestScript
15185 This script launches a GUI test using Squish. You should not call the
15186 script directly; instead, you should access it via the SQUISH_ADD_TEST
15187 macro that is defined in FindSquish.cmake.
15188 This script starts the Squish server, launches the test on the client,
15190 and finally stops the squish server. If any of these steps fail
15191 (including if the tests do not pass) then a fatal error is raised.
15192 TestBigEndian
15194 Define macro to determine endian type
15195 Check if the system is big endian or little endian
15197 TEST_BIG_ENDIAN(VARIABLE)
15199 VARIABLE - variable to store the result to
15200 TestCXXAcceptsFlag
15202 Deprecated. See CheckCXXCompilerFlag.
15203 Check if the CXX compiler accepts a flag.
15205 CHECK_CXX_ACCEPTS_FLAG(<flags> <variable>)
15207 <flags>
15209 the flags to try
15210 <variable>
15212 variable to store the result
15213 TestForANSIForScope
15215 Check for ANSI for scope support
15216 Check if the compiler restricts the scope of variables declared in a
15218 for-init-statement to the loop body.
15219 CMAKE_NO_ANSI_FOR_SCOPE - holds result
15221 TestForANSIStreamHeaders
15223 Test for compiler support of ANSI stream headers iostream, etc.
15224 check if the compiler supports the standard ANSI iostream header (with‐
15226 out the .h)
15227 CMAKE_NO_ANSI_STREAM_HEADERS - defined by the results
15229 TestForSSTREAM
15231 Test for compiler support of ANSI sstream header
15232 check if the compiler supports the standard ANSI sstream header
15234 CMAKE_NO_ANSI_STRING_STREAM - defined by the results
15236 TestForSTDNamespace
15238 Test for std:: namespace support
15239 check if the compiler supports std:: on stl classes
15241 CMAKE_NO_STD_NAMESPACE - defined by the results
15243 UseEcos
15245 This module defines variables and macros required to build eCos appli‐
15246 cation.
15247 This file contains the following macros: ECOS_ADD_INCLUDE_DIRECTORIES()
15249 - add the eCos include dirs ECOS_ADD_EXECUTABLE(name source1 … sourceN
15250 ) - create an eCos executable ECOS_ADJUST_DIRECTORY(VAR source1 …
15251 sourceN ) - adjusts the path of the source files and puts the result
15252 into VAR
15253 Macros for selecting the toolchain: ECOS_USE_ARM_ELF_TOOLS() - enable
15255 the ARM ELF toolchain for the directory where it is called
15256 ECOS_USE_I386_ELF_TOOLS() - enable the i386 ELF toolchain for the
15257 directory where it is called ECOS_USE_PPC_EABI_TOOLS() - enable the
15258 PowerPC toolchain for the directory where it is called
15259 It contains the following variables: ECOS_DEFINITIONS ECOSCONFIG_EXE‐
15261 CUTABLE ECOS_CONFIG_FILE - defaults to ecos.ecc, if your eCos configu‐
15262 ration file has a different name, adjust this variable for internal use
15263 only:
15264 ECOS_ADD_TARGET_LIB
15266 UseJavaClassFilelist
15268 This script create a list of compiled Java class files to be added to a
15269 jar file. This avoids including cmake files which get created in the
15270 binary directory.
15271 UseJava
15273 Use Module for Java
15274 This file provides functions for Java. It is assumed that Find‐
15276 Java.cmake has already been loaded. See FindJava.cmake for information
15277 on how to load Java into your CMake project.
15278 add_jar(target_name
15280 [SOURCES] source1 [source2 ...] [resource1 ...]
15281 [INCLUDE_JARS jar1 [jar2 ...]]
15282 [ENTRY_POINT entry]
15283 [VERSION version]
15284 [OUTPUT_NAME name]
15285 [OUTPUT_DIR dir]
15286 [GENERATE_NATIVE_HEADERS target [DESTINATION dir]]
15287 )
15288 This command creates a <target_name>.jar. It compiles the given source
15290 files (source) and adds the given resource files (resource) to the jar
15291 file. Source files can be java files or listing files (prefixed by
15292 ‘@’). If only resource files are given then just a jar file is cre‐
15293 ated. The list of include jars are added to the classpath when compil‐
15294 ing the java sources and also to the dependencies of the target.
15295 INCLUDE_JARS also accepts other target names created by add_jar. For
15296 backwards compatibility, jar files listed as sources are ignored (as
15297 they have been since the first version of this module).
15298 The default OUTPUT_DIR can also be changed by setting the variable
15300 CMAKE_JAVA_TARGET_OUTPUT_DIR.
15301 Optionaly, using option GENERATE_NATIVE_HEADERS, native header files
15303 can be generated for methods declared as native. These files provide
15304 the connective glue that allow your Java and C code to interact. An
15305 INTERFACE target will be created for an easy usage of generated files.
15306 Sub-option DESTINATION can be used to specify output directory for gen‐
15307 erated header files.
15308 GENERATE_NATIVE_HEADERS option requires, at least, version 1.8 of the
15310 JDK.
15311 Additional instructions:
15313 To add compile flags to the target you can set these flags with
15315 the following variable:
15316 set(CMAKE_JAVA_COMPILE_FLAGS -nowarn)
15318 To add a path or a jar file to the class path you can do this
15320 with the CMAKE_JAVA_INCLUDE_PATH variable.
15321 set(CMAKE_JAVA_INCLUDE_PATH /usr/share/java/shibboleet.jar)
15323 To use a different output name for the target you can set it with:
15325 add_jar(foobar foobar.java OUTPUT_NAME shibboleet.jar)
15327 To use a different output directory than CMAKE_CURRENT_BINARY_DIR
15329 you can set it with:
15330 add_jar(foobar foobar.java OUTPUT_DIR ${PROJECT_BINARY_DIR}/bin)
15332 To define an entry point in your jar you can set it with the ENTRY_POINT
15334 named argument:
15335 add_jar(example ENTRY_POINT com/examples/MyProject/Main)
15337 To define a custom manifest for the jar, you can set it with the manifest
15339 named argument:
15340 add_jar(example MANIFEST /path/to/manifest)
15342 To add a VERSION to the target output name you can set it using
15344 the VERSION named argument to add_jar. This will create a jar file with the
15345 name shibboleet-1.0.0.jar and will create a symlink shibboleet.jar
15346 pointing to the jar with the version information.
15347 add_jar(shibboleet shibbotleet.java VERSION 1.2.0)
15349 If the target is a JNI library, utilize the following commands to
15351 create a JNI symbolic link:
15352 set(CMAKE_JNI_TARGET TRUE)
15354 add_jar(shibboleet shibbotleet.java VERSION 1.2.0)
15355 install_jar(shibboleet ${LIB_INSTALL_DIR}/shibboleet)
15356 install_jni_symlink(shibboleet ${JAVA_LIB_INSTALL_DIR})
15357 If a single target needs to produce more than one jar from its
15359 java source code, to prevent the accumulation of duplicate class
15360 files in subsequent jars, set/reset CMAKE_JAR_CLASSES_PREFIX prior
15361 to calling the add_jar() function:
15362 set(CMAKE_JAR_CLASSES_PREFIX com/redhat/foo)
15364 add_jar(foo foo.java)
15365 set(CMAKE_JAR_CLASSES_PREFIX com/redhat/bar)
15367 add_jar(bar bar.java)
15368 For an optimum usage of option GENERATE_NATIVE_HEADERS, it is recommended to
15370 include module JNI before any call to add_jar. The produced target for native
15371 headers can then be used to compile C/C++ sources with command
15372 target_link_libraries.
15373 find_package(JNI)
15375 add_jar(foo foo.java GENERATE_NATIVE_HEADERS foo-native)
15376 add_library(bar bar.cpp)
15377 target_link_libraries(bar PRIVATE foo-native)
15378 Target Properties:
15380 The add_jar() function sets some target properties. You can get these
15382 properties with the
15383 get_property(TARGET <target_name> PROPERTY <propery_name>)
15384 command.
15385 INSTALL_FILES The files which should be installed. This is used by
15387 install_jar().
15388 JNI_SYMLINK The JNI symlink which should be installed.
15389 This is used by install_jni_symlink().
15390 JAR_FILE The location of the jar file so that you can include
15391 it.
15392 CLASSDIR The directory where the class files can be found. For
15393 example to use them with javah.
15394 find_jar(<VAR>
15396 name | NAMES name1 [name2 ...]
15397 [PATHS path1 [path2 ... ENV var]]
15398 [VERSIONS version1 [version2]]
15399 [DOC "cache documentation string"]
15400 )
15401 This command is used to find a full path to the named jar. A cache
15403 entry named by <VAR> is created to stor the result of this command. If
15404 the full path to a jar is found the result is stored in the variable
15405 and the search will not repeated unless the variable is cleared. If
15406 nothing is found, the result will be <VAR>-NOTFOUND, and the search
15407 will be attempted again next time find_jar is invoked with the same
15408 variable. The name of the full path to a file that is searched for is
15409 specified by the names listed after NAMES argument. Additional search
15410 locations can be specified after the PATHS argument. If you require
15411 special a version of a jar file you can specify it with the VERSIONS
15412 argument. The argument after DOC will be used for the documentation
15413 string in the cache.
15414 install_jar(target_name destination)
15416 install_jar(target_name DESTINATION destination [COMPONENT component])
15417 This command installs the TARGET_NAME files to the given DESTINATION.
15419 It should be called in the same scope as add_jar() or it will fail.
15420 Target Properties:
15422 The install_jar() function sets the INSTALL_DESTINATION target property
15424 on jars so installed. This property holds the DESTINATION as described
15425 above, and is used by install_jar_exports(). You can get this property
15426 with the
15427 get_property(TARGET <target_name> PROPERTY INSTALL_DESTINATION)
15428 command.
15429 install_jni_symlink(target_name destination)
15431 install_jni_symlink(target_name DESTINATION destination [COMPONENT component])
15432 This command installs the TARGET_NAME JNI symlinks to the given DESTI‐
15434 NATION. It should be called in the same scope as add_jar() or it will
15435 fail.
15436 install_jar_exports(TARGETS jars...
15438 [NAMESPACE <namespace>]
15439 FILE <filename>
15440 DESTINATION <dir> [COMPONENT <component>])
15441 This command installs a target export file <filename> for the named jar
15443 targets to the given DESTINATION. Its function is similar to that of
15444 install(EXPORTS ...).
15445 export_jars(TARGETS jars...
15447 [NAMESPACE <namespace>]
15448 FILE <filename>)
15449 This command writes a target export file <filename> for the named jar
15451 targets. Its function is similar to that of export(...).
15452 create_javadoc(<VAR>
15454 PACKAGES pkg1 [pkg2 ...]
15455 [SOURCEPATH <sourcepath>]
15456 [CLASSPATH <classpath>]
15457 [INSTALLPATH <install path>]
15458 [DOCTITLE "the documentation title"]
15459 [WINDOWTITLE "the title of the document"]
15460 [AUTHOR TRUE|FALSE]
15461 [USE TRUE|FALSE]
15462 [VERSION TRUE|FALSE]
15463 )
15464 Create java documentation based on files or packages. For more details
15466 please read the javadoc manpage.
15467 There are two main signatures for create_javadoc. The first signature
15469 works with package names on a path with source files:
15470 Example:
15472 create_javadoc(my_example_doc
15473 PACKAGES com.example.foo com.example.bar
15474 SOURCEPATH "${CMAKE_CURRENT_SOURCE_DIR}"
15475 CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH}
15476 WINDOWTITLE "My example"
15477 DOCTITLE "<h1>My example</h1>"
15478 AUTHOR TRUE
15479 USE TRUE
15480 VERSION TRUE
15481 )
15482 The second signature for create_javadoc works on a given list of files.
15484 create_javadoc(<VAR>
15486 FILES file1 [file2 ...]
15487 [CLASSPATH <classpath>]
15488 [INSTALLPATH <install path>]
15489 [DOCTITLE "the documentation title"]
15490 [WINDOWTITLE "the title of the document"]
15491 [AUTHOR TRUE|FALSE]
15492 [USE TRUE|FALSE]
15493 [VERSION TRUE|FALSE]
15494 )
15495 Example:
15497 create_javadoc(my_example_doc
15499 FILES ${example_SRCS}
15500 CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH}
15501 WINDOWTITLE "My example"
15502 DOCTITLE "<h1>My example</h1>"
15503 AUTHOR TRUE
15504 USE TRUE
15505 VERSION TRUE
15506 )
15507 Both signatures share most of the options. These options are the same
15509 as what you can find in the javadoc manpage. Please look at the man‐
15510 page for CLASSPATH, DOCTITLE, WINDOWTITLE, AUTHOR, USE and VERSION.
15511 The documentation will be by default installed to
15513 ${CMAKE_INSTALL_PREFIX}/share/javadoc/<VAR>
15515 if you don’t set the INSTALLPATH.
15517 create_javah(TARGET <target>
15519 GENERATED_FILES <VAR>
15520 CLASSES <class>...
15521 [CLASSPATH <classpath>...]
15522 [DEPENDS <depend>...]
15523 [OUTPUT_NAME <path>|OUTPUT_DIR <path>]
15524 )
15525 Create C header files from java classes. These files provide the con‐
15527 nective glue that allow your Java and C code to interact.
15528 This command will no longer be supported starting with version 10 of
15530 the JDK due to the suppression of javah tool. Command add_jar(GENER‐
15531 ATE_NATIVE_HEADERS) must be used instead.
15532 There are two main signatures for create_javah. The first signature
15534 returns generated files through variable specified by GENERATED_FILES
15535 option:
15536 Example:
15538 Create_javah(GENERATED_FILES files_headers
15539 CLASSES org.cmake.HelloWorld
15540 CLASSPATH hello.jar
15541 )
15542 The second signature for create_javah creates a target which encapsu‐
15544 lates header files generation.
15545 Example:
15547 Create_javah(TARGET target_headers
15548 CLASSES org.cmake.HelloWorld
15549 CLASSPATH hello.jar
15550 )
15551 Both signatures share same options.
15553 CLASSES <class>...
15555 Specifies Java classes used to generate headers.
15556 CLASSPATH <classpath>...
15558 Specifies various paths to look up classes. Here .class
15559 files, jar files or targets created by command add_jar can be
15560 used.
15561 DEPENDS <depend>...
15563 Targets on which the javah target depends
15564 OUTPUT_NAME <path>
15566 Concatenates the resulting header files for all the classes
15567 listed by option CLASSES into <path>. Same behavior as option
15568 ‘-o’ of javah tool.
15569 OUTPUT_DIR <path>
15571 Sets the directory where the header files will be generated.
15572 Same behavior as option ‘-d’ of javah tool. If not specified,
15573 ${CMAKE_CURRENT_BINARY_DIR} is used as output directory.
15574 UseJavaSymlinks
15576 Helper script for UseJava.cmake
15577 UsePkgConfig
15579 Obsolete pkg-config module for CMake, use FindPkgConfig instead.
15580 This module defines the following macro:
15582 PKGCONFIG(package includedir libdir linkflags cflags)
15584 Calling PKGCONFIG will fill the desired information into the 4 given
15586 arguments, e.g. PKGCONFIG(libart-2.0 LIBART_INCLUDE_DIR
15587 LIBART_LINK_DIR LIBART_LINK_FLAGS LIBART_CFLAGS) if pkg-config was NOT
15588 found or the specified software package doesn’t exist, the variable
15589 will be empty when the function returns, otherwise they will contain
15590 the respective information
15591 UseSWIG
15593 Defines the following macros for use with SWIG:
15594 swig_add_library
15596 Define swig module with given name and specified language:
15597 swig_add_library(<name>
15599 [TYPE <SHARED|MODULE|STATIC|USE_BUILD_SHARED_LIBS>]
15600 LANGUAGE <language>
15601 SOURCES <file>...
15602 )
15603 The variable SWIG_MODULE_<name>_REAL_NAME will be set to the
15605 name of the swig module target library.
15606 swig_link_libraries
15608 Link libraries to swig module:
15609 swig_link_libraries(<name> [ libraries ])
15611 Source file properties on module files can be set before the invocation
15613 of the swig_add_library macro to specify special behavior of SWIG:
15614 CPLUSPLUS
15616 Call SWIG in c++ mode. For example:
15617 set_property(SOURCE mymod.i PROPERTY CPLUSPLUS ON)
15619 swig_add_library(mymod LANGUAGE python SOURCES mymod.i)
15620 SWIG_FLAGS
15622 Add custom flags to the SWIG executable.
15623 SWIG_MODULE_NAME
15625 Specify the actual import name of the module in the target lan‐
15626 guage. This is required if it cannot be scanned automatically
15627 from source or different from the module file basename. For
15628 example:
15629 set_property(SOURCE mymod.i PROPERTY SWIG_MODULE_NAME mymod_realname)
15631 Some variables can be set to specify special behavior of SWIG:
15633 CMAKE_SWIG_FLAGS
15635 Add flags to all swig calls.
15636 CMAKE_SWIG_OUTDIR
15638 Specify where to write the language specific files (swig -outdir
15639 option).
15640 SWIG_OUTFILE_DIR
15642 Specify an output directory name where the generated source file
15643 will be placed. If not specified, CMAKE_SWIG_OUTDIR is used.
15644 SWIG_MODULE_<name>_EXTRA_DEPS
15646 Specify extra dependencies for the generated module for <name>.
15647 UsewxWidgets
15649 Convenience include for using wxWidgets library.
15650 Determines if wxWidgets was FOUND and sets the appropriate libs,
15652 incdirs, flags, etc. INCLUDE_DIRECTORIES and LINK_DIRECTORIES are
15653 called.
15654 USAGE
15656 # Note that for MinGW users the order of libs is important!
15658 find_package(wxWidgets REQUIRED net gl core base)
15659 include(${wxWidgets_USE_FILE})
15660 # and for each of your dependent executable/library targets:
15661 target_link_libraries(<YourTarget> ${wxWidgets_LIBRARIES})
15662 DEPRECATED
15664 LINK_LIBRARIES is not called in favor of adding dependencies per target.
15666 AUTHOR
15668 Jan Woetzel <jw -at- mip.informatik.uni-kiel.de>
15670 Use_wxWindows
15672 This convenience include finds if wxWindows is installed and set the
15673 appropriate libs, incdirs, flags etc. author Jan Woetzel <jw -at-
15674 mip.informatik.uni-kiel.de> (07/2003)
15675 USAGE:
15677 just include Use_wxWindows.cmake
15679 in your projects CMakeLists.txt
15680 include( ${CMAKE_MODULE_PATH}/Use_wxWindows.cmake)
15682 if you are sure you need GL then
15684 set(WXWINDOWS_USE_GL 1)
15686 *before* you include this file.
15688 WriteBasicConfigVersionFile
15690 WRITE_BASIC_CONFIG_VERSION_FILE( filename
15691 [VERSION major.minor.patch]
15692 COMPATIBILITY (AnyNewerVersion|SameMajorVersion|SameMinorVersion|ExactVersion)
15693 )
15694 Deprecated, see WRITE_BASIC_PACKAGE_VERSION_FILE(), it is identical.
15696 WriteCompilerDetectionHeader
15698 This module provides the function write_compiler_detection_header().
15699 The WRITE_COMPILER_DETECTION_HEADER function can be used to generate a
15701 file suitable for preprocessor inclusion which contains macros to be
15702 used in source code:
15703 write_compiler_detection_header(
15705 FILE <file>
15706 PREFIX <prefix>
15707 [OUTPUT_FILES_VAR <output_files_var> OUTPUT_DIR <output_dir>]
15708 COMPILERS <compiler> [...]
15709 FEATURES <feature> [...]
15710 [VERSION <version>]
15711 [PROLOG <prolog>]
15712 [EPILOG <epilog>]
15713 [ALLOW_UNKNOWN_COMPILERS]
15714 [ALLOW_UNKNOWN_COMPILER_VERSIONS]
15715 )
15716 The write_compiler_detection_header function generates the file <file>
15718 with macros which all have the prefix <prefix>.
15719 By default, all content is written directly to the <file>. The OUT‐
15721 PUT_FILES_VAR may be specified to cause the compiler-specific content
15722 to be written to separate files. The separate files are then available
15723 in the <output_files_var> and may be consumed by the caller for instal‐
15724 lation for example. The OUTPUT_DIR specifies a relative path from the
15725 main <file> to the compiler-specific files. For example:
15726 write_compiler_detection_header(
15728 FILE climbingstats_compiler_detection.h
15729 PREFIX ClimbingStats
15730 OUTPUT_FILES_VAR support_files
15731 OUTPUT_DIR compilers
15732 COMPILERS GNU Clang MSVC Intel
15733 FEATURES cxx_variadic_templates
15734 )
15735 install(FILES
15736 ${CMAKE_CURRENT_BINARY_DIR}/climbingstats_compiler_detection.h
15737 DESTINATION include
15738 )
15739 install(FILES
15740 ${support_files}
15741 DESTINATION include/compilers
15742 )
15743 VERSION may be used to specify the API version to be generated. Future
15745 versions of CMake may introduce alternative APIs. A given API is
15746 selected by any <version> value greater than or equal to the version of
15747 CMake that introduced the given API and less than the version of CMake
15748 that introduced its succeeding API. The value of the CMAKE_MINI‐
15749 MUM_REQUIRED_VERSION variable is used if no explicit version is speci‐
15750 fied. (As of CMake version 3.11.4 there is only one API version.)
15751 PROLOG may be specified as text content to write at the start of the
15753 header. EPILOG may be specified as text content to write at the end of
15754 the header
15755 At least one <compiler> and one <feature> must be listed. Compilers
15757 which are known to CMake, but not specified are detected and a pre‐
15758 processor #error is generated for them. A preprocessor macro matching
15759 <PREFIX>_COMPILER_IS_<compiler> is generated for each compiler known to
15760 CMake to contain the value 0 or 1.
15761 Possible compiler identifiers are documented with the CMAKE_<LANG>_COM‐
15763 PILER_ID variable. Available features in this version of CMake are
15764 listed in the CMAKE_C_KNOWN_FEATURES and CMAKE_CXX_KNOWN_FEATURES
15765 global properties. The {c,cxx}_std_* meta-features are ignored if
15766 requested.
15767 See the cmake-compile-features(7) manual for information on compile
15769 features.
15770 ALLOW_UNKNOWN_COMPILERS and ALLOW_UNKNOWN_COMPILER_VERSIONS cause the
15772 module to generate conditions that treat unknown compilers as simply
15773 lacking all features. Without these options the default behavior is to
15774 generate a #error for unknown compilers.
15775 Feature Test Macros
15777 For each compiler, a preprocessor macro is generated matching <PRE‐
15778 FIX>_COMPILER_IS_<compiler> which has the content either 0 or 1,
15779 depending on the compiler in use. Preprocessor macros for compiler ver‐
15780 sion components are generated matching <PREFIX>_COMPILER_VERSION_MAJOR
15781 <PREFIX>_COMPILER_VERSION_MINOR and <PREFIX>_COMPILER_VERSION_PATCH
15782 containing decimal values for the corresponding compiler version compo‐
15783 nents, if defined.
15784 A preprocessor test is generated based on the compiler version denoting
15786 whether each feature is enabled. A preprocessor macro matching <PRE‐
15787 FIX>_COMPILER_<FEATURE>, where <FEATURE> is the upper-case <feature>
15788 name, is generated to contain the value 0 or 1 depending on whether the
15789 compiler in use supports the feature:
15790 write_compiler_detection_header(
15792 FILE climbingstats_compiler_detection.h
15793 PREFIX ClimbingStats
15794 COMPILERS GNU Clang AppleClang MSVC Intel
15795 FEATURES cxx_variadic_templates
15796 )
15797 #if ClimbingStats_COMPILER_CXX_VARIADIC_TEMPLATES
15799 template<typename... T>
15800 void someInterface(T t...) { /* ... */ }
15801 #else
15802 // Compatibility versions
15803 template<typename T1>
15804 void someInterface(T1 t1) { /* ... */ }
15805 template<typename T1, typename T2>
15806 void someInterface(T1 t1, T2 t2) { /* ... */ }
15807 template<typename T1, typename T2, typename T3>
15808 void someInterface(T1 t1, T2 t2, T3 t3) { /* ... */ }
15809 #endif
15810 Symbol Macros
15812 Some additional symbol-defines are created for particular features for
15813 use as symbols which may be conditionally defined empty:
15814 class MyClass ClimbingStats_FINAL
15816 {
15817 ClimbingStats_CONSTEXPR int someInterface() { return 42; }
15818 };
15819 The ClimbingStats_FINAL macro will expand to final if the compiler (and
15821 its flags) support the cxx_final feature, and the ClimbingStats_CONST‐
15822 EXPR macro will expand to constexpr if cxx_constexpr is supported.
15823 The following features generate corresponding symbol defines:
15825 ┌──────────────────┬────────────────────┬─────────────┐
15827 │Feature │ Define │ Symbol │
15828 ├──────────────────┼────────────────────┼─────────────┤
15829 │c_restrict │ <PREFIX>_RESTRICT │ restrict │
15830 ├──────────────────┼────────────────────┼─────────────┤
15831 │cxx_constexpr │ <PREFIX>_CONSTEXPR │ constexpr │
15832 ├──────────────────┼────────────────────┼─────────────┤
15833 │cxx_deleted_func‐ │ <PRE‐ │ = delete │
15834 │tions │ FIX>_DELETED_FUNC‐ │ │
15835 │ │ TION │ │
15836 ├──────────────────┼────────────────────┼─────────────┤
15837 │cxx_extern_tem‐ │ <PRE‐ │ extern │
15838 │plates │ FIX>_EXTERN_TEM‐ │ │
15839 │ │ PLATE │ │
15840 ├──────────────────┼────────────────────┼─────────────┤
15841 │cxx_final │ <PREFIX>_FINAL │ final │
15842 ├──────────────────┼────────────────────┼─────────────┤
15843 │cxx_noexcept │ <PREFIX>_NOEXCEPT │ noexcept │
15844 ├──────────────────┼────────────────────┼─────────────┤
15845 │cxx_noexcept │ <PREFIX>_NOEX‐ │ noexcept(X) │
15846 │ │ CEPT_EXPR(X) │ │
15847 ├──────────────────┼────────────────────┼─────────────┤
15848 │cxx_override │ <PREFIX>_OVERRIDE │ override │
15849 └──────────────────┴────────────────────┴─────────────┘
15850 Compatibility Implementation Macros
15852 Some features are suitable for wrapping in a macro with a backward com‐
15853 patibility implementation if the compiler does not support the feature.
15854 When the cxx_static_assert feature is not provided by the compiler, a
15856 compatibility implementation is available via the <PRE‐
15857 FIX>_STATIC_ASSERT(COND) and <PREFIX>_STATIC_ASSERT_MSG(COND, MSG)
15858 function-like macros. The macros expand to static_assert where that
15859 compiler feature is available, and to a compatibility implementation
15860 otherwise. In the first form, the condition is stringified in the mes‐
15861 sage field of static_assert. In the second form, the message MSG is
15862 passed to the message field of static_assert, or ignored if using the
15863 backward compatibility implementation.
15864 The cxx_attribute_deprecated feature provides a macro definition <PRE‐
15866 FIX>_DEPRECATED, which expands to either the standard [[deprecated]]
15867 attribute or a compiler-specific decorator such as
15868 __attribute__((__deprecated__)) used by GNU compilers.
15869 The cxx_alignas feature provides a macro definition <PREFIX>_ALIGNAS
15871 which expands to either the standard alignas decorator or a com‐
15872 piler-specific decorator such as __attribute__ ((__aligned__)) used by
15873 GNU compilers.
15874 The cxx_alignof feature provides a macro definition <PREFIX>_ALIGNOF
15876 which expands to either the standard alignof decorator or a com‐
15877 piler-specific decorator such as __alignof__ used by GNU compilers.
15878 ┌───────────────────┬────────────────────────┬────────────────┐
15880 │Feature │ Define │ Symbol │
15881 ├───────────────────┼────────────────────────┼────────────────┤
15882 │cxx_alignas │ <PREFIX>_ALIGNAS │ alignas │
15883 ├───────────────────┼────────────────────────┼────────────────┤
15884 │cxx_alignof │ <PREFIX>_ALIGNOF │ alignof │
15885 ├───────────────────┼────────────────────────┼────────────────┤
15886 │cxx_nullptr │ <PREFIX>_NULLPTR │ nullptr │
15887 ├───────────────────┼────────────────────────┼────────────────┤
15888 │cxx_static_assert │ <PRE‐ │ static_assert │
15889 │ │ FIX>_STATIC_ASSERT │ │
15890 ├───────────────────┼────────────────────────┼────────────────┤
15891 │cxx_static_assert │ <PRE‐ │ static_assert │
15892 │ │ FIX>_STATIC_ASSERT_MSG │ │
15893 ├───────────────────┼────────────────────────┼────────────────┤
15894 │cxx_attribute_dep‐ │ <PREFIX>_DEPRECATED │ [[deprecated]] │
15895 │recated │ │ │
15896 ├───────────────────┼────────────────────────┼────────────────┤
15897 │cxx_attribute_dep‐ │ <PREFIX>_DEPRE‐ │ [[deprecated]] │
15898 │recated │ CATED_MSG │ │
15899 └───────────────────┴────────────────────────┴────────────────┘
15900 │cxx_thread_local │ <PREFIX>_THREAD_LOCAL │ thread_local │
15903 └───────────────────┴────────────────────────┴────────────────┘
15904 A use-case which arises with such deprecation macros is the deprecation
15906 of an entire library. In that case, all public API in the library may
15907 be decorated with the <PREFIX>_DEPRECATED macro. This results in very
15908 noisy build output when building the library itself, so the macro may
15909 be may be defined to empty in that case when building the deprecated
15910 library:
15911 add_library(compat_support ${srcs})
15913 target_compile_definitions(compat_support
15914 PRIVATE
15915 CompatSupport_DEPRECATED=
15916 )
15917
15919 2000-2018 Kitware, Inc. and Contributors
159203.11.4 May 13, 2019 CMAKE-MODULES(7)