# R8Forge ROT-8(1-Bit Brainfuck)的**汇编器** + **汇编期合成器**,一个仓库一份进程。 搜索器不再是独立程序:`%synth` 是汇编期指令,你给它一张真值表,它现场搜出最短的块序列 直接拼进纸带。代价模型和发射器从此是同一份代码,不用再维护两套"这个块要花多少条指令" 的估算。 细节(契约、数字、坑)都在别的文件里,这份 README 只负责"怎么跑起来"和"去哪儿看": | 想查什么 | 去哪儿 | |---|---| | `%synth` 完整语法、机器几何、**每个宏的契约**(吃什么留什么、几个 cell、纸带多长、谁验证) | [`SPEC.md`](SPEC.md) | | 怎么干活、踩过的坑、当前交接、别动清单 | [`AGENTS.md`](AGENTS.md) | | 设计推理长文(为什么这么写、失败的尝试) | [`docs/`](docs/) | | 还没做的事(候选、优化、工具) | [`TODO.md`](TODO.md) | ## 30 秒上手 ```sh cmake -S . -B build -G "Visual Studio 18 2026" -A x64 # 或者 Ninja / Makefile cmake --build build --config Release build/Release/r8forge examples/full_add.r8asm > adder.rot8 # 纸带进 stdout,说明进 stderr build/Release/r8forge_tape_run.exe adder.rot8 # 跑一遍,打印 out 和步数 ``` `examples/` 里每个 `.r8asm` 头部都有一行 `; out ...`,写着它应该打印什么;跑出来的 `out` 和那行一致才算对。 ## `%synth`:用真值表写代码 ```asm %include "asm/lib.r8asm" %synth fulladd params 6 map 0 1 1 2 1 2 2 3 ; 8 个输入组合各自的输出位取值,%1..%3 是输入 layout 0 1 2 3 4 5 ; 可选:各参数所在 cell 的地址(默认 0..n-1) %endsynth .var A 0 .var B 1 .var Ci 2 .var S 3 .var Co 4 .var T 5 fulladd A B Ci S Co T ; 这一行展开成汇编期合成的最短纸带 output S output Co ``` 三条要注意的: 1. **`map` 的项数决定输入个数**:2^K 项就是 `%1..%K` 为输入,值的第 j 位落到 `%(K+j+1)`,剩下的参数是必须结束为 0 的草稿。要完全显式(或输入不在最前面)就用 `stat`(整张状态表,2^params 项)。 2. **默认按"布局无关"口径搜**(flat):结果与 cell 布局无关,缓存能跨调用点复用。 想按真实 `.tp` 行走重新搜,加 `--synth-chars`。full_add 上两种口径是 **95 / 90 字符**。 3. `mode layers` 只求层数最少(快),`mode tape`(默认)求纸带最短。 结果按"真值表 + 口径"缓存在 `.r8forge_cache/`(**已入库**,克隆下来直接命中);要重算就删 那个目录。缓存键里带 `kModelVersion`,改指令模型必须 bump 它(`src/synth.cc`)。 ### 常用开关 ```sh r8forge asm/test.r8asm # 汇编,stdout 是纸带 r8forge --synth-chars examples/full_add.r8asm # 按真实布局重新搜 r8forge -j 4 examples/full_add.r8asm # 纸带搜索最多 4 个 worker(默认每硬件线程一个) r8forge -q examples/full_add.r8asm > full_add.rot8 # stdout 只剩纸带 r8forge --opt asm/test.r8asm > t.rot8 # 纸带窥孔优化:62351 -> 56338 字符 ``` `-j` 只影响纸带搜索(层数搜索是串行的);`-q` 只压 stdout,错误照旧进 stderr、退出码不变。 ## 目录结构 ``` include/r8forge/r8asm.hh 汇编器 + %synth 指令 include/r8forge/r8veritas.hh 搜索器 include/r8forge/geometry.hh 默认几何(11 位 × 259 格) src/r8asm.cc 汇编器实现 src/synth.cc 真值表 -> 搜索 asm/ 标准库(55 个宏,含 8 个 %synth 合成块) drv/ 单点验证驱动(喂固定输入跑一个宏,看 out/stat) examples/ 19 个能跑的例程:每组宏一份 + %synth 的几种写法 + 交互例程 tests/ 汇编器 / 虚拟机 / 字节级 / 例程 / 文档格式 自检 docs/ 设计笔记(长文) .r8forge_cache/ 合成结果缓存(已入库) SPEC.md AGENTS.md README.md 契约 / 工作手册 / 本文件 ``` ## 标准库 `asm/` 分四层,全部**位宽无关**(宏里写 `%rep _CELL_SIZE`,改几何自动跟着变): | 层 | 代表 | 一句话 | |---|---|---| | 位级(一个 cell 装一位) | `clb_bit_add_nc`、`bit_raw_add` | 8 个块是 `%synth` 合成的,与手写逐位一致 | | 字节级(一个 cell 一个机器字) | `raw_add`、`clb_add_nc` | `raw_*` 保留操作数、`clb_*_nc` 吃掉它们换 cell | | 原地 | `clb_inc_ip`、`clb_add_ip` | 结果回到原 cell,2~4 个 cell 就够 | | 大宏 | `clb_mul`、`clb_divmod`、`clb_digits`、`clb_undigits`、`clb_digits_signed`、`clb_divmod_signed` | 乘、除、整数 ↔ 4 位 ASCII;带 `signed` 的两个是二补码包装(负数显示/截断除法) | 契约(签名、参数类型、cell 数、纸带长度、由哪个测试验证)在 [`SPEC.md`](SPEC.md) §5–§9 (有符号数在 §5.4 + §7.10);为什么是现在这样(以及那些失败尝试)在 [`docs/byte-ops.md`](docs/byte-ops.md)。 ## 例子 `examples/` 里每个 `.r8asm` 都是能跑的程序,头部 `; out ...` 写它打印什么: ```sh build/Release/r8forge examples/digits_demo.r8asm > t.rot8 build/Release/r8forge_tape_run.exe t.rot8 # 打印 out 和步数 ``` `r8forge_examples_test` 会把它们全跑一遍、逐项核对头部那行 —— 例程不会悄悄腐掉。要喂输入的例程\n在头部多写一行 `; in ...`(`examples/echo_chars.r8asm` 是最小的例子),测试会先把那串字符\n交给 `inp`。每份例程 演示哪一组宏见 [`SPEC.md`](SPEC.md) §10.3。 ## 构建与自检 ```sh cmake -S . -B build -G "Visual Studio 18 2026" -A x64 cmake --build build --config Release build/Release/r8forge asm/test.r8asm # 全家桶:除两个 signed 包装宏外每个标准宏至少一次 build/Release/r8forge_synth_test examples/full_add.r8asm # 合成的块 + 虚拟机自检 build/Release/r8forge_byte_op_test # 字节级库穷举(23 项,含带符号数的全扫) build/Release/r8forge_examples_test # 例程 + 全家桶,核对 `; out` build/Release/r8forge_macro_docs_test # 宏注释格式 build/Release/r8forge_derive verify_loop.r8asm -1 0=5 # 动态循环:out 应该是 5 0 ctest --test-dir build -C Release -j 4 --output-on-failure # 上面这些一次跑完(8 条,约 12 秒) ``` `build/` 已经配好生成器:重编译请用**给它配的那个 cmake**(PATH 上的另一个版本会重新配置, 然后死在 `No preprocessor test for "PellesC"`),命令和"当前基线"的数字见 [`AGENTS.md`](AGENTS.md)。 ## 细节去哪看 * [`SPEC.md`](SPEC.md) —— 唯一事实源:`%synth` 语法语义、几何、每个宏的契约、验证矩阵、 边界、维护清单。 * [`AGENTS.md`](AGENTS.md) —— 工作手册:构建/自检命令、硬规则、坑、当前交接。 * [`docs/divmod.md`](docs/divmod.md) —— `clb_divmod` 的移位-恢复除法:每轮状态、坑、实测。 * [`docs/byte-ops.md`](docs/byte-ops.md) —— 字节级库的设计推理与教训。 * [`TODO.md`](TODO.md) —— 还没做的事:迷你 `printf`、纸带优化器、 `--profile`、缓存体检、CI。 * [`docs/calc.md`](docs/calc.md) —— 桌上计算器:命令协议、3 格 RPN 栈、终端外壳(回显/ 退格/提示符)、分阶段计划。 * [`docs/hardware.md`](docs/hardware.md) —— 造一台真的 ROT-8:硬件需求、ROM/RAM 预算、 FPGA / 分立 TTL / 机电三档载体、打包器与 RTL 对拍路线。