企业官网建设流程全解析

CANN asc-tools 快速入门：从环境准备到编译安装与 UT 测试的完整实战指南

【免费下载链接】asc-toolsAscend C Tools仓是CANN基于Ascend C编程语言推出的配套调试工具仓。项目地址: https://gitcode.com/cann/asc-tools

asc-tools 是 CANN 基于 Ascend C 编程语言推出的配套调试工具仓，内置 cpudebug（CPU 仿真调试）、npuchk（NPU 算子校验）、msobjdump（二进制转储）、optype_collector（算子类型采集）、show_kernel_debug_data（内核调试数据解析）等能力。本文以仓库官方快速入门文档 docs/00_quick_start.md 为主线，完整覆盖四种环境准备方式（云开发环境、CANN 镜像 Docker、DevContainer、物理机）、CANN 包下载安装、环境验证、源码编译安装与 UT 测试全流程，并结合仓库内的 build.sh、.devcontainer、version.cmake 等源码佐证，帮助你从零搭建可用的 Ascend C 算子开发与调试环境，并成功编译出cann-asc-tools安装包。

一、环境准备：先按“有无 NPU”和“使用目标”做选择

搭建 asc-tools 开发环境的第一步是明确两个前提：宿主机本地是否有 NPU 设备，以及你的使用目标是社区体验/算子开发（对应 CANN 商用/社区版），还是生态开发/源码贡献（对应 CANN master）。依据这两个条件，官方文档给出了如下决策表：

选择建议（摘自原文档）：

• 为了保障开发体验环境的质量，推荐基于容器化技术完成环境准备。
• 如不希望使用容器，也可在带 NPU 设备的主机上完成环境准备，请参考 CANN 软件安装指南中“在物理机上安装”章节。
• 针对仅体验“编译安装本开源仓 + 仿真环境运行算子”的用户，不要求主机带 NPU 设备，可跳过安装 NPU 驱动和固件，直接安装 CANN 包（见本文第四节）。这一点从源码结构可以得到印证：本仓的 cpudebug 仿真能力（cpudebug/include/tikicpulib.h 等）面向纯 CPU 仿真运行，算子样例（examples/02_cpudebug）可在无 NPU 的仿真环境运行。

二、方式一：CANNLab 云开发环境（无 NPU 用户首选）

对于无 NPU 设备的用户，可直接使用CANNLab 云开发环境，即“一站式开发平台”。该平台提供在线可直接运行的昇腾 ARM 架构环境，已预装必备的驱动固件、软件包和依赖，无需手动安装。目前仅适用于 Atlas A2 系列产品，提供两种接入方式：

• WebIDE：网页版便携开发体验。
• VSCode IDE：支持远程连接云开发环境，可享用 VSCode 插件市场生态。

接入步骤：

1. 进入开源仓 Gitcode 页面，单击“CANNLab > 云开发”按钮，使用已认证的华为云账号登录（未注册/认证需先按页面提示完成）。
2. 按页面提示创建 NPU 环境并配置规格，启动云开发环境后，单击“连接 > WebIDE 或 Visual Studio Code”进入一站式开发平台。
3. 当前开源项目资源默认位于/mnt/workspace/gitCode/${gitCode_id}目录下，其中${gitCode_id}为开发者个人 gitCode 账号。

[!NOTE] 使用说明

• 环境默认安装了最新的商用版 NPU 驱动和固件、CANN 包，源码下载时注意与软件配套。
• 如需下载特定版本的 CANN 包，请参考本文第四节。
• 更多关于 CANNLab 云开发环境的介绍，请参考仓库讨论区的 CANNLab 指导；Huawei Developer Space 插件为 VSCode IDE 接入云开发环境提供技术支持。
• 云开发环境与本文第六节“环境验证”中的命令适配：验证 CANN 包安装信息时，CANNLab 场景下需将默认路径中的/usr/local替换为/home/developer。

三、方式二：基于 CANN 镜像的 Docker（有 NPU 用户推荐）

3.1 确认主机环境

• NPU 驱动与固件：执行npu-smi info，若能输出 NPU 相关信息则已安装；如未安装，请参考 CANN 软件安装指南中“准备软件包”和“安装 NPU 驱动和固件”章节。注意：驱动与固件是运行态依赖，若仅编译本项目源码，可以不安装。
• Docker：执行docker --version，能输出版本信息即可；未安装请参考 Docker 官方安装指南。

3.2 拉取 CANN 镜像

从昇腾镜像仓库拉取已预集成 CANN 的镜像，命令格式为docker pull <ascend/cann:tag>：

# 示例：拉取 ascend/cann:tag 为 9.0.0-beta.2 的 CANN 社区包 docker pull swr.cn-south-1.myhuaweicloud.com/ascendhub/cann:9.0.0-beta.2-910b-ubuntu22.04-py3.11

[!NOTE] 使用说明

• 镜像默认安装了对应版本的 CANN 包，源码下载时注意与软件配套。
• 镜像文件较大，正常网速下下载时间约为 5～10 分钟。

3.3 运行 Docker：完整命令与参数表

拉取镜像后，必须以特定参数启动，使容器内能访问宿主机 NPU 设备：

docker run --name <cann_container> \ --ipc=host --net=host --privileged \ --device /dev/davinci0 \ --device /dev/davinci_manager \ --device /dev/devmm_svm \ --device /dev/hisi_hdc \ -v /usr/local/dcmi:/usr/local/dcmi \ -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \ -v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \ -v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \ -v /etc/ascend_install.info:/etc/ascend_install.info \ -v </home/your_host_dir>:</home/your_container_dir> \ -it <ascend/cann:tag> bash

各参数含义与注意事项如下：

从源码层面看，仓库自带的 DevContainer 配置（.devcontainer/devcontainer.json）使用了几乎一致的一组参数：--ipc=host --net=host --privileged，逐卡列出--device=/dev/davinci0至davinci7，并挂载davinci_manager、devmm_svm、hisi_hdc三个控制设备，同时以只读方式挂载驱动与 DCMI 目录。这份配置文件本身就是上述参数表的“可运行实例”，宿主机 NPU 数量不足时删除多余的--device=/dev/davinciN行即可。

四、方式三：DevContainer（有 NPU 用户，生态开发推荐）

对于有 NPU 设备、且计划向本仓贡献代码的用户，推荐使用DevContainer。它基于 VS Code Dev Containers，通过仓库内 .devcontainer 配置自动构建一致的容器化开发环境：

• 基础镜像为 Ubuntu 24.04，内置conda（默认激活py312环境，Python 3.12 + PyTorch 2.7.1）、Python等开发工具链，详见 .devcontainer/Dockerfile。
• 与宿主机的 NPU 驱动共享设备访问（驱动目录以只读方式挂载），适合需要编译源码、运行 UT、向本仓贡献代码的场景。
• 完整使用方法请参考仓库内的 .devcontainer/README.md。

[!NOTE] 使用说明 DevContainer仅挂载宿主机的 NPU 驱动（只读），CANN toolkit 和 ops 包需在容器启动后手动安装，请参考本文第五节。DevContainer 的 Python 依赖清单（以 Python 3.12 为例）可参考 .devcontainer/requirements.txt。

五、下载安装 CANN 包

CANN 包分为CANN toolkit 包和CANN ops 包两类。

5.1 下载 CANN 包

• 下载 CANN 商用/社区版：体验官网正式发布的 CANN 包，请访问昇腾社区“CANN 安装部署”页面获取对应版本。
• 下载 CANN master：体验 CANN master，请访问 CANN master 的 OBS 镜像网站，下载日期最新的 CANN 包。

5.2 安装 CANN 包

1. 安装 CANN toolkit 包（必选）

chmod +x Ascend-cann-toolkit_${cann_version}_linux-$(uname -m).run ./Ascend-cann-toolkit_${cann_version}_linux-$(uname -m).run --install --install-path=${install_path}

2. 安装 CANN ops 包（可选）

chmod +x Ascend-cann-${soc_name}-ops_${cann_version}_linux-$(uname -m).run ./Ascend-cann-${soc_name}-ops_${cann_version}_linux-$(uname -m).run --install --install-path=${install_path}

[!IMPORTANT] 安装说明 examples 中部分算子样例的编译运行依赖 ops 包，若想完整体验样例编译运行流程，建议安装此包。

参数说明：

版本配套关系是本仓编译的关键约束：根目录 version.cmake 中声明了当前 asc-tools 版本号（ASC_TOOLS_VERSION，仓库当前为 9.2.0），并通过set_cann_build_dependencies/set_cann_run_dependencies声明了对 runtime、ge-executor、metadef、asc-devkit 等同版本组件的编译/运行依赖。也就是说，编译本仓时必须搭配对应版本的 CANN 包，具体规则见本文第七节。

六、环境验证与环境变量配置

6.1 环境验证

[!NOTE] 使用前须知 云开发环境和基于 CANN 镜像的 Docker 已预装 CANN 包，可直接执行以下命令验证；DevContainer 和手动安装用户请在安装 CANN 包后执行。

• 检查 NPU 设备：

# 运行 npu-smi，若能正常显示设备信息，则驱动正常 npu-smi info

• 检查 CANN 包安装：

# 查看 CANN Toolkit 的 version 字段（默认路径安装）。CANNLab 场景下，请将 /usr/local 替换为 /home/developer cat /usr/local/Ascend/cann/$(uname -m)-linux/ascend_toolkit_install.info # 查看 CANN ops 的 version 字段（默认路径安装）。CANNLab 场景下，请将 /usr/local 替换为 /home/developer cat /usr/local/Ascend/cann/$(uname -m)-linux/ascend_ops_install.info

6.2 环境变量配置

[!NOTE] 使用前须知 云开发环境和基于 CANN 镜像的 Docker 已自动配置环境变量，可跳过此步骤。

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

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

七、源码编译步骤：下载、依赖与编译安装

7.1 下载源码

编译环境可以访问网络时，推荐命令行方式下载：

# 开发环境，非 root 用户执行；git_clone_path 为用户自建目录 cd ${git_clone_path} git clone https://gitcode.com/cann/asc-tools.git

如需切换到其它 tag 版本（以 v0.5.0 为例）：

git checkout v0.5.0

编译环境无法访问网络时，可通过压缩包方式下载（下载时间较短，步骤稍复杂）：

# 1. asc-tools 仓右上角选择【下载ZIP】。 # 2. 将 ZIP 包上传到开发环境普通用户某个目录，例如 ${git_clone_path}/asc-tools-master.zip。 # 3. 解压。 cd ${git_clone_path} unzip asc-tools-master.zip

7.2 离线编译的三类依赖包

离线方式下载源码后，还需同步准备以下依赖（下载压缩包命名与 tag/branch 相关，此处以 master 分支为例）：

（1）依赖代码仓的 master 分支压缩包：需分别下载 msot、mssanitizer、msopprof、msopgen、mskpp、mskl、msdebug 代码仓的 master 分支压缩包，即进入各仓页面后右上角选择【下载ZIP】。这些依赖仓与主 CMake 构建关系清晰：根目录 CMakeLists.txt 依次add_subdirectory了 cpudebug、npuchk、utils/msobjdump、utils/optype_collector、utils/templates、utils/show_kernel_debug_data 等子模块，而 msot 等仓则通过 build.sh 中的MSOT_SUBMODULES配置在--pkg --msot场景下被联动构建。

（2）闭源 cpudebug 包（Release 版）：根据实际环境下载对应 Release 版本的闭源 cpudebug 包（区分 x86_64 / aarch64 两个架构）。cpudebug 是本仓 CPU 仿真调试能力的核心运行库，其源码接口可见 cpudebug/include 目录（如 tikicpulib.h、kernel_fp16.h、kernel_fp32.h 等）。从构建脚本看，build.sh 的copy_deps_file函数会自动把构建目录下的cann-asc-tools-cpudebug-deps*.tar.gz复制到三方库目录，供编译使用。

（3）开源第三方软件依赖：

对于上述开源第三方软件，仓库提供了一键式下载脚本install_dep_tar.py：

python3 install_dep_tar.py --dest_dir=${your_3rd_party_path} # ${your_3rd_party_path} 为第三方软件存放路径

7.3 安装编译依赖

[!NOTE] 使用前须知 如果使用容器化技术，容器中已安装好依赖，可跳过此步骤。

以下所列仅为本开源仓源码编译用到的依赖，Python/gcc/cmake 的安装方法请参见配套版本的 CANN 用户手册中“安装CANN > 安装依赖”章节：

• python >= 3.7.0（注意：python 已宣布 3.7.x/3.8.x 版本 EOL，CANN 即将停止支持，请升级到 >= 3.9.x 版本）
• gcc 与 g++：支持版本范围 7.3.x 至 14.x（要求 gcc 与 g++ 版本一致）
• cmake >= 3.16.0（与根目录 CMakeLists.txt 中cmake_minimum_required(VERSION 3.16.0)的要求一致）
• ccache >= 4.6.1：建议版本 release-v4.6.1

x86_64 环境安装 ccache：

# 在准备安装的路径下创建 buildtools 目录，如有则忽略（此处以 /opt 为例） mkdir /opt/buildtools # 切换到安装包下载路径，将 ccache 解压到安装路径 tar -xf ccache-4.6.1-linux-x86_64.tar.xz -C /opt/buildtools chmod 755 /opt/buildtools/ccache-4.6.1-linux-x86_64/ccache mkdir -p /usr/local/ccache/bin # 建立软链接 ln -sf /opt/buildtools/ccache-4.6.1-linux-x86_64/ccache /usr/local/bin/ccache ln -sf /opt/buildtools/ccache-4.6.1-linux-x86_64/ccache /usr/local/ccache/bin/ccache # 将 ccache 添加到环境变量 PATH export PATH=/usr/local/ccache/bin:$PATH

aarch64 环境安装 ccache：需先下载依赖项 zstd 和 hiredis，再编译安装：

# 在准备安装的路径下创建 buildtools 目录，如有则忽略（此处以 /opt 为例） mkdir /opt/buildtools # 切换到安装包下载路径，将 zstd 解压到安装路径 tar -xf zstd-1.5.0.tar.gz -C /opt/buildtools cd /opt/buildtools/zstd-1.5.0 make -j 24 make install cd - # 将 hiredis 解压到安装路径 tar -xf hiredis-1.0.2.tar.gz -C /opt/buildtools cd /opt/buildtools/hiredis-1.0.2 make -j 24 prefix=/opt/buildtools/hiredis-1.0.2 all make prefix=/opt/buildtools/hiredis-1.0.2 install cd - # 将 ccache 解压到安装路径并编译 tar -xf ccache-4.6.1.tar.gz -C /opt/buildtools cd /opt/buildtools/ccache-4.6.1 mkdir build cd build/ cmake -DCMAKE_BUILD_TYPE=Release -DZSTD_LIBRARY=/usr/local/lib/libzstd.a -DZSTD_INCLUDE_DIR=/usr/local/include -DHIREDIS_LIBRARY=/usr/local/lib/libhiredis.a -DHIREDIS_INCLUDE_DIR=/usr/local/include .. make -j 24 make install mkdir -p /usr/local/ccache/bin # 建立软链接 ln -sf /usr/local/bin/ccache /usr/local/ccache/bin/ccache # 将 ccache 添加到环境变量 PATH export PATH=/usr/local/ccache/bin:$PATH

其余依赖按需安装：

• setuptools >= 45.2.0：pip3 install setuptools
• lcov >= 1.13（可选，仅执行 UT 时依赖）：Ubuntu（x86_64）执行apt install lcov；Euler（aarch64）执行yum install lcov
• pytest >= 8.3.2（可选，仅执行 UT 时依赖）：pip3 install pytest
• coverage >= 4.5.4（可选，仅执行 UT 时依赖）：pip3 install coverage
• googletest（可选，仅执行 UT 时依赖，建议 release-1.11.0）：

mkdir temp && cd temp # 在 googletest 源码根目录下创建临时目录并进入 cmake .. -DCMAKE_CXX_FLAGS="-fPIC -D_GLIBCXX_USE_CXX11_ABI=0" make make install # root 用户安装 googletest # sudo make install # 非 root 用户安装 googletest

7.4 编译 asc-tools 安装包

本开源仓提供一键式编译安装能力。进入开源仓代码根目录，执行：

cd asc-tools bash build.sh --pkg

若编译环境无法访问网络，需要在联网环境下载上述依赖代码仓、闭源及开源软件的压缩包并上传至编译环境，先创建存放目录：

mkdir -p {your_3rd_party_path}

将压缩包上传至{your_3rd_party_path}后，使用以下命令编译：

bash build.sh --pkg --cann_3rd_lib_path={your_3rd_party_path}

编译完成后会在build_out目录下生成cann-asc-tools_<cann_version>_linux-<arch>.run软件包。以仓库当前 version.cmake 声明的版本为例，产物即形如cann-asc-tools_9.2.0_linux-x86_64.run。

从 build.sh 源码看，该脚本还支持一组实用的构建参数，可在编译时按需使用：

[!CAUTION] 编译报错可能 本仓依赖其他 CANN 开源仓，暂不支持独立升级，须搭配对应版本的 CANN 包进行编译：

• master 分支→ 使用最新的 CANN master 包
• 特定 Tag→ 使用对应版本的官网正式发布的 CANN 包

7.5 安装 run 包

在开源仓根目录下执行下列命令，根据设置的环境变量路径，将编译生成的 run 包安装到 CANN 包的装包路径，同时会覆盖原 CANN 包中的 Ascend C 内容：

# 切换到 run 包生成路径下 cd build_out # 默认路径安装 run 包 ./cann-asc-tools_<cann_version>_linux-<arch>.run --full --pylocal # 指定路径安装 run 包 ./cann-asc-tools_<cann_version>_linux-<arch>.run --full --pylocal --install-path=${install_path}

安装后即可使用本仓提供的各工具能力，例如：

• CPU 仿真调试（examples/02_cpudebug）：在无 NPU 的仿真环境运行 Ascend C 算子；
• NPU 算子校验（npuchk，入口见 npuchk/ascendc_npuchk_report.py）；
• 二进制转储解析（msobjdump，入口见 utils/msobjdump/msobjdump/msobjdump_main.py）；
• 内核调试数据解析（show_kernel_debug_data，入口见 utils/show_kernel_debug_data/show_kernel_debug_data/data_converter.py）；
• 算子类型采集（optype_collector，入口见 utils/optype_collector/optype_collector/optype_collector_main.py）。

各工具的详细用法可继续阅读 docs/00_quick_start.md 之外的分册文档，如 docs/01_cpu_debug.md、docs/02_npu_check.md、docs/03_msobjdump.md、docs/04_show_kernel_debug_data.md、docs/05_optype_collector.md。

八、UT 测试（可选）

在开源仓根目录执行下列命令之一，将依次批跑 tests 目录下的用例，得到结果日志，用于看护编译是否正常：

bash build.sh -t

或

bash build.sh --test

若编译环境无法访问网络，需先在联网环境下载依赖代码仓及开源软件压缩包并上传至{your_3rd_party_path}目录：

mkdir -p {your_3rd_party_path}

上传依赖压缩包后，执行：

bash build.sh --test --cann_3rd_lib_path={your_3rd_party_path}

[!NOTE] 与编译的区别 相比编译，UT不下载 Release 版本的 cpudebug 包，而是需要根据实际环境下载对应Debug 版本的闭源 cpudebug 包（同样区分 x86_64 / aarch64）。Debug 版本相比 Release 版本更方便进行调试。

UT 用例覆盖了本仓各核心模块，从 tests/ut/testcase 目录结构可以看出测试面：acl_stub、regfwk（如 test_kernel_print_lock.cpp、test_stub_reg.cpp）、tikcpp_api_check（如 test_copy_check.cpp、test_vec_binary_check.cpp）、tikcpp_case_common（如 test_cpu_debug_check.cpp、test_kernel_utils.cpp）等；Python 侧测试位于 tests/py_ut/testcase，覆盖 msobjdump、optype_collector、show_kernel_debug_data 三个工具。从 build.sh 源码看，UT 模式下脚本会自动追加-DENABLE_TEST=ON -DTEST_MOD=all并将构建类型切换为Debug，测试还支持分模块运行（--cpp_utest/--python_utest）与 ASAN 开关（--asan）。

8.1 UT 测试显示覆盖率

• 依赖项：lcov >= 1.14
• 执行命令：

bash build.sh --test --cov

从 build.sh 源码可知，--cov对应在 CMake 配置中追加-DENABLE_GCOV=true，配合 tests/cmake/tools/generate_cpp_cov.sh 等脚本完成代码覆盖率统计。

九、总结

本仓的快速入门流程可以概括为一条主线：按有无 NPU 选定环境 → 准备对应版本的 CANN 包 → 验证环境与加载环境变量 → 下载源码与依赖 →bash build.sh --pkg编译 → 安装 run 包 → 可选 UT 测试。其中最容易踩坑的是版本配套关系：无论是 CANN 商用/社区版还是 CANN master，编译时必须与 version.cmake 声明的 asc-tools 版本匹配；离线编译场景则需完整准备依赖仓、闭源 cpudebug 包与开源第三方软件三类压缩包。掌握上述流程后，即可在本地完成 Ascend C 算子的仿真调试、NPU 校验与工具链的二次开发。

【免费下载链接】asc-toolsAscend C Tools仓是CANN基于Ascend C编程语言推出的配套调试工具仓。项目地址: https://gitcode.com/cann/asc-tools