命令行ninja在鸿蒙PC上的使用方法-智慧文博士

ohos-ninja是为 OpenHarmony 平台编译的 ninja 构建工具。本文档详细介绍如何在鸿蒙PC上安装和使用官方适配完成的 ninja 工具，包括 HNP 包的打包、安装和使用方法。

📋 目录

一、项目概述
二、为什么需要 HNP 包
三、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 预构建包wgethttps://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.1exportHNP_PUBLIC_PATH=/data/service/hnpexportNINJA_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/bashset-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}"];thenecho"解压${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"];thencp${EXTRACT_DIR}/COPYING${NINJA_INSTALL_PATH}/fi# 创建 hnp.jsonecho"创建 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 打包（如果可用）ifcommand-v hnpcli&>/dev/null;thenecho"使用 hnpcli 打包..."hnpcli pack -i${NINJA_INSTALL_PATH}-o${OUTPUT_DIR}/echo"HNP 包已生成:${OUTPUT_DIR}/ninja.hnp"elseecho"警告: 未找到 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.orgtar-zcf${WORKDIR}/${OUTPUT_DIR}/ohos_ninja_${NINJA_VERSION}.tar.gz ninja_${NINJA_VERSION}/cd->/dev/nullecho"打包完成！"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. 复制到安装目录sudocp-r ninja_1.13.1/* /data/service/hnp/ninja.org/ninja_1.13.1/# 3. 设置执行权限sudochmod+x /data/service/hnp/ninja.org/ninja_1.13.1/bin/ninja# 4. 创建符号链接（根据 hnp.json 配置）# hnp 系统会自动处理 links 配置，但也可以手动创建sudoln-sf /data/service/hnp/ninja.org/ninja_1.13.1/bin/ninja /usr/local/bin/ninja

4.2 验证安装

# 检查 ninja 是否在 PATH 中whichninja# 检查版本ninja --version# 应该输出：1.13.1

4.3 配置 PATH（可选）

如果 ninja 命令不在 PATH 中，可以手动添加到 PATH：

# 临时添加到 PATH（当前会话有效）exportPATH=$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'>>~/.bashrcsource~/.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 构建文件mkdirbuildcdbuild 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 项目中使用 ninjacd/path/to/openharmony ./build.sh --product-name rk3568 --build-target build_ohos# 构建系统会使用 ninja 来执行实际构建

场景 2：构建自定义 C++ 项目

# 创建 CMakeLists.txtcat>CMakeLists.txt<<'EOF' cmake_minimum_required(VERSION 3.10) project(MyProject) add_executable(hello hello.cpp) EOF# 生成 ninja 文件并构建mkdirbuild&&cdbuild cmake -G Ninja..ninja

六、常见问题

Q1: 为什么不能直接使用 tar.gz 包？

A:由于鸿蒙PC的系统安全规格限制，不允许通过"解压 + 配 PATH"的方式直接使用软件包。必须使用 HNP 包格式，通过官方包管理工具安装。

Q2: 如何获取 hnpcli 工具？

A:hnpcli 是鸿蒙PC的包管理工具，通常包含在 OHOS SDK 中。你可以：

从 OHOS SDK 下载
参考 DevBox 项目获取构建工具

Q3: 安装后找不到 ninja 命令？

A:检查以下几点：

确认安装路径是否正确：/data/service/hnp/ninja.org/ninja_1.13.1/bin/ninja
检查 PATH 环境变量是否包含该路径
检查 hnp.json 中的 links 配置是否正确
尝试手动创建符号链接

Q4: 如何卸载 ninja？

A:手动卸载：

# 删除安装目录sudorm-rf /data/service/hnp/ninja.org/ninja_1.13.1# 删除符号链接sudorm-f /usr/local/bin/ninja

Q5: 可以在开发板上使用 tar.gz 包吗？

A:可以。在鸿蒙开发板上，可以使用 hdc 推送 tar.gz 包，然后解压使用：

hdcfilesend ninja-1.13.1-ohos-arm64.tar.gz /data hdc shellcd/datatar-zxf ninja-1.13.1-ohos-arm64.tar.gzexportPATH=$PATH:/data/ninja-1.13.1-ohos-arm64/bin

Q6: 如何更新到新版本？

下载新版本的预构建包
按照打包步骤重新打包
卸载旧版本：hnp uninstall ninja
安装新版本：hnp install ninja.hnp

Q7: ninja 构建失败怎么办？