已合并
docs: 修复 QUICKSTART 易用性问题并补充构建 FAQ 与 _tiling 命名约束 #107
docs: 修复 QUICKSTART 易用性问题并补充构建 FAQ 与 _tiling 命名约束 #107
已合并
LiuZonggu创建于 9月17日
LiuZonggu成员
9月17日

描述

完善本仓文档易用性(中英文版本同步修改):

  • QUICKSTART.md / QUICKSTART_en.md:运行样例命令统一补充 --soc 参数,并说明其取值须与编译算子包时一致,否则可能报 error 161001(如 aclnnXxxGetWorkspaceSize failed);章节开头整合多场景编译指引(单算子/整库/离线编译),链接《build参数说明》与《源码构建指南》。
  • docs/zh/install/compile.md / docs/en/install/compile.md:新增 FAQ 章节,说明安装自定义 run 包报错权限不足的两种处理方式(推荐 --install-path 安装到用户可写路径并加载 set_env.bash;或使用 sudo -E 安装到系统 CANN 目录)。
  • CONTRIBUTING.md / CONTRIBUTING_en.md:算子最小交付件树补充可选的子场景 Tiling 文件(${op_name}_tiling_${sub_case}.cpp/.h),增加指向项目目录结构文档的链接,并补充 _tiling 命名约束说明。
  • docs/zh/install/dir_structure.md / docs/en/install/dir_structure.md:op_host 目录树补充 Tiling 交付件说明及 _tiling 命名约束。

根因说明:cmake/func.cmake 通过 file(GLOB ... *_tiling*.cpp) 收集 Tiling 源文件参与编译,不含 _tiling 的文件不会被 glob 命中,因而静默不编译,该约束此前未在文档中披露。

关联的Issue

https://gitcode.com/cann/ops-ras/issues/36

测试

文档更新

  • docs/QUICKSTART.md
  • docs/zh/install/compile.md
  • CONTRIBUTING.md
  • docs/zh/install/dir_structure.md
  • docs/QUICKSTART_en.md
  • docs/en/install/compile.md
  • CONTRIBUTING_en.md
  • docs/en/install/dir_structure.md

类型标签

likedislike
Pull Request已成功合入, 合并人@CANN-robot
(感谢 LiuZonggu 的贡献)
LLiuZonggu成员
9月17日 创建了 pull request,commit 0d818206
atomgit-bot
atomgit-bot
9月17日 评论:

变更摘要

本次改动为文档更新,目标是提升仓库文档的易用性并同步中英文版本。主要围绕三类内容展开:在 QUICKSTART.md / QUICKSTART_en.md 中为运行样例命令统一补充 --soc 参数并说明其取值需与编译算子包时一致(否则可能报 error 161001,如 aclnnXxxGetWorkspaceSize failed),同时整合单算子/整库/离线编译等多场景编译指引;在 docs/zh/install/compile.md / docs/en/install/compile.md 新增 FAQ 章节,说明自定义 run 包安装权限不足的两种处理方式;在 CONTRIBUTING.md / CONTRIBUTING_en.md 与 docs/zh/install/dir_structure.md / docs/en/install/dir_structure.md 中补充 Tiling 交付件及 _tiling 命名约束说明,以披露此前未见于文档的编译约束。

主要改动

  • --soc 参数说明补充:QUICKSTART.md 与 QUICKSTART_en.md 中的运行样例命令统一增加 --soc 参数,并提示其取值须与编译算子包时保持一致,否则可能触发 error 161001(如 aclnnXxxGetWorkspaceSize failed)。
  • 多场景编译指引整合:QUICKSTART.md / QUICKSTART_en.md 章节开头整合单算子、整库、离线编译等场景的编译指引,并链接《build参数说明》与《源码构建指南》。
  • 安装 FAQ 新增:docs/zh/install/compile.md / docs/en/install/compile.md 新增 FAQ 章节,说明安装自定义 run 包报权限不足的两种处理方式(推荐用 --install-path 安装到用户可写路径并加载 set_env.bash,或使用 sudo -E 安装到系统 CANN 目录)。
  • Tiling 交付件与命名约束披露:CONTRIBUTING.md / CONTRIBUTING_en.md 的算子最小交付件树补充可选的子场景 Tiling 文件 ${op_name}_tiling_${sub_case}.cpp/.h,并说明 _tiling 命名约束;docs/zh/install/dir_structure.md / docs/en/install/dir_structure.md 的 op_host 目录树同步补充 Tiling 交付件说明及该命名约束。
  • 目录结构文档链接:CONTRIBUTING.md / CONTRIBUTING_en.md 增加指向项目目录结构文档的链接,便于查阅交付件布局。
likedislike
不准确?
atomgit-bot
atomgit-bot
9月17日 评论:

🤖 本次改动均为数据 / 生成 / 二进制文件(如测试用例、锁文件、媒体资源),没有可审查的代码逻辑,已跳过 AI 代码审查。

likedislike
不准确?
CANN-robotCANN-robot成员
9月17日 添加了label:stat/needs-squash
CANN-robotCANN-robot成员
9月17日 添加了label:cann-cla/yes
CANN-robot
CANN-robot成员
9月17日 评论:

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
repo-cann/ops-ras ✅ yue-ma, 陈兴宇 (2/2) ✅ yue-ma (1/1)

💡 Tip:

  • Committer can comment /approve or /lgtm
  • Commenting /approve implies both code review (lgtm) and intent to merge (approve)

CLA Signature Pass

LiuZonggu, thanks for your pull request. All authors of the commits have signed the CLA. 👍

likedislike
LLiuZonggu成员
9月17日 修改了pull request 的描述
LLiuZonggu成员
9月17日 预合并成功(commit_id: 801459ae7c527869723331fd367ca157fcf76c73)
LLiuZonggu成员
9月17日 强制推送  1 个提交:c22f5cb3-docs: 修复 QUICKSTART 易用性问题并补充构建 FAQ 与 _tiling 命名约束
LLiuZonggu成员
9月17日 预合并成功(commit_id: 185bfd6cd485ed53794348de6083f47326ec5ab2)
CANN-robotCANN-robot成员
9月17日 删除了label:cann-cla/yes
CANN-robotCANN-robot成员
9月17日 删除了label:stat/needs-squash
CANN-robot
CANN-robot成员
9月17日 评论:

Notification

This pull request has been changed(code update) or closed, so removes the following label(s): stat/needs-squash.

likedislike
CANN-robotCANN-robot成员
9月17日 添加了label:cann-cla/yes
LLiuZonggu成员
9月17日 修改了pull request 的描述
LiuZonggu成员
9月17日 评论:

compile

likedislike
CANN-robotCANN-robot成员
9月17日 添加了label:ci-pipeline-running
CANN-robot
CANN-robot成员
9月17日 评论:

流水线任务触发成功
任务链接 [05ab35a77198410d8b45b5571fb5e02d][流水线指导]

任务名称状态日志下载链接
PreSmoke_ATK_Test_A2 ✅ SUCCESS >>>>>

[2026-09-17 17:05:46]    CI执行结束

likedislike
CANN-robot
CANN-robot成员
9月17日 评论:

流水线任务触发成功
任务链接 [d2218668eb3a4c769122572c8039dc9d][流水线指导]

任务名称状态日志下载链接
Compile_Ascend_X86 ✅ SUCCESS >>>>> >>>>>
Compile_Ascend_X86_mobile_station ✅ SUCCESS >>>>> >>>>>
Compile_Ascend_ARM ✅ SUCCESS >>>>> >>>>>
Compile_Ascend_single ✅ SUCCESS >>>>> >>>>>
pre_comment ✅ SUCCESS >>>>>
Compile_Ascend_X86_ubuntu24 ✅ SUCCESS >>>>> >>>>>
Compile_Ascend_X86_mobile_station_ubuntu24 ✅ SUCCESS >>>>> >>>>>
Compile_Ascend_ARM_ubuntu24 ✅ SUCCESS >>>>> >>>>>
Compile_Ascend_single_ubuntu24 ✅ SUCCESS >>>>> >>>>>
UT_Test_ophost ✅ SUCCESS
UT_Test_opapi ✅ SUCCESS
API_Check ✅ SUCCESS >>>>>

[2026-09-17 17:09:46]    CI执行结束

likedislike
LLiuZonggu成员
9月17日 修改了pull request 的描述
CANN-robot
CANN-robot成员
9月17日 评论:

流水线任务触发成功
任务链接 [fca982eb75204d12988c2090f8e684ea][流水线指导]

任务名称状态日志下载链接
codecheck ✅ SUCCESS >>>>>
SCA ✅ SUCCESS >>>>>
antipoison ✅ SUCCESS >>>>>
codecheck_Pr ❌ FAILED
codecheck_codestyle ✅ SUCCESS >>>>>
codecheck_precommit ⚠️ WARNING >>>>> >>>>>
likedislike
CANN-robotCANN-robot成员
9月17日 添加了label:api-check-pass
此处折叠了9条事件消息 查看更多
LLiuZonggu成员
9月17日 修改了pull request 的描述
LiuZonggu成员
9月17日 评论:

compile

likedislike
CANN-robotCANN-robot成员
9月17日 删除了label:ci-pipeline-failedapi-check-pass
CANN-robotCANN-robot成员
9月17日 添加了label:ci-pipeline-running
CANN-robot
CANN-robot成员
9月17日 评论:

流水线任务触发成功
任务链接 [e2bf3fe26085467790dcdb2921df72e6][流水线指导]

任务名称状态日志下载链接
PreSmoke_ATK_Test_A2 ✅ SUCCESS >>>>>

[2026-09-17 17:23:06]    CI执行结束

likedislike
CANN-robot
CANN-robot成员
9月17日 评论:

流水线任务触发成功
任务链接 [da029bc3a31547829a12be0304e6db8e][流水线指导]

任务名称状态日志下载链接
Compile_Ascend_X86 ✅ SUCCESS >>>>> >>>>>
Compile_Ascend_X86_mobile_station ✅ SUCCESS >>>>> >>>>>
Compile_Ascend_ARM ✅ SUCCESS >>>>> >>>>>
Compile_Ascend_single ✅ SUCCESS >>>>> >>>>>
pre_comment ✅ SUCCESS >>>>>
Compile_Ascend_X86_ubuntu24 ✅ SUCCESS >>>>> >>>>>
Compile_Ascend_X86_mobile_station_ubuntu24 ✅ SUCCESS >>>>> >>>>>
Compile_Ascend_ARM_ubuntu24 ✅ SUCCESS >>>>> >>>>>
Compile_Ascend_single_ubuntu24 ✅ SUCCESS >>>>> >>>>>
UT_Test_ophost ✅ SUCCESS
UT_Test_opapi ✅ SUCCESS
API_Check ✅ SUCCESS >>>>>

[2026-09-17 17:25:07]    CI执行结束

likedislike
CANN-robotCANN-robot成员
9月17日 添加了label:api-check-pass
CANN-robotCANN-robot成员
9月17日 删除了label:api-check-pass
CANN-robot
CANN-robot成员
9月17日 评论:

流水线任务触发成功
任务链接 [e771dd89a8f54434a2ddd2ff9c49b20f][流水线指导]

任务名称状态日志下载链接
codecheck ✅ SUCCESS >>>>>
SCA ✅ SUCCESS >>>>>
antipoison ✅ SUCCESS >>>>>
codecheck_Pr ✅ SUCCESS
codecheck_codestyle ✅ SUCCESS >>>>>
codecheck_precommit ⚠️ WARNING >>>>> >>>>>

[2026-09-17 17:26:28]    CI执行结束

likedislike
CANN-robotCANN-robot成员
9月17日 删除了label:ci-pipeline-running
CANN-robotCANN-robot成员
9月17日 添加了label:ci-pipeline-passed
yue-ma成员
9月18日 评论:

/lgtm
/approve

likedislike
CANN-robotCANN-robot成员
9月18日 添加了label:approved
chenxingyu18成员
9月18日 评论:

/lgtm

likedislike
CANN-robotCANN-robot成员
9月18日 添加了label:lgtm
CANN-robotCANN-robot成员
9月18日 关闭了关联的issue
CANN-robotCANN-robot成员
9月18日 合入了pull request