CANN runtime 开源仓库实战指南环境部署、源码编译与 UT 验证全流程【免费下载链接】runtime本项目提供CANN运行时组件和维测功能组件。项目地址: https://gitcode.com/cann/runtime导读README_en.md 是 CANN runtime 开源仓库的英文总入口文档它完整定义了该项目的定位、版本策略、目录组织、环境部署、源码编译、软件包安装与单元测试UT验证的标准流程。本文以该文档为主线结合仓库中build.sh、download_3rd_party.py、tests/build_ut.sh等实际构建脚本与src/CMakeLists.txt等模块定义逐层拆解从拿到源码到跑通 UT的完整闭环帮助开发者在自己的环境上复现 CANN Runtime 的编译与验证过程并理解每一步背后的实现细节。项目定位与核心组成CANN runtime 仓库提供两大组件群Runtime 组件提供昇腾AscendNPU 运行时用户编程接口即 ACL Runtime 系列 API与核心运行时实现覆盖设备管理、流Stream管理、事件Event管理、内存管理、任务调度等能力。维测功能组件面向性能分析与问题定位包括以下子模块性能调优msprof模块采集并分析 AI 任务在昇腾 SoC NPU IP 加速器上各运行阶段的关键性能指标输出性能数据帮助开发者快速识别软硬件性能瓶颈。精度调试adump模块支持对单个算子或模型逐算子层的输入输出数据 dump用于精度问题定位也支持在运行异常时 dump 异常算子的输入输出、workspace 与 tiling 信息用于分析 AI Core 异常。日志log模块提供进程执行信息记录能力包含进程打印与日志持久化辅助系统故障诊断其中的msnpureport命令行工具支持导出设备侧日志以及查询/设置设备侧状态。从src/CMakeLists.txt的子目录注册可以看到这些模块在源码中的实际组织方式src/runtime运行时核心、src/aclacl 对外 API含aclrt、acl_tdt_queue、acl_tdt_channel、src/dfxadump/log/msprof/trace/error_manager、src/mmpa平台抽象、src/tsd调度守护进程、src/queue_schedule与src/aicpu_sched任务队列与 AI CPU 调度等。版本兼容性与分支选择文档明确说明本项目的源码随 CANN 软件版本发布CANN 软件版本与项目 tag 的对应关系需参考 release 仓库的版本描述。为保证源码定制开发的平滑性务必选择与所用 CANN 版本兼容的 Gitcode tag 源码直接使用 master 分支存在版本不匹配风险。仓库的version.cmake文件声明了当前版本set_cann_package(npu-runtime VERSION 9.2.0)即当前主线对应 CANN 9.2.0 的 npu-runtime 包。文档同时在 Latest News 中记录了版本演进信息2025/12 项目首次发布2026/4 新增对 Ascend 950PR / Ascend 950DT 芯片的支持并持续增强 AclGraph 功能与文档结构。实操建议动手前先确认自己的 CANN 软件版本与所选的仓库 tag 是否配套再决定git clone时使用的分支或 tag避免编译期或运行期出现版本错配问题。仓库目录结构解读文档给出了关键目录树结合仓库实际内容可归纳如下目录/文件职责仓库内参考入口cmake/构建编译目录设备/桩 stub/第三方依赖/打包等 CMake 片段cmake/docs/文档中文总入口见 docs/zh/README.md含快速入门、编程指南、API 参考、日志/错误码/环境变量参考、架构指南与研发规范docs/zh/README.mdexample/基于 acl 接口的样例代码覆盖快速入门、基础特性、高级特性、内存进阶、可靠性、性能与场景案例example/README_en.mdinclude/3.1 包发布所需头文件dfx维测头文件与external对外头文件如acl.h、acl_rt.h等include/external/acl/pkg_inc/仓库管理相关头文件driver、runtime、profiling、dump 等内部接口声明pkg_inc/scripts/构建辅助文件与打包脚本scripts/src/3.1 包中所有模块的源码src/acl、src/dfx、src/mmpa、src/runtime等src/CMakeLists.txtstub/桩stub相关目录用于生成对外 API 的桩实现stub/tests/UT 测试用例按模块分目录存放tests/ut/acl、tests/ut/runtime、tests/ut/msprof等tests/ut/CMakeLists.txt顶层构建配置CMakeLists.txtbuild.sh项目构建脚本build.shdownload_3rd_party.py离线场景下第三方开源组件下载脚本download_3rd_party.pytests/build_ut.sh中的ut_path_map还给出了各模块名与 UT 用例目录的对应关系例如acl对应tests/ut/aclruntime对应tests/ut/runtime/runtimemsprof对应tests/ut/msprofadump对应tests/ut/adump。环境部署手动安装基础依赖基础依赖清单及版本要求注意版本约束依赖版本要求python 3.7.0Python 3.7/3.8 已官方 EOLCANN 将于 2027 年 3 月停止支持建议升级到 3.9.0pip3—gcc 7.3.0 13cmake 3.16.0ccache / 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 makeCentOS/EulerOS 系列安装示例sudo yum install python3 python3-pip python3-devel gcc gcc-c glibc-devel cmake ccache autoconf gperf libtool make若使用 Dev Container 方式编译仓库 .devcontainer/README_en.md 提供了容器内工具链清单Ubuntu 22.04 LTS 基础镜像、GCC/G 9.x、CMake 3.22、Python 3.10、ccache以及配合--asan使用的 gcc-9 sanitizer 运行库libasan5/libtsan0/libubsan1。手动安装CANN 软件包场景一体验 master 版本能力或基于 master 开发安装驱动与固件可选仅运行 样例 时需要只编译 runtime 包可跳过此步。下载与安装方法参考 CANN 软件安装指南的准备软件包与安装 NPU 驱动和固件章节。安装 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 型号名与产品对应关系如下产品soc_nameAtlas A2 训练系列产品 / Atlas A2 推理系列产品910bAtlas A3 训练系列产品 / Atlas A3 推理系列产品A3Ascend 950PR / Ascend 950DT 产品950场景二体验发布版本能力或基于发布版本开发前往 CANN 官方下载中心选择发布版本仅支持 CANN 8.5.0 及以后版本、产品型号与环境架构按快速安装指南完成安装。环境验证安装完成后用以下方式验证环境与驱动是否正常检查 NPU 设备npu-smi info若设备信息正常显示说明驱动工作正常。检查 CANN 版本# 查看 CANN Toolkit 开发套件包的版本信息默认路径安装 cat /usr/local/Ascend/cann/${arch}-linux/ascend_toolkit_install.info # 查看 CANN ops 包版本信息默认路径安装 cat /usr/local/Ascend/cann/${arch}-linux/ascend_ops_install.info其中${arch}为 CPU 架构aarch64 或 x86_64。源码构建Source Code Build下载源码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下载完成后使用如下命令编译--cann_3rd_lib_path需为绝对路径bash build.sh --cann_3rd_lib_paththird_partydownload_3rd_party.py的实现会解析README.md中第三方软件依赖表中的下载地址并逐一下载已存在的文件会跳过。更多编译参数可运行bash build.sh -h查看。从 build.sh 源码可以看到脚本支持的完整参数体系常用参数包括参数作用默认值-jN编译线程数CPU 核数-v/--verbose显示编译命令关闭--asan开启 AddressSanitizer 内存检测关闭--cov开启覆盖率统计关闭--build-typeRelease/Debug构建类型Release--pkg-typerpm/run/deb软件包类型run--ascend_install_pathPATHCANN 包安装路径/usr/local/Ascend/cann或ASCEND_HOME_PATH--cann_3rd_lib_pathPATH第三方依赖包路径./output/third_party--build_host_only仅构建 Host 侧目标关闭--enable-sign / --sign-script PATH使能签名关闭脚本内部会执行cmake -S ../ -B .完成配置传入ENABLE_OPEN_SRC、CMAKE_BUILD_TYPE、ASCEND_INSTALL_PATH、CANN_3RD_LIB_PATH、ENABLE_COV、ENABLE_ASAN、ENABLE_UT、PACKAGE_TYPE等参数随后执行cmake --build . -j${THREAD_NUM}与make package完成打包。编译结束后build_out目录下生成cann-npu-runtime_${version}_linux-${arch}.run软件包${version}版本号${arch}操作系统架构取值包括x86_64与aarch64。开源第三方软件依赖runtime 编译所依赖的开源第三方软件清单版本必须保持一致开源软件版本abseil-cpp20230802.1acl-compat9.2.0boost1.87.0eigen5.0.0googletest1.14.0json3.12.0libboundscheck1.1.16libseccomp2.5.4mockcpp含 mockcpp_patch2.7-h5protobuf25.1makeself2.5.0cann-cmakemaster-053[!NOTE] 如果从其他地址下载请确保版本号一致。安装 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 需要 googletest 单元测试框架。编译并执行 UT 测试用例bash tests/build_ut.sh --utacl --targetascendcl_utest -c --cann_3rd_lib_path${your_3rd_party_path}其中${your_3rd_party_path}必须是绝对路径。指定测试模块--ut--ut后接模块名。模块名与测试用例路径的映射定义在 tests/build_ut.sh 的ut_path_map中例如acl模块的用例位于tests/ut/aclruntime模块的用例位于tests/ut/runtime/runtime。指定测试目标文件--target各模块的编译目标可从对应模块的CMakeLists.txt查看。以acl为例tests/ut/acl/CMakeLists.txt 中的add_custom_target(ascendcl_utest DEPENDS ${ASCENDCL_TARGET})表明ascendcl_utest聚合了两个目标文件ascendcl_c_utest与ascendcl_cpp_utest。因此上面将--target指定为ascendcl_utest会编译并执行acl模块的全部测试用例也可以直接指定具体目标文件多个目标用空格分隔。其他编译参数-c获取覆盖率信息不需要可省略。使用前需安装lcovUbuntu/Debiansudo apt install lcovopenEulersudo dnf install lcov。若因版本差异报错请按提示调整脚本参数。--asan开启 AddressSanitizer 内存错误检测不需要可省略。AddressSanitizer 通常集成在 gcc 中无需单独安装如需单独安装需与 gcc 版本配套例如 gcc 9.5.0 对应 libasan6。--cann_3rd_lib_path指定第三方依赖路径联网环境可省略。从 tests/build_ut.sh 源码看脚本还支持--ut_timeoutSECONDS设置每个 UT 可执行文件的超时时间默认 0 表示不限制与-u/--ut [specific_ut]仅运行指定的某个测试等参数详细说明运行bash tests/build_ut.sh -h查看。UT 编译过程的中间文件与产物位于output和build目录如需清理历史编译记录rm -rf output/ build/UT 用例会以 gtest 的 XML 报告形式输出到output/report/ut目录若开启覆盖率统计脚本会调用lcov收集并生成 HTML 覆盖率报告输出在cov/目录并可结合--asan在运行前自动校验libasan.so、libubsan.so、libtsan.so等 sanitizer 运行库是否存在。进一步了解样例与学习资源样例代码example/README_en.md 说明 example 目录按能力分层的组织方式包括0_quickstart快速入门、1_basic_features设备/流/事件/内存等基础特性、2_advanced_featuresKernel 执行、ACL Graph、内置任务、回调等、3_memory_advanced自定义分配器、Host 注册、统一寻址等、4_reliability溢出检测、错误恢复、5_performance性能分析与精度调试、6_scenarios训练流水线、多设备推理等场景。样例运行前需按 README_en.md 完成环境准备并在编译源码后将其部署到环境。注意样例 README 中的产品支持表只列出已验证或已明确声明支持状态的产品Ascend 950PR/Ascend 950DT 为新接入产品部分历史样例尚未在其上完成验证。表中未列出的产品不代表不支持明确不支持的产品会用×标记并加注说明。样例对设备复位 API 的使用有明确约定单进程样例通常使用aclrtResetDeviceForce强制清理当前样例占用的 Device 资源同机多进程 IPC 样例使用aclrtResetDevice仅释放当前进程拥有的 Device 资源避免对其他进程造成强制复位影响。运行时文档Runtime 开发指南与 API 参考的完整中文入口见 docs/zh/README.md其文档导航覆盖快速入门、编程指南、API 参考、日志参考、错误码参考、环境变量参考、架构指南与研发规范。其中 docs/zh/quick_start/Runtime_overview.md 以一个 VectorAdd 向量加法示例展示了aclInit→aclrtSetDevice→aclrtCreateStream→aclrtMalloc→aclrtMemcpy→ 算子下发 →aclrtSynchronizeStream的完整编程闭环以及 Runtime 围绕任务执行生命周期提供的全局管理、Device、Context、Stream、Memory、Kernel、Event 等功能模块。相关仓库信息贡献指南、安全声明、开源许可。总结本文从 CANN runtime 仓库的英文总入口文档出发梳理了环境准备 → 源码编译 → 软件包安装 → UT 验证的完整链路并通过build.sh、download_3rd_party.py、tests/build_ut.sh、src/CMakeLists.txt等仓库文件核实了每一步的底层实现与参数含义。对开发者而言核心要点可概括为三条一是选对版本master 分支与 CANN 发布版本需配套使用二是分清场景联网与离线编译分别走bash build.sh与python download_3rd_party.py--cann_3rd_lib_path的路径三是善用 UT通过--ut、--target、-c、--asan的组合灵活控制验证范围与质量手段为基于 Runtime 源码的二次开发建立可靠的回归基线。【免费下载链接】runtime本项目提供CANN运行时组件和维测功能组件。项目地址: https://gitcode.com/cann/runtime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考