# 贡献指南

## 本地开发环境

- **GCC** 14.x+ (MinGW-w64)
- **CMake** 3.20+
- **LLVM** 22.x（需要 C API 库和头文件，路径见 CLAUDE.md）

## 开发流程

1. Fork 本仓库
2. `git clone <你的 fork>`
3. `git checkout -b feature/xxx`
4. 开发 + 测试
5. `git commit`（遵循约定式提交格式）
6. `git push`
7. 提交 Pull Request

## 运行测试

```bash
cd build

# 单元测试
./l_lang_lexer_test.exe     # 词法分析
./l_lang_test.exe           # 语法分析
./l_lang_sema_test.exe      # 语义分析

# 集成测试
for f in ../test/programs/*.l; do
    ./l_lang.exe "$f" -o /tmp/out.exe && /tmp/out.exe
done
```

## 代码规范

### C 代码

- C17 标准，`-Wall -Wextra -g` 零警告
- 注释用中文
- 内存统一使用 Arena bump allocator，不在局部函数内 malloc/free
- 错误信息格式：`文件名:行号:列号: 描述`
- 函数聚焦（< 100 行），文件内聚（< 500 行）

### 编译器架构约定

- 每个编译阶段独立模块，通过头文件声明公共接口
- 新增 AST 节点需同步更新 `sema.c` 和 `codegen.c`
- 新增 Token 类型需同步更新 `lexer.c` 和 `NAMES[]` 数组
- 新增内建函数需在 `sema.c`（注册签名）和 `codegen.c`（生成 IR）两处实现

## 提交格式

```
<类型>: <描述>
```

类型：`feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `perf`

## 项目结构

```
src/
├── lexer/      词法分析器
├── parser/     语法分析器
├── ast/        AST 定义
├── sema/       语义分析
├── codegen/    LLVM IR 生成
├── driver/     主入口 + 错误报告
└── util/       内存池
test/           测试
docs/           文档
```

## 开始贡献前

- 大改动建议先开 Issue 讨论
- 新语言特性需要在 `test/programs/` 添加对应的集成测试
- 不要引入编译警告