One runner means a push that lands while an older one is still building waits for it. Cancel-in-progress keeps the queue at one entry per branch; a manual sweep is still only cancelled by another push on the same ref.
R8Forge
ROT-8(1-Bit Brainfuck)的汇编器 + 汇编期合成器,一个仓库一份进程。
搜索器不再是独立程序:%synth 是汇编期指令,你给它一张真值表,它现场搜出最短的块序列
直接拼进纸带。代价模型和发射器从此是同一份代码,不用再维护两套"这个块要花多少条指令"
的估算。
细节(契约、数字、坑)都在别的文件里,这份 README 只负责"怎么跑起来"和"去哪儿看":
| 想查什么 | 去哪儿 |
|---|---|
%synth 完整语法、机器几何、每个宏的契约(吃什么留什么、几个 cell、纸带多长、谁验证) |
SPEC.md |
| 怎么干活、踩过的坑、当前交接、别动清单 | AGENTS.md |
| 设计推理长文(为什么这么写、失败的尝试) | docs/ |
| 还没做的事(候选、优化、工具) | TODO.md |
30 秒上手
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:用真值表写代码
%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
三条要注意的:
map的项数决定输入个数:2^K 项就是%1..%K为输入,值的第 j 位落到%(K+j+1),剩下的参数是必须结束为 0 的草稿。要完全显式(或输入不在最前面)就用stat(整张状态表,2^params 项)。- 默认按"布局无关"口径搜(flat):结果与 cell 布局无关,缓存能跨调用点复用。
想按真实
.tp行走重新搜,加--synth-chars。full_add 上两种口径是 95 / 90 字符。 mode layers只求层数最少(快),mode tape(默认)求纸带最短。
结果按"真值表 + 口径"缓存在 .r8forge_cache/(已入库,克隆下来直接命中);要重算就删
那个目录。缓存键里带 kModelVersion,改指令模型必须 bump 它(src/synth.cc)。
常用开关
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 只剩纸带
-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/ 标准库(48 个宏,含 8 个 %synth 合成块)
drv/ 单点验证驱动(喂固定输入跑一个宏,看 out/stat)
examples/ 15 个能跑的例程:每组宏一份 + %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 |
乘、除、整数 ↔ 4 位 ASCII |
契约(签名、参数类型、cell 数、纸带长度、由哪个测试验证)在 SPEC.md §5–§9;
为什么是现在这样(以及那些失败尝试)在 docs/byte-ops.md。
例子
examples/ 里每个 .r8asm 都是能跑的程序,头部 ; out ... 写它打印什么:
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 §10.3。
构建与自检
cmake -S . -B build -G "Visual Studio 18 2026" -A x64
cmake --build build --config Release
build/Release/r8forge asm/test.r8asm # 全家桶:每个标准宏至少一次
build/Release/r8forge_synth_test examples/full_add.r8asm # 合成的块 + 虚拟机自检
build/Release/r8forge_byte_op_test # 字节级库穷举
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
build/ 已经配好生成器:重编译请用给它配的那个 cmake(PATH 上的另一个版本会重新配置,
然后死在 No preprocessor test for "PellesC"),命令和"当前基线"的数字见
AGENTS.md。
细节去哪看
SPEC.md—— 唯一事实源:%synth语法语义、几何、每个宏的契约、验证矩阵、 边界、维护清单。AGENTS.md—— 工作手册:构建/自检命令、硬规则、坑、当前交接。docs/divmod.md——clb_divmod的移位-恢复除法:每轮状态、坑、实测。docs/byte-ops.md—— 字节级库的设计推理与教训。TODO.md—— 还没做的事:交互计算器、纸带优化器、--profile、缓存体检、CI。