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

📋 目录

• 一、项目概述
• 二、为什么需要 HNP 包
• 三、HNP 包打包方法
• 四、安装与使用
• 五、使用示例
• 六、常见问题
• 七、总结与最佳实践
• 八、参考资料

---

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

一、项目概述

1.1 CMake 工具简介

CMake（Cross-platform Make）是一个开源的跨平台构建系统生成器，用于管理软件构建过程。它使用独立于编译器的配置文件来控制软件编译过程。

核心特性：

• 🔧 跨平台构建：支持 Windows、Linux、macOS 等多种平台
• 📝 简单配置：通过 CMakeLists.txt 文件描述构建规则
• ⚡ 高效构建：生成原生构建系统（如 Makefile、Ninja）
• 🎯 依赖管理：强大的依赖查找和管理能力
• 🔄 模块化：丰富的模块和工具支持

主要应用场景：

• C/C++ 项目的构建管理
• 跨平台项目构建配置
• 大型项目的依赖管理
• 与 IDE 集成（如 CLion、Qt Creator）
• 自动化构建流程
  

1.2 项目信息

项目信息	详情
项目名称	ohos-cmake
版本	4.1.2（CMake 官方版本）
许可证	Apache License 2.0
目标平台	鸿蒙PC (aarch64-linux-ohos)
源码仓库	https://github.com/Kitware/CMake
适配仓库	https://github.com/Harmonybrew/ohos-cmake
预构建包	https://github.com/Harmonybrew/ohos-cmake/releases
编译方式	交叉编译（Cross Compilation）
依赖项	OpenSSL 3.0.9

1.3 CMake 构建流程

CMake 的典型构建流程包括：

1. 配置阶段：读取 CMakeLists.txt，生成构建系统文件
2. 生成阶段：创建 Makefile 或 Ninja 文件
3. 构建阶段：使用生成的构建系统编译项目

CMakeLists.txt → cmake configure → 构建系统文件 → 编译 → 可执行文件

1.4 为什么需要 ohos-cmake？

在鸿蒙PC上进行开发时，我们经常需要：

1. ✅ 构建 C/C++ 项目：管理复杂的 C/C++ 项目构建过程
2. ✅ 跨平台开发：使用统一的构建配置支持多平台
3. ✅ 依赖管理：自动查找和管理项目依赖
4. ✅ 与 IDE 集成：支持现代 IDE 的 CMake 项目

---

二、为什么需要 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 页面 下载官方适配完成的预构建包：

# 下载 cmake 预构建包
wget https://github.com/Harmonybrew/ohos-cmake/releases/download/4.1.2/cmake-4.1.2-ohos-arm64.tar.gz

3.1.2 解压并查看结构

# 解压 tar.gz 包
tar -zxf cmake-4.1.2-ohos-arm64.tar.gz

# 查看目录结构
tree cmake-4.1.2-ohos-arm64/

目录结构示例：

cmake-4.1.2-ohos-arm64/
├── bin/
│   ├── cmake          # cmake 可执行文件
│   ├── cpack          # cpack 打包工具
│   └── ctest          # ctest 测试工具
├── share/
│   └── cmake-4.1/     # CMake 模块和配置文件
├── licenses.txt       # 许可证文件（包含 CMake 和 OpenSSL）
└── ...

3.2 创建 HNP 包配置

3.2.1 创建 hnp.json

在解压后的目录中创建 hnp.json 配置文件：

{
    "type": "hnp-config",
    "name": "cmake",
    "version": "4.1.2",
    "install": {
        "links": [
            {
                "source": "bin/cmake",
                "target": "cmake"
            },
            {
                "source": "bin/cpack",
                "target": "cpack"
            },
            {
                "source": "bin/ctest",
                "target": "ctest"
            }
        ]
    }
}

配置说明：

• type: 固定为 "hnp-config"
• name: 包名称（cmake）
• version: 版本号（4.1.2）
• install.links: 安装时的符号链接配置
  • cmake: 主要的构建工具
  • cpack: 打包工具
  • ctest: 测试工具

3.2.2 准备安装目录结构

按照 HNP 包的路径规则，准备安装目录：

# HNP 包的路径规则：${HNP_PUBLIC_PATH}/<包名>.org/<包名>_<版本号>
# 例如：/data/service/hnp/cmake.org/cmake_4.1.2

export HNP_PUBLIC_PATH=/data/service/hnp
export CMAKE_INSTALL_PATH=${HNP_PUBLIC_PATH}/cmake.org/cmake_4.1.2

# 创建安装目录
mkdir -p ${CMAKE_INSTALL_PATH}

3.3 打包脚本

3.3.1 方法一：手动打包

创建打包脚本 pack_hnp.sh：

#!/bin/bash
set -e

# 配置变量
CMAKE_VERSION="4.1.2"
TAR_FILE="cmake-${CMAKE_VERSION}-ohos-arm64.tar.gz"
EXTRACT_DIR="cmake-${CMAKE_VERSION}-ohos-arm64"
HNP_PUBLIC_PATH="/data/service/hnp"
CMAKE_INSTALL_PATH="${HNP_PUBLIC_PATH}/cmake.org/cmake_${CMAKE_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 ${CMAKE_INSTALL_PATH}

# 复制文件
echo "复制文件..."
cp -r ${EXTRACT_DIR}/* ${CMAKE_INSTALL_PATH}/

# 创建 hnp.json
echo "创建 hnp.json..."
cat > ${CMAKE_INSTALL_PATH}/hnp.json << 'EOF'
{
    "type": "hnp-config",
    "name": "cmake",
    "version": "4.1.2",
    "install": {
        "links": [
            {
                "source": "bin/cmake",
                "target": "cmake"
            },
            {
                "source": "bin/cpack",
                "target": "cpack"
            },
            {
                "source": "bin/ctest",
                "target": "ctest"
            }
        ]
    }
}
EOF

# 设置执行权限
chmod +x ${CMAKE_INSTALL_PATH}/bin/*

# 使用 hnpcli 打包（如果可用）
if command -v hnpcli &> /dev/null; then
    echo "使用 hnpcli 打包..."
    hnpcli pack -i ${CMAKE_INSTALL_PATH} -o ${OUTPUT_DIR}/
    echo "HNP 包已生成: ${OUTPUT_DIR}/cmake.hnp"
else
    echo "警告: 未找到 hnpcli 工具，跳过 HNP 包生成"
    echo "请手动使用 hnpcli 打包:"
    echo "  hnpcli pack -i ${CMAKE_INSTALL_PATH} -o ${OUTPUT_DIR}/"
fi

# 生成 tar.gz 包（备用）
echo "生成 tar.gz 包..."
cd ${HNP_PUBLIC_PATH}/cmake.org
tar -zcf ${WORKDIR}/${OUTPUT_DIR}/ohos_cmake_${CMAKE_VERSION}.tar.gz cmake_${CMAKE_VERSION}/
cd - > /dev/null

echo "打包完成！"
echo "输出文件："
echo "  - ${OUTPUT_DIR}/cmake.hnp (如果 hnpcli 可用)"
echo "  - ${OUTPUT_DIR}/ohos_cmake_${CMAKE_VERSION}.tar.gz"

3.4 验证打包结果

打包完成后，验证生成的文件：

# 检查 HNP 包
ls -lh output/cmake.hnp

# 检查 tar.gz 包
ls -lh output/ohos_cmake_4.1.2.tar.gz

# 验证安装目录结构
tree ${CMAKE_INSTALL_PATH}/

预期的安装目录结构：

/data/service/hnp/cmake.org/cmake_4.1.2/
├── bin/
│   ├── cmake
│   ├── cpack
│   └── ctest
├── share/
│   └── cmake-4.1/
├── licenses.txt
└── hnp.json

---

四、安装与使用

4.1 安装 HNP 包

手动安装（使用 tar.gz）

# 在鸿蒙PC上执行

# 1. 解压 tar.gz 包
tar -xzf ohos_cmake_4.1.2.tar.gz

# 2. 复制到安装目录
sudo cp -r cmake_4.1.2/* /data/service/hnp/cmake.org/cmake_4.1.2/

# 3. 设置执行权限
sudo chmod +x /data/service/hnp/cmake.org/cmake_4.1.2/bin/*

# 4. 创建符号链接（根据 hnp.json 配置）
# hnp 系统会自动处理 links 配置，但也可以手动创建
sudo ln -sf /data/service/hnp/cmake.org/cmake_4.1.2/bin/cmake /usr/local/bin/cmake
sudo ln -sf /data/service/hnp/cmake.org/cmake_4.1.2/bin/cpack /usr/local/bin/cpack
sudo ln -sf /data/service/hnp/cmake.org/cmake_4.1.2/bin/ctest /usr/local/bin/ctest

4.2 验证安装

# 检查 cmake 是否可用
cmake --version

# 应该显示 CMake 的版本信息
# cmake version 4.1.2

4.3 使用 CMake

安装完成后，就可以使用 CMake 来构建项目了：

# 基本使用流程
mkdir build
cd build
cmake ..
make

# 或者使用 Ninja 作为后端
cmake -GNinja ..
ninja

---

五、使用示例

5.1 基本 CMake 项目

创建一个简单的 CMake 项目：

CMakeLists.txt:

cmake_minimum_required(VERSION 3.10)
project(HelloWorld)

add_executable(hello main.cpp)

main.cpp:

#include <iostream>

int main() {
    std::cout << "Hello, World!" << std::endl;
    return 0;
}

构建步骤：

mkdir build
cd build
cmake ..
make
./hello

5.2 使用外部库

CMakeLists.txt:

cmake_minimum_required(VERSION 3.10)
project(MyProject)

find_package(OpenSSL REQUIRED)

add_executable(myapp main.cpp)
target_link_libraries(myapp OpenSSL::SSL OpenSSL::Crypto)

5.3 配置构建选项

# 指定构建类型
cmake -DCMAKE_BUILD_TYPE=Release ..

# 指定安装路径
cmake -DCMAKE_INSTALL_PREFIX=/usr/local ..

# 传递自定义变量
cmake -DMY_VAR=value ..

5.4 使用 Ninja 后端

# 使用 Ninja 作为构建后端（更快）
cmake -GNinja ..
ninja

# 或者
cmake .. -G Ninja
ninja

5.5 交叉编译配置

# 设置交叉编译工具链
cmake -DCMAKE_TOOLCHAIN_FILE=toolchain.cmake ..

# 或者直接指定编译器
cmake -DCMAKE_C_COMPILER=aarch64-linux-ohos-clang \
      -DCMAKE_CXX_COMPILER=aarch64-linux-ohos-clang++ ..

---

六、常见问题

6.1 OpenSSL 依赖问题

问题： CMake 需要 OpenSSL，但找不到？

解决方案：

CMake 在构建时已经静态链接了 OpenSSL，运行时不需要额外的 OpenSSL 库。如果遇到问题，检查：

# 检查 CMake 的 OpenSSL 配置
cmake --version

# 查看 CMake 的模块路径
cmake --system-information | grep CMAKE_MODULE_PATH

6.2 CPU Affinity 补丁

问题： 为什么需要禁用 CPU affinity？

回答：

OpenHarmony 不支持 pthread_getaffinity_np 和 pthread_setaffinity_np 接口，因此在构建 CMake 时需要应用补丁来禁用这些功能。预构建包已经应用了这个补丁。

如果从源码构建，需要应用 0001-disable-cpu-affinity.patch 补丁。

6.3 权限问题

问题： 安装后无法执行 cmake 命令？

解决方案：

# 检查文件权限
ls -l /data/service/hnp/cmake.org/cmake_4.1.2/bin/cmake

# 设置执行权限
chmod +x /data/service/hnp/cmake.org/cmake_4.1.2/bin/cmake

# 检查符号链接
ls -l /usr/local/bin/cmake

6.4 构建相关问题

问题： 如何从源码构建 CMake？

回答：

参考项目 README 中的构建说明，需要在 Linux x64 服务器上运行 build.sh 脚本进行交叉编译：

# 在 Ubuntu 24.04 x64 上
sudo apt update && sudo apt install -y build-essential unzip cmake
./build.sh

构建过程会：

1. 下载 OpenHarmony SDK
2. 设置交叉编译环境
3. 编译 OpenSSL（CMake 的依赖）
4. 下载并编译 CMake 源码（应用 CPU affinity 补丁）
5. 生成预构建包

6.5 CMake 版本问题

问题： 项目要求特定版本的 CMake？

解决方案：

# 检查当前版本
cmake --version

# 如果版本不匹配，需要安装对应版本
# 或者使用 CMake 的版本要求检查
cmake_minimum_required(VERSION 3.10)

---

七、总结与最佳实践

7.1 使用建议

1. 优先使用 HNP 包：在鸿蒙PC上，优先使用 HNP 包安装，符合系统安全规范。
2. 选择合适的构建后端：对于大型项目，使用 Ninja 后端可以显著提升构建速度。
3. 管理依赖：使用 find_package 和 FetchContent 来管理项目依赖。
4. 版本管理：在 CMakeLists.txt 中指定 cmake_minimum_required，确保构建环境一致。

7.2 性能优化

1. 使用 Ninja 后端：Ninja 比 Make 更快，特别是对于大型项目。
2. 并行构建：使用 -j 选项（Make）或 -j 选项（Ninja）进行并行构建。
3. 增量构建：CMake 支持增量构建，只重新编译修改过的文件。
4. 缓存配置：使用 ccache 可以加速重复构建。

7.3 最佳实践

1. 项目结构：遵循标准的 CMake 项目结构，使用 build 目录进行构建。
2. 配置分离：将构建配置和源码分离，使用外部构建目录。
3. 模块化设计：将大型项目拆分为多个 CMake 子项目。
4. 文档化：在 CMakeLists.txt 中添加注释，说明配置选项和依赖关系。

---