| .\" Man page generated from reStructuredText. |
| . |
| .TH "CMAKE-MODULES" "7" "Apr 12, 2022" "3.23.1" "CMake" |
| .SH NAME |
| cmake-modules \- CMake Modules Reference |
| . |
| .nr rst2man-indent-level 0 |
| . |
| .de1 rstReportMargin |
| \\$1 \\n[an-margin] |
| level \\n[rst2man-indent-level] |
| level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] |
| - |
| \\n[rst2man-indent0] |
| \\n[rst2man-indent1] |
| \\n[rst2man-indent2] |
| .. |
| .de1 INDENT |
| .\" .rstReportMargin pre: |
| . RS \\$1 |
| . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] |
| . nr rst2man-indent-level +1 |
| .\" .rstReportMargin post: |
| .. |
| .de UNINDENT |
| . RE |
| .\" indent \\n[an-margin] |
| .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] |
| .nr rst2man-indent-level -1 |
| .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] |
| .in \\n[rst2man-indent\\n[rst2man-indent-level]]u |
| .. |
| .sp |
| The modules listed here are part of the CMake distribution. |
| Projects may provide further modules; their location(s) |
| can be specified in the \fBCMAKE_MODULE_PATH\fP variable. |
| .SH UTILITY MODULES |
| .sp |
| These modules are loaded using the \fBinclude()\fP command. |
| .SS AndroidTestUtilities |
| .sp |
| New in version 3.7. |
| |
| .sp |
| Create a test that automatically loads specified data onto an Android device. |
| .SS Introduction |
| .sp |
| Use this module to push data needed for testing an Android device behavior |
| onto a connected Android device. The module will accept files and libraries as |
| well as separate destinations for each. It will create a test that loads the |
| files into a device object store and link to them from the specified |
| destination. The files are only uploaded if they are not already in the object |
| store. |
| .sp |
| For example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| include(AndroidTestUtilities) |
| android_add_test_data( |
| example_setup_test |
| FILES <files>... |
| LIBS <libs>... |
| DEVICE_TEST_DIR "/data/local/tests/example" |
| DEVICE_OBJECT_STORE "/sdcard/.ExternalData/SHA" |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| At build time a test named "example_setup_test" will be created. Run this test |
| on the command line with \fBctest(1)\fP to load the data onto the Android |
| device. |
| .SS Module Functions |
| .INDENT 0.0 |
| .TP |
| .B android_add_test_data |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| android_add_test_data(<test\-name> |
| [FILES <files>...] [FILES_DEST <device\-dir>] |
| [LIBS <libs>...] [LIBS_DEST <device\-dir>] |
| [DEVICE_OBJECT_STORE <device\-dir>] |
| [DEVICE_TEST_DIR <device\-dir>] |
| [NO_LINK_REGEX <strings>...] |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The \fBandroid_add_test_data\fP function is used to copy files and libraries |
| needed to run project\-specific tests. On the host operating system, this is |
| done at build time. For on\-device testing, the files are loaded onto the |
| device by the manufactured test at run time. |
| .sp |
| This function accepts the following named parameters: |
| .INDENT 7.0 |
| .TP |
| .B \fBFILES <files>...\fP |
| zero or more files needed for testing |
| .TP |
| .B \fBLIBS <libs>...\fP |
| zero or more libraries needed for testing |
| .TP |
| .B \fBFILES_DEST <device\-dir>\fP |
| absolute path where the data files are expected to be |
| .TP |
| .B \fBLIBS_DEST <device\-dir>\fP |
| absolute path where the libraries are expected to be |
| .TP |
| .B \fBDEVICE_OBJECT_STORE <device\-dir>\fP |
| absolute path to the location where the data is stored on\-device |
| .TP |
| .B \fBDEVICE_TEST_DIR <device\-dir>\fP |
| absolute path to the root directory of the on\-device test location |
| .TP |
| .B \fBNO_LINK_REGEX <strings>...\fP |
| list of regex strings matching the names of files that should be |
| copied from the object store to the testing directory |
| .UNINDENT |
| .UNINDENT |
| .SS BundleUtilities |
| .sp |
| Functions to help assemble a standalone bundle application. |
| .sp |
| A collection of CMake utility functions useful for dealing with \fB\&.app\fP |
| bundles on the Mac and bundle\-like directories on any OS. |
| .sp |
| The following functions are provided by this module: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| fixup_bundle |
| copy_and_fixup_bundle |
| verify_app |
| get_bundle_main_executable |
| get_dotapp_dir |
| get_bundle_and_executable |
| get_bundle_all_executables |
| get_item_key |
| get_item_rpaths |
| clear_bundle_keys |
| set_bundle_key_values |
| get_bundle_keys |
| copy_resolved_item_into_bundle |
| copy_resolved_framework_into_bundle |
| fixup_bundle_item |
| verify_bundle_prerequisites |
| verify_bundle_symlinks |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Requires CMake 2.6 or greater because it uses function, break and |
| \fBPARENT_SCOPE\fP\&. Also depends on \fBGetPrerequisites.cmake\fP\&. |
| .sp |
| DO NOT USE THESE FUNCTIONS AT CONFIGURE TIME (from \fBCMakeLists.txt\fP)! |
| Instead, invoke them from an \fBinstall(CODE)\fP or |
| \fBinstall(SCRIPT)\fP rule. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| fixup_bundle(<app> <libs> <dirs>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Fix up \fB<app>\fP bundle in\-place and make it standalone, such that it can be |
| drag\-n\-drop copied to another machine and run on that machine as long |
| as all of the system libraries are compatible. |
| .sp |
| If you pass plugins to \fBfixup_bundle\fP as the libs parameter, you should |
| install them or copy them into the bundle before calling \fBfixup_bundle\fP\&. |
| The \fB<libs>\fP parameter is a list of libraries that must be fixed up, but |
| that cannot be determined by \fBotool\fP output analysis (i.e. \fBplugins\fP). |
| .sp |
| Gather all the keys for all the executables and libraries in a bundle, |
| and then, for each key, copy each prerequisite into the bundle. Then |
| fix each one up according to its own list of prerequisites. |
| .sp |
| Then clear all the keys and call \fBverify_app\fP on the final bundle to |
| ensure that it is truly standalone. |
| .sp |
| New in version 3.6: As an optional parameter (\fBIGNORE_ITEM\fP) a list of file names can be passed, |
| which are then ignored |
| (e.g. \fBIGNORE_ITEM "vcredist_x86.exe;vcredist_x64.exe"\fP). |
| |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| copy_and_fixup_bundle(<src> <dst> <libs> <dirs>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Makes a copy of the bundle \fB<src>\fP at location \fB<dst>\fP and then fixes up |
| the new copied bundle in\-place at \fB<dst>\fP\&. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| verify_app(<app>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Verifies that an application \fB<app>\fP appears valid based on running |
| analysis tools on it. Calls \fBmessage(FATAL_ERROR)\fP if the application |
| is not verified. |
| .sp |
| New in version 3.6: As an optional parameter (\fBIGNORE_ITEM\fP) a list of file names can be passed, |
| which are then ignored |
| (e.g. \fBIGNORE_ITEM "vcredist_x86.exe;vcredist_x64.exe"\fP) |
| |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| get_bundle_main_executable(<bundle> <result_var>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The result will be the full path name of the bundle\(aqs main executable |
| file or an \fBerror:\fP prefixed string if it could not be determined. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| get_dotapp_dir(<exe> <dotapp_dir_var>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Returns the nearest parent dir whose name ends with \fB\&.app\fP given the |
| full path to an executable. If there is no such parent dir, then |
| simply return the dir containing the executable. |
| .sp |
| The returned directory may or may not exist. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| get_bundle_and_executable(<app> <bundle_var> <executable_var> <valid_var>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Takes either a \fB\&.app\fP directory name or the name of an executable |
| nested inside a \fB\&.app\fP directory and returns the path to the \fB\&.app\fP |
| directory in \fB<bundle_var>\fP and the path to its main executable in |
| \fB<executable_var>\fP\&. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| get_bundle_all_executables(<bundle> <exes_var>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Scans \fB<bundle>\fP bundle recursively for all \fB<exes_var>\fP executable |
| files and accumulates them into a variable. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| get_item_key(<item> <key_var>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Given \fB<item>\fP file name, generate \fB<key_var>\fP key that should be unique |
| considering the set of libraries that need copying or fixing up to |
| make a bundle standalone. This is essentially the file name including |
| extension with \fB\&.\fP replaced by \fB_\fP |
| .sp |
| This key is used as a prefix for CMake variables so that we can |
| associate a set of variables with a given item based on its key. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| clear_bundle_keys(<keys_var>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Loop over the \fB<keys_var>\fP list of keys, clearing all the variables |
| associated with each key. After the loop, clear the list of keys itself. |
| .sp |
| Caller of \fBget_bundle_keys\fP should call \fBclear_bundle_keys\fP when done with |
| list of keys. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_bundle_key_values(<keys_var> <context> <item> <exepath> <dirs> |
| <copyflag> [<rpaths>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Add \fB<keys_var>\fP key to the list (if necessary) for the given item. |
| If added, also set all the variables associated with that key. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| get_bundle_keys(<app> <libs> <dirs> <keys_var>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Loop over all the executable and library files within \fB<app>\fP bundle (and |
| given as extra \fB<libs>\fP) and accumulate a list of keys representing |
| them. Set values associated with each key such that we can loop over |
| all of them and copy prerequisite libs into the bundle and then do |
| appropriate \fBinstall_name_tool\fP fixups. |
| .sp |
| New in version 3.6: As an optional parameter (\fBIGNORE_ITEM\fP) a list of file names can be passed, |
| which are then ignored |
| (e.g. \fBIGNORE_ITEM "vcredist_x86.exe;vcredist_x64.exe"\fP) |
| |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| copy_resolved_item_into_bundle(<resolved_item> <resolved_embedded_item>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Copy a resolved item into the bundle if necessary. |
| Copy is not necessary, if the \fB<resolved_item>\fP is "the same as" the |
| \fB<resolved_embedded_item>\fP\&. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| copy_resolved_framework_into_bundle(<resolved_item> <resolved_embedded_item>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Copy a resolved framework into the bundle if necessary. |
| Copy is not necessary, if the \fB<resolved_item>\fP is "the same as" the |
| \fB<resolved_embedded_item>\fP\&. |
| .sp |
| By default, \fBBU_COPY_FULL_FRAMEWORK_CONTENTS\fP is not set. If you want |
| full frameworks embedded in your bundles, set |
| \fBBU_COPY_FULL_FRAMEWORK_CONTENTS\fP to \fBON\fP before calling fixup_bundle. By |
| default, \fBCOPY_RESOLVED_FRAMEWORK_INTO_BUNDLE\fP copies the framework |
| dylib itself plus the framework \fBResources\fP directory. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| fixup_bundle_item(<resolved_embedded_item> <exepath> <dirs>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Get the direct/non\-system prerequisites of the \fB<resolved_embedded_item>\fP\&. |
| For each prerequisite, change the way it is referenced to the value of |
| the \fB_EMBEDDED_ITEM\fP keyed variable for that prerequisite. (Most likely |
| changing to an \fB@executable_path\fP style reference.) |
| .sp |
| This function requires that the \fB<resolved_embedded_item>\fP be \fBinside\fP |
| the bundle already. In other words, if you pass plugins to \fBfixup_bundle\fP |
| as the libs parameter, you should install them or copy them into the |
| bundle before calling \fBfixup_bundle\fP\&. The \fBlibs\fP parameter is a list of |
| libraries that must be fixed up, but that cannot be determined by |
| otool output analysis. (i.e., \fBplugins\fP) |
| .sp |
| Also, change the id of the item being fixed up to its own |
| \fB_EMBEDDED_ITEM\fP value. |
| .sp |
| Accumulate changes in a local variable and make \fIone\fP call to |
| \fBinstall_name_tool\fP at the end of the function with all the changes at |
| once. |
| .sp |
| If the \fBBU_CHMOD_BUNDLE_ITEMS\fP variable is set then bundle items will be |
| marked writable before \fBinstall_name_tool\fP tries to change them. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| verify_bundle_prerequisites(<bundle> <result_var> <info_var>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Verifies that the sum of all prerequisites of all files inside the |
| bundle are contained within the bundle or are \fBsystem\fP libraries, |
| presumed to exist everywhere. |
| .sp |
| New in version 3.6: As an optional parameter (\fBIGNORE_ITEM\fP) a list of file names can be passed, |
| which are then ignored |
| (e.g. \fBIGNORE_ITEM "vcredist_x86.exe;vcredist_x64.exe"\fP) |
| |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| verify_bundle_symlinks(<bundle> <result_var> <info_var>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Verifies that any symlinks found in the \fB<bundle>\fP bundle point to other files |
| that are already also in the bundle... Anything that points to an |
| external file causes this function to fail the verification. |
| .SS CheckCCompilerFlag |
| .sp |
| Check whether the C compiler supports a given flag. |
| .INDENT 0.0 |
| .TP |
| .B check_c_compiler_flag |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| check_c_compiler_flag(<flag> <var>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Check that the \fB<flag>\fP is accepted by the compiler without |
| a diagnostic. Stores the result in an internal cache entry |
| named \fB<var>\fP\&. |
| .UNINDENT |
| .sp |
| This command temporarily sets the \fBCMAKE_REQUIRED_DEFINITIONS\fP variable |
| and calls the \fBcheck_c_source_compiles\fP macro from the |
| \fBCheckCSourceCompiles\fP module. See documentation of that |
| module for a listing of variables that can otherwise modify the build. |
| .sp |
| A positive result from this check indicates only that the compiler did not |
| issue a diagnostic message when given the flag. Whether the flag has any |
| effect or even a specific one is beyond the scope of this module. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| Since the \fBtry_compile()\fP command forwards flags from variables |
| like \fBCMAKE_C_FLAGS\fP, unknown flags |
| in such variables may cause a false negative for this check. |
| .UNINDENT |
| .UNINDENT |
| .SS CheckCompilerFlag |
| .sp |
| New in version 3.19. |
| |
| .sp |
| Check whether the compiler supports a given flag. |
| .INDENT 0.0 |
| .TP |
| .B check_compiler_flag |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| check_compiler_flag(<lang> <flag> <var>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Check that the \fB<flag>\fP is accepted by the compiler without a diagnostic. |
| Stores the result in an internal cache entry named \fB<var>\fP\&. |
| .sp |
| This command temporarily sets the \fBCMAKE_REQUIRED_DEFINITIONS\fP variable |
| and calls the \fBcheck_source_compiles(<LANG>)\fP function from the |
| \fBCheckSourceCompiles\fP module. See documentation of that |
| module for a listing of variables that can otherwise modify the build. |
| .sp |
| A positive result from this check indicates only that the compiler did not |
| issue a diagnostic message when given the flag. Whether the flag has any |
| effect or even a specific one is beyond the scope of this module. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| Since the \fBtry_compile()\fP command forwards flags from variables |
| like \fBCMAKE_<LANG>_FLAGS\fP, unknown flags |
| in such variables may cause a false negative for this check. |
| .UNINDENT |
| .UNINDENT |
| .SS CheckCSourceCompiles |
| .sp |
| Check if given C source compiles and links into an executable. |
| .INDENT 0.0 |
| .TP |
| .B check_c_source_compiles |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| check_c_source_compiles(<code> <resultVar> |
| [FAIL_REGEX <regex1> [<regex2>...]]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Check that the source supplied in \fB<code>\fP can be compiled as a C source |
| file and linked as an executable (so it must contain at least a \fBmain()\fP |
| function). The result will be stored in the internal cache variable specified |
| by \fB<resultVar>\fP, with a boolean true value for success and boolean false |
| for failure. If \fBFAIL_REGEX\fP is provided, then failure is determined by |
| checking if anything in the output matches any of the specified regular |
| expressions. |
| .sp |
| The underlying check is performed by the \fBtry_compile()\fP command. The |
| compile and link commands can be influenced by setting any of the following |
| variables prior to calling \fBcheck_c_source_compiles()\fP: |
| .INDENT 7.0 |
| .TP |
| .B \fBCMAKE_REQUIRED_FLAGS\fP |
| Additional flags to pass to the compiler. Note that the contents of |
| \fBCMAKE_C_FLAGS\fP and its associated |
| configuration\-specific variable are automatically added to the compiler |
| command before the contents of \fBCMAKE_REQUIRED_FLAGS\fP\&. |
| .TP |
| .B \fBCMAKE_REQUIRED_DEFINITIONS\fP |
| A ;\-list of compiler definitions of the form |
| \fB\-DFOO\fP or \fB\-DFOO=bar\fP\&. A definition for the name specified by |
| \fB<resultVar>\fP will also be added automatically. |
| .TP |
| .B \fBCMAKE_REQUIRED_INCLUDES\fP |
| A ;\-list of header search paths to pass to |
| the compiler. These will be the only header search paths used by |
| \fBtry_compile()\fP, i.e. the contents of the \fBINCLUDE_DIRECTORIES\fP |
| directory property will be ignored. |
| .TP |
| .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP |
| New in version 3.14. |
| |
| .sp |
| A ;\-list of options to add to the link |
| command (see \fBtry_compile()\fP for further details). |
| .TP |
| .B \fBCMAKE_REQUIRED_LIBRARIES\fP |
| A ;\-list of libraries to add to the link |
| command. These can be the name of system libraries or they can be |
| Imported Targets (see \fBtry_compile()\fP for |
| further details). |
| .TP |
| .B \fBCMAKE_REQUIRED_QUIET\fP |
| New in version 3.1. |
| |
| .sp |
| If this variable evaluates to a boolean true value, all status messages |
| associated with the check will be suppressed. |
| .UNINDENT |
| .sp |
| The check is only performed once, with the result cached in the variable |
| named by \fB<resultVar>\fP\&. Every subsequent CMake run will re\-use this cached |
| value rather than performing the check again, even if the \fB<code>\fP changes. |
| In order to force the check to be re\-evaluated, the variable named by |
| \fB<resultVar>\fP must be manually removed from the cache. |
| .UNINDENT |
| .SS CheckCSourceRuns |
| .sp |
| Check if given C source compiles and links into an executable and can |
| subsequently be run. |
| .INDENT 0.0 |
| .TP |
| .B check_c_source_runs |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| check_c_source_runs(<code> <resultVar>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Check that the source supplied in \fB<code>\fP can be compiled as a C source |
| file, linked as an executable and then run. The \fB<code>\fP must contain at |
| least a \fBmain()\fP function. If the \fB<code>\fP could be built and run |
| successfully, the internal cache variable specified by \fB<resultVar>\fP will |
| be set to 1, otherwise it will be set to an value that evaluates to boolean |
| false (e.g. an empty string or an error message). |
| .sp |
| The underlying check is performed by the \fBtry_run()\fP command. The |
| compile and link commands can be influenced by setting any of the following |
| variables prior to calling \fBcheck_c_source_runs()\fP: |
| .INDENT 7.0 |
| .TP |
| .B \fBCMAKE_REQUIRED_FLAGS\fP |
| Additional flags to pass to the compiler. Note that the contents of |
| \fBCMAKE_C_FLAGS\fP and its associated |
| configuration\-specific variable are automatically added to the compiler |
| command before the contents of \fBCMAKE_REQUIRED_FLAGS\fP\&. |
| .TP |
| .B \fBCMAKE_REQUIRED_DEFINITIONS\fP |
| A ;\-list of compiler definitions of the form |
| \fB\-DFOO\fP or \fB\-DFOO=bar\fP\&. A definition for the name specified by |
| \fB<resultVar>\fP will also be added automatically. |
| .TP |
| .B \fBCMAKE_REQUIRED_INCLUDES\fP |
| A ;\-list of header search paths to pass to |
| the compiler. These will be the only header search paths used by |
| \fBtry_run()\fP, i.e. the contents of the \fBINCLUDE_DIRECTORIES\fP |
| directory property will be ignored. |
| .TP |
| .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP |
| New in version 3.14. |
| |
| .sp |
| A ;\-list of options to add to the link |
| command (see \fBtry_run()\fP for further details). |
| .TP |
| .B \fBCMAKE_REQUIRED_LIBRARIES\fP |
| A ;\-list of libraries to add to the link |
| command. These can be the name of system libraries or they can be |
| Imported Targets (see \fBtry_run()\fP for |
| further details). |
| .TP |
| .B \fBCMAKE_REQUIRED_QUIET\fP |
| New in version 3.1. |
| |
| .sp |
| If this variable evaluates to a boolean true value, all status messages |
| associated with the check will be suppressed. |
| .UNINDENT |
| .sp |
| The check is only performed once, with the result cached in the variable |
| named by \fB<resultVar>\fP\&. Every subsequent CMake run will re\-use this cached |
| value rather than performing the check again, even if the \fB<code>\fP changes. |
| In order to force the check to be re\-evaluated, the variable named by |
| \fB<resultVar>\fP must be manually removed from the cache. |
| .UNINDENT |
| .SS CheckCXXCompilerFlag |
| .sp |
| Check whether the CXX compiler supports a given flag. |
| .INDENT 0.0 |
| .TP |
| .B check_cxx_compiler_flag |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| check_cxx_compiler_flag(<flag> <var>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Check that the \fB<flag>\fP is accepted by the compiler without |
| a diagnostic. Stores the result in an internal cache entry |
| named \fB<var>\fP\&. |
| .UNINDENT |
| .sp |
| This command temporarily sets the \fBCMAKE_REQUIRED_DEFINITIONS\fP variable |
| and calls the \fBcheck_cxx_source_compiles\fP macro from the |
| \fBCheckCXXSourceCompiles\fP module. See documentation of that |
| module for a listing of variables that can otherwise modify the build. |
| .sp |
| A positive result from this check indicates only that the compiler did not |
| issue a diagnostic message when given the flag. Whether the flag has any |
| effect or even a specific one is beyond the scope of this module. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| Since the \fBtry_compile()\fP command forwards flags from variables |
| like \fBCMAKE_CXX_FLAGS\fP, unknown flags |
| in such variables may cause a false negative for this check. |
| .UNINDENT |
| .UNINDENT |
| .SS CheckCXXSourceCompiles |
| .sp |
| Check if given C++ source compiles and links into an executable. |
| .INDENT 0.0 |
| .TP |
| .B check_cxx_source_compiles |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| check_cxx_source_compiles(<code> <resultVar> |
| [FAIL_REGEX <regex1> [<regex2>...]]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Check that the source supplied in \fB<code>\fP can be compiled as a C++ source |
| file and linked as an executable (so it must contain at least a \fBmain()\fP |
| function). The result will be stored in the internal cache variable specified |
| by \fB<resultVar>\fP, with a boolean true value for success and boolean false |
| for failure. If \fBFAIL_REGEX\fP is provided, then failure is determined by |
| checking if anything in the output matches any of the specified regular |
| expressions. |
| .sp |
| The underlying check is performed by the \fBtry_compile()\fP command. The |
| compile and link commands can be influenced by setting any of the following |
| variables prior to calling \fBcheck_cxx_source_compiles()\fP: |
| .INDENT 7.0 |
| .TP |
| .B \fBCMAKE_REQUIRED_FLAGS\fP |
| Additional flags to pass to the compiler. Note that the contents of |
| \fBCMAKE_CXX_FLAGS\fP and its associated |
| configuration\-specific variable are automatically added to the compiler |
| command before the contents of \fBCMAKE_REQUIRED_FLAGS\fP\&. |
| .TP |
| .B \fBCMAKE_REQUIRED_DEFINITIONS\fP |
| A ;\-list of compiler definitions of the form |
| \fB\-DFOO\fP or \fB\-DFOO=bar\fP\&. A definition for the name specified by |
| \fB<resultVar>\fP will also be added automatically. |
| .TP |
| .B \fBCMAKE_REQUIRED_INCLUDES\fP |
| A ;\-list of header search paths to pass to |
| the compiler. These will be the only header search paths used by |
| \fBtry_compile()\fP, i.e. the contents of the \fBINCLUDE_DIRECTORIES\fP |
| directory property will be ignored. |
| .TP |
| .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP |
| New in version 3.14. |
| |
| .sp |
| A ;\-list of options to add to the link |
| command (see \fBtry_compile()\fP for further details). |
| .TP |
| .B \fBCMAKE_REQUIRED_LIBRARIES\fP |
| A ;\-list of libraries to add to the link |
| command. These can be the name of system libraries or they can be |
| Imported Targets (see \fBtry_compile()\fP for |
| further details). |
| .TP |
| .B \fBCMAKE_REQUIRED_QUIET\fP |
| New in version 3.1. |
| |
| .sp |
| If this variable evaluates to a boolean true value, all status messages |
| associated with the check will be suppressed. |
| .UNINDENT |
| .sp |
| The check is only performed once, with the result cached in the variable |
| named by \fB<resultVar>\fP\&. Every subsequent CMake run will re\-use this cached |
| value rather than performing the check again, even if the \fB<code>\fP changes. |
| In order to force the check to be re\-evaluated, the variable named by |
| \fB<resultVar>\fP must be manually removed from the cache. |
| .UNINDENT |
| .SS CheckCXXSourceRuns |
| .sp |
| Check if given C++ source compiles and links into an executable and can |
| subsequently be run. |
| .INDENT 0.0 |
| .TP |
| .B check_cxx_source_runs |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| check_cxx_source_runs(<code> <resultVar>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Check that the source supplied in \fB<code>\fP can be compiled as a C++ source |
| file, linked as an executable and then run. The \fB<code>\fP must contain at |
| least a \fBmain()\fP function. If the \fB<code>\fP could be built and run |
| successfully, the internal cache variable specified by \fB<resultVar>\fP will |
| be set to 1, otherwise it will be set to an value that evaluates to boolean |
| false (e.g. an empty string or an error message). |
| .sp |
| The underlying check is performed by the \fBtry_run()\fP command. The |
| compile and link commands can be influenced by setting any of the following |
| variables prior to calling \fBcheck_cxx_source_runs()\fP: |
| .INDENT 7.0 |
| .TP |
| .B \fBCMAKE_REQUIRED_FLAGS\fP |
| Additional flags to pass to the compiler. Note that the contents of |
| \fBCMAKE_CXX_FLAGS\fP and its associated |
| configuration\-specific variable are automatically added to the compiler |
| command before the contents of \fBCMAKE_REQUIRED_FLAGS\fP\&. |
| .TP |
| .B \fBCMAKE_REQUIRED_DEFINITIONS\fP |
| A ;\-list of compiler definitions of the form |
| \fB\-DFOO\fP or \fB\-DFOO=bar\fP\&. A definition for the name specified by |
| \fB<resultVar>\fP will also be added automatically. |
| .TP |
| .B \fBCMAKE_REQUIRED_INCLUDES\fP |
| A ;\-list of header search paths to pass to |
| the compiler. These will be the only header search paths used by |
| \fBtry_run()\fP, i.e. the contents of the \fBINCLUDE_DIRECTORIES\fP |
| directory property will be ignored. |
| .TP |
| .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP |
| New in version 3.14. |
| |
| .sp |
| A ;\-list of options to add to the link |
| command (see \fBtry_run()\fP for further details). |
| .TP |
| .B \fBCMAKE_REQUIRED_LIBRARIES\fP |
| A ;\-list of libraries to add to the link |
| command. These can be the name of system libraries or they can be |
| Imported Targets (see \fBtry_run()\fP for |
| further details). |
| .TP |
| .B \fBCMAKE_REQUIRED_QUIET\fP |
| New in version 3.1. |
| |
| .sp |
| If this variable evaluates to a boolean true value, all status messages |
| associated with the check will be suppressed. |
| .UNINDENT |
| .sp |
| The check is only performed once, with the result cached in the variable |
| named by \fB<resultVar>\fP\&. Every subsequent CMake run will re\-use this cached |
| value rather than performing the check again, even if the \fB<code>\fP changes. |
| In order to force the check to be re\-evaluated, the variable named by |
| \fB<resultVar>\fP must be manually removed from the cache. |
| .UNINDENT |
| .SS CheckCXXSymbolExists |
| .sp |
| Check if a symbol exists as a function, variable, or macro in \fBC++\fP\&. |
| .INDENT 0.0 |
| .TP |
| .B check_cxx_symbol_exists |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| check_cxx_symbol_exists(<symbol> <files> <variable>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Check that the \fB<symbol>\fP is available after including given header |
| \fB<files>\fP and store the result in a \fB<variable>\fP\&. Specify the list of |
| files in one argument as a semicolon\-separated list. |
| \fBcheck_cxx_symbol_exists()\fP can be used to check for symbols as seen by |
| the C++ compiler, as opposed to \fBcheck_symbol_exists()\fP, which always |
| uses the \fBC\fP compiler. |
| .sp |
| If the header files define the symbol as a macro it is considered |
| available and assumed to work. If the header files declare the symbol |
| as a function or variable then the symbol must also be available for |
| linking. If the symbol is a type, enum value, or C++ template it will |
| not be recognized: consider using the \fBCheckTypeSize\fP |
| or \fBCheckSourceCompiles\fP module instead. |
| .UNINDENT |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| This command is unreliable when \fB<symbol>\fP is (potentially) an overloaded |
| function. Since there is no reliable way to predict whether a given function |
| in the system environment may be defined as an overloaded function or may be |
| an overloaded function on other systems or will become so in the future, it |
| is generally advised to use the \fBCheckCXXSourceCompiles\fP module for |
| checking any function symbol (unless somehow you surely know the checked |
| function is not overloaded on other systems or will not be so in the |
| future). |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The following variables may be set before calling this macro to modify |
| the way the check is run: |
| .INDENT 0.0 |
| .TP |
| .B \fBCMAKE_REQUIRED_FLAGS\fP |
| string of compile command line flags. |
| .TP |
| .B \fBCMAKE_REQUIRED_DEFINITIONS\fP |
| a ;\-list of macros to define (\-DFOO=bar). |
| .TP |
| .B \fBCMAKE_REQUIRED_INCLUDES\fP |
| a ;\-list of header search paths to pass to |
| the compiler. |
| .TP |
| .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP |
| New in version 3.14: a ;\-list of options to add to the link command. |
| |
| .TP |
| .B \fBCMAKE_REQUIRED_LIBRARIES\fP |
| a ;\-list of libraries to add to the link |
| command. See policy \fBCMP0075\fP\&. |
| .TP |
| .B \fBCMAKE_REQUIRED_QUIET\fP |
| New in version 3.1: execute quietly without messages. |
| |
| .UNINDENT |
| .sp |
| For example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| include(CheckCXXSymbolExists) |
| |
| # Check for macro SEEK_SET |
| check_cxx_symbol_exists(SEEK_SET "cstdio" HAVE_SEEK_SET) |
| # Check for function std::fopen |
| check_cxx_symbol_exists(std::fopen "cstdio" HAVE_STD_FOPEN) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS CheckFortranCompilerFlag |
| .sp |
| New in version 3.3. |
| |
| .sp |
| Check whether the Fortran compiler supports a given flag. |
| .INDENT 0.0 |
| .TP |
| .B check_fortran_compiler_flag |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| check_fortran_compiler_flag(<flag> <var>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Check that the \fB<flag>\fP is accepted by the compiler without |
| a diagnostic. Stores the result in an internal cache entry |
| named \fB<var>\fP\&. |
| .UNINDENT |
| .sp |
| This command temporarily sets the \fBCMAKE_REQUIRED_DEFINITIONS\fP variable |
| and calls the \fBcheck_fortran_source_compiles\fP macro from the |
| \fBCheckFortranSourceCompiles\fP module. See documentation of that |
| module for a listing of variables that can otherwise modify the build. |
| .sp |
| A positive result from this check indicates only that the compiler did not |
| issue a diagnostic message when given the flag. Whether the flag has any |
| effect or even a specific one is beyond the scope of this module. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| Since the \fBtry_compile()\fP command forwards flags from variables |
| like \fBCMAKE_Fortran_FLAGS\fP, unknown flags |
| in such variables may cause a false negative for this check. |
| .UNINDENT |
| .UNINDENT |
| .SS CheckFortranFunctionExists |
| .sp |
| Check if a Fortran function exists. |
| .INDENT 0.0 |
| .TP |
| .B CHECK_FORTRAN_FUNCTION_EXISTS |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| CHECK_FORTRAN_FUNCTION_EXISTS(<function> <result>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| where |
| .INDENT 7.0 |
| .TP |
| .B \fB<function>\fP |
| the name of the Fortran function |
| .TP |
| .B \fB<result>\fP |
| variable to store the result; will be created as an internal cache variable. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| This command does not detect functions in Fortran modules. In general it is |
| recommended to use \fBCheckSourceCompiles\fP instead to determine if a |
| Fortran function or subroutine is available. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The following variables may be set before calling this macro to modify |
| the way the check is run: |
| .INDENT 0.0 |
| .TP |
| .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP |
| New in version 3.14: A ;\-list of options to add to the link |
| command (see \fBtry_compile()\fP for further details). |
| |
| .TP |
| .B \fBCMAKE_REQUIRED_LIBRARIES\fP |
| A ;\-list of libraries to add to the link |
| command. These can be the name of system libraries or they can be |
| Imported Targets (see \fBtry_compile()\fP for |
| further details). |
| .UNINDENT |
| .SS CheckFortranSourceCompiles |
| .sp |
| New in version 3.1. |
| |
| .sp |
| Check if given Fortran source compiles and links into an executable. |
| .INDENT 0.0 |
| .TP |
| .B check_fortran_source_compiles |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| check_fortran_source_compiles(<code> <resultVar> |
| [FAIL_REGEX <regex>...] |
| [SRC_EXT <extension>] |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Checks that the source supplied in \fB<code>\fP can be compiled as a Fortran |
| source file and linked as an executable. The \fB<code>\fP must be a Fortran program |
| containing at least an \fBend\fP statement\-\-for example: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| check_fortran_source_compiles("character :: b; error stop b; end" F2018ESTOPOK SRC_EXT F90) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This command can help avoid costly build processes when a compiler lacks support |
| for a necessary feature, or a particular vendor library is not compatible with |
| the Fortran compiler version being used. This generate\-time check may advise the |
| user of such before the main build process. See also the |
| \fBcheck_fortran_source_runs()\fP command to actually run the compiled code. |
| .sp |
| The result will be stored in the internal cache |
| variable \fB<resultVar>\fP, with a boolean true value for success and boolean |
| false for failure. |
| .sp |
| If \fBFAIL_REGEX\fP is provided, then failure is determined by checking |
| if anything in the output matches any of the specified regular expressions. |
| .sp |
| By default, the test source file will be given a \fB\&.F\fP file extension. The |
| \fBSRC_EXT\fP option can be used to override this with \fB\&.<extension>\fP instead\-\- |
| \fB\&.F90\fP is a typical choice. |
| .sp |
| The underlying check is performed by the \fBtry_compile()\fP command. The |
| compile and link commands can be influenced by setting any of the following |
| variables prior to calling \fBcheck_fortran_source_compiles()\fP: |
| .INDENT 7.0 |
| .TP |
| .B \fBCMAKE_REQUIRED_FLAGS\fP |
| Additional flags to pass to the compiler. Note that the contents of |
| \fBCMAKE_Fortran_FLAGS\fP and its associated |
| configuration\-specific variable are automatically added to the compiler |
| command before the contents of \fBCMAKE_REQUIRED_FLAGS\fP\&. |
| .TP |
| .B \fBCMAKE_REQUIRED_DEFINITIONS\fP |
| A ;\-list of compiler definitions of the form |
| \fB\-DFOO\fP or \fB\-DFOO=bar\fP\&. A definition for the name specified by |
| \fB<resultVar>\fP will also be added automatically. |
| .TP |
| .B \fBCMAKE_REQUIRED_INCLUDES\fP |
| A ;\-list of header search paths to pass to |
| the compiler. These will be the only header search paths used by |
| \fBtry_compile()\fP, i.e. the contents of the \fBINCLUDE_DIRECTORIES\fP |
| directory property will be ignored. |
| .TP |
| .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP |
| New in version 3.14. |
| |
| .sp |
| A ;\-list of options to add to the link |
| command (see \fBtry_compile()\fP for further details). |
| .TP |
| .B \fBCMAKE_REQUIRED_LIBRARIES\fP |
| A ;\-list of libraries to add to the link |
| command. These can be the name of system libraries or they can be |
| Imported Targets (see \fBtry_compile()\fP for |
| further details). |
| .TP |
| .B \fBCMAKE_REQUIRED_QUIET\fP |
| If this variable evaluates to a boolean true value, all status messages |
| associated with the check will be suppressed. |
| .UNINDENT |
| .sp |
| The check is only performed once, with the result cached in the variable |
| named by \fB<resultVar>\fP\&. Every subsequent CMake run will re\-use this cached |
| value rather than performing the check again, even if the \fB<code>\fP changes. |
| In order to force the check to be re\-evaluated, the variable named by |
| \fB<resultVar>\fP must be manually removed from the cache. |
| .UNINDENT |
| .SS CheckFortranSourceRuns |
| .sp |
| New in version 3.14. |
| |
| .sp |
| Check if given Fortran source compiles and links into an executable and can |
| subsequently be run. |
| .INDENT 0.0 |
| .TP |
| .B check_fortran_source_runs |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| check_fortran_source_runs(<code> <resultVar> |
| [SRC_EXT <extension>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Check that the source supplied in \fB<code>\fP can be compiled as a Fortran source |
| file, linked as an executable and then run. The \fB<code>\fP must be a Fortran program |
| containing at least an \fBend\fP statement\-\-for example: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| check_fortran_source_runs("real :: x[*]; call co_sum(x); end" F2018coarrayOK) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This command can help avoid costly build processes when a compiler lacks support |
| for a necessary feature, or a particular vendor library is not compatible with |
| the Fortran compiler version being used. Some of these failures only occur at runtime |
| instead of linktime, and a trivial runtime example can catch the issue before the |
| main build process. |
| .sp |
| If the \fB<code>\fP could be built and run |
| successfully, the internal cache variable specified by \fB<resultVar>\fP will |
| be set to 1, otherwise it will be set to an value that evaluates to boolean |
| false (e.g. an empty string or an error message). |
| .sp |
| By default, the test source file will be given a \fB\&.F90\fP file extension. The |
| \fBSRC_EXT\fP option can be used to override this with \fB\&.<extension>\fP instead. |
| .sp |
| The underlying check is performed by the \fBtry_run()\fP command. The |
| compile and link commands can be influenced by setting any of the following |
| variables prior to calling \fBcheck_fortran_source_runs()\fP: |
| .INDENT 7.0 |
| .TP |
| .B \fBCMAKE_REQUIRED_FLAGS\fP |
| Additional flags to pass to the compiler. Note that the contents of |
| \fBCMAKE_Fortran_FLAGS\fP and its associated |
| configuration\-specific variable are automatically added to the compiler |
| command before the contents of \fBCMAKE_REQUIRED_FLAGS\fP\&. |
| .TP |
| .B \fBCMAKE_REQUIRED_DEFINITIONS\fP |
| A ;\-list of compiler definitions of the form |
| \fB\-DFOO\fP or \fB\-DFOO=bar\fP\&. A definition for the name specified by |
| \fB<resultVar>\fP will also be added automatically. |
| .TP |
| .B \fBCMAKE_REQUIRED_INCLUDES\fP |
| A ;\-list of header search paths to pass to |
| the compiler. These will be the only header search paths used by |
| \fBtry_run()\fP, i.e. the contents of the \fBINCLUDE_DIRECTORIES\fP |
| directory property will be ignored. |
| .TP |
| .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP |
| A ;\-list of options to add to the link |
| command (see \fBtry_run()\fP for further details). |
| .TP |
| .B \fBCMAKE_REQUIRED_LIBRARIES\fP |
| A ;\-list of libraries to add to the link |
| command. These can be the name of system libraries or they can be |
| Imported Targets (see \fBtry_run()\fP for |
| further details). |
| .TP |
| .B \fBCMAKE_REQUIRED_QUIET\fP |
| If this variable evaluates to a boolean true value, all status messages |
| associated with the check will be suppressed. |
| .UNINDENT |
| .sp |
| The check is only performed once, with the result cached in the variable |
| named by \fB<resultVar>\fP\&. Every subsequent CMake run will re\-use this cached |
| value rather than performing the check again, even if the \fB<code>\fP changes. |
| In order to force the check to be re\-evaluated, the variable named by |
| \fB<resultVar>\fP must be manually removed from the cache. |
| .UNINDENT |
| .SS CheckFunctionExists |
| .sp |
| Check if a C function can be linked |
| .INDENT 0.0 |
| .TP |
| .B check_function_exists |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| check_function_exists(<function> <variable>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Checks that the \fB<function>\fP is provided by libraries on the system and store |
| the result in a \fB<variable>\fP, which will be created as an internal |
| cache variable. |
| .UNINDENT |
| .sp |
| The following variables may be set before calling this macro to modify the |
| way the check is run: |
| .INDENT 0.0 |
| .TP |
| .B \fBCMAKE_REQUIRED_FLAGS\fP |
| string of compile command line flags. |
| .TP |
| .B \fBCMAKE_REQUIRED_DEFINITIONS\fP |
| a ;\-list of macros to define (\-DFOO=bar). |
| .TP |
| .B \fBCMAKE_REQUIRED_INCLUDES\fP |
| a ;\-list of header search paths to pass to |
| the compiler. |
| .TP |
| .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP |
| New in version 3.14: a ;\-list of options to add to the link command. |
| |
| .TP |
| .B \fBCMAKE_REQUIRED_LIBRARIES\fP |
| a ;\-list of libraries to add to the link |
| command. See policy \fBCMP0075\fP\&. |
| .TP |
| .B \fBCMAKE_REQUIRED_QUIET\fP |
| New in version 3.1: execute quietly without messages. |
| |
| .UNINDENT |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| Prefer using \fBCheckSymbolExists\fP instead of this module, |
| for the following reasons: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBcheck_function_exists()\fP can\(aqt detect functions that are inlined |
| in headers or specified as a macro. |
| .IP \(bu 2 |
| \fBcheck_function_exists()\fP can\(aqt detect anything in the 32\-bit |
| versions of the Win32 API, because of a mismatch in calling conventions. |
| .IP \(bu 2 |
| \fBcheck_function_exists()\fP only verifies linking, it does not verify |
| that the function is declared in system headers. |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .SS CheckIncludeFileCXX |
| .sp |
| Provides a macro to check if a header file can be included in \fBCXX\fP\&. |
| .INDENT 0.0 |
| .TP |
| .B CHECK_INCLUDE_FILE_CXX |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| CHECK_INCLUDE_FILE_CXX(<include> <variable> [<flags>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Check if the given \fB<include>\fP file may be included in a \fBCXX\fP |
| source file and store the result in an internal cache entry named |
| \fB<variable>\fP\&. The optional third argument may be used to add |
| compilation flags to the check (or use \fBCMAKE_REQUIRED_FLAGS\fP below). |
| .UNINDENT |
| .sp |
| The following variables may be set before calling this macro to modify |
| the way the check is run: |
| .INDENT 0.0 |
| .TP |
| .B \fBCMAKE_REQUIRED_FLAGS\fP |
| string of compile command line flags. |
| .TP |
| .B \fBCMAKE_REQUIRED_DEFINITIONS\fP |
| a ;\-list of macros to define (\-DFOO=bar). |
| .TP |
| .B \fBCMAKE_REQUIRED_INCLUDES\fP |
| a ;\-list of header search paths to pass to |
| the compiler. |
| .TP |
| .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP |
| New in version 3.14: a ;\-list of options to add to the link command. |
| |
| .TP |
| .B \fBCMAKE_REQUIRED_LIBRARIES\fP |
| a ;\-list of libraries to add to the link |
| command. See policy \fBCMP0075\fP\&. |
| .TP |
| .B \fBCMAKE_REQUIRED_QUIET\fP |
| New in version 3.1: execute quietly without messages. |
| |
| .UNINDENT |
| .sp |
| See modules \fBCheckIncludeFile\fP and \fBCheckIncludeFiles\fP |
| to check for one or more \fBC\fP headers. |
| .SS CheckIncludeFile |
| .sp |
| Provides a macro to check if a header file can be included in \fBC\fP\&. |
| .INDENT 0.0 |
| .TP |
| .B CHECK_INCLUDE_FILE |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| CHECK_INCLUDE_FILE(<include> <variable> [<flags>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Check if the given \fB<include>\fP file may be included in a \fBC\fP |
| source file and store the result in an internal cache entry named |
| \fB<variable>\fP\&. The optional third argument may be used to add |
| compilation flags to the check (or use \fBCMAKE_REQUIRED_FLAGS\fP below). |
| .UNINDENT |
| .sp |
| The following variables may be set before calling this macro to modify |
| the way the check is run: |
| .INDENT 0.0 |
| .TP |
| .B \fBCMAKE_REQUIRED_FLAGS\fP |
| string of compile command line flags. |
| .TP |
| .B \fBCMAKE_REQUIRED_DEFINITIONS\fP |
| a ;\-list of macros to define (\-DFOO=bar). |
| .TP |
| .B \fBCMAKE_REQUIRED_INCLUDES\fP |
| a ;\-list of header search paths to pass to |
| the compiler. |
| .TP |
| .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP |
| New in version 3.14: a ;\-list of options to add to the link command. |
| |
| .TP |
| .B \fBCMAKE_REQUIRED_LIBRARIES\fP |
| a ;\-list of libraries to add to the link |
| command. See policy \fBCMP0075\fP\&. |
| .TP |
| .B \fBCMAKE_REQUIRED_QUIET\fP |
| New in version 3.1: execute quietly without messages. |
| |
| .UNINDENT |
| .sp |
| See the \fBCheckIncludeFiles\fP module to check for multiple headers |
| at once. See the \fBCheckIncludeFileCXX\fP module to check for headers |
| using the \fBCXX\fP language. |
| .SS CheckIncludeFiles |
| .sp |
| Provides a macro to check if a list of one or more header files can |
| be included together. |
| .INDENT 0.0 |
| .TP |
| .B CHECK_INCLUDE_FILES |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| CHECK_INCLUDE_FILES("<includes>" <variable> [LANGUAGE <language>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Check if the given \fB<includes>\fP list may be included together |
| in a source file and store the result in an internal cache |
| entry named \fB<variable>\fP\&. Specify the \fB<includes>\fP argument |
| as a ;\-list of header file names. |
| .sp |
| If \fBLANGUAGE\fP is set, the specified compiler will be used to perform the |
| check. Acceptable values are \fBC\fP and \fBCXX\fP\&. If not set, the C compiler |
| will be used if enabled. If the C compiler is not enabled, the C++ |
| compiler will be used if enabled. |
| .UNINDENT |
| .sp |
| The following variables may be set before calling this macro to modify |
| the way the check is run: |
| .INDENT 0.0 |
| .TP |
| .B \fBCMAKE_REQUIRED_FLAGS\fP |
| string of compile command line flags. |
| .TP |
| .B \fBCMAKE_REQUIRED_DEFINITIONS\fP |
| a ;\-list of macros to define (\-DFOO=bar). |
| .TP |
| .B \fBCMAKE_REQUIRED_INCLUDES\fP |
| a ;\-list of header search paths to pass to |
| the compiler. |
| .TP |
| .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP |
| New in version 3.14: a ;\-list of options to add to the link command. |
| |
| .TP |
| .B \fBCMAKE_REQUIRED_LIBRARIES\fP |
| a ;\-list of libraries to add to the link |
| command. See policy \fBCMP0075\fP\&. |
| .TP |
| .B \fBCMAKE_REQUIRED_QUIET\fP |
| New in version 3.1: execute quietly without messages. |
| |
| .UNINDENT |
| .sp |
| See modules \fBCheckIncludeFile\fP and \fBCheckIncludeFileCXX\fP |
| to check for a single header file in \fBC\fP or \fBCXX\fP languages. |
| .SS CheckIPOSupported |
| .sp |
| New in version 3.9. |
| |
| .sp |
| Check whether the compiler supports an interprocedural optimization (IPO/LTO). |
| Use this before enabling the \fBINTERPROCEDURAL_OPTIMIZATION\fP target |
| property. |
| .INDENT 0.0 |
| .TP |
| .B check_ipo_supported |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| check_ipo_supported([RESULT <result>] [OUTPUT <output>] |
| [LANGUAGES <lang>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Options are: |
| .INDENT 7.0 |
| .TP |
| .B \fBRESULT <result>\fP |
| Set \fB<result>\fP variable to \fBYES\fP if IPO is supported by the |
| compiler and \fBNO\fP otherwise. If this option is not given then |
| the command will issue a fatal error if IPO is not supported. |
| .TP |
| .B \fBOUTPUT <output>\fP |
| Set \fB<output>\fP variable with details about any error. |
| .TP |
| .B \fBLANGUAGES <lang>...\fP |
| Specify languages whose compilers to check. |
| Languages \fBC\fP, \fBCXX\fP, and \fBFortran\fP are supported. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| It makes no sense to use this module when \fBCMP0069\fP is set to \fBOLD\fP so |
| module will return error in this case. See policy \fBCMP0069\fP for details. |
| .sp |
| New in version 3.13: Add support for Visual Studio generators. |
| |
| .SS Examples |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| check_ipo_supported() # fatal error if IPO is not supported |
| set_property(TARGET foo PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| # Optional IPO. Do not use IPO if it\(aqs not supported by compiler. |
| check_ipo_supported(RESULT result OUTPUT output) |
| if(result) |
| set_property(TARGET foo PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE) |
| else() |
| message(WARNING "IPO is not supported: ${output}") |
| endif() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS CheckLanguage |
| .sp |
| Check if a language can be enabled |
| .sp |
| Usage: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| check_language(<lang>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| where \fB<lang>\fP is a language that may be passed to \fBenable_language()\fP |
| such as \fBFortran\fP\&. If \fBCMAKE_<LANG>_COMPILER\fP is already defined |
| the check does nothing. Otherwise it tries enabling the language in a |
| test project. The result is cached in \fBCMAKE_<LANG>_COMPILER\fP |
| as the compiler that was found, or \fBNOTFOUND\fP if the language cannot be |
| enabled. For CUDA which can have an explicit host compiler, the cache |
| \fBCMAKE_CUDA_HOST_COMPILER\fP variable will be set if it was required |
| for compilation (and cleared if it was not). |
| .sp |
| Example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| check_language(Fortran) |
| if(CMAKE_Fortran_COMPILER) |
| enable_language(Fortran) |
| else() |
| message(STATUS "No Fortran support") |
| endif() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS CheckLibraryExists |
| .sp |
| Check if the function exists. |
| .INDENT 0.0 |
| .TP |
| .B CHECK_LIBRARY_EXISTS |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| CHECK_LIBRARY_EXISTS(LIBRARY FUNCTION LOCATION VARIABLE) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| LIBRARY \- the name of the library you are looking for |
| FUNCTION \- the name of the function |
| LOCATION \- location where the library should be found |
| VARIABLE \- variable to store the result |
| Will be created as an internal cache variable. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The following variables may be set before calling this macro to modify |
| the way the check is run: |
| .INDENT 0.0 |
| .TP |
| .B \fBCMAKE_REQUIRED_FLAGS\fP |
| string of compile command line flags. |
| .TP |
| .B \fBCMAKE_REQUIRED_DEFINITIONS\fP |
| list of macros to define (\-DFOO=bar). |
| .TP |
| .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP |
| New in version 3.14: list of options to pass to link command. |
| |
| .TP |
| .B \fBCMAKE_REQUIRED_LIBRARIES\fP |
| list of libraries to link. |
| .TP |
| .B \fBCMAKE_REQUIRED_QUIET\fP |
| New in version 3.1: execute quietly without messages. |
| |
| .UNINDENT |
| .SS CheckLinkerFlag |
| .sp |
| New in version 3.18. |
| |
| .sp |
| Check whether the compiler supports a given link flag. |
| .INDENT 0.0 |
| .TP |
| .B check_linker_flag |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| check_linker_flag(<lang> <flag> <var>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Check that the link \fB<flag>\fP is accepted by the \fB<lang>\fP compiler without |
| a diagnostic. Stores the result in an internal cache entry named \fB<var>\fP\&. |
| .sp |
| This command temporarily sets the \fBCMAKE_REQUIRED_LINK_OPTIONS\fP variable |
| and calls the \fBcheck_source_compiles()\fP command from the |
| \fBCheckSourceCompiles\fP module. See that module\(aqs documentation |
| for a listing of variables that can otherwise modify the build. |
| .sp |
| The underlying implementation relies on the \fBLINK_OPTIONS\fP property |
| to check the specified flag. The \fBLINKER:\fP prefix, as described in the |
| \fBtarget_link_options()\fP command, can be used as well. |
| .sp |
| A positive result from this check indicates only that the compiler did not |
| issue a diagnostic message when given the link flag. Whether the flag has any |
| effect or even a specific one is beyond the scope of this module. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| Since the \fBtry_compile()\fP command forwards flags from variables |
| like \fBCMAKE_<LANG>_FLAGS\fP, unknown flags in such variables may |
| cause a false negative for this check. |
| .UNINDENT |
| .UNINDENT |
| .SS CheckOBJCCompilerFlag |
| .sp |
| New in version 3.16. |
| |
| .sp |
| Check whether the Objective\-C compiler supports a given flag. |
| .INDENT 0.0 |
| .TP |
| .B check_objc_compiler_flag |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| check_objc_compiler_flag(<flag> <var>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Check that the \fB<flag>\fP is accepted by the compiler without |
| a diagnostic. Stores the result in an internal cache entry |
| named \fB<var>\fP\&. |
| .UNINDENT |
| .sp |
| This command temporarily sets the \fBCMAKE_REQUIRED_DEFINITIONS\fP variable |
| and calls the \fBcheck_objc_source_compiles\fP macro from the |
| \fBCheckOBJCSourceCompiles\fP module. See documentation of that |
| module for a listing of variables that can otherwise modify the build. |
| .sp |
| A positive result from this check indicates only that the compiler did not |
| issue a diagnostic message when given the flag. Whether the flag has any |
| effect or even a specific one is beyond the scope of this module. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| Since the \fBtry_compile()\fP command forwards flags from variables |
| like \fBCMAKE_OBJC_FLAGS\fP, unknown flags |
| in such variables may cause a false negative for this check. |
| .UNINDENT |
| .UNINDENT |
| .SS CheckOBJCSourceCompiles |
| .sp |
| New in version 3.16. |
| |
| .sp |
| Check if given Objective\-C source compiles and links into an executable. |
| .INDENT 0.0 |
| .TP |
| .B check_objc_source_compiles |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| check_objc_source_compiles(<code> <resultVar> |
| [FAIL_REGEX <regex1> [<regex2>...]]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Check that the source supplied in \fB<code>\fP can be compiled as a Objectie\-C source |
| file and linked as an executable (so it must contain at least a \fBmain()\fP |
| function). The result will be stored in the internal cache variable specified |
| by \fB<resultVar>\fP, with a boolean true value for success and boolean false |
| for failure. If \fBFAIL_REGEX\fP is provided, then failure is determined by |
| checking if anything in the output matches any of the specified regular |
| expressions. |
| .sp |
| The underlying check is performed by the \fBtry_compile()\fP command. The |
| compile and link commands can be influenced by setting any of the following |
| variables prior to calling \fBcheck_objc_source_compiles()\fP: |
| .INDENT 7.0 |
| .TP |
| .B \fBCMAKE_REQUIRED_FLAGS\fP |
| Additional flags to pass to the compiler. Note that the contents of |
| \fBCMAKE_OBJC_FLAGS\fP and its associated |
| configuration\-specific variable are automatically added to the compiler |
| command before the contents of \fBCMAKE_REQUIRED_FLAGS\fP\&. |
| .TP |
| .B \fBCMAKE_REQUIRED_DEFINITIONS\fP |
| A ;\-list of compiler definitions of the form |
| \fB\-DFOO\fP or \fB\-DFOO=bar\fP\&. A definition for the name specified by |
| \fB<resultVar>\fP will also be added automatically. |
| .TP |
| .B \fBCMAKE_REQUIRED_INCLUDES\fP |
| A ;\-list of header search paths to pass to |
| the compiler. These will be the only header search paths used by |
| \fBtry_compile()\fP, i.e. the contents of the \fBINCLUDE_DIRECTORIES\fP |
| directory property will be ignored. |
| .TP |
| .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP |
| A ;\-list of options to add to the link |
| command (see \fBtry_compile()\fP for further details). |
| .TP |
| .B \fBCMAKE_REQUIRED_LIBRARIES\fP |
| A ;\-list of libraries to add to the link |
| command. These can be the name of system libraries or they can be |
| Imported Targets (see \fBtry_compile()\fP for |
| further details). |
| .TP |
| .B \fBCMAKE_REQUIRED_QUIET\fP |
| If this variable evaluates to a boolean true value, all status messages |
| associated with the check will be suppressed. |
| .UNINDENT |
| .sp |
| The check is only performed once, with the result cached in the variable |
| named by \fB<resultVar>\fP\&. Every subsequent CMake run will re\-use this cached |
| value rather than performing the check again, even if the \fB<code>\fP changes. |
| In order to force the check to be re\-evaluated, the variable named by |
| \fB<resultVar>\fP must be manually removed from the cache. |
| .UNINDENT |
| .SS CheckOBJCSourceRuns |
| .sp |
| New in version 3.16. |
| |
| .sp |
| Check if given Objective\-C source compiles and links into an executable and can |
| subsequently be run. |
| .INDENT 0.0 |
| .TP |
| .B check_objc_source_runs |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| check_objc_source_runs(<code> <resultVar>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Check that the source supplied in \fB<code>\fP can be compiled as a Objective\-C source |
| file, linked as an executable and then run. The \fB<code>\fP must contain at |
| least a \fBmain()\fP function. If the \fB<code>\fP could be built and run |
| successfully, the internal cache variable specified by \fB<resultVar>\fP will |
| be set to 1, otherwise it will be set to an value that evaluates to boolean |
| false (e.g. an empty string or an error message). |
| .sp |
| The underlying check is performed by the \fBtry_run()\fP command. The |
| compile and link commands can be influenced by setting any of the following |
| variables prior to calling \fBcheck_objc_source_runs()\fP: |
| .INDENT 7.0 |
| .TP |
| .B \fBCMAKE_REQUIRED_FLAGS\fP |
| Additional flags to pass to the compiler. Note that the contents of |
| \fBCMAKE_OBJC_FLAGS\fP and its associated |
| configuration\-specific variable are automatically added to the compiler |
| command before the contents of \fBCMAKE_REQUIRED_FLAGS\fP\&. |
| .TP |
| .B \fBCMAKE_REQUIRED_DEFINITIONS\fP |
| A ;\-list of compiler definitions of the form |
| \fB\-DFOO\fP or \fB\-DFOO=bar\fP\&. A definition for the name specified by |
| \fB<resultVar>\fP will also be added automatically. |
| .TP |
| .B \fBCMAKE_REQUIRED_INCLUDES\fP |
| A ;\-list of header search paths to pass to |
| the compiler. These will be the only header search paths used by |
| \fBtry_run()\fP, i.e. the contents of the \fBINCLUDE_DIRECTORIES\fP |
| directory property will be ignored. |
| .TP |
| .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP |
| A ;\-list of options to add to the link |
| command (see \fBtry_run()\fP for further details). |
| .TP |
| .B \fBCMAKE_REQUIRED_LIBRARIES\fP |
| A ;\-list of libraries to add to the link |
| command. These can be the name of system libraries or they can be |
| Imported Targets (see \fBtry_run()\fP for |
| further details). |
| .TP |
| .B \fBCMAKE_REQUIRED_QUIET\fP |
| If this variable evaluates to a boolean true value, all status messages |
| associated with the check will be suppressed. |
| .UNINDENT |
| .sp |
| The check is only performed once, with the result cached in the variable |
| named by \fB<resultVar>\fP\&. Every subsequent CMake run will re\-use this cached |
| value rather than performing the check again, even if the \fB<code>\fP changes. |
| In order to force the check to be re\-evaluated, the variable named by |
| \fB<resultVar>\fP must be manually removed from the cache. |
| .UNINDENT |
| .SS CheckOBJCXXCompilerFlag |
| .sp |
| New in version 3.16. |
| |
| .sp |
| Check whether the Objective\-C++ compiler supports a given flag. |
| .INDENT 0.0 |
| .TP |
| .B check_objcxx_compiler_flag |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| check_objcxx_compiler_flag(<flag> <var>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Check that the \fB<flag>\fP is accepted by the compiler without |
| a diagnostic. Stores the result in an internal cache entry |
| named \fB<var>\fP\&. |
| .UNINDENT |
| .sp |
| This command temporarily sets the \fBCMAKE_REQUIRED_DEFINITIONS\fP variable |
| and calls the \fBcheck_objcxx_source_compiles\fP macro from the |
| \fBCheckOBJCXXSourceCompiles\fP module. See documentation of that |
| module for a listing of variables that can otherwise modify the build. |
| .sp |
| A positive result from this check indicates only that the compiler did not |
| issue a diagnostic message when given the flag. Whether the flag has any |
| effect or even a specific one is beyond the scope of this module. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| Since the \fBtry_compile()\fP command forwards flags from variables |
| like \fBCMAKE_OBJCXX_FLAGS\fP, unknown flags |
| in such variables may cause a false negative for this check. |
| .UNINDENT |
| .UNINDENT |
| .SS CheckOBJCXXSourceCompiles |
| .sp |
| New in version 3.16. |
| |
| .sp |
| Check if given Objective\-C++ source compiles and links into an executable. |
| .INDENT 0.0 |
| .TP |
| .B check_objcxx_source_compiles |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| check_objcxx_source_compiles(<code> <resultVar> |
| [FAIL_REGEX <regex1> [<regex2>...]]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Check that the source supplied in \fB<code>\fP can be compiled as a Objective\-C++ source |
| file and linked as an executable (so it must contain at least a \fBmain()\fP |
| function). The result will be stored in the internal cache variable specified |
| by \fB<resultVar>\fP, with a boolean true value for success and boolean false |
| for failure. If \fBFAIL_REGEX\fP is provided, then failure is determined by |
| checking if anything in the output matches any of the specified regular |
| expressions. |
| .sp |
| The underlying check is performed by the \fBtry_compile()\fP command. The |
| compile and link commands can be influenced by setting any of the following |
| variables prior to calling \fBcheck_objcxx_source_compiles()\fP: |
| .INDENT 7.0 |
| .TP |
| .B \fBCMAKE_REQUIRED_FLAGS\fP |
| Additional flags to pass to the compiler. Note that the contents of |
| \fBCMAKE_OBJCXX_FLAGS\fP and its associated |
| configuration\-specific variable are automatically added to the compiler |
| command before the contents of \fBCMAKE_REQUIRED_FLAGS\fP\&. |
| .TP |
| .B \fBCMAKE_REQUIRED_DEFINITIONS\fP |
| A ;\-list of compiler definitions of the form |
| \fB\-DFOO\fP or \fB\-DFOO=bar\fP\&. A definition for the name specified by |
| \fB<resultVar>\fP will also be added automatically. |
| .TP |
| .B \fBCMAKE_REQUIRED_INCLUDES\fP |
| A ;\-list of header search paths to pass to |
| the compiler. These will be the only header search paths used by |
| \fBtry_compile()\fP, i.e. the contents of the \fBINCLUDE_DIRECTORIES\fP |
| directory property will be ignored. |
| .TP |
| .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP |
| A ;\-list of options to add to the link |
| command (see \fBtry_compile()\fP for further details). |
| .TP |
| .B \fBCMAKE_REQUIRED_LIBRARIES\fP |
| A ;\-list of libraries to add to the link |
| command. These can be the name of system libraries or they can be |
| Imported Targets (see \fBtry_compile()\fP for |
| further details). |
| .TP |
| .B \fBCMAKE_REQUIRED_QUIET\fP |
| If this variable evaluates to a boolean true value, all status messages |
| associated with the check will be suppressed. |
| .UNINDENT |
| .sp |
| The check is only performed once, with the result cached in the variable |
| named by \fB<resultVar>\fP\&. Every subsequent CMake run will re\-use this cached |
| value rather than performing the check again, even if the \fB<code>\fP changes. |
| In order to force the check to be re\-evaluated, the variable named by |
| \fB<resultVar>\fP must be manually removed from the cache. |
| .UNINDENT |
| .SS CheckOBJCXXSourceRuns |
| .sp |
| New in version 3.16. |
| |
| .sp |
| Check if given Objective\-C++ source compiles and links into an executable and can |
| subsequently be run. |
| .INDENT 0.0 |
| .TP |
| .B check_objcxx_source_runs |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| check_objcxx_source_runs(<code> <resultVar>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Check that the source supplied in \fB<code>\fP can be compiled as a Objective\-C++ source |
| file, linked as an executable and then run. The \fB<code>\fP must contain at |
| least a \fBmain()\fP function. If the \fB<code>\fP could be built and run |
| successfully, the internal cache variable specified by \fB<resultVar>\fP will |
| be set to 1, otherwise it will be set to an value that evaluates to boolean |
| false (e.g. an empty string or an error message). |
| .sp |
| The underlying check is performed by the \fBtry_run()\fP command. The |
| compile and link commands can be influenced by setting any of the following |
| variables prior to calling \fBcheck_objcxx_source_runs()\fP: |
| .INDENT 7.0 |
| .TP |
| .B \fBCMAKE_REQUIRED_FLAGS\fP |
| Additional flags to pass to the compiler. Note that the contents of |
| \fBCMAKE_OBJCXX_FLAGS\fP and its associated |
| configuration\-specific variable are automatically added to the compiler |
| command before the contents of \fBCMAKE_REQUIRED_FLAGS\fP\&. |
| .TP |
| .B \fBCMAKE_REQUIRED_DEFINITIONS\fP |
| A ;\-list of compiler definitions of the form |
| \fB\-DFOO\fP or \fB\-DFOO=bar\fP\&. A definition for the name specified by |
| \fB<resultVar>\fP will also be added automatically. |
| .TP |
| .B \fBCMAKE_REQUIRED_INCLUDES\fP |
| A ;\-list of header search paths to pass to |
| the compiler. These will be the only header search paths used by |
| \fBtry_run()\fP, i.e. the contents of the \fBINCLUDE_DIRECTORIES\fP |
| directory property will be ignored. |
| .TP |
| .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP |
| A ;\-list of options to add to the link |
| command (see \fBtry_run()\fP for further details). |
| .TP |
| .B \fBCMAKE_REQUIRED_LIBRARIES\fP |
| A ;\-list of libraries to add to the link |
| command. These can be the name of system libraries or they can be |
| Imported Targets (see \fBtry_run()\fP for |
| further details). |
| .TP |
| .B \fBCMAKE_REQUIRED_QUIET\fP |
| If this variable evaluates to a boolean true value, all status messages |
| associated with the check will be suppressed. |
| .UNINDENT |
| .sp |
| The check is only performed once, with the result cached in the variable |
| named by \fB<resultVar>\fP\&. Every subsequent CMake run will re\-use this cached |
| value rather than performing the check again, even if the \fB<code>\fP changes. |
| In order to force the check to be re\-evaluated, the variable named by |
| \fB<resultVar>\fP must be manually removed from the cache. |
| .UNINDENT |
| .SS CheckPIESupported |
| .sp |
| New in version 3.14. |
| |
| .sp |
| Check whether the linker supports Position Independent Code (PIE) or No |
| Position Independent Code (NO_PIE) for executables. |
| Use this to ensure that the \fBPOSITION_INDEPENDENT_CODE\fP target |
| property for executables will be honored at link time. |
| .INDENT 0.0 |
| .TP |
| .B check_pie_supported |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| check_pie_supported([OUTPUT_VARIABLE <output>] |
| [LANGUAGES <lang>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Options are: |
| .INDENT 7.0 |
| .TP |
| .B \fBOUTPUT_VARIABLE <output>\fP |
| Set \fB<output>\fP variable with details about any error. If the check is |
| bypassed because it uses cached results from a previous call, the output |
| will be empty even if errors were present in the previous call. |
| .TP |
| .B \fBLANGUAGES <lang>...\fP |
| Check the linkers used for each of the specified languages. |
| If this option is not provided, the command checks all enabled languages. |
| .sp |
| \fBC\fP, \fBCXX\fP, \fBFortran\fP are supported. |
| .sp |
| New in version 3.23: \fBOBJC\fP, \fBOBJCXX\fP, \fBCUDA\fP, and \fBHIP\fP are supported. |
| |
| .UNINDENT |
| .UNINDENT |
| .sp |
| It makes no sense to use this module when \fBCMP0083\fP is set to \fBOLD\fP, |
| so the command will return an error in this case. See policy \fBCMP0083\fP |
| for details. |
| .SS Variables |
| .sp |
| For each language checked, two boolean cache variables are defined. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .INDENT 0.0 |
| .TP |
| .B \fBCMAKE_<lang>_LINK_PIE_SUPPORTED\fP |
| Set to true if \fBPIE\fP is supported by the linker and false otherwise. |
| .TP |
| .B \fBCMAKE_<lang>_LINK_NO_PIE_SUPPORTED\fP |
| Set to true if \fBNO_PIE\fP is supported by the linker and false otherwise. |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .SS Examples |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| check_pie_supported() |
| set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| # Retrieve any error message. |
| check_pie_supported(OUTPUT_VARIABLE output LANGUAGES C) |
| set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE) |
| if(NOT CMAKE_C_LINK_PIE_SUPPORTED) |
| message(WARNING "PIE is not supported at link time: ${output}.\en" |
| "PIE link options will not be passed to linker.") |
| endif() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS CheckPrototypeDefinition |
| .sp |
| Check if the prototype we expect is correct. |
| .INDENT 0.0 |
| .TP |
| .B check_prototype_definition |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| check_prototype_definition(FUNCTION PROTOTYPE RETURN HEADER VARIABLE) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| FUNCTION \- The name of the function (used to check if prototype exists) |
| PROTOTYPE\- The prototype to check. |
| RETURN \- The return value of the function. |
| HEADER \- The header files required. |
| VARIABLE \- The variable to store the result. |
| Will be created as an internal cache variable. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Example: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| check_prototype_definition(getpwent_r |
| "struct passwd *getpwent_r(struct passwd *src, char *buf, int buflen)" |
| "NULL" |
| "unistd.h;pwd.h" |
| SOLARIS_GETPWENT_R) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The following variables may be set before calling this function to modify |
| the way the check is run: |
| .INDENT 0.0 |
| .TP |
| .B \fBCMAKE_REQUIRED_FLAGS\fP |
| string of compile command line flags. |
| .TP |
| .B \fBCMAKE_REQUIRED_DEFINITIONS\fP |
| list of macros to define (\-DFOO=bar). |
| .TP |
| .B \fBCMAKE_REQUIRED_INCLUDES\fP |
| list of include directories. |
| .TP |
| .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP |
| New in version 3.14: list of options to pass to link command. |
| |
| .TP |
| .B \fBCMAKE_REQUIRED_LIBRARIES\fP |
| list of libraries to link. |
| .TP |
| .B \fBCMAKE_REQUIRED_QUIET\fP |
| New in version 3.1: execute quietly without messages. |
| |
| .UNINDENT |
| .SS CheckSourceCompiles |
| .sp |
| New in version 3.19. |
| |
| .sp |
| Check if given source compiles and links into an executable. |
| .INDENT 0.0 |
| .TP |
| .B check_source_compiles |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| check_source_compiles(<lang> <code> <resultVar> |
| [FAIL_REGEX <regex1> [<regex2>...]] |
| [SRC_EXT <extension>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Check that the source supplied in \fB<code>\fP can be compiled as a source |
| file for the requested language and linked as an executable (so it must |
| contain at least a \fBmain()\fP function). The result will be stored in the |
| internal cache variable specified by \fB<resultVar>\fP, with a boolean true |
| value for success and boolean false for failure. If \fBFAIL_REGEX\fP is |
| provided, then failure is determined by checking if anything in the output |
| matches any of the specified regular expressions. |
| .sp |
| By default, the test source file will be given a file extension that matches |
| the requested language. The \fBSRC_EXT\fP option can be used to override this |
| with \fB\&.<extension>\fP instead. |
| .sp |
| The underlying check is performed by the \fBtry_compile()\fP command. The |
| compile and link commands can be influenced by setting any of the following |
| variables prior to calling \fBcheck_source_compiles()\fP: |
| .INDENT 7.0 |
| .TP |
| .B \fBCMAKE_REQUIRED_FLAGS\fP |
| Additional flags to pass to the compiler. Note that the contents of |
| \fBCMAKE_<LANG>_FLAGS\fP and its associated |
| configuration\-specific variable are automatically added to the compiler |
| command before the contents of \fBCMAKE_REQUIRED_FLAGS\fP\&. |
| .TP |
| .B \fBCMAKE_REQUIRED_DEFINITIONS\fP |
| A ;\-list of compiler definitions of the form |
| \fB\-DFOO\fP or \fB\-DFOO=bar\fP\&. A definition for the name specified by |
| \fB<resultVar>\fP will also be added automatically. |
| .TP |
| .B \fBCMAKE_REQUIRED_INCLUDES\fP |
| A ;\-list of header search paths to pass to |
| the compiler. These will be the only header search paths used by |
| \fBtry_compile()\fP, i.e. the contents of the \fBINCLUDE_DIRECTORIES\fP |
| directory property will be ignored. |
| .TP |
| .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP |
| A ;\-list of options to add to the link |
| command (see \fBtry_compile()\fP for further details). |
| .TP |
| .B \fBCMAKE_REQUIRED_LIBRARIES\fP |
| A ;\-list of libraries to add to the link |
| command. These can be the name of system libraries or they can be |
| Imported Targets (see \fBtry_compile()\fP for |
| further details). |
| .TP |
| .B \fBCMAKE_REQUIRED_QUIET\fP |
| If this variable evaluates to a boolean true value, all status messages |
| associated with the check will be suppressed. |
| .UNINDENT |
| .sp |
| The check is only performed once, with the result cached in the variable |
| named by \fB<resultVar>\fP\&. Every subsequent CMake run will re\-use this cached |
| value rather than performing the check again, even if the \fB<code>\fP changes. |
| In order to force the check to be re\-evaluated, the variable named by |
| \fB<resultVar>\fP must be manually removed from the cache. |
| .UNINDENT |
| .SS CheckSourceRuns |
| .sp |
| New in version 3.19. |
| |
| .sp |
| Check if given source compiles and links into an executable and can |
| subsequently be run. |
| .INDENT 0.0 |
| .TP |
| .B check_source_runs |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| check_source_runs(<lang> <code> <resultVar> |
| [SRC_EXT <extension>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Check that the source supplied in \fB<code>\fP can be compiled as a source |
| file for the requested language, linked as an executable and then run. |
| The \fB<code>\fP must contain at least a \fBmain()\fP function. If the \fB<code>\fP |
| could be built and run successfully, the internal cache variable specified by |
| \fB<resultVar>\fP will be set to 1, otherwise it will be set to an value that |
| evaluates to boolean false (e.g. an empty string or an error message). |
| .sp |
| By default, the test source file will be given a file extension that matches |
| the requested language. The \fBSRC_EXT\fP option can be used to override this |
| with \fB\&.<extension>\fP instead. |
| .sp |
| The underlying check is performed by the \fBtry_run()\fP command. The |
| compile and link commands can be influenced by setting any of the following |
| variables prior to calling \fBcheck_objc_source_runs()\fP: |
| .INDENT 7.0 |
| .TP |
| .B \fBCMAKE_REQUIRED_FLAGS\fP |
| Additional flags to pass to the compiler. Note that the contents of |
| \fBCMAKE_OBJC_FLAGS\fP and its associated |
| configuration\-specific variable are automatically added to the compiler |
| command before the contents of \fBCMAKE_REQUIRED_FLAGS\fP\&. |
| .TP |
| .B \fBCMAKE_REQUIRED_DEFINITIONS\fP |
| A ;\-list of compiler definitions of the form |
| \fB\-DFOO\fP or \fB\-DFOO=bar\fP\&. A definition for the name specified by |
| \fB<resultVar>\fP will also be added automatically. |
| .TP |
| .B \fBCMAKE_REQUIRED_INCLUDES\fP |
| A ;\-list of header search paths to pass to |
| the compiler. These will be the only header search paths used by |
| \fBtry_run()\fP, i.e. the contents of the \fBINCLUDE_DIRECTORIES\fP |
| directory property will be ignored. |
| .TP |
| .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP |
| A ;\-list of options to add to the link |
| command (see \fBtry_run()\fP for further details). |
| .TP |
| .B \fBCMAKE_REQUIRED_LIBRARIES\fP |
| A ;\-list of libraries to add to the link |
| command. These can be the name of system libraries or they can be |
| Imported Targets (see \fBtry_run()\fP for |
| further details). |
| .TP |
| .B \fBCMAKE_REQUIRED_QUIET\fP |
| If this variable evaluates to a boolean true value, all status messages |
| associated with the check will be suppressed. |
| .UNINDENT |
| .sp |
| The check is only performed once, with the result cached in the variable |
| named by \fB<resultVar>\fP\&. Every subsequent CMake run will re\-use this cached |
| value rather than performing the check again, even if the \fB<code>\fP changes. |
| In order to force the check to be re\-evaluated, the variable named by |
| \fB<resultVar>\fP must be manually removed from the cache. |
| .UNINDENT |
| .SS CheckStructHasMember |
| .sp |
| Check if the given struct or class has the specified member variable |
| .INDENT 0.0 |
| .TP |
| .B CHECK_STRUCT_HAS_MEMBER |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| CHECK_STRUCT_HAS_MEMBER(<struct> <member> <header> <variable> |
| [LANGUAGE <language>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| <struct> \- the name of the struct or class you are interested in |
| <member> \- the member which existence you want to check |
| <header> \- the header(s) where the prototype should be declared |
| <variable> \- variable to store the result |
| <language> \- the compiler to use (C or CXX) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The following variables may be set before calling this macro to modify |
| the way the check is run: |
| .INDENT 0.0 |
| .TP |
| .B \fBCMAKE_REQUIRED_FLAGS\fP |
| string of compile command line flags. |
| .TP |
| .B \fBCMAKE_REQUIRED_DEFINITIONS\fP |
| list of macros to define (\-DFOO=bar). |
| .TP |
| .B \fBCMAKE_REQUIRED_INCLUDES\fP |
| list of include directories. |
| .TP |
| .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP |
| New in version 3.14: list of options to pass to link command. |
| |
| .TP |
| .B \fBCMAKE_REQUIRED_LIBRARIES\fP |
| list of libraries to link. |
| .TP |
| .B \fBCMAKE_REQUIRED_QUIET\fP |
| New in version 3.1: execute quietly without messages. |
| |
| .UNINDENT |
| .sp |
| Example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| CHECK_STRUCT_HAS_MEMBER("struct timeval" tv_sec sys/select.h |
| HAVE_TIMEVAL_TV_SEC LANGUAGE C) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS CheckSymbolExists |
| .sp |
| Provides a macro to check if a symbol exists as a function, variable, |
| or macro in \fBC\fP\&. |
| .INDENT 0.0 |
| .TP |
| .B check_symbol_exists |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| check_symbol_exists(<symbol> <files> <variable>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Check that the \fB<symbol>\fP is available after including given header |
| \fB<files>\fP and store the result in a \fB<variable>\fP\&. Specify the list |
| of files in one argument as a semicolon\-separated list. |
| \fB<variable>\fP will be created as an internal cache variable. |
| .UNINDENT |
| .sp |
| If the header files define the symbol as a macro it is considered |
| available and assumed to work. If the header files declare the symbol |
| as a function or variable then the symbol must also be available for |
| linking (so intrinsics may not be detected). |
| If the symbol is a type, enum value, or intrinsic it will not be recognized |
| (consider using \fBCheckTypeSize\fP or \fBCheckSourceCompiles\fP). |
| If the check needs to be done in C++, consider using |
| \fBCheckCXXSymbolExists\fP instead. |
| .sp |
| The following variables may be set before calling this macro to modify |
| the way the check is run: |
| .INDENT 0.0 |
| .TP |
| .B \fBCMAKE_REQUIRED_FLAGS\fP |
| string of compile command line flags. |
| .TP |
| .B \fBCMAKE_REQUIRED_DEFINITIONS\fP |
| a ;\-list of macros to define (\-DFOO=bar). |
| .TP |
| .B \fBCMAKE_REQUIRED_INCLUDES\fP |
| a ;\-list of header search paths to pass to |
| the compiler. |
| .TP |
| .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP |
| New in version 3.14: a ;\-list of options to add to the link command. |
| |
| .TP |
| .B \fBCMAKE_REQUIRED_LIBRARIES\fP |
| a ;\-list of libraries to add to the link |
| command. See policy \fBCMP0075\fP\&. |
| .TP |
| .B \fBCMAKE_REQUIRED_QUIET\fP |
| New in version 3.1: execute quietly without messages. |
| |
| .UNINDENT |
| .sp |
| For example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| include(CheckSymbolExists) |
| |
| # Check for macro SEEK_SET |
| check_symbol_exists(SEEK_SET "stdio.h" HAVE_SEEK_SET) |
| # Check for function fopen |
| check_symbol_exists(fopen "stdio.h" HAVE_FOPEN) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS CheckTypeSize |
| .sp |
| Check sizeof a type |
| .INDENT 0.0 |
| .TP |
| .B check_type_size |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| check_type_size(<type> <variable> [BUILTIN_TYPES_ONLY] |
| [LANGUAGE <language>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Check if the type exists and determine its size. Results are reported |
| in the following variables: |
| .INDENT 7.0 |
| .TP |
| .B \fBHAVE_<variable>\fP |
| Holds a true or false value indicating whether the type exists. |
| .TP |
| .B \fB<variable>\fP |
| Holds one of the following values: |
| .INDENT 7.0 |
| .TP |
| .B \fB<size>\fP |
| Type has non\-zero size \fB<size>\fP\&. |
| .TP |
| .B \fB0\fP |
| Type has architecture\-dependent size. This may occur when |
| \fBCMAKE_OSX_ARCHITECTURES\fP has multiple architectures. |
| In this case \fB<variable>_CODE\fP contains C preprocessor tests |
| mapping from each architecture macro to the corresponding type size. |
| The list of architecture macros is stored in \fB<variable>_KEYS\fP, |
| and the value for each key is stored in \fB<variable>\-<key>\fP\&. |
| .TP |
| .B "" (empty string) |
| Type does not exist. |
| .UNINDENT |
| .TP |
| .B \fB<variable>_CODE\fP |
| Holds C preprocessor code to define the macro \fB<variable>\fP to the size |
| of the type, or to leave the macro undefined if the type does not exist. |
| .UNINDENT |
| .sp |
| The options are: |
| .sp |
| \fBBUILTIN_TYPES_ONLY\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| Support only compiler\-builtin types. If \fInot\fP given, the macro checks |
| for headers \fB<sys/types.h>\fP, \fB<stdint.h>\fP, and \fB<stddef.h>\fP, and |
| saves results in \fBHAVE_SYS_TYPES_H\fP, \fBHAVE_STDINT_H\fP, and |
| \fBHAVE_STDDEF_H\fP\&. The type size check automatically includes the |
| available headers, thus supporting checks of types defined in the headers. |
| .UNINDENT |
| .UNINDENT |
| .INDENT 7.0 |
| .TP |
| .B \fBLANGUAGE <language>\fP |
| Use the \fB<language>\fP compiler to perform the check. |
| Acceptable values are \fBC\fP and \fBCXX\fP\&. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Despite the name of the macro you may use it to check the size of more |
| complex expressions, too. To check e.g. for the size of a struct |
| member you can do something like this: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| check_type_size("((struct something*)0)\->member" SIZEOF_MEMBER) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The following variables may be set before calling this macro to modify |
| the way the check is run: |
| .INDENT 0.0 |
| .TP |
| .B \fBCMAKE_REQUIRED_FLAGS\fP |
| string of compile command line flags. |
| .TP |
| .B \fBCMAKE_REQUIRED_DEFINITIONS\fP |
| list of macros to define (\-DFOO=bar). |
| .TP |
| .B \fBCMAKE_REQUIRED_INCLUDES\fP |
| list of include directories. |
| .TP |
| .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP |
| New in version 3.14: list of options to pass to link command. |
| |
| .TP |
| .B \fBCMAKE_REQUIRED_LIBRARIES\fP |
| list of libraries to link. |
| .TP |
| .B \fBCMAKE_REQUIRED_QUIET\fP |
| New in version 3.1: execute quietly without messages. |
| |
| .TP |
| .B \fBCMAKE_EXTRA_INCLUDE_FILES\fP |
| list of extra headers to include. |
| .UNINDENT |
| .SS CheckVariableExists |
| .sp |
| Check if the variable exists. |
| .INDENT 0.0 |
| .TP |
| .B CHECK_VARIABLE_EXISTS |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| CHECK_VARIABLE_EXISTS(VAR VARIABLE) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| VAR \- the name of the variable |
| VARIABLE \- variable to store the result |
| Will be created as an internal cache variable. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This macro is only for \fBC\fP variables. |
| .UNINDENT |
| .sp |
| The following variables may be set before calling this macro to modify |
| the way the check is run: |
| .INDENT 0.0 |
| .TP |
| .B \fBCMAKE_REQUIRED_FLAGS\fP |
| string of compile command line flags. |
| .TP |
| .B \fBCMAKE_REQUIRED_DEFINITIONS\fP |
| list of macros to define (\-DFOO=bar). |
| .TP |
| .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP |
| New in version 3.14: list of options to pass to link command. |
| |
| .TP |
| .B \fBCMAKE_REQUIRED_LIBRARIES\fP |
| list of libraries to link. |
| .TP |
| .B \fBCMAKE_REQUIRED_QUIET\fP |
| New in version 3.1: execute quietly without messages. |
| |
| .UNINDENT |
| .SS CMakeAddFortranSubdirectory |
| .sp |
| Add a fortran\-only subdirectory, find a fortran compiler, and build. |
| .sp |
| The \fBcmake_add_fortran_subdirectory\fP function adds a subdirectory |
| to a project that contains a fortran\-only subproject. The module will |
| check the current compiler and see if it can support fortran. If no |
| fortran compiler is found and the compiler is MSVC, then this module |
| will find the MinGW gfortran. It will then use an external project to |
| build with the MinGW tools. It will also create imported targets for |
| the libraries created. This will only work if the fortran code is |
| built into a dll, so \fBBUILD_SHARED_LIBS\fP is turned on in |
| the project. In addition the \fBCMAKE_GNUtoMS\fP option is set |
| to on, so that Microsoft \fB\&.lib\fP files are created. Usage is as follows: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cmake_add_fortran_subdirectory( |
| <subdir> # name of subdirectory |
| PROJECT <project_name> # project name in subdir top CMakeLists.txt |
| ARCHIVE_DIR <dir> # dir where project places .lib files |
| RUNTIME_DIR <dir> # dir where project places .dll files |
| LIBRARIES <lib>... # names of library targets to import |
| LINK_LIBRARIES # link interface libraries for LIBRARIES |
| [LINK_LIBS <lib> <dep>...]... |
| CMAKE_COMMAND_LINE ... # extra command line flags to pass to cmake |
| NO_EXTERNAL_INSTALL # skip installation of external project |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Relative paths in \fBARCHIVE_DIR\fP and \fBRUNTIME_DIR\fP are interpreted with |
| respect to the build directory corresponding to the source directory |
| in which the function is invoked. |
| .sp |
| Limitations: |
| .sp |
| \fBNO_EXTERNAL_INSTALL\fP is required for forward compatibility with a |
| future version that supports installation of the external project |
| binaries during \fBmake install\fP\&. |
| .SS CMakeBackwardCompatibilityCXX |
| .sp |
| define a bunch of backwards compatibility variables |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| CMAKE_ANSI_CXXFLAGS \- flag for ansi c++ |
| CMAKE_HAS_ANSI_STRING_STREAM \- has <strstream> |
| include(TestForANSIStreamHeaders) |
| include(CheckIncludeFileCXX) |
| include(TestForSTDNamespace) |
| include(TestForANSIForScope) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS CMakeDependentOption |
| .sp |
| Macro to provide an option dependent on other options. |
| .sp |
| This macro presents an option to the user only if a set of other |
| conditions are true. |
| .INDENT 0.0 |
| .TP |
| .B cmake_dependent_option |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cmake_dependent_option(<option> "<help_text>" <value> <depends> <force>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Makes \fB<option>\fP available to the user if the |
| semicolon\-separated list of conditions in |
| \fB<depends>\fP are all true. Otherwise, a local variable named \fB<option>\fP |
| is set to \fB<force>\fP\&. |
| .sp |
| When \fB<option>\fP is available, the given \fB<help_text>\fP and initial |
| \fB<value>\fP are used. Otherwise, any value set by the user is preserved for |
| when \fB<depends>\fP is satisfied in the future. |
| .sp |
| Note that the \fB<option>\fP variable only has a value which satisfies the |
| \fB<depends>\fP condition within the scope of the caller because it is a local |
| variable. |
| .UNINDENT |
| .sp |
| Example invocation: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cmake_dependent_option(USE_FOO "Use Foo" ON "USE_BAR;NOT USE_ZOT" OFF) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| If \fBUSE_BAR\fP is true and \fBUSE_ZOT\fP is false, this provides an option called |
| \fBUSE_FOO\fP that defaults to ON. Otherwise, it sets \fBUSE_FOO\fP to OFF and |
| hides the option from the user. If the status of \fBUSE_BAR\fP or \fBUSE_ZOT\fP |
| ever changes, any value for the \fBUSE_FOO\fP option is saved so that when the |
| option is re\-enabled it retains its old value. |
| .sp |
| New in version 3.22: Full Condition Syntax is now supported. See policy \fBCMP0127\fP\&. |
| |
| .SS CMakeFindDependencyMacro |
| .INDENT 0.0 |
| .TP |
| .B find_dependency |
| The \fBfind_dependency()\fP macro wraps a \fBfind_package()\fP call for |
| a package dependency: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_dependency(<dep> [...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| It is designed to be used in a |
| Package Configuration File |
| (\fB<PackageName>Config.cmake\fP). \fBfind_dependency\fP forwards the correct |
| parameters for \fBQUIET\fP and \fBREQUIRED\fP which were passed to |
| the original \fBfind_package()\fP call. Any additional arguments |
| specified are forwarded to \fBfind_package()\fP\&. |
| .sp |
| If the dependency could not be found it sets an informative diagnostic |
| message and calls \fBreturn()\fP to end processing of the calling |
| package configuration file and return to the \fBfind_package()\fP |
| command that loaded it. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| The call to \fBreturn()\fP makes this macro unsuitable to call |
| from Find Modules\&. |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .SS CMakeFindFrameworks |
| .sp |
| helper module to find OSX frameworks |
| .sp |
| This module reads hints about search locations from variables: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| CMAKE_FIND_FRAMEWORK_EXTRA_LOCATIONS \- Extra directories |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS CMakeFindPackageMode |
| .sp |
| This file is executed by cmake when invoked with \-\-find\-package. It |
| expects that the following variables are set using \-D: |
| .INDENT 0.0 |
| .TP |
| .B \fBNAME\fP |
| name of the package |
| .TP |
| .B \fBCOMPILER_ID\fP |
| the CMake compiler ID for which the result is, |
| i.e. GNU/Intel/Clang/MSVC, etc. |
| .TP |
| .B \fBLANGUAGE\fP |
| language for which the result will be used, |
| i.e. C/CXX/Fortran/ASM |
| .TP |
| .B \fBMODE\fP |
| .INDENT 7.0 |
| .TP |
| .B \fBEXIST\fP |
| only check for existence of the given package |
| .TP |
| .B \fBCOMPILE\fP |
| print the flags needed for compiling an object file which uses |
| the given package |
| .TP |
| .B \fBLINK\fP |
| print the flags needed for linking when using the given package |
| .UNINDENT |
| .TP |
| .B \fBQUIET\fP |
| if TRUE, don\(aqt print anything |
| .UNINDENT |
| .SS CMakeGraphVizOptions |
| .sp |
| The builtin Graphviz support of CMake. |
| .SS Generating Graphviz files |
| .sp |
| CMake can generate \fI\%Graphviz\fP files showing the |
| dependencies between the targets in a project, as well as external libraries |
| which are linked against. |
| .sp |
| When running CMake with the \fB\-\-graphviz=foo.dot\fP option, it produces: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| a \fBfoo.dot\fP file, showing all dependencies in the project |
| .IP \(bu 2 |
| a \fBfoo.dot.<target>\fP file for each target, showing on which other targets |
| it depends |
| .IP \(bu 2 |
| a \fBfoo.dot.<target>.dependers\fP file for each target, showing which other |
| targets depend on it |
| .UNINDENT |
| .sp |
| Those .dot files can be converted to images using the \fIdot\fP command from the |
| Graphviz package: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| dot \-Tpng \-o foo.png foo.dot |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.10: The different dependency types \fBPUBLIC\fP, \fBINTERFACE\fP and \fBPRIVATE\fP |
| are represented as solid, dashed and dotted edges. |
| |
| .SS Variables specific to the Graphviz support |
| .sp |
| The resulting graphs can be huge. The look and content of the generated graphs |
| can be controlled using the file \fBCMakeGraphVizOptions.cmake\fP\&. This file is |
| first searched in \fBCMAKE_BINARY_DIR\fP, and then in |
| \fBCMAKE_SOURCE_DIR\fP\&. If found, the variables set in it are used to |
| adjust options for the generated Graphviz files. |
| .INDENT 0.0 |
| .TP |
| .B GRAPHVIZ_GRAPH_NAME |
| The graph name. |
| .INDENT 7.0 |
| .IP \(bu 2 |
| Mandatory: NO |
| .IP \(bu 2 |
| Default: value of \fBCMAKE_PROJECT_NAME\fP |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B GRAPHVIZ_GRAPH_HEADER |
| The header written at the top of the Graphviz files. |
| .INDENT 7.0 |
| .IP \(bu 2 |
| Mandatory: NO |
| .IP \(bu 2 |
| Default: "node [ fontsize = "12" ];" |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B GRAPHVIZ_NODE_PREFIX |
| The prefix for each node in the Graphviz files. |
| .INDENT 7.0 |
| .IP \(bu 2 |
| Mandatory: NO |
| .IP \(bu 2 |
| Default: "node" |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B GRAPHVIZ_EXECUTABLES |
| Set to FALSE to exclude executables from the generated graphs. |
| .INDENT 7.0 |
| .IP \(bu 2 |
| Mandatory: NO |
| .IP \(bu 2 |
| Default: TRUE |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B GRAPHVIZ_STATIC_LIBS |
| Set to FALSE to exclude static libraries from the generated graphs. |
| .INDENT 7.0 |
| .IP \(bu 2 |
| Mandatory: NO |
| .IP \(bu 2 |
| Default: TRUE |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B GRAPHVIZ_SHARED_LIBS |
| Set to FALSE to exclude shared libraries from the generated graphs. |
| .INDENT 7.0 |
| .IP \(bu 2 |
| Mandatory: NO |
| .IP \(bu 2 |
| Default: TRUE |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B GRAPHVIZ_MODULE_LIBS |
| Set to FALSE to exclude module libraries from the generated graphs. |
| .INDENT 7.0 |
| .IP \(bu 2 |
| Mandatory: NO |
| .IP \(bu 2 |
| Default: TRUE |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B GRAPHVIZ_INTERFACE_LIBS |
| Set to FALSE to exclude interface libraries from the generated graphs. |
| .INDENT 7.0 |
| .IP \(bu 2 |
| Mandatory: NO |
| .IP \(bu 2 |
| Default: TRUE |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B GRAPHVIZ_OBJECT_LIBS |
| Set to FALSE to exclude object libraries from the generated graphs. |
| .INDENT 7.0 |
| .IP \(bu 2 |
| Mandatory: NO |
| .IP \(bu 2 |
| Default: TRUE |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B GRAPHVIZ_UNKNOWN_LIBS |
| Set to FALSE to exclude unknown libraries from the generated graphs. |
| .INDENT 7.0 |
| .IP \(bu 2 |
| Mandatory: NO |
| .IP \(bu 2 |
| Default: TRUE |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B GRAPHVIZ_EXTERNAL_LIBS |
| Set to FALSE to exclude external libraries from the generated graphs. |
| .INDENT 7.0 |
| .IP \(bu 2 |
| Mandatory: NO |
| .IP \(bu 2 |
| Default: TRUE |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B GRAPHVIZ_CUSTOM_TARGETS |
| Set to TRUE to include custom targets in the generated graphs. |
| .INDENT 7.0 |
| .IP \(bu 2 |
| Mandatory: NO |
| .IP \(bu 2 |
| Default: FALSE |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B GRAPHVIZ_IGNORE_TARGETS |
| A list of regular expressions for names of targets to exclude from the |
| generated graphs. |
| .INDENT 7.0 |
| .IP \(bu 2 |
| Mandatory: NO |
| .IP \(bu 2 |
| Default: empty |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B GRAPHVIZ_GENERATE_PER_TARGET |
| Set to FALSE to not generate per\-target graphs \fBfoo.dot.<target>\fP\&. |
| .INDENT 7.0 |
| .IP \(bu 2 |
| Mandatory: NO |
| .IP \(bu 2 |
| Default: TRUE |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B GRAPHVIZ_GENERATE_DEPENDERS |
| Set to FALSE to not generate depender graphs \fBfoo.dot.<target>.dependers\fP\&. |
| .INDENT 7.0 |
| .IP \(bu 2 |
| Mandatory: NO |
| .IP \(bu 2 |
| Default: TRUE |
| .UNINDENT |
| .UNINDENT |
| .SS CMakePackageConfigHelpers |
| .sp |
| Helpers functions for creating config files that can be included by other |
| projects to find and use a package. |
| .sp |
| Adds the \fI\%configure_package_config_file()\fP and |
| \fI\%write_basic_package_version_file()\fP commands. |
| .SS Generating a Package Configuration File |
| .INDENT 0.0 |
| .TP |
| .B configure_package_config_file |
| Create a config file for a project: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| configure_package_config_file(<input> <output> |
| INSTALL_DESTINATION <path> |
| [PATH_VARS <var1> <var2> ... <varN>] |
| [NO_SET_AND_CHECK_MACRO] |
| [NO_CHECK_REQUIRED_COMPONENTS_MACRO] |
| [INSTALL_PREFIX <path>] |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBconfigure_package_config_file()\fP should be used instead of the plain |
| \fBconfigure_file()\fP command when creating the \fB<PackageName>Config.cmake\fP |
| or \fB<PackageName>\-config.cmake\fP file for installing a project or library. |
| It helps making the resulting package relocatable by avoiding hardcoded paths |
| in the installed \fBConfig.cmake\fP file. |
| .sp |
| In a \fBFooConfig.cmake\fP file there may be code like this to make the install |
| destinations know to the using project: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(FOO_INCLUDE_DIR "@CMAKE_INSTALL_FULL_INCLUDEDIR@" ) |
| set(FOO_DATA_DIR "@CMAKE_INSTALL_PREFIX@/@RELATIVE_DATA_INSTALL_DIR@" ) |
| set(FOO_ICONS_DIR "@CMAKE_INSTALL_PREFIX@/share/icons" ) |
| #...logic to determine installedPrefix from the own location... |
| set(FOO_CONFIG_DIR "${installedPrefix}/@CONFIG_INSTALL_DIR@" ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| All 4 options shown above are not sufficient, since the first 3 hardcode the |
| absolute directory locations, and the 4th case works only if the logic to |
| determine the \fBinstalledPrefix\fP is correct, and if \fBCONFIG_INSTALL_DIR\fP |
| contains a relative path, which in general cannot be guaranteed. This has the |
| effect that the resulting \fBFooConfig.cmake\fP file would work poorly under |
| Windows and OSX, where users are used to choose the install location of a |
| binary package at install time, independent from how |
| \fBCMAKE_INSTALL_PREFIX\fP was set at build/cmake time. |
| .sp |
| Using \fBconfigure_package_config_file\fP helps. If used correctly, it makes |
| the resulting \fBFooConfig.cmake\fP file relocatable. Usage: |
| .INDENT 0.0 |
| .IP 1. 3 |
| write a \fBFooConfig.cmake.in\fP file as you are used to |
| .IP 2. 3 |
| insert a line containing only the string \fB@PACKAGE_INIT@\fP |
| .IP 3. 3 |
| instead of \fBset(FOO_DIR "@SOME_INSTALL_DIR@")\fP, use |
| \fBset(FOO_DIR "@PACKAGE_SOME_INSTALL_DIR@")\fP (this must be after the |
| \fB@PACKAGE_INIT@\fP line) |
| .IP 4. 3 |
| instead of using the normal \fBconfigure_file()\fP, use |
| \fBconfigure_package_config_file()\fP |
| .UNINDENT |
| .sp |
| The \fB<input>\fP and \fB<output>\fP arguments are the input and output file, the |
| same way as in \fBconfigure_file()\fP\&. |
| .sp |
| The \fB<path>\fP given to \fBINSTALL_DESTINATION\fP must be the destination where |
| the \fBFooConfig.cmake\fP file will be installed to. This path can either be |
| absolute, or relative to the \fBINSTALL_PREFIX\fP path. |
| .sp |
| The variables \fB<var1>\fP to \fB<varN>\fP given as \fBPATH_VARS\fP are the |
| variables which contain install destinations. For each of them the macro will |
| create a helper variable \fBPACKAGE_<var...>\fP\&. These helper variables must be |
| used in the \fBFooConfig.cmake.in\fP file for setting the installed location. |
| They are calculated by \fBconfigure_package_config_file\fP so that they are |
| always relative to the installed location of the package. This works both for |
| relative and also for absolute locations. For absolute locations it works |
| only if the absolute location is a subdirectory of \fBINSTALL_PREFIX\fP\&. |
| .sp |
| New in version 3.1: If the \fBINSTALL_PREFIX\fP argument is passed, this is used as base path to |
| calculate all the relative paths. The \fB<path>\fP argument must be an absolute |
| path. If this argument is not passed, the \fBCMAKE_INSTALL_PREFIX\fP |
| variable will be used instead. The default value is good when generating a |
| FooConfig.cmake file to use your package from the install tree. When |
| generating a FooConfig.cmake file to use your package from the build tree this |
| option should be used. |
| |
| .sp |
| By default \fBconfigure_package_config_file\fP also generates two helper macros, |
| \fBset_and_check()\fP and \fBcheck_required_components()\fP into the |
| \fBFooConfig.cmake\fP file. |
| .sp |
| \fBset_and_check()\fP should be used instead of the normal \fBset()\fP command for |
| setting directories and file locations. Additionally to setting the variable |
| it also checks that the referenced file or directory actually exists and fails |
| with a \fBFATAL_ERROR\fP otherwise. This makes sure that the created |
| \fBFooConfig.cmake\fP file does not contain wrong references. |
| When using the \fBNO_SET_AND_CHECK_MACRO\fP, this macro is not generated |
| into the \fBFooConfig.cmake\fP file. |
| .sp |
| \fBcheck_required_components(<PackageName>)\fP should be called at the end of |
| the \fBFooConfig.cmake\fP file. This macro checks whether all requested, |
| non\-optional components have been found, and if this is not the case, sets |
| the \fBFoo_FOUND\fP variable to \fBFALSE\fP, so that the package is considered to |
| be not found. It does that by testing the \fBFoo_<Component>_FOUND\fP |
| variables for all requested required components. This macro should be |
| called even if the package doesn\(aqt provide any components to make sure |
| users are not specifying components erroneously. When using the |
| \fBNO_CHECK_REQUIRED_COMPONENTS_MACRO\fP option, this macro is not generated |
| into the \fBFooConfig.cmake\fP file. |
| .sp |
| For an example see below the documentation for |
| \fI\%write_basic_package_version_file()\fP\&. |
| .SS Generating a Package Version File |
| .INDENT 0.0 |
| .TP |
| .B write_basic_package_version_file |
| Create a version file for a project: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| write_basic_package_version_file(<filename> |
| [VERSION <major.minor.patch>] |
| COMPATIBILITY <AnyNewerVersion|SameMajorVersion|SameMinorVersion|ExactVersion> |
| [ARCH_INDEPENDENT] ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Writes a file for use as \fB<PackageName>ConfigVersion.cmake\fP file to |
| \fB<filename>\fP\&. See the documentation of \fBfind_package()\fP for |
| details on this. |
| .sp |
| \fB<filename>\fP is the output filename, it should be in the build tree. |
| \fB<major.minor.patch>\fP is the version number of the project to be installed. |
| .sp |
| If no \fBVERSION\fP is given, the \fBPROJECT_VERSION\fP variable is used. |
| If this hasn\(aqt been set, it errors out. |
| .sp |
| The \fBCOMPATIBILITY\fP mode \fBAnyNewerVersion\fP means that the installed |
| package version will be considered compatible if it is newer or exactly the |
| same as the requested version. This mode should be used for packages which |
| are fully backward compatible, also across major versions. |
| If \fBSameMajorVersion\fP is used instead, then the behavior differs from |
| \fBAnyNewerVersion\fP in that the major version number must be the same as |
| requested, e.g. version 2.0 will not be considered compatible if 1.0 is |
| requested. This mode should be used for packages which guarantee backward |
| compatibility within the same major version. |
| If \fBSameMinorVersion\fP is used, the behavior is the same as |
| \fBSameMajorVersion\fP, but both major and minor version must be the same as |
| requested, e.g version 0.2 will not be compatible if 0.1 is requested. |
| If \fBExactVersion\fP is used, then the package is only considered compatible if |
| the requested version matches exactly its own version number (not considering |
| the tweak version). For example, version 1.2.3 of a package is only |
| considered compatible to requested version 1.2.3. This mode is for packages |
| without compatibility guarantees. |
| If your project has more elaborated version matching rules, you will need to |
| write your own custom \fBConfigVersion.cmake\fP file instead of using this |
| macro. |
| .sp |
| New in version 3.11: The \fBSameMinorVersion\fP compatibility mode. |
| |
| .sp |
| New in version 3.14: If \fBARCH_INDEPENDENT\fP is given, the installed package version will be |
| considered compatible even if it was built for a different architecture than |
| the requested architecture. Otherwise, an architecture check will be performed, |
| and the package will be considered compatible only if the architecture matches |
| exactly. For example, if the package is built for a 32\-bit architecture, the |
| package is only considered compatible if it is used on a 32\-bit architecture, |
| unless \fBARCH_INDEPENDENT\fP is given, in which case the package is considered |
| compatible on any architecture. |
| |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| \fBARCH_INDEPENDENT\fP is intended for header\-only libraries or similar |
| packages with no binaries. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.19: \fBCOMPATIBILITY_MODE\fP \fBAnyNewerVersion\fP, \fBSameMajorVersion\fP and |
| \fBSameMinorVersion\fP handle the version range if any is specified |
| (see \fBfind_package()\fP command for the details). |
| \fBExactVersion\fP mode is incompatible with version ranges and will display an |
| author warning if one is specified. |
| |
| .sp |
| Internally, this macro executes \fBconfigure_file()\fP to create the |
| resulting version file. Depending on the \fBCOMPATIBILITY\fP, the corresponding |
| \fBBasicConfigVersion\-<COMPATIBILITY>.cmake.in\fP file is used. |
| Please note that these files are internal to CMake and you should not call |
| \fBconfigure_file()\fP on them yourself, but they can be used as starting |
| point to create more sophisticted custom \fBConfigVersion.cmake\fP files. |
| .SS Example Generating Package Files |
| .sp |
| Example using both \fI\%configure_package_config_file()\fP and |
| \fBwrite_basic_package_version_file()\fP: |
| .sp |
| \fBCMakeLists.txt\fP: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(INCLUDE_INSTALL_DIR include/ ... CACHE ) |
| set(LIB_INSTALL_DIR lib/ ... CACHE ) |
| set(SYSCONFIG_INSTALL_DIR etc/foo/ ... CACHE ) |
| #... |
| include(CMakePackageConfigHelpers) |
| configure_package_config_file(FooConfig.cmake.in |
| ${CMAKE_CURRENT_BINARY_DIR}/FooConfig.cmake |
| INSTALL_DESTINATION ${LIB_INSTALL_DIR}/Foo/cmake |
| PATH_VARS INCLUDE_INSTALL_DIR SYSCONFIG_INSTALL_DIR) |
| write_basic_package_version_file( |
| ${CMAKE_CURRENT_BINARY_DIR}/FooConfigVersion.cmake |
| VERSION 1.2.3 |
| COMPATIBILITY SameMajorVersion ) |
| install(FILES ${CMAKE_CURRENT_BINARY_DIR}/FooConfig.cmake |
| ${CMAKE_CURRENT_BINARY_DIR}/FooConfigVersion.cmake |
| DESTINATION ${LIB_INSTALL_DIR}/Foo/cmake ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBFooConfig.cmake.in\fP: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(FOO_VERSION x.y.z) |
| \&... |
| @PACKAGE_INIT@ |
| \&... |
| set_and_check(FOO_INCLUDE_DIR "@PACKAGE_INCLUDE_INSTALL_DIR@") |
| set_and_check(FOO_SYSCONFIG_DIR "@PACKAGE_SYSCONFIG_INSTALL_DIR@") |
| |
| check_required_components(Foo) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS CMakePrintHelpers |
| .sp |
| Convenience functions for printing properties and variables, useful |
| e.g. for debugging. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cmake_print_properties([TARGETS target1 .. targetN] |
| [SOURCES source1 .. sourceN] |
| [DIRECTORIES dir1 .. dirN] |
| [TESTS test1 .. testN] |
| [CACHE_ENTRIES entry1 .. entryN] |
| PROPERTIES prop1 .. propN ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This function prints the values of the properties of the given targets, |
| source files, directories, tests or cache entries. Exactly one of the |
| scope keywords must be used. Example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cmake_print_properties(TARGETS foo bar PROPERTIES |
| LOCATION INTERFACE_INCLUDE_DIRECTORIES) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This will print the LOCATION and INTERFACE_INCLUDE_DIRECTORIES properties for |
| both targets foo and bar. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cmake_print_variables(var1 var2 .. varN) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This function will print the name of each variable followed by its value. |
| Example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cmake_print_variables(CMAKE_C_COMPILER CMAKE_MAJOR_VERSION DOES_NOT_EXIST) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Gives: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| \-\- CMAKE_C_COMPILER="/usr/bin/gcc" ; CMAKE_MAJOR_VERSION="2" ; DOES_NOT_EXIST="" |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS CMakePrintSystemInformation |
| .sp |
| Print system information. |
| .sp |
| This module serves diagnostic purposes. Just include it in a |
| project to see various internal CMake variables. |
| .SS CMakePushCheckState |
| .sp |
| This module defines three macros: \fBCMAKE_PUSH_CHECK_STATE()\fP |
| \fBCMAKE_POP_CHECK_STATE()\fP and \fBCMAKE_RESET_CHECK_STATE()\fP These macros can |
| be used to save, restore and reset (i.e., clear contents) the state of |
| the variables \fBCMAKE_REQUIRED_FLAGS\fP, \fBCMAKE_REQUIRED_DEFINITIONS\fP, |
| \fBCMAKE_REQUIRED_LINK_OPTIONS\fP, \fBCMAKE_REQUIRED_LIBRARIES\fP, |
| \fBCMAKE_REQUIRED_INCLUDES\fP and \fBCMAKE_EXTRA_INCLUDE_FILES\fP used by the |
| various Check\-files coming with CMake, like e.g. \fBcheck_function_exists()\fP |
| etc. |
| The variable contents are pushed on a stack, pushing multiple times is |
| supported. This is useful e.g. when executing such tests in a Find\-module, |
| where they have to be set, but after the Find\-module has been executed they |
| should have the same value as they had before. |
| .sp |
| \fBCMAKE_PUSH_CHECK_STATE()\fP macro receives optional argument \fBRESET\fP\&. |
| Whether it\(aqs specified, \fBCMAKE_PUSH_CHECK_STATE()\fP will set all |
| \fBCMAKE_REQUIRED_*\fP variables to empty values, same as |
| \fBCMAKE_RESET_CHECK_STATE()\fP call will do. |
| .sp |
| Usage: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cmake_push_check_state(RESET) |
| set(CMAKE_REQUIRED_DEFINITIONS \-DSOME_MORE_DEF) |
| check_function_exists(...) |
| cmake_reset_check_state() |
| set(CMAKE_REQUIRED_DEFINITIONS \-DANOTHER_DEF) |
| check_function_exists(...) |
| cmake_pop_check_state() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS CMakeVerifyManifest |
| .sp |
| CMakeVerifyManifest.cmake |
| .sp |
| This script is used to verify that embedded manifests and side by side |
| manifests for a project match. To run this script, cd to a directory |
| and run the script with cmake \-P. On the command line you can pass in |
| versions that are OK even if not found in the .manifest files. For |
| example, cmake \-Dallow_versions=8.0.50608.0 |
| \-PCmakeVerifyManifest.cmake could be used to allow an embedded manifest |
| of 8.0.50608.0 to be used in a project even if that version was not |
| found in the .manifest file. |
| .SS CPack |
| .sp |
| Configure generators for binary installers and source packages. |
| .SS Introduction |
| .sp |
| The CPack module generates the configuration files \fBCPackConfig.cmake\fP |
| and \fBCPackSourceConfig.cmake\fP\&. They are intended for use in a subsequent |
| run of the \fBcpack\fP program where they steer the generation |
| of installers or/and source packages. |
| .sp |
| Depending on the CMake generator, the CPack module may also add two new build |
| targets, \fBpackage\fP and \fBpackage_source\fP\&. See the \fI\%packaging targets\fP |
| section below for details. |
| .sp |
| The generated binary installers will contain all files that have been installed |
| via CMake\(aqs \fBinstall()\fP command (and the deprecated commands |
| \fBinstall_files()\fP, \fBinstall_programs()\fP, and |
| \fBinstall_targets()\fP). Note that the \fBDESTINATION\fP option of the |
| \fBinstall()\fP command must be a relative path; otherwise installed files |
| are ignored by CPack. |
| .sp |
| Certain kinds of binary installers can be configured such that users can select |
| individual application components to install. See the \fBCPackComponent\fP |
| module for further details. |
| .sp |
| Source packages (configured through \fBCPackSourceConfig.cmake\fP and generated |
| by the \fBCPack Archive Generator\fP) will contain all source files in |
| the project directory except those specified in |
| \fI\%CPACK_SOURCE_IGNORE_FILES\fP\&. |
| .SS CPack Generators |
| .sp |
| The \fI\%CPACK_GENERATOR\fP variable has different meanings in different |
| contexts. In a \fBCMakeLists.txt\fP file, \fI\%CPACK_GENERATOR\fP is a |
| \fIlist of generators\fP: and when \fBcpack\fP is run with no other |
| arguments, it will iterate over that list and produce one package for each |
| generator. In a \fI\%CPACK_PROJECT_CONFIG_FILE\fP, |
| \fI\%CPACK_GENERATOR\fP is a \fIstring naming a single generator\fP\&. If you |
| need per\-cpack\-generator logic to control \fIother\fP cpack settings, then you |
| need a \fI\%CPACK_PROJECT_CONFIG_FILE\fP\&. |
| If set, the \fI\%CPACK_PROJECT_CONFIG_FILE\fP is included automatically |
| on a per\-generator basis. It only need contain overrides. |
| .sp |
| Here\(aqs how it works: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBcpack\fP runs |
| .IP \(bu 2 |
| it includes \fBCPackConfig.cmake\fP |
| .IP \(bu 2 |
| it iterates over the generators given by the \fB\-G\fP command line option, |
| or if no such option was specified, over the list of generators given by |
| the \fI\%CPACK_GENERATOR\fP variable set in the \fBCPackConfig.cmake\fP |
| input file. |
| .IP \(bu 2 |
| foreach generator, it then |
| .INDENT 2.0 |
| .IP \(bu 2 |
| sets \fI\%CPACK_GENERATOR\fP to the one currently being iterated |
| .IP \(bu 2 |
| includes the \fI\%CPACK_PROJECT_CONFIG_FILE\fP |
| .IP \(bu 2 |
| produces the package for that generator |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This is the key: For each generator listed in \fI\%CPACK_GENERATOR\fP in |
| \fBCPackConfig.cmake\fP, cpack will \fIreset\fP \fI\%CPACK_GENERATOR\fP |
| internally to \fIthe one currently being used\fP and then include the |
| \fI\%CPACK_PROJECT_CONFIG_FILE\fP\&. |
| .sp |
| For a list of available generators, see \fBcpack\-generators(7)\fP\&. |
| .SS Targets package and package_source |
| .sp |
| If CMake is run with the Makefile, Ninja, or Xcode generator, then |
| \fBinclude(CPack)\fP generates a target \fBpackage\fP\&. This makes it possible |
| to build a binary installer from CMake, Make, or Ninja: Instead of \fBcpack\fP, |
| one may call \fBcmake \-\-build . \-\-target package\fP or \fBmake package\fP or |
| \fBninja package\fP\&. The VS generator creates an uppercase target \fBPACKAGE\fP\&. |
| .sp |
| If CMake is run with the Makefile or Ninja generator, then \fBinclude(CPack)\fP |
| also generates a target \fBpackage_source\fP\&. To build a source package, |
| instead of \fBcpack \-G TGZ \-\-config CPackSourceConfig.cmake\fP one may call |
| \fBcmake \-\-build . \-\-target package_source\fP, \fBmake package_source\fP, |
| or \fBninja package_source\fP\&. |
| .SS Variables common to all CPack Generators |
| .sp |
| Before including this CPack module in your \fBCMakeLists.txt\fP file, there |
| are a variety of variables that can be set to customize the resulting |
| installers. The most commonly\-used variables are: |
| .INDENT 0.0 |
| .TP |
| .B CPACK_PACKAGE_NAME |
| The name of the package (or application). If not specified, it defaults to |
| the project name. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_PACKAGE_VENDOR |
| The name of the package vendor. (e.g., "Kitware"). The default is "Humanity". |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_PACKAGE_DIRECTORY |
| The directory in which CPack is doing its packaging. If it is not set |
| then this will default (internally) to the build dir. This variable may |
| be defined in a CPack config file or from the \fBcpack\fP |
| command line option \fB\-B\fP\&. If set, the command line option overrides the |
| value found in the config file. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_PACKAGE_VERSION_MAJOR |
| Package major version. This variable will always be set, but its default |
| value depends on whether or not version details were given to the |
| \fBproject()\fP command in the top level CMakeLists.txt file. If version |
| details were given, the default value will be |
| \fBCMAKE_PROJECT_VERSION_MAJOR\fP\&. If no version details were given, |
| a default version of 0.1.1 will be assumed, leading to |
| \fBCPACK_PACKAGE_VERSION_MAJOR\fP having a default value of 0. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_PACKAGE_VERSION_MINOR |
| Package minor version. The default value is determined based on whether or |
| not version details were given to the \fBproject()\fP command in the top |
| level CMakeLists.txt file. If version details were given, the default |
| value will be \fBCMAKE_PROJECT_VERSION_MINOR\fP, but if no minor |
| version component was specified then \fBCPACK_PACKAGE_VERSION_MINOR\fP will be |
| left unset. If no project version was given at all, a default version of |
| 0.1.1 will be assumed, leading to \fBCPACK_PACKAGE_VERSION_MINOR\fP having a |
| default value of 1. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_PACKAGE_VERSION_PATCH |
| Package patch version. The default value is determined based on whether or |
| not version details were given to the \fBproject()\fP command in the top |
| level CMakeLists.txt file. If version details were given, the default |
| value will be \fBCMAKE_PROJECT_VERSION_PATCH\fP, but if no patch |
| version component was specified then \fBCPACK_PACKAGE_VERSION_PATCH\fP will be |
| left unset. If no project version was given at all, a default version of |
| 0.1.1 will be assumed, leading to \fBCPACK_PACKAGE_VERSION_PATCH\fP having a |
| default value of 1. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_PACKAGE_DESCRIPTION |
| A description of the project, used in places such as the introduction |
| screen of CPack\-generated Windows installers. If not set, the value of |
| this variable is populated from the file named by |
| \fI\%CPACK_PACKAGE_DESCRIPTION_FILE\fP\&. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_PACKAGE_DESCRIPTION_FILE |
| A text file used to describe the project when |
| \fI\%CPACK_PACKAGE_DESCRIPTION\fP is not explicitly set. The default |
| value for \fBCPACK_PACKAGE_DESCRIPTION_FILE\fP points to a built\-in template |
| file \fBTemplates/CPack.GenericDescription.txt\fP\&. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_PACKAGE_DESCRIPTION_SUMMARY |
| Short description of the project (only a few words). If the |
| \fBCMAKE_PROJECT_DESCRIPTION\fP variable is set, it is used as the |
| default value, otherwise the default will be a string generated by CMake |
| based on \fBCMAKE_PROJECT_NAME\fP\&. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_PACKAGE_HOMEPAGE_URL |
| Project homepage URL. The default value is taken from the |
| \fBCMAKE_PROJECT_HOMEPAGE_URL\fP variable, which is set by the top |
| level \fBproject()\fP command, or else the default will be empty if no |
| URL was provided to \fBproject()\fP\&. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_PACKAGE_FILE_NAME |
| The name of the package file to generate, not including the |
| extension. For example, \fBcmake\-2.6.1\-Linux\-i686\fP\&. The default value |
| is: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ${CPACK_PACKAGE_NAME}\-${CPACK_PACKAGE_VERSION}\-${CPACK_SYSTEM_NAME} |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_PACKAGE_INSTALL_DIRECTORY |
| Installation directory on the target system. This may be used by some |
| CPack generators like NSIS to create an installation directory e.g., |
| "CMake 2.5" below the installation prefix. All installed elements will be |
| put inside this directory. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_PACKAGE_ICON |
| A branding image that will be displayed inside the installer (used by GUI |
| installers). |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_PACKAGE_CHECKSUM |
| New in version 3.7. |
| |
| .sp |
| An algorithm that will be used to generate an additional file with the |
| checksum of the package. The output file name will be: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ${CPACK_PACKAGE_FILE_NAME}.${CPACK_PACKAGE_CHECKSUM} |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Supported algorithms are those listed by the |
| string(<HASH>) command. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_PROJECT_CONFIG_FILE |
| CPack\-time project CPack configuration file. This file is included at cpack |
| time, once per generator after CPack has set \fI\%CPACK_GENERATOR\fP |
| to the actual generator being used. It allows per\-generator setting of |
| \fBCPACK_*\fP variables at cpack time. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_RESOURCE_FILE_LICENSE |
| License to be embedded in the installer. It will typically be displayed |
| to the user by the produced installer (often with an explicit "Accept" |
| button, for graphical installers) prior to installation. This license |
| file is NOT added to the installed files but is used by some CPack generators |
| like NSIS. If you want to install a license file (may be the same as this |
| one) along with your project, you must add an appropriate CMake |
| \fBinstall()\fP command in your \fBCMakeLists.txt\fP\&. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_RESOURCE_FILE_README |
| ReadMe file to be embedded in the installer. It typically describes in |
| some detail the purpose of the project during the installation. Not all |
| CPack generators use this file. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_RESOURCE_FILE_WELCOME |
| Welcome file to be embedded in the installer. It welcomes users to this |
| installer. Typically used in the graphical installers on Windows and Mac |
| OS X. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_MONOLITHIC_INSTALL |
| Disables the component\-based installation mechanism. When set, the |
| component specification is ignored and all installed items are put in a |
| single "MONOLITHIC" package. Some CPack generators do monolithic |
| packaging by default and may be asked to do component packaging by |
| setting \fBCPACK_<GENNAME>_COMPONENT_INSTALL\fP to \fBTRUE\fP\&. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_GENERATOR |
| List of CPack generators to use. If not specified, CPack will create a |
| set of options following the naming pattern |
| \fI\%CPACK_BINARY_<GENNAME>\fP (e.g. \fBCPACK_BINARY_NSIS\fP) allowing |
| the user to enable/disable individual generators. If the \fB\-G\fP option is |
| given on the \fBcpack\fP command line, it will override this |
| variable and any \fBCPACK_BINARY_<GENNAME>\fP options. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_OUTPUT_CONFIG_FILE |
| The name of the CPack binary configuration file. This file is the CPack |
| configuration generated by the CPack module for binary installers. |
| Defaults to \fBCPackConfig.cmake\fP\&. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_PACKAGE_EXECUTABLES |
| Lists each of the executables and associated text label to be used to |
| create Start Menu shortcuts. For example, setting this to the list |
| \fBccmake;CMake\fP will create a shortcut named "CMake" that will execute the |
| installed executable \fBccmake\fP\&. Not all CPack generators use it (at least |
| NSIS, and WIX do). |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_STRIP_FILES |
| List of files to be stripped. Starting with CMake 2.6.0, |
| \fBCPACK_STRIP_FILES\fP will be a boolean variable which enables |
| stripping of all files (a list of files evaluates to \fBTRUE\fP in CMake, |
| so this change is compatible). |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_VERBATIM_VARIABLES |
| New in version 3.4. |
| |
| .sp |
| If set to \fBTRUE\fP, values of variables prefixed with \fBCPACK_\fP will be |
| escaped before being written to the configuration files, so that the cpack |
| program receives them exactly as they were specified. If not, characters |
| like quotes and backslashes can cause parsing errors or alter the value |
| received by the cpack program. Defaults to \fBFALSE\fP for backwards |
| compatibility. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_THREADS |
| New in version 3.20. |
| |
| .sp |
| Number of threads to use when performing parallelized operations, such |
| as compressing the installer package. |
| .sp |
| Some compression methods used by CPack generators such as Debian or Archive |
| may take advantage of multiple CPU cores to speed up compression. |
| \fBCPACK_THREADS\fP can be set to specify how many threads will be |
| used for compression. |
| .sp |
| A positive integer can be used to specify an exact desired thread count. |
| .sp |
| When given a negative integer CPack will use the absolute value |
| as the upper limit but may choose a lower value based on |
| the available hardware concurrency. |
| .sp |
| Given 0 CPack will try to use all available CPU cores. |
| .sp |
| By default \fBCPACK_THREADS\fP is set to \fB1\fP\&. |
| .sp |
| Currently only \fBxz\fP compression \fImay\fP take advantage of multiple cores. |
| Other compression methods ignore this value and use only one thread. |
| .sp |
| New in version 3.21: Official CMake binaries available on \fBcmake.org\fP now ship |
| with a \fBliblzma\fP that supports parallel compression. |
| Older versions did not. |
| |
| .UNINDENT |
| .SS Variables for Source Package Generators |
| .sp |
| The following CPack variables are specific to source packages, and |
| will not affect binary packages: |
| .INDENT 0.0 |
| .TP |
| .B CPACK_SOURCE_PACKAGE_FILE_NAME |
| The name of the source package. For example \fBcmake\-2.6.1\fP\&. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_SOURCE_STRIP_FILES |
| List of files in the source tree that will be stripped. Starting with |
| CMake 2.6.0, \fBCPACK_SOURCE_STRIP_FILES\fP will be a boolean |
| variable which enables stripping of all files (a list of files evaluates |
| to \fBTRUE\fP in CMake, so this change is compatible). |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_SOURCE_GENERATOR |
| List of generators used for the source packages. As with |
| \fI\%CPACK_GENERATOR\fP, if this is not specified then CPack will |
| create a set of options (e.g. \fBCPACK_SOURCE_ZIP\fP) allowing |
| users to select which packages will be generated. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_SOURCE_OUTPUT_CONFIG_FILE |
| The name of the CPack source configuration file. This file is the CPack |
| configuration generated by the CPack module for source installers. |
| Defaults to \fBCPackSourceConfig.cmake\fP\&. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_SOURCE_IGNORE_FILES |
| Pattern of files in the source tree that won\(aqt be packaged when building |
| a source package. This is a list of regular expression patterns (that |
| must be properly escaped), e.g., |
| \fB/CVS/;/\e\e.svn/;\e\e.swp$;\e\e.#;/#;.*~;cscope.*\fP |
| .UNINDENT |
| .SS Variables for Advanced Use |
| .sp |
| The following variables are for advanced uses of CPack: |
| .INDENT 0.0 |
| .TP |
| .B CPACK_CMAKE_GENERATOR |
| What CMake generator should be used if the project is a CMake |
| project. Defaults to the value of \fBCMAKE_GENERATOR\fP\&. Few users |
| will want to change this setting. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_INSTALL_CMAKE_PROJECTS |
| List of four values that specify what project to install. The four values |
| are: Build directory, Project Name, Project Component, Directory. If |
| omitted, CPack will build an installer that installs everything. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_SYSTEM_NAME |
| System name, defaults to the value of \fBCMAKE_SYSTEM_NAME\fP, |
| except on Windows where it will be \fBwin32\fP or \fBwin64\fP\&. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_PACKAGE_VERSION |
| Package full version, used internally. By default, this is built from |
| \fI\%CPACK_PACKAGE_VERSION_MAJOR\fP, |
| \fI\%CPACK_PACKAGE_VERSION_MINOR\fP, and |
| \fI\%CPACK_PACKAGE_VERSION_PATCH\fP\&. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_TOPLEVEL_TAG |
| Directory for the installed files. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_INSTALL_COMMANDS |
| Extra commands to install components. The environment variable |
| \fBCMAKE_INSTALL_PREFIX\fP is set to the temporary install directory |
| during execution. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_INSTALL_SCRIPTS |
| New in version 3.16. |
| |
| .sp |
| Extra CMake scripts executed by CPack during its local staging |
| installation. They are executed before installing the files to be packaged. |
| The scripts are not called by a standalone install (e.g.: \fBmake install\fP). |
| For every script, the following variables will be set: |
| \fBCMAKE_CURRENT_SOURCE_DIR\fP, \fBCMAKE_CURRENT_BINARY_DIR\fP |
| and \fBCMAKE_INSTALL_PREFIX\fP (which is set to the staging install |
| directory). The singular form \fBCMAKE_INSTALL_SCRIPT\fP is supported as |
| an alternative variable for historical reasons, but its value is ignored if |
| \fBCMAKE_INSTALL_SCRIPTS\fP is set and a warning will be issued. |
| .sp |
| See also \fI\%CPACK_PRE_BUILD_SCRIPTS\fP and |
| \fI\%CPACK_POST_BUILD_SCRIPTS\fP which can be used to specify scripts |
| to be executed later in the packaging process. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_PRE_BUILD_SCRIPTS |
| New in version 3.19. |
| |
| .sp |
| List of CMake scripts to execute after CPack has installed the files to |
| be packaged into a staging directory and before producing the package(s) |
| from those files. See also \fI\%CPACK_INSTALL_SCRIPTS\fP and |
| \fI\%CPACK_POST_BUILD_SCRIPTS\fP\&. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_POST_BUILD_SCRIPTS |
| New in version 3.19. |
| |
| .sp |
| List of CMake scripts to execute after CPack has produced the resultant |
| packages and before copying them back to the build directory. |
| See also \fI\%CPACK_INSTALL_SCRIPTS\fP, |
| \fI\%CPACK_PRE_BUILD_SCRIPTS\fP and \fI\%CPACK_PACKAGE_FILES\fP\&. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_PACKAGE_FILES |
| New in version 3.19. |
| |
| .sp |
| List of package files created in the staging directory, with each file |
| provided as a full absolute path. This variable is populated by CPack |
| just before invoking the post\-build scripts listed in |
| \fI\%CPACK_POST_BUILD_SCRIPTS\fP\&. It is the preferred way for the |
| post\-build scripts to know the set of package files to operate on. |
| Projects should not try to set this variable themselves. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_INSTALLED_DIRECTORIES |
| Extra directories to install. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_PACKAGE_INSTALL_REGISTRY_KEY |
| Registry key used when installing this project. This is only used by |
| installers for Windows. The default value is based on the installation |
| directory. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_CREATE_DESKTOP_LINKS |
| List of desktop links to create. Each desktop link requires a |
| corresponding start menu shortcut as created by |
| \fI\%CPACK_PACKAGE_EXECUTABLES\fP\&. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_BINARY_<GENNAME> |
| CPack generated options for binary generators. The \fBCPack.cmake\fP module |
| generates (when \fI\%CPACK_GENERATOR\fP is not set) a set of CMake |
| options (see CMake \fBoption()\fP command) which may then be used to |
| select the CPack generator(s) to be used when building the \fBpackage\fP |
| target or when running \fBcpack\fP without the \fB\-G\fP option. |
| .UNINDENT |
| .SS CPackComponent |
| .sp |
| Configure components for binary installers and source packages. |
| .SS Introduction |
| .sp |
| This module is automatically included by \fBCPack\fP\&. |
| .sp |
| Certain binary installers (especially the graphical installers) generated |
| by CPack allow users to select individual application \fIcomponents\fP to install. |
| This module allows developers to configure the packaging of such components. |
| .sp |
| Contents is assigned to components by the \fBCOMPONENT\fP |
| argument of CMake\(aqs \fBinstall()\fP command. Components can be |
| annotated with user\-friendly names and descriptions, inter\-component |
| dependencies, etc., and grouped in various ways to customize the |
| resulting installer, using the commands described below. |
| .sp |
| To specify different groupings for different CPack generators use |
| a CPACK_PROJECT_CONFIG_FILE. |
| .SS Variables |
| .sp |
| The following variables influence the component\-specific packaging: |
| .INDENT 0.0 |
| .TP |
| .B CPACK_COMPONENTS_ALL |
| The list of component to install. |
| .sp |
| The default value of this variable is computed by CPack and contains all |
| components defined by the project. The user may set it to only include the |
| specified components. |
| .sp |
| Instead of specifying all the desired components, it is possible to obtain a |
| list of all defined components and then remove the unwanted ones from the |
| list. The \fBget_cmake_property()\fP command can be used to obtain the |
| \fBCOMPONENTS\fP property, then the \fBlist(REMOVE_ITEM)\fP command can be |
| used to remove the unwanted ones. For example, to use all defined components |
| except \fBfoo\fP and \fBbar\fP: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| get_cmake_property(CPACK_COMPONENTS_ALL COMPONENTS) |
| list(REMOVE_ITEM CPACK_COMPONENTS_ALL "foo" "bar") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_<GENNAME>_COMPONENT_INSTALL |
| Enable/Disable component install for CPack generator <GENNAME>. |
| .sp |
| Each CPack Generator (RPM, DEB, ARCHIVE, NSIS, DMG, etc...) has a legacy |
| default behavior. e.g. RPM builds monolithic whereas NSIS builds |
| component. One can change the default behavior by setting this variable to |
| 0/1 or OFF/ON. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_COMPONENTS_GROUPING |
| Specify how components are grouped for multi\-package component\-aware CPack |
| generators. |
| .sp |
| Some generators like RPM or ARCHIVE (TGZ, ZIP, ...) may generate |
| several packages files when there are components, depending |
| on the value of this variable: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| ONE_PER_GROUP (default): create one package per component group |
| .IP \(bu 2 |
| IGNORE : create one package per component (ignore the groups) |
| .IP \(bu 2 |
| ALL_COMPONENTS_IN_ONE : create a single package with all requested |
| components |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_COMPONENT_<compName>_DISPLAY_NAME |
| The name to be displayed for a component. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_COMPONENT_<compName>_DESCRIPTION |
| The description of a component. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_COMPONENT_<compName>_GROUP |
| The group of a component. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_COMPONENT_<compName>_DEPENDS |
| The dependencies (list of components) on which this component depends. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_COMPONENT_<compName>_HIDDEN |
| True if this component is hidden from the user. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_COMPONENT_<compName>_REQUIRED |
| True if this component is required. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CPACK_COMPONENT_<compName>_DISABLED |
| True if this component is not selected to be installed by default. |
| .UNINDENT |
| .SS Commands |
| .SS Add component |
| .INDENT 0.0 |
| .TP |
| .B cpack_add_component |
| .UNINDENT |
| .sp |
| Describe an installation component. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cpack_add_component(compname |
| [DISPLAY_NAME name] |
| [DESCRIPTION description] |
| [HIDDEN | REQUIRED | DISABLED ] |
| [GROUP group] |
| [DEPENDS comp1 comp2 ... ] |
| [INSTALL_TYPES type1 type2 ... ] |
| [DOWNLOADED] |
| [ARCHIVE_FILE filename] |
| [PLIST filename]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBcompname\fP is the name of an installation component, as defined by the |
| \fBCOMPONENT\fP argument of one or more CMake \fBinstall()\fP commands. |
| With the \fBcpack_add_component\fP command one can set a name, a description, |
| and other attributes of an installation component. |
| One can also assign a component to a component group. |
| .sp |
| DISPLAY_NAME is the displayed name of the component, used in graphical |
| installers to display the component name. This value can be any |
| string. |
| .sp |
| DESCRIPTION is an extended description of the component, used in |
| graphical installers to give the user additional information about the |
| component. Descriptions can span multiple lines using \fB\en\fP as the |
| line separator. Typically, these descriptions should be no more than |
| a few lines long. |
| .sp |
| HIDDEN indicates that this component will be hidden in the graphical |
| installer, so that the user cannot directly change whether it is |
| installed or not. |
| .sp |
| REQUIRED indicates that this component is required, and therefore will |
| always be installed. It will be visible in the graphical installer, |
| but it cannot be unselected. (Typically, required components are |
| shown greyed out). |
| .sp |
| DISABLED indicates that this component should be disabled (unselected) |
| by default. The user is free to select this component for |
| installation, unless it is also HIDDEN. |
| .sp |
| DEPENDS lists the components on which this component depends. If this |
| component is selected, then each of the components listed must also be |
| selected. The dependency information is encoded within the installer |
| itself, so that users cannot install inconsistent sets of components. |
| .sp |
| GROUP names the component group of which this component is a part. If |
| not provided, the component will be a standalone component, not part |
| of any component group. Component groups are described with the |
| cpack_add_component_group command, detailed below. |
| .sp |
| INSTALL_TYPES lists the installation types of which this component is |
| a part. When one of these installations types is selected, this |
| component will automatically be selected. Installation types are |
| described with the cpack_add_install_type command, detailed below. |
| .sp |
| DOWNLOADED indicates that this component should be downloaded |
| on\-the\-fly by the installer, rather than packaged in with the |
| installer itself. For more information, see the |
| cpack_configure_downloads command. |
| .sp |
| ARCHIVE_FILE provides a name for the archive file created by CPack to |
| be used for downloaded components. If not supplied, CPack will create |
| a file with some name based on CPACK_PACKAGE_FILE_NAME and the name of |
| the component. See cpack_configure_downloads for more information. |
| .sp |
| PLIST gives a filename that is passed to pkgbuild with the |
| \fB\-\-component\-plist\fP argument when using the productbuild generator. |
| .SS Add component group |
| .INDENT 0.0 |
| .TP |
| .B cpack_add_component_group |
| .UNINDENT |
| .sp |
| Describes a group of related CPack installation components. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cpack_add_component_group(groupname |
| [DISPLAY_NAME name] |
| [DESCRIPTION description] |
| [PARENT_GROUP parent] |
| [EXPANDED] |
| [BOLD_TITLE]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The cpack_add_component_group describes a group of installation |
| components, which will be placed together within the listing of |
| options. Typically, component groups allow the user to |
| select/deselect all of the components within a single group via a |
| single group\-level option. Use component groups to reduce the |
| complexity of installers with many options. groupname is an arbitrary |
| name used to identify the group in the GROUP argument of the |
| cpack_add_component command, which is used to place a component in a |
| group. The name of the group must not conflict with the name of any |
| component. |
| .sp |
| DISPLAY_NAME is the displayed name of the component group, used in |
| graphical installers to display the component group name. This value |
| can be any string. |
| .sp |
| DESCRIPTION is an extended description of the component group, used in |
| graphical installers to give the user additional information about the |
| components within that group. Descriptions can span multiple lines |
| using \fB\en\fP as the line separator. Typically, these descriptions |
| should be no more than a few lines long. |
| .sp |
| PARENT_GROUP, if supplied, names the parent group of this group. |
| Parent groups are used to establish a hierarchy of groups, providing |
| an arbitrary hierarchy of groups. |
| .sp |
| EXPANDED indicates that, by default, the group should show up as |
| "expanded", so that the user immediately sees all of the components |
| within the group. Otherwise, the group will initially show up as a |
| single entry. |
| .sp |
| BOLD_TITLE indicates that the group title should appear in bold, to |
| call the user\(aqs attention to the group. |
| .SS Add installation type |
| .INDENT 0.0 |
| .TP |
| .B cpack_add_install_type |
| .UNINDENT |
| .sp |
| Add a new installation type containing |
| a set of predefined component selections to the graphical installer. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cpack_add_install_type(typename |
| [DISPLAY_NAME name]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The cpack_add_install_type command identifies a set of preselected |
| components that represents a common use case for an application. For |
| example, a "Developer" install type might include an application along |
| with its header and library files, while an "End user" install type |
| might just include the application\(aqs executable. Each component |
| identifies itself with one or more install types via the INSTALL_TYPES |
| argument to cpack_add_component. |
| .sp |
| DISPLAY_NAME is the displayed name of the install type, which will |
| typically show up in a drop\-down box within a graphical installer. |
| This value can be any string. |
| .SS Configure downloads |
| .INDENT 0.0 |
| .TP |
| .B cpack_configure_downloads |
| .UNINDENT |
| .sp |
| Configure CPack to download |
| selected components on\-the\-fly as part of the installation process. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cpack_configure_downloads(site |
| [UPLOAD_DIRECTORY dirname] |
| [ALL] |
| [ADD_REMOVE|NO_ADD_REMOVE]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The cpack_configure_downloads command configures installation\-time |
| downloads of selected components. For each downloadable component, |
| CPack will create an archive containing the contents of that |
| component, which should be uploaded to the given site. When the user |
| selects that component for installation, the installer will download |
| and extract the component in place. This feature is useful for |
| creating small installers that only download the requested components, |
| saving bandwidth. Additionally, the installers are small enough that |
| they will be installed as part of the normal installation process, and |
| the "Change" button in Windows Add/Remove Programs control panel will |
| allow one to add or remove parts of the application after the original |
| installation. On Windows, the downloaded\-components functionality |
| requires the ZipDLL plug\-in for NSIS, available at: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| http://nsis.sourceforge.net/ZipDLL_plug\-in |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| On macOS, installers that download components on\-the\-fly can only |
| be built and installed on system using macOS 10.5 or later. |
| .sp |
| The site argument is a URL where the archives for downloadable |
| components will reside, e.g., |
| \fI\%https://cmake.org/files/2.6.1/installer/\fP All of the archives |
| produced by CPack should be uploaded to that location. |
| .sp |
| UPLOAD_DIRECTORY is the local directory where CPack will create the |
| various archives for each of the components. The contents of this |
| directory should be uploaded to a location accessible by the URL given |
| in the site argument. If omitted, CPack will use the directory |
| CPackUploads inside the CMake binary directory to store the generated |
| archives. |
| .sp |
| The ALL flag indicates that all components be downloaded. Otherwise, |
| only those components explicitly marked as DOWNLOADED or that have a |
| specified ARCHIVE_FILE will be downloaded. Additionally, the ALL |
| option implies ADD_REMOVE (unless NO_ADD_REMOVE is specified). |
| .sp |
| ADD_REMOVE indicates that CPack should install a copy of the installer |
| that can be called from Windows\(aq Add/Remove Programs dialog (via the |
| "Modify" button) to change the set of installed components. |
| NO_ADD_REMOVE turns off this behavior. This option is ignored on Mac |
| OS X. |
| .SS CPackIFW |
| .sp |
| New in version 3.1. |
| |
| .sp |
| This module looks for the location of the command\-line utilities supplied with the |
| \fI\%Qt Installer Framework\fP |
| (QtIFW). |
| .sp |
| The module also defines several commands to control the behavior of the |
| \fBCPack IFW Generator\fP\&. |
| .SS Commands |
| .sp |
| The module defines the following commands: |
| .INDENT 0.0 |
| .TP |
| .B cpack_ifw_configure_component |
| Sets the arguments specific to the CPack IFW generator. |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cpack_ifw_configure_component(<compname> [COMMON] [ESSENTIAL] [VIRTUAL] |
| [FORCED_INSTALLATION] [REQUIRES_ADMIN_RIGHTS] |
| [NAME <name>] |
| [DISPLAY_NAME <display_name>] # Note: Internationalization supported |
| [DESCRIPTION <description>] # Note: Internationalization supported |
| [UPDATE_TEXT <update_text>] |
| [VERSION <version>] |
| [RELEASE_DATE <release_date>] |
| [SCRIPT <script>] |
| [PRIORITY|SORTING_PRIORITY <sorting_priority>] # Note: PRIORITY is deprecated |
| [DEPENDS|DEPENDENCIES <com_id> ...] |
| [AUTO_DEPEND_ON <comp_id> ...] |
| [LICENSES <display_name> <file_path> ...] |
| [DEFAULT <value>] |
| [USER_INTERFACES <file_path> <file_path> ...] |
| [TRANSLATIONS <file_path> <file_path> ...] |
| [REPLACES <comp_id> ...] |
| [CHECKABLE <value>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This command should be called after \fBcpack_add_component()\fP command. |
| .INDENT 7.0 |
| .TP |
| .B \fBCOMMON\fP |
| if set, then the component will be packaged and installed as part |
| of a group to which it belongs. |
| .TP |
| .B \fBESSENTIAL\fP |
| New in version 3.6. |
| |
| .sp |
| if set, then the package manager stays disabled until that |
| component is updated. |
| .TP |
| .B \fBVIRTUAL\fP |
| New in version 3.8. |
| |
| .sp |
| if set, then the component will be hidden from the installer. |
| It is a equivalent of the \fBHIDDEN\fP option from the |
| \fBcpack_add_component()\fP command. |
| .TP |
| .B \fBFORCED_INSTALLATION\fP |
| New in version 3.8. |
| |
| .sp |
| if set, then the component must always be installed. |
| It is a equivalent of the \fBREQUIRED\fP option from the |
| \fBcpack_add_component()\fP command. |
| .TP |
| .B \fBREQUIRES_ADMIN_RIGHTS\fP |
| New in version 3.8. |
| |
| .sp |
| set it if the component needs to be installed with elevated permissions. |
| .TP |
| .B \fBNAME\fP |
| is used to create domain\-like identification for this component. |
| By default used origin component name. |
| .TP |
| .B \fBDISPLAY_NAME\fP |
| New in version 3.8. |
| |
| .sp |
| set to rewrite original name configured by |
| \fBcpack_add_component()\fP command. |
| .TP |
| .B \fBDESCRIPTION\fP |
| New in version 3.8. |
| |
| .sp |
| set to rewrite original description configured by |
| \fBcpack_add_component()\fP command. |
| .TP |
| .B \fBUPDATE_TEXT\fP |
| New in version 3.8. |
| |
| .sp |
| will be added to the component description if this is an update to |
| the component. |
| .TP |
| .B \fBVERSION\fP |
| is version of component. |
| By default used \fBCPACK_PACKAGE_VERSION\fP\&. |
| .TP |
| .B \fBRELEASE_DATE\fP |
| New in version 3.8. |
| |
| .sp |
| keep empty to auto generate. |
| .TP |
| .B \fBSCRIPT\fP |
| is a relative or absolute path to operations script |
| for this component. |
| .TP |
| .B \fBSORTING_PRIORITY\fP |
| New in version 3.8. |
| |
| .sp |
| is priority of the component in the tree. |
| .TP |
| .B \fBPRIORITY\fP |
| Deprecated since version 3.8: Old name for \fBSORTING_PRIORITY\fP\&. |
| |
| .TP |
| .B \fBDEPENDS\fP, \fBDEPENDENCIES\fP |
| New in version 3.8. |
| |
| .sp |
| list of dependency component or component group identifiers in |
| QtIFW style. |
| .sp |
| New in version 3.21. |
| |
| .sp |
| Component or group names listed as dependencies may contain hyphens. |
| This requires QtIFW 3.1 or later. |
| .TP |
| .B \fBAUTO_DEPEND_ON\fP |
| New in version 3.8. |
| |
| .sp |
| list of identifiers of component or component group in QtIFW style |
| that this component has an automatic dependency on. |
| .TP |
| .B \fBLICENSES\fP |
| pair of <display_name> and <file_path> of license text for this |
| component. You can specify more then one license. |
| .TP |
| .B \fBDEFAULT\fP |
| New in version 3.8. |
| |
| .sp |
| Possible values are: TRUE, FALSE, and SCRIPT. |
| Set to FALSE to disable the component in the installer or to SCRIPT |
| to resolved during runtime (don\(aqt forget add the file of the script |
| as a value of the \fBSCRIPT\fP option). |
| .TP |
| .B \fBUSER_INTERFACES\fP |
| New in version 3.7. |
| |
| .sp |
| is a list of <file_path> (\(aq.ui\(aq files) representing pages to load. |
| .TP |
| .B \fBTRANSLATIONS\fP |
| New in version 3.8. |
| |
| .sp |
| is a list of <file_path> (\(aq.qm\(aq files) representing translations to load. |
| .TP |
| .B \fBREPLACES\fP |
| New in version 3.10. |
| |
| .sp |
| list of identifiers of component or component group to replace. |
| .TP |
| .B \fBCHECKABLE\fP |
| New in version 3.10. |
| |
| .sp |
| Possible values are: TRUE, FALSE. |
| Set to FALSE if you want to hide the checkbox for an item. |
| This is useful when only a few subcomponents should be selected |
| instead of all. |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B cpack_ifw_configure_component_group |
| Sets the arguments specific to the CPack IFW generator. |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cpack_ifw_configure_component_group(<groupname> [VIRTUAL] |
| [FORCED_INSTALLATION] [REQUIRES_ADMIN_RIGHTS] |
| [NAME <name>] |
| [DISPLAY_NAME <display_name>] # Note: Internationalization supported |
| [DESCRIPTION <description>] # Note: Internationalization supported |
| [UPDATE_TEXT <update_text>] |
| [VERSION <version>] |
| [RELEASE_DATE <release_date>] |
| [SCRIPT <script>] |
| [PRIORITY|SORTING_PRIORITY <sorting_priority>] # Note: PRIORITY is deprecated |
| [DEPENDS|DEPENDENCIES <com_id> ...] |
| [AUTO_DEPEND_ON <comp_id> ...] |
| [LICENSES <display_name> <file_path> ...] |
| [DEFAULT <value>] |
| [USER_INTERFACES <file_path> <file_path> ...] |
| [TRANSLATIONS <file_path> <file_path> ...] |
| [REPLACES <comp_id> ...] |
| [CHECKABLE <value>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This command should be called after \fBcpack_add_component_group()\fP |
| command. |
| .INDENT 7.0 |
| .TP |
| .B \fBVIRTUAL\fP |
| New in version 3.8. |
| |
| .sp |
| if set, then the group will be hidden from the installer. |
| Note that setting this on a root component does not work. |
| .TP |
| .B \fBFORCED_INSTALLATION\fP |
| New in version 3.8. |
| |
| .sp |
| if set, then the group must always be installed. |
| .TP |
| .B \fBREQUIRES_ADMIN_RIGHTS\fP |
| New in version 3.8. |
| |
| .sp |
| set it if the component group needs to be installed with elevated |
| permissions. |
| .TP |
| .B \fBNAME\fP |
| is used to create domain\-like identification for this component group. |
| By default used origin component group name. |
| .TP |
| .B \fBDISPLAY_NAME\fP |
| New in version 3.8. |
| |
| .sp |
| set to rewrite original name configured by |
| \fBcpack_add_component_group()\fP command. |
| .TP |
| .B \fBDESCRIPTION\fP |
| New in version 3.8. |
| |
| .sp |
| set to rewrite original description configured by |
| \fBcpack_add_component_group()\fP command. |
| .TP |
| .B \fBUPDATE_TEXT\fP |
| New in version 3.8. |
| |
| .sp |
| will be added to the component group description if this is an update to |
| the component group. |
| .TP |
| .B \fBVERSION\fP |
| is version of component group. |
| By default used \fBCPACK_PACKAGE_VERSION\fP\&. |
| .TP |
| .B \fBRELEASE_DATE\fP |
| New in version 3.8. |
| |
| .sp |
| keep empty to auto generate. |
| .TP |
| .B \fBSCRIPT\fP |
| is a relative or absolute path to operations script |
| for this component group. |
| .TP |
| .B \fBSORTING_PRIORITY\fP |
| is priority of the component group in the tree. |
| .TP |
| .B \fBPRIORITY\fP |
| Deprecated since version 3.8: Old name for \fBSORTING_PRIORITY\fP\&. |
| |
| .TP |
| .B \fBDEPENDS\fP, \fBDEPENDENCIES\fP |
| New in version 3.8. |
| |
| .sp |
| list of dependency component or component group identifiers in |
| QtIFW style. |
| .sp |
| New in version 3.21. |
| |
| .sp |
| Component or group names listed as dependencies may contain hyphens. |
| This requires QtIFW 3.1 or later. |
| .TP |
| .B \fBAUTO_DEPEND_ON\fP |
| New in version 3.8. |
| |
| .sp |
| list of identifiers of component or component group in QtIFW style |
| that this component group has an automatic dependency on. |
| .TP |
| .B \fBLICENSES\fP |
| pair of <display_name> and <file_path> of license text for this |
| component group. You can specify more then one license. |
| .TP |
| .B \fBDEFAULT\fP |
| New in version 3.8. |
| |
| .sp |
| Possible values are: TRUE, FALSE, and SCRIPT. |
| Set to TRUE to preselect the group in the installer |
| (this takes effect only on groups that have no visible child components) |
| or to SCRIPT to resolved during runtime (don\(aqt forget add the file of |
| the script as a value of the \fBSCRIPT\fP option). |
| .TP |
| .B \fBUSER_INTERFACES\fP |
| New in version 3.7. |
| |
| .sp |
| is a list of <file_path> (\(aq.ui\(aq files) representing pages to load. |
| .TP |
| .B \fBTRANSLATIONS\fP |
| New in version 3.8. |
| |
| .sp |
| is a list of <file_path> (\(aq.qm\(aq files) representing translations to load. |
| .TP |
| .B \fBREPLACES\fP |
| New in version 3.10. |
| |
| .sp |
| list of identifiers of component or component group to replace. |
| .TP |
| .B \fBCHECKABLE\fP |
| New in version 3.10. |
| |
| .sp |
| Possible values are: TRUE, FALSE. |
| Set to FALSE if you want to hide the checkbox for an item. |
| This is useful when only a few subcomponents should be selected |
| instead of all. |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B cpack_ifw_add_repository |
| Add QtIFW specific remote repository to binary installer. |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cpack_ifw_add_repository(<reponame> [DISABLED] |
| URL <url> |
| [USERNAME <username>] |
| [PASSWORD <password>] |
| [DISPLAY_NAME <display_name>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This command will also add the <reponame> repository |
| to a variable \fBCPACK_IFW_REPOSITORIES_ALL\fP\&. |
| .INDENT 7.0 |
| .TP |
| .B \fBDISABLED\fP |
| if set, then the repository will be disabled by default. |
| .TP |
| .B \fBURL\fP |
| is points to a list of available components. |
| .TP |
| .B \fBUSERNAME\fP |
| is used as user on a protected repository. |
| .TP |
| .B \fBPASSWORD\fP |
| is password to use on a protected repository. |
| .TP |
| .B \fBDISPLAY_NAME\fP |
| is string to display instead of the URL. |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B cpack_ifw_update_repository |
| New in version 3.6. |
| |
| .sp |
| Update QtIFW specific repository from remote repository. |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cpack_ifw_update_repository(<reponame> |
| [[ADD|REMOVE] URL <url>]| |
| [REPLACE OLD_URL <old_url> NEW_URL <new_url>]] |
| [USERNAME <username>] |
| [PASSWORD <password>] |
| [DISPLAY_NAME <display_name>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This command will also add the <reponame> repository |
| to a variable \fBCPACK_IFW_REPOSITORIES_ALL\fP\&. |
| .INDENT 7.0 |
| .TP |
| .B \fBURL\fP |
| is points to a list of available components. |
| .TP |
| .B \fBOLD_URL\fP |
| is points to a list that will replaced. |
| .TP |
| .B \fBNEW_URL\fP |
| is points to a list that will replace to. |
| .TP |
| .B \fBUSERNAME\fP |
| is used as user on a protected repository. |
| .TP |
| .B \fBPASSWORD\fP |
| is password to use on a protected repository. |
| .TP |
| .B \fBDISPLAY_NAME\fP |
| is string to display instead of the URL. |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B cpack_ifw_add_package_resources |
| New in version 3.7. |
| |
| .sp |
| Add additional resources in the installer binary. |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cpack_ifw_add_package_resources(<file_path> <file_path> ...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This command will also add the specified files |
| to a variable \fBCPACK_IFW_PACKAGE_RESOURCES\fP\&. |
| .UNINDENT |
| .SS CPackIFWConfigureFile |
| .sp |
| New in version 3.8. |
| |
| .sp |
| The module defines \fBconfigure_file()\fP similar command to |
| configure file templates prepared in QtIFW/SDK/Creator style. |
| .SS Commands |
| .sp |
| The module defines the following commands: |
| .INDENT 0.0 |
| .TP |
| .B cpack_ifw_configure_file |
| Copy a file to another location and modify its contents. |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cpack_ifw_configure_file(<input> <output>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Copies an \fB<input>\fP file to an \fB<output>\fP file and substitutes variable |
| values referenced as \fB%{VAR}\fP or \fB%VAR%\fP in the input file content. |
| Each variable reference will be replaced with the current value of the |
| variable, or the empty string if the variable is not defined. |
| .UNINDENT |
| .SS CSharpUtilities |
| .sp |
| New in version 3.8. |
| |
| .sp |
| Functions to make configuration of CSharp/.NET targets easier. |
| .sp |
| A collection of CMake utility functions useful for dealing with CSharp |
| targets for Visual Studio generators from version 2010 and later. |
| .sp |
| The following functions are provided by this module: |
| .sp |
| \fBMain functions\fP |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fI\%csharp_set_windows_forms_properties()\fP |
| .IP \(bu 2 |
| \fI\%csharp_set_designer_cs_properties()\fP |
| .IP \(bu 2 |
| \fI\%csharp_set_xaml_cs_properties()\fP |
| .UNINDENT |
| .sp |
| \fBHelper functions\fP |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fI\%csharp_get_filename_keys()\fP |
| .IP \(bu 2 |
| \fI\%csharp_get_filename_key_base()\fP |
| .IP \(bu 2 |
| \fI\%csharp_get_dependentupon_name()\fP |
| .UNINDENT |
| .SS Main functions provided by the module |
| .INDENT 0.0 |
| .TP |
| .B csharp_set_windows_forms_properties |
| Sets source file properties for use of Windows Forms. Use this, if your CSharp |
| target uses Windows Forms: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| csharp_set_windows_forms_properties([<file1> [<file2> [...]]]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 7.0 |
| .TP |
| .B \fB<fileN>\fP |
| List of all source files which are relevant for setting the |
| \fBVS_CSHARP_<tagname>\fP properties (including \fB\&.cs\fP, \fB\&.resx\fP and |
| \fB\&.Designer.cs\fP extensions). |
| .UNINDENT |
| .sp |
| In the list of all given files for all files ending with \fB\&.Designer.cs\fP and |
| \fB\&.resx\fP is searched. For every \fIdesigner\fP or \fIresource\fP file a file with the |
| same base name but only \fB\&.cs\fP as extension is searched. If this is found, the |
| \fBVS_CSHARP_<tagname>\fP properties are set as follows: |
| .INDENT 7.0 |
| .TP |
| for the \fB\&.cs\fP file: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| VS_CSHARP_SubType "Form" |
| .UNINDENT |
| .TP |
| for the \fB\&.Designer.cs\fP file (if it exists): |
| .INDENT 7.0 |
| .IP \(bu 2 |
| VS_CSHARP_DependentUpon <cs\-filename> |
| .IP \(bu 2 |
| VS_CSHARP_DesignTime "" (delete tag if previously defined) |
| .IP \(bu 2 |
| VS_CSHARP_AutoGen ""(delete tag if previously defined) |
| .UNINDENT |
| .TP |
| for the \fB\&.resx\fP file (if it exists): |
| .INDENT 7.0 |
| .IP \(bu 2 |
| VS_RESOURCE_GENERATOR "" (delete tag if previously defined) |
| .IP \(bu 2 |
| VS_CSHARP_DependentUpon <cs\-filename> |
| .IP \(bu 2 |
| VS_CSHARP_SubType "Designer" |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B csharp_set_designer_cs_properties |
| Sets source file properties of \fB\&.Designer.cs\fP files depending on |
| sibling filenames. Use this, if your CSharp target does \fBnot\fP |
| use Windows Forms (for Windows Forms use |
| \fI\%csharp_set_designer_cs_properties()\fP instead): |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| csharp_set_designer_cs_properties([<file1> [<file2> [...]]]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 7.0 |
| .TP |
| .B \fB<fileN>\fP |
| List of all source files which are relevant for setting the |
| \fBVS_CSHARP_<tagname>\fP properties (including \fB\&.cs\fP, |
| \fB\&.resx\fP, \fB\&.settings\fP and \fB\&.Designer.cs\fP extensions). |
| .UNINDENT |
| .sp |
| In the list of all given files for all files ending with |
| \fB\&.Designer.cs\fP is searched. For every \fIdesigner\fP file all files |
| with the same base name but different extensions are searched. If |
| a match is found, the source file properties of the \fIdesigner\fP file |
| are set depending on the extension of the matched file: |
| .INDENT 7.0 |
| .TP |
| if match is \fB\&.resx\fP file: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| VS_CSHARP_AutoGen "True" |
| .IP \(bu 2 |
| VS_CSHARP_DesignTime "True" |
| .IP \(bu 2 |
| VS_CSHARP_DependentUpon <resx\-filename> |
| .UNINDENT |
| .TP |
| if match is \fB\&.cs\fP file: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| VS_CSHARP_DependentUpon <cs\-filename> |
| .UNINDENT |
| .TP |
| if match is \fB\&.settings\fP file: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| VS_CSHARP_AutoGen "True" |
| .IP \(bu 2 |
| VS_CSHARP_DesignTimeSharedInput "True" |
| .IP \(bu 2 |
| VS_CSHARP_DependentUpon <settings\-filename> |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| Because the source file properties of the \fB\&.Designer.cs\fP file are set according |
| to the found matches and every match sets the \fBVS_CSHARP_DependentUpon\fP |
| property, there should only be one match for each \fBDesigner.cs\fP file. |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B csharp_set_xaml_cs_properties |
| Sets source file properties for use of Windows Presentation Foundation (WPF) and |
| XAML. Use this, if your CSharp target uses WPF/XAML: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| csharp_set_xaml_cs_properties([<file1> [<file2> [...]]]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 7.0 |
| .TP |
| .B \fB<fileN>\fP |
| List of all source files which are relevant for setting the |
| \fBVS_CSHARP_<tagname>\fP properties (including \fB\&.cs\fP, |
| \fB\&.xaml\fP, and \fB\&.xaml.cs\fP extensions). |
| .UNINDENT |
| .sp |
| In the list of all given files for all files ending with |
| \fB\&.xaml.cs\fP is searched. For every \fIxaml\-cs\fP file, a file |
| with the same base name but extension \fB\&.xaml\fP is searched. |
| If a match is found, the source file properties of the \fB\&.xaml.cs\fP |
| file are set: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .INDENT 0.0 |
| .IP \(bu 2 |
| VS_CSHARP_DependentUpon <xaml\-filename> |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .SS Helper functions which are used by the above ones |
| .INDENT 0.0 |
| .TP |
| .B csharp_get_filename_keys |
| Helper function which computes a list of key values to identify |
| source files independently of relative/absolute paths given in cmake |
| and eliminates case sensitivity: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| csharp_get_filename_keys(OUT [<file1> [<file2> [...]]]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 7.0 |
| .TP |
| .B \fBOUT\fP |
| Name of the variable in which the list of keys is stored |
| .TP |
| .B \fB<fileN>\fP |
| filename(s) as given to to CSharp target using \fBadd_library()\fP |
| or \fBadd_executable()\fP |
| .UNINDENT |
| .sp |
| In some way the function applies a canonicalization to the source names. |
| This is necessary to find file matches if the files have been added to |
| the target with different directory prefixes: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_library(lib |
| myfile.cs |
| ${CMAKE_CURRENT_SOURCE_DIR}/myfile.Designer.cs) |
| |
| set_source_files_properties(myfile.Designer.cs PROPERTIES |
| VS_CSHARP_DependentUpon myfile.cs) |
| |
| # this will fail, because in cmake |
| # \- ${CMAKE_CURRENT_SOURCE_DIR}/myfile.Designer.cs |
| # \- myfile.Designer.cs |
| # are not the same source file. The source file property is not set. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B csharp_get_filename_key_base |
| Returns the full filepath and name \fBwithout\fP extension of a key. |
| KEY is expected to be a key from csharp_get_filename_keys. In BASE |
| the value of KEY without the file extension is returned: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| csharp_get_filename_key_base(BASE KEY) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 7.0 |
| .TP |
| .B \fBBASE\fP |
| Name of the variable with the computed "base" of \fBKEY\fP\&. |
| .TP |
| .B \fBKEY\fP |
| The key of which the base will be computed. Expected to be a |
| upper case full filename. |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B csharp_get_dependentupon_name |
| Computes a string which can be used as value for the source file property |
| \fBVS_CSHARP_<tagname>\fP with \fItarget\fP being \fBDependentUpon\fP: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| csharp_get_dependentupon_name(NAME FILE) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 7.0 |
| .TP |
| .B \fBNAME\fP |
| Name of the variable with the result value |
| .TP |
| .B \fBFILE\fP |
| Filename to convert to \fB<DependentUpon>\fP value |
| .UNINDENT |
| .sp |
| Actually this is only the filename without any path given at the moment. |
| .UNINDENT |
| .SS CTest |
| .sp |
| Configure a project for testing with CTest/CDash |
| .sp |
| Include this module in the top CMakeLists.txt file of a project to |
| enable testing with CTest and dashboard submissions to CDash: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| project(MyProject) |
| \&... |
| include(CTest) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The module automatically creates a \fBBUILD_TESTING\fP option that selects |
| whether to enable testing support (\fBON\fP by default). After including |
| the module, use code like: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| if(BUILD_TESTING) |
| # ... CMake code to create tests ... |
| endif() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| to creating tests when testing is enabled. |
| .sp |
| To enable submissions to a CDash server, create a \fBCTestConfig.cmake\fP |
| file at the top of the project with content such as: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(CTEST_NIGHTLY_START_TIME "01:00:00 UTC") |
| set(CTEST_SUBMIT_URL "http://my.cdash.org/submit.php?project=MyProject") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| (the CDash server can provide the file to a project administrator who |
| configures \fBMyProject\fP). Settings in the config file are shared by |
| both this \fBCTest\fP module and the \fBctest(1)\fP command\-line |
| Dashboard Client mode (\fBctest \-S\fP). |
| .sp |
| While building a project for submission to CDash, CTest scans the |
| build output for errors and warnings and reports them with surrounding |
| context from the build log. This generic approach works for all build |
| tools, but does not give details about the command invocation that |
| produced a given problem. One may get more detailed reports by setting |
| the \fBCTEST_USE_LAUNCHERS\fP variable: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(CTEST_USE_LAUNCHERS 1) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| in the \fBCTestConfig.cmake\fP file. |
| .SS CTestCoverageCollectGCOV |
| .sp |
| New in version 3.2. |
| |
| .sp |
| This module provides the \fBctest_coverage_collect_gcov\fP function. |
| .sp |
| This function runs gcov on all .gcda files found in the binary tree |
| and packages the resulting .gcov files into a tar file. |
| This tarball also contains the following: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fIdata.json\fP defines the source and build directories for use by CDash. |
| .IP \(bu 2 |
| \fILabels.json\fP indicates any \fBLABELS\fP that have been set on the |
| source files. |
| .IP \(bu 2 |
| The \fIuncovered\fP directory holds any uncovered files found by |
| \fBCTEST_EXTRA_COVERAGE_GLOB\fP\&. |
| .UNINDENT |
| .sp |
| After generating this tar file, it can be sent to CDash for display with the |
| \fBctest_submit(CDASH_UPLOAD)\fP command. |
| .INDENT 0.0 |
| .TP |
| .B ctest_coverage_collect_gcov |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ctest_coverage_collect_gcov(TARBALL <tarfile> |
| [SOURCE <source_dir>][BUILD <build_dir>] |
| [GCOV_COMMAND <gcov_command>] |
| [GCOV_OPTIONS <options>...] |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Run gcov and package a tar file for CDash. The options are: |
| .INDENT 7.0 |
| .TP |
| .B \fBTARBALL <tarfile>\fP |
| Specify the location of the \fB\&.tar\fP file to be created for later |
| upload to CDash. Relative paths will be interpreted with respect |
| to the top\-level build directory. |
| .TP |
| .B \fBTARBALL_COMPRESSION <option>\fP |
| New in version 3.18. |
| |
| .sp |
| Specify a compression algorithm for the |
| \fBTARBALL\fP data file. Using this option reduces the size of the data file |
| before it is submitted to CDash. \fB<option>\fP must be one of \fBGZIP\fP, |
| \fBBZIP2\fP, \fBXZ\fP, \fBZSTD\fP, \fBFROM_EXT\fP, or an expression that CMake |
| evaluates as \fBFALSE\fP\&. The default value is \fBBZIP2\fP\&. |
| .sp |
| If \fBFROM_EXT\fP is specified, the resulting file will be compressed based on |
| the file extension of the \fB<tarfile>\fP (i.e. \fB\&.tar.gz\fP will use \fBGZIP\fP |
| compression). File extensions that will produce compressed output include |
| \fB\&.tar.gz\fP, \fB\&.tgz\fP, \fB\&.tar.bzip2\fP, \fB\&.tbz\fP, \fB\&.tar.xz\fP, and \fB\&.txz\fP\&. |
| .TP |
| .B \fBSOURCE <source_dir>\fP |
| Specify the top\-level source directory for the build. |
| Default is the value of \fBCTEST_SOURCE_DIRECTORY\fP\&. |
| .TP |
| .B \fBBUILD <build_dir>\fP |
| Specify the top\-level build directory for the build. |
| Default is the value of \fBCTEST_BINARY_DIRECTORY\fP\&. |
| .TP |
| .B \fBGCOV_COMMAND <gcov_command>\fP |
| Specify the full path to the \fBgcov\fP command on the machine. |
| Default is the value of \fBCTEST_COVERAGE_COMMAND\fP\&. |
| .TP |
| .B \fBGCOV_OPTIONS <options>...\fP |
| Specify options to be passed to gcov. The \fBgcov\fP command |
| is run as \fBgcov <options>... \-o <gcov\-dir> <file>.gcda\fP\&. |
| If not specified, the default option is just \fB\-b \-x\fP\&. |
| .TP |
| .B \fBGLOB\fP |
| New in version 3.6. |
| |
| .sp |
| Recursively search for .gcda files in build_dir rather than |
| determining search locations by reading TargetDirectories.txt. |
| .TP |
| .B \fBDELETE\fP |
| New in version 3.6. |
| |
| .sp |
| Delete coverage files after they\(aqve been packaged into the .tar. |
| .TP |
| .B \fBQUIET\fP |
| Suppress non\-error messages that otherwise would have been |
| printed out by this function. |
| .UNINDENT |
| .sp |
| New in version 3.3: Added support for the \fBCTEST_CUSTOM_COVERAGE_EXCLUDE\fP variable. |
| |
| .UNINDENT |
| .SS CTestScriptMode |
| .sp |
| This file is read by ctest in script mode (\-S) |
| .SS CTestUseLaunchers |
| .sp |
| Set the RULE_LAUNCH_* global properties when CTEST_USE_LAUNCHERS is on. |
| .sp |
| CTestUseLaunchers is automatically included when you include(CTest). |
| However, it is split out into its own module file so projects can use |
| the CTEST_USE_LAUNCHERS functionality independently. |
| .sp |
| To use launchers, set CTEST_USE_LAUNCHERS to ON in a ctest \-S |
| dashboard script, and then also set it in the cache of the configured |
| project. Both cmake and ctest need to know the value of it for the |
| launchers to work properly. CMake needs to know in order to generate |
| proper build rules, and ctest, in order to produce the proper error |
| and warning analysis. |
| .sp |
| For convenience, you may set the ENV variable |
| CTEST_USE_LAUNCHERS_DEFAULT in your ctest \-S script, too. Then, as |
| long as your CMakeLists uses include(CTest) or |
| include(CTestUseLaunchers), it will use the value of the ENV variable |
| to initialize a CTEST_USE_LAUNCHERS cache variable. This cache |
| variable initialization only occurs if CTEST_USE_LAUNCHERS is not |
| already defined. |
| .sp |
| New in version 3.8: If CTEST_USE_LAUNCHERS is on in a ctest \-S script |
| the ctest_configure command will add \-DCTEST_USE_LAUNCHERS:BOOL=TRUE |
| to the cmake command used to configure the project. |
| |
| .SS Dart |
| .sp |
| Configure a project for testing with CTest or old Dart Tcl Client |
| .sp |
| This file is the backwards\-compatibility version of the CTest module. |
| It supports using the old Dart 1 Tcl client for driving dashboard |
| submissions as well as testing with CTest. This module should be |
| included in the CMakeLists.txt file at the top of a project. Typical |
| usage: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| include(Dart) |
| if(BUILD_TESTING) |
| # ... testing related CMake code ... |
| endif() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The BUILD_TESTING option is created by the Dart module to determine |
| whether testing support should be enabled. The default is ON. |
| .SS DeployQt4 |
| .sp |
| Functions to help assemble a standalone Qt4 executable. |
| .sp |
| A collection of CMake utility functions useful for deploying Qt4 |
| executables. |
| .sp |
| The following functions are provided by this module: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| write_qt4_conf |
| resolve_qt4_paths |
| fixup_qt4_executable |
| install_qt4_plugin_path |
| install_qt4_plugin |
| install_qt4_executable |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Requires CMake 2.6 or greater because it uses function and |
| PARENT_SCOPE. Also depends on BundleUtilities.cmake. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| write_qt4_conf(<qt_conf_dir> <qt_conf_contents>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Writes a qt.conf file with the <qt_conf_contents> into <qt_conf_dir>. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| resolve_qt4_paths(<paths_var> [<executable_path>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Loop through <paths_var> list and if any don\(aqt exist resolve them |
| relative to the <executable_path> (if supplied) or the |
| CMAKE_INSTALL_PREFIX. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| fixup_qt4_executable(<executable> |
| [<qtplugins> <libs> <dirs> <plugins_dir> <request_qt_conf>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Copies Qt plugins, writes a Qt configuration file (if needed) and |
| fixes up a Qt4 executable using BundleUtilities so it is standalone |
| and can be drag\-and\-drop copied to another machine as long as all of |
| the system libraries are compatible. |
| .sp |
| <executable> should point to the executable to be fixed\-up. |
| .sp |
| <qtplugins> should contain a list of the names or paths of any Qt |
| plugins to be installed. |
| .sp |
| <libs> will be passed to BundleUtilities and should be a list of any |
| already installed plugins, libraries or executables to also be |
| fixed\-up. |
| .sp |
| <dirs> will be passed to BundleUtilities and should contain and |
| directories to be searched to find library dependencies. |
| .sp |
| <plugins_dir> allows an custom plugins directory to be used. |
| .sp |
| <request_qt_conf> will force a qt.conf file to be written even if not |
| needed. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| install_qt4_plugin_path(plugin executable copy installed_plugin_path_var |
| <plugins_dir> <component> <configurations>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Install (or copy) a resolved <plugin> to the default plugins directory |
| (or <plugins_dir>) relative to <executable> and store the result in |
| <installed_plugin_path_var>. |
| .sp |
| If <copy> is set to TRUE then the plugins will be copied rather than |
| installed. This is to allow this module to be used at CMake time |
| rather than install time. |
| .sp |
| If <component> is set then anything installed will use this COMPONENT. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| install_qt4_plugin(plugin executable copy installed_plugin_path_var |
| <plugins_dir> <component>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Install (or copy) an unresolved <plugin> to the default plugins |
| directory (or <plugins_dir>) relative to <executable> and store the |
| result in <installed_plugin_path_var>. See documentation of |
| INSTALL_QT4_PLUGIN_PATH. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| install_qt4_executable(<executable> |
| [<qtplugins> <libs> <dirs> <plugins_dir> <request_qt_conf> <component>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Installs Qt plugins, writes a Qt configuration file (if needed) and |
| fixes up a Qt4 executable using BundleUtilities so it is standalone |
| and can be drag\-and\-drop copied to another machine as long as all of |
| the system libraries are compatible. The executable will be fixed\-up |
| at install time. <component> is the COMPONENT used for bundle fixup |
| and plugin installation. See documentation of FIXUP_QT4_BUNDLE. |
| .SS ExternalData |
| .sp |
| Manage data files stored outside source tree |
| .SS Introduction |
| .sp |
| Use this module to unambiguously reference data files stored outside |
| the source tree and fetch them at build time from arbitrary local and |
| remote content\-addressed locations. Functions provided by this module |
| recognize arguments with the syntax \fBDATA{<name>}\fP as references to |
| external data, replace them with full paths to local copies of those |
| data, and create build rules to fetch and update the local copies. |
| .sp |
| For example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| include(ExternalData) |
| set(ExternalData_URL_TEMPLATES "file:///local/%(algo)/%(hash)" |
| "file:////host/share/%(algo)/%(hash)" |
| "http://data.org/%(algo)/%(hash)") |
| ExternalData_Add_Test(MyData |
| NAME MyTest |
| COMMAND MyExe DATA{MyInput.png} |
| ) |
| ExternalData_Add_Target(MyData) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| When test \fBMyTest\fP runs the \fBDATA{MyInput.png}\fP argument will be |
| replaced by the full path to a real instance of the data file |
| \fBMyInput.png\fP on disk. If the source tree contains a content link |
| such as \fBMyInput.png.md5\fP then the \fBMyData\fP target creates a real |
| \fBMyInput.png\fP in the build tree. |
| .SS Module Functions |
| .INDENT 0.0 |
| .TP |
| .B ExternalData_Expand_Arguments |
| The \fBExternalData_Expand_Arguments\fP function evaluates \fBDATA{}\fP |
| references in its arguments and constructs a new list of arguments: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ExternalData_Expand_Arguments( |
| <target> # Name of data management target |
| <outVar> # Output variable |
| [args...] # Input arguments, DATA{} allowed |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| It replaces each \fBDATA{}\fP reference in an argument with the full path of |
| a real data file on disk that will exist after the \fB<target>\fP builds. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B ExternalData_Add_Test |
| The \fBExternalData_Add_Test\fP function wraps around the CMake |
| \fBadd_test()\fP command but supports \fBDATA{}\fP references in |
| its arguments: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ExternalData_Add_Test( |
| <target> # Name of data management target |
| ... # Arguments of add_test(), DATA{} allowed |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| It passes its arguments through \fBExternalData_Expand_Arguments\fP and then |
| invokes the \fBadd_test()\fP command using the results. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B ExternalData_Add_Target |
| The \fBExternalData_Add_Target\fP function creates a custom target to |
| manage local instances of data files stored externally: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ExternalData_Add_Target( |
| <target> # Name of data management target |
| [SHOW_PROGRESS <ON|OFF>] # Show progress during the download |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| It creates custom commands in the target as necessary to make data |
| files available for each \fBDATA{}\fP reference previously evaluated by |
| other functions provided by this module. |
| Data files may be fetched from one of the URL templates specified in |
| the \fBExternalData_URL_TEMPLATES\fP variable, or may be found locally |
| in one of the paths specified in the \fBExternalData_OBJECT_STORES\fP |
| variable. |
| .sp |
| New in version 3.20: The \fBSHOW_PROGRESS\fP argument may be passed to suppress progress information |
| during the download of objects. If not provided, it defaults to \fBOFF\fP for |
| \fBNinja\fP and \fBNinja Multi\-Config\fP generators and \fBON\fP |
| otherwise. |
| |
| .sp |
| Typically only one target is needed to manage all external data within |
| a project. Call this function once at the end of configuration after |
| all data references have been processed. |
| .UNINDENT |
| .SS Module Variables |
| .sp |
| The following variables configure behavior. They should be set before |
| calling any of the functions provided by this module. |
| .INDENT 0.0 |
| .TP |
| .B ExternalData_BINARY_ROOT |
| The \fBExternalData_BINARY_ROOT\fP variable may be set to the directory to |
| hold the real data files named by expanded \fBDATA{}\fP references. The |
| default is \fBCMAKE_BINARY_DIR\fP\&. The directory layout will mirror that of |
| content links under \fBExternalData_SOURCE_ROOT\fP\&. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B ExternalData_CUSTOM_SCRIPT_<key> |
| New in version 3.2. |
| |
| .sp |
| Specify a full path to a \fB\&.cmake\fP custom fetch script identified by |
| \fB<key>\fP in entries of the \fBExternalData_URL_TEMPLATES\fP list. |
| See \fI\%Custom Fetch Scripts\fP\&. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B ExternalData_LINK_CONTENT |
| The \fBExternalData_LINK_CONTENT\fP variable may be set to the name of a |
| supported hash algorithm to enable automatic conversion of real data |
| files referenced by the \fBDATA{}\fP syntax into content links. For each |
| such \fB<file>\fP a content link named \fB<file><ext>\fP is created. The |
| original file is renamed to the form \fB\&.ExternalData_<algo>_<hash>\fP to |
| stage it for future transmission to one of the locations in the list |
| of URL templates (by means outside the scope of this module). The |
| data fetch rule created for the content link will use the staged |
| object if it cannot be found using any URL template. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B ExternalData_NO_SYMLINKS |
| New in version 3.3. |
| |
| .sp |
| The real data files named by expanded \fBDATA{}\fP references may be made |
| available under \fBExternalData_BINARY_ROOT\fP using symbolic links on |
| some platforms. The \fBExternalData_NO_SYMLINKS\fP variable may be set |
| to disable use of symbolic links and enable use of copies instead. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B ExternalData_OBJECT_STORES |
| The \fBExternalData_OBJECT_STORES\fP variable may be set to a list of local |
| directories that store objects using the layout \fB<dir>/%(algo)/%(hash)\fP\&. |
| These directories will be searched first for a needed object. If the |
| object is not available in any store then it will be fetched remotely |
| using the URL templates and added to the first local store listed. If |
| no stores are specified the default is a location inside the build |
| tree. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B ExternalData_SERIES_PARSE |
| .TP |
| .B ExternalData_SERIES_PARSE_PREFIX |
| .TP |
| .B ExternalData_SERIES_PARSE_NUMBER |
| .TP |
| .B ExternalData_SERIES_PARSE_SUFFIX |
| .TP |
| .B ExternalData_SERIES_MATCH |
| See \fI\%Referencing File Series\fP\&. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B ExternalData_SOURCE_ROOT |
| The \fBExternalData_SOURCE_ROOT\fP variable may be set to the highest source |
| directory containing any path named by a \fBDATA{}\fP reference. The |
| default is \fBCMAKE_SOURCE_DIR\fP\&. \fBExternalData_SOURCE_ROOT\fP and |
| \fBCMAKE_SOURCE_DIR\fP must refer to directories within a single source |
| distribution (e.g. they come together in one tarball). |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B ExternalData_TIMEOUT_ABSOLUTE |
| The \fBExternalData_TIMEOUT_ABSOLUTE\fP variable sets the download |
| absolute timeout, in seconds, with a default of \fB300\fP seconds. |
| Set to \fB0\fP to disable enforcement. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B ExternalData_TIMEOUT_INACTIVITY |
| The \fBExternalData_TIMEOUT_INACTIVITY\fP variable sets the download |
| inactivity timeout, in seconds, with a default of \fB60\fP seconds. |
| Set to \fB0\fP to disable enforcement. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B ExternalData_URL_ALGO_<algo>_<key> |
| New in version 3.3. |
| |
| .sp |
| Specify a custom URL component to be substituted for URL template |
| placeholders of the form \fB%(algo:<key>)\fP, where \fB<key>\fP is a |
| valid C identifier, when fetching an object referenced via hash |
| algorithm \fB<algo>\fP\&. If not defined, the default URL component |
| is just \fB<algo>\fP for any \fB<key>\fP\&. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B ExternalData_URL_TEMPLATES |
| The \fBExternalData_URL_TEMPLATES\fP may be set to provide a list |
| of URL templates using the placeholders \fB%(algo)\fP and \fB%(hash)\fP |
| in each template. Data fetch rules try each URL template in order |
| by substituting the hash algorithm name for \fB%(algo)\fP and the hash |
| value for \fB%(hash)\fP\&. Alternatively one may use \fB%(algo:<key>)\fP |
| with \fBExternalData_URL_ALGO_<algo>_<key>\fP variables to gain more |
| flexibility in remote URLs. |
| .UNINDENT |
| .SS Referencing Files |
| .SS Referencing Single Files |
| .sp |
| The \fBDATA{}\fP syntax is literal and the \fB<name>\fP is a full or relative path |
| within the source tree. The source tree must contain either a real |
| data file at \fB<name>\fP or a "content link" at \fB<name><ext>\fP containing a |
| hash of the real file using a hash algorithm corresponding to \fB<ext>\fP\&. |
| For example, the argument \fBDATA{img.png}\fP may be satisfied by either a |
| real \fBimg.png\fP file in the current source directory or a \fBimg.png.md5\fP |
| file containing its MD5 sum. |
| .sp |
| New in version 3.8: Multiple content links of the same name with different hash algorithms |
| are supported (e.g. \fBimg.png.sha256\fP and \fBimg.png.sha1\fP) so long as |
| they all correspond to the same real file. This allows objects to be |
| fetched from sources indexed by different hash algorithms. |
| |
| .SS Referencing File Series |
| .sp |
| The \fBDATA{}\fP syntax can be told to fetch a file series using the form |
| \fBDATA{<name>,:}\fP, where the \fB:\fP is literal. If the source tree |
| contains a group of files or content links named like a series then a |
| reference to one member adds rules to fetch all of them. Although all |
| members of a series are fetched, only the file originally named by the |
| \fBDATA{}\fP argument is substituted for it. The default configuration |
| recognizes file series names ending with \fB#.ext\fP, \fB_#.ext\fP, \fB\&.#.ext\fP, |
| or \fB\-#.ext\fP where \fB#\fP is a sequence of decimal digits and \fB\&.ext\fP is |
| any single extension. Configure it with a regex that parses \fB<number>\fP |
| and \fB<suffix>\fP parts from the end of \fB<name>\fP: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ExternalData_SERIES_PARSE = regex of the form (<number>)(<suffix>)$ |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| For more complicated cases set: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ExternalData_SERIES_PARSE = regex with at least two () groups |
| ExternalData_SERIES_PARSE_PREFIX = <prefix> regex group number, if any |
| ExternalData_SERIES_PARSE_NUMBER = <number> regex group number |
| ExternalData_SERIES_PARSE_SUFFIX = <suffix> regex group number |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Configure series number matching with a regex that matches the |
| \fB<number>\fP part of series members named \fB<prefix><number><suffix>\fP: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ExternalData_SERIES_MATCH = regex matching <number> in all series members |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Note that the \fB<suffix>\fP of a series does not include a hash\-algorithm |
| extension. |
| .SS Referencing Associated Files |
| .sp |
| The \fBDATA{}\fP syntax can alternatively match files associated with the |
| named file and contained in the same directory. Associated files may |
| be specified by options using the syntax |
| \fBDATA{<name>,<opt1>,<opt2>,...}\fP\&. Each option may specify one file by |
| name or specify a regular expression to match file names using the |
| syntax \fBREGEX:<regex>\fP\&. For example, the arguments: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| DATA{MyData/MyInput.mhd,MyInput.img} # File pair |
| DATA{MyData/MyFrames00.png,REGEX:MyFrames[0\-9]+\e\e.png} # Series |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| will pass \fBMyInput.mha\fP and \fBMyFrames00.png\fP on the command line but |
| ensure that the associated files are present next to them. |
| .SS Referencing Directories |
| .sp |
| The \fBDATA{}\fP syntax may reference a directory using a trailing slash and |
| a list of associated files. The form \fBDATA{<name>/,<opt1>,<opt2>,...}\fP |
| adds rules to fetch any files in the directory that match one of the |
| associated file options. For example, the argument |
| \fBDATA{MyDataDir/,REGEX:.*}\fP will pass the full path to a \fBMyDataDir\fP |
| directory on the command line and ensure that the directory contains |
| files corresponding to every file or content link in the \fBMyDataDir\fP |
| source directory. |
| .sp |
| New in version 3.3: In order to match associated files in subdirectories, |
| specify a \fBRECURSE:\fP option, e.g. \fBDATA{MyDataDir/,RECURSE:,REGEX:.*}\fP\&. |
| |
| .SS Hash Algorithms |
| .sp |
| The following hash algorithms are supported: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| %(algo) <ext> Description |
| \-\-\-\-\-\-\- \-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\- |
| MD5 .md5 Message\-Digest Algorithm 5, RFC 1321 |
| SHA1 .sha1 US Secure Hash Algorithm 1, RFC 3174 |
| SHA224 .sha224 US Secure Hash Algorithms, RFC 4634 |
| SHA256 .sha256 US Secure Hash Algorithms, RFC 4634 |
| SHA384 .sha384 US Secure Hash Algorithms, RFC 4634 |
| SHA512 .sha512 US Secure Hash Algorithms, RFC 4634 |
| SHA3_224 .sha3\-224 Keccak SHA\-3 |
| SHA3_256 .sha3\-256 Keccak SHA\-3 |
| SHA3_384 .sha3\-384 Keccak SHA\-3 |
| SHA3_512 .sha3\-512 Keccak SHA\-3 |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.8: Added the \fBSHA3_*\fP hash algorithms. |
| |
| .sp |
| Note that the hashes are used only for unique data identification and |
| download verification. |
| .SS Custom Fetch Scripts |
| .sp |
| New in version 3.2. |
| |
| .sp |
| When a data file must be fetched from one of the URL templates |
| specified in the \fBExternalData_URL_TEMPLATES\fP variable, it is |
| normally downloaded using the \fBfile(DOWNLOAD)\fP command. |
| One may specify usage of a custom fetch script by using a URL |
| template of the form \fBExternalDataCustomScript://<key>/<loc>\fP\&. |
| The \fB<key>\fP must be a C identifier, and the \fB<loc>\fP must |
| contain the \fB%(algo)\fP and \fB%(hash)\fP placeholders. |
| A variable corresponding to the key, \fBExternalData_CUSTOM_SCRIPT_<key>\fP, |
| must be set to the full path to a \fB\&.cmake\fP script file. The script |
| will be included to perform the actual fetch, and provided with |
| the following variables: |
| .INDENT 0.0 |
| .TP |
| .B ExternalData_CUSTOM_LOCATION |
| When a custom fetch script is loaded, this variable is set to the |
| location part of the URL, which will contain the substituted hash |
| algorithm name and content hash value. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B ExternalData_CUSTOM_FILE |
| When a custom fetch script is loaded, this variable is set to the |
| full path to a file in which the script must store the fetched |
| content. The name of the file is unspecified and should not be |
| interpreted in any way. |
| .UNINDENT |
| .sp |
| The custom fetch script is expected to store fetched content in the |
| file or set a variable: |
| .INDENT 0.0 |
| .TP |
| .B ExternalData_CUSTOM_ERROR |
| When a custom fetch script fails to fetch the requested content, |
| it must set this variable to a short one\-line message describing |
| the reason for failure. |
| .UNINDENT |
| .SS ExternalProject |
| .SS Commands |
| .SS External Project Definition |
| .INDENT 0.0 |
| .TP |
| .B ExternalProject_Add |
| The \fBExternalProject_Add()\fP function creates a custom target to drive |
| download, update/patch, configure, build, install and test steps of an |
| external project: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ExternalProject_Add(<name> [<option>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The individual steps within the process can be driven independently if |
| required (e.g. for CDash submission) and extra custom steps can be defined, |
| along with the ability to control the step dependencies. The directory |
| structure used for the management of the external project can also be |
| customized. The function supports a large number of options which can be used |
| to tailor the external project behavior. |
| .INDENT 7.0 |
| .TP |
| \fBDirectory Options:\fP |
| Most of the time, the default directory layout is sufficient. It is largely |
| an implementation detail that the main project usually doesn\(aqt need to |
| change. In some circumstances, however, control over the directory layout |
| can be useful or necessary. The directory options are potentially more |
| useful from the point of view that the main build can use the |
| \fI\%ExternalProject_Get_Property()\fP command to retrieve their values, |
| thereby allowing the main project to refer to build artifacts of the |
| external project. |
| .INDENT 7.0 |
| .TP |
| .B \fBPREFIX <dir>\fP |
| Root directory for the external project. Unless otherwise noted below, |
| all other directories associated with the external project will be |
| created under here. |
| .TP |
| .B \fBTMP_DIR <dir>\fP |
| Directory in which to store temporary files. |
| .TP |
| .B \fBSTAMP_DIR <dir>\fP |
| Directory in which to store the timestamps of each step. Log files from |
| individual steps are also created in here unless overridden by LOG_DIR |
| (see \fILogging Options\fP below). |
| .TP |
| .B \fBLOG_DIR <dir>\fP |
| New in version 3.14. |
| |
| .sp |
| Directory in which to store the logs of each step. |
| .TP |
| .B \fBDOWNLOAD_DIR <dir>\fP |
| Directory in which to store downloaded files before unpacking them. This |
| directory is only used by the URL download method, all other download |
| methods use \fBSOURCE_DIR\fP directly instead. |
| .TP |
| .B \fBSOURCE_DIR <dir>\fP |
| Source directory into which downloaded contents will be unpacked, or for |
| non\-URL download methods, the directory in which the repository should be |
| checked out, cloned, etc. If no download method is specified, this must |
| point to an existing directory where the external project has already |
| been unpacked or cloned/checked out. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| If a download method is specified, any existing contents of the source |
| directory may be deleted. Only the URL download method checks whether |
| this directory is either missing or empty before initiating the |
| download, stopping with an error if it is not empty. All other |
| download methods silently discard any previous contents of the source |
| directory. |
| .UNINDENT |
| .UNINDENT |
| .TP |
| .B \fBBINARY_DIR <dir>\fP |
| Specify the build directory location. This option is ignored if |
| \fBBUILD_IN_SOURCE\fP is enabled. |
| .TP |
| .B \fBINSTALL_DIR <dir>\fP |
| Installation prefix to be placed in the \fB<INSTALL_DIR>\fP placeholder. |
| This does not actually configure the external project to install to |
| the given prefix. That must be done by passing appropriate arguments |
| to the external project configuration step, e.g. using \fB<INSTALL_DIR>\fP\&. |
| .UNINDENT |
| .sp |
| If any of the above \fB\&..._DIR\fP options are not specified, their defaults |
| are computed as follows. If the \fBPREFIX\fP option is given or the |
| \fBEP_PREFIX\fP directory property is set, then an external project is built |
| and installed under the specified prefix: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| TMP_DIR = <prefix>/tmp |
| STAMP_DIR = <prefix>/src/<name>\-stamp |
| DOWNLOAD_DIR = <prefix>/src |
| SOURCE_DIR = <prefix>/src/<name> |
| BINARY_DIR = <prefix>/src/<name>\-build |
| INSTALL_DIR = <prefix> |
| LOG_DIR = <STAMP_DIR> |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Otherwise, if the \fBEP_BASE\fP directory property is set then components |
| of an external project are stored under the specified base: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| TMP_DIR = <base>/tmp/<name> |
| STAMP_DIR = <base>/Stamp/<name> |
| DOWNLOAD_DIR = <base>/Download/<name> |
| SOURCE_DIR = <base>/Source/<name> |
| BINARY_DIR = <base>/Build/<name> |
| INSTALL_DIR = <base>/Install/<name> |
| LOG_DIR = <STAMP_DIR> |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| If no \fBPREFIX\fP, \fBEP_PREFIX\fP, or \fBEP_BASE\fP is specified, then the |
| default is to set \fBPREFIX\fP to \fB<name>\-prefix\fP\&. Relative paths are |
| interpreted with respect to \fBCMAKE_CURRENT_BINARY_DIR\fP at the |
| point where \fBExternalProject_Add()\fP is called. |
| .TP |
| \fBDownload Step Options:\fP |
| A download method can be omitted if the \fBSOURCE_DIR\fP option is used to |
| point to an existing non\-empty directory. Otherwise, one of the download |
| methods below must be specified (multiple download methods should not be |
| given) or a custom \fBDOWNLOAD_COMMAND\fP provided. |
| .INDENT 7.0 |
| .TP |
| .B \fBDOWNLOAD_COMMAND <cmd>...\fP |
| Overrides the command used for the download step |
| (\fBgenerator expressions\fP are |
| supported). If this option is specified, all other download options will |
| be ignored. Providing an empty string for \fB<cmd>\fP effectively disables |
| the download step. |
| .TP |
| .B \fIURL Download\fP |
| .INDENT 7.0 |
| .TP |
| .B \fBURL <url1> [<url2>...]\fP |
| List of paths and/or URL(s) of the external project\(aqs source. When more |
| than one URL is given, they are tried in turn until one succeeds. A URL |
| may be an ordinary path in the local file system (in which case it |
| must be the only URL provided) or any downloadable URL supported by the |
| \fBfile(DOWNLOAD)\fP command. A local filesystem path may refer to |
| either an existing directory or to an archive file, whereas a URL is |
| expected to point to a file which can be treated as an archive. When an |
| archive is used, it will be unpacked automatically unless the |
| \fBDOWNLOAD_NO_EXTRACT\fP option is set to prevent it. The archive type |
| is determined by inspecting the actual content rather than using logic |
| based on the file extension. |
| .sp |
| Changed in version 3.7: Multiple URLs are allowed. |
| |
| .TP |
| .B \fBURL_HASH <algo>=<hashValue>\fP |
| Hash of the archive file to be downloaded. The argument should be of |
| the form \fB<algo>=<hashValue>\fP where \fBalgo\fP can be any of the hashing |
| algorithms supported by the \fBfile()\fP command. Specifying this |
| option is strongly recommended for URL downloads, as it ensures the |
| integrity of the downloaded content. It is also used as a check for a |
| previously downloaded file, allowing connection to the remote location |
| to be avoided altogether if the local directory already has a file from |
| an earlier download that matches the specified hash. |
| .TP |
| .B \fBURL_MD5 <md5>\fP |
| Equivalent to \fBURL_HASH MD5=<md5>\fP\&. |
| .TP |
| .B \fBDOWNLOAD_NAME <fname>\fP |
| File name to use for the downloaded file. If not given, the end of the |
| URL is used to determine the file name. This option is rarely needed, |
| the default name is generally suitable and is not normally used outside |
| of code internal to the \fBExternalProject\fP module. |
| .TP |
| .B \fBDOWNLOAD_NO_EXTRACT <bool>\fP |
| New in version 3.6. |
| |
| .sp |
| Allows the extraction part of the download step to be disabled by |
| passing a boolean true value for this option. If this option is not |
| given, the downloaded contents will be unpacked automatically if |
| required. If extraction has been disabled, the full path to the |
| downloaded file is available as \fB<DOWNLOADED_FILE>\fP in subsequent |
| steps or as the property \fBDOWNLOADED_FILE\fP with the |
| \fI\%ExternalProject_Get_Property()\fP command. |
| .TP |
| .B \fBDOWNLOAD_NO_PROGRESS <bool>\fP |
| Can be used to disable logging the download progress. If this option is |
| not given, download progress messages will be logged. |
| .TP |
| .B \fBTIMEOUT <seconds>\fP |
| Maximum time allowed for file download operations. |
| .TP |
| .B \fBINACTIVITY_TIMEOUT <seconds>\fP |
| New in version 3.19. |
| |
| .sp |
| Terminate the operation after a period of inactivity. |
| .TP |
| .B \fBHTTP_USERNAME <username>\fP |
| New in version 3.7. |
| |
| .sp |
| Username for the download operation if authentication is required. |
| .TP |
| .B \fBHTTP_PASSWORD <password>\fP |
| New in version 3.7. |
| |
| .sp |
| Password for the download operation if authentication is required. |
| .TP |
| .B \fBHTTP_HEADER <header1> [<header2>...]\fP |
| New in version 3.7. |
| |
| .sp |
| Provides an arbitrary list of HTTP headers for the download operation. |
| This can be useful for accessing content in systems like AWS, etc. |
| .TP |
| .B \fBTLS_VERIFY <bool>\fP |
| Specifies whether certificate verification should be performed for |
| https URLs. If this option is not provided, the default behavior is |
| determined by the \fBCMAKE_TLS_VERIFY\fP variable (see |
| \fBfile(DOWNLOAD)\fP). If that is also not set, certificate |
| verification will not be performed. In situations where \fBURL_HASH\fP |
| cannot be provided, this option can be an alternative verification |
| measure. |
| .sp |
| Changed in version 3.6: This option also applies to \fBgit clone\fP invocations. |
| |
| .TP |
| .B \fBTLS_CAINFO <file>\fP |
| Specify a custom certificate authority file to use if \fBTLS_VERIFY\fP |
| is enabled. If this option is not specified, the value of the |
| \fBCMAKE_TLS_CAINFO\fP variable will be used instead (see |
| \fBfile(DOWNLOAD)\fP) |
| .TP |
| .B \fBNETRC <level>\fP |
| New in version 3.11. |
| |
| .sp |
| Specify whether the \fB\&.netrc\fP file is to be used for operation. |
| If this option is not specified, the value of the \fBCMAKE_NETRC\fP |
| variable will be used instead (see \fBfile(DOWNLOAD)\fP) |
| Valid levels are: |
| .INDENT 7.0 |
| .TP |
| .B \fBIGNORED\fP |
| The \fB\&.netrc\fP file is ignored. |
| This is the default. |
| .TP |
| .B \fBOPTIONAL\fP |
| The \fB\&.netrc\fP file is optional, and information in the URL |
| is preferred. The file will be scanned to find which ever |
| information is not specified in the URL. |
| .TP |
| .B \fBREQUIRED\fP |
| The \fB\&.netrc\fP file is required, and information in the URL |
| is ignored. |
| .UNINDENT |
| .TP |
| .B \fBNETRC_FILE <file>\fP |
| New in version 3.11. |
| |
| .sp |
| Specify an alternative \fB\&.netrc\fP file to the one in your home directory |
| if the \fBNETRC\fP level is \fBOPTIONAL\fP or \fBREQUIRED\fP\&. If this option |
| is not specified, the value of the \fBCMAKE_NETRC_FILE\fP variable |
| will be used instead (see \fBfile(DOWNLOAD)\fP) |
| .UNINDENT |
| .sp |
| New in version 3.1: Added support for \fItbz2\fP, \fI\&.tar.xz\fP, \fI\&.txz\fP, and \fI\&.7z\fP extensions. |
| |
| .TP |
| .B \fIGit\fP |
| NOTE: A git version of 1.6.5 or later is required if this download method |
| is used. |
| .INDENT 7.0 |
| .TP |
| .B \fBGIT_REPOSITORY <url>\fP |
| URL of the git repository. Any URL understood by the \fBgit\fP command |
| may be used. |
| .TP |
| .B \fBGIT_TAG <tag>\fP |
| Git branch name, tag or commit hash. Note that branch names and tags |
| should generally be specified as remote names (i.e. \fBorigin/myBranch\fP |
| rather than simply \fBmyBranch\fP). This ensures that if the remote end |
| has its tag moved or branch rebased or history rewritten, the local |
| clone will still be updated correctly. In general, however, specifying |
| a commit hash should be preferred for a number of reasons: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| If the local clone already has the commit corresponding to the hash, |
| no \fBgit fetch\fP needs to be performed to check for changes each time |
| CMake is re\-run. This can result in a significant speed up if many |
| external projects are being used. |
| .IP \(bu 2 |
| Using a specific git hash ensures that the main project\(aqs own history |
| is fully traceable to a specific point in the external project\(aqs |
| evolution. If a branch or tag name is used instead, then checking out |
| a specific commit of the main project doesn\(aqt necessarily pin the |
| whole build to a specific point in the life of the external project. |
| The lack of such deterministic behavior makes the main project lose |
| traceability and repeatability. |
| .UNINDENT |
| .sp |
| If \fBGIT_SHALLOW\fP is enabled then \fBGIT_TAG\fP works only with |
| branch names and tags. A commit hash is not allowed. |
| .TP |
| .B \fBGIT_REMOTE_NAME <name>\fP |
| The optional name of the remote. If this option is not specified, it |
| defaults to \fBorigin\fP\&. |
| .TP |
| .B \fBGIT_SUBMODULES <module>...\fP |
| Specific git submodules that should also be updated. If this option is |
| not provided, all git submodules will be updated. |
| .sp |
| Changed in version 3.16: When \fBCMP0097\fP is set to \fBNEW\fP, if this value is set |
| to an empty string then no submodules are initialized or updated. |
| |
| .TP |
| .B \fBGIT_SUBMODULES_RECURSE <bool>\fP |
| New in version 3.17. |
| |
| .sp |
| Specify whether git submodules (if any) should update recursively by |
| passing the \fB\-\-recursive\fP flag to \fBgit submodule update\fP\&. |
| If not specified, the default is on. |
| .TP |
| .B \fBGIT_SHALLOW <bool>\fP |
| New in version 3.6. |
| |
| .sp |
| When this option is enabled, the \fBgit clone\fP operation will be given |
| the \fB\-\-depth 1\fP option. This performs a shallow clone, which avoids |
| downloading the whole history and instead retrieves just the commit |
| denoted by the \fBGIT_TAG\fP option. |
| .TP |
| .B \fBGIT_PROGRESS <bool>\fP |
| New in version 3.8. |
| |
| .sp |
| When enabled, this option instructs the \fBgit clone\fP operation to |
| report its progress by passing it the \fB\-\-progress\fP option. Without |
| this option, the clone step for large projects may appear to make the |
| build stall, since nothing will be logged until the clone operation |
| finishes. While this option can be used to provide progress to prevent |
| the appearance of the build having stalled, it may also make the build |
| overly noisy if lots of external projects are used. |
| .TP |
| .B \fBGIT_CONFIG <option1> [<option2>...]\fP |
| New in version 3.8. |
| |
| .sp |
| Specify a list of config options to pass to \fBgit clone\fP\&. Each option |
| listed will be transformed into its own \fB\-\-config <option>\fP on the |
| \fBgit clone\fP command line, with each option required to be in the |
| form \fBkey=value\fP\&. |
| .TP |
| .B \fBGIT_REMOTE_UPDATE_STRATEGY <strategy>\fP |
| New in version 3.18. |
| |
| .sp |
| When \fBGIT_TAG\fP refers to a remote branch, this option can be used to |
| specify how the update step behaves. The \fB<strategy>\fP must be one of |
| the following: |
| .INDENT 7.0 |
| .TP |
| .B \fBCHECKOUT\fP |
| Ignore the local branch and always checkout the branch specified by |
| \fBGIT_TAG\fP\&. |
| .TP |
| .B \fBREBASE\fP |
| Try to rebase the current branch to the one specified by \fBGIT_TAG\fP\&. |
| If there are local uncommitted changes, they will be stashed first |
| and popped again after rebasing. If rebasing or popping stashed |
| changes fail, abort the rebase and halt with an error. |
| When \fBGIT_REMOTE_UPDATE_STRATEGY\fP is not present, this is the |
| default strategy unless the default has been overridden with |
| \fBCMAKE_EP_GIT_REMOTE_UPDATE_STRATEGY\fP (see below). |
| .TP |
| .B \fBREBASE_CHECKOUT\fP |
| Same as \fBREBASE\fP except if the rebase fails, an annotated tag will |
| be created at the original \fBHEAD\fP position from before the rebase |
| and then checkout \fBGIT_TAG\fP just like the \fBCHECKOUT\fP strategy. |
| The message stored on the annotated tag will give information about |
| what was attempted and the tag name will include a timestamp so that |
| each failed run will add a new tag. This strategy ensures no changes |
| will be lost, but updates should always succeed if \fBGIT_TAG\fP refers |
| to a valid ref unless there are uncommitted changes that cannot be |
| popped successfully. |
| .UNINDENT |
| .sp |
| The variable \fBCMAKE_EP_GIT_REMOTE_UPDATE_STRATEGY\fP can be set to |
| override the default strategy. This variable should not be set by a |
| project, it is intended for the user to set. It is primarily intended |
| for use in continuous integration scripts to ensure that when history |
| is rewritten on a remote branch, the build doesn\(aqt end up with unintended |
| changes or failed builds resulting from conflicts during rebase operations. |
| .UNINDENT |
| .TP |
| .B \fISubversion\fP |
| .INDENT 7.0 |
| .TP |
| .B \fBSVN_REPOSITORY <url>\fP |
| URL of the Subversion repository. |
| .TP |
| .B \fBSVN_REVISION \-r<rev>\fP |
| Revision to checkout from the Subversion repository. |
| .TP |
| .B \fBSVN_USERNAME <username>\fP |
| Username for the Subversion checkout and update. |
| .TP |
| .B \fBSVN_PASSWORD <password>\fP |
| Password for the Subversion checkout and update. |
| .TP |
| .B \fBSVN_TRUST_CERT <bool>\fP |
| Specifies whether to trust the Subversion server site certificate. If |
| enabled, the \fB\-\-trust\-server\-cert\fP option is passed to the \fBsvn\fP |
| checkout and update commands. |
| .UNINDENT |
| .TP |
| .B \fIMercurial\fP |
| .INDENT 7.0 |
| .TP |
| .B \fBHG_REPOSITORY <url>\fP |
| URL of the mercurial repository. |
| .TP |
| .B \fBHG_TAG <tag>\fP |
| Mercurial branch name, tag or commit id. |
| .UNINDENT |
| .TP |
| .B \fICVS\fP |
| .INDENT 7.0 |
| .TP |
| .B \fBCVS_REPOSITORY <cvsroot>\fP |
| CVSROOT of the CVS repository. |
| .TP |
| .B \fBCVS_MODULE <mod>\fP |
| Module to checkout from the CVS repository. |
| .TP |
| .B \fBCVS_TAG <tag>\fP |
| Tag to checkout from the CVS repository. |
| .UNINDENT |
| .UNINDENT |
| .TP |
| \fBUpdate Step Options:\fP |
| Whenever CMake is re\-run, by default the external project\(aqs sources will be |
| updated if the download method supports updates (e.g. a git repository |
| would be checked if the \fBGIT_TAG\fP does not refer to a specific commit). |
| .INDENT 7.0 |
| .TP |
| .B \fBUPDATE_COMMAND <cmd>...\fP |
| Overrides the download method\(aqs update step with a custom command. |
| The command may use |
| \fBgenerator expressions\fP\&. |
| .TP |
| .B \fBUPDATE_DISCONNECTED <bool>\fP |
| New in version 3.2. |
| |
| .sp |
| When enabled, this option causes the update step to be skipped. It does |
| not, however, prevent the download step. The update step can still be |
| added as a step target (see \fI\%ExternalProject_Add_StepTargets()\fP) |
| and called manually. This is useful if you want to allow developers to |
| build the project when disconnected from the network (the network may |
| still be needed for the download step though). |
| .sp |
| When this option is present, it is generally advisable to make the value |
| a cache variable under the developer\(aqs control rather than hard\-coding |
| it. If this option is not present, the default value is taken from the |
| \fBEP_UPDATE_DISCONNECTED\fP directory property. If that is also not |
| defined, updates are performed as normal. The \fBEP_UPDATE_DISCONNECTED\fP |
| directory property is intended as a convenience for controlling the |
| \fBUPDATE_DISCONNECTED\fP behavior for an entire section of a project\(aqs |
| directory hierarchy and may be a more convenient method of giving |
| developers control over whether or not to perform updates (assuming the |
| project also provides a cache variable or some other convenient method |
| for setting the directory property). |
| .sp |
| This may cause a step target to be created automatically for the |
| \fBdownload\fP step. See policy \fBCMP0114\fP\&. |
| .UNINDENT |
| .TP |
| \fBPatch Step Options:\fP |
| .INDENT 7.0 |
| .TP |
| .B \fBPATCH_COMMAND <cmd>...\fP |
| Specifies a custom command to patch the sources after an update. By |
| default, no patch command is defined. Note that it can be quite difficult |
| to define an appropriate patch command that performs robustly, especially |
| for download methods such as git where changing the \fBGIT_TAG\fP will not |
| discard changes from a previous patch, but the patch command will be |
| called again after updating to the new tag. |
| .UNINDENT |
| .TP |
| \fBConfigure Step Options:\fP |
| The configure step is run after the download and update steps. By default, |
| the external project is assumed to be a CMake project, but this can be |
| overridden if required. |
| .INDENT 7.0 |
| .TP |
| .B \fBCONFIGURE_COMMAND <cmd>...\fP |
| The default configure command runs CMake with a few options based on |
| the main project. The options added are typically only those needed to |
| use the same generator as the main project, but the \fBCMAKE_GENERATOR\fP |
| option can be given to override this. The project is responsible for |
| adding any toolchain details, flags or other settings it wants to |
| re\-use from the main project or otherwise specify (see \fBCMAKE_ARGS\fP, |
| \fBCMAKE_CACHE_ARGS\fP and \fBCMAKE_CACHE_DEFAULT_ARGS\fP below). |
| .sp |
| For non\-CMake external projects, the \fBCONFIGURE_COMMAND\fP option must |
| be used to override the default configure command |
| (\fBgenerator expressions\fP are |
| supported). For projects that require no configure step, specify this |
| option with an empty string as the command to execute. |
| .TP |
| .B \fBCMAKE_COMMAND /.../cmake\fP |
| Specify an alternative cmake executable for the configure step (use an |
| absolute path). This is generally not recommended, since it is |
| usually desirable to use the same CMake version throughout the whole |
| build. This option is ignored if a custom configure command has been |
| specified with \fBCONFIGURE_COMMAND\fP\&. |
| .TP |
| .B \fBCMAKE_GENERATOR <gen>\fP |
| Override the CMake generator used for the configure step. Without this |
| option, the same generator as the main build will be used. This option is |
| ignored if a custom configure command has been specified with the |
| \fBCONFIGURE_COMMAND\fP option. |
| .TP |
| .B \fBCMAKE_GENERATOR_PLATFORM <platform>\fP |
| New in version 3.1. |
| |
| .sp |
| Pass a generator\-specific platform name to the CMake command (see |
| \fBCMAKE_GENERATOR_PLATFORM\fP). It is an error to provide this |
| option without the \fBCMAKE_GENERATOR\fP option. |
| .TP |
| .B \fBCMAKE_GENERATOR_TOOLSET <toolset>\fP |
| Pass a generator\-specific toolset name to the CMake command (see |
| \fBCMAKE_GENERATOR_TOOLSET\fP). It is an error to provide this |
| option without the \fBCMAKE_GENERATOR\fP option. |
| .TP |
| .B \fBCMAKE_GENERATOR_INSTANCE <instance>\fP |
| New in version 3.11. |
| |
| .sp |
| Pass a generator\-specific instance selection to the CMake command (see |
| \fBCMAKE_GENERATOR_INSTANCE\fP). It is an error to provide this |
| option without the \fBCMAKE_GENERATOR\fP option. |
| .TP |
| .B \fBCMAKE_ARGS <arg>...\fP |
| The specified arguments are passed to the \fBcmake\fP command line. They |
| can be any argument the \fBcmake\fP command understands, not just cache |
| values defined by \fB\-D...\fP arguments (see also |
| \fBCMake Options\fP). |
| .sp |
| New in version 3.3: Arguments may use \fBgenerator expressions\fP\&. |
| |
| .TP |
| .B \fBCMAKE_CACHE_ARGS <arg>...\fP |
| This is an alternate way of specifying cache variables where command line |
| length issues may become a problem. The arguments are expected to be in |
| the form \fB\-Dvar:STRING=value\fP, which are then transformed into |
| CMake \fBset()\fP commands with the \fBFORCE\fP option used. These |
| \fBset()\fP commands are written to a pre\-load script which is then applied |
| using the \fBcmake \-C\fP command line option. |
| .sp |
| New in version 3.3: Arguments may use \fBgenerator expressions\fP\&. |
| |
| .TP |
| .B \fBCMAKE_CACHE_DEFAULT_ARGS <arg>...\fP |
| New in version 3.2. |
| |
| .sp |
| This is the same as the \fBCMAKE_CACHE_ARGS\fP option except the \fBset()\fP |
| commands do not include the \fBFORCE\fP keyword. This means the values act |
| as initial defaults only and will not override any variables already set |
| from a previous run. Use this option with care, as it can lead to |
| different behavior depending on whether the build starts from a fresh |
| build directory or re\-uses previous build contents. |
| .sp |
| New in version 3.15: If the CMake generator is the \fBGreen Hills MULTI\fP and not overridden then |
| the original project\(aqs settings for the GHS toolset and target system |
| customization cache variables are propagated into the external project. |
| |
| .TP |
| .B \fBSOURCE_SUBDIR <dir>\fP |
| New in version 3.7. |
| |
| .sp |
| When no \fBCONFIGURE_COMMAND\fP option is specified, the configure step |
| assumes the external project has a \fBCMakeLists.txt\fP file at the top of |
| its source tree (i.e. in \fBSOURCE_DIR\fP). The \fBSOURCE_SUBDIR\fP option |
| can be used to point to an alternative directory within the source tree |
| to use as the top of the CMake source tree instead. This must be a |
| relative path and it will be interpreted as being relative to |
| \fBSOURCE_DIR\fP\&. |
| .sp |
| New in version 3.14: When \fBBUILD_IN_SOURCE\fP option is enabled, the \fBBUILD_COMMAND\fP |
| is used to point to an alternative directory within the source tree. |
| |
| .TP |
| .B \fBCONFIGURE_HANDLED_BY_BUILD <bool>\fP |
| New in version 3.20. |
| |
| .sp |
| Enabling this option relaxes the dependencies of the configure step on |
| other external projects to order\-only. This means the configure step will |
| be executed after its external project dependencies are built but it will |
| not be marked dirty when one of its external project dependencies is |
| rebuilt. This option can be enabled when the build step is smart enough |
| to figure out if the configure step needs to be rerun. CMake and Meson are |
| examples of build systems whose build step is smart enough to know if the |
| configure step needs to be rerun. |
| .UNINDENT |
| .TP |
| \fBBuild Step Options:\fP |
| If the configure step assumed the external project uses CMake as its build |
| system, the build step will also. Otherwise, the build step will assume a |
| Makefile\-based build and simply run \fBmake\fP with no arguments as the |
| default build step. This can be overridden with custom build commands if |
| required. |
| .sp |
| If both the main project and the external project use make as their build |
| tool, the build step of the external project is invoked as a recursive |
| make using \fB$(MAKE)\fP\&. This will communicate some build tool settings |
| from the main project to the external project. If either the main project |
| or external project is not using make, no build tool settings will be |
| passed to the external project other than those established by the |
| configure step (i.e. running \fBninja \-v\fP in the main project will not |
| pass \fB\-v\fP to the external project\(aqs build step, even if it also uses |
| \fBninja\fP as its build tool). |
| .INDENT 7.0 |
| .TP |
| .B \fBBUILD_COMMAND <cmd>...\fP |
| Overrides the default build command |
| (\fBgenerator expressions\fP are |
| supported). If this option is not given, the default build command will |
| be chosen to integrate with the main build in the most appropriate way |
| (e.g. using recursive \fBmake\fP for Makefile generators or |
| \fBcmake \-\-build\fP if the project uses a CMake build). This option can be |
| specified with an empty string as the command to make the build step do |
| nothing. |
| .TP |
| .B \fBBUILD_IN_SOURCE <bool>\fP |
| When this option is enabled, the build will be done directly within the |
| external project\(aqs source tree. This should generally be avoided, the use |
| of a separate build directory is usually preferred, but it can be useful |
| when the external project assumes an in\-source build. The \fBBINARY_DIR\fP |
| option should not be specified if building in\-source. |
| .TP |
| .B \fBBUILD_ALWAYS <bool>\fP |
| Enabling this option forces the build step to always be run. This can be |
| the easiest way to robustly ensure that the external project\(aqs own build |
| dependencies are evaluated rather than relying on the default |
| success timestamp\-based method. This option is not normally needed unless |
| developers are expected to modify something the external project\(aqs build |
| depends on in a way that is not detectable via the step target |
| dependencies (e.g. \fBSOURCE_DIR\fP is used without a download method and |
| developers might modify the sources in \fBSOURCE_DIR\fP). |
| .TP |
| .B \fBBUILD_BYPRODUCTS <file>...\fP |
| New in version 3.2. |
| |
| .sp |
| Specifies files that will be generated by the build command but which |
| might or might not have their modification time updated by subsequent |
| builds. These ultimately get passed through as \fBBYPRODUCTS\fP to the |
| build step\(aqs own underlying call to \fBadd_custom_command()\fP\&. |
| .UNINDENT |
| .TP |
| \fBInstall Step Options:\fP |
| If the configure step assumed the external project uses CMake as its build |
| system, the install step will also. Otherwise, the install step will assume |
| a Makefile\-based build and simply run \fBmake install\fP as the default build |
| step. This can be overridden with custom install commands if required. |
| .INDENT 7.0 |
| .TP |
| .B \fBINSTALL_COMMAND <cmd>...\fP |
| The external project\(aqs own install step is invoked as part of the main |
| project\(aqs \fIbuild\fP\&. It is done after the external project\(aqs build step |
| and may be before or after the external project\(aqs test step (see the |
| \fBTEST_BEFORE_INSTALL\fP option below). The external project\(aqs install |
| rules are not part of the main project\(aqs install rules, so if anything |
| from the external project should be installed as part of the main build, |
| these need to be specified in the main build as additional |
| \fBinstall()\fP commands. The default install step builds the |
| \fBinstall\fP target of the external project, but this can be overridden |
| with a custom command using this option |
| (\fBgenerator expressions\fP are |
| supported). Passing an empty string as the \fB<cmd>\fP makes the install |
| step do nothing. |
| .UNINDENT |
| .sp |
| \fBNOTE:\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| If the \fBCMAKE_INSTALL_MODE\fP environment variable is set when the |
| main project is built, it will only have an effect if the following |
| conditions are met: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| The main project\(aqs configure step assumed the external project uses |
| CMake as its build system. |
| .IP \(bu 2 |
| The external project\(aqs install command actually runs. Note that due |
| to the way \fBExternalProject\fP may use timestamps internally, if |
| nothing the install step depends on needs to be re\-executed, the |
| install command might also not need to run. |
| .UNINDENT |
| .sp |
| Note also that \fBExternalProject\fP does not check whether the |
| \fBCMAKE_INSTALL_MODE\fP environment variable changes from one run |
| to another. |
| .UNINDENT |
| .UNINDENT |
| .TP |
| \fBTest Step Options:\fP |
| The test step is only defined if at least one of the following \fBTEST_...\fP |
| options are provided. |
| .INDENT 7.0 |
| .TP |
| .B \fBTEST_COMMAND <cmd>...\fP |
| Overrides the default test command |
| (\fBgenerator expressions\fP are |
| supported). If this option is not given, the default behavior of the test |
| step is to build the external project\(aqs own \fBtest\fP target. This option |
| can be specified with \fB<cmd>\fP as an empty string, which allows the test |
| step to still be defined, but it will do nothing. Do not specify any of |
| the other \fBTEST_...\fP options if providing an empty string as the test |
| command, but prefer to omit all \fBTEST_...\fP options altogether if the |
| test step target is not needed. |
| .TP |
| .B \fBTEST_BEFORE_INSTALL <bool>\fP |
| When this option is enabled, the test step will be executed before the |
| install step. The default behavior is for the test step to run after the |
| install step. |
| .TP |
| .B \fBTEST_AFTER_INSTALL <bool>\fP |
| This option is mainly useful as a way to indicate that the test step is |
| desired but all default behavior is sufficient. Specifying this option |
| with a boolean true value ensures the test step is defined and that it |
| comes after the install step. If both \fBTEST_BEFORE_INSTALL\fP and |
| \fBTEST_AFTER_INSTALL\fP are enabled, the latter is silently ignored. |
| .TP |
| .B \fBTEST_EXCLUDE_FROM_MAIN <bool>\fP |
| New in version 3.2. |
| |
| .sp |
| If enabled, the main build\(aqs default ALL target will not depend on the |
| test step. This can be a useful way of ensuring the test step is defined |
| but only gets invoked when manually requested. |
| This may cause a step target to be created automatically for either |
| the \fBinstall\fP or \fBbuild\fP step. See policy \fBCMP0114\fP\&. |
| .UNINDENT |
| .TP |
| \fBOutput Logging Options:\fP |
| Each of the following \fBLOG_...\fP options can be used to wrap the relevant |
| step in a script to capture its output to files. The log files will be |
| created in \fBLOG_DIR\fP if supplied or otherwise the \fBSTAMP_DIR\fP |
| directory with step\-specific file names. |
| .INDENT 7.0 |
| .TP |
| .B \fBLOG_DOWNLOAD <bool>\fP |
| When enabled, the output of the download step is logged to files. |
| .TP |
| .B \fBLOG_UPDATE <bool>\fP |
| When enabled, the output of the update step is logged to files. |
| .TP |
| .B \fBLOG_PATCH <bool>\fP |
| New in version 3.14. |
| |
| .sp |
| When enabled, the output of the patch step is logged to files. |
| .TP |
| .B \fBLOG_CONFIGURE <bool>\fP |
| When enabled, the output of the configure step is logged to files. |
| .TP |
| .B \fBLOG_BUILD <bool>\fP |
| When enabled, the output of the build step is logged to files. |
| .TP |
| .B \fBLOG_INSTALL <bool>\fP |
| When enabled, the output of the install step is logged to files. |
| .TP |
| .B \fBLOG_TEST <bool>\fP |
| When enabled, the output of the test step is logged to files. |
| .TP |
| .B \fBLOG_MERGED_STDOUTERR <bool>\fP |
| New in version 3.14. |
| |
| .sp |
| When enabled, stdout and stderr will be merged for any step whose |
| output is being logged to files. |
| .TP |
| .B \fBLOG_OUTPUT_ON_FAILURE <bool>\fP |
| New in version 3.14. |
| |
| .sp |
| This option only has an effect if at least one of the other \fBLOG_<step>\fP |
| options is enabled. If an error occurs for a step which has logging to |
| file enabled, that step\(aqs output will be printed to the console if |
| \fBLOG_OUTPUT_ON_FAILURE\fP is set to true. For cases where a large amount |
| of output is recorded, just the end of that output may be printed to the |
| console. |
| .UNINDENT |
| .TP |
| \fBTerminal Access Options:\fP |
| New in version 3.4. |
| |
| .sp |
| Steps can be given direct access to the terminal in some cases. Giving a |
| step access to the terminal may allow it to receive terminal input if |
| required, such as for authentication details not provided by other options. |
| With the \fBNinja\fP generator, these options place the steps in the |
| \fBconsole\fP \fBjob pool\fP\&. Each step can be given access |
| to the terminal individually via the following options: |
| .INDENT 7.0 |
| .TP |
| .B \fBUSES_TERMINAL_DOWNLOAD <bool>\fP |
| Give the download step access to the terminal. |
| .TP |
| .B \fBUSES_TERMINAL_UPDATE <bool>\fP |
| Give the update step access to the terminal. |
| .TP |
| .B \fBUSES_TERMINAL_PATCH <bool>\fP |
| New in version 3.23. |
| |
| .sp |
| Give the patch step access to the terminal. |
| .TP |
| .B \fBUSES_TERMINAL_CONFIGURE <bool>\fP |
| Give the configure step access to the terminal. |
| .TP |
| .B \fBUSES_TERMINAL_BUILD <bool>\fP |
| Give the build step access to the terminal. |
| .TP |
| .B \fBUSES_TERMINAL_INSTALL <bool>\fP |
| Give the install step access to the terminal. |
| .TP |
| .B \fBUSES_TERMINAL_TEST <bool>\fP |
| Give the test step access to the terminal. |
| .UNINDENT |
| .TP |
| \fBTarget Options:\fP |
| .INDENT 7.0 |
| .TP |
| .B \fBDEPENDS <targets>...\fP |
| Specify other targets on which the external project depends. The other |
| targets will be brought up to date before any of the external project\(aqs |
| steps are executed. Because the external project uses additional custom |
| targets internally for each step, the \fBDEPENDS\fP option is the most |
| convenient way to ensure all of those steps depend on the other targets. |
| Simply doing |
| \fBadd_dependencies(<name> <targets>)\fP will |
| not make any of the steps dependent on \fB<targets>\fP\&. |
| .TP |
| .B \fBEXCLUDE_FROM_ALL <bool>\fP |
| When enabled, this option excludes the external project from the default |
| ALL target of the main build. |
| .TP |
| .B \fBSTEP_TARGETS <step\-target>...\fP |
| Generate custom targets for the specified steps. This is required if the |
| steps need to be triggered manually or if they need to be used as |
| dependencies of other targets. If this option is not specified, the |
| default value is taken from the \fBEP_STEP_TARGETS\fP directory property. |
| See \fI\%ExternalProject_Add_StepTargets()\fP below for further |
| discussion of the effects of this option. |
| .TP |
| .B \fBINDEPENDENT_STEP_TARGETS <step\-target>...\fP |
| Deprecated since version 3.19: This is allowed only if policy \fBCMP0114\fP is not set to \fBNEW\fP\&. |
| |
| .sp |
| Generates custom targets for the specified steps and prevent these targets |
| from having the usual dependencies applied to them. If this option is not |
| specified, the default value is taken from the |
| \fBEP_INDEPENDENT_STEP_TARGETS\fP directory property. This option is mostly |
| useful for allowing individual steps to be driven independently, such as |
| for a CDash setup where each step should be initiated and reported |
| individually rather than as one whole build. See |
| \fI\%ExternalProject_Add_StepTargets()\fP below for further discussion |
| of the effects of this option. |
| .UNINDENT |
| .TP |
| \fBMiscellaneous Options:\fP |
| .INDENT 7.0 |
| .TP |
| .B \fBLIST_SEPARATOR <sep>\fP |
| For any of the various \fB\&..._COMMAND\fP options, and \fBCMAKE_ARGS\fP, |
| replace \fB;\fP with \fB<sep>\fP in the specified command lines. |
| This can be useful where list variables may be given in commands where |
| they should end up as space\-separated arguments (\fB<sep>\fP would be a |
| single space character string in this case). |
| .TP |
| .B \fBCOMMAND <cmd>...\fP |
| Any of the other \fB\&..._COMMAND\fP options can have additional commands |
| appended to them by following them with as many \fBCOMMAND ...\fP options |
| as needed |
| (\fBgenerator expressions\fP are |
| supported). For example: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ExternalProject_Add(example |
| ... # Download options, etc. |
| BUILD_COMMAND ${CMAKE_COMMAND} \-E echo "Starting $<CONFIG> build" |
| COMMAND ${CMAKE_COMMAND} \-\-build <BINARY_DIR> \-\-config $<CONFIG> |
| COMMAND ${CMAKE_COMMAND} \-E echo "$<CONFIG> build complete" |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .sp |
| It should also be noted that each build step is created via a call to |
| \fI\%ExternalProject_Add_Step()\fP\&. See that command\(aqs documentation for the |
| automatic substitutions that are supported for some options. |
| .UNINDENT |
| .SS Obtaining Project Properties |
| .INDENT 0.0 |
| .TP |
| .B ExternalProject_Get_Property |
| The \fBExternalProject_Get_Property()\fP function retrieves external project |
| target properties: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ExternalProject_Get_Property(<name> <prop1> [<prop2>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The function stores property values in variables of the same name. Property |
| names correspond to the keyword argument names of \fBExternalProject_Add()\fP\&. |
| For example, the source directory might be retrieved like so: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ExternalProject_Get_property(myExtProj SOURCE_DIR) |
| message("Source dir of myExtProj = ${SOURCE_DIR}") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .SS Explicit Step Management |
| .sp |
| The \fBExternalProject_Add()\fP function on its own is often sufficient for |
| incorporating an external project into the main build. Certain scenarios |
| require additional work to implement desired behavior, such as adding in a |
| custom step or making steps available as manually triggerable targets. The |
| \fBExternalProject_Add_Step()\fP, \fBExternalProject_Add_StepTargets()\fP and |
| \fBExternalProject_Add_StepDependencies\fP functions provide the lower level |
| control needed to implement such step\-level capabilities. |
| .INDENT 0.0 |
| .TP |
| .B ExternalProject_Add_Step |
| The \fBExternalProject_Add_Step()\fP function specifies an additional custom |
| step for an external project defined by an earlier call to |
| \fI\%ExternalProject_Add()\fP: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ExternalProject_Add_Step(<name> <step> [<option>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fB<name>\fP is the same as the name passed to the original call to |
| \fI\%ExternalProject_Add()\fP\&. The specified \fB<step>\fP must not be one of |
| the pre\-defined steps (\fBmkdir\fP, \fBdownload\fP, \fBupdate\fP, |
| \fBpatch\fP, \fBconfigure\fP, \fBbuild\fP, \fBinstall\fP or \fBtest\fP). The supported |
| options are: |
| .INDENT 7.0 |
| .TP |
| .B \fBCOMMAND <cmd>...\fP |
| The command line to be executed by this custom step |
| (\fBgenerator expressions\fP are |
| supported). This option can be repeated multiple times to specify multiple |
| commands to be executed in order. |
| .TP |
| .B \fBCOMMENT "<text>..."\fP |
| Text to be printed when the custom step executes. |
| .TP |
| .B \fBDEPENDEES <step>...\fP |
| Other steps (custom or pre\-defined) on which this step depends. |
| .TP |
| .B \fBDEPENDERS <step>...\fP |
| Other steps (custom or pre\-defined) that depend on this new custom step. |
| .TP |
| .B \fBDEPENDS <file>...\fP |
| Files on which this custom step depends. |
| .TP |
| .B \fBINDEPENDENT <bool>\fP |
| New in version 3.19. |
| |
| .sp |
| Specifies whether this step is independent of the external dependencies |
| specified by the \fI\%ExternalProject_Add()\fP\(aqs \fBDEPENDS\fP option. |
| The default is \fBFALSE\fP\&. Steps marked as independent may depend only |
| on other steps marked independent. See policy \fBCMP0114\fP\&. |
| .sp |
| Note that this use of the term "independent" refers only to independence |
| from external targets specified by the \fBDEPENDS\fP option and is |
| orthogonal to a step\(aqs dependencies on other steps. |
| .sp |
| If a step target is created for an independent step by the |
| \fI\%ExternalProject_Add()\fP \fBSTEP_TARGETS\fP option or by the |
| \fI\%ExternalProject_Add_StepTargets()\fP function, it will not depend |
| on the external targets, but may depend on targets for other steps. |
| .TP |
| .B \fBBYPRODUCTS <file>...\fP |
| New in version 3.2. |
| |
| .sp |
| Files that will be generated by this custom step but which might or might |
| not have their modification time updated by subsequent builds. This list of |
| files will ultimately be passed through as the \fBBYPRODUCTS\fP option to the |
| \fBadd_custom_command()\fP used to implement the custom step internally. |
| .TP |
| .B \fBALWAYS <bool>\fP |
| When enabled, this option specifies that the custom step should always be |
| run (i.e. that it is always considered out of date). |
| .TP |
| .B \fBEXCLUDE_FROM_MAIN <bool>\fP |
| When enabled, this option specifies that the external project\(aqs main target |
| does not depend on the custom step. |
| This may cause step targets to be created automatically for the steps on |
| which this step depends. See policy \fBCMP0114\fP\&. |
| .TP |
| .B \fBWORKING_DIRECTORY <dir>\fP |
| Specifies the working directory to set before running the custom step\(aqs |
| command. If this option is not specified, the directory will be the value |
| of the \fBCMAKE_CURRENT_BINARY_DIR\fP at the point where |
| \fBExternalProject_Add_Step()\fP was called. |
| .TP |
| .B \fBLOG <bool>\fP |
| If set, this causes the output from the custom step to be captured to files |
| in the external project\(aqs \fBLOG_DIR\fP if supplied or \fBSTAMP_DIR\fP\&. |
| .TP |
| .B \fBUSES_TERMINAL <bool>\fP |
| If enabled, this gives the custom step direct access to the terminal if |
| possible. |
| .UNINDENT |
| .sp |
| The command line, comment, working directory and byproducts of every |
| standard and custom step are processed to replace the tokens |
| \fB<SOURCE_DIR>\fP, \fB<SOURCE_SUBDIR>\fP, \fB<BINARY_DIR>\fP, \fB<INSTALL_DIR>\fP |
| \fB<TMP_DIR>\fP, \fB<DOWNLOAD_DIR>\fP and \fB<DOWNLOADED_FILE>\fP with their |
| corresponding property values defined in the original call to |
| \fI\%ExternalProject_Add()\fP\&. |
| .sp |
| New in version 3.3: Token replacement is extended to byproducts. |
| |
| .sp |
| New in version 3.11: The \fB<DOWNLOAD_DIR>\fP substitution token. |
| |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B ExternalProject_Add_StepTargets |
| The \fBExternalProject_Add_StepTargets()\fP function generates targets for the |
| steps listed. The name of each created target will be of the form |
| \fB<name>\-<step>\fP: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ExternalProject_Add_StepTargets(<name> <step1> [<step2>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Creating a target for a step allows it to be used as a dependency of another |
| target or to be triggered manually. Having targets for specific steps also |
| allows them to be driven independently of each other by specifying targets on |
| build command lines. For example, you may be submitting to a sub\-project |
| based dashboard where you want to drive the configure portion of the build, |
| then submit to the dashboard, followed by the build portion, followed |
| by tests. If you invoke a custom target that depends on a step halfway |
| through the step dependency chain, then all the previous steps will also run |
| to ensure everything is up to date. |
| .sp |
| Internally, \fI\%ExternalProject_Add()\fP calls |
| \fI\%ExternalProject_Add_Step()\fP to create each step. If any |
| \fBSTEP_TARGETS\fP were specified, then \fBExternalProject_Add_StepTargets()\fP |
| will also be called after \fI\%ExternalProject_Add_Step()\fP\&. Even if a |
| step is not mentioned in the \fBSTEP_TARGETS\fP option, |
| \fBExternalProject_Add_StepTargets()\fP can still be called later to manually |
| define a target for the step. |
| .sp |
| The \fBSTEP_TARGETS\fP option for \fI\%ExternalProject_Add()\fP is generally |
| the easiest way to ensure targets are created for specific steps of interest. |
| For custom steps, \fBExternalProject_Add_StepTargets()\fP must be called |
| explicitly if a target should also be created for that custom step. |
| An alternative to these two options is to populate the \fBEP_STEP_TARGETS\fP |
| directory property. It acts as a default for the step target options and |
| can save having to repeatedly specify the same set of step targets when |
| multiple external projects are being defined. |
| .sp |
| New in version 3.19: If \fBCMP0114\fP is set to \fBNEW\fP, step targets are fully responsible |
| for holding the custom commands implementing their steps. The primary target |
| created by \fBExternalProject_Add\fP depends on the step targets, and the |
| step targets depend on each other. The target\-level dependencies match |
| the file\-level dependencies used by the custom commands for each step. |
| The targets for steps created with \fI\%ExternalProject_Add_Step()\fP\(aqs |
| \fBINDEPENDENT\fP option do not depend on the external targets specified |
| by \fI\%ExternalProject_Add()\fP\(aqs \fBDEPENDS\fP option. The predefined |
| steps \fBmkdir\fP, \fBdownload\fP, \fBupdate\fP, and \fBpatch\fP are independent. |
| |
| .sp |
| If \fBCMP0114\fP is not \fBNEW\fP, the following deprecated behavior |
| is available: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| A deprecated \fBNO_DEPENDS\fP option may be specified immediately after the |
| \fB<name>\fP and before the first step. |
| If the \fBNO_DEPENDS\fP option is specified, the step target will not depend on |
| the dependencies of the external project (i.e. on any dependencies of the |
| \fB<name>\fP custom target created by \fI\%ExternalProject_Add()\fP). This is |
| usually safe for the \fBdownload\fP, \fBupdate\fP and \fBpatch\fP steps, since they |
| do not typically require that the dependencies are updated and built. Using |
| \fBNO_DEPENDS\fP for any of the other pre\-defined steps, however, may break |
| parallel builds. Only use \fBNO_DEPENDS\fP where it is certain that the named |
| steps genuinely do not have dependencies. For custom steps, consider whether |
| or not the custom commands require the dependencies to be configured, built |
| and installed. |
| .IP \(bu 2 |
| The \fBINDEPENDENT_STEP_TARGETS\fP option for \fI\%ExternalProject_Add()\fP, |
| or the \fBEP_INDEPENDENT_STEP_TARGETS\fP directory property, tells the |
| function to call \fBExternalProject_Add_StepTargets()\fP internally |
| using the \fBNO_DEPENDS\fP option for the specified steps. |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B ExternalProject_Add_StepDependencies |
| New in version 3.2. |
| |
| .sp |
| The \fBExternalProject_Add_StepDependencies()\fP function can be used to add |
| dependencies to a step. The dependencies added must be targets CMake already |
| knows about (these can be ordinary executable or library targets, custom |
| targets or even step targets of another external project): |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ExternalProject_Add_StepDependencies(<name> <step> <target1> [<target2>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This function takes care to set both target and file level dependencies and |
| will ensure that parallel builds will not break. It should be used instead of |
| \fBadd_dependencies()\fP whenever adding a dependency for some of the step |
| targets generated by the \fBExternalProject\fP module. |
| .UNINDENT |
| .SS Examples |
| .sp |
| The following example shows how to download and build a hypothetical project |
| called \fIFooBar\fP from github: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| include(ExternalProject) |
| ExternalProject_Add(foobar |
| GIT_REPOSITORY git@github.com:FooCo/FooBar.git |
| GIT_TAG origin/release/1.2.3 |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| For the sake of the example, also define a second hypothetical external project |
| called \fISecretSauce\fP, which is downloaded from a web server. Two URLs are given |
| to take advantage of a faster internal network if available, with a fallback to |
| a slower external server. The project is a typical \fBMakefile\fP project with no |
| configure step, so some of the default commands are overridden. The build is |
| only required to build the \fIsauce\fP target: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_program(MAKE_EXE NAMES gmake nmake make) |
| ExternalProject_Add(secretsauce |
| URL http://intranet.somecompany.com/artifacts/sauce\-2.7.tgz |
| https://www.somecompany.com/downloads/sauce\-2.7.zip |
| URL_HASH MD5=d41d8cd98f00b204e9800998ecf8427e |
| CONFIGURE_COMMAND "" |
| BUILD_COMMAND ${MAKE_EXE} sauce |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Suppose the build step of \fBsecretsauce\fP requires that \fBfoobar\fP must already |
| be built. This could be enforced like so: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ExternalProject_Add_StepDependencies(secretsauce build foobar) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Another alternative would be to create a custom target for \fBfoobar\fP\(aqs build |
| step and make \fBsecretsauce\fP depend on that rather than the whole \fBfoobar\fP |
| project. This would mean \fBfoobar\fP only needs to be built, it doesn\(aqt need to |
| run its install or test steps before \fBsecretsauce\fP can be built. The |
| dependency can also be defined along with the \fBsecretsauce\fP project: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ExternalProject_Add_StepTargets(foobar build) |
| ExternalProject_Add(secretsauce |
| URL http://intranet.somecompany.com/artifacts/sauce\-2.7.tgz |
| https://www.somecompany.com/downloads/sauce\-2.7.zip |
| URL_HASH MD5=d41d8cd98f00b204e9800998ecf8427e |
| CONFIGURE_COMMAND "" |
| BUILD_COMMAND ${MAKE_EXE} sauce |
| DEPENDS foobar\-build |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Instead of calling \fI\%ExternalProject_Add_StepTargets()\fP, the target could |
| be defined along with the \fBfoobar\fP project itself: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ExternalProject_Add(foobar |
| GIT_REPOSITORY git@github.com:FooCo/FooBar.git |
| GIT_TAG origin/release/1.2.3 |
| STEP_TARGETS build |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| If many external projects should have the same set of step targets, setting a |
| directory property may be more convenient. The \fBbuild\fP step target could be |
| created automatically by setting the \fBEP_STEP_TARGETS\fP directory property |
| before creating the external projects with \fI\%ExternalProject_Add()\fP: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_property(DIRECTORY PROPERTY EP_STEP_TARGETS build) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Lastly, suppose that \fBsecretsauce\fP provides a script called \fBmakedoc\fP which |
| can be used to generate its own documentation. Further suppose that the script |
| expects the output directory to be provided as the only parameter and that it |
| should be run from the \fBsecretsauce\fP source directory. A custom step and a |
| custom target to trigger the script can be defined like so: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ExternalProject_Add_Step(secretsauce docs |
| COMMAND <SOURCE_DIR>/makedoc <BINARY_DIR> |
| WORKING_DIRECTORY <SOURCE_DIR> |
| COMMENT "Building secretsauce docs" |
| ALWAYS TRUE |
| EXCLUDE_FROM_MAIN TRUE |
| ) |
| ExternalProject_Add_StepTargets(secretsauce docs) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The custom step could then be triggered from the main build like so: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cmake \-\-build . \-\-target secretsauce\-docs |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FeatureSummary |
| .sp |
| Functions for generating a summary of enabled/disabled features. |
| .sp |
| These functions can be used to generate a summary of enabled and disabled |
| packages and/or feature for a build tree such as: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| \-\- The following OPTIONAL packages have been found: |
| LibXml2 (required version >= 2.4), XML processing lib, <http://xmlsoft.org> |
| * Enables HTML\-import in MyWordProcessor |
| * Enables odt\-export in MyWordProcessor |
| PNG, A PNG image library., <http://www.libpng.org/pub/png/> |
| * Enables saving screenshots |
| \-\- The following OPTIONAL packages have not been found: |
| Lua51, The Lua scripting language., <http://www.lua.org> |
| * Enables macros in MyWordProcessor |
| Foo, Foo provides cool stuff. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS Global Properties |
| .INDENT 0.0 |
| .TP |
| .B FeatureSummary_PKG_TYPES |
| .UNINDENT |
| .sp |
| The global property \fI\%FeatureSummary_PKG_TYPES\fP defines the type of |
| packages used by \fIFeatureSummary\fP\&. |
| .sp |
| The order in this list is important, the first package type in the list is the |
| least important, the last is the most important. the of a package can only be |
| changed to higher types. |
| .sp |
| The default package types are , \fBRUNTIME\fP, \fBOPTIONAL\fP, \fBRECOMMENDED\fP and |
| \fBREQUIRED\fP, and their importance is |
| \fBRUNTIME < OPTIONAL < RECOMMENDED < REQUIRED\fP\&. |
| .INDENT 0.0 |
| .TP |
| .B FeatureSummary_REQUIRED_PKG_TYPES |
| .UNINDENT |
| .sp |
| The global property \fI\%FeatureSummary_REQUIRED_PKG_TYPES\fP defines which |
| package types are required. |
| .sp |
| If one or more package in this categories has not been found, CMake will abort |
| when calling \fI\%feature_summary()\fP with the |
| \(aqFATAL_ON_MISSING_REQUIRED_PACKAGES\(aq option enabled. |
| .sp |
| The default value for this global property is \fBREQUIRED\fP\&. |
| .INDENT 0.0 |
| .TP |
| .B FeatureSummary_DEFAULT_PKG_TYPE |
| .UNINDENT |
| .sp |
| The global property \fI\%FeatureSummary_DEFAULT_PKG_TYPE\fP defines which |
| package type is the default one. |
| When calling \fI\%feature_summary()\fP, if the user did not set the package type |
| explicitly, the package will be assigned to this category. |
| .sp |
| This value must be one of the types defined in the |
| \fI\%FeatureSummary_PKG_TYPES\fP global property unless the package type |
| is set for all the packages. |
| .sp |
| The default value for this global property is \fBOPTIONAL\fP\&. |
| .INDENT 0.0 |
| .TP |
| .B FeatureSummary_<TYPE>_DESCRIPTION |
| .UNINDENT |
| .sp |
| New in version 3.9. |
| |
| .sp |
| The global property \fI\%FeatureSummary_<TYPE>_DESCRIPTION\fP can be defined |
| for each type to replace the type name with the specified string whenever the |
| package type is used in an output string. |
| .sp |
| If not set, the string "\fB<TYPE>\fP packages" is used. |
| .SS Functions |
| .INDENT 0.0 |
| .TP |
| .B feature_summary |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| feature_summary( [FILENAME <file>] |
| [APPEND] |
| [VAR <variable_name>] |
| [INCLUDE_QUIET_PACKAGES] |
| [FATAL_ON_MISSING_REQUIRED_PACKAGES] |
| [DESCRIPTION "<description>" | DEFAULT_DESCRIPTION] |
| [QUIET_ON_EMPTY] |
| WHAT (ALL |
| | PACKAGES_FOUND | PACKAGES_NOT_FOUND |
| | <TYPE>_PACKAGES_FOUND | <TYPE>_PACKAGES_NOT_FOUND |
| | ENABLED_FEATURES | DISABLED_FEATURES) |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The \fBfeature_summary()\fP macro can be used to print information about |
| enabled or disabled packages or features of a project. By default, |
| only the names of the features/packages will be printed and their |
| required version when one was specified. Use \fBset_package_properties()\fP |
| to add more useful information, like e.g. a download URL for the |
| respective package or their purpose in the project. |
| .sp |
| The \fBWHAT\fP option is the only mandatory option. Here you specify what |
| information will be printed: |
| .INDENT 7.0 |
| .TP |
| .B \fBALL\fP |
| print everything |
| .TP |
| .B \fBENABLED_FEATURES\fP |
| the list of all features which are enabled |
| .TP |
| .B \fBDISABLED_FEATURES\fP |
| the list of all features which are disabled |
| .TP |
| .B \fBPACKAGES_FOUND\fP |
| the list of all packages which have been found |
| .TP |
| .B \fBPACKAGES_NOT_FOUND\fP |
| the list of all packages which have not been found |
| .UNINDENT |
| .sp |
| For each package type \fB<TYPE>\fP defined by the |
| \fI\%FeatureSummary_PKG_TYPES\fP global property, the following |
| information can also be used: |
| .INDENT 7.0 |
| .TP |
| .B \fB<TYPE>_PACKAGES_FOUND\fP |
| only those packages which have been found which have the type <TYPE> |
| .TP |
| .B \fB<TYPE>_PACKAGES_NOT_FOUND\fP |
| only those packages which have not been found which have the type <TYPE> |
| .UNINDENT |
| .sp |
| Changed in version 3.1: With the exception of the \fBALL\fP value, these values can be combined |
| in order to customize the output. For example: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| feature_summary(WHAT ENABLED_FEATURES DISABLED_FEATURES) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| |
| .sp |
| If a \fBFILENAME\fP is given, the information is printed into this file. If |
| \fBAPPEND\fP is used, it is appended to this file, otherwise the file is |
| overwritten if it already existed. If the VAR option is used, the |
| information is "printed" into the specified variable. If \fBFILENAME\fP is |
| not used, the information is printed to the terminal. Using the |
| \fBDESCRIPTION\fP option a description or headline can be set which will be |
| printed above the actual content. If only one type of |
| package was requested, no title is printed, unless it is explicitly set using |
| either \fBDESCRIPTION\fP to use a custom string, or \fBDEFAULT_DESCRIPTION\fP to |
| use a default title for the requested type. |
| If \fBINCLUDE_QUIET_PACKAGES\fP is given, packages which have been searched with |
| \fBfind_package(... QUIET)\fP will also be listed. By default they are skipped. |
| If \fBFATAL_ON_MISSING_REQUIRED_PACKAGES\fP is given, CMake will abort if a |
| package which is marked as one of the package types listed in the |
| \fI\%FeatureSummary_REQUIRED_PKG_TYPES\fP global property has not been |
| found. |
| The default value for the \fI\%FeatureSummary_REQUIRED_PKG_TYPES\fP global |
| property is \fBREQUIRED\fP\&. |
| .sp |
| New in version 3.9: The \fBDEFAULT_DESCRIPTION\fP option. |
| |
| .sp |
| The \fI\%FeatureSummary_DEFAULT_PKG_TYPE\fP global property can be |
| modified to change the default package type assigned when not explicitly |
| assigned by the user. |
| .sp |
| New in version 3.8: If the \fBQUIET_ON_EMPTY\fP option is used, if only one type of package was |
| requested, and no packages belonging to that category were found, then no |
| output (including the \fBDESCRIPTION\fP) is printed or added to the \fBVAR\fP |
| variable. |
| |
| .sp |
| Example 1, append everything to a file: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| include(FeatureSummary) |
| feature_summary(WHAT ALL |
| FILENAME ${CMAKE_BINARY_DIR}/all.log APPEND) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Example 2, print the enabled features into the variable |
| enabledFeaturesText, including QUIET packages: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| include(FeatureSummary) |
| feature_summary(WHAT ENABLED_FEATURES |
| INCLUDE_QUIET_PACKAGES |
| DESCRIPTION "Enabled Features:" |
| VAR enabledFeaturesText) |
| message(STATUS "${enabledFeaturesText}") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Example 3, change default package types and print only the categories that |
| are not empty: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| include(FeatureSummary) |
| set_property(GLOBAL APPEND PROPERTY FeatureSummary_PKG_TYPES BUILD) |
| find_package(FOO) |
| set_package_properties(FOO PROPERTIES TYPE BUILD) |
| feature_summary(WHAT BUILD_PACKAGES_FOUND |
| Description "Build tools found:" |
| QUIET_ON_EMPTY) |
| feature_summary(WHAT BUILD_PACKAGES_NOT_FOUND |
| Description "Build tools not found:" |
| QUIET_ON_EMPTY) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B set_package_properties |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_package_properties(<name> PROPERTIES |
| [ URL <url> ] |
| [ DESCRIPTION <description> ] |
| [ TYPE (RUNTIME|OPTIONAL|RECOMMENDED|REQUIRED) ] |
| [ PURPOSE <purpose> ] |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Use this macro to set up information about the named package, which |
| can then be displayed via FEATURE_SUMMARY(). This can be done either |
| directly in the Find\-module or in the project which uses the module |
| after the find_package() call. The features for which information can |
| be set are added automatically by the find_package() command. |
| .INDENT 7.0 |
| .TP |
| .B \fBURL <url>\fP |
| This should be the homepage of the package, or something similar. |
| Ideally this is set already directly in the Find\-module. |
| .TP |
| .B \fBDESCRIPTION <description>\fP |
| A short description what that package is, at most one sentence. |
| Ideally this is set already directly in the Find\-module. |
| .TP |
| .B \fBTYPE <type>\fP |
| What type of dependency has the using project on that package. |
| Default is \fBOPTIONAL\fP\&. In this case it is a package which can be used |
| by the project when available at buildtime, but it also work without. |
| \fBRECOMMENDED\fP is similar to \fBOPTIONAL\fP, i.e. the project will build if |
| the package is not present, but the functionality of the resulting |
| binaries will be severely limited. If a \fBREQUIRED\fP package is not |
| available at buildtime, the project may not even build. This can be |
| combined with the \fBFATAL_ON_MISSING_REQUIRED_PACKAGES\fP argument for |
| \fBfeature_summary()\fP\&. Last, a \fBRUNTIME\fP package is a package which is |
| actually not used at all during the build, but which is required for |
| actually running the resulting binaries. So if such a package is |
| missing, the project can still be built, but it may not work later on. |
| If \fBset_package_properties()\fP is called multiple times for the same |
| package with different TYPEs, the \fBTYPE\fP is only changed to higher |
| TYPEs (\fBRUNTIME < OPTIONAL < RECOMMENDED < REQUIRED\fP), lower TYPEs are |
| ignored. The \fBTYPE\fP property is project\-specific, so it cannot be set |
| by the Find\-module, but must be set in the project. |
| Type accepted can be changed by setting the |
| \fI\%FeatureSummary_PKG_TYPES\fP global property. |
| .TP |
| .B \fBPURPOSE <purpose>\fP |
| This describes which features this package enables in the |
| project, i.e. it tells the user what functionality he gets in the |
| resulting binaries. If set_package_properties() is called multiple |
| times for a package, all PURPOSE properties are appended to a list of |
| purposes of the package in the project. As the TYPE property, also |
| the PURPOSE property is project\-specific, so it cannot be set by the |
| Find\-module, but must be set in the project. |
| .UNINDENT |
| .sp |
| Example for setting the info for a package: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_package(LibXml2) |
| set_package_properties(LibXml2 PROPERTIES |
| DESCRIPTION "A XML processing library." |
| URL "http://xmlsoft.org/") |
| # or |
| set_package_properties(LibXml2 PROPERTIES |
| TYPE RECOMMENDED |
| PURPOSE "Enables HTML\-import in MyWordProcessor") |
| # or |
| set_package_properties(LibXml2 PROPERTIES |
| TYPE OPTIONAL |
| PURPOSE "Enables odt\-export in MyWordProcessor") |
| |
| find_package(DBUS) |
| set_package_properties(DBUS PROPERTIES |
| TYPE RUNTIME |
| PURPOSE "Necessary to disable the screensaver during a presentation") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B add_feature_info |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_feature_info(<name> <enabled> <description>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Use this macro to add information about a feature with the given \fB<name>\fP\&. |
| \fB<enabled>\fP contains whether this feature is enabled or not. It can be a |
| variable or a list of conditions. |
| \fB<description>\fP is a text describing the feature. The information can |
| be displayed using \fBfeature_summary()\fP for \fBENABLED_FEATURES\fP and |
| \fBDISABLED_FEATURES\fP respectively. |
| .sp |
| Changed in version 3.8: \fB<enabled>\fP can be a list of conditions. |
| |
| .sp |
| Example for setting the info for a feature: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| option(WITH_FOO "Help for foo" ON) |
| add_feature_info(Foo WITH_FOO "The Foo feature provides very cool stuff.") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .SS Legacy Macros |
| .sp |
| The following macros are provided for compatibility with previous |
| CMake versions: |
| .INDENT 0.0 |
| .TP |
| .B set_package_info |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_package_info(<name> <description> [ <url> [<purpose>] ]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Use this macro to set up information about the named package, which |
| can then be displayed via \fBfeature_summary()\fP\&. This can be done either |
| directly in the Find\-module or in the project which uses the module |
| after the \fBfind_package()\fP call. The features for which information |
| can be set are added automatically by the \fBfind_package()\fP command. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B set_feature_info |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_feature_info(<name> <description> [<url>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Does the same as: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_package_info(<name> <description> <url>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B print_enabled_features |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| print_enabled_features() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Does the same as |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| feature_summary(WHAT ENABLED_FEATURES DESCRIPTION "Enabled features:") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B print_disabled_features |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| print_disabled_features() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Does the same as |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| feature_summary(WHAT DISABLED_FEATURES DESCRIPTION "Disabled features:") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .SS FetchContent |
| .sp |
| New in version 3.11. |
| |
| .SS Overview |
| .sp |
| This module enables populating content at configure time via any method |
| supported by the \fBExternalProject\fP module. Whereas |
| \fBExternalProject_Add()\fP downloads at build time, the |
| \fBFetchContent\fP module makes content available immediately, allowing the |
| configure step to use the content in commands like \fBadd_subdirectory()\fP, |
| \fBinclude()\fP or \fBfile()\fP operations. |
| .sp |
| Content population details should be defined separately from the command that |
| performs the actual population. This separation ensures that all the |
| dependency details are defined before anything might try to use them to |
| populate content. This is particularly important in more complex project |
| hierarchies where dependencies may be shared between multiple projects. |
| .sp |
| The following shows a typical example of declaring content details for some |
| dependencies and then ensuring they are populated with a separate call: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| FetchContent_Declare( |
| googletest |
| GIT_REPOSITORY https://github.com/google/googletest.git |
| GIT_TAG 703bd9caab50b139428cea1aaff9974ebee5742e # release\-1.10.0 |
| ) |
| FetchContent_Declare( |
| myCompanyIcons |
| URL https://intranet.mycompany.com/assets/iconset_1.12.tar.gz |
| URL_HASH MD5=5588a7b18261c20068beabfb4f530b87 |
| ) |
| |
| FetchContent_MakeAvailable(googletest myCompanyIcons) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The \fI\%FetchContent_MakeAvailable()\fP command ensures the named |
| dependencies have been populated, either by an earlier call or by populating |
| them itself. When performing the population, it will also add them to the |
| main build, if possible, so that the main build can use the populated |
| projects\(aq targets, etc. See the command\(aqs documentation for how these steps |
| are performed. |
| .sp |
| When using a hierarchical project arrangement, projects at higher levels in |
| the hierarchy are able to override the declared details of content specified |
| anywhere lower in the project hierarchy. The first details to be declared |
| for a given dependency take precedence, regardless of where in the project |
| hierarchy that occurs. Similarly, the first call that tries to populate a |
| dependency "wins", with subsequent populations reusing the result of the |
| first instead of repeating the population again. |
| See the \fI\%Examples\fP which demonstrate |
| this scenario. |
| .sp |
| In some cases, the main project may need to have more precise control over |
| the population, or it may be required to explicitly define the population |
| steps in a way that cannot be captured by the declared details alone. |
| For such situations, the lower level \fI\%FetchContent_GetProperties()\fP and |
| \fI\%FetchContent_Populate()\fP commands can be used. These lack the richer |
| features provided by \fI\%FetchContent_MakeAvailable()\fP though, so their |
| direct use should be considered a last resort. The typical pattern of such |
| custom steps looks like this: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| # NOTE: Where possible, prefer to use FetchContent_MakeAvailable() |
| # instead of custom logic like this |
| |
| # Check if population has already been performed |
| FetchContent_GetProperties(depname) |
| if(NOT depname_POPULATED) |
| # Fetch the content using previously declared details |
| FetchContent_Populate(depname) |
| |
| # Set custom variables, policies, etc. |
| # ... |
| |
| # Bring the populated content into the build |
| add_subdirectory(${depname_SOURCE_DIR} ${depname_BINARY_DIR}) |
| endif() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The \fBFetchContent\fP module also supports defining and populating |
| content in a single call, with no check for whether the content has been |
| populated elsewhere already. This should not be done in projects, but may |
| be appropriate for populating content in CMake\(aqs script mode. |
| See \fI\%FetchContent_Populate()\fP for details. |
| .SS Commands |
| .INDENT 0.0 |
| .TP |
| .B FetchContent_Declare |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| FetchContent_Declare(<name> <contentOptions>...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The \fBFetchContent_Declare()\fP function records the options that describe |
| how to populate the specified content. If such details have already |
| been recorded earlier in this project (regardless of where in the project |
| hierarchy), this and all later calls for the same content \fB<name>\fP are |
| ignored. This "first to record, wins" approach is what allows hierarchical |
| projects to have parent projects override content details of child projects. |
| .sp |
| The content \fB<name>\fP can be any string without spaces, but good practice |
| would be to use only letters, numbers and underscores. The name will be |
| treated case\-insensitively and it should be obvious for the content it |
| represents, often being the name of the child project or the value given |
| to its top level \fBproject()\fP command (if it is a CMake project). |
| For well\-known public projects, the name should generally be the official |
| name of the project. Choosing an unusual name makes it unlikely that other |
| projects needing that same content will use the same name, leading to |
| the content being populated multiple times. |
| .sp |
| The \fB<contentOptions>\fP can be any of the download, update or patch options |
| that the \fBExternalProject_Add()\fP command understands. The configure, |
| build, install and test steps are explicitly disabled and therefore options |
| related to them will be ignored. The \fBSOURCE_SUBDIR\fP option is an |
| exception, see \fI\%FetchContent_MakeAvailable()\fP for details on how that |
| affects behavior. |
| .sp |
| In most cases, \fB<contentOptions>\fP will just be a couple of options defining |
| the download method and method\-specific details like a commit tag or archive |
| hash. For example: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| FetchContent_Declare( |
| googletest |
| GIT_REPOSITORY https://github.com/google/googletest.git |
| GIT_TAG 703bd9caab50b139428cea1aaff9974ebee5742e # release\-1.10.0 |
| ) |
| |
| FetchContent_Declare( |
| myCompanyIcons |
| URL https://intranet.mycompany.com/assets/iconset_1.12.tar.gz |
| URL_HASH MD5=5588a7b18261c20068beabfb4f530b87 |
| ) |
| |
| FetchContent_Declare( |
| myCompanyCertificates |
| SVN_REPOSITORY svn+ssh://svn.mycompany.com/srv/svn/trunk/certs |
| SVN_REVISION \-r12345 |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Where contents are being fetched from a remote location and you do not |
| control that server, it is advisable to use a hash for \fBGIT_TAG\fP rather |
| than a branch or tag name. A commit hash is more secure and helps to |
| confirm that the downloaded contents are what you expected. |
| .sp |
| Changed in version 3.14: Commands for the download, update or patch steps can access the terminal. |
| This may be needed for things like password prompts or real\-time display |
| of command progress. |
| |
| .sp |
| New in version 3.22: The \fBCMAKE_TLS_VERIFY\fP, \fBCMAKE_TLS_CAINFO\fP, |
| \fBCMAKE_NETRC\fP and \fBCMAKE_NETRC_FILE\fP variables now |
| provide the defaults for their corresponding content options, just like |
| they do for \fBExternalProject_Add()\fP\&. Previously, these variables |
| were ignored by the \fBFetchContent\fP module. |
| |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B FetchContent_MakeAvailable |
| New in version 3.14. |
| |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| FetchContent_MakeAvailable(<name1> [<name2>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This command ensures that each of the named dependencies are populated and |
| potentially added to the build by the time it returns. It iterates over |
| the list, and for each dependency, the following logic is applied: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| If the dependency has already been populated earlier in this run, set |
| the \fB<lowercaseName>_POPULATED\fP, \fB<lowercaseName>_SOURCE_DIR\fP and |
| \fB<lowercaseName>_BINARY_DIR\fP variables in the same way as a call to |
| \fI\%FetchContent_GetProperties()\fP, then skip the remaining steps |
| below and move on to the next dependency in the list. |
| .IP \(bu 2 |
| Call \fI\%FetchContent_Populate()\fP to populate the dependency using |
| the details recorded by an earlier call to \fI\%FetchContent_Declare()\fP\&. |
| Halt with a fatal error if no such details have been recorded. |
| \fI\%FETCHCONTENT_SOURCE_DIR_<uppercaseName>\fP can be used to override |
| the declared details and use content provided at the specified location |
| instead. |
| .IP \(bu 2 |
| If the top directory of the populated content contains a \fBCMakeLists.txt\fP |
| file, call \fBadd_subdirectory()\fP to add it to the main build. |
| It is not an error for there to be no \fBCMakeLists.txt\fP file, which |
| allows the command to be used for dependencies that make downloaded |
| content available at a known location, but which do not need or support |
| being added directly to the build. |
| .sp |
| New in version 3.18: The \fBSOURCE_SUBDIR\fP option can be given in the declared details to |
| look somewhere below the top directory instead (i.e. the same way that |
| \fBSOURCE_SUBDIR\fP is used by the \fBExternalProject_Add()\fP |
| command). The path provided with \fBSOURCE_SUBDIR\fP must be relative |
| and will be treated as relative to the top directory. It can also |
| point to a directory that does not contain a \fBCMakeLists.txt\fP file |
| or even to a directory that doesn\(aqt exist. This can be used to avoid |
| adding a project that contains a \fBCMakeLists.txt\fP file in its top |
| directory. |
| |
| .UNINDENT |
| .sp |
| Projects should aim to declare the details of all dependencies they might |
| use before they call \fBFetchContent_MakeAvailable()\fP for any of them. |
| This ensures that if any of the dependencies are also sub\-dependencies of |
| one or more of the others, the main project still controls the details |
| that will be used (because it will declare them first before the |
| dependencies get a chance to). In the following code samples, assume that |
| the \fBuses_other\fP dependency also uses \fBFetchContent\fP to add the \fBother\fP |
| dependency internally: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| # WRONG: Should declare all details first |
| FetchContent_Declare(uses_other ...) |
| FetchContent_MakeAvailable(uses_other) |
| |
| FetchContent_Declare(other ...) # Will be ignored, uses_other beat us to it |
| FetchContent_MakeAvailable(other) # Would use details declared by uses_other |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| # CORRECT: All details declared first, so they will take priority |
| FetchContent_Declare(uses_other ...) |
| FetchContent_Declare(other ...) |
| FetchContent_MakeAvailable(uses_other other) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B FetchContent_Populate |
| . |
| \fBNOTE:\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| Where possible, prefer to use \fI\%FetchContent_MakeAvailable()\fP |
| instead of implementing population manually with this command. |
| .UNINDENT |
| .UNINDENT |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| FetchContent_Populate(<name>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| In most cases, the only argument given to \fBFetchContent_Populate()\fP is the |
| \fB<name>\fP\&. When used this way, the command assumes the content details have |
| been recorded by an earlier call to \fI\%FetchContent_Declare()\fP\&. The |
| details are stored in a global property, so they are unaffected by things |
| like variable or directory scope. Therefore, it doesn\(aqt matter where in the |
| project the details were previously declared, as long as they have been |
| declared before the call to \fBFetchContent_Populate()\fP\&. Those saved details |
| are then used to construct a call to \fBExternalProject_Add()\fP in a |
| private sub\-build to perform the content population immediately. The |
| implementation of \fBExternalProject_Add()\fP ensures that if the content has |
| already been populated in a previous CMake run, that content will be reused |
| rather than repopulating them again. For the common case where population |
| involves downloading content, the cost of the download is only paid once. |
| .sp |
| An internal global property records when a particular content population |
| request has been processed. If \fBFetchContent_Populate()\fP is called more |
| than once for the same content name within a configure run, the second call |
| will halt with an error. Projects can and should check whether content |
| population has already been processed with the |
| \fI\%FetchContent_GetProperties()\fP command before calling |
| \fBFetchContent_Populate()\fP\&. |
| .sp |
| \fBFetchContent_Populate()\fP will set three variables in the scope of the |
| caller: |
| .INDENT 7.0 |
| .TP |
| .B \fB<lowercaseName>_POPULATED\fP |
| This will always be set to \fBTRUE\fP by the call. |
| .TP |
| .B \fB<lowercaseName>_SOURCE_DIR\fP |
| The location where the populated content can be found upon return. |
| .TP |
| .B \fB<lowercaseName>_BINARY_DIR\fP |
| A directory intended for use as a corresponding build directory. |
| .UNINDENT |
| .sp |
| The main use case for the \fB<lowercaseName>_SOURCE_DIR\fP and |
| \fB<lowercaseName>_BINARY_DIR\fP variables is to call |
| \fBadd_subdirectory()\fP immediately after population: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| FetchContent_Populate(FooBar) |
| add_subdirectory(${foobar_SOURCE_DIR} ${foobar_BINARY_DIR}) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The values of the three variables can also be retrieved from anywhere in the |
| project hierarchy using the \fI\%FetchContent_GetProperties()\fP command. |
| .sp |
| The \fBFetchContent_Populate()\fP command also supports a syntax allowing the |
| content details to be specified directly rather than using any saved |
| details. This is more low\-level and use of this form is generally to be |
| avoided in favor of using saved content details as outlined above. |
| Nevertheless, in certain situations it can be useful to invoke the content |
| population as an isolated operation (typically as part of implementing some |
| other higher level feature or when using CMake in script mode): |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| FetchContent_Populate( |
| <name> |
| [QUIET] |
| [SUBBUILD_DIR <subBuildDir>] |
| [SOURCE_DIR <srcDir>] |
| [BINARY_DIR <binDir>] |
| ... |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This form has a number of key differences to that where only \fB<name>\fP is |
| provided: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| All required population details are assumed to have been provided directly |
| in the call to \fBFetchContent_Populate()\fP\&. Any saved details for |
| \fB<name>\fP are ignored. |
| .IP \(bu 2 |
| No check is made for whether content for \fB<name>\fP has already been |
| populated. |
| .IP \(bu 2 |
| No global property is set to record that the population has occurred. |
| .IP \(bu 2 |
| No global properties record the source or binary directories used for the |
| populated content. |
| .IP \(bu 2 |
| The \fBFETCHCONTENT_FULLY_DISCONNECTED\fP and |
| \fBFETCHCONTENT_UPDATES_DISCONNECTED\fP cache variables are ignored. |
| .UNINDENT |
| .sp |
| The \fB<lowercaseName>_SOURCE_DIR\fP and \fB<lowercaseName>_BINARY_DIR\fP |
| variables are still returned to the caller, but since these locations are |
| not stored as global properties when this form is used, they are only |
| available to the calling scope and below rather than the entire project |
| hierarchy. No \fB<lowercaseName>_POPULATED\fP variable is set in the caller\(aqs |
| scope with this form. |
| .sp |
| The supported options for \fBFetchContent_Populate()\fP are the same as those |
| for \fI\%FetchContent_Declare()\fP\&. Those few options shown just |
| above are either specific to \fBFetchContent_Populate()\fP or their behavior is |
| slightly modified from how \fBExternalProject_Add()\fP treats them: |
| .INDENT 7.0 |
| .TP |
| .B \fBQUIET\fP |
| The \fBQUIET\fP option can be given to hide the output associated with |
| populating the specified content. If the population fails, the output will |
| be shown regardless of whether this option was given or not so that the |
| cause of the failure can be diagnosed. The global \fBFETCHCONTENT_QUIET\fP |
| cache variable has no effect on \fBFetchContent_Populate()\fP calls where the |
| content details are provided directly. |
| .TP |
| .B \fBSUBBUILD_DIR\fP |
| The \fBSUBBUILD_DIR\fP argument can be provided to change the location of the |
| sub\-build created to perform the population. The default value is |
| \fB${CMAKE_CURRENT_BINARY_DIR}/<lowercaseName>\-subbuild\fP and it would be |
| unusual to need to override this default. If a relative path is specified, |
| it will be interpreted as relative to \fBCMAKE_CURRENT_BINARY_DIR\fP\&. |
| This option should not be confused with the \fBSOURCE_SUBDIR\fP option which |
| only affects the \fI\%FetchContent_MakeAvailable()\fP command. |
| .TP |
| .B \fBSOURCE_DIR\fP, \fBBINARY_DIR\fP |
| The \fBSOURCE_DIR\fP and \fBBINARY_DIR\fP arguments are supported by |
| \fBExternalProject_Add()\fP, but different default values are used by |
| \fBFetchContent_Populate()\fP\&. \fBSOURCE_DIR\fP defaults to |
| \fB${CMAKE_CURRENT_BINARY_DIR}/<lowercaseName>\-src\fP and \fBBINARY_DIR\fP |
| defaults to \fB${CMAKE_CURRENT_BINARY_DIR}/<lowercaseName>\-build\fP\&. |
| If a relative path is specified, it will be interpreted as relative to |
| \fBCMAKE_CURRENT_BINARY_DIR\fP\&. |
| .UNINDENT |
| .sp |
| In addition to the above explicit options, any other unrecognized options are |
| passed through unmodified to \fBExternalProject_Add()\fP to perform the |
| download, patch and update steps. The following options are explicitly |
| prohibited (they are disabled by the \fBFetchContent_Populate()\fP command): |
| .INDENT 7.0 |
| .IP \(bu 2 |
| \fBCONFIGURE_COMMAND\fP |
| .IP \(bu 2 |
| \fBBUILD_COMMAND\fP |
| .IP \(bu 2 |
| \fBINSTALL_COMMAND\fP |
| .IP \(bu 2 |
| \fBTEST_COMMAND\fP |
| .UNINDENT |
| .sp |
| If using \fBFetchContent_Populate()\fP within CMake\(aqs script mode, be aware |
| that the implementation sets up a sub\-build which therefore requires a CMake |
| generator and build tool to be available. If these cannot be found by |
| default, then the \fBCMAKE_GENERATOR\fP and/or |
| \fBCMAKE_MAKE_PROGRAM\fP variables will need to be set appropriately |
| on the command line invoking the script. |
| .sp |
| New in version 3.18: Added support for the \fBDOWNLOAD_NO_EXTRACT\fP option. |
| |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B FetchContent_GetProperties |
| When using saved content details, a call to |
| \fI\%FetchContent_MakeAvailable()\fP or \fI\%FetchContent_Populate()\fP |
| records information in global properties which can be queried at any time. |
| This information includes the source and binary directories associated with |
| the content and also whether or not the content population has been processed |
| during the current configure run. |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| FetchContent_GetProperties( |
| <name> |
| [SOURCE_DIR <srcDirVar>] |
| [BINARY_DIR <binDirVar>] |
| [POPULATED <doneVar>] |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The \fBSOURCE_DIR\fP, \fBBINARY_DIR\fP and \fBPOPULATED\fP options can be used to |
| specify which properties should be retrieved. Each option accepts a value |
| which is the name of the variable in which to store that property. Most of |
| the time though, only \fB<name>\fP is given, in which case the call will then |
| set the same variables as a call to |
| \fI\%FetchContent_MakeAvailable(name)\fP or |
| \fI\%FetchContent_Populate(name)\fP\&. |
| .sp |
| This command is rarely needed when using |
| \fI\%FetchContent_MakeAvailable()\fP\&. It is more commonly used as part of |
| implementing the following pattern with \fI\%FetchContent_Populate()\fP, |
| which ensures that the relevant variables will always be defined regardless |
| of whether or not the population has been performed elsewhere in the project |
| already: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| # Check if population has already been performed |
| FetchContent_GetProperties(depname) |
| if(NOT depname_POPULATED) |
| # Fetch the content using previously declared details |
| FetchContent_Populate(depname) |
| |
| # Set custom variables, policies, etc. |
| # ... |
| |
| # Bring the populated content into the build |
| add_subdirectory(${depname_SOURCE_DIR} ${depname_BINARY_DIR}) |
| endif() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .SS Variables |
| .sp |
| A number of cache variables can influence the behavior where details from a |
| \fI\%FetchContent_Declare()\fP call are used to populate content. |
| The variables are all intended for the developer to customize behavior and |
| should not normally be set by the project. |
| .INDENT 0.0 |
| .TP |
| .B FETCHCONTENT_BASE_DIR |
| In most cases, the saved details do not specify any options relating to the |
| directories to use for the internal sub\-build, final source and build areas. |
| It is generally best to leave these decisions up to the \fBFetchContent\fP |
| module to handle on the project\(aqs behalf. The \fBFETCHCONTENT_BASE_DIR\fP |
| cache variable controls the point under which all content population |
| directories are collected, but in most cases, developers would not need to |
| change this. The default location is \fB${CMAKE_BINARY_DIR}/_deps\fP, but if |
| developers change this value, they should aim to keep the path short and |
| just below the top level of the build tree to avoid running into path |
| length problems on Windows. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B FETCHCONTENT_QUIET |
| The logging output during population can be quite verbose, making the |
| configure stage quite noisy. This cache option (\fBON\fP by default) hides |
| all population output unless an error is encountered. If experiencing |
| problems with hung downloads, temporarily switching this option off may |
| help diagnose which content population is causing the issue. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B FETCHCONTENT_FULLY_DISCONNECTED |
| When this option is enabled, no attempt is made to download or update |
| any content. It is assumed that all content has already been populated in |
| a previous run or the source directories have been pointed at existing |
| contents the developer has provided manually (using options described |
| further below). When the developer knows that no changes have been made to |
| any content details, turning this option \fBON\fP can significantly speed up |
| the configure stage. It is \fBOFF\fP by default. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B FETCHCONTENT_UPDATES_DISCONNECTED |
| This is a less severe download/update control compared to |
| \fI\%FETCHCONTENT_FULLY_DISCONNECTED\fP\&. Instead of bypassing all |
| download and update logic, \fBFETCHCONTENT_UPDATES_DISCONNECTED\fP only |
| disables the update stage. Therefore, if content has not been downloaded |
| previously, it will still be downloaded when this option is enabled. |
| This can speed up the configure stage, but not as much as |
| \fI\%FETCHCONTENT_FULLY_DISCONNECTED\fP\&. It is \fBOFF\fP by default. |
| .UNINDENT |
| .sp |
| In addition to the above cache variables, the following cache variables are |
| also defined for each content name: |
| .INDENT 0.0 |
| .TP |
| .B FETCHCONTENT_SOURCE_DIR_<uppercaseName> |
| If this is set, no download or update steps are performed for the specified |
| content and the \fB<lowercaseName>_SOURCE_DIR\fP variable returned to the |
| caller is pointed at this location. This gives developers a way to have a |
| separate checkout of the content that they can modify freely without |
| interference from the build. The build simply uses that existing source, |
| but it still defines \fB<lowercaseName>_BINARY_DIR\fP to point inside its own |
| build area. Developers are strongly encouraged to use this mechanism rather |
| than editing the sources populated in the default location, as changes to |
| sources in the default location can be lost when content population details |
| are changed by the project. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B FETCHCONTENT_UPDATES_DISCONNECTED_<uppercaseName> |
| This is the per\-content equivalent of |
| \fI\%FETCHCONTENT_UPDATES_DISCONNECTED\fP\&. If the global option or |
| this option is \fBON\fP, then updates will be disabled for the named content. |
| Disabling updates for individual content can be useful for content whose |
| details rarely change, while still leaving other frequently changing content |
| with updates enabled. |
| .UNINDENT |
| .SS Examples |
| .sp |
| This first fairly straightforward example ensures that some popular testing |
| frameworks are available to the main build: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| include(FetchContent) |
| FetchContent_Declare( |
| googletest |
| GIT_REPOSITORY https://github.com/google/googletest.git |
| GIT_TAG 703bd9caab50b139428cea1aaff9974ebee5742e # release\-1.10.0 |
| ) |
| FetchContent_Declare( |
| Catch2 |
| GIT_REPOSITORY https://github.com/catchorg/Catch2.git |
| GIT_TAG de6fe184a9ac1a06895cdd1c9b437f0a0bdf14ad # v2.13.4 |
| ) |
| |
| # After the following call, the CMake targets defined by googletest and |
| # Catch2 will be available to the rest of the build |
| FetchContent_MakeAvailable(googletest Catch2) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| If the sub\-project\(aqs \fBCMakeLists.txt\fP file is not at the top level of its |
| source tree, the \fBSOURCE_SUBDIR\fP option can be used to tell \fBFetchContent\fP |
| where to find it. The following example shows how to use that option and |
| it also sets a variable which is meaningful to the subproject before pulling |
| it into the main build: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| include(FetchContent) |
| FetchContent_Declare( |
| protobuf |
| GIT_REPOSITORY https://github.com/protocolbuffers/protobuf.git |
| GIT_TAG ae50d9b9902526efd6c7a1907d09739f959c6297 # v3.15.0 |
| SOURCE_SUBDIR cmake |
| ) |
| set(protobuf_BUILD_TESTS OFF) |
| FetchContent_MakeAvailable(protobuf) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| In more complex project hierarchies, the dependency relationships can be more |
| complicated. Consider a hierarchy where \fBprojA\fP is the top level project and |
| it depends directly on projects \fBprojB\fP and \fBprojC\fP\&. Both \fBprojB\fP and |
| \fBprojC\fP can be built standalone and they also both depend on another project |
| \fBprojD\fP\&. \fBprojB\fP additionally depends on \fBprojE\fP\&. This example assumes |
| that all five projects are available on a company git server. The |
| \fBCMakeLists.txt\fP of each project might have sections like the following: |
| .sp |
| \fIprojA\fP: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| include(FetchContent) |
| FetchContent_Declare( |
| projB |
| GIT_REPOSITORY git@mycompany.com:git/projB.git |
| GIT_TAG 4a89dc7e24ff212a7b5167bef7ab079d |
| ) |
| FetchContent_Declare( |
| projC |
| GIT_REPOSITORY git@mycompany.com:git/projC.git |
| GIT_TAG 4ad4016bd1d8d5412d135cf8ceea1bb9 |
| ) |
| FetchContent_Declare( |
| projD |
| GIT_REPOSITORY git@mycompany.com:git/projD.git |
| GIT_TAG origin/integrationBranch |
| ) |
| FetchContent_Declare( |
| projE |
| GIT_REPOSITORY git@mycompany.com:git/projE.git |
| GIT_TAG v2.3\-rc1 |
| ) |
| |
| # Order is important, see notes in the discussion further below |
| FetchContent_MakeAvailable(projD projB projC) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fIprojB\fP: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| include(FetchContent) |
| FetchContent_Declare( |
| projD |
| GIT_REPOSITORY git@mycompany.com:git/projD.git |
| GIT_TAG 20b415f9034bbd2a2e8216e9a5c9e632 |
| ) |
| FetchContent_Declare( |
| projE |
| GIT_REPOSITORY git@mycompany.com:git/projE.git |
| GIT_TAG 68e20f674a48be38d60e129f600faf7d |
| ) |
| |
| FetchContent_MakeAvailable(projD projE) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fIprojC\fP: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| include(FetchContent) |
| FetchContent_Declare( |
| projD |
| GIT_REPOSITORY git@mycompany.com:git/projD.git |
| GIT_TAG 7d9a17ad2c962aa13e2fbb8043fb6b8a |
| ) |
| |
| # This particular version of projD requires workarounds |
| FetchContent_GetProperties(projD) |
| if(NOT projd_POPULATED) |
| FetchContent_Populate(projD) |
| |
| # Copy an additional/replacement file into the populated source |
| file(COPY someFile.c DESTINATION ${projd_SOURCE_DIR}/src) |
| |
| add_subdirectory(${projd_SOURCE_DIR} ${projd_BINARY_DIR}) |
| endif() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| A few key points should be noted in the above: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBprojB\fP and \fBprojC\fP define different content details for \fBprojD\fP, |
| but \fBprojA\fP also defines a set of content details for \fBprojD\fP\&. |
| Because \fBprojA\fP will define them first, the details from \fBprojB\fP and |
| \fBprojC\fP will not be used. The override details defined by \fBprojA\fP |
| are not required to match either of those from \fBprojB\fP or \fBprojC\fP, but |
| it is up to the higher level project to ensure that the details it does |
| define still make sense for the child projects. |
| .IP \(bu 2 |
| In the \fBprojA\fP call to \fI\%FetchContent_MakeAvailable()\fP, \fBprojD\fP |
| is listed ahead of \fBprojB\fP and \fBprojC\fP to ensure that \fBprojA\fP is in |
| control of how \fBprojD\fP is populated. |
| .IP \(bu 2 |
| While \fBprojA\fP defines content details for \fBprojE\fP, it does not need |
| to explicitly call \fBFetchContent_MakeAvailable(projE)\fP or |
| \fBFetchContent_Populate(projD)\fP itself. Instead, it leaves that to the |
| child \fBprojB\fP\&. For higher level projects, it is often enough to just |
| define the override content details and leave the actual population to the |
| child projects. This saves repeating the same thing at each level of the |
| project hierarchy unnecessarily. |
| .UNINDENT |
| .sp |
| Projects don\(aqt always need to add the populated content to the build. |
| Sometimes the project just wants to make the downloaded content available at |
| a predictable location. The next example ensures that a set of standard |
| company toolchain files (and potentially even the toolchain binaries |
| themselves) is available early enough to be used for that same build. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cmake_minimum_required(VERSION 3.14) |
| |
| include(FetchContent) |
| FetchContent_Declare( |
| mycom_toolchains |
| URL https://intranet.mycompany.com//toolchains_1.3.2.tar.gz |
| ) |
| FetchContent_MakeAvailable(mycom_toolchains) |
| |
| project(CrossCompileExample) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The project could be configured to use one of the downloaded toolchains like |
| so: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cmake \-DCMAKE_TOOLCHAIN_FILE=_deps/mycom_toolchains\-src/toolchain_arm.cmake /path/to/src |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| When CMake processes the \fBCMakeLists.txt\fP file, it will download and unpack |
| the tarball into \fB_deps/mycompany_toolchains\-src\fP relative to the build |
| directory. The \fBCMAKE_TOOLCHAIN_FILE\fP variable is not used until |
| the \fBproject()\fP command is reached, at which point CMake looks for the |
| named toolchain file relative to the build directory. Because the tarball has |
| already been downloaded and unpacked by then, the toolchain file will be in |
| place, even the very first time that \fBcmake\fP is run in the build directory. |
| .sp |
| Lastly, the following example demonstrates how one might download and unpack a |
| firmware tarball using CMake\(aqs \fBscript mode\fP\&. The call to |
| \fI\%FetchContent_Populate()\fP specifies all the content details and the |
| unpacked firmware will be placed in a \fBfirmware\fP directory below the |
| current working directory. |
| .sp |
| \fIgetFirmware.cmake\fP: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| # NOTE: Intended to be run in script mode with cmake \-P |
| include(FetchContent) |
| FetchContent_Populate( |
| firmware |
| URL https://mycompany.com/assets/firmware\-1.23\-arm.tar.gz |
| URL_HASH MD5=68247684da89b608d466253762b0ff11 |
| SOURCE_DIR firmware |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindPackageHandleStandardArgs |
| .sp |
| This module provides functions intended to be used in Find Modules |
| implementing \fBfind_package(<PackageName>)\fP calls. |
| .INDENT 0.0 |
| .TP |
| .B find_package_handle_standard_args |
| This command handles the \fBREQUIRED\fP, \fBQUIET\fP and version\-related |
| arguments of \fBfind_package()\fP\&. It also sets the |
| \fB<PackageName>_FOUND\fP variable. The package is considered found if all |
| variables listed contain valid results, e.g. valid filepaths. |
| .sp |
| There are two signatures: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_package_handle_standard_args(<PackageName> |
| (DEFAULT_MSG|<custom\-failure\-message>) |
| <required\-var>... |
| ) |
| |
| find_package_handle_standard_args(<PackageName> |
| [FOUND_VAR <result\-var>] |
| [REQUIRED_VARS <required\-var>...] |
| [VERSION_VAR <version\-var>] |
| [HANDLE_VERSION_RANGE] |
| [HANDLE_COMPONENTS] |
| [CONFIG_MODE] |
| [NAME_MISMATCHED] |
| [REASON_FAILURE_MESSAGE <reason\-failure\-message>] |
| [FAIL_MESSAGE <custom\-failure\-message>] |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The \fB<PackageName>_FOUND\fP variable will be set to \fBTRUE\fP if all |
| the variables \fB<required\-var>...\fP are valid and any optional |
| constraints are satisfied, and \fBFALSE\fP otherwise. A success or |
| failure message may be displayed based on the results and on |
| whether the \fBREQUIRED\fP and/or \fBQUIET\fP option was given to |
| the \fBfind_package()\fP call. |
| .sp |
| The options are: |
| .INDENT 7.0 |
| .TP |
| .B \fB(DEFAULT_MSG|<custom\-failure\-message>)\fP |
| In the simple signature this specifies the failure message. |
| Use \fBDEFAULT_MSG\fP to ask for a default message to be computed |
| (recommended). Not valid in the full signature. |
| .TP |
| .B \fBFOUND_VAR <result\-var>\fP |
| Deprecated since version 3.3. |
| |
| .sp |
| Specifies either \fB<PackageName>_FOUND\fP or |
| \fB<PACKAGENAME>_FOUND\fP as the result variable. This exists only |
| for compatibility with older versions of CMake and is now ignored. |
| Result variables of both names are always set for compatibility. |
| .TP |
| .B \fBREQUIRED_VARS <required\-var>...\fP |
| Specify the variables which are required for this package. |
| These may be named in the generated failure message asking the |
| user to set the missing variable values. Therefore these should |
| typically be cache entries such as \fBFOO_LIBRARY\fP and not output |
| variables like \fBFOO_LIBRARIES\fP\&. |
| .sp |
| Changed in version 3.18: If \fBHANDLE_COMPONENTS\fP is specified, this option can be omitted. |
| |
| .TP |
| .B \fBVERSION_VAR <version\-var>\fP |
| Specify the name of a variable that holds the version of the package |
| that has been found. This version will be checked against the |
| (potentially) specified required version given to the |
| \fBfind_package()\fP call, including its \fBEXACT\fP option. |
| The default messages include information about the required |
| version and the version which has been actually found, both |
| if the version is ok or not. |
| .TP |
| .B \fBHANDLE_VERSION_RANGE\fP |
| New in version 3.19. |
| |
| .sp |
| Enable handling of a version range, if one is specified. Without this |
| option, a developer warning will be displayed if a version range is |
| specified. |
| .TP |
| .B \fBHANDLE_COMPONENTS\fP |
| Enable handling of package components. In this case, the command |
| will report which components have been found and which are missing, |
| and the \fB<PackageName>_FOUND\fP variable will be set to \fBFALSE\fP |
| if any of the required components (i.e. not the ones listed after |
| the \fBOPTIONAL_COMPONENTS\fP option of \fBfind_package()\fP) are |
| missing. |
| .TP |
| .B \fBCONFIG_MODE\fP |
| Specify that the calling find module is a wrapper around a |
| call to \fBfind_package(<PackageName> NO_MODULE)\fP\&. This implies |
| a \fBVERSION_VAR\fP value of \fB<PackageName>_VERSION\fP\&. The command |
| will automatically check whether the package configuration file |
| was found. |
| .TP |
| .B \fBREASON_FAILURE_MESSAGE <reason\-failure\-message>\fP |
| New in version 3.16. |
| |
| .sp |
| Specify a custom message of the reason for the failure which will be |
| appended to the default generated message. |
| .TP |
| .B \fBFAIL_MESSAGE <custom\-failure\-message>\fP |
| Specify a custom failure message instead of using the default |
| generated message. Not recommended. |
| .TP |
| .B \fBNAME_MISMATCHED\fP |
| New in version 3.17. |
| |
| .sp |
| Indicate that the \fB<PackageName>\fP does not match |
| \fB${CMAKE_FIND_PACKAGE_NAME}\fP\&. This is usually a mistake and raises a |
| warning, but it may be intentional for usage of the command for components |
| of a larger package. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Example for the simple signature: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_package_handle_standard_args(LibXml2 DEFAULT_MSG |
| LIBXML2_LIBRARY LIBXML2_INCLUDE_DIR) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The \fBLibXml2\fP package is considered to be found if both |
| \fBLIBXML2_LIBRARY\fP and \fBLIBXML2_INCLUDE_DIR\fP are valid. |
| Then also \fBLibXml2_FOUND\fP is set to \fBTRUE\fP\&. If it is not found |
| and \fBREQUIRED\fP was used, it fails with a |
| \fBmessage(FATAL_ERROR)\fP, independent whether \fBQUIET\fP was |
| used or not. If it is found, success will be reported, including |
| the content of the first \fB<required\-var>\fP\&. On repeated CMake runs, |
| the same message will not be printed again. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| If \fB<PackageName>\fP does not match \fBCMAKE_FIND_PACKAGE_NAME\fP for the |
| calling module, a warning that there is a mismatch is given. The |
| \fBFPHSA_NAME_MISMATCHED\fP variable may be set to bypass the warning if using |
| the old signature and the \fBNAME_MISMATCHED\fP argument using the new |
| signature. To avoid forcing the caller to require newer versions of CMake for |
| usage, the variable\(aqs value will be used if defined when the |
| \fBNAME_MISMATCHED\fP argument is not passed for the new signature (but using |
| both is an error).. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Example for the full signature: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_package_handle_standard_args(LibArchive |
| REQUIRED_VARS LibArchive_LIBRARY LibArchive_INCLUDE_DIR |
| VERSION_VAR LibArchive_VERSION) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| In this case, the \fBLibArchive\fP package is considered to be found if |
| both \fBLibArchive_LIBRARY\fP and \fBLibArchive_INCLUDE_DIR\fP are valid. |
| Also the version of \fBLibArchive\fP will be checked by using the version |
| contained in \fBLibArchive_VERSION\fP\&. Since no \fBFAIL_MESSAGE\fP is given, |
| the default messages will be printed. |
| .sp |
| Another example for the full signature: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_package(Automoc4 QUIET NO_MODULE HINTS /opt/automoc4) |
| find_package_handle_standard_args(Automoc4 CONFIG_MODE) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| In this case, a \fBFindAutmoc4.cmake\fP module wraps a call to |
| \fBfind_package(Automoc4 NO_MODULE)\fP and adds an additional search |
| directory for \fBautomoc4\fP\&. Then the call to |
| \fBfind_package_handle_standard_args\fP produces a proper success/failure |
| message. |
| .INDENT 0.0 |
| .TP |
| .B find_package_check_version |
| New in version 3.19. |
| |
| .sp |
| Helper function which can be used to check if a \fB<version>\fP is valid |
| against version\-related arguments of \fBfind_package()\fP\&. |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_package_check_version(<version> <result\-var> |
| [HANDLE_VERSION_RANGE] |
| [RESULT_MESSAGE_VARIABLE <message\-var>] |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The \fB<result\-var>\fP will hold a boolean value giving the result of the check. |
| .sp |
| The options are: |
| .INDENT 7.0 |
| .TP |
| .B \fBHANDLE_VERSION_RANGE\fP |
| Enable handling of a version range, if one is specified. Without this |
| option, a developer warning will be displayed if a version range is |
| specified. |
| .TP |
| .B \fBRESULT_MESSAGE_VARIABLE <message\-var>\fP |
| Specify a variable to get back a message describing the result of the check. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Example for the usage: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_package_check_version(1.2.3 result HANDLE_VERSION_RANGE |
| RESULT_MESSAGE_VARIABLE reason) |
| if (result) |
| message (STATUS "${reason}") |
| else() |
| message (FATAL_ERROR "${reason}") |
| endif() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindPackageMessage |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_package_message(<name> "message for user" "find result details") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This function is intended to be used in FindXXX.cmake modules files. |
| It will print a message once for each unique find result. This is |
| useful for telling the user where a package was found. The first |
| argument specifies the name (XXX) of the package. The second argument |
| specifies the message to display. The third argument lists details |
| about the find result so that if they change the message will be |
| displayed again. The macro also obeys the QUIET argument to the |
| find_package command. |
| .sp |
| Example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| if(X11_FOUND) |
| find_package_message(X11 "Found X11: ${X11_X11_LIB}" |
| "[${X11_X11_LIB}][${X11_INCLUDE_DIR}]") |
| else() |
| ... |
| endif() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FortranCInterface |
| .sp |
| Fortran/C Interface Detection |
| .sp |
| This module automatically detects the API by which C and Fortran |
| languages interact. |
| .SS Module Variables |
| .sp |
| Variables that indicate if the mangling is found: |
| .INDENT 0.0 |
| .TP |
| .B \fBFortranCInterface_GLOBAL_FOUND\fP |
| Global subroutines and functions. |
| .TP |
| .B \fBFortranCInterface_MODULE_FOUND\fP |
| Module subroutines and functions (declared by "MODULE PROCEDURE"). |
| .UNINDENT |
| .sp |
| This module also provides the following variables to specify |
| the detected mangling, though a typical use case does not need |
| to reference them and can use the \fI\%Module Functions\fP below. |
| .INDENT 0.0 |
| .TP |
| .B \fBFortranCInterface_GLOBAL_PREFIX\fP |
| Prefix for a global symbol without an underscore. |
| .TP |
| .B \fBFortranCInterface_GLOBAL_SUFFIX\fP |
| Suffix for a global symbol without an underscore. |
| .TP |
| .B \fBFortranCInterface_GLOBAL_CASE\fP |
| The case for a global symbol without an underscore, |
| either \fBUPPER\fP or \fBLOWER\fP\&. |
| .TP |
| .B \fBFortranCInterface_GLOBAL__PREFIX\fP |
| Prefix for a global symbol with an underscore. |
| .TP |
| .B \fBFortranCInterface_GLOBAL__SUFFIX\fP |
| Suffix for a global symbol with an underscore. |
| .TP |
| .B \fBFortranCInterface_GLOBAL__CASE\fP |
| The case for a global symbol with an underscore, |
| either \fBUPPER\fP or \fBLOWER\fP\&. |
| .TP |
| .B \fBFortranCInterface_MODULE_PREFIX\fP |
| Prefix for a module symbol without an underscore. |
| .TP |
| .B \fBFortranCInterface_MODULE_MIDDLE\fP |
| Middle of a module symbol without an underscore that appears |
| between the name of the module and the name of the symbol. |
| .TP |
| .B \fBFortranCInterface_MODULE_SUFFIX\fP |
| Suffix for a module symbol without an underscore. |
| .TP |
| .B \fBFortranCInterface_MODULE_CASE\fP |
| The case for a module symbol without an underscore, |
| either \fBUPPER\fP or \fBLOWER\fP\&. |
| .TP |
| .B \fBFortranCInterface_MODULE__PREFIX\fP |
| Prefix for a module symbol with an underscore. |
| .TP |
| .B \fBFortranCInterface_MODULE__MIDDLE\fP |
| Middle of a module symbol with an underscore that appears |
| between the name of the module and the name of the symbol. |
| .TP |
| .B \fBFortranCInterface_MODULE__SUFFIX\fP |
| Suffix for a module symbol with an underscore. |
| .TP |
| .B \fBFortranCInterface_MODULE__CASE\fP |
| The case for a module symbol with an underscore, |
| either \fBUPPER\fP or \fBLOWER\fP\&. |
| .UNINDENT |
| .SS Module Functions |
| .INDENT 0.0 |
| .TP |
| .B FortranCInterface_HEADER |
| The \fBFortranCInterface_HEADER\fP function is provided to generate a |
| C header file containing macros to mangle symbol names: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| FortranCInterface_HEADER(<file> |
| [MACRO_NAMESPACE <macro\-ns>] |
| [SYMBOL_NAMESPACE <ns>] |
| [SYMBOLS [<module>:]<function> ...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| It generates in \fB<file>\fP definitions of the following macros: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| #define FortranCInterface_GLOBAL (name,NAME) ... |
| #define FortranCInterface_GLOBAL_(name,NAME) ... |
| #define FortranCInterface_MODULE (mod,name, MOD,NAME) ... |
| #define FortranCInterface_MODULE_(mod,name, MOD,NAME) ... |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| These macros mangle four categories of Fortran symbols, respectively: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| Global symbols without \(aq_\(aq: \fBcall mysub()\fP |
| .IP \(bu 2 |
| Global symbols with \(aq_\(aq : \fBcall my_sub()\fP |
| .IP \(bu 2 |
| Module symbols without \(aq_\(aq: \fBuse mymod; call mysub()\fP |
| .IP \(bu 2 |
| Module symbols with \(aq_\(aq : \fBuse mymod; call my_sub()\fP |
| .UNINDENT |
| .sp |
| If mangling for a category is not known, its macro is left undefined. |
| All macros require raw names in both lower case and upper case. |
| .sp |
| The options are: |
| .INDENT 7.0 |
| .TP |
| .B \fBMACRO_NAMESPACE\fP |
| Replace the default \fBFortranCInterface_\fP prefix with a given |
| namespace \fB<macro\-ns>\fP\&. |
| .TP |
| .B \fBSYMBOLS\fP |
| List symbols to mangle automatically with C preprocessor definitions: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| <function> ==> #define <ns><function> ... |
| <module>:<function> ==> #define <ns><module>_<function> ... |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| If the mangling for some symbol is not known then no preprocessor |
| definition is created, and a warning is displayed. |
| .TP |
| .B \fBSYMBOL_NAMESPACE\fP |
| Prefix all preprocessor definitions generated by the \fBSYMBOLS\fP |
| option with a given namespace \fB<ns>\fP\&. |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B FortranCInterface_VERIFY |
| The \fBFortranCInterface_VERIFY\fP function is provided to verify |
| that the Fortran and C/C++ compilers work together: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| FortranCInterface_VERIFY([CXX] [QUIET]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| It tests whether a simple test executable using Fortran and C (and C++ |
| when the CXX option is given) compiles and links successfully. The |
| result is stored in the cache entry \fBFortranCInterface_VERIFIED_C\fP |
| (or \fBFortranCInterface_VERIFIED_CXX\fP if \fBCXX\fP is given) as a boolean. |
| If the check fails and \fBQUIET\fP is not given the function terminates with a |
| fatal error message describing the problem. The purpose of this check |
| is to stop a build early for incompatible compiler combinations. The |
| test is built in the \fBRelease\fP configuration. |
| .UNINDENT |
| .SS Example Usage |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| include(FortranCInterface) |
| FortranCInterface_HEADER(FC.h MACRO_NAMESPACE "FC_") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This creates a "FC.h" header that defines mangling macros \fBFC_GLOBAL()\fP, |
| \fBFC_GLOBAL_()\fP, \fBFC_MODULE()\fP, and \fBFC_MODULE_()\fP\&. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| include(FortranCInterface) |
| FortranCInterface_HEADER(FCMangle.h |
| MACRO_NAMESPACE "FC_" |
| SYMBOL_NAMESPACE "FC_" |
| SYMBOLS mysub mymod:my_sub) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This creates a "FCMangle.h" header that defines the same \fBFC_*()\fP |
| mangling macros as the previous example plus preprocessor symbols |
| \fBFC_mysub\fP and \fBFC_mymod_my_sub\fP\&. |
| .SS Additional Manglings |
| .sp |
| FortranCInterface is aware of possible \fBGLOBAL\fP and \fBMODULE\fP manglings |
| for many Fortran compilers, but it also provides an interface to specify |
| new possible manglings. Set the variables: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| FortranCInterface_GLOBAL_SYMBOLS |
| FortranCInterface_MODULE_SYMBOLS |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| before including FortranCInterface to specify manglings of the symbols |
| \fBMySub\fP, \fBMy_Sub\fP, \fBMyModule:MySub\fP, and \fBMy_Module:My_Sub\fP\&. |
| For example, the code: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(FortranCInterface_GLOBAL_SYMBOLS mysub_ my_sub__ MYSUB_) |
| # ^^^^^ ^^^^^^ ^^^^^ |
| set(FortranCInterface_MODULE_SYMBOLS |
| __mymodule_MOD_mysub __my_module_MOD_my_sub) |
| # ^^^^^^^^ ^^^^^ ^^^^^^^^^ ^^^^^^ |
| include(FortranCInterface) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| tells FortranCInterface to try given \fBGLOBAL\fP and \fBMODULE\fP manglings. |
| (The carets point at raw symbol names for clarity in this example but |
| are not needed.) |
| .SS GenerateExportHeader |
| .sp |
| Function for generation of export macros for libraries |
| .sp |
| This module provides the function \fBGENERATE_EXPORT_HEADER()\fP\&. |
| .sp |
| New in version 3.12: Added support for C projects. Previous versions supported C++ project only. |
| |
| .sp |
| The \fBGENERATE_EXPORT_HEADER\fP function can be used to generate a file |
| suitable for preprocessor inclusion which contains EXPORT macros to be |
| used in library classes: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| GENERATE_EXPORT_HEADER( LIBRARY_TARGET |
| [BASE_NAME <base_name>] |
| [EXPORT_MACRO_NAME <export_macro_name>] |
| [EXPORT_FILE_NAME <export_file_name>] |
| [DEPRECATED_MACRO_NAME <deprecated_macro_name>] |
| [NO_EXPORT_MACRO_NAME <no_export_macro_name>] |
| [INCLUDE_GUARD_NAME <include_guard_name>] |
| [STATIC_DEFINE <static_define>] |
| [NO_DEPRECATED_MACRO_NAME <no_deprecated_macro_name>] |
| [DEFINE_NO_DEPRECATED] |
| [PREFIX_NAME <prefix_name>] |
| [CUSTOM_CONTENT_FROM_VARIABLE <variable>] |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The target properties \fBCXX_VISIBILITY_PRESET\fP |
| and \fBVISIBILITY_INLINES_HIDDEN\fP can be used to add the appropriate |
| compile flags for targets. See the documentation of those target properties, |
| and the convenience variables |
| \fBCMAKE_CXX_VISIBILITY_PRESET\fP and |
| \fBCMAKE_VISIBILITY_INLINES_HIDDEN\fP\&. |
| .sp |
| By default \fBGENERATE_EXPORT_HEADER()\fP generates macro names in a file |
| name determined by the name of the library. This means that in the |
| simplest case, users of \fBGenerateExportHeader\fP will be equivalent to: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(CMAKE_CXX_VISIBILITY_PRESET hidden) |
| set(CMAKE_VISIBILITY_INLINES_HIDDEN 1) |
| add_library(somelib someclass.cpp) |
| generate_export_header(somelib) |
| install(TARGETS somelib DESTINATION ${LIBRARY_INSTALL_DIR}) |
| install(FILES |
| someclass.h |
| ${PROJECT_BINARY_DIR}/somelib_export.h DESTINATION ${INCLUDE_INSTALL_DIR} |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| And in the ABI header files: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| #include "somelib_export.h" |
| class SOMELIB_EXPORT SomeClass { |
| ... |
| }; |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The CMake fragment will generate a file in the |
| \fB${CMAKE_CURRENT_BINARY_DIR}\fP called \fBsomelib_export.h\fP containing the |
| macros \fBSOMELIB_EXPORT\fP, \fBSOMELIB_NO_EXPORT\fP, \fBSOMELIB_DEPRECATED\fP, |
| \fBSOMELIB_DEPRECATED_EXPORT\fP and \fBSOMELIB_DEPRECATED_NO_EXPORT\fP\&. |
| They will be followed by content taken from the variable specified by |
| the \fBCUSTOM_CONTENT_FROM_VARIABLE\fP option, if any. |
| The resulting file should be installed with other headers in the library. |
| .sp |
| The \fBBASE_NAME\fP argument can be used to override the file name and the |
| names used for the macros: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_library(somelib someclass.cpp) |
| generate_export_header(somelib |
| BASE_NAME other_name |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Generates a file called \fBother_name_export.h\fP containing the macros |
| \fBOTHER_NAME_EXPORT\fP, \fBOTHER_NAME_NO_EXPORT\fP and \fBOTHER_NAME_DEPRECATED\fP |
| etc. |
| .sp |
| The \fBBASE_NAME\fP may be overridden by specifying other options in the |
| function. For example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_library(somelib someclass.cpp) |
| generate_export_header(somelib |
| EXPORT_MACRO_NAME OTHER_NAME_EXPORT |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| creates the macro \fBOTHER_NAME_EXPORT\fP instead of \fBSOMELIB_EXPORT\fP, but |
| other macros and the generated file name is as default: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_library(somelib someclass.cpp) |
| generate_export_header(somelib |
| DEPRECATED_MACRO_NAME KDE_DEPRECATED |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| creates the macro \fBKDE_DEPRECATED\fP instead of \fBSOMELIB_DEPRECATED\fP\&. |
| .sp |
| If \fBLIBRARY_TARGET\fP is a static library, macros are defined without |
| values. |
| .sp |
| If the same sources are used to create both a shared and a static |
| library, the uppercased symbol \fB${BASE_NAME}_STATIC_DEFINE\fP should be |
| used when building the static library: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_library(shared_variant SHARED ${lib_SRCS}) |
| add_library(static_variant ${lib_SRCS}) |
| generate_export_header(shared_variant BASE_NAME libshared_and_static) |
| set_target_properties(static_variant PROPERTIES |
| COMPILE_FLAGS \-DLIBSHARED_AND_STATIC_STATIC_DEFINE) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This will cause the export macros to expand to nothing when building |
| the static library. |
| .sp |
| If \fBDEFINE_NO_DEPRECATED\fP is specified, then a macro |
| \fB${BASE_NAME}_NO_DEPRECATED\fP will be defined This macro can be used to |
| remove deprecated code from preprocessor output: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| option(EXCLUDE_DEPRECATED "Exclude deprecated parts of the library" FALSE) |
| if (EXCLUDE_DEPRECATED) |
| set(NO_BUILD_DEPRECATED DEFINE_NO_DEPRECATED) |
| endif() |
| generate_export_header(somelib ${NO_BUILD_DEPRECATED}) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| And then in somelib: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| class SOMELIB_EXPORT SomeClass |
| { |
| public: |
| #ifndef SOMELIB_NO_DEPRECATED |
| SOMELIB_DEPRECATED void oldMethod(); |
| #endif |
| }; |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| #ifndef SOMELIB_NO_DEPRECATED |
| void SomeClass::oldMethod() { } |
| #endif |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| If \fBPREFIX_NAME\fP is specified, the argument will be used as a prefix to |
| all generated macros. |
| .sp |
| For example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| generate_export_header(somelib PREFIX_NAME VTK_) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Generates the macros \fBVTK_SOMELIB_EXPORT\fP etc. |
| .sp |
| New in version 3.1: Library target can be an \fBOBJECT\fP library. |
| |
| .sp |
| New in version 3.7: Added the \fBCUSTOM_CONTENT_FROM_VARIABLE\fP option. |
| |
| .sp |
| New in version 3.11: Added the \fBINCLUDE_GUARD_NAME\fP option. |
| |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ADD_COMPILER_EXPORT_FLAGS( [<output_variable>] ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Deprecated since version 3.0: Set the target properties |
| \fBCXX_VISIBILITY_PRESET\fP and |
| \fBVISIBILITY_INLINES_HIDDEN\fP instead. |
| |
| .sp |
| The \fBADD_COMPILER_EXPORT_FLAGS\fP function adds \fB\-fvisibility=hidden\fP to |
| \fBCMAKE_CXX_FLAGS\fP if supported, and is a no\-op |
| on Windows which does not need extra compiler flags for exporting support. |
| You may optionally pass a single argument to \fBADD_COMPILER_EXPORT_FLAGS\fP |
| that will be populated with the \fBCXX_FLAGS\fP required to enable visibility |
| support for the compiler/architecture in use. |
| .SS GetPrerequisites |
| .sp |
| Deprecated since version 3.16: Use \fBfile(GET_RUNTIME_DEPENDENCIES)\fP instead. |
| |
| .sp |
| Functions to analyze and list executable file prerequisites. |
| .sp |
| This module provides functions to list the .dll, .dylib or .so files |
| that an executable or shared library file depends on. (Its |
| prerequisites.) |
| .sp |
| It uses various tools to obtain the list of required shared library |
| files: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| dumpbin (Windows) |
| objdump (MinGW on Windows) |
| ldd (Linux/Unix) |
| otool (Mac OSX) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Changed in version 3.16: The tool specified by \fBCMAKE_OBJDUMP\fP will be used, if set. |
| |
| .sp |
| The following functions are provided by this module: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| get_prerequisites |
| list_prerequisites |
| list_prerequisites_by_glob |
| gp_append_unique |
| is_file_executable |
| gp_item_default_embedded_path |
| (projects can override with gp_item_default_embedded_path_override) |
| gp_resolve_item |
| (projects can override with gp_resolve_item_override) |
| gp_resolved_file_type |
| (projects can override with gp_resolved_file_type_override) |
| gp_file_type |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| GET_PREREQUISITES(<target> <prerequisites_var> <exclude_system> <recurse> |
| <exepath> <dirs> [<rpaths>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Get the list of shared library files required by <target>. The list |
| in the variable named <prerequisites_var> should be empty on first |
| entry to this function. On exit, <prerequisites_var> will contain the |
| list of required shared library files. |
| .sp |
| <target> is the full path to an executable file. <prerequisites_var> |
| is the name of a CMake variable to contain the results. |
| <exclude_system> must be 0 or 1 indicating whether to include or |
| exclude "system" prerequisites. If <recurse> is set to 1 all |
| prerequisites will be found recursively, if set to 0 only direct |
| prerequisites are listed. <exepath> is the path to the top level |
| executable used for @executable_path replacement on the Mac. <dirs> is |
| a list of paths where libraries might be found: these paths are |
| searched first when a target without any path info is given. Then |
| standard system locations are also searched: PATH, Framework |
| locations, /usr/lib... |
| .sp |
| New in version 3.14: The variable GET_PREREQUISITES_VERBOSE can be set to true to enable verbose |
| output. |
| |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| LIST_PREREQUISITES(<target> [<recurse> [<exclude_system> [<verbose>]]]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Print a message listing the prerequisites of <target>. |
| .sp |
| <target> is the name of a shared library or executable target or the |
| full path to a shared library or executable file. If <recurse> is set |
| to 1 all prerequisites will be found recursively, if set to 0 only |
| direct prerequisites are listed. <exclude_system> must be 0 or 1 |
| indicating whether to include or exclude "system" prerequisites. With |
| <verbose> set to 0 only the full path names of the prerequisites are |
| printed, set to 1 extra information will be displayed. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| LIST_PREREQUISITES_BY_GLOB(<glob_arg> <glob_exp>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Print the prerequisites of shared library and executable files |
| matching a globbing pattern. <glob_arg> is GLOB or GLOB_RECURSE and |
| <glob_exp> is a globbing expression used with "file(GLOB" or |
| "file(GLOB_RECURSE" to retrieve a list of matching files. If a |
| matching file is executable, its prerequisites are listed. |
| .sp |
| Any additional (optional) arguments provided are passed along as the |
| optional arguments to the list_prerequisites calls. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| GP_APPEND_UNIQUE(<list_var> <value>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Append <value> to the list variable <list_var> only if the value is |
| not already in the list. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| IS_FILE_EXECUTABLE(<file> <result_var>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Return 1 in <result_var> if <file> is a binary executable, 0 |
| otherwise. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| GP_ITEM_DEFAULT_EMBEDDED_PATH(<item> <default_embedded_path_var>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Return the path that others should refer to the item by when the item |
| is embedded inside a bundle. |
| .sp |
| Override on a per\-project basis by providing a project\-specific |
| gp_item_default_embedded_path_override function. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| GP_RESOLVE_ITEM(<context> <item> <exepath> <dirs> <resolved_item_var> |
| [<rpaths>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Resolve an item into an existing full path file. |
| .sp |
| Override on a per\-project basis by providing a project\-specific |
| gp_resolve_item_override function. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| GP_RESOLVED_FILE_TYPE(<original_file> <file> <exepath> <dirs> <type_var> |
| [<rpaths>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Return the type of <file> with respect to <original_file>. String |
| describing type of prerequisite is returned in variable named |
| <type_var>. |
| .sp |
| Use <exepath> and <dirs> if necessary to resolve non\-absolute <file> |
| values \-\- but only for non\-embedded items. |
| .sp |
| Possible types are: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| system |
| local |
| embedded |
| other |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Override on a per\-project basis by providing a project\-specific |
| gp_resolved_file_type_override function. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| GP_FILE_TYPE(<original_file> <file> <type_var>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Return the type of <file> with respect to <original_file>. String |
| describing type of prerequisite is returned in variable named |
| <type_var>. |
| .sp |
| Possible types are: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| system |
| local |
| embedded |
| other |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS GNUInstallDirs |
| .sp |
| Define GNU standard installation directories |
| .sp |
| Provides install directory variables as defined by the |
| \fI\%GNU Coding Standards\fP\&. |
| .SS Result Variables |
| .sp |
| Inclusion of this module defines the following variables: |
| .sp |
| \fBCMAKE_INSTALL_<dir>\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| Destination for files of a given type. This value may be passed to |
| the \fBDESTINATION\fP options of \fBinstall()\fP commands for the |
| corresponding file type. It should typically be a path relative to |
| the installation prefix so that it can be converted to an absolute |
| path in a relocatable way (see \fBCMAKE_INSTALL_FULL_<dir>\fP). |
| However, an absolute path is also allowed. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBCMAKE_INSTALL_FULL_<dir>\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| The absolute path generated from the corresponding \fBCMAKE_INSTALL_<dir>\fP |
| value. If the value is not already an absolute path, an absolute path |
| is constructed typically by prepending the value of the |
| \fBCMAKE_INSTALL_PREFIX\fP variable. However, there are some |
| \fI\%special cases\fP as documented below. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| where \fB<dir>\fP is one of: |
| .INDENT 0.0 |
| .TP |
| .B \fBBINDIR\fP |
| user executables (\fBbin\fP) |
| .TP |
| .B \fBSBINDIR\fP |
| system admin executables (\fBsbin\fP) |
| .TP |
| .B \fBLIBEXECDIR\fP |
| program executables (\fBlibexec\fP) |
| .TP |
| .B \fBSYSCONFDIR\fP |
| read\-only single\-machine data (\fBetc\fP) |
| .TP |
| .B \fBSHAREDSTATEDIR\fP |
| modifiable architecture\-independent data (\fBcom\fP) |
| .TP |
| .B \fBLOCALSTATEDIR\fP |
| modifiable single\-machine data (\fBvar\fP) |
| .TP |
| .B \fBRUNSTATEDIR\fP |
| New in version 3.9: run\-time variable data (\fBLOCALSTATEDIR/run\fP) |
| |
| .TP |
| .B \fBLIBDIR\fP |
| object code libraries (\fBlib\fP or \fBlib64\fP) |
| .sp |
| On Debian, this may be \fBlib/<multiarch\-tuple>\fP when |
| \fBCMAKE_INSTALL_PREFIX\fP is \fB/usr\fP\&. |
| .TP |
| .B \fBINCLUDEDIR\fP |
| C header files (\fBinclude\fP) |
| .TP |
| .B \fBOLDINCLUDEDIR\fP |
| C header files for non\-gcc (\fB/usr/include\fP) |
| .TP |
| .B \fBDATAROOTDIR\fP |
| read\-only architecture\-independent data root (\fBshare\fP) |
| .TP |
| .B \fBDATADIR\fP |
| read\-only architecture\-independent data (\fBDATAROOTDIR\fP) |
| .TP |
| .B \fBINFODIR\fP |
| info documentation (\fBDATAROOTDIR/info\fP) |
| .TP |
| .B \fBLOCALEDIR\fP |
| locale\-dependent data (\fBDATAROOTDIR/locale\fP) |
| .TP |
| .B \fBMANDIR\fP |
| man documentation (\fBDATAROOTDIR/man\fP) |
| .TP |
| .B \fBDOCDIR\fP |
| documentation root (\fBDATAROOTDIR/doc/PROJECT_NAME\fP) |
| .UNINDENT |
| .sp |
| If the includer does not define a value the above\-shown default will be |
| used and the value will appear in the cache for editing by the user. |
| .SS Special Cases |
| .sp |
| New in version 3.4. |
| |
| .sp |
| The following values of \fBCMAKE_INSTALL_PREFIX\fP are special: |
| .sp |
| \fB/\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| For \fB<dir>\fP other than the \fBSYSCONFDIR\fP, \fBLOCALSTATEDIR\fP and |
| \fBRUNSTATEDIR\fP, the value of \fBCMAKE_INSTALL_<dir>\fP is prefixed |
| with \fBusr/\fP if it is not user\-specified as an absolute path. |
| For example, the \fBINCLUDEDIR\fP value \fBinclude\fP becomes \fBusr/include\fP\&. |
| This is required by the \fI\%GNU Coding Standards\fP, which state: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| When building the complete GNU system, the prefix will be empty |
| and \fB/usr\fP will be a symbolic link to \fB/\fP\&. |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fB/usr\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| For \fB<dir>\fP equal to \fBSYSCONFDIR\fP, \fBLOCALSTATEDIR\fP or |
| \fBRUNSTATEDIR\fP, the \fBCMAKE_INSTALL_FULL_<dir>\fP is computed by |
| prepending just \fB/\fP to the value of \fBCMAKE_INSTALL_<dir>\fP |
| if it is not user\-specified as an absolute path. |
| For example, the \fBSYSCONFDIR\fP value \fBetc\fP becomes \fB/etc\fP\&. |
| This is required by the \fI\%GNU Coding Standards\fP\&. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fB/opt/...\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| For \fB<dir>\fP equal to \fBSYSCONFDIR\fP, \fBLOCALSTATEDIR\fP or |
| \fBRUNSTATEDIR\fP, the \fBCMAKE_INSTALL_FULL_<dir>\fP is computed by |
| \fIappending\fP the prefix to the value of \fBCMAKE_INSTALL_<dir>\fP |
| if it is not user\-specified as an absolute path. |
| For example, the \fBSYSCONFDIR\fP value \fBetc\fP becomes \fB/etc/opt/...\fP\&. |
| This is defined by the \fI\%Filesystem Hierarchy Standard\fP\&. |
| .UNINDENT |
| .UNINDENT |
| .SS Macros |
| .INDENT 0.0 |
| .TP |
| .B GNUInstallDirs_get_absolute_install_dir |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| GNUInstallDirs_get_absolute_install_dir(absvar var dirname) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.7. |
| |
| .sp |
| Set the given variable \fBabsvar\fP to the absolute path contained |
| within the variable \fBvar\fP\&. This is to allow the computation of an |
| absolute path, accounting for all the special cases documented |
| above. While this macro is used to compute the various |
| \fBCMAKE_INSTALL_FULL_<dir>\fP variables, it is exposed publicly to |
| allow users who create additional path variables to also compute |
| absolute paths where necessary, using the same logic. \fBdirname\fP is |
| the directory name to get, e.g. \fBBINDIR\fP\&. |
| .sp |
| Changed in version 3.20: Added the \fB<dirname>\fP parameter. Previous versions of CMake passed |
| this value through the variable \fB${dir}\fP\&. |
| |
| .UNINDENT |
| .SS GoogleTest |
| .sp |
| New in version 3.9. |
| |
| .sp |
| This module defines functions to help use the Google Test infrastructure. Two |
| mechanisms for adding tests are provided. \fI\%gtest_add_tests()\fP has been |
| around for some time, originally via \fBfind_package(GTest)\fP\&. |
| \fI\%gtest_discover_tests()\fP was introduced in CMake 3.10. |
| .sp |
| The (older) \fI\%gtest_add_tests()\fP scans source files to identify tests. |
| This is usually effective, with some caveats, including in cross\-compiling |
| environments, and makes setting additional properties on tests more convenient. |
| However, its handling of parameterized tests is less comprehensive, and it |
| requires re\-running CMake to detect changes to the list of tests. |
| .sp |
| The (newer) \fI\%gtest_discover_tests()\fP discovers tests by asking the |
| compiled test executable to enumerate its tests. This is more robust and |
| provides better handling of parameterized tests, and does not require CMake |
| to be re\-run when tests change. However, it may not work in a cross\-compiling |
| environment, and setting test properties is less convenient. |
| .sp |
| More details can be found in the documentation of the respective functions. |
| .sp |
| Both commands are intended to replace use of \fBadd_test()\fP to register |
| tests, and will create a separate CTest test for each Google Test test case. |
| Note that this is in some cases less efficient, as common set\-up and tear\-down |
| logic cannot be shared by multiple test cases executing in the same instance. |
| However, it provides more fine\-grained pass/fail information to CTest, which is |
| usually considered as more beneficial. By default, the CTest test name is the |
| same as the Google Test name (i.e. \fBsuite.testcase\fP); see also |
| \fBTEST_PREFIX\fP and \fBTEST_SUFFIX\fP\&. |
| .INDENT 0.0 |
| .TP |
| .B gtest_add_tests |
| Automatically add tests with CTest by scanning source code for Google Test |
| macros: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| gtest_add_tests(TARGET target |
| [SOURCES src1...] |
| [EXTRA_ARGS arg1...] |
| [WORKING_DIRECTORY dir] |
| [TEST_PREFIX prefix] |
| [TEST_SUFFIX suffix] |
| [SKIP_DEPENDENCY] |
| [TEST_LIST outVar] |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBgtest_add_tests\fP attempts to identify tests by scanning source files. |
| Although this is generally effective, it uses only a basic regular expression |
| match, which can be defeated by atypical test declarations, and is unable to |
| fully "split" parameterized tests. Additionally, it requires that CMake be |
| re\-run to discover any newly added, removed or renamed tests (by default, |
| this means that CMake is re\-run when any test source file is changed, but see |
| \fBSKIP_DEPENDENCY\fP). However, it has the advantage of declaring tests at |
| CMake time, which somewhat simplifies setting additional properties on tests, |
| and always works in a cross\-compiling environment. |
| .sp |
| The options are: |
| .INDENT 7.0 |
| .TP |
| .B \fBTARGET target\fP |
| Specifies the Google Test executable, which must be a known CMake |
| executable target. CMake will substitute the location of the built |
| executable when running the test. |
| .TP |
| .B \fBSOURCES src1...\fP |
| When provided, only the listed files will be scanned for test cases. If |
| this option is not given, the \fBSOURCES\fP property of the |
| specified \fBtarget\fP will be used to obtain the list of sources. |
| .TP |
| .B \fBEXTRA_ARGS arg1...\fP |
| Any extra arguments to pass on the command line to each test case. |
| .TP |
| .B \fBWORKING_DIRECTORY dir\fP |
| Specifies the directory in which to run the discovered test cases. If this |
| option is not provided, the current binary directory is used. |
| .TP |
| .B \fBTEST_PREFIX prefix\fP |
| Specifies a \fBprefix\fP to be prepended to the name of each discovered test |
| case. This can be useful when the same source files are being used in |
| multiple calls to \fBgtest_add_test()\fP but with different \fBEXTRA_ARGS\fP\&. |
| .TP |
| .B \fBTEST_SUFFIX suffix\fP |
| Similar to \fBTEST_PREFIX\fP except the \fBsuffix\fP is appended to the name of |
| every discovered test case. Both \fBTEST_PREFIX\fP and \fBTEST_SUFFIX\fP may |
| be specified. |
| .TP |
| .B \fBSKIP_DEPENDENCY\fP |
| Normally, the function creates a dependency which will cause CMake to be |
| re\-run if any of the sources being scanned are changed. This is to ensure |
| that the list of discovered tests is updated. If this behavior is not |
| desired (as may be the case while actually writing the test cases), this |
| option can be used to prevent the dependency from being added. |
| .TP |
| .B \fBTEST_LIST outVar\fP |
| The variable named by \fBoutVar\fP will be populated in the calling scope |
| with the list of discovered test cases. This allows the caller to do |
| things like manipulate test properties of the discovered tests. |
| .UNINDENT |
| .sp |
| Usage example: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| include(GoogleTest) |
| add_executable(FooTest FooUnitTest.cxx) |
| gtest_add_tests(TARGET FooTest |
| TEST_SUFFIX .noArgs |
| TEST_LIST noArgsTests |
| ) |
| gtest_add_tests(TARGET FooTest |
| EXTRA_ARGS \-\-someArg someValue |
| TEST_SUFFIX .withArgs |
| TEST_LIST withArgsTests |
| ) |
| set_tests_properties(${noArgsTests} PROPERTIES TIMEOUT 10) |
| set_tests_properties(${withArgsTests} PROPERTIES TIMEOUT 20) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| For backward compatibility, the following form is also supported: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| gtest_add_tests(exe args files...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 7.0 |
| .TP |
| .B \fBexe\fP |
| The path to the test executable or the name of a CMake target. |
| .TP |
| .B \fBargs\fP |
| A ;\-list of extra arguments to be passed to executable. The entire |
| list must be passed as a single argument. Enclose it in quotes, |
| or pass \fB""\fP for no arguments. |
| .TP |
| .B \fBfiles...\fP |
| A list of source files to search for tests and test fixtures. |
| Alternatively, use \fBAUTO\fP to specify that \fBexe\fP is the name |
| of a CMake executable target whose sources should be scanned. |
| .UNINDENT |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| include(GoogleTest) |
| set(FooTestArgs \-\-foo 1 \-\-bar 2) |
| add_executable(FooTest FooUnitTest.cxx) |
| gtest_add_tests(FooTest "${FooTestArgs}" AUTO) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B gtest_discover_tests |
| Automatically add tests with CTest by querying the compiled test executable |
| for available tests: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| gtest_discover_tests(target |
| [EXTRA_ARGS arg1...] |
| [WORKING_DIRECTORY dir] |
| [TEST_PREFIX prefix] |
| [TEST_SUFFIX suffix] |
| [TEST_FILTER expr] |
| [NO_PRETTY_TYPES] [NO_PRETTY_VALUES] |
| [PROPERTIES name1 value1...] |
| [TEST_LIST var] |
| [DISCOVERY_TIMEOUT seconds] |
| [XML_OUTPUT_DIR dir] |
| [DISCOVERY_MODE <POST_BUILD|PRE_TEST>] |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.10. |
| |
| .sp |
| \fBgtest_discover_tests()\fP sets up a post\-build command on the test executable |
| that generates the list of tests by parsing the output from running the test |
| with the \fB\-\-gtest_list_tests\fP argument. Compared to the source parsing |
| approach of \fI\%gtest_add_tests()\fP, this ensures that the full list of |
| tests, including instantiations of parameterized tests, is obtained. Since |
| test discovery occurs at build time, it is not necessary to re\-run CMake when |
| the list of tests changes. |
| However, it requires that \fBCROSSCOMPILING_EMULATOR\fP is properly set |
| in order to function in a cross\-compiling environment. |
| .sp |
| Additionally, setting properties on tests is somewhat less convenient, since |
| the tests are not available at CMake time. Additional test properties may be |
| assigned to the set of tests as a whole using the \fBPROPERTIES\fP option. If |
| more fine\-grained test control is needed, custom content may be provided |
| through an external CTest script using the \fBTEST_INCLUDE_FILES\fP |
| directory property. The set of discovered tests is made accessible to such a |
| script via the \fB<target>_TESTS\fP variable. |
| .sp |
| The options are: |
| .INDENT 7.0 |
| .TP |
| .B \fBtarget\fP |
| Specifies the Google Test executable, which must be a known CMake |
| executable target. CMake will substitute the location of the built |
| executable when running the test. |
| .TP |
| .B \fBEXTRA_ARGS arg1...\fP |
| Any extra arguments to pass on the command line to each test case. |
| .TP |
| .B \fBWORKING_DIRECTORY dir\fP |
| Specifies the directory in which to run the discovered test cases. If this |
| option is not provided, the current binary directory is used. |
| .TP |
| .B \fBTEST_PREFIX prefix\fP |
| Specifies a \fBprefix\fP to be prepended to the name of each discovered test |
| case. This can be useful when the same test executable is being used in |
| multiple calls to \fBgtest_discover_tests()\fP but with different |
| \fBEXTRA_ARGS\fP\&. |
| .TP |
| .B \fBTEST_SUFFIX suffix\fP |
| Similar to \fBTEST_PREFIX\fP except the \fBsuffix\fP is appended to the name of |
| every discovered test case. Both \fBTEST_PREFIX\fP and \fBTEST_SUFFIX\fP may |
| be specified. |
| .TP |
| .B \fBTEST_FILTER expr\fP |
| New in version 3.22. |
| |
| .sp |
| Filter expression to pass as a \fB\-\-gtest_filter\fP argument during test |
| discovery. Note that the expression is a wildcard\-based format that |
| matches against the original test names as used by gtest. For type or |
| value\-parameterized tests, these names may be different to the potentially |
| pretty\-printed test names that \fBctest\fP uses. |
| .TP |
| .B \fBNO_PRETTY_TYPES\fP |
| By default, the type index of type\-parameterized tests is replaced by the |
| actual type name in the CTest test name. If this behavior is undesirable |
| (e.g. because the type names are unwieldy), this option will suppress this |
| behavior. |
| .TP |
| .B \fBNO_PRETTY_VALUES\fP |
| By default, the value index of value\-parameterized tests is replaced by the |
| actual value in the CTest test name. If this behavior is undesirable |
| (e.g. because the value strings are unwieldy), this option will suppress |
| this behavior. |
| .TP |
| .B \fBPROPERTIES name1 value1...\fP |
| Specifies additional properties to be set on all tests discovered by this |
| invocation of \fBgtest_discover_tests()\fP\&. |
| .TP |
| .B \fBTEST_LIST var\fP |
| Make the list of tests available in the variable \fBvar\fP, rather than the |
| default \fB<target>_TESTS\fP\&. This can be useful when the same test |
| executable is being used in multiple calls to \fBgtest_discover_tests()\fP\&. |
| Note that this variable is only available in CTest. |
| .TP |
| .B \fBDISCOVERY_TIMEOUT num\fP |
| New in version 3.10.3. |
| |
| .sp |
| Specifies how long (in seconds) CMake will wait for the test to enumerate |
| available tests. If the test takes longer than this, discovery (and your |
| build) will fail. Most test executables will enumerate their tests very |
| quickly, but under some exceptional circumstances, a test may require a |
| longer timeout. The default is 5. See also the \fBTIMEOUT\fP option of |
| \fBexecute_process()\fP\&. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| In CMake versions 3.10.1 and 3.10.2, this option was called \fBTIMEOUT\fP\&. |
| This clashed with the \fBTIMEOUT\fP test property, which is one of the |
| common properties that would be set with the \fBPROPERTIES\fP keyword, |
| usually leading to legal but unintended behavior. The keyword was |
| changed to \fBDISCOVERY_TIMEOUT\fP in CMake 3.10.3 to address this |
| problem. The ambiguous behavior of the \fBTIMEOUT\fP keyword in 3.10.1 |
| and 3.10.2 has not been preserved. |
| .UNINDENT |
| .UNINDENT |
| .TP |
| .B \fBXML_OUTPUT_DIR dir\fP |
| New in version 3.18. |
| |
| .sp |
| If specified, the parameter is passed along with \fB\-\-gtest_output=xml:\fP |
| to test executable. The actual file name is the same as the test target, |
| including prefix and suffix. This should be used instead of |
| \fBEXTRA_ARGS \-\-gtest_output=xml\fP to avoid race conditions writing the |
| XML result output when using parallel test execution. |
| .TP |
| .B \fBDISCOVERY_MODE\fP |
| New in version 3.18. |
| |
| .sp |
| Provides greater control over when \fBgtest_discover_tests()\fP performs test |
| discovery. By default, \fBPOST_BUILD\fP sets up a post\-build command |
| to perform test discovery at build time. In certain scenarios, like |
| cross\-compiling, this \fBPOST_BUILD\fP behavior is not desirable. |
| By contrast, \fBPRE_TEST\fP delays test discovery until just prior to test |
| execution. This way test discovery occurs in the target environment |
| where the test has a better chance at finding appropriate runtime |
| dependencies. |
| .sp |
| \fBDISCOVERY_MODE\fP defaults to the value of the |
| \fBCMAKE_GTEST_DISCOVER_TESTS_DISCOVERY_MODE\fP variable if it is not |
| passed when calling \fBgtest_discover_tests()\fP\&. This provides a mechanism |
| for globally selecting a preferred test discovery behavior without having |
| to modify each call site. |
| .UNINDENT |
| .UNINDENT |
| .SS InstallRequiredSystemLibraries |
| .sp |
| Include this module to search for compiler\-provided system runtime |
| libraries and add install rules for them. Some optional variables |
| may be set prior to including the module to adjust behavior: |
| .INDENT 0.0 |
| .TP |
| .B \fBCMAKE_INSTALL_SYSTEM_RUNTIME_LIBS\fP |
| Specify additional runtime libraries that may not be detected. |
| After inclusion any detected libraries will be appended to this. |
| .TP |
| .B \fBCMAKE_INSTALL_SYSTEM_RUNTIME_LIBS_SKIP\fP |
| Set to TRUE to skip calling the \fBinstall(PROGRAMS)\fP command to |
| allow the includer to specify its own install rule, using the value of |
| \fBCMAKE_INSTALL_SYSTEM_RUNTIME_LIBS\fP to get the list of libraries. |
| .TP |
| .B \fBCMAKE_INSTALL_DEBUG_LIBRARIES\fP |
| Set to TRUE to install the debug runtime libraries when available |
| with MSVC tools. |
| .TP |
| .B \fBCMAKE_INSTALL_DEBUG_LIBRARIES_ONLY\fP |
| Set to TRUE to install only the debug runtime libraries with MSVC |
| tools even if the release runtime libraries are also available. |
| .TP |
| .B \fBCMAKE_INSTALL_UCRT_LIBRARIES\fP |
| New in version 3.6. |
| |
| .sp |
| Set to TRUE to install the Windows Universal CRT libraries for |
| app\-local deployment (e.g. to Windows XP). This is meaningful |
| only with MSVC from Visual Studio 2015 or higher. |
| .sp |
| New in version 3.9: One may set a \fBCMAKE_WINDOWS_KITS_10_DIR\fP \fIenvironment variable\fP |
| to an absolute path to tell CMake to look for Windows 10 SDKs in |
| a custom location. The specified directory is expected to contain |
| \fBRedist/ucrt/DLLs/*\fP directories. |
| |
| .TP |
| .B \fBCMAKE_INSTALL_MFC_LIBRARIES\fP |
| Set to TRUE to install the MSVC MFC runtime libraries. |
| .TP |
| .B \fBCMAKE_INSTALL_OPENMP_LIBRARIES\fP |
| Set to TRUE to install the MSVC OpenMP runtime libraries |
| .TP |
| .B \fBCMAKE_INSTALL_SYSTEM_RUNTIME_DESTINATION\fP |
| Specify the \fBinstall(PROGRAMS)\fP command \fBDESTINATION\fP |
| option. If not specified, the default is \fBbin\fP on Windows |
| and \fBlib\fP elsewhere. |
| .TP |
| .B \fBCMAKE_INSTALL_SYSTEM_RUNTIME_LIBS_NO_WARNINGS\fP |
| Set to TRUE to disable warnings about required library files that |
| do not exist. (For example, Visual Studio Express editions may |
| not provide the redistributable files.) |
| .TP |
| .B \fBCMAKE_INSTALL_SYSTEM_RUNTIME_COMPONENT\fP |
| New in version 3.3. |
| |
| .sp |
| Specify the \fBinstall(PROGRAMS)\fP command \fBCOMPONENT\fP |
| option. If not specified, no such option will be used. |
| .UNINDENT |
| .sp |
| New in version 3.10: Support for installing Intel compiler runtimes. |
| |
| .SS ProcessorCount |
| .sp |
| ProcessorCount(var) |
| .sp |
| Determine the number of processors/cores and save value in ${var} |
| .sp |
| Sets the variable named ${var} to the number of physical cores |
| available on the machine if the information can be determined. |
| Otherwise it is set to 0. Currently this functionality is implemented |
| for AIX, cygwin, FreeBSD, HPUX, Linux, macOS, QNX, Sun and |
| Windows. |
| .sp |
| Changed in version 3.15: On Linux, returns the container CPU count instead of the host CPU count. |
| |
| .sp |
| This function is guaranteed to return a positive integer (>=1) if it |
| succeeds. It returns 0 if there\(aqs a problem determining the processor |
| count. |
| .sp |
| Example use, in a ctest \-S dashboard script: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| include(ProcessorCount) |
| ProcessorCount(N) |
| if(NOT N EQUAL 0) |
| set(CTEST_BUILD_FLAGS \-j${N}) |
| set(ctest_test_args ${ctest_test_args} PARALLEL_LEVEL ${N}) |
| endif() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This function is intended to offer an approximation of the value of |
| the number of compute cores available on the current machine, such |
| that you may use that value for parallel building and parallel |
| testing. It is meant to help utilize as much of the machine as seems |
| reasonable. Of course, knowledge of what else might be running on the |
| machine simultaneously should be used when deciding whether to request |
| a machine\(aqs full capacity all for yourself. |
| .SS SelectLibraryConfigurations |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| select_library_configurations(basename) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This macro takes a library base name as an argument, and will choose |
| good values for the variables |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| basename_LIBRARY |
| basename_LIBRARIES |
| basename_LIBRARY_DEBUG |
| basename_LIBRARY_RELEASE |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| depending on what has been found and set. |
| .sp |
| If only \fBbasename_LIBRARY_RELEASE\fP is defined, \fBbasename_LIBRARY\fP will |
| be set to the release value, and \fBbasename_LIBRARY_DEBUG\fP will be set |
| to \fBbasename_LIBRARY_DEBUG\-NOTFOUND\fP\&. If only \fBbasename_LIBRARY_DEBUG\fP |
| is defined, then \fBbasename_LIBRARY\fP will take the debug value, and |
| \fBbasename_LIBRARY_RELEASE\fP will be set to \fBbasename_LIBRARY_RELEASE\-NOTFOUND\fP\&. |
| .sp |
| If the generator supports configuration types, then \fBbasename_LIBRARY\fP |
| and \fBbasename_LIBRARIES\fP will be set with debug and optimized flags |
| specifying the library to be used for the given configuration. If no |
| build type has been set or the generator in use does not support |
| configuration types, then \fBbasename_LIBRARY\fP and \fBbasename_LIBRARIES\fP |
| will take only the release value, or the debug value if the release one |
| is not set. |
| .SS SquishTestScript |
| .sp |
| This script launches a GUI test using Squish. You should not call the |
| script directly; instead, you should access it via the SQUISH_ADD_TEST |
| macro that is defined in FindSquish.cmake. |
| .sp |
| This script starts the Squish server, launches the test on the client, |
| and finally stops the squish server. If any of these steps fail |
| (including if the tests do not pass) then a fatal error is raised. |
| .SS TestBigEndian |
| .sp |
| Deprecated since version 3.20: Supserseded by the \fBCMAKE_<LANG>_BYTE_ORDER\fP variable. |
| |
| .sp |
| Check if the target architecture is big endian or little endian. |
| .INDENT 0.0 |
| .TP |
| .B test_big_endian |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| test_big_endian(<var>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Stores in variable \fB<var>\fP either 1 or 0 indicating whether the |
| target architecture is big or little endian. |
| .UNINDENT |
| .SS TestForANSIForScope |
| .sp |
| Check for ANSI for scope support |
| .sp |
| Check if the compiler restricts the scope of variables declared in a |
| for\-init\-statement to the loop body. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| CMAKE_NO_ANSI_FOR_SCOPE \- holds result |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS TestForANSIStreamHeaders |
| .sp |
| Test for compiler support of ANSI stream headers iostream, etc. |
| .sp |
| check if the compiler supports the standard ANSI iostream header |
| (without the .h) |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| CMAKE_NO_ANSI_STREAM_HEADERS \- defined by the results |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS TestForSSTREAM |
| .sp |
| Test for compiler support of ANSI sstream header |
| .sp |
| check if the compiler supports the standard ANSI sstream header |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| CMAKE_NO_ANSI_STRING_STREAM \- defined by the results |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS TestForSTDNamespace |
| .sp |
| Test for std:: namespace support |
| .sp |
| check if the compiler supports std:: on stl classes |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| CMAKE_NO_STD_NAMESPACE \- defined by the results |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS UseEcos |
| .sp |
| This module defines variables and macros required to build eCos application. |
| .sp |
| This file contains the following macros: |
| ECOS_ADD_INCLUDE_DIRECTORIES() \- add the eCos include dirs |
| ECOS_ADD_EXECUTABLE(name source1 ... sourceN ) \- create an eCos |
| executable ECOS_ADJUST_DIRECTORY(VAR source1 ... sourceN ) \- adjusts |
| the path of the source files and puts the result into VAR |
| .sp |
| Macros for selecting the toolchain: ECOS_USE_ARM_ELF_TOOLS() \- enable |
| the ARM ELF toolchain for the directory where it is called |
| ECOS_USE_I386_ELF_TOOLS() \- enable the i386 ELF toolchain for the |
| directory where it is called ECOS_USE_PPC_EABI_TOOLS() \- enable the |
| PowerPC toolchain for the directory where it is called |
| .sp |
| It contains the following variables: ECOS_DEFINITIONS |
| ECOSCONFIG_EXECUTABLE ECOS_CONFIG_FILE \- defaults to ecos.ecc, if your |
| eCos configuration file has a different name, adjust this variable for |
| internal use only: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ECOS_ADD_TARGET_LIB |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS UseJava |
| .sp |
| This file provides support for \fBJava\fP\&. It is assumed that |
| \fBFindJava\fP has already been loaded. See \fBFindJava\fP for |
| information on how to load Java into your \fBCMake\fP project. |
| .SS Synopsis |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| \fI\%Creating and Installing JARS\fP |
| \fI\%add_jar\fP (<target_name> [SOURCES] <source1> [<source2>...] ...) |
| \fI\%install_jar\fP (<target_name> DESTINATION <destination> [COMPONENT <component>]) |
| \fI\%install_jni_symlink\fP (<target_name> DESTINATION <destination> [COMPONENT <component>]) |
| |
| \fI\%Header Generation\fP |
| \fI\%create_javah\fP ((TARGET <target> | GENERATED_FILES <VAR>) CLASSES <class>... ...) |
| |
| \fI\%Exporting JAR Targets\fP |
| \fI\%install_jar_exports\fP (TARGETS <jars>... FILE <filename> DESTINATION <destination> ...) |
| \fI\%export_jars\fP (TARGETS <jars>... [NAMESPACE <namespace>] FILE <filename>) |
| |
| \fI\%Finding JARs\fP |
| \fI\%find_jar\fP (<VAR> NAMES <name1> [<name2>...] [PATHS <path1> [<path2>... ENV <var>]] ...) |
| |
| \fI\%Creating Java Documentation\fP |
| \fI\%create_javadoc\fP (<VAR> (PACKAGES <pkg1> [<pkg2>...] | FILES <file1> [<file2>...]) ...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS Creating And Installing JARs |
| .INDENT 0.0 |
| .TP |
| .B add_jar |
| Creates a jar file containing java objects and, optionally, resources: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_jar(<target_name> |
| [SOURCES] <source1> [<source2>...] [<resource1>...] |
| [RESOURCES NAMESPACE <ns1> <resource1>... [NAMESPACE <nsX> <resourceX>...]... ] |
| [INCLUDE_JARS <jar1> [<jar2>...]] |
| [ENTRY_POINT <entry>] |
| [VERSION <version>] |
| [MANIFEST <manifest>] |
| [OUTPUT_NAME <name>] |
| [OUTPUT_DIR <dir>] |
| [GENERATE_NATIVE_HEADERS <target> |
| [DESTINATION (<dir>|INSTALL <dir> [BUILD <dir>])]] |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This command creates a \fB<target_name>.jar\fP\&. It compiles the given |
| \fB<source>\fP files and adds the given \fB<resource>\fP files to |
| the jar file. Source files can be java files or listing files |
| (prefixed by \fB@\fP). If only resource files are given then just a jar file |
| is created. |
| .INDENT 7.0 |
| .TP |
| .B \fBSOURCES\fP |
| Compiles the specified source files and adds the result in the jar file. |
| .sp |
| New in version 3.4: Support for response files, prefixed by \fB@\fP\&. |
| |
| .TP |
| .B \fBRESOURCES\fP |
| New in version 3.21. |
| |
| .sp |
| Adds the named \fB<resource>\fP files to the jar by stripping the source file |
| path and placing the file beneath \fB<ns>\fP within the jar. |
| .sp |
| For example: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| RESOURCES NAMESPACE "/com/my/namespace" "a/path/to/resource.txt" |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| results in a resource accessible via \fB/com/my/namespace/resource.txt\fP |
| within the jar. |
| .sp |
| Resources may be added without adjusting the namespace by adding them to |
| the list of \fBSOURCES\fP (original behavior), in this case, resource |
| paths must be relative to \fBCMAKE_CURRENT_SOURCE_DIR\fP\&. Adding resources |
| without using the \fBRESOURCES\fP parameter in out of source builds will |
| almost certainly result in confusion. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| Adding resources via the \fBSOURCES\fP parameter relies upon a hard\-coded |
| list of file extensions which are tested to determine whether they |
| compile (e.g. File.java). \fBSOURCES\fP files which match the extensions |
| are compiled. Files which do not match are treated as resources. To |
| include uncompiled resources matching those file extensions use |
| the \fBRESOURCES\fP parameter. |
| .UNINDENT |
| .UNINDENT |
| .TP |
| .B \fBINCLUDE_JARS\fP |
| The list of jars are added to the classpath when compiling the java sources |
| and also to the dependencies of the target. \fBINCLUDE_JARS\fP also accepts |
| other target names created by \fBadd_jar()\fP\&. For backwards compatibility, |
| jar files listed as sources are ignored (as they have been since the first |
| version of this module). |
| .TP |
| .B \fBENTRY_POINT\fP |
| Defines an entry point in the jar file. |
| .TP |
| .B \fBVERSION\fP |
| Adds a version to the target output name. |
| .sp |
| The following example will create a jar file with the name |
| \fBshibboleet\-1.2.0.jar\fP and will create a symlink \fBshibboleet.jar\fP |
| pointing to the jar with the version information. |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_jar(shibboleet shibbotleet.java VERSION 1.2.0) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .TP |
| .B \fBMANIFEST\fP |
| Defines a custom manifest for the jar. |
| .TP |
| .B \fBOUTPUT_NAME\fP |
| Specify a different output name for the target. |
| .TP |
| .B \fBOUTPUT_DIR\fP |
| Sets the directory where the jar file will be generated. If not specified, |
| \fBCMAKE_CURRENT_BINARY_DIR\fP is used as the output directory. |
| .TP |
| .B \fBGENERATE_NATIVE_HEADERS\fP |
| New in version 3.11. |
| |
| .sp |
| Generates native header files for methods declared as native. These files |
| provide the connective glue that allow your Java and C code to interact. |
| An INTERFACE target will be created for an easy usage of generated files. |
| Sub\-option \fBDESTINATION\fP can be used to specify the output directory for |
| generated header files. |
| .sp |
| This option requires, at least, version 1.8 of the JDK. |
| .sp |
| For an optimum usage of this option, it is recommended to include module |
| JNI before any call to \fBadd_jar()\fP\&. The produced target for native |
| headers can then be used to compile C/C++ sources with the |
| \fBtarget_link_libraries()\fP command. |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_package(JNI) |
| add_jar(foo foo.java GENERATE_NATIVE_HEADERS foo\-native) |
| add_library(bar bar.cpp) |
| target_link_libraries(bar PRIVATE foo\-native) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.20: \fBDESTINATION\fP sub\-option now supports the possibility to specify |
| different output directories for \fBBUILD\fP and \fBINSTALL\fP steps. If |
| \fBBUILD\fP directory is not specified, a default directory will be used. |
| .sp |
| To export the interface target generated by \fBGENERATE_NATIVE_HEADERS\fP |
| option, sub\-option \fBINSTALL\fP of \fBDESTINATION\fP is required: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_jar(foo foo.java GENERATE_NATIVE_HEADERS foo\-native |
| DESTINATION INSTALL include) |
| install(TARGETS foo\-native EXPORT native) |
| install(DIRECTORY "$<TARGET_PROPERTY:foo\-native,NATIVE_HEADERS_DIRECTORY>/" |
| DESTINATION include) |
| install(EXPORT native DESTINATION /to/export NAMESPACE foo) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| |
| .UNINDENT |
| .sp |
| Some variables can be set to customize the behavior of \fBadd_jar()\fP as well |
| as the java compiler: |
| .INDENT 7.0 |
| .TP |
| .B \fBCMAKE_JAVA_COMPILE_FLAGS\fP |
| Specify additional flags to java compiler. |
| .TP |
| .B \fBCMAKE_JAVA_INCLUDE_PATH\fP |
| Specify additional paths to the class path. |
| .TP |
| .B \fBCMAKE_JNI_TARGET\fP |
| If the target is a JNI library, sets this boolean variable to \fBTRUE\fP to |
| enable creation of a JNI symbolic link (see also |
| \fI\%install_jni_symlink()\fP). |
| .TP |
| .B \fBCMAKE_JAR_CLASSES_PREFIX\fP |
| If multiple jars should be produced from the same java source filetree, |
| to prevent the accumulation of duplicate class files in subsequent jars, |
| set/reset \fBCMAKE_JAR_CLASSES_PREFIX\fP prior to calling the \fBadd_jar()\fP: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(CMAKE_JAR_CLASSES_PREFIX com/redhat/foo) |
| add_jar(foo foo.java) |
| |
| set(CMAKE_JAR_CLASSES_PREFIX com/redhat/bar) |
| add_jar(bar bar.java) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The \fBadd_jar()\fP function sets the following target properties on |
| \fB<target_name>\fP: |
| .INDENT 7.0 |
| .TP |
| .B \fBINSTALL_FILES\fP |
| The files which should be installed. This is used by |
| \fI\%install_jar()\fP\&. |
| .TP |
| .B \fBJNI_SYMLINK\fP |
| The JNI symlink which should be installed. This is used by |
| \fI\%install_jni_symlink()\fP\&. |
| .TP |
| .B \fBJAR_FILE\fP |
| The location of the jar file so that you can include it. |
| .TP |
| .B \fBCLASSDIR\fP |
| The directory where the class files can be found. For example to use them |
| with \fBjavah\fP\&. |
| .TP |
| .B \fBNATIVE_HEADERS_DIRECTORY\fP |
| New in version 3.20. |
| |
| .sp |
| The directory where native headers are generated. Defined when option |
| \fBGENERATE_NATIVE_HEADERS\fP is specified. |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B install_jar |
| This command installs the jar file to the given destination: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| install_jar(<target_name> <destination>) |
| install_jar(<target_name> DESTINATION <destination> [COMPONENT <component>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This command installs the \fB<target_name>\fP file to the given |
| \fB<destination>\fP\&. It should be called in the same scope as |
| \fI\%add_jar()\fP or it will fail. |
| .sp |
| New in version 3.4: The second signature with \fBDESTINATION\fP and \fBCOMPONENT\fP options. |
| |
| .INDENT 7.0 |
| .TP |
| .B \fBDESTINATION\fP |
| Specify the directory on disk to which a file will be installed. |
| .TP |
| .B \fBCOMPONENT\fP |
| Specify an installation component name with which the install rule is |
| associated, such as "runtime" or "development". |
| .UNINDENT |
| .sp |
| The \fBinstall_jar()\fP command sets the following target properties |
| on \fB<target_name>\fP: |
| .INDENT 7.0 |
| .TP |
| .B \fBINSTALL_DESTINATION\fP |
| Holds the \fB<destination>\fP as described above, and is used by |
| \fI\%install_jar_exports()\fP\&. |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B install_jni_symlink |
| Installs JNI symlinks for target generated by \fI\%add_jar()\fP: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| install_jni_symlink(<target_name> <destination>) |
| install_jni_symlink(<target_name> DESTINATION <destination> [COMPONENT <component>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This command installs the \fB<target_name>\fP JNI symlinks to the given |
| \fB<destination>\fP\&. It should be called in the same scope as |
| \fI\%add_jar()\fP or it will fail. |
| .sp |
| New in version 3.4: The second signature with \fBDESTINATION\fP and \fBCOMPONENT\fP options. |
| |
| .INDENT 7.0 |
| .TP |
| .B \fBDESTINATION\fP |
| Specify the directory on disk to which a file will be installed. |
| .TP |
| .B \fBCOMPONENT\fP |
| Specify an installation component name with which the install rule is |
| associated, such as "runtime" or "development". |
| .UNINDENT |
| .sp |
| Utilize the following commands to create a JNI symbolic link: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(CMAKE_JNI_TARGET TRUE) |
| add_jar(shibboleet shibbotleet.java VERSION 1.2.0) |
| install_jar(shibboleet ${LIB_INSTALL_DIR}/shibboleet) |
| install_jni_symlink(shibboleet ${JAVA_LIB_INSTALL_DIR}) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .SS Header Generation |
| .INDENT 0.0 |
| .TP |
| .B create_javah |
| New in version 3.4. |
| |
| .sp |
| Generates C header files for java classes: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| create_javah(TARGET <target> | GENERATED_FILES <VAR> |
| CLASSES <class>... |
| [CLASSPATH <classpath>...] |
| [DEPENDS <depend>...] |
| [OUTPUT_NAME <path>|OUTPUT_DIR <path>] |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Deprecated since version 3.11: This command will no longer be supported starting with version 10 of the JDK |
| due to the \fI\%suppression of javah tool\fP\&. |
| The \fI\%add_jar(GENERATE_NATIVE_HEADERS)\fP command should be |
| used instead. |
| |
| .sp |
| Create C header files from java classes. These files provide the connective |
| glue that allow your Java and C code to interact. |
| .sp |
| There are two main signatures for \fBcreate_javah()\fP\&. The first signature |
| returns generated files through variable specified by the \fBGENERATED_FILES\fP |
| option. For example: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| create_javah(GENERATED_FILES files_headers |
| CLASSES org.cmake.HelloWorld |
| CLASSPATH hello.jar |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The second signature for \fBcreate_javah()\fP creates a target which |
| encapsulates header files generation. E.g. |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| create_javah(TARGET target_headers |
| CLASSES org.cmake.HelloWorld |
| CLASSPATH hello.jar |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Both signatures share same options. |
| .INDENT 7.0 |
| .TP |
| .B \fBCLASSES\fP |
| Specifies Java classes used to generate headers. |
| .TP |
| .B \fBCLASSPATH\fP |
| Specifies various paths to look up classes. Here \fB\&.class\fP files, jar |
| files or targets created by command add_jar can be used. |
| .TP |
| .B \fBDEPENDS\fP |
| Targets on which the javah target depends. |
| .TP |
| .B \fBOUTPUT_NAME\fP |
| Concatenates the resulting header files for all the classes listed by |
| option \fBCLASSES\fP into \fB<path>\fP\&. Same behavior as option \fB\-o\fP of |
| \fBjavah\fP tool. |
| .TP |
| .B \fBOUTPUT_DIR\fP |
| Sets the directory where the header files will be generated. Same behavior |
| as option \fB\-d\fP of \fBjavah\fP tool. If not specified, |
| \fBCMAKE_CURRENT_BINARY_DIR\fP is used as the output directory. |
| .UNINDENT |
| .UNINDENT |
| .SS Exporting JAR Targets |
| .INDENT 0.0 |
| .TP |
| .B install_jar_exports |
| New in version 3.7. |
| |
| .sp |
| Installs a target export file: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| install_jar_exports(TARGETS <jars>... |
| [NAMESPACE <namespace>] |
| FILE <filename> |
| DESTINATION <destination> [COMPONENT <component>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This command installs a target export file \fB<filename>\fP for the named jar |
| targets to the given \fB<destination>\fP directory. Its function is similar to |
| that of \fBinstall(EXPORT)\fP\&. |
| .INDENT 7.0 |
| .TP |
| .B \fBTARGETS\fP |
| List of targets created by \fI\%add_jar()\fP command. |
| .TP |
| .B \fBNAMESPACE\fP |
| New in version 3.9. |
| |
| .sp |
| The \fB<namespace>\fP value will be prepend to the target names as they are |
| written to the import file. |
| .TP |
| .B \fBFILE\fP |
| Specify name of the export file. |
| .TP |
| .B \fBDESTINATION\fP |
| Specify the directory on disk to which a file will be installed. |
| .TP |
| .B \fBCOMPONENT\fP |
| Specify an installation component name with which the install rule is |
| associated, such as "runtime" or "development". |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B export_jars |
| New in version 3.7. |
| |
| .sp |
| Writes a target export file: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| export_jars(TARGETS <jars>... |
| [NAMESPACE <namespace>] |
| FILE <filename>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This command writes a target export file \fB<filename>\fP for the named \fB<jars>\fP |
| targets. Its function is similar to that of \fBexport()\fP\&. |
| .INDENT 7.0 |
| .TP |
| .B \fBTARGETS\fP |
| List of targets created by \fI\%add_jar()\fP command. |
| .TP |
| .B \fBNAMESPACE\fP |
| New in version 3.9. |
| |
| .sp |
| The \fB<namespace>\fP value will be prepend to the target names as they are |
| written to the import file. |
| .TP |
| .B \fBFILE\fP |
| Specify name of the export file. |
| .UNINDENT |
| .UNINDENT |
| .SS Finding JARs |
| .INDENT 0.0 |
| .TP |
| .B find_jar |
| Finds the specified jar file: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_jar(<VAR> |
| <name> | NAMES <name1> [<name2>...] |
| [PATHS <path1> [<path2>... ENV <var>]] |
| [VERSIONS <version1> [<version2>]] |
| [DOC "cache documentation string"] |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This command is used to find a full path to the named jar. A cache |
| entry named by \fB<VAR>\fP is created to store the result of this command. |
| If the full path to a jar is found the result is stored in the |
| variable and the search will not repeated unless the variable is |
| cleared. If nothing is found, the result will be \fB<VAR>\-NOTFOUND\fP, and |
| the search will be attempted again next time \fBfind_jar()\fP is invoked with |
| the same variable. |
| .INDENT 7.0 |
| .TP |
| .B \fBNAMES\fP |
| Specify one or more possible names for the jar file. |
| .TP |
| .B \fBPATHS\fP |
| Specify directories to search in addition to the default locations. |
| The \fBENV\fP var sub\-option reads paths from a system environment variable. |
| .TP |
| .B \fBVERSIONS\fP |
| Specify jar versions. |
| .TP |
| .B \fBDOC\fP |
| Specify the documentation string for the \fB<VAR>\fP cache entry. |
| .UNINDENT |
| .UNINDENT |
| .SS Creating Java Documentation |
| .INDENT 0.0 |
| .TP |
| .B create_javadoc |
| Creates java documentation based on files and packages: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| create_javadoc(<VAR> |
| (PACKAGES <pkg1> [<pkg2>...] | FILES <file1> [<file2>...]) |
| [SOURCEPATH <sourcepath>] |
| [CLASSPATH <classpath>] |
| [INSTALLPATH <install path>] |
| [DOCTITLE <the documentation title>] |
| [WINDOWTITLE <the title of the document>] |
| [AUTHOR (TRUE|FALSE)] |
| [USE (TRUE|FALSE)] |
| [VERSION (TRUE|FALSE)] |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The \fBcreate_javadoc()\fP command can be used to create java documentation. |
| There are two main signatures for \fBcreate_javadoc()\fP\&. |
| .sp |
| The first signature works with package names on a path with source files: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| create_javadoc(my_example_doc |
| PACKAGES com.example.foo com.example.bar |
| SOURCEPATH "${CMAKE_CURRENT_SOURCE_DIR}" |
| CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH} |
| WINDOWTITLE "My example" |
| DOCTITLE "<h1>My example</h1>" |
| AUTHOR TRUE |
| USE TRUE |
| VERSION TRUE |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The second signature for \fBcreate_javadoc()\fP works on a given list of files: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| create_javadoc(my_example_doc |
| FILES java/A.java java/B.java |
| CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH} |
| WINDOWTITLE "My example" |
| DOCTITLE "<h1>My example</h1>" |
| AUTHOR TRUE |
| USE TRUE |
| VERSION TRUE |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Both signatures share most of the options. For more details please read the |
| javadoc manpage. |
| .INDENT 7.0 |
| .TP |
| .B \fBPACKAGES\fP |
| Specify java packages. |
| .TP |
| .B \fBFILES\fP |
| Specify java source files. If relative paths are specified, they are |
| relative to \fBCMAKE_CURRENT_SOURCE_DIR\fP\&. |
| .TP |
| .B \fBSOURCEPATH\fP |
| Specify the directory where to look for packages. By default, |
| \fBCMAKE_CURRENT_SOURCE_DIR\fP directory is used. |
| .TP |
| .B \fBCLASSPATH\fP |
| Specify where to find user class files. Same behavior as option |
| \fB\-classpath\fP of \fBjavadoc\fP tool. |
| .TP |
| .B \fBINSTALLPATH\fP |
| Specify where to install the java documentation. If you specified, the |
| documentation will be installed to |
| \fB${CMAKE_INSTALL_PREFIX}/share/javadoc/<VAR>\fP\&. |
| .TP |
| .B \fBDOCTITLE\fP |
| Specify the title to place near the top of the overview summary file. |
| Same behavior as option \fB\-doctitle\fP of \fBjavadoc\fP tool. |
| .TP |
| .B \fBWINDOWTITLE\fP |
| Specify the title to be placed in the HTML \fB<title>\fP tag. Same behavior |
| as option \fB\-windowtitle\fP of \fBjavadoc\fP tool. |
| .TP |
| .B \fBAUTHOR\fP |
| When value \fBTRUE\fP is specified, includes the \fB@author\fP text in the |
| generated docs. Same behavior as option \fB\-author\fP of \fBjavadoc\fP tool. |
| .TP |
| .B \fBUSE\fP |
| When value \fBTRUE\fP is specified, creates class and package usage pages. |
| Includes one Use page for each documented class and package. Same behavior |
| as option \fB\-use\fP of \fBjavadoc\fP tool. |
| .TP |
| .B \fBVERSION\fP |
| When value \fBTRUE\fP is specified, includes the version text in the |
| generated docs. Same behavior as option \fB\-version\fP of \fBjavadoc\fP tool. |
| .UNINDENT |
| .UNINDENT |
| .SS UseSWIG |
| .sp |
| This file provides support for \fBSWIG\fP\&. It is assumed that \fBFindSWIG\fP |
| module has already been loaded. |
| .sp |
| Defines the following command for use with \fBSWIG\fP: |
| .INDENT 0.0 |
| .TP |
| .B swig_add_library |
| New in version 3.8. |
| |
| .sp |
| Define swig module with given name and specified language: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| swig_add_library(<name> |
| [TYPE <SHARED|MODULE|STATIC|USE_BUILD_SHARED_LIBS>] |
| LANGUAGE <language> |
| [NO_PROXY] |
| [OUTPUT_DIR <directory>] |
| [OUTFILE_DIR <directory>] |
| SOURCES <file>... |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Targets created with the \fBswig_add_library\fP command have the same |
| capabilities as targets created with the \fBadd_library()\fP command, so |
| those targets can be used with any command expecting a target (e.g. |
| \fBtarget_link_libraries()\fP). |
| .sp |
| Changed in version 3.13: This command creates a target with the specified \fB<name>\fP when |
| policy \fBCMP0078\fP is set to \fBNEW\fP\&. Otherwise, the legacy |
| behavior will choose a different target name and store it in the |
| \fBSWIG_MODULE_<name>_REAL_NAME\fP variable. |
| |
| .sp |
| Changed in version 3.15: Alternate library name (set with the \fBOUTPUT_NAME\fP property, |
| for example) will be passed on to \fBPython\fP and \fBCSharp\fP wrapper |
| libraries. |
| |
| .sp |
| Changed in version 3.21: Generated library use standard naming conventions for \fBCSharp\fP language |
| when policy \fBCMP0122\fP is set to \fBNEW\fP\&. Otherwise, the legacy |
| behavior is applied. |
| |
| .sp |
| \fBNOTE:\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| For multi\-config generators, this module does not support |
| configuration\-specific files generated by \fBSWIG\fP\&. All build |
| configurations must result in the same generated source file. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBNOTE:\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| For Makefile Generators, if, for some sources, the |
| \fBUSE_SWIG_DEPENDENCIES\fP property is \fBFALSE\fP, \fBswig_add_library\fP does |
| not track file dependencies, so depending on the \fB<name>_swig_compilation\fP |
| custom target is required for targets which require the \fBswig\fP\-generated |
| files to exist. Other generators may depend on the source files that would |
| be generated by SWIG. |
| .UNINDENT |
| .UNINDENT |
| .INDENT 7.0 |
| .TP |
| .B \fBTYPE\fP |
| \fBSHARED\fP, \fBMODULE\fP and \fBSTATIC\fP have the same semantic as for the |
| \fBadd_library()\fP command. If \fBUSE_BUILD_SHARED_LIBS\fP is specified, |
| the library type will be \fBSTATIC\fP or \fBSHARED\fP based on whether the |
| current value of the \fBBUILD_SHARED_LIBS\fP variable is \fBON\fP\&. If |
| no type is specified, \fBMODULE\fP will be used. |
| .TP |
| .B \fBLANGUAGE\fP |
| Specify the target language. |
| .sp |
| New in version 3.1: Go and Lua language support. |
| |
| .sp |
| New in version 3.2: R language support. |
| |
| .sp |
| New in version 3.18: Fortran language support. |
| |
| .TP |
| .B \fBNO_PROXY\fP |
| New in version 3.12. |
| |
| .sp |
| Prevent the generation of the wrapper layer (swig \fB\-noproxy\fP option). |
| .TP |
| .B \fBOUTPUT_DIR\fP |
| New in version 3.12. |
| |
| .sp |
| Specify where to write the language specific files (swig \fB\-outdir\fP |
| option). If not given, the \fBCMAKE_SWIG_OUTDIR\fP variable will be used. |
| If neither is specified, the default depends on the value of the |
| \fBUseSWIG_MODULE_VERSION\fP variable as follows: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| If \fBUseSWIG_MODULE_VERSION\fP is 1 or is undefined, output is written to |
| the \fBCMAKE_CURRENT_BINARY_DIR\fP directory. |
| .IP \(bu 2 |
| If \fBUseSWIG_MODULE_VERSION\fP is 2, a dedicated directory will be used. |
| The path of this directory can be retrieved from the |
| \fBSWIG_SUPPORT_FILES_DIRECTORY\fP target property. |
| .UNINDENT |
| .TP |
| .B \fBOUTFILE_DIR\fP |
| New in version 3.12. |
| |
| .sp |
| Specify an output directory name where the generated source file will be |
| placed (swig \fB\-o\fP option). If not specified, the \fBSWIG_OUTFILE_DIR\fP |
| variable will be used. If neither is specified, \fBOUTPUT_DIR\fP or |
| \fBCMAKE_SWIG_OUTDIR\fP is used instead. |
| .TP |
| .B \fBSOURCES\fP |
| List of sources for the library. Files with extension \fB\&.i\fP will be |
| identified as sources for the \fBSWIG\fP tool. Other files will be handled in |
| the standard way. |
| .sp |
| New in version 3.14: This behavior can be overridden by specifying the variable |
| \fBSWIG_SOURCE_FILE_EXTENSIONS\fP\&. |
| |
| .UNINDENT |
| .sp |
| \fBNOTE:\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| If \fBUseSWIG_MODULE_VERSION\fP is set to 2, it is \fBstrongly\fP recommended |
| to use a dedicated directory unique to the target when either the |
| \fBOUTPUT_DIR\fP option or the \fBCMAKE_SWIG_OUTDIR\fP variable are specified. |
| The output directory contents are erased as part of the target build, so |
| to prevent interference between targets or losing other important files, |
| each target should have its own dedicated output directory. |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B swig_link_libraries |
| Link libraries to swig module: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| swig_link_libraries(<name> <item>...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This command has same capabilities as \fBtarget_link_libraries()\fP |
| command. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| If variable \fBUseSWIG_TARGET_NAME_PREFERENCE\fP is set to \fBSTANDARD\fP, this |
| command is deprecated and \fBtarget_link_libraries()\fP command must be |
| used instead. |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Source file properties on module files \fBmust\fP be set before the invocation |
| of the \fBswig_add_library\fP command to specify special behavior of SWIG and |
| ensure generated files will receive the required settings. |
| .INDENT 0.0 |
| .TP |
| .B \fBCPLUSPLUS\fP |
| Call SWIG in c++ mode. For example: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_property(SOURCE mymod.i PROPERTY CPLUSPLUS ON) |
| swig_add_library(mymod LANGUAGE python SOURCES mymod.i) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .TP |
| .B \fBSWIG_FLAGS\fP |
| Deprecated since version 3.12: Replaced with the fine\-grained properties that follow. |
| |
| .sp |
| Pass custom flags to the SWIG executable. |
| .TP |
| .B \fBINCLUDE_DIRECTORIES\fP, \fBCOMPILE_DEFINITIONS\fP and \fBCOMPILE_OPTIONS\fP |
| New in version 3.12. |
| |
| .sp |
| Add custom flags to SWIG compiler and have same semantic as properties |
| \fBINCLUDE_DIRECTORIES\fP, \fBCOMPILE_DEFINITIONS\fP and |
| \fBCOMPILE_OPTIONS\fP\&. |
| .TP |
| .B \fBUSE_TARGET_INCLUDE_DIRECTORIES\fP |
| New in version 3.13. |
| |
| .sp |
| If set to \fBTRUE\fP, contents of target property |
| \fBINCLUDE_DIRECTORIES\fP will be forwarded to \fBSWIG\fP compiler. |
| If set to \fBFALSE\fP target property \fBINCLUDE_DIRECTORIES\fP will be |
| ignored. If not set, target property \fBSWIG_USE_TARGET_INCLUDE_DIRECTORIES\fP |
| will be considered. |
| .TP |
| .B \fBGENERATED_INCLUDE_DIRECTORIES\fP, \fBGENERATED_COMPILE_DEFINITIONS\fP and \fBGENERATED_COMPILE_OPTIONS\fP |
| New in version 3.12. |
| |
| .sp |
| Add custom flags to the C/C++ generated source. They will fill, respectively, |
| properties \fBINCLUDE_DIRECTORIES\fP, \fBCOMPILE_DEFINITIONS\fP and |
| \fBCOMPILE_OPTIONS\fP of generated C/C++ file. |
| .TP |
| .B \fBDEPENDS\fP |
| New in version 3.12. |
| |
| .sp |
| Specify additional dependencies to the source file. |
| .TP |
| .B \fBUSE_SWIG_DEPENDENCIES\fP |
| New in version 3.20. |
| |
| .sp |
| If set to \fBTRUE\fP, implicit dependencies are generated by the \fBswig\fP tool |
| itself. This property is only meaningful for |
| Makefile, |
| Ninja, \fBXcode\fP, and |
| Visual Studio |
| (\fBVisual Studio 11 2012\fP and above) generators. Default value is |
| \fBFALSE\fP\&. |
| .sp |
| New in version 3.21: Added the support of \fBXcode\fP generator. |
| |
| .sp |
| New in version 3.22: Added the support of Visual Studio Generators\&. |
| |
| .TP |
| .B \fBSWIG_MODULE_NAME\fP |
| Specify the actual import name of the module in the target language. |
| This is required if it cannot be scanned automatically from source |
| or different from the module file basename. For example: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_property(SOURCE mymod.i PROPERTY SWIG_MODULE_NAME mymod_realname) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Changed in version 3.14: If policy \fBCMP0086\fP is set to \fBNEW\fP, \fB\-module <module_name>\fP |
| is passed to \fBSWIG\fP compiler. |
| |
| .TP |
| .B \fBOUTPUT_DIR\fP |
| New in version 3.19. |
| |
| .sp |
| Specify where to write the language specific files (swig \fB\-outdir\fP option) |
| for the considered source file. If not specified, the other ways to define |
| the output directory applies (see \fBOUTPUT_DIR\fP option of |
| \fBswig_add_library()\fP command). |
| .TP |
| .B \fBOUTFILE_DIR\fP |
| New in version 3.19. |
| |
| .sp |
| Specify an output directory where the generated source file will be placed |
| (swig \fB\-o\fP option) for the considered source file. If not specified, |
| \fBOUTPUT_DIR\fP source property will be used. If neither are specified, the |
| other ways to define output file directory applies (see \fBOUTFILE_DIR\fP |
| option of \fBswig_add_library()\fP command). |
| .UNINDENT |
| .sp |
| Target library properties can be set to apply same configuration to all SWIG |
| input files. |
| .INDENT 0.0 |
| .TP |
| .B \fBSWIG_INCLUDE_DIRECTORIES\fP, \fBSWIG_COMPILE_DEFINITIONS\fP and \fBSWIG_COMPILE_OPTIONS\fP |
| New in version 3.12. |
| |
| .sp |
| These properties will be applied to all SWIG input files and have same |
| semantic as target properties \fBINCLUDE_DIRECTORIES\fP, |
| \fBCOMPILE_DEFINITIONS\fP and \fBCOMPILE_OPTIONS\fP\&. |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set (UseSWIG_TARGET_NAME_PREFERENCE STANDARD) |
| swig_add_library(mymod LANGUAGE python SOURCES mymod.i) |
| set_property(TARGET mymod PROPERTY SWIG_COMPILE_DEFINITIONS MY_DEF1 MY_DEF2) |
| set_property(TARGET mymod PROPERTY SWIG_COMPILE_OPTIONS \-bla \-blb) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .TP |
| .B \fBSWIG_USE_TARGET_INCLUDE_DIRECTORIES\fP |
| New in version 3.13. |
| |
| .sp |
| If set to \fBTRUE\fP, contents of target property |
| \fBINCLUDE_DIRECTORIES\fP will be forwarded to \fBSWIG\fP compiler. |
| If set to \fBFALSE\fP or not defined, target property |
| \fBINCLUDE_DIRECTORIES\fP will be ignored. This behavior can be |
| overridden by specifying source property \fBUSE_TARGET_INCLUDE_DIRECTORIES\fP\&. |
| .TP |
| .B \fBSWIG_GENERATED_INCLUDE_DIRECTORIES\fP, \fBSWIG_GENERATED_COMPILE_DEFINITIONS\fP and \fBSWIG_GENERATED_COMPILE_OPTIONS\fP |
| New in version 3.12. |
| |
| .sp |
| These properties will populate, respectively, properties |
| \fBINCLUDE_DIRECTORIES\fP, \fBCOMPILE_DEFINITIONS\fP and |
| \fBCOMPILE_FLAGS\fP of all generated C/C++ files. |
| .TP |
| .B \fBSWIG_DEPENDS\fP |
| New in version 3.12. |
| |
| .sp |
| Add dependencies to all SWIG input files. |
| .UNINDENT |
| .sp |
| The following target properties are output properties and can be used to get |
| information about support files generated by \fBSWIG\fP interface compilation. |
| .INDENT 0.0 |
| .TP |
| .B \fBSWIG_SUPPORT_FILES\fP |
| New in version 3.12. |
| |
| .sp |
| This output property list of wrapper files generated during SWIG compilation. |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set (UseSWIG_TARGET_NAME_PREFERENCE STANDARD) |
| swig_add_library(mymod LANGUAGE python SOURCES mymod.i) |
| get_property(support_files TARGET mymod PROPERTY SWIG_SUPPORT_FILES) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBNOTE:\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| Only most principal support files are listed. In case some advanced |
| features of \fBSWIG\fP are used (for example \fB%template\fP), associated |
| support files may not be listed. Prefer to use the |
| \fBSWIG_SUPPORT_FILES_DIRECTORY\fP property to handle support files. |
| .UNINDENT |
| .UNINDENT |
| .TP |
| .B \fBSWIG_SUPPORT_FILES_DIRECTORY\fP |
| New in version 3.12. |
| |
| .sp |
| This output property specifies the directory where support files will be |
| generated. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| When source property \fBOUTPUT_DIR\fP is defined, multiple directories can be |
| specified as part of \fBSWIG_SUPPORT_FILES_DIRECTORY\fP\&. |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Some variables can be set to customize the behavior of \fBswig_add_library\fP |
| as well as \fBSWIG\fP: |
| .INDENT 0.0 |
| .TP |
| .B \fBUseSWIG_MODULE_VERSION\fP |
| New in version 3.12. |
| |
| .sp |
| Specify different behaviors for \fBUseSWIG\fP module. |
| .INDENT 7.0 |
| .IP \(bu 2 |
| Set to 1 or undefined: Legacy behavior is applied. |
| .IP \(bu 2 |
| Set to 2: A new strategy is applied regarding support files: the output |
| directory of support files is erased before \fBSWIG\fP interface compilation. |
| .UNINDENT |
| .TP |
| .B \fBCMAKE_SWIG_FLAGS\fP |
| Add flags to all swig calls. |
| .TP |
| .B \fBCMAKE_SWIG_OUTDIR\fP |
| Specify where to write the language specific files (swig \fB\-outdir\fP option). |
| .TP |
| .B \fBSWIG_OUTFILE_DIR\fP |
| New in version 3.8. |
| |
| .sp |
| Specify an output directory name where the generated source file will be |
| placed. If not specified, \fBCMAKE_SWIG_OUTDIR\fP is used. |
| .TP |
| .B \fBSWIG_MODULE_<name>_EXTRA_DEPS\fP |
| Specify extra dependencies for the generated module for \fB<name>\fP\&. |
| .TP |
| .B \fBSWIG_SOURCE_FILE_EXTENSIONS\fP |
| New in version 3.14. |
| |
| .sp |
| Specify a list of source file extensions to override the default |
| behavior of considering only \fB\&.i\fP files as sources for the \fBSWIG\fP |
| tool. For example: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(SWIG_SOURCE_FILE_EXTENSIONS ".i" ".swg") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .TP |
| .B \fBSWIG_USE_SWIG_DEPENDENCIES\fP |
| New in version 3.20. |
| |
| .sp |
| If set to \fBTRUE\fP, implicit dependencies are generated by the \fBswig\fP tool |
| itself. This variable is only meaningful for |
| Makefile, |
| Ninja, \fBXcode\fP, and |
| Visual Studio |
| (\fBVisual Studio 11 2012\fP and above) generators. Default value is |
| \fBFALSE\fP\&. |
| .sp |
| Source file property \fBUSE_SWIG_DEPENDENCIES\fP, if not defined, will be |
| initialized with the value of this variable. |
| .sp |
| New in version 3.21: Added the support of \fBXcode\fP generator. |
| |
| .sp |
| New in version 3.22: Added the support of Visual Studio Generators\&. |
| |
| .UNINDENT |
| .SS UsewxWidgets |
| .sp |
| Convenience include for using wxWidgets library. |
| .sp |
| Determines if wxWidgets was FOUND and sets the appropriate libs, |
| incdirs, flags, etc. INCLUDE_DIRECTORIES and LINK_DIRECTORIES are |
| called. |
| .sp |
| USAGE |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| # Note that for MinGW users the order of libs is important! |
| find_package(wxWidgets REQUIRED net gl core base) |
| include(${wxWidgets_USE_FILE}) |
| # and for each of your dependent executable/library targets: |
| target_link_libraries(<YourTarget> ${wxWidgets_LIBRARIES}) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| DEPRECATED |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| LINK_LIBRARIES is not called in favor of adding dependencies per target. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| AUTHOR |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| Jan Woetzel <jw \-at\- mip.informatik.uni\-kiel.de> |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SH FIND MODULES |
| .sp |
| These modules search for third\-party software. |
| They are normally called through the \fBfind_package()\fP command. |
| .SS FindALSA |
| .sp |
| Find Advanced Linux Sound Architecture (ALSA) |
| .sp |
| Find the alsa libraries (\fBasound\fP) |
| .SS IMPORTED Targets |
| .sp |
| New in version 3.12. |
| |
| .sp |
| This module defines \fBIMPORTED\fP target \fBALSA::ALSA\fP, if |
| ALSA has been found. |
| .SS Result Variables |
| .sp |
| This module defines the following variables: |
| .INDENT 0.0 |
| .TP |
| .B \fBALSA_FOUND\fP |
| True if ALSA_INCLUDE_DIR & ALSA_LIBRARY are found |
| .TP |
| .B \fBALSA_LIBRARIES\fP |
| List of libraries when using ALSA. |
| .TP |
| .B \fBALSA_INCLUDE_DIRS\fP |
| Where to find the ALSA headers. |
| .UNINDENT |
| .SS Cache variables |
| .sp |
| The following cache variables may also be set: |
| .INDENT 0.0 |
| .TP |
| .B \fBALSA_INCLUDE_DIR\fP |
| the ALSA include directory |
| .TP |
| .B \fBALSA_LIBRARY\fP |
| the absolute path of the asound library |
| .UNINDENT |
| .SS FindArmadillo |
| .sp |
| Find the Armadillo C++ library. |
| Armadillo is a library for linear algebra & scientific computing. |
| .sp |
| New in version 3.18: Support for linking wrapped libraries directly (\fBARMA_DONT_USE_WRAPPER\fP). |
| |
| .sp |
| Using Armadillo: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_package(Armadillo REQUIRED) |
| include_directories(${ARMADILLO_INCLUDE_DIRS}) |
| add_executable(foo foo.cc) |
| target_link_libraries(foo ${ARMADILLO_LIBRARIES}) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This module sets the following variables: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ARMADILLO_FOUND \- set to true if the library is found |
| ARMADILLO_INCLUDE_DIRS \- list of required include directories |
| ARMADILLO_LIBRARIES \- list of libraries to be linked |
| ARMADILLO_VERSION_MAJOR \- major version number |
| ARMADILLO_VERSION_MINOR \- minor version number |
| ARMADILLO_VERSION_PATCH \- patch version number |
| ARMADILLO_VERSION_STRING \- version number as a string (ex: "1.0.4") |
| ARMADILLO_VERSION_NAME \- name of the version (ex: "Antipodean Antileech") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindASPELL |
| .sp |
| Try to find ASPELL |
| .sp |
| Once done this will define |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ASPELL_FOUND \- system has ASPELL |
| ASPELL_EXECUTABLE \- the ASPELL executable |
| ASPELL_INCLUDE_DIR \- the ASPELL include directory |
| ASPELL_LIBRARIES \- The libraries needed to use ASPELL |
| ASPELL_DEFINITIONS \- Compiler switches required for using ASPELL |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindAVIFile |
| .sp |
| Locate AVIFILE library and include paths |
| .sp |
| AVIFILE (\fI\%http://avifile.sourceforge.net/\fP) is a set of libraries for |
| i386 machines to use various AVI codecs. Support is limited beyond |
| Linux. Windows provides native AVI support, and so doesn\(aqt need this |
| library. This module defines |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| AVIFILE_INCLUDE_DIR, where to find avifile.h , etc. |
| AVIFILE_LIBRARIES, the libraries to link against |
| AVIFILE_DEFINITIONS, definitions to use when compiling |
| AVIFILE_FOUND, If false, don\(aqt try to use AVIFILE |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindBacktrace |
| .sp |
| Find provider for \fI\%backtrace(3)\fP\&. |
| .sp |
| Checks if OS supports \fBbacktrace(3)\fP via either \fBlibc\fP or custom library. |
| This module defines the following variables: |
| .INDENT 0.0 |
| .TP |
| .B \fBBacktrace_HEADER\fP |
| The header file needed for \fBbacktrace(3)\fP\&. Cached. |
| Could be forcibly set by user. |
| .TP |
| .B \fBBacktrace_INCLUDE_DIRS\fP |
| The include directories needed to use \fBbacktrace(3)\fP header. |
| .TP |
| .B \fBBacktrace_LIBRARIES\fP |
| The libraries (linker flags) needed to use \fBbacktrace(3)\fP, if any. |
| .TP |
| .B \fBBacktrace_FOUND\fP |
| Is set if and only if \fBbacktrace(3)\fP support detected. |
| .UNINDENT |
| .sp |
| The following cache variables are also available to set or use: |
| .INDENT 0.0 |
| .TP |
| .B \fBBacktrace_LIBRARY\fP |
| The external library providing backtrace, if any. |
| .TP |
| .B \fBBacktrace_INCLUDE_DIR\fP |
| The directory holding the \fBbacktrace(3)\fP header. |
| .UNINDENT |
| .sp |
| Typical usage is to generate of header file using \fBconfigure_file()\fP |
| with the contents like the following: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| #cmakedefine01 Backtrace_FOUND |
| #if Backtrace_FOUND |
| # include <${Backtrace_HEADER}> |
| #endif |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| And then reference that generated header file in actual source. |
| .SS FindBISON |
| .sp |
| Find \fBbison\fP executable and provide a macro to generate custom build rules. |
| .sp |
| The module defines the following variables: |
| .INDENT 0.0 |
| .TP |
| .B \fBBISON_EXECUTABLE\fP |
| path to the \fBbison\fP program |
| .TP |
| .B \fBBISON_VERSION\fP |
| version of \fBbison\fP |
| .TP |
| .B \fBBISON_FOUND\fP |
| "True" if the program was found |
| .UNINDENT |
| .sp |
| The minimum required version of \fBbison\fP can be specified using the |
| standard CMake syntax, e.g. \fBfind_package(BISON 2.1.3)\fP\&. |
| .sp |
| If \fBbison\fP is found, the module defines the macro: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| BISON_TARGET(<Name> <YaccInput> <CodeOutput> |
| [COMPILE_FLAGS <flags>] |
| [DEFINES_FILE <file>] |
| [VERBOSE [<file>]] |
| [REPORT_FILE <file>] |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| which will create a custom rule to generate a parser. \fB<YaccInput>\fP is |
| the path to a yacc file. \fB<CodeOutput>\fP is the name of the source file |
| generated by bison. A header file is also be generated, and contains |
| the token list. |
| .sp |
| Changed in version 3.14: When \fBCMP0088\fP is set to \fBNEW\fP, \fBbison\fP runs in the |
| \fBCMAKE_CURRENT_BINARY_DIR\fP directory. |
| |
| .sp |
| The options are: |
| .INDENT 0.0 |
| .TP |
| .B \fBCOMPILE_FLAGS <flags>\fP |
| Specify flags to be added to the \fBbison\fP command line. |
| .TP |
| .B \fBDEFINES_FILE <file>\fP |
| New in version 3.4. |
| |
| .sp |
| Specify a non\-default header \fB<file>\fP to be generated by \fBbison\fP\&. |
| .TP |
| .B \fBVERBOSE [<file>]\fP |
| Tell \fBbison\fP to write a report file of the grammar and parser. |
| .sp |
| Deprecated since version 3.7: If \fB<file>\fP is given, it specifies path the report file is copied to. |
| \fB[<file>]\fP is left for backward compatibility of this module. |
| Use \fBVERBOSE REPORT_FILE <file>\fP\&. |
| |
| .TP |
| .B \fBREPORT_FILE <file>\fP |
| New in version 3.7. |
| |
| .sp |
| Specify a non\-default report \fB<file>\fP, if generated. |
| .UNINDENT |
| .sp |
| The macro defines the following variables: |
| .INDENT 0.0 |
| .TP |
| .B \fBBISON_<Name>_DEFINED\fP |
| \fBTrue\fP is the macro ran successfully |
| .TP |
| .B \fBBISON_<Name>_INPUT\fP |
| The input source file, an alias for <YaccInput> |
| .TP |
| .B \fBBISON_<Name>_OUTPUT_SOURCE\fP |
| The source file generated by bison |
| .TP |
| .B \fBBISON_<Name>_OUTPUT_HEADER\fP |
| The header file generated by bison |
| .TP |
| .B \fBBISON_<Name>_OUTPUTS\fP |
| All files generated by bison including the source, the header and the report |
| .TP |
| .B \fBBISON_<Name>_COMPILE_FLAGS\fP |
| Options used in the \fBbison\fP command line |
| .UNINDENT |
| .sp |
| Example usage: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_package(BISON) |
| BISON_TARGET(MyParser parser.y ${CMAKE_CURRENT_BINARY_DIR}/parser.cpp |
| DEFINES_FILE ${CMAKE_CURRENT_BINARY_DIR}/parser.h) |
| add_executable(Foo main.cpp ${BISON_MyParser_OUTPUTS}) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindBLAS |
| .sp |
| Find Basic Linear Algebra Subprograms (BLAS) library |
| .sp |
| This module finds an installed Fortran library that implements the |
| \fI\%BLAS linear\-algebra interface\fP\&. |
| .sp |
| At least one of the \fBC\fP, \fBCXX\fP, or \fBFortran\fP languages must be enabled. |
| .SS Input Variables |
| .sp |
| The following variables may be set to influence this module\(aqs behavior: |
| .INDENT 0.0 |
| .TP |
| .B \fBBLA_STATIC\fP |
| if \fBON\fP use static linkage |
| .TP |
| .B \fBBLA_VENDOR\fP |
| Set to one of the \fI\%BLAS/LAPACK Vendors\fP to search for BLAS only |
| from the specified vendor. If not set, all vendors are considered. |
| .TP |
| .B \fBBLA_F95\fP |
| if \fBON\fP tries to find the BLAS95 interfaces |
| .TP |
| .B \fBBLA_PREFER_PKGCONFIG\fP |
| New in version 3.11. |
| |
| .sp |
| if set \fBpkg\-config\fP will be used to search for a BLAS library first |
| and if one is found that is preferred |
| .TP |
| .B \fBBLA_SIZEOF_INTEGER\fP |
| New in version 3.22. |
| |
| .sp |
| Specify the BLAS/LAPACK library integer size: |
| .INDENT 7.0 |
| .TP |
| .B \fB4\fP |
| Search for a BLAS/LAPACK with 32\-bit integer interfaces. |
| .TP |
| .B \fB8\fP |
| Search for a BLAS/LAPACK with 64\-bit integer interfaces. |
| .TP |
| .B \fBANY\fP |
| Search for any BLAS/LAPACK. |
| Most likely, a BLAS/LAPACK with 32\-bit integer interfaces will be found. |
| .UNINDENT |
| .UNINDENT |
| .SS Imported targets |
| .sp |
| This module defines the following \fBIMPORTED\fP targets: |
| .INDENT 0.0 |
| .TP |
| .B \fBBLAS::BLAS\fP |
| New in version 3.18. |
| |
| .sp |
| The libraries to use for BLAS, if found. |
| .UNINDENT |
| .SS Result Variables |
| .sp |
| This module defines the following variables: |
| .INDENT 0.0 |
| .TP |
| .B \fBBLAS_FOUND\fP |
| library implementing the BLAS interface is found |
| .TP |
| .B \fBBLAS_LINKER_FLAGS\fP |
| uncached list of required linker flags (excluding \fB\-l\fP and \fB\-L\fP). |
| .TP |
| .B \fBBLAS_LIBRARIES\fP |
| uncached list of libraries (using full path name) to link against |
| to use BLAS (may be empty if compiler implicitly links BLAS) |
| .TP |
| .B \fBBLAS95_LIBRARIES\fP |
| uncached list of libraries (using full path name) to link against |
| to use BLAS95 interface |
| .TP |
| .B \fBBLAS95_FOUND\fP |
| library implementing the BLAS95 interface is found |
| .UNINDENT |
| .SS BLAS/LAPACK Vendors |
| .INDENT 0.0 |
| .TP |
| .B \fBGeneric\fP |
| Generic reference implementation |
| .TP |
| .B \fBACML\fP, \fBACML_MP\fP, \fBACML_GPU\fP |
| AMD Core Math Library |
| .TP |
| .B \fBApple\fP, \fBNAS\fP |
| Apple BLAS (Accelerate), and Apple NAS (vecLib) |
| .TP |
| .B \fBArm\fP, \fBArm_mp\fP, \fBArm_ilp64\fP, \fBArm_ilp64_mp\fP |
| New in version 3.18. |
| |
| .sp |
| Arm Performance Libraries |
| .TP |
| .B \fBATLAS\fP |
| Automatically Tuned Linear Algebra Software |
| .TP |
| .B \fBCXML\fP, \fBDXML\fP |
| Compaq/Digital Extended Math Library |
| .TP |
| .B \fBEML\fP, \fBEML_mt\fP |
| New in version 3.20. |
| |
| .sp |
| Elbrus Math Library |
| .TP |
| .B \fBFLAME\fP |
| New in version 3.11. |
| |
| .sp |
| BLIS Framework |
| .TP |
| .B \fBFlexiBLAS\fP |
| New in version 3.19. |
| |
| .TP |
| .B \fBFujitsu_SSL2\fP, \fBFujitsu_SSL2BLAMP\fP, \fBFujitsu_SSL2SVE\fP, \fBFujitsu_SSL2BLAMPSVE\fP |
| New in version 3.20. |
| |
| .sp |
| Fujitsu SSL2 serial and parallel blas/lapack with SVE instructions |
| .TP |
| .B \fBGoto\fP |
| GotoBLAS |
| .UNINDENT |
| .sp |
| \fBIBMESSL\fP, \fBIBMESSL_SMP\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| IBM Engineering and Scientific Subroutine Library |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B \fBIntel\fP |
| Intel MKL 32 bit and 64 bit obsolete versions |
| .TP |
| .B \fBIntel10_32\fP |
| Intel MKL v10 32 bit, threaded code |
| .TP |
| .B \fBIntel10_64lp\fP |
| Intel MKL v10+ 64 bit, threaded code, lp64 model |
| .TP |
| .B \fBIntel10_64lp_seq\fP |
| Intel MKL v10+ 64 bit, sequential code, lp64 model |
| .TP |
| .B \fBIntel10_64ilp\fP |
| New in version 3.13. |
| |
| .sp |
| Intel MKL v10+ 64 bit, threaded code, ilp64 model |
| .TP |
| .B \fBIntel10_64ilp_seq\fP |
| New in version 3.13. |
| |
| .sp |
| Intel MKL v10+ 64 bit, sequential code, ilp64 model |
| .TP |
| .B \fBIntel10_64_dyn\fP |
| New in version 3.17. |
| |
| .sp |
| Intel MKL v10+ 64 bit, single dynamic library |
| .TP |
| .B \fBNVHPC\fP |
| New in version 3.21. |
| |
| .sp |
| NVIDIA HPC SDK |
| .TP |
| .B \fBOpenBLAS\fP |
| New in version 3.6. |
| |
| .TP |
| .B \fBPhiPACK\fP |
| Portable High Performance ANSI C (PHiPAC) |
| .TP |
| .B \fBSCSL\fP, \fBSCSL_mp\fP |
| Scientific Computing Software Library |
| .TP |
| .B \fBSGIMATH\fP |
| SGI Scientific Mathematical Library |
| .TP |
| .B \fBSunPerf\fP |
| Sun Performance Library |
| .UNINDENT |
| .SS Intel MKL |
| .sp |
| To use the Intel MKL implementation of BLAS, a project must enable at least |
| one of the \fBC\fP or \fBCXX\fP languages. Set \fBBLA_VENDOR\fP to an Intel MKL |
| variant either on the command\-line as \fB\-DBLA_VENDOR=Intel10_64lp\fP or in |
| project code: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(BLA_VENDOR Intel10_64lp) |
| find_package(BLAS) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| In order to build a project using Intel MKL, and end user must first |
| establish an Intel MKL environment: |
| .INDENT 0.0 |
| .TP |
| .B Intel oneAPI |
| Source the full Intel environment script: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| \&. /opt/intel/oneapi/setvars.sh |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Or, source the MKL component environment script: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| \&. /opt/intel/oneapi/mkl/latest/env/vars.sh |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .TP |
| .B Intel Classic |
| Source the full Intel environment script: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| \&. /opt/intel/bin/compilervars.sh intel64 |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Or, source the MKL component environment script: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| \&. /opt/intel/mkl/bin/mklvars.sh intel64 |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The above environment scripts set the \fBMKLROOT\fP environment variable |
| to the top of the MKL installation. They also add the location of the |
| runtime libraries to the dynamic library loader environment variable for |
| your platform (e.g. \fBLD_LIBRARY_PATH\fP). This is necessary for programs |
| linked against MKL to run. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| As of Intel oneAPI 2021.2, loading only the MKL component does not |
| make all of its dependencies available. In particular, the \fBiomp5\fP |
| library must be available separately, or provided by also loading |
| the compiler component environment: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| \&. /opt/intel/oneapi/compiler/latest/env/vars.sh |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .SS FindBoost |
| .sp |
| Find Boost include dirs and libraries |
| .sp |
| Use this module by invoking \fBfind_package()\fP with the form: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_package(Boost |
| [version] [EXACT] # Minimum or EXACT version e.g. 1.67.0 |
| [REQUIRED] # Fail with error if Boost is not found |
| [COMPONENTS <libs>...] # Boost libraries by their canonical name |
| # e.g. "date_time" for "libboost_date_time" |
| [OPTIONAL_COMPONENTS <libs>...] |
| # Optional Boost libraries by their canonical name) |
| ) # e.g. "date_time" for "libboost_date_time" |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This module finds headers and requested component libraries OR a CMake |
| package configuration file provided by a "Boost CMake" build. For the |
| latter case skip to the \fI\%Boost CMake\fP section below. |
| .sp |
| New in version 3.7: \fBbzip2\fP and \fBzlib\fP components (Windows only). |
| |
| .sp |
| New in version 3.11: The \fBOPTIONAL_COMPONENTS\fP option. |
| |
| .sp |
| New in version 3.13: \fBstacktrace_*\fP components. |
| |
| .sp |
| New in version 3.19: \fBbzip2\fP and \fBzlib\fP components on all platforms. |
| |
| .SS Result Variables |
| .sp |
| This module defines the following variables: |
| .INDENT 0.0 |
| .TP |
| .B \fBBoost_FOUND\fP |
| True if headers and requested libraries were found. |
| .TP |
| .B \fBBoost_INCLUDE_DIRS\fP |
| Boost include directories. |
| .TP |
| .B \fBBoost_LIBRARY_DIRS\fP |
| Link directories for Boost libraries. |
| .TP |
| .B \fBBoost_LIBRARIES\fP |
| Boost component libraries to be linked. |
| .TP |
| .B \fBBoost_<COMPONENT>_FOUND\fP |
| True if component \fB<COMPONENT>\fP was found (\fB<COMPONENT>\fP name is upper\-case). |
| .TP |
| .B \fBBoost_<COMPONENT>_LIBRARY\fP |
| Libraries to link for component \fB<COMPONENT>\fP (may include |
| \fBtarget_link_libraries()\fP debug/optimized keywords). |
| .TP |
| .B \fBBoost_VERSION_MACRO\fP |
| \fBBOOST_VERSION\fP value from \fBboost/version.hpp\fP\&. |
| .TP |
| .B \fBBoost_VERSION_STRING\fP |
| Boost version number in \fBX.Y.Z\fP format. |
| .TP |
| .B \fBBoost_VERSION\fP |
| Boost version number in \fBX.Y.Z\fP format (same as \fBBoost_VERSION_STRING\fP). |
| .sp |
| Changed in version 3.15: In previous CMake versions, this variable used the raw version string |
| from the Boost header (same as \fBBoost_VERSION_MACRO\fP). |
| See policy \fBCMP0093\fP\&. |
| |
| .TP |
| .B \fBBoost_LIB_VERSION\fP |
| Version string appended to library filenames. |
| .TP |
| .B \fBBoost_VERSION_MAJOR\fP, \fBBoost_MAJOR_VERSION\fP |
| Boost major version number (\fBX\fP in \fBX.Y.Z\fP). |
| .TP |
| .B \fBBoost_VERSION_MINOR\fP, \fBBoost_MINOR_VERSION\fP |
| Boost minor version number (\fBY\fP in \fBX.Y.Z\fP). |
| .TP |
| .B \fBBoost_VERSION_PATCH\fP, \fBBoost_SUBMINOR_VERSION\fP |
| Boost subminor version number (\fBZ\fP in \fBX.Y.Z\fP). |
| .TP |
| .B \fBBoost_VERSION_COUNT\fP |
| Amount of version components (3). |
| .TP |
| .B \fBBoost_LIB_DIAGNOSTIC_DEFINITIONS\fP (Windows\-specific) |
| Pass to \fBadd_definitions()\fP to have diagnostic |
| information about Boost\(aqs automatic linking |
| displayed during compilation |
| .UNINDENT |
| .sp |
| New in version 3.15: The \fBBoost_VERSION_<PART>\fP variables. |
| |
| .SS Cache variables |
| .sp |
| Search results are saved persistently in CMake cache entries: |
| .INDENT 0.0 |
| .TP |
| .B \fBBoost_INCLUDE_DIR\fP |
| Directory containing Boost headers. |
| .TP |
| .B \fBBoost_LIBRARY_DIR_RELEASE\fP |
| Directory containing release Boost libraries. |
| .TP |
| .B \fBBoost_LIBRARY_DIR_DEBUG\fP |
| Directory containing debug Boost libraries. |
| .TP |
| .B \fBBoost_<COMPONENT>_LIBRARY_DEBUG\fP |
| Component \fB<COMPONENT>\fP library debug variant. |
| .TP |
| .B \fBBoost_<COMPONENT>_LIBRARY_RELEASE\fP |
| Component \fB<COMPONENT>\fP library release variant. |
| .UNINDENT |
| .sp |
| New in version 3.3: Per\-configuration variables \fBBoost_LIBRARY_DIR_RELEASE\fP and |
| \fBBoost_LIBRARY_DIR_DEBUG\fP\&. |
| |
| .SS Hints |
| .sp |
| This module reads hints about search locations from variables: |
| .INDENT 0.0 |
| .TP |
| .B \fBBOOST_ROOT\fP, \fBBOOSTROOT\fP |
| Preferred installation prefix. |
| .TP |
| .B \fBBOOST_INCLUDEDIR\fP |
| Preferred include directory e.g. \fB<prefix>/include\fP\&. |
| .TP |
| .B \fBBOOST_LIBRARYDIR\fP |
| Preferred library directory e.g. \fB<prefix>/lib\fP\&. |
| .TP |
| .B \fBBoost_NO_SYSTEM_PATHS\fP |
| Set to \fBON\fP to disable searching in locations not |
| specified by these hint variables. Default is \fBOFF\fP\&. |
| .TP |
| .B \fBBoost_ADDITIONAL_VERSIONS\fP |
| List of Boost versions not known to this module. |
| (Boost install locations may contain the version). |
| .UNINDENT |
| .sp |
| Users may set these hints or results as \fBCACHE\fP entries. Projects |
| should not read these entries directly but instead use the above |
| result variables. Note that some hint names start in upper\-case |
| \fBBOOST\fP\&. One may specify these as environment variables if they are |
| not specified as CMake variables or cache entries. |
| .sp |
| This module first searches for the Boost header files using the above |
| hint variables (excluding \fBBOOST_LIBRARYDIR\fP) and saves the result in |
| \fBBoost_INCLUDE_DIR\fP\&. Then it searches for requested component libraries |
| using the above hints (excluding \fBBOOST_INCLUDEDIR\fP and |
| \fBBoost_ADDITIONAL_VERSIONS\fP), "lib" directories near \fBBoost_INCLUDE_DIR\fP, |
| and the library name configuration settings below. It saves the |
| library directories in \fBBoost_LIBRARY_DIR_DEBUG\fP and |
| \fBBoost_LIBRARY_DIR_RELEASE\fP and individual library |
| locations in \fBBoost_<COMPONENT>_LIBRARY_DEBUG\fP and \fBBoost_<COMPONENT>_LIBRARY_RELEASE\fP\&. |
| When one changes settings used by previous searches in the same build |
| tree (excluding environment variables) this module discards previous |
| search results affected by the changes and searches again. |
| .SS Imported Targets |
| .sp |
| New in version 3.5. |
| |
| .sp |
| This module defines the following \fBIMPORTED\fP targets: |
| .INDENT 0.0 |
| .TP |
| .B \fBBoost::boost\fP |
| Target for header\-only dependencies. (Boost include directory). |
| .TP |
| .B \fBBoost::headers\fP |
| New in version 3.15: Alias for \fBBoost::boost\fP\&. |
| |
| .TP |
| .B \fBBoost::<component>\fP |
| Target for specific component dependency (shared or static library); |
| \fB<component>\fP name is lower\-case. |
| .TP |
| .B \fBBoost::diagnostic_definitions\fP |
| Interface target to enable diagnostic information about Boost\(aqs automatic |
| linking during compilation (adds \fB\-DBOOST_LIB_DIAGNOSTIC\fP). |
| .TP |
| .B \fBBoost::disable_autolinking\fP |
| Interface target to disable automatic linking with MSVC |
| (adds \fB\-DBOOST_ALL_NO_LIB\fP). |
| .TP |
| .B \fBBoost::dynamic_linking\fP |
| Interface target to enable dynamic linking with MSVC |
| (adds \fB\-DBOOST_ALL_DYN_LINK\fP). |
| .UNINDENT |
| .sp |
| Implicit dependencies such as \fBBoost::filesystem\fP requiring |
| \fBBoost::system\fP will be automatically detected and satisfied, even |
| if system is not specified when using \fBfind_package()\fP and if |
| \fBBoost::system\fP is not added to \fBtarget_link_libraries()\fP\&. If using |
| \fBBoost::thread\fP, then \fBThreads::Threads\fP will also be added automatically. |
| .sp |
| It is important to note that the imported targets behave differently |
| than variables created by this module: multiple calls to |
| \fBfind_package(Boost)\fP in the same directory or sub\-directories with |
| different options (e.g. static or shared) will not override the |
| values of the targets created by the first call. |
| .SS Other Variables |
| .sp |
| Boost libraries come in many variants encoded in their file name. |
| Users or projects may tell this module which variant to find by |
| setting variables: |
| .INDENT 0.0 |
| .TP |
| .B \fBBoost_USE_DEBUG_LIBS\fP |
| New in version 3.10. |
| |
| .sp |
| Set to \fBON\fP or \fBOFF\fP to specify whether to search and use the debug |
| libraries. Default is \fBON\fP\&. |
| .TP |
| .B \fBBoost_USE_RELEASE_LIBS\fP |
| New in version 3.10. |
| |
| .sp |
| Set to \fBON\fP or \fBOFF\fP to specify whether to search and use the release |
| libraries. Default is \fBON\fP\&. |
| .TP |
| .B \fBBoost_USE_MULTITHREADED\fP |
| Set to OFF to use the non\-multithreaded libraries ("mt" tag). Default is |
| \fBON\fP\&. |
| .TP |
| .B \fBBoost_USE_STATIC_LIBS\fP |
| Set to ON to force the use of the static libraries. Default is \fBOFF\fP\&. |
| .TP |
| .B \fBBoost_USE_STATIC_RUNTIME\fP |
| Set to \fBON\fP or \fBOFF\fP to specify whether to use libraries linked |
| statically to the C++ runtime ("s" tag). Default is platform dependent. |
| .TP |
| .B \fBBoost_USE_DEBUG_RUNTIME\fP |
| Set to \fBON\fP or \fBOFF\fP to specify whether to use libraries linked to the |
| MS debug C++ runtime ("g" tag). Default is \fBON\fP\&. |
| .TP |
| .B \fBBoost_USE_DEBUG_PYTHON\fP |
| Set to \fBON\fP to use libraries compiled with a debug Python build ("y" |
| tag). Default is \fBOFF\fP\&. |
| .TP |
| .B \fBBoost_USE_STLPORT\fP |
| Set to \fBON\fP to use libraries compiled with STLPort ("p" tag). Default is |
| \fBOFF\fP\&. |
| .TP |
| .B \fBBoost_USE_STLPORT_DEPRECATED_NATIVE_IOSTREAMS\fP |
| Set to ON to use libraries compiled with STLPort deprecated "native |
| iostreams" ("n" tag). Default is \fBOFF\fP\&. |
| .TP |
| .B \fBBoost_COMPILER\fP |
| Set to the compiler\-specific library suffix (e.g. \fB\-gcc43\fP). Default is |
| auto\-computed for the C++ compiler in use. |
| .sp |
| Changed in version 3.9: A list may be used if multiple compatible suffixes should be tested for, |
| in decreasing order of preference. |
| |
| .TP |
| .B \fBBoost_LIB_PREFIX\fP |
| New in version 3.18. |
| |
| .sp |
| Set to the platform\-specific library name prefix (e.g. \fBlib\fP) used by |
| Boost static libs. This is needed only on platforms where CMake does not |
| know the prefix by default. |
| .TP |
| .B \fBBoost_ARCHITECTURE\fP |
| New in version 3.13. |
| |
| .sp |
| Set to the architecture\-specific library suffix (e.g. \fB\-x64\fP). |
| Default is auto\-computed for the C++ compiler in use. |
| .TP |
| .B \fBBoost_THREADAPI\fP |
| Suffix for \fBthread\fP component library name, such as \fBpthread\fP or |
| \fBwin32\fP\&. Names with and without this suffix will both be tried. |
| .TP |
| .B \fBBoost_NAMESPACE\fP |
| Alternate namespace used to build boost with e.g. if set to \fBmyboost\fP, |
| will search for \fBmyboost_thread\fP instead of \fBboost_thread\fP\&. |
| .UNINDENT |
| .sp |
| Other variables one may set to control this module are: |
| .INDENT 0.0 |
| .TP |
| .B \fBBoost_DEBUG\fP |
| Set to \fBON\fP to enable debug output from \fBFindBoost\fP\&. |
| Please enable this before filing any bug report. |
| .TP |
| .B \fBBoost_REALPATH\fP |
| Set to \fBON\fP to resolve symlinks for discovered libraries to assist with |
| packaging. For example, the "system" component library may be resolved to |
| \fB/usr/lib/libboost_system.so.1.67.0\fP instead of |
| \fB/usr/lib/libboost_system.so\fP\&. This does not affect linking and should |
| not be enabled unless the user needs this information. |
| .TP |
| .B \fBBoost_LIBRARY_DIR\fP |
| Default value for \fBBoost_LIBRARY_DIR_RELEASE\fP and |
| \fBBoost_LIBRARY_DIR_DEBUG\fP\&. |
| .TP |
| .B \fBBoost_NO_WARN_NEW_VERSIONS\fP |
| New in version 3.20. |
| |
| .sp |
| Set to \fBON\fP to suppress the warning about unknown dependencies for new |
| Boost versions. |
| .UNINDENT |
| .sp |
| On Visual Studio and Borland compilers Boost headers request automatic |
| linking to corresponding libraries. This requires matching libraries |
| to be linked explicitly or available in the link library search path. |
| In this case setting \fBBoost_USE_STATIC_LIBS\fP to \fBOFF\fP may not achieve |
| dynamic linking. Boost automatic linking typically requests static |
| libraries with a few exceptions (such as \fBBoost.Python\fP). Use: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_definitions(${Boost_LIB_DIAGNOSTIC_DEFINITIONS}) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| to ask Boost to report information about automatic linking requests. |
| .SS Examples |
| .sp |
| Find Boost headers only: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_package(Boost 1.36.0) |
| if(Boost_FOUND) |
| include_directories(${Boost_INCLUDE_DIRS}) |
| add_executable(foo foo.cc) |
| endif() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Find Boost libraries and use imported targets: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_package(Boost 1.56 REQUIRED COMPONENTS |
| date_time filesystem iostreams) |
| add_executable(foo foo.cc) |
| target_link_libraries(foo Boost::date_time Boost::filesystem |
| Boost::iostreams) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Find Boost Python 3.6 libraries and use imported targets: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_package(Boost 1.67 REQUIRED COMPONENTS |
| python36 numpy36) |
| add_executable(foo foo.cc) |
| target_link_libraries(foo Boost::python36 Boost::numpy36) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Find Boost headers and some \fIstatic\fP (release only) libraries: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(Boost_USE_STATIC_LIBS ON) # only find static libs |
| set(Boost_USE_DEBUG_LIBS OFF) # ignore debug libs and |
| set(Boost_USE_RELEASE_LIBS ON) # only find release libs |
| set(Boost_USE_MULTITHREADED ON) |
| set(Boost_USE_STATIC_RUNTIME OFF) |
| find_package(Boost 1.66.0 COMPONENTS date_time filesystem system ...) |
| if(Boost_FOUND) |
| include_directories(${Boost_INCLUDE_DIRS}) |
| add_executable(foo foo.cc) |
| target_link_libraries(foo ${Boost_LIBRARIES}) |
| endif() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS Boost CMake |
| .sp |
| If Boost was built using the boost\-cmake project or from Boost 1.70.0 on |
| it provides a package configuration file for use with find_package\(aqs config mode. |
| This module looks for the package configuration file called |
| \fBBoostConfig.cmake\fP or \fBboost\-config.cmake\fP and stores the result in |
| \fBCACHE\fP entry \fBBoost_DIR\fP\&. If found, the package configuration file is loaded |
| and this module returns with no further action. See documentation of |
| the Boost CMake package configuration for details on what it provides. |
| .sp |
| Set \fBBoost_NO_BOOST_CMAKE\fP to \fBON\fP, to disable the search for boost\-cmake. |
| .SS FindBullet |
| .sp |
| Try to find the Bullet physics engine |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| This module defines the following variables |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| BULLET_FOUND \- Was bullet found |
| BULLET_INCLUDE_DIRS \- the Bullet include directories |
| BULLET_LIBRARIES \- Link to this, by default it includes |
| all bullet components (Dynamics, |
| Collision, LinearMath, & SoftBody) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| This module accepts the following variables |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| BULLET_ROOT \- Can be set to bullet install path or Windows build path |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindBZip2 |
| .sp |
| Try to find BZip2 |
| .SS IMPORTED Targets |
| .sp |
| New in version 3.12. |
| |
| .sp |
| This module defines \fBIMPORTED\fP target \fBBZip2::BZip2\fP, if |
| BZip2 has been found. |
| .SS Result Variables |
| .sp |
| This module defines the following variables: |
| .INDENT 0.0 |
| .TP |
| .B \fBBZIP2_FOUND\fP |
| system has BZip2 |
| .TP |
| .B \fBBZIP2_INCLUDE_DIRS\fP |
| New in version 3.12: the BZip2 include directories |
| |
| .TP |
| .B \fBBZIP2_LIBRARIES\fP |
| Link these to use BZip2 |
| .TP |
| .B \fBBZIP2_NEED_PREFIX\fP |
| this is set if the functions are prefixed with \fBBZ2_\fP |
| .TP |
| .B \fBBZIP2_VERSION_STRING\fP |
| the version of BZip2 found |
| .UNINDENT |
| .SS Cache variables |
| .sp |
| The following cache variables may also be set: |
| .INDENT 0.0 |
| .TP |
| .B \fBBZIP2_INCLUDE_DIR\fP |
| the BZip2 include directory |
| .UNINDENT |
| .SS FindCABLE |
| .sp |
| Find CABLE |
| .sp |
| This module finds if CABLE is installed and determines where the |
| include files and libraries are. This code sets the following |
| variables: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| CABLE the path to the cable executable |
| CABLE_TCL_LIBRARY the path to the Tcl wrapper library |
| CABLE_INCLUDE_DIR the path to the include directory |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| To build Tcl wrappers, you should add shared library and link it to |
| ${CABLE_TCL_LIBRARY}. You should also add ${CABLE_INCLUDE_DIR} as an |
| include directory. |
| .SS FindCoin3D |
| .sp |
| Find Coin3D (Open Inventor) |
| .sp |
| Coin3D is an implementation of the Open Inventor API. It provides |
| data structures and algorithms for 3D visualization. |
| .sp |
| This module defines the following variables |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| COIN3D_FOUND \- system has Coin3D \- Open Inventor |
| COIN3D_INCLUDE_DIRS \- where the Inventor include directory can be found |
| COIN3D_LIBRARIES \- Link to this to use Coin3D |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindCUDAToolkit |
| .sp |
| New in version 3.17. |
| |
| .sp |
| This script locates the NVIDIA CUDA toolkit and the associated libraries, but |
| does not require the \fBCUDA\fP language be enabled for a given project. This |
| module does not search for the NVIDIA CUDA Samples. |
| .sp |
| New in version 3.19: QNX support. |
| |
| .SS Search Behavior |
| .sp |
| The CUDA Toolkit search behavior uses the following order: |
| .INDENT 0.0 |
| .IP 1. 3 |
| If the \fBCUDA\fP language has been enabled we will use the directory |
| containing the compiler as the first search location for \fBnvcc\fP\&. |
| .IP 2. 3 |
| If the \fBCUDAToolkit_ROOT\fP cmake configuration variable (e.g., |
| \fB\-DCUDAToolkit_ROOT=/some/path\fP) \fIor\fP environment variable is defined, it |
| will be searched. If both an environment variable \fBand\fP a |
| configuration variable are specified, the \fIconfiguration\fP variable takes |
| precedence. |
| .sp |
| The directory specified here must be such that the executable \fBnvcc\fP or |
| the appropriate \fBversion.txt\fP file can be found underneath the specified |
| directory. |
| .IP 3. 3 |
| If the CUDA_PATH environment variable is defined, it will be searched |
| for \fBnvcc\fP\&. |
| .IP 4. 3 |
| The user\(aqs path is searched for \fBnvcc\fP using \fBfind_program()\fP\&. If |
| this is found, no subsequent search attempts are performed. Users are |
| responsible for ensuring that the first \fBnvcc\fP to show up in the path is |
| the desired path in the event that multiple CUDA Toolkits are installed. |
| .IP 5. 3 |
| On Unix systems, if the symbolic link \fB/usr/local/cuda\fP exists, this is |
| used. No subsequent search attempts are performed. No default symbolic link |
| location exists for the Windows platform. |
| .IP 6. 3 |
| The platform specific default install locations are searched. If exactly one |
| candidate is found, this is used. The default CUDA Toolkit install locations |
| searched are: |
| .TS |
| center; |
| |l|l|. |
| _ |
| T{ |
| Platform |
| T} T{ |
| Search Pattern |
| T} |
| _ |
| T{ |
| macOS |
| T} T{ |
| \fB/Developer/NVIDIA/CUDA\-X.Y\fP |
| T} |
| _ |
| T{ |
| Other Unix |
| T} T{ |
| \fB/usr/local/cuda\-X.Y\fP |
| T} |
| _ |
| T{ |
| Windows |
| T} T{ |
| \fBC:\eProgram Files\eNVIDIA GPU Computing Toolkit\eCUDA\evX.Y\fP |
| T} |
| _ |
| .TE |
| .sp |
| Where \fBX.Y\fP would be a specific version of the CUDA Toolkit, such as |
| \fB/usr/local/cuda\-9.0\fP or |
| \fBC:\eProgram Files\eNVIDIA GPU Computing Toolkit\eCUDA\ev9.0\fP |
| .sp |
| \fBNOTE:\fP |
| .INDENT 3.0 |
| .INDENT 3.5 |
| When multiple CUDA Toolkits are installed in the default location of a |
| system (e.g., both \fB/usr/local/cuda\-9.0\fP and \fB/usr/local/cuda\-10.0\fP |
| exist but the \fB/usr/local/cuda\fP symbolic link does \fBnot\fP exist), this |
| package is marked as \fBnot\fP found. |
| .sp |
| There are too many factors involved in making an automatic decision in |
| the presence of multiple CUDA Toolkits being installed. In this |
| situation, users are encouraged to either (1) set \fBCUDAToolkit_ROOT\fP or |
| (2) ensure that the correct \fBnvcc\fP executable shows up in \fB$PATH\fP for |
| \fBfind_program()\fP to find. |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .SS Arguments |
| .INDENT 0.0 |
| .TP |
| .B \fB[<version>]\fP |
| The \fB[<version>]\fP argument requests a version with which the package found |
| should be compatible. See find_package version format |
| for more details. |
| .UNINDENT |
| .SS Options |
| .INDENT 0.0 |
| .TP |
| .B \fBREQUIRED\fP |
| If specified, configuration will error if a suitable CUDA Toolkit is not |
| found. |
| .TP |
| .B \fBQUIET\fP |
| If specified, the search for a suitable CUDA Toolkit will not produce any |
| messages. |
| .TP |
| .B \fBEXACT\fP |
| If specified, the CUDA Toolkit is considered found only if the exact |
| \fBVERSION\fP specified is recovered. |
| .UNINDENT |
| .SS Imported targets |
| .sp |
| An imported target named \fBCUDA::toolkit\fP is provided. |
| .sp |
| This module defines \fBIMPORTED\fP targets for each |
| of the following libraries that are part of the CUDAToolkit: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fI\%CUDA Runtime Library\fP |
| .IP \(bu 2 |
| \fI\%CUDA Driver Library\fP |
| .IP \(bu 2 |
| \fI\%cuBLAS\fP |
| .IP \(bu 2 |
| \fI\%cuFFT\fP |
| .IP \(bu 2 |
| \fI\%cuRAND\fP |
| .IP \(bu 2 |
| \fI\%cuSOLVER\fP |
| .IP \(bu 2 |
| \fI\%cuSPARSE\fP |
| .IP \(bu 2 |
| \fI\%cuPTI\fP |
| .IP \(bu 2 |
| \fI\%NPP\fP |
| .IP \(bu 2 |
| \fI\%nvBLAS\fP |
| .IP \(bu 2 |
| \fI\%nvGRAPH\fP |
| .IP \(bu 2 |
| \fI\%nvJPEG\fP |
| .IP \(bu 2 |
| \fI\%nvidia\-ML\fP |
| .IP \(bu 2 |
| \fI\%nvRTC\fP |
| .IP \(bu 2 |
| \fI\%nvToolsExt\fP |
| .IP \(bu 2 |
| \fI\%OpenCL\fP |
| .IP \(bu 2 |
| \fI\%cuLIBOS\fP |
| .UNINDENT |
| .SS CUDA Runtime Library |
| .sp |
| The CUDA Runtime library (cudart) are what most applications will typically |
| need to link against to make any calls such as \fIcudaMalloc\fP, and \fIcudaFree\fP\&. |
| .sp |
| Targets Created: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBCUDA::cudart\fP |
| .IP \(bu 2 |
| \fBCUDA::cudart_static\fP |
| .UNINDENT |
| .SS CUDA Driver Library |
| .sp |
| The CUDA Driver library (cuda) are used by applications that use calls |
| such as \fIcuMemAlloc\fP, and \fIcuMemFree\fP\&. |
| .sp |
| Targets Created: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBCUDA::cuda_driver\fP |
| .UNINDENT |
| .SS cuBLAS |
| .sp |
| The \fI\%cuBLAS\fP library. |
| .sp |
| Targets Created: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBCUDA::cublas\fP |
| .IP \(bu 2 |
| \fBCUDA::cublas_static\fP |
| .IP \(bu 2 |
| \fBCUDA::cublasLt\fP starting in CUDA 10.1 |
| .IP \(bu 2 |
| \fBCUDA::cublasLt_static\fP starting in CUDA 10.1 |
| .UNINDENT |
| .SS cuFFT |
| .sp |
| The \fI\%cuFFT\fP library. |
| .sp |
| Targets Created: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBCUDA::cufft\fP |
| .IP \(bu 2 |
| \fBCUDA::cufftw\fP |
| .IP \(bu 2 |
| \fBCUDA::cufft_static\fP |
| .IP \(bu 2 |
| \fBCUDA::cufft_static_nocallback\fP starting in CUDA 9.2, requires CMake 3.23+ |
| .IP \(bu 2 |
| \fBCUDA::cufftw_static\fP |
| .UNINDENT |
| .SS cuRAND |
| .sp |
| The \fI\%cuRAND\fP library. |
| .sp |
| Targets Created: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBCUDA::curand\fP |
| .IP \(bu 2 |
| \fBCUDA::curand_static\fP |
| .UNINDENT |
| .SS cuSOLVER |
| .sp |
| The \fI\%cuSOLVER\fP library. |
| .sp |
| Targets Created: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBCUDA::cusolver\fP |
| .IP \(bu 2 |
| \fBCUDA::cusolver_static\fP |
| .UNINDENT |
| .SS cuSPARSE |
| .sp |
| The \fI\%cuSPARSE\fP library. |
| .sp |
| Targets Created: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBCUDA::cusparse\fP |
| .IP \(bu 2 |
| \fBCUDA::cusparse_static\fP |
| .UNINDENT |
| .SS cupti |
| .sp |
| The \fI\%NVIDIA CUDA Profiling Tools Interface\fP\&. |
| .sp |
| Targets Created: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBCUDA::cupti\fP |
| .IP \(bu 2 |
| \fBCUDA::cupti_static\fP |
| .UNINDENT |
| .SS NPP |
| .sp |
| The \fI\%NPP\fP libraries. |
| .sp |
| Targets Created: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fInppc\fP: |
| .INDENT 2.0 |
| .IP \(bu 2 |
| \fBCUDA::nppc\fP |
| .IP \(bu 2 |
| \fBCUDA::nppc_static\fP |
| .UNINDENT |
| .IP \(bu 2 |
| \fInppial\fP: Arithmetic and logical operation functions in \fInppi_arithmetic_and_logical_operations.h\fP |
| .INDENT 2.0 |
| .IP \(bu 2 |
| \fBCUDA::nppial\fP |
| .IP \(bu 2 |
| \fBCUDA::nppial_static\fP |
| .UNINDENT |
| .IP \(bu 2 |
| \fInppicc\fP: Color conversion and sampling functions in \fInppi_color_conversion.h\fP |
| .INDENT 2.0 |
| .IP \(bu 2 |
| \fBCUDA::nppicc\fP |
| .IP \(bu 2 |
| \fBCUDA::nppicc_static\fP |
| .UNINDENT |
| .IP \(bu 2 |
| \fInppicom\fP: JPEG compression and decompression functions in \fInppi_compression_functions.h\fP |
| Removed starting in CUDA 11.0, use \fI\%nvJPEG\fP instead. |
| .INDENT 2.0 |
| .IP \(bu 2 |
| \fBCUDA::nppicom\fP |
| .IP \(bu 2 |
| \fBCUDA::nppicom_static\fP |
| .UNINDENT |
| .IP \(bu 2 |
| \fInppidei\fP: Data exchange and initialization functions in \fInppi_data_exchange_and_initialization.h\fP |
| .INDENT 2.0 |
| .IP \(bu 2 |
| \fBCUDA::nppidei\fP |
| .IP \(bu 2 |
| \fBCUDA::nppidei_static\fP |
| .UNINDENT |
| .IP \(bu 2 |
| \fInppif\fP: Filtering and computer vision functions in \fInppi_filter_functions.h\fP |
| .INDENT 2.0 |
| .IP \(bu 2 |
| \fBCUDA::nppif\fP |
| .IP \(bu 2 |
| \fBCUDA::nppif_static\fP |
| .UNINDENT |
| .IP \(bu 2 |
| \fInppig\fP: Geometry transformation functions found in \fInppi_geometry_transforms.h\fP |
| .INDENT 2.0 |
| .IP \(bu 2 |
| \fBCUDA::nppig\fP |
| .IP \(bu 2 |
| \fBCUDA::nppig_static\fP |
| .UNINDENT |
| .IP \(bu 2 |
| \fInppim\fP: Morphological operation functions found in \fInppi_morphological_operations.h\fP |
| .INDENT 2.0 |
| .IP \(bu 2 |
| \fBCUDA::nppim\fP |
| .IP \(bu 2 |
| \fBCUDA::nppim_static\fP |
| .UNINDENT |
| .IP \(bu 2 |
| \fInppist\fP: Statistics and linear transform in \fInppi_statistics_functions.h\fP and \fInppi_linear_transforms.h\fP |
| .INDENT 2.0 |
| .IP \(bu 2 |
| \fBCUDA::nppist\fP |
| .IP \(bu 2 |
| \fBCUDA::nppist_static\fP |
| .UNINDENT |
| .IP \(bu 2 |
| \fInppisu\fP: Memory support functions in \fInppi_support_functions.h\fP |
| .INDENT 2.0 |
| .IP \(bu 2 |
| \fBCUDA::nppisu\fP |
| .IP \(bu 2 |
| \fBCUDA::nppisu_static\fP |
| .UNINDENT |
| .IP \(bu 2 |
| \fInppitc\fP: Threshold and compare operation functions in \fInppi_threshold_and_compare_operations.h\fP |
| .INDENT 2.0 |
| .IP \(bu 2 |
| \fBCUDA::nppitc\fP |
| .IP \(bu 2 |
| \fBCUDA::nppitc_static\fP |
| .UNINDENT |
| .IP \(bu 2 |
| \fInpps\fP: |
| .INDENT 2.0 |
| .IP \(bu 2 |
| \fBCUDA::npps\fP |
| .IP \(bu 2 |
| \fBCUDA::npps_static\fP |
| .UNINDENT |
| .UNINDENT |
| .SS nvBLAS |
| .sp |
| The \fI\%nvBLAS\fP libraries. |
| This is a shared library only. |
| .sp |
| Targets Created: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBCUDA::nvblas\fP |
| .UNINDENT |
| .SS nvGRAPH |
| .sp |
| The \fI\%nvGRAPH\fP library. |
| Removed starting in CUDA 11.0 |
| .sp |
| Targets Created: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBCUDA::nvgraph\fP |
| .IP \(bu 2 |
| \fBCUDA::nvgraph_static\fP |
| .UNINDENT |
| .SS nvJPEG |
| .sp |
| The \fI\%nvJPEG\fP library. |
| Introduced in CUDA 10. |
| .sp |
| Targets Created: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBCUDA::nvjpeg\fP |
| .IP \(bu 2 |
| \fBCUDA::nvjpeg_static\fP |
| .UNINDENT |
| .SS nvRTC |
| .sp |
| The \fI\%nvRTC\fP (Runtime Compilation) library. |
| This is a shared library only. |
| .sp |
| Targets Created: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBCUDA::nvrtc\fP |
| .UNINDENT |
| .SS nvidia\-ML |
| .sp |
| The \fI\%NVIDIA Management Library\fP\&. |
| This is a shared library only. |
| .sp |
| Targets Created: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBCUDA::nvml\fP |
| .UNINDENT |
| .SS nvToolsExt |
| .sp |
| The \fI\%NVIDIA Tools Extension\fP\&. |
| This is a shared library only. |
| .sp |
| Targets Created: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBCUDA::nvToolsExt\fP |
| .UNINDENT |
| .SS OpenCL |
| .sp |
| The \fI\%NVIDIA OpenCL Library\fP\&. |
| This is a shared library only. |
| .sp |
| Targets Created: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBCUDA::OpenCL\fP |
| .UNINDENT |
| .SS cuLIBOS |
| .sp |
| The cuLIBOS library is a backend thread abstraction layer library which is |
| static only. The \fBCUDA::cublas_static\fP, \fBCUDA::cusparse_static\fP, |
| \fBCUDA::cufft_static\fP, \fBCUDA::curand_static\fP, and (when implemented) NPP |
| libraries all automatically have this dependency linked. |
| .sp |
| Target Created: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBCUDA::culibos\fP |
| .UNINDENT |
| .sp |
| \fBNote\fP: direct usage of this target by consumers should not be necessary. |
| .SS Result variables |
| .INDENT 0.0 |
| .TP |
| .B \fBCUDAToolkit_FOUND\fP |
| A boolean specifying whether or not the CUDA Toolkit was found. |
| .TP |
| .B \fBCUDAToolkit_VERSION\fP |
| The exact version of the CUDA Toolkit found (as reported by |
| \fBnvcc \-\-version\fP or \fBversion.txt\fP). |
| .TP |
| .B \fBCUDAToolkit_VERSION_MAJOR\fP |
| The major version of the CUDA Toolkit. |
| .TP |
| .B \fBCUDAToolkit_VERSION_MINOR\fP |
| The minor version of the CUDA Toolkit. |
| .TP |
| .B \fBCUDAToolkit_VERSION_PATCH\fP |
| The patch version of the CUDA Toolkit. |
| .TP |
| .B \fBCUDAToolkit_BIN_DIR\fP |
| The path to the CUDA Toolkit library directory that contains the CUDA |
| executable \fBnvcc\fP\&. |
| .TP |
| .B \fBCUDAToolkit_INCLUDE_DIRS\fP |
| The path to the CUDA Toolkit \fBinclude\fP folder containing the header files |
| required to compile a project linking against CUDA. |
| .TP |
| .B \fBCUDAToolkit_LIBRARY_DIR\fP |
| The path to the CUDA Toolkit library directory that contains the CUDA |
| Runtime library \fBcudart\fP\&. |
| .TP |
| .B \fBCUDAToolkit_LIBRARY_ROOT\fP |
| New in version 3.18. |
| |
| .sp |
| The path to the CUDA Toolkit directory containing the nvvm directory and |
| version.txt. |
| .TP |
| .B \fBCUDAToolkit_TARGET_DIR\fP |
| The path to the CUDA Toolkit directory including the target architecture |
| when cross\-compiling. When not cross\-compiling this will be equivalent to |
| the parent directory of \fBCUDAToolkit_BIN_DIR\fP\&. |
| .TP |
| .B \fBCUDAToolkit_NVCC_EXECUTABLE\fP |
| The path to the NVIDIA CUDA compiler \fBnvcc\fP\&. Note that this path may |
| \fBnot\fP be the same as |
| \fBCMAKE_CUDA_COMPILER\fP\&. \fBnvcc\fP must be |
| found to determine the CUDA Toolkit version as well as determining other |
| features of the Toolkit. This variable is set for the convenience of |
| modules that depend on this one. |
| .UNINDENT |
| .SS FindCups |
| .sp |
| Find the Common UNIX Printing System (CUPS). |
| .sp |
| Set \fBCUPS_REQUIRE_IPP_DELETE_ATTRIBUTE\fP to \fBTRUE\fP if you need a version which |
| features this function (i.e. at least \fB1.1.19\fP) |
| .SS Imported targets |
| .sp |
| New in version 3.15. |
| |
| .sp |
| This module defines \fBIMPORTED\fP target \fBCups::Cups\fP, if Cups has |
| been found. |
| .SS Result variables |
| .sp |
| This module will set the following variables in your project: |
| .INDENT 0.0 |
| .TP |
| .B \fBCUPS_FOUND\fP |
| true if CUPS headers and libraries were found |
| .TP |
| .B \fBCUPS_INCLUDE_DIRS\fP |
| the directory containing the Cups headers |
| .TP |
| .B \fBCUPS_LIBRARIES\fP |
| the libraries to link against to use CUPS. |
| .TP |
| .B \fBCUPS_VERSION_STRING\fP |
| the version of CUPS found (since CMake 2.8.8) |
| .UNINDENT |
| .SS Cache variables |
| .sp |
| The following cache variables may also be set: |
| .INDENT 0.0 |
| .TP |
| .B \fBCUPS_INCLUDE_DIR\fP |
| the directory containing the Cups headers |
| .UNINDENT |
| .SS FindCURL |
| .sp |
| Find the native CURL headers and libraries. |
| .sp |
| New in version 3.14: This module accept optional COMPONENTS to check supported features and |
| protocols: |
| |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| PROTOCOLS: ICT FILE FTP FTPS GOPHER HTTP HTTPS IMAP IMAPS LDAP LDAPS POP3 |
| POP3S RTMP RTSP SCP SFTP SMB SMBS SMTP SMTPS TELNET TFTP |
| FEATURES: SSL IPv6 UnixSockets libz AsynchDNS IDN GSS\-API PSL SPNEGO |
| Kerberos NTLM NTLM_WB TLS\-SRP HTTP2 HTTPS\-proxy |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS IMPORTED Targets |
| .sp |
| New in version 3.12. |
| |
| .sp |
| This module defines \fBIMPORTED\fP target \fBCURL::libcurl\fP, if |
| curl has been found. |
| .SS Result Variables |
| .sp |
| This module defines the following variables: |
| .INDENT 0.0 |
| .TP |
| .B \fBCURL_FOUND\fP |
| "True" if \fBcurl\fP found. |
| .TP |
| .B \fBCURL_INCLUDE_DIRS\fP |
| where to find \fBcurl\fP/\fBcurl.h\fP, etc. |
| .TP |
| .B \fBCURL_LIBRARIES\fP |
| List of libraries when using \fBcurl\fP\&. |
| .TP |
| .B \fBCURL_VERSION_STRING\fP |
| The version of \fBcurl\fP found. |
| .UNINDENT |
| .sp |
| New in version 3.13: Debug and Release variants are found separately. |
| |
| .SS CURL CMake |
| .sp |
| New in version 3.17. |
| |
| .sp |
| If CURL was built using the CMake buildsystem then it provides its own |
| \fBCURLConfig.cmake\fP file for use with the \fBfind_package()\fP command\(aqs |
| config mode. This module looks for this file and, if found, |
| returns its results with no further action. |
| .sp |
| Set \fBCURL_NO_CURL_CMAKE\fP to \fBON\fP to disable this search. |
| .SS FindCurses |
| .sp |
| Find the curses or ncurses include file and library. |
| .SS Result Variables |
| .sp |
| This module defines the following variables: |
| .INDENT 0.0 |
| .TP |
| .B \fBCURSES_FOUND\fP |
| True if Curses is found. |
| .TP |
| .B \fBCURSES_INCLUDE_DIRS\fP |
| The include directories needed to use Curses. |
| .TP |
| .B \fBCURSES_LIBRARIES\fP |
| The libraries needed to use Curses. |
| .TP |
| .B \fBCURSES_CFLAGS\fP |
| New in version 3.16. |
| |
| .sp |
| Parameters which ought be given to C/C++ compilers when using Curses. |
| .TP |
| .B \fBCURSES_HAVE_CURSES_H\fP |
| True if curses.h is available. |
| .TP |
| .B \fBCURSES_HAVE_NCURSES_H\fP |
| True if ncurses.h is available. |
| .TP |
| .B \fBCURSES_HAVE_NCURSES_NCURSES_H\fP |
| True if \fBncurses/ncurses.h\fP is available. |
| .TP |
| .B \fBCURSES_HAVE_NCURSES_CURSES_H\fP |
| True if \fBncurses/curses.h\fP is available. |
| .UNINDENT |
| .sp |
| Set \fBCURSES_NEED_NCURSES\fP to \fBTRUE\fP before the |
| \fBfind_package(Curses)\fP call if NCurses functionality is required. |
| .sp |
| New in version 3.10: Set \fBCURSES_NEED_WIDE\fP to \fBTRUE\fP before the |
| \fBfind_package(Curses)\fP call if unicode functionality is required. |
| |
| .SS Backward Compatibility |
| .sp |
| The following variable are provided for backward compatibility: |
| .INDENT 0.0 |
| .TP |
| .B \fBCURSES_INCLUDE_DIR\fP |
| Path to Curses include. Use \fBCURSES_INCLUDE_DIRS\fP instead. |
| .TP |
| .B \fBCURSES_LIBRARY\fP |
| Path to Curses library. Use \fBCURSES_LIBRARIES\fP instead. |
| .UNINDENT |
| .SS FindCVS |
| .sp |
| Find the Concurrent Versions System (CVS). |
| .sp |
| The module defines the following variables: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| CVS_EXECUTABLE \- path to cvs command line client |
| CVS_FOUND \- true if the command line client was found |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Example usage: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_package(CVS) |
| if(CVS_FOUND) |
| message("CVS found: ${CVS_EXECUTABLE}") |
| endif() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindCxxTest |
| .sp |
| Find CxxTest unit testing framework. |
| .sp |
| Find the CxxTest suite and declare a helper macro for creating unit |
| tests and integrating them with CTest. For more details on CxxTest |
| see \fI\%http://cxxtest.tigris.org\fP |
| .sp |
| INPUT Variables |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| CXXTEST_USE_PYTHON [deprecated since 1.3] |
| Only used in the case both Python & Perl |
| are detected on the system to control |
| which CxxTest code generator is used. |
| Valid only for CxxTest version 3. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| NOTE: In older versions of this Find Module, |
| this variable controlled if the Python test |
| generator was used instead of the Perl one, |
| regardless of which scripting language the |
| user had installed. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| CXXTEST_TESTGEN_ARGS (since CMake 2.8.3) |
| Specify a list of options to pass to the CxxTest code |
| generator. If not defined, \-\-error\-printer is |
| passed. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| OUTPUT Variables |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| CXXTEST_FOUND |
| True if the CxxTest framework was found |
| CXXTEST_INCLUDE_DIRS |
| Where to find the CxxTest include directory |
| CXXTEST_PERL_TESTGEN_EXECUTABLE |
| The perl\-based test generator |
| CXXTEST_PYTHON_TESTGEN_EXECUTABLE |
| The python\-based test generator |
| CXXTEST_TESTGEN_EXECUTABLE (since CMake 2.8.3) |
| The test generator that is actually used (chosen using user preferences |
| and interpreters found in the system) |
| CXXTEST_TESTGEN_INTERPRETER (since CMake 2.8.3) |
| The full path to the Perl or Python executable on the system, on |
| platforms where the script cannot be executed using its shebang line. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| MACROS for optional use by CMake users: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| CXXTEST_ADD_TEST(<test_name> <gen_source_file> <input_files_to_testgen...>) |
| Creates a CxxTest runner and adds it to the CTest testing suite |
| Parameters: |
| test_name The name of the test |
| gen_source_file The generated source filename to be |
| generated by CxxTest |
| input_files_to_testgen The list of header files containing the |
| CxxTest::TestSuite\(aqs to be included in |
| this runner |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| #============== |
| Example Usage: |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_package(CxxTest) |
| if(CXXTEST_FOUND) |
| include_directories(${CXXTEST_INCLUDE_DIR}) |
| enable_testing() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| CXXTEST_ADD_TEST(unittest_foo foo_test.cc |
| ${CMAKE_CURRENT_SOURCE_DIR}/foo_test.h) |
| target_link_libraries(unittest_foo foo) # as needed |
| endif() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| This will (if CxxTest is found): |
| 1. Invoke the testgen executable to autogenerate foo_test.cc in the |
| binary tree from "foo_test.h" in the current source directory. |
| 2. Create an executable and test called unittest_foo. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| #============= |
| Example foo_test.h: |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| #include <cxxtest/TestSuite.h> |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| class MyTestSuite : public CxxTest::TestSuite |
| { |
| public: |
| void testAddition( void ) |
| { |
| TS_ASSERT( 1 + 1 > 1 ); |
| TS_ASSERT_EQUALS( 1 + 1, 2 ); |
| } |
| }; |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindCygwin |
| .sp |
| Find Cygwin, a POSIX\-compatible environment that runs natively |
| on Microsoft Windows |
| .SS FindDart |
| .sp |
| Find DART |
| .sp |
| This module looks for the dart testing software and sets DART_ROOT to |
| point to where it found it. |
| .SS FindDCMTK |
| .sp |
| Find DICOM ToolKit (DCMTK) libraries and applications |
| .sp |
| The module defines the following variables: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| DCMTK_INCLUDE_DIRS \- Directories to include to use DCMTK |
| DCMTK_LIBRARIES \- Files to link against to use DCMTK |
| DCMTK_FOUND \- If false, don\(aqt try to use DCMTK |
| DCMTK_DIR \- (optional) Source directory for DCMTK |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS Compatibility |
| .sp |
| This module is able to find a version of DCMTK that does or does not export |
| a \fIDCMTKConfig.cmake\fP file. It applies a two step process: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| Step 1: Attempt to find DCMTK version providing a \fIDCMTKConfig.cmake\fP file. |
| .IP \(bu 2 |
| Step 2: If step 1 failed, rely on \fIFindDCMTK.cmake\fP to set \fIDCMTK_*\fP variables details below. |
| .UNINDENT |
| .sp |
| \fI\%Recent DCMTK\fP |
| provides a \fIDCMTKConfig.cmake\fP \fBpackage configuration file\fP\&. To exclusively use the package configuration file |
| (recommended when possible), pass the \fINO_MODULE\fP option to |
| \fBfind_package()\fP\&. For example, \fIfind_package(DCMTK NO_MODULE)\fP\&. |
| This requires official DCMTK snapshot \fI3.6.1_20140617\fP or newer. |
| .sp |
| Until all clients update to the more recent DCMTK, build systems will need |
| to support different versions of DCMTK. |
| .sp |
| On any given system, the following combinations of DCMTK versions could be |
| considered: |
| .TS |
| center; |
| |l|l|l|l|. |
| _ |
| T{ |
| T} T{ |
| SYSTEM DCMTK |
| T} T{ |
| LOCAL DCMTK |
| T} T{ |
| Supported ? |
| T} |
| _ |
| T{ |
| Case A |
| T} T{ |
| NA |
| T} T{ |
| [ ] DCMTKConfig |
| T} T{ |
| YES |
| T} |
| _ |
| T{ |
| Case B |
| T} T{ |
| NA |
| T} T{ |
| [X] DCMTKConfig |
| T} T{ |
| YES |
| T} |
| _ |
| T{ |
| Case C |
| T} T{ |
| [ ] DCMTKConfig |
| T} T{ |
| NA |
| T} T{ |
| YES |
| T} |
| _ |
| T{ |
| Case D |
| T} T{ |
| [X] DCMTKConfig |
| T} T{ |
| NA |
| T} T{ |
| YES |
| T} |
| _ |
| T{ |
| Case E |
| T} T{ |
| [ ] DCMTKConfig |
| T} T{ |
| [ ] DCMTKConfig |
| T} T{ |
| YES (*) |
| T} |
| _ |
| T{ |
| Case F |
| T} T{ |
| [X] DCMTKConfig |
| T} T{ |
| [ ] DCMTKConfig |
| T} T{ |
| NO |
| T} |
| _ |
| T{ |
| Case G |
| T} T{ |
| [ ] DCMTKConfig |
| T} T{ |
| [X] DCMTKConfig |
| T} T{ |
| YES |
| T} |
| _ |
| T{ |
| Case H |
| T} T{ |
| [X] DCMTKConfig |
| T} T{ |
| [X] DCMTKConfig |
| T} T{ |
| YES |
| T} |
| _ |
| .TE |
| .INDENT 0.0 |
| .INDENT 3.5 |
| (*) See Troubleshooting section. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Legend: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| NA ...............: Means that no System or Local DCMTK is available |
| .sp |
| [ ] DCMTKConfig ..: Means that the version of DCMTK does NOT export a DCMTKConfig.cmake file. |
| .sp |
| [X] DCMTKConfig ..: Means that the version of DCMTK exports a DCMTKConfig.cmake file. |
| .UNINDENT |
| .UNINDENT |
| .SS Troubleshooting |
| .sp |
| What to do if my project finds a different version of DCMTK? |
| .sp |
| Remove DCMTK entry from the CMake cache per \fBfind_package()\fP |
| documentation. |
| .SS FindDevIL |
| .sp |
| This module locates the developer\(aqs image library. |
| \fI\%http://openil.sourceforge.net/\fP |
| .SS IMPORTED Targets |
| .sp |
| New in version 3.21. |
| |
| .sp |
| This module defines the \fBIMPORTED\fP targets: |
| .INDENT 0.0 |
| .TP |
| .B \fBDevIL::IL\fP |
| Defined if the system has DevIL. |
| .TP |
| .B \fBDevIL::ILU\fP |
| Defined if the system has DevIL Utilities. |
| .TP |
| .B \fBDevIL::ILUT\fP |
| Defined if the system has DevIL Utility Toolkit. |
| .UNINDENT |
| .SS Result Variables |
| .sp |
| This module sets: |
| .INDENT 0.0 |
| .TP |
| .B \fBIL_LIBRARIES\fP |
| The name of the IL library. These include the full path to |
| the core DevIL library. This one has to be linked into the |
| application. |
| .TP |
| .B \fBILU_LIBRARIES\fP |
| The name of the ILU library. Again, the full path. This |
| library is for filters and effects, not actual loading. It |
| doesn\(aqt have to be linked if the functionality it provides |
| is not used. |
| .TP |
| .B \fBILUT_LIBRARIES\fP |
| The name of the ILUT library. Full path. This part of the |
| library interfaces with OpenGL. It is not strictly needed |
| in applications. |
| .TP |
| .B \fBIL_INCLUDE_DIR\fP |
| where to find the il.h, ilu.h and ilut.h files. |
| .TP |
| .B \fBDevIL_FOUND\fP |
| This is set to TRUE if all the above variables were set. |
| This will be set to false if ILU or ILUT are not found, |
| even if they are not needed. In most systems, if one |
| library is found all the others are as well. That\(aqs the |
| way the DevIL developers release it. |
| .TP |
| .B \fBDevIL_ILUT_FOUND\fP |
| New in version 3.21. |
| |
| .sp |
| This is set to TRUE if the ILUT library is found. |
| .UNINDENT |
| .SS FindDoxygen |
| .sp |
| Doxygen is a documentation generation tool (see \fI\%http://www.doxygen.org\fP). |
| This module looks for Doxygen and some optional tools it supports: |
| .INDENT 0.0 |
| .TP |
| .B \fBdot\fP |
| \fI\%Graphviz\fP \fBdot\fP utility used to render various |
| graphs. |
| .TP |
| .B \fBmscgen\fP |
| \fI\%Message Chart Generator\fP utility used |
| by Doxygen\(aqs \fB\emsc\fP and \fB\emscfile\fP commands. |
| .TP |
| .B \fBdia\fP |
| \fI\%Dia\fP the diagram editor used by Doxygen\(aqs |
| \fB\ediafile\fP command. |
| .UNINDENT |
| .sp |
| New in version 3.9: These tools are available as components in the \fBfind_package()\fP command. |
| For example: |
| |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| # Require dot, treat the other components as optional |
| find_package(Doxygen |
| REQUIRED dot |
| OPTIONAL_COMPONENTS mscgen dia) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The following variables are defined by this module: |
| .INDENT 0.0 |
| .TP |
| .B DOXYGEN_FOUND |
| True if the \fBdoxygen\fP executable was found. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B DOXYGEN_VERSION |
| The version reported by \fBdoxygen \-\-version\fP\&. |
| .UNINDENT |
| .sp |
| New in version 3.9: The module defines \fBIMPORTED\fP targets for Doxygen and each component found. |
| These can be used as part of custom commands, etc. and should be preferred over |
| old\-style (and now deprecated) variables like \fBDOXYGEN_EXECUTABLE\fP\&. The |
| following import targets are defined if their corresponding executable could be |
| found (the component import targets will only be defined if that component was |
| requested): |
| |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| Doxygen::doxygen |
| Doxygen::dot |
| Doxygen::mscgen |
| Doxygen::dia |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS Functions |
| .INDENT 0.0 |
| .TP |
| .B doxygen_add_docs |
| New in version 3.9. |
| |
| .sp |
| This function is intended as a convenience for adding a target for generating |
| documentation with Doxygen. It aims to provide sensible defaults so that |
| projects can generally just provide the input files and directories and that |
| will be sufficient to give sensible results. The function supports the |
| ability to customize the Doxygen configuration used to build the |
| documentation. |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| doxygen_add_docs(targetName |
| [filesOrDirs...] |
| [ALL] |
| [USE_STAMP_FILE] |
| [WORKING_DIRECTORY dir] |
| [COMMENT comment]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The function constructs a \fBDoxyfile\fP and defines a custom target that runs |
| Doxygen on that generated file. The listed files and directories are used as |
| the \fBINPUT\fP of the generated \fBDoxyfile\fP and they can contain wildcards. |
| Any files that are listed explicitly will also be added as \fBSOURCES\fP of the |
| custom target so they will show up in an IDE project\(aqs source list. |
| .sp |
| So that relative input paths work as expected, by default the working |
| directory of the Doxygen command will be the current source directory (i.e. |
| \fBCMAKE_CURRENT_SOURCE_DIR\fP). This can be overridden with the |
| \fBWORKING_DIRECTORY\fP option to change the directory used as the relative |
| base point. Note also that Doxygen\(aqs default behavior is to strip the working |
| directory from relative paths in the generated documentation (see the |
| \fBSTRIP_FROM_PATH\fP \fI\%Doxygen config option\fP for details). |
| .sp |
| If provided, the optional \fBcomment\fP will be passed as the \fBCOMMENT\fP for |
| the \fBadd_custom_target()\fP command used to create the custom target |
| internally. |
| .sp |
| New in version 3.12: If \fBALL\fP is set, the target will be added to the default build target. |
| |
| .sp |
| New in version 3.16: If \fBUSE_STAMP_FILE\fP is set, the custom command defined by this function will |
| create a stamp file with the name \fB<targetName>.stamp\fP in the current |
| binary directory whenever doxygen is re\-run. With this option present, all |
| items in \fB<filesOrDirs>\fP must be files (i.e. no directories, symlinks or |
| wildcards) and each of the files must exist at the time |
| \fBdoxygen_add_docs()\fP is called. An error will be raised if any of the |
| items listed is missing or is not a file when \fBUSE_STAMP_FILE\fP is given. |
| A dependency will be created on each of the files so that doxygen will only |
| be re\-run if one of the files is updated. Without the \fBUSE_STAMP_FILE\fP |
| option, doxygen will always be re\-run if the \fB<targetName>\fP target is built |
| regardless of whether anything listed in \fB<filesOrDirs>\fP has changed. |
| |
| .sp |
| The contents of the generated \fBDoxyfile\fP can be customized by setting CMake |
| variables before calling \fBdoxygen_add_docs()\fP\&. Any variable with a name of |
| the form \fBDOXYGEN_<tag>\fP will have its value substituted for the |
| corresponding \fB<tag>\fP configuration option in the \fBDoxyfile\fP\&. See the |
| \fI\%Doxygen documentation\fP for the |
| full list of supported configuration options. |
| .sp |
| Some of Doxygen\(aqs defaults are overridden to provide more appropriate |
| behavior for a CMake project. Each of the following will be explicitly set |
| unless the variable already has a value before \fBdoxygen_add_docs()\fP is |
| called (with some exceptions noted): |
| .INDENT 7.0 |
| .TP |
| .B DOXYGEN_HAVE_DOT |
| Set to \fBYES\fP if the \fBdot\fP component was requested and it was found, |
| \fBNO\fP otherwise. Any existing value of \fBDOXYGEN_HAVE_DOT\fP is ignored. |
| .UNINDENT |
| .INDENT 7.0 |
| .TP |
| .B DOXYGEN_DOT_MULTI_TARGETS |
| Set to \fBYES\fP by this module (note that this requires a \fBdot\fP version |
| newer than 1.8.10). This option is only meaningful if \fBDOXYGEN_HAVE_DOT\fP |
| is also set to \fBYES\fP\&. |
| .UNINDENT |
| .INDENT 7.0 |
| .TP |
| .B DOXYGEN_GENERATE_LATEX |
| Set to \fBNO\fP by this module. |
| .UNINDENT |
| .INDENT 7.0 |
| .TP |
| .B DOXYGEN_WARN_FORMAT |
| For Visual Studio based generators, this is set to the form recognized by |
| the Visual Studio IDE: \fB$file($line) : $text\fP\&. For all other generators, |
| Doxygen\(aqs default value is not overridden. |
| .UNINDENT |
| .INDENT 7.0 |
| .TP |
| .B DOXYGEN_PROJECT_NAME |
| Populated with the name of the current project (i.e. |
| \fBPROJECT_NAME\fP). |
| .UNINDENT |
| .INDENT 7.0 |
| .TP |
| .B DOXYGEN_PROJECT_NUMBER |
| Populated with the version of the current project (i.e. |
| \fBPROJECT_VERSION\fP). |
| .UNINDENT |
| .INDENT 7.0 |
| .TP |
| .B DOXYGEN_PROJECT_BRIEF |
| Populated with the description of the current project (i.e. |
| \fBPROJECT_DESCRIPTION\fP). |
| .UNINDENT |
| .INDENT 7.0 |
| .TP |
| .B DOXYGEN_INPUT |
| Projects should not set this variable. It will be populated with the set of |
| files and directories passed to \fBdoxygen_add_docs()\fP, thereby providing |
| consistent behavior with the other built\-in commands like |
| \fBadd_executable()\fP, \fBadd_library()\fP and |
| \fBadd_custom_target()\fP\&. If a variable named \fBDOXYGEN_INPUT\fP is set |
| by the project, it will be ignored and a warning will be issued. |
| .UNINDENT |
| .INDENT 7.0 |
| .TP |
| .B DOXYGEN_RECURSIVE |
| Set to \fBYES\fP by this module. |
| .UNINDENT |
| .INDENT 7.0 |
| .TP |
| .B DOXYGEN_EXCLUDE_PATTERNS |
| If the set of inputs includes directories, this variable will specify |
| patterns used to exclude files from them. The following patterns are added |
| by \fBdoxygen_add_docs()\fP to ensure CMake\-specific files and directories |
| are not included in the input. If the project sets |
| \fBDOXYGEN_EXCLUDE_PATTERNS\fP, those contents are merged with these |
| additional patterns rather than replacing them: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| */.git/* |
| */.svn/* |
| */.hg/* |
| */CMakeFiles/* |
| */_CPack_Packages/* |
| DartConfiguration.tcl |
| CMakeLists.txt |
| CMakeCache.txt |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .INDENT 7.0 |
| .TP |
| .B DOXYGEN_OUTPUT_DIRECTORY |
| Set to \fBCMAKE_CURRENT_BINARY_DIR\fP by this module. Note that if |
| the project provides its own value for this and it is a relative path, it |
| will be converted to an absolute path relative to the current binary |
| directory. This is necessary because doxygen will normally be run from a |
| directory within the source tree so that relative source paths work as |
| expected. If this directory does not exist, it will be recursively created |
| prior to executing the doxygen commands. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| To change any of these defaults or override any other Doxygen config option, |
| set relevant variables before calling \fBdoxygen_add_docs()\fP\&. For example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(DOXYGEN_GENERATE_HTML NO) |
| set(DOXYGEN_GENERATE_MAN YES) |
| |
| doxygen_add_docs( |
| doxygen |
| ${PROJECT_SOURCE_DIR} |
| COMMENT "Generate man pages" |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .sp |
| A number of Doxygen config options accept lists of values, but Doxygen requires |
| them to be separated by whitespace. CMake variables hold lists as a string with |
| items separated by semi\-colons, so a conversion needs to be performed. The |
| \fBdoxygen_add_docs()\fP command specifically checks the following Doxygen config |
| options and will convert their associated CMake variable\(aqs contents into the |
| required form if set. CMake variables are named \fBDOXYGEN_<name>\fP for the |
| Doxygen settings specified here. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ABBREVIATE_BRIEF |
| ALIASES |
| CITE_BIB_FILES |
| DIAFILE_DIRS |
| DOTFILE_DIRS |
| DOT_FONTPATH |
| ENABLED_SECTIONS |
| EXAMPLE_PATH |
| EXAMPLE_PATTERNS |
| EXCLUDE |
| EXCLUDE_PATTERNS |
| EXCLUDE_SYMBOLS |
| EXPAND_AS_DEFINED |
| EXTENSION_MAPPING |
| EXTRA_PACKAGES |
| EXTRA_SEARCH_MAPPINGS |
| FILE_PATTERNS |
| FILTER_PATTERNS |
| FILTER_SOURCE_PATTERNS |
| HTML_EXTRA_FILES |
| HTML_EXTRA_STYLESHEET |
| IGNORE_PREFIX |
| IMAGE_PATH |
| INCLUDE_FILE_PATTERNS |
| INCLUDE_PATH |
| INPUT |
| LATEX_EXTRA_FILES |
| LATEX_EXTRA_STYLESHEET |
| MATHJAX_EXTENSIONS |
| MSCFILE_DIRS |
| PLANTUML_INCLUDE_PATH |
| PREDEFINED |
| QHP_CUST_FILTER_ATTRS |
| QHP_SECT_FILTER_ATTRS |
| STRIP_FROM_INC_PATH |
| STRIP_FROM_PATH |
| TAGFILES |
| TCL_SUBST |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The following single value Doxygen options will be quoted automatically |
| if they contain at least one space: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| CHM_FILE |
| DIA_PATH |
| DOCBOOK_OUTPUT |
| DOCSET_FEEDNAME |
| DOCSET_PUBLISHER_NAME |
| DOT_FONTNAME |
| DOT_PATH |
| EXTERNAL_SEARCH_ID |
| FILE_VERSION_FILTER |
| GENERATE_TAGFILE |
| HHC_LOCATION |
| HTML_FOOTER |
| HTML_HEADER |
| HTML_OUTPUT |
| HTML_STYLESHEET |
| INPUT_FILTER |
| LATEX_FOOTER |
| LATEX_HEADER |
| LATEX_OUTPUT |
| LAYOUT_FILE |
| MAN_OUTPUT |
| MAN_SUBDIR |
| MATHJAX_CODEFILE |
| MSCGEN_PATH |
| OUTPUT_DIRECTORY |
| PERL_PATH |
| PLANTUML_JAR_PATH |
| PROJECT_BRIEF |
| PROJECT_LOGO |
| PROJECT_NAME |
| QCH_FILE |
| QHG_LOCATION |
| QHP_CUST_FILTER_NAME |
| QHP_VIRTUAL_FOLDER |
| RTF_EXTENSIONS_FILE |
| RTF_OUTPUT |
| RTF_STYLESHEET_FILE |
| SEARCHDATA_FILE |
| USE_MDFILE_AS_MAINPAGE |
| WARN_FORMAT |
| WARN_LOGFILE |
| XML_OUTPUT |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.11: There are situations where it may be undesirable for a particular config option |
| to be automatically quoted by \fBdoxygen_add_docs()\fP, such as \fBALIASES\fP which |
| may need to include its own embedded quoting. The \fBDOXYGEN_VERBATIM_VARS\fP |
| variable can be used to specify a list of Doxygen variables (including the |
| leading \fBDOXYGEN_\fP prefix) which should not be quoted. The project is then |
| responsible for ensuring that those variables\(aq values make sense when placed |
| directly in the Doxygen input file. In the case of list variables, list items |
| are still separated by spaces, it is only the automatic quoting that is |
| skipped. For example, the following allows \fBdoxygen_add_docs()\fP to apply |
| quoting to \fBDOXYGEN_PROJECT_BRIEF\fP, but not each item in the |
| \fBDOXYGEN_ALIASES\fP list (bracket syntax can also |
| be used to make working with embedded quotes easier): |
| |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(DOXYGEN_PROJECT_BRIEF "String with spaces") |
| set(DOXYGEN_ALIASES |
| [[somealias="@some_command param"]] |
| "anotherAlias=@foobar" |
| ) |
| set(DOXYGEN_VERBATIM_VARS DOXYGEN_ALIASES) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The resultant \fBDoxyfile\fP will contain the following lines: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| PROJECT_BRIEF = "String with spaces" |
| ALIASES = somealias="@some_command param" anotherAlias=@foobar |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS Deprecated Result Variables |
| .sp |
| Deprecated since version 3.9. |
| |
| .sp |
| For compatibility with previous versions of CMake, the following variables |
| are also defined but they are deprecated and should no longer be used: |
| .INDENT 0.0 |
| .TP |
| .B DOXYGEN_EXECUTABLE |
| The path to the \fBdoxygen\fP command. If projects need to refer to the |
| \fBdoxygen\fP executable directly, they should use the \fBDoxygen::doxygen\fP |
| import target instead. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B DOXYGEN_DOT_FOUND |
| True if the \fBdot\fP executable was found. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B DOXYGEN_DOT_EXECUTABLE |
| The path to the \fBdot\fP command. If projects need to refer to the \fBdot\fP |
| executable directly, they should use the \fBDoxygen::dot\fP import target |
| instead. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B DOXYGEN_DOT_PATH |
| The path to the directory containing the \fBdot\fP executable as reported in |
| \fBDOXYGEN_DOT_EXECUTABLE\fP\&. The path may have forward slashes even on Windows |
| and is not suitable for direct substitution into a \fBDoxyfile.in\fP template. |
| If you need this value, get the \fBIMPORTED_LOCATION\fP property of the |
| \fBDoxygen::dot\fP target and use \fBget_filename_component()\fP to extract |
| the directory part of that path. You may also want to consider using |
| \fBfile(TO_NATIVE_PATH)\fP to prepare the path for a Doxygen |
| configuration file. |
| .UNINDENT |
| .SS Deprecated Hint Variables |
| .sp |
| Deprecated since version 3.9. |
| |
| .INDENT 0.0 |
| .TP |
| .B DOXYGEN_SKIP_DOT |
| This variable has no effect for the component form of \fBfind_package\fP\&. |
| In backward compatibility mode (i.e. without components list) it prevents |
| the finder module from searching for Graphviz\(aqs \fBdot\fP utility. |
| .UNINDENT |
| .SS FindEnvModules |
| .sp |
| New in version 3.15. |
| |
| .sp |
| Locate an environment module implementation and make commands available to |
| CMake scripts to use them. This is compatible with both Lua\-based Lmod |
| and TCL\-based EnvironmentModules. |
| .sp |
| This module is intended for the use case of setting up the compiler and library |
| environment within a CTest Script (\fBctest \-S\fP). It can |
| also be used in a CMake Script (\fBcmake \-P\fP). |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| The loaded environment will not survive past the end of the calling process. |
| Do not use this module in project code (\fBCMakeLists.txt\fP files) to load |
| a compiler environment; it will not be available during the build. Instead |
| load the environment manually before running CMake or using the generated |
| build system. |
| .UNINDENT |
| .UNINDENT |
| .SS Example Usage |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(CTEST_BUILD_NAME "CrayLinux\-CrayPE\-Cray\-dynamic") |
| set(CTEST_BUILD_CONFIGURATION Release) |
| set(CTEST_BUILD_FLAGS "\-k \-j8") |
| set(CTEST_CMAKE_GENERATOR "Unix Makefiles") |
| |
| \&... |
| |
| find_package(EnvModules REQUIRED) |
| |
| env_module(purge) |
| env_module(load modules) |
| env_module(load craype) |
| env_module(load PrgEnv\-cray) |
| env_module(load craype\-knl) |
| env_module(load cray\-mpich) |
| env_module(load cray\-libsci) |
| |
| set(ENV{CRAYPE_LINK_TYPE} dynamic) |
| |
| \&... |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS Result Variables |
| .sp |
| This module will set the following variables in your project: |
| .INDENT 0.0 |
| .TP |
| .B \fBEnvModules_FOUND\fP |
| True if a compatible environment modules framework was found. |
| .UNINDENT |
| .SS Cache Variables |
| .sp |
| The following cache variable will be set: |
| .INDENT 0.0 |
| .TP |
| .B \fBEnvModules_COMMAND\fP |
| The low level module command to use. Currently supported |
| implementations are the Lua based Lmod and TCL based EnvironmentModules. |
| .UNINDENT |
| .SS Environment Variables |
| .INDENT 0.0 |
| .TP |
| .B \fBENV{MODULESHOME}\fP |
| Usually set by the module environment implementation, used as a hint to |
| locate the module command to execute. |
| .UNINDENT |
| .SS Provided Functions |
| .sp |
| This defines the following CMake functions for interacting with environment |
| modules: |
| .INDENT 0.0 |
| .TP |
| .B env_module |
| Execute an aribitrary module command: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| env_module(cmd arg1 ... argN) |
| env_module( |
| COMMAND cmd arg1 ... argN |
| [OUTPUT_VARIABLE <out\-var>] |
| [RESULT_VARIABLE <ret\-var>] |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The options are: |
| .INDENT 7.0 |
| .TP |
| .B \fBcmd arg1 ... argN\fP |
| The module sub\-command and arguments to execute as if they were |
| passed directly to the module command in your shell environment. |
| .TP |
| .B \fBOUTPUT_VARIABLE <out\-var>\fP |
| The standard output from executing the module command. |
| .TP |
| .B \fBRESULT_VARIABLE <ret\-var>\fP |
| The return code from executing the module command. |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B env_module_swap |
| Swap one module for another: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| env_module_swap(out_mod in_mod |
| [OUTPUT_VARIABLE <out\-var>] |
| [RESULT_VARIABLE <ret\-var>] |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This is functionally equivalent to the \fBmodule swap out_mod in_mod\fP shell |
| command. The options are: |
| .INDENT 7.0 |
| .TP |
| .B \fBOUTPUT_VARIABLE <out\-var>\fP |
| The standard output from executing the module command. |
| .TP |
| .B \fBRESULT_VARIABLE <ret\-var>\fP |
| The return code from executing the module command. |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B env_module_list |
| Retrieve the list of currently loaded modules: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| env_module_list(<out\-var>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This is functionally equivalent to the \fBmodule list\fP shell command. |
| The result is stored in \fB<out\-var>\fP as a properly formatted CMake |
| semicolon\-separated list variable. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B env_module_avail |
| Retrieve the list of available modules: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| env_module_avail([<mod\-prefix>] <out\-var>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This is functionally equivalent to the \fBmodule avail <mod\-prefix>\fP shell |
| command. The result is stored in \fB<out\-var>\fP as a properly formatted |
| CMake semicolon\-separated list variable. |
| .UNINDENT |
| .SS FindEXPAT |
| .sp |
| Find the native Expat headers and library. |
| Expat is a stream\-oriented XML parser library written in C. |
| .SS Imported Targets |
| .sp |
| New in version 3.10. |
| |
| .sp |
| This module defines the following \fBIMPORTED\fP targets: |
| .INDENT 0.0 |
| .TP |
| .B \fBEXPAT::EXPAT\fP |
| The Expat \fBexpat\fP library, if found. |
| .UNINDENT |
| .SS Result Variables |
| .sp |
| This module will set the following variables in your project: |
| .INDENT 0.0 |
| .TP |
| .B \fBEXPAT_INCLUDE_DIRS\fP |
| where to find expat.h, etc. |
| .TP |
| .B \fBEXPAT_LIBRARIES\fP |
| the libraries to link against to use Expat. |
| .TP |
| .B \fBEXPAT_FOUND\fP |
| true if the Expat headers and libraries were found. |
| .UNINDENT |
| .SS FindFLEX |
| .sp |
| Find Fast Lexical Analyzer (Flex) executable and provides a macro |
| to generate custom build rules |
| .sp |
| The module defines the following variables: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| FLEX_FOUND \- True is flex executable is found |
| FLEX_EXECUTABLE \- the path to the flex executable |
| FLEX_VERSION \- the version of flex |
| FLEX_LIBRARIES \- The flex libraries |
| FLEX_INCLUDE_DIRS \- The path to the flex headers |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The minimum required version of flex can be specified using the |
| standard syntax, e.g. \fBfind_package(FLEX 2.5.13)\fP |
| .sp |
| If flex is found on the system, the module provides the macro: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| FLEX_TARGET(Name FlexInput FlexOutput |
| [COMPILE_FLAGS <string>] |
| [DEFINES_FILE <string>] |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| which creates a custom command to generate the \fBFlexOutput\fP file from |
| the \fBFlexInput\fP file. Name is an alias used to get details of this custom |
| command. If \fBCOMPILE_FLAGS\fP option is specified, the next |
| parameter is added to the flex command line. |
| .sp |
| New in version 3.5: If flex is configured to |
| output a header file, the \fBDEFINES_FILE\fP option may be used to specify its |
| name. |
| |
| .sp |
| Changed in version 3.17: When \fBCMP0098\fP is set to \fBNEW\fP, \fBflex\fP runs in the |
| \fBCMAKE_CURRENT_BINARY_DIR\fP directory. |
| |
| .sp |
| The macro defines the following variables: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| FLEX_${Name}_DEFINED \- true is the macro ran successfully |
| FLEX_${Name}_OUTPUTS \- the source file generated by the custom rule, an |
| alias for FlexOutput |
| FLEX_${Name}_INPUT \- the flex source file, an alias for ${FlexInput} |
| FLEX_${Name}_OUTPUT_HEADER \- the header flex output, if any. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Flex scanners often use tokens defined by Bison: the code generated |
| by Flex depends of the header generated by Bison. This module also |
| defines a macro: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ADD_FLEX_BISON_DEPENDENCY(FlexTarget BisonTarget) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| which adds the required dependency between a scanner and a parser |
| where \fBFlexTarget\fP and \fBBisonTarget\fP are the first parameters of |
| respectively \fBFLEX_TARGET\fP and \fBBISON_TARGET\fP macros. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ==================================================================== |
| Example: |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_package(BISON) |
| find_package(FLEX) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| BISON_TARGET(MyParser parser.y ${CMAKE_CURRENT_BINARY_DIR}/parser.cpp) |
| FLEX_TARGET(MyScanner lexer.l ${CMAKE_CURRENT_BINARY_DIR}/lexer.cpp) |
| ADD_FLEX_BISON_DEPENDENCY(MyScanner MyParser) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| include_directories(${CMAKE_CURRENT_BINARY_DIR}) |
| add_executable(Foo |
| Foo.cc |
| ${BISON_MyParser_OUTPUTS} |
| ${FLEX_MyScanner_OUTPUTS} |
| ) |
| target_link_libraries(Foo ${FLEX_LIBRARIES}) |
| ==================================================================== |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindFLTK |
| .sp |
| Find the Fast Light Toolkit (FLTK) library |
| .SS Input Variables |
| .sp |
| By default this module will search for all of the FLTK components and |
| add them to the \fBFLTK_LIBRARIES\fP variable. You can limit the components |
| which get placed in \fBFLTK_LIBRARIES\fP by defining one or more of the |
| following three options: |
| .INDENT 0.0 |
| .TP |
| .B \fBFLTK_SKIP_OPENGL\fP |
| Set to true to disable searching for the FLTK GL library |
| .TP |
| .B \fBFLTK_SKIP_FORMS\fP |
| Set to true to disable searching for the FLTK Forms library |
| .TP |
| .B \fBFLTK_SKIP_IMAGES\fP |
| Set to true to disable searching for the FLTK Images library |
| .UNINDENT |
| .sp |
| FLTK is composed also by a binary tool. You can set the following option: |
| .INDENT 0.0 |
| .TP |
| .B \fBFLTK_SKIP_FLUID\fP |
| Set to true to not look for the FLUID binary |
| .UNINDENT |
| .SS Result Variables |
| .sp |
| The following variables will be defined: |
| .INDENT 0.0 |
| .TP |
| .B \fBFLTK_FOUND\fP |
| True if all components not skipped were found |
| .TP |
| .B \fBFLTK_INCLUDE_DIR\fP |
| Path to the include directory for FLTK header files |
| .TP |
| .B \fBFLTK_LIBRARIES\fP |
| List of the FLTK libraries found |
| .TP |
| .B \fBFLTK_FLUID_EXECUTABLE\fP |
| Path to the FLUID binary tool |
| .TP |
| .B \fBFLTK_WRAP_UI\fP |
| True if FLUID is found, used to enable the FLTK_WRAP_UI command |
| .UNINDENT |
| .SS Cache Variables |
| .sp |
| The following cache variables are also available to set or use: |
| .INDENT 0.0 |
| .TP |
| .B \fBFLTK_BASE_LIBRARY_RELEASE\fP |
| The FLTK base library (optimized) |
| .TP |
| .B \fBFLTK_BASE_LIBRARY_DEBUG\fP |
| The FLTK base library (debug) |
| .TP |
| .B \fBFLTK_GL_LIBRARY_RELEASE\fP |
| The FLTK GL library (optimized) |
| .TP |
| .B \fBFLTK_GL_LIBRARY_DEBUG\fP |
| The FLTK GL library (debug) |
| .TP |
| .B \fBFLTK_FORMS_LIBRARY_RELEASE\fP |
| The FLTK Forms library (optimized) |
| .TP |
| .B \fBFLTK_FORMS_LIBRARY_DEBUG\fP |
| The FLTK Forms library (debug) |
| .TP |
| .B \fBFLTK_IMAGES_LIBRARY_RELEASE\fP |
| The FLTK Images protobuf library (optimized) |
| .TP |
| .B \fBFLTK_IMAGES_LIBRARY_DEBUG\fP |
| The FLTK Images library (debug) |
| .UNINDENT |
| .sp |
| New in version 3.11: Debug and Release variants are found separately and use per\-configuration |
| variables. |
| |
| .SS FindFLTK2 |
| .sp |
| Find the native FLTK 2.0 includes and library |
| .sp |
| The following settings are defined |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| FLTK2_FLUID_EXECUTABLE, where to find the Fluid tool |
| FLTK2_WRAP_UI, This enables the FLTK2_WRAP_UI command |
| FLTK2_INCLUDE_DIR, where to find include files |
| FLTK2_LIBRARIES, list of fltk2 libraries |
| FLTK2_FOUND, Don\(aqt use FLTK2 if false. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The following settings should not be used in general. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| FLTK2_BASE_LIBRARY = the full path to fltk2.lib |
| FLTK2_GL_LIBRARY = the full path to fltk2_gl.lib |
| FLTK2_IMAGES_LIBRARY = the full path to fltk2_images.lib |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindFontconfig |
| .sp |
| New in version 3.14. |
| |
| .sp |
| Find Fontconfig headers and library. |
| .SS Imported Targets |
| .INDENT 0.0 |
| .TP |
| .B \fBFontconfig::Fontconfig\fP |
| The Fontconfig library, if found. |
| .UNINDENT |
| .SS Result Variables |
| .sp |
| This will define the following variables in your project: |
| .INDENT 0.0 |
| .TP |
| .B \fBFontconfig_FOUND\fP |
| true if (the requested version of) Fontconfig is available. |
| .TP |
| .B \fBFontconfig_VERSION\fP |
| the version of Fontconfig. |
| .TP |
| .B \fBFontconfig_LIBRARIES\fP |
| the libraries to link against to use Fontconfig. |
| .TP |
| .B \fBFontconfig_INCLUDE_DIRS\fP |
| where to find the Fontconfig headers. |
| .TP |
| .B \fBFontconfig_COMPILE_OPTIONS\fP |
| this should be passed to target_compile_options(), if the |
| target is not used for linking |
| .UNINDENT |
| .SS FindFreetype |
| .sp |
| Find the FreeType font renderer includes and library. |
| .SS Imported Targets |
| .sp |
| New in version 3.10. |
| |
| .sp |
| This module defines the following \fBIMPORTED\fP target: |
| .INDENT 0.0 |
| .TP |
| .B \fBFreetype::Freetype\fP |
| The Freetype \fBfreetype\fP library, if found |
| .UNINDENT |
| .SS Result Variables |
| .sp |
| This module will set the following variables in your project: |
| .INDENT 0.0 |
| .TP |
| .B \fBFREETYPE_FOUND\fP |
| true if the Freetype headers and libraries were found |
| .TP |
| .B \fBFREETYPE_INCLUDE_DIRS\fP |
| directories containing the Freetype headers. This is the |
| concatenation of the variables: |
| .INDENT 7.0 |
| .TP |
| .B \fBFREETYPE_INCLUDE_DIR_ft2build\fP |
| directory holding the main Freetype API configuration header |
| .TP |
| .B \fBFREETYPE_INCLUDE_DIR_freetype2\fP |
| directory holding Freetype public headers |
| .UNINDENT |
| .TP |
| .B \fBFREETYPE_LIBRARIES\fP |
| the library to link against |
| .TP |
| .B \fBFREETYPE_VERSION_STRING\fP |
| the version of freetype found |
| .UNINDENT |
| .sp |
| New in version 3.7: Debug and Release variants are found separately. |
| |
| .SS Hints |
| .sp |
| The user may set the environment variable \fBFREETYPE_DIR\fP to the root |
| directory of a Freetype installation. |
| .SS FindGCCXML |
| .sp |
| Find the GCC\-XML front\-end executable. |
| .sp |
| This module will define the following variables: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| GCCXML \- the GCC\-XML front\-end executable. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindGDAL |
| .sp |
| Find Geospatial Data Abstraction Library (GDAL). |
| .SS IMPORTED Targets |
| .sp |
| New in version 3.14. |
| |
| .sp |
| This module defines \fBIMPORTED\fP target \fBGDAL::GDAL\fP |
| if GDAL has been found. |
| .SS Result Variables |
| .sp |
| This module will set the following variables in your project: |
| .INDENT 0.0 |
| .TP |
| .B \fBGDAL_FOUND\fP |
| True if GDAL is found. |
| .TP |
| .B \fBGDAL_INCLUDE_DIRS\fP |
| Include directories for GDAL headers. |
| .TP |
| .B \fBGDAL_LIBRARIES\fP |
| Libraries to link to GDAL. |
| .TP |
| .B \fBGDAL_VERSION\fP |
| New in version 3.14: The version of GDAL found. |
| |
| .UNINDENT |
| .SS Cache variables |
| .sp |
| The following cache variables may also be set: |
| .INDENT 0.0 |
| .TP |
| .B \fBGDAL_LIBRARY\fP |
| The libgdal library file. |
| .TP |
| .B \fBGDAL_INCLUDE_DIR\fP |
| The directory containing \fBgdal.h\fP\&. |
| .UNINDENT |
| .SS Hints |
| .sp |
| Set \fBGDAL_DIR\fP or \fBGDAL_ROOT\fP in the environment to specify the |
| GDAL installation prefix. |
| .sp |
| The following variables may be set to modify the search strategy: |
| .INDENT 0.0 |
| .TP |
| .B \fBFindGDAL_SKIP_GDAL_CONFIG\fP |
| If set, \fBgdal\-config\fP will not be used. This can be useful if there are |
| GDAL libraries built with autotools (which provide the tool) and CMake (which |
| do not) in the same environment. |
| .TP |
| .B \fBGDAL_ADDITIONAL_LIBRARY_VERSIONS\fP |
| Extra versions of library names to search for. |
| .UNINDENT |
| .SS FindGettext |
| .sp |
| Find GNU gettext tools |
| .sp |
| This module looks for the GNU gettext tools. This module defines the |
| following values: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| GETTEXT_MSGMERGE_EXECUTABLE: the full path to the msgmerge tool. |
| GETTEXT_MSGFMT_EXECUTABLE: the full path to the msgfmt tool. |
| GETTEXT_FOUND: True if gettext has been found. |
| GETTEXT_VERSION_STRING: the version of gettext found (since CMake 2.8.8) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Additionally it provides the following macros: |
| .sp |
| GETTEXT_CREATE_TRANSLATIONS ( outputFile [ALL] file1 ... fileN ) |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| This will create a target "translations" which will convert the |
| given input po files into the binary output mo file. If the |
| ALL option is used, the translations will also be created when |
| building the default target. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| GETTEXT_PROCESS_POT_FILE( <potfile> [ALL] [INSTALL_DESTINATION <destdir>] |
| LANGUAGES <lang1> <lang2> ... ) |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| Process the given pot file to mo files. |
| If INSTALL_DESTINATION is given then automatically install rules will |
| be created, the language subdirectory will be taken into account |
| (by default use share/locale/). |
| If ALL is specified, the pot file is processed when building the all target. |
| It creates a custom target "potfile". |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| GETTEXT_PROCESS_PO_FILES( <lang> [ALL] [INSTALL_DESTINATION <dir>] |
| PO_FILES <po1> <po2> ... ) |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| Process the given po files to mo files for the given language. |
| If INSTALL_DESTINATION is given then automatically install rules will |
| be created, the language subdirectory will be taken into account |
| (by default use share/locale/). |
| If ALL is specified, the po files are processed when building the all target. |
| It creates a custom target "pofiles". |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.2: If you wish to use the Gettext library (libintl), use \fBFindIntl\fP\&. |
| |
| .SS FindGIF |
| .sp |
| This finds the Graphics Interchange Format (GIF) library (\fBgiflib\fP) |
| .SS Imported targets |
| .sp |
| This module defines the following \fBIMPORTED\fP target: |
| .INDENT 0.0 |
| .TP |
| .B \fBGIF::GIF\fP |
| The \fBgiflib\fP library, if found. |
| .UNINDENT |
| .SS Result variables |
| .sp |
| This module will set the following variables in your project: |
| .INDENT 0.0 |
| .TP |
| .B \fBGIF_FOUND\fP |
| If false, do not try to use GIF. |
| .TP |
| .B \fBGIF_INCLUDE_DIRS\fP |
| where to find gif_lib.h, etc. |
| .TP |
| .B \fBGIF_LIBRARIES\fP |
| the libraries needed to use GIF. |
| .TP |
| .B \fBGIF_VERSION\fP |
| 3, 4 or a full version string (eg 5.1.4) for versions >= 4.1.6. |
| .UNINDENT |
| .SS Cache variables |
| .sp |
| The following cache variables may also be set: |
| .INDENT 0.0 |
| .TP |
| .B \fBGIF_INCLUDE_DIR\fP |
| where to find the GIF headers. |
| .TP |
| .B \fBGIF_LIBRARY\fP |
| where to find the GIF library. |
| .UNINDENT |
| .SS Hints |
| .sp |
| \fBGIF_DIR\fP is an environment variable that would correspond to the |
| \fB\&./configure \-\-prefix=$GIF_DIR\fP\&. |
| .SS FindGit |
| .sp |
| The module defines the following variables: |
| .INDENT 0.0 |
| .TP |
| .B \fBGIT_EXECUTABLE\fP |
| Path to Git command\-line client. |
| .TP |
| .B \fBGit_FOUND\fP, \fBGIT_FOUND\fP |
| True if the Git command\-line client was found. |
| .TP |
| .B \fBGIT_VERSION_STRING\fP |
| The version of Git found. |
| .UNINDENT |
| .sp |
| New in version 3.14: The module defines the following \fBIMPORTED\fP targets (when |
| \fBCMAKE_ROLE\fP is \fBPROJECT\fP): |
| |
| .INDENT 0.0 |
| .TP |
| .B \fBGit::Git\fP |
| Executable of the Git command\-line client. |
| .UNINDENT |
| .sp |
| Example usage: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_package(Git) |
| if(Git_FOUND) |
| message("Git found: ${GIT_EXECUTABLE}") |
| endif() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindGLEW |
| .sp |
| Find the OpenGL Extension Wrangler Library (GLEW) |
| .SS Input Variables |
| .sp |
| The following variables may be set to influence this module\(aqs behavior: |
| .INDENT 0.0 |
| .TP |
| .B \fBGLEW_USE_STATIC_LIBS\fP |
| to find and create \fBIMPORTED\fP target for static linkage. |
| .TP |
| .B \fBGLEW_VERBOSE\fP |
| to output a detailed log of this module. |
| .UNINDENT |
| .SS Imported Targets |
| .sp |
| New in version 3.1. |
| |
| .sp |
| This module defines the following Imported Targets: |
| .INDENT 0.0 |
| .TP |
| .B \fBGLEW::glew\fP |
| The GLEW shared library. |
| .TP |
| .B \fBGLEW::glew_s\fP |
| The GLEW static library, if \fBGLEW_USE_STATIC_LIBS\fP is set to \fBTRUE\fP\&. |
| .TP |
| .B \fBGLEW::GLEW\fP |
| Duplicates either \fBGLEW::glew\fP or \fBGLEW::glew_s\fP based on availability. |
| .UNINDENT |
| .SS Result Variables |
| .sp |
| This module defines the following variables: |
| .INDENT 0.0 |
| .TP |
| .B \fBGLEW_INCLUDE_DIRS\fP |
| include directories for GLEW |
| .TP |
| .B \fBGLEW_LIBRARIES\fP |
| libraries to link against GLEW |
| .TP |
| .B \fBGLEW_SHARED_LIBRARIES\fP |
| libraries to link against shared GLEW |
| .TP |
| .B \fBGLEW_STATIC_LIBRARIES\fP |
| libraries to link against static GLEW |
| .TP |
| .B \fBGLEW_FOUND\fP |
| true if GLEW has been found and can be used |
| .TP |
| .B \fBGLEW_VERSION\fP |
| GLEW version |
| .TP |
| .B \fBGLEW_VERSION_MAJOR\fP |
| GLEW major version |
| .TP |
| .B \fBGLEW_VERSION_MINOR\fP |
| GLEW minor version |
| .TP |
| .B \fBGLEW_VERSION_MICRO\fP |
| GLEW micro version |
| .UNINDENT |
| .sp |
| New in version 3.7: Debug and Release variants are found separately. |
| |
| .SS FindGLUT |
| .sp |
| Find OpenGL Utility Toolkit (GLUT) library and include files. |
| .SS IMPORTED Targets |
| .sp |
| New in version 3.1. |
| |
| .sp |
| This module defines the \fBIMPORTED\fP targets: |
| .INDENT 0.0 |
| .TP |
| .B \fBGLUT::GLUT\fP |
| Defined if the system has GLUT. |
| .UNINDENT |
| .SS Result Variables |
| .sp |
| This module defines the following variables: |
| .INDENT 0.0 |
| .TP |
| .B \fBGLUT_FOUND\fP |
| True if \fBglut\fP was found. |
| .TP |
| .B \fBGLUT_INCLUDE_DIRS\fP |
| New in version 3.23. |
| |
| .sp |
| Where to find GL/glut.h, etc. |
| .TP |
| .B \fBGLUT_LIBRARIES\fP |
| List of libraries for using \fBglut\fP\&. |
| .UNINDENT |
| .SS Cache Variables |
| .sp |
| This module may set the following variables depending on platform. |
| These variables may optionally be set to help this module find the |
| correct files, but clients should not use these as results: |
| .INDENT 0.0 |
| .TP |
| .B \fBGLUT_INCLUDE_DIR\fP |
| The full path to the directory containing \fBGL/glut.h\fP, |
| not including \fBGL/\fP\&. |
| .TP |
| .B \fBGLUT_glut_LIBRARY\fP |
| The full path to the glut library. |
| .TP |
| .B \fBGLUT_Xmu_LIBRARY\fP |
| The full path to the Xmu library. |
| .TP |
| .B \fBGLUT_Xi_LIBRARY\fP |
| The full path to the Xi Library. |
| .UNINDENT |
| .SS Obsolete Variables |
| .sp |
| The following variables may also be provided, for backwards compatibility: |
| .INDENT 0.0 |
| .TP |
| .B \fBGLUT_INCLUDE_DIR\fP |
| This is one of above \fI\%Cache Variables\fP, but prior to CMake 3.23 was |
| also a result variable. Prefer to use \fBGLUT_INCLUDE_DIRS\fP instead |
| in CMake 3.23 and above. |
| .UNINDENT |
| .SS FindGnuplot |
| .sp |
| this module looks for gnuplot |
| .sp |
| Once done this will define |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| GNUPLOT_FOUND \- system has Gnuplot |
| GNUPLOT_EXECUTABLE \- the Gnuplot executable |
| GNUPLOT_VERSION_STRING \- the version of Gnuplot found (since CMake 2.8.8) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| GNUPLOT_VERSION_STRING will not work for old versions like 3.7.1. |
| .SS FindGnuTLS |
| .sp |
| Find the GNU Transport Layer Security library (gnutls) |
| .SS IMPORTED Targets |
| .sp |
| New in version 3.16. |
| |
| .sp |
| This module defines \fBIMPORTED\fP target \fBGnuTLS::GnuTLS\fP, if |
| gnutls has been found. |
| .SS Result Variables |
| .INDENT 0.0 |
| .TP |
| .B \fBGNUTLS_FOUND\fP |
| System has gnutls |
| .TP |
| .B \fBGNUTLS_INCLUDE_DIR\fP |
| The gnutls include directory |
| .TP |
| .B \fBGNUTLS_LIBRARIES\fP |
| The libraries needed to use gnutls |
| .TP |
| .B \fBGNUTLS_DEFINITIONS\fP |
| Compiler switches required for using gnutls |
| .TP |
| .B \fBGNUTLS_VERSION\fP |
| version of gnutls. |
| .UNINDENT |
| .SS FindGSL |
| .sp |
| New in version 3.2. |
| |
| .sp |
| Find the native GNU Scientific Library (GSL) includes and libraries. |
| .sp |
| The GNU Scientific Library (GSL) is a numerical library for C and C++ |
| programmers. It is free software under the GNU General Public |
| License. |
| .SS Imported Targets |
| .sp |
| If GSL is found, this module defines the following \fBIMPORTED\fP |
| targets: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| GSL::gsl \- The main GSL library. |
| GSL::gslcblas \- The CBLAS support library used by GSL. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS Result Variables |
| .sp |
| This module will set the following variables in your project: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| GSL_FOUND \- True if GSL found on the local system |
| GSL_INCLUDE_DIRS \- Location of GSL header files. |
| GSL_LIBRARIES \- The GSL libraries. |
| GSL_VERSION \- The version of the discovered GSL install. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS Hints |
| .sp |
| Set \fBGSL_ROOT_DIR\fP to a directory that contains a GSL installation. |
| .sp |
| This script expects to find libraries at \fB$GSL_ROOT_DIR/lib\fP and the GSL |
| headers at \fB$GSL_ROOT_DIR/include/gsl\fP\&. The library directory may |
| optionally provide Release and Debug folders. If available, the libraries |
| named \fBgsld\fP, \fBgslblasd\fP or \fBcblasd\fP are recognized as debug libraries. |
| For Unix\-like systems, this script will use \fB$GSL_ROOT_DIR/bin/gsl\-config\fP |
| (if found) to aid in the discovery of GSL. |
| .SS Cache Variables |
| .sp |
| This module may set the following variables depending on platform and type |
| of GSL installation discovered. These variables may optionally be set to |
| help this module find the correct files: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| GSL_CBLAS_LIBRARY \- Location of the GSL CBLAS library. |
| GSL_CBLAS_LIBRARY_DEBUG \- Location of the debug GSL CBLAS library (if any). |
| GSL_CONFIG_EXECUTABLE \- Location of the \(ga\(gagsl\-config\(ga\(ga script (if any). |
| GSL_LIBRARY \- Location of the GSL library. |
| GSL_LIBRARY_DEBUG \- Location of the debug GSL library (if any). |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindGTest |
| .sp |
| Locate the Google C++ Testing Framework. |
| .sp |
| New in version 3.20: Upstream \fBGTestConfig.cmake\fP is used if possible. |
| |
| .SS Imported targets |
| .sp |
| New in version 3.20: This module defines the following \fBIMPORTED\fP targets: |
| |
| .INDENT 0.0 |
| .TP |
| .B \fBGTest::gtest\fP |
| The Google Test \fBgtest\fP library, if found; adds Thread::Thread |
| automatically |
| .TP |
| .B \fBGTest::gtest_main\fP |
| The Google Test \fBgtest_main\fP library, if found |
| .UNINDENT |
| .sp |
| New in version 3.23. |
| |
| .INDENT 0.0 |
| .TP |
| .B \fBGTest::gmock\fP |
| The Google Mock \fBgmock\fP library, if found; adds Thread::Thread |
| automatically |
| .TP |
| .B \fBGTest::gmock_main\fP |
| The Google Mock \fBgmock_main\fP library, if found |
| .UNINDENT |
| .sp |
| Deprecated since version 3.20: For backwards compatibility, this module defines additionally the |
| following deprecated \fBIMPORTED\fP targets (available since 3.5): |
| |
| .INDENT 0.0 |
| .TP |
| .B \fBGTest::GTest\fP |
| The Google Test \fBgtest\fP library, if found; adds Thread::Thread |
| automatically |
| .TP |
| .B \fBGTest::Main\fP |
| The Google Test \fBgtest_main\fP library, if found |
| .UNINDENT |
| .SS Result variables |
| .sp |
| This module will set the following variables in your project: |
| .INDENT 0.0 |
| .TP |
| .B \fBGTest_FOUND\fP |
| Found the Google Testing framework |
| .TP |
| .B \fBGTEST_INCLUDE_DIRS\fP |
| the directory containing the Google Test headers |
| .UNINDENT |
| .sp |
| The library variables below are set as normal variables. These |
| contain debug/optimized keywords when a debugging library is found. |
| .INDENT 0.0 |
| .TP |
| .B \fBGTEST_LIBRARIES\fP |
| The Google Test \fBgtest\fP library; note it also requires linking |
| with an appropriate thread library |
| .TP |
| .B \fBGTEST_MAIN_LIBRARIES\fP |
| The Google Test \fBgtest_main\fP library |
| .TP |
| .B \fBGTEST_BOTH_LIBRARIES\fP |
| Both \fBgtest\fP and \fBgtest_main\fP |
| .UNINDENT |
| .SS Cache variables |
| .sp |
| The following cache variables may also be set: |
| .INDENT 0.0 |
| .TP |
| .B \fBGTEST_ROOT\fP |
| The root directory of the Google Test installation (may also be |
| set as an environment variable) |
| .TP |
| .B \fBGTEST_MSVC_SEARCH\fP |
| If compiling with MSVC, this variable can be set to \fBMT\fP or |
| \fBMD\fP (the default) to enable searching a GTest build tree |
| .UNINDENT |
| .SS Example usage |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| enable_testing() |
| find_package(GTest REQUIRED) |
| |
| add_executable(foo foo.cc) |
| target_link_libraries(foo GTest::gtest GTest::gtest_main) |
| |
| add_test(AllTestsInFoo foo) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS Deeper integration with CTest |
| .sp |
| See \fBGoogleTest\fP for information on the \fBgtest_add_tests()\fP |
| and \fBgtest_discover_tests()\fP commands. |
| .sp |
| Changed in version 3.9: Previous CMake versions defined \fBgtest_add_tests()\fP macro in this |
| module. |
| |
| .SS FindGTK |
| .sp |
| Find GTK, glib and GTKGLArea |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| GTK_INCLUDE_DIR \- Directories to include to use GTK |
| GTK_LIBRARIES \- Files to link against to use GTK |
| GTK_FOUND \- GTK was found |
| GTK_GL_FOUND \- GTK\(aqs GL features were found |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindGTK2 |
| .sp |
| Find the GTK2 widget libraries and several of its other optional components |
| like \fBgtkmm\fP, \fBglade\fP, and \fBglademm\fP\&. |
| .sp |
| Specify one or more of the following components as you call this find |
| module. See example below. |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBgtk\fP |
| .IP \(bu 2 |
| \fBgtkmm\fP |
| .IP \(bu 2 |
| \fBglade\fP |
| .IP \(bu 2 |
| \fBglademm\fP |
| .UNINDENT |
| .SS Imported Targets |
| .sp |
| This module defines the following \fBIMPORTED\fP targets (subject to |
| component selection): |
| .sp |
| \fBGTK2::atk\fP, \fBGTK2::atkmm\fP, \fBGTK2::cairo\fP, \fBGTK2::cairomm\fP, |
| \fBGTK2::gdk_pixbuf\fP, \fBGTK2::gdk\fP, \fBGTK2::gdkmm\fP, \fBGTK2::gio\fP, |
| \fBGTK2::giomm\fP, \fBGTK2::glade\fP, \fBGTK2::glademm\fP, \fBGTK2::glib\fP, |
| \fBGTK2::glibmm\fP, \fBGTK2::gmodule\fP, \fBGTK2::gobject\fP, \fBGTK2::gthread\fP, |
| \fBGTK2::gtk\fP, \fBGTK2::gtkmm\fP, \fBGTK2::harfbuzz\fP, \fBGTK2::pango\fP, |
| \fBGTK2::pangocairo\fP, \fBGTK2::pangoft2\fP, \fBGTK2::pangomm\fP, |
| \fBGTK2::pangoxft\fP, \fBGTK2::sigc\fP\&. |
| .sp |
| New in version 3.16.7: Added the \fBGTK2::harfbuzz\fP target. |
| |
| .SS Result Variables |
| .sp |
| The following variables will be defined for your use |
| .INDENT 0.0 |
| .TP |
| .B \fBGTK2_FOUND\fP |
| Were all of your specified components found? |
| .TP |
| .B \fBGTK2_INCLUDE_DIRS\fP |
| All include directories |
| .TP |
| .B \fBGTK2_LIBRARIES\fP |
| All libraries |
| .TP |
| .B \fBGTK2_TARGETS\fP |
| New in version 3.5: All imported targets |
| |
| .TP |
| .B \fBGTK2_DEFINITIONS\fP |
| Additional compiler flags |
| .TP |
| .B \fBGTK2_VERSION\fP |
| The version of GTK2 found (x.y.z) |
| .TP |
| .B \fBGTK2_MAJOR_VERSION\fP |
| The major version of GTK2 |
| .TP |
| .B \fBGTK2_MINOR_VERSION\fP |
| The minor version of GTK2 |
| .TP |
| .B \fBGTK2_PATCH_VERSION\fP |
| The patch version of GTK2 |
| .UNINDENT |
| .sp |
| New in version 3.5: When \fBGTK2_USE_IMPORTED_TARGETS\fP is set to \fBTRUE\fP, \fBGTK2_LIBRARIES\fP |
| will list imported targets instead of library paths. |
| |
| .SS Input Variables |
| .sp |
| Optional variables you can define prior to calling this module: |
| .INDENT 0.0 |
| .TP |
| .B \fBGTK2_DEBUG\fP |
| Enables verbose debugging of the module |
| .TP |
| .B \fBGTK2_ADDITIONAL_SUFFIXES\fP |
| Allows defining additional directories to search for include files |
| .UNINDENT |
| .SS Example Usage |
| .sp |
| Call \fBfind_package()\fP once. Here are some examples to pick from: |
| .sp |
| Require GTK 2.6 or later: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_package(GTK2 2.6 REQUIRED gtk) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Require GTK 2.10 or later and Glade: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_package(GTK2 2.10 REQUIRED gtk glade) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Search for GTK/GTKMM 2.8 or later: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_package(GTK2 2.8 COMPONENTS gtk gtkmm) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Use the results: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| if(GTK2_FOUND) |
| include_directories(${GTK2_INCLUDE_DIRS}) |
| add_executable(mygui mygui.cc) |
| target_link_libraries(mygui ${GTK2_LIBRARIES}) |
| endif() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindHDF5 |
| .sp |
| Find Hierarchical Data Format (HDF5), a library for reading and writing |
| self describing array data. |
| .sp |
| This module invokes the \fBHDF5\fP wrapper compiler that should be installed |
| alongside \fBHDF5\fP\&. Depending upon the \fBHDF5\fP Configuration, the wrapper |
| compiler is called either \fBh5cc\fP or \fBh5pcc\fP\&. If this succeeds, the module |
| will then call the compiler with the show argument to see what flags |
| are used when compiling an \fBHDF5\fP client application. |
| .sp |
| The module will optionally accept the \fBCOMPONENTS\fP argument. If no |
| \fBCOMPONENTS\fP are specified, then the find module will default to finding |
| only the \fBHDF5\fP C library. If one or more \fBCOMPONENTS\fP are specified, the |
| module will attempt to find the language bindings for the specified |
| components. The valid components are \fBC\fP, \fBCXX\fP, \fBFortran\fP, \fBHL\fP\&. |
| \fBHL\fP refers to the "high\-level" HDF5 functions for C and Fortran. |
| If the \fBCOMPONENTS\fP argument is not given, the module will |
| attempt to find only the C bindings. |
| For example, to use Fortran HDF5 and HDF5\-HL functions, do: |
| \fBfind_package(HDF5 COMPONENTS Fortran HL)\fP\&. |
| .sp |
| This module will read the variable |
| \fBHDF5_USE_STATIC_LIBRARIES\fP to determine whether or not to prefer a |
| static link to a dynamic link for \fBHDF5\fP and all of it\(aqs dependencies. |
| To use this feature, make sure that the \fBHDF5_USE_STATIC_LIBRARIES\fP |
| variable is set before the call to find_package. |
| .sp |
| New in version 3.10: Support for \fBHDF5_USE_STATIC_LIBRARIES\fP on Windows. |
| |
| .sp |
| Both the serial and parallel \fBHDF5\fP wrappers are considered and the first |
| directory to contain either one will be used. In the event that both appear |
| in the same directory the serial version is preferentially selected. This |
| behavior can be reversed by setting the variable \fBHDF5_PREFER_PARALLEL\fP to |
| \fBTRUE\fP\&. |
| .sp |
| In addition to finding the includes and libraries required to compile |
| an \fBHDF5\fP client application, this module also makes an effort to find |
| tools that come with the \fBHDF5\fP distribution that may be useful for |
| regression testing. |
| .SS Result Variables |
| .sp |
| This module will set the following variables in your project: |
| .INDENT 0.0 |
| .TP |
| .B \fBHDF5_FOUND\fP |
| HDF5 was found on the system |
| .TP |
| .B \fBHDF5_VERSION\fP |
| New in version 3.3: HDF5 library version |
| |
| .TP |
| .B \fBHDF5_INCLUDE_DIRS\fP |
| Location of the HDF5 header files |
| .TP |
| .B \fBHDF5_DEFINITIONS\fP |
| Required compiler definitions for HDF5 |
| .TP |
| .B \fBHDF5_LIBRARIES\fP |
| Required libraries for all requested bindings |
| .TP |
| .B \fBHDF5_HL_LIBRARIES\fP |
| Required libraries for the HDF5 high level API for all bindings, |
| if the \fBHL\fP component is enabled |
| .UNINDENT |
| .sp |
| Available components are: \fBC\fP \fBCXX\fP \fBFortran\fP and \fBHL\fP\&. |
| For each enabled language binding, a corresponding \fBHDF5_${LANG}_LIBRARIES\fP |
| variable, and potentially \fBHDF5_${LANG}_DEFINITIONS\fP, will be defined. |
| If the \fBHL\fP component is enabled, then an \fBHDF5_${LANG}_HL_LIBRARIES\fP will |
| also be defined. With all components enabled, the following variables will be defined: |
| .INDENT 0.0 |
| .TP |
| .B \fBHDF5_C_DEFINITIONS\fP |
| Required compiler definitions for HDF5 C bindings |
| .TP |
| .B \fBHDF5_CXX_DEFINITIONS\fP |
| Required compiler definitions for HDF5 C++ bindings |
| .TP |
| .B \fBHDF5_Fortran_DEFINITIONS\fP |
| Required compiler definitions for HDF5 Fortran bindings |
| .TP |
| .B \fBHDF5_C_INCLUDE_DIRS\fP |
| Required include directories for HDF5 C bindings |
| .TP |
| .B \fBHDF5_CXX_INCLUDE_DIRS\fP |
| Required include directories for HDF5 C++ bindings |
| .TP |
| .B \fBHDF5_Fortran_INCLUDE_DIRS\fP |
| Required include directories for HDF5 Fortran bindings |
| .TP |
| .B \fBHDF5_C_LIBRARIES\fP |
| Required libraries for the HDF5 C bindings |
| .TP |
| .B \fBHDF5_CXX_LIBRARIES\fP |
| Required libraries for the HDF5 C++ bindings |
| .TP |
| .B \fBHDF5_Fortran_LIBRARIES\fP |
| Required libraries for the HDF5 Fortran bindings |
| .TP |
| .B \fBHDF5_C_HL_LIBRARIES\fP |
| Required libraries for the high level C bindings |
| .TP |
| .B \fBHDF5_CXX_HL_LIBRARIES\fP |
| Required libraries for the high level C++ bindings |
| .TP |
| .B \fBHDF5_Fortran_HL_LIBRARIES\fP |
| Required libraries for the high level Fortran bindings. |
| .TP |
| .B \fBHDF5_IS_PARALLEL\fP |
| HDF5 library has parallel IO support |
| .TP |
| .B \fBHDF5_C_COMPILER_EXECUTABLE\fP |
| path to the HDF5 C wrapper compiler |
| .TP |
| .B \fBHDF5_CXX_COMPILER_EXECUTABLE\fP |
| path to the HDF5 C++ wrapper compiler |
| .TP |
| .B \fBHDF5_Fortran_COMPILER_EXECUTABLE\fP |
| path to the HDF5 Fortran wrapper compiler |
| .TP |
| .B \fBHDF5_C_COMPILER_EXECUTABLE_NO_INTERROGATE\fP |
| path to the primary C compiler which is also the HDF5 wrapper |
| .TP |
| .B \fBHDF5_CXX_COMPILER_EXECUTABLE_NO_INTERROGATE\fP |
| path to the primary C++ compiler which is also the HDF5 wrapper |
| .TP |
| .B \fBHDF5_Fortran_COMPILER_EXECUTABLE_NO_INTERROGATE\fP |
| path to the primary Fortran compiler which is also the HDF5 wrapper |
| .TP |
| .B \fBHDF5_DIFF_EXECUTABLE\fP |
| path to the HDF5 dataset comparison tool |
| .UNINDENT |
| .sp |
| With all components enabled, the following targets will be defined: |
| .INDENT 0.0 |
| .TP |
| .B \fBHDF5::HDF5\fP |
| All detected \fBHDF5_LIBRARIES\fP\&. |
| .TP |
| .B \fBhdf5::hdf5\fP |
| C library. |
| .TP |
| .B \fBhdf5::hdf5_cpp\fP |
| C++ library. |
| .TP |
| .B \fBhdf5::hdf5_fortran\fP |
| Fortran library. |
| .TP |
| .B \fBhdf5::hdf5_hl\fP |
| High\-level C library. |
| .TP |
| .B \fBhdf5::hdf5_hl_cpp\fP |
| High\-level C++ library. |
| .TP |
| .B \fBhdf5::hdf5_hl_fortran\fP |
| High\-level Fortran library. |
| .TP |
| .B \fBhdf5::h5diff\fP |
| \fBh5diff\fP executable. |
| .UNINDENT |
| .SS Hints |
| .sp |
| The following variables can be set to guide the search for HDF5 libraries and includes: |
| .INDENT 0.0 |
| .TP |
| .B \fBHDF5_PREFER_PARALLEL\fP |
| New in version 3.4. |
| |
| .sp |
| set \fBtrue\fP to prefer parallel HDF5 (by default, serial is preferred) |
| .TP |
| .B \fBHDF5_FIND_DEBUG\fP |
| New in version 3.9. |
| |
| .sp |
| Set \fBtrue\fP to get extra debugging output. |
| .TP |
| .B \fBHDF5_NO_FIND_PACKAGE_CONFIG_FILE\fP |
| New in version 3.8. |
| |
| .sp |
| Set \fBtrue\fP to skip trying to find \fBhdf5\-config.cmake\fP\&. |
| .UNINDENT |
| .SS FindHg |
| .sp |
| Extract information from a mercurial working copy. |
| .sp |
| The module defines the following variables: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| HG_EXECUTABLE \- path to mercurial command line client (hg) |
| HG_FOUND \- true if the command line client was found |
| HG_VERSION_STRING \- the version of mercurial found |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.1: If the command line client executable is found the following macro is defined: |
| |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| HG_WC_INFO(<dir> <var\-prefix>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Hg_WC_INFO extracts information of a mercurial working copy |
| at a given location. This macro defines the following variables: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| <var\-prefix>_WC_CHANGESET \- current changeset |
| <var\-prefix>_WC_REVISION \- current revision |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Example usage: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_package(Hg) |
| if(HG_FOUND) |
| message("hg found: ${HG_EXECUTABLE}") |
| HG_WC_INFO(${PROJECT_SOURCE_DIR} Project) |
| message("Current revision is ${Project_WC_REVISION}") |
| message("Current changeset is ${Project_WC_CHANGESET}") |
| endif() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindHSPELL |
| .sp |
| Try to find Hebrew spell\-checker (Hspell) and morphology engine. |
| .sp |
| Once done this will define |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| HSPELL_FOUND \- system has Hspell |
| HSPELL_INCLUDE_DIR \- the Hspell include directory |
| HSPELL_LIBRARIES \- The libraries needed to use Hspell |
| HSPELL_DEFINITIONS \- Compiler switches required for using Hspell |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| HSPELL_VERSION_STRING \- The version of Hspell found (x.y) |
| HSPELL_MAJOR_VERSION \- the major version of Hspell |
| HSPELL_MINOR_VERSION \- The minor version of Hspell |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindHTMLHelp |
| .sp |
| This module looks for Microsoft HTML Help Compiler |
| .sp |
| It defines: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| HTML_HELP_COMPILER : full path to the Compiler (hhc.exe) |
| HTML_HELP_INCLUDE_PATH : include path to the API (htmlhelp.h) |
| HTML_HELP_LIBRARY : full path to the library (htmlhelp.lib) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindIce |
| .sp |
| New in version 3.1. |
| |
| .sp |
| Find the ZeroC Internet Communication Engine (ICE) programs, |
| libraries and datafiles. |
| .sp |
| This module supports multiple components. |
| Components can include any of: \fBFreeze\fP, \fBGlacier2\fP, \fBIce\fP, |
| \fBIceBox\fP, \fBIceDB\fP, \fBIceDiscovery\fP, \fBIceGrid\fP, |
| \fBIceLocatorDiscovery\fP, \fBIcePatch\fP, \fBIceSSL\fP, \fBIceStorm\fP, |
| \fBIceUtil\fP, \fBIceXML\fP, or \fBSlice\fP\&. |
| .sp |
| Ice 3.7 and later also include C++11\-specific components: |
| \fBGlacier2++11\fP, \fBIce++11\fP, \fBIceBox++11\fP, \fBIceDiscovery++11\fP |
| \fBIceGrid\fP, \fBIceLocatorDiscovery++11\fP, \fBIceSSL++11\fP, |
| \fBIceStorm++11\fP |
| .sp |
| Note that the set of supported components is Ice version\-specific. |
| .sp |
| New in version 3.4: Imported targets for components and most \fBEXECUTABLE\fP variables. |
| |
| .sp |
| New in version 3.7: Debug and Release variants are found separately. |
| |
| .sp |
| New in version 3.10: Ice 3.7 support, including new components, programs and the Nuget package. |
| |
| .sp |
| This module reports information about the Ice installation in |
| several variables. General variables: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| Ice_VERSION \- Ice release version |
| Ice_FOUND \- true if the main programs and libraries were found |
| Ice_LIBRARIES \- component libraries to be linked |
| Ice_INCLUDE_DIRS \- the directories containing the Ice headers |
| Ice_SLICE_DIRS \- the directories containing the Ice slice interface |
| definitions |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Imported targets: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| Ice::<C> |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Where \fB<C>\fP is the name of an Ice component, for example |
| \fBIce::Glacier2\fP or \fBIce++11\fP\&. |
| .sp |
| Ice slice programs are reported in: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| Ice_SLICE2CONFLUENCE_EXECUTABLE \- path to slice2confluence executable |
| Ice_SLICE2CPP_EXECUTABLE \- path to slice2cpp executable |
| Ice_SLICE2CS_EXECUTABLE \- path to slice2cs executable |
| Ice_SLICE2FREEZEJ_EXECUTABLE \- path to slice2freezej executable |
| Ice_SLICE2FREEZE_EXECUTABLE \- path to slice2freeze executable |
| Ice_SLICE2HTML_EXECUTABLE \- path to slice2html executable |
| Ice_SLICE2JAVA_EXECUTABLE \- path to slice2java executable |
| Ice_SLICE2JS_EXECUTABLE \- path to slice2js executable |
| Ice_SLICE2MATLAB_EXECUTABLE \- path to slice2matlab executable |
| Ice_SLICE2OBJC_EXECUTABLE \- path to slice2objc executable |
| Ice_SLICE2PHP_EXECUTABLE \- path to slice2php executable |
| Ice_SLICE2PY_EXECUTABLE \- path to slice2py executable |
| Ice_SLICE2RB_EXECUTABLE \- path to slice2rb executable |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.14: Variables for \fBslice2confluence\fP and \fBslice2matlab\fP\&. |
| |
| .sp |
| Ice programs are reported in: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| Ice_GLACIER2ROUTER_EXECUTABLE \- path to glacier2router executable |
| Ice_ICEBOX_EXECUTABLE \- path to icebox executable |
| Ice_ICEBOXXX11_EXECUTABLE \- path to icebox++11 executable |
| Ice_ICEBOXADMIN_EXECUTABLE \- path to iceboxadmin executable |
| Ice_ICEBOXD_EXECUTABLE \- path to iceboxd executable |
| Ice_ICEBOXNET_EXECUTABLE \- path to iceboxnet executable |
| Ice_ICEBRIDGE_EXECUTABLE \- path to icebridge executable |
| Ice_ICEGRIDADMIN_EXECUTABLE \- path to icegridadmin executable |
| Ice_ICEGRIDDB_EXECUTABLE \- path to icegriddb executable |
| Ice_ICEGRIDNODE_EXECUTABLE \- path to icegridnode executable |
| Ice_ICEGRIDNODED_EXECUTABLE \- path to icegridnoded executable |
| Ice_ICEGRIDREGISTRY_EXECUTABLE \- path to icegridregistry executable |
| Ice_ICEGRIDREGISTRYD_EXECUTABLE \- path to icegridregistryd executable |
| Ice_ICEPATCH2CALC_EXECUTABLE \- path to icepatch2calc executable |
| Ice_ICEPATCH2CLIENT_EXECUTABLE \- path to icepatch2client executable |
| Ice_ICEPATCH2SERVER_EXECUTABLE \- path to icepatch2server executable |
| Ice_ICESERVICEINSTALL_EXECUTABLE \- path to iceserviceinstall executable |
| Ice_ICESTORMADMIN_EXECUTABLE \- path to icestormadmin executable |
| Ice_ICESTORMDB_EXECUTABLE \- path to icestormdb executable |
| Ice_ICESTORMMIGRATE_EXECUTABLE \- path to icestormmigrate executable |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Ice db programs (Windows only; standard system versions on all other |
| platforms) are reported in: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| Ice_DB_ARCHIVE_EXECUTABLE \- path to db_archive executable |
| Ice_DB_CHECKPOINT_EXECUTABLE \- path to db_checkpoint executable |
| Ice_DB_DEADLOCK_EXECUTABLE \- path to db_deadlock executable |
| Ice_DB_DUMP_EXECUTABLE \- path to db_dump executable |
| Ice_DB_HOTBACKUP_EXECUTABLE \- path to db_hotbackup executable |
| Ice_DB_LOAD_EXECUTABLE \- path to db_load executable |
| Ice_DB_LOG_VERIFY_EXECUTABLE \- path to db_log_verify executable |
| Ice_DB_PRINTLOG_EXECUTABLE \- path to db_printlog executable |
| Ice_DB_RECOVER_EXECUTABLE \- path to db_recover executable |
| Ice_DB_STAT_EXECUTABLE \- path to db_stat executable |
| Ice_DB_TUNER_EXECUTABLE \- path to db_tuner executable |
| Ice_DB_UPGRADE_EXECUTABLE \- path to db_upgrade executable |
| Ice_DB_VERIFY_EXECUTABLE \- path to db_verify executable |
| Ice_DUMPDB_EXECUTABLE \- path to dumpdb executable |
| Ice_TRANSFORMDB_EXECUTABLE \- path to transformdb executable |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Ice component libraries are reported in: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| Ice_<C>_FOUND \- ON if component was found |
| Ice_<C>_LIBRARIES \- libraries for component |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Note that \fB<C>\fP is the uppercased name of the component. |
| .sp |
| This module reads hints about search results from: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| Ice_HOME \- the root of the Ice installation |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The environment variable \fBICE_HOME\fP may also be used; the |
| Ice_HOME variable takes precedence. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| On Windows, Ice 3.7.0 and later provide libraries via the NuGet |
| package manager. Appropriate NuGet packages will be searched for |
| using \fBCMAKE_PREFIX_PATH\fP, or alternatively \fBIce_HOME\fP may be |
| set to the location of a specific NuGet package to restrict the |
| search. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The following cache variables may also be set: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| Ice_<P>_EXECUTABLE \- the path to executable <P> |
| Ice_INCLUDE_DIR \- the directory containing the Ice headers |
| Ice_SLICE_DIR \- the directory containing the Ice slice interface |
| definitions |
| Ice_<C>_LIBRARY \- the library for component <C> |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| In most cases none of the above variables will require setting, |
| unless multiple Ice versions are available and a specific version |
| is required. On Windows, the most recent version of Ice will be |
| found through the registry. On Unix, the programs, headers and |
| libraries will usually be in standard locations, but Ice_SLICE_DIRS |
| might not be automatically detected (commonly known locations are |
| searched). All the other variables are defaulted using Ice_HOME, |
| if set. It\(aqs possible to set Ice_HOME and selectively specify |
| alternative locations for the other components; this might be |
| required for e.g. newer versions of Visual Studio if the |
| heuristics are not sufficient to identify the correct programs and |
| libraries for the specific Visual Studio version. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Other variables one may set to control this module are: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| Ice_DEBUG \- Set to ON to enable debug output from FindIce. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindIconv |
| .sp |
| New in version 3.11. |
| |
| .sp |
| This module finds the \fBiconv()\fP POSIX.1 functions on the system. |
| These functions might be provided in the regular C library or externally |
| in the form of an additional library. |
| .sp |
| The following variables are provided to indicate iconv support: |
| .INDENT 0.0 |
| .TP |
| .B Iconv_FOUND |
| Variable indicating if the iconv support was found. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B Iconv_INCLUDE_DIRS |
| The directories containing the iconv headers. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B Iconv_LIBRARIES |
| The iconv libraries to be linked. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B Iconv_VERSION |
| New in version 3.21. |
| |
| .sp |
| The version of iconv found (x.y) |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B Iconv_VERSION_MAJOR |
| New in version 3.21. |
| |
| .sp |
| The major version of iconv |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B Iconv_VERSION_MINOR |
| New in version 3.21. |
| |
| .sp |
| The minor version of iconv |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B Iconv_IS_BUILT_IN |
| A variable indicating whether iconv support is stemming from the |
| C library or not. Even if the C library provides \fIiconv()\fP, the presence of |
| an external \fIlibiconv\fP implementation might lead to this being false. |
| .UNINDENT |
| .sp |
| Additionally, the following \fBIMPORTED\fP target is being provided: |
| .INDENT 0.0 |
| .TP |
| .B Iconv::Iconv |
| Imported target for using iconv. |
| .UNINDENT |
| .sp |
| The following cache variables may also be set: |
| .INDENT 0.0 |
| .TP |
| .B Iconv_INCLUDE_DIR |
| The directory containing the iconv headers. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B Iconv_LIBRARY |
| The iconv library (if not implicitly given in the C library). |
| .UNINDENT |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| On POSIX platforms, iconv might be part of the C library and the cache |
| variables \fBIconv_INCLUDE_DIR\fP and \fBIconv_LIBRARY\fP might be empty. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| Some libiconv implementations don\(aqt embed the version number in their header files. |
| In this case the variables \fBIconv_VERSION*\fP will be empty. |
| .UNINDENT |
| .UNINDENT |
| .SS FindIcotool |
| .sp |
| Find icotool |
| .sp |
| This module looks for icotool. Convert and create Win32 icon and cursor files. |
| This module defines the following values: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ICOTOOL_EXECUTABLE: the full path to the icotool tool. |
| ICOTOOL_FOUND: True if icotool has been found. |
| ICOTOOL_VERSION_STRING: the version of icotool found. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindICU |
| .sp |
| New in version 3.7. |
| |
| .sp |
| Find the International Components for Unicode (ICU) libraries and |
| programs. |
| .sp |
| This module supports multiple components. |
| Components can include any of: \fBdata\fP, \fBi18n\fP, \fBio\fP, \fBle\fP, |
| \fBlx\fP, \fBtest\fP, \fBtu\fP and \fBuc\fP\&. |
| .sp |
| Note that on Windows \fBdata\fP is named \fBdt\fP and \fBi18n\fP is named |
| \fBin\fP; any of the names may be used, and the appropriate |
| platform\-specific library name will be automatically selected. |
| .sp |
| New in version 3.11: Added support for static libraries on Windows. |
| |
| .sp |
| This module reports information about the ICU installation in |
| several variables. General variables: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ICU_VERSION \- ICU release version |
| ICU_FOUND \- true if the main programs and libraries were found |
| ICU_LIBRARIES \- component libraries to be linked |
| ICU_INCLUDE_DIRS \- the directories containing the ICU headers |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Imported targets: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ICU::<C> |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Where \fB<C>\fP is the name of an ICU component, for example |
| \fBICU::i18n\fP; \fB<C>\fP is lower\-case. |
| .sp |
| ICU programs are reported in: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ICU_GENCNVAL_EXECUTABLE \- path to gencnval executable |
| ICU_ICUINFO_EXECUTABLE \- path to icuinfo executable |
| ICU_GENBRK_EXECUTABLE \- path to genbrk executable |
| ICU_ICU\-CONFIG_EXECUTABLE \- path to icu\-config executable |
| ICU_GENRB_EXECUTABLE \- path to genrb executable |
| ICU_GENDICT_EXECUTABLE \- path to gendict executable |
| ICU_DERB_EXECUTABLE \- path to derb executable |
| ICU_PKGDATA_EXECUTABLE \- path to pkgdata executable |
| ICU_UCONV_EXECUTABLE \- path to uconv executable |
| ICU_GENCFU_EXECUTABLE \- path to gencfu executable |
| ICU_MAKECONV_EXECUTABLE \- path to makeconv executable |
| ICU_GENNORM2_EXECUTABLE \- path to gennorm2 executable |
| ICU_GENCCODE_EXECUTABLE \- path to genccode executable |
| ICU_GENSPREP_EXECUTABLE \- path to gensprep executable |
| ICU_ICUPKG_EXECUTABLE \- path to icupkg executable |
| ICU_GENCMN_EXECUTABLE \- path to gencmn executable |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| ICU component libraries are reported in: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ICU_<C>_FOUND \- ON if component was found; \(ga\(ga<C>\(ga\(ga is upper\-case. |
| ICU_<C>_LIBRARIES \- libraries for component; \(ga\(ga<C>\(ga\(ga is upper\-case. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| ICU datafiles are reported in: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ICU_MAKEFILE_INC \- Makefile.inc |
| ICU_PKGDATA_INC \- pkgdata.inc |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This module reads hints about search results from: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ICU_ROOT \- the root of the ICU installation |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The environment variable \fBICU_ROOT\fP may also be used; the |
| ICU_ROOT variable takes precedence. |
| .sp |
| The following cache variables may also be set: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ICU_<P>_EXECUTABLE \- the path to executable <P>; \(ga\(ga<P>\(ga\(ga is upper\-case. |
| ICU_INCLUDE_DIR \- the directory containing the ICU headers |
| ICU_<C>_LIBRARY \- the library for component <C>; \(ga\(ga<C>\(ga\(ga is upper\-case. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| In most cases none of the above variables will require setting, |
| unless multiple ICU versions are available and a specific version |
| is required. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Other variables one may set to control this module are: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ICU_DEBUG \- Set to ON to enable debug output from FindICU. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindImageMagick |
| .sp |
| Find ImageMagick binary suite. |
| .sp |
| New in version 3.9: Added support for ImageMagick 7. |
| |
| .sp |
| This module will search for a set of ImageMagick tools specified as |
| components in the \fBfind_package()\fP call. Typical components include, |
| but are not limited to (future versions of ImageMagick might have |
| additional components not listed here): |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| animate |
| compare |
| composite |
| conjure |
| convert |
| display |
| identify |
| import |
| mogrify |
| montage |
| stream |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| If no component is specified in the \fBfind_package()\fP call, then it only |
| searches for the ImageMagick executable directory. This code defines |
| the following variables: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ImageMagick_FOUND \- TRUE if all components are found. |
| ImageMagick_EXECUTABLE_DIR \- Full path to executables directory. |
| ImageMagick_<component>_FOUND \- TRUE if <component> is found. |
| ImageMagick_<component>_EXECUTABLE \- Full path to <component> executable. |
| ImageMagick_VERSION_STRING \- the version of ImageMagick found |
| (since CMake 2.8.8) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBImageMagick_VERSION_STRING\fP will not work for old versions like 5.2.3. |
| .sp |
| There are also components for the following ImageMagick APIs: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| Magick++ |
| MagickWand |
| MagickCore |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| For these components the following variables are set: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ImageMagick_FOUND \- TRUE if all components are found. |
| ImageMagick_INCLUDE_DIRS \- Full paths to all include dirs. |
| ImageMagick_LIBRARIES \- Full paths to all libraries. |
| ImageMagick_<component>_FOUND \- TRUE if <component> is found. |
| ImageMagick_<component>_INCLUDE_DIRS \- Full path to <component> include dirs. |
| ImageMagick_<component>_LIBRARIES \- Full path to <component> libraries. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Example Usages: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_package(ImageMagick) |
| find_package(ImageMagick COMPONENTS convert) |
| find_package(ImageMagick COMPONENTS convert mogrify display) |
| find_package(ImageMagick COMPONENTS Magick++) |
| find_package(ImageMagick COMPONENTS Magick++ convert) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Note that the standard \fBfind_package()\fP features are supported (i.e., |
| \fBQUIET\fP, \fBREQUIRED\fP, etc.). |
| .SS FindIntl |
| .sp |
| New in version 3.2. |
| |
| .sp |
| Find the Gettext libintl headers and libraries. |
| .sp |
| This module reports information about the Gettext libintl |
| installation in several variables. |
| .INDENT 0.0 |
| .TP |
| .B Intl_FOUND |
| True if libintl is found. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B Intl_INCLUDE_DIRS |
| The directory containing the libintl headers. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B Intl_LIBRARIES |
| The intl libraries to be linked. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B Intl_VERSION |
| New in version 3.21. |
| |
| .sp |
| The version of intl found (x.y.z) |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B Intl_VERSION_MAJOR |
| New in version 3.21. |
| |
| .sp |
| The major version of intl |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B Intl_VERSION_MINOR |
| New in version 3.21. |
| |
| .sp |
| The minor version of intl |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B Intl_VERSION_PATCH |
| New in version 3.21. |
| |
| .sp |
| The patch version of intl |
| .UNINDENT |
| .sp |
| New in version 3.20: This module defines \fBIMPORTED\fP target \fBIntl::Intl\fP\&. |
| |
| .sp |
| The following cache variables may also be set: |
| .INDENT 0.0 |
| .TP |
| .B Intl_INCLUDE_DIR |
| The directory containing the libintl headers |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B Intl_LIBRARY |
| The libintl library (if any) |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B Intl_IS_BUILT_IN |
| New in version 3.20. |
| |
| .sp |
| whether \fBintl\fP is a part of the C library. |
| .UNINDENT |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| On some platforms, such as Linux with GNU libc, the gettext |
| functions are present in the C standard library and libintl |
| is not required. \fBIntl_LIBRARIES\fP will be empty in this |
| case. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| Some libintl implementations don\(aqt embed the version number in their header files. |
| In this case the variables \fBIntl_VERSION*\fP will be empty. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| If you wish to use the Gettext tools (\fBmsgmerge\fP, |
| \fBmsgfmt\fP, etc.), use \fBFindGettext\fP\&. |
| .UNINDENT |
| .UNINDENT |
| .SS FindITK |
| .sp |
| This module no longer exists. |
| .sp |
| This module existed in versions of CMake prior to 3.1, but became |
| only a thin wrapper around \fBfind_package(ITK NO_MODULE)\fP to |
| provide compatibility for projects using long\-outdated conventions. |
| Now \fBfind_package(ITK)\fP will search for \fBITKConfig.cmake\fP |
| directly. |
| .SS FindJasper |
| .sp |
| Find the Jasper JPEG2000 library. |
| .SS IMPORTED Targets |
| .INDENT 0.0 |
| .TP |
| .B \fBJasper::Jasper\fP |
| The jasper library, if found. |
| .UNINDENT |
| .SS Result Variables |
| .sp |
| This module defines the following variables: |
| .INDENT 0.0 |
| .TP |
| .B \fBJASPER_FOUND\fP |
| system has Jasper |
| .TP |
| .B \fBJASPER_INCLUDE_DIRS\fP |
| New in version 3.22. |
| |
| .sp |
| the Jasper include directory |
| .TP |
| .B \fBJASPER_LIBRARIES\fP |
| the libraries needed to use Jasper |
| .TP |
| .B \fBJASPER_VERSION_STRING\fP |
| the version of Jasper found |
| .UNINDENT |
| .SS Cache variables |
| .sp |
| The following cache variables may also be set: |
| .INDENT 0.0 |
| .TP |
| .B \fBJASPER_INCLUDE_DIR\fP |
| where to find jasper/jasper.h, etc. |
| .TP |
| .B \fBJASPER_LIBRARY_RELEASE\fP |
| where to find the Jasper library (optimized). |
| .TP |
| .B \fBJASPER_LIBARRY_DEBUG\fP |
| where to find the Jasper library (debug). |
| .UNINDENT |
| .SS FindJava |
| .sp |
| Find Java |
| .sp |
| This module finds if Java is installed and determines where the |
| include files and libraries are. The caller may set variable \fBJAVA_HOME\fP |
| to specify a Java installation prefix explicitly. |
| .sp |
| See also the \fBFindJNI\fP module to find Java Native Interface (JNI). |
| .sp |
| New in version 3.10: Added support for Java 9+ version parsing. |
| |
| .sp |
| Specify one or more of the following components as you call this find module. See example below. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| Runtime = Java Runtime Environment used to execute Java byte\-compiled applications |
| Development = Development tools (java, javac, javah, jar and javadoc), includes Runtime component |
| IdlJ = Interface Description Language (IDL) to Java compiler |
| JarSigner = Signer and verifier tool for Java Archive (JAR) files |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This module sets the following result variables: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| Java_JAVA_EXECUTABLE = the full path to the Java runtime |
| Java_JAVAC_EXECUTABLE = the full path to the Java compiler |
| Java_JAVAH_EXECUTABLE = the full path to the Java header generator |
| Java_JAVADOC_EXECUTABLE = the full path to the Java documentation generator |
| Java_IDLJ_EXECUTABLE = the full path to the Java idl compiler |
| Java_JAR_EXECUTABLE = the full path to the Java archiver |
| Java_JARSIGNER_EXECUTABLE = the full path to the Java jar signer |
| Java_VERSION_STRING = Version of java found, eg. 1.6.0_12 |
| Java_VERSION_MAJOR = The major version of the package found. |
| Java_VERSION_MINOR = The minor version of the package found. |
| Java_VERSION_PATCH = The patch version of the package found. |
| Java_VERSION_TWEAK = The tweak version of the package found (after \(aq_\(aq) |
| Java_VERSION = This is set to: $major[.$minor[.$patch[.$tweak]]] |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.4: Added the \fBJava_IDLJ_EXECUTABLE\fP and \fBJava_JARSIGNER_EXECUTABLE\fP |
| variables. |
| |
| .sp |
| The minimum required version of Java can be specified using the |
| \fBfind_package()\fP syntax, e.g. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_package(Java 1.8) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| NOTE: \fB${Java_VERSION}\fP and \fB${Java_VERSION_STRING}\fP are not guaranteed to |
| be identical. For example some java version may return: |
| \fBJava_VERSION_STRING = 1.8.0_17\fP and \fBJava_VERSION = 1.8.0.17\fP |
| .sp |
| another example is the Java OEM, with: \fBJava_VERSION_STRING = 1.8.0\-oem\fP |
| and \fBJava_VERSION = 1.8.0\fP |
| .sp |
| For these components the following variables are set: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| Java_FOUND \- TRUE if all components are found. |
| Java_<component>_FOUND \- TRUE if <component> is found. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Example Usages: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_package(Java) |
| find_package(Java 1.8 REQUIRED) |
| find_package(Java COMPONENTS Runtime) |
| find_package(Java COMPONENTS Development) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindJNI |
| .sp |
| Find Java Native Interface (JNI) libraries. |
| .sp |
| JNI enables Java code running in a Java Virtual Machine (JVM) to call |
| and be called by native applications and libraries written in other |
| languages such as C, C++. |
| .sp |
| This module finds if Java is installed and determines where the |
| include files and libraries are. It also determines what the name of |
| the library is. The caller may set variable \fBJAVA_HOME\fP to specify a |
| Java installation prefix explicitly. |
| .SS Result Variables |
| .sp |
| This module sets the following result variables: |
| .INDENT 0.0 |
| .TP |
| .B \fBJNI_INCLUDE_DIRS\fP |
| the include dirs to use |
| .TP |
| .B \fBJNI_LIBRARIES\fP |
| the libraries to use (JAWT and JVM) |
| .TP |
| .B \fBJNI_FOUND\fP |
| TRUE if JNI headers and libraries were found. |
| .UNINDENT |
| .SS Cache Variables |
| .sp |
| The following cache variables are also available to set or use: |
| .INDENT 0.0 |
| .TP |
| .B \fBJAVA_AWT_LIBRARY\fP |
| the path to the Java AWT Native Interface (JAWT) library |
| .TP |
| .B \fBJAVA_JVM_LIBRARY\fP |
| the path to the Java Virtual Machine (JVM) library |
| .TP |
| .B \fBJAVA_INCLUDE_PATH\fP |
| the include path to jni.h |
| .TP |
| .B \fBJAVA_INCLUDE_PATH2\fP |
| the include path to jni_md.h and jniport.h |
| .TP |
| .B \fBJAVA_AWT_INCLUDE_PATH\fP |
| the include path to jawt.h |
| .UNINDENT |
| .SS FindJPEG |
| .sp |
| Find the Joint Photographic Experts Group (JPEG) library (\fBlibjpeg\fP) |
| .SS Imported targets |
| .sp |
| New in version 3.12. |
| |
| .sp |
| This module defines the following \fBIMPORTED\fP targets: |
| .INDENT 0.0 |
| .TP |
| .B \fBJPEG::JPEG\fP |
| The JPEG library, if found. |
| .UNINDENT |
| .SS Result variables |
| .sp |
| This module will set the following variables in your project: |
| .INDENT 0.0 |
| .TP |
| .B \fBJPEG_FOUND\fP |
| If false, do not try to use JPEG. |
| .TP |
| .B \fBJPEG_INCLUDE_DIRS\fP |
| where to find jpeglib.h, etc. |
| .TP |
| .B \fBJPEG_LIBRARIES\fP |
| the libraries needed to use JPEG. |
| .TP |
| .B \fBJPEG_VERSION\fP |
| New in version 3.12: the version of the JPEG library found |
| |
| .UNINDENT |
| .SS Cache variables |
| .sp |
| The following cache variables may also be set: |
| .INDENT 0.0 |
| .TP |
| .B \fBJPEG_INCLUDE_DIRS\fP |
| where to find jpeglib.h, etc. |
| .TP |
| .B \fBJPEG_LIBRARY_RELEASE\fP |
| where to find the JPEG library (optimized). |
| .TP |
| .B \fBJPEG_LIBRARY_DEBUG\fP |
| where to find the JPEG library (debug). |
| .UNINDENT |
| .sp |
| New in version 3.12: Debug and Release variand are found separately. |
| |
| .SS Obsolete variables |
| .INDENT 0.0 |
| .TP |
| .B \fBJPEG_INCLUDE_DIR\fP |
| where to find jpeglib.h, etc. (same as JPEG_INCLUDE_DIRS) |
| .TP |
| .B \fBJPEG_LIBRARY\fP |
| where to find the JPEG library. |
| .UNINDENT |
| .SS FindKDE3 |
| .sp |
| Find the KDE3 include and library dirs, KDE preprocessors and define a some macros |
| .sp |
| This module defines the following variables: |
| .INDENT 0.0 |
| .TP |
| .B \fBKDE3_DEFINITIONS\fP |
| compiler definitions required for compiling KDE software |
| .TP |
| .B \fBKDE3_INCLUDE_DIR\fP |
| the KDE include directory |
| .TP |
| .B \fBKDE3_INCLUDE_DIRS\fP |
| the KDE and the Qt include directory, for use with include_directories() |
| .TP |
| .B \fBKDE3_LIB_DIR\fP |
| the directory where the KDE libraries are installed, for use with link_directories() |
| .TP |
| .B \fBQT_AND_KDECORE_LIBS\fP |
| this contains both the Qt and the kdecore library |
| .TP |
| .B \fBKDE3_DCOPIDL_EXECUTABLE\fP |
| the dcopidl executable |
| .TP |
| .B \fBKDE3_DCOPIDL2CPP_EXECUTABLE\fP |
| the dcopidl2cpp executable |
| .TP |
| .B \fBKDE3_KCFGC_EXECUTABLE\fP |
| the kconfig_compiler executable |
| .TP |
| .B \fBKDE3_FOUND\fP |
| set to TRUE if all of the above has been found |
| .UNINDENT |
| .sp |
| The following user adjustable options are provided: |
| .INDENT 0.0 |
| .TP |
| .B \fBKDE3_BUILD_TESTS\fP |
| enable this to build KDE testcases |
| .UNINDENT |
| .sp |
| It also adds the following macros (from \fBKDE3Macros.cmake\fP) \fBSRCS_VAR\fP is |
| always the variable which contains the list of source files for your |
| application or library. |
| .sp |
| KDE3_AUTOMOC(file1 ... fileN) |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| Call this if you want to have automatic moc file handling. |
| This means if you include "foo.moc" in the source file foo.cpp |
| a moc file for the header foo.h will be created automatically. |
| You can set the property SKIP_AUTOMAKE using set_source_files_properties() |
| to exclude some files in the list from being processed. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| KDE3_ADD_MOC_FILES(SRCS_VAR file1 ... fileN ) |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| If you don\(aqt use the KDE3_AUTOMOC() macro, for the files |
| listed here moc files will be created (named "foo.moc.cpp") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| KDE3_ADD_DCOP_SKELS(SRCS_VAR header1.h ... headerN.h ) |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| Use this to generate DCOP skeletions from the listed headers. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| KDE3_ADD_DCOP_STUBS(SRCS_VAR header1.h ... headerN.h ) |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| Use this to generate DCOP stubs from the listed headers. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| KDE3_ADD_UI_FILES(SRCS_VAR file1.ui ... fileN.ui ) |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| Use this to add the Qt designer ui files to your application/library. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| KDE3_ADD_KCFG_FILES(SRCS_VAR file1.kcfgc ... fileN.kcfgc ) |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| Use this to add KDE kconfig compiler files to your application/library. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| KDE3_INSTALL_LIBTOOL_FILE(target) |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| This will create and install a simple libtool file for the given target. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| KDE3_ADD_EXECUTABLE(name file1 ... fileN ) |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| Currently identical to add_executable(), may provide some advanced |
| features in the future. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| KDE3_ADD_KPART(name [WITH_PREFIX] file1 ... fileN ) |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| Create a KDE plugin (KPart, kioslave, etc.) from the given source files. |
| If WITH_PREFIX is given, the resulting plugin will have the prefix "lib", |
| otherwise it won\(aqt. |
| It creates and installs an appropriate libtool la\-file. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| KDE3_ADD_KDEINIT_EXECUTABLE(name file1 ... fileN ) |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| Create a KDE application in the form of a module loadable via kdeinit. |
| A library named kdeinit_<name> will be created and a small executable |
| which links to it. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The option KDE3_ENABLE_FINAL to enable all\-in\-one compilation is no |
| longer supported. |
| .sp |
| Author: Alexander Neundorf <\fI\%neundorf@kde.org\fP> |
| .SS FindKDE4 |
| .sp |
| Find KDE4 and provide all necessary variables and macros to compile |
| software for it. It looks for KDE 4 in the following directories in |
| the given order: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| CMAKE_INSTALL_PREFIX |
| KDEDIRS |
| /opt/kde4 |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Please look in \fBFindKDE4Internal.cmake\fP and \fBKDE4Macros.cmake\fP for more |
| information. They are installed with the KDE 4 libraries in |
| $KDEDIRS/share/apps/cmake/modules/. |
| .sp |
| Author: Alexander Neundorf <\fI\%neundorf@kde.org\fP> |
| .SS FindLAPACK |
| .sp |
| Find Linear Algebra PACKage (LAPACK) library |
| .sp |
| This module finds an installed Fortran library that implements the |
| \fI\%LAPACK linear\-algebra interface\fP\&. |
| .sp |
| At least one of the \fBC\fP, \fBCXX\fP, or \fBFortran\fP languages must be enabled. |
| .SS Input Variables |
| .sp |
| The following variables may be set to influence this module\(aqs behavior: |
| .INDENT 0.0 |
| .TP |
| .B \fBBLA_STATIC\fP |
| if \fBON\fP use static linkage |
| .TP |
| .B \fBBLA_VENDOR\fP |
| Set to one of the BLAS/LAPACK Vendors to search for BLAS only |
| from the specified vendor. If not set, all vendors are considered. |
| .TP |
| .B \fBBLA_F95\fP |
| if \fBON\fP tries to find the BLAS95/LAPACK95 interfaces |
| .TP |
| .B \fBBLA_PREFER_PKGCONFIG\fP |
| New in version 3.20. |
| |
| .sp |
| if set \fBpkg\-config\fP will be used to search for a LAPACK library first |
| and if one is found that is preferred |
| .TP |
| .B \fBBLA_SIZEOF_INTEGER\fP |
| New in version 3.22. |
| |
| .sp |
| Specify the BLAS/LAPACK library integer size: |
| .INDENT 7.0 |
| .TP |
| .B \fB4\fP |
| Search for a BLAS/LAPACK with 32\-bit integer interfaces. |
| .TP |
| .B \fB8\fP |
| Search for a BLAS/LAPACK with 64\-bit integer interfaces. |
| .TP |
| .B \fBANY\fP |
| Search for any BLAS/LAPACK. |
| Most likely, a BLAS/LAPACK with 32\-bit integer interfaces will be found. |
| .UNINDENT |
| .UNINDENT |
| .SS Imported targets |
| .sp |
| This module defines the following \fBIMPORTED\fP targets: |
| .INDENT 0.0 |
| .TP |
| .B \fBLAPACK::LAPACK\fP |
| New in version 3.18. |
| |
| .sp |
| The libraries to use for LAPACK, if found. |
| .UNINDENT |
| .SS Result Variables |
| .sp |
| This module defines the following variables: |
| .INDENT 0.0 |
| .TP |
| .B \fBLAPACK_FOUND\fP |
| library implementing the LAPACK interface is found |
| .TP |
| .B \fBLAPACK_LINKER_FLAGS\fP |
| uncached list of required linker flags (excluding \fB\-l\fP and \fB\-L\fP). |
| .TP |
| .B \fBLAPACK_LIBRARIES\fP |
| uncached list of libraries (using full path name) to link against |
| to use LAPACK |
| .TP |
| .B \fBLAPACK95_LIBRARIES\fP |
| uncached list of libraries (using full path name) to link against |
| to use LAPACK95 |
| .TP |
| .B \fBLAPACK95_FOUND\fP |
| library implementing the LAPACK95 interface is found |
| .UNINDENT |
| .SS Intel MKL |
| .sp |
| To use the Intel MKL implementation of LAPACK, a project must enable at least |
| one of the \fBC\fP or \fBCXX\fP languages. Set \fBBLA_VENDOR\fP to an Intel MKL |
| variant either on the command\-line as \fB\-DBLA_VENDOR=Intel10_64lp\fP or in |
| project code: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(BLA_VENDOR Intel10_64lp) |
| find_package(LAPACK) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| In order to build a project using Intel MKL, and end user must first |
| establish an Intel MKL environment. See the \fBFindBLAS\fP module |
| section on Intel MKL for details. |
| .SS FindLATEX |
| .sp |
| Find LaTeX |
| .sp |
| This module finds an installed LaTeX and determines the location |
| of the compiler. Additionally the module looks for Latex\-related |
| software like BibTeX. |
| .sp |
| New in version 3.2: Component processing; support for htlatex, pdftops, Biber, xindy, XeLaTeX, |
| LuaLaTeX. |
| |
| .sp |
| This module sets the following result variables: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| LATEX_FOUND: whether found Latex and requested components |
| LATEX_<component>_FOUND: whether found <component> |
| LATEX_COMPILER: path to the LaTeX compiler |
| PDFLATEX_COMPILER: path to the PdfLaTeX compiler |
| XELATEX_COMPILER: path to the XeLaTeX compiler |
| LUALATEX_COMPILER: path to the LuaLaTeX compiler |
| BIBTEX_COMPILER: path to the BibTeX compiler |
| BIBER_COMPILER: path to the Biber compiler |
| MAKEINDEX_COMPILER: path to the MakeIndex compiler |
| XINDY_COMPILER: path to the xindy compiler |
| DVIPS_CONVERTER: path to the DVIPS converter |
| DVIPDF_CONVERTER: path to the DVIPDF converter |
| PS2PDF_CONVERTER: path to the PS2PDF converter |
| PDFTOPS_CONVERTER: path to the pdftops converter |
| LATEX2HTML_CONVERTER: path to the LaTeX2Html converter |
| HTLATEX_COMPILER: path to the htlatex compiler |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Possible components are: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| PDFLATEX |
| XELATEX |
| LUALATEX |
| BIBTEX |
| BIBER |
| MAKEINDEX |
| XINDY |
| DVIPS |
| DVIPDF |
| PS2PDF |
| PDFTOPS |
| LATEX2HTML |
| HTLATEX |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Example Usages: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_package(LATEX) |
| find_package(LATEX COMPONENTS PDFLATEX) |
| find_package(LATEX COMPONENTS BIBTEX PS2PDF) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindLibArchive |
| .sp |
| Find libarchive library and headers. |
| Libarchive is multi\-format archive and compression library. |
| .sp |
| The module defines the following variables: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| LibArchive_FOUND \- true if libarchive was found |
| LibArchive_INCLUDE_DIRS \- include search path |
| LibArchive_LIBRARIES \- libraries to link |
| LibArchive_VERSION \- libarchive 3\-component version number |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The module defines the following \fBIMPORTED\fP targets: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| LibArchive::LibArchive \- target for linking against libarchive |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.6: Support for new libarchive 3.2 version string format. |
| |
| .SS FindLibinput |
| .sp |
| New in version 3.14. |
| |
| .sp |
| Find libinput headers and library. |
| .SS Imported Targets |
| .INDENT 0.0 |
| .TP |
| .B \fBLibinput::Libinput\fP |
| The libinput library, if found. |
| .UNINDENT |
| .SS Result Variables |
| .sp |
| This will define the following variables in your project: |
| .INDENT 0.0 |
| .TP |
| .B \fBLibinput_FOUND\fP |
| true if (the requested version of) libinput is available. |
| .TP |
| .B \fBLibinput_VERSION\fP |
| the version of libinput. |
| .TP |
| .B \fBLibinput_LIBRARIES\fP |
| the libraries to link against to use libinput. |
| .TP |
| .B \fBLibinput_INCLUDE_DIRS\fP |
| where to find the libinput headers. |
| .TP |
| .B \fBLibinput_COMPILE_OPTIONS\fP |
| this should be passed to target_compile_options(), if the |
| target is not used for linking |
| .UNINDENT |
| .SS FindLibLZMA |
| .sp |
| Find LZMA compression algorithm headers and library. |
| .SS Imported Targets |
| .sp |
| New in version 3.14. |
| |
| .sp |
| This module defines \fBIMPORTED\fP target \fBLibLZMA::LibLZMA\fP, if |
| liblzma has been found. |
| .SS Result variables |
| .sp |
| This module will set the following variables in your project: |
| .INDENT 0.0 |
| .TP |
| .B \fBLIBLZMA_FOUND\fP |
| True if liblzma headers and library were found. |
| .TP |
| .B \fBLIBLZMA_INCLUDE_DIRS\fP |
| Directory where liblzma headers are located. |
| .TP |
| .B \fBLIBLZMA_LIBRARIES\fP |
| Lzma libraries to link against. |
| .TP |
| .B \fBLIBLZMA_HAS_AUTO_DECODER\fP |
| True if lzma_auto_decoder() is found (required). |
| .TP |
| .B \fBLIBLZMA_HAS_EASY_ENCODER\fP |
| True if lzma_easy_encoder() is found (required). |
| .TP |
| .B \fBLIBLZMA_HAS_LZMA_PRESET\fP |
| True if lzma_lzma_preset() is found (required). |
| .TP |
| .B \fBLIBLZMA_VERSION_MAJOR\fP |
| The major version of lzma |
| .TP |
| .B \fBLIBLZMA_VERSION_MINOR\fP |
| The minor version of lzma |
| .TP |
| .B \fBLIBLZMA_VERSION_PATCH\fP |
| The patch version of lzma |
| .TP |
| .B \fBLIBLZMA_VERSION_STRING\fP |
| version number as a string (ex: "5.0.3") |
| .UNINDENT |
| .SS FindLibXml2 |
| .sp |
| Find the XML processing library (libxml2). |
| .SS IMPORTED Targets |
| .sp |
| New in version 3.12. |
| |
| .sp |
| The following \fBIMPORTED\fP targets may be defined: |
| .INDENT 0.0 |
| .TP |
| .B \fBLibXml2::LibXml2\fP |
| libxml2 library. |
| .TP |
| .B \fBLibXml2::xmllint\fP |
| New in version 3.17. |
| |
| .sp |
| xmllint command\-line executable. |
| .UNINDENT |
| .SS Result variables |
| .sp |
| This module will set the following variables in your project: |
| .INDENT 0.0 |
| .TP |
| .B \fBLibXml2_FOUND\fP |
| true if libxml2 headers and libraries were found |
| .TP |
| .B \fBLIBXML2_INCLUDE_DIR\fP |
| the directory containing LibXml2 headers |
| .TP |
| .B \fBLIBXML2_INCLUDE_DIRS\fP |
| list of the include directories needed to use LibXml2 |
| .TP |
| .B \fBLIBXML2_LIBRARIES\fP |
| LibXml2 libraries to be linked |
| .TP |
| .B \fBLIBXML2_DEFINITIONS\fP |
| the compiler switches required for using LibXml2 |
| .TP |
| .B \fBLIBXML2_XMLLINT_EXECUTABLE\fP |
| path to the XML checking tool xmllint coming with LibXml2 |
| .TP |
| .B \fBLIBXML2_VERSION_STRING\fP |
| the version of LibXml2 found (since CMake 2.8.8) |
| .UNINDENT |
| .SS Cache variables |
| .sp |
| The following cache variables may also be set: |
| .INDENT 0.0 |
| .TP |
| .B \fBLIBXML2_INCLUDE_DIR\fP |
| the directory containing LibXml2 headers |
| .TP |
| .B \fBLIBXML2_LIBRARY\fP |
| path to the LibXml2 library |
| .UNINDENT |
| .SS FindLibXslt |
| .sp |
| Find the XSL Transformations, Extensible Stylesheet Language |
| Transformations (XSLT) library (LibXslt) |
| .SS IMPORTED Targets |
| .sp |
| New in version 3.18. |
| |
| .sp |
| The following \fBIMPORTED\fP targets may be defined: |
| .INDENT 0.0 |
| .TP |
| .B \fBLibXslt::LibXslt\fP |
| If the libxslt library has been found |
| .TP |
| .B \fBLibXslt::LibExslt\fP |
| If the libexslt library has been found |
| .TP |
| .B \fBLibXslt::xsltproc\fP |
| If the xsltproc command\-line executable has been found |
| .UNINDENT |
| .SS Result variables |
| .sp |
| This module will set the following variables in your project: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| LIBXSLT_FOUND \- system has LibXslt |
| LIBXSLT_INCLUDE_DIR \- the LibXslt include directory |
| LIBXSLT_LIBRARIES \- Link these to LibXslt |
| LIBXSLT_DEFINITIONS \- Compiler switches required for using LibXslt |
| LIBXSLT_VERSION_STRING \- version of LibXslt found (since CMake 2.8.8) |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Additionally, the following two variables are set (but not required |
| for using xslt): |
| .INDENT 0.0 |
| .TP |
| .B \fBLIBXSLT_EXSLT_INCLUDE_DIR\fP |
| New in version 3.18: The include directory for exslt. |
| |
| .TP |
| .B \fBLIBXSLT_EXSLT_LIBRARIES\fP |
| Link to these if you need to link against the exslt library. |
| .TP |
| .B \fBLIBXSLT_XSLTPROC_EXECUTABLE\fP |
| Contains the full path to the xsltproc executable if found. |
| .UNINDENT |
| .SS FindLTTngUST |
| .sp |
| New in version 3.6. |
| |
| .sp |
| Find |
| \fI\%Linux Trace Toolkit Next Generation (LTTng\-UST)\fP library. |
| .SS Imported target |
| .sp |
| This module defines the following \fBIMPORTED\fP target: |
| .INDENT 0.0 |
| .TP |
| .B \fBLTTng::UST\fP |
| The LTTng\-UST library, if found |
| .UNINDENT |
| .SS Result variables |
| .sp |
| This module sets the following |
| .INDENT 0.0 |
| .TP |
| .B \fBLTTNGUST_FOUND\fP |
| \fBTRUE\fP if system has LTTng\-UST |
| .TP |
| .B \fBLTTNGUST_INCLUDE_DIRS\fP |
| The LTTng\-UST include directories |
| .TP |
| .B \fBLTTNGUST_LIBRARIES\fP |
| The libraries needed to use LTTng\-UST |
| .TP |
| .B \fBLTTNGUST_VERSION_STRING\fP |
| The LTTng\-UST version |
| .TP |
| .B \fBLTTNGUST_HAS_TRACEF\fP |
| \fBTRUE\fP if the \fBtracef()\fP API is available in the system\(aqs LTTng\-UST |
| .TP |
| .B \fBLTTNGUST_HAS_TRACELOG\fP |
| \fBTRUE\fP if the \fBtracelog()\fP API is available in the system\(aqs LTTng\-UST |
| .UNINDENT |
| .SS FindLua |
| .sp |
| Locate Lua library. |
| .sp |
| New in version 3.18: Support for Lua 5.4. |
| |
| .sp |
| This module defines: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| :: |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| LUA_FOUND \- if false, do not try to link to Lua |
| LUA_LIBRARIES \- both lua and lualib |
| LUA_INCLUDE_DIR \- where to find lua.h |
| LUA_VERSION_STRING \- the version of Lua found |
| LUA_VERSION_MAJOR \- the major version of Lua |
| LUA_VERSION_MINOR \- the minor version of Lua |
| LUA_VERSION_PATCH \- the patch version of Lua |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Note that the expected include convention is |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| #include "lua.h" |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| and not |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| #include <lua/lua.h> |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This is because, the lua location is not standardized and may exist in |
| locations other than lua/ |
| .SS FindLua50 |
| .sp |
| Locate Lua library. |
| This module defines: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| :: |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| LUA50_FOUND, if false, do not try to link to Lua |
| LUA_LIBRARIES, both lua and lualib |
| LUA_INCLUDE_DIR, where to find lua.h and lualib.h (and probably lauxlib.h) |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Note that the expected include convention is |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| #include "lua.h" |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| and not |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| #include <lua/lua.h> |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This is because, the lua location is not standardized and may exist in |
| locations other than lua/ |
| .SS FindLua51 |
| .sp |
| Locate Lua library. |
| This module defines: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| :: |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| LUA51_FOUND, if false, do not try to link to Lua |
| LUA_LIBRARIES |
| LUA_INCLUDE_DIR, where to find lua.h |
| LUA_VERSION_STRING, the version of Lua found (since CMake 2.8.8) |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Note that the expected include convention is |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| #include "lua.h" |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| and not |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| #include <lua/lua.h> |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This is because, the lua location is not standardized and may exist in |
| locations other than lua/ |
| .SS FindMatlab |
| .sp |
| Finds Matlab or Matlab Compiler Runtime (MCR) and provides Matlab tools, |
| libraries and compilers to CMake. |
| .sp |
| This package primary purpose is to find the libraries associated with Matlab |
| or the MCR in order to be able to build Matlab extensions (mex files). It |
| can also be used: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| to run specific commands in Matlab in case Matlab is available |
| .IP \(bu 2 |
| for declaring Matlab unit test |
| .IP \(bu 2 |
| to retrieve various information from Matlab (mex extensions, versions and |
| release queries, ...) |
| .UNINDENT |
| .sp |
| New in version 3.12: Added Matlab Compiler Runtime (MCR) support. |
| |
| .sp |
| The module supports the following components: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBENG_LIBRARY\fP and \fBMAT_LIBRARY\fP: respectively the \fBENG\fP and \fBMAT\fP |
| libraries of Matlab |
| .IP \(bu 2 |
| \fBMAIN_PROGRAM\fP the Matlab binary program. Note that this component is not |
| available on the MCR version, and will yield an error if the MCR is found |
| instead of the regular Matlab installation. |
| .IP \(bu 2 |
| \fBMEX_COMPILER\fP the MEX compiler. |
| .IP \(bu 2 |
| \fBMCC_COMPILER\fP the MCC compiler, included with the Matlab Compiler add\-on. |
| .IP \(bu 2 |
| \fBSIMULINK\fP the Simulink environment. |
| .UNINDENT |
| .sp |
| New in version 3.7: Added the \fBMAT_LIBRARY\fP component. |
| |
| .sp |
| New in version 3.13: Added the \fBENGINE_LIBRARY\fP, \fBDATAARRAY_LIBRARY\fP and \fBMCC_COMPILER\fP |
| components. |
| |
| .sp |
| Changed in version 3.14: Removed the \fBMX_LIBRARY\fP, \fBENGINE_LIBRARY\fP and \fBDATAARRAY_LIBRARY\fP |
| components. These libraries are found unconditionally. |
| |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| The version given to the \fBfind_package()\fP directive is the Matlab |
| \fBversion\fP, which should not be confused with the Matlab \fIrelease\fP name |
| (eg. \fIR2014\fP). |
| The \fI\%matlab_get_version_from_release_name()\fP and |
| \fI\%matlab_get_release_name_from_version()\fP provide a mapping |
| between the release name and the version. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The variable \fI\%Matlab_ROOT_DIR\fP may be specified in order to give |
| the path of the desired Matlab version. Otherwise, the behavior is platform |
| specific: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| Windows: The installed versions of Matlab/MCR are retrieved from the |
| Windows registry |
| .IP \(bu 2 |
| OS X: The installed versions of Matlab/MCR are given by the MATLAB |
| default installation paths in \fB/Application\fP\&. If no such application is |
| found, it falls back to the one that might be accessible from the \fBPATH\fP\&. |
| .IP \(bu 2 |
| Unix: The desired Matlab should be accessible from the \fBPATH\fP\&. This does |
| not work for MCR installation and \fI\%Matlab_ROOT_DIR\fP should be |
| specified on this platform. |
| .UNINDENT |
| .sp |
| Additional information is provided when \fI\%MATLAB_FIND_DEBUG\fP is set. |
| When a Matlab/MCR installation is found automatically and the \fBMATLAB_VERSION\fP |
| is not given, the version is queried from Matlab directly (on Windows this |
| may pop up a Matlab window) or from the MCR installation. |
| .sp |
| The mapping of the release names and the version of Matlab is performed by |
| defining pairs (name, version). The variable |
| \fI\%MATLAB_ADDITIONAL_VERSIONS\fP may be provided before the call to |
| the \fBfind_package()\fP in order to handle additional versions. |
| .sp |
| A Matlab scripts can be added to the set of tests using the |
| \fI\%matlab_add_unit_test()\fP\&. By default, the Matlab unit test framework |
| will be used (>= 2013a) to run this script, but regular \fB\&.m\fP files |
| returning an exit code can be used as well (0 indicating a success). |
| .SS Module Input Variables |
| .sp |
| Users or projects may set the following variables to configure the module |
| behavior: |
| .INDENT 0.0 |
| .TP |
| .B \fI\%Matlab_ROOT_DIR\fP |
| the root of the Matlab installation. |
| .TP |
| .B \fI\%MATLAB_FIND_DEBUG\fP |
| outputs debug information |
| .TP |
| .B \fI\%MATLAB_ADDITIONAL_VERSIONS\fP |
| additional versions of Matlab for the automatic retrieval of the installed |
| versions. |
| .UNINDENT |
| .SS Imported targets |
| .sp |
| New in version 3.22. |
| |
| .sp |
| This module defines the following \fBIMPORTED\fP targets: |
| .INDENT 0.0 |
| .TP |
| .B \fBMatlab::mex\fP |
| The \fBmex\fP library, always available. |
| .TP |
| .B \fBMatlab::mx\fP |
| The mx library of Matlab (arrays), always available. |
| .TP |
| .B \fBMatlab::eng\fP |
| Matlab engine library. Available only if the \fBENG_LIBRARY\fP component |
| is requested. |
| .TP |
| .B \fBMatlab::mat\fP |
| Matlab matrix library. Available only if the \fBMAT_LIBRARY\fP component |
| is requested. |
| .TP |
| .B \fBMatlab::MatlabEngine\fP |
| Matlab C++ engine library, always available for R2018a and newer. |
| .TP |
| .B \fBMatlab::MatlabDataArray\fP |
| Matlab C++ data array library, always available for R2018a and newer. |
| .UNINDENT |
| .SS Variables defined by the module |
| .SS Result variables |
| .INDENT 0.0 |
| .TP |
| .B \fBMatlab_FOUND\fP |
| \fBTRUE\fP if the Matlab installation is found, \fBFALSE\fP |
| otherwise. All variable below are defined if Matlab is found. |
| .TP |
| .B \fBMatlab_ROOT_DIR\fP |
| the final root of the Matlab installation determined by the FindMatlab |
| module. |
| .TP |
| .B \fBMatlab_MAIN_PROGRAM\fP |
| the Matlab binary program. Available only if the component \fBMAIN_PROGRAM\fP |
| is given in the \fBfind_package()\fP directive. |
| .TP |
| .B \fBMatlab_INCLUDE_DIRS\fP |
| the path of the Matlab libraries headers |
| .TP |
| .B \fBMatlab_MEX_LIBRARY\fP |
| library for mex, always available. |
| .TP |
| .B \fBMatlab_MX_LIBRARY\fP |
| mx library of Matlab (arrays), always available. |
| .TP |
| .B \fBMatlab_ENG_LIBRARY\fP |
| Matlab engine library. Available only if the component \fBENG_LIBRARY\fP |
| is requested. |
| .TP |
| .B \fBMatlab_MAT_LIBRARY\fP |
| Matlab matrix library. Available only if the component \fBMAT_LIBRARY\fP |
| is requested. |
| .TP |
| .B \fBMatlab_ENGINE_LIBRARY\fP |
| New in version 3.13. |
| |
| .sp |
| Matlab C++ engine library, always available for R2018a and newer. |
| .TP |
| .B \fBMatlab_DATAARRAY_LIBRARY\fP |
| New in version 3.13. |
| |
| .sp |
| Matlab C++ data array library, always available for R2018a and newer. |
| .TP |
| .B \fBMatlab_LIBRARIES\fP |
| the whole set of libraries of Matlab |
| .TP |
| .B \fBMatlab_MEX_COMPILER\fP |
| the mex compiler of Matlab. Currently not used. |
| Available only if the component \fBMEX_COMPILER\fP is requested. |
| .TP |
| .B \fBMatlab_MCC_COMPILER\fP |
| New in version 3.13. |
| |
| .sp |
| the mcc compiler of Matlab. Included with the Matlab Compiler add\-on. |
| Available only if the component \fBMCC_COMPILER\fP is requested. |
| .UNINDENT |
| .SS Cached variables |
| .INDENT 0.0 |
| .TP |
| .B \fBMatlab_MEX_EXTENSION\fP |
| the extension of the mex files for the current platform (given by Matlab). |
| .TP |
| .B \fBMatlab_ROOT_DIR\fP |
| the location of the root of the Matlab installation found. If this value |
| is changed by the user, the result variables are recomputed. |
| .UNINDENT |
| .SS Provided macros |
| .INDENT 0.0 |
| .TP |
| .B \fI\%matlab_get_version_from_release_name()\fP |
| returns the version from the release name |
| .TP |
| .B \fI\%matlab_get_release_name_from_version()\fP |
| returns the release name from the Matlab version |
| .UNINDENT |
| .SS Provided functions |
| .INDENT 0.0 |
| .TP |
| .B \fI\%matlab_add_mex()\fP |
| adds a target compiling a MEX file. |
| .TP |
| .B \fI\%matlab_add_unit_test()\fP |
| adds a Matlab unit test file as a test to the project. |
| .TP |
| .B \fI\%matlab_extract_all_installed_versions_from_registry()\fP |
| parses the registry for all Matlab versions. Available on Windows only. |
| The part of the registry parsed is dependent on the host processor |
| .TP |
| .B \fI\%matlab_get_all_valid_matlab_roots_from_registry()\fP |
| returns all the possible Matlab or MCR paths, according to a previously |
| given list. Only the existing/accessible paths are kept. This is mainly |
| useful for the searching all possible Matlab installation. |
| .TP |
| .B \fI\%matlab_get_mex_suffix()\fP |
| returns the suffix to be used for the mex files |
| (platform/architecture dependent) |
| .TP |
| .B \fI\%matlab_get_version_from_matlab_run()\fP |
| returns the version of Matlab/MCR, given the full directory of the Matlab/MCR |
| installation path. |
| .UNINDENT |
| .SS Known issues |
| .INDENT 0.0 |
| .TP |
| \fBSymbol clash in a MEX target\fP |
| By default, every symbols inside a MEX |
| file defined with the command \fI\%matlab_add_mex()\fP have hidden |
| visibility, except for the entry point. This is the default behavior of |
| the MEX compiler, which lowers the risk of symbol collision between the |
| libraries shipped with Matlab, and the libraries to which the MEX file is |
| linking to. This is also the default on Windows platforms. |
| .sp |
| However, this is not sufficient in certain case, where for instance your |
| MEX file is linking against libraries that are already loaded by Matlab, |
| even if those libraries have different SONAMES. |
| A possible solution is to hide the symbols of the libraries to which the |
| MEX target is linking to. This can be achieved in GNU GCC compilers with |
| the linker option \fB\-Wl,\-\-exclude\-libs,ALL\fP\&. |
| .TP |
| \fBTests using GPU resources\fP |
| in case your MEX file is using the GPU and |
| in order to be able to run unit tests on this MEX file, the GPU resources |
| should be properly released by Matlab. A possible solution is to make |
| Matlab aware of the use of the GPU resources in the session, which can be |
| performed by a command such as \fBD = gpuDevice()\fP at the beginning of |
| the test script (or via a fixture). |
| .UNINDENT |
| .SS Reference |
| .INDENT 0.0 |
| .TP |
| .B Matlab_ROOT_DIR |
| The root folder of the Matlab installation. If set before the call to |
| \fBfind_package()\fP, the module will look for the components in that |
| path. If not set, then an automatic search of Matlab |
| will be performed. If set, it should point to a valid version of Matlab. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B MATLAB_FIND_DEBUG |
| If set, the lookup of Matlab and the intermediate configuration steps are |
| outputted to the console. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B MATLAB_ADDITIONAL_VERSIONS |
| If set, specifies additional versions of Matlab that may be looked for. |
| The variable should be a list of strings, organized by pairs of release |
| name and versions, such as follows: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(MATLAB_ADDITIONAL_VERSIONS |
| "release_name1=corresponding_version1" |
| "release_name2=corresponding_version2" |
| ... |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Example: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(MATLAB_ADDITIONAL_VERSIONS |
| "R2013b=8.2" |
| "R2013a=8.1" |
| "R2012b=8.0") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The order of entries in this list matters when several versions of |
| Matlab are installed. The priority is set according to the ordering in |
| this list. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B matlab_get_version_from_release_name |
| Returns the version of Matlab (17.58) from a release name (R2017k) |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B matlab_get_release_name_from_version |
| Returns the release name (R2017k) from the version of Matlab (17.58) |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B matlab_extract_all_installed_versions_from_registry |
| This function parses the registry and founds the Matlab versions that are |
| installed. The found versions are returned in \fImatlab_versions\fP\&. |
| Set \fIwin64\fP to \fITRUE\fP if the 64 bit version of Matlab should be looked for |
| The returned list contains all versions under |
| \fBHKLM\e\eSOFTWARE\e\eMathworks\e\eMATLAB\fP and |
| \fBHKLM\e\eSOFTWARE\e\eMathworks\e\eMATLAB Runtime\fP or an empty list in case an |
| error occurred (or nothing found). |
| .sp |
| \fBNOTE:\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| Only the versions are provided. No check is made over the existence of the |
| installation referenced in the registry, |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B matlab_get_all_valid_matlab_roots_from_registry |
| Populates the Matlab root with valid versions of Matlab or |
| Matlab Runtime (MCR). |
| The returned matlab_roots is organized in triplets |
| \fB(type,version_number,matlab_root_path)\fP, where \fBtype\fP |
| indicates either \fBMATLAB\fP or \fBMCR\fP\&. |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| matlab_get_all_valid_matlab_roots_from_registry( |
| matlab_versions |
| matlab_roots) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 7.0 |
| .TP |
| .B \fBmatlab_versions\fP |
| the versions of each of the Matlab or MCR installations |
| .TP |
| .B \fBmatlab_roots\fP |
| the location of each of the Matlab or MCR installations |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B matlab_get_mex_suffix |
| Returns the extension of the mex files (the suffixes). |
| This function should not be called before the appropriate Matlab root has |
| been found. |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| matlab_get_mex_suffix( |
| matlab_root |
| mex_suffix) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 7.0 |
| .TP |
| .B \fBmatlab_root\fP |
| the root of the Matlab/MCR installation |
| .TP |
| .B \fBmex_suffix\fP |
| the variable name in which the suffix will be returned. |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B matlab_get_version_from_matlab_run |
| This function runs Matlab program specified on arguments and extracts its |
| version. If the path provided for the Matlab installation points to an MCR |
| installation, the version is extracted from the installed files. |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| matlab_get_version_from_matlab_run( |
| matlab_binary_path |
| matlab_list_versions) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 7.0 |
| .TP |
| .B \fBmatlab_binary_path\fP |
| the location of the \fImatlab\fP binary executable |
| .TP |
| .B \fBmatlab_list_versions\fP |
| the version extracted from Matlab |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B matlab_add_unit_test |
| Adds a Matlab unit test to the test set of cmake/ctest. |
| This command requires the component \fBMAIN_PROGRAM\fP and hence is not |
| available for an MCR installation. |
| .sp |
| The unit test uses the Matlab unittest framework (default, available |
| starting Matlab 2013b+) except if the option \fBNO_UNITTEST_FRAMEWORK\fP |
| is given. |
| .sp |
| The function expects one Matlab test script file to be given. |
| In the case \fBNO_UNITTEST_FRAMEWORK\fP is given, the unittest script file |
| should contain the script to be run, plus an exit command with the exit |
| value. This exit value will be passed to the ctest framework (0 success, |
| non 0 failure). Additional arguments accepted by \fBadd_test()\fP can be |
| passed through \fBTEST_ARGS\fP (eg. \fBCONFIGURATION <config> ...\fP). |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| matlab_add_unit_test( |
| NAME <name> |
| UNITTEST_FILE matlab_file_containing_unittest.m |
| [CUSTOM_TEST_COMMAND matlab_command_to_run_as_test] |
| [UNITTEST_PRECOMMAND matlab_command_to_run] |
| [TIMEOUT timeout] |
| [ADDITIONAL_PATH path1 [path2 ...]] |
| [MATLAB_ADDITIONAL_STARTUP_OPTIONS option1 [option2 ...]] |
| [TEST_ARGS arg1 [arg2 ...]] |
| [NO_UNITTEST_FRAMEWORK] |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The function arguments are: |
| .INDENT 7.0 |
| .TP |
| .B \fBNAME\fP |
| name of the unittest in ctest. |
| .TP |
| .B \fBUNITTEST_FILE\fP |
| the matlab unittest file. Its path will be automatically |
| added to the Matlab path. |
| .TP |
| .B \fBCUSTOM_TEST_COMMAND\fP |
| Matlab script command to run as the test. |
| If this is not set, then the following is run: |
| \fBruntests(\(aqmatlab_file_name\(aq), exit(max([ans(1,:).Failed]))\fP |
| where \fBmatlab_file_name\fP is the \fBUNITTEST_FILE\fP without the extension. |
| .TP |
| .B \fBUNITTEST_PRECOMMAND\fP |
| Matlab script command to be ran before the file |
| containing the test (eg. GPU device initialization based on CMake |
| variables). |
| .TP |
| .B \fBTIMEOUT\fP |
| the test timeout in seconds. Defaults to 180 seconds as the |
| Matlab unit test may hang. |
| .TP |
| .B \fBADDITIONAL_PATH\fP |
| a list of paths to add to the Matlab path prior to |
| running the unit test. |
| .TP |
| .B \fBMATLAB_ADDITIONAL_STARTUP_OPTIONS\fP |
| a list of additional option in order |
| to run Matlab from the command line. |
| \fB\-nosplash \-nodesktop \-nodisplay\fP are always added. |
| .TP |
| .B \fBTEST_ARGS\fP |
| Additional options provided to the add_test command. These |
| options are added to the default options (eg. "CONFIGURATIONS Release") |
| .TP |
| .B \fBNO_UNITTEST_FRAMEWORK\fP |
| when set, indicates that the test should not |
| use the unittest framework of Matlab (available for versions >= R2013a). |
| .TP |
| .B \fBWORKING_DIRECTORY\fP |
| This will be the working directory for the test. If specified it will |
| also be the output directory used for the log file of the test run. |
| If not specified the temporary directory \fB${CMAKE_BINARY_DIR}/Matlab\fP will |
| be used as the working directory and the log location. |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B matlab_add_mex |
| Adds a Matlab MEX target. |
| This commands compiles the given sources with the current tool\-chain in |
| order to produce a MEX file. The final name of the produced output may be |
| specified, as well as additional link libraries, and a documentation entry |
| for the MEX file. Remaining arguments of the call are passed to the |
| \fBadd_library()\fP or \fBadd_executable()\fP command. |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| matlab_add_mex( |
| NAME <name> |
| [EXECUTABLE | MODULE | SHARED] |
| SRC src1 [src2 ...] |
| [OUTPUT_NAME output_name] |
| [DOCUMENTATION file.txt] |
| [LINK_TO target1 target2 ...] |
| [R2017b | R2018a] |
| [EXCLUDE_FROM_ALL] |
| [...] |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 7.0 |
| .TP |
| .B \fBNAME\fP |
| name of the target. |
| .TP |
| .B \fBSRC\fP |
| list of source files. |
| .TP |
| .B \fBLINK_TO\fP |
| a list of additional link dependencies. The target links to \fBlibmex\fP |
| and \fBlibmx\fP by default. |
| .TP |
| .B \fBOUTPUT_NAME\fP |
| if given, overrides the default name. The default name is |
| the name of the target without any prefix and |
| with \fBMatlab_MEX_EXTENSION\fP suffix. |
| .TP |
| .B \fBDOCUMENTATION\fP |
| if given, the file \fBfile.txt\fP will be considered as |
| being the documentation file for the MEX file. This file is copied into |
| the same folder without any processing, with the same name as the final |
| mex file, and with extension \fI\&.m\fP\&. In that case, typing \fBhelp <name>\fP |
| in Matlab prints the documentation contained in this file. |
| .TP |
| .B \fBR2017b\fP or \fBR2018a\fP |
| New in version 3.14. |
| |
| .sp |
| May be given to specify the version of the C API |
| to use: \fBR2017b\fP specifies the traditional (separate complex) C API, |
| and corresponds to the \fB\-R2017b\fP flag for the \fImex\fP command. \fBR2018a\fP |
| specifies the new interleaved complex C API, and corresponds to the |
| \fB\-R2018a\fP flag for the \fImex\fP command. Ignored if MATLAB version prior |
| to R2018a. Defaults to \fBR2017b\fP\&. |
| .TP |
| .B \fBMODULE\fP or \fBSHARED\fP |
| New in version 3.7. |
| |
| .sp |
| May be given to specify the type of library to be |
| created. |
| .TP |
| .B \fBEXECUTABLE\fP |
| New in version 3.7. |
| |
| .sp |
| May be given to create an executable instead of |
| a library. If no type is given explicitly, the type is \fBSHARED\fP\&. |
| .TP |
| .B \fBEXCLUDE_FROM_ALL\fP |
| This option has the same meaning as for \fBEXCLUDE_FROM_ALL\fP and |
| is forwarded to \fBadd_library()\fP or \fBadd_executable()\fP |
| commands. |
| .UNINDENT |
| .sp |
| The documentation file is not processed and should be in the following |
| format: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| % This is the documentation |
| function ret = mex_target_output_name(input1) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .SS FindMFC |
| .sp |
| Find Microsoft Foundation Class Library (MFC) on Windows |
| .sp |
| Find the native MFC \- i.e. decide if an application can link to the |
| MFC libraries. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| MFC_FOUND \- Was MFC support found |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| You don\(aqt need to include anything or link anything to use it. |
| .SS FindMotif |
| .sp |
| Try to find Motif (or lesstif) |
| .sp |
| Once done this will define: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| MOTIF_FOUND \- system has MOTIF |
| MOTIF_INCLUDE_DIR \- include paths to use Motif |
| MOTIF_LIBRARIES \- Link these to use Motif |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindMPEG |
| .sp |
| Find the native MPEG includes and library |
| .sp |
| This module defines |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| MPEG_INCLUDE_DIR, where to find MPEG.h, etc. |
| MPEG_LIBRARIES, the libraries required to use MPEG. |
| MPEG_FOUND, If false, do not try to use MPEG. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| also defined, but not for general use are |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| MPEG_mpeg2_LIBRARY, where to find the MPEG library. |
| MPEG_vo_LIBRARY, where to find the vo library. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindMPEG2 |
| .sp |
| Find the native MPEG2 includes and library |
| .sp |
| This module defines |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| MPEG2_INCLUDE_DIR, path to mpeg2dec/mpeg2.h, etc. |
| MPEG2_LIBRARIES, the libraries required to use MPEG2. |
| MPEG2_FOUND, If false, do not try to use MPEG2. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| also defined, but not for general use are |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| MPEG2_mpeg2_LIBRARY, where to find the MPEG2 library. |
| MPEG2_vo_LIBRARY, where to find the vo library. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindMPI |
| .sp |
| Find a Message Passing Interface (MPI) implementation. |
| .sp |
| The Message Passing Interface (MPI) is a library used to write |
| high\-performance distributed\-memory parallel applications, and is |
| typically deployed on a cluster. MPI is a standard interface (defined |
| by the MPI forum) for which many implementations are available. |
| .sp |
| New in version 3.10: Major overhaul of the module: many new variables, per\-language components, |
| support for a wider variety of runtimes. |
| |
| .SS Variables for using MPI |
| .sp |
| The module exposes the components \fBC\fP, \fBCXX\fP, \fBMPICXX\fP and \fBFortran\fP\&. |
| Each of these controls the various MPI languages to search for. |
| The difference between \fBCXX\fP and \fBMPICXX\fP is that \fBCXX\fP refers to the |
| MPI C API being usable from C++, whereas \fBMPICXX\fP refers to the MPI\-2 C++ API |
| that was removed again in MPI\-3. |
| .sp |
| Depending on the enabled components the following variables will be set: |
| .INDENT 0.0 |
| .TP |
| .B \fBMPI_FOUND\fP |
| Variable indicating that MPI settings for all requested languages have been found. |
| If no components are specified, this is true if MPI settings for all enabled languages |
| were detected. Note that the \fBMPICXX\fP component does not affect this variable. |
| .TP |
| .B \fBMPI_VERSION\fP |
| Minimal version of MPI detected among the requested languages, or all enabled languages |
| if no components were specified. |
| .UNINDENT |
| .sp |
| This module will set the following variables per language in your |
| project, where \fB<lang>\fP is one of C, CXX, or Fortran: |
| .INDENT 0.0 |
| .TP |
| .B \fBMPI_<lang>_FOUND\fP |
| Variable indicating the MPI settings for \fB<lang>\fP were found and that |
| simple MPI test programs compile with the provided settings. |
| .TP |
| .B \fBMPI_<lang>_COMPILER\fP |
| MPI compiler for \fB<lang>\fP if such a program exists. |
| .TP |
| .B \fBMPI_<lang>_COMPILE_OPTIONS\fP |
| Compilation options for MPI programs in \fB<lang>\fP, given as a ;\-list\&. |
| .TP |
| .B \fBMPI_<lang>_COMPILE_DEFINITIONS\fP |
| Compilation definitions for MPI programs in \fB<lang>\fP, given as a ;\-list\&. |
| .TP |
| .B \fBMPI_<lang>_INCLUDE_DIRS\fP |
| Include path(s) for MPI header. |
| .TP |
| .B \fBMPI_<lang>_LINK_FLAGS\fP |
| Linker flags for MPI programs. |
| .TP |
| .B \fBMPI_<lang>_LIBRARIES\fP |
| All libraries to link MPI programs against. |
| .UNINDENT |
| .sp |
| New in version 3.9: Additionally, the following \fBIMPORTED\fP targets are defined: |
| |
| .INDENT 0.0 |
| .TP |
| .B \fBMPI::MPI_<lang>\fP |
| Target for using MPI from \fB<lang>\fP\&. |
| .UNINDENT |
| .sp |
| The following variables indicating which bindings are present will be defined: |
| .INDENT 0.0 |
| .TP |
| .B \fBMPI_MPICXX_FOUND\fP |
| Variable indicating whether the MPI\-2 C++ bindings are present (introduced in MPI\-2, removed with MPI\-3). |
| .TP |
| .B \fBMPI_Fortran_HAVE_F77_HEADER\fP |
| True if the Fortran 77 header \fBmpif.h\fP is available. |
| .TP |
| .B \fBMPI_Fortran_HAVE_F90_MODULE\fP |
| True if the Fortran 90 module \fBmpi\fP can be used for accessing MPI (MPI\-2 and higher only). |
| .TP |
| .B \fBMPI_Fortran_HAVE_F08_MODULE\fP |
| True if the Fortran 2008 \fBmpi_f08\fP is available to MPI programs (MPI\-3 and higher only). |
| .UNINDENT |
| .sp |
| If possible, the MPI version will be determined by this module. The facilities to detect the MPI version |
| were introduced with MPI\-1.2, and therefore cannot be found for older MPI versions. |
| .INDENT 0.0 |
| .TP |
| .B \fBMPI_<lang>_VERSION_MAJOR\fP |
| Major version of MPI implemented for \fB<lang>\fP by the MPI distribution. |
| .TP |
| .B \fBMPI_<lang>_VERSION_MINOR\fP |
| Minor version of MPI implemented for \fB<lang>\fP by the MPI distribution. |
| .TP |
| .B \fBMPI_<lang>_VERSION\fP |
| MPI version implemented for \fB<lang>\fP by the MPI distribution. |
| .UNINDENT |
| .sp |
| Note that there\(aqs no variable for the C bindings being accessible through \fBmpi.h\fP, since the MPI standards |
| always have required this binding to work in both C and C++ code. |
| .sp |
| For running MPI programs, the module sets the following variables |
| .INDENT 0.0 |
| .TP |
| .B \fBMPIEXEC_EXECUTABLE\fP |
| Executable for running MPI programs, if such exists. |
| .TP |
| .B \fBMPIEXEC_NUMPROC_FLAG\fP |
| Flag to pass to \fBmpiexec\fP before giving it the number of processors to run on. |
| .TP |
| .B \fBMPIEXEC_MAX_NUMPROCS\fP |
| Number of MPI processors to utilize. Defaults to the number |
| of processors detected on the host system. |
| .TP |
| .B \fBMPIEXEC_PREFLAGS\fP |
| Flags to pass to \fBmpiexec\fP directly before the executable to run. |
| .TP |
| .B \fBMPIEXEC_POSTFLAGS\fP |
| Flags to pass to \fBmpiexec\fP after other flags. |
| .UNINDENT |
| .SS Variables for locating MPI |
| .sp |
| This module performs a four step search for an MPI implementation: |
| .INDENT 0.0 |
| .IP 1. 3 |
| Search for \fBMPIEXEC_EXECUTABLE\fP and, if found, use its base directory. |
| .IP 2. 3 |
| Check if the compiler has MPI support built\-in. This is the case if the user passed a |
| compiler wrapper as \fBCMAKE_<LANG>_COMPILER\fP or if they use Cray system compiler wrappers. |
| .IP 3. 3 |
| Attempt to find an MPI compiler wrapper and determine the compiler information from it. |
| .IP 4. 3 |
| Try to find an MPI implementation that does not ship such a wrapper by guessing settings. |
| Currently, only Microsoft MPI and MPICH2 on Windows are supported. |
| .UNINDENT |
| .sp |
| For controlling the \fBMPIEXEC_EXECUTABLE\fP step, the following variables may be set: |
| .INDENT 0.0 |
| .TP |
| .B \fBMPIEXEC_EXECUTABLE\fP |
| Manually specify the location of \fBmpiexec\fP\&. |
| .TP |
| .B \fBMPI_HOME\fP |
| Specify the base directory of the MPI installation. |
| .TP |
| .B \fBENV{MPI_HOME}\fP |
| Environment variable to specify the base directory of the MPI installation. |
| .TP |
| .B \fBENV{I_MPI_ROOT}\fP |
| Environment variable to specify the base directory of the MPI installation. |
| .UNINDENT |
| .sp |
| For controlling the compiler wrapper step, the following variables may be set: |
| .INDENT 0.0 |
| .TP |
| .B \fBMPI_<lang>_COMPILER\fP |
| Search for the specified compiler wrapper and use it. |
| .TP |
| .B \fBMPI_<lang>_COMPILER_FLAGS\fP |
| Flags to pass to the MPI compiler wrapper during interrogation. Some compiler wrappers |
| support linking debug or tracing libraries if a specific flag is passed and this variable |
| may be used to obtain them. |
| .TP |
| .B \fBMPI_COMPILER_FLAGS\fP |
| Used to initialize \fBMPI_<lang>_COMPILER_FLAGS\fP if no language specific flag has been given. |
| Empty by default. |
| .TP |
| .B \fBMPI_EXECUTABLE_SUFFIX\fP |
| A suffix which is appended to all names that are being looked for. For instance you may set this |
| to \fB\&.mpich\fP or \fB\&.openmpi\fP to prefer the one or the other on Debian and its derivatives. |
| .UNINDENT |
| .sp |
| In order to control the guessing step, the following variable may be set: |
| .INDENT 0.0 |
| .TP |
| .B \fBMPI_GUESS_LIBRARY_NAME\fP |
| Valid values are \fBMSMPI\fP and \fBMPICH2\fP\&. If set, only the given library will be searched for. |
| By default, \fBMSMPI\fP will be preferred over \fBMPICH2\fP if both are available. |
| This also sets \fBMPI_SKIP_COMPILER_WRAPPER\fP to \fBtrue\fP, which may be overridden. |
| .UNINDENT |
| .sp |
| Each of the search steps may be skipped with the following control variables: |
| .INDENT 0.0 |
| .TP |
| .B \fBMPI_ASSUME_NO_BUILTIN_MPI\fP |
| If true, the module assumes that the compiler itself does not provide an MPI implementation and |
| skips to step 2. |
| .TP |
| .B \fBMPI_SKIP_COMPILER_WRAPPER\fP |
| If true, no compiler wrapper will be searched for. |
| .TP |
| .B \fBMPI_SKIP_GUESSING\fP |
| If true, the guessing step will be skipped. |
| .UNINDENT |
| .sp |
| Additionally, the following control variable is available to change search behavior: |
| .INDENT 0.0 |
| .TP |
| .B \fBMPI_CXX_SKIP_MPICXX\fP |
| Add some definitions that will disable the MPI\-2 C++ bindings. |
| Currently supported are MPICH, Open MPI, Platform MPI and derivatives thereof, |
| for example MVAPICH or Intel MPI. |
| .UNINDENT |
| .sp |
| If the find procedure fails for a variable \fBMPI_<lang>_WORKS\fP, then the settings detected by or passed to |
| the module did not work and even a simple MPI test program failed to compile. |
| .sp |
| If all of these parameters were not sufficient to find the right MPI implementation, a user may |
| disable the entire autodetection process by specifying both a list of libraries in \fBMPI_<lang>_LIBRARIES\fP |
| and a list of include directories in \fBMPI_<lang>_ADDITIONAL_INCLUDE_DIRS\fP\&. |
| Any other variable may be set in addition to these two. The module will then validate the MPI settings and store the |
| settings in the cache. |
| .SS Cache variables for MPI |
| .sp |
| The variable \fBMPI_<lang>_INCLUDE_DIRS\fP will be assembled from the following variables. |
| For C and CXX: |
| .INDENT 0.0 |
| .TP |
| .B \fBMPI_<lang>_HEADER_DIR\fP |
| Location of the \fBmpi.h\fP header on disk. |
| .UNINDENT |
| .sp |
| For Fortran: |
| .INDENT 0.0 |
| .TP |
| .B \fBMPI_Fortran_F77_HEADER_DIR\fP |
| Location of the Fortran 77 header \fBmpif.h\fP, if it exists. |
| .TP |
| .B \fBMPI_Fortran_MODULE_DIR\fP |
| Location of the \fBmpi\fP or \fBmpi_f08\fP modules, if available. |
| .UNINDENT |
| .sp |
| For all languages the following variables are additionally considered: |
| .INDENT 0.0 |
| .TP |
| .B \fBMPI_<lang>_ADDITIONAL_INCLUDE_DIRS\fP |
| A ;\-list of paths needed in addition to the normal include directories. |
| .TP |
| .B \fBMPI_<include_name>_INCLUDE_DIR\fP |
| Path variables for include folders referred to by \fB<include_name>\fP\&. |
| .TP |
| .B \fBMPI_<lang>_ADDITIONAL_INCLUDE_VARS\fP |
| A ;\-list of \fB<include_name>\fP that will be added to the include locations of \fB<lang>\fP\&. |
| .UNINDENT |
| .sp |
| The variable \fBMPI_<lang>_LIBRARIES\fP will be assembled from the following variables: |
| .INDENT 0.0 |
| .TP |
| .B \fBMPI_<lib_name>_LIBRARY\fP |
| The location of a library called \fB<lib_name>\fP for use with MPI. |
| .TP |
| .B \fBMPI_<lang>_LIB_NAMES\fP |
| A ;\-list of \fB<lib_name>\fP that will be added to the include locations of \fB<lang>\fP\&. |
| .UNINDENT |
| .SS Usage of mpiexec |
| .sp |
| When using \fBMPIEXEC_EXECUTABLE\fP to execute MPI applications, you should typically |
| use all of the \fBMPIEXEC_EXECUTABLE\fP flags as follows: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ${MPIEXEC_EXECUTABLE} ${MPIEXEC_NUMPROC_FLAG} ${MPIEXEC_MAX_NUMPROCS} |
| ${MPIEXEC_PREFLAGS} EXECUTABLE ${MPIEXEC_POSTFLAGS} ARGS |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| where \fBEXECUTABLE\fP is the MPI program, and \fBARGS\fP are the arguments to |
| pass to the MPI program. |
| .SS Advanced variables for using MPI |
| .sp |
| The module can perform some advanced feature detections upon explicit request. |
| .sp |
| \fBImportant notice:\fP The following checks cannot be performed without \fIexecuting\fP an MPI test program. |
| Consider the special considerations for the behavior of \fBtry_run()\fP during cross compilation. |
| Moreover, running an MPI program can cause additional issues, like a firewall notification on some systems. |
| You should only enable these detections if you absolutely need the information. |
| .sp |
| If the following variables are set to true, the respective search will be performed: |
| .INDENT 0.0 |
| .TP |
| .B \fBMPI_DETERMINE_Fortran_CAPABILITIES\fP |
| Determine for all available Fortran bindings what the values of \fBMPI_SUBARRAYS_SUPPORTED\fP and |
| \fBMPI_ASYNC_PROTECTS_NONBLOCKING\fP are and make their values available as \fBMPI_Fortran_<binding>_SUBARRAYS\fP |
| and \fBMPI_Fortran_<binding>_ASYNCPROT\fP, where \fB<binding>\fP is one of \fBF77_HEADER\fP, \fBF90_MODULE\fP and |
| \fBF08_MODULE\fP\&. |
| .TP |
| .B \fBMPI_DETERMINE_LIBRARY_VERSION\fP |
| For each language, find the output of \fBMPI_Get_library_version\fP and make it available as \fBMPI_<lang>_LIBRARY_VERSION_STRING\fP\&. |
| This information is usually tied to the runtime component of an MPI implementation and might differ depending on \fB<lang>\fP\&. |
| Note that the return value is entirely implementation defined. This information might be used to identify |
| the MPI vendor and for example pick the correct one of multiple third party binaries that matches the MPI vendor. |
| .UNINDENT |
| .SS Backward Compatibility |
| .sp |
| Deprecated since version 3.10. |
| |
| .sp |
| For backward compatibility with older versions of FindMPI, these |
| variables are set: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| MPI_COMPILER MPI_LIBRARY MPI_EXTRA_LIBRARY |
| MPI_COMPILE_FLAGS MPI_INCLUDE_PATH MPI_LINK_FLAGS |
| MPI_LIBRARIES |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| In new projects, please use the \fBMPI_<lang>_XXX\fP equivalents. |
| Additionally, the following variables are deprecated: |
| .INDENT 0.0 |
| .TP |
| .B \fBMPI_<lang>_COMPILE_FLAGS\fP |
| Use \fBMPI_<lang>_COMPILE_OPTIONS\fP and \fBMPI_<lang>_COMPILE_DEFINITIONS\fP instead. |
| .TP |
| .B \fBMPI_<lang>_INCLUDE_PATH\fP |
| For consumption use \fBMPI_<lang>_INCLUDE_DIRS\fP and for specifying folders use \fBMPI_<lang>_ADDITIONAL_INCLUDE_DIRS\fP instead. |
| .TP |
| .B \fBMPIEXEC\fP |
| Use \fBMPIEXEC_EXECUTABLE\fP instead. |
| .UNINDENT |
| .SS FindMsys |
| .sp |
| New in version 3.21. |
| |
| .sp |
| Find MSYS, a POSIX\-compatible environment that runs natively |
| on Microsoft Windows |
| .SS FindODBC |
| .sp |
| New in version 3.12. |
| |
| .sp |
| Find an Open Database Connectivity (ODBC) include directory and library. |
| .sp |
| On Windows, when building with Visual Studio, this module assumes the ODBC |
| library is provided by the available Windows SDK. |
| .sp |
| On Unix, this module allows to search for ODBC library provided by |
| unixODBC or iODBC implementations of ODBC API. |
| This module reads hint about location of the config program: |
| .INDENT 0.0 |
| .TP |
| .B ODBC_CONFIG |
| Location of odbc_config or iodbc\-config program |
| .UNINDENT |
| .sp |
| Otherwise, this module tries to find the config program, |
| first from unixODBC, then from iODBC. |
| If no config program found, this module searches for ODBC header |
| and library in list of known locations. |
| .SS Imported targets |
| .sp |
| This module defines the following \fBIMPORTED\fP targets: |
| .INDENT 0.0 |
| .TP |
| .B ODBC::ODBC |
| Imported target for using the ODBC library, if found. |
| .UNINDENT |
| .SS Result variables |
| .INDENT 0.0 |
| .TP |
| .B ODBC_FOUND |
| Set to true if ODBC library found, otherwise false or undefined. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B ODBC_INCLUDE_DIRS |
| Paths to include directories listed in one variable for use by ODBC client. |
| May be empty on Windows, where the include directory corresponding to the |
| expected Windows SDK is already available in the compilation environment. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B ODBC_LIBRARIES |
| Paths to libraries to linked against to use ODBC. |
| May just a library name on Windows, where the library directory corresponding |
| to the expected Windows SDK is already available in the compilation environment. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B ODBC_CONFIG |
| Path to unixODBC or iODBC config program, if found or specified. |
| .UNINDENT |
| .SS Cache variables |
| .sp |
| For users who wish to edit and control the module behavior, this module |
| reads hints about search locations from the following variables: |
| .INDENT 0.0 |
| .TP |
| .B ODBC_INCLUDE_DIR |
| Path to ODBC include directory with \fBsql.h\fP header. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B ODBC_LIBRARY |
| Path to ODBC library to be linked. |
| .UNINDENT |
| .sp |
| These variables should not be used directly by project code. |
| .SS Limitations |
| .sp |
| On Windows, this module does not search for iODBC. |
| On Unix, there is no way to prefer unixODBC over iODBC, or vice versa, |
| other than providing the config program location using the \fBODBC_CONFIG\fP\&. |
| This module does not allow to search for a specific ODBC driver. |
| .SS FindOpenACC |
| .sp |
| New in version 3.10. |
| |
| .sp |
| Detect OpenACC support by the compiler. |
| .sp |
| This module can be used to detect OpenACC support in a compiler. |
| If the compiler supports OpenACC, the flags required to compile with |
| OpenACC support are returned in variables for the different languages. |
| Currently, only NVHPC, PGI, GNU and Cray compilers are supported. |
| .SS Imported Targets |
| .sp |
| New in version 3.16. |
| |
| .sp |
| The module provides \fBIMPORTED\fP targets: |
| .INDENT 0.0 |
| .TP |
| .B \fBOpenACC::OpenACC_<lang>\fP |
| Target for using OpenACC from \fB<lang>\fP\&. |
| .UNINDENT |
| .SS Variables |
| .sp |
| This module will set the following variables per language in your |
| project, where \fB<lang>\fP is one of C, CXX, or Fortran: |
| .INDENT 0.0 |
| .TP |
| .B \fBOpenACC_<lang>_FOUND\fP |
| Variable indicating if OpenACC support for \fB<lang>\fP was detected. |
| .TP |
| .B \fBOpenACC_<lang>_FLAGS\fP |
| OpenACC compiler flags for \fB<lang>\fP, separated by spaces. |
| .TP |
| .B \fBOpenACC_<lang>_OPTIONS\fP |
| New in version 3.16. |
| |
| .sp |
| OpenACC compiler flags for \fB<lang>\fP, as a list. Suitable for usage |
| with target_compile_options or target_link_options. |
| .UNINDENT |
| .sp |
| The module will also try to provide the OpenACC version variables: |
| .INDENT 0.0 |
| .TP |
| .B \fBOpenACC_<lang>_SPEC_DATE\fP |
| Date of the OpenACC specification implemented by the \fB<lang>\fP compiler. |
| .TP |
| .B \fBOpenACC_<lang>_VERSION_MAJOR\fP |
| Major version of OpenACC implemented by the \fB<lang>\fP compiler. |
| .TP |
| .B \fBOpenACC_<lang>_VERSION_MINOR\fP |
| Minor version of OpenACC implemented by the \fB<lang>\fP compiler. |
| .TP |
| .B \fBOpenACC_<lang>_VERSION\fP |
| OpenACC version implemented by the \fB<lang>\fP compiler. |
| .UNINDENT |
| .sp |
| The specification date is formatted as given in the OpenACC standard: |
| \fByyyymm\fP where \fByyyy\fP and \fBmm\fP represents the year and month of |
| the OpenACC specification implemented by the \fB<lang>\fP compiler. |
| .SS Input Variables |
| .sp |
| \fBOpenACC_ACCEL_TARGET=<target>\fP |
| If set, will the correct target accelerator flag set to the <target> will |
| be returned with OpenACC_<lang>_FLAGS. |
| .SS FindOpenAL |
| .sp |
| Finds Open Audio Library (OpenAL). |
| .sp |
| Projects using this module should use \fB#include "al.h"\fP to include the OpenAL |
| header file, \fBnot\fP \fB#include <AL/al.h>\fP\&. The reason for this is that the |
| latter is not entirely portable. Windows/Creative Labs does not by default put |
| their headers in \fBAL/\fP and macOS uses the convention \fB<OpenAL/al.h>\fP\&. |
| .SS Hints |
| .sp |
| Environment variable \fB$OPENALDIR\fP can be used to set the prefix of OpenAL |
| installation to be found. |
| .sp |
| By default on macOS, system framework is search first. In other words, |
| OpenAL is searched in the following order: |
| .INDENT 0.0 |
| .IP 1. 3 |
| System framework: \fB/System/Library/Frameworks\fP, whose priority can be |
| changed via setting the \fBCMAKE_FIND_FRAMEWORK\fP variable. |
| .IP 2. 3 |
| Environment variable \fB$OPENALDIR\fP\&. |
| .IP 3. 3 |
| System paths. |
| .IP 4. 3 |
| User\-compiled framework: \fB~/Library/Frameworks\fP\&. |
| .IP 5. 3 |
| Manually compiled framework: \fB/Library/Frameworks\fP\&. |
| .IP 6. 3 |
| Add\-on package: \fB/opt\fP\&. |
| .UNINDENT |
| .SS Result Variables |
| .sp |
| This module defines the following variables: |
| .INDENT 0.0 |
| .TP |
| .B \fBOPENAL_FOUND\fP |
| If false, do not try to link to OpenAL |
| .TP |
| .B \fBOPENAL_INCLUDE_DIR\fP |
| OpenAL include directory |
| .TP |
| .B \fBOPENAL_LIBRARY\fP |
| Path to the OpenAL library |
| .TP |
| .B \fBOPENAL_VERSION_STRING\fP |
| Human\-readable string containing the version of OpenAL |
| .UNINDENT |
| .SS FindOpenCL |
| .sp |
| New in version 3.1. |
| |
| .sp |
| Finds Open Computing Language (OpenCL) |
| .sp |
| New in version 3.10: Detection of OpenCL 2.1 and 2.2. |
| |
| .SS IMPORTED Targets |
| .sp |
| New in version 3.7. |
| |
| .sp |
| This module defines \fBIMPORTED\fP target \fBOpenCL::OpenCL\fP, if |
| OpenCL has been found. |
| .SS Result Variables |
| .sp |
| This module defines the following variables: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| OpenCL_FOUND \- True if OpenCL was found |
| OpenCL_INCLUDE_DIRS \- include directories for OpenCL |
| OpenCL_LIBRARIES \- link against this library to use OpenCL |
| OpenCL_VERSION_STRING \- Highest supported OpenCL version (eg. 1.2) |
| OpenCL_VERSION_MAJOR \- The major version of the OpenCL implementation |
| OpenCL_VERSION_MINOR \- The minor version of the OpenCL implementation |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The module will also define two cache variables: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| OpenCL_INCLUDE_DIR \- the OpenCL include directory |
| OpenCL_LIBRARY \- the path to the OpenCL library |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindOpenGL |
| .sp |
| FindModule for OpenGL and OpenGL Utility Library (GLU). |
| .sp |
| Changed in version 3.2: X11 is no longer added as a dependency on Unix/Linux systems. |
| |
| .sp |
| New in version 3.10: GLVND support on Linux. See the \fI\%Linux\-specific\fP section below. |
| |
| .SS Optional COMPONENTS |
| .sp |
| New in version 3.10. |
| |
| .sp |
| This module respects several optional COMPONENTS: \fBEGL\fP, \fBGLX\fP, and |
| \fBOpenGL\fP\&. There are corresponding import targets for each of these flags. |
| .SS IMPORTED Targets |
| .sp |
| New in version 3.8. |
| |
| .sp |
| This module defines the \fBIMPORTED\fP targets: |
| .INDENT 0.0 |
| .TP |
| .B \fBOpenGL::GL\fP |
| Defined to the platform\-specific OpenGL libraries if the system has OpenGL. |
| .TP |
| .B \fBOpenGL::GLU\fP |
| Defined if the system has OpenGL Utility Library (GLU). |
| .UNINDENT |
| .sp |
| New in version 3.10: Additionally, the following GLVND\-specific library targets are defined: |
| |
| .INDENT 0.0 |
| .TP |
| .B \fBOpenGL::OpenGL\fP |
| Defined to libOpenGL if the system is GLVND\-based. |
| .TP |
| .B \fBOpenGL::GLX\fP |
| Defined if the system has OpenGL Extension to the X Window System (GLX). |
| .TP |
| .B \fBOpenGL::EGL\fP |
| Defined if the system has EGL. |
| .UNINDENT |
| .SS Result Variables |
| .sp |
| This module sets the following variables: |
| .INDENT 0.0 |
| .TP |
| .B \fBOPENGL_FOUND\fP |
| True, if the system has OpenGL and all components are found. |
| .TP |
| .B \fBOPENGL_XMESA_FOUND\fP |
| True, if the system has XMESA. |
| .TP |
| .B \fBOPENGL_GLU_FOUND\fP |
| True, if the system has GLU. |
| .TP |
| .B \fBOpenGL_OpenGL_FOUND\fP |
| True, if the system has an OpenGL library. |
| .TP |
| .B \fBOpenGL_GLX_FOUND\fP |
| True, if the system has GLX. |
| .TP |
| .B \fBOpenGL_EGL_FOUND\fP |
| True, if the system has EGL. |
| .TP |
| .B \fBOPENGL_INCLUDE_DIR\fP |
| Path to the OpenGL include directory. |
| .TP |
| .B \fBOPENGL_EGL_INCLUDE_DIRS\fP |
| Path to the EGL include directory. |
| .TP |
| .B \fBOPENGL_LIBRARIES\fP |
| Paths to the OpenGL library, windowing system libraries, and GLU libraries. |
| On Linux, this assumes GLX and is never correct for EGL\-based targets. |
| Clients are encouraged to use the \fBOpenGL::*\fP import targets instead. |
| .UNINDENT |
| .sp |
| New in version 3.10: Variables for GLVND\-specific libraries \fBOpenGL\fP, \fBEGL\fP and \fBGLX\fP\&. |
| |
| .SS Cache variables |
| .sp |
| The following cache variables may also be set: |
| .INDENT 0.0 |
| .TP |
| .B \fBOPENGL_egl_LIBRARY\fP |
| Path to the EGL library. |
| .TP |
| .B \fBOPENGL_glu_LIBRARY\fP |
| Path to the GLU library. |
| .TP |
| .B \fBOPENGL_glx_LIBRARY\fP |
| Path to the GLVND \(aqGLX\(aq library. |
| .TP |
| .B \fBOPENGL_opengl_LIBRARY\fP |
| Path to the GLVND \(aqOpenGL\(aq library |
| .TP |
| .B \fBOPENGL_gl_LIBRARY\fP |
| Path to the OpenGL library. New code should prefer the \fBOpenGL::*\fP import |
| targets. |
| .UNINDENT |
| .sp |
| New in version 3.10: Variables for GLVND\-specific libraries \fBOpenGL\fP, \fBEGL\fP and \fBGLX\fP\&. |
| |
| .SS Linux\-specific |
| .sp |
| Some Linux systems utilize GLVND as a new ABI for OpenGL. GLVND separates |
| context libraries from OpenGL itself; OpenGL lives in "libOpenGL", and |
| contexts are defined in "libGLX" or "libEGL". GLVND is currently the only way |
| to get OpenGL 3+ functionality via EGL in a manner portable across vendors. |
| Projects may use GLVND explicitly with target \fBOpenGL::OpenGL\fP and either |
| \fBOpenGL::GLX\fP or \fBOpenGL::EGL\fP\&. |
| .sp |
| Projects may use the \fBOpenGL::GL\fP target (or \fBOPENGL_LIBRARIES\fP variable) |
| to use legacy GL interfaces. These will use the legacy GL library located |
| by \fBOPENGL_gl_LIBRARY\fP, if available. If \fBOPENGL_gl_LIBRARY\fP is empty or |
| not found and GLVND is available, the \fBOpenGL::GL\fP target will use GLVND |
| \fBOpenGL::OpenGL\fP and \fBOpenGL::GLX\fP (and the \fBOPENGL_LIBRARIES\fP |
| variable will use the corresponding libraries). Thus, for non\-EGL\-based |
| Linux targets, the \fBOpenGL::GL\fP target is most portable. |
| .sp |
| A \fBOpenGL_GL_PREFERENCE\fP variable may be set to specify the preferred way |
| to provide legacy GL interfaces in case multiple choices are available. |
| The value may be one of: |
| .INDENT 0.0 |
| .TP |
| .B \fBGLVND\fP |
| If the GLVND OpenGL and GLX libraries are available, prefer them. |
| This forces \fBOPENGL_gl_LIBRARY\fP to be empty. |
| .sp |
| Changed in version 3.11: This is the default, unless policy \fBCMP0072\fP is set to \fBOLD\fP |
| and no components are requeted (since components |
| correspond to GLVND libraries). |
| |
| .TP |
| .B \fBLEGACY\fP |
| Prefer to use the legacy libGL library, if available. |
| .UNINDENT |
| .sp |
| For EGL targets the client must rely on GLVND support on the user\(aqs system. |
| Linking should use the \fBOpenGL::OpenGL OpenGL::EGL\fP targets. Using GLES* |
| libraries is theoretically possible in place of \fBOpenGL::OpenGL\fP, but this |
| module does not currently support that; contributions welcome. |
| .sp |
| \fBOPENGL_egl_LIBRARY\fP and \fBOPENGL_EGL_INCLUDE_DIRS\fP are defined in the case of |
| GLVND. For non\-GLVND Linux and other systems these are left undefined. |
| .SS macOS\-Specific |
| .sp |
| On OSX FindOpenGL defaults to using the framework version of OpenGL. People |
| will have to change the cache values of OPENGL_glu_LIBRARY and |
| OPENGL_gl_LIBRARY to use OpenGL with X11 on OSX. |
| .SS FindOpenMP |
| .sp |
| Finds Open Multi\-Processing (OpenMP) support. |
| .sp |
| This module can be used to detect OpenMP support in a compiler. If |
| the compiler supports OpenMP, the flags required to compile with |
| OpenMP support are returned in variables for the different languages. |
| The variables may be empty if the compiler does not need a special |
| flag to support OpenMP. |
| .sp |
| New in version 3.5: Clang support. |
| |
| .SS Variables |
| .sp |
| New in version 3.10: The module exposes the components \fBC\fP, \fBCXX\fP, and \fBFortran\fP\&. |
| Each of these controls the various languages to search OpenMP support for. |
| |
| .sp |
| Depending on the enabled components the following variables will be set: |
| .INDENT 0.0 |
| .TP |
| .B \fBOpenMP_FOUND\fP |
| Variable indicating that OpenMP flags for all requested languages have been found. |
| If no components are specified, this is true if OpenMP settings for all enabled languages |
| were detected. |
| .TP |
| .B \fBOpenMP_VERSION\fP |
| Minimal version of the OpenMP standard detected among the requested languages, |
| or all enabled languages if no components were specified. |
| .UNINDENT |
| .sp |
| This module will set the following variables per language in your |
| project, where \fB<lang>\fP is one of C, CXX, or Fortran: |
| .INDENT 0.0 |
| .TP |
| .B \fBOpenMP_<lang>_FOUND\fP |
| Variable indicating if OpenMP support for \fB<lang>\fP was detected. |
| .TP |
| .B \fBOpenMP_<lang>_FLAGS\fP |
| OpenMP compiler flags for \fB<lang>\fP, separated by spaces. |
| .TP |
| .B \fBOpenMP_<lang>_INCLUDE_DIRS\fP |
| Directories that must be added to the header search path for \fB<lang>\fP |
| when using OpenMP. |
| .UNINDENT |
| .sp |
| For linking with OpenMP code written in \fB<lang>\fP, the following |
| variables are provided: |
| .INDENT 0.0 |
| .TP |
| .B \fBOpenMP_<lang>_LIB_NAMES\fP |
| ;\-list of libraries for OpenMP programs for \fB<lang>\fP\&. |
| .TP |
| .B \fBOpenMP_<libname>_LIBRARY\fP |
| Location of the individual libraries needed for OpenMP support in \fB<lang>\fP\&. |
| .TP |
| .B \fBOpenMP_<lang>_LIBRARIES\fP |
| A list of libraries needed to link with OpenMP code written in \fB<lang>\fP\&. |
| .UNINDENT |
| .sp |
| Additionally, the module provides \fBIMPORTED\fP targets: |
| .INDENT 0.0 |
| .TP |
| .B \fBOpenMP::OpenMP_<lang>\fP |
| Target for using OpenMP from \fB<lang>\fP\&. |
| .UNINDENT |
| .sp |
| Specifically for Fortran, the module sets the following variables: |
| .INDENT 0.0 |
| .TP |
| .B \fBOpenMP_Fortran_HAVE_OMPLIB_HEADER\fP |
| Boolean indicating if OpenMP is accessible through \fBomp_lib.h\fP\&. |
| .TP |
| .B \fBOpenMP_Fortran_HAVE_OMPLIB_MODULE\fP |
| Boolean indicating if OpenMP is accessible through the \fBomp_lib\fP Fortran module. |
| .UNINDENT |
| .sp |
| The module will also try to provide the OpenMP version variables: |
| .INDENT 0.0 |
| .TP |
| .B \fBOpenMP_<lang>_SPEC_DATE\fP |
| New in version 3.7. |
| |
| .sp |
| Date of the OpenMP specification implemented by the \fB<lang>\fP compiler. |
| .TP |
| .B \fBOpenMP_<lang>_VERSION_MAJOR\fP |
| Major version of OpenMP implemented by the \fB<lang>\fP compiler. |
| .TP |
| .B \fBOpenMP_<lang>_VERSION_MINOR\fP |
| Minor version of OpenMP implemented by the \fB<lang>\fP compiler. |
| .TP |
| .B \fBOpenMP_<lang>_VERSION\fP |
| OpenMP version implemented by the \fB<lang>\fP compiler. |
| .UNINDENT |
| .sp |
| The specification date is formatted as given in the OpenMP standard: |
| \fByyyymm\fP where \fByyyy\fP and \fBmm\fP represents the year and month of |
| the OpenMP specification implemented by the \fB<lang>\fP compiler. |
| .sp |
| For some compilers, it may be necessary to add a header search path to find |
| the relevant OpenMP headers. This location may be language\-specific. Where |
| this is needed, the module may attempt to find the location, but it can be |
| provided directly by setting the \fBOpenMP_<lang>_INCLUDE_DIR\fP cache variable. |
| Note that this variable is an _input_ control to the module. Project code |
| should use the \fBOpenMP_<lang>_INCLUDE_DIRS\fP _output_ variable if it needs |
| to know what include directories are needed. |
| .SS FindOpenSceneGraph |
| .sp |
| Find OpenSceneGraph (3D graphics application programming interface) |
| .sp |
| This module searches for the OpenSceneGraph core "osg" library as well |
| as \fBFindOpenThreads\fP, and whatever additional \fBCOMPONENTS\fP |
| (nodekits) that you specify. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| See http://www.openscenegraph.org |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| NOTE: To use this module effectively you must either require \fBCMake >= |
| 2.6.3\fP with \fBcmake_minimum_required(VERSION 2.6.3)\fP or download |
| and place \fBFindOpenThreads\fP, \fBFindosg\fP functions, |
| \fBFindosg\fP and \fBFind<etc>.cmake\fP files into your |
| \fBCMAKE_MODULE_PATH\fP\&. |
| |
| .sp |
| .ce |
| ---- |
| |
| .ce 0 |
| .sp |
| .sp |
| This module accepts the following variables (note mixed case) |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| OpenSceneGraph_DEBUG \- Enable debugging output |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| OpenSceneGraph_MARK_AS_ADVANCED \- Mark cache variables as advanced |
| automatically |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The following environment variables are also respected for finding the |
| OSG and it\(aqs various components. \fBCMAKE_PREFIX_PATH\fP can also be |
| used for this (see \fBfind_library()\fP CMake documentation). |
| .INDENT 0.0 |
| .TP |
| .B \fB<MODULE>_DIR\fP |
| (where \fBMODULE\fP is of the form "OSGVOLUME" and there is |
| a \fBFindosgVolume\fP\&.cmake\(ga file) |
| .TP |
| .B \fBOSG_DIR\fP |
| .TP |
| .B \fBOSGDIR\fP |
| .TP |
| .B \fBOSG_ROOT\fP |
| .UNINDENT |
| .sp |
| [CMake 2.8.10]: The CMake variable \fBOSG_DIR\fP can now be used as well to |
| influence detection, instead of needing to specify an environment |
| variable. |
| .sp |
| This module defines the following output variables: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| OPENSCENEGRAPH_FOUND \- Was the OSG and all of the specified components found? |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| OPENSCENEGRAPH_VERSION \- The version of the OSG which was found |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| OPENSCENEGRAPH_INCLUDE_DIRS \- Where to find the headers |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| OPENSCENEGRAPH_LIBRARIES \- The OSG libraries |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| ================================== Example Usage: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_package(OpenSceneGraph 2.0.0 REQUIRED osgDB osgUtil) |
| # libOpenThreads & libosg automatically searched |
| include_directories(${OPENSCENEGRAPH_INCLUDE_DIRS}) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_executable(foo foo.cc) |
| target_link_libraries(foo ${OPENSCENEGRAPH_LIBRARIES}) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindOpenSSL |
| .sp |
| Find the OpenSSL encryption library. |
| .sp |
| This module finds an installed OpenSSL library and determines its version. |
| .sp |
| New in version 3.19: When a version is requested, it can be specified as a simple value or as a |
| range. For a detailed description of version range usage and capabilities, |
| refer to the \fBfind_package()\fP command. |
| |
| .sp |
| New in version 3.18: Support for OpenSSL 3.0. |
| |
| .SS Optional COMPONENTS |
| .sp |
| New in version 3.12. |
| |
| .sp |
| This module supports two optional COMPONENTS: \fBCrypto\fP and \fBSSL\fP\&. Both |
| components have associated imported targets, as described below. |
| .SS Imported Targets |
| .sp |
| New in version 3.4. |
| |
| .sp |
| This module defines the following \fBIMPORTED\fP targets: |
| .INDENT 0.0 |
| .TP |
| .B \fBOpenSSL::SSL\fP |
| The OpenSSL \fBssl\fP library, if found. |
| .TP |
| .B \fBOpenSSL::Crypto\fP |
| The OpenSSL \fBcrypto\fP library, if found. |
| .TP |
| .B \fBOpenSSL::applink\fP |
| New in version 3.18. |
| |
| .sp |
| The OpenSSL \fBapplink\fP components that might be need to be compiled into |
| projects under MSVC. This target is available only if found OpenSSL version |
| is not less than 0.9.8. By linking this target the above OpenSSL targets can |
| be linked even if the project has different MSVC runtime configurations with |
| the above OpenSSL targets. This target has no effect on platforms other than |
| MSVC. |
| .UNINDENT |
| .sp |
| NOTE: Due to how \fBINTERFACE_SOURCES\fP are consumed by the consuming target, |
| unless you certainly know what you are doing, it is always preferred to link |
| \fBOpenSSL::applink\fP target as \fBPRIVATE\fP and to make sure that this target is |
| linked at most once for the whole dependency graph of any library or |
| executable: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| target_link_libraries(myTarget PRIVATE OpenSSL::applink) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Otherwise you would probably encounter unexpected random problems when building |
| and linking, as both the ISO C and the ISO C++ standard claims almost nothing |
| about what a link process should be. |
| .SS Result Variables |
| .sp |
| This module will set the following variables in your project: |
| .INDENT 0.0 |
| .TP |
| .B \fBOPENSSL_FOUND\fP |
| System has the OpenSSL library. If no components are requested it only |
| requires the crypto library. |
| .TP |
| .B \fBOPENSSL_INCLUDE_DIR\fP |
| The OpenSSL include directory. |
| .TP |
| .B \fBOPENSSL_CRYPTO_LIBRARY\fP |
| The OpenSSL crypto library. |
| .TP |
| .B \fBOPENSSL_CRYPTO_LIBRARIES\fP |
| The OpenSSL crypto library and its dependencies. |
| .TP |
| .B \fBOPENSSL_SSL_LIBRARY\fP |
| The OpenSSL SSL library. |
| .TP |
| .B \fBOPENSSL_SSL_LIBRARIES\fP |
| The OpenSSL SSL library and its dependencies. |
| .TP |
| .B \fBOPENSSL_LIBRARIES\fP |
| All OpenSSL libraries and their dependencies. |
| .TP |
| .B \fBOPENSSL_VERSION\fP |
| This is set to \fB$major.$minor.$revision$patch\fP (e.g. \fB0.9.8s\fP). |
| .TP |
| .B \fBOPENSSL_APPLINK_SOURCE\fP |
| The sources in the target \fBOpenSSL::applink\fP that is mentioned above. This |
| variable shall always be undefined if found openssl version is less than |
| 0.9.8 or if platform is not MSVC. |
| .UNINDENT |
| .SS Hints |
| .sp |
| Set \fBOPENSSL_ROOT_DIR\fP to the root directory of an OpenSSL installation. |
| .sp |
| New in version 3.4: Set \fBOPENSSL_USE_STATIC_LIBS\fP to \fBTRUE\fP to look for static libraries. |
| |
| .sp |
| New in version 3.5: Set \fBOPENSSL_MSVC_STATIC_RT\fP set \fBTRUE\fP to choose the MT version of the lib. |
| |
| .SS FindOpenThreads |
| .sp |
| OpenThreads is a C++ based threading library. Its largest userbase |
| seems to OpenSceneGraph so you might notice I accept OSGDIR as an |
| environment path. I consider this part of the Findosg* suite used to |
| find OpenSceneGraph components. Each component is separate and you |
| must opt in to each module. |
| .sp |
| Locate OpenThreads This module defines OPENTHREADS_LIBRARY |
| OPENTHREADS_FOUND, if false, do not try to link to OpenThreads |
| OPENTHREADS_INCLUDE_DIR, where to find the headers |
| .sp |
| $OPENTHREADS_DIR is an environment variable that would correspond to |
| the ./configure \-\-prefix=$OPENTHREADS_DIR used in building osg. |
| .sp |
| [CMake 2.8.10]: The CMake variables OPENTHREADS_DIR or OSG_DIR can now |
| be used as well to influence detection, instead of needing to specify |
| an environment variable. |
| .sp |
| Created by Eric Wing. |
| .SS Findosg |
| .sp |
| NOTE: It is highly recommended that you use the new |
| FindOpenSceneGraph.cmake introduced in CMake 2.6.3 and not use this |
| Find module directly. |
| .sp |
| This is part of the Findosg* suite used to find OpenSceneGraph |
| components. Each component is separate and you must opt in to each |
| module. You must also opt into OpenGL and OpenThreads (and Producer |
| if needed) as these modules won\(aqt do it for you. This is to allow you |
| control over your own system piece by piece in case you need to opt |
| out of certain components or change the Find behavior for a particular |
| module (perhaps because the default FindOpenGL.cmake module doesn\(aqt |
| work with your system as an example). If you want to use a more |
| convenient module that includes everything, use the |
| FindOpenSceneGraph.cmake instead of the Findosg*.cmake modules. |
| .sp |
| Locate osg This module defines |
| .sp |
| OSG_FOUND \- Was the Osg found? OSG_INCLUDE_DIR \- Where to find the |
| headers OSG_LIBRARIES \- The libraries to link against for the OSG (use |
| this) |
| .sp |
| OSG_LIBRARY \- The OSG library OSG_LIBRARY_DEBUG \- The OSG debug |
| library |
| .sp |
| $OSGDIR is an environment variable that would correspond to the |
| \&./configure \-\-prefix=$OSGDIR used in building osg. |
| .sp |
| Created by Eric Wing. |
| .SS Findosg_functions |
| .sp |
| This CMake file contains two macros to assist with searching for OSG |
| libraries and nodekits. Please see FindOpenSceneGraph.cmake for full |
| documentation. |
| .SS FindosgAnimation |
| .sp |
| This is part of the Findosg* suite used to find OpenSceneGraph |
| components. Each component is separate and you must opt in to each |
| module. You must also opt into OpenGL and OpenThreads (and Producer |
| if needed) as these modules won\(aqt do it for you. This is to allow you |
| control over your own system piece by piece in case you need to opt |
| out of certain components or change the Find behavior for a particular |
| module (perhaps because the default FindOpenGL.cmake module doesn\(aqt |
| work with your system as an example). If you want to use a more |
| convenient module that includes everything, use the |
| FindOpenSceneGraph.cmake instead of the Findosg*.cmake modules. |
| .sp |
| Locate osgAnimation This module defines |
| .sp |
| OSGANIMATION_FOUND \- Was osgAnimation found? OSGANIMATION_INCLUDE_DIR |
| \- Where to find the headers OSGANIMATION_LIBRARIES \- The libraries to |
| link against for the OSG (use this) |
| .sp |
| OSGANIMATION_LIBRARY \- The OSG library OSGANIMATION_LIBRARY_DEBUG \- |
| The OSG debug library |
| .sp |
| $OSGDIR is an environment variable that would correspond to the |
| \&./configure \-\-prefix=$OSGDIR used in building osg. |
| .sp |
| Created by Eric Wing. |
| .SS FindosgDB |
| .sp |
| This is part of the \fBFindosg*\fP suite used to find OpenSceneGraph |
| components. Each component is separate and you must opt in to each |
| module. You must also opt into OpenGL and OpenThreads (and Producer |
| if needed) as these modules won\(aqt do it for you. This is to allow you |
| control over your own system piece by piece in case you need to opt |
| out of certain components or change the Find behavior for a particular |
| module (perhaps because the default \fBFindOpenGL\fP module doesn\(aqt |
| work with your system as an example). If you want to use a more |
| convenient module that includes everything, use the |
| \fBFindOpenSceneGraph\fP instead of the \fBFindosg*.cmake\fP modules. |
| .sp |
| Locate osgDB This module defines: |
| .INDENT 0.0 |
| .TP |
| .B \fBOSGDB_FOUND\fP |
| Was osgDB found? |
| .TP |
| .B \fBOSGDB_INCLUDE_DIR\fP |
| Where to find the headers |
| .TP |
| .B \fBOSGDB_LIBRARIES\fP |
| The libraries to link against for the osgDB |
| .TP |
| .B \fBOSGDB_LIBRARY\fP |
| The osgDB library |
| .TP |
| .B \fBOSGDB_LIBRARY_DEBUG\fP |
| The osgDB debug library |
| .UNINDENT |
| .sp |
| \fB$OSGDIR\fP is an environment variable that would correspond to: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| \&./configure \-\-prefix=$OSGDIR used in building osg. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindosgFX |
| .sp |
| This is part of the Findosg* suite used to find OpenSceneGraph |
| components. Each component is separate and you must opt in to each |
| module. You must also opt into OpenGL and OpenThreads (and Producer |
| if needed) as these modules won\(aqt do it for you. This is to allow you |
| control over your own system piece by piece in case you need to opt |
| out of certain components or change the Find behavior for a particular |
| module (perhaps because the default FindOpenGL.cmake module doesn\(aqt |
| work with your system as an example). If you want to use a more |
| convenient module that includes everything, use the |
| FindOpenSceneGraph.cmake instead of the Findosg*.cmake modules. |
| .sp |
| Locate osgFX This module defines |
| .sp |
| OSGFX_FOUND \- Was osgFX found? OSGFX_INCLUDE_DIR \- Where to find the |
| headers OSGFX_LIBRARIES \- The libraries to link against for the osgFX |
| (use this) |
| .sp |
| OSGFX_LIBRARY \- The osgFX library OSGFX_LIBRARY_DEBUG \- The osgFX |
| debug library |
| .sp |
| $OSGDIR is an environment variable that would correspond to the |
| \&./configure \-\-prefix=$OSGDIR used in building osg. |
| .sp |
| Created by Eric Wing. |
| .SS FindosgGA |
| .sp |
| This is part of the Findosg* suite used to find OpenSceneGraph |
| components. Each component is separate and you must opt in to each |
| module. You must also opt into OpenGL and OpenThreads (and Producer |
| if needed) as these modules won\(aqt do it for you. This is to allow you |
| control over your own system piece by piece in case you need to opt |
| out of certain components or change the Find behavior for a particular |
| module (perhaps because the default FindOpenGL.cmake module doesn\(aqt |
| work with your system as an example). If you want to use a more |
| convenient module that includes everything, use the |
| FindOpenSceneGraph.cmake instead of the Findosg*.cmake modules. |
| .sp |
| Locate osgGA This module defines |
| .sp |
| OSGGA_FOUND \- Was osgGA found? OSGGA_INCLUDE_DIR \- Where to find the |
| headers OSGGA_LIBRARIES \- The libraries to link against for the osgGA |
| (use this) |
| .sp |
| OSGGA_LIBRARY \- The osgGA library OSGGA_LIBRARY_DEBUG \- The osgGA |
| debug library |
| .sp |
| $OSGDIR is an environment variable that would correspond to the |
| \&./configure \-\-prefix=$OSGDIR used in building osg. |
| .sp |
| Created by Eric Wing. |
| .SS FindosgIntrospection |
| .sp |
| This is part of the Findosg* suite used to find OpenSceneGraph |
| components. Each component is separate and you must opt in to each |
| module. You must also opt into OpenGL and OpenThreads (and Producer |
| if needed) as these modules won\(aqt do it for you. This is to allow you |
| control over your own system piece by piece in case you need to opt |
| out of certain components or change the Find behavior for a particular |
| module (perhaps because the default FindOpenGL.cmake module doesn\(aqt |
| work with your system as an example). If you want to use a more |
| convenient module that includes everything, use the |
| FindOpenSceneGraph.cmake instead of the Findosg*.cmake modules. |
| .sp |
| Locate osgINTROSPECTION This module defines |
| .sp |
| OSGINTROSPECTION_FOUND \- Was osgIntrospection found? |
| OSGINTROSPECTION_INCLUDE_DIR \- Where to find the headers |
| OSGINTROSPECTION_LIBRARIES \- The libraries to link for |
| osgIntrospection (use this) |
| .sp |
| OSGINTROSPECTION_LIBRARY \- The osgIntrospection library |
| OSGINTROSPECTION_LIBRARY_DEBUG \- The osgIntrospection debug library |
| .sp |
| $OSGDIR is an environment variable that would correspond to the |
| \&./configure \-\-prefix=$OSGDIR used in building osg. |
| .sp |
| Created by Eric Wing. |
| .SS FindosgManipulator |
| .sp |
| This is part of the Findosg* suite used to find OpenSceneGraph |
| components. Each component is separate and you must opt in to each |
| module. You must also opt into OpenGL and OpenThreads (and Producer |
| if needed) as these modules won\(aqt do it for you. This is to allow you |
| control over your own system piece by piece in case you need to opt |
| out of certain components or change the Find behavior for a particular |
| module (perhaps because the default FindOpenGL.cmake module doesn\(aqt |
| work with your system as an example). If you want to use a more |
| convenient module that includes everything, use the |
| FindOpenSceneGraph.cmake instead of the Findosg*.cmake modules. |
| .sp |
| Locate osgManipulator This module defines |
| .sp |
| OSGMANIPULATOR_FOUND \- Was osgManipulator found? |
| OSGMANIPULATOR_INCLUDE_DIR \- Where to find the headers |
| OSGMANIPULATOR_LIBRARIES \- The libraries to link for osgManipulator |
| (use this) |
| .sp |
| OSGMANIPULATOR_LIBRARY \- The osgManipulator library |
| OSGMANIPULATOR_LIBRARY_DEBUG \- The osgManipulator debug library |
| .sp |
| $OSGDIR is an environment variable that would correspond to the |
| \&./configure \-\-prefix=$OSGDIR used in building osg. |
| .sp |
| Created by Eric Wing. |
| .SS FindosgParticle |
| .sp |
| This is part of the Findosg* suite used to find OpenSceneGraph |
| components. Each component is separate and you must opt in to each |
| module. You must also opt into OpenGL and OpenThreads (and Producer |
| if needed) as these modules won\(aqt do it for you. This is to allow you |
| control over your own system piece by piece in case you need to opt |
| out of certain components or change the Find behavior for a particular |
| module (perhaps because the default FindOpenGL.cmake module doesn\(aqt |
| work with your system as an example). If you want to use a more |
| convenient module that includes everything, use the |
| FindOpenSceneGraph.cmake instead of the Findosg*.cmake modules. |
| .sp |
| Locate osgParticle This module defines |
| .sp |
| OSGPARTICLE_FOUND \- Was osgParticle found? OSGPARTICLE_INCLUDE_DIR \- |
| Where to find the headers OSGPARTICLE_LIBRARIES \- The libraries to |
| link for osgParticle (use this) |
| .sp |
| OSGPARTICLE_LIBRARY \- The osgParticle library |
| OSGPARTICLE_LIBRARY_DEBUG \- The osgParticle debug library |
| .sp |
| $OSGDIR is an environment variable that would correspond to the |
| \&./configure \-\-prefix=$OSGDIR used in building osg. |
| .sp |
| Created by Eric Wing. |
| .SS FindosgPresentation |
| .sp |
| This is part of the Findosg* suite used to find OpenSceneGraph |
| components. Each component is separate and you must opt in to each |
| module. You must also opt into OpenGL and OpenThreads (and Producer |
| if needed) as these modules won\(aqt do it for you. This is to allow you |
| control over your own system piece by piece in case you need to opt |
| out of certain components or change the Find behavior for a particular |
| module (perhaps because the default FindOpenGL.cmake module doesn\(aqt |
| work with your system as an example). If you want to use a more |
| convenient module that includes everything, use the |
| FindOpenSceneGraph.cmake instead of the Findosg*.cmake modules. |
| .sp |
| Locate osgPresentation This module defines |
| .sp |
| OSGPRESENTATION_FOUND \- Was osgPresentation found? |
| OSGPRESENTATION_INCLUDE_DIR \- Where to find the headers |
| OSGPRESENTATION_LIBRARIES \- The libraries to link for osgPresentation |
| (use this) |
| .sp |
| OSGPRESENTATION_LIBRARY \- The osgPresentation library |
| OSGPRESENTATION_LIBRARY_DEBUG \- The osgPresentation debug library |
| .sp |
| $OSGDIR is an environment variable that would correspond to the |
| \&./configure \-\-prefix=$OSGDIR used in building osg. |
| .sp |
| Created by Eric Wing. Modified to work with osgPresentation by Robert |
| Osfield, January 2012. |
| .SS FindosgProducer |
| .sp |
| This is part of the Findosg* suite used to find OpenSceneGraph |
| components. Each component is separate and you must opt in to each |
| module. You must also opt into OpenGL and OpenThreads (and Producer |
| if needed) as these modules won\(aqt do it for you. This is to allow you |
| control over your own system piece by piece in case you need to opt |
| out of certain components or change the Find behavior for a particular |
| module (perhaps because the default FindOpenGL.cmake module doesn\(aqt |
| work with your system as an example). If you want to use a more |
| convenient module that includes everything, use the |
| FindOpenSceneGraph.cmake instead of the Findosg*.cmake modules. |
| .sp |
| Locate osgProducer This module defines |
| .sp |
| OSGPRODUCER_FOUND \- Was osgProducer found? OSGPRODUCER_INCLUDE_DIR \- |
| Where to find the headers OSGPRODUCER_LIBRARIES \- The libraries to |
| link for osgProducer (use this) |
| .sp |
| OSGPRODUCER_LIBRARY \- The osgProducer library |
| OSGPRODUCER_LIBRARY_DEBUG \- The osgProducer debug library |
| .sp |
| $OSGDIR is an environment variable that would correspond to the |
| \&./configure \-\-prefix=$OSGDIR used in building osg. |
| .sp |
| Created by Eric Wing. |
| .SS FindosgQt |
| .sp |
| This is part of the Findosg* suite used to find OpenSceneGraph |
| components. Each component is separate and you must opt in to each |
| module. You must also opt into OpenGL and OpenThreads (and Producer |
| if needed) as these modules won\(aqt do it for you. This is to allow you |
| control over your own system piece by piece in case you need to opt |
| out of certain components or change the Find behavior for a particular |
| module (perhaps because the default FindOpenGL.cmake module doesn\(aqt |
| work with your system as an example). If you want to use a more |
| convenient module that includes everything, use the |
| FindOpenSceneGraph.cmake instead of the Findosg*.cmake modules. |
| .sp |
| Locate osgQt This module defines |
| .sp |
| OSGQT_FOUND \- Was osgQt found? OSGQT_INCLUDE_DIR \- Where to find the |
| headers OSGQT_LIBRARIES \- The libraries to link for osgQt (use this) |
| .sp |
| OSGQT_LIBRARY \- The osgQt library OSGQT_LIBRARY_DEBUG \- The osgQt |
| debug library |
| .sp |
| $OSGDIR is an environment variable that would correspond to the |
| \&./configure \-\-prefix=$OSGDIR used in building osg. |
| .sp |
| Created by Eric Wing. Modified to work with osgQt by Robert Osfield, |
| January 2012. |
| .SS FindosgShadow |
| .sp |
| This is part of the Findosg* suite used to find OpenSceneGraph |
| components. Each component is separate and you must opt in to each |
| module. You must also opt into OpenGL and OpenThreads (and Producer |
| if needed) as these modules won\(aqt do it for you. This is to allow you |
| control over your own system piece by piece in case you need to opt |
| out of certain components or change the Find behavior for a particular |
| module (perhaps because the default FindOpenGL.cmake module doesn\(aqt |
| work with your system as an example). If you want to use a more |
| convenient module that includes everything, use the |
| FindOpenSceneGraph.cmake instead of the Findosg*.cmake modules. |
| .sp |
| Locate osgShadow This module defines |
| .sp |
| OSGSHADOW_FOUND \- Was osgShadow found? OSGSHADOW_INCLUDE_DIR \- Where |
| to find the headers OSGSHADOW_LIBRARIES \- The libraries to link for |
| osgShadow (use this) |
| .sp |
| OSGSHADOW_LIBRARY \- The osgShadow library OSGSHADOW_LIBRARY_DEBUG \- |
| The osgShadow debug library |
| .sp |
| $OSGDIR is an environment variable that would correspond to the |
| \&./configure \-\-prefix=$OSGDIR used in building osg. |
| .sp |
| Created by Eric Wing. |
| .SS FindosgSim |
| .sp |
| This is part of the Findosg* suite used to find OpenSceneGraph |
| components. Each component is separate and you must opt in to each |
| module. You must also opt into OpenGL and OpenThreads (and Producer |
| if needed) as these modules won\(aqt do it for you. This is to allow you |
| control over your own system piece by piece in case you need to opt |
| out of certain components or change the Find behavior for a particular |
| module (perhaps because the default FindOpenGL.cmake module doesn\(aqt |
| work with your system as an example). If you want to use a more |
| convenient module that includes everything, use the |
| FindOpenSceneGraph.cmake instead of the Findosg*.cmake modules. |
| .sp |
| Locate osgSim This module defines |
| .sp |
| OSGSIM_FOUND \- Was osgSim found? OSGSIM_INCLUDE_DIR \- Where to find |
| the headers OSGSIM_LIBRARIES \- The libraries to link for osgSim (use |
| this) |
| .sp |
| OSGSIM_LIBRARY \- The osgSim library OSGSIM_LIBRARY_DEBUG \- The osgSim |
| debug library |
| .sp |
| $OSGDIR is an environment variable that would correspond to the |
| \&./configure \-\-prefix=$OSGDIR used in building osg. |
| .sp |
| Created by Eric Wing. |
| .SS FindosgTerrain |
| .sp |
| This is part of the Findosg* suite used to find OpenSceneGraph |
| components. Each component is separate and you must opt in to each |
| module. You must also opt into OpenGL and OpenThreads (and Producer |
| if needed) as these modules won\(aqt do it for you. This is to allow you |
| control over your own system piece by piece in case you need to opt |
| out of certain components or change the Find behavior for a particular |
| module (perhaps because the default FindOpenGL.cmake module doesn\(aqt |
| work with your system as an example). If you want to use a more |
| convenient module that includes everything, use the |
| FindOpenSceneGraph.cmake instead of the Findosg*.cmake modules. |
| .sp |
| Locate osgTerrain This module defines |
| .sp |
| OSGTERRAIN_FOUND \- Was osgTerrain found? OSGTERRAIN_INCLUDE_DIR \- |
| Where to find the headers OSGTERRAIN_LIBRARIES \- The libraries to link |
| for osgTerrain (use this) |
| .sp |
| OSGTERRAIN_LIBRARY \- The osgTerrain library OSGTERRAIN_LIBRARY_DEBUG \- |
| The osgTerrain debug library |
| .sp |
| $OSGDIR is an environment variable that would correspond to the |
| \&./configure \-\-prefix=$OSGDIR used in building osg. |
| .sp |
| Created by Eric Wing. |
| .SS FindosgText |
| .sp |
| This is part of the Findosg* suite used to find OpenSceneGraph |
| components. Each component is separate and you must opt in to each |
| module. You must also opt into OpenGL and OpenThreads (and Producer |
| if needed) as these modules won\(aqt do it for you. This is to allow you |
| control over your own system piece by piece in case you need to opt |
| out of certain components or change the Find behavior for a particular |
| module (perhaps because the default FindOpenGL.cmake module doesn\(aqt |
| work with your system as an example). If you want to use a more |
| convenient module that includes everything, use the |
| FindOpenSceneGraph.cmake instead of the Findosg*.cmake modules. |
| .sp |
| Locate osgText This module defines |
| .sp |
| OSGTEXT_FOUND \- Was osgText found? OSGTEXT_INCLUDE_DIR \- Where to find |
| the headers OSGTEXT_LIBRARIES \- The libraries to link for osgText (use |
| this) |
| .sp |
| OSGTEXT_LIBRARY \- The osgText library OSGTEXT_LIBRARY_DEBUG \- The |
| osgText debug library |
| .sp |
| $OSGDIR is an environment variable that would correspond to the |
| \&./configure \-\-prefix=$OSGDIR used in building osg. |
| .sp |
| Created by Eric Wing. |
| .SS FindosgUtil |
| .sp |
| This is part of the Findosg* suite used to find OpenSceneGraph |
| components. Each component is separate and you must opt in to each |
| module. You must also opt into OpenGL and OpenThreads (and Producer |
| if needed) as these modules won\(aqt do it for you. This is to allow you |
| control over your own system piece by piece in case you need to opt |
| out of certain components or change the Find behavior for a particular |
| module (perhaps because the default FindOpenGL.cmake module doesn\(aqt |
| work with your system as an example). If you want to use a more |
| convenient module that includes everything, use the |
| FindOpenSceneGraph.cmake instead of the Findosg*.cmake modules. |
| .sp |
| Locate osgUtil This module defines |
| .sp |
| OSGUTIL_FOUND \- Was osgUtil found? OSGUTIL_INCLUDE_DIR \- Where to find |
| the headers OSGUTIL_LIBRARIES \- The libraries to link for osgUtil (use |
| this) |
| .sp |
| OSGUTIL_LIBRARY \- The osgUtil library OSGUTIL_LIBRARY_DEBUG \- The |
| osgUtil debug library |
| .sp |
| $OSGDIR is an environment variable that would correspond to the |
| \&./configure \-\-prefix=$OSGDIR used in building osg. |
| .sp |
| Created by Eric Wing. |
| .SS FindosgViewer |
| .sp |
| This is part of the Findosg* suite used to find OpenSceneGraph |
| components. Each component is separate and you must opt in to each |
| module. You must also opt into OpenGL and OpenThreads (and Producer |
| if needed) as these modules won\(aqt do it for you. This is to allow you |
| control over your own system piece by piece in case you need to opt |
| out of certain components or change the Find behavior for a particular |
| module (perhaps because the default FindOpenGL.cmake module doesn\(aqt |
| work with your system as an example). If you want to use a more |
| convenient module that includes everything, use the |
| FindOpenSceneGraph.cmake instead of the Findosg*.cmake modules. |
| .sp |
| Locate osgViewer This module defines |
| .sp |
| OSGVIEWER_FOUND \- Was osgViewer found? OSGVIEWER_INCLUDE_DIR \- Where |
| to find the headers OSGVIEWER_LIBRARIES \- The libraries to link for |
| osgViewer (use this) |
| .sp |
| OSGVIEWER_LIBRARY \- The osgViewer library OSGVIEWER_LIBRARY_DEBUG \- |
| The osgViewer debug library |
| .sp |
| $OSGDIR is an environment variable that would correspond to the |
| \&./configure \-\-prefix=$OSGDIR used in building osg. |
| .sp |
| Created by Eric Wing. |
| .SS FindosgVolume |
| .sp |
| This is part of the Findosg* suite used to find OpenSceneGraph |
| components. Each component is separate and you must opt in to each |
| module. You must also opt into OpenGL and OpenThreads (and Producer |
| if needed) as these modules won\(aqt do it for you. This is to allow you |
| control over your own system piece by piece in case you need to opt |
| out of certain components or change the Find behavior for a particular |
| module (perhaps because the default FindOpenGL.cmake module doesn\(aqt |
| work with your system as an example). If you want to use a more |
| convenient module that includes everything, use the |
| FindOpenSceneGraph.cmake instead of the Findosg*.cmake modules. |
| .sp |
| Locate osgVolume This module defines |
| .sp |
| OSGVOLUME_FOUND \- Was osgVolume found? OSGVOLUME_INCLUDE_DIR \- Where |
| to find the headers OSGVOLUME_LIBRARIES \- The libraries to link for |
| osgVolume (use this) |
| .sp |
| OSGVOLUME_LIBRARY \- The osgVolume library OSGVOLUME_LIBRARY_DEBUG \- |
| The osgVolume debug library |
| .sp |
| $OSGDIR is an environment variable that would correspond to the |
| \&./configure \-\-prefix=$OSGDIR used in building osg. |
| .sp |
| Created by Eric Wing. |
| .SS FindosgWidget |
| .sp |
| This is part of the Findosg* suite used to find OpenSceneGraph |
| components. Each component is separate and you must opt in to each |
| module. You must also opt into OpenGL and OpenThreads (and Producer |
| if needed) as these modules won\(aqt do it for you. This is to allow you |
| control over your own system piece by piece in case you need to opt |
| out of certain components or change the Find behavior for a particular |
| module (perhaps because the default FindOpenGL.cmake module doesn\(aqt |
| work with your system as an example). If you want to use a more |
| convenient module that includes everything, use the |
| FindOpenSceneGraph.cmake instead of the Findosg*.cmake modules. |
| .sp |
| Locate osgWidget This module defines |
| .sp |
| OSGWIDGET_FOUND \- Was osgWidget found? OSGWIDGET_INCLUDE_DIR \- Where |
| to find the headers OSGWIDGET_LIBRARIES \- The libraries to link for |
| osgWidget (use this) |
| .sp |
| OSGWIDGET_LIBRARY \- The osgWidget library OSGWIDGET_LIBRARY_DEBUG \- |
| The osgWidget debug library |
| .sp |
| $OSGDIR is an environment variable that would correspond to the |
| \&./configure \-\-prefix=$OSGDIR used in building osg. |
| .sp |
| FindosgWidget.cmake tweaked from Findosg* suite as created by Eric |
| Wing. |
| .SS FindPatch |
| .sp |
| New in version 3.10. |
| |
| .sp |
| The module defines the following variables: |
| .INDENT 0.0 |
| .TP |
| .B \fBPatch_EXECUTABLE\fP |
| Path to patch command\-line executable. |
| .TP |
| .B \fBPatch_FOUND\fP |
| True if the patch command\-line executable was found. |
| .UNINDENT |
| .sp |
| The following \fBIMPORTED\fP targets are also defined: |
| .INDENT 0.0 |
| .TP |
| .B \fBPatch::patch\fP |
| The command\-line executable. |
| .UNINDENT |
| .sp |
| Example usage: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_package(Patch) |
| if(Patch_FOUND) |
| message("Patch found: ${Patch_EXECUTABLE}") |
| endif() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindPerl |
| .sp |
| Find perl |
| .sp |
| this module looks for Perl |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| PERL_EXECUTABLE \- the full path to perl |
| PERL_FOUND \- If false, don\(aqt attempt to use perl. |
| PERL_VERSION_STRING \- version of perl found (since CMake 2.8.8) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindPerlLibs |
| .sp |
| Find Perl libraries |
| .sp |
| This module finds if PERL is installed and determines where the |
| include files and libraries are. It also determines what the name of |
| the library is. This code sets the following variables: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| PERLLIBS_FOUND = True if perl.h & libperl were found |
| PERL_INCLUDE_PATH = path to where perl.h is found |
| PERL_LIBRARY = path to libperl |
| PERL_EXECUTABLE = full path to the perl binary |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The minimum required version of Perl can be specified using the |
| standard syntax, e.g. find_package(PerlLibs 6.0) |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| The following variables are also available if needed |
| (introduced after CMake 2.6.4) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| PERL_SITESEARCH = path to the sitesearch install dir (\-V:installsitesearch) |
| PERL_SITEARCH = path to the sitelib install directory (\-V:installsitearch) |
| PERL_SITELIB = path to the sitelib install directory (\-V:installsitelib) |
| PERL_VENDORARCH = path to the vendor arch install directory (\-V:installvendorarch) |
| PERL_VENDORLIB = path to the vendor lib install directory (\-V:installvendorlib) |
| PERL_ARCHLIB = path to the core arch lib install directory (\-V:archlib) |
| PERL_PRIVLIB = path to the core priv lib install directory (\-V:privlib) |
| PERL_UPDATE_ARCHLIB = path to the update arch lib install directory (\-V:installarchlib) |
| PERL_UPDATE_PRIVLIB = path to the update priv lib install directory (\-V:installprivlib) |
| PERL_EXTRA_C_FLAGS = Compilation flags used to build perl |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindPHP4 |
| .sp |
| Find PHP4 |
| .sp |
| This module finds if PHP4 is installed and determines where the |
| include files and libraries are. It also determines what the name of |
| the library is. This code sets the following variables: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| PHP4_INCLUDE_PATH = path to where php.h can be found |
| PHP4_EXECUTABLE = full path to the php4 binary |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindPhysFS |
| .sp |
| Locate PhysFS library This module defines PHYSFS_LIBRARY, the name of |
| the library to link against PHYSFS_FOUND, if false, do not try to link |
| to PHYSFS PHYSFS_INCLUDE_DIR, where to find physfs.h |
| .sp |
| $PHYSFSDIR is an environment variable that would correspond to the |
| \&./configure \-\-prefix=$PHYSFSDIR used in building PHYSFS. |
| .sp |
| Created by Eric Wing. |
| .SS FindPike |
| .sp |
| Find Pike |
| .sp |
| This module finds if PIKE is installed and determines where the |
| include files and libraries are. It also determines what the name of |
| the library is. This code sets the following variables: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| PIKE_INCLUDE_PATH = path to where program.h is found |
| PIKE_EXECUTABLE = full path to the pike binary |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindPkgConfig |
| .sp |
| A \fBpkg\-config\fP module for CMake. |
| .sp |
| Finds the \fBpkg\-config\fP executable and adds the \fI\%pkg_get_variable()\fP, |
| \fI\%pkg_check_modules()\fP and \fI\%pkg_search_module()\fP commands. The |
| following variables will also be set: |
| .INDENT 0.0 |
| .TP |
| .B \fBPKG_CONFIG_FOUND\fP |
| True if a pkg\-config executable was found. |
| .TP |
| .B \fBPKG_CONFIG_VERSION_STRING\fP |
| New in version 2.8.8. |
| |
| .sp |
| The version of pkg\-config that was found. |
| .TP |
| .B \fBPKG_CONFIG_EXECUTABLE\fP |
| The pathname of the pkg\-config program. |
| .TP |
| .B \fBPKG_CONFIG_ARGN\fP |
| New in version 3.22. |
| |
| .sp |
| A list of arguments to pass to pkg\-config. |
| .UNINDENT |
| .sp |
| Both \fBPKG_CONFIG_EXECUTABLE\fP and \fBPKG_CONFIG_ARGN\fP are initialized by the |
| module, but may be overridden by the user. See \fI\%Variables Affecting Behavior\fP |
| for how these variables are initialized. |
| .INDENT 0.0 |
| .TP |
| .B pkg_check_modules |
| Checks for all the given modules, setting a variety of result variables in |
| the calling scope. |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| pkg_check_modules(<prefix> |
| [REQUIRED] [QUIET] |
| [NO_CMAKE_PATH] |
| [NO_CMAKE_ENVIRONMENT_PATH] |
| [IMPORTED_TARGET [GLOBAL]] |
| <moduleSpec> [<moduleSpec>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| When the \fBREQUIRED\fP argument is given, the command will fail with an error |
| if module(s) could not be found. |
| .sp |
| When the \fBQUIET\fP argument is given, no status messages will be printed. |
| .sp |
| New in version 3.1: The \fBCMAKE_PREFIX_PATH\fP, |
| \fBCMAKE_FRAMEWORK_PATH\fP, and \fBCMAKE_APPBUNDLE_PATH\fP cache |
| and environment variables will be added to the \fBpkg\-config\fP search path. |
| The \fBNO_CMAKE_PATH\fP and \fBNO_CMAKE_ENVIRONMENT_PATH\fP arguments |
| disable this behavior for the cache variables and environment variables |
| respectively. |
| The \fI\%PKG_CONFIG_USE_CMAKE_PREFIX_PATH\fP variable set to \fBFALSE\fP |
| disables this behavior globally. |
| |
| .sp |
| New in version 3.6: The \fBIMPORTED_TARGET\fP argument will create an imported target named |
| \fBPkgConfig::<prefix>\fP that can be passed directly as an argument to |
| \fBtarget_link_libraries()\fP\&. |
| |
| .sp |
| New in version 3.13: The \fBGLOBAL\fP argument will make the |
| imported target available in global scope. |
| |
| .sp |
| New in version 3.15: Non\-library linker options reported by \fBpkg\-config\fP are stored in the |
| \fBINTERFACE_LINK_OPTIONS\fP target property. |
| |
| .sp |
| Changed in version 3.18: Include directories specified with \fB\-isystem\fP are stored in the |
| \fBINTERFACE_INCLUDE_DIRECTORIES\fP target property. Previous |
| versions of CMake left them in the \fBINTERFACE_COMPILE_OPTIONS\fP |
| property. |
| |
| .sp |
| Each \fB<moduleSpec>\fP can be either a bare module name or it can be a |
| module name with a version constraint (operators \fB=\fP, \fB<\fP, \fB>\fP, |
| \fB<=\fP and \fB>=\fP are supported). The following are examples for a module |
| named \fBfoo\fP with various constraints: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| \fBfoo\fP matches any version. |
| .IP \(bu 2 |
| \fBfoo<2\fP only matches versions before 2. |
| .IP \(bu 2 |
| \fBfoo>=3.1\fP matches any version from 3.1 or later. |
| .IP \(bu 2 |
| \fBfoo=1.2.3\fP requires that foo must be exactly version 1.2.3. |
| .UNINDENT |
| .sp |
| The following variables may be set upon return. Two sets of values exist: |
| One for the common case (\fB<XXX> = <prefix>\fP) and another for the |
| information \fBpkg\-config\fP provides when called with the \fB\-\-static\fP |
| option (\fB<XXX> = <prefix>_STATIC\fP). |
| .INDENT 7.0 |
| .TP |
| .B \fB<XXX>_FOUND\fP |
| set to 1 if module(s) exist |
| .TP |
| .B \fB<XXX>_LIBRARIES\fP |
| only the libraries (without the \(aq\-l\(aq) |
| .TP |
| .B \fB<XXX>_LINK_LIBRARIES\fP |
| the libraries and their absolute paths |
| .TP |
| .B \fB<XXX>_LIBRARY_DIRS\fP |
| the paths of the libraries (without the \(aq\-L\(aq) |
| .TP |
| .B \fB<XXX>_LDFLAGS\fP |
| all required linker flags |
| .TP |
| .B \fB<XXX>_LDFLAGS_OTHER\fP |
| all other linker flags |
| .TP |
| .B \fB<XXX>_INCLUDE_DIRS\fP |
| the \(aq\-I\(aq preprocessor flags (without the \(aq\-I\(aq) |
| .TP |
| .B \fB<XXX>_CFLAGS\fP |
| all required cflags |
| .TP |
| .B \fB<XXX>_CFLAGS_OTHER\fP |
| the other compiler flags |
| .UNINDENT |
| .sp |
| All but \fB<XXX>_FOUND\fP may be a ;\-list if the |
| associated variable returned from \fBpkg\-config\fP has multiple values. |
| .sp |
| Changed in version 3.18: Include directories specified with \fB\-isystem\fP are stored in the |
| \fB<XXX>_INCLUDE_DIRS\fP variable. Previous versions of CMake left them |
| in \fB<XXX>_CFLAGS_OTHER\fP\&. |
| |
| .sp |
| There are some special variables whose prefix depends on the number of |
| \fB<moduleSpec>\fP given. When there is only one \fB<moduleSpec>\fP, |
| \fB<YYY>\fP will simply be \fB<prefix>\fP, but if two or more \fB<moduleSpec>\fP |
| items are given, \fB<YYY>\fP will be \fB<prefix>_<moduleName>\fP\&. |
| .INDENT 7.0 |
| .TP |
| .B \fB<YYY>_VERSION\fP |
| version of the module |
| .TP |
| .B \fB<YYY>_PREFIX\fP |
| prefix directory of the module |
| .TP |
| .B \fB<YYY>_INCLUDEDIR\fP |
| include directory of the module |
| .TP |
| .B \fB<YYY>_LIBDIR\fP |
| lib directory of the module |
| .UNINDENT |
| .sp |
| Changed in version 3.8: For any given \fB<prefix>\fP, \fBpkg_check_modules()\fP can be called multiple |
| times with different parameters. Previous versions of CMake cached and |
| returned the first successful result. |
| |
| .sp |
| Changed in version 3.16: If a full path to the found library can\(aqt be determined, but it\(aqs still |
| visible to the linker, pass it through as \fB\-l<name>\fP\&. Previous versions |
| of CMake failed in this case. |
| |
| .sp |
| Examples: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| pkg_check_modules (GLIB2 glib\-2.0) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Looks for any version of glib2. If found, the output variable |
| \fBGLIB2_VERSION\fP will hold the actual version found. |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| pkg_check_modules (GLIB2 glib\-2.0>=2.10) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Looks for at least version 2.10 of glib2. If found, the output variable |
| \fBGLIB2_VERSION\fP will hold the actual version found. |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| pkg_check_modules (FOO glib\-2.0>=2.10 gtk+\-2.0) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Looks for both glib2\-2.0 (at least version 2.10) and any version of |
| gtk2+\-2.0. Only if both are found will \fBFOO\fP be considered found. |
| The \fBFOO_glib\-2.0_VERSION\fP and \fBFOO_gtk+\-2.0_VERSION\fP variables will be |
| set to their respective found module versions. |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| pkg_check_modules (XRENDER REQUIRED xrender) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Requires any version of \fBxrender\fP\&. Example output variables set by a |
| successful call: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| XRENDER_LIBRARIES=Xrender;X11 |
| XRENDER_STATIC_LIBRARIES=Xrender;X11;pthread;Xau;Xdmcp |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B pkg_search_module |
| The behavior of this command is the same as \fI\%pkg_check_modules()\fP, |
| except that rather than checking for all the specified modules, it searches |
| for just the first successful match. |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| pkg_search_module(<prefix> |
| [REQUIRED] [QUIET] |
| [NO_CMAKE_PATH] |
| [NO_CMAKE_ENVIRONMENT_PATH] |
| [IMPORTED_TARGET [GLOBAL]] |
| <moduleSpec> [<moduleSpec>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.16: If a module is found, the \fB<prefix>_MODULE_NAME\fP variable will contain the |
| name of the matching module. This variable can be used if you need to run |
| \fI\%pkg_get_variable()\fP\&. |
| |
| .sp |
| Example: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| pkg_search_module (BAR libxml\-2.0 libxml2 libxml>=2) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B pkg_get_variable |
| New in version 3.4. |
| |
| .sp |
| Retrieves the value of a pkg\-config variable \fBvarName\fP and stores it in the |
| result variable \fBresultVar\fP in the calling scope. |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| pkg_get_variable(<resultVar> <moduleName> <varName>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| If \fBpkg\-config\fP returns multiple values for the specified variable, |
| \fBresultVar\fP will contain a ;\-list\&. |
| .sp |
| For example: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| pkg_get_variable(GI_GIRDIR gobject\-introspection\-1.0 girdir) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .SS Variables Affecting Behavior |
| .INDENT 0.0 |
| .TP |
| .B PKG_CONFIG_EXECUTABLE |
| This cache variable can be set to the path of the pkg\-config executable. |
| \fBfind_program()\fP is called internally by the module with this |
| variable. |
| .sp |
| New in version 3.1: The \fBPKG_CONFIG\fP environment variable can be used as a hint if |
| \fBPKG_CONFIG_EXECUTABLE\fP has not yet been set. |
| |
| .sp |
| Changed in version 3.22: If the \fBPKG_CONFIG\fP environment variable is set, only the first |
| argument is taken from it when using it as a hint. |
| |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B PKG_CONFIG_ARGN |
| New in version 3.22. |
| |
| .sp |
| This cache variable can be set to a list of arguments to additionally pass |
| to pkg\-config if needed. If not provided, it will be initialized from the |
| \fBPKG_CONFIG\fP environment variable, if set. The first argument in that |
| environment variable is assumed to be the pkg\-config program, while all |
| remaining arguments after that are used to initialize \fBPKG_CONFIG_ARGN\fP\&. |
| If no such environment variable is defined, \fBPKG_CONFIG_ARGN\fP is |
| initialized to an empty string. The module does not update the variable once |
| it has been set in the cache. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B PKG_CONFIG_USE_CMAKE_PREFIX_PATH |
| New in version 3.1. |
| |
| .sp |
| Specifies whether \fI\%pkg_check_modules()\fP and |
| \fI\%pkg_search_module()\fP should add the paths in the |
| \fBCMAKE_PREFIX_PATH\fP, \fBCMAKE_FRAMEWORK_PATH\fP and |
| \fBCMAKE_APPBUNDLE_PATH\fP cache and environment variables to the |
| \fBpkg\-config\fP search path. |
| .sp |
| If this variable is not set, this behavior is enabled by default if |
| \fBCMAKE_MINIMUM_REQUIRED_VERSION\fP is 3.1 or later, disabled |
| otherwise. |
| .UNINDENT |
| .SS FindPNG |
| .sp |
| Find libpng, the official reference library for the PNG image format. |
| .SS Imported targets |
| .sp |
| New in version 3.5. |
| |
| .sp |
| This module defines the following \fBIMPORTED\fP target: |
| .INDENT 0.0 |
| .TP |
| .B \fBPNG::PNG\fP |
| The libpng library, if found. |
| .UNINDENT |
| .SS Result variables |
| .sp |
| This module will set the following variables in your project: |
| .INDENT 0.0 |
| .TP |
| .B \fBPNG_INCLUDE_DIRS\fP |
| where to find png.h, etc. |
| .TP |
| .B \fBPNG_LIBRARIES\fP |
| the libraries to link against to use PNG. |
| .TP |
| .B \fBPNG_DEFINITIONS\fP |
| You should add_definitions(${PNG_DEFINITIONS}) before compiling code |
| that includes png library files. |
| .TP |
| .B \fBPNG_FOUND\fP |
| If false, do not try to use PNG. |
| .TP |
| .B \fBPNG_VERSION_STRING\fP |
| the version of the PNG library found (since CMake 2.8.8) |
| .UNINDENT |
| .SS Obsolete variables |
| .sp |
| The following variables may also be set, for backwards compatibility: |
| .INDENT 0.0 |
| .TP |
| .B \fBPNG_LIBRARY\fP |
| where to find the PNG library. |
| .TP |
| .B \fBPNG_INCLUDE_DIR\fP |
| where to find the PNG headers (same as PNG_INCLUDE_DIRS) |
| .UNINDENT |
| .sp |
| Since PNG depends on the ZLib compression library, none of the above |
| will be defined unless ZLib can be found. |
| .SS FindPostgreSQL |
| .sp |
| Find the PostgreSQL installation. |
| .SS IMPORTED Targets |
| .sp |
| New in version 3.14. |
| |
| .sp |
| This module defines \fBIMPORTED\fP target \fBPostgreSQL::PostgreSQL\fP |
| if PostgreSQL has been found. |
| .SS Result Variables |
| .sp |
| This module will set the following variables in your project: |
| .INDENT 0.0 |
| .TP |
| .B \fBPostgreSQL_FOUND\fP |
| True if PostgreSQL is found. |
| .TP |
| .B \fBPostgreSQL_LIBRARIES\fP |
| the PostgreSQL libraries needed for linking |
| .TP |
| .B \fBPostgreSQL_INCLUDE_DIRS\fP |
| the directories of the PostgreSQL headers |
| .TP |
| .B \fBPostgreSQL_LIBRARY_DIRS\fP |
| the link directories for PostgreSQL libraries |
| .TP |
| .B \fBPostgreSQL_VERSION_STRING\fP |
| the version of PostgreSQL found |
| .TP |
| .B \fBPostgreSQL_TYPE_INCLUDE_DIR\fP |
| the directories of the PostgreSQL server headers |
| .UNINDENT |
| .SS Components |
| .sp |
| This module contains additional \fBServer\fP component, that forcibly checks |
| for the presence of server headers. Note that \fBPostgreSQL_TYPE_INCLUDE_DIR\fP |
| is set regardless of the presence of the \fBServer\fP component in find_package call. |
| .SS FindProducer |
| .sp |
| Though Producer isn\(aqt directly part of OpenSceneGraph, its primary |
| user is OSG so I consider this part of the Findosg* suite used to find |
| OpenSceneGraph components. You\(aqll notice that I accept OSGDIR as an |
| environment path. |
| .sp |
| Each component is separate and you must opt in to each module. You |
| must also opt into OpenGL (and OpenThreads?) as these modules won\(aqt do |
| it for you. This is to allow you control over your own system piece |
| by piece in case you need to opt out of certain components or change |
| the Find behavior for a particular module (perhaps because the default |
| FindOpenGL.cmake module doesn\(aqt work with your system as an example). |
| If you want to use a more convenient module that includes everything, |
| use the FindOpenSceneGraph.cmake instead of the Findosg*.cmake |
| modules. |
| .sp |
| Locate Producer This module defines PRODUCER_LIBRARY PRODUCER_FOUND, |
| if false, do not try to link to Producer PRODUCER_INCLUDE_DIR, where |
| to find the headers |
| .sp |
| $PRODUCER_DIR is an environment variable that would correspond to the |
| \&./configure \-\-prefix=$PRODUCER_DIR used in building osg. |
| .sp |
| Created by Eric Wing. |
| .SS FindProtobuf |
| .sp |
| Locate and configure the Google Protocol Buffers library. |
| .sp |
| New in version 3.6: Support for \fBfind_package()\fP version checks. |
| |
| .sp |
| Changed in version 3.6: All input and output variables use the \fBProtobuf_\fP prefix. |
| Variables with \fBPROTOBUF_\fP prefix are still supported for compatibility. |
| |
| .sp |
| The following variables can be set and are optional: |
| .INDENT 0.0 |
| .TP |
| .B \fBProtobuf_SRC_ROOT_FOLDER\fP |
| When compiling with MSVC, if this cache variable is set |
| the protobuf\-default VS project build locations |
| (vsprojects/Debug and vsprojects/Release |
| or vsprojects/x64/Debug and vsprojects/x64/Release) |
| will be searched for libraries and binaries. |
| .TP |
| .B \fBProtobuf_IMPORT_DIRS\fP |
| List of additional directories to be searched for |
| imported .proto files. |
| .TP |
| .B \fBProtobuf_DEBUG\fP |
| New in version 3.6. |
| |
| .sp |
| Show debug messages. |
| .TP |
| .B \fBProtobuf_USE_STATIC_LIBS\fP |
| New in version 3.9. |
| |
| .sp |
| Set to ON to force the use of the static libraries. |
| Default is OFF. |
| .UNINDENT |
| .sp |
| Defines the following variables: |
| .INDENT 0.0 |
| .TP |
| .B \fBProtobuf_FOUND\fP |
| Found the Google Protocol Buffers library |
| (libprotobuf & header files) |
| .TP |
| .B \fBProtobuf_VERSION\fP |
| New in version 3.6. |
| |
| .sp |
| Version of package found. |
| .TP |
| .B \fBProtobuf_INCLUDE_DIRS\fP |
| Include directories for Google Protocol Buffers |
| .TP |
| .B \fBProtobuf_LIBRARIES\fP |
| The protobuf libraries |
| .TP |
| .B \fBProtobuf_PROTOC_LIBRARIES\fP |
| The protoc libraries |
| .TP |
| .B \fBProtobuf_LITE_LIBRARIES\fP |
| The protobuf\-lite libraries |
| .UNINDENT |
| .sp |
| New in version 3.9: The following \fBIMPORTED\fP targets are also defined: |
| |
| .INDENT 0.0 |
| .TP |
| .B \fBprotobuf::libprotobuf\fP |
| The protobuf library. |
| .TP |
| .B \fBprotobuf::libprotobuf\-lite\fP |
| The protobuf lite library. |
| .TP |
| .B \fBprotobuf::libprotoc\fP |
| The protoc library. |
| .TP |
| .B \fBprotobuf::protoc\fP |
| New in version 3.10: The protoc compiler. |
| |
| .UNINDENT |
| .sp |
| The following cache variables are also available to set or use: |
| .INDENT 0.0 |
| .TP |
| .B \fBProtobuf_LIBRARY\fP |
| The protobuf library |
| .TP |
| .B \fBProtobuf_PROTOC_LIBRARY\fP |
| The protoc library |
| .TP |
| .B \fBProtobuf_INCLUDE_DIR\fP |
| The include directory for protocol buffers |
| .TP |
| .B \fBProtobuf_PROTOC_EXECUTABLE\fP |
| The protoc compiler |
| .TP |
| .B \fBProtobuf_LIBRARY_DEBUG\fP |
| The protobuf library (debug) |
| .TP |
| .B \fBProtobuf_PROTOC_LIBRARY_DEBUG\fP |
| The protoc library (debug) |
| .TP |
| .B \fBProtobuf_LITE_LIBRARY\fP |
| The protobuf lite library |
| .TP |
| .B \fBProtobuf_LITE_LIBRARY_DEBUG\fP |
| The protobuf lite library (debug) |
| .UNINDENT |
| .sp |
| Example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_package(Protobuf REQUIRED) |
| include_directories(${Protobuf_INCLUDE_DIRS}) |
| include_directories(${CMAKE_CURRENT_BINARY_DIR}) |
| protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS foo.proto) |
| protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS EXPORT_MACRO DLL_EXPORT foo.proto) |
| protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS DESCRIPTORS PROTO_DESCS foo.proto) |
| protobuf_generate_python(PROTO_PY foo.proto) |
| add_executable(bar bar.cc ${PROTO_SRCS} ${PROTO_HDRS}) |
| target_link_libraries(bar ${Protobuf_LIBRARIES}) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| The \fBprotobuf_generate_cpp\fP and \fBprotobuf_generate_python\fP |
| functions and \fBadd_executable()\fP or \fBadd_library()\fP |
| calls only work properly within the same directory. |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B protobuf_generate_cpp |
| Add custom commands to process \fB\&.proto\fP files to C++: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| protobuf_generate_cpp (<SRCS> <HDRS> |
| [DESCRIPTORS <DESC>] [EXPORT_MACRO <MACRO>] [<ARGN>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 7.0 |
| .TP |
| .B \fBSRCS\fP |
| Variable to define with autogenerated source files |
| .TP |
| .B \fBHDRS\fP |
| Variable to define with autogenerated header files |
| .TP |
| .B \fBDESCRIPTORS\fP |
| New in version 3.10: Variable to define with autogenerated descriptor files, if requested. |
| |
| .TP |
| .B \fBEXPORT_MACRO\fP |
| is a macro which should expand to \fB__declspec(dllexport)\fP or |
| \fB__declspec(dllimport)\fP depending on what is being compiled. |
| .TP |
| .B \fBARGN\fP |
| \fB\&.proto\fP files |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B protobuf_generate_python |
| New in version 3.4. |
| |
| .sp |
| Add custom commands to process \fB\&.proto\fP files to Python: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| protobuf_generate_python (<PY> [<ARGN>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 7.0 |
| .TP |
| .B \fBPY\fP |
| Variable to define with autogenerated Python files |
| .TP |
| .B \fBARGN\fP |
| \fB\&.proto\fP files |
| .UNINDENT |
| .UNINDENT |
| .SS FindPython |
| .sp |
| New in version 3.12. |
| |
| .sp |
| Find Python interpreter, compiler and development environment (include |
| directories and libraries). |
| .sp |
| New in version 3.19: When a version is requested, it can be specified as a simple value or as a |
| range. For a detailed description of version range usage and capabilities, |
| refer to the \fBfind_package()\fP command. |
| |
| .sp |
| The following components are supported: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBInterpreter\fP: search for Python interpreter. |
| .IP \(bu 2 |
| \fBCompiler\fP: search for Python compiler. Only offered by IronPython. |
| .IP \(bu 2 |
| \fBDevelopment\fP: search for development artifacts (include directories and |
| libraries). |
| .sp |
| New in version 3.18: This component includes two sub\-components which can be specified |
| independently: |
| .INDENT 2.0 |
| .IP \(bu 2 |
| \fBDevelopment.Module\fP: search for artifacts for Python module |
| developments. |
| .IP \(bu 2 |
| \fBDevelopment.Embed\fP: search for artifacts for Python embedding |
| developments. |
| .UNINDENT |
| |
| .IP \(bu 2 |
| \fBNumPy\fP: search for NumPy include directories. |
| .UNINDENT |
| .sp |
| New in version 3.14: Added the \fBNumPy\fP component. |
| |
| .sp |
| If no \fBCOMPONENTS\fP are specified, \fBInterpreter\fP is assumed. |
| .sp |
| If component \fBDevelopment\fP is specified, it implies sub\-components |
| \fBDevelopment.Module\fP and \fBDevelopment.Embed\fP\&. |
| .sp |
| To ensure consistent versions between components \fBInterpreter\fP, \fBCompiler\fP, |
| \fBDevelopment\fP (or one of its sub\-components) and \fBNumPy\fP, specify all |
| components at the same time: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_package (Python COMPONENTS Interpreter Development) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This module looks preferably for version 3 of Python. If not found, version 2 |
| is searched. |
| To manage concurrent versions 3 and 2 of Python, use \fBFindPython3\fP and |
| \fBFindPython2\fP modules rather than this one. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| If components \fBInterpreter\fP and \fBDevelopment\fP (or one of its |
| sub\-components) are both specified, this module search only for interpreter |
| with same platform architecture as the one defined by \fBCMake\fP |
| configuration. This constraint does not apply if only \fBInterpreter\fP |
| component is specified. |
| .UNINDENT |
| .UNINDENT |
| .SS Imported Targets |
| .sp |
| This module defines the following Imported Targets: |
| .sp |
| Changed in version 3.14: Imported Targets are only created when |
| \fBCMAKE_ROLE\fP is \fBPROJECT\fP\&. |
| |
| .INDENT 0.0 |
| .TP |
| .B \fBPython::Interpreter\fP |
| Python interpreter. Target defined if component \fBInterpreter\fP is found. |
| .TP |
| .B \fBPython::Compiler\fP |
| Python compiler. Target defined if component \fBCompiler\fP is found. |
| .TP |
| .B \fBPython::Module\fP |
| New in version 3.15. |
| |
| .sp |
| Python library for Python module. Target defined if component |
| \fBDevelopment.Module\fP is found. |
| .TP |
| .B \fBPython::Python\fP |
| Python library for Python embedding. Target defined if component |
| \fBDevelopment.Embed\fP is found. |
| .TP |
| .B \fBPython::NumPy\fP |
| New in version 3.14. |
| |
| .sp |
| NumPy Python library. Target defined if component \fBNumPy\fP is found. |
| .UNINDENT |
| .SS Result Variables |
| .sp |
| This module will set the following variables in your project |
| (see Standard Variable Names): |
| .INDENT 0.0 |
| .TP |
| .B \fBPython_FOUND\fP |
| System has the Python requested components. |
| .TP |
| .B \fBPython_Interpreter_FOUND\fP |
| System has the Python interpreter. |
| .TP |
| .B \fBPython_EXECUTABLE\fP |
| Path to the Python interpreter. |
| .TP |
| .B \fBPython_INTERPRETER_ID\fP |
| .INDENT 7.0 |
| .TP |
| .B A short string unique to the interpreter. Possible values include: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| Python |
| .IP \(bu 2 |
| ActivePython |
| .IP \(bu 2 |
| Anaconda |
| .IP \(bu 2 |
| Canopy |
| .IP \(bu 2 |
| IronPython |
| .IP \(bu 2 |
| PyPy |
| .UNINDENT |
| .UNINDENT |
| .TP |
| .B \fBPython_STDLIB\fP |
| Standard platform independent installation directory. |
| .sp |
| Information returned by |
| \fBdistutils.sysconfig.get_python_lib(plat_specific=False,standard_lib=True)\fP |
| or else \fBsysconfig.get_path(\(aqstdlib\(aq)\fP\&. |
| .TP |
| .B \fBPython_STDARCH\fP |
| Standard platform dependent installation directory. |
| .sp |
| Information returned by |
| \fBdistutils.sysconfig.get_python_lib(plat_specific=True,standard_lib=True)\fP |
| or else \fBsysconfig.get_path(\(aqplatstdlib\(aq)\fP\&. |
| .TP |
| .B \fBPython_SITELIB\fP |
| Third\-party platform independent installation directory. |
| .sp |
| Information returned by |
| \fBdistutils.sysconfig.get_python_lib(plat_specific=False,standard_lib=False)\fP |
| or else \fBsysconfig.get_path(\(aqpurelib\(aq)\fP\&. |
| .TP |
| .B \fBPython_SITEARCH\fP |
| Third\-party platform dependent installation directory. |
| .sp |
| Information returned by |
| \fBdistutils.sysconfig.get_python_lib(plat_specific=True,standard_lib=False)\fP |
| or else \fBsysconfig.get_path(\(aqplatlib\(aq)\fP\&. |
| .TP |
| .B \fBPython_SOABI\fP |
| New in version 3.17. |
| |
| .sp |
| Extension suffix for modules. |
| .sp |
| Information returned by |
| \fBdistutils.sysconfig.get_config_var(\(aqSOABI\(aq)\fP or computed from |
| \fBdistutils.sysconfig.get_config_var(\(aqEXT_SUFFIX\(aq)\fP or |
| \fBpython\-config \-\-extension\-suffix\fP\&. If package \fBdistutils.sysconfig\fP is |
| not available, \fBsysconfig.get_config_var(\(aqSOABI\(aq)\fP or |
| \fBsysconfig.get_config_var(\(aqEXT_SUFFIX\(aq)\fP are used. |
| .TP |
| .B \fBPython_Compiler_FOUND\fP |
| System has the Python compiler. |
| .TP |
| .B \fBPython_COMPILER\fP |
| Path to the Python compiler. Only offered by IronPython. |
| .TP |
| .B \fBPython_COMPILER_ID\fP |
| .INDENT 7.0 |
| .TP |
| .B A short string unique to the compiler. Possible values include: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| IronPython |
| .UNINDENT |
| .UNINDENT |
| .TP |
| .B \fBPython_DOTNET_LAUNCHER\fP |
| New in version 3.18. |
| |
| .sp |
| The \fB\&.Net\fP interpreter. Only used by \fBIronPython\fP implementation. |
| .TP |
| .B \fBPython_Development_FOUND\fP |
| System has the Python development artifacts. |
| .TP |
| .B \fBPython_Development.Module_FOUND\fP |
| New in version 3.18. |
| |
| .sp |
| System has the Python development artifacts for Python module. |
| .TP |
| .B \fBPython_Development.Embed_FOUND\fP |
| New in version 3.18. |
| |
| .sp |
| System has the Python development artifacts for Python embedding. |
| .UNINDENT |
| .sp |
| \fBPython_INCLUDE_DIRS\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| The Python include directories. |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B \fBPython_LINK_OPTIONS\fP |
| New in version 3.19. |
| |
| .sp |
| The Python link options. Some configurations require specific link options |
| for a correct build and execution. |
| .TP |
| .B \fBPython_LIBRARIES\fP |
| The Python libraries. |
| .TP |
| .B \fBPython_LIBRARY_DIRS\fP |
| The Python library directories. |
| .TP |
| .B \fBPython_RUNTIME_LIBRARY_DIRS\fP |
| The Python runtime library directories. |
| .TP |
| .B \fBPython_VERSION\fP |
| Python version. |
| .TP |
| .B \fBPython_VERSION_MAJOR\fP |
| Python major version. |
| .TP |
| .B \fBPython_VERSION_MINOR\fP |
| Python minor version. |
| .TP |
| .B \fBPython_VERSION_PATCH\fP |
| Python patch version. |
| .TP |
| .B \fBPython_PyPy_VERSION\fP |
| New in version 3.18. |
| |
| .sp |
| Python PyPy version. |
| .TP |
| .B \fBPython_NumPy_FOUND\fP |
| New in version 3.14. |
| |
| .sp |
| System has the NumPy. |
| .TP |
| .B \fBPython_NumPy_INCLUDE_DIRS\fP |
| New in version 3.14. |
| |
| .sp |
| The NumPy include directories. |
| .TP |
| .B \fBPython_NumPy_VERSION\fP |
| New in version 3.14. |
| |
| .sp |
| The NumPy version. |
| .UNINDENT |
| .SS Hints |
| .INDENT 0.0 |
| .TP |
| .B \fBPython_ROOT_DIR\fP |
| Define the root directory of a Python installation. |
| .TP |
| .B \fBPython_USE_STATIC_LIBS\fP |
| .INDENT 7.0 |
| .IP \(bu 2 |
| If not defined, search for shared libraries and static libraries in that |
| order. |
| .IP \(bu 2 |
| If set to TRUE, search \fBonly\fP for static libraries. |
| .IP \(bu 2 |
| If set to FALSE, search \fBonly\fP for shared libraries. |
| .UNINDENT |
| .sp |
| \fBNOTE:\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| This hint will be ignored on \fBWindows\fP because static libraries are not |
| available on this platform. |
| .UNINDENT |
| .UNINDENT |
| .TP |
| .B \fBPython_FIND_ABI\fP |
| New in version 3.16. |
| |
| .sp |
| This variable defines which ABIs, as defined in |
| \fI\%PEP 3149\fP, should be searched. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| This hint will be honored only when searched for \fBPython\fP version 3. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBNOTE:\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| If \fBPython_FIND_ABI\fP is not defined, any ABI will be searched. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The \fBPython_FIND_ABI\fP variable is a 3\-tuple specifying, in that order, |
| \fBpydebug\fP (\fBd\fP), \fBpymalloc\fP (\fBm\fP) and \fBunicode\fP (\fBu\fP) flags. |
| Each element can be set to one of the following: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| \fBON\fP: Corresponding flag is selected. |
| .IP \(bu 2 |
| \fBOFF\fP: Corresponding flag is not selected. |
| .IP \(bu 2 |
| \fBANY\fP: The two possibilities (\fBON\fP and \fBOFF\fP) will be searched. |
| .UNINDENT |
| .sp |
| From this 3\-tuple, various ABIs will be searched starting from the most |
| specialized to the most general. Moreover, \fBdebug\fP versions will be |
| searched \fBafter\fP \fBnon\-debug\fP ones. |
| .sp |
| For example, if we have: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set (Python_FIND_ABI "ON" "ANY" "ANY") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The following flags combinations will be appended, in that order, to the |
| artifact names: \fBdmu\fP, \fBdm\fP, \fBdu\fP, and \fBd\fP\&. |
| .sp |
| And to search any possible ABIs: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set (Python_FIND_ABI "ANY" "ANY" "ANY") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The following combinations, in that order, will be used: \fBmu\fP, \fBm\fP, |
| \fBu\fP, \fB<empty>\fP, \fBdmu\fP, \fBdm\fP, \fBdu\fP and \fBd\fP\&. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| This hint is useful only on \fBPOSIX\fP systems. So, on \fBWindows\fP systems, |
| when \fBPython_FIND_ABI\fP is defined, \fBPython\fP distributions from |
| \fI\%python.org\fP will be found only if value for |
| each flag is \fBOFF\fP or \fBANY\fP\&. |
| .UNINDENT |
| .UNINDENT |
| .TP |
| .B \fBPython_FIND_STRATEGY\fP |
| New in version 3.15. |
| |
| .sp |
| This variable defines how lookup will be done. |
| The \fBPython_FIND_STRATEGY\fP variable can be set to one of the following: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| \fBVERSION\fP: Try to find the most recent version in all specified |
| locations. |
| This is the default if policy \fBCMP0094\fP is undefined or set to |
| \fBOLD\fP\&. |
| .IP \(bu 2 |
| \fBLOCATION\fP: Stops lookup as soon as a version satisfying version |
| constraints is founded. |
| This is the default if policy \fBCMP0094\fP is set to \fBNEW\fP\&. |
| .UNINDENT |
| .TP |
| .B \fBPython_FIND_REGISTRY\fP |
| New in version 3.13. |
| |
| .sp |
| On Windows the \fBPython_FIND_REGISTRY\fP variable determine the order |
| of preference between registry and environment variables. |
| the \fBPython_FIND_REGISTRY\fP variable can be set to one of the following: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| \fBFIRST\fP: Try to use registry before environment variables. |
| This is the default. |
| .IP \(bu 2 |
| \fBLAST\fP: Try to use registry after environment variables. |
| .IP \(bu 2 |
| \fBNEVER\fP: Never try to use registry. |
| .UNINDENT |
| .TP |
| .B \fBPython_FIND_FRAMEWORK\fP |
| New in version 3.15. |
| |
| .sp |
| On macOS the \fBPython_FIND_FRAMEWORK\fP variable determine the order of |
| preference between Apple\-style and unix\-style package components. |
| This variable can take same values as \fBCMAKE_FIND_FRAMEWORK\fP |
| variable. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| Value \fBONLY\fP is not supported so \fBFIRST\fP will be used instead. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| If \fBPython_FIND_FRAMEWORK\fP is not defined, \fBCMAKE_FIND_FRAMEWORK\fP |
| variable will be used, if any. |
| .TP |
| .B \fBPython_FIND_VIRTUALENV\fP |
| New in version 3.15. |
| |
| .sp |
| This variable defines the handling of virtual environments managed by |
| \fBvirtualenv\fP or \fBconda\fP\&. It is meaningful only when a virtual environment |
| is active (i.e. the \fBactivate\fP script has been evaluated). In this case, it |
| takes precedence over \fBPython_FIND_REGISTRY\fP and \fBCMAKE_FIND_FRAMEWORK\fP |
| variables. The \fBPython_FIND_VIRTUALENV\fP variable can be set to one of the |
| following: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| \fBFIRST\fP: The virtual environment is used before any other standard |
| paths to look\-up for the interpreter. This is the default. |
| .IP \(bu 2 |
| \fBONLY\fP: Only the virtual environment is used to look\-up for the |
| interpreter. |
| .IP \(bu 2 |
| \fBSTANDARD\fP: The virtual environment is not used to look\-up for the |
| interpreter but environment variable \fBPATH\fP is always considered. |
| In this case, variable \fBPython_FIND_REGISTRY\fP (Windows) or |
| \fBCMAKE_FIND_FRAMEWORK\fP (macOS) can be set with value \fBLAST\fP or |
| \fBNEVER\fP to select preferably the interpreter from the virtual |
| environment. |
| .UNINDENT |
| .sp |
| New in version 3.17: Added support for \fBconda\fP environments. |
| |
| .sp |
| \fBNOTE:\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| If the component \fBDevelopment\fP is requested, it is \fBstrongly\fP |
| recommended to also include the component \fBInterpreter\fP to get expected |
| result. |
| .UNINDENT |
| .UNINDENT |
| .TP |
| .B \fBPython_FIND_IMPLEMENTATIONS\fP |
| New in version 3.18. |
| |
| .sp |
| This variable defines, in an ordered list, the different implementations |
| which will be searched. The \fBPython_FIND_IMPLEMENTATIONS\fP variable can |
| hold the following values: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| \fBCPython\fP: this is the standard implementation. Various products, like |
| \fBAnaconda\fP or \fBActivePython\fP, rely on this implementation. |
| .IP \(bu 2 |
| \fBIronPython\fP: This implementation use the \fBCSharp\fP language for |
| \fB\&.NET Framework\fP on top of the \fIDynamic Language Runtime\fP (\fBDLR\fP). |
| See \fI\%IronPython\fP\&. |
| .IP \(bu 2 |
| \fBPyPy\fP: This implementation use \fBRPython\fP language and |
| \fBRPython translation toolchain\fP to produce the python interpreter. |
| See \fI\%PyPy\fP\&. |
| .UNINDENT |
| .sp |
| The default value is: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| Windows platform: \fBCPython\fP, \fBIronPython\fP |
| .IP \(bu 2 |
| Other platforms: \fBCPython\fP |
| .UNINDENT |
| .sp |
| \fBNOTE:\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| This hint has the lowest priority of all hints, so even if, for example, |
| you specify \fBIronPython\fP first and \fBCPython\fP in second, a python |
| product based on \fBCPython\fP can be selected because, for example with |
| \fBPython_FIND_STRATEGY=LOCATION\fP, each location will be search first for |
| \fBIronPython\fP and second for \fBCPython\fP\&. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBNOTE:\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| When \fBIronPython\fP is specified, on platforms other than \fBWindows\fP, the |
| \fB\&.Net\fP interpreter (i.e. \fBmono\fP command) is expected to be available |
| through the \fBPATH\fP variable. |
| .UNINDENT |
| .UNINDENT |
| .TP |
| .B \fBPython_FIND_UNVERSIONED_NAMES\fP |
| New in version 3.20. |
| |
| .sp |
| This variable defines how the generic names will be searched. Currently, it |
| only applies to the generic names of the interpreter, namely, \fBpython3\fP or |
| \fBpython2\fP and \fBpython\fP\&. |
| The \fBPython_FIND_UNVERSIONED_NAMES\fP variable can be set to one of the |
| following values: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| \fBFIRST\fP: The generic names are searched before the more specialized ones |
| (such as \fBpython2.5\fP for example). |
| .IP \(bu 2 |
| \fBLAST\fP: The generic names are searched after the more specialized ones. |
| This is the default. |
| .IP \(bu 2 |
| \fBNEVER\fP: The generic name are not searched at all. |
| .UNINDENT |
| .UNINDENT |
| .SS Artifacts Specification |
| .sp |
| New in version 3.16. |
| |
| .sp |
| To solve special cases, it is possible to specify directly the artifacts by |
| setting the following variables: |
| .INDENT 0.0 |
| .TP |
| .B \fBPython_EXECUTABLE\fP |
| The path to the interpreter. |
| .TP |
| .B \fBPython_COMPILER\fP |
| The path to the compiler. |
| .TP |
| .B \fBPython_DOTNET_LAUNCHER\fP |
| New in version 3.18. |
| |
| .sp |
| The \fB\&.Net\fP interpreter. Only used by \fBIronPython\fP implementation. |
| .TP |
| .B \fBPython_LIBRARY\fP |
| The path to the library. It will be used to compute the |
| variables \fBPython_LIBRARIES\fP, \fBPython_LIBRARY_DIRS\fP and |
| \fBPython_RUNTIME_LIBRARY_DIRS\fP\&. |
| .TP |
| .B \fBPython_INCLUDE_DIR\fP |
| The path to the directory of the \fBPython\fP headers. It will be used to |
| compute the variable \fBPython_INCLUDE_DIRS\fP\&. |
| .TP |
| .B \fBPython_NumPy_INCLUDE_DIR\fP |
| The path to the directory of the \fBNumPy\fP headers. It will be used to |
| compute the variable \fBPython_NumPy_INCLUDE_DIRS\fP\&. |
| .UNINDENT |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| All paths must be absolute. Any artifact specified with a relative path |
| will be ignored. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| When an artifact is specified, all \fBHINTS\fP will be ignored and no search |
| will be performed for this artifact. |
| .sp |
| If more than one artifact is specified, it is the user\(aqs responsibility to |
| ensure the consistency of the various artifacts. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| By default, this module supports multiple calls in different directories of a |
| project with different version/component requirements while providing correct |
| and consistent results for each call. To support this behavior, \fBCMake\fP cache |
| is not used in the traditional way which can be problematic for interactive |
| specification. So, to enable also interactive specification, module behavior |
| can be controlled with the following variable: |
| .INDENT 0.0 |
| .TP |
| .B \fBPython_ARTIFACTS_INTERACTIVE\fP |
| New in version 3.18. |
| |
| .sp |
| Selects the behavior of the module. This is a boolean variable: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| If set to \fBTRUE\fP: Create CMake cache entries for the above artifact |
| specification variables so that users can edit them interactively. |
| This disables support for multiple version/component requirements. |
| .IP \(bu 2 |
| If set to \fBFALSE\fP or undefined: Enable multiple version/component |
| requirements. |
| .UNINDENT |
| .UNINDENT |
| .SS Commands |
| .sp |
| This module defines the command \fBPython_add_library\fP (when |
| \fBCMAKE_ROLE\fP is \fBPROJECT\fP), which has the same semantics as |
| \fBadd_library()\fP and adds a dependency to target \fBPython::Python\fP or, |
| when library type is \fBMODULE\fP, to target \fBPython::Module\fP and takes care of |
| Python module naming rules: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| Python_add_library (<name> [STATIC | SHARED | MODULE [WITH_SOABI]] |
| <source1> [<source2> ...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| If the library type is not specified, \fBMODULE\fP is assumed. |
| .sp |
| New in version 3.17: For \fBMODULE\fP library type, if option \fBWITH_SOABI\fP is specified, the |
| module suffix will include the \fBPython_SOABI\fP value, if any. |
| |
| .SS FindPython2 |
| .sp |
| New in version 3.12. |
| |
| .sp |
| Find Python 2 interpreter, compiler and development environment (include |
| directories and libraries). |
| .sp |
| New in version 3.19: When a version is requested, it can be specified as a simple value or as a |
| range. For a detailed description of version range usage and capabilities, |
| refer to the \fBfind_package()\fP command. |
| |
| .sp |
| The following components are supported: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBInterpreter\fP: search for Python 2 interpreter |
| .IP \(bu 2 |
| \fBCompiler\fP: search for Python 2 compiler. Only offered by IronPython. |
| .IP \(bu 2 |
| \fBDevelopment\fP: search for development artifacts (include directories and |
| libraries). |
| .sp |
| New in version 3.18: This component includes two sub\-components which can be specified |
| independently: |
| .INDENT 2.0 |
| .IP \(bu 2 |
| \fBDevelopment.Module\fP: search for artifacts for Python 2 module |
| developments. |
| .IP \(bu 2 |
| \fBDevelopment.Embed\fP: search for artifacts for Python 2 embedding |
| developments. |
| .UNINDENT |
| |
| .IP \(bu 2 |
| \fBNumPy\fP: search for NumPy include directories. |
| .UNINDENT |
| .sp |
| New in version 3.14: Added the \fBNumPy\fP component. |
| |
| .sp |
| If no \fBCOMPONENTS\fP are specified, \fBInterpreter\fP is assumed. |
| .sp |
| If component \fBDevelopment\fP is specified, it implies sub\-components |
| \fBDevelopment.Module\fP and \fBDevelopment.Embed\fP\&. |
| .sp |
| To ensure consistent versions between components \fBInterpreter\fP, \fBCompiler\fP, |
| \fBDevelopment\fP (or one of its sub\-components) and \fBNumPy\fP, specify all |
| components at the same time: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_package (Python2 COMPONENTS Interpreter Development) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This module looks only for version 2 of Python. This module can be used |
| concurrently with \fBFindPython3\fP module to use both Python versions. |
| .sp |
| The \fBFindPython\fP module can be used if Python version does not matter |
| for you. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| If components \fBInterpreter\fP and \fBDevelopment\fP (or one of its |
| sub\-components) are both specified, this module search only for interpreter |
| with same platform architecture as the one defined by \fBCMake\fP |
| configuration. This constraint does not apply if only \fBInterpreter\fP |
| component is specified. |
| .UNINDENT |
| .UNINDENT |
| .SS Imported Targets |
| .sp |
| This module defines the following Imported Targets: |
| .sp |
| Changed in version 3.14: Imported Targets are only created when |
| \fBCMAKE_ROLE\fP is \fBPROJECT\fP\&. |
| |
| .INDENT 0.0 |
| .TP |
| .B \fBPython2::Interpreter\fP |
| Python 2 interpreter. Target defined if component \fBInterpreter\fP is found. |
| .TP |
| .B \fBPython2::Compiler\fP |
| Python 2 compiler. Target defined if component \fBCompiler\fP is found. |
| .TP |
| .B \fBPython2::Module\fP |
| New in version 3.15. |
| |
| .sp |
| Python 2 library for Python module. Target defined if component |
| \fBDevelopment.Module\fP is found. |
| .TP |
| .B \fBPython2::Python\fP |
| Python 2 library for Python embedding. Target defined if component |
| \fBDevelopment.Embed\fP is found. |
| .TP |
| .B \fBPython2::NumPy\fP |
| New in version 3.14. |
| |
| .sp |
| NumPy library for Python 2. Target defined if component \fBNumPy\fP is found. |
| .UNINDENT |
| .SS Result Variables |
| .sp |
| This module will set the following variables in your project |
| (see Standard Variable Names): |
| .INDENT 0.0 |
| .TP |
| .B \fBPython2_FOUND\fP |
| System has the Python 2 requested components. |
| .TP |
| .B \fBPython2_Interpreter_FOUND\fP |
| System has the Python 2 interpreter. |
| .TP |
| .B \fBPython2_EXECUTABLE\fP |
| Path to the Python 2 interpreter. |
| .TP |
| .B \fBPython2_INTERPRETER_ID\fP |
| .INDENT 7.0 |
| .TP |
| .B A short string unique to the interpreter. Possible values include: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| Python |
| .IP \(bu 2 |
| ActivePython |
| .IP \(bu 2 |
| Anaconda |
| .IP \(bu 2 |
| Canopy |
| .IP \(bu 2 |
| IronPython |
| .IP \(bu 2 |
| PyPy |
| .UNINDENT |
| .UNINDENT |
| .TP |
| .B \fBPython2_STDLIB\fP |
| Standard platform independent installation directory. |
| .sp |
| Information returned by |
| \fBdistutils.sysconfig.get_python_lib(plat_specific=False,standard_lib=True)\fP |
| or else \fBsysconfig.get_path(\(aqstdlib\(aq)\fP\&. |
| .TP |
| .B \fBPython2_STDARCH\fP |
| Standard platform dependent installation directory. |
| .sp |
| Information returned by |
| \fBdistutils.sysconfig.get_python_lib(plat_specific=True,standard_lib=True)\fP |
| or else \fBsysconfig.get_path(\(aqplatstdlib\(aq)\fP\&. |
| .TP |
| .B \fBPython2_SITELIB\fP |
| Third\-party platform independent installation directory. |
| .sp |
| Information returned by |
| \fBdistutils.sysconfig.get_python_lib(plat_specific=False,standard_lib=False)\fP |
| or else \fBsysconfig.get_path(\(aqpurelib\(aq)\fP\&. |
| .TP |
| .B \fBPython2_SITEARCH\fP |
| Third\-party platform dependent installation directory. |
| .sp |
| Information returned by |
| \fBdistutils.sysconfig.get_python_lib(plat_specific=True,standard_lib=False)\fP |
| or else \fBsysconfig.get_path(\(aqplatlib\(aq)\fP\&. |
| .TP |
| .B \fBPython2_Compiler_FOUND\fP |
| System has the Python 2 compiler. |
| .TP |
| .B \fBPython2_COMPILER\fP |
| Path to the Python 2 compiler. Only offered by IronPython. |
| .TP |
| .B \fBPython2_COMPILER_ID\fP |
| .INDENT 7.0 |
| .TP |
| .B A short string unique to the compiler. Possible values include: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| IronPython |
| .UNINDENT |
| .UNINDENT |
| .TP |
| .B \fBPython2_DOTNET_LAUNCHER\fP |
| New in version 3.18. |
| |
| .sp |
| The \fB\&.Net\fP interpreter. Only used by \fBIronPython\fP implementation. |
| .TP |
| .B \fBPython2_Development_FOUND\fP |
| System has the Python 2 development artifacts. |
| .TP |
| .B \fBPython2_Development.Module_FOUND\fP |
| New in version 3.18. |
| |
| .sp |
| System has the Python 2 development artifacts for Python module. |
| .TP |
| .B \fBPython2_Development.Embed_FOUND\fP |
| New in version 3.18. |
| |
| .sp |
| System has the Python 2 development artifacts for Python embedding. |
| .TP |
| .B \fBPython2_INCLUDE_DIRS\fP |
| The Python 2 include directories. |
| .TP |
| .B \fBPython2_LINK_OPTIONS\fP |
| New in version 3.19. |
| |
| .sp |
| The Python 2 link options. Some configurations require specific link options |
| for a correct build and execution. |
| .TP |
| .B \fBPython2_LIBRARIES\fP |
| The Python 2 libraries. |
| .TP |
| .B \fBPython2_LIBRARY_DIRS\fP |
| The Python 2 library directories. |
| .TP |
| .B \fBPython2_RUNTIME_LIBRARY_DIRS\fP |
| The Python 2 runtime library directories. |
| .TP |
| .B \fBPython2_VERSION\fP |
| Python 2 version. |
| .TP |
| .B \fBPython2_VERSION_MAJOR\fP |
| Python 2 major version. |
| .TP |
| .B \fBPython2_VERSION_MINOR\fP |
| Python 2 minor version. |
| .TP |
| .B \fBPython2_VERSION_PATCH\fP |
| Python 2 patch version. |
| .TP |
| .B \fBPython2_PyPy_VERSION\fP |
| New in version 3.18. |
| |
| .sp |
| Python 2 PyPy version. |
| .TP |
| .B \fBPython2_NumPy_FOUND\fP |
| New in version 3.14. |
| |
| .sp |
| System has the NumPy. |
| .TP |
| .B \fBPython2_NumPy_INCLUDE_DIRS\fP |
| New in version 3.14. |
| |
| .sp |
| The NumPy include directories. |
| .TP |
| .B \fBPython2_NumPy_VERSION\fP |
| New in version 3.14. |
| |
| .sp |
| The NumPy version. |
| .UNINDENT |
| .SS Hints |
| .INDENT 0.0 |
| .TP |
| .B \fBPython2_ROOT_DIR\fP |
| Define the root directory of a Python 2 installation. |
| .TP |
| .B \fBPython2_USE_STATIC_LIBS\fP |
| .INDENT 7.0 |
| .IP \(bu 2 |
| If not defined, search for shared libraries and static libraries in that |
| order. |
| .IP \(bu 2 |
| If set to TRUE, search \fBonly\fP for static libraries. |
| .IP \(bu 2 |
| If set to FALSE, search \fBonly\fP for shared libraries. |
| .UNINDENT |
| .sp |
| \fBNOTE:\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| This hint will be ignored on \fBWindows\fP because static libraries are not |
| available on this platform. |
| .UNINDENT |
| .UNINDENT |
| .TP |
| .B \fBPython2_FIND_STRATEGY\fP |
| New in version 3.15. |
| |
| .sp |
| This variable defines how lookup will be done. |
| The \fBPython2_FIND_STRATEGY\fP variable can be set to one of the following: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| \fBVERSION\fP: Try to find the most recent version in all specified |
| locations. |
| This is the default if policy \fBCMP0094\fP is undefined or set to |
| \fBOLD\fP\&. |
| .IP \(bu 2 |
| \fBLOCATION\fP: Stops lookup as soon as a version satisfying version |
| constraints is founded. |
| This is the default if policy \fBCMP0094\fP is set to \fBNEW\fP\&. |
| .UNINDENT |
| .TP |
| .B \fBPython2_FIND_REGISTRY\fP |
| New in version 3.13. |
| |
| .sp |
| On Windows the \fBPython2_FIND_REGISTRY\fP variable determine the order |
| of preference between registry and environment variables. |
| the \fBPython2_FIND_REGISTRY\fP variable can be set to one of the following: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| \fBFIRST\fP: Try to use registry before environment variables. |
| This is the default. |
| .IP \(bu 2 |
| \fBLAST\fP: Try to use registry after environment variables. |
| .IP \(bu 2 |
| \fBNEVER\fP: Never try to use registry. |
| .UNINDENT |
| .TP |
| .B \fBPython2_FIND_FRAMEWORK\fP |
| New in version 3.15. |
| |
| .sp |
| On macOS the \fBPython2_FIND_FRAMEWORK\fP variable determine the order of |
| preference between Apple\-style and unix\-style package components. |
| This variable can take same values as \fBCMAKE_FIND_FRAMEWORK\fP |
| variable. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| Value \fBONLY\fP is not supported so \fBFIRST\fP will be used instead. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| If \fBPython2_FIND_FRAMEWORK\fP is not defined, \fBCMAKE_FIND_FRAMEWORK\fP |
| variable will be used, if any. |
| .TP |
| .B \fBPython2_FIND_VIRTUALENV\fP |
| New in version 3.15. |
| |
| .sp |
| This variable defines the handling of virtual environments managed by |
| \fBvirtualenv\fP or \fBconda\fP\&. It is meaningful only when a virtual environment |
| is active (i.e. the \fBactivate\fP script has been evaluated). In this case, it |
| takes precedence over \fBPython2_FIND_REGISTRY\fP and \fBCMAKE_FIND_FRAMEWORK\fP |
| variables. The \fBPython2_FIND_VIRTUALENV\fP variable can be set to one of the |
| following: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| \fBFIRST\fP: The virtual environment is used before any other standard |
| paths to look\-up for the interpreter. This is the default. |
| .IP \(bu 2 |
| \fBONLY\fP: Only the virtual environment is used to look\-up for the |
| interpreter. |
| .IP \(bu 2 |
| \fBSTANDARD\fP: The virtual environment is not used to look\-up for the |
| interpreter but environment variable \fBPATH\fP is always considered. |
| In this case, variable \fBPython2_FIND_REGISTRY\fP (Windows) or |
| \fBCMAKE_FIND_FRAMEWORK\fP (macOS) can be set with value \fBLAST\fP or |
| \fBNEVER\fP to select preferably the interpreter from the virtual |
| environment. |
| .UNINDENT |
| .sp |
| New in version 3.17: Added support for \fBconda\fP environments. |
| |
| .sp |
| \fBNOTE:\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| If the component \fBDevelopment\fP is requested, it is \fBstrongly\fP |
| recommended to also include the component \fBInterpreter\fP to get expected |
| result. |
| .UNINDENT |
| .UNINDENT |
| .TP |
| .B \fBPython2_FIND_IMPLEMENTATIONS\fP |
| New in version 3.18. |
| |
| .sp |
| This variable defines, in an ordered list, the different implementations |
| which will be searched. The \fBPython2_FIND_IMPLEMENTATIONS\fP variable can |
| hold the following values: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| \fBCPython\fP: this is the standard implementation. Various products, like |
| \fBAnaconda\fP or \fBActivePython\fP, rely on this implementation. |
| .IP \(bu 2 |
| \fBIronPython\fP: This implementation use the \fBCSharp\fP language for |
| \fB\&.NET Framework\fP on top of the \fIDynamic Language Runtime\fP (\fBDLR\fP). |
| See \fI\%IronPython\fP\&. |
| .IP \(bu 2 |
| \fBPyPy\fP: This implementation use \fBRPython\fP language and |
| \fBRPython translation toolchain\fP to produce the python interpreter. |
| See \fI\%PyPy\fP\&. |
| .UNINDENT |
| .sp |
| The default value is: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| Windows platform: \fBCPython\fP, \fBIronPython\fP |
| .IP \(bu 2 |
| Other platforms: \fBCPython\fP |
| .UNINDENT |
| .sp |
| \fBNOTE:\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| This hint has the lowest priority of all hints, so even if, for example, |
| you specify \fBIronPython\fP first and \fBCPython\fP in second, a python |
| product based on \fBCPython\fP can be selected because, for example with |
| \fBPython2_FIND_STRATEGY=LOCATION\fP, each location will be search first for |
| \fBIronPython\fP and second for \fBCPython\fP\&. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBNOTE:\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| When \fBIronPython\fP is specified, on platforms other than \fBWindows\fP, the |
| \fB\&.Net\fP interpreter (i.e. \fBmono\fP command) is expected to be available |
| through the \fBPATH\fP variable. |
| .UNINDENT |
| .UNINDENT |
| .TP |
| .B \fBPython2_FIND_UNVERSIONED_NAMES\fP |
| New in version 3.20. |
| |
| .sp |
| This variable defines how the generic names will be searched. Currently, it |
| only applies to the generic names of the interpreter, namely, \fBpython2\fP and |
| \fBpython\fP\&. |
| The \fBPython2_FIND_UNVERSIONED_NAMES\fP variable can be set to one of the |
| following values: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| \fBFIRST\fP: The generic names are searched before the more specialized ones |
| (such as \fBpython2.5\fP for example). |
| .IP \(bu 2 |
| \fBLAST\fP: The generic names are searched after the more specialized ones. |
| This is the default. |
| .IP \(bu 2 |
| \fBNEVER\fP: The generic name are not searched at all. |
| .UNINDENT |
| .UNINDENT |
| .SS Artifacts Specification |
| .sp |
| New in version 3.16. |
| |
| .sp |
| To solve special cases, it is possible to specify directly the artifacts by |
| setting the following variables: |
| .INDENT 0.0 |
| .TP |
| .B \fBPython2_EXECUTABLE\fP |
| The path to the interpreter. |
| .TP |
| .B \fBPython2_COMPILER\fP |
| The path to the compiler. |
| .TP |
| .B \fBPython2_DOTNET_LAUNCHER\fP |
| New in version 3.18. |
| |
| .sp |
| The \fB\&.Net\fP interpreter. Only used by \fBIronPython\fP implementation. |
| .TP |
| .B \fBPython2_LIBRARY\fP |
| The path to the library. It will be used to compute the |
| variables \fBPython2_LIBRARIES\fP, \fBPython2_LIBRARY_DIRS\fP and |
| \fBPython2_RUNTIME_LIBRARY_DIRS\fP\&. |
| .TP |
| .B \fBPython2_INCLUDE_DIR\fP |
| The path to the directory of the \fBPython\fP headers. It will be used to |
| compute the variable \fBPython2_INCLUDE_DIRS\fP\&. |
| .TP |
| .B \fBPython2_NumPy_INCLUDE_DIR\fP |
| The path to the directory of the \fBNumPy\fP headers. It will be used to |
| compute the variable \fBPython2_NumPy_INCLUDE_DIRS\fP\&. |
| .UNINDENT |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| All paths must be absolute. Any artifact specified with a relative path |
| will be ignored. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| When an artifact is specified, all \fBHINTS\fP will be ignored and no search |
| will be performed for this artifact. |
| .sp |
| If more than one artifact is specified, it is the user\(aqs responsibility to |
| ensure the consistency of the various artifacts. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| By default, this module supports multiple calls in different directories of a |
| project with different version/component requirements while providing correct |
| and consistent results for each call. To support this behavior, \fBCMake\fP cache |
| is not used in the traditional way which can be problematic for interactive |
| specification. So, to enable also interactive specification, module behavior |
| can be controlled with the following variable: |
| .INDENT 0.0 |
| .TP |
| .B \fBPython2_ARTIFACTS_INTERACTIVE\fP |
| New in version 3.18. |
| |
| .sp |
| Selects the behavior of the module. This is a boolean variable: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| If set to \fBTRUE\fP: Create CMake cache entries for the above artifact |
| specification variables so that users can edit them interactively. |
| This disables support for multiple version/component requirements. |
| .IP \(bu 2 |
| If set to \fBFALSE\fP or undefined: Enable multiple version/component |
| requirements. |
| .UNINDENT |
| .UNINDENT |
| .SS Commands |
| .sp |
| This module defines the command \fBPython2_add_library\fP (when |
| \fBCMAKE_ROLE\fP is \fBPROJECT\fP), which has the same semantics as |
| \fBadd_library()\fP and adds a dependency to target \fBPython2::Python\fP or, |
| when library type is \fBMODULE\fP, to target \fBPython2::Module\fP and takes care |
| of Python module naming rules: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| Python2_add_library (<name> [STATIC | SHARED | MODULE] |
| <source1> [<source2> ...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| If library type is not specified, \fBMODULE\fP is assumed. |
| .SS FindPython3 |
| .sp |
| New in version 3.12. |
| |
| .sp |
| Find Python 3 interpreter, compiler and development environment (include |
| directories and libraries). |
| .sp |
| New in version 3.19: When a version is requested, it can be specified as a simple value or as a |
| range. For a detailed description of version range usage and capabilities, |
| refer to the \fBfind_package()\fP command. |
| |
| .sp |
| The following components are supported: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBInterpreter\fP: search for Python 3 interpreter |
| .IP \(bu 2 |
| \fBCompiler\fP: search for Python 3 compiler. Only offered by IronPython. |
| .IP \(bu 2 |
| \fBDevelopment\fP: search for development artifacts (include directories and |
| libraries). |
| .sp |
| New in version 3.18: This component includes two sub\-components which can be specified |
| independently: |
| .INDENT 2.0 |
| .IP \(bu 2 |
| \fBDevelopment.Module\fP: search for artifacts for Python 3 module |
| developments. |
| .IP \(bu 2 |
| \fBDevelopment.Embed\fP: search for artifacts for Python 3 embedding |
| developments. |
| .UNINDENT |
| |
| .IP \(bu 2 |
| \fBNumPy\fP: search for NumPy include directories. |
| .UNINDENT |
| .sp |
| New in version 3.14: Added the \fBNumPy\fP component. |
| |
| .sp |
| If no \fBCOMPONENTS\fP are specified, \fBInterpreter\fP is assumed. |
| .sp |
| If component \fBDevelopment\fP is specified, it implies sub\-components |
| \fBDevelopment.Module\fP and \fBDevelopment.Embed\fP\&. |
| .sp |
| To ensure consistent versions between components \fBInterpreter\fP, \fBCompiler\fP, |
| \fBDevelopment\fP (or one of its sub\-components) and \fBNumPy\fP, specify all |
| components at the same time: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_package (Python3 COMPONENTS Interpreter Development) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This module looks only for version 3 of Python. This module can be used |
| concurrently with \fBFindPython2\fP module to use both Python versions. |
| .sp |
| The \fBFindPython\fP module can be used if Python version does not matter |
| for you. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| If components \fBInterpreter\fP and \fBDevelopment\fP (or one of its |
| sub\-components) are both specified, this module search only for interpreter |
| with same platform architecture as the one defined by \fBCMake\fP |
| configuration. This constraint does not apply if only \fBInterpreter\fP |
| component is specified. |
| .UNINDENT |
| .UNINDENT |
| .SS Imported Targets |
| .sp |
| This module defines the following Imported Targets: |
| .sp |
| Changed in version 3.14: Imported Targets are only created when |
| \fBCMAKE_ROLE\fP is \fBPROJECT\fP\&. |
| |
| .INDENT 0.0 |
| .TP |
| .B \fBPython3::Interpreter\fP |
| Python 3 interpreter. Target defined if component \fBInterpreter\fP is found. |
| .TP |
| .B \fBPython3::Compiler\fP |
| Python 3 compiler. Target defined if component \fBCompiler\fP is found. |
| .TP |
| .B \fBPython3::Module\fP |
| New in version 3.15. |
| |
| .sp |
| Python 3 library for Python module. Target defined if component |
| \fBDevelopment.Module\fP is found. |
| .TP |
| .B \fBPython3::Python\fP |
| Python 3 library for Python embedding. Target defined if component |
| \fBDevelopment.Embed\fP is found. |
| .TP |
| .B \fBPython3::NumPy\fP |
| New in version 3.14. |
| |
| .sp |
| NumPy library for Python 3. Target defined if component \fBNumPy\fP is found. |
| .UNINDENT |
| .SS Result Variables |
| .sp |
| This module will set the following variables in your project |
| (see Standard Variable Names): |
| .INDENT 0.0 |
| .TP |
| .B \fBPython3_FOUND\fP |
| System has the Python 3 requested components. |
| .TP |
| .B \fBPython3_Interpreter_FOUND\fP |
| System has the Python 3 interpreter. |
| .TP |
| .B \fBPython3_EXECUTABLE\fP |
| Path to the Python 3 interpreter. |
| .TP |
| .B \fBPython3_INTERPRETER_ID\fP |
| .INDENT 7.0 |
| .TP |
| .B A short string unique to the interpreter. Possible values include: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| Python |
| .IP \(bu 2 |
| ActivePython |
| .IP \(bu 2 |
| Anaconda |
| .IP \(bu 2 |
| Canopy |
| .IP \(bu 2 |
| IronPython |
| .IP \(bu 2 |
| PyPy |
| .UNINDENT |
| .UNINDENT |
| .TP |
| .B \fBPython3_STDLIB\fP |
| Standard platform independent installation directory. |
| .sp |
| Information returned by |
| \fBdistutils.sysconfig.get_python_lib(plat_specific=False,standard_lib=True)\fP |
| or else \fBsysconfig.get_path(\(aqstdlib\(aq)\fP\&. |
| .TP |
| .B \fBPython3_STDARCH\fP |
| Standard platform dependent installation directory. |
| .sp |
| Information returned by |
| \fBdistutils.sysconfig.get_python_lib(plat_specific=True,standard_lib=True)\fP |
| or else \fBsysconfig.get_path(\(aqplatstdlib\(aq)\fP\&. |
| .TP |
| .B \fBPython3_SITELIB\fP |
| Third\-party platform independent installation directory. |
| .sp |
| Information returned by |
| \fBdistutils.sysconfig.get_python_lib(plat_specific=False,standard_lib=False)\fP |
| or else \fBsysconfig.get_path(\(aqpurelib\(aq)\fP\&. |
| .TP |
| .B \fBPython3_SITEARCH\fP |
| Third\-party platform dependent installation directory. |
| .sp |
| Information returned by |
| \fBdistutils.sysconfig.get_python_lib(plat_specific=True,standard_lib=False)\fP |
| or else \fBsysconfig.get_path(\(aqplatlib\(aq)\fP\&. |
| .TP |
| .B \fBPython3_SOABI\fP |
| New in version 3.17. |
| |
| .sp |
| Extension suffix for modules. |
| .sp |
| Information returned by |
| \fBdistutils.sysconfig.get_config_var(\(aqSOABI\(aq)\fP or computed from |
| \fBdistutils.sysconfig.get_config_var(\(aqEXT_SUFFIX\(aq)\fP or |
| \fBpython3\-config \-\-extension\-suffix\fP\&. If package \fBdistutils.sysconfig\fP is |
| not available, \fBsysconfig.get_config_var(\(aqSOABI\(aq)\fP or |
| \fBsysconfig.get_config_var(\(aqEXT_SUFFIX\(aq)\fP are used. |
| .TP |
| .B \fBPython3_Compiler_FOUND\fP |
| System has the Python 3 compiler. |
| .TP |
| .B \fBPython3_COMPILER\fP |
| Path to the Python 3 compiler. Only offered by IronPython. |
| .TP |
| .B \fBPython3_COMPILER_ID\fP |
| .INDENT 7.0 |
| .TP |
| .B A short string unique to the compiler. Possible values include: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| IronPython |
| .UNINDENT |
| .UNINDENT |
| .TP |
| .B \fBPython3_DOTNET_LAUNCHER\fP |
| New in version 3.18. |
| |
| .sp |
| The \fB\&.Net\fP interpreter. Only used by \fBIronPython\fP implementation. |
| .UNINDENT |
| .sp |
| \fBPython3_Development_FOUND\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| System has the Python 3 development artifacts. |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B \fBPython3_Development.Module_FOUND\fP |
| New in version 3.18. |
| |
| .sp |
| System has the Python 3 development artifacts for Python module. |
| .TP |
| .B \fBPython3_Development.Embed_FOUND\fP |
| New in version 3.18. |
| |
| .sp |
| System has the Python 3 development artifacts for Python embedding. |
| .UNINDENT |
| .sp |
| \fBPython3_INCLUDE_DIRS\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| The Python 3 include directories. |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B \fBPython3_LINK_OPTIONS\fP |
| New in version 3.19. |
| |
| .sp |
| The Python 3 link options. Some configurations require specific link options |
| for a correct build and execution. |
| .TP |
| .B \fBPython3_LIBRARIES\fP |
| The Python 3 libraries. |
| .TP |
| .B \fBPython3_LIBRARY_DIRS\fP |
| The Python 3 library directories. |
| .TP |
| .B \fBPython3_RUNTIME_LIBRARY_DIRS\fP |
| The Python 3 runtime library directories. |
| .TP |
| .B \fBPython3_VERSION\fP |
| Python 3 version. |
| .TP |
| .B \fBPython3_VERSION_MAJOR\fP |
| Python 3 major version. |
| .TP |
| .B \fBPython3_VERSION_MINOR\fP |
| Python 3 minor version. |
| .TP |
| .B \fBPython3_VERSION_PATCH\fP |
| Python 3 patch version. |
| .TP |
| .B \fBPython3_PyPy_VERSION\fP |
| New in version 3.18. |
| |
| .sp |
| Python 3 PyPy version. |
| .TP |
| .B \fBPython3_NumPy_FOUND\fP |
| New in version 3.14. |
| |
| .sp |
| System has the NumPy. |
| .TP |
| .B \fBPython3_NumPy_INCLUDE_DIRS\fP |
| New in version 3.14. |
| |
| .sp |
| The NumPy include directories. |
| .TP |
| .B \fBPython3_NumPy_VERSION\fP |
| New in version 3.14. |
| |
| .sp |
| The NumPy version. |
| .UNINDENT |
| .SS Hints |
| .INDENT 0.0 |
| .TP |
| .B \fBPython3_ROOT_DIR\fP |
| Define the root directory of a Python 3 installation. |
| .TP |
| .B \fBPython3_USE_STATIC_LIBS\fP |
| .INDENT 7.0 |
| .IP \(bu 2 |
| If not defined, search for shared libraries and static libraries in that |
| order. |
| .IP \(bu 2 |
| If set to TRUE, search \fBonly\fP for static libraries. |
| .IP \(bu 2 |
| If set to FALSE, search \fBonly\fP for shared libraries. |
| .UNINDENT |
| .sp |
| \fBNOTE:\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| This hint will be ignored on \fBWindows\fP because static libraries are not |
| available on this platform. |
| .UNINDENT |
| .UNINDENT |
| .TP |
| .B \fBPython3_FIND_ABI\fP |
| New in version 3.16. |
| |
| .sp |
| This variable defines which ABIs, as defined in |
| \fI\%PEP 3149\fP, should be searched. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| If \fBPython3_FIND_ABI\fP is not defined, any ABI will be searched. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The \fBPython3_FIND_ABI\fP variable is a 3\-tuple specifying, in that order, |
| \fBpydebug\fP (\fBd\fP), \fBpymalloc\fP (\fBm\fP) and \fBunicode\fP (\fBu\fP) flags. |
| Each element can be set to one of the following: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| \fBON\fP: Corresponding flag is selected. |
| .IP \(bu 2 |
| \fBOFF\fP: Corresponding flag is not selected. |
| .IP \(bu 2 |
| \fBANY\fP: The two possibilities (\fBON\fP and \fBOFF\fP) will be searched. |
| .UNINDENT |
| .sp |
| From this 3\-tuple, various ABIs will be searched starting from the most |
| specialized to the most general. Moreover, \fBdebug\fP versions will be |
| searched \fBafter\fP \fBnon\-debug\fP ones. |
| .sp |
| For example, if we have: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set (Python3_FIND_ABI "ON" "ANY" "ANY") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The following flags combinations will be appended, in that order, to the |
| artifact names: \fBdmu\fP, \fBdm\fP, \fBdu\fP, and \fBd\fP\&. |
| .sp |
| And to search any possible ABIs: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set (Python3_FIND_ABI "ANY" "ANY" "ANY") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The following combinations, in that order, will be used: \fBmu\fP, \fBm\fP, |
| \fBu\fP, \fB<empty>\fP, \fBdmu\fP, \fBdm\fP, \fBdu\fP and \fBd\fP\&. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| This hint is useful only on \fBPOSIX\fP systems. So, on \fBWindows\fP systems, |
| when \fBPython3_FIND_ABI\fP is defined, \fBPython\fP distributions from |
| \fI\%python.org\fP will be found only if value for |
| each flag is \fBOFF\fP or \fBANY\fP\&. |
| .UNINDENT |
| .UNINDENT |
| .TP |
| .B \fBPython3_FIND_STRATEGY\fP |
| New in version 3.15. |
| |
| .sp |
| This variable defines how lookup will be done. |
| The \fBPython3_FIND_STRATEGY\fP variable can be set to one of the following: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| \fBVERSION\fP: Try to find the most recent version in all specified |
| locations. |
| This is the default if policy \fBCMP0094\fP is undefined or set to |
| \fBOLD\fP\&. |
| .IP \(bu 2 |
| \fBLOCATION\fP: Stops lookup as soon as a version satisfying version |
| constraints is founded. |
| This is the default if policy \fBCMP0094\fP is set to \fBNEW\fP\&. |
| .UNINDENT |
| .TP |
| .B \fBPython3_FIND_REGISTRY\fP |
| New in version 3.13. |
| |
| .sp |
| On Windows the \fBPython3_FIND_REGISTRY\fP variable determine the order |
| of preference between registry and environment variables. |
| The \fBPython3_FIND_REGISTRY\fP variable can be set to one of the following: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| \fBFIRST\fP: Try to use registry before environment variables. |
| This is the default. |
| .IP \(bu 2 |
| \fBLAST\fP: Try to use registry after environment variables. |
| .IP \(bu 2 |
| \fBNEVER\fP: Never try to use registry. |
| .UNINDENT |
| .TP |
| .B \fBPython3_FIND_FRAMEWORK\fP |
| New in version 3.15. |
| |
| .sp |
| On macOS the \fBPython3_FIND_FRAMEWORK\fP variable determine the order of |
| preference between Apple\-style and unix\-style package components. |
| This variable can take same values as \fBCMAKE_FIND_FRAMEWORK\fP |
| variable. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| Value \fBONLY\fP is not supported so \fBFIRST\fP will be used instead. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| If \fBPython3_FIND_FRAMEWORK\fP is not defined, \fBCMAKE_FIND_FRAMEWORK\fP |
| variable will be used, if any. |
| .TP |
| .B \fBPython3_FIND_VIRTUALENV\fP |
| New in version 3.15. |
| |
| .sp |
| This variable defines the handling of virtual environments managed by |
| \fBvirtualenv\fP or \fBconda\fP\&. It is meaningful only when a virtual environment |
| is active (i.e. the \fBactivate\fP script has been evaluated). In this case, it |
| takes precedence over \fBPython3_FIND_REGISTRY\fP and \fBCMAKE_FIND_FRAMEWORK\fP |
| variables. The \fBPython3_FIND_VIRTUALENV\fP variable can be set to one of the |
| following: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| \fBFIRST\fP: The virtual environment is used before any other standard |
| paths to look\-up for the interpreter. This is the default. |
| .IP \(bu 2 |
| \fBONLY\fP: Only the virtual environment is used to look\-up for the |
| interpreter. |
| .IP \(bu 2 |
| \fBSTANDARD\fP: The virtual environment is not used to look\-up for the |
| interpreter but environment variable \fBPATH\fP is always considered. |
| In this case, variable \fBPython3_FIND_REGISTRY\fP (Windows) or |
| \fBCMAKE_FIND_FRAMEWORK\fP (macOS) can be set with value \fBLAST\fP or |
| \fBNEVER\fP to select preferably the interpreter from the virtual |
| environment. |
| .UNINDENT |
| .sp |
| New in version 3.17: Added support for \fBconda\fP environments. |
| |
| .sp |
| \fBNOTE:\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| If the component \fBDevelopment\fP is requested, it is \fBstrongly\fP |
| recommended to also include the component \fBInterpreter\fP to get expected |
| result. |
| .UNINDENT |
| .UNINDENT |
| .TP |
| .B \fBPython3_FIND_IMPLEMENTATIONS\fP |
| New in version 3.18. |
| |
| .sp |
| This variable defines, in an ordered list, the different implementations |
| which will be searched. The \fBPython3_FIND_IMPLEMENTATIONS\fP variable can |
| hold the following values: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| \fBCPython\fP: this is the standard implementation. Various products, like |
| \fBAnaconda\fP or \fBActivePython\fP, rely on this implementation. |
| .IP \(bu 2 |
| \fBIronPython\fP: This implementation use the \fBCSharp\fP language for |
| \fB\&.NET Framework\fP on top of the \fIDynamic Language Runtime\fP (\fBDLR\fP). |
| See \fI\%IronPython\fP\&. |
| .IP \(bu 2 |
| \fBPyPy\fP: This implementation use \fBRPython\fP language and |
| \fBRPython translation toolchain\fP to produce the python interpreter. |
| See \fI\%PyPy\fP\&. |
| .UNINDENT |
| .sp |
| The default value is: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| Windows platform: \fBCPython\fP, \fBIronPython\fP |
| .IP \(bu 2 |
| Other platforms: \fBCPython\fP |
| .UNINDENT |
| .sp |
| \fBNOTE:\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| This hint has the lowest priority of all hints, so even if, for example, |
| you specify \fBIronPython\fP first and \fBCPython\fP in second, a python |
| product based on \fBCPython\fP can be selected because, for example with |
| \fBPython3_FIND_STRATEGY=LOCATION\fP, each location will be search first for |
| \fBIronPython\fP and second for \fBCPython\fP\&. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBNOTE:\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| When \fBIronPython\fP is specified, on platforms other than \fBWindows\fP, the |
| \fB\&.Net\fP interpreter (i.e. \fBmono\fP command) is expected to be available |
| through the \fBPATH\fP variable. |
| .UNINDENT |
| .UNINDENT |
| .TP |
| .B \fBPython3_FIND_UNVERSIONED_NAMES\fP |
| New in version 3.20. |
| |
| .sp |
| This variable defines how the generic names will be searched. Currently, it |
| only applies to the generic names of the interpreter, namely, \fBpython3\fP and |
| \fBpython\fP\&. |
| The \fBPython3_FIND_UNVERSIONED_NAMES\fP variable can be set to one of the |
| following values: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| \fBFIRST\fP: The generic names are searched before the more specialized ones |
| (such as \fBpython3.5\fP for example). |
| .IP \(bu 2 |
| \fBLAST\fP: The generic names are searched after the more specialized ones. |
| This is the default. |
| .IP \(bu 2 |
| \fBNEVER\fP: The generic name are not searched at all. |
| .UNINDENT |
| .UNINDENT |
| .SS Artifacts Specification |
| .sp |
| New in version 3.16. |
| |
| .sp |
| To solve special cases, it is possible to specify directly the artifacts by |
| setting the following variables: |
| .INDENT 0.0 |
| .TP |
| .B \fBPython3_EXECUTABLE\fP |
| The path to the interpreter. |
| .TP |
| .B \fBPython3_COMPILER\fP |
| The path to the compiler. |
| .TP |
| .B \fBPython3_DOTNET_LAUNCHER\fP |
| New in version 3.18. |
| |
| .sp |
| The \fB\&.Net\fP interpreter. Only used by \fBIronPython\fP implementation. |
| .TP |
| .B \fBPython3_LIBRARY\fP |
| The path to the library. It will be used to compute the |
| variables \fBPython3_LIBRARIES\fP, \fBPython3_LIBRARY_DIRS\fP and |
| \fBPython3_RUNTIME_LIBRARY_DIRS\fP\&. |
| .TP |
| .B \fBPython3_INCLUDE_DIR\fP |
| The path to the directory of the \fBPython\fP headers. It will be used to |
| compute the variable \fBPython3_INCLUDE_DIRS\fP\&. |
| .TP |
| .B \fBPython3_NumPy_INCLUDE_DIR\fP |
| The path to the directory of the \fBNumPy\fP headers. It will be used to |
| compute the variable \fBPython3_NumPy_INCLUDE_DIRS\fP\&. |
| .UNINDENT |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| All paths must be absolute. Any artifact specified with a relative path |
| will be ignored. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| When an artifact is specified, all \fBHINTS\fP will be ignored and no search |
| will be performed for this artifact. |
| .sp |
| If more than one artifact is specified, it is the user\(aqs responsibility to |
| ensure the consistency of the various artifacts. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| By default, this module supports multiple calls in different directories of a |
| project with different version/component requirements while providing correct |
| and consistent results for each call. To support this behavior, \fBCMake\fP cache |
| is not used in the traditional way which can be problematic for interactive |
| specification. So, to enable also interactive specification, module behavior |
| can be controlled with the following variable: |
| .INDENT 0.0 |
| .TP |
| .B \fBPython3_ARTIFACTS_INTERACTIVE\fP |
| New in version 3.18. |
| |
| .sp |
| Selects the behavior of the module. This is a boolean variable: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| If set to \fBTRUE\fP: Create CMake cache entries for the above artifact |
| specification variables so that users can edit them interactively. |
| This disables support for multiple version/component requirements. |
| .IP \(bu 2 |
| If set to \fBFALSE\fP or undefined: Enable multiple version/component |
| requirements. |
| .UNINDENT |
| .UNINDENT |
| .SS Commands |
| .sp |
| This module defines the command \fBPython3_add_library\fP (when |
| \fBCMAKE_ROLE\fP is \fBPROJECT\fP), which has the same semantics as |
| \fBadd_library()\fP and adds a dependency to target \fBPython3::Python\fP or, |
| when library type is \fBMODULE\fP, to target \fBPython3::Module\fP and takes care |
| of Python module naming rules: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| Python3_add_library (<name> [STATIC | SHARED | MODULE [WITH_SOABI]] |
| <source1> [<source2> ...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| If the library type is not specified, \fBMODULE\fP is assumed. |
| .sp |
| New in version 3.17: For \fBMODULE\fP library type, if option \fBWITH_SOABI\fP is specified, the |
| module suffix will include the \fBPython3_SOABI\fP value, if any. |
| |
| .SS FindQt3 |
| .sp |
| Locate Qt include paths and libraries |
| .sp |
| This module defines: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| QT_INCLUDE_DIR \- where to find qt.h, etc. |
| QT_LIBRARIES \- the libraries to link against to use Qt. |
| QT_DEFINITIONS \- definitions to use when |
| compiling code that uses Qt. |
| QT_FOUND \- If false, don\(aqt try to use Qt. |
| QT_VERSION_STRING \- the version of Qt found |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| If you need the multithreaded version of Qt, set QT_MT_REQUIRED to |
| TRUE |
| .sp |
| Also defined, but not for general use are: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| QT_MOC_EXECUTABLE, where to find the moc tool. |
| QT_UIC_EXECUTABLE, where to find the uic tool. |
| QT_QT_LIBRARY, where to find the Qt library. |
| QT_QTMAIN_LIBRARY, where to find the qtmain |
| library. This is only required by Qt3 on Windows. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindQt4 |
| .SS Finding and Using Qt4 |
| .sp |
| This module can be used to find Qt4. The most important issue is that |
| the Qt4 qmake is available via the system path. This qmake is then |
| used to detect basically everything else. This module defines a |
| number of \fBIMPORTED\fP targets, macros and variables. |
| .sp |
| Typical usage could be something like: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(CMAKE_AUTOMOC ON) |
| set(CMAKE_INCLUDE_CURRENT_DIR ON) |
| find_package(Qt4 4.4.3 REQUIRED QtGui QtXml) |
| add_executable(myexe main.cpp) |
| target_link_libraries(myexe Qt4::QtGui Qt4::QtXml) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| When using \fBIMPORTED\fP targets, the qtmain.lib static library is |
| automatically linked on Windows for \fBWIN32\fP |
| executables. To disable that globally, set the |
| \fBQT4_NO_LINK_QTMAIN\fP variable before finding Qt4. To disable that |
| for a particular executable, set the \fBQT4_NO_LINK_QTMAIN\fP target |
| property to \fBTRUE\fP on the executable. |
| .UNINDENT |
| .UNINDENT |
| .SS Qt Build Tools |
| .sp |
| Qt relies on some bundled tools for code generation, such as \fBmoc\fP for |
| meta\-object code generation,\(ga\(gauic\(ga\(ga for widget layout and population, |
| and \fBrcc\fP for virtual filesystem content generation. These tools may be |
| automatically invoked by \fBcmake(1)\fP if the appropriate conditions |
| are met. See \fBcmake\-qt(7)\fP for more. |
| .SS Qt Macros |
| .sp |
| In some cases it can be necessary or useful to invoke the Qt build tools in a |
| more\-manual way. Several macros are available to add targets for such uses. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| macro QT4_WRAP_CPP(outfiles inputfile ... [TARGET tgt] OPTIONS ...) |
| create moc code from a list of files containing Qt class with |
| the Q_OBJECT declaration. Per\-directory preprocessor definitions |
| are also added. If the <tgt> is specified, the |
| INTERFACE_INCLUDE_DIRECTORIES and INTERFACE_COMPILE_DEFINITIONS from |
| the <tgt> are passed to moc. Options may be given to moc, such as |
| those found when executing "moc \-help". |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| macro QT4_WRAP_UI(outfiles inputfile ... OPTIONS ...) |
| create code from a list of Qt designer ui files. |
| Options may be given to uic, such as those found |
| when executing "uic \-help" |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| macro QT4_ADD_RESOURCES(outfiles inputfile ... OPTIONS ...) |
| create code from a list of Qt resource files. |
| Options may be given to rcc, such as those found |
| when executing "rcc \-help" |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| macro QT4_GENERATE_MOC(inputfile outputfile [TARGET tgt]) |
| creates a rule to run moc on infile and create outfile. |
| Use this if for some reason QT4_WRAP_CPP() isn\(aqt appropriate, e.g. |
| because you need a custom filename for the moc file or something |
| similar. If the <tgt> is specified, the |
| INTERFACE_INCLUDE_DIRECTORIES and INTERFACE_COMPILE_DEFINITIONS from |
| the <tgt> are passed to moc. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| macro QT4_ADD_DBUS_INTERFACE(outfiles interface basename) |
| Create the interface header and implementation files with the |
| given basename from the given interface xml file and add it to |
| the list of sources. |
| |
| You can pass additional parameters to the qdbusxml2cpp call by setting |
| properties on the input file: |
| |
| INCLUDE the given file will be included in the generate interface header |
| |
| CLASSNAME the generated class is named accordingly |
| |
| NO_NAMESPACE the generated class is not wrapped in a namespace |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| macro QT4_ADD_DBUS_INTERFACES(outfiles inputfile ... ) |
| Create the interface header and implementation files |
| for all listed interface xml files. |
| The basename will be automatically determined from the name |
| of the xml file. |
| |
| The source file properties described for |
| QT4_ADD_DBUS_INTERFACE also apply here. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| macro QT4_ADD_DBUS_ADAPTOR(outfiles xmlfile parentheader parentclassname |
| [basename] [classname]) |
| create a dbus adaptor (header and implementation file) from the xml file |
| describing the interface, and add it to the list of sources. The adaptor |
| forwards the calls to a parent class, defined in parentheader and named |
| parentclassname. The name of the generated files will be |
| <basename>adaptor.{cpp,h} where basename defaults to the basename of the |
| xml file. |
| If <classname> is provided, then it will be used as the classname of the |
| adaptor itself. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| macro QT4_GENERATE_DBUS_INTERFACE( header [interfacename] OPTIONS ...) |
| generate the xml interface file from the given header. |
| If the optional argument interfacename is omitted, the name of the |
| interface file is constructed from the basename of the header with |
| the suffix .xml appended. |
| Options may be given to qdbuscpp2xml, such as those found when |
| executing "qdbuscpp2xml \-\-help" |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| macro QT4_CREATE_TRANSLATION( qm_files directories ... sources ... |
| ts_files ... OPTIONS ...) |
| out: qm_files |
| in: directories sources ts_files |
| options: flags to pass to lupdate, such as \-extensions to specify |
| extensions for a directory scan. |
| generates commands to create .ts (via lupdate) and .qm |
| (via lrelease) \- files from directories and/or sources. The ts files are |
| created and/or updated in the source tree (unless given with full paths). |
| The qm files are generated in the build tree. |
| Updating the translations can be done by adding the qm_files |
| to the source list of your library/executable, so they are |
| always updated, or by adding a custom target to control when |
| they get updated/generated. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| macro QT4_ADD_TRANSLATION( qm_files ts_files ... ) |
| out: qm_files |
| in: ts_files |
| generates commands to create .qm from .ts \- files. The generated |
| filenames can be found in qm_files. The ts_files |
| must exist and are not updated in any way. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| macro QT4_AUTOMOC(sourcefile1 sourcefile2 ... [TARGET tgt]) |
| The qt4_automoc macro is obsolete. Use the CMAKE_AUTOMOC feature instead. |
| This macro is still experimental. |
| It can be used to have moc automatically handled. |
| So if you have the files foo.h and foo.cpp, and in foo.h a |
| a class uses the Q_OBJECT macro, moc has to run on it. If you don\(aqt |
| want to use QT4_WRAP_CPP() (which is reliable and mature), you can insert |
| #include "foo.moc" |
| in foo.cpp and then give foo.cpp as argument to QT4_AUTOMOC(). This will |
| scan all listed files at cmake\-time for such included moc files and if it |
| finds them cause a rule to be generated to run moc at build time on the |
| accompanying header file foo.h. |
| If a source file has the SKIP_AUTOMOC property set it will be ignored by |
| this macro. |
| If the <tgt> is specified, the INTERFACE_INCLUDE_DIRECTORIES and |
| INTERFACE_COMPILE_DEFINITIONS from the <tgt> are passed to moc. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| function QT4_USE_MODULES( target [link_type] modules...) |
| This function is obsolete. Use target_link_libraries with IMPORTED targets |
| instead. |
| Make <target> use the <modules> from Qt. Using a Qt module means |
| to link to the library, add the relevant include directories for the |
| module, and add the relevant compiler defines for using the module. |
| Modules are roughly equivalent to components of Qt4, so usage would be |
| something like: |
| qt4_use_modules(myexe Core Gui Declarative) |
| to use QtCore, QtGui and QtDeclarative. The optional <link_type> argument |
| can be specified as either LINK_PUBLIC or LINK_PRIVATE to specify the |
| same argument to the target_link_libraries call. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS IMPORTED Targets |
| .sp |
| A particular Qt library may be used by using the corresponding |
| \fBIMPORTED\fP target with the \fBtarget_link_libraries()\fP |
| command: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| target_link_libraries(myexe Qt4::QtGui Qt4::QtXml) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Using a target in this way causes :cmake(1)\(ga to use the appropriate include |
| directories and compile definitions for the target when compiling \fBmyexe\fP\&. |
| .sp |
| Targets are aware of their dependencies, so for example it is not necessary |
| to list \fBQt4::QtCore\fP if another Qt library is listed, and it is not |
| necessary to list \fBQt4::QtGui\fP if \fBQt4::QtDeclarative\fP is listed. |
| Targets may be tested for existence in the usual way with the |
| \fBif(TARGET)\fP command. |
| .sp |
| The Qt toolkit may contain both debug and release libraries. |
| \fBcmake(1)\fP will choose the appropriate version based on the build |
| configuration. |
| .INDENT 0.0 |
| .TP |
| .B \fBQt4::QtCore\fP |
| The QtCore target |
| .TP |
| .B \fBQt4::QtGui\fP |
| The QtGui target |
| .TP |
| .B \fBQt4::Qt3Support\fP |
| The Qt3Support target |
| .TP |
| .B \fBQt4::QtAssistant\fP |
| The QtAssistant target |
| .TP |
| .B \fBQt4::QtAssistantClient\fP |
| The QtAssistantClient target |
| .TP |
| .B \fBQt4::QAxContainer\fP |
| The QAxContainer target (Windows only) |
| .TP |
| .B \fBQt4::QAxServer\fP |
| The QAxServer target (Windows only) |
| .TP |
| .B \fBQt4::QtDBus\fP |
| The QtDBus target |
| .TP |
| .B \fBQt4::QtDeclarative\fP |
| The QtDeclarative target |
| .TP |
| .B \fBQt4::QtDesigner\fP |
| The QtDesigner target |
| .TP |
| .B \fBQt4::QtDesignerComponents\fP |
| The QtDesignerComponents target |
| .TP |
| .B \fBQt4::QtHelp\fP |
| The QtHelp target |
| .TP |
| .B \fBQt4::QtMotif\fP |
| The QtMotif target |
| .TP |
| .B \fBQt4::QtMultimedia\fP |
| The QtMultimedia target |
| .TP |
| .B \fBQt4::QtNetwork\fP |
| The QtNetwork target |
| .TP |
| .B \fBQt4::QtNsPLugin\fP |
| The QtNsPLugin target |
| .TP |
| .B \fBQt4::QtOpenGL\fP |
| The QtOpenGL target |
| .TP |
| .B \fBQt4::QtScript\fP |
| The QtScript target |
| .TP |
| .B \fBQt4::QtScriptTools\fP |
| The QtScriptTools target |
| .TP |
| .B \fBQt4::QtSql\fP |
| The QtSql target |
| .TP |
| .B \fBQt4::QtSvg\fP |
| The QtSvg target |
| .TP |
| .B \fBQt4::QtTest\fP |
| The QtTest target |
| .TP |
| .B \fBQt4::QtUiTools\fP |
| The QtUiTools target |
| .TP |
| .B \fBQt4::QtWebKit\fP |
| The QtWebKit target |
| .TP |
| .B \fBQt4::QtXml\fP |
| The QtXml target |
| .TP |
| .B \fBQt4::QtXmlPatterns\fP |
| The QtXmlPatterns target |
| .TP |
| .B \fBQt4::phonon\fP |
| The phonon target |
| .UNINDENT |
| .SS Result Variables |
| .INDENT 0.0 |
| .INDENT 3.5 |
| Below is a detailed list of variables that FindQt4.cmake sets. |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B \fBQt4_FOUND\fP |
| If false, don\(aqt try to use Qt 4. |
| .TP |
| .B \fBQT_FOUND\fP |
| If false, don\(aqt try to use Qt. This variable is for compatibility only. |
| .TP |
| .B \fBQT4_FOUND\fP |
| If false, don\(aqt try to use Qt 4. This variable is for compatibility only. |
| .TP |
| .B \fBQT_VERSION_MAJOR\fP |
| The major version of Qt found. |
| .TP |
| .B \fBQT_VERSION_MINOR\fP |
| The minor version of Qt found. |
| .TP |
| .B \fBQT_VERSION_PATCH\fP |
| The patch version of Qt found. |
| .UNINDENT |
| .SS FindQuickTime |
| .sp |
| Locate QuickTime This module defines QUICKTIME_LIBRARY |
| QUICKTIME_FOUND, if false, do not try to link to gdal |
| QUICKTIME_INCLUDE_DIR, where to find the headers |
| .sp |
| $QUICKTIME_DIR is an environment variable that would correspond to the |
| \&./configure \-\-prefix=$QUICKTIME_DIR |
| .sp |
| Created by Eric Wing. |
| .SS FindRTI |
| .sp |
| Try to find M&S HLA RTI libraries |
| .sp |
| This module finds if any HLA RTI is installed and locates the standard |
| RTI include files and libraries. |
| .sp |
| RTI is a simulation infrastructure standardized by IEEE and SISO. It |
| has a well defined C++ API that assures that simulation applications |
| are independent on a particular RTI implementation. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| http://en.wikipedia.org/wiki/Run\-Time_Infrastructure_(simulation) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This code sets the following variables: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| RTI_INCLUDE_DIR = the directory where RTI includes file are found |
| RTI_LIBRARIES = The libraries to link against to use RTI |
| RTI_DEFINITIONS = \-DRTI_USES_STD_FSTREAM |
| RTI_FOUND = Set to FALSE if any HLA RTI was not found |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Report problems to <\fI\%certi\-devel@nongnu.org\fP> |
| .SS FindRuby |
| .sp |
| Find Ruby |
| .sp |
| This module finds if Ruby is installed and determines where the |
| include files and libraries are. Ruby 1.8 through 3.1 are |
| supported. |
| .sp |
| The minimum required version of Ruby can be specified using the |
| standard syntax, e.g. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_package(Ruby 2.5.1 EXACT REQUIRED) |
| # OR |
| find_package(Ruby 2.4) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| It also determines what the name of the library is. |
| .sp |
| Virtual environments such as RVM are handled as well, by passing |
| the argument \fBRuby_FIND_VIRTUALENV\fP |
| .SS Result Variables |
| .sp |
| This module will set the following variables in your project: |
| .INDENT 0.0 |
| .TP |
| .B \fBRuby_FOUND\fP |
| set to true if ruby was found successfully |
| .TP |
| .B \fBRuby_EXECUTABLE\fP |
| full path to the ruby binary |
| .TP |
| .B \fBRuby_INCLUDE_DIRS\fP |
| include dirs to be used when using the ruby library |
| .TP |
| .B \fBRuby_LIBRARIES\fP |
| New in version 3.18: libraries needed to use ruby from C. |
| |
| .TP |
| .B \fBRuby_VERSION\fP |
| the version of ruby which was found, e.g. "1.8.7" |
| .TP |
| .B \fBRuby_VERSION_MAJOR\fP |
| Ruby major version. |
| .TP |
| .B \fBRuby_VERSION_MINOR\fP |
| Ruby minor version. |
| .TP |
| .B \fBRuby_VERSION_PATCH\fP |
| Ruby patch version. |
| .UNINDENT |
| .sp |
| Changed in version 3.18: Previous versions of CMake used the \fBRUBY_\fP prefix for all variables. |
| The following variables are provided for compatibility reasons, |
| don\(aqt use them in new code: |
| |
| .INDENT 0.0 |
| .TP |
| .B \fBRUBY_EXECUTABLE\fP |
| same as Ruby_EXECUTABLE. |
| .TP |
| .B \fBRUBY_INCLUDE_DIRS\fP |
| same as Ruby_INCLUDE_DIRS. |
| .TP |
| .B \fBRUBY_INCLUDE_PATH\fP |
| same as Ruby_INCLUDE_DIRS. |
| .TP |
| .B \fBRUBY_LIBRARY\fP |
| same as Ruby_LIBRARY. |
| .TP |
| .B \fBRUBY_VERSION\fP |
| same as Ruby_VERSION. |
| .TP |
| .B \fBRUBY_FOUND\fP |
| same as Ruby_FOUND. |
| .UNINDENT |
| .SS Hints |
| .sp |
| New in version 3.18. |
| |
| .INDENT 0.0 |
| .TP |
| .B \fBRuby_ROOT_DIR\fP |
| Define the root directory of a Ruby installation. |
| .TP |
| .B \fBRuby_FIND_VIRTUALENV\fP |
| This variable defines the handling of virtual environments managed by |
| \fBrvm\fP\&. It is meaningful only when a virtual environment |
| is active (i.e. the \fBrvm\fP script has been evaluated or at least the |
| \fBMY_RUBY_HOME\fP environment variable is set). |
| The \fBRuby_FIND_VIRTUALENV\fP variable can be set to empty or |
| one of the following: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| \fBFIRST\fP: The virtual environment is used before any other standard |
| paths to look\-up for the interpreter. This is the default. |
| .IP \(bu 2 |
| \fBONLY\fP: Only the virtual environment is used to look\-up for the |
| interpreter. |
| .IP \(bu 2 |
| \fBSTANDARD\fP: The virtual environment is not used to look\-up for the |
| interpreter (assuming it isn\(aqt still in the PATH...) |
| .UNINDENT |
| .UNINDENT |
| .SS FindSDL |
| .sp |
| Locate the SDL library |
| .SS Imported targets |
| .sp |
| New in version 3.19. |
| |
| .sp |
| This module defines the following \fBIMPORTED\fP target: |
| .INDENT 0.0 |
| .TP |
| .B \fBSDL::SDL\fP |
| The SDL library, if found |
| .UNINDENT |
| .SS Result variables |
| .sp |
| This module will set the following variables in your project: |
| .INDENT 0.0 |
| .TP |
| .B \fBSDL_INCLUDE_DIRS\fP |
| where to find SDL.h |
| .TP |
| .B \fBSDL_LIBRARIES\fP |
| the name of the library to link against |
| .TP |
| .B \fBSDL_FOUND\fP |
| if false, do not try to link to SDL |
| .TP |
| .B \fBSDL_VERSION\fP |
| the human\-readable string containing the version of SDL if found |
| .TP |
| .B \fBSDL_VERSION_MAJOR\fP |
| SDL major version |
| .TP |
| .B \fBSDL_VERSION_MINOR\fP |
| SDL minor version |
| .TP |
| .B \fBSDL_VERSION_PATCH\fP |
| SDL patch version |
| .UNINDENT |
| .sp |
| New in version 3.19: Added the \fBSDL_INCLUDE_DIRS\fP, \fBSDL_LIBRARIES\fP and \fBSDL_VERSION[_<PART>]\fP |
| variables. |
| |
| .SS Cache variables |
| .sp |
| These variables may optionally be set to help this module find the correct files: |
| .INDENT 0.0 |
| .TP |
| .B \fBSDL_INCLUDE_DIR\fP |
| where to find SDL.h |
| .TP |
| .B \fBSDL_LIBRARY\fP |
| the name of the library to link against |
| .UNINDENT |
| .SS Variables for locating SDL |
| .sp |
| This module responds to the flag: |
| .INDENT 0.0 |
| .TP |
| .B \fBSDL_BUILDING_LIBRARY\fP |
| If this is defined, then no SDL_main will be linked in because |
| only applications need main(). |
| Otherwise, it is assumed you are building an application and this |
| module will attempt to locate and set the proper link flags |
| as part of the returned SDL_LIBRARY variable. |
| .UNINDENT |
| .SS Obsolete variables |
| .sp |
| Deprecated since version 3.19. |
| |
| .sp |
| These variables are obsolete and provided for backwards compatibility: |
| .INDENT 0.0 |
| .TP |
| .B \fBSDL_VERSION_STRING\fP |
| the human\-readable string containing the version of SDL if found. |
| Identical to SDL_VERSION |
| .UNINDENT |
| .sp |
| Don\(aqt forget to include SDLmain.h and SDLmain.m your project for the |
| OS X framework based version. (Other versions link to \-lSDLmain which |
| this module will try to find on your behalf.) Also for OS X, this |
| module will automatically add the \-framework Cocoa on your behalf. |
| .sp |
| Additional Note: If you see an empty SDL_LIBRARY_TEMP in your |
| configuration and no SDL_LIBRARY, it means CMake did not find your SDL |
| library (SDL.dll, libsdl.so, SDL.framework, etc). Set |
| SDL_LIBRARY_TEMP to point to your SDL library, and configure again. |
| Similarly, if you see an empty SDLMAIN_LIBRARY, you should set this |
| value as appropriate. These values are used to generate the final |
| SDL_LIBRARY variable, but when these values are unset, SDL_LIBRARY |
| does not get created. |
| .sp |
| $SDLDIR is an environment variable that would correspond to the |
| \&./configure \-\-prefix=$SDLDIR used in building SDL. l.e.galup 9\-20\-02 |
| .sp |
| On OSX, this will prefer the Framework version (if found) over others. |
| People will have to manually change the cache values of SDL_LIBRARY to |
| override this selection or set the CMake environment |
| CMAKE_INCLUDE_PATH to modify the search paths. |
| .sp |
| Note that the header path has changed from SDL/SDL.h to just SDL.h |
| This needed to change because "proper" SDL convention is #include |
| "SDL.h", not <SDL/SDL.h>. This is done for portability reasons |
| because not all systems place things in SDL/ (see FreeBSD). |
| .SS FindSDL_image |
| .sp |
| Locate SDL_image library |
| .sp |
| This module defines: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| SDL_IMAGE_LIBRARIES, the name of the library to link against |
| SDL_IMAGE_INCLUDE_DIRS, where to find the headers |
| SDL_IMAGE_FOUND, if false, do not try to link against |
| SDL_IMAGE_VERSION_STRING \- human\-readable string containing the |
| version of SDL_image |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| For backward compatibility the following variables are also set: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| SDLIMAGE_LIBRARY (same value as SDL_IMAGE_LIBRARIES) |
| SDLIMAGE_INCLUDE_DIR (same value as SDL_IMAGE_INCLUDE_DIRS) |
| SDLIMAGE_FOUND (same value as SDL_IMAGE_FOUND) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| $SDLDIR is an environment variable that would correspond to the |
| \&./configure \-\-prefix=$SDLDIR used in building SDL. |
| .sp |
| Created by Eric Wing. This was influenced by the FindSDL.cmake |
| module, but with modifications to recognize OS X frameworks and |
| additional Unix paths (FreeBSD, etc). |
| .SS FindSDL_mixer |
| .sp |
| Locate SDL_mixer library |
| .sp |
| This module defines: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| SDL_MIXER_LIBRARIES, the name of the library to link against |
| SDL_MIXER_INCLUDE_DIRS, where to find the headers |
| SDL_MIXER_FOUND, if false, do not try to link against |
| SDL_MIXER_VERSION_STRING \- human\-readable string containing the |
| version of SDL_mixer |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| For backward compatibility the following variables are also set: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| SDLMIXER_LIBRARY (same value as SDL_MIXER_LIBRARIES) |
| SDLMIXER_INCLUDE_DIR (same value as SDL_MIXER_INCLUDE_DIRS) |
| SDLMIXER_FOUND (same value as SDL_MIXER_FOUND) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| $SDLDIR is an environment variable that would correspond to the |
| \&./configure \-\-prefix=$SDLDIR used in building SDL. |
| .sp |
| Created by Eric Wing. This was influenced by the FindSDL.cmake |
| module, but with modifications to recognize OS X frameworks and |
| additional Unix paths (FreeBSD, etc). |
| .SS FindSDL_net |
| .sp |
| Locate SDL_net library |
| .sp |
| This module defines: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| SDL_NET_LIBRARIES, the name of the library to link against |
| SDL_NET_INCLUDE_DIRS, where to find the headers |
| SDL_NET_FOUND, if false, do not try to link against |
| SDL_NET_VERSION_STRING \- human\-readable string containing the version of SDL_net |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| For backward compatibility the following variables are also set: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| SDLNET_LIBRARY (same value as SDL_NET_LIBRARIES) |
| SDLNET_INCLUDE_DIR (same value as SDL_NET_INCLUDE_DIRS) |
| SDLNET_FOUND (same value as SDL_NET_FOUND) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| $SDLDIR is an environment variable that would correspond to the |
| \&./configure \-\-prefix=$SDLDIR used in building SDL. |
| .sp |
| Created by Eric Wing. This was influenced by the FindSDL.cmake |
| module, but with modifications to recognize OS X frameworks and |
| additional Unix paths (FreeBSD, etc). |
| .SS FindSDL_sound |
| .sp |
| Locates the SDL_sound library |
| .sp |
| This module depends on SDL being found and must be called AFTER |
| FindSDL.cmake is called. |
| .sp |
| This module defines |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| SDL_SOUND_INCLUDE_DIR, where to find SDL_sound.h |
| SDL_SOUND_FOUND, if false, do not try to link to SDL_sound |
| SDL_SOUND_LIBRARIES, this contains the list of libraries that you need |
| to link against. |
| SDL_SOUND_EXTRAS, this is an optional variable for you to add your own |
| flags to SDL_SOUND_LIBRARIES. This is prepended to SDL_SOUND_LIBRARIES. |
| This is available mostly for cases this module failed to anticipate for |
| and you must add additional flags. This is marked as ADVANCED. |
| SDL_SOUND_VERSION_STRING, human\-readable string containing the |
| version of SDL_sound |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This module also defines (but you shouldn\(aqt need to use directly) |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| SDL_SOUND_LIBRARY, the name of just the SDL_sound library you would link |
| against. Use SDL_SOUND_LIBRARIES for you link instructions and not this one. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| And might define the following as needed |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| MIKMOD_LIBRARY |
| MODPLUG_LIBRARY |
| OGG_LIBRARY |
| VORBIS_LIBRARY |
| SMPEG_LIBRARY |
| FLAC_LIBRARY |
| SPEEX_LIBRARY |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Typically, you should not use these variables directly, and you should |
| use SDL_SOUND_LIBRARIES which contains SDL_SOUND_LIBRARY and the other |
| audio libraries (if needed) to successfully compile on your system. |
| .sp |
| Created by Eric Wing. This module is a bit more complicated than the |
| other FindSDL* family modules. The reason is that SDL_sound can be |
| compiled in a large variety of different ways which are independent of |
| platform. SDL_sound may dynamically link against other 3rd party |
| libraries to get additional codec support, such as Ogg Vorbis, SMPEG, |
| ModPlug, MikMod, FLAC, Speex, and potentially others. Under some |
| circumstances which I don\(aqt fully understand, there seems to be a |
| requirement that dependent libraries of libraries you use must also be |
| explicitly linked against in order to successfully compile. SDL_sound |
| does not currently have any system in place to know how it was |
| compiled. So this CMake module does the hard work in trying to |
| discover which 3rd party libraries are required for building (if any). |
| This module uses a brute force approach to create a test program that |
| uses SDL_sound, and then tries to build it. If the build fails, it |
| parses the error output for known symbol names to figure out which |
| libraries are needed. |
| .sp |
| Responds to the $SDLDIR and $SDLSOUNDDIR environmental variable that |
| would correspond to the ./configure \-\-prefix=$SDLDIR used in building |
| SDL. |
| .sp |
| On OSX, this will prefer the Framework version (if found) over others. |
| People will have to manually change the cache values of SDL_LIBRARY to |
| override this selectionor set the CMake environment CMAKE_INCLUDE_PATH |
| to modify the search paths. |
| .SS FindSDL_ttf |
| .sp |
| Locate SDL_ttf library |
| .sp |
| This module defines: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| SDL_TTF_LIBRARIES, the name of the library to link against |
| SDL_TTF_INCLUDE_DIRS, where to find the headers |
| SDL_TTF_FOUND, if false, do not try to link against |
| SDL_TTF_VERSION_STRING \- human\-readable string containing the version of SDL_ttf |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| For backward compatibility the following variables are also set: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| SDLTTF_LIBRARY (same value as SDL_TTF_LIBRARIES) |
| SDLTTF_INCLUDE_DIR (same value as SDL_TTF_INCLUDE_DIRS) |
| SDLTTF_FOUND (same value as SDL_TTF_FOUND) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| $SDLDIR is an environment variable that would correspond to the |
| \&./configure \-\-prefix=$SDLDIR used in building SDL. |
| .sp |
| Created by Eric Wing. This was influenced by the FindSDL.cmake |
| module, but with modifications to recognize OS X frameworks and |
| additional Unix paths (FreeBSD, etc). |
| .SS FindSelfPackers |
| .sp |
| Find upx |
| .sp |
| This module looks for some executable packers (i.e. software that |
| compress executables or shared libs into on\-the\-fly self\-extracting |
| executables or shared libs. Examples: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| UPX: http://wildsau.idv.uni\-linz.ac.at/mfx/upx.html |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindSquish |
| .sp |
| \-\- Typical Use |
| .sp |
| This module can be used to find Squish. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| SQUISH_FOUND If false, don\(aqt try to use Squish |
| SQUISH_VERSION The full version of Squish found |
| SQUISH_VERSION_MAJOR The major version of Squish found |
| SQUISH_VERSION_MINOR The minor version of Squish found |
| SQUISH_VERSION_PATCH The patch version of Squish found |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| SQUISH_INSTALL_DIR The Squish installation directory |
| (containing bin, lib, etc) |
| SQUISH_SERVER_EXECUTABLE The squishserver executable |
| SQUISH_CLIENT_EXECUTABLE The squishrunner executable |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| SQUISH_INSTALL_DIR_FOUND Was the install directory found? |
| SQUISH_SERVER_EXECUTABLE_FOUND Was the server executable found? |
| SQUISH_CLIENT_EXECUTABLE_FOUND Was the client executable found? |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| It provides the function squish_add_test() for adding a squish test |
| to cmake using Squish >= 4.x: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| squish_add_test(cmakeTestName |
| AUT targetName SUITE suiteName TEST squishTestName |
| [SETTINGSGROUP group] [PRE_COMMAND command] [POST_COMMAND command] ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Changed in version 3.18: In previous CMake versions, this function was named \fBsquish_v4_add_test\fP\&. |
| |
| .sp |
| The arguments have the following meaning: |
| .INDENT 0.0 |
| .TP |
| .B \fBcmakeTestName\fP |
| this will be used as the first argument for add_test() |
| .TP |
| .B \fBAUT targetName\fP |
| the name of the cmake target which will be used as AUT, i.e. the |
| executable which will be tested. |
| .TP |
| .B \fBSUITE suiteName\fP |
| this is either the full path to the squish suite, or just the |
| last directory of the suite, i.e. the suite name. In this case |
| the CMakeLists.txt which calls squish_add_test() must be located |
| in the parent directory of the suite directory. |
| .TP |
| .B \fBTEST squishTestName\fP |
| the name of the squish test, i.e. the name of the subdirectory |
| of the test inside the suite directory. |
| .TP |
| .B \fBSETTINGSGROUP group\fP |
| deprecated, this argument will be ignored. |
| .TP |
| .B \fBPRE_COMMAND command\fP |
| if specified, the given command will be executed before starting the squish test. |
| .TP |
| .B \fBPOST_COMMAND command\fP |
| same as PRE_COMMAND, but after the squish test has been executed. |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| enable_testing() |
| find_package(Squish 6.5) |
| if (SQUISH_FOUND) |
| squish_add_test(myTestName |
| AUT myApp |
| SUITE ${CMAKE_SOURCE_DIR}/tests/mySuite |
| TEST someSquishTest |
| ) |
| endif () |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| For users of Squish version 3.x the macro squish_v3_add_test() is |
| provided: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| squish_v3_add_test(testName applicationUnderTest testCase envVars testWrapper) |
| Use this macro to add a test using Squish 3.x. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| enable_testing() |
| find_package(Squish 3.0) |
| if (SQUISH_FOUND) |
| squish_v3_add_test(myTestName myApplication testCase envVars testWrapper) |
| endif () |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindSQLite3 |
| .sp |
| New in version 3.14. |
| |
| .sp |
| Find the SQLite libraries, v3 |
| .SS IMPORTED targets |
| .sp |
| This module defines the following \fBIMPORTED\fP target: |
| .sp |
| \fBSQLite::SQLite3\fP |
| .SS Result variables |
| .sp |
| This module will set the following variables if found: |
| .INDENT 0.0 |
| .TP |
| .B \fBSQLite3_INCLUDE_DIRS\fP |
| where to find sqlite3.h, etc. |
| .TP |
| .B \fBSQLite3_LIBRARIES\fP |
| the libraries to link against to use SQLite3. |
| .TP |
| .B \fBSQLite3_VERSION\fP |
| version of the SQLite3 library found |
| .TP |
| .B \fBSQLite3_FOUND\fP |
| TRUE if found |
| .UNINDENT |
| .SS FindSubversion |
| .sp |
| Extract information from a subversion working copy |
| .sp |
| The module defines the following variables: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| Subversion_SVN_EXECUTABLE \- path to svn command line client |
| Subversion_VERSION_SVN \- version of svn command line client |
| Subversion_FOUND \- true if the command line client was found |
| SUBVERSION_FOUND \- same as Subversion_FOUND, set for compatibility reasons |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The minimum required version of Subversion can be specified using the |
| standard syntax, e.g. \fBfind_package(Subversion 1.4)\fP\&. |
| .sp |
| If the command line client executable is found two macros are defined: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| Subversion_WC_INFO(<dir> <var\-prefix> [IGNORE_SVN_FAILURE]) |
| Subversion_WC_LOG(<dir> <var\-prefix>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBSubversion_WC_INFO\fP extracts information of a subversion working copy at a |
| given location. This macro defines the following variables if running |
| Subversion\(aqs \fBinfo\fP command on \fB<dir>\fP succeeds; otherwise a |
| \fBSEND_ERROR\fP message is generated. |
| .sp |
| New in version 3.13: The error can be ignored by providing the |
| \fBIGNORE_SVN_FAILURE\fP option, which causes these variables to remain |
| undefined. |
| |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| <var\-prefix>_WC_URL \- url of the repository (at <dir>) |
| <var\-prefix>_WC_ROOT \- root url of the repository |
| <var\-prefix>_WC_REVISION \- current revision |
| <var\-prefix>_WC_LAST_CHANGED_AUTHOR \- author of last commit |
| <var\-prefix>_WC_LAST_CHANGED_DATE \- date of last commit |
| <var\-prefix>_WC_LAST_CHANGED_REV \- revision of last commit |
| <var\-prefix>_WC_INFO \- output of command \(gasvn info <dir>\(aq |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBSubversion_WC_LOG\fP retrieves the log message of the base revision of a |
| subversion working copy at a given location. This macro defines the variable: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| <var\-prefix>_LAST_CHANGED_LOG \- last log of base revision |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Example usage: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_package(Subversion) |
| if(SUBVERSION_FOUND) |
| Subversion_WC_INFO(${PROJECT_SOURCE_DIR} Project) |
| message("Current revision is ${Project_WC_REVISION}") |
| Subversion_WC_LOG(${PROJECT_SOURCE_DIR} Project) |
| message("Last changed log is ${Project_LAST_CHANGED_LOG}") |
| endif() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindSWIG |
| .sp |
| Find the Simplified Wrapper and Interface Generator (\fI\%SWIG\fP) executable. |
| .sp |
| This module finds an installed SWIG and determines its version. |
| .sp |
| New in version 3.18: If a \fBCOMPONENTS\fP or \fBOPTIONAL_COMPONENTS\fP argument is given to the |
| \fBfind_package()\fP command, it will also determine supported target |
| languages. |
| |
| .sp |
| New in version 3.19: When a version is requested, it can be specified as a simple value or as a |
| range. For a detailed description of version range usage and capabilities, |
| refer to the \fBfind_package()\fP command. |
| |
| .sp |
| The module defines the following variables: |
| .INDENT 0.0 |
| .TP |
| .B \fBSWIG_FOUND\fP |
| Whether SWIG and any required components were found on the system. |
| .TP |
| .B \fBSWIG_EXECUTABLE\fP |
| Path to the SWIG executable. |
| .TP |
| .B \fBSWIG_DIR\fP |
| Path to the installed SWIG \fBLib\fP directory (result of \fBswig \-swiglib\fP). |
| .TP |
| .B \fBSWIG_VERSION\fP |
| SWIG executable version (result of \fBswig \-version\fP). |
| .TP |
| .B \fBSWIG_<lang>_FOUND\fP |
| If \fBCOMPONENTS\fP or \fBOPTIONAL_COMPONENTS\fP are requested, each available |
| target language \fB<lang>\fP (lowercase) will be set to TRUE. |
| .UNINDENT |
| .sp |
| Any \fBCOMPONENTS\fP given to \fBfind_package\fP should be the names of supported |
| target languages as provided to the LANGUAGE argument of \fBswig_add_library\fP, |
| such as \fBpython\fP or \fBperl5\fP\&. Language names \fImust\fP be lowercase. |
| .sp |
| All information is collected from the \fBSWIG_EXECUTABLE\fP, so the version |
| to be found can be changed from the command line by means of setting |
| \fBSWIG_EXECUTABLE\fP\&. |
| .sp |
| Example usage requiring SWIG 4.0 or higher and Python language support, with |
| optional Fortran support: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_package(SWIG 4.0 COMPONENTS python OPTIONAL_COMPONENTS fortran) |
| if(SWIG_FOUND) |
| message("SWIG found: ${SWIG_EXECUTABLE}") |
| if(NOT SWIG_fortran_FOUND) |
| message(WARNING "SWIG Fortran bindings cannot be generated") |
| endif() |
| endif() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindTCL |
| .sp |
| TK_INTERNAL_PATH was removed. |
| .sp |
| This module finds if Tcl is installed and determines where the include |
| files and libraries are. It also determines what the name of the |
| library is. This code sets the following variables: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| TCL_FOUND = Tcl was found |
| TK_FOUND = Tk was found |
| TCLTK_FOUND = Tcl and Tk were found |
| TCL_LIBRARY = path to Tcl library (tcl tcl80) |
| TCL_INCLUDE_PATH = path to where tcl.h can be found |
| TCL_TCLSH = path to tclsh binary (tcl tcl80) |
| TK_LIBRARY = path to Tk library (tk tk80 etc) |
| TK_INCLUDE_PATH = path to where tk.h can be found |
| TK_WISH = full path to the wish executable |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| In an effort to remove some clutter and clear up some issues for |
| people who are not necessarily Tcl/Tk gurus/developers, some |
| variables were moved or removed. Changes compared to CMake 2.4 are: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| => they were only useful for people writing Tcl/Tk extensions. |
| => these libs are not packaged by default with Tcl/Tk distributions. |
| Even when Tcl/Tk is built from source, several flavors of debug libs |
| are created and there is no real reason to pick a single one |
| specifically (say, amongst tcl84g, tcl84gs, or tcl84sgx). |
| Let\(aqs leave that choice to the user by allowing him to assign |
| TCL_LIBRARY to any Tcl library, debug or not. |
| => this ended up being only a Win32 variable, and there is a lot of |
| confusion regarding the location of this file in an installed Tcl/Tk |
| tree anyway (see 8.5 for example). If you need the internal path at |
| this point it is safer you ask directly where the *source* tree is |
| and dig from there. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindTclsh |
| .sp |
| Find tclsh |
| .sp |
| This module finds if TCL is installed and determines where the include |
| files and libraries are. It also determines what the name of the |
| library is. This code sets the following variables: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| TCLSH_FOUND = TRUE if tclsh has been found |
| TCL_TCLSH = the path to the tclsh executable |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindTclStub |
| .sp |
| TCL_STUB_LIBRARY_DEBUG and TK_STUB_LIBRARY_DEBUG were removed. |
| .sp |
| This module finds Tcl stub libraries. It first finds Tcl include |
| files and libraries by calling FindTCL.cmake. How to Use the Tcl |
| Stubs Library: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| http://tcl.activestate.com/doc/howto/stubs.html |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Using Stub Libraries: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| http://safari.oreilly.com/0130385603/ch48lev1sec3 |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This code sets the following variables: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| TCL_STUB_LIBRARY = path to Tcl stub library |
| TK_STUB_LIBRARY = path to Tk stub library |
| TTK_STUB_LIBRARY = path to ttk stub library |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| In an effort to remove some clutter and clear up some issues for |
| people who are not necessarily Tcl/Tk gurus/developers, some |
| variables were moved or removed. Changes compared to CMake 2.4 are: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| => these libs are not packaged by default with Tcl/Tk distributions. |
| Even when Tcl/Tk is built from source, several flavors of debug libs |
| are created and there is no real reason to pick a single one |
| specifically (say, amongst tclstub84g, tclstub84gs, or tclstub84sgx). |
| Let\(aqs leave that choice to the user by allowing him to assign |
| TCL_STUB_LIBRARY to any Tcl library, debug or not. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindThreads |
| .sp |
| This module determines the thread library of the system. |
| .SS Imported Targets |
| .sp |
| New in version 3.1. |
| |
| .sp |
| This module defines the following \fBIMPORTED\fP target: |
| .INDENT 0.0 |
| .TP |
| .B \fBThreads::Threads\fP |
| The thread library, if found. |
| .UNINDENT |
| .SS Result Variables |
| .sp |
| The following variables are set: |
| .INDENT 0.0 |
| .TP |
| .B \fBThreads_FOUND\fP |
| If a supported thread library was found. |
| .TP |
| .B \fBCMAKE_THREAD_LIBS_INIT\fP |
| The thread library to use. This may be empty if the thread functions |
| are provided by the system libraries and no special flags are needed |
| to use them. |
| .TP |
| .B \fBCMAKE_USE_WIN32_THREADS_INIT\fP |
| If the found thread library is the win32 one. |
| .TP |
| .B \fBCMAKE_USE_PTHREADS_INIT\fP |
| If the found thread library is pthread compatible. |
| .TP |
| .B \fBCMAKE_HP_PTHREADS_INIT\fP |
| If the found thread library is the HP thread library. |
| .UNINDENT |
| .SS Variables Affecting Behavior |
| .INDENT 0.0 |
| .TP |
| .B THREADS_PREFER_PTHREAD_FLAG |
| New in version 3.1. |
| |
| .sp |
| If the use of the \-pthread compiler and linker flag is preferred then |
| the caller can set this variable to TRUE. The compiler flag can only be |
| used with the imported target. Use of both the imported target as well |
| as this switch is highly recommended for new code. |
| .sp |
| This variable has no effect if the system libraries provide the |
| thread functions, i.e. when \fBCMAKE_THREAD_LIBS_INIT\fP will be empty. |
| .UNINDENT |
| .SS FindTIFF |
| .sp |
| Find the TIFF library (\fBlibtiff\fP, \fI\%https://libtiff.gitlab.io/libtiff/\fP). |
| .SS Optional COMPONENTS |
| .sp |
| This module supports the optional component \fICXX\fP, for use with the COMPONENTS |
| argument of the \fBfind_package()\fP command. This component has an associated |
| imported target, as described below. |
| .SS Imported targets |
| .sp |
| New in version 3.5. |
| |
| .sp |
| This module defines the following \fBIMPORTED\fP targets: |
| .INDENT 0.0 |
| .TP |
| .B \fBTIFF::TIFF\fP |
| The TIFF library, if found. |
| .TP |
| .B \fBTIFF::CXX\fP |
| New in version 3.19. |
| |
| .sp |
| The C++ wrapper libtiffxx, if requested by the \fICOMPONENTS CXX\fP option, |
| if the compiler is not MSVC (which includes the C++ wrapper in libtiff), |
| and if found. |
| .UNINDENT |
| .SS Result variables |
| .sp |
| This module will set the following variables in your project: |
| .INDENT 0.0 |
| .TP |
| .B \fBTIFF_FOUND\fP |
| true if the TIFF headers and libraries were found |
| .TP |
| .B \fBTIFF_INCLUDE_DIR\fP |
| the directory containing the TIFF headers |
| .TP |
| .B \fBTIFF_INCLUDE_DIRS\fP |
| the directory containing the TIFF headers |
| .TP |
| .B \fBTIFF_LIBRARIES\fP |
| TIFF libraries to be linked |
| .UNINDENT |
| .SS Cache variables |
| .sp |
| The following cache variables may also be set: |
| .INDENT 0.0 |
| .TP |
| .B \fBTIFF_INCLUDE_DIR\fP |
| the directory containing the TIFF headers |
| .TP |
| .B \fBTIFF_LIBRARY_RELEASE\fP |
| the path to the TIFF library for release configurations |
| .TP |
| .B \fBTIFF_LIBRARY_DEBUG\fP |
| the path to the TIFF library for debug configurations |
| .TP |
| .B \fBTIFFXX_LIBRARY_RELEASE\fP |
| the path to the TIFFXX library for release configurations |
| .TP |
| .B \fBTIFFXX_LIBRARY_DEBUG\fP |
| the path to the TIFFXX library for debug configurations |
| .UNINDENT |
| .sp |
| New in version 3.4: Debug and Release variants are found separately. |
| |
| .SS FindUnixCommands |
| .sp |
| Find Unix commands, including the ones from Cygwin |
| .sp |
| This module looks for the Unix commands \fBbash\fP, \fBcp\fP, \fBgzip\fP, |
| \fBmv\fP, \fBrm\fP, and \fBtar\fP and stores the result in the variables |
| \fBBASH\fP, \fBCP\fP, \fBGZIP\fP, \fBMV\fP, \fBRM\fP, and \fBTAR\fP\&. |
| .SS FindVTK |
| .sp |
| This module no longer exists. |
| .sp |
| This module existed in versions of CMake prior to 3.1, but became |
| only a thin wrapper around \fBfind_package(VTK NO_MODULE)\fP to |
| provide compatibility for projects using long\-outdated conventions. |
| Now \fBfind_package(VTK)\fP will search for \fBVTKConfig.cmake\fP |
| directly. |
| .SS FindVulkan |
| .sp |
| New in version 3.7. |
| |
| .sp |
| Find Vulkan, which is a low\-overhead, cross\-platform 3D graphics |
| and computing API. |
| .SS IMPORTED Targets |
| .sp |
| This module defines \fBIMPORTED\fP targets if Vulkan has been found: |
| .INDENT 0.0 |
| .TP |
| .B \fBVulkan::Vulkan\fP |
| The main Vulkan library. |
| .TP |
| .B \fBVulkan::glslc\fP |
| New in version 3.19. |
| |
| .sp |
| The GLSLC SPIR\-V compiler, if it has been found. |
| .TP |
| .B \fBVulkan::Headers\fP |
| New in version 3.21. |
| |
| .sp |
| Provides just Vulkan headers include paths, if found. No library is |
| included in this target. This can be useful for applications that |
| load Vulkan library dynamically. |
| .TP |
| .B \fBVulkan::glslangValidator\fP |
| New in version 3.21. |
| |
| .sp |
| The glslangValidator tool, if found. It is used to compile GLSL and |
| HLSL shaders into SPIR\-V. |
| .UNINDENT |
| .SS Result Variables |
| .sp |
| This module defines the following variables: |
| .INDENT 0.0 |
| .TP |
| .B \fBVulkan_FOUND\fP |
| set to true if Vulkan was found |
| .TP |
| .B \fBVulkan_INCLUDE_DIRS\fP |
| include directories for Vulkan |
| .TP |
| .B \fBVulkan_LIBRARIES\fP |
| link against this library to use Vulkan |
| .TP |
| .B \fBVulkan_VERSION\fP |
| New in version 3.23. |
| |
| .sp |
| value from \fBvulkan/vulkan_core.h\fP |
| .UNINDENT |
| .sp |
| The module will also defines these cache variables: |
| .INDENT 0.0 |
| .TP |
| .B \fBVulkan_INCLUDE_DIR\fP |
| the Vulkan include directory |
| .TP |
| .B \fBVulkan_LIBRARY\fP |
| the path to the Vulkan library |
| .TP |
| .B \fBVulkan_GLSLC_EXECUTABLE\fP |
| the path to the GLSL SPIR\-V compiler |
| .TP |
| .B \fBVulkan_GLSLANG_VALIDATOR_EXECUTABLE\fP |
| the path to the glslangValidator tool |
| .UNINDENT |
| .SS Hints |
| .sp |
| New in version 3.18. |
| |
| .sp |
| The \fBVULKAN_SDK\fP environment variable optionally specifies the |
| location of the Vulkan SDK root directory for the given |
| architecture. It is typically set by sourcing the toplevel |
| \fBsetup\-env.sh\fP script of the Vulkan SDK directory into the shell |
| environment. |
| .SS FindWget |
| .sp |
| Find wget |
| .sp |
| This module looks for wget. This module defines the following values: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| WGET_EXECUTABLE: the full path to the wget tool. |
| WGET_FOUND: True if wget has been found. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindWish |
| .sp |
| Find wish installation |
| .sp |
| This module finds if TCL is installed and determines where the include |
| files and libraries are. It also determines what the name of the |
| library is. This code sets the following variables: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| TK_WISH = the path to the wish executable |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| if UNIX is defined, then it will look for the cygwin version first |
| .SS FindwxWidgets |
| .sp |
| Find a wxWidgets (a.k.a., wxWindows) installation. |
| .sp |
| This module finds if wxWidgets is installed and selects a default |
| configuration to use. wxWidgets is a modular library. To specify the |
| modules that you will use, you need to name them as components to the |
| package: |
| .sp |
| find_package(wxWidgets COMPONENTS core base ... OPTIONAL_COMPONENTS net ...) |
| .sp |
| New in version 3.4: Support for \fBfind_package()\fP version argument; \fBwebview\fP component. |
| |
| .sp |
| New in version 3.14: \fBOPTIONAL_COMPONENTS\fP support. |
| |
| .sp |
| There are two search branches: a windows style and a unix style. For |
| windows, the following variables are searched for and set to defaults |
| in case of multiple choices. Change them if the defaults are not |
| desired (i.e., these are the only variables you should change to |
| select a configuration): |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| wxWidgets_ROOT_DIR \- Base wxWidgets directory |
| (e.g., C:/wxWidgets\-2.6.3). |
| wxWidgets_LIB_DIR \- Path to wxWidgets libraries |
| (e.g., C:/wxWidgets\-2.6.3/lib/vc_lib). |
| wxWidgets_CONFIGURATION \- Configuration to use |
| (e.g., msw, mswd, mswu, mswunivud, etc.) |
| wxWidgets_EXCLUDE_COMMON_LIBRARIES |
| \- Set to TRUE to exclude linking of |
| commonly required libs (e.g., png tiff |
| jpeg zlib regex expat). |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| For unix style it uses the wx\-config utility. You can select between |
| debug/release, unicode/ansi, universal/non\-universal, and |
| static/shared in the QtDialog or ccmake interfaces by turning ON/OFF |
| the following variables: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| wxWidgets_USE_DEBUG |
| wxWidgets_USE_UNICODE |
| wxWidgets_USE_UNIVERSAL |
| wxWidgets_USE_STATIC |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| There is also a wxWidgets_CONFIG_OPTIONS variable for all other |
| options that need to be passed to the wx\-config utility. For example, |
| to use the base toolkit found in the /usr/local path, set the variable |
| (before calling the FIND_PACKAGE command) as such: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(wxWidgets_CONFIG_OPTIONS \-\-toolkit=base \-\-prefix=/usr) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The following are set after the configuration is done for both windows |
| and unix style: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| wxWidgets_FOUND \- Set to TRUE if wxWidgets was found. |
| wxWidgets_INCLUDE_DIRS \- Include directories for WIN32 |
| i.e., where to find "wx/wx.h" and |
| "wx/setup.h"; possibly empty for unices. |
| wxWidgets_LIBRARIES \- Path to the wxWidgets libraries. |
| wxWidgets_LIBRARY_DIRS \- compile time link dirs, useful for |
| rpath on UNIX. Typically an empty string |
| in WIN32 environment. |
| wxWidgets_DEFINITIONS \- Contains defines required to compile/link |
| against WX, e.g. WXUSINGDLL |
| wxWidgets_DEFINITIONS_DEBUG\- Contains defines required to compile/link |
| against WX debug builds, e.g. __WXDEBUG__ |
| wxWidgets_CXX_FLAGS \- Include dirs and compiler flags for |
| unices, empty on WIN32. Essentially |
| "\(gawx\-config \-\-cxxflags\(ga". |
| wxWidgets_USE_FILE \- Convenience include file. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.11: The following environment variables can be used as hints: \fBWX_CONFIG\fP, |
| \fBWXRC_CMD\fP\&. |
| |
| .sp |
| Sample usage: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| # Note that for MinGW users the order of libs is important! |
| find_package(wxWidgets COMPONENTS gl core base OPTIONAL_COMPONENTS net) |
| if(wxWidgets_FOUND) |
| include(${wxWidgets_USE_FILE}) |
| # and for each of your dependent executable/library targets: |
| target_link_libraries(<YourTarget> ${wxWidgets_LIBRARIES}) |
| endif() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| If wxWidgets is required (i.e., not an optional part): |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_package(wxWidgets REQUIRED gl core base OPTIONAL_COMPONENTS net) |
| include(${wxWidgets_USE_FILE}) |
| # and for each of your dependent executable/library targets: |
| target_link_libraries(<YourTarget> ${wxWidgets_LIBRARIES}) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindX11 |
| .sp |
| Find X11 installation |
| .sp |
| Try to find X11 on UNIX systems. The following values are defined |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| X11_FOUND \- True if X11 is available |
| X11_INCLUDE_DIR \- include directories to use X11 |
| X11_LIBRARIES \- link against these to use X11 |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| and also the following more fine grained variables and targets: |
| .sp |
| New in version 3.14: Imported targets. |
| |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| X11_ICE_INCLUDE_PATH, X11_ICE_LIB, X11_ICE_FOUND, X11::ICE |
| X11_SM_INCLUDE_PATH, X11_SM_LIB, X11_SM_FOUND, X11::SM |
| X11_X11_INCLUDE_PATH, X11_X11_LIB, X11::X11 |
| X11_Xaccessrules_INCLUDE_PATH, |
| X11_Xaccessstr_INCLUDE_PATH, X11_Xaccess_FOUND |
| X11_Xau_INCLUDE_PATH, X11_Xau_LIB, X11_Xau_FOUND, X11::Xau |
| X11_xcb_INCLUDE_PATH, X11_xcb_LIB, X11_xcb_FOUND, X11::xcb |
| X11_X11_xcb_INCLUDE_PATH, X11_X11_xcb_LIB, X11_X11_xcb_FOUND, X11::X11_xcb |
| X11_xcb_icccm_INCLUDE_PATH, X11_xcb_icccm_LIB, X11_xcb_icccm_FOUND, X11::xcb_icccm |
| X11_xcb_util_INCLUDE_PATH, X11_xcb_util_LIB, X11_xcb_util_FOUND, X11::xcb_util |
| X11_xcb_xfixes_INCLUDE_PATH, X11_xcb_xfixes_LIB, X11_xcb_xfixes_FOUND, X11::xcb_xfixes |
| X11_xcb_xkb_INCLUDE_PATH, X11_xcb_xkb_LIB, X11_xcb_xkb_FOUND, X11::xcb_xkb |
| X11_Xcomposite_INCLUDE_PATH, X11_Xcomposite_LIB, X11_Xcomposite_FOUND, X11::Xcomposite |
| X11_Xcursor_INCLUDE_PATH, X11_Xcursor_LIB, X11_Xcursor_FOUND, X11::Xcursor |
| X11_Xdamage_INCLUDE_PATH, X11_Xdamage_LIB, X11_Xdamage_FOUND, X11::Xdamage |
| X11_Xdmcp_INCLUDE_PATH, X11_Xdmcp_LIB, X11_Xdmcp_FOUND, X11::Xdmcp |
| X11_Xext_INCLUDE_PATH, X11_Xext_LIB, X11_Xext_FOUND, X11::Xext |
| X11_Xxf86misc_INCLUDE_PATH, X11_Xxf86misc_LIB, X11_Xxf86misc_FOUND, X11::Xxf86misc |
| X11_Xxf86vm_INCLUDE_PATH, X11_Xxf86vm_LIB X11_Xxf86vm_FOUND, X11::Xxf86vm |
| X11_Xfixes_INCLUDE_PATH, X11_Xfixes_LIB, X11_Xfixes_FOUND, X11::Xfixes |
| X11_Xft_INCLUDE_PATH, X11_Xft_LIB, X11_Xft_FOUND, X11::Xft |
| X11_Xi_INCLUDE_PATH, X11_Xi_LIB, X11_Xi_FOUND, X11::Xi |
| X11_Xinerama_INCLUDE_PATH, X11_Xinerama_LIB, X11_Xinerama_FOUND, X11::Xinerama |
| X11_Xkb_INCLUDE_PATH, |
| X11_Xkblib_INCLUDE_PATH, X11_Xkb_FOUND, X11::Xkb |
| X11_xkbcommon_INCLUDE_PATH, X11_xkbcommon_LIB, X11_xkbcommon_FOUND, X11::xkbcommon |
| X11_xkbcommon_X11_INCLUDE_PATH,X11_xkbcommon_X11_LIB,X11_xkbcommon_X11_FOUND,X11::xkbcommon_X11 |
| X11_xkbfile_INCLUDE_PATH, X11_xkbfile_LIB, X11_xkbfile_FOUND, X11::xkbfile |
| X11_Xmu_INCLUDE_PATH, X11_Xmu_LIB, X11_Xmu_FOUND, X11::Xmu |
| X11_Xpm_INCLUDE_PATH, X11_Xpm_LIB, X11_Xpm_FOUND, X11::Xpm |
| X11_Xtst_INCLUDE_PATH, X11_Xtst_LIB, X11_Xtst_FOUND, X11::Xtst |
| X11_Xrandr_INCLUDE_PATH, X11_Xrandr_LIB, X11_Xrandr_FOUND, X11::Xrandr |
| X11_Xrender_INCLUDE_PATH, X11_Xrender_LIB, X11_Xrender_FOUND, X11::Xrender |
| X11_XRes_INCLUDE_PATH, X11_XRes_LIB, X11_XRes_FOUND, X11::XRes |
| X11_Xss_INCLUDE_PATH, X11_Xss_LIB, X11_Xss_FOUND, X11::Xss |
| X11_Xt_INCLUDE_PATH, X11_Xt_LIB, X11_Xt_FOUND, X11::Xt |
| X11_Xutil_INCLUDE_PATH, X11_Xutil_FOUND, X11::Xutil |
| X11_Xv_INCLUDE_PATH, X11_Xv_LIB, X11_Xv_FOUND, X11::Xv |
| X11_dpms_INCLUDE_PATH, (in X11_Xext_LIB), X11_dpms_FOUND |
| X11_XShm_INCLUDE_PATH, (in X11_Xext_LIB), X11_XShm_FOUND |
| X11_Xshape_INCLUDE_PATH, (in X11_Xext_LIB), X11_Xshape_FOUND |
| X11_XSync_INCLUDE_PATH, (in X11_Xext_LIB), X11_XSync_FOUND |
| X11_Xaw_INCLUDE_PATH, X11_Xaw_LIB X11_Xaw_FOUND X11::Xaw |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.14: Renamed \fBXxf86misc\fP, \fBX11_Xxf86misc\fP, \fBX11_Xxf86vm\fP, \fBX11_xkbfile\fP, |
| \fBX11_Xtst\fP, and \fBX11_Xss\fP libraries to match their file names. |
| Deprecated the \fBX11_Xinput\fP library. Old names are still available |
| for compatibility. |
| |
| .sp |
| New in version 3.14: Added the \fBX11_Xext_INCLUDE_PATH\fP variable. |
| |
| .sp |
| New in version 3.18: Added the \fBxcb\fP, \fBX11\-xcb\fP, \fBxcb\-icccm\fP, \fBxcb\-xkb\fP, \fBxkbcommon\fP, |
| and \fBxkbcommon\-X11\fP libraries. |
| |
| .sp |
| New in version 3.19: Added the \fBXaw\fP, \fBxcb_util\fP, and \fBxcb_xfixes\fP libraries. |
| |
| .SS FindXalanC |
| .sp |
| New in version 3.5. |
| |
| .sp |
| Find the Apache Xalan\-C++ XSL transform processor headers and libraries. |
| .SS Imported targets |
| .sp |
| This module defines the following \fBIMPORTED\fP targets: |
| .INDENT 0.0 |
| .TP |
| .B \fBXalanC::XalanC\fP |
| The Xalan\-C++ \fBxalan\-c\fP library, if found. |
| .UNINDENT |
| .SS Result variables |
| .sp |
| This module will set the following variables in your project: |
| .INDENT 0.0 |
| .TP |
| .B \fBXalanC_FOUND\fP |
| true if the Xalan headers and libraries were found |
| .TP |
| .B \fBXalanC_VERSION\fP |
| Xalan release version |
| .TP |
| .B \fBXalanC_INCLUDE_DIRS\fP |
| the directory containing the Xalan headers; note |
| \fBXercesC_INCLUDE_DIRS\fP is also required |
| .TP |
| .B \fBXalanC_LIBRARIES\fP |
| Xalan libraries to be linked; note \fBXercesC_LIBRARIES\fP is also |
| required |
| .UNINDENT |
| .SS Cache variables |
| .sp |
| The following cache variables may also be set: |
| .INDENT 0.0 |
| .TP |
| .B \fBXalanC_INCLUDE_DIR\fP |
| the directory containing the Xalan headers |
| .TP |
| .B \fBXalanC_LIBRARY\fP |
| the Xalan library |
| .UNINDENT |
| .SS FindXCTest |
| .sp |
| New in version 3.3. |
| |
| .sp |
| Functions to help creating and executing XCTest bundles. |
| .sp |
| An XCTest bundle is a CFBundle with a special product\-type |
| and bundle extension. The Mac Developer Library provides more |
| information in the \fI\%Testing with Xcode\fP document. |
| .SS Module Functions |
| .INDENT 0.0 |
| .TP |
| .B xctest_add_bundle |
| The \fBxctest_add_bundle\fP function creates a XCTest bundle named |
| <target> which will test the target <testee>. Supported target types |
| for testee are Frameworks and App Bundles: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| xctest_add_bundle( |
| <target> # Name of the XCTest bundle |
| <testee> # Target name of the testee |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B xctest_add_test |
| The \fBxctest_add_test\fP function adds an XCTest bundle to the |
| project to be run by \fBctest(1)\fP\&. The test will be named |
| <name> and tests <bundle>: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| xctest_add_test( |
| <name> # Test name |
| <bundle> # Target name of XCTest bundle |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .SS Module Variables |
| .sp |
| The following variables are set by including this module: |
| .INDENT 0.0 |
| .TP |
| .B XCTest_FOUND |
| True if the XCTest Framework and executable were found. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B XCTest_EXECUTABLE |
| The path to the xctest command line tool used to execute XCTest bundles. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B XCTest_INCLUDE_DIRS |
| The directory containing the XCTest Framework headers. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B XCTest_LIBRARIES |
| The location of the XCTest Framework. |
| .UNINDENT |
| .SS FindXercesC |
| .sp |
| New in version 3.1. |
| |
| .sp |
| Find the Apache Xerces\-C++ validating XML parser headers and libraries. |
| .SS Imported targets |
| .sp |
| New in version 3.5. |
| |
| .sp |
| This module defines the following \fBIMPORTED\fP targets: |
| .INDENT 0.0 |
| .TP |
| .B \fBXercesC::XercesC\fP |
| The Xerces\-C++ \fBxerces\-c\fP library, if found. |
| .UNINDENT |
| .SS Result variables |
| .sp |
| This module will set the following variables in your project: |
| .INDENT 0.0 |
| .TP |
| .B \fBXercesC_FOUND\fP |
| true if the Xerces headers and libraries were found |
| .TP |
| .B \fBXercesC_VERSION\fP |
| Xerces release version |
| .TP |
| .B \fBXercesC_INCLUDE_DIRS\fP |
| the directory containing the Xerces headers |
| .TP |
| .B \fBXercesC_LIBRARIES\fP |
| Xerces libraries to be linked |
| .UNINDENT |
| .SS Cache variables |
| .sp |
| The following cache variables may also be set: |
| .INDENT 0.0 |
| .TP |
| .B \fBXercesC_INCLUDE_DIR\fP |
| the directory containing the Xerces headers |
| .TP |
| .B \fBXercesC_LIBRARY\fP |
| the Xerces library |
| .UNINDENT |
| .sp |
| New in version 3.4: Debug and Release variants are found separately. |
| |
| .SS FindXMLRPC |
| .sp |
| Find xmlrpc |
| .sp |
| Find the native XMLRPC headers and libraries. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| XMLRPC_INCLUDE_DIRS \- where to find xmlrpc.h, etc. |
| XMLRPC_LIBRARIES \- List of libraries when using xmlrpc. |
| XMLRPC_FOUND \- True if xmlrpc found. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| XMLRPC modules may be specified as components for this find module. |
| Modules may be listed by running "xmlrpc\-c\-config". Modules include: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| c++ C++ wrapper code |
| libwww\-client libwww\-based client |
| cgi\-server CGI\-based server |
| abyss\-server ABYSS\-based server |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Typical usage: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_package(XMLRPC REQUIRED libwww\-client) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindZLIB |
| .sp |
| Find the native ZLIB includes and library. |
| .SS IMPORTED Targets |
| .sp |
| New in version 3.1. |
| |
| .sp |
| This module defines \fBIMPORTED\fP target \fBZLIB::ZLIB\fP, if |
| ZLIB has been found. |
| .SS Result Variables |
| .sp |
| This module defines the following variables: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ZLIB_INCLUDE_DIRS \- where to find zlib.h, etc. |
| ZLIB_LIBRARIES \- List of libraries when using zlib. |
| ZLIB_FOUND \- True if zlib found. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ZLIB_VERSION_STRING \- The version of zlib found (x.y.z) |
| ZLIB_VERSION_MAJOR \- The major version of zlib |
| ZLIB_VERSION_MINOR \- The minor version of zlib |
| ZLIB_VERSION_PATCH \- The patch version of zlib |
| ZLIB_VERSION_TWEAK \- The tweak version of zlib |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.4: Debug and Release variants are found separately. |
| |
| .SS Backward Compatibility |
| .sp |
| The following variable are provided for backward compatibility |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ZLIB_MAJOR_VERSION \- The major version of zlib |
| ZLIB_MINOR_VERSION \- The minor version of zlib |
| ZLIB_PATCH_VERSION \- The patch version of zlib |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS Hints |
| .sp |
| A user may set \fBZLIB_ROOT\fP to a zlib installation root to tell this |
| module where to look. |
| .SH DEPRECATED MODULES |
| .SS Deprecated Utility Modules |
| .SS AddFileDependencies |
| .sp |
| Deprecated since version 3.20. |
| |
| .sp |
| Add dependencies to a source file. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_file_dependencies(<source> <files>...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Adds the given \fB<files>\fP to the dependencies of file \fB<source>\fP\&. |
| .sp |
| Do not use this command in new code. It is just a wrapper around: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_property(SOURCE <source> APPEND PROPERTY OBJECT_DEPENDS <files>...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Instead use the \fBset_property()\fP command to append to the |
| \fBOBJECT_DEPENDS\fP source file property directly. |
| .SS CMakeDetermineVSServicePack |
| .sp |
| Deprecated since version 3.0: Do not use. |
| |
| .sp |
| The functionality of this module has been superseded by the |
| \fBCMAKE_<LANG>_COMPILER_VERSION\fP variable that contains |
| the compiler version number. |
| .sp |
| Determine the Visual Studio service pack of the \(aqcl\(aq in use. |
| .sp |
| Usage: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| if(MSVC) |
| include(CMakeDetermineVSServicePack) |
| DetermineVSServicePack( my_service_pack ) |
| if( my_service_pack ) |
| message(STATUS "Detected: ${my_service_pack}") |
| endif() |
| endif() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Function DetermineVSServicePack sets the given variable to one of the |
| following values or an empty string if unknown: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| vc80, vc80sp1 |
| vc90, vc90sp1 |
| vc100, vc100sp1 |
| vc110, vc110sp1, vc110sp2, vc110sp3, vc110sp4 |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS CMakeExpandImportedTargets |
| .sp |
| Deprecated since version 3.4: Do not use. |
| |
| .sp |
| This module was once needed to expand imported targets to the underlying |
| libraries they reference on disk for use with the \fBtry_compile()\fP |
| and \fBtry_run()\fP commands. These commands now support imported |
| libraries in their \fBLINK_LIBRARIES\fP options (since CMake 2.8.11 |
| for \fBtry_compile()\fP and since CMake 3.2 for \fBtry_run()\fP). |
| .sp |
| This module does not support the policy \fBCMP0022\fP \fBNEW\fP |
| behavior or use of the \fBINTERFACE_LINK_LIBRARIES\fP property |
| because \fBgenerator expressions\fP |
| cannot be evaluated during configuration. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| CMAKE_EXPAND_IMPORTED_TARGETS(<var> LIBRARIES lib1 lib2...libN |
| [CONFIGURATION <config>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| CMAKE_EXPAND_IMPORTED_TARGETS() takes a list of libraries and replaces |
| all imported targets contained in this list with their actual file |
| paths of the referenced libraries on disk, including the libraries |
| from their link interfaces. If a CONFIGURATION is given, it uses the |
| respective configuration of the imported targets if it exists. If no |
| CONFIGURATION is given, it uses the first configuration from |
| ${CMAKE_CONFIGURATION_TYPES} if set, otherwise ${CMAKE_BUILD_TYPE}. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cmake_expand_imported_targets(expandedLibs |
| LIBRARIES ${CMAKE_REQUIRED_LIBRARIES} |
| CONFIGURATION "${CMAKE_TRY_COMPILE_CONFIGURATION}" ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS CMakeForceCompiler |
| .sp |
| Deprecated since version 3.6: Do not use. |
| |
| .sp |
| The macros provided by this module were once intended for use by |
| cross\-compiling toolchain files when CMake was not able to automatically |
| detect the compiler identification. Since the introduction of this module, |
| CMake\(aqs compiler identification capabilities have improved and can now be |
| taught to recognize any compiler. Furthermore, the suite of information |
| CMake detects from a compiler is now too extensive to be provided by |
| toolchain files using these macros. |
| .sp |
| One common use case for this module was to skip CMake\(aqs checks for a |
| working compiler when using a cross\-compiler that cannot link binaries |
| without special flags or custom linker scripts. This case is now supported |
| by setting the \fBCMAKE_TRY_COMPILE_TARGET_TYPE\fP variable in the |
| toolchain file instead. |
| |
| .sp |
| .ce |
| ---- |
| |
| .ce 0 |
| .sp |
| .sp |
| Macro \fBCMAKE_FORCE_C_COMPILER\fP has the following signature: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| CMAKE_FORCE_C_COMPILER(<compiler> <compiler\-id>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| It sets \fBCMAKE_C_COMPILER\fP to |
| the given compiler and the cmake internal variable |
| \fBCMAKE_C_COMPILER_ID\fP to the given |
| compiler\-id. It also bypasses the check for working compiler and basic |
| compiler information tests. |
| .sp |
| Macro \fBCMAKE_FORCE_CXX_COMPILER\fP has the following signature: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| CMAKE_FORCE_CXX_COMPILER(<compiler> <compiler\-id>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| It sets \fBCMAKE_CXX_COMPILER\fP to |
| the given compiler and the cmake internal variable |
| \fBCMAKE_CXX_COMPILER_ID\fP to the given |
| compiler\-id. It also bypasses the check for working compiler and basic |
| compiler information tests. |
| .sp |
| Macro \fBCMAKE_FORCE_Fortran_COMPILER\fP has the following signature: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| CMAKE_FORCE_Fortran_COMPILER(<compiler> <compiler\-id>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| It sets \fBCMAKE_Fortran_COMPILER\fP to |
| the given compiler and the cmake internal variable |
| \fBCMAKE_Fortran_COMPILER_ID\fP to the given |
| compiler\-id. It also bypasses the check for working compiler and basic |
| compiler information tests. |
| .sp |
| So a simple toolchain file could look like this: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| include (CMakeForceCompiler) |
| set(CMAKE_SYSTEM_NAME Generic) |
| CMAKE_FORCE_C_COMPILER (chc12 MetrowerksHicross) |
| CMAKE_FORCE_CXX_COMPILER (chc12 MetrowerksHicross) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS CMakeParseArguments |
| .sp |
| This module once implemented the \fBcmake_parse_arguments()\fP command |
| that is now implemented natively by CMake. It is now an empty placeholder |
| for compatibility with projects that include it to get the command from |
| CMake 3.4 and lower. |
| .SS Documentation |
| .sp |
| Deprecated since version 3.18: This module does nothing, unless policy \fBCMP0106\fP is set to \fBOLD\fP\&. |
| |
| .sp |
| This module provides support for the VTK documentation framework. It |
| relies on several tools (Doxygen, Perl, etc). |
| .SS MacroAddFileDependencies |
| .sp |
| Deprecated since version 3.14. |
| |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| MACRO_ADD_FILE_DEPENDENCIES(<source> <files>...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Do not use this command in new code. It is just a wrapper around: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_property(SOURCE <source> APPEND PROPERTY OBJECT_DEPENDS <files>...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Instead use the \fBset_property()\fP command to append to the |
| \fBOBJECT_DEPENDS\fP source file property directly. |
| .SS TestCXXAcceptsFlag |
| .sp |
| Deprecated since version 3.0: See \fBCheckCXXCompilerFlag\fP\&. |
| |
| .sp |
| Check if the CXX compiler accepts a flag. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| CHECK_CXX_ACCEPTS_FLAG(<flags> <variable>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B \fB<flags>\fP |
| the flags to try |
| .TP |
| .B \fB<variable>\fP |
| variable to store the result |
| .UNINDENT |
| .SS UseJavaClassFilelist |
| .sp |
| Changed in version 3.20: This module was previously documented by mistake and was never meant for |
| direct inclusion by project code. See the \fBUseJava\fP module. |
| |
| .SS UseJavaSymlinks |
| .sp |
| Changed in version 3.20: This module was previously documented by mistake and was never meant for |
| direct inclusion by project code. See the \fBUseJava\fP module. |
| |
| .SS UsePkgConfig |
| .sp |
| Obsolete pkg\-config module for CMake, use FindPkgConfig instead. |
| .sp |
| This module defines the following macro: |
| .sp |
| PKGCONFIG(package includedir libdir linkflags cflags) |
| .sp |
| Calling PKGCONFIG will fill the desired information into the 4 given |
| arguments, e.g. PKGCONFIG(libart\-2.0 LIBART_INCLUDE_DIR |
| LIBART_LINK_DIR LIBART_LINK_FLAGS LIBART_CFLAGS) if pkg\-config was NOT |
| found or the specified software package doesn\(aqt exist, the variable |
| will be empty when the function returns, otherwise they will contain |
| the respective information |
| .SS Use_wxWindows |
| .sp |
| Deprecated since version 2.8.10: Use \fBfind_package(wxWidgets)\fP and \fBinclude(${wxWidgets_USE_FILE})\fP instead. |
| |
| .sp |
| This convenience include finds if wxWindows is installed and set the |
| appropriate libs, incdirs, flags etc. author Jan Woetzel <jw \-at\- |
| mip.informatik.uni\-kiel.de> (07/2003) |
| .sp |
| USAGE: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| just include Use_wxWindows.cmake |
| in your projects CMakeLists.txt |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| include( ${CMAKE_MODULE_PATH}/Use_wxWindows.cmake) |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| if you are sure you need GL then |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| set(WXWINDOWS_USE_GL 1) |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| *before* you include this file. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS WriteBasicConfigVersionFile |
| .sp |
| Deprecated since version 3.0: Use the identical command \fBwrite_basic_package_version_file()\fP |
| from module \fBCMakePackageConfigHelpers\fP\&. |
| |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| WRITE_BASIC_CONFIG_VERSION_FILE( filename |
| [VERSION major.minor.patch] |
| COMPATIBILITY (AnyNewerVersion|SameMajorVersion|SameMinorVersion|ExactVersion) |
| [ARCH_INDEPENDENT] |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS WriteCompilerDetectionHeader |
| .sp |
| Deprecated since version 3.20: This module is available only if policy \fBCMP0120\fP |
| is not set to \fBNEW\fP\&. Do not use it in new code. |
| |
| .sp |
| New in version 3.1. |
| |
| .sp |
| This module provides the function \fBwrite_compiler_detection_header()\fP\&. |
| .sp |
| This function can be used to generate a file suitable for preprocessor |
| inclusion which contains macros to be used in source code: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| write_compiler_detection_header( |
| FILE <file> |
| PREFIX <prefix> |
| [OUTPUT_FILES_VAR <output_files_var> OUTPUT_DIR <output_dir>] |
| COMPILERS <compiler> [...] |
| FEATURES <feature> [...] |
| [BARE_FEATURES <feature> [...]] |
| [VERSION <version>] |
| [PROLOG <prolog>] |
| [EPILOG <epilog>] |
| [ALLOW_UNKNOWN_COMPILERS] |
| [ALLOW_UNKNOWN_COMPILER_VERSIONS] |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This generates the file \fB<file>\fP with macros which all have the prefix |
| \fB<prefix>\fP\&. |
| .sp |
| By default, all content is written directly to the \fB<file>\fP\&. The |
| \fBOUTPUT_FILES_VAR\fP may be specified to cause the compiler\-specific |
| content to be written to separate files. The separate files are then |
| available in the \fB<output_files_var>\fP and may be consumed by the caller |
| for installation for example. The \fBOUTPUT_DIR\fP specifies a relative |
| path from the main \fB<file>\fP to the compiler\-specific files. For example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| write_compiler_detection_header( |
| FILE climbingstats_compiler_detection.h |
| PREFIX ClimbingStats |
| OUTPUT_FILES_VAR support_files |
| OUTPUT_DIR compilers |
| COMPILERS GNU Clang MSVC Intel |
| FEATURES cxx_variadic_templates |
| ) |
| install(FILES |
| ${CMAKE_CURRENT_BINARY_DIR}/climbingstats_compiler_detection.h |
| DESTINATION include |
| ) |
| install(FILES |
| ${support_files} |
| DESTINATION include/compilers |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBVERSION\fP may be used to specify the API version to be generated. |
| Future versions of CMake may introduce alternative APIs. A given |
| API is selected by any \fB<version>\fP value greater than or equal |
| to the version of CMake that introduced the given API and less |
| than the version of CMake that introduced its succeeding API. |
| The value of the \fBCMAKE_MINIMUM_REQUIRED_VERSION\fP |
| variable is used if no explicit version is specified. |
| (As of CMake version 3.23.1 there is only one API version.) |
| .sp |
| \fBPROLOG\fP may be specified as text content to write at the start of the |
| header. \fBEPILOG\fP may be specified as text content to write at the end |
| of the header |
| .sp |
| At least one \fB<compiler>\fP and one \fB<feature>\fP must be listed. Compilers |
| which are known to CMake, but not specified are detected and a preprocessor |
| \fB#error\fP is generated for them. A preprocessor macro matching |
| \fB<PREFIX>_COMPILER_IS_<compiler>\fP is generated for each compiler |
| known to CMake to contain the value \fB0\fP or \fB1\fP\&. |
| .sp |
| Possible compiler identifiers are documented with the |
| \fBCMAKE_<LANG>_COMPILER_ID\fP variable. |
| Available features in this version of CMake are listed in the |
| \fBCMAKE_C_KNOWN_FEATURES\fP and |
| \fBCMAKE_CXX_KNOWN_FEATURES\fP global properties. |
| See the \fBcmake\-compile\-features(7)\fP manual for information on |
| compile features. |
| .sp |
| New in version 3.2: Added \fBMSVC\fP and \fBAppleClang\fP compiler support. |
| |
| .sp |
| New in version 3.6: Added \fBIntel\fP compiler support. |
| |
| .sp |
| Changed in version 3.8: The \fB{c,cxx}_std_*\fP meta\-features are ignored if requested. |
| |
| .sp |
| New in version 3.8: \fBALLOW_UNKNOWN_COMPILERS\fP and \fBALLOW_UNKNOWN_COMPILER_VERSIONS\fP cause |
| the module to generate conditions that treat unknown compilers as simply |
| lacking all features. Without these options the default behavior is to |
| generate a \fB#error\fP for unknown compilers and versions. |
| |
| .sp |
| New in version 3.12: \fBBARE_FEATURES\fP will define the compatibility macros with the name used in |
| newer versions of the language standard, so the code can use the new feature |
| name unconditionally. |
| |
| .SS Feature Test Macros |
| .sp |
| For each compiler, a preprocessor macro is generated matching |
| \fB<PREFIX>_COMPILER_IS_<compiler>\fP which has the content either \fB0\fP |
| or \fB1\fP, depending on the compiler in use. Preprocessor macros for |
| compiler version components are generated matching |
| \fB<PREFIX>_COMPILER_VERSION_MAJOR\fP \fB<PREFIX>_COMPILER_VERSION_MINOR\fP |
| and \fB<PREFIX>_COMPILER_VERSION_PATCH\fP containing decimal values |
| for the corresponding compiler version components, if defined. |
| .sp |
| A preprocessor test is generated based on the compiler version |
| denoting whether each feature is enabled. A preprocessor macro |
| matching \fB<PREFIX>_COMPILER_<FEATURE>\fP, where \fB<FEATURE>\fP is the |
| upper\-case \fB<feature>\fP name, is generated to contain the value |
| \fB0\fP or \fB1\fP depending on whether the compiler in use supports the |
| feature: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| write_compiler_detection_header( |
| FILE climbingstats_compiler_detection.h |
| PREFIX ClimbingStats |
| COMPILERS GNU Clang AppleClang MSVC Intel |
| FEATURES cxx_variadic_templates |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| #if ClimbingStats_COMPILER_CXX_VARIADIC_TEMPLATES |
| template<typename... T> |
| void someInterface(T t...) { /* ... */ } |
| #else |
| // Compatibility versions |
| template<typename T1> |
| void someInterface(T1 t1) { /* ... */ } |
| template<typename T1, typename T2> |
| void someInterface(T1 t1, T2 t2) { /* ... */ } |
| template<typename T1, typename T2, typename T3> |
| void someInterface(T1 t1, T2 t2, T3 t3) { /* ... */ } |
| #endif |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS Symbol Macros |
| .sp |
| Some additional symbol\-defines are created for particular features for |
| use as symbols which may be conditionally defined empty: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| class MyClass ClimbingStats_FINAL |
| { |
| ClimbingStats_CONSTEXPR int someInterface() { return 42; } |
| }; |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The \fBClimbingStats_FINAL\fP macro will expand to \fBfinal\fP if the |
| compiler (and its flags) support the \fBcxx_final\fP feature, and the |
| \fBClimbingStats_CONSTEXPR\fP macro will expand to \fBconstexpr\fP |
| if \fBcxx_constexpr\fP is supported. |
| .sp |
| If \fBBARE_FEATURES cxx_final\fP was given as argument the \fBfinal\fP keyword |
| will be defined for old compilers, too. |
| .sp |
| The following features generate corresponding symbol defines and if they |
| are available as \fBBARE_FEATURES\fP: |
| .TS |
| center; |
| |l|l|l|l|. |
| _ |
| T{ |
| Feature |
| T} T{ |
| Define |
| T} T{ |
| Symbol |
| T} T{ |
| bare |
| T} |
| _ |
| T{ |
| \fBc_restrict\fP |
| T} T{ |
| \fB<PREFIX>_RESTRICT\fP |
| T} T{ |
| \fBrestrict\fP |
| T} T{ |
| yes |
| T} |
| _ |
| T{ |
| \fBcxx_constexpr\fP |
| T} T{ |
| \fB<PREFIX>_CONSTEXPR\fP |
| T} T{ |
| \fBconstexpr\fP |
| T} T{ |
| yes |
| T} |
| _ |
| T{ |
| \fBcxx_deleted_functions\fP |
| T} T{ |
| \fB<PREFIX>_DELETED_FUNCTION\fP |
| T} T{ |
| \fB= delete\fP |
| T} T{ |
| T} |
| _ |
| T{ |
| \fBcxx_extern_templates\fP |
| T} T{ |
| \fB<PREFIX>_EXTERN_TEMPLATE\fP |
| T} T{ |
| \fBextern\fP |
| T} T{ |
| T} |
| _ |
| T{ |
| \fBcxx_final\fP |
| T} T{ |
| \fB<PREFIX>_FINAL\fP |
| T} T{ |
| \fBfinal\fP |
| T} T{ |
| yes |
| T} |
| _ |
| T{ |
| \fBcxx_noexcept\fP |
| T} T{ |
| \fB<PREFIX>_NOEXCEPT\fP |
| T} T{ |
| \fBnoexcept\fP |
| T} T{ |
| yes |
| T} |
| _ |
| T{ |
| \fBcxx_noexcept\fP |
| T} T{ |
| \fB<PREFIX>_NOEXCEPT_EXPR(X)\fP |
| T} T{ |
| \fBnoexcept(X)\fP |
| T} T{ |
| T} |
| _ |
| T{ |
| \fBcxx_override\fP |
| T} T{ |
| \fB<PREFIX>_OVERRIDE\fP |
| T} T{ |
| \fBoverride\fP |
| T} T{ |
| yes |
| T} |
| _ |
| .TE |
| .SS Compatibility Implementation Macros |
| .sp |
| Some features are suitable for wrapping in a macro with a backward |
| compatibility implementation if the compiler does not support the feature. |
| .sp |
| When the \fBcxx_static_assert\fP feature is not provided by the compiler, |
| a compatibility implementation is available via the |
| \fB<PREFIX>_STATIC_ASSERT(COND)\fP and |
| \fB<PREFIX>_STATIC_ASSERT_MSG(COND, MSG)\fP function\-like macros. The macros |
| expand to \fBstatic_assert\fP where that compiler feature is available, and |
| to a compatibility implementation otherwise. In the first form, the |
| condition is stringified in the message field of \fBstatic_assert\fP\&. In |
| the second form, the message \fBMSG\fP is passed to the message field of |
| \fBstatic_assert\fP, or ignored if using the backward compatibility |
| implementation. |
| .sp |
| The \fBcxx_attribute_deprecated\fP feature provides a macro definition |
| \fB<PREFIX>_DEPRECATED\fP, which expands to either the standard |
| \fB[[deprecated]]\fP attribute or a compiler\-specific decorator such |
| as \fB__attribute__((__deprecated__))\fP used by GNU compilers. |
| .sp |
| The \fBcxx_alignas\fP feature provides a macro definition |
| \fB<PREFIX>_ALIGNAS\fP which expands to either the standard \fBalignas\fP |
| decorator or a compiler\-specific decorator such as |
| \fB__attribute__ ((__aligned__))\fP used by GNU compilers. |
| .sp |
| The \fBcxx_alignof\fP feature provides a macro definition |
| \fB<PREFIX>_ALIGNOF\fP which expands to either the standard \fBalignof\fP |
| decorator or a compiler\-specific decorator such as \fB__alignof__\fP |
| used by GNU compilers. |
| .TS |
| center; |
| |l|l|l|l|. |
| _ |
| T{ |
| Feature |
| T} T{ |
| Define |
| T} T{ |
| Symbol |
| T} T{ |
| bare |
| T} |
| _ |
| T{ |
| \fBcxx_alignas\fP |
| T} T{ |
| \fB<PREFIX>_ALIGNAS\fP |
| T} T{ |
| \fBalignas\fP |
| T} T{ |
| T} |
| _ |
| T{ |
| \fBcxx_alignof\fP |
| T} T{ |
| \fB<PREFIX>_ALIGNOF\fP |
| T} T{ |
| \fBalignof\fP |
| T} T{ |
| T} |
| _ |
| T{ |
| \fBcxx_nullptr\fP |
| T} T{ |
| \fB<PREFIX>_NULLPTR\fP |
| T} T{ |
| \fBnullptr\fP |
| T} T{ |
| yes |
| T} |
| _ |
| T{ |
| \fBcxx_static_assert\fP |
| T} T{ |
| \fB<PREFIX>_STATIC_ASSERT\fP |
| T} T{ |
| \fBstatic_assert\fP |
| T} T{ |
| T} |
| _ |
| T{ |
| \fBcxx_static_assert\fP |
| T} T{ |
| \fB<PREFIX>_STATIC_ASSERT_MSG\fP |
| T} T{ |
| \fBstatic_assert\fP |
| T} T{ |
| T} |
| _ |
| T{ |
| \fBcxx_attribute_deprecated\fP |
| T} T{ |
| \fB<PREFIX>_DEPRECATED\fP |
| T} T{ |
| \fB[[deprecated]]\fP |
| T} T{ |
| T} |
| _ |
| T{ |
| \fBcxx_attribute_deprecated\fP |
| T} T{ |
| \fB<PREFIX>_DEPRECATED_MSG\fP |
| T} T{ |
| \fB[[deprecated]]\fP |
| T} T{ |
| T} |
| _ |
| T{ |
| \fBcxx_thread_local\fP |
| T} T{ |
| \fB<PREFIX>_THREAD_LOCAL\fP |
| T} T{ |
| \fBthread_local\fP |
| T} T{ |
| T} |
| _ |
| .TE |
| .sp |
| A use\-case which arises with such deprecation macros is the deprecation |
| of an entire library. In that case, all public API in the library may |
| be decorated with the \fB<PREFIX>_DEPRECATED\fP macro. This results in |
| very noisy build output when building the library itself, so the macro |
| may be may be defined to empty in that case when building the deprecated |
| library: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_library(compat_support ${srcs}) |
| target_compile_definitions(compat_support |
| PRIVATE |
| CompatSupport_DEPRECATED= |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS Example Usage |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| This section was migrated from the \fBcmake\-compile\-features(7)\fP |
| manual since it relies on the \fBWriteCompilerDetectionHeader\fP module |
| which is removed by policy \fBCMP0120\fP\&. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Compile features may be preferred if available, without creating a hard |
| requirement. For example, a library may provide alternative |
| implementations depending on whether the \fBcxx_variadic_templates\fP |
| feature is available: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| #if Foo_COMPILER_CXX_VARIADIC_TEMPLATES |
| template<int I, int... Is> |
| struct Interface; |
| |
| template<int I> |
| struct Interface<I> |
| { |
| static int accumulate() |
| { |
| return I; |
| } |
| }; |
| |
| template<int I, int... Is> |
| struct Interface |
| { |
| static int accumulate() |
| { |
| return I + Interface<Is...>::accumulate(); |
| } |
| }; |
| #else |
| template<int I1, int I2 = 0, int I3 = 0, int I4 = 0> |
| struct Interface |
| { |
| static int accumulate() { return I1 + I2 + I3 + I4; } |
| }; |
| #endif |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Such an interface depends on using the correct preprocessor defines for the |
| compiler features. CMake can generate a header file containing such |
| defines using the \fI\%WriteCompilerDetectionHeader\fP module. The |
| module contains the \fBwrite_compiler_detection_header\fP function which |
| accepts parameters to control the content of the generated header file: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| write_compiler_detection_header( |
| FILE "${CMAKE_CURRENT_BINARY_DIR}/foo_compiler_detection.h" |
| PREFIX Foo |
| COMPILERS GNU |
| FEATURES |
| cxx_variadic_templates |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Such a header file may be used internally in the source code of a project, |
| and it may be installed and used in the interface of library code. |
| .sp |
| For each feature listed in \fBFEATURES\fP, a preprocessor definition |
| is created in the header file, and defined to either \fB1\fP or \fB0\fP\&. |
| .sp |
| Additionally, some features call for additional defines, such as the |
| \fBcxx_final\fP and \fBcxx_override\fP features. Rather than being used in |
| \fB#ifdef\fP code, the \fBfinal\fP keyword is abstracted by a symbol |
| which is defined to either \fBfinal\fP, a compiler\-specific equivalent, or |
| to empty. That way, C++ code can be written to unconditionally use the |
| symbol, and compiler support determines what it is expanded to: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| struct Interface { |
| virtual void Execute() = 0; |
| }; |
| |
| struct Concrete Foo_FINAL { |
| void Execute() Foo_OVERRIDE; |
| }; |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| In this case, \fBFoo_FINAL\fP will expand to \fBfinal\fP if the |
| compiler supports the keyword, or to empty otherwise. |
| .sp |
| In this use\-case, the project code may wish to enable a particular language |
| standard if available from the compiler. The \fBCXX_STANDARD\fP |
| target property may be set to the desired language standard for a particular |
| target, and the \fBCMAKE_CXX_STANDARD\fP variable may be set to |
| influence all following targets: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| write_compiler_detection_header( |
| FILE "${CMAKE_CURRENT_BINARY_DIR}/foo_compiler_detection.h" |
| PREFIX Foo |
| COMPILERS GNU |
| FEATURES |
| cxx_final cxx_override |
| ) |
| |
| # Includes foo_compiler_detection.h and uses the Foo_FINAL symbol |
| # which will expand to \(aqfinal\(aq if the compiler supports the requested |
| # CXX_STANDARD. |
| add_library(foo foo.cpp) |
| set_property(TARGET foo PROPERTY CXX_STANDARD 11) |
| |
| # Includes foo_compiler_detection.h and uses the Foo_FINAL symbol |
| # which will expand to \(aqfinal\(aq if the compiler supports the feature, |
| # even though CXX_STANDARD is not set explicitly. The requirement of |
| # cxx_constexpr causes CMake to set CXX_STANDARD internally, which |
| # affects the compile flags. |
| add_library(foo_impl foo_impl.cpp) |
| target_compile_features(foo_impl PRIVATE cxx_constexpr) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The \fBwrite_compiler_detection_header\fP function also creates compatibility |
| code for other features which have standard equivalents. For example, the |
| \fBcxx_static_assert\fP feature is emulated with a template and abstracted |
| via the \fB<PREFIX>_STATIC_ASSERT\fP and \fB<PREFIX>_STATIC_ASSERT_MSG\fP |
| function\-macros. |
| .SS Deprecated Find Modules |
| .SS FindCUDA |
| .sp |
| \fBWARNING:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| \fIDeprecated since version 3.10.\fP |
| .UNINDENT |
| .UNINDENT |
| .sp |
| It is no longer necessary to use this module or call \fBfind_package(CUDA)\fP |
| for compiling CUDA code. Instead, list \fBCUDA\fP among the languages named |
| in the top\-level call to the \fBproject()\fP command, or call the |
| \fBenable_language()\fP command with \fBCUDA\fP\&. |
| Then one can add CUDA (\fB\&.cu\fP) sources directly to targets similar to other |
| languages. |
| .sp |
| New in version 3.17: To find and use the CUDA toolkit libraries manually, use the |
| \fBFindCUDAToolkit\fP module instead. It works regardless of the |
| \fBCUDA\fP language being enabled. |
| |
| .SS Documentation of Deprecated Usage |
| .sp |
| Tools for building CUDA C files: libraries and build dependencies. |
| .sp |
| This script locates the NVIDIA CUDA C tools. It should work on Linux, |
| Windows, and macOS and should be reasonably up to date with CUDA C |
| releases. |
| .sp |
| New in version 3.19: QNX support. |
| |
| .sp |
| This script makes use of the standard \fBfind_package()\fP arguments of |
| \fB<VERSION>\fP, \fBREQUIRED\fP and \fBQUIET\fP\&. \fBCUDA_FOUND\fP will report if an |
| acceptable version of CUDA was found. |
| .sp |
| The script will prompt the user to specify \fBCUDA_TOOLKIT_ROOT_DIR\fP if |
| the prefix cannot be determined by the location of nvcc in the system |
| path and \fBREQUIRED\fP is specified to \fBfind_package()\fP\&. To use |
| a different installed version of the toolkit set the environment variable |
| \fBCUDA_BIN_PATH\fP before running cmake (e.g. |
| \fBCUDA_BIN_PATH=/usr/local/cuda1.0\fP instead of the default |
| \fB/usr/local/cuda\fP) or set \fBCUDA_TOOLKIT_ROOT_DIR\fP after configuring. If |
| you change the value of \fBCUDA_TOOLKIT_ROOT_DIR\fP, various components that |
| depend on the path will be relocated. |
| .sp |
| It might be necessary to set \fBCUDA_TOOLKIT_ROOT_DIR\fP manually on certain |
| platforms, or to use a CUDA runtime not installed in the default |
| location. In newer versions of the toolkit the CUDA library is |
| included with the graphics driver \-\- be sure that the driver version |
| matches what is needed by the CUDA runtime version. |
| .SS Input Variables |
| .sp |
| The following variables affect the behavior of the macros in the |
| script (in alphabetical order). Note that any of these flags can be |
| changed multiple times in the same directory before calling |
| \fBcuda_add_executable()\fP, \fBcuda_add_library()\fP, \fBcuda_compile()\fP, |
| \fBcuda_compile_ptx()\fP, \fBcuda_compile_fatbin()\fP, \fBcuda_compile_cubin()\fP |
| or \fBcuda_wrap_srcs()\fP: |
| .INDENT 0.0 |
| .TP |
| .B \fBCUDA_64_BIT_DEVICE_CODE\fP (Default: host bit size) |
| Set to \fBON\fP to compile for 64 bit device code, OFF for 32 bit device code. |
| Note that making this different from the host code when generating object |
| or C files from CUDA code just won\(aqt work, because size_t gets defined by |
| nvcc in the generated source. If you compile to PTX and then load the |
| file yourself, you can mix bit sizes between device and host. |
| .TP |
| .B \fBCUDA_ATTACH_VS_BUILD_RULE_TO_CUDA_FILE\fP (Default: \fBON\fP) |
| Set to \fBON\fP if you want the custom build rule to be attached to the source |
| file in Visual Studio. Turn OFF if you add the same cuda file to multiple |
| targets. |
| .sp |
| This allows the user to build the target from the CUDA file; however, bad |
| things can happen if the CUDA source file is added to multiple targets. |
| When performing parallel builds it is possible for the custom build |
| command to be run more than once and in parallel causing cryptic build |
| errors. VS runs the rules for every source file in the target, and a |
| source can have only one rule no matter how many projects it is added to. |
| When the rule is run from multiple targets race conditions can occur on |
| the generated file. Eventually everything will get built, but if the user |
| is unaware of this behavior, there may be confusion. It would be nice if |
| this script could detect the reuse of source files across multiple targets |
| and turn the option off for the user, but no good solution could be found. |
| .TP |
| .B \fBCUDA_BUILD_CUBIN\fP (Default: \fBOFF\fP) |
| Set to \fBON\fP to enable and extra compilation pass with the \fB\-cubin\fP option in |
| Device mode. The output is parsed and register, shared memory usage is |
| printed during build. |
| .TP |
| .B \fBCUDA_BUILD_EMULATION\fP (Default: \fBOFF\fP for device mode) |
| Set to \fBON\fP for Emulation mode. \fB\-D_DEVICEEMU\fP is defined for CUDA C files |
| when \fBCUDA_BUILD_EMULATION\fP is \fBTRUE\fP\&. |
| .TP |
| .B \fBCUDA_LINK_LIBRARIES_KEYWORD\fP (Default: \fB""\fP) |
| New in version 3.9. |
| |
| .sp |
| The \fB<PRIVATE|PUBLIC|INTERFACE>\fP keyword to use for internal |
| \fBtarget_link_libraries()\fP calls. The default is to use no keyword which |
| uses the old "plain" form of \fBtarget_link_libraries()\fP\&. Note that is matters |
| because whatever is used inside the \fBFindCUDA\fP module must also be used |
| outside \- the two forms of \fBtarget_link_libraries()\fP cannot be mixed. |
| .TP |
| .B \fBCUDA_GENERATED_OUTPUT_DIR\fP (Default: \fBCMAKE_CURRENT_BINARY_DIR\fP) |
| Set to the path you wish to have the generated files placed. If it is |
| blank output files will be placed in \fBCMAKE_CURRENT_BINARY_DIR\fP\&. |
| Intermediate files will always be placed in |
| \fBCMAKE_CURRENT_BINARY_DIR/CMakeFiles\fP\&. |
| .TP |
| .B \fBCUDA_HOST_COMPILATION_CPP\fP (Default: \fBON\fP) |
| Set to \fBOFF\fP for C compilation of host code. |
| .TP |
| .B \fBCUDA_HOST_COMPILER\fP (Default: \fBCMAKE_C_COMPILER\fP) |
| Set the host compiler to be used by nvcc. Ignored if \fB\-ccbin\fP or |
| \fB\-\-compiler\-bindir\fP is already present in the \fBCUDA_NVCC_FLAGS\fP or |
| \fBCUDA_NVCC_FLAGS_<CONFIG>\fP variables. For Visual Studio targets, |
| the host compiler is constructed with one or more visual studio macros |
| such as \fB$(VCInstallDir)\fP, that expands out to the path when |
| the command is run from within VS. |
| .sp |
| New in version 3.13: If the \fBCUDAHOSTCXX\fP environment variable is set it will |
| be used as the default. |
| |
| .TP |
| .B \fBCUDA_NVCC_FLAGS\fP, \fBCUDA_NVCC_FLAGS_<CONFIG>\fP |
| Additional NVCC command line arguments. NOTE: multiple arguments must be |
| semi\-colon delimited (e.g. \fB\-\-compiler\-options;\-Wall\fP) |
| .sp |
| New in version 3.6: Contents of these variables may use |
| \fBgenerator expressions\fP\&. |
| |
| .TP |
| .B \fBCUDA_PROPAGATE_HOST_FLAGS\fP (Default: \fBON\fP) |
| Set to \fBON\fP to propagate \fBCMAKE_{C,CXX}_FLAGS\fP and their configuration |
| dependent counterparts (e.g. \fBCMAKE_C_FLAGS_DEBUG\fP) automatically to the |
| host compiler through nvcc\(aqs \fB\-Xcompiler\fP flag. This helps make the |
| generated host code match the rest of the system better. Sometimes |
| certain flags give nvcc problems, and this will help you turn the flag |
| propagation off. This does not affect the flags supplied directly to nvcc |
| via \fBCUDA_NVCC_FLAGS\fP or through the \fBOPTION\fP flags specified through |
| \fBcuda_add_library()\fP, \fBcuda_add_executable()\fP, or \fBcuda_wrap_srcs()\fP\&. Flags used for |
| shared library compilation are not affected by this flag. |
| .TP |
| .B \fBCUDA_SEPARABLE_COMPILATION\fP (Default: \fBOFF\fP) |
| If set this will enable separable compilation for all CUDA runtime object |
| files. If used outside of \fBcuda_add_executable()\fP and \fBcuda_add_library()\fP |
| (e.g. calling \fBcuda_wrap_srcs()\fP directly), |
| \fBcuda_compute_separable_compilation_object_file_name()\fP and |
| \fBcuda_link_separable_compilation_objects()\fP should be called. |
| .TP |
| .B \fBCUDA_SOURCE_PROPERTY_FORMAT\fP |
| New in version 3.3. |
| |
| .sp |
| If this source file property is set, it can override the format specified |
| to \fBcuda_wrap_srcs()\fP (\fBOBJ\fP, \fBPTX\fP, \fBCUBIN\fP, or \fBFATBIN\fP). If an input source file |
| is not a \fB\&.cu\fP file, setting this file will cause it to be treated as a \fB\&.cu\fP |
| file. See documentation for set_source_files_properties on how to set |
| this property. |
| .TP |
| .B \fBCUDA_USE_STATIC_CUDA_RUNTIME\fP (Default: \fBON\fP) |
| New in version 3.3. |
| |
| .sp |
| When enabled the static version of the CUDA runtime library will be used |
| in \fBCUDA_LIBRARIES\fP\&. If the version of CUDA configured doesn\(aqt support |
| this option, then it will be silently disabled. |
| .TP |
| .B \fBCUDA_VERBOSE_BUILD\fP (Default: \fBOFF\fP) |
| Set to \fBON\fP to see all the commands used when building the CUDA file. When |
| using a Makefile generator the value defaults to \fBVERBOSE\fP (run |
| \fBmake VERBOSE=1\fP to see output), although setting \fBCUDA_VERBOSE_BUILD\fP to \fBON\fP will |
| always print the output. |
| .UNINDENT |
| .SS Commands |
| .sp |
| The script creates the following functions and macros (in alphabetical order): |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cuda_add_cufft_to_target(<cuda_target>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Adds the cufft library to the target (can be any target). Handles whether |
| you are in emulation mode or not. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cuda_add_cublas_to_target(<cuda_target>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Adds the cublas library to the target (can be any target). Handles |
| whether you are in emulation mode or not. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cuda_add_executable(<cuda_target> <file>... |
| [WIN32] [MACOSX_BUNDLE] [EXCLUDE_FROM_ALL] [OPTIONS ...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Creates an executable \fB<cuda_target>\fP which is made up of the files |
| specified. All of the non CUDA C files are compiled using the standard |
| build rules specified by CMake and the CUDA files are compiled to object |
| files using nvcc and the host compiler. In addition \fBCUDA_INCLUDE_DIRS\fP is |
| added automatically to \fBinclude_directories()\fP\&. Some standard CMake target |
| calls can be used on the target after calling this macro |
| (e.g. \fBset_target_properties()\fP and \fBtarget_link_libraries()\fP), but setting |
| properties that adjust compilation flags will not affect code compiled by |
| nvcc. Such flags should be modified before calling \fBcuda_add_executable()\fP, |
| \fBcuda_add_library()\fP or \fBcuda_wrap_srcs()\fP\&. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cuda_add_library(<cuda_target> <file>... |
| [STATIC | SHARED | MODULE] [EXCLUDE_FROM_ALL] [OPTIONS ...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Same as \fBcuda_add_executable()\fP except that a library is created. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cuda_build_clean_target() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Creates a convenience target that deletes all the dependency files |
| generated. You should make clean after running this target to ensure the |
| dependency files get regenerated. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cuda_compile(<generated_files> <file>... [STATIC | SHARED | MODULE] |
| [OPTIONS ...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Returns a list of generated files from the input source files to be used |
| with \fBadd_library()\fP or \fBadd_executable()\fP\&. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cuda_compile_ptx(<generated_files> <file>... [OPTIONS ...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Returns a list of \fBPTX\fP files generated from the input source files. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cuda_compile_fatbin(<generated_files> <file>... [OPTIONS ...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.1. |
| |
| .sp |
| Returns a list of \fBFATBIN\fP files generated from the input source files. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cuda_compile_cubin(<generated_files> <file>... [OPTIONS ...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.1. |
| |
| .sp |
| Returns a list of \fBCUBIN\fP files generated from the input source files. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cuda_compute_separable_compilation_object_file_name(<output_file_var> |
| <cuda_target> |
| <object_files>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Compute the name of the intermediate link file used for separable |
| compilation. This file name is typically passed into |
| \fBCUDA_LINK_SEPARABLE_COMPILATION_OBJECTS\fP\&. output_file_var is produced |
| based on cuda_target the list of objects files that need separable |
| compilation as specified by \fB<object_files>\fP\&. If the \fB<object_files>\fP list is |
| empty, then \fB<output_file_var>\fP will be empty. This function is called |
| automatically for \fBcuda_add_library()\fP and \fBcuda_add_executable()\fP\&. Note that |
| this is a function and not a macro. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cuda_include_directories(path0 path1 ...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Sets the directories that should be passed to nvcc |
| (e.g. \fBnvcc \-Ipath0 \-Ipath1 ...\fP). These paths usually contain other \fB\&.cu\fP |
| files. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cuda_link_separable_compilation_objects(<output_file_var> <cuda_target> |
| <nvcc_flags> <object_files>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Generates the link object required by separable compilation from the given |
| object files. This is called automatically for \fBcuda_add_executable()\fP and |
| \fBcuda_add_library()\fP, but can be called manually when using \fBcuda_wrap_srcs()\fP |
| directly. When called from \fBcuda_add_library()\fP or \fBcuda_add_executable()\fP the |
| \fB<nvcc_flags>\fP passed in are the same as the flags passed in via the \fBOPTIONS\fP |
| argument. The only nvcc flag added automatically is the bitness flag as |
| specified by \fBCUDA_64_BIT_DEVICE_CODE\fP\&. Note that this is a function |
| instead of a macro. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cuda_select_nvcc_arch_flags(<out_variable> [<target_CUDA_architecture> ...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Selects GPU arch flags for nvcc based on \fBtarget_CUDA_architecture\fP\&. |
| .sp |
| Values for \fBtarget_CUDA_architecture\fP: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBAuto\fP: detects local machine GPU compute arch at runtime. |
| .IP \(bu 2 |
| \fBCommon\fP and \fBAll\fP: cover common and entire subsets of architectures. |
| .IP \(bu 2 |
| \fB<name>\fP: one of \fBFermi\fP, \fBKepler\fP, \fBMaxwell\fP, \fBKepler+Tegra\fP, \fBKepler+Tesla\fP, \fBMaxwell+Tegra\fP, \fBPascal\fP\&. |
| .IP \(bu 2 |
| \fB<ver>\fP, \fB<ver>(<ver>)\fP, \fB<ver>+PTX\fP, where \fB<ver>\fP is one of |
| \fB2.0\fP, \fB2.1\fP, \fB3.0\fP, \fB3.2\fP, \fB3.5\fP, \fB3.7\fP, \fB5.0\fP, \fB5.2\fP, \fB5.3\fP, \fB6.0\fP, \fB6.2\fP\&. |
| .UNINDENT |
| .sp |
| Returns list of flags to be added to \fBCUDA_NVCC_FLAGS\fP in \fB<out_variable>\fP\&. |
| Additionally, sets \fB<out_variable>_readable\fP to the resulting numeric list. |
| .sp |
| Example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cuda_select_nvcc_arch_flags(ARCH_FLAGS 3.0 3.5+PTX 5.2(5.0) Maxwell) |
| list(APPEND CUDA_NVCC_FLAGS ${ARCH_FLAGS}) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| More info on CUDA architectures: \fI\%https://en.wikipedia.org/wiki/CUDA\fP\&. |
| Note that this is a function instead of a macro. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cuda_wrap_srcs(<cuda_target> <format> <generated_files> <file>... |
| [STATIC | SHARED | MODULE] [OPTIONS ...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This is where all the magic happens. \fBcuda_add_executable()\fP, |
| \fBcuda_add_library()\fP, \fBcuda_compile()\fP, and \fBcuda_compile_ptx()\fP all call this |
| function under the hood. |
| .sp |
| Given the list of files \fB<file>...\fP this macro generates |
| custom commands that generate either PTX or linkable objects (use \fBPTX\fP or |
| \fBOBJ\fP for the \fB<format>\fP argument to switch). Files that don\(aqt end with \fB\&.cu\fP |
| or have the \fBHEADER_FILE_ONLY\fP property are ignored. |
| .sp |
| The arguments passed in after \fBOPTIONS\fP are extra command line options to |
| give to nvcc. You can also specify per configuration options by |
| specifying the name of the configuration followed by the options. General |
| options must precede configuration specific options. Not all |
| configurations need to be specified, only the ones provided will be used. |
| For example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cuda_add_executable(... |
| OPTIONS \-DFLAG=2 "\-DFLAG_OTHER=space in flag" |
| DEBUG \-g |
| RELEASE \-\-use_fast_math |
| RELWITHDEBINFO \-\-use_fast_math;\-g |
| MINSIZEREL \-\-use_fast_math) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| For certain configurations (namely VS generating object files with |
| \fBCUDA_ATTACH_VS_BUILD_RULE_TO_CUDA_FILE\fP set to \fBON\fP), no generated file will |
| be produced for the given cuda file. This is because when you add the |
| cuda file to Visual Studio it knows that this file produces an object file |
| and will link in the resulting object file automatically. |
| .sp |
| This script will also generate a separate cmake script that is used at |
| build time to invoke nvcc. This is for several reasons: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| nvcc can return negative numbers as return values which confuses |
| Visual Studio into thinking that the command succeeded. The script now |
| checks the error codes and produces errors when there was a problem. |
| .IP \(bu 2 |
| nvcc has been known to not delete incomplete results when it |
| encounters problems. This confuses build systems into thinking the |
| target was generated when in fact an unusable file exists. The script |
| now deletes the output files if there was an error. |
| .IP \(bu 2 |
| By putting all the options that affect the build into a file and then |
| make the build rule dependent on the file, the output files will be |
| regenerated when the options change. |
| .UNINDENT |
| .sp |
| This script also looks at optional arguments \fBSTATIC\fP, \fBSHARED\fP, or \fBMODULE\fP to |
| determine when to target the object compilation for a shared library. |
| \fBBUILD_SHARED_LIBS\fP is ignored in \fBcuda_wrap_srcs()\fP, but it is respected in |
| \fBcuda_add_library()\fP\&. On some systems special flags are added for building |
| objects intended for shared libraries. A preprocessor macro, |
| \fB<target_name>_EXPORTS\fP is defined when a shared library compilation is |
| detected. |
| .sp |
| Flags passed into add_definitions with \fB\-D\fP or \fB/D\fP are passed along to nvcc. |
| .SS Result Variables |
| .sp |
| The script defines the following variables: |
| .INDENT 0.0 |
| .TP |
| .B \fBCUDA_VERSION_MAJOR\fP |
| The major version of cuda as reported by nvcc. |
| .TP |
| .B \fBCUDA_VERSION_MINOR\fP |
| The minor version. |
| .TP |
| .B \fBCUDA_VERSION\fP, \fBCUDA_VERSION_STRING\fP |
| Full version in the \fBX.Y\fP format. |
| .TP |
| .B \fBCUDA_HAS_FP16\fP |
| New in version 3.6: Whether a short float (\fBfloat16\fP, \fBfp16\fP) is supported. |
| |
| .TP |
| .B \fBCUDA_TOOLKIT_ROOT_DIR\fP |
| Path to the CUDA Toolkit (defined if not set). |
| .TP |
| .B \fBCUDA_SDK_ROOT_DIR\fP |
| Path to the CUDA SDK. Use this to find files in the SDK. This script will |
| not directly support finding specific libraries or headers, as that isn\(aqt |
| supported by NVIDIA. If you want to change libraries when the path changes |
| see the \fBFindCUDA.cmake\fP script for an example of how to clear these |
| variables. There are also examples of how to use the \fBCUDA_SDK_ROOT_DIR\fP |
| to locate headers or libraries, if you so choose (at your own risk). |
| .TP |
| .B \fBCUDA_INCLUDE_DIRS\fP |
| Include directory for cuda headers. Added automatically |
| for \fBcuda_add_executable()\fP and \fBcuda_add_library()\fP\&. |
| .TP |
| .B \fBCUDA_LIBRARIES\fP |
| Cuda RT library. |
| .TP |
| .B \fBCUDA_CUFFT_LIBRARIES\fP |
| Device or emulation library for the Cuda FFT implementation (alternative to |
| \fBcuda_add_cufft_to_target()\fP macro) |
| .TP |
| .B \fBCUDA_CUBLAS_LIBRARIES\fP |
| Device or emulation library for the Cuda BLAS implementation (alternative to |
| \fBcuda_add_cublas_to_target()\fP macro). |
| .TP |
| .B \fBCUDA_cudart_static_LIBRARY\fP |
| Statically linkable cuda runtime library. |
| Only available for CUDA version 5.5+. |
| .TP |
| .B \fBCUDA_cudadevrt_LIBRARY\fP |
| New in version 3.7: Device runtime library. Required for separable compilation. |
| |
| .TP |
| .B \fBCUDA_cupti_LIBRARY\fP |
| CUDA Profiling Tools Interface library. |
| Only available for CUDA version 4.0+. |
| .TP |
| .B \fBCUDA_curand_LIBRARY\fP |
| CUDA Random Number Generation library. |
| Only available for CUDA version 3.2+. |
| .TP |
| .B \fBCUDA_cusolver_LIBRARY\fP |
| New in version 3.2: CUDA Direct Solver library. |
| Only available for CUDA version 7.0+. |
| |
| .TP |
| .B \fBCUDA_cusparse_LIBRARY\fP |
| CUDA Sparse Matrix library. |
| Only available for CUDA version 3.2+. |
| .TP |
| .B \fBCUDA_npp_LIBRARY\fP |
| NVIDIA Performance Primitives lib. |
| Only available for CUDA version 4.0+. |
| .TP |
| .B \fBCUDA_nppc_LIBRARY\fP |
| NVIDIA Performance Primitives lib (core). |
| Only available for CUDA version 5.5+. |
| .TP |
| .B \fBCUDA_nppi_LIBRARY\fP |
| NVIDIA Performance Primitives lib (image processing). |
| Only available for CUDA version 5.5 \- 8.0. |
| .TP |
| .B \fBCUDA_nppial_LIBRARY\fP |
| NVIDIA Performance Primitives lib (image processing). |
| Only available for CUDA version 9.0. |
| .TP |
| .B \fBCUDA_nppicc_LIBRARY\fP |
| NVIDIA Performance Primitives lib (image processing). |
| Only available for CUDA version 9.0. |
| .TP |
| .B \fBCUDA_nppicom_LIBRARY\fP |
| NVIDIA Performance Primitives lib (image processing). |
| Only available for CUDA version 9.0 \- 10.2. |
| Replaced by nvjpeg. |
| .TP |
| .B \fBCUDA_nppidei_LIBRARY\fP |
| NVIDIA Performance Primitives lib (image processing). |
| Only available for CUDA version 9.0. |
| .TP |
| .B \fBCUDA_nppif_LIBRARY\fP |
| NVIDIA Performance Primitives lib (image processing). |
| Only available for CUDA version 9.0. |
| .TP |
| .B \fBCUDA_nppig_LIBRARY\fP |
| NVIDIA Performance Primitives lib (image processing). |
| Only available for CUDA version 9.0. |
| .TP |
| .B \fBCUDA_nppim_LIBRARY\fP |
| NVIDIA Performance Primitives lib (image processing). |
| Only available for CUDA version 9.0. |
| .TP |
| .B \fBCUDA_nppist_LIBRARY\fP |
| NVIDIA Performance Primitives lib (image processing). |
| Only available for CUDA version 9.0. |
| .TP |
| .B \fBCUDA_nppisu_LIBRARY\fP |
| NVIDIA Performance Primitives lib (image processing). |
| Only available for CUDA version 9.0. |
| .TP |
| .B \fBCUDA_nppitc_LIBRARY\fP |
| NVIDIA Performance Primitives lib (image processing). |
| Only available for CUDA version 9.0. |
| .TP |
| .B \fBCUDA_npps_LIBRARY\fP |
| NVIDIA Performance Primitives lib (signal processing). |
| Only available for CUDA version 5.5+. |
| .TP |
| .B \fBCUDA_nvcuvenc_LIBRARY\fP |
| CUDA Video Encoder library. |
| Only available for CUDA version 3.2+. |
| Windows only. |
| .TP |
| .B \fBCUDA_nvcuvid_LIBRARY\fP |
| CUDA Video Decoder library. |
| Only available for CUDA version 3.2+. |
| Windows only. |
| .TP |
| .B \fBCUDA_nvToolsExt_LIBRARY\fP |
| New in version 3.16: NVIDA CUDA Tools Extension library. |
| Available for CUDA version 5+. |
| |
| .TP |
| .B \fBCUDA_OpenCL_LIBRARY\fP |
| New in version 3.16: NVIDA CUDA OpenCL library. |
| Available for CUDA version 5+. |
| |
| .UNINDENT |
| .SS FindPythonInterp |
| .sp |
| Deprecated since version 3.12: Use \fBFindPython3\fP, \fBFindPython2\fP or \fBFindPython\fP instead. |
| |
| .sp |
| Find python interpreter |
| .sp |
| This module finds if Python interpreter is installed and determines |
| where the executables are. This code sets the following variables: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| PYTHONINTERP_FOUND \- Was the Python executable found |
| PYTHON_EXECUTABLE \- path to the Python interpreter |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| PYTHON_VERSION_STRING \- Python version found e.g. 2.5.2 |
| PYTHON_VERSION_MAJOR \- Python major version found e.g. 2 |
| PYTHON_VERSION_MINOR \- Python minor version found e.g. 5 |
| PYTHON_VERSION_PATCH \- Python patch version found e.g. 2 |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The Python_ADDITIONAL_VERSIONS variable can be used to specify a list |
| of version numbers that should be taken into account when searching |
| for Python. You need to set this variable before calling |
| find_package(PythonInterp). |
| .sp |
| If calling both \fBfind_package(PythonInterp)\fP and |
| \fBfind_package(PythonLibs)\fP, call \fBfind_package(PythonInterp)\fP first to |
| get the currently active Python version by default with a consistent version |
| of PYTHON_LIBRARIES. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| A call to \fBfind_package(PythonInterp ${V})\fP for python version \fBV\fP |
| may find a \fBpython\fP executable with no version suffix. In this case |
| no attempt is made to avoid python executables from other versions. |
| Use \fBFindPython3\fP, \fBFindPython2\fP or \fBFindPython\fP |
| instead. |
| .UNINDENT |
| .UNINDENT |
| .SS FindPythonLibs |
| .sp |
| Deprecated since version 3.12: Use \fBFindPython3\fP, \fBFindPython2\fP or \fBFindPython\fP instead. |
| |
| .sp |
| Find python libraries |
| .sp |
| This module finds if Python is installed and determines where the |
| include files and libraries are. It also determines what the name of |
| the library is. This code sets the following variables: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| PYTHONLIBS_FOUND \- have the Python libs been found |
| PYTHON_LIBRARIES \- path to the python library |
| PYTHON_INCLUDE_PATH \- path to where Python.h is found (deprecated) |
| PYTHON_INCLUDE_DIRS \- path to where Python.h is found |
| PYTHON_DEBUG_LIBRARIES \- path to the debug library (deprecated) |
| PYTHONLIBS_VERSION_STRING \- version of the Python libs found (since CMake 2.8.8) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The Python_ADDITIONAL_VERSIONS variable can be used to specify a list |
| of version numbers that should be taken into account when searching |
| for Python. You need to set this variable before calling |
| find_package(PythonLibs). |
| .sp |
| If you\(aqd like to specify the installation of Python to use, you should |
| modify the following cache variables: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| PYTHON_LIBRARY \- path to the python library |
| PYTHON_INCLUDE_DIR \- path to where Python.h is found |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| If calling both \fBfind_package(PythonInterp)\fP and |
| \fBfind_package(PythonLibs)\fP, call \fBfind_package(PythonInterp)\fP first to |
| get the currently active Python version by default with a consistent version |
| of PYTHON_LIBRARIES. |
| .SS FindQt |
| .sp |
| Deprecated since version 3.14: This module is available only if policy \fBCMP0084\fP is not set to \fBNEW\fP\&. |
| |
| .sp |
| Searches for all installed versions of Qt3 or Qt4. |
| .sp |
| This module cannot handle Qt5 or any later versions. |
| For those, see \fBcmake\-qt(7)\fP\&. |
| .sp |
| This module should only be used if your project can work with multiple |
| versions of Qt. If not, you should just directly use FindQt4 or |
| FindQt3. If multiple versions of Qt are found on the machine, then |
| The user must set the option DESIRED_QT_VERSION to the version they |
| want to use. If only one version of qt is found on the machine, then |
| the DESIRED_QT_VERSION is set to that version and the matching FindQt3 |
| or FindQt4 module is included. Once the user sets DESIRED_QT_VERSION, |
| then the FindQt3 or FindQt4 module is included. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| QT_REQUIRED if this is set to TRUE then if CMake can |
| not find Qt4 or Qt3 an error is raised |
| and a message is sent to the user. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| DESIRED_QT_VERSION OPTION is created |
| QT4_INSTALLED is set to TRUE if qt4 is found. |
| QT3_INSTALLED is set to TRUE if qt3 is found. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FindwxWindows |
| .sp |
| Deprecated since version 3.0: Replaced by \fBFindwxWidgets\fP\&. |
| |
| .sp |
| Find wxWindows (wxWidgets) installation |
| .sp |
| This module finds if wxWindows/wxWidgets is installed and determines |
| where the include files and libraries are. It also determines what |
| the name of the library is. This code sets the following variables: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| WXWINDOWS_FOUND = system has WxWindows |
| WXWINDOWS_LIBRARIES = path to the wxWindows libraries |
| on Unix/Linux with additional |
| linker flags from |
| "wx\-config \-\-libs" |
| CMAKE_WXWINDOWS_CXX_FLAGS = Compiler flags for wxWindows, |
| essentially "\(gawx\-config \-\-cxxflags\(ga" |
| on Linux |
| WXWINDOWS_INCLUDE_DIR = where to find "wx/wx.h" and "wx/setup.h" |
| WXWINDOWS_LINK_DIRECTORIES = link directories, useful for rpath on |
| Unix |
| WXWINDOWS_DEFINITIONS = extra defines |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| OPTIONS If you need OpenGL support please |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(WXWINDOWS_USE_GL 1) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| in your CMakeLists.txt \fIbefore\fP you include this file. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| HAVE_ISYSTEM \- true required to replace \-I by \-isystem on g++ |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| For convenience include Use_wxWindows.cmake in your project\(aqs |
| CMakeLists.txt using |
| include(${CMAKE_CURRENT_LIST_DIR}/Use_wxWindows.cmake). |
| .sp |
| USAGE |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(WXWINDOWS_USE_GL 1) |
| find_package(wxWindows) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| NOTES wxWidgets 2.6.x is supported for monolithic builds e.g. |
| compiled in wx/build/msw dir as: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| nmake \-f makefile.vc BUILD=debug SHARED=0 USE_OPENGL=1 MONOLITHIC=1 |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| DEPRECATED |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| CMAKE_WX_CAN_COMPILE |
| WXWINDOWS_LIBRARY |
| CMAKE_WX_CXX_FLAGS |
| WXWINDOWS_INCLUDE_PATH |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| AUTHOR Jan Woetzel <\fI\%http://www.mip.informatik.uni\-kiel.de/~jw\fP> |
| (07/2003\-01/2006) |
| .SS Legacy CPack Modules |
| .sp |
| These modules used to be mistakenly exposed to the user, and have been moved |
| out of user visibility. They are for CPack internal use, and should never be |
| used directly. |
| .SS CPackArchive |
| .sp |
| New in version 3.9. |
| |
| .sp |
| The documentation for the CPack Archive generator has moved here: \fBCPack Archive Generator\fP |
| .SS CPackBundle |
| .sp |
| The documentation for the CPack Bundle generator has moved here: \fBCPack Bundle Generator\fP |
| .SS CPackCygwin |
| .sp |
| The documentation for the CPack Cygwin generator has moved here: \fBCPack Cygwin Generator\fP |
| .SS CPackDeb |
| .sp |
| The documentation for the CPack DEB generator has moved here: \fBCPack DEB Generator\fP |
| .SS CPackDMG |
| .sp |
| The documentation for the CPack DragNDrop generator has moved here: \fBCPack DragNDrop Generator\fP |
| .SS CPackFreeBSD |
| .sp |
| New in version 3.10. |
| |
| .sp |
| The documentation for the CPack FreeBSD generator has moved here: \fBCPack FreeBSD Generator\fP |
| .SS CPackNSIS |
| .sp |
| The documentation for the CPack NSIS generator has moved here: \fBCPack NSIS Generator\fP |
| .SS CPackNuGet |
| .sp |
| New in version 3.12. |
| |
| .sp |
| The documentation for the CPack NuGet generator has moved here: \fBCPack NuGet Generator\fP |
| .SS CPackPackageMaker |
| .sp |
| The documentation for the CPack PackageMaker generator has moved here: \fBCPack PackageMaker Generator\fP |
| .SS CPackProductBuild |
| .sp |
| New in version 3.7. |
| |
| .sp |
| The documentation for the CPack productbuild generator has moved here: \fBCPack productbuild Generator\fP |
| .SS CPackRPM |
| .sp |
| The documentation for the CPack RPM generator has moved here: \fBCPack RPM Generator\fP |
| .SS CPackWIX |
| .sp |
| The documentation for the CPack WIX generator has moved here: |
| \fBCPack WIX Generator\fP |
| .SH COPYRIGHT |
| 2000-2022 Kitware, Inc. and Contributors |
| .\" Generated by docutils manpage writer. |
| . |