Skip to content

Commit b824bf3

Browse files
pirunxipirunxi
committed
commit development, interop, reference, samples docs
1 parent 21215f1 commit b824bf3

15 files changed

Lines changed: 643 additions & 56 deletions

‎docs/development/contributing.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,65 @@
11
# 贡献指南
22

3+
感谢参与 LeanCLR 与文档建设。
4+
35
## 参与方式
46

7+
| 仓库 | 内容 |
8+
|------|------|
9+
| [leanclr](https://github.com/focus-creative-games/leanclr) | 运行时、LeanAOT、测试 |
10+
| [leanclr-doc](https://github.com/focus-creative-games/leanclr-doc) | 文档站（https://doc.leanclr.com） |
11+
| [leanclr-unity](https://github.com/focus-creative-games/leanclr-unity) | Unity 插件 |
12+
13+
问题讨论：[Discord](https://discord.gg/esAYcM6RDQ) / QQ 群 1047250380
14+
515
## 代码风格
616

17+
### C++（runtime）
18+
19+
- 遵循仓库根目录 `.clang-format`
20+
- Windows 格式化：`scripts\dev\format-cpp-files.bat`
21+
- 运行时最低 **C++11**（`src/runtime/CMakeLists.txt`）
22+
23+
### C#
24+
25+
- 与现有测试项目风格一致
26+
- 新测试类使用 `TC_` 前缀，见 [测试框架](./test-framework)
27+
728
## Pull Request 流程
29+
30+
1. Fork 目标仓库，从 `main` 拉分支
31+
2. 小步提交，附带清晰说明
32+
3. **运行时改动**：在本地跑通测试
33+
```bat
34+
scripts\test\build-all.bat Release
35+
scripts\test\run.bat Release
36+
```
37+
4. **文档改动**：在 `leanclr-doc` 目录 `npm run build` 确保无断链
38+
5. 提交 PR，描述动机、测试方式、关联 Issue（如有）
39+
40+
## 本地开发环境（IDE）
41+
42+
### Cursor / VS Code + clangd
43+
44+
1. 用仓库**根目录**打开工作区（不要只开 `src/runtime`）
45+
2. 编译标志：`src/runtime/compile_flags.txt`（`-I.` 为 runtime 根）
46+
3. 启用 clangd，禁用与 cpptools 冲突的 IntelliSense
47+
4. 修改 CMake 宏（如 GC 选项）后，同步更新 `compile_flags.txt` 中对应 `-D`
48+
49+
### Visual Studio
50+
51+
```bat
52+
scripts\build.bat runtime sln
53+
```
54+
55+
在 `out/cmake/runtime/vs-sln-x64/` 打开 `leanclr.sln`。
56+
57+
## 文档贡献
58+
59+
- **不要**再往 `leanclr` 仓库 `docs/` 添加内容（已废弃）
60+
- 在 [leanclr-doc](https://github.com/focus-creative-games/leanclr-doc) 编辑 `docs/` 下 Markdown
61+
- 中文为主；英文 locale 后续单独添加
62+
63+
## 许可证
64+
65+
贡献代码即表示同意以仓库 [MIT License](https://github.com/focus-creative-games/leanclr/blob/main/LICENSE) 发布。

‎docs/development/dev-scripts.md‎

Lines changed: 65 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,69 @@
11
# 开发脚本
22

3-
## 代码格式化
3+
仓库级脚本的**完整索引**。日常常用命令见 [脚本参考](../integration/scripts-reference)。
44

5-
## 清理输出目录
5+
输出根目录：`out/`（可用 `LEANCLR_OUT_ROOT` 覆盖）。
66

7-
## 代码生成
7+
## 目录布局
8+
9+
```text
10+
scripts/
11+
├── build.sh / build.bat # 总入口
12+
├── ci.sh # Linux CI：构建 + 测试
13+
├── test/ # 测试 runner 与 managed 构建
14+
├── runtime/ # leanclr 静态库
15+
├── leanaot/ # LeanAOT
16+
├── generator/ # opcode / icall 代码生成
17+
├── dev/ # clean-out、format-cpp
18+
└── lib/ # 路径辅助
19+
```
20+
21+
## 脚本索引
22+
23+
| 脚本 | 说明 |
24+
|------|------|
25+
| `ci.sh` | `test/build-all` + `test/run` |
26+
| `test/build-all.*` | 构建 runner + managed DLL → `dlls/` |
27+
| `test/basic-tester/build.*` | 构建 `test.exe` |
28+
| `test/run.*` | 运行 basic-tester |
29+
| `runtime/build.*` | 构建 `leanclr` → `out/cmake/runtime/...` |
30+
| `test/aot-tester/build.*` | 构建 aot-tester |
31+
| `test/aot-tester/gen_cpp.*` | LeanAOT 生成 `src/tests/aot-tester/cpp/` |
32+
| `test/aot-tester/gen_cpp_posix.*` | POSIX BCL 变体 cpp |
33+
| `test/aot-tester/run.*` | 构建并运行 aot-tester |
34+
| `test/aot-tester/build-wasm.*` | WASM 版 aot-tester |
35+
| `leanaot/build.*` | 构建 LeanAOT → `out/dotnet/LeanAOT/...` |
36+
| `publish_leanaot.bat` | 发布 LeanAOT 到同级 `leanclr-unity` 包目录 |
37+
| `publish_pgo2aot.bat` | 发布 pgo2aot 到 unity 包 |
38+
| `publish_runtime.bat` | 同步 runtime 到 unity 包 |
39+
| `publish_csharp.bat` | 同步 Profile.cs、pgo2aot 工具到 unity |
40+
| `generator/gen_*.bat` | 再生 opcode 头文件、icall JSON |
41+
| `dev/format-cpp-files.bat` | clang-format `src/runtime` |
42+
| `dev/clean-out.*` | 删除整个 `out/` |
43+
44+
## 转发脚本
45+
46+
以下目录的 `build.*` 转发到 `scripts/`，产物仍在 `out/`：
47+
48+
- `src/runtime/build.*`
49+
- `src/samples/*/build.*`
50+
- `src/tests/basic-tester/build.*`
51+
- `src/tools/lean/build.*`
52+
53+
## 与 Unity 包同步
54+
55+
`publish_*.bat` 假设 `leanclr-unity` 与 `leanclr` 为**同级目录**：
56+
57+
```text
58+
workspace/
59+
├── leanclr/
60+
└── leanclr-unity/ # 或 leanclr4unity 本地克隆名
61+
```
62+
63+
同步目标为 `leanclr-unity/LeanCLR~/` 下各子目录。仅维护 Unity 包的同学通常直接安装 git 包，无需运行 publish 脚本。
64+
65+
## 相关文档
66+
67+
- [脚本参考](../integration/scripts-reference)
68+
- [测试指南](./testing)
69+
- [输出目录结构](../integration/output-layout)

‎docs/development/test-framework.md‎

Lines changed: 115 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,119 @@
22

33
## 目录结构
44

5-
## 测试项目说明
5+
```text
6+
tests/
7+
├── basic-tester/ # C++ runner（CI）
8+
├── aot-tester/ # AOT runner
9+
├── managed/
10+
│ ├── managed.sln
11+
│ ├── Common/ # Assert、[UnitTest]、TestCaseBase
12+
│ ├── SharedTests/ # 共享源，链入 CoreTests / AotTests
13+
│ ├── CoreTests/ # CLR / IL / C# 语义
14+
│ ├── CorlibTests/ # BCL icall / intrinsic
15+
│ ├── AotTests/ # LeanAOT 专有
16+
│ ├── ILTests/ # .il + wrapper
17+
│ └── RunTests/ # C# 反射 runner（本地）
18+
└── TESTING.md # 仓库内简短索引（指向文档站）
19+
```
620

7-
## 添加测试用例
21+
## 测试项目职责
22+
23+
| 项目 | 测什么 | 不应放什么 |
24+
|------|--------|------------|
25+
| **CoreTests** | 解释器、IL（C# 可写）、C# 特性、回归 | BCL icall 细节、AOT 链路专有 |
26+
| **CorlibTests** | mscorlib / System：icall、intrinsic、P/Invoke | 纯 CLR 指令语义 |
27+
| **ILTests** | C# 难构造的 IL（`.il` + ilasm） | 可用 C# 表达的用例 |
28+
| **AotTests** | IL→C++ 后正确性 | 与 CoreTests 完全重复的指令测 |
29+
| **Common** | 基础设施 | 测试用例本身 |
30+
31+
## Runner 发现规则
32+
33+
| 规则 | basic-tester | RunTests | AotTests.App |
34+
|------|-------------|----------|--------------|
35+
| 标记 | `[UnitTest]` | `[UnitTest]` | `[UnitTest]` |
36+
| 签名 | `void`，无参 | 同左 | 同左 |
37+
| static 方法 | **不支持** | 支持 | 支持 |
38+
| 跳过 | 无 | `[IgnoreTest]` 类级 | 无 |
39+
| 推荐基类 | `TestCaseBase` | 同左 | 多数未继承 |
40+
41+
## 编写测试
42+
43+
### 最小示例
44+
45+
```csharp
46+
namespace Tests.CSharp
47+
{
48+
class TC_MyFeature : TestCaseBase
49+
{
50+
[UnitTest]
51+
public void Addition()
52+
{
53+
Assert.Equal(3, 1 + 2);
54+
}
55+
}
56+
}
57+
```
58+
59+
- 类推荐命名 `TC_{主题}.cs`
60+
- 方法：`public void`、无参、`[UnitTest]`
61+
- basic-tester 要求**实例方法**（非 static）
62+
63+
### Assert API（Common）
64+
65+
| 方法 | 说明 |
66+
|------|------|
67+
| `Fail()` / `Fail(string)` | 立即失败 |
68+
| `IsTrue` / `IsFalse` / `True` / `False` | 布尔 |
69+
| `Null` / `NotNull` | 引用 |
70+
| `Equal` / `NotEqual` | 值相等 |
71+
| `EqualAny` | `Object.Equals` |
72+
73+
### 放置指南
74+
75+
| 场景 | 项目 | 目录 |
76+
|------|------|------|
77+
| IL 指令（C#） | CoreTests | `Instructions/` |
78+
| C# 语言特性 | CoreTests | `Runtime/` |
79+
| Bug 回归 | CoreTests | `Regression/` |
80+
| Fixture | CoreTests | `Shared/Fixtures/` |
81+
| BCL icall | CorlibTests | `InternalCall/` |
82+
| 纯 IL asm | ILTests | `Instructions/*.il` + `Wrappers/` |
83+
| 跨解释器+AOT 共享 | SharedTests | `Instructions/` 或 `Runtime/` |
84+
| AOT 专有 | AotTests | 项目根目录 |
85+
86+
### CoreTests 目录（摘要）
87+
88+
```text
89+
CoreTests/
90+
├── Runtime/ # C# 语言特性
91+
├── Instructions/ # IL 指令（Arithmetic、Branches…）
92+
├── Regression/ # 历史 Bug
93+
├── Shared/Fixtures/ # 辅助类型（namespace AOTDefs）
94+
└── Bootstrap/ # C++ 引导测
95+
```
96+
97+
### ILTests {#iltests}
98+
99+
1. 在 `ILTests/Instructions/` 添加 `.il`，程序集名须为 **`ILTests.Native`**
100+
2. 在 `ILTests/Wrappers/` 添加 `TC_*.cs`，`[UnitTest]` 调用 IL 并断言
101+
3. `dotnet build managed.sln` 会通过 ILAsm NuGet 编译 `.il`
102+
103+
产出：`ILTests.Native.dll` + `ILTests.dll`（wrapper）。
104+
105+
### AotTests 专有用例（示例）
106+
107+
| 文件 | 说明 |
108+
|------|------|
109+
| `TC_EvalStackNotEmpty.cs` | HL 转换 eval stack |
110+
| `TC_StaticCtorOrder.cs` | 静态构造器顺序 |
111+
| `TC_Call_AotInterp.cs` | AOT / 解释器混编 |
112+
| `TC_PInvoke.cs` | P/Invoke 相关 |
113+
| `TC_MonoPInvokeCallback.cs` | 回调 |
114+
115+
依赖 `AOTDefs` 的通用测试留在 **CoreTests**，由解释器路径执行。
116+
117+
## 相关文档
118+
119+
- [测试指南](./testing) — 构建与运行
120+
- [开发脚本](./dev-scripts)

‎docs/development/testing.md‎

Lines changed: 90 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,95 @@
11
# 测试指南
22

3+
本文描述 LeanCLR `src/tests/` 的构建、运行方式与测试体系概览。编写用例与目录约定见 [测试框架](./test-framework)。
4+
5+
脚本索引见 [开发脚本](./dev-scripts) 或 [脚本参考](../integration/scripts-reference)。
6+
37
## 测试体系概览
48

5-
## 构建与运行测试
9+
```text
10+
src/tests/
11+
├── basic-tester/ # C++ runner — CI 主路径（解释器 + BCL + ILTests）
12+
├── aot-tester/ # AOT 正确性 runner
13+
└── managed/ # C# 测试程序集（CoreTests、CorlibTests、AotTests、ILTests…）
14+
```
15+
16+
| Runner | 加载程序集 | 用途 |
17+
|--------|------------|------|
18+
| **basic-tester** | CoreTests, CorlibTests, ILTests, … | **CI 默认** |
19+
| **RunTests.exe** | 含 AotTests 等 | 本地一次性跑多套 managed 测试 |
20+
| **aot-tester** | AotTests | AOT 流水线验证 |
21+
22+
## 构建与运行
23+
24+
### 一键（推荐）
25+
26+
```bat
27+
scripts\test\build-all.bat Debug x64
28+
scripts\test\run.bat Debug x64
29+
```
30+
31+
Linux / macOS：
32+
33+
```bash
34+
./scripts/ci.sh Release
35+
```
36+
37+
### 分步
38+
39+
```bat
40+
scripts\test\basic-tester\build.bat Debug x64
41+
dotnet build src\tests\managed\managed.sln -c Debug
42+
scripts\test\run.bat Debug x64
43+
```
44+
45+
`build-all` 会将 `Common.dll`、`CoreTests.dll`、`CorlibTests.dll`、`ILTests.dll`、`ILTests.Native.dll` 等复制到 runner 旁 `dlls/` 目录。
46+
47+
### AOT 测试
48+
49+
```bat
50+
scripts\build.bat aot-tester gen-cpp
51+
scripts\build.bat aot-tester run Release x64
52+
```
53+
54+
### 本地调试（含 AotTests）
55+
56+
```bat
57+
dotnet build src\tests\managed\managed.sln -c Debug
58+
out\dotnet\RunTests\Debug\RunTests.exe
59+
```
60+
61+
## 输出路径
62+
63+
- C++ runner：`out/cmake/tests/basic-tester/<Config>-<Arch>/bin/...`
64+
- Managed DLL：`out/dotnet/<ProjectName>/<Config>/`
65+
66+
见 [输出目录结构](../integration/output-layout)。
67+
68+
## 命名规范
69+
70+
| 类别 | 规范 | 示例 |
71+
|------|------|------|
72+
| 测试类 | `TC_{主题}` | `TC_conv_i4` |
73+
| 回归 | `Issue_{yyyyMMdd}_{desc}` | `Issue_20220617_ArrayCustomArg` |
74+
| Fixture | 无 `TC_` 前缀 | `TypeStaticFields` |
75+
76+
新用例请遵循上述约定，避免 `Test*` 与 `TC_*` 混用。
77+
78+
## 常见问题
79+
80+
**报错 "Test runner not found"**
81+
先构建 basic-tester：`scripts\test\basic-tester\build.bat Debug x64`
82+
83+
**能否只跑单个测试？**
84+
当前 runner **不支持过滤**，所有带 `[UnitTest]` 的方法都会执行。
85+
86+
**ILTests 如何添加？**
87+
见 [测试框架 — ILTests](./test-framework#iltests)。
88+
89+
**Assert 维护位置**
90+
仅在 `managed/Common/Assert.cs` 维护一份。
91+
92+
## 相关文档
693

7-
## 测试约定
94+
- [测试框架](./test-framework) — 项目职责、Assert API、放置指南
95+
- [贡献指南](./contributing)

‎docs/integration/project-structure.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@ leanclr/
6363
|------|------|
6464
| **startup** | Win64 最小嵌入 |
6565
| **lean-wasm** | 浏览器 WASM |
66-
| **custom-pinvoke-x64 / wasm** | 自定义 P/Invoke |
66+
| **custom-pinvoke-x64** | 自定义 P/Invoke 示例 |
6767
| **simple-aot** | AOT 生成 C++ 并链接 |
6868

6969
## tests

‎docs/interop/custom-pinvoke.md‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,9 @@
22

33
LeanCLR 支持自定义 **P/Invoke**，在托管 C# 与原生 C++ 之间互操作。为保持跨平台可移植性，P/Invoke 目标目前须为 **AOT 编译的原生函数**；在 IL→AOT 工具链完全自动化之前，**需手动注册**原生实现。
44

5-
示例工程：
5+
**各平台（Win64、WebAssembly、Unity 发布目标等）使用同一套注册 API**，无平台分支写法。参考示例：
66

7-
- `src/samples/custom-pinvoke-x64` — Windows x64
8-
- `src/samples/custom-pinvoke-wasm` — WebAssembly
7+
- `src/samples/custom-pinvoke-x64`
98

109
## 概述
1110

@@ -127,11 +126,11 @@ int main()
127126
- 在 `initialize` **之后**注册
128127
- 签名字符串与 C# 元数据严格一致
129128
- 使用 `RuntimeApi` 辅助函数访问栈，避免手工算偏移
130-
- WASM 平台注意 `__Internal` 与 JS 胶水，见 [P/Invoke 示例](./pinvoke-samples)
129+
- 换平台时复用同一套 C# 声明与 `register_pinvoke_func` 逻辑，仅原生函数实现与链接方式随宿主工具链变化
131130

132131
## LeanAOT 自动生成（展望）
133132

134-
LeanAOT toolchain 发展后，部分 P/Invoke 包装可由 AOT 自动生成。当前以手动注册为准。
133+
LeanAOT toolchain 发展后，部分 P/Invoke 包装可由 AOT 自动生成。当前以手动注册为准。
135134

136135
## 相关文档
137136

0 commit comments

Comments
 (0)