CANN Runtime 样例构建模式全解析：5 种 CMake 模式与 4 种 run.sh 模式的选择与实践

CANN Runtime 样例构建模式全解析5 种 CMake 模式与 4 种 run.sh 模式的选择与实践【免费下载链接】runtime本项目提供CANN运行时组件和维测功能组件。项目地址: https://gitcode.com/cann/runtime导读CANN Runtime 开源仓库的example/目录下收录了大量可直接编译运行的示例程序覆盖设备管理、Stream/Event、内存拷贝、自定义算子、Profiling、Adump 等能力。为了在不同功能需求下保持构建脚本的一致性仓库沉淀了一套可复用的构建范式5 种 CMake 构建模式Pattern A~E与 4 种 run.sh 运行模式Pattern 1~4。本文基于仓库内部的构建模式参考文档.claude/skills/hlt-to-sample-generator/references/sample-build-patterns.md结合example/目录中的真实CMakeLists.txt与run.sh完整讲解每种模式的适用场景、关键特征、配置参数并给出模式选择决策树帮助你在开发新样例或移植样例时快速选型、一次编译通过。构建模式总览CANN Runtime 的样例构建体系围绕两条主线展开CMake 模式Pattern A~E回答该样例需要链接哪些库、引入哪些头文件路径、是否需要 AscendC kernel 编译基础设施。run.sh 模式Pattern 1~4回答该样例如何准备环境、构建、安装、运行与验证。模式名称核心特征CMake Pattern AACL-only最简单仅链接libascendcl.so无算子无 kernelCMake Pattern BACL opapi使用 aclnn 预置算子如aclnnAddCMake Pattern CACL AscendC kernel通过ascendc_library编译自定义 kernelCMake Pattern DACL AscendC fatbinkernel launch 场景使用ascendc_fatbin_libraryCMake Pattern EProfiling / Adump 特定库额外链接 msprofiler / ascend_dump 等库run.sh Pattern 1简单构建运行source setenv.bash cmake make 运行run.sh Pattern 2构建 安装 验证使用新式 cmake CLI输出捕获到文件run.sh Pattern 3Full kernel 构建流水线自动检测 SOC_VERSION / ASCENDC_CMAKE_DIRrun.sh Pattern 4多进程/多程序IPC、跨进程、跨服务器场景CMake Pattern AACL-only最简构建适用场景只使用基础 acl / aclrt 接口不使用 aclnn 算子不使用 AscendC kernel。代表样例example/1_basic_features/device/、example/1_basic_features/stream/、example/1_basic_features/event/、example/4_reliability/overflow_detection/。cmake_minimum_required(VERSION 3.16.0) project(Runtime_Sample) include_directories( ${ASCEND_CANN_PACKAGE_PATH}/include ${CMAKE_CURRENT_SOURCE_DIR}/../../..) link_directories(${ASCEND_CANN_PACKAGE_PATH}/lib64) add_executable(main main.cpp) target_compile_options(main PRIVATE -O2 -stdc17 -D_GLIBCXX_USE_CXX11_ABI0 -Wall -Werror) target_link_libraries(main PRIVATE ${ASCEND_CANN_PACKAGE_PATH}/lib64/libascendcl.so)关键特征只链接libascendcl.so这是 ACL 运行时对外提供的核心封装库包含aclInit、aclrtSetDevice、aclrtMalloc等接口include 路径只有 CANN 安装包头文件${ASCEND_CANN_PACKAGE_PATH}/include与 example 根目录后者用于引用仓库级公共头文件不需要SOC_VERSION/ASCENDC_CMAKE_DIR环境变量因为不涉及 AscendC kernel 编译这也是 Pattern A 与 Pattern C/D 最直观的区别。仓库中 example/1_basic_features/event/0_event_status/CMakeLists.txt 即采用此结构。注意编译选项中的-D_GLIBCXX_USE_CXX11_ABI0是 CANN 生态的常见约定用于与 CANN 安装包内的预编译库保持 ABI 一致避免链接期符号冲突-Wall -Werror则要求样例代码零警告。CMake Pattern BACL opapiaclnn 预置算子适用场景使用 aclnn 预置算子如aclnnAdd不使用自定义 AscendC kernel。代表样例example/0_quickstart/0_hello_cann、example/2_advanced_features/model_ri/0_simple_model。cmake_minimum_required(VERSION 3.16.0) project(Runtime_Sample) include_directories( ${ASCEND_CANN_PACKAGE_PATH}/include ${ASCEND_CANN_PACKAGE_PATH}/aclnn ${CMAKE_CURRENT_SOURCE_DIR}/../../.. ${CMAKE_CURRENT_SOURCE_DIR}/..) link_directories(${ASCEND_CANN_PACKAGE_PATH}/lib64) add_executable(main main.cpp ../model_utils.cpp) target_link_libraries(main PRIVATE ${ASCEND_CANN_PACKAGE_PATH}/lib64/libascendcl.so ${ASCEND_CANN_PACKAGE_PATH}/lib64/libnnopbase.so ${ASCEND_CANN_PACKAGE_PATH}/lib64/libopapi.so)关键特征include${ASCEND_CANN_PACKAGE_PATH}/aclnn提供aclnnop/aclnn_add.h等 aclnn 算子头文件链接libnnopbase.solibopapi.soaclnn 算子执行所需的算子基础库与算子 API 库二者缺一不可可能包含类别级共享源文件如../model_utils.cpp此时额外 include${CMAKE_CURRENT_SOURCE_DIR}/..以引入类别级头文件。关于仓库未发布 API如果样例使用本仓库尚未随 CANN 发布release的接口需要在include_directories最前面插入仓库自身的头文件路径使仓库头文件优先于安装包头文件被解析include_directories( ${CMAKE_CURRENT_SOURCE_DIR}/../../../../include/external # repo 头文件优先 ${ASCEND_CANN_PACKAGE_PATH}/include ${ASCEND_CANN_PACKAGE_PATH}/aclnn ...)这里../../../../include/external指向仓库根目录的 include/external即acl.h、acl_rt.h等公开头文件所在目录保证样例能编译到仓库最新接口。以仓库内的 example/0_quickstart/0_hello_cann/CMakeLists.txt 为例它还额外链接了libacl_rt.so对应aclrtMalloc/aclrtMemcpy等纯 RT 接口example/2_advanced_features/model_ri/0_simple_model 则在add_executable中追加../model_utils.cpp共享源码是 Pattern B 带类别级共享文件的典型形态。CMake Pattern CACL AscendC kernelascendc_library适用场景使用自定义 AscendC kernelkernel 源文件通过ascendc_library编译为静态库。代表样例example/1_basic_features/memory/大部分样例、example/5_performance/adump/。cmake_minimum_required(VERSION 3.16.0) project(Runtime_Sample) set(SOC_VERSION $ENV{SOC_VERSION}) set(ASCENDC_CMAKE_DIR $ENV{ASCENDC_CMAKE_DIR}) set(RUN_MODE npu CACHE STRING run mode: npu) set(CMAKE_BUILD_TYPE Debug CACHE STRING Build type Release/Debug (default Debug) FORCE) set(CMAKE_INSTALL_PREFIX ${CMAKE_CURRENT_LIST_DIR}/out CACHE STRING path for install() FORCE) include(${ASCENDC_CMAKE_DIR}/ascendc.cmake) ascendc_library(kernels STATIC ../../../kernel_func/easy_OP.cpp) include_directories( ${ASCEND_CANN_PACKAGE_PATH}/include ${CMAKE_CURRENT_SOURCE_DIR}/../../..) link_directories(${ASCEND_CANN_PACKAGE_PATH}/lib64) add_executable(main main.cpp) target_link_libraries(main PRIVATE ascendcl)关键特征需要环境变量SOC_VERSION和ASCENDC_CMAKE_DIR通常由 example/set_sample_env.sh 自动检测并导出见下文 run.sh Pattern 3 的说明include(${ASCENDC_CMAKE_DIR}/ascendc.cmake)引入 AscendC 构建基础设施提供ascendc_library等函数ascendc_library(kernels STATIC ...)将 kernel 源文件编译为静态库第一个参数是库名第二个参数是库类型如 STATIC后续为 kernel 源文件列表kernel 源文件统一放在 example/kernel_func/如easy_OP.cpp、kernel_add.cpp、kernel_ops.h通过相对路径引用链接ascendclCMake target 名这是 Pattern C 与 Pattern D 的又一区别点Pattern C 直接写 target 名Pattern D 链接具体.so路径。ascendc.cmake的路径由ASCENDC_CMAKE_DIR指向其典型位置是 CANN 安装包下的tikcpp/ascendc_kernel_cmake与 ACL 库一样按主机架构区分如x86_64-linux/、aarch64-linux/。CMake Pattern DACL AscendC fatbinkernel launch适用场景kernel launch 样例即使用...调用语法直接发射 kernel需要ascendc_fatbin_library将一个或多个 kernel 编译为 fatbin。代表样例example/2_advanced_features/kernel/0_launch_kernel。cmake_minimum_required(VERSION 3.16.0) project(Kernel_Launch_Sample) set(SOC_VERSION $ENV{SOC_VERSION}) set(ASCENDC_CMAKE_DIR $ENV{ASCENDC_CMAKE_DIR}) set(RUN_MODE npu CACHE STRING run mode: npu) set(CMAKE_BUILD_TYPE Debug CACHE STRING Build type Release/Debug (default Debug) FORCE) set(CMAKE_INSTALL_PREFIX ${CMAKE_CURRENT_LIST_DIR}/out CACHE STRING path for install() FORCE) file(GLOB KERNEL_FILES ../../../kernel_func/add_custom.cpp) include(${ASCENDC_CMAKE_DIR}/ascendc.cmake) ascendc_fatbin_library(ascendc_kernels ${KERNEL_FILES}) include_directories( ${ASCEND_CANN_PACKAGE_PATH}/include ${CMAKE_CURRENT_SOURCE_DIR}/../../..) link_directories(${ASCEND_CANN_PACKAGE_PATH}/lib64) add_executable(main main.cpp ../file_ops.cpp) target_link_libraries(main PRIVATE ${ASCEND_CANN_PACKAGE_PATH}/lib64/libacl_rt.so)关键特征使用ascendc_fatbin_library()将 kernel 编译为 fatbin可执行二进制镜像供 host 侧在运行时加载发射链接libacl_rt.so而非libascendcl.so——kernel launch 场景需要rtKernelLaunch等底层 RT 接口通常配合install()步骤将产物部署到out/bin/、out/lib/host 程序运行时通过LD_LIBRARY_PATH找到 fatbin。仓库实际实现 example/2_advanced_features/kernel/0_launch_kernel/CMakeLists.txt 展示了更完整的形式用file(GLOB KERNEL_FILES_SIMPLE .../add_custom.cpp)与file(GLOB KERNEL_FILES_PLACEHOLDER .../add_custom_tiling.cpp)分别声明两组 kernel再分别调用ascendc_fatbin_library()产出ascendc_kernels_simple与ascendc_kernels_placeholder最后用install(TARGETS ... RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})部署可执行文件对应out/bin/目录。CMake Pattern EProfiling / Adump 特定库适用场景性能分析profiling或精度调试adump。该模式并非独立范式而是针对特定库的追加式配置。Profiling 变体代表样例example/5_performance/profiling/。cmake_minimum_required(VERSION 3.16.0) project(Profiling_Sample) set(ASCEND_CANN_PACKAGE_PATH $ENV{ASCEND_HOME_PATH}) include_directories( ${ASCEND_CANN_PACKAGE_PATH}/include ${ASCEND_CANN_PACKAGE_PATH}/include/driver ${ASCEND_CANN_PACKAGE_PATH}/include/acl ${ASCEND_CANN_PACKAGE_PATH}/runtime/include ${CMAKE_CURRENT_SOURCE_DIR}/../../..) link_directories(${ASCEND_CANN_PACKAGE_PATH}/lib64) add_executable(main main.cpp) target_link_libraries(main PRIVATE ${ASCEND_CANN_PACKAGE_PATH}/lib64/libmsprofiler.so ${ASCEND_CANN_PACKAGE_PATH}/lib64/libascendcl.so ${ASCEND_CANN_PACKAGE_PATH}/lib64/libprofapi.so)关键特征使用$ENV{ASCEND_HOME_PATH}而非 CMake 变量ASCEND_CANN_PACKAGE_PATH——直接在 CMake 层读取环境变量要求运行环境已正确导出ASCEND_HOME_PATH通常由set_env.sh完成额外 includeinclude/driver、include/acl、runtime/include这些目录对应驱动层接口、ACL 头文件与运行时头文件供msprof与aprof相关 API 使用链接libmsprofiler.solibprofapi.so前者是 msprof 采样/采集核心库后者是 profiling 的公开 API 库。仓库中的 example/5_performance/profiling/0_create_config/CMakeLists.txt 即完全采用此写法。Adump 变体Adump精度比对/张量 dump基于Pattern C带ascendc.cmake与ascendc_library在此基础上额外链接libascend_dump.so与libopapi.sotarget_link_libraries(main PRIVATE ${ASCEND_CANN_PACKAGE_PATH}/lib64/libascendcl.so ${ASCEND_CANN_PACKAGE_PATH}/lib64/libnnopbase.so ${ASCEND_CANN_PACKAGE_PATH}/lib64/libopapi.so ${ASCEND_CANN_PACKAGE_PATH}/lib64/libascend_dump.so)仓库实现 example/5_performance/adump/0_adump_args/CMakeLists.txt 与文档完全一致在 include 中同时引入${ASCEND_CANN_PACKAGE_PATH}/aclnn链接libascendcl.so、libnnopbase.so、libopapi.so、libascend_dump.so。libascend_dump.so提供aclmdlInitDump/aclrtSetDumpConfig等 dump 接口用于在算子输出阶段抓取张量数据。run.sh Pattern 1简单构建运行适用场景Pattern A / Pattern B 样例不涉及 AscendC kernel。set -e _ASCEND_INSTALL_PATH$ASCEND_INSTALL_PATH source $_ASCEND_INSTALL_PATH/bin/setenv.bash SCRIPT_DIR$(cd $(dirname ${BASH_SOURCE[0]}) pwd) cd ${SCRIPT_DIR} BUILD_DIR${SCRIPT_DIR}/build mkdir -p ${BUILD_DIR} cd ${BUILD_DIR} cmake .. -DASCEND_CANN_PACKAGE_PATH${_ASCEND_INSTALL_PATH} make -j$(nproc) cd ${SCRIPT_DIR} ./build/main关键特征先source .../bin/setenv.bash初始化 CANN 运行环境导出ASCEND_HOME_PATH、LD_LIBRARY_PATH等经典两段式构建cmake ..生成构建系统 make -j$(nproc)并行编译直接运行./build/main不做 install、不做输出捕获。仓库中的 example/0_quickstart/0_hello_cann/run.sh 是该模式的增强版它额外source .../common/resolve_cann_env.sh并调用resolve_cann_env自动探测 CANN 安装路径见下文环境自动探测再进入build/目录执行 cmake 与 make最后打印可执行文件位置并运行./build/main。run.sh Pattern 2构建 安装 验证适用场景需要 install 步骤或有输出验证的样例。set -e _ASCEND_INSTALL_PATH$ASCEND_INSTALL_PATH source $_ASCEND_INSTALL_PATH/bin/setenv.bash rm -rf build mkdir -p build cmake -B build -DASCEND_CANN_PACKAGE_PATH${_ASCEND_INSTALL_PATH} cmake --build build -j cmake --install build ./build/main | tee output_msg.txt关键特征使用新式 cmake CLIcmake -B build指定构建目录、cmake --build build -j并行构建、cmake --install build执行安装规则通过| tee output_msg.txt将程序输出同时回显并捕获到文件便于后续比对验证。仓库中的 example/1_basic_features/event/0_event_status/run.sh 即采用 Pattern 2从ASCEND_HOME_PATH解析 CANN 路径并 sourcebin/setenv.bash若未设置环境变量则直接报错退出随后执行三条新式 cmake 命令最后./build/main | tee output_msg.txt。注意该脚本要求调用前已source cann_path/set_env.sh这是它比 Pattern 1 更依赖用户环境的原因。run.sh Pattern 3Full kernel 构建流水线适用场景Pattern C / Pattern D 样例需要 AscendC kernel 编译这是所有模式中自动化程度最高的一个。set -euo pipefail SCRIPT_DIR$(cd $(dirname ${BASH_SOURCE[0]}) pwd) EXAMPLE_DIR$(cd ${SCRIPT_DIR}/../../.. pwd) source ${EXAMPLE_DIR}/common/resolve_cann_env.sh resolve_cann_env detect_sample_env # 调用 set_sample_env.sh 自动检测 SOC_VERSION / ASCENDC_CMAKE_DIR # 构建参数 SOC_VERSION${SOC_VERSION} BUILD_TYPEDebug BUILD_DIR${SCRIPT_DIR}/build INSTALL_PREFIX${SCRIPT_DIR}/out cmake -B ${BUILD_DIR} \ -DSOC_VERSION${SOC_VERSION} \ -DCMAKE_BUILD_TYPE${BUILD_TYPE} \ -DCMAKE_INSTALL_PREFIX${INSTALL_PREFIX} \ -DASCEND_CANN_PACKAGE_PATH${ASCEND_INSTALL_PATH} cmake --build ${BUILD_DIR} -j$(nproc) cmake --install ${BUILD_DIR} # 运行 ${INSTALL_PREFIX}/bin/main ${RUN_MODE}关键特征使用set -euo pipefail严格模式任何一步失败立即终止通过 example/common/resolve_cann_env.sh 的resolve_cann_env自动定位 CANN 安装路径通过detect_sample_env调用 example/set_sample_env.sh自动检测SOC_VERSION/ASCENDC_CMAKE_DIR无需用户手动设置将SOC_VERSION/ASCENDC_CMAKE_DIR显式传给 cmake后者在 CMake 侧通过set(... $ENV{...})读取使用新式cmake --build/--installCLI最终从out/bin/运行带 run mode 参数的可执行文件。仓库实现 example/2_advanced_features/kernel/0_launch_kernel/run.sh 完整展示了这一流水线它定义detect_sample_env若SOC_VERSION、ASCENDC_CMAKE_DIR已导出则跳过检测校验环境变量与ascendc.cmake存在性后用getopt解析-r/--run-mode参数取值为simple或placeholder构建并 install 到out/随后生成测试数据、运行out/bin/ascendc_kernels_bbit最后用md5sum与 Python 脚本比对输出结果——这是构建 安装 验证在 kernel 场景下的完整闭环。run.sh Pattern 4多进程/多程序适用场景IPC、跨进程、跨服务器样例典型形态是proc_a.cppproc_b.cpp两个可执行文件或server.cppclient.cpp的服务端/客户端组合。实现要点这类样例无法用单一可执行文件验证脚本通常分别构建并启动多个程序并使用文件协调机制——进程间通过写 done 文件作为完成信号来同步时序避免竞态。仓库中 example/1_basic_features/memory/10_ipc_memory_withpid、example/1_basic_features/memory/11_ipc_memory_withoutpid 等 IPC 样例即属于此模式每个样例包含两个.cpp与各自的run.sh。环境自动探测resolve_cann_env.sh 与 set_sample_env.shrun.sh Pattern 3 之所以能做到零手动配置依赖 example 根目录的两个配套脚本这也是样例构建体系中重要的基础设施example/common/resolve_cann_env.sh的resolve_cann_env函数按优先级探测 CANN 安装路径环境变量ASCEND_INSTALL_PATH、ASCEND_HOME_PATH常用默认位置${HOME}/Ascend/cann、${HOME}/Ascend/ascend-toolkit/latest、/usr/local/Ascend/cann、/usr/local/Ascend/ascend-toolkit/latest、/opt/Ascend/cann对每个候选路径先确认存在set_env.sh或bin/setenv.bash再调用resolve_cann_has_acl_layout检查该路径是否存在标准的 ACL 布局include/acl/acl.hlib64/libacl_rt.so同时兼容arch-linux架构目录布局命中后导出ASCEND_INSTALL_PATH与ASCEND_HOME_PATH并 source 对应环境脚本全部失败则打印已检查路径清单并提示手动设置。example/set_sample_env.sh进一步自动检测SOC_VERSION与ASCENDC_CMAKE_DIR它会编译并运行 example/tools/get_soc_version/get_soc_version.cpp这个小工具直接调用aclrtGetSocName()获取与样例构建完全一致的 SOC 名称字符串get_soc_version.cpp注释明确说明该接口无需aclInit因此 helper 轻量且快速再按架构候选路径如${cann_path}/tikcpp/ascendc_kernel_cmake定位包含ascendc.cmake的目录最终导出ASCEND_INSTALL_PATH、ASCEND_HOME_PATH、SOC_VERSION、ASCENDC_CMAKE_DIR四个变量。以source方式执行即可在当前 shell 生效。模式选择决策树将上述模式串起来可形成如下决策路径是否使用 aclnn 预置算子 ├── 否 → 是否使用自定义 AscendC kernel │ ├── 否 → Pattern A (ACL-only) │ └── 是 → 是否使用 调用语法kernel launch │ ├── 否 → Pattern C (ascendc_library) │ └── 是 → Pattern D (ascendc_fatbin_library) └── 是 → 是否使用 model RI 或其他高级 API ├── 否 → Pattern B (ACLopapi) └── 是 → Pattern B 可能需要 repo 未发布头文件 可能需要特定链接库 是否是 profiling/adump ├── 是 → Pattern E (特定库)对应 run.sh 的选择Pattern A / B → run.sh Pattern 1 或 2Pattern C / D → run.sh Pattern 3kernel 编译必须走自动检测流水线多进程/多程序IPC、跨服务器→ run.sh Pattern 4。常见问题与排错建议结合上述模式特征编译样例时的常见问题可以快速定位SOC_VERSION未定义 /ASCENDC_CMAKE_DIR为空说明走了 Pattern C/D 却没有执行 Pattern 3 的 run.sh或set_sample_env.sh检测失败。确认 CANN 安装路径下存在tikcpp/ascendc_kernel_cmake/ascendc.cmake并以source方式运行set_sample_env.sh后再编译。找不到aclnnop/aclnn_add.hPattern B 必须 include${ASCEND_CANN_PACKAGE_PATH}/aclnn并链接libnnopbase.so与libopapi.so三者缺一不可。链接libascendcl.so与libacl_rt.so的选择困惑kernel launch 场景Pattern D用libacl_rt.so纯 ACL/算子场景Pattern A/B用libascendcl.soPattern C 则直接用 CMake target 名ascendcl。链接期GLIBCXX相关符号错误确认编译选项包含-D_GLIBCXX_USE_CXX11_ABI0与 CANN 安装包预编译库保持一致。运行期找不到.so检查是否 source 了setenv.bash或参考 Pattern D 的out/lib路径配置LD_LIBRARY_PATH。总结CANN Runtime 样例构建体系通过 5 种 CMake 模式覆盖纯 ACL → aclnn 算子 → 自定义 AscendC kernel → kernel launch → 性能/精度工具的完整能力梯度并以 4 种 run.sh 模式解决环境准备、构建、安装、验证与多进程编排的自动化问题。编写新样例时只需对照决策树选定 CMake 与 run.sh 模式再参考仓库中对应代表样例的CMakeLists.txt与run.sh拷贝改造即可这也是该模式参考文档被沉淀为样例生成工具核心参考资料的原因。【免费下载链接】runtime本项目提供CANN运行时组件和维测功能组件。项目地址: https://gitcode.com/cann/runtime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考