Pull Request has been successfully merged by CANN-robot.
(Thank you for zhugexun_sjtu's contribution.)变更摘要
本 PR 是面向中文文档的去 msOpGen 化改造:将 docs/zh 中以 msOpGen 工具生成算子工程为主线的说明,改为引导开发者直接创建目录、编写 CMakeLists.txt,并通过 CANN 提供的 npu_op_* 系列 CMake 接口完成算子包声明、aclnn 代码生成与 Host/核函数侧库编译。改写内容与 examples/01_simd_cpp_api/02_features/99_acl_based/00_acl_compilation 样例保持一致,同时统一了 ASCEND_COMPUTE_UNIT 配置位置与核函数命名等表述。
主要改动
- 快速入门改为手写 CMake 工程:
aclnn_quick_start.md删除msOpGenJSON 原型与msopgen gen命令,改为创建op_host/op_kernel目录并给出顶层、op_host、op_kernel三层CMakeLists.txt,使用find_package(ASC)、npu_op_package、npu_op_code_gen、npu_op_library、npu_op_kernel_sources、npu_op_kernel_library、npu_op_package_add等接口。 - 编译部署流程调整:
basic_process.md将 CMakeLists.txt 内设置变量作为推荐方式(方式一),CMakePresets.json降为可选的解耦方式(方式二);编译命令由./build.sh改为cmake ..与make -j binary package,产物目录由build_out改为build。 - 配置项引用口径统一:
AddConfig.md、HcclServerType.md、op_compilation_migration.md、operator_prototype_definition.md中,ASCEND_COMPUTE_UNIT的取值说明由“CMakePresets.json中由msOpGen自动生成”改为“与 CMakeLists.txt 中设置的变量或CMakePresets.json中的字段一致”。 - 框架适配与术语表述更新:
tensorflow_framework.md移除msopgen ... -f tf命令,改为在framework/tf_plugin下编写插件并通过npu_op_library的TF_PLUGIN类型编译;glossary.md、overview.md将“自定义算子工程”定义改为基于 CMake 组织编译、由开发者直接编写。 - 辅助说明与示例清理:
external_sample_links.md删除 msOpGen 样例链接;naming_conversion_table.md改为按命名规则编写文件即可免于在npu_op_kernel_sources中指定KERNEL_FILE;kernel_operator_implementation.md与kernel_tiling_info_incorrect.md将自动生成模板/ref后缀等描述改为开发者编写时的约定。
变更摘要
本 PR 对 docs/zh 下 15 个文档进行去 msOpGen 化改造:不再以 msOpGen 工具生成算子工程为主线,改为引导开发者直接创建工程目录并编写 CMakeLists.txt,使用 CANN 提供的 npu_op_* 系列 CMake 接口声明算子包、生成 aclnn 单算子调用代码、编译 Host 侧与核函数(Kernel)侧库,写法与 examples/01_simd_cpp_api/02_features/99_acl_based/00_acl_compilation 样例保持一致。
主要改动
- 快速入门改为手写工程与 CMake:
aclnn_quick_start.md移除add_custom.json原型文件与msopgen gen -i ... -c ... -lan cpp -out ...命令,改为mkdir -p AddCustom/op_host AddCustom/op_kernel建目录,并给出顶层、op_host、op_kernel三份CMakeLists.txt,涉及find_package(ASC)、npu_op_package、npu_op_code_gen、npu_op_library、npu_op_kernel_sources、npu_op_kernel_library、npu_op_package_add。 - 编译部署流程改用 cmake/make:
basic_process.md将“在 CMakeLists.txt 中设置变量”提为推荐的方式一,CMakePresets.json降为可选的方式二;编译步骤由./build.sh改为mkdir -p build && cd build+cmake ..+make -j binary package,安装包路径由build_out改为build。 ASCEND_COMPUTE_UNIT取值规则统一:AddConfig.md、HcclServerType.md、2201_to_3510_guide/op_compilation_migration.md、operator_prototype_definition.md中,将该字段的填写规则从“CMakePresets.json中由 msOpGen 自动生成”改为“与 CMakeLists.txt 中设置的变量或CMakePresets.json中的字段一致”。- 框架适配与术语描述调整:
tensorflow_framework.md删除msopgen ... -f tf命令,改为在framework/tf_plugin目录编写适配插件并通过npu_op_library的TF_PLUGIN类型编译;glossary.md、overview.md将“自定义算子工程”重新定义为开发者直接编写、基于 CMake 组织编译的工程。 - 辅助文档同步清理:
external_sample_links.md去掉 msOpGen 样例条目;naming_conversion_table.md改为遵循命名规则即可省略npu_op_kernel_sources的KERNEL_FILE;kernel_operator_implementation.md、kernel_tiling_info_incorrect.md将“msOpGen 自动生成模板/ref后缀”改为开发者编写时的约定,cmake_function_reference.md概述同步改为开发者自行编写 CMakeLists.txt。


代码审查
审查结论
本次改动是纯文档变更(15 个文件),不涉及代码与构建脚本本身的可执行逻辑;整体方向(去 msOpGen 化、引导直接编写 CMakeLists.txt)内部基本自洽,但存在若干“只改了一半”的残留与示例不完整问题。
发现清单(按严重度)
| 优先级 | 文件:行 | 问题 |
|---|---|---|
| P2 | aclnn_quick_start.md:136-140 | 新增 op_host/CMakeLists.txt 样例未编译 cust_op_proto(GRAPH),与同文档部署目录结构(op_proto)、basic_process.md 的“run 包包含算子原型库”说明不一致,入图/框架适配场景会缺原型库 |
| P3 | basic_process.md:63 | set(A ..) | set(B ..) 不是合法 CMake,被提升为“推荐默认方式”后复制即配置失败 |
| P3 | operator_prototype_definition.md:204 | 句子缺谓语“保持一致”,且仍残留“使用 msOpGen 创建工程时自动生成”的旧表述 |
| P3 | tensorflow_framework.md:17 | 单向改动:“会在算子工程目录下生成 framework/tf_plugin”(第 30 行)与第 32–46 行 msOpGen 目录结构未同步,且未说明 add_subdirectory(framework) 的构建接入 |
| P3 | tensorflow_framework.md:17 | 链接“TF_PLUGIN 库编译样例”指向的章节内并无 TF_PLUGIN 示例(仅参数枚举) |
| P3 | basic_process.md:129 | 新增页内跳转依赖中文+全角冒号的自动锚点,与本文件统一使用显式 <a id> 的约定不符,存在死链风险 |
| P3 | aclnn_quick_start.md:368 | 编译步骤的 cd AddCustom 与新增“创建工程”步骤中的 cd AddCustom 叠加,顺序执行会报目录不存在 |
逐文件复核结果
docs/zh/api/.../AddConfig.md、.../HcclServerType.md:表述已与新 CMake 流程一致,no issues。docs/zh/guide/cross_gen_migration_guide/.../op_compilation_migration.md:no issues。aclnn_operator_development/aclnn_quick_start.md:2 条(P2 缺 GRAPH 原型库;P3 重复 cd)。aclnn_operator_development/appendix/cmake_function_reference.md:no issues(概述改写正确)。aclnn_operator_development/appendix/external_sample_links.md:删除 msOpGen 样例后列表结构完好,no issues。aclnn_operator_development/appendix/naming_conversion_table.md:与KERNEL_FILE可选语义一致,no issues。aclnn_operator_development/compilation_and_deployment/basic_process.md:2 条(P3 非法 CMake 写法;P3 锚点约定)。aclnn_operator_development/design_and_implementation/kernel_operator_implementation.md:no issues。aclnn_operator_development/design_and_implementation/operator_prototype_definition.md:1 条(P3 残句+ msOpGen 残留)。aclnn_operator_development/overview.md:no issues(与样例工程的偏差已在 P2 中作为证据引用)。ai_framework_adaptation/tensorflow_framework.md:2 条(均为 P3)。operator_graph_development/overview.md、appendix/faq/kernel_tiling_info_incorrect.md、technical_appendix/concepts_and_terms/glossary.md:no issues。
总体风险判断
无 P0/P1。主要风险集中在“快速入门示例工程不完整”(缺 GRAPH 原型库)与两处“只改一半”的残留表述(TF 插件目录的自动生成说明、原型定义处的 msOpGen 断言),会影响按文档新建工程的开发者(尤其入图/框架适配路径);其余为示例可用性与锚点一致性级别的低风险问题,建议一并修正后合入。
| 类型 | 数量 |
|---|---|
| 🔴 阻塞 | 0 |
| 🟡 建议 | 1 |
💬 仅评论


Thanks for your pull-request.
The full list of commands accepted by me can be found at here.
You can get sig-info at here.
You can self-configure the PR merge rules for this repository. For more details, please refer to Here.
For more, you also can visit HICANN.
PR Approval Progress
✅ Congratulations! All modules have met the lgtm and approve requirements.
Module Approval Details
| module | lgtm status | approve status |
|---|---|---|
| cmake | ✅ chentianyu19, hujiawen_kaven (2/2) | ✅ chentianyu19 (1/1) |
| docs | ✅ ai_xin, chentianyu19, hujiawen_kaven (3/2) | ✅ ai_xin (1/1) |
| examples | ✅ ai_xin, hujiawen_kaven, chentianyu19 (3/2) | ✅ ai_xin (1/1) |
| tools/build | ✅ hujiawen_kaven, chentianyu19 (2/2) | ✅ hujiawen_kaven (1/1) |
💡 Tip:
- Committer can comment
/approveor/lgtm- Commenting
/approveimplies both code review (lgtm) and intent to merge (approve)
CLA Signature Pass
xun_zhuge, thanks for your pull request. All authors of the commits have signed the CLA. 👍


/lgtm
/approve


The MR can not be merged, because of CodeReview discussion not resolved
If you want to solve this problem, you can click here to do it in the FAQs.


描述
将自定义算子工程的编程指南改为从零创建目录、编写源文件和 CMakeLists.txt,再通过 CANN 提供的 npu_op_* 接口完成编译、打包、部署和调用验证。
ASCEND_SOC_SERIES在find_package(ASC)之后设置会被静默忽略,现通过_asc_ensure_build_target()宏在首次实际使用时重新解析,与ASCEND_COMPUTE_UNIT的顺序无关行为保持一致。if(NOT DEFINED ASCEND_COMPUTE_UNIT)判断;统一构建目录命名为build,去掉编译调试/加速/动静态库等文档对 CMakePresets.json 的隐性依赖。CMAKE_CROSS_LIBRARY_PATH变量说明。SOC_SERIES/COMPUTE_UNIT参数的层次关系说明及按系列分流核函数的场景示例。mc32dm11a此前只存在于 CMake 侧白名单,opbuild 侧缺失会导致该型号被静默判定为非法值(仅告警不报错),现已补齐。关联的Issue
无。
测试
_asc_ensure_build_target()宏在 7 种设置顺序/冲突场景下的行为。文档更新
更新中文算子工程快速入门、编译部署、CMake 函数参考、框架适配、入图开发、原型注册及相关实践与 API 说明。PR 共涉及 24 个文档文件、3 个 CMake 框架/脚本文件、2 个样例 CMakeLists.txt 文件、2 个 opbuild 工具文件。
类型标签