143 lines
4.8 KiB
Markdown
143 lines
4.8 KiB
Markdown
# AGENTS.md
|
||
|
||
本文件为 L Language 项目的 Codex 上下文文件，定义项目架构、构建命令、核心 API 和开发约定。
|
||
|
||
## 项目概述
|
||
|
||
L Language v0.5 — C17 实现的静态类型编译型语言，Rust 风格语法，LLVM 22.x 后端。5 阶段流水线：词法 → 语法 → 语义 → IR → 可执行文件。38 单元测试 + 23 集成程序。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
├── include/l_lang.h TypeKind(10), SourceLoc 公共头文件
|
||
├── src/
|
||
│ ├── lexer/ {token,lexer} 手写状态机, 50 Token 类型
|
||
│ ├── parser/ parser.c 递归下降 + Pratt, 825 行
|
||
│ ├── ast/ ast.{c,h} 25 种 AST 节点 + 工厂函数
|
||
│ ├── sema/ {symbol,sema} 作用域链 + 类型推断 + impl mangle
|
||
│ ├── codegen/{codegen,target} LLVM-C API → 目标代码, 824 行
|
||
│ ├── driver/ {main,error} 入口 + 命令行解析 + 错误报告
|
||
│ └── util/ arena.c Bump allocator (8MB)
|
||
├── test/
|
||
│ ├── test_{lexer,parser,sema,codegen}.c 单元测试 (38)
|
||
│ └── programs/*.l 集成测试 (23)
|
||
└── docs/
|
||
├── PRD.md 产品需求文档 (v0.1)
|
||
├── analysis/ 架构分析报告
|
||
└── architecture-improvements.md
|
||
```
|
||
|
||
## 构建命令
|
||
|
||
```powershell
|
||
cd build
|
||
cmake .. -G "MinGW Makefiles" -DCMAKE_PREFIX_PATH="D:/settings/Language/LLVM"
|
||
mingw32-make -j4
|
||
mingw32-make l_lang # 仅编译器
|
||
```
|
||
|
||
## 编译流水线
|
||
|
||
```
|
||
源码(.l) → Lexer → Parser → Sema → Codegen → Target(obj) → GCC 链接(.exe)
|
||
50 Tok 25 AST 类型标注 LLVM IR .o 可执行文件
|
||
```
|
||
|
||
## 核心 API
|
||
|
||
```c
|
||
// lexer.h — 词法分析
|
||
Token* lex(Arena* a, const char* source, const char* filename,
|
||
size_t* count, ErrorInfo* error);
|
||
|
||
// parser.h — 语法分析
|
||
AstNode* parse(Arena* a, const Token* tokens, size_t count,
|
||
const char* filename, ErrorInfo* error);
|
||
|
||
// sema.h — 语义分析
|
||
void sema_analyze(AstNode* ast, ErrorList* errors, Arena* arena);
|
||
|
||
// codegen.h — IR 生成
|
||
LLVMModuleRef codegen_module(AstNode* ast, const char* module_name,
|
||
const char** error_msg);
|
||
```
|
||
|
||
## 类型系统
|
||
|
||
| L 类型 | LLVM 类型 | TypeKind |
|
||
|--------|-----------|----------|
|
||
| i64 | LLVMInt64Type() | TYPE_I64 |
|
||
| f64 | LLVMDoubleType() | TYPE_F64 |
|
||
| bool | LLVMInt1Type() | TYPE_BOOL |
|
||
| str | LLVMInt8PtrType() | TYPE_STR |
|
||
| void | LLVMVoidType() | TYPE_VOID |
|
||
| struct | LLVMStructType() | TYPE_STRUCT |
|
||
| enum | (i64 常量) | TYPE_ENUM |
|
||
| [T; N] | LLVMArrayType() | TYPE_ARRAY |
|
||
|
||
## 运算符优先级 (Pratt)
|
||
|
||
| 优先级 | 运算符 |
|
||
|--------|--------|
|
||
| 70 (最高) | `-`(一元负) `!` |
|
||
| 60 | `*` `/` `%` |
|
||
| 50 | `+` `-` |
|
||
| 40 | `==` `!=` `<` `>` `<=` `>=` |
|
||
| 30 | `&&` |
|
||
| 20 | `\|\|` |
|
||
|
||
## 关键架构决策
|
||
|
||
| 决策 | 说明 |
|
||
|------|------|
|
||
| impl mangle | sema 将 `impl S { fn f }` 改名为 `S$f`，codegen 零修改 |
|
||
| match 脱糖 | parser 将 match 转为 let+if-else 链，sema/codegen 完全复用 |
|
||
| for 脱糖 | for 转为 let mut+while+assign |
|
||
| 复合赋值脱糖 | `x += 1` → `x = x + 1` |
|
||
| parse_type_expr 统一 | 所有类型标注经同一函数解析 |
|
||
| RAII cleanup_list | 作用域级自动 free，dynamic resize |
|
||
|
||
## 版本状态
|
||
|
||
| 指标 | v0.5 |
|
||
|------|------|
|
||
| 实现代码 | ~3,336 行 |
|
||
| Token 类型 | 50 |
|
||
| AST 节点 | 25 |
|
||
| TypeKind | 10 |
|
||
| SymbolKind | 5 (VAR/PARAM/FN/STRUCT/ENUM) |
|
||
| P0 完成度 | 4/4 (100%) |
|
||
| P1 完成度 | 6/6 (100%) |
|
||
| 已知技术债务 | 10 项 |
|
||
|
||
## 开发约定
|
||
|
||
- **语言标准**: C17，`-Wall -Wextra -g`，零警告
|
||
- **内存管理**: Token/AST/符号表均在 arena 分配，禁止 malloc/free 散落
|
||
- **错误消息**: 中文，格式 `文件名:行号:列号: 描述`
|
||
- **平台**: Windows 11 + MinGW-w64，链接器用 gcc（非 clang）
|
||
- **LLVM 路径**: `D:\settings\Language\LLVM`（v22.1.7，C API）
|
||
- **去糖优先**: 复杂语法优先在 parser 层去糖为简单原语，减少 sema/codegen 改动
|
||
- **新增功能流程**: lexer token → ast 节点 → parser 解析 → sema 检查 → codegen 生成 → 测试
|
||
|
||
## 测试
|
||
|
||
```powershell
|
||
./l_lang_lexer_test.exe # 3 测试
|
||
./l_lang_test.exe # 5 测试
|
||
./l_lang_sema_test.exe # 21 测试
|
||
./l_lang_codegen_test.exe # 9 测试
|
||
|
||
# 集成测试
|
||
Get-ChildItem test/programs/*.l | ForEach-Object {
|
||
./l_lang.exe $_.FullName -o test.exe
|
||
./test.exe
|
||
}
|
||
```
|
||
|
||
## 当前技术债务 (优先级排序)
|
||
|
||
1. **高**: analyze_expr 膨胀 (350+ 行)，match/sema 无单元测试
|
||
2. **中**: parser.c 825 行单文件，codegen.c 824 行单文件，match 脱糖在 parser 非独立 pass，`[Point; N]` 未实现
|
||
3. **低**: TypeKind 耦合 (改 7+ 文件)，AST Visitor 缺失，CHANGELOG 未更新 v0.4/v0.5，LLVM 22 无 mem2reg C API
|