build-qt 1.0.1

一个用于在 Windows/Linux/macOS 上自动化构建 Qt for OpenHarmony（OHOS）的工具集

build-qt-ohos (Qt for OHOS 一键构建脚本)

一个用于在 Windows/Linux/macOS 上自动化构建 Qt for OpenHarmony（OHOS）的工具集：

• 自动克隆 Qt 源码和 OHOS 补丁仓库，并应用补丁
• 自动检查/安装构建依赖（Windows 下可自动下载 Perl、MinGW；各平台可自动下载 OHOS SDK）
• 一条命令完成 configure/build/install，并可打包产物
• 支持 Qt 5.15.12 ，支持 arm64-v8a/armeabi-v7a/x86_64

本文档依据仓库代码与 configure.json 整理，覆盖从准备环境到产物打包的完整流程。

---

功能简介

本项目通过 build-qt-ohos.py 提供以下能力：

• init：
  • 克隆 Qt 源码仓库（可选浅克隆/指定分支或 tag）
  • 克隆 Qt for OHOS 补丁仓库
  • 自动应用对应版本的补丁（并复制 qtohextras 模块）
• env_check：
  • 自动检测 Perl/MinGW（Windows）、make/Perl（Linux/macOS）
  • 自动下载/解压缺失组件（Windows：Perl/MinGW；各平台：OHOS SDK native 包）
  • 设置 OHOS_SDK_PATH 环境变量
• 构建阶段：configure/build/install/clean/all/print_build_info
• 打包：将安装前缀目录打包为 zip（Windows）或 tar.gz（Linux/macOS）

核心模块：

• build_qt/qt_repo.py：Git 操作与补丁应用
• build_qt/config.py：配置、环境检测与依赖下载
• build_qt/qt_build.py：调用 Qt configure/make/make install
• build_qt/utils.py：下载、校验、解压与打包
• build_qt/ohos_sdk_downloader.py：从官方接口拉取并下载 OHOS SDK

支持平台

• Windows 10/11（推荐）
• Linux 发行版（需编译工具链）
• macOS（需 Xcode/Command Line Tools）

脚本会根据平台选择合适的 make 工具：

• Windows：mingw32-make
• Linux/macOS：make

先决条件

• Python 3.8+（建议 3.10+）
• Git 命令行（脚本通过 GitPython/系统 git 调用）
• 网络可访问以下源：
  • Qt 源码与补丁仓库（默认 GitCode 镜像）
  • 依赖组件下载（Perl/MinGW 预编译包、OHOS SDK 官方接口）
• 充足磁盘空间：
  • Qt 源码 + 构建中间文件 + 安装产物，建议预留 20GB 以上

安装依赖

在项目根目录执行：

python -m pip install -r requirements.txt

包含：requests、GitPython、questionary、rich、py7zr。

快速上手

以下以 Windows cmd 为例（Linux/macOS 命令相同，仅输出格式略有差异）：

1. 初始化仓库并应用补丁（首次执行会创建/询问用户配置）

python build-qt-ohos.py --init

2. 检查并准备开发环境（Windows 会自动下载 Perl/MinGW；任何平台会下载 OHOS SDK native 包）

python build-qt-ohos.py --env_check

3. 一条命令完成配置、编译、安装，并打包产物

python build-qt-ohos.py --exe_stage all --with_pack

构建完成的安装目录和压缩包位置见下文“构建输出与打包”。

详细命令

build-qt-ohos.py 支持以下参数（来自脚本源码）：

• --init：初始化 Qt 仓库并应用补丁
• --env_check：检查并准备开发环境
• --reset_repo：重置 Qt 源码与所有子模块（git reset --hard/clean），并重新应用补丁
• --exe_stage {configure|build|install|clean|all|print_build_info}：执行指定阶段
  • configure：调用 Qt 的 configure(.bat) 生成构建配置
  • build：调用 make -jN 或 mingw32-make -jN
  • install：make install
  • clean：仅删除构建目录（不触碰源码）
  • all：依次执行 configure/build/install
  • print_build_info：打印当前构建参数与路径
• --with_pack：在安装完成后打包产物

常用组合示例：

:: 配置
python build-qt-ohos.py --exe_stage configure

:: 构建（使用配置中的并行任务数）
python build-qt-ohos.py --exe_stage build

:: 安装
python build-qt-ohos.py --exe_stage install

:: 打包
python build-qt-ohos.py --exe_stage install --with_pack

:: 一次性构建 + 打包
python build-qt-ohos.py --exe_stage all --with_pack

:: 查看当前构建信息
python build-qt-ohos.py --exe_stage print_build_info

:: 清理构建目录
python build-qt-ohos.py --exe_stage clean

:: 重置源码并重新应用补丁（会丢弃未提交修改）
python build-qt-ohos.py --reset_repo

配置说明

项目提供两级配置：

• 全局配置：configure.json（随仓库提供，不要直接改动默认值，除非知道自己在做什么）
• 用户配置：configure.json.user（首次交互式生成；如需修改，建议编辑此文件）

首次运行时，如果终端为交互模式，脚本会通过 questionary 弹出问答，生成 configure.json.user。

关键配置项（位于 config 段，用户配置会覆盖全局配置）：

• working_dir：工作目录，默认 ${pwd}/work（${pwd} 为本仓库根）
• perl（Windows 默认会自动下载到 ${pwd}/work/perl/bin）
• mingw（Windows 默认会自动下载到 ${pwd}/work/mingw/bin）
• ohos_sdk：OHOS SDK 解压目标目录，支持 ${ohos_version} 占位
• ohos_version：OHOS SDK 的 apiVersion（例如 15）
• build_type：release 或 debug
• build_ohos_abi：arm64-v8a、armeabi-v7a、x86_64
• build_qt_tag：支持 v5.15.12-lts-lgpl 或 v6.5.6-lts-lgpl
• clone_depth：源码浅克隆深度，建议 1（0 为完整克隆）
• jobs：并行编译任务数，建议不超过 CPU 物理核心数
• verbose：是否在 Qt configure 中开启 -verbose

仓库/依赖（来自 repositories 与 dependencies 段）：

• Qt 源码：https://gitcode.com/qtforohos/qt5.git
• Qt OHOS 补丁：https://gitcode.com/openharmony-sig/qt.git
• Perl/MinGW（Windows 预编译包，托管于 GitCode Releases）
• OHOS SDK 列表接口：https://repo.harmonyos.com/sdkmanager/v5/ohos/getSdkList

Qt configure 选项（来自 qt-config 段，脚本自动拼装）：

• -opensource -confirm-license（或 -commercial）
• -platform <win32-g++|linux-g++|macx-clang>（按宿主系统自动选择）
• -xplatform oh-clang（面向 OHOS 交叉编译）
• OpenGL：-opengl es2，可选附加 -opengles3
• 其他：-no-dbus、-disable-rpath、-nomake tests -nomake examples
• 每个受支持 Qt 版本还会附带相应 -skip 模块列表（详见 configure.json）

构建输出与打包

目录约定（均可从 print_build_info 查看）：

• Qt 源码目录：{working_dir}/qt5
• 构建目录：{working_dir}/qt5/build/{release|debug}
• 安装前缀（prefix）：{working_dir}/output/Qt{QtVer}-ohos{OHOSVer}-{ABI}
• 打包位置：{working_dir}/output/Qt{QtVer}_OHOS{OHOSVer}_{ABI}_{os}.{zip|tar.gz}
  • Windows 打包为 .zip
  • Linux/macOS 打包为 .tar.gz

示例：output/Qt5.15.12-ohos15-arm64-v8a/ 与 output/Qt5.15.12_OHOS15_arm64-v8a_windows.zip

常见问题与排查

• Git 不可用/未安装
  • 请先安装 Git，并确保 git --version 正常。
• Windows 自动安装 Perl/MinGW 失败
  • 检查网络与磁盘空间；删除 work/.temp 后重试 --env_check。
• OHOS SDK 下载失败或校验失败
  • 接口访问可能受网络限制；重试或更换网络。
• --reset_repo 会清除本地改动
  • 该命令执行 git reset --hard + git clean -fdx，请谨慎使用。
• 补丁应用失败
  • 脚本会先对主仓库与子模块执行 reset/clean，然后按版本目录（例如 patch/v5.15.12）依次 git apply。若仓库状态异常，建议先 --reset_repo 再 --init。
• Linux/macOS 缺少构建工具
  • Linux：sudo apt-get update && sudo apt-get install build-essential
  • macOS：从 App Store 安装 Xcode 或安装 Command Line Tools
• Windows 路径过长
  • 建议将 working_dir 配置到路径较短的位置，例如 D:\qt-work。

致谢

• 本项目依赖的python开源库：GitPython、Requests、Questionary、Rich、py7zr
• 本项目应用的的第三方python代码：ziptools

反馈与建议

Bug报告

请通过以下方式报告问题：

• OpenHarmony SIG Qt Issues：Qt OpenHarmony Issues

报告模板：

## Bug描述
简要描述遇到的问题

## 复现步骤
1. 步骤一
2. 步骤二
3. 步骤三

## 期望行为
描述期望的正确行为

## 实际行为
描述实际发生的行为

## 环境信息
- Qt版本：
- OpenHarmony版本：

## 附加信息
- 错误日志
- 截图（如适用）

功能建议

欢迎提交功能建议和改进建议：

BUG反馈

如果您发现该项目中的错误或有改进建议：

• 欢迎在OpenHarmony SIG Qt社区提交Issue，本项目仓库只做更新不处理Issue

---

附录

---

本项目将持续更新。

免责说明

• 使用 OpenHarmony SIG Qt 提供的补丁编译的SDK 产生的任何问题，请通过 OpenHarmony SIG Qt 社区寻求帮助
• 建议在生产环境使用前进行充分测试验证

最后更新: 2025年10月14日

适用版本: Qt for OpenHarmony (基于Qt 5.15) & OpenHarmony API 15 (5.0.3)+