企业官网建设流程全解析

CANN Runtime 开源仓库实战指南：环境部署、源码构建与单元测试全流程解析

【免费下载链接】runtime本项目提供CANN运行时组件和维测功能组件。项目地址: https://gitcode.com/cann/runtime

本指南以 CANN / runtime 开源仓库为对象，系统讲解其核心组成（Ascend NPU 运行时编程接口与核心实现、性能采集/精度调试/日志等维测组件）、环境部署步骤、源码构建流程以及基于 googletest 的单元测试（UT）验证方法。读完本文，你将能够独立完成从基础依赖安装、CANN 软件包部署、build.sh编译 runtime 包到tests/build_ut.sh运行模块化 UT 用例的完整闭环，并理解每一步背后的源码依据。

项目定位与核心能力

本仓库提供CANN 运行时组件和维测功能组件两部分能力，是整个 CANN 软件栈中面向昇腾 AI 处理器的底层运行时基座。

• Runtime 组件：提供 Ascend NPU 运行时用户编程接口和运行时核心实现，涵盖设备管理、流（Stream）管理、Event 管理、内存管理、任务调度等功能。其对外 API 头文件集中在 include/external/acl（如acl_rt.h、acl_rt_api.h、acl_base.h等），核心实现位于 src/runtime（api、core、feature等子目录），另有 src/acl 承载 aclrt、aclrt_c、aclrt_impl 等对外 API 封装。
• 维测功能组件：面向性能调优、精度调试与故障诊断，包含三个核心模块（源码均在 src/dfx 下）：
  • 性能调优（msprof）：采集和分析运行在昇腾 AI 处理器 SoC NPU IP 加速器上 AI 任务各运行阶段的关键性能指标，依据输出的性能数据快速定位软、硬件性能瓶颈，提升 AI 任务性能分析的效率；
  • 精度调试（adump）：支持 Dump 单算子或模型（每一层算子）的输入/输出数据，用于与指定算子或模型对比定位精度问题；也支持在运行时异常时 Dump 异常算子的输入/输出数据、Workspace 信息、Tiling 信息，用于分析 AI Core Error 问题；
  • 日志（log）：提供记录进程执行过程信息的能力，日志接口支持进程打印与落盘日志，便于系统故障诊断与问题定位。该模块下的msnpureport为命令行工具，支持导出 device 侧日志、查询与设置 device 侧状态等功能。

从源码结构看，仓库还包含mmpa（跨平台接口抽象）、platform（平台信息管理）、queue_schedule（队列调度）、aicpu_sched（AI CPU 调度）、tsd（TSD 客户端）等模块，共同支撑运行时能力的完整闭环。

版本配套与发布节奏

本项目源码会跟随 CANN 软件版本发布，CANN 软件版本与本项目标签的对应关系以release仓库中的版本说明为准。当前仓库version.cmake中声明了软件包版本：

set_cann_package(npu-runtime VERSION "9.2.0")

为确保源码定制开发顺利进行，请选择配套的 CANN 版本与 Gitcode 标签源码；直接使用master分支可能存在版本不匹配的风险。仓库动态方面，2025 年 12 月 runtime 项目首次上线，2026 年 4 月起支持 Ascend 950PR / Ascend 950DT 芯片，并持续增强 AclGraph 功能、优化文档结构。

仓库目录结构解读

README 给出了关键目录组织，结合仓库实际内容整理如下：

环境部署：从零搭建昇腾开发环境

基础依赖及版本要求

本项目基础依赖如下（注意版本要求）：

• python >= 3.7.0（python 3.7 / python3.8 官方已 EOL，CANN 将于 2027 年 3 月停止支持，请升级到 >= 3.9.0）
• pip3
• gcc >= 7.3.0, <= 13
• cmake >= 3.16.0
• ccache
• autoconf
• gperf
• libtool
• make
• libc6-dev / glibc-devel

Ubuntu/Debian 操作系统安装命令示例：

sudo apt install python3 python3-pip python3-dev gcc-9 g++-9 libc6-dev cmake ccache autoconf gperf libtool libtool-bin make

CentOS/EulerOS 操作系统安装命令示例：

sudo yum install python3 python3-pip python3-devel gcc gcc-c++ glibc-devel cmake ccache autoconf gperf libtool make

手动安装 CANN 软件包

对于有昇腾设备的开发者，手动搭建昇腾环境分为两种场景：

场景 1：体验 master 版本能力或基于 master 版本进行开发

1. 安装驱动与固件（可选，仅运行 样例 依赖）：若仅编译 runtime 包可跳过本步骤；运行 runtime 样例时须安装驱动与固件，具体参考《CANN 软件安装指南》中"准备软件包"和"安装 NPU 驱动和固件"章节。
2. 安装 CANN 包：选择最新时间版本，并根据产品型号和环境架构下载对应包。

• 安装 CANN toolkit 包：

# 确保安装包具有可执行权限 chmod +x Ascend-cann-toolkit_${cann_version}_linux-${arch}.run # 安装命令 ./Ascend-cann-toolkit_${cann_version}_linux-${arch}.run --install --install-path=${install_path}

参数说明：

• ${cann_version}：CANN 包版本号；

• ${arch}：CPU 架构，如aarch64、x86_64；

• ${install_path}：指定安装路径，需要与 Toolkit 包安装在相同路径，root 用户默认安装在/usr/local/Ascend目录。

• 安装 CANN ops 算子包（可选，仅运行 样例 依赖）：

# 确保安装包具有可执行权限 chmod +x Ascend-cann-${soc_name}-ops_${cann_version}_linux-${arch}.run # 安装命令 ./Ascend-cann-${soc_name}-ops_${cann_version}_linux-${arch}.run --install --install-path=${install_path}

其中${soc_name}表示 NPU 型号名称，各产品的对应关系如下：

场景 2：体验已发布版本能力或基于已发布版本进行开发

访问 CANN 官网下载中心，选择发布版本（仅支持CANN 8.5.0 及后续版本）、产品型号和环境架构，参考 CANN 快速安装指导完成安装。

环境验证

安装完 CANN 包后，需验证环境和驱动是否正常。

检查 NPU 设备：运行npu-smi，若能正常显示设备信息，则驱动正常。

npu-smi info

检查 CANN 版本：查看安装信息文件中的version字段（默认路径安装，${arch}表示 CPU 架构，即aarch64或x86_64）。

# 查看 CANN Toolkit 开发套件包的 version 字段提供的版本信息 cat /usr/local/Ascend/cann/${arch}-linux/ascend_toolkit_install.info # 查看 CANN ops 包版本信息 cat /usr/local/Ascend/cann/${arch}-linux/ascend_ops_install.info

源码构建 runtime 包

本项目支持源码构建，编译运行前需先完成上述环境部署。源码构建可选择本机源码构建（下载源码 → 环境变量配置 → 编译 runtime 包）或Docker 源码构建（在容器内完成，参考.devcontainer目录说明）。

下载源码

# 下载项目源码，以 master 分支为例 git clone https://gitcode.com/cann/runtime.git

环境变量配置

按需选择合适的命令使环境变量生效：

# 默认路径安装，以 root 用户为例（非 root 用户，将 /usr/local 替换为 ${HOME}） source /usr/local/Ascend/cann/set_env.sh # 指定路径安装 source ${install_path}/cann/set_env.sh

编译 runtime 包

若编译环境可以访问网络，编译过程中将自动下载开源第三方软件：

bash build.sh

若编译环境无法访问网络，可直接调用脚本获取开源组件压缩包，脚本会自动下载至当前新建的third_party目录中：

python download_3rd_party.py

下载完成后使用如下命令编译：

bash build.sh --cann_3rd_lib_path=third_party

更多编译参数可通过bash build.sh -h查看。结合 build.sh 源码，实际支持的参数包括：

编译完成后，会在build_out目录下生成cann-npu-runtime_${version}_linux-${arch}.run软件包。其中${version}表示版本号，${arch}表示操作系统架构（x86_64或aarch64）。

开源第三方软件依赖

runtime 编译时依赖的开源第三方软件如下（若从其他地址下载，请确保版本号一致）：

注意：如果您从其他地址下载，请确保版本号一致。

安装 runtime 包

执行如下命令安装编译生成的 runtime 软件包：

cd build_out; ./cann-npu-runtime_${version}_linux-${arch}.run --full --install-path=${install_path}

• ${version}：run 包版本号；
• ${arch}：CPU 架构，如aarch64、x86_64；
• ${install_path}：指定安装路径，可选，默认安装在/usr/local/Ascend目录。

安装完成之后，用户编译生成的 Runtime 软件包会替换已安装 CANN 开发套件包中的 Runtime 相关软件，实现自研运行时的覆盖式部署。

本地验证：UT 单元测试

编译完成后，可通过单元测试（UT, Unit Testing）验证项目功能是否正常。执行 UT 用例依赖 googletest 单元测试框架，其详细用例筛选用法可参考 googletest 官方文档（--gtest_filter等高级选项）。

编译执行 UT 测试用例

bash tests/build_ut.sh --ut=acl --target=ascendcl_utest -c --cann_3rd_lib_path=${your_3rd_party_path}

其中${your_3rd_party_path}必须为绝对路径。

指定测试模块（--ut）

runtime仓中的 UT 用例按模块分类归档在 tests/ut 的不同目录下，所有模块名称与用例路径的映射关系定义在 tests/build_ut.sh 的ut_path_map中：

指定测试目标文件（--target）

通过--target指定待测用例编译出的具体目标文件，可同时指定多个（用空格分隔）。各模块包含的目标文件可从对应模块的CMakeLists.txt中查看；同时ut_name_map提供了每个模块的默认目标：

例如对于acl模块，从 tests/ut/acl/CMakeLists.txt 中的add_custom_target可看出编译目标命名为ascendcl_utest，并包含ascendcl_c_utest和ascendcl_cpp_utest两个目标文件；指定--target=ascendcl_utest即编译执行acl模块中的所有用例，也可指定具体的目标文件精确执行。

其他编译参数

• -c/--cov：获取覆盖率（无需时可省略）。需先安装lcov（Ubuntu/Debian：sudo apt install lcov；openEuler：sudo dnf install lcov）；若因版本差异报错，请按提示调整脚本参数。从 tests/build_ut.sh 可见，覆盖率统计基于lcov -c收集数据并调用genhtml生成报告到cov/目录；
• --asan：启用 AddressSanitizer 进行内存错误检测（无需时可省略）。AddressSanitizer 通常已集成在 gcc 中；如需单独安装，请确保与 gcc 版本兼容（如 gcc 9.5.0 匹配 libasan6 版本）。脚本会校验libasan.so、libubsan.so、libtsan.so是否存在；
• --ut_timeout=<SECONDS>：为每个 UT 可执行文件设置超时时间（默认 0 表示不限制），超时返回 124/137 时判定用例超时失败；
• --cann_3rd_lib_path：指定第三方依赖路径，联网环境可省略；
• -j<N>：编译线程数，默认 8。

更详细的编译命令参数可通过bash tests/build_ut.sh -h查看。UT 用例编译的中间产物及产物位于output和build下，如需清除历史编译记录：

rm -rf output/ build/

用例筛选与报告输出

脚本通过find遍历目标目录下的可执行文件，逐个以--gtest_output=xml:${report_dir}/${filename}.xml方式执行，XML 报告输出到output/report/ut/。如需筛选运行部分用例，可结合 googletest 的--gtest_filter机制在可执行文件级别进行筛选。

从样例到进阶学习

完成环境部署与源码构建后，可参考 example 目录下的样例进一步了解本仓。样例按主题分层组织：

• 0_quickstart：快速入门（hello_cann、错误处理、系统信息、跨版本、自定义算子启动、运行时生命周期回调）；
• 1_basic_features：基础特性（context、device、event、memory、stream 各场景）；
• 2_advanced_features：进阶特性（内置任务、callback、ipcevent、kernel 启动、label、model_ri、notify、tdt_channel、tdt_queue）；
• 3_memory_advanced：内存进阶（自定义分配器、cache 维护、host_register、managed_memory）；
• 4_reliability：可靠性（错误恢复、容错、溢出检测）；
• 5_performance：性能（adump、log、profiling）；
• 6_scenarios：典型场景（容错执行、图像处理、多设备推理、训练流水线）。

学习教程方面，Runtime 提供了开发指南与 API 参考，详见 docs/zh/README.md，涵盖 Runtime 编程模型、异步任务执行、内存管理、ACL Graph、多设备编程、进程间通信、运行时核心资源控制等主题，以及完整的 API 参考（设备管理、Stream/Event/Notify 管理、内存分配与拷贝、内核加载执行、Profiling、Dump 配置等）。

相关信息与总结

• 贡献相关：贡献指南、安全声明、许可证；
• 仓库配套有英文版文档 README_en.md 与 docs/en，便于国际化开发者阅读。

总体来看，CANN runtime 仓库的完整工作流可以概括为：确认版本配套 → 安装基础依赖与 CANN 软件包 → 环境验证 → 下载源码并配置环境变量 → 通过build.sh编译 runtime 包 → 安装生成的.run包 → 通过tests/build_ut.sh执行模块化 UT 用例 → 参考 example 与 docs 进行二次开发。理解build.sh与tests/build_ut.sh两个构建脚本的参数体系（模块映射、目标映射、覆盖率与 ASAN 开关），是高效使用本仓库的关键入口。

【免费下载链接】runtime本项目提供CANN运行时组件和维测功能组件。项目地址: https://gitcode.com/cann/runtime