# 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 正确解析