commit initial

.monkeycode/specs/2026-05-20-tiny-c-compiler-csharp/requirements.md

@@ -0,0 +1,116 @@
+# Requirements Document
+
+## Introduction
+
+本项目旨在开发一个使用 C# 语言编写的 C 语言编译器，参考 TCC（Tiny C Compiler）的设计理念。编译器将 C 源代码直接编译为 x86/x64 本地机器码，而非 MSIL（Microsoft Intermediate Language）。目标是实现一个轻量级、快速的 C 编译器，支持 C99 标准的核心特性。
+
+## Glossary
+
+- **TCC**: Tiny C Compiler，一个小型、快速的 C 编译器
+- **本地代码**: 直接可在 CPU 上执行的机器码（x86/x64）
+- **MSIL**: Microsoft Intermediate Language，.NET 平台的中间语言
+- **代码生成**: 将中间表示转换为目标机器码的过程
+- **词法分析**: 将源代码分解为 token 流的过程
+- **语法分析**: 将 token 流构建为抽象语法树（AST）的过程
+- **语义分析**: 验证 AST 的语义正确性并进行类型检查
+- **目标平台**: x86 (32-bit) 和 x64 (64-bit) Windows/Linux
+
+## Requirements
+
+### Requirement 1: 词法分析器
+
+**User Story:** AS 一个 C 编译器开发者，I WANT 实现词法分析器，SO THAT 可以将 C 源代码转换为 token 流
+
+#### Acceptance Criteria
+
+1. WHEN 接收到 C 源代码文件，词法分析器 SHALL 输出 token 流
+2. WHEN 遇到 C 语言关键字（if, else, while, for, int, char 等），词法分析器 SHALL 识别为关键字 token
+3. WHEN 遇到标识符，词法分析器 SHALL 识别为标识符 token
+4. WHEN 遇到字面量（整数、浮点数、字符、字符串），词法分析器 SHALL 识别为相应的字面量 token
+5. WHEN 遇到注释（单行 // 和多行 /* */），词法分析器 SHALL 忽略注释内容
+6. WHEN 遇到词法错误，词法分析器 SHALL 报告错误位置和错误信息
+
+### Requirement 2: 语法分析器
+
+**User Story:** AS 一个 C 编译器开发者，I WANT 实现语法分析器，SO THAT 可以将 token 流构建为抽象语法树（AST）
+
+#### Acceptance Criteria
+
+1. WHEN 接收到 token 流，语法分析器 SHALL 构建 AST
+2. WHEN 遇到语法错误，语法分析器 SHALL 报告错误位置和错误描述
+3. WHILE 解析表达式，语法分析器 SHALL 正确处理运算符优先级
+4. WHEN 解析函数定义，语法分析器 SHALL 识别函数名、参数列表和函数体
+5. WHEN 解析控制流语句（if, while, for, switch），语法分析器 SHALL 构建对应的控制流 AST 节点
+
+### Requirement 3: 语义分析器
+
+**User Story:** AS 一个 C 编译器开发者，I WANT 实现语义分析器，SO THAT 可以验证 AST 的语义正确性
+
+#### Acceptance Criteria
+
+1. WHEN 接收到 AST，语义分析器 SHALL 执行类型检查
+2. WHEN 遇到未声明的变量，语义分析器 SHALL 报告错误
+3. WHEN 遇到类型不匹配的赋值或运算，语义分析器 SHALL 报告类型错误
+4. WHEN 遇到函数调用，语义分析器 SHALL 验证函数签名和参数类型
+5. WHILE 解析作用域，语义分析器 SHALL 正确管理变量的作用域
+
+### Requirement 4: 中间表示（IR）生成
+
+**User Story:** AS 一个 C 编译器开发者，I WANT 生成中间表示，SO THAT 可以优化并转换为目标机器码
+
+#### Acceptance Criteria
+
+1. WHEN 接收到语义分析后的 AST，IR 生成器 SHALL 输出三地址码形式的 IR
+2. WHEN 生成 IR，IR 生成器 SHALL 处理控制流图的构建
+3. WHILE 生成 IR，IR 生成器 SHALL 支持基本的数据流分析
+
+### Requirement 5: 代码生成器（x86/x64）
+
+**User Story:** AS 一个 C 编译器开发者，I WANT 实现代码生成器，SO THAT 可以将 IR 转换为 x86/x64 本地机器码
+
+#### Acceptance Criteria
+
+1. WHEN 接收到 IR，代码生成器 SHALL 输出 x86/x64 机器码
+2. WHEN 处理函数调用，代码生成器 SHALL 遵循目标平台的调用约定（calling convention）
+3. WHEN 处理局部变量，代码生成器 SHALL 分配栈空间
+4. WHEN 处理全局变量，代码生成器 SHALL 在数据段分配空间
+5. IF 目标平台为 x64，代码生成器 SHALL 使用 x64 寄存器
+6. IF 目标平台为 x86，代码生成器 SHALL 使用 x86 寄存器
+
+### Requirement 6: 可执行文件生成
+
+**User Story:** AS 一个 C 编译器用户，I WANT 编译器生成可执行文件，SO THAT 可以直接运行编译后的程序
+
+#### Acceptance Criteria
+
+1. WHEN 编译完成，编译器 SHALL 生成 PE（Windows）或 ELF（Linux）格式的可执行文件
+2. WHEN 生成 PE 文件，编译器 SHALL 包含正确的 PE 头和节表
+3. WHEN 生成 ELF 文件，编译器 SHALL 包含正确的 ELF 头和节头
+4. WHEN 生成的可执行文件被操作系统加载，操作系统 SHALL 能够正确执行程序
+
+### Requirement 7: 命令行接口
+
+**User Story:** AS 一个 C 编译器用户，I WANT 使用命令行编译 C 文件，SO THAT 可以方便地集成到构建系统中
+
+#### Acceptance Criteria
+
+1. WHEN 用户提供源文件路径，编译器 SHALL 编译并生成可执行文件
+2. WHEN 用户指定输出文件名，编译器 SHALL 使用指定的文件名
+3. WHEN 用户指定目标架构（x86/x64），编译器 SHALL 生成对应架构的代码
+4. IF 编译过程中发生错误，编译器 SHALL 输出错误信息并返回非零退出码
+5. WHEN 用户请求帮助信息，编译器 SHALL 显示使用说明
+
+### Requirement 8: C99 核心特性支持
+
+**User Story:** AS 一个 C 程序员，I WANT 编译器支持 C99 核心特性，SO THAT 可以编译现有的 C 代码
+
+#### Acceptance Criteria
+
+1. WHEN 编译 C99 代码，编译器 SHALL 支持基本数据类型（int, char, float, double, long, short）
+2. WHEN 编译 C99 代码，编译器 SHALL 支持指针和数组
+3. WHEN 编译 C99 代码，编译器 SHALL 支持结构体（struct）和联合体（union）
+4. WHEN 编译 C99 代码，编译器 SHALL 支持函数定义和调用
+5. WHEN 编译 C99 代码，编译器 SHALL 支持控制流语句（if, else, while, for, do-while, switch, break, continue, return）
+6. WHEN 编译 C99 代码，编译器 SHALL 支持宏定义（#define）和条件编译（#ifdef, #ifndef, #endif）
+7. WHEN 编译 C99 代码，编译器 SHALL 支持头文件包含（#include）
+8. IF 使用 C99 特性（如单行注释 //），编译器 SHALL 正确解析