ohos-ninja 是为 OpenHarmony 平台编译的 ninja 构建工具。本文档详细介绍如何在鸿蒙PC上安装和使用官方适配完成的 ninja 工具,包括 HNP 包的打包、安装和使用方法。
📋 目录
一、项目概述
1.1 ninja 工具简介
ninja 是一个小型构建系统,专注于速度。它是 Google 开发的一个构建工具,被广泛用于大型项目的构建,如 Chromium、LLVM 等。
核心特性:
- ⚡ 极速构建:专注于构建速度,启动开销极小
- 📝 简单配置:通过
build.ninja文件描述构建规则 - 🔧 跨平台:支持 Linux、macOS、Windows 等平台
- 🎯 专注构建:不做依赖分析,只负责执行构建命令
主要应用场景:
- 大型 C/C++ 项目的构建
- CMake 项目的后端构建工具
- 需要快速增量构建的项目
- 与 GN、CMake 等构建系统生成器配合使用

1.2 项目信息
| 项目信息 | 详情 |
|---|---|
| 项目名称 | ohos-ninja |
| 版本 | 1.13.1(官方适配版本) |
| 许可证 | Apache License 2.0 |
| 目标平台 | 鸿蒙PC (aarch64-linux-ohos) |
| 源码仓库 | https://github.com/ninja-build/ninja |
| 适配仓库 | https://github.com/Harmonybrew/ohos-ninja |
| 预构建包 | https://github.com/Harmonybrew/ohos-ninja/releases |
1.3 为什么需要 ohos-ninja?
在鸿蒙PC上进行开发时,我们经常需要:
- ✅ 构建大型项目:使用 CMake 等构建系统生成 ninja 文件后,需要 ninja 来执行构建
- ✅ 快速增量构建:ninja 的增量构建能力可以显著提升开发效率
- ✅ 与构建系统集成:许多现代构建系统(如 CMake、GN)都支持生成 ninja 文件
二、为什么需要 HNP 包
2.1 系统安全限制
重要说明: 在鸿蒙PC上,由于系统安全规格限制等原因,暂不支持通过"解压 + 配 PATH"的方式直接使用 tar.gz 包。
这意味着:
- ❌ 不能直接解压 tar.gz 包到任意目录
- ❌ 不能通过设置 PATH 环境变量来使用
- ✅ 必须打包成 HNP(HarmonyOS Native Package)格式才能正常使用
2.2 HNP 包的优势
HNP 包是鸿蒙PC的官方包管理格式,具有以下优势:
- ✅ 系统集成:与鸿蒙PC的包管理系统集成
- ✅ 安全可靠:通过官方工具安装,符合系统安全规范
- ✅ 易于管理:支持安装、卸载、更新等操作
- ✅ 路径规范:统一安装在
/data/service/hnp/目录下
2.3 其他平台的使用方式
在鸿蒙开发板上:
- 可以使用 hdc 推送 tar.gz 包
- 支持"解压 + 配 PATH"的方式
在鸿蒙容器中:
- 可以直接下载 tar.gz 包
- 支持"解压 + 配 PATH"的方式
三、HNP 包打包方法
3.1 准备工作
3.1.1 下载预构建包
首先,从 release 页面 下载官方适配完成的预构建包:
# 下载 ninja 预构建包
wget https://github.com/Harmonybrew/ohos-ninja/releases/download/1.13.1/ninja-1.13.1-ohos-arm64.tar.gz
3.1.2 解压并查看结构
# 解压 tar.gz 包
tar -zxf ninja-1.13.1-ohos-arm64.tar.gz
# 查看目录结构
tree ninja-1.13.1-ohos-arm64/
目录结构示例:
ninja-1.13.1-ohos-arm64/
├── bin/
│ └── ninja # ninja 可执行文件
└── COPYING # 许可证文件
3.2 创建 HNP 包配置
3.2.1 创建 hnp.json
在解压后的目录中创建 hnp.json 配置文件:
{
"type": "hnp-config",
"name": "ninja",
"version": "1.13.1",
"install": {
"links": [
{
"source": "bin/ninja",
"target": "ninja"
}
]
}
}
配置说明:
type: 固定为"hnp-config"name: 包名称(ninja)version: 版本号(1.13.1)install.links: 安装时的符号链接配置source: 源文件路径(相对于安装目录)target: 链接目标名称(命令名称)
3.2.2 准备安装目录结构
按照 HNP 包的路径规则,准备安装目录:
# HNP 包的路径规则:${HNP_PUBLIC_PATH}/<包名>.org/<包名>_<版本号>
# 例如:/data/service/hnp/ninja.org/ninja_1.13.1
export HNP_PUBLIC_PATH=/data/service/hnp
export NINJA_INSTALL_PATH=${HNP_PUBLIC_PATH}/ninja.org/ninja_1.13.1
# 创建安装目录
mkdir -p ${NINJA_INSTALL_PATH}
3.3 打包脚本
3.3.1 方法一:手动打包
创建打包脚本 pack_hnp.sh:
#!/bin/bash
set -e
# 配置变量
NINJA_VERSION="1.13.1"
TAR_FILE="ninja-${NINJA_VERSION}-ohos-arm64.tar.gz"
EXTRACT_DIR="ninja-${NINJA_VERSION}-ohos-arm64"
HNP_PUBLIC_PATH="/data/service/hnp"
NINJA_INSTALL_PATH="${HNP_PUBLIC_PATH}/ninja.org/ninja_${NINJA_VERSION}"
OUTPUT_DIR="output"
WORKDIR=$(pwd)
# 创建输出目录
mkdir -p ${OUTPUT_DIR}
# 解压 tar.gz 包
if [ ! -d "${EXTRACT_DIR}" ]; then
echo "解压 ${TAR_FILE}..."
tar -zxf ${TAR_FILE}
fi
# 创建安装目录
echo "创建安装目录..."
mkdir -p ${NINJA_INSTALL_PATH}/bin
# 复制文件
echo "复制文件..."
cp -r ${EXTRACT_DIR}/bin/* ${NINJA_INSTALL_PATH}/bin/
if [ -f "${EXTRACT_DIR}/COPYING" ]; then
cp ${EXTRACT_DIR}/COPYING ${NINJA_INSTALL_PATH}/
fi
# 创建 hnp.json
echo "创建 hnp.json..."
cat > ${NINJA_INSTALL_PATH}/hnp.json << 'EOF'
{
"type": "hnp-config",
"name": "ninja",
"version": "1.13.1",
"install": {
"links": [
{
"source": "bin/ninja",
"target": "ninja"
}
]
}
}
EOF
# 设置执行权限
chmod +x ${NINJA_INSTALL_PATH}/bin/ninja
# 使用 hnpcli 打包(如果可用)
if command -v hnpcli &> /dev/null; then
echo "使用 hnpcli 打包..."
hnpcli pack -i ${NINJA_INSTALL_PATH} -o ${OUTPUT_DIR}/
echo "HNP 包已生成: ${OUTPUT_DIR}/ninja.hnp"
else
echo "警告: 未找到 hnpcli 工具,跳过 HNP 包生成"
echo "请手动使用 hnpcli 打包:"
echo " hnpcli pack -i ${NINJA_INSTALL_PATH} -o ${OUTPUT_DIR}/"
fi
# 生成 tar.gz 包(备用)
echo "生成 tar.gz 包..."
cd ${HNP_PUBLIC_PATH}/ninja.org
tar -zcf ${WORKDIR}/${OUTPUT_DIR}/ohos_ninja_${NINJA_VERSION}.tar.gz ninja_${NINJA_VERSION}/
cd - > /dev/null
echo "打包完成!"
echo "输出文件:"
echo " - ${OUTPUT_DIR}/ninja.hnp (如果 hnpcli 可用)"
echo " - ${OUTPUT_DIR}/ohos_ninja_${NINJA_VERSION}.tar.gz"
3.4 验证打包结果
打包完成后,验证生成的文件:
# 检查 HNP 包
ls -lh output/ninja.hnp
# 检查 tar.gz 包
ls -lh output/ohos_ninja_1.13.1.tar.gz
# 验证安装目录结构
tree ${NINJA_INSTALL_PATH}/
预期的安装目录结构:
/data/service/hnp/ninja.org/ninja_1.13.1/
├── bin/
│ └── ninja # ninja 可执行文件
├── COPYING # 许可证文件(如果有)
└── hnp.json # HNP 配置文件
四、安装与使用
4.1 安装 HNP 包
手动安装(使用 tar.gz)
# 在鸿蒙PC上执行
# 1. 解压 tar.gz 包
tar -xzf ohos_ninja_1.13.1.tar.gz
# 2. 复制到安装目录
sudo cp -r ninja_1.13.1/* /data/service/hnp/ninja.org/ninja_1.13.1/
# 3. 设置执行权限
sudo chmod +x /data/service/hnp/ninja.org/ninja_1.13.1/bin/ninja
# 4. 创建符号链接(根据 hnp.json 配置)
# hnp 系统会自动处理 links 配置,但也可以手动创建
sudo ln -sf /data/service/hnp/ninja.org/ninja_1.13.1/bin/ninja /usr/local/bin/ninja
4.2 验证安装
# 检查 ninja 是否在 PATH 中
which ninja
# 检查版本
ninja --version
# 应该输出:1.13.1
4.3 配置 PATH(可选)
如果 ninja 命令不在 PATH 中,可以手动添加到 PATH:
# 临时添加到 PATH(当前会话有效)
export PATH=$PATH:/data/service/hnp/ninja.org/ninja_1.13.1/bin
# 永久添加到 PATH(添加到 ~/.bashrc 或 ~/.zshrc)
echo 'export PATH=$PATH:/data/service/hnp/ninja.org/ninja_1.13.1/bin' >> ~/.bashrc
source ~/.bashrc
五、使用示例
5.1 基本使用
5.1.1 查看帮助
ninja --help
5.1.2 查看版本
ninja --version
# 输出: 1.13.1
5.2 与 CMake 配合使用
5.2.1 生成 ninja 文件
# 使用 CMake 生成 ninja 构建文件
mkdir build
cd build
cmake -G Ninja ..
# 这会生成 build.ninja 文件
5.2.2 执行构建
# 在 build 目录中执行构建
ninja
# 或者指定构建文件
ninja -f build.ninja
# 并行构建(使用 4 个线程)
ninja -j4
5.2.3 清理构建
# 清理构建产物
ninja -t clean
5.3 与 GN 配合使用
# 使用 GN 生成 ninja 文件
gn gen out/Default
# 使用 ninja 构建
ninja -C out/Default
5.4 高级用法
5.4.1 查看构建图
# 生成构建图(需要 graphviz)
ninja -t graph | dot -Tpng -o graph.png
5.4.2 查看构建目标
# 列出所有构建目标
ninja -t targets all
# 列出所有规则
ninja -t rules
5.4.3 调试构建
# 详细输出
ninja -v
# 解释为什么需要重新构建某个目标
ninja -t explain
5.5 实际应用场景
场景 1:构建 OpenHarmony 项目
# 在 OpenHarmony 项目中使用 ninja
cd /path/to/openharmony
./build.sh --product-name rk3568 --build-target build_ohos
# 构建系统会使用 ninja 来执行实际构建
场景 2:构建自定义 C++ 项目
# 创建 CMakeLists.txt
cat > CMakeLists.txt << 'EOF'
cmake_minimum_required(VERSION 3.10)
project(MyProject)
add_executable(hello hello.cpp)
EOF
# 生成 ninja 文件并构建
mkdir build && cd build
cmake -G Ninja ..
ninja
六、常见问题
Q1: 为什么不能直接使用 tar.gz 包?
A: 由于鸿蒙PC的系统安全规格限制,不允许通过"解压 + 配 PATH"的方式直接使用软件包。必须使用 HNP 包格式,通过官方包管理工具安装。
Q2: 如何获取 hnpcli 工具?
A: hnpcli 是鸿蒙PC的包管理工具,通常包含在 OHOS SDK 中。你可以:
Q3: 安装后找不到 ninja 命令?
A: 检查以下几点:
- 确认安装路径是否正确:
/data/service/hnp/ninja.org/ninja_1.13.1/bin/ninja - 检查 PATH 环境变量是否包含该路径
- 检查 hnp.json 中的 links 配置是否正确
- 尝试手动创建符号链接
Q4: 如何卸载 ninja?
A: 手动卸载:
# 删除安装目录
sudo rm -rf /data/service/hnp/ninja.org/ninja_1.13.1
# 删除符号链接
sudo rm -f /usr/local/bin/ninja
Q5: 可以在开发板上使用 tar.gz 包吗?
A: 可以。在鸿蒙开发板上,可以使用 hdc 推送 tar.gz 包,然后解压使用:
hdc file send ninja-1.13.1-ohos-arm64.tar.gz /data
hdc shell
cd /data
tar -zxf ninja-1.13.1-ohos-arm64.tar.gz
export PATH=$PATH:/data/ninja-1.13.1-ohos-arm64/bin
Q6: 如何更新到新版本?
A:
- 下载新版本的预构建包
- 按照打包步骤重新打包
- 卸载旧版本:
hnp uninstall ninja - 安装新版本:
hnp install ninja.hnp
Q7: ninja 构建失败怎么办?
A: 检查以下几点:
- 确认 build.ninja 文件是否正确生成
- 检查依赖项是否都已安装
- 查看详细错误信息:
ninja -v - 清理后重新构建:
ninja -t clean && ninja
七、总结与最佳实践
7.1 安装最佳实践
- 使用 HNP 包:始终使用 HNP 包格式在鸿蒙PC上安装
- 版本管理:明确指定版本号,避免版本冲突
- 路径规范:遵循 HNP 包的路径规范:
/data/service/hnp/<包名>.org/<包名>_<版本号>
7.2 使用最佳实践
- 与构建系统配合:ninja 通常与 CMake、GN 等构建系统生成器配合使用
- 并行构建:使用
-j参数指定并行数,提升构建速度 - 增量构建:ninja 会自动进行增量构建,只重新构建变更的部分
7.3 性能优化
- 合理设置并行数:
ninja -j$(nproc)使用所有 CPU 核心 - 使用构建缓存:对于大型项目,考虑使用 ccache 等缓存工具
- SSD 存储:将构建目录放在 SSD 上可以显著提升构建速度
7.4 故障排查
- 查看构建日志:使用
-v参数查看详细构建信息 - 检查依赖:使用
ninja -t explain查看为什么需要重新构建 - 清理重建:遇到问题时,尝试
ninja -t clean后重新构建
📎 附录
A. 📁 文件清单
📦 预构建包:
ninja-1.13.1-ohos-arm64.tar.gz- 官方适配完成的预构建包
📝 配置文件:
hnp.json- HNP 包配置文件
📦 生成文件:
ninja.hnp- HNP 格式安装包ohos_ninja_1.13.1.tar.gz- tar.gz 格式发布包
B. 💻 常用命令
# 打包命令
./pack_hnp.sh
# 安装命令
hnp install ninja.hnp
# 验证安装
ninja --version
# 使用 ninja 构建
ninja -j$(nproc)
# 清理构建
ninja -t clean
C. 📌 版本信息
- 📁 ninja 版本: 1.13.1
- 📅 适配日期: 2025-12-15
- 🎯 目标平台: aarch64-linux-ohos
- 🔧 构建系统: CMake
- 📦 包格式: HNP (HarmonyOS Native Package)=
🎉 结语
本文档详细介绍了如何在鸿蒙PC上安装和使用官方适配完成的 ninja 构建工具。通过将预构建的 tar.gz 包打包成 HNP 格式,我们可以在鸿蒙PC上安全、规范地使用 ninja 工具。
希望本文档能够帮助开发者:
- 📦 理解 HNP 包的必要性和打包方法
- 🔧 掌握 ninja 在鸿蒙PC上的安装和使用
- 📚 学习与 CMake、GN 等构建系统的配合使用
- 💻 提升大型项目的构建效率
💬 如有问题或建议,欢迎反馈!
660

被折叠的 条评论
为什么被折叠?



