构建工具开发工具CLI【免费下载链接】CMakeMirror of CMake upstream repository项目地址https://gitcode.com/gh_mirrors/cm/CMake点击查看免费下载本文围绕 CMake 官方仓库中 FindProtobuf 模块 的完整文档展开系统讲解如何在 CMake 工程中查找并链接 Protocol BuffersProtobuf库、利用protobuf_generate系列命令在构建期自动从.proto文件生成 C/Python 源码并结合模块源码实现与仓库自带测试用例帮助读者掌握从find_package到代码生成、链接、gRPC 扩展的全链路集成方案。一、模块定位module mode 与 config mode 的区别Protocol Buffers 是 Google 开发的开源、语言中立、平台无关的结构化数据序列化机制常用于程序间或网络间的数据交换。CMake 官方提供的FindProtobuf模块位于 Modules/FindProtobuf.cmake其用途是在module mode下查找已安装的 Protobuf 库find_package(Protobuf [version] [...])需要特别注意的是模块文档开篇即强调如果 Protobuf 库是使用其CMake 构建系统构建并安装的它会提供一份package configuration file配置模式包此时应优先使用config modefind_package(Protobuf CONFIG)在 config mode 下导入目标和protobuf_generate等命令由上游 Protobuf 包自身提供本模块文档中记录的部分变量在 config mode 下不可用因为官方推荐直接使用导入目标具体用法以 Protobuf 上游文档为准。官方明确表示当 Protobuf 使用 CMake 构建时config mode 是推荐用法。本模块仅在 module mode 下工作即执行find_package(Protobuf)且未命中 config 包、或设置CMAKE_FIND_PACKAGE_PREFER_CONFIG FALSE时由 CMake 加载本模块完成查找。从版本演进看模块支持两个关键里程碑3.6find_package(Protobuf version)支持版本号参数所有输入/输出变量统一改用Protobuf_前缀PROTOBUF_前缀仅保留向后兼容。3.9 起陆续引入protobuf::libprotobuf、protobuf::libprotobuf-lite、protobuf::libprotoc导入库目标与protobuf::protoc导入可执行目标。二、导入目标Imported Targets当模块成功找到 Protobuf 后会提供以下导入目标均为::命名空间目标可直接用于target_link_libraries目标名引入版本说明protobuf::libprotobuf3.9封装完整 Protobuf 库的使用要求库存在即可用protobuf::libprotobuf-lite3.9封装精简版protobuf-lite库体积更小适用于嵌入式等受限场景protobuf::libprotoc3.9封装protoc库编译器库写编译器插件时使用protobuf::protoc3.10导入的protoc编译器可执行目标从源码实现看这些目标在 Modules/FindProtobuf.cmake 中以UNKNOWN IMPORTED/IMPORTED类型创建并附带精确的使用要求INTERFACE_INCLUDE_DIRECTORIES指向Protobuf_INCLUDE_DIR同时记录IMPORTED_LOCATION以及按配置区分的IMPORTED_LOCATION_RELEASE/IMPORTED_LOCATION_DEBUG由Protobuf_LIBRARY_RELEASE/Protobuf_LIBRARY_DEBUG驱动若Protobuf_VERSION不低于 3.6目标会附加INTERFACE_COMPILE_FEATURES cxx_std_11自动为下游目标启用 C11 编译特性见 Modules/FindProtobuf.cmake在 Windows 且未使用静态库时会自动附加PROTOBUF_USE_DLLS编译定义以匹配 DLL 导出约定在 UNIX 平台若找到Threads::Threads则自动追加链接Threads::ThreadsProtobuf 头文件可能依赖线程。三、结果变量与缓存变量3.1 结果变量Result Variables查找结束后模块会定义以下变量变量引入版本含义Protobuf_FOUND3.3是否找到指定版本Protobuf 库的布尔值Protobuf_VERSION3.6找到的 Protobuf 版本号Protobuf_INCLUDE_DIRS—使用 Protobuf 所需的头文件目录Protobuf_LIBRARIES—使用 Protobuf 需要链接的库列表Protobuf_PROTOC_LIBRARIES—使用protoc库需要链接的库列表Protobuf_LITE_LIBRARIES—使用protobuf-lite库需要链接的库列表3.2 缓存变量Cache Variables以下缓存变量也可供用户设置或查询缓存变量含义Protobuf_INCLUDE_DIR包含 Protobuf 头文件的目录Protobuf_LIBRARYprotobuf库的路径Protobuf_PROTOC_LIBRARYprotoc库的路径Protobuf_PROTOC_EXECUTABLEprotoc编译器的路径Protobuf_LIBRARY_DEBUGprotobuf调试库的路径Protobuf_PROTOC_LIBRARY_DEBUGprotoc调试库的路径Protobuf_LITE_LIBRARYprotobuf-lite库的路径Protobuf_LITE_LIBRARY_DEBUGprotobuf-lite调试库的路径Protobuf_SRC_ROOT_FOLDERMSVC 下使用的 Protobuf 源码根目录见下文Protobuf_SRC_ROOT_FOLDER专用于 Windows/MSVC 场景当使用 Protobuf 自带的 Visual Studio 工程构建产物时设置该变量后模块会去以下位置查找库和可执行文件Protobuf_SRC_ROOT_FOLDER/vsprojects/{Debug,Release}Protobuf_SRC_ROOT_FOLDER/vsprojects/x64/{Debug,Release}3.3 向后兼容双写大小写前缀模块保留了大量向后兼容逻辑查找前会把已定义的PROTOBUF_*大写输入变量如PROTOBUF_SRC_ROOT_FOLDER、PROTOBUF_IMPORT_DIRS、PROTOBUF_DEBUG等映射为Protobuf_*形式查找结束后又会把全部Protobuf_*输出变量以string(TOUPPER)形式回写到PROTOBUF_*大写变量见 Modules/FindProtobuf.cmake。因此旧工程中依赖PROTOBUF_LIBRARIES等大写变量的代码仍然可用但新代码应统一使用Protobuf_前缀。四、查找前的 Hint 变量在调用find_package(Protobuf)之前可以设置以下可选变量影响查找行为Protobuf_DEBUG3.6 引入布尔值置 ON 后模块会打印内部调试信息便于排查查找路径、版本解析等问题。源码中大量使用if(Protobuf_DEBUG)输出message(STATUS ...)例如输出Protobuf_USE_STATIC_LIBS当前值、common.h位置、从common.h解析出的版本号、protoc --version结果等。Protobuf_USE_STATIC_LIBS3.9 引入置 ON 强制使用静态库默认 OFF。实现上置 ON 时模块会临时修改CMAKE_FIND_LIBRARY_SUFFIXESWindows 下优先.lib/.a其他平台直接置为.a查找结束后恢复原值见 Modules/FindProtobuf.cmake。五、核心命令protobuf_generateprotobuf_generate命令3.13 引入用于在构建期从.proto模式文件自动生成源码是现代用法的主力命令其完整签名如下protobuf_generate( [TARGET target] [LANGUAGE lang] [OUT_VAR variable] [EXPORT_MACRO macro] [PROTOC_OUT_DIR out-dir] [PLUGIN plugin] [PLUGIN_OPTIONS plugin-options] [DEPENDENCIES dependencies...] [PROTOS proto-files...] [IMPORT_DIRS dirs...] [APPEND_PATH] [GENERATE_EXTENSIONS extensions...] [PROTOC_OPTIONS options...] [PROTOC_EXE executable] [DESCRIPTORS] )5.1 各选项详解选项说明TARGET target生成的源码文件作为源文件加入该 CMake 目标当不使用OUT_VAR时必须指定LANGUAGE lang取cpp或python决定生成哪种源码默认cpp。其他语言请配合GENERATE_EXTENSIONS使用OUT_VAR variable将生成的源文件路径列表写入该 CMake 变量EXPORT_MACRO macro应用于所有生成的 Protobuf 消息类与 extern 变量的预处理宏名常用于 DLL 导出声明展开为__declspec(dllexport)或__declspec(dllimport)仅当LANGUAGE为cpp时生效PROTOC_OUT_DIR out-dir生成文件的输出目录默认为CMAKE_CURRENT_BINARY_DIRPLUGIN plugin3.21 引入可选的插件可执行程序例如grpc_cpp_plugin的路径PLUGIN_OPTIONS plugin-options3.28 引入传给插件的额外选项如 gRPC C 插件的generate_mock_codetrueDEPENDENCIES dependencies...3.28 引入生成所依赖的项转发给底层的add_custom_command(DEPENDS)。4.1 起该参数支持多个值DEPENDENCIES a b c...此前只接受单值DEPENDENCIES a;b;c;...PROTOS proto-files...要处理的.proto文件列表若同时指定了target则与目标上的所有.proto源文件合并IMPORT_DIRS dirs...模式文件的一个或多个公共父目录。例如模式文件是proto/helloworld/helloworld.proto、导入目录是proto/则生成文件为out-dir/helloworld/helloworld.pb.h和out-dir/helloworld/helloworld.pb.ccAPPEND_PATH指定后把所有.proto文件的基路径追加到IMPORT_DIRS即让protoc对每个包含.proto文件的目录都加上-I参数GENERATE_EXTENSIONS extensions...省略LANGUAGE时必须设置用于指定protoc生成文件的扩展名PROTOC_OPTIONS options...3.28 引入直接传给protoc编译器的额外命令行选项PROTOC_EXE executable4.0 引入用于生成绑定的命令行程序、路径或 CMake 可执行目标省略时默认使用protobuf::protoc导入目标DESCRIPTORS指定后为每个.proto源文件附加--descriptor_set_outproto-file选项生成自描述消息描述文件仅当lang为cpp且处于 module mode 时可用config mode 下不可用5.2 源码级执行机制从 Modules/FindProtobuf.cmake 的实现可以看清该命令的完整工作流参数校验PROTOS与TARGET均未提供或OUT_VAR与TARGET均未提供时message(SEND_ERROR)报错并return()LANGUAGE缺省为cpp统一转为小写PROTOC_OUT_DIR缺省为${CMAKE_CURRENT_BINARY_DIR}。默认扩展名映射cpp→.pb.h .pb.ccpython→_pb2.py其他语言若无GENERATE_EXTENSIONS会直接报错。收集.proto文件指定TARGET时通过get_target_property(... SOURCES)取出目标源文件筛选出以proto结尾的文件并入PROTOS。确定protoc可执行文件未显式传PROTOC_EXE时要求存在protobuf::protoc目标否则报错并提示三种补救方式设置Protobuf_PROTOC_EXECUTABLE变量、给protobuf_generate传PROTOC_EXE、或确保protoc在 CMake 搜索路径中。构建-I导入路径APPEND_PATH为真时为每个.proto文件所在目录追加-I随后追加IMPORT_DIRS均取绝对路径并去重若未启用APPEND_PATH还会默认追加-I ${CMAKE_CURRENT_SOURCE_DIR}。计算生成文件路径对每个.proto文件计算相对目录默认相对CMAKE_CURRENT_SOURCE_DIR拼出PROTOC_OUT_DIR/相对路径/基名扩展名若启用DESCRIPTORS且语言为cpp额外生成${CMAKE_CURRENT_BINARY_DIR}/基名.desc。生成自定义命令最终通过add_custom_command执行protoc命令行形如protoc [PROTOC_OPTIONS...] --lang_out [plugin-options]:PROTOC_OUT_DIR [--plugin...] [--descriptor_set_out...] [-I dir...] abs.proto依赖项包含.proto文件本身、protobuf::protoc以及用户传入的DEPENDENCIES并注明VERBATIM保证参数原样传递。产出与注入所有生成文件被标记为GENERATED TRUEOUT_VAR结果写回父作用域PARENT_SCOPE指定TARGET时通过target_sources(... PRIVATE ...)注入目标。仓库自带测试 Tests/FindProtobuf/Test/CMakeLists.txt 展示了多个典型用法例如add_library(msgs_protoc_options msgs/example.proto) protobuf_generate(TARGET msgs_protoc_options DESCRIPTORS EXPORT_MACRO PROTO_EXPORT PLUGIN_OPTIONS speed PROTOC_OPTIONS --include_imports --include_source_info)并注释说明多个 protoc/plugin 选项必须仍然汇成单一的 COMMENT 字符串——这正是实现中对PLUGIN_OPTIONS用逗号拼接、对PROTOC_OPTIONS以空格替换分号的细节体现。六、Deprecated 命令protobuf_generate_cpp / protobuf_generate_python为向后兼容模块保留了旧版命令4.1 起标记为 deprecated应迁移到protobuf_generate。6.1 protobuf_generate_cpp在构建期从.proto文件生成 C 源码protobuf_generate_cpp( sources-variable headers-variable [DESCRIPTORS variable] [EXPORT_MACRO macro] proto-files... )sources-variable保存生成的 C 源文件列表的变量名headers-variable保存生成的头文件列表的变量名DESCRIPTORS variable3.10 引入保存生成的描述文件列表config mode 下不可用EXPORT_MACRO macro展开为__declspec(dllexport)/__declspec(dllimport)的宏名proto-files...一个或多个待处理的.proto文件。6.2 protobuf_generate_python3.4 引入4.1 起 deprecated在构建期生成 Python 源码protobuf_generate_python(python-sources-variable proto-files...)6.3 两个旧命令共用的前置变量调用旧命令前还可设置以下变量Protobuf_IMPORT_DIRS4.1 deprecated附加的.proto导入搜索目录列表PROTOBUF_GENERATE_CPP_APPEND_PATH4.1 deprecated请改用protobuf_generate(APPEND_PATH)布尔值为真时让protoc对每个包含.proto文件的目录都传-I默认值为真见源码if(NOT DEFINED PROTOBUF_GENERATE_CPP_APPEND_PATH) set(PROTOBUF_GENERATE_CPP_APPEND_PATH TRUE)。6.4 旧命令的作用域与 config mode 限制重要两个旧命令只在与find_package(Protobuf ...)相同的目录作用域内正确工作若 Protobuf 以config mode找到则自 Protobuf 3.0.0 起protobuf_generate_cpp()与protobuf_generate_python()不可用除非在调用find_package(Protobuf ...)之前将上游包配置提示变量protobuf_MODULE_COMPATIBLE设为布尔真。实现上两个旧函数本质是protobuf_generate的薄包装PROTOBUF_GENERATE_CPP解析参数后转调protobuf_generate(... LANGUAGE cpp ...)再把输出的文件按扩展名.cc源、.desc描述文件、其余头文件分类回写PROTOBUF_GENERATE_PYTHON则转调protobuf_generate(... LANGUAGE python ...)见 Modules/FindProtobuf.cmake。七、完整实战示例7.1 查找 Protobuf 的三种基本写法# 只查找未找到不报错 find_package(Protobuf) # 指定最低版本 find_package(Protobuf 30) # 必需找不到则停止并报错 find_package(Protobuf REQUIRED)7.2 config mode 优先、module mode 兜底某些 Protobuf 安装可能不提供 package configuration file。官方推荐的兜底写法是利用CMAKE_FIND_PACKAGE_PREFER_CONFIGset(CMAKE_FIND_PACKAGE_PREFER_CONFIG TRUE) find_package(Protobuf) unset(CMAKE_FIND_PACKAGE_PREFER_CONFIG)这样优先尝试 config mode找不到配置文件时自动回退到 module mode。7.3 链接导入目标find_package(Protobuf) target_link_libraries(example PRIVATE protobuf::libprotobuf)7.4 完整工程生成并编译 C 代码CMakeLists.txtcmake_minimum_required(VERSION 3.24) project(ProtobufExample) add_executable(example main.cxx person.proto) find_package(Protobuf) if(Protobuf_FOUND) protobuf_generate(TARGET example) endif() target_link_libraries(example PRIVATE protobuf::libprotobuf) target_include_directories(example PRIVATE ${CMAKE_CURRENT_BINARY_DIR})person.protosyntax proto3; message Person { string name 1; int32 id 2; }main.cxx#include iostream #include person.pb.h int main() { Person person; person.set_name(Alice); person.set_id(123); std::cout Name: person.name() \n; std::cout ID: person.id() \n; return 0; }注意example目标把person.proto直接作为源文件加入protobuf_generate(TARGET example)自动收集其中的.proto文件并生成person.pb.h/person.pb.cc注入目标头文件生成在${CMAKE_CURRENT_BINARY_DIR}故需将该目录加入包含路径。7.5 Protobuf gRPCgRPC 场景使用PLUGIN、PLUGIN_OPTIONS与GENERATE_EXTENSIONS组合生成服务桩代码find_package(Protobuf REQUIRED) find_package(gRPC CONFIG REQUIRED) add_library(ProtoExample Example.proto) target_link_libraries(ProtoExample PUBLIC gRPC::grpc) protobuf_generate(TARGET ProtoExample) protobuf_generate( TARGET ProtoExample LANGUAGE grpc PLUGIN protoc-gen-grpc$TARGET_FILE:gRPC::grpc_cpp_plugin PLUGIN_OPTIONS generate_mock_codetrue GENERATE_EXTENSIONS .grpc.pb.h .grpc.pb.cc )这里LANGUAGE grpc并非内置语言必须配合GENERATE_EXTENSIONS指明插件输出扩展名$TARGET_FILE:...生成器表达式在构建期解析为插件绝对路径。仓库测试中对应的 gRPC 用例受CMake_TEST_FindProtobuf_gRPC开关控制还演示了IMPORT_DIRS与APPEND_PATH对输出目录布局的影响见 Tests/FindProtobuf/Test/CMakeLists.txt默认无 IMPORT_DIRS/APPEND_PATH生成文件落在${CMAKE_CURRENT_BINARY_DIR}/msgs/grpc/带IMPORT_DIRS msgs/落在${CMAKE_CURRENT_BINARY_DIR}/grpc/带APPEND_PATH直接落在${CMAKE_CURRENT_BINARY_DIR}/。7.6 从旧命令升级到 protobuf_generate旧式 C 生成find_package(Protobuf) if(Protobuf_FOUND) protobuf_generate_cpp( proto_sources proto_headers EXPORT_MACRO DLL_EXPORT DESCRIPTORS proto_descriptors src/protocol/Proto1.proto src/protocol/Proto2.proto ) endif() target_sources( example PRIVATE ${proto_sources} ${proto_headers} ${proto_descriptors} ) target_link_libraries(example PRIVATE protobuf::libprotobuf)升级后的等价写法find_package(Protobuf) if(Protobuf_FOUND) protobuf_generate( TARGET example EXPORT_MACRO DLL_EXPORT IMPORT_DIRS src/protocol DESCRIPTORS PROTOS src/protocol/Proto1.proto src/protocol/Proto2.proto ) endif() target_link_libraries(example PRIVATE protobuf::libprotobuf)旧式 Python 生成find_package(Protobuf) if(Protobuf_FOUND) protobuf_generate_python(python_sources foo.proto) endif() add_custom_target(proto_files DEPENDS ${python_sources})升级后find_package(Protobuf) if(Protobuf_FOUND) protobuf_generate( LANGUAGE python PROTOS foo.proto OUT_VAR python_sources ) endif() add_custom_target(proto_files DEPENDS ${python_sources})八、模块内部查找流程与版本校验理解模块的查找顺序有助于排查“找不到库”或“版本不匹配”的问题。从 Modules/FindProtobuf.cmake 源码看主要流程如下库查找通过内部函数_protobuf_find_libraries依次查找Protobufprotobuf、Protobuf_LITEprotobuf-lite、Protobuf_PROTOCprotoc每个库同时查找 release 与 debug 变体debug 名自动加d后缀再借助SelectLibraryConfigurations.cmake的select_library_configurations合成*_LIBRARIESUNIX 下若启用了线程还会追加${CMAKE_THREAD_LIBS_INIT}。头文件查找find_path(Protobuf_INCLUDE_DIR google/protobuf/service.h ...)。编译器查找find_program(Protobuf_PROTOC_EXECUTABLE NAMES protoc ...)MSVC 下额外搜索vsprojects/{x64/}{Debug,Release}目录。版本解析读取${Protobuf_INCLUDE_DIR}/google/protobuf/stubs/common.h中的GOOGLE_PROTOBUF_VERSION宏形如3023002的整数通过math(EXPR ...)拆出主/次/修订号组成Protobuf_VERSION。版本一致性校验执行protoc --version解析libprotoc version与库版本比对不一致时输出WARNING实现中还特别注释protoc 22 及以后版本不再打印主版本号因此比对逻辑额外兼容minor.subminor形式见 Modules/FindProtobuf.cmake。最终判定调用find_package_handle_standard_args(Protobuf REQUIRED_VARS Protobuf_LIBRARIES Protobuf_INCLUDE_DIR VERSION_VAR Protobuf_VERSION)生成标准的Protobuf_FOUND结果与错误提示。模块还针对 MSVC 做了特殊兼容由于 Google 提供的 vcproj 工程在 Windows 上生成的库带lib前缀模块会临时把CMAKE_FIND_LIBRARY_PREFIXES改为lib 再恢复确保libprotobuf这类命名也能被正确匹配。九、官方回归测试验证模块与生成命令仓库为 FindProtobuf 提供了完整回归测试位于 Tests/FindProtobuf/CMakeLists.txt 与 Tests/FindProtobuf/Test/CMakeLists.txt通过ctest --build-and-test在临时目录独立构建TestFindProtobuf工程覆盖分别用导入目标protobuf::libprotobuf、protobuf::libprotobuf-lite、protobuf::libprotoc和传统变量${Protobuf_INCLUDE_DIRS}、${Protobuf_LIBRARIES}、${Protobuf_LITE_LIBRARIES}、${Protobuf_PROTOC_LIBRARIES}两种风格链接并运行测试程序通过protobuf::protoc --version验证导入的可执行目标可用调用protobuf_generate_cpp生成msgs/example.proto与msgs/example_desc.proto的源码与描述文件编译后运行test_generate、test_desc验证生成代码可编译、可运行在 gRPC 开关开启时验证PLUGIN、IMPORT_DIRS、APPEND_PATH三种模式下生成的 gRPC 桩代码均可构建运行。测试目标属性中设置的FAIL_REGULAR_EXPRESSION PROTOC_EXE还用于捕获PROTOC_EXE相关错误输出。这些用例可直接作为读者本地集成 Protobuf 的参考模板。十、快速决策清单用 config mode 还是 module modeProtobuf 由 CMake 构建安装 → 优先find_package(Protobuf CONFIG)否则用本模块module mode并可用CMAKE_FIND_PACKAGE_PREFER_CONFIG实现“config 优先、module 兜底”。链接用目标还是变量优先protobuf::libprotobuf等命名空间目标自动携带包含目录、C11 特性、Windows DLL 定义、线程依赖老代码可继续用Protobuf_LIBRARIES系列变量。生成代码用什么命令新工程一律用protobuf_generate旧命令仅在维护遗留代码时使用并注意其目录作用域与 config mode 限制。多语言/插件怎么办非 cpp/python 语言必须提供GENERATE_EXTENSIONSgRPC 等插件用PLUGINPLUGIN_OPTIONS。排查问题开什么开关设置Protobuf_DEBUGON可观察模块完整查找过程Protobuf_USE_STATIC_LIBSON强制静态链接。赞分享构建工具开发工具CLI【免费下载链接】CMakeMirror of CMake upstream repository项目地址https://gitcode.com/gh_mirrors/cm/CMake点击查看免费下载相关推荐鸣潮后台自动战斗与自动刷声骸如何配置ok-ww 自动化工具 15 分钟上手实录鸣潮后台自动战斗与自动刷声骸如何配置ok ww 自动化工具 15 分钟上手实录 晚上十一点一局打完正准备关游戏突然想起来今天的日常还没清体力也还剩大半构建工具开发工具CLINumPy F2PY 与 CMake 集成实战构建 Fortran 扩展模块的完整指南NumPy F2PY 与 CMake 集成实战构建 Fortran 扩展模块的完整指南 导读 本文围绕 doc/source/f2py/buildtools/科学计算数据分析【免费下载】 Protocol Buffers CMake集成指南protobuf_generate函数详解Protocol Buffers CMake集成指南protobuf_generate函数详解 前言 在现代C项目中Protocol Buffers简序列化代码生成上一篇探索未来的数据存储Dragonfly 开源数据库下一篇Kubernetes DRA 动态资源分配升级/降级端到端测试套件test/e2e_dra运行指南与源码解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考