文章目录

【鸿蒙PC命令行适配】鸿蒙 PC对SQLite的适配移植实战：交叉编译与部署方案详解

前言

在鸿蒙 PC 的开发环境中，数据库是应用存储与数据管理的核心组件。SQLite 以其轻量、嵌入式、零配置的特性，在桌面和移动平台都有广泛应用。对于鸿蒙 PC 开发者来说，直接使用系统自带数据库可能无法满足版本控制、性能优化或自定义编译需求，因此掌握 SQLite 的交叉编译和部署方法非常必要。本文将从源码下载、工具链配置到编译部署，手把手讲解在鸿蒙 PC 上完整适配 SQLite 的流程，帮助开发者实现可控、稳定的数据库环境。

在这里插入图片描述

一、SQLite 在鸿蒙 PC 中的定位

SQLite 是一款轻量级嵌入式数据库，它将整个数据库引擎封装在一个库中，既可以作为静态库链接到应用，也可以生成动态库或独立的命令行工具。其特点在于：

  1. 零依赖与高可移植性
    SQLite 仅依赖标准 C 运行环境，不依赖外部数据库服务，非常适合嵌入式平台，包括鸿蒙 PC。

  2. 轻量与高性能
    SQLite 的核心库非常小，运行时内存占用低，I/O 性能高，适合对资源敏感的 PC 端命令行工具和服务端应用。

  3. 灵活的部署方式
    可以生成：

    • 静态库：直接编译进应用，适合小型工具或单文件部署
    • 动态库：供多个应用共享，适合复杂系统
    • 命令行工具 sqlite3：用于调试、测试和快速验证数据库操作

在鸿蒙 PC 的生态中，SQLite 可以用于：

  • 应用本地数据存储：例如配置文件、日志和缓存
  • 快速原型开发：在没有完整数据库服务时进行快速数据操作
  • 系统工具集成：命令行工具、脚本执行环境等

因此，掌握 SQLite 的交叉编译与适配，是鸿蒙 PC 开发者必备技能。

在这里插入图片描述

二、整体适配思路

在鸿蒙 PC 平台上适配 SQLite，核心在于 交叉编译与工具链配置。整体思路可以概括为以下：

在鸿蒙 PC 平台上适配 SQLite 的核心在于交叉编译与工具链配置。整体流程包括环境准备、源码获取、交叉编译、部署验证以及问题排查与优化。开发者需先安装 OHOS SDK 并配置 Clang/LLVM 工具链与 sysroot，确保可针对 aarch64 架构生成可执行文件；随后获取 SQLite 官方源码，保证稳定性和兼容性。在交叉编译环节，可选择标准 configure + make 工程化方式生成库和工具，或用极简方式快速验证工具链。完成编译后，将产物部署到鸿蒙 PC 并通过 SQL 测试验证功能，同时注意宿主机与目标架构差异、链接器配置以及静态/动态库选择，从而实现稳定、可控的 SQLite 适配与部署。

通过以上整体思路，开发者可以系统化、工程化地在鸿蒙 PC 上完成 SQLite 的适配和部署，为后续应用开发打下稳固基础。

在这里插入图片描述

三、前置条件：OHOS SDK 与 Clang/LLVM 工具链准备

在开始 OpenHarmony（OHOS）开发与交叉编译之前，必须确保 SDK 和工具链已正确安装。本章将系统介绍在 Linux 环境下的安装与配置步骤，包括 SDK 下载、解压、工具链验证以及环境变量设置。

3.1 OHOS SDK 安装

首先，需要从 OpenHarmony 每日构建（Daily Build）页面 下载最新 SDK。请确保网络稳定，因为文件较大，下载时间可能较长。

wget https://cidownload.openharmony.cn/version/Daily_Version/OpenHarmony_6.1.0.28/20260121_020509/version-Daily_Version-OpenHarmony_6.1.0.28-20260121_020509-ohos-sdk-public.tar.gz

下载完成后，可使用以下命令检查文件大小和完整性：

ls -lh version-Daily_Version-OpenHarmony_6.1.0.28-20260121_020509-ohos-sdk-public.tar.gz

在这里插入图片描述

提示：下载过程中如出现中断，可使用 wget -c 继续下载未完成的文件。

3.2 Clang/LLVM 工具链解压与验证

3.2.1 解压 SDK

将下载的 SDK 压缩包解压到 /opt 目录（可根据实际需求调整路径）：

sudo tar -xzf version-Daily_Version-OpenHarmony_6.1.0.28-20260121_020509-ohos-sdk-public.tar.gz -C /opt

进入解压后的 SDK 目录，重点关注 Linux 平台子目录：

cd /opt/ohos-sdk/linux

3.2.2 解压工具链与原生组件

OHOS SDK 内部提供了 Linux 平台的原生工具和交叉编译工具链，分别存放在 native*.zip 与 toolchains*.zip 文件中。使用以下命令解压：

sudo unzip native*.zip
sudo unzip toolchains*.zip

解压完成后的目录结构示例如下：

在这里插入图片描述

3.2.3 验证工具链完整性

进入解压后的 LLVM 工具目录，检查核心工具是否完整：

ls native/llvm/bin

输出应包含以下关键工具：

  • clang：C 语言编译器
  • clang++：C++ 编译器
  • llvm-as：LLVM 汇编器
  • 其他常用 LLVM 工具（如 llc, llvm-link 等）

示例输出：

在这里插入图片描述

注意：确保以上工具可执行，否则后续交叉编译过程会失败。

3.3 环境变量配置

为了在终端直接调用 SDK 提供的工具链，需要将其路径加入系统环境变量中。可在当前用户的 ~/.bashrc 或 ~/.zshrc 中添加：

export OHOS_SDK_PATH=/opt/ohos-sdk/linux
export PATH=$OHOS_SDK_PATH/native/llvm/bin:$PATH

使修改生效：

source ~/.bashrc   # 或 source ~/.zshrc

验证是否成功：

clang --version

输出类似如下信息，即表示环境变量配置成功，LLVM 工具链可以在任何终端直接使用。

在这里插入图片描述

完成上述步骤后，OHOS SDK 与 Clang/LLVM 工具链已在 Linux 系统中正确安装并配置好环境变量。下一步即可开始基于 OHOS 的应用开发与交叉编译工作。

四、下载与准备 SQLite 源码

在交叉编译或构建数据库相关应用时，推荐使用 SQLite 官方源码，因为它最干净、最稳定，并且 ABI 兼容性良好。

4.1 下载 SQLite 源码

可以通过官方提供的压缩包直接下载：

wget https://www.sqlite.org/2024/sqlite-autoconf-3460000.tar.gz

说明：

  • 3460000 为 SQLite 3.46.0 的版本号，可根据需要替换为其他版本。
  • SQLite 的 ABI 稳定性较高，因此版本升级通常不会破坏接口兼容性。

下载完成后解压：

tar -xzf sqlite-autoconf-3460000.tar.gz
cd sqlite-autoconf-3460000

提示：如果在大陆服务器下载速度较慢，可以使用本地上传或镜像源，操作方式与官方源码一致。

在这里插入图片描述

4.2 查看源码目录结构

解压完成后，源码目录结构如下：

在这里插入图片描述

说明：

  • sqlite3.c 和 sqlite3.h 是核心源文件，可直接用于编译。
  • configure 脚本和 Makefile 用于生成标准 Linux 或交叉编译环境下的可执行文件。
  • shell.c 提供 SQLite 命令行工具实现，可用于测试与调试。

完成上述步骤后，SQLite 源码已准备好，可用于后续的交叉编译、嵌入式构建或定制化开发。下一步可以根据目标平台配置编译参数进行构建。

五、核心：交叉编译 SQLite

在 OHOS 平台上使用 SQLite 时，需要将其交叉编译为目标架构（aarch64-linux-ohos）的二进制。以下内容分为两种方式：标准工程化交叉编译与极简暴力验证法。

5.1 方式一：Autoconf 标准交叉编译（推荐）

这是最稳妥、工程化的方式，适合正式发布和集成到项目中。

5.1.1 初次尝试

在源码目录下直接使用标准 configure：

./configure \
  --host=aarch64-linux-ohos \
  --prefix=$(pwd)/target \
  CC=clang \
  CFLAGS="--target=aarch64-linux-ohos -fPIC" \
  LDFLAGS="--target=aarch64-linux-ohos"

可能报错如下：

在这里插入图片描述

原因分析：

  • 宿主机原生 clang（x86_64-linux-gnu）没有 OHOS sysroot
  • 缺少 libc、ld.so、启动文件 crt*.o
  • configure 在测试编译简单程序时会失败，报出：
C compiler cannot create executables

这是交叉编译常见问题，非偶然失败。

5.1.2 设置 OHOS SDK 环境

为正确交叉编译，需设置 SDK 环境变量：

export OHOS_SDK=/opt/ohos-sdk/linux/native
export PATH=$OHOS_SDK/llvm/bin:$PATH
export SYSROOT=$OHOS_SDK/sysroot

然后执行 configure，并指定 sysroot：

./configure \
  --host=aarch64-linux-ohos \
  --prefix=$(pwd)/target \
  CC=clang \
  CFLAGS="--target=aarch64-linux-ohos --sysroot=$SYSROOT -fPIC" \
  LDFLAGS="--target=aarch64-linux-ohos --sysroot=$SYSROOT"

在这里插入图片描述
在这里插入图片描述

此时 configure 可通过，生成 Makefile。

5.1.3 避免宿主机链接器干扰

执行 make 可能报错：

/usr/bin/ld: cannot find crtbeginS.o
Relocations in generic ELF (EM: 183)
File in wrong format

原因：

  • /usr/bin/ld 是宿主机 x86_64 链接器
  • 目标是 aarch64，格式不匹配
  • 启动文件位于 sysroot 中，宿主机链接器找不到

解决方法：显式指定交叉链接器和工具：

export CC=clang
export CFLAGS="--target=aarch64-linux-ohos --sysroot=$SYSROOT -fPIC"
export LDFLAGS="--target=aarch64-linux-ohos --sysroot=$SYSROOT"
export AR=$OHOS_SDK/llvm/bin/llvm-ar
export RANLIB=$OHOS_SDK/llvm/bin/llvm-ranlib
export LD=$OHOS_SDK/llvm/bin/clang

重点：使用 SDK 自带的 clang 作为链接器，不要走 /usr/bin/ld。

5.1.4 编译与安装

重新执行编译：

make -j2
make install

编译成功示意：

在这里插入图片描述

如果希望生成 静态库（推荐工程化）：

./configure \
  --host=aarch64-linux-gnu \
  --prefix=$(pwd)/target \
  CC=$OHOS_SDK/llvm/bin/clang \
  CFLAGS="--target=aarch64-linux-ohos --sysroot=$SYSROOT -fPIC" \
  LDFLAGS="--target=aarch64-linux-ohos --sysroot=$SYSROOT" \
  AR=$OHOS_SDK/llvm/bin/llvm-ar \
  RANLIB=$OHOS_SDK/llvm/bin/llvm-ranlib \
  --disable-shared

编译完成后生成目录结构：

在这里插入图片描述
在这里插入图片描述

最终产物：

target/
  bin/sqlite3
  lib/libsqlite3.a
  include/sqlite3.h

这些即可直接在鸿蒙 PC 上使用。

5.2 方式二：极简暴力法（仅作教学验证）

如果只想验证工具链是否可用，可直接手动编译，不使用 configure：

5.2.1 生成动态库

clang \
  --target=aarch64-linux-ohos \
  -fPIC -shared \
  sqlite3.c \
  -o libsqlite3.so

5.2.2 生成命令行可执行文件

clang \
  --target=aarch64-linux-ohos \
  sqlite3.c \
  -o sqlite3

说明：

  • 适合快速验证工具链
  • 不支持 feature 开关
  • 不适合生产环境或工程化发布
  • 推荐方式：Autoconf 标准交叉编译，生成静态库和可执行文件
  • 验证工具链：极简暴力法
  • 核心关键：指定交叉 sysroot 和工具链，避免宿主机链接器干扰

六、运行 SQLite 到鸿蒙 PC

完成交叉编译后，我们将生成的产物部署到鸿蒙 PC，并验证可执行性。

6.1 部署文件

交叉编译生成的产物如下：

bin/sqlite3
lib/libsqlite3.a
include/sqlite3.la

将这些文件上传或拷贝到鸿蒙 PC 对应目录。示意图如下：

在这里插入图片描述
在这里插入图片描述
在这里插入图片描述

6.2 执行 SQLite

进入部署目录后，尝试运行：

./sqlite3 test.db

可能出现报错：

zsh: permission denied: ./sqlite3

原因：文件没有可执行权限，导致 shell 无法执行。

6.3 解决方法

为可执行文件添加权限：

chmod +x ./sqlite3

再次执行：

./sqlite3 test.db

此时 SQLite 命令行工具运行成功，示意图如下：

在这里插入图片描述

  • 部署文件包括 可执行文件、静态库和头文件。
  • 部署到鸿蒙 PC 后，需要确保 可执行权限。
  • 成功运行后即可使用 SQLite 命令行操作数据库。

七、鸿蒙 PC SQLite 运行效果

7.1. 简单 SQL 验证

在 SQLite 提示符下执行：

sqlite> CREATE TABLE user(id INTEGER PRIMARY KEY, name TEXT);
sqlite> INSERT INTO user(name) VALUES('Alice');
sqlite> INSERT INTO user(name) VALUES('Bob');
sqlite> SELECT * FROM user;

输出示例：

在这里插入图片描述

说明：

  • SQLite 核心功能正常
  • 表、插入、查询操作均可使用
  • 说明数据库文件在鸿蒙 PC 文件系统下可读写

7.2. 高级验证

如果你的项目中有线程安全或 JSON 功能，可以做进一步验证：

sqlite> SELECT json('{"key": "value"}');

返回：

在这里插入图片描述

说明 JSON1 扩展生效，线程安全模式正常。

  • ：bin/sqlite3 可直接执行，无需设置 LD_LIBRARY_PATH
  • 务必保证 .so 文件路径正确，并签名 ELF 文件
  • 数据库文件必须写入鸿蒙允许访问的路径，如 /storage/Users/currentUser/
  • 与 OpenSSL 一样，验证可执行文件 + 库加载 + 简单功能，即可确认交叉编译成功

八、心得

在本次鸿蒙 PC SQLite 适配与交叉编译实战中，我总结了以下几点经验与体会：

  1. 工具链和 sysroot 是关键

    • 交叉编译的核心在于使用正确的目标架构工具链和 sysroot。
    • OHOS SDK 提供的 Clang/LLVM 工具链完整性直接影响编译成功率。
    • 避免宿主机链接器干扰是成功的前提，否则会出现 ELF 格式不匹配的错误。

  2. Autoconf 标准化流程稳妥

    • 尽管手动极简编译能快速验证工具链可用性，但生产环境应使用 configure + make 工程化方式。
    • 静态库 + 可执行文件组合，能同时满足嵌入式部署和命令行调试需求。

  3. 调试和验证必不可少

    • 交叉编译完成后，务必在鸿蒙 PC 上运行可执行文件进行验证。
    • 从简单的建表、插入、查询开始，逐步扩展到线程安全、JSON 扩展等高级功能。
    • 文件权限、ELF 签名和库路径问题是常见坑点，提前检查可避免浪费时间。

  4. 灵活部署策略

    • 根据应用需求选择静态库还是动态库。
    • 命令行工具 sqlite3 适合快速验证和调试，库文件可集成到应用中。
    • 对于长期维护项目，建议统一使用 SDK 提供的交叉工具链生成的产物，保证稳定性。

  5. 文档和版本控制

    • SQLite 的源码和版本号需要明确记录，以便后续迭代或回滚。
    • OHOS SDK 版本更新时，需要验证工具链兼容性，避免出现编译失败或功能异常。

通过本次实践，可以明显感受到鸿蒙 PC 交叉编译环境的规范性和挑战性：一旦掌握工具链、sysroot 和交叉编译流程，就能灵活控制数据库的版本和功能，显著提升开发效率和系统稳定性。

在这里插入图片描述

九、总结

通过本次实践，我们完整掌握了在鸿蒙 PC 上适配 SQLite 的流程：从 OHOS SDK 与 Clang/LLVM 工具链的环境准备，到 SQLite 官方源码获取，再到标准化交叉编译、部署与验证，最终实现了可执行命令行工具和库文件的稳定运行。整个过程中，工具链配置、sysroot 指定以及宿主机链接器干扰是关键难点，而验证和权限设置是确保成功运行的重要环节。掌握这一流程，不仅能够灵活控制 SQLite 的版本和功能，也为后续在鸿蒙 PC 上移植其他第三方库打下了坚实基础，实现了开发环境可控、部署可靠、功能完整的目标。

欢迎加入开源鸿蒙PC社区：https://harmonypc.csdn.net/

# harmonyos # sqlite # jvm
Logo
Harmony PC 开发者社区

赋能鸿蒙PC开发者，共建全场景原生生态，共享一次开发多端部署创新价值。

更多推荐

cover

交叉编译 OpenSSL 3.5：鸿蒙 PC 命令行适配实战指南【鸿蒙PC真机实战】

avatar Harmony PC 开发者社区
cover

鸿蒙 PC 版真机运行——开源鸿蒙原生开发案例之鸿蒙开发者应用个人页面完整实现与 Bug 优化

avatar Harmony PC 开发者社区
cover

鸿蒙 PC 实战：交叉编译 zlib（aarch64-linux-ohos）完整可复现指南

avatar Harmony PC 开发者社区