当前位置： 首页 > news >正文

Protocol Buffers (protobuf) HarmonyOS 适配指南

news 2026/5/11 20:27:14

目录

  • 概述
  • Protocol Buffers 简介
  • 适配准备
  • 构建脚本详解
  • 遇到的问题及解决方案
  • 构建流程
  • 使用示例
  • 总结

概述

本文档详细介绍了如何将 Google Protocol Buffers (protobuf) 3.25.2 适配到 HarmonyOS 平台，包括交叉编译配置、CMake 构建系统集成、以及 HarmonyOS Native Package (HNP) 打包过程。

项目信息：

  • 库名称: Protocol Buffers (protobuf)
  • 版本: 3.25.2
  • 构建系统: CMake
  • 目标平台: HarmonyOS (aarch64-linux-ohos)
  • 仓库地址: git@gitcode.com:nutpi/protobuf.git
  • Tag: v3.25.2-harmonyos

Protocol Buffers 简介

Protocol Buffers（简称 protobuf）是 Google 开发的一种语言无关、平台无关的序列化结构化数据的机制。它提供了一种高效、可扩展的方式来序列化结构化数据，常用于：

  • 数据交换格式: 用于不同服务之间的数据通信
  • 配置文件: 用于存储和读取配置信息
  • RPC 通信: 作为 gRPC 等 RPC 框架的数据序列化格式
  • 数据存储: 用于持久化结构化数据

主要特性

  • 高效: 比 XML 和 JSON 更小、更快
  • 跨语言: 支持 C++、Java、Python、Go、C# 等多种语言
  • 向后兼容: 支持字段的添加和删除，保持向后兼容
  • 强类型: 通过.proto文件定义数据结构，提供类型安全

开发环境

移植环境说明：该命令基于build配置框架进行移植编译，环境搭建可以参考文章《开源软件鸿蒙化适配与构建指南(交叉编译)》，主要是ohos sdk的下载配置和build配置框架的下载使用说明。

项目名称Protocol Buffers (protobuf)
开源协议GPL-2.0-or-later
源码版本3.25.2
目标平台aarch64-linux-ohos
依赖项OpenHarmony SDK、CMake
操作系统平台OpenHarmony PC
源码地址https://gitcode.com/nutpi/protobuf

基本使用

  1. 定义 .proto 文件:
syntax = "proto3"; message Person { string name = 1; int32 id = 2; string email = 3; }
  1. 编译 .proto 文件:
protoc--cpp_out=. person.proto
  1. 在代码中使用:
#include"person.pb.h"Person person;person.set_name("John Doe");person.set_id(1234);person.set_email("john@example.com");// 序列化std::string serialized;person.SerializeToString(&serialized);// 反序列化Person deserialized_person;deserialized_person.ParseFromString(serialized);

适配准备

环境要求

  • HarmonyOS SDK: 已配置交叉编译工具链
  • CMake: 3.16 或更高版本（推荐使用 DevEco Studio SDK 自带的 CMake）
  • 构建工具: make、tar、gzip
  • 网络连接: 构建过程中需要下载 Abseil 依赖

目录结构

code/protobuf/ ├── build_ohos.sh # HarmonyOS 构建脚本 ├── hnp.json # HNP 配置文件 ├── CMakeLists.txt # CMake 主配置文件 ├── src/ # 源代码目录 ├── cmake/ # CMake 模块 └── build_ohos/ # 构建输出目录（自动生成）

构建脚本详解

build_ohos.sh 脚本结构

构建脚本build_ohos.sh主要包含以下部分：

1. 环境变量设置
exportPROTOBUF_INSTALL_HNP_PATH=${HNP_PUBLIC_PATH}/protobuf.org/protobuf_3.25.2

设置安装路径，遵循 HNP 包命名规范：{组织}.{域名}/{包名}_{版本}。

2. CMake 检测

脚本会按以下顺序查找 CMake：

  1. PATH 环境变量中的 cmake
  2. DevEco Studio SDK 的 CMake:
    /Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/native/build-tools/cmake/bin/cmake
  3. Homebrew 安装的 CMake:/opt/homebrew/bin/cmake
  4. 传统路径:/usr/local/bin/cmake

如果都找不到，脚本会给出清晰的错误提示和安装建议。

3. CMake 配置
${CMAKE_CMD}..\-DCMAKE_BUILD_TYPE=Release\-DCMAKE_INSTALL_PREFIX=${PROTOBUF_INSTALL_HNP_PATH}\-DCMAKE_SYSTEM_NAME=Linux\-DCMAKE_SYSTEM_PROCESSOR=aarch64\-DCMAKE_C_COMPILER="${CC}"\-DCMAKE_CXX_COMPILER="${CXX}"\-DCMAKE_C_FLAGS="${CFLAGS}"\-DCMAKE_CXX_FLAGS="${CXXFLAGS}"\-DCMAKE_EXE_LINKER_FLAGS="${LDFLAGS}"\-DCMAKE_SHARED_LINKER_FLAGS="${LDFLAGS}"\-DCMAKE_SYSROOT="${SYSROOT}"\-Dprotobuf_BUILD_TESTS=OFF\-Dprotobuf_BUILD_EXAMPLES=OFF\-DBUILD_SHARED_LIBS=OFF\-DCMAKE_POSITION_INDEPENDENT_CODE=ON

关键配置说明：

  • CMAKE_SYSTEM_NAME=Linux: 指定目标系统为 Linux（HarmonyOS 基于 Linux 内核）
  • CMAKE_SYSTEM_PROCESSOR=aarch64: 指定目标架构为 ARM64
  • CMAKE_SYSROOT: 指定 HarmonyOS SDK 的 sysroot 路径
  • BUILD_SHARED_LIBS=OFF: 构建静态库（适合 HarmonyOS 应用分发）
  • protobuf_BUILD_TESTS=OFF: 禁用测试构建（交叉编译环境无法运行测试）
  • protobuf_BUILD_EXAMPLES=OFF: 禁用示例构建（减少构建时间）
  • CMAKE_POSITION_INDEPENDENT_CODE=ON: 启用位置无关代码（PIC），便于静态库链接
4. 构建和安装
# 构建（并行编译）${CMAKE_CMD}--build.--configRelease--parallel$(sysctl-nhw.ncpu)# 安装到指定目录${CMAKE_CMD}--install.--configRelease
5. HNP 打包
# 复制 HNP 配置文件cphnp.json${PROTOBUF_INSTALL_HNP_PATH}/# 打包为 HNP 格式${HNP_TOOL}pack-i${PROTOBUF_INSTALL_HNP_PATH}-o${ARCHIVE_PATH}/# 创建 tar.gz 归档tar-zvcf${ARCHIVE_PATH}/ohos_protobuf_3.25.2.tar.gz protobuf_3.25.2/

遇到的问题及解决方案

问题 1: CMake 未安装

错误信息：

build_ohos.sh: line 40: cmake: command not found Error: CMake configuration failed

原因分析：
系统未安装 CMake，或者 CMake 不在 PATH 环境变量中。

解决方案：

  1. 使用 DevEco Studio SDK 的 CMake（推荐）:
    脚本会自动检测并使用 DevEco Studio SDK 自带的 CMake（版本 3.28.2）。

  2. 手动安装 CMake:

    # macOS (如果 Homebrew 可用)brewinstallcmake# 或从官网下载# https://cmake.org/download/

  3. 添加到 PATH:
    如果 CMake 已安装但不在 PATH 中，可以添加到.zshrc或.bashrc:

    exportPATH="/path/to/cmake/bin:$PATH"

问题 2: Homebrew CMake 安装失败

错误信息：

Error: Cask 'cmake' definition is invalid: 'conflicts_with' stanza failed

原因分析：
Homebrew 的 CMake cask 定义存在问题，可能是版本冲突或配置错误。

解决方案：
使用 DevEco Studio SDK 的 CMake，脚本已自动支持检测该路径。

问题 3: 依赖下载问题

现象：
CMake 配置时会自动下载 Abseil 依赖：

-- Could NOT find absl (missing: absl_DIR) -- Fallback to downloading Abseil 20250512.1 from GitHub

解决方案：
这是正常行为。protobuf 依赖 Abseil（Google 的 C++ 基础库），CMake 会自动从 GitHub 下载。确保：

  • 网络连接正常
  • 可以访问 GitHub（可能需要代理）

如果下载失败，可以：

  1. 配置 Git 代理
  2. 手动下载 Abseil 并放到third_party/目录
  3. 使用镜像源

问题 4: ZLIB 未找到

警告信息：

-- Could NOT find ZLIB (missing: ZLIB_LIBRARY) (found version "1.3.1")

原因分析：
CMake 找到了 ZLIB 的版本信息，但找不到库文件路径。

解决方案：
这个警告通常不影响构建。protobuf 可以编译，但某些压缩功能可能不可用。如果需要完整的 ZLIB 支持，可以：

  1. 在 HarmonyOS SDK 中安装 ZLIB
  2. 通过 CMake 变量指定 ZLIB 路径：
    -DZLIB_ROOT=/path/to/zlib

构建流程

完整构建步骤

  1. 准备环境:

    # 设置 HarmonyOS SDK 路径exportOHOS_SDK=/path/to/ohosdk# 运行主构建脚本./build.sh--sdk${OHOS_SDK}

  2. 构建过程:

    • CMake 配置（检测工具链、下载依赖）
    • 编译源代码（C++ 编译器）
    • 安装到指定目录
    • 打包为 HNP 格式

  3. 输出文件:

    • ${ARCHIVE_PATH}/protobuf.hnp- HNP 格式包
    • ${ARCHIVE_PATH}/ohos_protobuf_3.25.2.tar.gz- 压缩归档

构建时间

  • CMake 配置: 约 1-2 分钟（包括下载 Abseil）
  • 编译: 约 5-10 分钟（取决于 CPU 核心数）
  • 安装和打包: 约 30 秒

总计: 约 7-13 分钟

使用示例

在 HarmonyOS 应用中使用 protobuf

1. 定义 .proto 文件

创建person.proto:

syntax = "proto3"; package tutorial; message Person { string name = 1; int32 id = 2; string email = 3; enum PhoneType { MOBILE = 0; HOME = 1; WORK = 2; } message PhoneNumber { string number = 1; PhoneType type = 2; } repeated PhoneNumber phones = 4; }
2. 编译 .proto 文件
# 使用交叉编译的 protoc${PROTOBUF_INSTALL_HNP_PATH}/bin/protoc\--cpp_out=.\--proto_path=.\person.proto
3. 在 C++ 代码中使用
#include"person.pb.h"#include<iostream>#include<fstream>intmain(){// 创建 Person 对象tutorial::Person person;person.set_name("John Doe");person.set_id(1234);person.set_email("john@example.com");// 添加电话号码tutorial::Person::PhoneNumber*phone=person.add_phones();phone->set_number("123-456-7890");phone->set_type(tutorial::Person::MOBILE);// 序列化到文件std::fstreamoutput("person.pb",std::ios::out|std::ios::binary|std::ios::trunc);if(!person.SerializeToOstream(&output)){std::cerr<<"Failed to write person."<<std::endl;return-1;}output.close();// 从文件反序列化tutorial::Person person2;std::fstreaminput("person.pb",std::ios::in|std::ios::binary);if(!person2.ParseFromIstream(&input)){std::cerr<<"Failed to parse person."<<std::endl;return-1;}// 读取数据std::cout<<"Name: "<<person2.name()<<std::endl;std::cout<<"ID: "<<person2.id()<<std::endl;std::cout<<"Email: "<<person2.email()<<std::endl;return0;}
4. 编译应用
# 使用 HarmonyOS SDK 工具链${CC}-std=c++17\-I${PROTOBUF_INSTALL_HNP_PATH}/include\-L${PROTOBUF_INSTALL_HNP_PATH}/lib\person.pb.cc main.cpp\-lprotobuf\-operson_app

在 HarmonyOS Native 应用中使用

在 HarmonyOS Native 应用的CMakeLists.txt中：

cmake_minimum_required(VERSION 3.16) project(PersonApp) set(CMAKE_CXX_STANDARD 17) # 查找 protobuf find_package(Protobuf REQUIRED) # 编译 .proto 文件 protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS person.proto) # 添加可执行文件 add_executable(person_app main.cpp ${PROTO_SRCS} ) # 链接 protobuf target_link_libraries(person_app ${Protobuf_LIBRARIES} ) target_include_directories(person_app PRIVATE ${Protobuf_INCLUDE_DIRS} )

总结

适配要点

  1. CMake 构建系统: protobuf 使用 CMake，需要正确配置交叉编译工具链
  2. 依赖管理: protobuf 依赖 Abseil，CMake 会自动下载
  3. 静态库构建: 构建静态库便于 HarmonyOS 应用分发
  4. 工具链配置: 正确设置编译器、链接器和 sysroot

优势

  • 标准化: protobuf 是业界标准的数据序列化格式
  • 高效: 序列化后的数据体积小、速度快
  • 跨语言: 支持多种编程语言，便于不同服务间通信
  • 向后兼容: 支持字段的添加和删除，保持 API 兼容性

应用场景

  • 微服务通信: 服务间的数据交换
  • 配置文件: 结构化配置的存储和读取
  • 数据持久化: 高效的数据存储格式
  • RPC 框架: 作为 gRPC 等 RPC 框架的基础

后续工作

  • 测试 protobuf 在 HarmonyOS 上的完整功能
  • 优化构建脚本，支持更多配置选项
  • 添加使用文档和示例代码
  • 集成到 HarmonyOS 应用开发工具链

相关链接：

  • Protocol Buffers 官方文档
  • GitCode 仓库
  • HarmonyOS Native 开发文档
  • PC代码仓
  • 欢迎加入开源鸿蒙PC社区：https://harmonypc.csdn.net/
http://www.jsqmd.com/news/489172/

相关文章：

  • 2026年口碑好的一体板品牌推荐：A 级防火一体板/保温装饰一体板/陶瓷保温装饰一体板厂家精选 - 品牌宣传支持者
  • 如何为Cloudreve配置前端代码覆盖率报告：Jenkins与GitLab CI集成全指南
  • 终极Professional Programming排版艺术：代码与文档格式规范完全指南
  • 终极指南：clipboard.js与前端技术愿景——现代复制粘贴解决方案的演进之路
  • 室内家具检测数据集-8,055张图片 家具识别 室内设计 智能家居 房产科技 电商视觉 AR/VR 家居自动化
  • 终极Marlin固件安全评估：全面代码审查与漏洞扫描指南
  • FireRed-OCR Studio效果展示：工程制图中尺寸标注+公差符号+技术要求识别
  • Phi-4-reasoning-vision-15B部署教程：GPU利用率提升40%的常驻加载实践
  • 终极指南：Lago事件处理熔断机制如何防止级联故障的系统保护设计
  • Linux实用工具：Tmux使用教程
  • 终极指南：Marlin固件硬件监控系统如何实现实时数据追踪与历史趋势分析
  • COVID-Net：革命性开源AI工具如何通过胸部X光片检测COVID-19
  • 比迪丽AI绘画行业落地：ACG展会物料生成、COSER宣传图智能辅助制作
  • 如何用Screenshot-to-code打造AI网页开发神器：从创意到产品的完整指南
  • Java学习路线
  • MySQL安装使用远程操作
  • eblog用户认证与授权：Shiro框架集成最佳实践
  • Stable-Diffusion-v1-5-archiveAIGC内容分级：面向青少年/儿童的安全生成模式配置
  • 终极指南：Ludwig分布式训练节点配置与资源分配最佳实践
  • gte-base-zh镜像免配置亮点：预置常用curl/postman测试脚本
  • Lychee-Rerank-MM应用案例：时尚穿搭图→商品链接多模态推荐排序
  • 2025年11月最新：ChatGPT Plus 升级指南（6种方法全解析）
  • AudioSeal应用场景：播客制作、有声书分发、智能客服语音版权管控
  • 终极指南：如何使用clipboard.js构建无障碍复制功能
  • YOLO X Layout快速部署：使用systemd守护进程确保app.py服务开机自启不中断
  • 华为OD机试真题 - 最多香蕉数量 / 贪吃的猴子 (C/C++/Py/Java/Js/Go)
  • Nano-Banana软萌拆拆屋实战：从Pinterest灵感图生成精准拆解提示词
  • Python入门
  • 造相-Z-Image惊艳效果展示：低步高效（4-20步）生成高清写实图真实案例
  • 华为OD机试双机位C卷-风险投资计划(Py/Java/C/C++/Js/Go)