graph-autofusion 编译构建全攻略build.sh 参数详解、增量编译与常见报错排查实战【免费下载链接】graph-autofusionGraph-autofusion 是一个面向昇腾Ascend芯片的轻量级、解耦式组件集合旨在通过自动融合技术加速模型执行。 目前已开源 SuperKernel 组件和 Autofuse 组件未来将持续开放更多自动融合相关模块。项目地址: https://gitcode.com/cann/graph-autofusion本指南以 graph-autofusion 仓库中的构建辅助技能文档为核心骨架围绕项目根目录的build.sh统一构建入口系统讲解编译、打包、测试运行、环境配置与第三方依赖管理的完整实操流程并结合 build.sh 源码与 docs/zh/build.md 官方文档做纵深解读。读完本文你将掌握如何避免编译 OOM 与超时、如何用增量编译实现秒级迭代、如何按模块运行 UT/ST、如何完成离线编译与.run包安装卸载以及常见编译错误的精准定位与修复。一、构建入口与核心参数总览graph-autofusion 使用项目根目录的 build.sh 作为统一构建入口支持编译、打包、测试、覆盖率采集等全部构建动作。其完整用法为sh build.sh [-h|--help] [--pkg] [-u|--ut] [-s|--st] [--implpy|cpp|all] [--modulename] [-c|--coverage] [-j N] [--build-typeTYPE] [--no-autofuse] [--output_pathPATH] [--cann_3rd_lib_pathPATH] [--run_example] [--test_caseFILTER]各参数含义与源码 build.sh 的usage()逐一对应参数说明取值/默认值-h, --help打印用法说明—--pkg构建并打包生成.run运行包开/关--no-autofuse跳过 autofuse 后端编译仅编译 SuperKernel开/关-j N编译线程数默认取 CPU 核数文档与源码均强调必须显式限制-u, --ut运行单元测试开/关-s, --st运行系统测试开/关--implpy\|cpp\|all选择测试实现类型默认 all--modulename选择测试模块superkernel / autofuse_framework / autofuse_ascendc_api / autofuse_e2e / all-c, --coverage带覆盖率报告运行测试开/关--output_pathPATH运行包输出目录默认./build_out--cann_3rd_lib_pathPATH第三方依赖包路径默认./output/third_party--build-typeTYPE编译类型Debug / Release默认 Release--pkg-typeTYPE打包类型run / rpm / deb默认 run-f FILE变更文件清单文件用于智能模块选择详见后文文件路径几个从源码确认的关键行为必须带参数运行源码 checkopts() 中build.sh无参数时直接报错退出has no options available, please select at least one option!因此sh build.sh裸跑是无效的。-j 校验严格check_param_j()只接受正整数超过 CPU 核数时会被钳制为核数build.sh#L88-L105。--module只影响测试范围不影响编译范围编译始终全量执行要限制编译范围应改用cmake --build build --target target后文详解。新增参数源码中已实现SKILL 文档未列全--pkg-typerun/rpm/deb、-f FILE智能模块选择、--autofuse与--no-autofuse对应显式开启 autofuse。二、两条铁律编译必须加 -j、警惕编译超时2.1 为什么必须指定-j 8编译默认并行度无限制。在 build.sh 中CPU_NUM$(($(cat /proc/cpuinfo | grep ^processor | wc -l))) THREAD_NUM${CPU_NUM}即默认线程数等于机器全部 CPU 核数多核服务器上并行编译会瞬间吃满内存导致OOMKilled。因此所有编译命令必须指定-j 8或合理线程数否则默认无限制会导致 OOM。2.2 编译超时与三套解决方案全量编译 autofuse 组件耗时较长通常 15–30 分钟可能超过工具的执行超时限制。解决方案按优先级排列方案一优先增量编译推荐。已有build/目录时只重编变更的源文件cmake --build build --target target -j 8方案二后台运行全量编译。用nohup避免超时中断# 后台运行日志写入 build.log nohup sh build.sh --pkg -j 8 build.log 21 # 查看编译进度 tail -f build.log # 检查编译是否完成 ps aux | grep build.sh | grep -v grep方案三分阶段编译。拆成多个可短时完成的子任务# 先编译核心库 cmake --build build --target aihac_codegen -j 8 # 再编译测试目标 cmake --build build --target test_common -j 8检查编译产物ls -la build/cann-graph-autofusion_*.run ls -la build/autofuse/tests/ut/common/test_common三、增量编译日常开发首选CMake 天然支持增量编译build/目录已存在时只重编译变更的源文件日常开发应优先增量编译避免全量重建。3.1 判断是否需要全量重建场景是否需要全量说明修改了.cpp/.h/.py源码否增量编译即可修改了CMakeLists.txt否CMake 自动检测并重新 configure切换 Debug/Release是编译选项变化需清理build/首次编译是无build/目录切换了 CANN Toolkit 版本是头文件和库路径变化添加了新的源文件否CMake 的CONFIGURE_DEPENDS/GLOB_RECURSE会自动发现3.2 三种增量编译方式# 方式一通过 build.sh自动 configure build未变更文件不重编 sh build.sh --pkg -j 8 # 方式二直接 cmake --build跳过 configure最快适用于源码修改 cmake --build build --target ascendsk -j 8 # 只重编 SuperKernel cmake --build build --target aihac_codegen -j 8 # 只重编 autofuse 核心库 cmake --build build --target pyautofuse -j 8 # 只重编 Python 绑定 cmake --build build -j 8 # 增量编译所有目标 # 方式三只编译指定目标后直接打包 cmake --build build --target ascendsk -j 8 cmake --build build --target package -j 83.3 单目标增量编译参考表根据修改的源码区域选择对应的编译目标.so产物路径已在仓库 CMake 配置中确认如 autofuse/CMakeLists.txt 定义aihac_codegen、super_kernel/CMakeLists.txt 定义ascendsk修改的源码目录编译目标.so 产物super_kernel/src/ascendskbuild/super_kernel/libascendsk.sosuper_kernel/kernel/ascendsk含 sk_scope 子目标build/super_kernel/libascendsk.sosuper_kernel/*.pysuperkernel_whlbuild/super_kernel/superkernel-*.whlautofuse/codegen/aihac_codegenbuild/autofuse/libaihac_codegen.soautofuse/optimize/aihac_codegenbuild/autofuse/libaihac_codegen.soautofuse/ascir/aihac_codegen含ascir、ascir_builtin_opsbuild/autofuse/libaihac_codegen.soautofuse/graph_metadef/graph/graph_af、graph_base_af、aihac_ir等各自.soautofuse/compiler/py_module/pyautofusebuild/autofuse/compiler/py_module/pyautofuse.soautofuse/att/aihac_codegenbuild/autofuse/libaihac_codegen.soautofuse/common/aihac_codegenbuild/autofuse/libaihac_codegen.so说明ascir、ascir_builtin_ops等子目标会通过target_sources汇聚进aihac_codegen见 autofuse/ascir/generator/CMakeLists.txt因此修改 ascir 区域统一重编aihac_codegen即可。3.4 快速迭代工作流修改代码后快速验证、不打包# 1. 增量编译目标库 cmake --build build --target ascendsk -j 8 # 2. 直接运行测试验证 sh build.sh -u --modulesuperkernel --implpy # 或 sh build.sh -u --modulesuperkernel --implcpp --test_case*SkEntry*3.5 换 .so替换动态库快速验证需要把编译产物部署到 CANN 安装目录或其他环境时# 增量编译目标 cmake --build build --target ascendsk -j 8 cmake --build build --target aihac_codegen -j 8 # 替换到部署目录 cp build/super_kernel/libascendsk.so 部署路径/lib64/ cp build/autofuse/libaihac_codegen.so 部署路径/lib64/ # 或通过 LD_LIBRARY_PATH 优先加载 export LD_LIBRARY_PATH$(pwd)/build/super_kernel:$(pwd)/build/autofuse:$LD_LIBRARY_PATH注意换.so需确保 ABI 兼容相同编译选项、相同编译器版本、相同 Build Type。否则会出现链接期/运行期符号错误。四、全量编译仅在必要时使用首次编译、切换 Build Type、切换 Toolkit 版本# 清理后全量重建 rm -rf build sh build.sh --pkg -j 8 # 切换 Debug 模式需全量 rm -rf build sh build.sh --pkg --build-typeDebug -j 8从源码看cmake_config()会将-DCMAKE_BUILD_TYPE${BUILD_TYPE}传给 CMakebuild.shBuild Type 变化后旧缓存会冲突因此必须先清理build/。五、常用构建命令实战5.1 编译# 编译并打包Release 模式最常用已有 build/ 时自动增量 sh build.sh --pkg -j 8 # Debug 模式编译切换 Build Type 需全量 rm -rf build sh build.sh --pkg --build-typeDebug -j 8 # 跳过 autofuse 后端编译只编 SuperKernel sh build.sh --pkg --no-autofuse -j 8再次强调--no-autofuse会向 CMake 传递-DBUILD_AUTOFUSEOFF见 build.sh仅影响编译范围。5.2 打包# 构建运行包已有 build/ 时增量编译后打包 sh build.sh --pkg -j 8 # 只重新打包不重编适用于已编译完成只需生成 .run 包 cmake --build build --target package -j 8 # 指定输出路径 sh build.sh --pkg --output_path/path/to/output -j 8打包流程在源码build_package()build.sh中实现先cmake --build . --target all package再将_CPack_Packages/makeself_staging/下的cann-graph-autofusion*.run拷贝到输出目录默认build_out/。5.3 运行测试# SuperKernel Python UT sh build.sh -u --modulesuperkernel --implpy # SuperKernel C UT sh build.sh -u --modulesuperkernel --implcpp # SuperKernel Python ST sh build.sh -s --modulesuperkernel --implpy # Autofuse Framework UT sh build.sh -u --moduleautofuse_framework # Autofuse AscendC API UT sh build.sh -u --moduleautofuse_ascendc_api # Autofuse E2E ST sh build.sh -s --moduleautofuse_e2e # 带覆盖率报告 sh build.sh -u --modulesuperkernel -c # 运行指定的 C UT 用例gtest filter sh build.sh -u --modulesuperkernel --implcpp --test_case*SkEntry*注意autofuse_e2e模块只支持 ST-s不支持 UT-u。这一约束在源码 build.sh 的MODULE_ACTION_HANDLERS中写死autofuse_e2e只注册了all_st动作。从源码看测试的底层调用链SuperKernel 测试py 测试实际执行pip install -e .[dev]后运行pytest tests/ut -m ut -n auto或pytest tests/st -m st -n autobuild.shcpp 测试则重新 configure CMake 并构建run_super_kernel_aot_utest/run_super_kernel_aot_stest目标build.sh。Autofuse 测试统一转调 scripts/test/run_autofuse_test.sh按模块映射为framework/ascendc_api/e2ebuild.sh。5.4 运行示例sh build.sh --run_example --modulesuperkernel5.5 智能模块选择-f FILE源码新增了-f FILE参数传入包含变更文件列表的文件analyze_changed_modules()会分析变更范围build.sh仅修改super_kernel/跳过 autofuse 编译与 autofuse 测试仅修改autofuse/跳过 superkernel 测试两者都改全量构建仅修改docs/、examples/、.claude/、.opencode/、README 等跳过全部构建退出码 200。该机制适合 CI 场景按变更范围做差异化构建可显著缩短流水线时间。六、支持的测试模块一览模块名说明支持的测试类型superkernelSuperKernel 组件UTpy/cpp、STpyautofuse_frameworkAutofuse 框架UT、STautofuse_ascendc_apiAutofuse AscendC APIUT、STautofuse_e2eAutofuse 端到端测试仅 ST七、环境依赖与环境变量7.1 依赖版本要求依赖版本要求CANN Toolkit 9.1.0使用/cann-toolkit-installer安装Python3 3.8.0建议 3.9使用虚拟环境CMake 3.16.0bash 5.0补充说明来自 docs/zh/build.mdGCC 7.3.0默认使用环境已装 gcc/g如需切换到 gcc15/gcc16可显式设置export CCgcc-15 CXXg-15或GCC_VERSION15。7.2 必须 source CANN 环境变量编译前必须 source CANN 环境变量。set_env.sh位于ASCEND_HOME_PATH目录下# 如果 ASCEND_HOME_PATH 已设置 source ${ASCEND_HOME_PATH}/set_env.sh # 常见安装路径按优先级尝试 source /home/developer/Ascend/master/cann-9.1.0/set_env.sh # master 构建版本 source /home/developer/Ascend/cann-9.0.0/set_env.sh # 发布版本 source /usr/local/Ascend/cann/set_env.sh # 系统级安装注意项目源码依赖 CANN 9.1.0 的 API如sk::SkSystemArgs使用低版本 Toolkit 会编译报错no type named SkSystemArgs优先使用 master 路径下的 Toolkit。ASCEND_HOME_PATH会通过build.sh的CUSTOM_OPTION以-DASCEND_INSTALL_PATH传入 CMakebuild.sh。7.3 验证环境# 检查 ASCEND_HOME_PATH 是否设置 echo $ASCEND_HOME_PATH # 检查 atc 工具是否存在 ls ${ASCEND_HOME_PATH}/bin/atc # 检查 set_env.sh 是否存在 ls ${ASCEND_HOME_PATH}/set_env.sh也可运行仓库自带的 scripts/check_env.sh 一键体检输出[PASS]/[WARNING]/[ERROR]三档结果详见 docs/zh/build.md 4.2.2 节。八、第三方依赖管理首次编译会自动下载第三方依赖到output/third_party/后续编译跳过此步骤。离线环境需手动下载并放到open_source/目录针对 makeself、cann-cmake详见 docs/zh/build.md。指定第三方库路径sh build.sh --cann_3rd_lib_path/path/to/third_party -j 88.1 网络与代理问题编译过程中 CMake 通过ExternalProject_Add从外网自动下载 autofuse 和 superkernel AOT UT 所需第三方源码包abseil-cpp、boost、json、protobuf、symengine、googletest、mockcpp 等。内网/Docker 环境无法直连外网时方案一配置代理推荐。build.sh会自动检测并继承 shell 中的http_proxy/https_proxy环境变量源码 build.sh 会打印代理检测信息export http_proxyhttp://user:passwordproxy-server:port export https_proxyhttp://user:passwordproxy-server:port bash build.sh --pkg方案二手动预下载离线编译。在联网机器上预先下载第三方包abseil-cpp 20230802.1、json 3.11.3、boost 1.87.0、protobuf 25.1、symengine 0.12.0、googletest 1.14.0、mockcpp 2.7 mockcpp-2.7-h5.patch、makeself 2.5.0 等下载地址清单见 docs/zh/build.md拷贝到output/third_party/对应子目录后编译# 创建目录结构 mkdir -p output/third_party/{abseil-cpp,json,boost,protobuf,symengine,gtest,mockcpp,makeself} # 将包放入对应目录再指定路径编译 bash build.sh --pkg --cann_3rd_lib_path$(pwd)/output/third_party关键细节mockcpp-2.7-h5.patch是 mockcpp 编译必需的补丁CMake 会在解压后自动执行git init git apply应用优先查找output/third_party/mockcpp-2.7-h5.patch备用路径output/third_party/pkg/若缺失离线环境会构建失败。同时必须保证 CANN 安装路径安装.run包与 cann-toolkit 的路径一致与构建环境匹配。九、编译产物说明9.1 目录结构build/ # 编译中间文件CMAKE_INSTALL_PREFIX ├── super_kernel/ │ ├── libascendsk.so # SuperKernel 动态库 │ └── superkernel-*.whl # Python wheel 包 ├── autofuse/ │ ├── libaihac_codegen.so # autofuse 编译器核心库 │ ├── compiler/py_module/pyautofuse.so # Python 绑定 │ ├── ascir/meta/libascir.so │ ├── ascir/generator/libascir_builtin_ops.so │ ├── graph_metadef/graph/ │ │ ├── libgraph_af.so │ │ ├── libgraph_base_af.so │ │ ├── expression/libaihac_symbolizer_af.so │ │ └── ascendc_ir/ │ │ ├── libaihac_ir.so │ │ └── generator/ │ │ ├── libascir_generate.so │ │ └── libaihac_ir_register.so │ └── tests/ # 测试专用 .so仅测试时生成 └── _CPack_Packages/ # 打包中间文件 build_out/ # 最终输出 └── cann-graph-autofusion_*.run # 运行包可部署9.2 正式产物 .so 清单11 个.so编译目标说明libascendsk.soascendskSuperKernel 动态库libaihac_codegen.soaihac_codegenAutofuse 编译器核心libgraph_af.sograph_af图定义库libgraph_base_af.sograph_base_af图基础设施libaihac_ir.soaihac_irAIHAC IRlibaihac_ir_register.soaihac_ir_registerAIHAC IR 注册libaihac_symbolizer_af.soaihac_symbolizer_af符号化库libascir.soascirASCIR 中间表示libascir_builtin_ops.soascir_builtin_opsASCIR 内置算子libascir_generate.soascir_generateASCIR 代码生成pyautofuse.sopyautofusePython 绑定模块十、run 包安装与卸载测试前置条件重要执行 UT/ST 测试前必须先安装编译生成的.run包。否则测试运行时LD_LIBRARY_PATH会加载到 CANN 安装路径下的旧版本动态库导致undefined symbol等运行时错误。安装# 如需指定安装路径则加上 --install-path${install_path} ./build_out/cann-graph-autofusion_${cann_version}_linux-${arch}.run --full --quiet --pylocal--full全量模式安装--install-path指定安装路径默认/usr/local/Ascendroot 用户或${HOME}/Ascend非 root 用户且需与 cann-toolkit 安装路径保持一致--quiet静默安装跳过人机交互--pylocal将包内.whl跟随 run 包路径安装否则装入本地 python 的 site-packages。卸载# 指定路径安装时同样加上 --install-path ./build_out/cann-graph-autofusion_${cann_version}_linux-${arch}.run --uninstall安装完成后可参考 super_kernel/examples/README.md 与 autofuse/examples/pytorch/README.md 尝试运行样例。十一、常见编译错误排查问题根因解决方案no type named SkSystemArgsCANN Toolkit 版本过低使用 9.1.0执行source /home/developer/Ascend/master/cann-9.1.0/set_env.sh切换 master 版本CANN Toolkit 未找到ASCEND_HOME_PATH未设置或未安装执行source ${ASCEND_HOME_PATH}/set_env.sh未安装则使用/cann-toolkit-installer安装编译 OOMKilled编译默认并行度无限制必须使用-j 8限制并行线程数第三方依赖下载失败网络不通 / 缺离线包配置代理或手动下载到output/third_party/mockcpp 需同时准备 patch 文件CMake 版本过低环境 CMake 过旧升级到 3.16.0Python 版本不兼容环境 Python 过旧使用 Python 3.9 虚拟环境增量编译后链接错误切换了 Build Type 或 Toolkit 版本但未清理build/执行rm -rf build后全量重建十二、结语一条可落地的构建工作流综合 SKILL 文档与仓库源码推荐一条经过验证的日常构建路径环境准备安装 CANN Toolkit 9.1.0source ${ASCEND_HOME_PATH}/set_env.sh创建 Python 3.9 虚拟环境并pip3 install -r super_kernel/requirements-dev.txt运行 scripts/check_env.sh 体检首次全量编译rm -rf build sh build.sh --pkg -j 8确保第三方依赖自动下载或离线就绪日常迭代修改源码后cmake --build build --target 目标 -j 8增量编译配合sh build.sh -u --module模块 --implpy|cpp快速验证发版打包sh build.sh --pkg -j 8生成build_out/cann-graph-autofusion_*.run安装后执行 UT/ST 全量回归sh build.sh -u/-s -c可同时采集覆盖率。把「加-j 8」「优先增量」「切 Build Type/Toolkit 必清 build」「UT/ST 前先装 run 包」四条铁律内化成习惯就能在 graph-autofusion 的编译构建上少踩绝大多数坑。【免费下载链接】graph-autofusionGraph-autofusion 是一个面向昇腾Ascend芯片的轻量级、解耦式组件集合旨在通过自动融合技术加速模型执行。 目前已开源 SuperKernel 组件和 Autofuse 组件未来将持续开放更多自动融合相关模块。项目地址: https://gitcode.com/cann/graph-autofusion创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
graph-autofusion 编译构建全攻略：build.sh 参数详解、增量编译与常见报错排查实战
graph-autofusion 编译构建全攻略build.sh 参数详解、增量编译与常见报错排查实战【免费下载链接】graph-autofusionGraph-autofusion 是一个面向昇腾Ascend芯片的轻量级、解耦式组件集合旨在通过自动融合技术加速模型执行。 目前已开源 SuperKernel 组件和 Autofuse 组件未来将持续开放更多自动融合相关模块。项目地址: https://gitcode.com/cann/graph-autofusion本指南以 graph-autofusion 仓库中的构建辅助技能文档为核心骨架围绕项目根目录的build.sh统一构建入口系统讲解编译、打包、测试运行、环境配置与第三方依赖管理的完整实操流程并结合 build.sh 源码与 docs/zh/build.md 官方文档做纵深解读。读完本文你将掌握如何避免编译 OOM 与超时、如何用增量编译实现秒级迭代、如何按模块运行 UT/ST、如何完成离线编译与.run包安装卸载以及常见编译错误的精准定位与修复。一、构建入口与核心参数总览graph-autofusion 使用项目根目录的 build.sh 作为统一构建入口支持编译、打包、测试、覆盖率采集等全部构建动作。其完整用法为sh build.sh [-h|--help] [--pkg] [-u|--ut] [-s|--st] [--implpy|cpp|all] [--modulename] [-c|--coverage] [-j N] [--build-typeTYPE] [--no-autofuse] [--output_pathPATH] [--cann_3rd_lib_pathPATH] [--run_example] [--test_caseFILTER]各参数含义与源码 build.sh 的usage()逐一对应参数说明取值/默认值-h, --help打印用法说明—--pkg构建并打包生成.run运行包开/关--no-autofuse跳过 autofuse 后端编译仅编译 SuperKernel开/关-j N编译线程数默认取 CPU 核数文档与源码均强调必须显式限制-u, --ut运行单元测试开/关-s, --st运行系统测试开/关--implpy\|cpp\|all选择测试实现类型默认 all--modulename选择测试模块superkernel / autofuse_framework / autofuse_ascendc_api / autofuse_e2e / all-c, --coverage带覆盖率报告运行测试开/关--output_pathPATH运行包输出目录默认./build_out--cann_3rd_lib_pathPATH第三方依赖包路径默认./output/third_party--build-typeTYPE编译类型Debug / Release默认 Release--pkg-typeTYPE打包类型run / rpm / deb默认 run-f FILE变更文件清单文件用于智能模块选择详见后文文件路径几个从源码确认的关键行为必须带参数运行源码 checkopts() 中build.sh无参数时直接报错退出has no options available, please select at least one option!因此sh build.sh裸跑是无效的。-j 校验严格check_param_j()只接受正整数超过 CPU 核数时会被钳制为核数build.sh#L88-L105。--module只影响测试范围不影响编译范围编译始终全量执行要限制编译范围应改用cmake --build build --target target后文详解。新增参数源码中已实现SKILL 文档未列全--pkg-typerun/rpm/deb、-f FILE智能模块选择、--autofuse与--no-autofuse对应显式开启 autofuse。二、两条铁律编译必须加 -j、警惕编译超时2.1 为什么必须指定-j 8编译默认并行度无限制。在 build.sh 中CPU_NUM$(($(cat /proc/cpuinfo | grep ^processor | wc -l))) THREAD_NUM${CPU_NUM}即默认线程数等于机器全部 CPU 核数多核服务器上并行编译会瞬间吃满内存导致OOMKilled。因此所有编译命令必须指定-j 8或合理线程数否则默认无限制会导致 OOM。2.2 编译超时与三套解决方案全量编译 autofuse 组件耗时较长通常 15–30 分钟可能超过工具的执行超时限制。解决方案按优先级排列方案一优先增量编译推荐。已有build/目录时只重编变更的源文件cmake --build build --target target -j 8方案二后台运行全量编译。用nohup避免超时中断# 后台运行日志写入 build.log nohup sh build.sh --pkg -j 8 build.log 21 # 查看编译进度 tail -f build.log # 检查编译是否完成 ps aux | grep build.sh | grep -v grep方案三分阶段编译。拆成多个可短时完成的子任务# 先编译核心库 cmake --build build --target aihac_codegen -j 8 # 再编译测试目标 cmake --build build --target test_common -j 8检查编译产物ls -la build/cann-graph-autofusion_*.run ls -la build/autofuse/tests/ut/common/test_common三、增量编译日常开发首选CMake 天然支持增量编译build/目录已存在时只重编译变更的源文件日常开发应优先增量编译避免全量重建。3.1 判断是否需要全量重建场景是否需要全量说明修改了.cpp/.h/.py源码否增量编译即可修改了CMakeLists.txt否CMake 自动检测并重新 configure切换 Debug/Release是编译选项变化需清理build/首次编译是无build/目录切换了 CANN Toolkit 版本是头文件和库路径变化添加了新的源文件否CMake 的CONFIGURE_DEPENDS/GLOB_RECURSE会自动发现3.2 三种增量编译方式# 方式一通过 build.sh自动 configure build未变更文件不重编 sh build.sh --pkg -j 8 # 方式二直接 cmake --build跳过 configure最快适用于源码修改 cmake --build build --target ascendsk -j 8 # 只重编 SuperKernel cmake --build build --target aihac_codegen -j 8 # 只重编 autofuse 核心库 cmake --build build --target pyautofuse -j 8 # 只重编 Python 绑定 cmake --build build -j 8 # 增量编译所有目标 # 方式三只编译指定目标后直接打包 cmake --build build --target ascendsk -j 8 cmake --build build --target package -j 83.3 单目标增量编译参考表根据修改的源码区域选择对应的编译目标.so产物路径已在仓库 CMake 配置中确认如 autofuse/CMakeLists.txt 定义aihac_codegen、super_kernel/CMakeLists.txt 定义ascendsk修改的源码目录编译目标.so 产物super_kernel/src/ascendskbuild/super_kernel/libascendsk.sosuper_kernel/kernel/ascendsk含 sk_scope 子目标build/super_kernel/libascendsk.sosuper_kernel/*.pysuperkernel_whlbuild/super_kernel/superkernel-*.whlautofuse/codegen/aihac_codegenbuild/autofuse/libaihac_codegen.soautofuse/optimize/aihac_codegenbuild/autofuse/libaihac_codegen.soautofuse/ascir/aihac_codegen含ascir、ascir_builtin_opsbuild/autofuse/libaihac_codegen.soautofuse/graph_metadef/graph/graph_af、graph_base_af、aihac_ir等各自.soautofuse/compiler/py_module/pyautofusebuild/autofuse/compiler/py_module/pyautofuse.soautofuse/att/aihac_codegenbuild/autofuse/libaihac_codegen.soautofuse/common/aihac_codegenbuild/autofuse/libaihac_codegen.so说明ascir、ascir_builtin_ops等子目标会通过target_sources汇聚进aihac_codegen见 autofuse/ascir/generator/CMakeLists.txt因此修改 ascir 区域统一重编aihac_codegen即可。3.4 快速迭代工作流修改代码后快速验证、不打包# 1. 增量编译目标库 cmake --build build --target ascendsk -j 8 # 2. 直接运行测试验证 sh build.sh -u --modulesuperkernel --implpy # 或 sh build.sh -u --modulesuperkernel --implcpp --test_case*SkEntry*3.5 换 .so替换动态库快速验证需要把编译产物部署到 CANN 安装目录或其他环境时# 增量编译目标 cmake --build build --target ascendsk -j 8 cmake --build build --target aihac_codegen -j 8 # 替换到部署目录 cp build/super_kernel/libascendsk.so 部署路径/lib64/ cp build/autofuse/libaihac_codegen.so 部署路径/lib64/ # 或通过 LD_LIBRARY_PATH 优先加载 export LD_LIBRARY_PATH$(pwd)/build/super_kernel:$(pwd)/build/autofuse:$LD_LIBRARY_PATH注意换.so需确保 ABI 兼容相同编译选项、相同编译器版本、相同 Build Type。否则会出现链接期/运行期符号错误。四、全量编译仅在必要时使用首次编译、切换 Build Type、切换 Toolkit 版本# 清理后全量重建 rm -rf build sh build.sh --pkg -j 8 # 切换 Debug 模式需全量 rm -rf build sh build.sh --pkg --build-typeDebug -j 8从源码看cmake_config()会将-DCMAKE_BUILD_TYPE${BUILD_TYPE}传给 CMakebuild.shBuild Type 变化后旧缓存会冲突因此必须先清理build/。五、常用构建命令实战5.1 编译# 编译并打包Release 模式最常用已有 build/ 时自动增量 sh build.sh --pkg -j 8 # Debug 模式编译切换 Build Type 需全量 rm -rf build sh build.sh --pkg --build-typeDebug -j 8 # 跳过 autofuse 后端编译只编 SuperKernel sh build.sh --pkg --no-autofuse -j 8再次强调--no-autofuse会向 CMake 传递-DBUILD_AUTOFUSEOFF见 build.sh仅影响编译范围。5.2 打包# 构建运行包已有 build/ 时增量编译后打包 sh build.sh --pkg -j 8 # 只重新打包不重编适用于已编译完成只需生成 .run 包 cmake --build build --target package -j 8 # 指定输出路径 sh build.sh --pkg --output_path/path/to/output -j 8打包流程在源码build_package()build.sh中实现先cmake --build . --target all package再将_CPack_Packages/makeself_staging/下的cann-graph-autofusion*.run拷贝到输出目录默认build_out/。5.3 运行测试# SuperKernel Python UT sh build.sh -u --modulesuperkernel --implpy # SuperKernel C UT sh build.sh -u --modulesuperkernel --implcpp # SuperKernel Python ST sh build.sh -s --modulesuperkernel --implpy # Autofuse Framework UT sh build.sh -u --moduleautofuse_framework # Autofuse AscendC API UT sh build.sh -u --moduleautofuse_ascendc_api # Autofuse E2E ST sh build.sh -s --moduleautofuse_e2e # 带覆盖率报告 sh build.sh -u --modulesuperkernel -c # 运行指定的 C UT 用例gtest filter sh build.sh -u --modulesuperkernel --implcpp --test_case*SkEntry*注意autofuse_e2e模块只支持 ST-s不支持 UT-u。这一约束在源码 build.sh 的MODULE_ACTION_HANDLERS中写死autofuse_e2e只注册了all_st动作。从源码看测试的底层调用链SuperKernel 测试py 测试实际执行pip install -e .[dev]后运行pytest tests/ut -m ut -n auto或pytest tests/st -m st -n autobuild.shcpp 测试则重新 configure CMake 并构建run_super_kernel_aot_utest/run_super_kernel_aot_stest目标build.sh。Autofuse 测试统一转调 scripts/test/run_autofuse_test.sh按模块映射为framework/ascendc_api/e2ebuild.sh。5.4 运行示例sh build.sh --run_example --modulesuperkernel5.5 智能模块选择-f FILE源码新增了-f FILE参数传入包含变更文件列表的文件analyze_changed_modules()会分析变更范围build.sh仅修改super_kernel/跳过 autofuse 编译与 autofuse 测试仅修改autofuse/跳过 superkernel 测试两者都改全量构建仅修改docs/、examples/、.claude/、.opencode/、README 等跳过全部构建退出码 200。该机制适合 CI 场景按变更范围做差异化构建可显著缩短流水线时间。六、支持的测试模块一览模块名说明支持的测试类型superkernelSuperKernel 组件UTpy/cpp、STpyautofuse_frameworkAutofuse 框架UT、STautofuse_ascendc_apiAutofuse AscendC APIUT、STautofuse_e2eAutofuse 端到端测试仅 ST七、环境依赖与环境变量7.1 依赖版本要求依赖版本要求CANN Toolkit 9.1.0使用/cann-toolkit-installer安装Python3 3.8.0建议 3.9使用虚拟环境CMake 3.16.0bash 5.0补充说明来自 docs/zh/build.mdGCC 7.3.0默认使用环境已装 gcc/g如需切换到 gcc15/gcc16可显式设置export CCgcc-15 CXXg-15或GCC_VERSION15。7.2 必须 source CANN 环境变量编译前必须 source CANN 环境变量。set_env.sh位于ASCEND_HOME_PATH目录下# 如果 ASCEND_HOME_PATH 已设置 source ${ASCEND_HOME_PATH}/set_env.sh # 常见安装路径按优先级尝试 source /home/developer/Ascend/master/cann-9.1.0/set_env.sh # master 构建版本 source /home/developer/Ascend/cann-9.0.0/set_env.sh # 发布版本 source /usr/local/Ascend/cann/set_env.sh # 系统级安装注意项目源码依赖 CANN 9.1.0 的 API如sk::SkSystemArgs使用低版本 Toolkit 会编译报错no type named SkSystemArgs优先使用 master 路径下的 Toolkit。ASCEND_HOME_PATH会通过build.sh的CUSTOM_OPTION以-DASCEND_INSTALL_PATH传入 CMakebuild.sh。7.3 验证环境# 检查 ASCEND_HOME_PATH 是否设置 echo $ASCEND_HOME_PATH # 检查 atc 工具是否存在 ls ${ASCEND_HOME_PATH}/bin/atc # 检查 set_env.sh 是否存在 ls ${ASCEND_HOME_PATH}/set_env.sh也可运行仓库自带的 scripts/check_env.sh 一键体检输出[PASS]/[WARNING]/[ERROR]三档结果详见 docs/zh/build.md 4.2.2 节。八、第三方依赖管理首次编译会自动下载第三方依赖到output/third_party/后续编译跳过此步骤。离线环境需手动下载并放到open_source/目录针对 makeself、cann-cmake详见 docs/zh/build.md。指定第三方库路径sh build.sh --cann_3rd_lib_path/path/to/third_party -j 88.1 网络与代理问题编译过程中 CMake 通过ExternalProject_Add从外网自动下载 autofuse 和 superkernel AOT UT 所需第三方源码包abseil-cpp、boost、json、protobuf、symengine、googletest、mockcpp 等。内网/Docker 环境无法直连外网时方案一配置代理推荐。build.sh会自动检测并继承 shell 中的http_proxy/https_proxy环境变量源码 build.sh 会打印代理检测信息export http_proxyhttp://user:passwordproxy-server:port export https_proxyhttp://user:passwordproxy-server:port bash build.sh --pkg方案二手动预下载离线编译。在联网机器上预先下载第三方包abseil-cpp 20230802.1、json 3.11.3、boost 1.87.0、protobuf 25.1、symengine 0.12.0、googletest 1.14.0、mockcpp 2.7 mockcpp-2.7-h5.patch、makeself 2.5.0 等下载地址清单见 docs/zh/build.md拷贝到output/third_party/对应子目录后编译# 创建目录结构 mkdir -p output/third_party/{abseil-cpp,json,boost,protobuf,symengine,gtest,mockcpp,makeself} # 将包放入对应目录再指定路径编译 bash build.sh --pkg --cann_3rd_lib_path$(pwd)/output/third_party关键细节mockcpp-2.7-h5.patch是 mockcpp 编译必需的补丁CMake 会在解压后自动执行git init git apply应用优先查找output/third_party/mockcpp-2.7-h5.patch备用路径output/third_party/pkg/若缺失离线环境会构建失败。同时必须保证 CANN 安装路径安装.run包与 cann-toolkit 的路径一致与构建环境匹配。九、编译产物说明9.1 目录结构build/ # 编译中间文件CMAKE_INSTALL_PREFIX ├── super_kernel/ │ ├── libascendsk.so # SuperKernel 动态库 │ └── superkernel-*.whl # Python wheel 包 ├── autofuse/ │ ├── libaihac_codegen.so # autofuse 编译器核心库 │ ├── compiler/py_module/pyautofuse.so # Python 绑定 │ ├── ascir/meta/libascir.so │ ├── ascir/generator/libascir_builtin_ops.so │ ├── graph_metadef/graph/ │ │ ├── libgraph_af.so │ │ ├── libgraph_base_af.so │ │ ├── expression/libaihac_symbolizer_af.so │ │ └── ascendc_ir/ │ │ ├── libaihac_ir.so │ │ └── generator/ │ │ ├── libascir_generate.so │ │ └── libaihac_ir_register.so │ └── tests/ # 测试专用 .so仅测试时生成 └── _CPack_Packages/ # 打包中间文件 build_out/ # 最终输出 └── cann-graph-autofusion_*.run # 运行包可部署9.2 正式产物 .so 清单11 个.so编译目标说明libascendsk.soascendskSuperKernel 动态库libaihac_codegen.soaihac_codegenAutofuse 编译器核心libgraph_af.sograph_af图定义库libgraph_base_af.sograph_base_af图基础设施libaihac_ir.soaihac_irAIHAC IRlibaihac_ir_register.soaihac_ir_registerAIHAC IR 注册libaihac_symbolizer_af.soaihac_symbolizer_af符号化库libascir.soascirASCIR 中间表示libascir_builtin_ops.soascir_builtin_opsASCIR 内置算子libascir_generate.soascir_generateASCIR 代码生成pyautofuse.sopyautofusePython 绑定模块十、run 包安装与卸载测试前置条件重要执行 UT/ST 测试前必须先安装编译生成的.run包。否则测试运行时LD_LIBRARY_PATH会加载到 CANN 安装路径下的旧版本动态库导致undefined symbol等运行时错误。安装# 如需指定安装路径则加上 --install-path${install_path} ./build_out/cann-graph-autofusion_${cann_version}_linux-${arch}.run --full --quiet --pylocal--full全量模式安装--install-path指定安装路径默认/usr/local/Ascendroot 用户或${HOME}/Ascend非 root 用户且需与 cann-toolkit 安装路径保持一致--quiet静默安装跳过人机交互--pylocal将包内.whl跟随 run 包路径安装否则装入本地 python 的 site-packages。卸载# 指定路径安装时同样加上 --install-path ./build_out/cann-graph-autofusion_${cann_version}_linux-${arch}.run --uninstall安装完成后可参考 super_kernel/examples/README.md 与 autofuse/examples/pytorch/README.md 尝试运行样例。十一、常见编译错误排查问题根因解决方案no type named SkSystemArgsCANN Toolkit 版本过低使用 9.1.0执行source /home/developer/Ascend/master/cann-9.1.0/set_env.sh切换 master 版本CANN Toolkit 未找到ASCEND_HOME_PATH未设置或未安装执行source ${ASCEND_HOME_PATH}/set_env.sh未安装则使用/cann-toolkit-installer安装编译 OOMKilled编译默认并行度无限制必须使用-j 8限制并行线程数第三方依赖下载失败网络不通 / 缺离线包配置代理或手动下载到output/third_party/mockcpp 需同时准备 patch 文件CMake 版本过低环境 CMake 过旧升级到 3.16.0Python 版本不兼容环境 Python 过旧使用 Python 3.9 虚拟环境增量编译后链接错误切换了 Build Type 或 Toolkit 版本但未清理build/执行rm -rf build后全量重建十二、结语一条可落地的构建工作流综合 SKILL 文档与仓库源码推荐一条经过验证的日常构建路径环境准备安装 CANN Toolkit 9.1.0source ${ASCEND_HOME_PATH}/set_env.sh创建 Python 3.9 虚拟环境并pip3 install -r super_kernel/requirements-dev.txt运行 scripts/check_env.sh 体检首次全量编译rm -rf build sh build.sh --pkg -j 8确保第三方依赖自动下载或离线就绪日常迭代修改源码后cmake --build build --target 目标 -j 8增量编译配合sh build.sh -u --module模块 --implpy|cpp快速验证发版打包sh build.sh --pkg -j 8生成build_out/cann-graph-autofusion_*.run安装后执行 UT/ST 全量回归sh build.sh -u/-s -c可同时采集覆盖率。把「加-j 8」「优先增量」「切 Build Type/Toolkit 必清 build」「UT/ST 前先装 run 包」四条铁律内化成习惯就能在 graph-autofusion 的编译构建上少踩绝大多数坑。【免费下载链接】graph-autofusionGraph-autofusion 是一个面向昇腾Ascend芯片的轻量级、解耦式组件集合旨在通过自动融合技术加速模型执行。 目前已开源 SuperKernel 组件和 Autofuse 组件未来将持续开放更多自动融合相关模块。项目地址: https://gitcode.com/cann/graph-autofusion创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
