XU XUv0.13.1
EN

文档

原生模块与 .xulib 规范

在系统级软件工程中,与成熟的 C/C++ 原生代码库集成是极其关键的基础能力。Xu 语言提供了零抽象成本、强类型检查的原生互操作机制。很多开发者在初次接触时会产生疑问:“为什么 Xu 既支持标准通用 .a(静态归档库),又要引入便携式 .xulib?”

本文档深入解析 Xu 的原生互操作机制、通用静态库与 .xulib 的分工定位、支持的完整数据类型映射表以及端到端完整的 7 个开发动作。

1. 核心结论:通用 .a 与 .xulib 的关系

一步原生链接目前仅支持 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 语言类型对应典型用途与参数机制
intxu_int (int64_t)64 位标准有符号整数,常用于计数、长度、索引偏移
f6464 位浮点 (IEEE-754)双精度浮点数。标量位模式通过通用寄存器直传,C 侧借助内联转换函数实现无损映射
booluint8_t / bool布尔真假逻辑(1 为 true,0 为 false)
i32int32_t32 位有符号整数,用于系统 API 错误码、区间截断
u32uint32_t32 位无符号整数,用于位移操作、掩码、哈希与校验和
u8uint8_t8 位无符号单字节,用于协议解析、字符码、单通道像素数据
voidvoid无返回值过程,用于重置、初始化或内部有状态副作用操作

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)。容器采用紧凑的线性段式布局,由魔数签名、定长头部、契约清单、切片索引表与二进制切片负载五大部分组成:

.xulib 二进制容器物理内存与磁盘排布图 (Physical Binary Layout)
SPEC xulib-1
0x00..0x06 (7B)
Magic: "XULIB\x01\x00"
魔数标识与主版本校验
0x07..0x08 (2B)
Version = 1
u16 次版本号
0x09..0x0A (2B)
Flags = 0
u16 扩展位掩码
0x0B..0x0E (4B)
Manifest Len = N
u32 小端序清单长度
0x0F..0x0F+N (N Bytes UTF-8)
JSON Manifest (模块接口契约与签名清单)
包含 module 命名空间、abi: "xu-c-1"、format: "xulib-1"(导出签名位于切片 XUOBJ 元数据中)、slices 各架构 SHA-256 校验散列
0x0F+N 处 (4B)
Slice Count = M
u32 小端序切片总数
连续变长索引项
Slice Index Table (架构切片索引表数组)
每个切片顺序记录:target_name(目标三元组)、kind(archive/object)、file_offset 与 file_size、sha256 散列防篡改指纹
macOS Slice 偏移处
macOS 切片 (Mach-O)
标准 Unix .a(含 bridge.o + xu.o __DATA,__xumeta)
Linux Slice 偏移处
Linux 切片 (ELF)
标准 Unix .a(含原生 .o + xu.o .xumeta)
Windows Slice 偏移处
Windows 切片 (COFF)
标准 .a / .lib(含原生 .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 适配工作。

模块与依赖规范 · 官方扩展包 (Packages) · 命令行工具链参考