commit initial

.monkeycode/specs/2026-05-20-tinycc-improvements/requirements.md

@@ -0,0 +1,123 @@
+# Requirements Document
+
+## Introduction
+
+本改进计划涵盖 TinyCC 编译器的 9 个核心改进方向，包括端到端测试、错误报告增强、代码清理、语义分析完善、预处理器集成、代码生成优化、调试信息支持、PE 格式支持及性能基准测试。
+
+## Glossary
+
+- **TinyCC**: 本项目实现的轻量级 C 编译器
+- **E2E 测试**: 端到端测试，验证完整编译流程
+- **ELF**: Executable and Linkable Format，Linux 可执行文件格式
+- **PE**: Portable Executable，Windows 可执行文件格式
+- **DWARF**: 调试信息格式，支持源码级调试
+- **ABI**: Application Binary Interface，应用二进制接口
+
+## Requirements
+
+### Requirement 1: 端到端编译测试
+
+**User Story:** AS 一个编译器开发者，I WANT 验证完整编译流程生成的可执行文件能够正确运行，SO THAT 确保编译器各组件协同工作正常
+
+#### Acceptance Criteria
+
+1. WHEN 提供包含 `main` 函数的 C 源代码，编译器 SHALL 生成可在 Linux 上执行的 ELF 文件
+2. WHEN 运行生成的 ELF 文件，程序 SHALL 返回正确的退出码
+3. WHEN 编译包含算术运算的 C 程序，执行程序 SHALL 输出正确的计算结果
+4. WHEN 编译包含函数调用的 C 程序，执行程序 SHALL 正确调用函数并返回结果
+5. WHEN 编译包含控制流语句（if/while/for）的 C 程序，执行程序 SHALL 正确执行控制流
+
+### Requirement 2: 增强错误报告
+
+**User Story:** AS 一个 C 程序员，I WANT 编译器提供包含代码上下文和位置提示的错误信息，SO THAT 能够快速定位和修复代码问题
+
+#### Acceptance Criteria
+
+1. WHEN 报告编译错误，错误信息 SHALL 包含文件名、行号和列号
+2. WHEN 报告语法错误，错误信息 SHALL 显示出错代码行及错误位置标记
+3. WHEN 报告类型错误，错误信息 SHALL 说明期望的类型和实际提供的类型
+4. WHEN 报告多个错误，编译器 SHALL 汇总所有错误并一次性输出
+5. IF 错误信息包含建议，建议 SHALL 提供可能的修复方向
+
+### Requirement 3: 清理误提交文件
+
+**User Story:** AS 一个仓库维护者，I WANT 从版本控制中移除构建产物和临时文件，SO THAT 保持仓库整洁并减小仓库体积
+
+#### Acceptance Criteria
+
+1. WHEN 提交代码，构建目录 `bin/` 和 `obj/` SHALL 被 `.gitignore` 排除
+2. WHEN 提交代码，临时测试文件 `test_output` SHALL 从版本控制中移除
+3. WHEN 提交代码，本地测试文件 `test.c` SHALL 从版本控制中移除
+
+### Requirement 4: 语义分析器完整实现
+
+**User Story:** AS 一个 C 编译器开发者，I WANT 语义分析器能够验证程序的语义正确性，SO THAT 拒绝语义错误的 C 程序
+
+#### Acceptance Criteria
+
+1. WHEN 遇到未声明的变量，语义分析器 SHALL 报告"未声明的标识符"错误
+2. WHEN 遇到类型不匹配的赋值操作，语义分析器 SHALL 报告类型不匹配错误
+3. WHEN 遇到函数调用参数数量不匹配，语义分析器 SHALL 报告参数数量错误
+4. WHEN 遇到函数调用参数类型不匹配，语义分析器 SHALL 报告参数类型错误
+5. WHILE 处理嵌套作用域，语义分析器 SHALL 正确解析变量的词法作用域
+6. WHEN 遇到重复的函数声明，语义分析器 SHALL 报告重复定义错误
+
+### Requirement 5: 预处理器集成到编译流程
+
+**User Story:** AS 一个 C 编译器用户，I WANT 编译器正确处理预处理指令，SO THAT 可以编译包含宏和头文件的 C 程序
+
+#### Acceptance Criteria
+
+1. WHEN 遇到 `#include` 指令，预处理器 SHALL 展开并包含指定头文件的内容
+2. WHEN 遇到 `#define` 宏定义，预处理器 SHALL 在后续代码中展开宏
+3. WHEN 遇到 `#ifdef`/`#ifndef` 条件编译，预处理器 SHALL 根据宏定义情况选择编译分支
+4. WHEN 预处理完成后，编译器驱动 SHALL 将预处理后的源代码传递给词法分析器
+5. IF 头文件不存在，预处理器 SHALL 报告错误并提供搜索路径信息
+
+### Requirement 6: 代码生成优化验证
+
+**User Story:** AS 一个编译器开发者，I WANT 验证优化后的代码生成器能够正确分配寄存器并生成高效代码，SO THAT 提升生成程序的执行性能
+
+#### Acceptance Criteria
+
+1. WHEN 使用优化代码生成器编译函数，寄存器分配算法 SHALL 为活跃变量分配物理寄存器
+2. WHEN 寄存器数量不足，寄存器分配算法 SHALL 正确地将变量溢出到栈
+3. WHEN 生成优化后的机器码，程序执行结果 SHALL 与未优化版本一致
+4. WHILE 分配寄存器，寄存器分配算法 SHALL 遵循调用约定保留被调用者保存的寄存器
+5. IF 代码生成器生成溢出代码，溢出区域 SHALL 正确管理栈帧布局
+
+### Requirement 7: DWARF 调试信息生成
+
+**User Story:** AS 一个 C 程序员，I WANT 编译器生成 DWARF 调试信息，SO THAT 可以使用 gdb 对生成的可执行文件进行源码级调试
+
+#### Acceptance Criteria
+
+1. WHEN 启用调试信息选项，编译器 SHALL 在 ELF 文件中生成 `.debug_info` 节
+2. WHEN 生成调试信息，调试信息 SHALL 包含源文件路径和行号映射
+3. WHEN 生成调试信息，调试信息 SHALL 包含变量名称、类型和作用域信息
+4. WHEN 使用 gdb 加载生成的可执行文件，gdb SHALL 能够显示源代码并设置断点
+5. IF 未启用调试信息选项，编译器 SHALL 不生成调试信息以减小文件体积
+
+### Requirement 8: PE 格式可执行文件支持
+
+**User Story:** AS 一个 Windows 用户，I WANT 编译器生成 Windows PE 格式的可执行文件，SO THAT 可以在 Windows 系统上运行编译后的程序
+
+#### Acceptance Criteria
+
+1. WHEN 指定目标平台为 Windows x64，编译器 SHALL 生成 PE32+ 格式的可执行文件
+2. WHEN 生成 PE 文件，PE 文件 SHALL 包含正确的 DOS 头和 PE 签名
+3. WHEN 生成 PE 文件，PE 文件 SHALL 包含有效的节表（`.text`、`.data`）
+4. WHEN 运行生成的 PE 文件，Windows 操作系统 SHALL 能够加载并执行程序
+5. WHEN 生成 PE 文件，PE 文件 SHALL 设置正确的入口点（Entry Point）
+
+### Requirement 9: 编译性能基准测试
+
+**User Story:** AS 一个编译器开发者，I WANT 建立编译性能基准，SO THAT 可以量化编译器性能变化并识别性能瓶颈
+
+#### Acceptance Criteria
+
+1. WHEN 运行性能基准测试，测试 SHALL 测量编译器处理标准 C 文件的编译时间
+2. WHEN 运行性能基准测试，测试 SHALL 测量生成代码的执行时间
+3. WHEN 运行性能基准测试，测试 SHALL 输出编译时间和执行时间的统计报告
+4. WHILE 进行性能优化，开发者 SHALL 能够对比优化前后的基准测试结果
+5. IF 性能基准测试发现回归，测试结果 SHALL 标记性能下降的模块