编译构建指南

本文档介绍 RNOH 的编译构建流程，包括 Debug 和 Release 包的使用方法、CMake 配置和环境配置。

一、构建模式概述

模式	用途	特点	包体积	性能
Debug	开发调试	包含完整符号、可调试、无优化	大	慢
Release	生产发布	符号剥离、优化编译、体积小	小	快
Release2	特殊场景	与 Release 类似，可能有不同优化配置	小	快

二、使用 Debug 包

2.1 获取 Debug 包

Debug 包通常通过以下方式获取：

本地编译：在 DevEco Studio 中选择 Debug 模式编译
npm 下载：从 npm 下载 react-native-harmony 包（通常包含 Debug 版本的 har）

2.2 配置使用 Debug 包

步骤一：配置 oh-package.json5

在 HarmonyOS 工程的 oh-package.json5 中添加依赖：

{
  "dependencies": {
    "@rnoh/react-native-openharmony": "0.84.1"  // 使用 Debug 版本
  }
  }
}

步骤二：配置 build-profile.json5

确保 build-profile.json5 中使用 Debug 配置：

{
  "apiType": "stageMode",
  "targets": [
    {
      "name": "default",
      "runtimeOS": "HarmonyOS"
    }
  ],
  "buildOptionSet": [
    {
      "name": "debug",
      "externalNativeOptions": {
        "path": "./src/main/cpp/CMakeLists.txt",
        "arguments": [
          "-DCMAKE_BUILD_TYPE=Debug"
        ]
      },
      "nativeLib": {
        "debugSymbol": {
          "strip": false  // Debug 模式不剥离符号
        }
      }
    }
  ]
}

步骤三：配置 CMakeLists.txt（Debug 模式）

cmake_minimum_required(VERSION 3.10)
project(MyApp)

# Debug 模式基本配置
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# 添加 RNOH 依赖
add_subdirectory(${RNOH_CPP_DIR} ./rnoh)

# Debug 模式特有配置
if(CMAKE_BUILD_TYPE STREQUAL "Debug")
    # 启用调试符号
    add_compile_options(-g)
    
    # 禁用优化
    add_compile_options(-O0)
    
    # 启用地址检查（可选，用于调试内存问题）
    # add_compile_options(-fsanitize=address)
endif()

2.3 DevEco Studio 编译 Debug 包

打开 DevEco Studio
在工具栏选择 Build Mode 为 Debug
点击 Build > Make Module 'entry'
编译完成后，产物位于 build/default/outputs/default/

2.4 Debug 包调试

Debug 包包含完整符号，可以：

在 DevEco Studio 中进行 C++ 代码调试
设置断点、查看变量、单步执行
使用 LLDB 命令行调试

三、使用 Release 包

3.1 获取 Release 包

Release 包通过以下方式获取：

本地编译：在 DevEco Studio 中选择 Release 模式编译
npm 下载：从 npm 下载 react-native-harmony_release 包
官方发布：从官方渠道获取 Release 版本的 har 包

3.2 配置使用 Release 包

步骤一：配置 oh-package.json5

{
  "dependencies": {
    "@rnoh/react-native-openharmony": "file:./react_native_openharmony_release.har"  // 使用本地 Release 包
  }
}

或使用 npm 版本：

{
  "dependencies": {
     "@rnoh/react-native-openharmony": "0.84.1"  // 指定版本

  }
}

步骤二：配置 build-profile.json5（Release 模式）

{
  "apiType": "stageMode",
  "targets": [
    {
      "name": "default",
      "runtimeOS": "HarmonyOS"
    }
  ],
  "buildOptionSet": [
    {
      "name": "release",
      "externalNativeOptions": {
        "path": "./src/main/cpp/CMakeLists.txt",
        "arguments": [
          "-DRNOH_APP_DIR=${RNOH_CPP_DIR}",
          "-DCMAKE_BUILD_TYPE=Release"
        ],
        "cppFlags": "-fstack-protector-strong -Wl,-z,noexecstack"
      },
      "nativeLib": {
        "debugSymbol": {
          "strip": true  // Release 模式剥离符号
        }
      }
    }
  ]
}

步骤三：配置 CMakeLists.txt（Release 模式）

使用 Release 包需要特殊的 CMake 配置：

cmake_minimum_required(VERSION 3.10)
project(MyApp)

# Release 模式基本配置
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# Release 模式特有配置
if(CMAKE_BUILD_TYPE STREQUAL "Release")
    # 启用最高优化
    add_compile_options(-O3)
    
    # 启用链接时优化（可选）
    # add_compile_options(-flto)
    
    # 禁用调试符号
    add_compile_options(-g0)
endif()

# 添加 RNOH 依赖（Release 版本）
add_subdirectory(${RNOH_CPP_DIR} ./rnoh)

Release 包专用 CMakeLists.txt 示例：

参考模板文件：CMakeLists-release.txt

3.3 DevEco Studio 编译 Release 包

打开 DevEco Studio
在工具栏选择 Build Mode 为 Release
设置 Debuggable 为 false
点击 Build > Make Module 'entry'
编译完成后，产物位于 build/release/outputs/default/

3.4 Release 包签名

Release 包需要签名才能安装到真机：

在 DevEco Studio 中配置签名：
- File > Project Structure > Signing Configs
- 添加签名证书和配置
或手动配置 build-profile.json5：

{
  "signingConfigs": [
    {
      "name": "release",
      "type": "HarmonyOS",
      "material": {
        "certpath": "path/to/cert.cer",
        "storePassword": "your_password",
        "keyAlias": "your_alias",
        "keyPassword": "your_key_password",
        "profile": "path/to/profile.p7b",
        "signAlg": "SHA256withECDSA",
        "storeFile": "path/to/store.p12"
      }
    }
  ]
}

四、CMake 配置详解

4.1 CMakeLists.txt 基础结构

cmake_minimum_required(VERSION 3.10)

# 项目名称
project(MyRNApp)

# C++ 标准
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# RNOH 相关路径（需要根据实际工程调整）
set(RNOH_CPP_DIR "${OH_ROOT_DIR}/native/api/10/packages/react_native_openharmony")

# 添加编译参数
add_compile_definitions(
    WITH_HITRACE_SYSTRACE=1
    WITH_HITRACE_REACT_MARKER=1
)

# 添加源文件
add_executable(my_app
    src/main/cpp/main.cpp
    src/main/cpp/PackageProvider.cpp
)

# 链接 RNOH 库
target_link_libraries(my_app
    ${OH_LIB_DIR}/librnoh_core.so
    ${OH_LIB_DIR}/librnoh_core_package.so
)

# 添加 RNOH 模块
add_subdirectory(${RNOH_CPP_DIR} ./rnoh)

4.2 常用 CMake 变量

变量	说明	示例值
`CMAKE_BUILD_TYPE`	构建类型	Debug / Release
`RNOH_CPP_DIR`	RNOH C++ 源码路径	`${OH_ROOT_DIR}/native/api/10/packages/react_native_openharmony`
`CMAKE_CXX_STANDARD`	C++ 标准	17
`OH_LIB_DIR`	OpenHarmony 库路径	`${OHOS_SDK}/native/llvm/lib`

4.3 常用编译选项

选项	说明	Debug	Release
`-g`	生成调试符号	✓	✗
`-O0`	无优化	✓	✗
`-O3`	最高优化	✗	✓
`-fstack-protector-strong`	栈保护	可选	✓
`-Wl,-z,noexecstack`	禁止栈执行	可选	✓

4.4 RNOH 特定编译选项

# RNOH 特定选项
add_compile_definitions(
    # Hitrace 支持（性能分析）
    WITH_HITRACE_SYSTRACE=ON
    WITH_HITRACE_REACT_MARKER=ON
    
    # 日志级别
    LOG_VERBOSITY_LEVEL=1
    
    # JSVM 支持
    ADD_JSVM_SO=ON
)

五、环境配置

5.1 DevEco Studio 环境配置

SDK 配置

打开 DevEco Studio
File > Settings > HarmonyOS SDK
配置 SDK 路径和版本：
- HarmonyOS SDK：建议使用 API 10 或以上
- Native SDK：包含 NDK 工具链

NDK 配置

确保 NDK 工具链正确配置：

// build-profile.json5
{
  "nativeCompiler": "BiSheng"  // 使用 BiSheng 编译器
}

5.2 命令行环境配置

配置环境变量

# HarmonyOS SDK 路径
export OHOS_SDK=/path/to/harmonyos/sdk

# NDK 路径
export OHOS_NDK=${OHOS_SDK}/native

# 工具链路径
export PATH=${OHOS_NDK}/llvm/bin:$PATH

Hvigorw 命令

# 编译 Debug 版本
hvigorw --mode module -p product=default -p module=entry@default -p buildMode=debug assembleHap

# 编译 Release 版本
hvigorw --mode module -p product=default -p module=entry@default -p buildMode=release -p debuggable=false assembleHap

5.3 检查环境

# 检查 CMake 版本
cmake --version

# 检查 LLVM 工具链
llvm-clang --version

# 检查 Hvigorw
hvigorw -v

六、构建命令速查

6.1 DevEco Studio GUI 操作

操作	菜单路径
编译 Module	Build > Make Module 'xxx'
清理工程	Build > Clean Project
重新编译	Build > Rebuild Project
打包 HAP	Build > Build Hap(s)/APP(s) > Build Hap(s)

6.2 命令行操作

# 清理
hvigorw clean

# 编译 Debug
hvigorw --mode module -p buildMode=debug assembleHap

# 编译 Release
hvigorw --mode module -p buildMode=release -p debuggable=false assembleHap

# 打包 APP
hvigorw --mode module -p buildMode=release assembleApp

七、常见问题

7.1 Debug 包编译慢

原因：Debug 模式无优化，包含调试信息

解决方案：

开发阶段使用 Debug 包
性能测试使用 Release 包
需要快速验证时，可以临时使用 Release 包

7.2 Release 包无法调试

原因：Release 包剥离了调试符号

解决方案：

使用配套的 .sym 符号文件进行崩溃分析
参考详细的符号管理指南：RNOH 构建与符号管理工程级指南

7.3 编译报错找不到 RNOH

原因：RNOH 依赖配置错误

解决方案：

检查 oh-package.json5 中的依赖配置
检查 CMakeLists.txt 中的路径配置
确保 ohpm install 已执行

7.4 Release 包安装失败

原因：签名配置错误

解决方案：

检查签名配置是否正确
确保使用正确的证书和 profile
检查 build-profile.json5 中的 signingConfigs 配置

编译构建指南

一、构建模式概述

二、使用 Debug 包

2.1 获取 Debug 包

2.2 配置使用 Debug 包

步骤一：配置 oh-package.json5

步骤二：配置 build-profile.json5

步骤三：配置 CMakeLists.txt（Debug 模式）

2.3 DevEco Studio 编译 Debug 包

2.4 Debug 包调试

三、使用 Release 包

3.1 获取 Release 包

3.2 配置使用 Release 包

步骤一：配置 oh-package.json5

步骤二：配置 build-profile.json5（Release 模式）

步骤三：配置 CMakeLists.txt（Release 模式）

3.3 DevEco Studio 编译 Release 包

3.4 Release 包签名

四、CMake 配置详解

4.1 CMakeLists.txt 基础结构

4.2 常用 CMake 变量

4.3 常用编译选项

4.4 RNOH 特定编译选项

五、环境配置

5.1 DevEco Studio 环境配置

SDK 配置

NDK 配置

5.2 命令行环境配置

配置环境变量

Hvigorw 命令

5.3 检查环境

六、构建命令速查

6.1 DevEco Studio GUI 操作

6.2 命令行操作

七、常见问题

7.1 Debug 包编译慢

7.2 Release 包无法调试

7.3 编译报错找不到 RNOH

7.4 Release 包安装失败

八、相关文档