字节码序列化(.obc)¶
本页是 Oort 字节码文件格式的规范性文档,描述 oort_lang.bytecode.serialize
实际写出/读入的二进制布局。任何偏离都应被视为 bug。指令编码、操作码编号与常量池
描述符的语义见 spec 12;本页只新增文件层(头、
布局、tagged 编码),不重复指令语义。
类型擦除边界:本格式承载的是动态/类型擦除字节码(与 spec 12 一致),不携带
oort-core 静态类型,方言中立。
扩展名与种类¶
- 扩展名
.obc(Oort ByteCode)。它不是.ort,模块加载器只认.ort,故.obc文件不会被误当源码模块。 .obc是通用「Oort 编译字节码」扩展名:未来 typed/静态字节码共用.obc, 靠文件头的 kind 字段区分(见下)。kind 分「种类」、version 分「修订」,二者 分离,避免扩展名 proliferation。
编码原语¶
全部小端:
| 记法 | 含义 |
|---|---|
u8/u16/u32 |
无符号整数(1/2/4 字节) |
i32/i64 |
有符号整数(4/8 字节,补码) |
f64 |
IEEE-754 双精度(8 字节) |
bool |
u8,0/1 |
string |
u32 字节长度 + UTF-8 字节 |
opt<T> |
bool 存在标志 + 存在时的 T |
seq<T> |
u32 个数 + 逐个 T |
文件头¶
kind:字节码种类。0= 动态/类型擦除(当前);1= typed 标量子集 (研究性,见 spec 14);2+预留。读入方遇到不支持的 kind 必须显式拒绝。version:该 kind 的格式修订号,当前写出2(OP 0023:模式字面量值、 MatchArm guard 字段);读入兼容1与2。不支持的 version 显式拒绝。
模块布局¶
function_index(DEF_FUN/MAKE_CLOSURE 的 Bx、ClassSpec 各方法/槽初始化器、
MatchArmSpec、ExtensionSpec、ParamSpec.default_index)一律索引 functions 表,
不含 main。
Proto 布局¶
按序:
| 字段 | 编码 |
|---|---|
| name | string |
| params | seq<string> |
| register_count | u16 |
| local_count | u16 |
| scratch_base | u16 |
| flags | u8:bit0 has_this、bit1 uses_cells、bit2 defines_extensions |
| signature | 见下 |
| code | seq<u32>(32 位指令字,编码见 spec 12) |
| constants | seq<Constant>(tagged,见下) |
| positions | bool 存在标志 + 存在时:string filename + seq<Position> |
Position = u32 start_line + i32 start_column(-1 表示无列)。positions
可选——VM 有兜底位置;line_table 由 positions 的行号派生,不单独落盘。
SignatureSpec:bool has_this + seq<ParamSpec>。
ParamSpec:string name + u8 kind + u16 slot + bool has_default +
opt<u32> default_index。kind 编号:0 POS_ONLY、1 POS_OR_KW、2 VAR_POS、
3 KW_ONLY、4 VAR_KW、5 BLOCK。
常量池(tagged)¶
每项 = u8 tag + payload。保留类型标签(VM 按类型校验描述符)。
| tag | 类型 | payload |
|---|---|---|
| 0 | Null | 无 |
| 1 | Bool | bool |
| 2 | Int | i64 |
| 3 | Float | f64 |
| 4 | String | string |
| 5 | SlotsTuple | seq<u16>(FRESH 的寄存器槽号) |
| 10 | ClassSpec | 见下 |
| 11 | CallSpec | u16 positional_count + seq<string> keywords + bool has_block |
| 12 | EnumSpec | string name + seq<(string, u16)> constructors(名, 元数) |
| 13 | MatchSpec | seq<MatchArm> |
| 15 | ImportSpec | string module_path + opt<string> alias + seq<(string, opt<string>)> names + bool is_from |
| 16 | ExtensionSpec | string name + u32 function_index + opt<string> symbol + u16 operand_count + string receiver_name |
ClassSpec:string name + u16 base_count + seq<(string, u32)> methods +
seq<(string, bool, opt<u32>)> slots(名, mutable, 初始化器索引)+
seq<(string, u32)> class_methods + seq<(string, u16, u32)> operators
(symbol, operand_count, 索引)+ bool has_metaclass。
MatchArm = Pattern + u32 function_index + opt<u32> guard_index。
guard_index 自 version 2 起写出/读入;version 1 的 arm 没有该字段,读入时
视为 None。
Pattern(递归)= u8 kind + string name + seq<Pattern> args;kind 编号:
0 wildcard、1 name、2 constructor、3 literal_int、4 literal_float、
5 literal_string、6 literal_bool、7 tuple、8 or。version 2 中 literal 类 kind
在 args 之后追加一个 tagged Constant 作为模式字面量值(version 1 无此字段)。
描述符字段语义见 spec 12 与 bytecode/code.py。
限制与校验¶
- Int 范围:当前序列化器把整数常量限制在 i64;超范围在写出期拒绝
(
ObcError)。语言语义是任意精度,BigInt 支持留待后续(与 Rust spike 的 i64 值表示一致)。 - 加载期校验:magic/kind/version 匹配;函数索引 < len(functions); register_count ≤ 256;常量池 ≤ 65536 项。
- 常量池去重规则(区分 Bool/Int/Float)由编译期保证(spec 12),文件按编译产物 原样承载。
实现与往返¶
- 写出/读入:
oort_lang.bytecode.serialize.write_obc/read_obc。 - 发射:
scripts/compile_obc.py input.ort [-o output.obc]。 - 往返测试:
tests/unit/backend/test_serialize.py(结构相等 + 读回模块交 Python VM 执行输出一致)。