与其他项目的整合

相关源文件

• CMakeLists.txt
• Protobuf.podspec
• WORKSPACE
• bazel/upb_proto_library.bzl
• cmake/BUILD.bazel
• csharp/Google.Protobuf.Tools.nuspec
• csharp/src/Google.Protobuf/Google.Protobuf.csproj
• java/bom/pom.xml
• java/pom.xml
• php/ext/google/protobuf/protobuf.h
• python/google/protobuf/__init__.py
• ruby/google-protobuf.gemspec
• upb/port/BUILD

本文档提供了在不同构建系统和编程语言中将 Protocol Buffers 集成到各种项目类型的指南。它涵盖了在您的项目中有效使用 Protocol Buffers 所需的特定配置选项、依赖声明和集成模式。

集成选项概述

Protocol Buffers 可以通过多种机制集成到您的项目中

1. 构建系统集成 - 将 Protocol Buffers 添加到 Bazel、CMake、Maven 或其他构建系统中
2. 特定语言集成 - 将 Protocol Buffers 与 Java、C#、Python 等一起使用
3. 代码生成工作流 - 设置 protoc 编译器并管理生成代码

下图说明了 Protocol Buffers 的主要集成点

来源： WORKSPACE1-250 CMakeLists.txt1-350 java/pom.xml1-292 python/google/protobuf/__init__.py1-10

构建系统集成

Bazel 集成

Protocol Buffers 通过仓库中定义的规则提供对 Bazel 的原生支持。

将 Protocol Buffers 添加到您的 Bazel 项目

1. 将 Protocol Buffers 仓库添加到您的 WORKSPACE 文件

http_archive(
    name = "com_google_protobuf",
    urls = ["https://github.com/protocolbuffers/protobuf/archive/refs/tags/vX.Y.Z.tar.gz"],
    strip_prefix = "protobuf-X.Y.Z",
)

load("@com_google_protobuf//:protobuf_deps.bzl", "protobuf_deps")
protobuf_deps()

2. 在您的 BUILD 文件中使用 Protocol Buffers 规则

load("@com_google_protobuf//bazel:upb_proto_library.bzl", "upb_proto_library")

proto_library(
    name = "my_proto",
    srcs = ["my.proto"],
)

upb_proto_library(
    name = "my_proto_upb",
    deps = [":my_proto"],
)

关键 Bazel 规则包括

• upb_proto_library - 使用 μpb (upb) 生成 C/C++ 代码
• upb_proto_reflection_library - 生成反射数据

来源： WORKSPACE1-309 bazel/upb_proto_library.bzl1-36

CMake 集成

Protocol Buffers 可以通过以下方式与 CMake 项目集成

• 将 Protocol Buffers 作为项目的一部分进行构建
• 使用预安装的 Protocol Buffers 包

对于从源代码构建

1. 将 Protocol Buffers 添加为子目录

2. 配置构建选项

3. 链接 Protocol Buffers 库

对于使用预安装的包

关键 CMake 选项包括

• protobuf_BUILD_SHARED_LIBS - 构建为共享库（默认：OFF）
• protobuf_WITH_ZLIB - 启用 ZLIB 支持（默认：ON）
• protobuf_BUILD_TESTS - 构建测试（默认：ON）
• protobuf_INSTALL - 安装库和头文件（默认：ON）

来源： CMakeLists.txt27-53 CMakeLists.txt159-180

Maven 集成

对于使用 Maven 的 Java 项目，请将 Protocol Buffers 依赖项添加到您的 pom.xml

用于附加工具

在构建过程中从 .proto 文件生成 Java 代码

来源： java/pom.xml1-293 java/bom/pom.xml58-75

特定语言集成

下图说明了不同编程语言的集成工作流

来源： java/pom.xml7 csharp/src/Google.Protobuf/Google.Protobuf.csproj8 python/google/protobuf/__init__.py10 ruby/google-protobuf.gemspec3 php/ext/google/protobuf/protobuf.h35 Protobuf.podspec8

Java 集成

使用以下方式将 Protocol Buffers 添加到 Java 项目

1. Maven 依赖项在 pom.xml

2. Gradle 依赖项

3. 用于 Kotlin 支持

来源： java/pom.xml6-7 java/bom/pom.xml59-73

C# 集成

1. 安装 NuGet 包

Install-Package Google.Protobuf -Version 3.31.0

2. 用于工具和 protoc 编译器

Install-Package Google.Protobuf.Tools -Version 3.31.0

3. .csproj 引用

来源： csharp/src/Google.Protobuf/Google.Protobuf.csproj8 csharp/Google.Protobuf.Tools.nuspec8

Python 集成

1. 通过 pip 安装

2. 在 Python 代码中导入

来源： python/google/protobuf/__init__.py10

Ruby 集成

1. 添加到 Gemfile

2. 或直接安装

来源： ruby/google-protobuf.gemspec2-3

PHP 集成

1. 安装 PHP 扩展

2. 添加到 php.ini

extension=protobuf.so

来源： php/ext/google/protobuf/protobuf.h35

Objective-C 集成

添加到 Podfile

来源： Protobuf.podspec7-8

集成工作流程

集成 Protocol Buffers 的典型工作流程包括以下步骤

来源： WORKSPACE1-100 CMakeLists.txt1-100 java/pom.xml1-100

常见集成模式

构建配置选项

下表总结了跨构建系统的关键配置选项

功能	Bazel	CMake	Maven
共享库	--compilation_mode=dbg	protobuf_BUILD_SHARED_LIBS=ON	不适用
ZLIB 支持	WORKSPACE 中的依赖项	protobuf_WITH_ZLIB=ON	不适用
代码生成	upb_proto_library	protobuf_generate()	protobuf-maven-plugin
测试	cc_test 规则	protobuf_BUILD_TESTS=ON	JUnit 依赖项

来源： WORKSPACE35-50 CMakeLists.txt27-53 java/pom.xml67-106

版本控制与兼容性

Protocol Buffers 遵循语义化版本控制

版本组件	含义	示例
主版本 (X.y.z)	破坏性变更	3.x.x → 4.x.x
次版本 (x.Y.z)	新功能（向后兼容）	4.1.x → 4.2.x
修订版 (x.y.Z)	Bug修复	4.1.1 → 4.1.2

不同语言的当前版本

• Java: 4.31.0 (java/pom.xml7)
• C#: 3.31.0 (csharp/src/Google.Protobuf/Google.Protobuf.csproj8)
• Python: 6.31.0 (python/google/protobuf/__init__.py10)
• Ruby: 4.31.0 (ruby/google-protobuf.gemspec3)
• PHP: 4.31.0 (php/ext/google/protobuf/protobuf.h35)
• Objective-C: 4.31.0 (Protobuf.podspec8)

集成方法

集成 Protocol Buffers 有两种常见模式

1. 系统级安装:

   • Protocol Buffers 全局安装并供多个项目使用
   • 设置更简单，但可能导致版本冲突

2. 项目特定集成:

   • Protocol Buffers 直接包含在您的项目内
   • 隔离性更好，但项目体积较大

故障排除常见集成问题

问题	常见原因	解决方案
版本不匹配	运行时库版本与 protoc 版本不匹配	确保两者版本相同
缺少依赖项	缺少传递性依赖	显式添加所需依赖项
构建错误	错误的构建配置	验证构建系统设置
跨语言问题	特定语言的限制	使用兼容的 proto 功能

延伸阅读

• 有关 Bazel 构建系统的详细信息，请参阅 Bazel 构建系统
• 有关 CMake 构建系统的详细信息，请参阅 CMake 构建系统
• 有关特定语言实现的信息，请参阅 语言实现

来源： CMakeLists.txt1-350 WORKSPACE1-309 java/pom.xml1-293