原生模块与 .xulib 规范
在系统级软件工程中,与成熟的 C/C++ 原生代码库集成是极其关键的基础能力。Xu 语言提供了零抽象成本、强类型检查的原生互操作机制。很多开发者在初次接触时会产生疑问:“为什么 Xu 既支持标准通用 .a(静态归档库),又要引入便携式 .xulib?”
本文档深入解析 Xu 的原生互操作机制、通用静态库与 .xulib 的分工定位、支持的完整数据类型映射表以及端到端完整的 7 个开发动作。
1. 核心结论:通用 .a 与 .xulib 的关系
- 标准通用
.a(Unix 静态归档库)原生支持且地位完全平等:使用xu native compile或xu native archive将 Xu 接口元数据与原生对象一起打包。在macos-arm64和macos-x64上,可在命令行xu build main.xu module.a或xu.xun的native:中直接声明引用,底层最终由操作系统原生链接器(ld/clang/lld)静态链接。 .xulib是面向跨平台生态分发的“多目标切片元数据包”:它并不是一种全新的专有机器码格式,其内部包裹的依然是各个目标平台标准的.a静态切片,额外附加了强类型签名契约(JSON Manifest)与 SHA-256 完整性哈希。
一步原生链接目前仅支持 macos-arm64 和 macos-x64,需要 macOS C 工具链。其他目标须使用 --emit-obj,将 XUOBJ 转为平台对象,再由外部系统链接器完成链接。容器支持多目标切片并不扩大一步链接的平台范围。下方七步示例使用 macOS 切片。
| 特性维度 | 通用 .a 静态库 | 便携式 .xulib 容器包 |
|---|---|---|
| 适用场景 | 单目标平台开发、本地临时调试、私有定制 C 链接 | 跨平台模块分发、开源生态扩展包(如 packages/sqlite) |
| 架构支持 | 单架构单目标(如仅 linux-x64 或仅 macos-arm64) | 多目标多架构统一打包(单个文件内嵌全平台切片) |
| 跨平台切换 | 需在配置文件或构建脚本中编写复杂的 OS/Arch 切换条件 | 构建器自动按当前 --target 提取匹配切片,零配置透明跨平台 |
| 类型安全 | xu native compile/archive 生成的归档包含 XUOBJ 导出签名 | 内置 JSON Manifest 与 XUOBJ 契约,编译期完成强类型检查 |
| 完整性校验 | 无内置防篡改机制 | 每个架构切片均记录 SHA-256 校验和,解包即校验 |
2. 跨语言支持的数据类型与 ABI 对照
在 abi: "xu-c-1" 协议下,Xu 统一使用机器通用标量寄存器完成高效传递,严格杜绝重型胶水代码:
| Xu 数据类型 | C 语言类型对应 | 典型用途与参数机制 |
|---|---|---|
int | xu_int (int64_t) | 64 位标准有符号整数,常用于计数、长度、索引偏移 |
f64 | 64 位浮点 (IEEE-754) | 双精度浮点数。标量位模式通过通用寄存器直传,C 侧借助内联转换函数实现无损映射 |
bool | uint8_t / bool | 布尔真假逻辑(1 为 true,0 为 false) |
i32 | int32_t | 32 位有符号整数,用于系统 API 错误码、区间截断 |
u32 | uint32_t | 32 位无符号整数,用于位移操作、掩码、哈希与校验和 |
u8 | uint8_t | 8 位无符号单字节,用于协议解析、字符码、单通道像素数据 |
void | void | 无返回值过程,用于重置、初始化或内部有状态副作用操作 |
2.1 同步借用 i64 批量数据:xu-c-2
Xu 0.11.3 新增显式的 abi: "xu-c-2" 契约。清单参数 i64_span 映射为 Xu &[]int 及指向 xu_i64_span 的 C 指针;i64_span_mut 映射为 $&[]int 及指向 xu_i64_span_mut 的指针。匹配 SDK 的 include/xu_native.h 定义布局:八字节元素数量,随后是数据指针。
每次同步调用提供独立的临时描述符。原生代码不得保留描述符或数据指针、修改描述符字段、调整数组大小或接管所有权;可写借用仅允许修改元素。空借用的数据指针可以为空。容量和 Xu 内部描述符不跨越此边界。
当前 C2 支持宿主 64 位目标、64 位 int 标量参数,以及 int/void 返回值,不定义浮点签名、通用回调或借用返回值。适配器处理平台参数寄存器、栈参数与 Win64 shadow space,但不扩展前述一步链接支持。需要传递原生函数值时,应通过 Xu 包装函数使用。
C2 使用 XUOBJ version 2 与 xulib-2,容器在偏移 7 处记录版本 2;旧产品明确拒绝此格式,C1 库继续兼容。下方布局图描述 C1 容器。容器选择与切片提取发生在构建期,C2 仍需在运行期准备调用临时描述符与参数。
3. .xulib 内部结构与二进制规范
.xulib 是自描述的多架构静态库容器(规范版本 xulib-1)。容器采用紧凑的线性段式布局,由魔数签名、定长头部、契约清单、切片索引表与二进制切片负载五大部分组成:
module 命名空间、abi: "xu-c-1"、format: "xulib-1"(导出签名位于切片 XUOBJ 元数据中)、slices 各架构 SHA-256 校验散列target_name(目标三元组)、kind(archive/object)、file_offset 与 file_size、sha256 散列防篡改指纹bridge.o + xu.o __DATA,__xumeta).o + xu.o .xumeta).obj + xu.o .xumeta)完整的 .xulib 二进制容器物理字段规范对照表:
| 偏移区间 (Offset) | 字段名称 (Field) | 类型与尺寸 | 规范定义与物理语义说明 |
|---|---|---|---|
| 物理段 1:固定容器文件头 (Fixed Container Header · 15 Bytes) | |||
0x00..0x06 (7 Bytes) |
魔数标识 (Magic) | char[7] |
固定为 "XULIB\x01\x00",用于快速识别合规的 .xulib 二进制容器并校验主版本。 |
0x07..0x08 (2 Bytes) |
次版本号 (Version) | u16 (小端序) |
容器格式次版本号,当前规范固定为 1。 |
0x09..0x0A (2 Bytes) |
标志位 (Flags) | u16 (位掩码) |
保留供未来容器扩展(如压缩、嵌入式签名),默认填 0。 |
0x0B..0x0E (4 Bytes) |
清单长度 (Manifest Len) | u32 (小端序) |
记录紧随其后的 JSON 契约文本总字节数 $N$。 |
| 物理段 2:契约元数据清单 (JSON Manifest · N Bytes) | |||
0x0F..0x0F+N ($N$ Bytes) |
契约清单 (Manifest) | UTF-8 紧凑文本 |
xu native pack 写出的容器顶层元数据:• module:全局唯一的模块命名空间标识(如 "native_add")• abi:原生接口协议规范版本(如 "xu-c-1")• format:容器格式标识("xulib-1")• slices:记录各目标平台的切片名及对应的 SHA-256 签名散列
|
| 物理段 3:切片索引表 (Slice Index Table) | |||
0x0F+N 处 (4 Bytes) |
切片总数 (Slice Count) | u32 (小端序) |
记录索引表中连续排列的多架构目标切片数量 $M$。 |
| 连续变长索引项 | 切片索引表条目 (Entries) | 变长连续结构体数组 |
每个切片条目顺序包含: • target_len (u16) + target_name(如 "macos-arm64"、"linux-x64")• kind_len (u8) + kind("archive" 静态库或 "object" 单对象)• file_offset (u64) + file_size (u64) 绝对文件偏移与切片尺寸• sha256 (32 Bytes) 二进制散列防篡改校验码
|
| 物理段 4:多架构二进制切片负载 (Multi-Arch Payload Slices) | |||
| 根据索引绝对偏移 | macOS 切片 (Mach-O) | 标准 Unix .a |
包含 Mach-O 机器码对象(如 bridge.o)+ xu.o(含 __DATA,__xumeta 符号段)。 |
| 根据索引绝对偏移 | Linux 切片 (ELF) | 标准 Unix .a |
包含 Linux ELF 机器码对象 + xu.o(含 .xumeta 符号段)。 |
| 根据索引绝对偏移 | Windows 切片 (COFF) | 标准 .a / .lib |
包含 Windows COFF 机器码对象 + xu.o(含 .xumeta 符号段)。 |
巧妙的双面兼容设计:每个平台的切片本质是一个标准的 .a 静态归档库。它将由外部原生工具链(如 C / C++ / Rust)编译出的原生业务对象(如 sqlite3.o、bridge.o),与一份格式合规并包含 Xu 导出类型签名的元数据对象(xu.o)统一打包在一起。操作系统的通用链接器直接链接这些原生的业务机器码,而 Xu 编译器则读取 xu.o 专用 .xumeta 段(Mach-O 下为 __DATA,__xumeta)中的类型契约完成编译期安全检查,两者互不干扰。
输入 native.json 声明 exports,各归档的 xu.o XUOBJ 元数据保存这些类型签名。产品工具 xu native pack 不把 exports 复制到顶层清单。源码树中的 Python 辅助工具 scripts/xunative.py 会复制输入清单,因此其输出保留 exports。读取方应从切片元数据获取接口,不能要求顶层必有导出表。
4. 完整的 7 个开发动作指南
动作一:编写 C 桥接源码 (bridge.c)
包含官方头文件 xu_native.h,使用 XU_NATIVE_SYMBOL(...) 宏导出函数,自动抹平 Apple Mach-O(下划线前缀)与 Linux ELF/Windows COFF 的符号命名差异:
#include "xu_native.h"
#include <stdint.h>
#include <stdbool.h>
#include <string.h>
// 1. int (64 位整数)
xu_int XU_NATIVE_SYMBOL(xu_native_add_add)(xu_int a, xu_int b) {
return a + b;
}
// 2. f64 (64 位双精度浮点无损互转)
static inline double xu_to_double(xu_int bits) {
double v; memcpy(&v;, &bits;, sizeof(double)); return v;
}
static inline xu_int double_to_xu(double v) {
xu_int b; memcpy(&b;, &v;, sizeof(xu_int)); return b;
}
xu_int XU_NATIVE_SYMBOL(xu_native_add_scale_f64)(xu_int val_bits, xu_int factor_bits) {
return double_to_xu(xu_to_double(val_bits) * xu_to_double(factor_bits));
}
// 3. bool (布尔判断)
uint8_t XU_NATIVE_SYMBOL(xu_native_add_is_even)(xu_int n) {
return (n % 2 == 0) ? 1 : 0;
}
// 4. i32 (32 位有符号整数范围截断)
int32_t XU_NATIVE_SYMBOL(xu_native_add_clamp_i32)(int32_t val, int32_t min_v, int32_t max_v) {
if (val < min_v) return min_v;
if (val > max_v) return max_v;
return val;
}
// 5. u32 (32 位无符号整数循环位移)
uint32_t XU_NATIVE_SYMBOL(xu_native_add_rotate_left_u32)(uint32_t val, uint32_t shift) {
shift &= 31;
if (shift == 0) return val;
return (val << shift) | (val >> (32 - shift));
}
// 6. u8 (8 位无符号单字节掩码)
uint8_t XU_NATIVE_SYMBOL(xu_native_add_mask_u8)(uint8_t b, uint8_t mask) {
return (uint8_t)(b & mask);
}
// 7. void (无返回值状态操作与副作用)
static xu_int g_counter = 0;
void XU_NATIVE_SYMBOL(xu_native_add_reset_counter)(void) { g_counter = 0; }
void XU_NATIVE_SYMBOL(xu_native_add_add_to_counter)(xu_int delta) { g_counter += delta; }
xu_int XU_NATIVE_SYMBOL(xu_native_add_get_counter)(void) { return g_counter; }
动作二:声明类型元数据契约清单 (native.json)
{
"module": "native_add",
"abi": "xu-c-1",
"exports": [
{"name": "add", "params": ["int", "int"], "ret": "int"},
{"name": "scale_f64", "params": ["f64", "f64"], "ret": "f64"},
{"name": "is_even", "params": ["int"], "ret": "bool"},
{"name": "clamp_i32", "params": ["i32", "i32", "i32"], "ret": "i32"},
{"name": "rotate_left_u32", "params": ["u32", "u32"], "ret": "u32"},
{"name": "mask_u8", "params": ["u8", "u8"], "ret": "u8"},
{"name": "reset_counter", "params": [], "ret": "void"},
{"name": "add_to_counter", "params": ["int"], "ret": "void"},
{"name": "get_counter", "params": [], "ret": "int"}
]
}
动作三:单目标切片静态编译 (xu native compile)
为各个受支持的目标平台分别生成带有元数据的 .a 切片:
mkdir -p native
# 针对 macOS Apple Silicon (ARM64)
xu native compile \
--manifest native.json --target macos-arm64 bridge.c \
-o native/native_add-arm64.a
# 针对 macOS Intel (x86_64)
xu native compile \
--manifest native.json --target macos-x64 bridge.c \
-o native/native_add-x64.a
动作四:全目标切片聚合打包 (xu native pack)
将单目标切片聚合装载为全平台自描述的便携式 .xulib 文件:
xu native pack \
--manifest native.json \
--slice macos-arm64=native/native_add-arm64.a \
--slice macos-x64=native/native_add-x64.a \
-o native/native_add.xulib
你还可以通过 xu native inspect native/native_add.xulib 检视容器切片列表与 SHA-256 摘要,或使用 xu native extract 单独提取切片。
动作五:在工程项目配置中声明原生模块 (xu.xun)
module: my_project
version: !ver 0.1.0
xu: !ver 0.13.1
native:
native_add: file:./native/native_add.xulib
动作六:在 Xu 源码中导入与调用 (main.xu)
@main
#native_add
fn main() int {
println("=== Xu <-> Native C Multi-Type Interop Demo ===")
// 1. int
sum := native_add.add(20, 22)
println("1. int add(20, 22) = " + str(sum))
// 2. f64
scaled := native_add.scale_f64(1.5, 3.0)
println("2. f64 scale_f64(1.5, 3.0) * 10 = " + str(int(scaled * 10.0)))
// 3. bool
println("3. bool is_even(42) = " + str(native_add.is_even(42)))
// 4. i32
clamped := native_add.clamp_i32(i32(150), i32(0), i32(100))
println("4. i32 clamp_i32(150, 0, 100) = " + str(int(clamped)))
// 5. u32
rotated := native_add.rotate_left_u32(u32(1), u32(4))
println("5. u32 rotate_left_u32(1, 4) = " + str(int(rotated)))
// 6. u8
masked := native_add.mask_u8(u8(255), u8(15))
println("6. u8 mask_u8(255, 15) = " + str(int(masked)))
// 7. void
native_add.reset_counter()
native_add.add_to_counter(100)
c := native_add.get_counter()
println("7. void state counter = " + str(c))
println("=== All Native Type Assertions Passed ===")
<< 0
}
动作七:macOS 静态构建与运行验证
# 编译为原生机器码可执行文件并运行
xu run .
终端即刻呈现经过静态编译期检查与硬件指令调用的原生结果:
=== Xu <-> Native C Multi-Type Interop Demo ===
1. int add(20, 22) = 42
2. f64 scale_f64(1.5, 3.0) * 10 = 45
3. bool is_even(42) = true
4. i32 clamp_i32(150, 0, 100) = 100
5. u32 rotate_left_u32(1, 4) = 16
6. u8 mask_u8(255, 15) = 15
7. void state counter = 100
=== All Native Type Assertions Passed ===
Linux x64 外部链接
安装 Clang 与归档工具后,使用 xu native compile --manifest native.json --target linux-x64 bridge.c -o native_add-linux.a 准备 linux-x64 归档。使用上面的 main.xu 和该归档,输出 XUOBJ,再用匹配 SDK 的内部辅助命令 _elf_o 转换并外部链接:
xu build main.xu native_add-linux.a --target linux-x64 --emit-obj -o main.xuobj
xu _elf_o main.xuobj main.o
cc -nostartfiles -no-pie main.o native_add-linux.a -o app
./app
Xu 提供自己的入口点,因此此 Linux 链接命令省略 C 启动文件。Windows 和其他目标须使用对应的对象转换工具、入口点及运行库链接选项;上述 Linux 命令仅适用于 Linux x64。
5. 常见问题解答 (FAQ)
Q:我只在本地开发单平台工具,不想打包 .xulib,可以直接用 .a 吗?
A:在上述 macOS 目标上可以。直接在 xu.xun 中写 native_add: file:./native/native_add-arm64.a 或在命令行执行 xu build main.xu ./native/native_add-arm64.a 即可。注意 .a 内需包含带有导出签名的 xu.o(可使用 xu native compile 或 xu native archive 生成)。
Q:.xulib 会影响运行期性能吗?
A:容器在构建期处理,不需要运行时解包器;选中的原生切片直接链接到应用。C2 调用仍须准备借用描述符与平台参数,容器提取不会消除这些 ABI 适配工作。