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.mdCMake 工程主文件deps/xxHash/cmake_unofficial/CMakeLists.txt包配置模板deps/xxHash/cmake_unofficial/xxHashConfig.cmake.inxxHash 源码与头文件deps/xxHash/xxhash.h、deps/xxHash/xxhash.c、deps/xxHash/xxh3.h本仓库以第三方依赖形式 vendored 了 xxHash。从 deps/xxHash/xxhash.h 的版本宏可以确认当前版本为0.8.1XXH_VERSION_MAJOR0、XXH_VERSION_MINOR8、XXH_VERSION_RELEASE1CMake 工程文件会直接解析这三个宏来生成库的版本号与 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.7REQUIRED表示找不到即报错终止配置。导入成功后即可直接链接命名空间目标xxHash::xxhashPRIVATE 表明该依赖仅作用于MyTarget自身不向传递依赖暴露。构建选项一览按 README 原文cmake ../cmake_unofficial时可选传以下参数CMake 选项取值默认值作用-DXXHASH_BUILD_ENABLE_INLINE_APION/OFFON为-DXXH_INLINE_ALL内联 API 加入xxhash.c编译单元-DXXHASH_BUILD_XXHSUMON/OFFON是否构建命令行校验工具xxhsum-DBUILD_SHARED_LIBSON/OFFON是否构建动态库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}/man1CMake 包配置文件安装到${CMAKE_INSTALL_LIBDIR}/cmake/xxHash/包括xxHashConfig.cmake、xxHashConfigVersion.cmake与xxHashTargets.cmakepkg-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_ALLxxhash.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_MODEOFF走完整构建安装流程若作为子目录被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/SOVERSIONSOVERSION仅取主版本号0。版本信息单一来源避免手写两份。2. CMake 策略兼容处理。工程声明cmake_minimum_required(VERSION 2.8.12 FATAL_ERROR)对 CMake 3.13 启用CMP0077option()不覆盖普通变量保证下游set()预置生效对 CMake 3.0 启用CMP0048并将project(xxHash VERSION ... LANGUAGES C)改为带版本的项目声明兼顾新旧工具链。3. 默认 Release 与调试断言。未显式指定CMAKE_BUILD_TYPE时默认置为Release当构建类型为Debug且 CMake 3.12 时追加编译宏XXH_DEBUGLEVEL1从而启用assert()帮助排查问题见 xxhash.h 对XXH_DEBUGLEVEL的说明。4. 共享库导出宏。当BUILD_SHARED_LIBSON时对xxhash目标追加PUBLIC XXH_EXPORT编译定义配合XXH_IMPORTMSVC 动态链接场景控制符号的导入导出保证 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.cmakexxHashTargets.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基准测试程序可用于独立验证哈希正确性与性能。延伸阅读xxHash 算法特性、构建宏与示例代码deps/xxHash/README.mdCMake 集成指南原文deps/xxHash/cmake_unofficial/README.md完整 CMake 工程实现deps/xxHash/cmake_unofficial/CMakeLists.txtXXH3/XXH128 头文件deps/xxHash/xxh3.hRetroArch 中 zstd/XXH64 校验的实际使用libretro-common/encodings/encoding_rzstd.c【免费下载链接】RetroArchCross-platform, sophisticated frontend for the libretro API. Licensed GPLv3.项目地址: https://gitcode.com/GitHub_Trending/re/RetroArch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考