CMake中find_path的使用

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

find_path (
          
          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( 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) # 如果没找到目录,结果将为-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：指定由命名的缓存条目的文档字符串，即在CMakeCache.txt文件中会增加对的描述。示例代码段如下：

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()加载的任何其它脚本，搜索当前package唯一的前缀。具体来说，查看_ROOT CMake变量和_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.换句话说，搜索顺序将是：_ROOT, ENV{_ROOT}, _ROOT, ENV{_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