diff options
Diffstat (limited to 'Help/command/find_library.rst')
| -rw-r--r-- | Help/command/find_library.rst | 171 |
1 files changed, 171 insertions, 0 deletions
diff --git a/Help/command/find_library.rst b/Help/command/find_library.rst new file mode 100644 index 0000000..39ec4af --- /dev/null +++ b/Help/command/find_library.rst @@ -0,0 +1,171 @@ +find_library +------------ + +Find a library. + +:: + + find_library(<VAR> name1 [path1 path2 ...]) + +This is the short-hand signature for the command that is sufficient in +many cases. It is the same as find_library(<VAR> name1 [PATHS path1 +path2 ...]) + +:: + + find_library( + <VAR> + name | NAMES name1 [name2 ...] [NAMES_PER_DIR] + [HINTS path1 [path2 ... ENV var]] + [PATHS path1 [path2 ... ENV var]] + [PATH_SUFFIXES suffix1 [suffix2 ...]] + [DOC "cache documentation string"] + [NO_DEFAULT_PATH] + [NO_CMAKE_ENVIRONMENT_PATH] + [NO_CMAKE_PATH] + [NO_SYSTEM_ENVIRONMENT_PATH] + [NO_CMAKE_SYSTEM_PATH] + [CMAKE_FIND_ROOT_PATH_BOTH | + ONLY_CMAKE_FIND_ROOT_PATH | + NO_CMAKE_FIND_ROOT_PATH] + ) + +This command is used to find a library. A cache entry named by <VAR> +is created to store the result of this command. If the library is +found the result is stored in the variable and the search will not be +repeated unless the variable is cleared. If nothing is found, the +result will be <VAR>-NOTFOUND, and the search will be attempted again +the next time find_library is invoked with the same variable. The +name of the library that is searched for is specified by the names +listed after the NAMES argument. Additional search locations can be +specified after the PATHS argument. If ENV var is found in the HINTS +or PATHS section the environment variable var will be read and +converted from a system environment variable to a cmake style list of +paths. For example ENV PATH would be a way to list the system path +variable. The argument after DOC will be used for the documentation +string in the cache. PATH_SUFFIXES specifies additional +subdirectories to check below each search path. + +If NO_DEFAULT_PATH is specified, then no additional paths are added to +the search. If NO_DEFAULT_PATH is not specified, the search process +is as follows: + +1. Search paths specified in cmake-specific cache variables. These +are intended to be used on the command line with a -DVAR=value. This +can be skipped if NO_CMAKE_PATH is passed. + +:: + + <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and + <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH + CMAKE_LIBRARY_PATH + CMAKE_FRAMEWORK_PATH + +2. Search paths specified in cmake-specific environment variables. +These are intended to be set in the user's shell configuration. This +can be skipped if NO_CMAKE_ENVIRONMENT_PATH is passed. + +:: + + <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and + <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH + CMAKE_LIBRARY_PATH + CMAKE_FRAMEWORK_PATH + +3. Search the paths specified by the HINTS option. These should be +paths computed by system introspection, such as a hint provided by the +location of another item already found. Hard-coded guesses should be +specified with the PATHS option. + +4. Search the standard system environment variables. This can be +skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument. + +:: + + PATH + LIB + +5. Search cmake variables defined in the Platform files for the +current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is +passed. + +:: + + <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and + <prefix>/lib for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH + CMAKE_SYSTEM_LIBRARY_PATH + CMAKE_SYSTEM_FRAMEWORK_PATH + +6. Search the paths specified by the PATHS option or in the +short-hand version of the command. These are typically hard-coded +guesses. + +On Darwin or systems supporting OS X Frameworks, the cmake variable +CMAKE_FIND_FRAMEWORK can be set to empty or one of the following: + +:: + + "FIRST" - Try to find frameworks before standard + libraries or headers. This is the default on Darwin. + "LAST" - Try to find frameworks after standard + libraries or headers. + "ONLY" - Only try to find frameworks. + "NEVER" - Never try to find frameworks. + +On Darwin or systems supporting OS X Application Bundles, the cmake +variable CMAKE_FIND_APPBUNDLE can be set to empty or one of the +following: + +:: + + "FIRST" - Try to find application bundles before standard + programs. This is the default on Darwin. + "LAST" - Try to find application bundles after standard + programs. + "ONLY" - Only try to find application bundles. + "NEVER" - Never try to find application bundles. + +The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more +directories to be prepended to all other search directories. This +effectively "re-roots" the entire search under given locations. By +default it is empty. It is especially useful when cross-compiling to +point to the root directory of the target environment and CMake will +search there too. By default at first the directories listed in +CMAKE_FIND_ROOT_PATH and then the non-rooted directories will be +searched. The default behavior can be adjusted by setting +CMAKE_FIND_ROOT_PATH_MODE_LIBRARY. This behavior can be manually +overridden on a per-call basis. By using CMAKE_FIND_ROOT_PATH_BOTH +the search order will be as described above. If +NO_CMAKE_FIND_ROOT_PATH is used then CMAKE_FIND_ROOT_PATH will not be +used. If ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted +directories will be searched. + +The default search order is designed to be most-specific to +least-specific for common use cases. Projects may override the order +by simply calling the command multiple times and using the NO_* +options: + +:: + + find_library(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH) + find_library(<VAR> NAMES name) + +Once one of the calls succeeds the result variable will be set and +stored in the cache so that no call will search again. + +When more than one value is given to the NAMES option this command by +default will consider one name at a time and search every directory +for it. The NAMES_PER_DIR option tells this command to consider one +directory at a time and search for all names in it. + +If the library found is a framework, then VAR will be set to the full +path to the framework <fullPath>/A.framework. When a full path to a +framework is used as a library, CMake will use a -framework A, and a +-F<fullPath> to link the framework to the target. + +If the global property FIND_LIBRARY_USE_LIB64_PATHS is set all search +paths will be tested as normal, with "64/" appended, and with all +matches of "lib/" replaced with "lib64/". This property is +automatically set for the platforms that are known to need it if at +least one of the languages supported by the PROJECT command is +enabled. |