项目结构
仓库 UCPU (项目 Code CIN / 包 codecin) 由三部分组成: Python 包 codecin/ (CLI 外壳 + 编译/装载编排 + 结果回写)、Go 原生库/编译器 codecin/native/ (语言实现核心: CIN 编译器、字节码 VM、CROM、AOT 运行时、cincc 原生编译器)、 以及 docs/ 官方文档站 (VitePress, 同时是独立仓库 Code-CIN-Docs, 以 git submodule 内嵌)。
v5.9.0 起 Code CIN 为 native-only 架构: 纯 Python 解释器与 JIT 已整体删除, 默认路径统一由 Go 原生引擎执行 (ABI v2, 整程序一次调用)。v7.22.10 另有 --native 的 cincc 机器码主线。
顶层目录树
text
UCPU/
├── cpu.py # 唯一 CLI 入口 (转发到 codecin.cli: main)
├── codecin/ # Python 主包
│ ├── lib/ # 内置标准库 pic 包 (pic.toml + src/<name>.cin)
│ ├── native/ # Go 原生库源码 (module codecin-native)
│ └── ...
├── tests/ # pytest 套件 (test_*.py + helpers/conftest)
├── script/ # 代码生成、版本脚本、安装脚本
├── examples/ # 示例程序 (.cin / .asm)
├── misc/ # 编辑器支持 (vim 语法/文件类型检测)
├── docs/ # 官方文档站 (VitePress, 独立 git 仓库)
├── .github/workflows/ # CI 与 Release 工作流
├── basic.cin # CIN 综合示例 (回归基准)
├── test_asm.asm # 汇编测试样例
├── pyproject.toml # 项目元数据 + dynamic version + package-data
├── setup.py # BuildPyWithNative 构建钩子 (现场编译原生库)
├── MANIFEST.in # sdist 清单
├── build.sh / build.bat # PyPI 发布脚本 (只发 sdist)
├── requirements.txt # 运行时依赖 (rich)
├── requirements-dev.txt # 开发依赖 (pytest / pytest-cov / ruff)
├── CHANGELOG.md / LICENSE / README.md
└── .editorconfig / .gitattributes / .gitignorecodecin/ — Python 包
| 模块 | 职责 |
|---|---|
__init__.py | 包导出 (CPU/Config/Syscall/Opcode/Constants/CPUSimulatorError 等) 与版本号单一真源 __version__ = "x.y.z" |
cli.py | 命令行入口: build_parser() (argparse) → Config → 加载 → 运行; 唯一参数表来源 |
config.py | Config dataclass: 全部运行配置字段 + validate() 夹取 (内存默认 1 GiB) |
cpu.py | CPU 编排 (native-only): 编译/装载 (.cin/.asm/.pl/.sdgcc/.bin/.crom) → 一次调用 Go 引擎 → 回写寄存器/内存/统计 |
isa.py | 指令集定义: Opcode、Syscall (0–157)、Cond、Constants、KIND_*、BC_MAGIC |
assembler.py | ASM / PL 汇编器: .equ 常量、表达式、数据段、标签、内存操作数 |
cin.py | CIN 高级语言编译器: 词法/语法/代码生成、import 展开、HOST_BUILTINS 表 |
memory.py | FastMemory 稀疏分页内存 (4 KiB 页按需分配, resident_bytes 只算已触碰页) 与逐字节保护表 |
registers.py | RegisterFile (X0–X31/XZR) 与 VectorRegisterFile (V0–V31 × 4 lane) |
stats.py | 统计载体: Statistics / PerformanceCounters / InstructionProfiler / BranchPredictor (默认路径下主要承载引擎回传的步数) |
sdgcc.py | .sdgcc 容器读写: v1/v2 头部、CODE/META/SYMS/SRCS 段、可选 zlib 压缩 (CODE 段 = BIN v3) |
crom.py | 段式 CROM v4 镜像与 BIN v3 容器读写 (只存已分配页; 兼容读旧 CROM v3 / BIN v2) |
native.py | Go 原生库 ctypes 桥接: 库查找、ABI v2 codecin_run_v2 调用与结果解码 |
aot.py | AOT 编排: 依赖检查 → 编译/优化 → C/Go native/VM 后端 → 独立产物; 缓存/调试构建 |
cbackend.py | C 后端: 指令流 → C 源码, 调 GCC/Clang/zig cc 产出独立可执行文件 |
native_codegen.py | 旧 Go native 后端: 指令流 → 直接调用 NativeRuntime 的 Go 源码 (基本块拆分) |
optimizer.py | IR 优化器: -O0..3 (窥孔/常量折叠/不可达代码删除) |
object.py | 可重定位 .co 对象、.colib 归档、链接器、重定位与链接期 GC |
disasm.py | 反汇编 .sdgcc / .bin 字节码为文本清单 (支持 BIN v3 与旧 BIN v2 头) |
environment.py | 宿主工具链检测与安装提示 (find_tool/install_hint/native_runtime_hint), 供 AOT、pip 安装与 --build-info 环境自检共用 |
stdlib.py | 内置标准库清单与分类 (library_report, 按"纯 CIN / 兼容层 / 需原生运行时"三分类), 驱动 --libs |
console.py | rich 适配层: Console / Table / Panel / Colors (模块禁止直接 print) |
logger.py | rich 日志器: DEBUG/INFO/WARNING/ERROR/CRITICAL + trace / dump / hexdump |
version.py | 版本设施: version_tuple / compare / version_info (纯函数) 与 build_info() 环境自检 (永不抛异常), 驱动 --build-info 与 bump_version.py |
errors.py | 异常层次: CPUSimulatorError 及子类 |
随包分发的二进制: codecin_native.dll 与 codecin_native.h (Windows 预编译库与 c-shared 头文件)。
text
codecin/lib/<name>/src/<name>.cin (41 个内置标准库, import 时按裸名字解析到这里)
array bigint bits bitset codec combin conv cppstd cstd csv
dp ffi fmt frac gostd graph gui hash heap io json key
math matrix net path queue rand set sort stat str termux
test text time token tree unionfind validate veccodecin/native/ — Go 原生库
Go 模块名 codecin-native, go.mod 声明 go 1.26。
text
codecin/native/
├── go.mod # module codecin-native / go 1.26 (无第三方依赖)
├── main.go # package main: cgo c-shared 库入口
├── cmd/cincc/main.go # package main: cincc 编译器命令 (-o / -target / -v)
├── build.sh / build.ps1 # Linux/Termux/macOS 与 Windows 构建脚本
├── ir/ # 中间表示: ir.go (Program / Instr / Operand / DataWrite)
├── engine/ # 字节码 VM 与运行时
│ ├── vm.go # 原生字节码 VM (engine.Run, ABI v2 整程序执行)
│ ├── native.go # NativeRuntime: native 后端的指令原语 (直接调用)
│ ├── ops_ext.go # 扩展指令实现
│ ├── crom.go # CROM 打包/解包
│ ├── encode.go # IR → UCBC 编码
│ ├── isa_gen.go # 生成物: 操作码/操作数种类/SYS 常量 (勿手改)
│ ├── version_gen.go # 生成物: BuildVersion (勿手改)
│ ├── args.go # CLI 裸参数 (arg_count/arg) 与行输入
│ ├── hostnet.go / netsock.go # HTTP / TCP / UDP / DNS 宿主调用
│ ├── ffi_registry.go / ffi_windows.go / ffi_unix.go / ffi_nocgo.go
│ │ # FFI 动态库调用 (cgo 实现带构建标签, !cgo 桩)
│ ├── canvas.go # 2D 画布 (image/png, 导出 PNG)
│ ├── gui*.go # GUI 窗口 (windows / x11 / stub 三实现)
│ ├── audio.go + audio_windows.go / audio_other.go # 音频后端 (//go:build 拆分)
│ ├── keyboard*.go / stdin*.go / console_*.go / mem_*.go
│ │ # 键盘/标准输入/控制台/内存分配的平台实现
│ ├── system.go # 文件/进程/环境/系统信息宿主调用
│ ├── termux.go # Termux API (termux-* 命令)
│ ├── hostdesktop.go / hostcrypto.go # 桌面集成 (剪贴板/通知/open_url) 与哈希编码
│ └── *_test.go # Go 侧单元测试
├── compiler/ # Go 版 CIN 编译器 (与 cin.py 双语对齐)
│ ├── tokenizer.go / parser.go / types.go / codegen.go
│ ├── syscalls.go # 生成物: SYS 功能号常量 (勿手改)
│ └── compile_test.go
├── mc/ # cincc 原生编译器: 指令选择/寄存器分配/ELF 写出
│ ├── *.go # x86-64 稳定, AArch64 骨架; runtime 内建
│ └── *_test.go # go test ./mc
├── aot/ # AOT 产物运行时
│ ├── aot.go # aot.Main(bytecode, memImage) -> int (VM 后端)
│ └── stub_main.go.txt # VM 产物入口模板
└── native_test.go / *_test.goGo 侧有两个 package main: c-shared 库入口 main.go, 以及编译器命令 cmd/cincc/。cincc 只负责把 CIN 编译为机器码, 不提供运行/日志/调试命令; 用户命令行入口仍是 Python (codecin / 安装后的 console script)。历史版本里的 cmd/codecin/ 全 Go CLI 已移除, 现在新增的 cmd/cincc 是编译器而非用户 CLI。
三语言输入与两条执行主线
text
输入 (三语言) 前端 中间产物
─────────────────────────────────────────────────────────────────────────
.cin (CIN 高级语言) ──► cin.py / compiler/*.go ──► UCBC 字节码
.pl (PL 关键字汇编) ──► assembler.py ──► UCBC 字节码
.asm (ASM 汇编) ──► assembler.py ──► UCBC 字节码
.sdgcc (默认容器) ──► sdgcc.unwrap ──► BIN v3 + 元数据/符号/源码清单
.bin (CPUSA 容器) ──► crom.load_bin ──► UCBC 字节码 + 内存镜像
.crom (CROM v4 镜像) ──► crom.load_crom ──► 内存镜像text
执行 (两条主线)
─────────────────────────────────────────────────────────
默认路径: .sdgcc ─► Go 原生 VM (native.py → ctypes → codecin_run_v2, ABI v2)
整程序一次调用, 回传寄存器/向量/NZCV/脏内存段/输出
动态库缺失时抛 CPUSimulatorError 并附重建指引, 无回退
原生路径: .cin ─► cincc (Go) ─► x86-64 ELF ─► 操作系统直接执行
--native / --native-out; Windows 经 WSL; 覆盖语言子集tests/ — 测试套件
| 文件 | 覆盖点 |
|---|---|
conftest.py | 会话级工作目录夹具 (workdir, 落在仓库内 .pytest_tmp/) |
helpers.py | new_cpu / run_program / run_cin_source / run_cin_file / asm_program / snapshot |
test_isa_single_source.py | ISA 单一真源守卫: 各手写映射表与 isa.py 不漂移 |
test_assembler_ext.py | 汇编器 .equ / 表达式 / 符号算术 / 数据段表达式 |
test_cli.py | argparser 选项、帮助文本、退出码 |
test_sparse_memory.py | 稀疏分页内存: 按需分配页、resident_bytes、越界与负地址提示 |
test_features_ab.py | --bounds-check / --seed 确定性 / --disasm |
test_cin_syntax.py | CIN 新语法: break/continue、do-while、switch、复合赋值、三目、类型别名 |
test_cin_new_features.py | 位运算、idiv、字符串单字符、min/max、floor/ceil/round、atoi、trim |
test_switch_semantics.py | switch 语义回归 (Go 与 Python 双编译器对齐) |
test_literals_and_bom.py | 数值字面量与 UTF-8 BOM import 的双端一致性 |
test_compiler_errors.py | 非法程序必须被 Go 与 Python 两侧同时拒绝 |
test_features_import.py | 字符串内建 + import/lib 模块化 |
test_features_importloc.py | import 行级源映射 (file:line 精确定位) |
test_libs.py | 官方标准库行为回归 |
test_libs_ext.py | 新增标准库 bits/stat/hash/validate/matrix/queue |
test_lib_*.py | 逐库回归: bigint/bitset/codec/combin/csv/dp/frac/fmt/graph/heap/set/text/token/tree/unionfind 等 |
test_ffi_net.py | FFI 动态库调用与网络系统调用 (TCP/UDP/DNS/HTTP 扩展) |
test_cin_host.py / test_cin_host_ext.py | CIN 宿主能力 (画布 / 联网音频 / 桌面集成) |
test_gui.py / test_keyboard.py | GUI 窗口与键盘轮询 (需真实显示/终端, 无则 skip) |
test_cin_system.py | 系统原生交互 / Termux API 内建 |
test_environment.py | 工具链检测与安装提示 (environment.py) |
test_examples.py | examples/ 示例冒烟 (结果确定) |
test_native_hardening.py | 原生库加固: 步数用尽报错、不可信输入、缓冲上限 |
test_native_lib_lookup.py | 原生库查找顺序: 架构专属名优先于通用名 |
test_sdgcc.py | .sdgcc 容器读写: 头部/段表/压缩/兼容 BIN v3 |
test_cbackend.py | C 后端: 指令展开、目标映射、编译与运行 |
test_bin_compat.py | BIN v3 / 旧 v2 只读兼容 |
test_no_go_cli.py | Go 侧入口约定: c-shared 库入口 + cmd/cincc 编译器, 无用户 CLI |
test_aot.py | AOT 产物可独立运行、交叉编译、静态链接 (无 PT_INTERP)、目标解析 |
test_packaging.py | 打包设计门禁: package-data / MANIFEST / 只发 sdist / BuildPyWithNative |
test_version.py | 版本设施: pyproject dynamic / Go BuildVersion / semver / --version / --build-info; build_info() 绝不抛异常; bump_version.py 全链路; CHANGELOG.md 必须含当前版本小节 |
test_workflows.py | GitHub Actions 工作流静态校验 (表达式函数、matrix 引用、job/step 形状) |
script/、examples/、misc/
| 路径 | 说明 |
|---|---|
script/gen_isa_docs.py | 由 isa.py 生成仓库指令表 docs/ISA.md 与站点页 docs/reference/isa.md; --check 校验 |
script/gen_native_isa.py | 由 isa.py 生成 engine/isa_gen.go、compiler/syscalls.go、engine/version_gen.go; --check 校验 |
script/bump_version.py | 一条命令提版本: 校验 → 改 __init__.py → 重生成 version_gen.go → 插入 CHANGELOG 骨架 |
script/install_termux.sh | Termux (Android) 安装辅助脚本 |
examples/*.cin | control_flow / literals_types / modules_demo / stdlib_demo / bitwise_builtins / system_interaction |
examples/asm_constants.asm | 汇编器 .equ 与表达式示例 |
misc/vim/ | Vim 支持: ftdetect/codecin.vim、syntax/cin.vim、syntax/codecinasm.vim |
关键约束
1. Go 侧不提供用户 CLI
语言实现全在 Go (codecin/native/ 下的 CIN 编译器、字节码 VM、CROM), 但 Go 侧 没有用户命令行入口。允许的 package main 有两个:
main.go: cgo 的 c-shared 库入口, 导出codecin_run_v2/codecin_free/codecin_crom_pack/codecin_crom_unpack/codecin_version, 由 Python ctypes 加载;cmd/cincc/main.go:cincc编译器命令, 只做 CIN → 机器码, 由 Python 的--native/mkn build --native调用。
tests/test_no_go_cli.py 与 CI 的 native 作业检查 package main 白名单, 并断言 main.go 仍包含 #include <stdlib.h>; cmd/cincc 不导出 C ABI, 也不是用户 CLI。
2. 常量单一真源: isa.py → Go
codecin/isa.py 是唯一权威: Opcode 编码、Syscall 功能号、KIND_* 操作数 类型码、Constants.ARG_COUNTS、__version__ (对 Go 版本常量而言)。 script/gen_native_isa.py 把它们生成到 Go 侧, 生成物禁止手工修改:
| 生成物 | 内容 | 头部标记 |
|---|---|---|
codecin/native/engine/isa_gen.go | op* 操作码、kind*、opcodeByName、argCounts、sys* | // Code generated by script/gen_native_isa.py ... DO NOT EDIT. |
codecin/native/compiler/syscalls.go | 编译器用的 SysXXX 常量 | 同上 |
codecin/native/engine/version_gen.go | engine.BuildVersion | // ... from codecin/__init__.py |
生成物必须是 gofmt 干净的 LF 文件: CI 的 native 作业跑 gofmt -l . 门禁, gen_native_isa.py --check 还会显式拒绝 CRLF (见 .gitattributes 的 *.go text eol=lf)。
3. 其他不可漂移的约定
| 约定 | 把关点 |
|---|---|
CIN 编译器双语对齐 (Python cin.py 与 Go compiler/) | tests/test_compiler_errors.py、tests/test_switch_semantics.py、tests/test_literals_and_bom.py |
版本号只是 codecin/__init__.py 一个数 | tests/test_version.py、Release 工作流的 version-check 作业 |
| PyPI 包不含预编译原生库 | tests/test_packaging.py、CI dist 作业 |
| 内置标准库必须随包分发 | pyproject.toml package-data + MANIFEST.in、CI dist 作业断言 codecin/lib/*/src/*.cin |
指令集文档与 isa.py 一致 | script/gen_isa_docs.py --check、script/gen_native_isa.py --check |
改一处要同步哪些文件
| 你改了什么 | 必须同步的地方 | 命令 |
|---|---|---|
| 新增/删除一条指令 | isa.py (Opcode/OPCODE_NAMES/ARG_COUNTS/BRANCH_OPS/FP_OPS) → engine/vm.go → assembler.py → native/mc (cincc 指令选择) | python script/gen_isa_docs.py、python script/gen_native_isa.py、重编原生库、pytest、go test ./mc |
| 新增一个 SYS 功能号 | isa.py: Syscall → engine/vm.go: doSyscall → cin.py: HOST_BUILTINS (若暴露给 CIN) + compiler/codegen.go: hostBuiltins → native/mc 运行时 | 同上 (编号三处必须一致) |
| 改了版本号 | codecin/__init__.py: __version__ (唯一真源) → 重新生成 version_gen.go; CHANGELOG.md 加 ## [x.y.z] 条目 | python script/bump_version.py x.y.z (先 --dry-run 预演)、pytest tests/test_version.py |
| 改了内置标准库 | codecin/lib/<name>/src/<name>.cin (package-data 自动覆盖) | pytest tests/test_libs.py tests/test_libs_ext.py |
| 改了打包配置 | pyproject.toml / MANIFEST.in / setup.py / build.sh / build.bat | pytest tests/test_packaging.py |
| 改了 CI 工作流 | .github/workflows/*.yml | pytest tests/test_workflows.py |
| 改了寄存器/内存语义 | registers.py / memory.py / cpu.py 以及 engine/vm.go (原生侧) | pytest tests/test_sparse_memory.py |
| 改了 CIN 语法 | cin.py 以及 compiler/*.go (双编译器必须同时对) | pytest tests/test_cin_syntax.py tests/test_switch_semantics.py tests/test_compiler_errors.py |
| 新增平台相关宿主 API | engine/audio_*.go 式的 //go:build 拆分 (否则其它平台编不过) | CI native 作业的交叉编译自检 |
| 新增文档站页面 | docs/<section>/<page>.md + docs/.vitepress/config.mts 的 sidebar | cd docs && npm run docs:build |
相关页面
- 编译 Go 原生库与 cincc — 三平台构建命令与产物
- 测试与 CI — 本地复现 CI 的完整命令
- 打包与发布 — 版本真源、构建钩子、Release 资产
- 扩展指令 / 系统调用 — 逐步改动清单
- 架构总览 — 分层与数据流