From b3dac750c08175f6d7291b157de8457d355ab02b Mon Sep 17 00:00:00 2001
From: Yaossg <yaossg@outlook.com>
Date: Sun, 17 Nov 2024 00:29:14 +0800
Subject: [PATCH] readme

---
 README.md | 119 ++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 112 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index a592a9e..8d078d7 100644
--- a/README.md
+++ b/README.md
@@ -1,21 +1,126 @@
 # RVBTCC
 
-- 约 1400 行的轻量级自举编译器
-- 编译器和自举编译器行为一致
-- 语法类似 C，输出 RISC-V 汇编
-- 依赖几个 libc 函数用于输入输出
-- 不使用动态内存分配，嵌入式友好
+- 约 1400 行的轻量级自举编译器。
+- 编译器和自举编译器行为一致。
+- 语法类似 C，输出 RISC-V 汇编。
+- 依赖几个 libc 函数用于输入输出。
+- 不使用动态内存分配，嵌入式友好。
 
 ## 用法
 
-编译运行程序
+目前没提供在 RISC-V 真机上运行和自举的脚本。下面是在其它平台设备上模拟的方案。
+
+安装以下依赖
+
+```sh
+sudo apt install gcc-12-riscv64-linux-gnu qemu-user qemu-system-misc
+```
+
+编译运行程序，src 为本语言源代码。可以编译 demo 文件夹下的实例。
 
 ```sh
 $ ./run.sh <src>
 ```
 
-自举编译器
+自举编译器，输出的文件位于 build 文件夹中。
 
 ```sh
 $ ./boot.sh
 ```
+
+输出六个文件：
+
+| 源代码            | 编译器    | 汇编    | 可执行    | 命名                   |
+| ----------------- | --------- | ------- | --------- | ---------------------- |
+| boot.c boot-lib.c | gcc       |         | gcc.out   | 自制编译器             |
+| boot.c boot-lib.h | gcc.out   | boot1.s | boot1.out | 自举自制编译器         |
+| boot.c boot-lib.h | boot1.out | boot2.s | boot2.out | 自举自举自制编译器     |
+| boot.c boot-lib.h | boot2.out | boot3.s |           | 验证自举自举自制编译器 |
+
+自举的目标为 boot1.s == boot2.s == boot3.s
+
+## 语言文档
+
+### 关键字
+
+本语言包含的关键字即为支持的标量类型的关键字和流程控制的关键字。
+
+此外还支持 `const` 关键字，但是行为是直接忽略。这是为了更好兼容 C 程序。
+
+### 支持六个基本类型
+
+| 标量类型 | 指针类型 |
+| -------- | -------- |
+| `void`   | `void*`  |
+| `char`   | `char*`  |
+| `int`    | `int*`   |
+
+- 注意指针类型不是复合得来的，而是被视作整体。因此也不存在二重指针。
+
+- 函数和数组不是类型系统的一部分。
+  - 可以认为数组的名字就是对应的指针类型。
+  - 函数名字本身建议仅用于直接调用，其它行为可视为 UB。
+- 数组只支持一维数组，且数组的元素不能是指针类型。
+- 全局变量不能是指针类型。
+
+### 支持的流程控制
+
+- `if` `else`
+- `while` `for`
+- `break` `continue`
+- `return`
+
+
+### 支持以下运算符
+
+| 运算符                            | 含义                                            | 结合性   |
+| --------------------------------- | ----------------------------------------------- | -------- |
+| `++` `--` `()` `[]`               | 后缀自增自减 函数调用 数组下标                  | 从左到右 |
+| `++` `--` `+` `-` `*` `&` `!` `~` | 前缀自增自减 正负号 取地址 解引用 逻辑非 按位非 | 从右到左 |
+| `*` `/` `%`                       | 乘除余                                          | 从左到右 |
+| `+` `-`                           | 加减                                            | 从左到右 |
+| `<<` `>>`                         | 左移和算术右移                                  | 从左到右 |
+| `<` `<=` `>` `>=`                 | 关系比较                                        | 从左到右 |
+| `==` `!=`                         | 相等比较                                        | 从左到右 |
+| `&`                               | 按位与                                          | 从左到右 |
+| `^`                               | 按位异或                                        | 从左到右 |
+| `|`                               | 按位或                                          | 从左到右 |
+| `&&`                              | 逻辑与                                          | 从左到右 |
+| `||`                              | 逻辑或                                          | 从左到右 |
+| `=`                               | 赋值                                            | 从右到左 |
+
+- 加减号支持整数之间，指针与整数，指针之间的运算。
+- 逻辑与和逻辑或支持短路求值。
+
+### 其它支持与不支持
+
+- 支持全局变量和局部变量，局部变量遮挡全局变量。
+- 重名的局部变量为同一变量，不支持局部变量之间的遮挡。
+- 函数只支持最多八个参数。支持可变参数。
+- 支持函数声明，不支持变量声明。
+- 类型检查做的较少，若 C 编译器报错，而本语言编译通过，就可以认为是 UB。
+
+## 限制
+
+编译过程中涉及的以下参数：
+
+- 符号表总长度、字符串表总长度
+- 符号数、字符串数、全局变量数、局部变量数
+
+不能超过源代码中指定的常数。如果有必要这些常数可以适度加大。
+
+目前源代码中的常数能够保证自举。
+
+## 依赖
+
+直接依赖下面这些 C 语言库函数，在本语言中提供声明后调用。
+
+- `printf`
+- `getchar`
+- `exit`
+
+间接依赖下面这些 C 语言库函数，在 C 语言中进行封装后调用。
+
+- `ungetc`（理论上非必须，可以在本语言中手动模拟）
+- `vfprintf` 和可变参数有关的宏（用于输出调试信息，非必须）
+