CMake Programming (ii) __ Programming

Cmd#29:find_file find the full path to a file.

   Find_file (<VAR> name1 [path1 path2 ...])

This is a streamlined format for the command, which is sufficient for most occasions. It is find_file with command (<VAR> name1 [PATHS path1 path2 ...]) is equivalent.

   Find_file (
             <VAR>
             name | NAMES name1 [name2 ...]
             [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 the full path to the specified file. A name is a <VAR> cache entry (see CMakeCache.txt's introduction--) variable is created to store the result of the command. If a full path to the file is found, the result is stored in the variable and the search process is not repeated unless the variable is cleared. If nothing is found, the result of the search will be <VAR>-NOTFOUND; and the search will retry the next time the find_file is called with the same variable. The file names of the files being searched are specified by the list of names after the names option. Additional search locations that are attached can be specified after the Paths option. If env var appears in the hints or paths segment, the environment variable var will be read and then converted to a system-level environment variable and stored in a CMake-style path list. For example, using ENV path will list the system's path variables. The variables after doc will be used for the document string (documentation string) in the cache. path_suffixes Specifies the subpath that needs to be searched under each search path.

If the No_default_path option is specified, no additional paths are appended to the search. If you do not specify the No_default_path option, the search process is as follows:

1, the search path specified in the CMake specific cache variable. These paths are used to set the-dvar=value in the command line. If the No_cmake_path option is used, the path is skipped. This translation may be wrong. The search path also includes:

For each path in the Cmake_prefix_path <prefix>,<prefix>/include
Variable: Cmake_include_path
Variable: Cmake_framework_path

2. Search the search path specified in the CMake specific environment variable. The path is set in the user's shell configuration. If the No_cmake_environment_path option is specified, the path is skipped. The search path also includes:

For each path in the Cmake_prefix_path <prefix>,<prefix>/include
Variable: Cmake_include_path
Variable: Cmake_framework_path

3, the search path specified by the HINTS option. These paths are computed by the system introspection (introspection), such as traces of the location of other items that have been discovered. hard-coded reference paths should be specified using the Paths option. (What is the difference between hints and paths?) Higher priority than the latter. Have questions. -----)

4, search the standard system environment variables. If you specify the No_system_environment_path option, the search path skips subsequent parameters. The search path includes the environment variable path include.

5. Find the CMake variable defined in the platform file of the current system. If the No_cmake_system_path option is specified, the path is skipped. Other search paths also include the following:

For each path in the Cmake_prefix_path <prefix>,<prefix>/include
Variable: Cmake_system_include_path
Variable: Cmake_system_framework_path

6, search the path specified by the Paths option or the path specified in the short version of the command. This is generally a hard coded reference path. On the Darwin latter system that supports the OS X framework, the CMake variable cmake_find_framwork can be set to null or one of the following values:

   "First"  -find the frame before the standard library or header file. For the Darwin system, this is the default.
   "Last"   -find the frame after the standard library or header file.
   "Only"   -look for frames only.
   "NEVER"-never find frames.

On Darwin or a system that supports OS X application bundles, the CMake variable cmake_find_appbundle can be set to null or one of the following values:

   "First"  -find application bundles before standard procedures, which is also the default option for the Darwin system.
   "Last"   -look for application bundlestry after standard programs.
   "only"   -find only application bundles.
   "NEVER"-Never find application bundles.

The CMake variable cmake_find_root_path specifies one or more search paths before all other search paths. This option effectively assigns the highest priority path for the entire search path under the given location. By default, it is empty. When you cross-compile a target in the root directory in the target environment, CMake also searches for those paths, which is useful at this point. By default, the path listed in the cmake_find_root_path variable is searched first, followed by the non-root path. Set the Cmake_find_root_path_mode_include variable to adjust the default behavior. This behavior can be manually overwritten each time it is invoked. By using the Cmake_find_root_path_both variable, the search order will be the same as above. If the No_cmake_find_root_path variable is used, then Cmake_find_root_path will not be used. If you use the Only_cmake_find_root_path variable, only the path in Cmake_find_root_path (that is, the re-rooted directory) is searched.

In general, the default search order is from the most specific path to the least specific path. The project can override this order as long as the command is invoked multiple times with the no_* option.
Find_file (<VAR> NAMES name PATHS PATHS ... No_default_path)
Find_file (<VAR> NAMES name)

As soon as one of these calls succeeds, the return variable is set and stored in the cache, and the command is no longer searched.

Cmd#30:find_library Find a library file

   Find_library (<VAR> name1 [path1 path2 ...])

This is a short version of the command, which is sufficient in most cases. It is find_library with command (<VAR> name1 [PATHS path1 path2 ...]) Equivalent.

 find_library (<VAR> name |
             NAMES name1 [name2 ...] [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 file. A cache entry named <VAR> is created to store the results of the command. If the library file is found, the result is stored in the variable, and the search process is no longer repeated unless the variable is emptied. If not found, the result variable will be <var>-notfound, and the search process will try again the next time the Find_library command is invoked with the same variable. The filename listed after the names parameter is the name of the library to be searched. The additional search location is specified after the paths parameter. If you set the ENV variable var in the Hints or paths field, the environment variable var will be read and converted from the system environment variable to a cmake-style path list. For example, specifying the env path is a way to get the system path variable and convert it to a cmake list. The parameter after Doc is used as a comment string in the cache. The path_suffixes option specifies the sub paths to be searched under each search path.

If the No_default_path option is specified, there will be no additional paths in the search process. If you do not specify this option, the search process is as follows:

1, search cmake specific cache variable specified path. These variables are the variables specified by-dvar=value when using the CMake command line. If the No_cmake_path option is specified, these paths are skipped. The search path also includes:

   For each <prefix> in the Cmake_prefix_path, the path <prefix>/lib 
   cmake_library_path
   Cmake_framework_path

2. Search the path specified by the CMake specific environment variable. These variables are variables set in the user's shell configuration. If the No_cmake_environment_path option is specified, these paths are skipped. The search path also includes:

   For each <prefix> in the Cmake_prefix_path, the path <prefix>/lib 
   cmake_library_path
   Cmake_framework_path

3, search the path specified by the HINTS option. These paths are the paths estimated by the system introspection (introspection), such as reference information provided by the address of another discovered library file. Hard-coded recommended paths should be specified through the Paths option.

4, find the standard system environment variables. If the No_system_environment_path option is specified, these paths are skipped. The search path also includes:

   PATH
   LIB

5, find the CMake variable defined in the platform file for the current system. If the No_cmake_system_path option is specified, the path is skipped. The search path also includes:

   For each <prefix> in the Cmake_system_prefix_path, the path <prefix>/lib 
   cmake_system_library_path
   CMAKE_ System_framework_path

6, search paths option or the path specified by the compact command. These are usually hard-coded recommended search paths.

On Darwin or a system that supports the OS X framework, the CMake variable cmake_find_framework can be used to set to NULL, or one of the following values:

   "First"  -find the frame before a standard library or header file. This is the default option on the Darwin system.
   "Last"   -find the frame after the standard library or header file.
   "Only"   -just look for frames.
   "NEVER"-never find frames.

In Darwin or a system that supports OS X application bundles, CMake variable cmake_find_appbundle can be set to null or one of the following values:

   "First"  -find application bundles before a standard library or header file. This is the default option on the Darwin system.
   "Last"   -finds application bundles after a standard library or header file.
   "Only"   -just look for application bundles.
   "NEVER"-Never find application bundles.

The CMake variable cmake_find_root_path specifies one or more search paths that take precedence over other search paths. The variable can effectively reposition the root path of the search at a given location. The variable defaults to NULL. When using cross compilation, the variable is useful: Use the variable to point to the root of the target environment, and then CMake will find it there. By default, the paths listed in Cmake_find_root_path are searched first, followed by the "non-root" path. The default rule can be adjusted by setting the cmake_find_root_path_mode_library. You can manually override the default behavior by setting this variable before each call to the command. If the No_cmake_find_root_path variable is used, only the relocated path is searched.

The default search order design logic is based on the most specific to the least specific when used. You can override this default order for the project by invoking the Find_library command multiple times and the no_* option:

    Find_library (<VAR> NAMES name PATHS PATHS ... No_default_path)
   find_library (<VAR> NAMES name)

As long as one of these calls returns successfully, the resulting variable is set and stored in the cache, so that subsequent calls are not searched again. If the library found is a frame, VAR will be set to the full path to the frame "< full path >/a.framework". When a full path to a frame is used as a library file, CMake will use-framework A and-f< the full path > These two options to connect the framework to the target.

Cmd#31:find_package load settings for external projects.

  Find_package (<package> [version] [EXACT] [QUIET]
               [[required| Components] [components ...]]
               [No_policy_scope])

Locate and load the settings for the foreign project. The command sets the <package>_found variable to indicate whether the package being found is located. If the package is found, the information associated with it can be obtained from the variables recorded in the package itself. The quiet option will ban the substitution of warning messages when they are not found. The required option means that if the report is not found, the CMake process terminates and the warning message is output. After the required option, or if the required option is not specified but the components option is specified, some of the package-related part listings (components list) can be listed after them. The [version] parameter requires a version number, which is the version number (format is major[.minor[.patch[.tweak]] that the package you are looking for should be compatible with. The exact option requires that the version number must match exactly. The [version] and exact options automatically invoke forward inheritance from outside if a recursive call to the command is not given within Find-module. Support for versions currently exists only between packages and packages (see below).

The user code should generally use the simple call format described above to query the required packages. The remainder of this command document details the full command format of the find_package and the specific query process. We encourage you to continue reading the project maintenance staff who are looking for and providing packages through this command.

This command has two modes of searching for packages: module mode and configuration mode. When the command is invoked through the above streamlined format, the modular pattern is shared. In this mode, CMake searches for all files named Find<package>.cmake, where the path is specified by the variable by the Cmake_module_path variable specified when the CMake was installed. If the file is found, it is read and processed by the CMake. This pattern is responsible for locating packages, checking versions, and generating any other required information. Many lookup modules (Find-module) provide only limited, or even no support for versioning, to view the documentation for that module. If no modules are found, the command goes into configuration mode to continue execution.

The command format in full configuration mode is:

  Find_package (<package> [version] [EXACT] [QUIET]
               [[required| Components] [components ...]] [No_module]
               [No_policy_scope]
               [NAMES name1 [name2 ...]]
               [Configs config1 [Config2 ...]]
               [Hints path1 [path2 ...]]
               [PATHS path1 [path2 ...]]
               [Path_suffixes suffix1 [suffix2 ...]]
               [No_default_path]
               [No_cmake_environment_path]
               [No_cmake_path]
               [No_system_environment_path]
               [No_cmake_package_registry]
               [No_cmake_builds_path]
               [No_cmake_system_path]
               [Cmake_find_root_path_both |
                Only_cmake_find_root_path |
                No_cmake_find_root_path])

No_module can be used to explicitly skip module mode. It also implicitly specifies that you do not use those options that are used in a thin format.

Configuration mode attempts to find a location for the configuration file provided by the package to be looked up. The path containing the file is stored in a cache entry named <package>_dir. By default, this command searches for a package named <package>. If the names option is specified, then the names parameter replaces the role of <package>. This command searches for each file named <name>config.cmake or <name all lowercase >-config.cmake for each name in names. You can change the name of a possible configuration file by using the Configs option. The following describes the search process. If a configuration file is found, it will be read and processed by CMake. Because the file is provided by the package itself, it already knows the location of the content in the package. The full address of the configuration file is stored in the CMake variable <package>_config.

All cmake configuration files to be processed will search for the package installation information and store the appropriate version number (appropriate version) that matches the installation in CMake variable <package>_considered_configs. The version number (associated version) associated with it will be stored in the <package>_considered_versions.

If the package configuration file is not found, CMake will generate an error profile to describe the problem-unless the quiet option is specified. If the required option is specified and the package is not found, a fatal error is reported and the configuration step terminates execution. If the <package>_dir variable is set, but it does not contain profile information, then CMake will simply ignore it and start looking again.

If the [version] parameter is given, then configuration mode only finds those versions of the package that are requested in the command (format is major[.minor[.patch[.tweak]]) that are compatible with the version of the package request. If the exact option is specified, a package can only be found if the version it requests matches exactly the version provided by [version]. CMake does not make any conversion to the meaning of the version number. The package version number is checked by the package's own version file. For an alternative package profile <config-file>.cmake, the corresponding version file is positioned next to it, and the name is either <config-file>-version.cmake or < Config-file>version.cmake. If this version of the file is not available, the configuration file is considered incompatible with any of the requested versions. When a version file is found, it is loaded and then used to check the version number of the (find_package) request. The version file is loaded in a nested domain defined by the following variables:

   Package_find_name          = <package> name.
   package_find_version       = Requested full version string
   Package_find_version_major = If requested, it is MAJOR version number, otherwise it is 0.
   Package_find_version_minor = If requested, then it is the MINOR version number, otherwise it is 0.
   Package_find_version_patch = If requested, then it is the PATCH version number, otherwise it is 0.
   Package_find_version_tweak = If requested, then it is the TWEAK version number, otherwise it is 0.
   Package_find_version_count = version number contains several points, 0 to 4.

The version file checks to see if it satisfies the requested version number, and then sets the following variables:

  Package_version            = The complete version string provided.
  Package_version_exact      = Returns True if the version number matches exactly.
  package_version_compatible = Returns True if the version number is compatible.
  package_version_unsuitable = Returns true if it is not appropriate for any version.

The following variables will be checked by the Find_package command to determine whether the configuration file provides an acceptable version. After the Find_package command returns, these variables are not available. If the version is acceptable, the following variables will be set:

  <package>_version       = The complete version string provided.
  <package>_version_major = If requested, then it is the MAJOR version number, otherwise it is 0.
  <package>_version_minor = If requested, then it is the MINOR version number, otherwise it is 0.
  <package>_version_patch = If requested, then it is the PATCH version number, otherwise it is 0.
  <package>_version_tweak = If requested, then it is the TWEAK version number, otherwise it is 0.
  <package>_version_count = version number contains several points, 0 to 4.

The corresponding package configuration file is then loaded. When multiple package profiles are available, and the version files of these packages are compatible with the requested version, the choice of which package will be indeterminate. It should not be assumed that CMake will choose the highest or lowest version. (The above paragraphs are descriptions of the version matching steps in the find_package and do not require user intervention.) ）

Configuration mode provides an interface to advanced interfaces and search steps. Most of these provided interfaces are for completeness, and in modular mode, packages are find-module loaded for internal use. Most users should simply call:

  Find_package (<package> [Major[.minor]] [EXACT] [required| QUIET])

To find the package. Encourage package maintainers who need to provide CMake package profiles to name these files and install them, so the entire process below will find them without the need for additional options.

CMake constructs a set of possible installation prefixes for the package. Under each prefix, several directories are searched to find the configuration file. The following table shows the path to be searched. Each entry is specifically specified for the Windows (W), UNIX (U), or Apple (A)-Installed installation tree.

    <prefix>/                                               (W)
   <prefix>/(cmake| CMake)/                                 (w)
   <prefix>/<name>*/                                       (w)
   <prefix>/<name>*/(cmake| CMake)/                         (W)
   <prefix>/(share|lib)/cmake/<name>*/                     (U)
   <prefix>/(share|lib)/ <name>*/                           (U)
   <prefix>/(share|lib)/<name>*/(cmake| CMake)/             (U)

On systems that support OS X platforms and application bundles, the framework or bundles that contains the configuration files is searched in the following paths:

    <prefix>/<name>.framework/resources/                    (A)
   <prefix>/<name>.framework/resources/ cmake/              (a)
   <prefix>/<name>.framework/versions/*/resources/         (a)
   <prefix>/< name>.framework/versions/*/resources/cmake/   (A)
   <prefix>/<name>.app/contents/resources/                 (a)
   <prefix>/<name>.app/contents/resources/cmake/           (a)

In all of these cases the,<name> is case-sensitive and corresponds to any name given in <package> or by names.

These path sets are used to collaborate with engineering that provides configuration files on their respective installation trees. The above path, marked (W), is specifically set up for installation on Windows, where the <prefix> part may be the top-level installation path for an application. Those marked (U) are set specifically for installation on UNIX platforms, where <prefix> is shared by multiple packages. This is only a convention, so all (W) and (U) paths will still be searched on all platforms. The paths that are marked (A) are specifically set for installation on the Apple platform. The CMake variable cmake_find_framework and cmake_find_appbundle determine the order of preference, as follows:

The installation prefix is constructed from the following steps. If the No_default_path option is specified, all no_* options will be activated.

1, search in the CMake specific cache variable specified in the search path. These variables are designed to be specified on the command line with the-dvar=value option. You can skip the search path by specifying the No_cmake_path option. The search path also includes:

    Cmake_prefix_path
   Cmake_framework_path
   Cmake_appbundle_path

2, search cmake specific environment variables. These variables are designed to be configured in the user's shell configuration. You can skip the path by specifying the No_cmake_environment_path option. The search path includes:

   <package>_dir
   cmake_prefix_path
   cmake_framework_path
   Cmake_appbundle_path

3, search the path specified by the HINTS option. These paths should be generated when the operating system is introspective, such as a clue provided by the location of other items that have been found. hard-coded reference paths should be specified in the Paths option.

4, search the standard system environment variables. If the No_system_environment_path option is specified, these paths are skipped. Path entries that end with "/bin" or "/sbin" are automatically converted to their parent path. The search path includes:

   PATH

5, search the CMake GUI in the latest configuration of the construction of the project tree. You can skip these paths by setting the No_cmake_builds_path option. This is intended to be prepared when the user is building several interdependent projects in sequence.

6, search the path stored in the CMake User Pack registry. You can skip these paths by setting the No_cmake_package_registry option. When CMake uses export (package<name>) to configure a project, these paths are stored in the registry. See the documentation for the export (PACKAGE) command for more details.

7. Search the CMake variables defined in the current system's platform files. You can skip these paths with the No_cmake_system_path option.

   Cmake_system_prefix_path

   Cmake_system_framework_path

   Cmake_system_appbundle_path

8, search the path specified by the Paths option. These paths are generally hard-coded reference paths.

On Darwin or a system that supports the OS X framework, the CMake variable cmake_find_framework can be used to set to NULL, or one of the following values:

   "First"  -find the frame before a standard library or header file. This is the default option on the Darwin system.
   "Last"   -find the frame after the standard library or header file.
   "Only"   -just look for frames.
   "NEVER"-never find frames.

In Darwin or a system that supports OS X application bundles, CMake variable cmake_find_appbundle can be set to null or one of the following values:

    "First"  -find application bundles before a standard library or header file. This is the default option on the Darwin system.
   "Last"   -finds application bundles after a standard library or header file.
   "Only"   -just look for application bundles.
   "NEVER"-Never find application bundles.

The CMake variable cmake_find_root_path specifies one or more search paths that take precedence over other search paths. The variable can effectively reposition the root path of the search at a given location. The variable defaults to NULL. When using cross compilation, the variable is useful: Use the variable to point to the root of the target environment, and then CMake will find it there. By default, the paths listed in Cmake_find_root_path are searched first, followed by the "non-root" path. The default rule can be adjusted by setting the cmake_find_root_path_mode_library. You can manually override the default behavior by setting this variable before each call to the command. If the No_cmake_find_root_path variable is used, only the relocated path is searched.

The default search order design logic is based on the most specific to the least specific when used. You can override this default order for the project by invoking the Find_library command multiple times and the no_* option:

     Find_library (<VAR> NAMES name PATHS PATHS ... No_default_path)
    find_library (<VAR> NAMES name)

As long as one of these calls returns successfully, the resulting variable is set and stored in the cache, so that subsequent calls are not searched again. If the library found is a frame, VAR will be set to the full path to the frame "< full path >/a.framework". When a full path to a frame is used as a library file, CMake will use-framework A and-f< the full path > These two options to connect the framework to the target.

See the discussion of the No_policy_scope option in the documentation for the Cmake_policy () command.

Cmd#32:find_path search for a path containing a file