OpenHarmony 使用 Lycium 交叉编译完整指南

什么是交叉编译？

交叉编译是指在一个平台（如 x86_64 Linux）上编译出能在另一个平台（如 ARM 架构的 OpenHarmony 设备）上运行的程序。

Lycium 交叉编译框架介绍

Lycium 是一款专为 OpenHarmony 设计的编译框架工具，帮助开发者基于 Shell 脚本快速配置 C/C++ 三方库的编译方式和参数，实现高效的交叉编译，并生成可在目标设备上运行的二进制文件。

环境准备

安装基础编译工具

安装必要的编译构建工具：

sudo apt update && sudo apt install -y gcc cmake make pkg-config autoconf automake ninja-build

SDK下载与配置

Step 1: 创建工作目录并下载SDK

在 Linux 环境下执行以下命令：

# 创建SDK目录
mkdir -p ~/ohos_sdk
cd ~/ohos_sdk

# 下载 OpenHarmony 6.0 SDK
wget https://repo.huaweicloud.com/openharmony/os/6.0-Release/ohos-sdk-windows_linux-public.tar.gz

Step 2: 解压SDK

OpenHarmony SDK 采用两层压缩结构，需要分两步解压：

# 第一步：解压外层 tar.gz 压缩包
tar -zxvf ohos-sdk-windows_linux-public.tar.gz

# 查看解压后的内容
ls
# 输出: daily_build.log  linux  manifest_tag.xml  windows

# 第二步：进入 linux 目录
cd linux

# 查看 linux 目录中的内容（里面还有多个 .zip 文件）
ls
# 输出: native.zip  ets.zip  js.zip  toolchains.zip  ...

# 批量解压所有 .zip 文件
for i in *.zip; do unzip -q $i; done

Step 3: 配置环境变量

Lycium 需要使用 Native SDK 中的工具链，配置环境变量指向 SDK 目录：

# 设置 OHOS_SDK 路径（native的父目录）
export OHOS_SDK=~/ohos_sdk/linux

# 将配置写入 .bashrc（永久生效）
echo 'export OHOS_SDK=~/ohos_sdk/linux' >> ~/.bashrc
source ~/.bashrc

# 验证配置
echo $OHOS_SDK
# 应输出: /home/xxx/ohos_sdk/linux

交叉编译实践

Step 1: 下载三方库源码仓库

获取 OpenHarmony 官方维护的 C/C++ 三方库集合：

# 回到用户主目录
cd ~
# 克隆 TPC C/C++ 三方库仓库
git clone https://gitcode.com/openharmony-sig/tpc_c_cplusplus.git

# 进入lycium目录
cd tpc_c_cplusplus/lycium

# 执行编译脚本
./build.sh p7zip

Step 4: 查看编译产物

编译成功后，可以看到类似以下提示：

编译生成的库文件位于tpc_c_cplusplus/lycium/usr/ 目录下：

HAP包集成验证

开发环境

• IDE: DevEco Studio 6.0.1 Release
• 测试设备: RK3568 开发板
• SDK版本: 20

Step 1: 创建 Native C++ 工程

使用 DevEco Studio 创建一个 Native C++ 应用工程。

Step 2: 拷贝编译产物

将编译生成的对应架构的 .so 库文件拷贝到工程目录并改名libxxx.so：

项目根目录/entry/libs/arm64-v8a/lib7z.so

目录结构：

Step 3: 配置 CMakeLists.txt

修改 entry/src/main/cpp/CMakeLists.txt 文件，导入预编译的 lib7z.so 库：

# the minimum version of CMake.
cmake_minimum_required(VERSION 3.5.0)
project(MyApplication)

set(NATIVERENDER_ROOT_PATH ${CMAKE_CURRENT_SOURCE_DIR})

if(DEFINED PACKAGE_FIND_FILE)
    include(${PACKAGE_FIND_FILE})
endif()

include_directories(${NATIVERENDER_ROOT_PATH}
                    ${NATIVERENDER_ROOT_PATH}/include)

# 导入预编译的 lib7z.so 库
add_library(7z SHARED IMPORTED GLOBAL)
set_target_properties(7z PROPERTIES
    IMPORTED_LOCATION ${CMAKE_CURRENT_SOURCE_DIR}/../../../libs/${OHOS_ARCH}/lib7z.so
    IMPORTED_NO_SONAME TRUE
)

# 创建 entry 模块并链接库
add_library(entry SHARED napi_init.cpp)
target_link_libraries(entry PUBLIC libace_napi.z.so 7z)

Step 4: 编写 NAPI 桥接层

使用 p7zip 源码中的 CRC32 计算接口作为示例。

修改 napi_init.cpp 文件：增加以下代码

#include <cstring>

// 声明 7z 库中的 CRC32 函数
extern "C" {
    typedef uint32_t UInt32;
    void CrcGenerateTable(void);
    UInt32 CrcCalc(const void *data, size_t size);
}

// NAPI 封装：测试 7z 库的 CRC32 计算
static napi_value Test7z(napi_env env, napi_callback_info info)
{
    // 初始化 CRC 表
    CrcGenerateTable(); 
    // 测试字符串
    const char* testStr = "Hello, 7zip!";
    // 计算 CRC32
    UInt32 crc = CrcCalc(testStr, strlen(testStr));  
    // 返回结果给 JS
    napi_value result;
    napi_create_uint32(env, crc, &result);
    return result;
}

// 注册 NAPI 模块
EXTERN_C_START
static napi_value Init(napi_env env, napi_value exports)
{
    napi_property_descriptor desc[] = {
        { "add", nullptr, Add, nullptr, nullptr, nullptr, napi_default, nullptr },
        { "test7z", nullptr, Test7z, nullptr, nullptr, nullptr, napi_default, nullptr }
    };
    napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);
    return exports;
}
EXTERN_C_END

static napi_module demoModule = {
    .nm_version = 1,
    .nm_flags = 0,
    .nm_filename = nullptr,
    .nm_register_func = Init,
    .nm_modname = "entry",
    .nm_priv = ((void*)0),
    .reserved = { 0 },
};

extern "C" __attribute__((constructor)) void RegisterEntryModule(void)
{
    napi_module_register(&demoModule);
}

Step 5: 声明 TypeScript 接口

修改 entry/src/main/cpp/types/libentry/index.d.ts 文件：

export const add: (a: number, b: number) => number;
export const test7z: () => number;

Step 6: 编写测试页面

修改 entry/src/main/ets/pages/Index.ets 文件：

import { hilog } from '@kit.PerformanceAnalysisKit';
import testNapi from 'libentry.so';

const DOMAIN = 0x0000;

@Entry
@Component
struct Index {
  @State message: string = 'Hello World';
  @State crcResult: string = '点击测试 7z 库';

  build() {
    Row() {
      Column() {
        // 测试基础 NAPI 接口
        Text(this.message)
          .fontSize($r('app.float.page_text_font_size'))
          .fontWeight(FontWeight.Bold)
          .onClick(() => {
            this.message = 'Welcome';
            hilog.info(DOMAIN, 'testTag', 'Test NAPI 2 + 3 = %{public}d', testNapi.add(2, 3));
          })

        // 测试 7z 库 CRC32 功能
        Text(this.crcResult)
          .fontSize(20)
          .fontColor(Color.Blue)
          .margin({ top: 20 })
          .padding(10)
          .backgroundColor('#f0f0f0')
          .borderRadius(8)
          .onClick(() => {
            try {
              const crc = testNapi.test7z();
              this.crcResult = `7z库测试成功!\nCRC32值: 0x${crc.toString(16).toUpperCase()}`;
              hilog.info(DOMAIN, 'testTag', 'Test 7z CRC32 = 0x%{public}s', crc.toString(16));
            } catch (error) {
              this.crcResult = `7z库测试失败: ${error}`;
              hilog.error(DOMAIN, 'testTag', 'Test 7z failed: %{public}s', error);
            }
          })
      }
      .width('100%')
    }
    .height('100%')
  }
}

常见问题与解决方案

问题 1: ABI 类型不匹配

错误提示：

TypeError: Cannot read property add of undefined

原因分析：

设备支持的 ABI 架构与编译的库架构不匹配。

解决方法：

修改模块级 build-profile.json5 文件，配置正确的 ABI 类型并且将工程转化为OpenHarmony工程：

参考文档： HarmonyOS FAQ - 应用调试常见问题

问题 2: SystemCapability 配置缺失

错误提示：

解决方法：

在 entry/src/main 目录下创建 syscap.json 文件并配置