docs(VSCode Plugin): add build documentation and images for VSCode Plugin#135
Open
Platohykj wants to merge 1 commit intoruyisdk:zhfrom
Open
docs(VSCode Plugin): add build documentation and images for VSCode Plugin#135Platohykj wants to merge 1 commit intoruyisdk:zhfrom
Platohykj wants to merge 1 commit intoruyisdk:zhfrom
Conversation
Contributor
Reviewer's GuideAdds a new VSCode plugin build documentation page describing the RuyiSDK build system, including venv integration and custom build rules, and adjusts sidebar ordering to insert this page before the usage cases section. Flow diagram for RuyiSDK build rule selection and executionflowchart TD
A_Start[Start Build Request]
B_CheckCustom[Check .ruyi-build-rules.json in workspace root]
C_CustomRules[Load custom rules]
D_DefaultRules[Use built in default rules]
E_DetectIndicators[Detect indicators in workspace root]
F_CMake[CMakeLists.txt found]
G_Make[Makefile or GNUmakefile or makefile found]
H_CFiles[C source files *.c found in root]
I_NoMatch[No recognizable build system]
J_SelectCMake[Select CMake rule]
K_SelectMake[Select GNU Make rule]
L_SelectGCC[Select GCC C rule]
M_CheckVenv[Is Ruyi venv active]
N_UseVenv[Prepare venv environment]
O_UseSystem[Use system environment]
P_LoopSteps[Execute each build step]
Q_StepOK[Step succeeded]
R_StepFail[Step failed]
S_NotifyFail[Show Build failed and stop]
T_NotifyNoSystem[Show no recognizable build system]
U_NotifySuccess[Show Build succeeded]
A_Start --> B_CheckCustom
B_CheckCustom -->|Yes| C_CustomRules
B_CheckCustom -->|No| D_DefaultRules
C_CustomRules --> E_DetectIndicators
D_DefaultRules --> E_DetectIndicators
E_DetectIndicators -->|CMake| F_CMake
E_DetectIndicators -->|Make| G_Make
E_DetectIndicators -->|C_files| H_CFiles
E_DetectIndicators -->|None| I_NoMatch
F_CMake --> J_SelectCMake
G_Make --> K_SelectMake
H_CFiles --> L_SelectGCC
I_NoMatch --> T_NotifyNoSystem
J_SelectCMake --> M_CheckVenv
K_SelectMake --> M_CheckVenv
L_SelectGCC --> M_CheckVenv
M_CheckVenv -->|Venv active| N_UseVenv
M_CheckVenv -->|No venv| O_UseSystem
N_UseVenv --> P_LoopSteps
O_UseSystem --> P_LoopSteps
P_LoopSteps --> Q_StepOK
P_LoopSteps --> R_StepFail
Q_StepOK --> P_LoopSteps
R_StepFail --> S_NotifyFail
P_LoopSteps --> U_NotifySuccess
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Hey - I've found 2 issues, and left some high level feedback:
- The new screenshots all use the generic
alt textstring; consider replacing these with short, descriptive alt texts so the page is more accessible and easier to understand when images fail to load. - The description mentions changing the sidebar position of the '插件使用案例' section from 7 to 8, while the new
build.mdxusessidebar_position: 7; double-check the sidebar positions to ensure the new build page and the cases section appear in the intended order.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- The new screenshots all use the generic `alt text` string; consider replacing these with short, descriptive alt texts so the page is more accessible and easier to understand when images fail to load.
- The description mentions changing the sidebar position of the '插件使用案例' section from 7 to 8, while the new `build.mdx` uses `sidebar_position: 7`; double-check the sidebar positions to ensure the new build page and the cases section appear in the intended order.
## Individual Comments
### Comment 1
<location path="VSCode-Plugins/build.mdx" line_range="102-104" />
<code_context>
+
+- `.ruyi-build-rules.json`
+
+注意：
+
+- 该文件会**整体替换**扩展内置规则（不是增量合并）
+
+### 7.1 规则文件结构
</code_context>
<issue_to_address>
**suggestion:** Clarify how to preserve built‑in rules when using `.ruyi-build-rules.json`.
Since this behavior can easily surprise users (e.g., unintentionally losing default CMake/Make/GCC behavior), it would help to add a short note on how to start from the built‑in rules (for example, by copying a documented/template rules file) and then customize them, making it clear they must explicitly re‑define all desired behaviors.
```suggestion
注意：
- 该文件会**整体替换**扩展内置规则（不是增量合并）
- 如果你希望在内置规则基础上做少量调整，建议先从扩展提供的示例规则文件或文档中的模板复制一份 `.ruyi-build-rules.json`，然后在此基础上修改；请注意你需要在该文件中**显式定义所有希望保留的行为**，否则对应的默认规则会被完全覆盖。
```
</issue_to_address>
### Comment 2
<location path="VSCode-Plugins/build.mdx" line_range="180-183" />
<code_context>
+ "steps": [
+ {
+ "name": "Compile All",
+ "command": "for f in *.c; do gcc \"$f\" -O2 -Wall -o \"${f%.c}\"; done",
+ "args": [],
+ "workdir": ".",
+ "useShell": true
+ }
+ ]
</code_context>
<issue_to_address>
**suggestion:** Mention shell compatibility / platform considerations for the `useShell` example.
This example assumes a POSIX‑compatible shell (`for`, `do`, `done`, `$f`, `${f%.c}`). Please note what shell `useShell: true` actually uses on each platform, and call out that this command won’t work as‑is on Windows shells like `cmd.exe` or PowerShell (or briefly describe the differing behavior).
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
Comment on lines
+102
to
+104
| 注意： | ||
|
|
||
| - 该文件会**整体替换**扩展内置规则（不是增量合并） |
Contributor
There was a problem hiding this comment.
suggestion: Clarify how to preserve built‑in rules when using .ruyi-build-rules.json.
Since this behavior can easily surprise users (e.g., unintentionally losing default CMake/Make/GCC behavior), it would help to add a short note on how to start from the built‑in rules (for example, by copying a documented/template rules file) and then customize them, making it clear they must explicitly re‑define all desired behaviors.
Suggested change
| 注意： | |
| - 该文件会**整体替换**扩展内置规则（不是增量合并） | |
| 注意： | |
| - 该文件会**整体替换**扩展内置规则（不是增量合并） | |
| - 如果你希望在内置规则基础上做少量调整，建议先从扩展提供的示例规则文件或文档中的模板复制一份 `.ruyi-build-rules.json`，然后在此基础上修改；请注意你需要在该文件中**显式定义所有希望保留的行为**，否则对应的默认规则会被完全覆盖。 |
Comment on lines
+180
to
+183
| "command": "for f in *.c; do gcc \"$f\" -O2 -Wall -o \"${f%.c}\"; done", | ||
| "args": [], | ||
| "workdir": ".", | ||
| "useShell": true |
Contributor
There was a problem hiding this comment.
suggestion: Mention shell compatibility / platform considerations for the useShell example.
This example assumes a POSIX‑compatible shell (for, do, done, $f, ${f%.c}). Please note what shell useShell: true actually uses on each platform, and call out that this command won’t work as‑is on Windows shells like cmd.exe or PowerShell (or briefly describe the differing behavior).
There was a problem hiding this comment.
Pull request overview
This PR adds a new documentation page describing the RuyiSDK VS Code plugin’s build system (including rule detection, venv behavior, logs, and custom .ruyi-build-rules.json), and updates sidebar ordering to accommodate the new page.
Changes:
- Added
VSCode-Plugins/build.mdxbuild-system documentation with screenshots and advanced customization examples. - Adjusted the sidebar ordering for the “插件使用案例” section to keep navigation order consistent after adding the new page.
Reviewed changes
Copilot reviewed 2 out of 6 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| VSCode-Plugins/cases/category.json | Moves the “插件使用案例” category position to keep sidebar ordering aligned with the new build page. |
| VSCode-Plugins/build.mdx | New build documentation page covering workflows, venv interaction, logging, and custom build rule configuration. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+31
to
+36
|  | ||
| - 编辑器标题栏按钮（`Build Project`） | ||
|  | ||
| - 命令面板执行 `Ruyi: Build Project` | ||
|  | ||
|
|
Comment on lines
+73
to
+81
| - 需要开发者自行套用虚拟环境里的工具链[^1] | ||
| - 一键编译功能不会帮助开发者自动把该工具链注入到项目配置中 | ||
|
|
||
| 当没有激活 venv 时： | ||
|
|
||
| - 构建将使用系统环境中的工具（例如系统 `cmake`、`gcc`、`make`） | ||
|
|
||
| [^1]: 例如 CMake 项目通常需要开发者自行指定 `CMAKE_TOOLCHAIN_FILE`、Preset 或相关缓存项；Makefile 项目通常需要自行设置 `CC`、`CXX` 或其他工具链变量。 | ||
|
|
…ugin Signed-off-by: Platohykj <guanting.plct@isrc.iscas.ac.cn>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request adds comprehensive documentation for the build system in the RuyiSDK VSCode plugin and makes a minor adjustment to the sidebar ordering of the plugin usage cases. The main focus is on providing users with clear instructions and customization options for building projects with the RuyiSDK extension.
Documentation improvements:
VSCode-Plugins/build.mdx, which provides detailed instructions on how to use the RuyiSDK build system in VSCode. The documentation covers build system features, usage workflows, automatic detection rules, integration with virtual environments (venv), output logs, and advanced customization of build rules via.ruyi-build-rules.json.Sidebar and navigation:
VSCode-Plugins/cases/_category_.jsonto change the sidebar position of the "插件使用案例" section from 7 to 8, reflecting the addition of the new build documentation.Summary by Sourcery
Document the RuyiSDK VSCode extension build workflow and update related navigation order.
Enhancements:
Documentation: