1 The role of find_package
find_package is the instruction in CMake used to find and load external libraries. It can search for library files in the system or user-specified path according to the specified parameters, and generate corresponding variables for subsequent use.
2 basic syntax of find_package
find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE]
[REQUIRED] [[COMPONENTS] [components...]]
[OPTIONAL_COMPONENTS components...]
[NO_POLICY_SCOPE])
Parameter explanation:
version: The version is appropriate (the major version number is the same)
EXACT: The versions must be consistent
QUIET: No error will be reported if the package is not found
REQUIRED: The package must be found, otherwise it will stop
Usage examples:
// 查找名为 OpenCV 的包，找不到不报错，也不打印任何信息。
find_package(OpenCV QUIET)
// 查找名为 OpenCV 的包，找不到就报错（并终止 cmake 进程，不再继续往下执行）
find_package(OpenCV REQUIRED) # 最常见用法
// 查找名为 OpenCV 的包，找不到就报错，且必须具有 OpenCV::core 和 OpenCV::videoio 这两个组件，如果没有这两个组件也会报错
find_package(OpenCV REQUIRED COMPONENTS core videoio)
//查找名为 OpenCV 的包，找不到就报错，可具有 OpenCV::core 和 OpenCV::videoio 这两个组件，没有这两组件不会报错，通过 ${OpenCV_core_FOUND} 查询是否找到 core 组件。
find_package(OpenCV REQUIRED OPTIONAL_COMPONENTS core videoio)
3 Find_package search path
The find_package directive will search for packages in the following paths:
System default path: find_package will first search for the package in the system default path. These paths usually include package directories provided by some common package managers and operating systems.
CMake module path: If CMake modules are enabled, find_package also looks for packages in the CMake module path. Additional module paths can be specified by setting the CMAKE_MODULE_PATH variable.
User-specified paths: Additional search paths can be specified using the CMAKE_PREFIX_PATH variable. In this way, find_package will search for packages in these specified paths.
Project path: If the project currently being processed has the CMAKE_PREFIX_PATH variable defined, then find_package will also search for the package in the path of the project.
In short, find_package will search for packages in the system default path, CMake module path, user-specified path and project path.
4 Two package finding modes of find_package
4.1 Introduction to Module mode and config mode
The find_package instruction has two modes for finding packages: module mode and configuration mode.
Module mode: In module mode, find_package will search for a file named <package>-config.cmake in the specified path. If this file is found, then it will add the directory where the file is located to the include directory and generate corresponding variables, such as <package>_INCLUDE_DIRS, <package>_LIBRARIES, etc. In this way, you can use the header files and library files provided by this package in your project.
Configuration mode (Config mode): In configuration mode, find_package will search for a file named <package>Config.cmake in the specified path. If this file is found, then it will add the directory where the file is located to the include directory and generate corresponding variables, such as <package>_INCLUDE_DIRS, <package>_LIBRARIES, etc. Then, it will call the add_subdirectory() function in the file to add the modules and configuration mode packages in the subdirectory to the search process. In this way, you can use the header files, library files provided by this package, and other packages in the subdirectory in your project.
4.2 Examples of using Module mode and config mode
Module mode (Module mode) and configuration mode (Config mode) are two modes of finding packages for the find_package instruction. Examples of usage of the two modes are given below:
Module mode:
Suppose we have a package named example, which provides a module named Example. We can use the module pattern to find and use this package.
First, add the following content in the CMakeLists.txt file:
# 设置寻找路径
set(CMAKE_PREFIX_PATH /path/to/search1 /path/to/search2)
# 查找名为"example"的包
find_package(example REQUIRED)
# 使用包中的模块
include_directories(${example_INCLUDE_DIRS})
add_executable(my_app main.cpp)
target_link_libraries(my_app ${example_LIBRARIES})
In this example, find_package will look for the package named example in the specified path. If the package is found, it will add the directory where the package is located to the include directory and generate corresponding variables, such as example_INCLUDE_DIRS, example_LIBRARIES, etc. Then, we can use the header files and library files provided by this package in the project.
Config mode:
Suppose we have a package named example, which provides a configuration script named ExampleConfig.cmake. We can use configuration mode to find and use this package.
First, add the following content in the CMakeLists.txt file:
# 设置寻找路径
set(CMAKE_PREFIX_PATH /path/to/search1 /path/to/search2)
# 查找名为"example"的包
find_package(example REQUIRED)
# 使用包中的配置脚本
include_directories(${example_INCLUDE_DIRS})
add_executable(my_app main.cpp)
target_link_libraries(my_app ${example_LIBRARIES})
In this example, find_package will look for the package named example in the specified path. If the package is found, it will add the directory where the package is located to the include directory and generate corresponding variables, such as example_INCLUDE_DIRS, example_LIBRARIES, etc. Then, it will call the add_subdirectory() function in the configuration file to add the modules and configuration mode packages in the subdirectory to the search process . In this way, we can use the header files, library files provided by this package, and other packages in the subdirectory in the project.