OpenHarmony开发者论坛

标题: OpenHarmony 使用 Lycium 交叉编译完整指南 [打印本页]
作者: qzq    时间: 2025-12-30 15:25
标题: OpenHarmony 使用 Lycium 交叉编译完整指南
[md]```
# OpenHarmony 使用 Lycium 交叉编译完整指南

## 什么是交叉编译？

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

---

## Lycium 交叉编译框架介绍

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


## 环境准备

### 安装基础编译工具

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

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

---

## SDK下载与配置

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

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

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

# 下载 OpenHarmony 6.0 SDK
wget https://repo.huaweicloud.com/ope ... linux-public.tar.gz
```

### Step 2: 解压SDK

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

```bash
# 第一步：解压外层 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 目录：

```bash
# 设置 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++ 三方库集合：

```bash
# 回到用户主目录
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: 查看编译产物

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

![image.png](https://forums-obs.openharmony.c ... rrphljyubgrnsr7.png "image.png")
编译生成的库文件位于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
```

**目录结构：**

![image2.png](https://forums-obs.openharmony.c ... 1azuz8zg8htf6f1.png "image2.png")

### Step 3: 配置 CMakeLists.txt

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

```cmake
# 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` 文件：增加以下代码

```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` 文件：

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

### Step 6: 编写测试页面

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

```typescript
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工程：

![image3.png](https://forums-obs.openharmony.c ... i8tmluucucxcruz.png "image3.png")

![image6.png](https://forums-obs.openharmony.c ... vne7hxf2z212421.png "image6.png")

**参考文档：** [HarmonyOS FAQ - 应用调试常见问题](https://developer.huawei.com/con ... qs-app-debugging-14)

---

### 问题 2: SystemCapability 配置缺失

**错误提示：**

![image4.png](https://forums-obs.openharmony.c ... knxp8kwd4xod4vs.png "image4.png")

**解决方法：**

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

![image5.png](https://forums-obs.openharmony.c ... scrcnj4csjvrmds.png "image5.png")

```

```
[/md]



欢迎光临 OpenHarmony开发者论坛 (https://forums.openharmony.cn/) Powered by Discuz! X3.5