如何用CMake find_package正确引入Boost模块？含头文件模块问题

问题场景 #

查找常规Boost编译型模块（比如program_options）的CMake代码很直观：

cmake_minimum_required(VERSION 3.25)
project(win32)

set(CMAKE_CXX_STANDARD 17)

find_package(fmt CONFIG REQUIRED)
find_package(Boost REQUIRED COMPONENTS program_options)

add_executable(win32  main.cpp)

target_link_libraries(win32 PRIVATE fmt::fmt Boost::program_options)

但如果尝试给find_package添加lexical_cast这类仅头文件的Boost模块作为COMPONENTS参数，会直接报错，错误日志如下：

[0/1] Re-running CMake...
CMake Warning at C:/Users/isudfv/AppData/Local/JetBrains/Toolbox/apps/CLion/ch-0/231.8109.80/bin/cmake/win/x64/share/cmake-3.25/Modules/FindBoost.cmake:2218 (message):
  No header defined for lexical_cast; skipping header check (note:
  header-only libraries have no designated component)
Call Stack (most recent call first):
  C:/Program Files/Vcpkg/installed/x64-windows-static/share/boost/vcpkg-cmake-wrapper.cmake:11 (_find_package)
  C:/Program Files/Vcpkg/scripts/buildsystems/vcpkg.cmake:806 (include)
  CMakeLists.txt:8 (find_package)


CMake Error at C:/Users/isudfv/AppData/Local/JetBrains/Toolbox/apps/CLion/ch-0/231.8109.80/bin/cmake/win/x64/share/cmake-3.25/Modules/FindPackageHandleStandardArgs.cmake:230 (message):
  Could NOT find Boost (missing: lexical_cast) (found version "1.81.0")
Call Stack (most recent call first):
  C:/Users/isudfv/AppData/Local/JetBrains/Toolbox/apps/CLion/ch-0/231.8109.80/bin/cmake/win/x64/share/cmake-3.25/Modules/FindPackageHandleStandardArgs.cmake:600 (_FPHSA_FAILURE_MESSAGE)
  C:/Users/isudfv/AppData/Local/JetBrains/Toolbox/apps/CLion/ch-0/231.8109.80/bin/cmake/win/x64/share/cmake-3.25/Modules/FindBoost.cmake:2377 (find_package_handle_standard_args)
  C:/Program Files/Vcpkg/installed/x64-windows-static/share/boost/vcpkg-cmake-wrapper.cmake:11 (_find_package)
  C:/Program Files/Vcpkg/scripts/buildsystems/vcpkg.cmake:806 (include)
  CMakeLists.txt:8 (find_package)


ninja: error: rebuilding 'build.ninja': subcommand failed
-- Configuring incomplete, errors occurred!
See also "C:/Users/isudfv/Desktop/tmp/win32/cmake-build-release/CMakeFiles/CMakeOutput.log".
FAILED: build.ninja 

有人建议用target_include_directories手动指定Boost头文件路径，但这种写法会破坏CMake代码的统一性，其实有更规范的解决方式。

问题根源 #

CMake的FindBoost模块里，仅头文件的Boost库没有对应的组件标识，错误日志里的提示已经说得很清楚：header-only libraries have no designated component。所以不能把这类头文件模块加到COMPONENTS参数里。

正确解决方法 #

CMake为Boost头文件库提供了统一的导入目标Boost::headers，只要正确使用这个目标，就能和编译型组件的写法保持一致，不需要手动指定包含路径。

1. 仅使用头文件模块的场景 #

cmake_minimum_required(VERSION 3.25)
project(win32)

set(CMAKE_CXX_STANDARD 17)

find_package(fmt CONFIG REQUIRED)
# 不需要指定COMPONENTS，直接查找Boost
find_package(Boost REQUIRED)

add_executable(win32 main.cpp)

# 链接Boost::headers，自动添加Boost头文件路径
target_link_libraries(win32 PRIVATE fmt::fmt Boost::headers)

2. 同时使用编译型组件和头文件模块的场景 #

如果项目里既有program_options这类编译型组件，又要用到lexical_cast这类头文件模块，只需要在COMPONENTS里指定编译型组件，然后同时链接编译型组件目标和Boost::headers即可：

cmake_minimum_required(VERSION 3.25)
project(win32)

set(CMAKE_CXX_STANDARD 17)

find_package(fmt CONFIG REQUIRED)
# 仅指定编译型组件
find_package(Boost REQUIRED COMPONENTS program_options)

add_executable(win32 main.cpp)

# 同时链接编译型组件和头文件目标
target_link_libraries(win32 PRIVATE fmt::fmt Boost::program_options Boost::headers)

这种写法和编译型组件的链接方式完全统一，不需要额外的target_include_directories，符合CMake的现代目标导向写法规范。

内容的提问来源于stack exchange，提问作者isudfv