RetroArch 依赖 xxHash 0.8.1 的 CMake 集成指南：find_package 与 add

RetroArch 依赖 xxHash 0.8.1 的 CMake 集成指南：find_package 与 add_subdirectory 双路径实战

【免费下载链接】RetroArchCross-platform, sophisticated frontend for the libretro API. Licensed GPLv3.项目地址: https://gitcode.com/GitHub_Trending/re/RetroArch

本篇技术指南以 xxHash 官方 CMake 集成说明（仓库内 deps/xxHash/cmake_unofficial/README.md）为骨架，结合本仓库实际 vendor 的 xxHash 0.8.1 源码与 CMake 工程文件，完整讲解两种把 xxHash 接入下游 C/C++ 项目的标准做法：一是独立构建并install后通过find_package(xxHash CONFIG)导入；二是通过add_subdirectory直接作为子目录内嵌编译。读者将掌握全部构建选项的语义与默认值、导入/导出机制（xxHash::xxhash目标、xxHashConfig.cmake、pkg-config）、以及 bundled 模式下的行为差异，可直接迁移到自己的项目中使用。

关联文档与仓库上下文

集成指南原文：deps/xxHash/cmake_unofficial/README.md
CMake 工程主文件：deps/xxHash/cmake_unofficial/CMakeLists.txt
包配置模板：deps/xxHash/cmake_unofficial/xxHashConfig.cmake.in
xxHash 源码与头文件：deps/xxHash/xxhash.h、deps/xxHash/xxhash.c、deps/xxHash/xxh3.h

本仓库以第三方依赖形式 vendored 了 xxHash。从 deps/xxHash/xxhash.h 的版本宏可以确认当前版本为0.8.1（XXH_VERSION_MAJOR=0、XXH_VERSION_MINOR=8、XXH_VERSION_RELEASE=1），CMake 工程文件会直接解析这三个宏来生成库的版本号与 SOVERSION，因此集成方无需手工维护版本信息。

在 RetroArch 代码库中，xxHash 被真实用于校验 zstd 压缩帧的完整性——libretro-common/encodings/encoding_rzstd.c 的注释明确说明 zstd 帧的XXH64校验和会被跳过而不校验（读取侧兼容），这是理解该哈希库为何作为强制依赖被引入的典型场景。

方式一：独立构建并安装，通过 find_package 导入目标

这是文档给出的第一种集成路径，适合 xxHash 作为系统级/独立第三方库安装、多个项目共享一份二进制的情况。完整流程如下：

cd </path/to/xxHash/> mkdir build cd build cmake ../cmake_unofficial [options] cmake --build . cmake --build . --target install # 可选，安装到系统或指定前缀

对应到本仓库即为：

cd deps/xxHash mkdir build cd build cmake ../cmake_unofficial cmake --build . cmake --build . --target install

构建完成后，在下游工程的CMakeLists.txt中添加：

find_package(xxHash 0.7 CONFIG REQUIRED) ... target_link_libraries(MyTarget PRIVATE xxHash::xxhash)

find_package(xxHash 0.7 CONFIG REQUIRED)的含义是：以CONFIG 模式查找名为xxHash的包，并要求版本不低于 0.7；REQUIRED表示找不到即报错终止配置。导入成功后即可直接链接命名空间目标xxHash::xxhash（PRIVATE 表明该依赖仅作用于MyTarget自身，不向传递依赖暴露）。

构建选项一览

按 README 原文，cmake ../cmake_unofficial时可选传以下参数：

CMake 选项	取值	默认值	作用
`-DXXHASH_BUILD_ENABLE_INLINE_API`	`ON`/`OFF`	`ON`	为`-DXXH_INLINE_ALL`内联 API 加入`xxhash.c`编译单元
`-DXXHASH_BUILD_XXHSUM`	`ON`/`OFF`	`ON`	是否构建命令行校验工具`xxhsum`
`-DBUILD_SHARED_LIBS`	`ON`/`OFF`	`ON`	是否构建动态库（`OFF`则构建静态库）
`-DCMAKE_INSTALL_PREFIX`	路径	系统默认前缀	自定义安装前缀目录

XXH_INLINE_ALL是 xxHash 的重要编译宏：启用后所有函数变为inline，实现直接内嵌进xxhash.h，无需单独链接xxhash.o。xxHash 官方文档指出，当待哈希数据长度是编译期常量时，内联带来的小数据哈希性能提升可达 200% 以上。在 deps/xxHash/xxhash.h 中可以看到对应的用法示例——在被包含单元内先#define XXH_INLINE_ALL再#include "xxhash.h"，且此时不应再单独编译链接xxhash.o。

安装产物与 CONFIG 包导出

执行install后，CMakeLists.txt 会完成如下安装布局（均遵循GNUInstallDirs标准目录）：

库文件安装到${CMAKE_INSTALL_LIBDIR}（含SOVERSION/VERSION属性）；
公共头文件xxhash.h、xxh3.h安装到${CMAKE_INSTALL_INCLUDEDIR}；
xxhsum可执行文件安装到${CMAKE_INSTALL_BINDIR}，其 man 手册xxhsum.1安装到${CMAKE_INSTALL_MANDIR}/man1；
CMake 包配置文件安装到${CMAKE_INSTALL_LIBDIR}/cmake/xxHash/，包括xxHashConfig.cmake、xxHashConfigVersion.cmake与xxHashTargets.cmake；
pkg-config 文件libxxhash.pc安装到${CMAKE_INSTALL_LIBDIR}/pkgconfig。

这正是find_package(xxHash CONFIG)能被解析的原理：find_package在CMAKE_PREFIX_PATH/安装前缀下搜索xxHashConfig.cmake，而 xxHashConfig.cmake.in 仅有一行核心逻辑——include(${CMAKE_CURRENT_LIST_DIR}/xxHashTargets.cmake)，把install(EXPORT xxHashTargets NAMESPACE xxHash::)导出的目标（含xxHash::xxhash）加载进当前工程。版本兼容模式为AnyNewerVersion，即下游find_package(xxHash 0.7)时，任何 >= 0.7 的已安装版本均可匹配。

关于 XXHASH_BUILD_ENABLE_INLINE_API 的版本差异说明

需要特别指出：README 中记载的XXHASH_BUILD_ENABLE_INLINE_API选项，在当前仓库 vendor 的 0.8.1 版 CMakeLists.txt 中已不再作为显式 option 出现。从当前源码看，xxhash库目标直接以add_library(xxhash "${XXHASH_DIR}/xxhash.c")的方式无条件编译 deps/xxHash/xxhash.c；与此同时 xxHash 从 0.8.x 起已把实现整体移入xxhash.h（见 xxhash.h 的说明），xxhash.c仅作为传统链接方式的兼容入口保留。因此在新版本中，无论是否使用XXH_INLINE_ALL，xxhash.c都会被加入构建；该选项在 README 中属于对早期版本的说明，实际配置时以当前CMakeLists.txt为准即可。

方式二：add_subdirectory 内嵌集成（Bundled 模式）

当不想把 xxHash 作为独立包安装，而是直接随下游工程一起编译时，采用子目录方式。在下游工程的CMakeLists.txt中加入：

option(BUILD_SHARED_LIBS "Build shared libs" OFF) # 可选 ... set(XXHASH_BUILD_ENABLE_INLINE_API OFF) # 可选 set(XXHASH_BUILD_XXHSUM OFF) # 可选 add_subdirectory(</path/to/xxHash/cmake_unofficial/> </path/to/xxHash/build/> EXCLUDE_FROM_ALL) ... target_link_libraries(MyTarget PRIVATE xxHash::xxhash)

要点解读：

add_subdirectory的第一个参数必须指向cmake_unofficial/目录本身（工程文件所在地），第二个参数是 xxHash 的二进制输出目录，EXCLUDE_FROM_ALL保证不会把xxhsum等目标并入下游默认构建目标；
下游在add_subdirectory之前通过普通变量（set）预设XXHASH_BUILD_XXHSUM等值即可覆盖 xxHash 内部默认，无需改动 xxHash 源码；
子目录集成成功后，xxHash::xxhash这一命名空间别名目标同样立即可用，链接方式与方式一完全一致。

Bundled 模式的自动判定逻辑

从 CMakeLists.txt 源码可以看到一套自动化策略：

if(NOT DEFINED XXHASH_BUNDLED_MODE) if("${PROJECT_SOURCE_DIR}" STREQUAL "${CMAKE_SOURCE_DIR}") set(XXHASH_BUNDLED_MODE OFF) else() set(XXHASH_BUNDLED_MODE ON) endif() endif() CMAKE_DEPENDENT_OPTION(BUILD_SHARED_LIBS "Build shared libraries" ON "NOT XXHASH_BUNDLED_MODE" OFF)

即：若 xxHash 是顶层工程（PROJECT_SOURCE_DIR == CMAKE_SOURCE_DIR）则XXHASH_BUNDLED_MODE=OFF，走完整构建+安装流程；若作为子目录被add_subdirectory引入，则自动进入 Bundled 模式：强制静态库、跳过全部 install 规则（包括install(TARGETS ...)、头文件安装、man 页与 CONFIG 包导出、pkg-config 生成），只保留编译目标本身，从而不对宿主工程产生任何安装副作用。BUILD_SHARED_LIBS的默认值也会被该模式钳制为OFF。若确需覆盖，可在add_subdirectory前显式set(XXHASH_BUNDLED_MODE OFF)。

CMakeLists.txt 源码级要点剖析

结合 deps/xxHash/cmake_unofficial/CMakeLists.txt 的完整实现，可归纳出若干值得借鉴的工程细节：

1. 从头文件动态解析版本。通过file(STRINGS ...)正则匹配xxhash.h中的XXH_VERSION_MAJOR/MINOR/RELEASE三个宏，拼出XXHASH_VERSION_STRING（如本仓库的0.8.1）并作为project()版本与库VERSION/SOVERSION（SOVERSION仅取主版本号0）。版本信息单一来源，避免手写两份。

2. CMake 策略兼容处理。工程声明cmake_minimum_required(VERSION 2.8.12 FATAL_ERROR)，对 CMake >= 3.13 启用CMP0077（option()不覆盖普通变量，保证下游set()预置生效），对 CMake >= 3.0 启用CMP0048并将project(xxHash VERSION ... LANGUAGES C)改为带版本的项目声明，兼顾新旧工具链。

3. 默认 Release 与调试断言。未显式指定CMAKE_BUILD_TYPE时默认置为Release；当构建类型为Debug且 CMake >= 3.12 时追加编译宏XXH_DEBUGLEVEL=1，从而启用assert()帮助排查问题（见 xxhash.h 对XXH_DEBUGLEVEL的说明）。

4. 共享库导出宏。当BUILD_SHARED_LIBS=ON时，对xxhash目标追加PUBLIC XXH_EXPORT编译定义，配合XXH_IMPORT（MSVC 动态链接场景）控制符号的导入导出，保证 Windows 下 DLL 链接正确。

5. 双别名目标。add_library(xxhash ...)后紧跟add_library(xxHash::xxhash ALIAS xxhash)；xxhsum可执行程序（由 cli/xxhsum.c 与xsum_os_specific.c、xsum_output.c、xsum_sanity_check.c、xsum_bench.c组合而成）同理提供xxHash::xxhsum别名，且xxhsum仅PRIVATE链接xxhash。

6. 双通道依赖发现。同时导出 CMake CONFIG 包（xxHashConfig.cmake+xxHashTargets.cmake，命名空间xxHash::）与 pkg-config 文件（libxxhash.pc），使find_package(xxHash)与pkg_check_modules(xxhash)两种生态都能消费。

两种方式的对比与选型建议

维度	方式一：find_package 导入	方式二：add_subdirectory 子目录
构建主体	先独立构建并 install xxHash	随下游工程一起编译
版本控制	依赖安装环境中的版本	随源码仓库锁定版本，可复现
是否产生安装产物	是（含头文件/man/包配置/pc 文件）	否（Bundled 模式自动跳过 install）
库类型	可共享库或静态库	强制静态库（默认）
典型场景	系统级依赖、多项目共享	CI 可控、离线构建、vendored 依赖

对于 RetroArch 这类以可复现构建、跨平台为第一诉求的工程，把 xxHash 作为 vendor 依赖、以子目录方式接入是更贴合的做法——这正是本仓库将完整 xxHash 源码置于 deps/xxHash 的原因；同时其 cli/ 目录还提供了xxhsum命令行工具与xsum_bench.c基准测试程序，可用于独立验证哈希正确性与性能。