CMake中find_path的使用

Posted fengbingchun

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了CMake中find_path的使用相关的知识,希望对你有一定的参考价值。

      CMake中的命令find_path用于查找指定的文件的目录,其格式如下:将创建一个由<VAR>命名的缓存条目即cache变量,将<VAR>的值存入CMakeCache.txt中);或如果指定了NO_CACHE,由<VAR>命名的普通变量来存储此命令的结果。如果指定的文件在目录中找到,则结果将存储在<VAR>中除非清除<VAR>,否则不会重复搜索如果没找到,结果将为<VAR>-NOTFOUND

find_path (
          <VAR>
          name | NAMES name1 [name2 ...]
          [HINTS [path | ENV var]... ]
          [PATHS [path | ENV var]... ]
          [REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)]
          [PATH_SUFFIXES suffix1 [suffix2 ...]]
          [DOC "cache documentation string"]
          [NO_CACHE]
          [REQUIRED]
          [NO_DEFAULT_PATH]
          [NO_PACKAGE_ROOT_PATH]
          [NO_CMAKE_PATH]
          [NO_CMAKE_ENVIRONMENT_PATH]
          [NO_SYSTEM_ENVIRONMENT_PATH]
          [NO_CMAKE_SYSTEM_PATH]
          [NO_CMAKE_INSTALL_PREFIX]
          [CMAKE_FIND_ROOT_PATH_BOTH |
           ONLY_CMAKE_FIND_ROOT_PATH |
           NO_CMAKE_FIND_ROOT_PATH]
)

      选项包括:
      (1).NAMES:为要查找的目录中的文件指定一个或多个可能的名字。当使用它来指定带有和不带有版本后缀的名称时,建议首先指定不受版本控制的名字,以便在发行版(distributions)提供的软件包之前找到本地构建的软件包。示例代码段如下:

unset(var CACHE) # 清除变量,带有CACHE也从缓存文件CMakeCache.txt中清除,若不带CACHE则缓存文件CMakeCache.txt中仍然存在var的值
find_path(var NAMES opencv.hpp HINTS /opt/opencv3.1/include/opencv2)
message("var: $var") # var: /opt/opencv3.1/include/opencv2

unset(var CACHE)
find_path(var string.h) # 最简格式:find_path(<VAR> name),查找默认路径
message("var: $var") # var: /usr/include

# 如果找到目录,则结果将存储在变量中,除非清除变量,否则不会重复搜索
find_path(var NAMES opencv.hpp HINTS /opt/opencv3.1/include/opencv2) # 注意:未清除变量,不会重复搜索,最终结果是不对的,并没有查找opencv.hpp文件所在的目录
message("var: $var") # var: /usr/include

unset(var) # 若不带CACHE,则var是/usr/include而不是/opt/opencv3.1/include/opencv2
find_path(var NAMES opencv.hpp HINTS /opt/opencv3.1/include/opencv2)
message("var: $var") # var: /usr/include

unset(var CACHE)
find_path(var NAMES opencv.hpp) # 如果没找到目录,结果将为<VAR>-NOTFOUND
message("var: $var") # var: var-NOTFOUND
if($var STREQUAL "var-NOTFOUND")
	message(WARNING "the specified directory was not found")
endif()
if(NOT var) # 注意这里是var不是$var
	message(WARNING "the specified directory was not found")
endif()

unset(var) # 不带CACHE则缓存文件CMakeCache.txt中仍然存在var的值

      (2).HINTS, PATHS:指定除默认位置外要搜索的目录。"ENV var"子选项从系统环境变量读取路径。注意HINTS与PATHS区别:HINTS是在搜索系统路径之前先搜索HINTS指定的路径。PATHS是先搜索系统路径,然后再搜索PATHS指定的路径。示例代码段如下:

# 手动在/opt目录下建了个空的string.h文件
unset(var CACHE)
find_path(var NAMES string.h PATHS /opt) # PATHS:先搜索系统路径,然后再搜索PATHS指定的路径
message("var: $var") # var: /usr/include

unset(var CACHE)
find_path(var NAMES string.h HINTS /opt) # HINTS:先搜索HINTS指定的路径,然后再搜索系统路径
message("var: $var") # var: /opt

      (3).REGISTRY_VIEW:3.24版本中引入。指定必须要查询的注册表视图。此选项仅在Windows平台上有意义,在其它平台上将被忽略。
      (4).PATH_SUFFIXES:若在PATHS或HINTS指定的路径中没有找到,则继续会在PATHS/PATH_SUFFIXES或HINTS/PATH_SUFFIXES指定的路径中搜索。示例代码段如下:

unset(var CACHE)
find_path(var NAMES opencv.hpp PATHS /opt/opencv3.1/ NO_DEFAULT_PATH) # 仅搜索:/opt/opencv3.1/ 
message("var: $var") # var: var-NOTFOUND

unset(var CACHE)
find_path(var NAMES opencv.hpp PATHS /opt/opencv3.1 PATH_SUFFIXES include/opencv2 NO_DEFAULT_PATH) # 搜索:(1)./opt/opencv3.1/; (2)./opt/opencv3.1/include/opencv2/
message("var: $var") # var: /opt/opencv3.1/include/opencv2

unset(var CACHE)
find_path(var NAMES opencv.hpp PATHS /opt/opencv3.4.2/ NO_DEFAULT_PATH) # 仅搜索:/opt/opencv3.4.2/ 
message("var: $var") # var: var-NOTFOUND

unset(var CACHE)
find_path(var NAMES opencv.hpp HINTS /opt/opencv3.4.2 PATH_SUFFIXES include/opencv2 NO_DEFAULT_PATH) # 搜索:(1)./opt/opencv3.4.2/; (2)./opt/opencv3.4.2/include/opencv2/
message("var: $var") # var: /opt/opencv3.4.2/include/opencv2

      (5).DOC:指定由<VAR>命名的缓存条目的文档字符串,即在CMakeCache.txt文件中会增加对<VAR>的描述。示例代码段如下:

unset(var CACHE)
find_path(var NAMES opencv.hpp HINTS /opt/opencv3.1/include/opencv2 DOC "opencv head file") # CMakeCache.txt中会对var增加注释说明
message("var: $var") # var: /opt/opencv3.1/include/opencv2

      在没有添加DOC选项时,CMakeCache.txt中var内容为:

//Path to a file.
var:PATH=/opt/opencv3.1/include/opencv2

      添加DOC选项后,CMakeCache.txt中var内容变为:

//opencv head file
var:PATH=/opt/opencv3.1/include/opencv2

      (6).NO_CACHE:3.21版本中引入。搜索结果将存储在普通变量中而不是缓存条目中。如果变量在调用之前已经设置(作为普通变量或缓存变量),则搜索将不会发生。应谨慎使用此选项,因为它会大大增加重复配置步骤的成本。示例代码段如下:

unset(var1 CACHE)
find_path(var1 NAMES string.h NO_CACHE) # 带有NO_CACHE后,var1的值将不会存入CMakeCache.txt中
message("var1: $var1") # var1: /usr/include/

unset(var2 CACHE)
find_path(var2 NAMES string.h) # 不带NO_CACHE,var2的值将写入CMakeCache.txt中
message("var2: $var2") # var2: /usr/include/

      (7).REQUIRED:3.18版本中引入。如果未找到任何内容,则停止处理并触发错误消息,否则下次使用相同的变量调用find_path时将再次尝试搜索。示例代码段如下:

unset(var CACHE)
find_path(var NAMES opencv.hpp) # 找不到会继续后续的执行
message("var: $var") # var: var-NOTFOUND

unset(var CACHE)
find_path(var NAMES opencv.hpp REQUIRED) # 将触发error,停止后续的执行:CMake Error at test_find_path.cmake:76 (find_path): Could not find var using the following names: opencv.hpp

      (8).NO_DEFAULT_PATH:如果指定了此选项,则不会向搜索中添加其它路径。默认搜索路径将失效,只会搜索PATHS和HINTS指定的路径

# 手动在/opt目录下建了个空的string.h文件
unset(var CACHE)
find_path(var NAMES string.h PATHS /opt NO_DEFAULT_PATH) # 指定不使用默认路径,path最后带不带"/"均可
message("var: $var") # var: /opt

unset(var CACHE)
find_path(var NAMES string.h NO_DEFAULT_PATH)
message("var: $var") # var: var-NOTFOUND

unset(var CACHE)
find_path(var NAMES string.h)
message("var: $var") # var: /usr/include

      如果未指定NO_DEFAULT_PATH选项,则搜索过程如下:
      (1).3.12版本中引入。如果调用来自于find module或通过调用find_package(<PackageName>)加载的任何其它脚本,搜索当前package唯一的前缀。具体来说,查看<PackageName>_ROOT CMake变量和<PackageName>_ROOT环境变量。package root变量作为堆栈维护,因此如果从嵌套的find modules或config packages中调用,则root paths from the parent's find module or config package will be searched after paths from the current module or package.换句话说,搜索顺序将是:<CurrentPackage>_ROOT, ENV<CurrentPackage>_ROOT, <ParentPackage>_ROOT, ENV<ParentPackage>_ROOT等。如果设置了NO_PACKAGE_ROOT_PATH或将CMAKE_FIND_USE_PACKAGE_ROOT_PATH设置为FALSE,则可以跳过此步骤。
      (2).在特定于cmake(cmake-specific)的缓存变量中指定的搜索路径。这些旨在通过-DVAR=value在命令行上使用。这些值被解释为分号分割的列表。如果设置了NO_CMAKE_PATH或将CMAKE_FIND_USE_CMAKE_PATH设置为FALSE,则可以跳过此步骤。
      (3).在特定于cmake(cmake-specific)的环境变量中指定的搜索路径。这些旨在用户的shell配置中设置。如果设置了NO_CMAKE_ENVIRONMENT_PATH或将CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH设置为FALSE,则可以跳过此步骤。
      (4).搜索由HINTS选项指定的路径。这些应该是系统introspection计算的路径。
      (5).在标准系统环境变量(standard system environment variables)中指定的搜索路径。如果设置了NO_SYSTEM_ENVIRONMENT_PATH或将CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH设置为FALSE,则可以跳过此操作。
      (6).搜索当前系统的Platform文件中定义的cmake变量。如果设置了NO_CMAKE_INSTALL_PREFIX或将CMAKE_FIND_USE_INSTALL_PREFIX设置为FALSE,则可以跳过搜索CMAKE_INSTALL_PREFIX和CMAKE_STAGING_PREFIX。如果设置了NO_CMAKE_SYSTEM_PATH或将CMAKE_FIND_USE_CMAKE_SYSTEM_PATH设置为FALSE,则可以跳过所有这些位置。The platform paths that these variables contain are locations that typically include installed software. An example being /usr/local for UNIX based platforms.
      (7).搜索由PATHS选项或in the short-hand version of the command指定的路径。These are typically hard-coded guesses.
      CMAKE_IGNORE_PATH, CMAKE_IGNORE_PREFIX_PATH, CMAKE_SYSTEM_IGNORE_PATH和CMAKE_SYSTEM_IGNORE_PREFIX_PATH变量也可能导致上述某些位置被忽略。

      以上测试代码搜索本机中的OpenCV头文件,本机中有多个版本的OpenCV库:
      (1).4.5.4:头文件存放路径,系统默认的安装路径,通过命令sudo apt install libopencv-dev安装:/usr/include/opencv4/; OpenCVConfig.cmake存放路径:/usr/lib/x86_64-linux-gnu/cmake/opencv4/
      (2).3.1:头文件存放路径:/opt/opencv3.1/include/; OpenCVConfig.cmake存放路径:/opt/opencv3.1/share/OpenCV/
      (3).3.4.2:头文件存放路径:/opt/opencv3.4.2/include/; OpenCVConfig.cmake存放路径:/opt/opencv3.4.2/share/OpenCV/

      执行上述测试代码需要3个文件:build.sh, CMakeLists.txt, test_find_path.cmake

     build.sh内容如下:

#! /bin/bash

# supported input parameters
params=(function macro cmake_parse_arguments \\
		find_library find_path find_file find_program find_package)

usage()

	echo "Error: $0 needs to have an input parameter"

	echo "supported input parameters:"
	for param in $params[@]; do
		echo "  $0 $param"
	done

	exit -1


if [ $# != 1 ]; then
	usage
fi

flag=0
for param in $params[@]; do
	if [ $1 == $param ]; then
		flag=1
		break
	fi
done

if [ $flag == 0 ]; then
	echo "Error: parameter \\"$1\\" is not supported"
	usage
	exit -1
fi

if [[ ! -d "build" ]]; then
	mkdir build
	cd build
else
	cd build
fi

echo "==== test $1 ===="
cmake -DTEST_CMAKE_FEATURE=$1 ..

      CMakeLists.txt内容如下:

CMAKE_MINIMUM_REQUIRED(VERSION 3.22)
PROJECT(cmake_feature_usage)

message("#### current cmake version: $CMAKE_MAJOR_VERSION.$CMAKE_MINOR_VERSION.$CMAKE_PATCH_VERSION")
include(test_$TEST_CMAKE_FEATURE.cmake)
message("==== test finish ====")

      test_find_path.cmake内容:为上面所有的示例代码

      执行可能的结果如下图所示:

      GitHub: https://github.com/fengbingchun/Linux_Code_Test

以上是关于CMake中find_path的使用的主要内容,如果未能解决你的问题,请参考以下文章

CMake基础教程(18)find_path查找文件路径

cmake find_path 其中路径包含版本号

如何通过CMake查找特定/本地文件

使用 CMake 查找 libffi 头文件

CMake比较实用的命令小记

如何创建正确的 Find***.cmake 文件