---

引言​

MoonBit 是一门现代化函数式编程语言，它有着严谨的类型系统，高可读性的语法，以及专为AI设计的工具链等。然而，重复造轮子并不可取。无数经过时间检验、性能卓越的库是用C语言（或兼容C ABI的语言，如C++、Rust）编写的。从底层硬件操作到复杂的科学计算，再到图形渲染，C的生态系统是一座蕴藏着无尽宝藏的富矿。

那么，我们能否让现代的MoonBit与这些经典的C库协同工作，让新世界的开拓者也能使用旧时代的强大工具呢？答案是肯定的。通过C语言外部函数接口（C Foreign Function Interface, C-FFI），MoonBit拥有调用C函数的能力，将新旧两个世界连接起来。

这篇文章将作为你的向导，带你一步步探索MoonBit C-FFI的奥秘。我们将通过一个具体的例子——为一个C语言编写的数学库 mymath​ 创建MoonBit绑定——来学习如何处理不同类型的数据、指针、结构体乃至函数指针。

预先准备​

要连接到任何一个C库，我们需要知道这个C库的头文件的函数，如何找到头文件，如何找到库文件。对于我们这篇文章的任务来说。C语言数学库的头文件就是 mymath.h​。它定义了我们希望在MoonBit中调用的各种函数和类型。我们这里假设我们的mymath​是安装到系统上的，编译时使用-I/usr/inluclude​来找到头文件，使用-L/usr/lib -lmymath​来链接库，下面是我们的mymath.h​的部分内容。

// mymath.h

// --- 基础函数 ---
void print_version();
int version_major();
int is_normal(double input);

// --- 浮点数计算 ---
float sinf(float input);
float cosf(float input);
float tanf(float input);
double sin(double input);
double cos(double input);
double tan(double input);

// --- 字符串与指针 ---
int parse_int(char* str);
char* version();
int tan_with_errcode(double input, double* output);

// --- 数组操作 ---
int sin_array(int input_len, double* inputs, double* outputs);
int cos_array(int input_len, double* inputs, double* outputs);
int tan_array(int input_len, double* inputs, double* outputs);

// --- 结构体与复杂类型 ---
typedef struct {
  double real;
  double img;
} Complex;

Complex* new_complex(double r, double i);
void multiply(Complex* a, Complex* b, Complex** result);
void init_n_complexes(int n, Complex** complex_array);

// --- 函数指针 ---
void for_each_complex(int n, Complex** arr, void (*call_back)(Complex*));

基础准备 (The Groundwork)​

在编写任何 FFI 代码之前，我们需要先搭建好 MoonBit 与 C 代码之间的桥梁。

编译到 Native​

首先，MoonBit 代码需要被编译成原生机器码。这可以通过以下命令完成：

moon build --target native

这个命令会将你的 MoonBit 项目编译成 C 代码，并使用系统上的 C 编译器（如 GCC 或 Clang）将其编译为最终的可执行文件。编译后的 C 文件位于 target/native/release/build/​ 目录下，按包名存放在相应的子目录中。例如，main/main.mbt​ 会被编译到 target/native/release/build/main/main.c​。

配置链接​

仅仅编译是不够的，我们还需要告诉 MoonBit 编译器如何找到并链接到我们的 mymath​ 库。这需要在项目的 moon.pkg.json​ 文件中进行配置。

{
  "supported-targets": ["native"],
  "link": {
    "native": {
      "cc": "clang",
      "cc-flags": "-I/usr/include",
      "cc-link-flags": "-L/usr/lib -lmymath"
    }
  }
}

• ​cc​: 指定用于编译C代码的编译器，例如 clang​ 或 gcc​。
• ​cc-flags​: 编译C文件时需要的标志，通常用来指定头文件搜索路径（-I​）。
• ​cc-link-flags​: 链接时需要的标志，通常用来指定库文件搜索路径（-L​）和具体要链接的库（-l​）。

同时，我们还需要一个 "胶水" C 文件，我们这里命名为 cwrap.c​，用来包含 C 库的头文件和 MoonBit 的运行时头文件。

// cwrap.c
#include <mymath.h>
#include <moonbit.h>

这个胶水文件也需要通过 moon.pkg.json​ 告知 MoonBit 编译器：

{
  // ... 其他配置
  "native-stub": ["cwrap.c"]
}

完成这些配置后，我们的项目就已经准备好与 mymath​ 库进行链接了。

第一次跨语言调用 (The First FFI Call)​

万事俱备，让我们来进行第一次真正的跨语言调用。在 MoonBit 中声明一个外部 C 函数，语法如下：

extern "C" fn moonbit_function_name(arg: Type) -> ReturnType = "c_function_name"

• ​extern "C"​：告诉 MoonBit 编译器，这是一个外部 C 函数。
• ​moonbit_function_name​：在 MoonBit 代码中使用的函数名。
• ​"c_function_name"​：实际链接到的 C 函数的名称。

让我们用 mymath.h​ 中最简单的 version_major​ 函数来小试牛刀：

extern "C" fn version_major() -> 
Int
Int = "version_major"

注意：MoonBit 拥有强大的死代码消除（DCE）能力。如果你只是声明了上面的 FFI 函数但从未在代码中（例如 main​ 函数）实际调用它，编译器会认为它是无用代码，并不会在最终生成的 C 代码中包含它的声明。所以，请确保你至少在一个地方调用了它！

跨越类型系统的鸿沟 (Navigating the Type System Chasm)​

真正的挑战在于处理两种语言之间的数据类型差异，对于一些复杂的类型情况，需要读者有一定的C语言知识。

3.1 基本类型：(Basic Types)​

对于基础的数值类型，MoonBit 和 C 之间有直接且清晰的对应关系。

MoonBit Type	C Type	Notes
​Int​	​int32_t​
​Int64​	​int64_t​
​UInt​	​uint32_t​
​UInt64​	​uint64_t​
​Float​	​float​
​Double​	​double​
​Bool​	​int32_t​	C语言标准没有原生 bool​，通常用 int32_t​ (0/1) 表示
​Unit​	​void​ (返回值)	用于表示 C 函数没有返回值的情况
​Byte​	​uint8_t​

根据这个表格，我们可以轻松地为 mymath.h​ 中的大部分简单函数编写 FFI 声明：

extern "C" fn print_version() -> 
Unit
Unit = "print_version"
extern "C" fn version_major() -> 
Int
Int = "version_major"

// 返回值语义上是布尔值，使用 MoonBit 的 Bool 类型更清晰
extern "C" fn is_normal(input: 
Double
Double) -> 
Bool
Bool = "is_normal"

extern "C" fn sinf(input: 
Float
Float) -> 
Float
Float = "sinf"
extern "C" fn cosf(input: 
Float
Float) -> 
Float
Float = "cosf"
extern "C" fn tanf(input: 
Float
Float) -> 
Float
Float = "tanf"

extern "C" fn sin(input: 
Double
Double) -> 
Double
Double = "sin"
extern "C" fn cos(input: 
Double
Double) -> 
Double
Double = "cos"
extern "C" fn tan(input: 
Double
Double) -> 
Double
Double = "tan"

3.2 字符串 (Strings)​

事情在遇到字符串时开始变得有趣。你可能会想当然地把 C 的 char*​ 映射到 MoonBit 的 String​，但这是一个常见的陷阱。

​MoonBit​ 的 String​ 和 C 的 char*​ 在内存布局上完全不同。char*​ 是一个指向以 \0​ 结尾的字节序列的指针，而 MoonBit​ 的 String​ 是一个由 GC 管理的、包含长度信息和 UTF-16 编码数据的复杂对象。

参数传递：从 MoonBit 到 C

当我们需要将一个 MoonBit 字符串传递给一个接受 char*​ 的 C 函数时（如 parse_int​），我们需要手动进行转换。一个推荐的做法是将其转换为 Bytes​ 类型。

// 一个辅助函数，将 MoonBit String 转换为 C 期望的 null-terminated byte array
fn 
fn string_to_c_bytes(s : String) -> Bytes
string_to_c_bytes(
String
s: 
String
String) -> 
Bytes
Bytes {
  let mut 
Array[Byte]
arr = 
String
s.
fn String::to_bytes(self : String) -> Bytes
String holds a sequence of UTF-16 code units encoded in little endian format
to_bytes().
fn Bytes::to_array(self : Bytes) -> Array[Byte]
Converts a bytes sequence into an array of bytes.
Parameters:

bytes : A sequence of bytes to be converted into an array.
Returns an array containing the same bytes as the input sequence.
Example:
let bytes = b"hello"
let arr = bytes.to_array()
inspect(arr, content="[b'\\x68', b'\\x65', b'\\x6C', b'\\x6C', b'\\x6F']")
to_array()
  // 确保以 \0 结尾
  if 
Array[Byte]
arr.
fn[A] Array::last(self : Array[A]) -> A?
Returns the last element of the array, or None if the array is empty.
Parameters:

array : The array to get the last element from.
Returns an optional value containing the last element of the array. The
result is None if the array is empty, or Some(x) where x is the last
element of the array.
Example:
let arr = [1, 2, 3]
inspect(arr.last(), content="Some(3)")
let empty : Array[Int] = []
inspect(empty.last(), content="None")
last() 
fn[T : Eq] @moonbitlang/core/builtin.op_notequal(x : T, y : T) -> Bool
!= 
(Byte) -> Byte?
Some(0) {
    
Array[Byte]
arr.
fn[T] Array::push(self : Array[T], value : T) -> Unit
Adds an element to the end of the array.
If the array is at capacity, it will be reallocated.
Example
  let v = []
  v.push(3)
push(0)
  }
  
(ArrayView[Byte]) -> Bytes
Bytes::
fn Bytes::from_array(arr : ArrayView[Byte]) -> Bytes
Creates a new bytes sequence from a byte array.
Parameters:

array : An array of bytes to be converted.
Returns a new bytes sequence containing the same bytes as the input array.
Example:
let arr = [b'h', b'i']
let bytes = Bytes::from_array(arr)
inspect(
  bytes,
  content=(
    #|b"hi"
  ),
)
from_array(
Array[Byte]
arr)
}

// FFI 声明，注意参数类型是 Bytes
#borrow(s) // 告诉编译器我们只是借用 s，不要增加其引用计数
extern "C" fn __parse_int(s: 
Bytes
Bytes) -> 
Int
Int = "parse_int"

// 封装成一个对用户友好的 MoonBit 函数
fn 
fn parse_int(str : String) -> Int
parse_int(
String
str: 
String
String) -> 
Int
Int {
  let 
Bytes
s = 
fn string_to_c_bytes(s : String) -> Bytes
string_to_c_bytes(
String
str)
  
fn __parse_int(s : Bytes) -> Int
__parse_int(
Bytes
s)
}

​ ​#borrow​​ 标记 ​borrow​ 标记是一个优化提示。它告诉编译器，C函数只是"借用"这个参数，不会持有它的所有权。这可以避免不必要的引用计数操作，防止潜在的内存泄漏。

返回值：从 C 到 MoonBit

反过来，当 C 函数返回一个 char*​ 时（如 version​），情况更加复杂。我们绝对不能直接将其声明为返回 Bytes​ 或 String​：

// 错误的做法！
extern "C" fn version() -> 
Bytes
Bytes = "version"

这是因为 C 函数返回的只是一个裸指针，它缺少 MoonBit GC 所需的头部信息。直接这样转换会导致运行时崩溃。

正确的做法是，将返回的 char*​ 视为一个不透明的句柄，然后在 C "胶水" 代码中编写一个转换函数，手动将其转换为一个合法的 MoonBit 字符串。

MoonBit 侧：

// 1. 声明一个外部类型来代表 C 字符串指针
#extern
type CStr

// 2. 声明一个 FFI 函数，它调用 C 包装器
extern "C" fn 
type CStr
CStr::to_string(self: 
type CStr
Self) -> 
String
String = "cstr_to_moonbit_str"

// 3. 声明原始的 C 函数，它返回我们的不透明类型
extern "C" fn __version() -> 
type CStr
CStr = "version"

// 4. 封装成一个安全的 MoonBit 函数
fn 
fn version() -> String
version() -> 
String
String {
  
fn __version() -> CStr
__version().
fn CStr::to_string(self : CStr) -> String
to_string()
}

C 侧 (在 ​cwrap.c​​ 中添加):

#include <string.h> // for strlen

// 这个函数负责将 char* 正确地转换为带 GC 头的 moonbit_string_t
moonbit_string_t cstr_to_moonbit_str(char *ptr) {
  if (ptr == NULL) {
    return moonbit_make_string(0, 0);
  }
  int32_t len = strlen(ptr);
  // moonbit_make_string 会分配一个带 GC 头的 MoonBit 字符串对象
  moonbit_string_t ms = moonbit_make_string(len, 0);
  for (int i = 0; i < len; i++) {
    ms[i] = (uint16_t)ptr[i]; // 假设是 ASCII 兼容的
  }
  // 注意：是否需要 free(ptr) 取决于 C 库的 API 约定。
  // 如果 version() 返回的内存需要调用者释放，这里就需要 free。
  return ms;
}

这个模式虽然初看有些繁琐，但它保证了内存安全，是处理 C 字符串返回值的标准做法。

3.3 指针的艺术：传递引用与数组 (The Art of Pointers: Passing by Reference and Arrays)​

C 语言大量使用指针来实现"输出参数"和传递数组。MoonBit 为此提供了专门的类型。

单个值的"输出"参数

当 C 函数使用指针来返回一个额外的值时，如 tan_with_errcode(double input, double* output)​，MoonBit 使用 Ref[T]​ 类型来对应。

extern "C" fn tan_with_errcode(input: 
Double
Double, output: 
struct Ref[A] {
  mut val: A
}
Ref[
Double
Double]) -> 
Int
Int = "tan_with_errcode"

​Ref[T]​ 在 MoonBit 中是一个包含单个 T​ 类型字段的结构体。当它传递给 C 时，MoonBit 会传递这个结构体的地址。从 C 的角度看，一个指向 struct { T val; }​ 的指针和一个指向 T​ 的指针在内存地址上是等价的，因此可以直接工作。

数组：传递数据集合

当 C 函数需要处理一个数组时（例如 double* inputs​），MoonBit 使用 FixedArray[T]​ 类型来映射。FixedArray[T]​ 在内存中就是一块连续的 T​ 类型元素，其指针可以直接传递给 C。

extern "C" fn sin_array(len: 
Int
Int, inputs: 
type FixedArray[A]
FixedArray[
Double
Double], outputs: 
type FixedArray[A]
FixedArray[
Double
Double]) -> 
Int
Int = "sin_array"
extern "C" fn cos_array(len: 
Int
Int, inputs: 
type FixedArray[A]
FixedArray[
Double
Double], outputs: 
type FixedArray[A]
FixedArray[
Double
Double]) -> 
Int
Int = "cos_array"
extern "C" fn tan_array(len: 
Int
Int, inputs: 
type FixedArray[A]
FixedArray[
Double
Double], outputs: 
type FixedArray[A]
FixedArray[
Double
Double]) -> 
Int
Int = "tan_array"

3.4 外部类型：拥抱不透明的 C 结构体 (External Types: Embracing Opaque C Structs)​

对于 C 中的 struct​，比如 Complex​，最佳实践通常是将其视为一个"不透明类型"（Opaque Type）。我们只在 MoonBit 中创建一个对它的引用（或句柄），而不关心其内部的具体字段。

这通过 #extern type​ 语法实现：

#extern
type Complex

这个声明告诉 MoonBit："存在一个名为 Complex​ 的外部类型。你不需要知道它的内部结构，只要把它当成一个指针大小的句柄来传递就行了。" 在生成的 C 代码中，Complex​ 类型会被处理成 void*​。这通常是安全的，因为所有对 Complex​ 的操作都是在 C 库内部完成的，MoonBit 侧只负责传递指针。

基于这个原则，我们可以为 mymath.h​ 中与 Complex​ 相关的函数编写 FFI：

// C: Complex* new_complex(double r, double i);
// 返回一个指向 Complex 的指针，在 MoonBit 中就是返回一个 Complex 句柄
extern "C" fn new_complex(r: 
Double
Double, i: 
Double
Double) -> 
type Complex
Complex = "new_complex"

// C: void multiply(Complex* a, Complex* b, Complex** result);
// Complex* 对应 Complex，而 Complex** 对应 Ref[Complex]
extern "C" fn multiply(a: 
type Complex
Complex, b: 
type Complex
Complex, res: 
struct Ref[A] {
  mut val: A
}
Ref[
type Complex
Complex]) -> 
Unit
Unit = "multiply"

// C: void init_n_complexes(int n, Complex** complex_array);
// Complex** 在这里作为数组使用，对应 FixedArray[Complex]
extern "C" fn init_n_complexes(n: 
Int
Int, complex_array: 
type FixedArray[A]
FixedArray[
type Complex
Complex]) -> 
Unit
Unit = "init_n_complexes"

最佳实践：封装原生 FFI 直接暴露 FFI 函数会让使用者感到困惑（比如 Ref​ 和 FixedArray​）。强烈建议在 FFI 声明之上再构建一层对 MoonBit 用户更友好的 API。

// 在 Complex 类型上定义方法，隐藏 FFI 细节
fn 
type Complex
Complex::
fn Complex::mul(self : Complex, other : Complex) -> Complex
mul(
Complex
self: 
type Complex
Complex, 
Complex
other: 
type Complex
Complex) -> 
type Complex
Complex {
  // 创建一个临时的 Ref 用于接收结果
  let 
Ref[Complex]
res: 
struct Ref[A] {
  mut val: A
}
Ref[
type Complex
Complex] = 
struct Ref[A] {
  mut val: A
}
Ref::{ 
Complex
val: 
fn new_complex(r : Double, i : Double) -> Complex
new_complex(0, 0) }
  
fn multiply(a : Complex, b : Complex, res : Ref[Complex]) -> Unit
multiply(
Complex
self, 
Complex
other, 
Ref[Complex]
res)
  
Ref[Complex]
res.
Complex
val // 返回结果
}

fn 
fn init_n(n : Int) -> Array[Complex]
init_n(
Int
n: 
Int
Int) -> 
type Array[T]
An Array is a collection of values that supports random access and can
grow in size.
Array[
type Complex
Complex] {
  // 使用 FixedArray::make 创建数组
  let 
FixedArray[Complex]
arr = 
type FixedArray[A]
FixedArray::
fn[T] FixedArray::make(len : Int, init : T) -> FixedArray[T]
Creates a new fixed-size array with the specified length, initializing all
elements with the given value.
Parameters:

length : The length of the array to create. Must be non-negative.
initial_value : The value used to initialize all elements in the array.
Returns a new fixed-size array of type FixedArray[T] with length
elements, where each element is initialized to initial_value.
Throws a panic if length is negative.
Example:
let arr = FixedArray::make(3, 42)
inspect(arr[0], content="42")
inspect(arr.length(), content="3")
WARNING: A common pitfall is creating with the same initial value, for example:
let two_dimension_array = FixedArray::make(10, FixedArray::make(10, 0))
two_dimension_array[0][5] = 10
assert_eq(two_dimension_array[5][5], 10)
This is because all the cells reference to the same object (the FixedArray[Int] in this case).
One should use makei() instead which creates an object for each index.
make(
Int
n, 
fn new_complex(r : Double, i : Double) -> Complex
new_complex(0, 0))
  
fn init_n_complexes(n : Int, complex_array : FixedArray[Complex]) -> Unit
init_n_complexes(
Int
n, 
FixedArray[Complex]
arr)
  // 将 FixedArray 转换为对用户更友好的 Array
  
type Array[T]
An Array is a collection of values that supports random access and can
grow in size.
Array::
fn[T] Array::from_fixed_array(arr : FixedArray[T]) -> Array[T]
Creates a new dynamic array from a fixed-size array.
Parameters:

arr : The fixed-size array to convert. The elements of this array will be
copied to the new array.
Returns a new dynamic array containing all elements from the input fixed-size
array.
Example:
let fixed = FixedArray::make(3, 42)
let dynamic = Array::from_fixed_array(fixed)
inspect(dynamic, content="[42, 42, 42]")
from_fixed_array(
FixedArray[Complex]
arr)
}

3.5 函数指针：当 C 需要回调 MoonBit (Function Pointers: When C Needs to Call Back)​

​mymath.h​ 中最复杂的函数是 for_each_complex​，它接受一个函数指针作为参数。

void for_each_complex(int n, Complex** arr, void (*call_back)(Complex*));

一个常见的误解是试图将 MoonBit 的闭包类型 (Complex) -> Unit​ 直接映射到 C 的函数指针。这是不行的，因为 MoonBit 的闭包在底层是一个包含两部分的结构体：一个指向实际函数代码的指针，以及一个指向其捕获的环境数据的指针。

为了传递一个纯粹的、无环境捕获的函数指针，MoonBit 提供了 FuncRef​ 类型：

extern "C" fn for_each_complex(
  n: 
Int
Int,
  arr: 
type FixedArray[A]
FixedArray[
type Complex
Complex],
  call_back: FuncRef[(
type Complex
Complex) -> 
Unit
Unit] // 使用 FuncRef 包装函数类型
) -> 
Unit
Unit = "for_each_complex"

任何被 FuncRef​ 包裹的函数类型，在传递给 C 时，都会被转换成一个标准的 C 函数指针。

如何声明一个FuncRef​？只要使用let​就可以了，只要函数没有捕获外部变量，就可以声明成功。

fn 
fn print_complex(c : Complex) -> Unit
print_complex(
Complex
c: 
type Complex
Complex) -> 
Unit
Unit { ... }

fn main {
  let 
FuncRef[(Complex) -> Unit]
print_complex
FuncRef[(Complex) -> Unit]
 : FuncRef[(
type Complex
Complex
FuncRef[(Complex) -> Unit]
) -> 
Unit
Unit
FuncRef[(Complex) -> Unit]
] = (
Complex
c) => 
fn print_complex(c : Complex) -> Unit
print_complex(
Complex
c)
  // ...
}

第四站：高级课题——GC管理(Advanced Topic: GC Management)​

我们已经了解了大部分类型的转换问题，但还有一个非常重大的问题：内存管理。C 依赖手动的 malloc​/free​，而 MoonBit 拥有自动的垃圾回收（GC）。当 C 库创建了一个对象（如 new_complex​），谁来负责释放它？

可以不要GC吗？ ​

一些库作者可能会选择不做GC，而是把所有的析构操作都留给用户。这种做法在一些库上有其合理性，因为有些库，例如一些高性能计算库，图形库等，为了提高性能或者稳定性，本身就会放弃掉一些GC特性，但带来的问题就是对程序员的水平要求较高。大多数库还是需要提供GC来增强用户体验的。

理想情况下，我们希望 MoonBit 的 GC 能够自动管理这些 C 对象的生命周期。MoonBit 提供了两种机制来实现这一点。

4.1 简单情况​

如果 C 结构体非常简单，并且你确信它的内存布局在所有平台上都是稳定不变的，你可以直接在 MoonBit 中重新定义它。

// mymath.h: typedef struct { double real; double img; } Complex;
// MoonBit:
struct Complex {
  r: Double,
  i: Double
}

这样做，Complex​ 就成了一个真正的 MoonBit 对象。MoonBit 编译器会自动为它管理内存，添加 GC 头。当你把它传递给 C 函数时，MoonBit 会传递一个指向其数据部分的指针，这通常是可行的。

但这种方法有很大的局限性：

• 它要求你精确知道 C 结构体的内存布局、对齐方式等，这可能很脆弱。
• 如果 C 函数返回一个 Complex*​，你不能直接使用它。你必须像处理字符串返回值一样，编写一个 C 包装函数，将 C 结构体的数据复制到一个新创建的、带 GC 头的 MoonBit Complex​ 对象中。

因此，这种方法只适用于最简单的情况。对于大多数场景，我们推荐更健壮的析构方案。

4.2 复杂情况，使用析构函数（Finalizer） (The Complex Situation: Using Finalizers)​

这是一种更通用和安全的方法。核心思想是：创建一个 MoonBit 对象来"包装"C 指针，并告诉 MoonBit 的 GC，当这个包装对象被回收时，应该调用一个特定的 C 函数（析构函数）来释放底层的 C 指针。

这个过程分为几步：

1. 在 MoonBit 中声明两种类型

#extern
type C_Complex // 代表原始的、不透明的 C 指针

type Complex C_Complex // 一个 MoonBit 类型，它内部包装了一个 C_Complex

​type Complex C_Complex​ 是一个特殊的声明，它创建了一个名为 Complex​ 的 MoonBit 对象类型，其内部有一个字段，类型为 C_Complex​。我们可以通过 .inner()​ 方法访问到这个内部字段。

2. 在 C 中提供析构函数和包装函数

我们需要一个 C 函数来释放 Complex​ 对象，以及一个函数来创建我们带 GC 功能的 MoonBit 包装对象。

C 侧 (在 ​cwrap.c​​ 中添加):

// mymath 库应该提供一个释放 Complex 的函数，假设是 free_complex
// void free_complex(Complex* c);

// 我们需要一个 void* 版本的析构函数给 MoonBit GC 使用
void free_complex_finalizer(void* obj) {
    // MoonBit 外部对象的布局是 { void (*finalizer)(void*); T data; }
    // 我们需要从 obj 中提取出真正的 Complex 指针
    // 假设 MoonBit 的 Complex 包装器只有一个字段
    Complex* c_obj = *((Complex**)obj);
    free_complex(c_obj); // 调用真正的析构函数, 如果mymath库提供的话
    // free(c_obj); // 如果是标准的 malloc 分配的
}

// 定义 MoonBit 的 Complex 包装器在 C 中的样子
typedef struct {
  Complex* val;
} MoonBit_Complex;

// 创建 MoonBit 包装对象的函数
MoonBit_Complex* new_mbt_complex(Complex* c_complex) {
  // `moonbit_make_external_obj` 是关键
  // 它创建一个由 GC 管理的外部对象，并注册其析构函数。
  MoonBit_Complex* mbt_complex = moonbit_make_external_obj(
      &free_complex_finalizer,
      sizeof(MoonBit_Complex)
  );
  mbt_complex->val = c_complex;
  return mbt_complex;
}

3. 在 MoonBit 中使用包装函数

现在，我们不直接调用 new_complex，而是调用我们的包装函数 new_mbt_complex。

// FFI 声明指向我们的 C 包装函数
extern "C" fn __new_managed_complex(c_complex: 
type C_Complex
C_Complex) -> 
type Complex
Complex = "new_mbt_complex"

// 原始的 C new_complex 函数返回一个裸指针
extern "C" fn __new_unmanaged_complex(r: 
Double
Double, i: 
Double
Double) -> 
type C_Complex
C_Complex = "new_complex"

// 最终提供给用户的、安全的、GC 友好的 new 函数
fn 
type Complex
Complex::
fn Complex::new(r : Double, i : Double) -> Complex
new(
Double
r: 
Double
Double, 
Double
i: 
Double
Double) -> 
type Complex
Complex {
  let 
C_Complex
c_ptr = 
fn __new_unmanaged_complex(r : Double, i : Double) -> C_Complex
__new_unmanaged_complex(
Double
r, 
Double
i)
  
fn __new_managed_complex(c_complex : C_Complex) -> Complex
__new_managed_complex(
C_Complex
c_ptr)
}

现在，当 Complex::new 创建的对象在 MoonBit 中不再被使用时，GC 会自动调用 free_complex_finalizer，从而安全地释放了 C 库分配的内存。

当需要将我们管理的 Complex 对象传递给其他 C 函数时，只需使用 .inner() 方法：

// 假设有一个C函数 `double length(Complex*);`
extern "C" fn length(c_complex: 
type C_Complex
C_Complex) -> 
Double
Double = "length"

fn 
type Complex
Complex::
fn Complex::length(self : Complex) -> Double
length(
Complex
self: 
type Complex
Self) -> 
Double
Double {
  // self.inner() 返回内部的 C_Complex (即 C 指针)
  
fn length(c_complex : C_Complex) -> Double
length(
Complex
self.
() -> C_Complex
inner())
}

结语 (Conclusion)​

这篇文章带你从基本类型，到复杂的结构体类型，再到函数指针类型，梳理了在MoonBit中做C-FFI的流程。末尾讨论了MoonBit管理c对象的GC问题。希望对广大读者的库开发有帮助。

---

引言​

在编程语言设计的过程中，语法前端负责理解和验证程序的结构与语义，而编译器后端则承担着将这些抽象概念转化为可执行机器代码的重任。后端的实现不仅需要对目标体系结构有深入的理解，更要掌握复杂的优化技术来生成高效的代码。

LLVM（Low Level Virtual Machine）作为现代编译器基础设施的集大成者，为我们提供了一个强大而灵活的解决方案。通过将程序转换为LLVM中间表示（Intermediate Representation, IR），我们可以利用LLVM成熟的工具链将代码编译到多种目标架构，包括RISC-V、ARM和x86等。

Moonbit的LLVM生态

Moonbit官方提供了两个重要的LLVM相关项目：

• ​**llvm.mbt**​：原版LLVM的Moonbit语言绑定，提供对llvm-c接口的直接访问。需要安装完整的LLVM工具链，只能生成native后端，需要自行解决编译和链接的问题，但能够生成与原版LLVM完全兼容的IR。
• ​**MoonLLVM**​：纯Moonbit实现的LLVM仿制版，无需外部依赖即可生成LLVM IR，支持JavaScript和WebAssembly后端

本文选择llvm.mbt​作为我们的工具，其API设计参考了Rust生态中广受好评的inkwell库。

在上篇《Moonbit 与 LLVM 共舞：实现现代编译器（上篇）》中，我们已经完成了从源代码到类型化抽象语法树的转换。本篇将承接这一成果，重点阐述代码生成的核心技术和实现细节。

---

第一章：LLVM类型系统的Moonbit表示​

在深入代码生成之前，我们需要首先理解llvm.mbt​如何在Moonbit的类型系统中表示LLVM的各种概念。LLVM的类型系统相当复杂，包含基本类型、复合类型和函数类型等多个层次。

Trait Object：类型的抽象表示​

在llvm.mbt​的API设计中，你会频繁遇到&Type​这一核心概念。这并非一个具体的struct或enum，而是一个Trait Object——可以将其理解为面向对象编程中抽象基类的函数式对等物。

// &Type是一个trait object，代表任意LLVM类型
let 
Unit
some_type: &Type = 
Unit
context.
() -> Unit
i32_type()

类型识别与转换​

要确定一个&Type​的具体类型，我们需要通过as_type_enum​接口进行运行时类型检查：

pub fn 
fn identify_type(ty : Unit) -> String
identify_type(
Unit
ty: &Type) -> 
String
String {
  match 
Unit
ty.
() -> Unit
as_type_enum() {
    
(Unit) -> Unit
IntType(
Unit
int_ty) => "Integer type with \{
Unit
int_ty.
() -> Unit
get_bit_width()} bits"
    
(_/0) -> Unit
FloatType(
_/0
float_ty) => "Floating point type"
    
(_/0) -> Unit
PointerType(
_/0
ptr_ty) => "Pointer type"
    
(_/0) -> Unit
FunctionType(
_/0
func_ty) => "Function type"
    
(_/0) -> Unit
ArrayType(
_/0
array_ty) => "Array type"
    
(_/0) -> Unit
StructType(
_/0
struct_ty) => "Structure type"
    
(_/0) -> Unit
VectorType(
_/0
vec_ty) => "Vector type"
    
(_/0) -> Unit
ScalableVectorType(
_/0
svec_ty) => "Scalable vector type"
    
(_/0) -> Unit
MetadataType(
_/0
meta_ty) => "Metadata type"
  }
}

安全的类型转换策略​

当我们确信某个&Type​具有特定的类型时，有多种转换方式可供选择：

1. 直接转换（适用于确定性场景）

let 
Unit
ty: &Type = 
Unit
context.
() -> Unit
i32_type()
let 
?
i32_ty = 
let ty : Unit
ty.
() -> ?
into_int_type()  // 直接转换，错误由llvm.mbt处理
let 
?
bit_width = 
let i32_ty : ?
i32_ty.
() -> ?
get_bit_width()  // 调用IntType特有的方法

2. 防御性转换（推荐的生产环境做法）

let 
Unit
ty: &Type = 
() -> Unit
get_some_type()  // 从某处获得的未知类型

guard ty.as_type_enum() is IntType(i32_ty) else {
  raise CodeGenError("Expected integer type, got \{ty}")
}

// 现在可以安全地使用i32_ty
let 
?
bit_width = 
let i32_ty : ?
i32_ty.
() -> ?
get_bit_width()

复合类型的构造​

LLVM支持多种复合类型，这些类型通常通过基本类型的方法来构造：

pub fn 
fn create_composite_types(context : ?) -> Unit
create_composite_types(
?
context: @llvm.Context) -> 
Unit
Unit {
  let 
Unit
i32_ty = 
?
context.
() -> Unit
i32_type()
  let 
Unit
f64_ty = 
?
context.
() -> Unit
f64_type()

  // 数组类型：[16 x i32]
  let 
Unit
i32_array_ty = 
Unit
i32_ty.
(Int) -> Unit
array_type(16)

  // 函数类型：i32 (i32, i32)
  let 
Unit
add_func_ty = 
Unit
i32_ty.
(Array[Unit]) -> Unit
fn_type([
Unit
i32_ty, 
Unit
i32_ty])

  // 结构体类型：{i32, f64}
  let 
Unit
struct_ty = 
?
context.
(Array[Unit]) -> Unit
struct_type([
Unit
i32_ty, 
Unit
f64_ty])

  // 指针类型（LLVM 18+中所有指针都是opaque）
  let 
Unit
ptr_ty = 
Unit
i32_ty.
() -> Unit
ptr_type()

  // 输出类型信息用于验证
  
fn[T : Show] println(input : T) -> Unit
Prints any value that implements the Show trait to the standard output,
followed by a newline.
Parameters:

value : The value to be printed. Must implement the Show trait.
Example:
  println(42)
  println("Hello, World!")
  println([1, 2, 3])
println("Array type: \{
Unit
i32_array_ty}")      // [16 x i32]
  
fn[T : Show] println(input : T) -> Unit
Prints any value that implements the Show trait to the standard output,
followed by a newline.
Parameters:

value : The value to be printed. Must implement the Show trait.
Example:
  println(42)
  println("Hello, World!")
  println([1, 2, 3])
println("Function type: \{
Unit
add_func_ty}")    // i32 (i32, i32)
  
fn[T : Show] println(input : T) -> Unit
Prints any value that implements the Show trait to the standard output,
followed by a newline.
Parameters:

value : The value to be printed. Must implement the Show trait.
Example:
  println(42)
  println("Hello, World!")
  println([1, 2, 3])
println("Struct type: \{
Unit
struct_ty}")        // {i32, f64}
  
fn[T : Show] println(input : T) -> Unit
Prints any value that implements the Show trait to the standard output,
followed by a newline.
Parameters:

value : The value to be printed. Must implement the Show trait.
Example:
  println(42)
  println("Hello, World!")
  println([1, 2, 3])
println("Pointer type: \{
Unit
ptr_ty}")          // ptr
}

重要提醒：Opaque指针

自LLVM 18版本开始，所有指针类型都采用了opaque指针设计。这意味着无论指向什么类型，所有指针在IR中都表示为ptr​，指向的具体类型信息在类型系统中不再可见。

---

第二章：LLVM值系统与BasicValue概念​

相比类型系统，LLVM的值系统会复杂一些。llvm.mbt​与inkwell一致，将值分为两个重要的抽象层次。Value​ 和 BasicValue​。不同点在于在于区分值的创建来源和值的使用方式：

• Value：关注值是如何产生的（常量、指令结果等）
• BasicValue：关注值具有什么样的基本类型（整数、浮点数、指针等）

实际应用示例​

pub fn 
fn demonstrate_value_system(context : ?, builder : ?) -> Unit
demonstrate_value_system(
?
context: Context, 
?
builder: Builder) -> 
Unit
Unit {
  let 
Unit
i32_ty = 
?
context.
() -> Unit
i32_type()

  // 创建两个整数常量 - 这些直接就是IntValue
  let 
Unit
const1 = 
Unit
i32_ty.
(Int) -> Unit
const_int(10)  // Value: IntValue, BasicValue: IntValue
  let 
Unit
const2 = 
Unit
i32_ty.
(Int) -> Unit
const_int(20)  // Value: IntValue, BasicValue: IntValue

  // 执行加法运算 - 结果是一个指令InstructionValue
  let 
Unit
add_result = 
?
builder.
(Unit, Unit) -> Unit
build_int_add(
Unit
const1, 
Unit
const2)

  // 在不同的上下文中，我们需要不同的视角：

  // 作为指令来检查其属性
  let 
Unit
instruction = 
Unit
add_result.
() -> Unit
as_instruction()
  
fn[T : Show] println(input : T) -> Unit
Prints any value that implements the Show trait to the standard output,
followed by a newline.
Parameters:

value : The value to be printed. Must implement the Show trait.
Example:
  println(42)
  println("Hello, World!")
  println([1, 2, 3])
println("Instruction opcode: \{
Unit
instruction.
() -> Unit
get_opcode()}")

  // 作为基本值来获取其类型
  let 
Unit
basic_value = 
Unit
add_result.
() -> Unit
into_basic_value()
  
fn[T : Show] println(input : T) -> Unit
Prints any value that implements the Show trait to the standard output,
followed by a newline.
Parameters:

value : The value to be printed. Must implement the Show trait.
Example:
  println(42)
  println("Hello, World!")
  println([1, 2, 3])
println("Result type: \{
Unit
basic_value.
() -> Unit
get_type()}")

  // 作为整数值来进行后续计算
  let 
Unit
int_value = 
Unit
add_result.
() -> Unit
into_int_value()
  let 
Unit
final_result = 
?
builder.
(Unit, Unit) -> Unit
build_int_mul(
Unit
int_value, 
Unit
const1)
}

值类型的完整分类​

1. ValueEnum：所有可能的值类型

pub enum ValueEnum {
  
(?) -> ValueEnum
IntValue(IntValue)              // 整数值
  
(?) -> ValueEnum
FloatValue(FloatValue)          // 浮点数值
  
(?) -> ValueEnum
PointerValue(PointerValue)      // 指针值
  
(?) -> ValueEnum
StructValue(StructValue)        // 结构体值
  
(?) -> ValueEnum
FunctionValue(FunctionValue)    // 函数值
  
(?) -> ValueEnum
ArrayValue(ArrayValue)          // 数组值
  
(?) -> ValueEnum
VectorValue(VectorValue)        // 向量值
  
(?) -> ValueEnum
PhiValue(PhiValue)             // Phi节点值
  
(?) -> ValueEnum
ScalableVectorValue(ScalableVectorValue)  // 可伸缩向量值
  
(?) -> ValueEnum
MetadataValue(MetadataValue)    // 元数据值
  
(?) -> ValueEnum
CallSiteValue(CallSiteValue)    // 调用点值
  
(?) -> ValueEnum
GlobalValue(GlobalValue)        // 全局值
  
(?) -> ValueEnum
InstructionValue(InstructionValue)  // 指令值
} derive(
trait Show {
  output(Self, &Logger) -> Unit
  to_string(Self) -> String
}
Trait for types that can be converted to String
Show)

2. BasicValueEnum：具有基本类型的值

pub enum BasicValueEnum {
  
(?) -> BasicValueEnum
ArrayValue(ArrayValue)              // 数组值
  
(?) -> BasicValueEnum
IntValue(IntValue)                  // 整数值
  
(?) -> BasicValueEnum
FloatValue(FloatValue)              // 浮点数值
  
(?) -> BasicValueEnum
PointerValue(PointerValue)          // 指针值
  
(?) -> BasicValueEnum
StructValue(StructValue)            // 结构体值
  
(?) -> BasicValueEnum
VectorValue(VectorValue)            // 向量值
  
(?) -> BasicValueEnum
ScalableVectorValue(ScalableVectorValue)  // 可伸缩向量值
} derive(
trait Show {
  output(Self, &Logger) -> Unit
  to_string(Self) -> String
}
Trait for types that can be converted to String
Show)

💡 值转换的最佳实践​

在实际的代码生成过程中，我们经常需要在不同的值视角之间进行转换：

pub fn 
fn value_conversion_patterns(instruction_result : Unit) -> Unit
value_conversion_patterns(
Unit
instruction_result: &Value) -> 
Unit
Unit {
  // 模式1：我知道这是什么类型，直接转换
  let 
Unit
int_val = 
Unit
instruction_result.
() -> Unit
into_int_value()

  // 模式2：我只需要一个基本值，不关心具体类型
  let 
Unit
basic_val = 
Unit
instruction_result.
() -> Unit
into_basic_value()

  // 模式3：防御性编程，检查后转换
  match 
Unit
instruction_result.
() -> Unit
as_value_enum() {
    // 处理整数值
    
(Unit) -> Unit
IntValue(
Unit
int_val) => 
(Unit) -> Unit
handle_integer(
Unit
int_val)
    // 处理浮点值
    
(Unit) -> Unit
FloatValue(
Unit
float_val) => 
(Unit) -> Unit
handle_float(
Unit
float_val)
    _ => raise 
Error
CodeGenError("Unexpected value type")
  }
}

通过这种双层抽象，llvm.mbt​既保持了LLVM值系统的完整性，又为Moonbit开发者提供了直观易用的接口。

---

第三章：LLVM IR生成实战​

在理解了类型和值系统的基础上，让我们通过一个完整的示例来演示如何使用llvm.mbt​生成LLVM IR。这个示例将实现一个简单的 muladd​ 函数，展示从初始化到指令生成的完整流程。

基础设施初始化​

任何LLVM程序的开始都需要建立三个核心组件：

pub fn 
fn initialize_llvm() -> (?, ?, ?)
initialize_llvm() -> (Context, Module, Builder) {
  // 1. 创建LLVM上下文 - 所有LLVM对象的容器
  let 
?
context = 
() -> ?
@llvm.Context::
() -> ?
create()

  // 2. 创建模块 - 函数和全局变量的容器
  let 
?
module = 
?
context.
(String) -> ?
create_module("demo_module")

  // 3. 创建IR构建器 - 用于生成指令
  let 
?
builder = 
?
context.
() -> ?
create_builder()

  (
?
context, 
?
module, 
?
builder)
}

一个简单的函数生成示例​

让我们实现一个计算 (a * b) + c​ 的函数：

pub fn 
fn generate_muladd_function() -> String
generate_muladd_function() -> 
String
String {
  // 初始化LLVM基础设施
  let (
?
context, 
?
module, 
?
builder) = 
fn initialize_llvm() -> (?, ?, ?)
initialize_llvm()

  // 定义函数签名
  let 
Unit
i32_ty = 
?
context.
() -> Unit
i32_type()
  let 
Unit
func_type = 
Unit
i32_ty.
(Array[Unit]) -> Unit
fn_type([
Unit
i32_ty, 
Unit
i32_ty, 
Unit
i32_ty])
  let 
Unit
func_value = 
?
module.
(String, Unit) -> Unit
add_function("muladd", 
Unit
func_type)

  // 创建函数入口基本块
  let 
Unit
entry_block = 
?
context.
(Unit, String) -> Unit
append_basic_block(
Unit
func_value, "entry")
  
?
builder.
(Unit) -> Unit
position_at_end(
Unit
entry_block)

  // 获取函数参数
  let 
Unit
arg_a = 
Unit
func_value.
(Int) -> Unit
get_nth_param(0).
() -> Unit
unwrap().
() -> Unit
into_int_value()
  let 
Unit
arg_b = 
Unit
func_value.
(Int) -> Unit
get_nth_param(1).
() -> Unit
unwrap().
() -> Unit
into_int_value()
  let 
Unit
arg_c = 
Unit
func_value.
(Int) -> Unit
get_nth_param(2).
() -> Unit
unwrap().
() -> Unit
into_int_value()

  // 生成计算指令
  let 
Unit
mul_result = 
?
builder.
(Unit, Unit) -> Unit
build_int_mul(
Unit
arg_a, 
Unit
arg_b).
() -> Unit
into_int_value()
  let 
Unit
add_result = 
?
builder.
(Unit, Unit) -> Unit
build_int_add(
Unit
mul_result, 
Unit
arg_c)

  // 生成返回指令
  let _ = 
?
builder.
(Unit) -> Unit
build_return(
Unit
add_result)

  // 输出生成的IR
  
?
module.
() -> String
dump()
}

生成的LLVM IR​

运行上述代码将产生以下LLVM中间表示：

; ModuleID = 'demo_module'
source_filename = "demo_module"

define i32 @muladd(i32 %0, i32 %1, i32 %2) {
entry:
  %3 = mul i32 %0, %1
  %4 = add i32 %3, %2
  ret i32 %4
}

💡 代码生成最佳实践​

1. 命名约定

有返回值的指令，构建接口有一个name​的label argument，可以给指令的结果添加名称。

let 
?
mul_result = 
Unit
builder.
(Unit, Unit, String) -> ?
build_int_mul(
Unit
lhs, 
Unit
rhs, 
String
name="temp_product")
let 
?
final_result = 
Unit
builder.
(?, Unit, String) -> ?
build_int_add(
let mul_result : ?
mul_result, 
Unit
offset, 
String
name="final_sum")

2. 错误处理

使用raise而并非panic来进行错误处理，对不好直接确定的情况进行异常管理。

// 对可能失败的操作进行检查
match func_value.get_nth_param(index) {
  Some(param) => param.into_int_value()
  None => raise CodeGenError("Function parameter \{index} not found")
}

---

第四章：TinyMoonbit编译器实现​

现在让我们将注意力转向真正的编译器实现，将上篇文章中构建的抽象语法树转换为LLVM IR。

类型映射：从Parser到LLVM​

首先需要建立TinyMoonbit类型系统与LLVM类型系统之间的映射关系：

pub struct CodeGen {
  
?
parser_program : Program                    // 源程序的AST表示
  
?
llvm_context : @llvm.Context               // LLVM上下文
  
?
llvm_module : @llvm.Module                 // LLVM模块
  
?
builder : @llvm.Builder                    // IR构建器
  
Map[String, ?]
llvm_functions : 
type Map[K, V]
Mutable linked hash map that maintains the order of insertion, not thread safe.
Example
  let map = { 3: "three", 8 :  "eight", 1 :  "one"}
  assert_eq(map.get(2), None)
  assert_eq(map.get(3), Some("three"))
  map.set(3, "updated")
  assert_eq(map.get(3), Some("updated"))
Map[
String
String, @llvm.FunctionValue]  // 函数映射表
}

pub fn 
(?, ?) -> Unit raise
convert_type(
?
self : Self, 
?
parser_type : Type) -> &@llvm.Type raise {
  match 
?
parser_type {
    Type::
?
Unit => 
?
self
Unit
.
?
llvm_context
Unit
.
() -> Unit
void_type
Unit
() as &@llvm.Type
    Type::
?
Bool => 
?
self.
?
llvm_context.
() -> Unit
bool_type()
    Type::
?
Int => 
?
self.
?
llvm_context.
() -> Unit
i32_type()
    Type::
?
Double => 
?
self.
?
llvm_context.
() -> Unit
f64_type()
    // 可以根据需要扩展更多类型
  }
}

环境管理：变量到值的映射​

在代码生成阶段，我们需要维护一个从变量名到LLVM值的映射关系：

pub struct Env {
  
Env?
parent : 
struct Env {
  parent: Env?
  symbols: Map[String, Unit]
  codegen: CodeGen
  parser_function: ?
  llvm_function: ?
}
Env?                        // 父环境引用
  
Map[String, Unit]
symbols : 
type Map[K, V]
Mutable linked hash map that maintains the order of insertion, not thread safe.
Example
  let map = { 3: "three", 8 :  "eight", 1 :  "one"}
  assert_eq(map.get(2), None)
  assert_eq(map.get(3), Some("three"))
  map.set(3, "updated")
  assert_eq(map.get(3), Some("updated"))
Map[
String
String, &@llvm.Value]        // 局部变量映射

  // 全局信息
  
CodeGen
codegen : 
struct CodeGen {
  parser_program: ?
  llvm_context: ?
  llvm_module: ?
  builder: ?
  llvm_functions: Map[String, ?]
}
CodeGen                           // 代码生成器引用
  
?
parser_function : Function                  // 当前函数的AST
  
?
llvm_function : @llvm.FunctionValue         // 当前函数的LLVM表示
}

pub fn 
(?, String) -> Unit?
get_symbol(
?
self : Self, 
String
name : 
String
String) -> &@llvm.Value? {
  match 
?
self.
Map[String, Unit]
symbols.
fn[K : Hash + Eq, V] Map::get(self : Map[K, V], key : K) -> V?
Retrieves the value associated with a given key in the hash map.
Parameters:

self : The hash map to search in.
key : The key to look up in the map.
Returns Some(value) if the key exists in the map, None otherwise.
Example:
let map = { "key": 42 }
inspect(map.get("key"), content="Some(42)")
inspect(map.get("nonexistent"), content="None")
get(
String
name) {
    
(Unit) -> Unit?
Some(
Unit
value) => 
(Unit) -> Unit?
Some(
Unit
value)
    
Unit?
None =>
      match 
?
self.
Env?
parent {
        
(Env) -> Env?
Some(
Env
parent_env) => 
Env
parent_env.
(String) -> Unit?
get_symbol(
String
name)
        
Env?
None => 
Unit?
None
      }
  }
}

变量处理：内存分配策略​

TinyMoonbit作为一个系统级语言，支持变量的重新赋值。在LLVM IR的SSA（Static Single Assignment）形式中，我们需要采用alloca + load/store的模式来实现可变变量：

pub fn Stmt::
(?, Env) -> Unit raise
emit(
?
self : Self, 
Env
env : 
struct Env {
  parent: Env?
  symbols: Map[String, Unit]
  codegen: CodeGen
  parser_function: ?
  llvm_function: ?
}
Env) -> 
Unit
Unit raise {
  match 
?
self {
    // 变量声明：例如let x : Int = 5;
    
(String, Unit, Unit) -> ?
Let(
String
var_name, 
Unit
var_type, 
Unit
init_expr) => {
      // 转换类型并分配栈空间
      let 
Unit
llvm_type = 
Env
env.
CodeGen
codegen.
(Unit) -> Unit
convert_type(
Unit
var_type)
      let 
Unit
alloca = 
Env
env.
CodeGen
codegen.
?
builder.
(Unit, String) -> Unit
build_alloca(
Unit
llvm_type, 
String
var_name)

      // 将分配的指针记录到符号表
      
Env
env.
Map[String, Unit]
symbols.
fn[K : Hash + Eq, V] Map::set(self : Map[K, V], key : K, value : V) -> Unit
Sets a key-value pair into the hash map. If the key already exists, updates
its value. If the hash map is near full capacity, automatically
grows the internal storage to accommodate more entries.
Parameters:

map : The hash map to modify.
key : The key to insert or update. Must implement Hash and Eq traits.
value : The value to associate with the key.
Example:
let map : Map[String, Int] = Map::new()
map.set("key", 42)
inspect(map.get("key"), content="Some(42)")
map.set("key", 24) // update existing key
inspect(map.get("key"), content="Some(24)")
set(
String
var_name, 
Unit
alloca
Unit
 as &@llvm.Value)

      // 计算初始化表达式的值
      let 
Unit
init_value = 
Unit
init_expr.
(Env) -> Unit
emit(
Env
env).
() -> Unit
into_basic_value()

      // 将初始值存储到分配的内存
      let _ = 
Env
env.
CodeGen
codegen.
?
builder.
(Unit, Unit) -> Unit
build_store(
Unit
alloca, 
Unit
init_value)
    }

    // 变量赋值：x = 10;
    
(Unit, Unit) -> ?
Assign(
Unit
var_name, 
Unit
rhs_expr) => {
      // 从符号表获取变量的内存地址
      guard let 
(_/0) -> Unit
Some(
_/0
var_ptr) = 
Env
env.
(Unit) -> Unit
get_symbol(
Unit
var_name) else {
        raise 
Error
CodeGenError("Undefined variable: \{
Unit
var_name}")
      }

      // 计算右侧表达式的值
      let 
Unit
rhs_value = 
Unit
rhs_expr.
(Env) -> Unit
emit(
Env
env).
() -> Unit
into_basic_value()

      // 存储新值到变量内存
      let _ = 
Env
env.
CodeGen
codegen.
?
builder.
(Unit, Unit) -> Unit
build_store(
Unit
var_ptr, 
Unit
rhs_value)
    }

    // 其他语句类型...
    _ => { /* 处理其他语句 */ }
  }
}

设计决策：为什么使用alloca？

在函数式语言中，不可变变量可以直接映射为SSA值。但TinyMoonbit支持变量重新赋值，这与SSA的"每个变量只赋值一次"原则冲突。

alloca + load/store 模式是处理可变变量的标准做法：

• ​alloca​：在栈上分配内存空间
• ​store​：将值写入内存
• ​load​：从内存读取值

LLVM的优化过程会自动将简单的alloca转换回值形式（mem2reg优化）。

表达式代码生成​

表达式的代码生成相对直观，主要是根据表达式类型调用相应的指令构建方法：

fn Expr::
(?, Env) -> Unit raise
emit(
?
self: Self, 
Env
env: 
struct Env {
  parent: Env?
  symbols: Map[String, Unit]
  codegen: CodeGen
  parser_function: ?
  llvm_function: ?
}
Env) -> &@llvm.Value raise {
  match 
?
self {
    
(Unit) -> ?
AtomExpr(
Unit
atom_expr, ..) => 
Unit
atom_expr.
(Env) -> Unit
emit(
Env
env)
    
(String, Unit, _/0) -> ?
Unary("-", 
Unit
expr, 
_/0
ty = 
(_/0) -> _/0
Some(
_/0
Int)) => {
      let 
Unit
value = 
Unit
expr.
() -> Unit
emit().
() -> Unit
into_int_value()
      let 
Unit
zero = 
Env
env.
Unit
gen.
Unit
llvm_ctx.
() -> Unit
i32_type().
() -> Unit
const_zeor()
      
Env
env.
Unit
gen.
?
builder.
(Unit, Unit) -> Unit
build_int_sub(
Unit
zero, 
Unit
value)
    }
    
(String, Unit, _/0) -> ?
Unary("-", 
Unit
expr, 
_/0
ty = 
(_/0) -> _/0
Some(
_/0
Double)) => {
      let 
Unit
value = 
Unit
expr.
() -> Unit
emit().
() -> Unit
into_float_value()
      
Env
env.
Unit
gen.
?
builder.
(Unit) -> Unit
build_float_neg(
Unit
value)
    }
    
(String, Unit, Unit, _/0) -> ?
Binary("+", 
Unit
lhs, 
Unit
rhs, 
_/0
ty=
(_/0) -> _/0
Some(
_/0
Int)) => {
      let 
Unit
lhs_val = 
Unit
lhs.
() -> Unit
emit().
() -> Unit
into_int_value()
      let 
Unit
rhs_val = 
Unit
rhs.
() -> Unit
emit().
() -> Unit
into_int_value()
      
Env
env.
Unit
gen.
?
builder.
(Unit, Unit) -> Unit
build_int_add(
Unit
lhs_val, 
Unit
rhs_val)
    }
    // ... others
  }
}

技术细节：浮点数取负

注意在处理浮点数取负时，我们使用 build_float_neg​ 而不是用零减去操作数。这是因为：

1. IEEE 754标准：浮点数有特殊值（如NaN、∞），简单的减法可能产生不正确的结果
2. 性能考虑：专用的否定指令在现代处理器上通常更高效
3. 精度保证：避免了不必要的舍入误差

---

第五章：控制流指令的实现​

控制流是程序逻辑的骨架，包括条件分支和循环结构。在LLVM IR中，控制流通过基本块（Basic Blocks）和分支指令来实现。每个基本块代表一个没有内部跳转的指令序列，块与块之间通过分支指令连接。

条件分支：if-else语句的实现​

条件分支需要创建多个基本块来表示不同的执行路径：

fn Stmt::
(?, Env) -> Unit raise
emit(
?
self: Self, 
Env
env: 
struct Env {
  parent: Env?
  symbols: Map[String, Unit]
  codegen: CodeGen
  parser_function: ?
  llvm_function: ?
}
Env) -> 
Unit
Unit raise {
  let 
Unit
ctx = 
Env
env.
Unit
gen.
Unit
llvm_ctx
  let 
Unit
func = 
Env
env.
Unit
llvm_func
  let 
?
builder = 
Env
env.
Unit
gen.
?
builder
  match 
?
self {
    
(Unit, Unit, Unit) -> ?
If(
Unit
cond, 
Unit
then_stmts, 
Unit
else_stmts) => {
      let 
Unit
cond_val = 
Unit
cond.
(Env) -> Unit
emit(
Env
env).
() -> Unit
into_int_value()

      // 创建三个基本块
      let 
Unit
then_block = 
Unit
ctx.
(Unit) -> Unit
append_basic_block(
Unit
llvm_func)
      let 
Unit
else_block = 
Unit
ctx.
(Unit) -> Unit
append_basic_block(
Unit
llvm_func)
      let 
Unit
merge_block = 
Unit
ctx.
(Unit) -> Unit
append_basic_block(
Unit
llvm_func)

      // 创建跳转指令
      let _ = 
?
builder.
(Unit, Unit, Unit) -> Unit
build_conditional_branch(
        
Unit
cond_val, 
Unit
then_block, 
Unit
else_block,
      )

      // 生成then_block的代码
      
?
builder.
(Unit) -> Unit
position_at_end(
Unit
then_block)
      let 
Unit
then_env = 
?
self.
() -> Unit
subenv()
      
Unit
then_stmts.
((Unit) -> Unit) -> Unit
each(
Unit
s => 
Unit
s.
(Unit) -> Unit
emitStmt(
Unit
then_env))
      let _ = 
?
builder.
(Unit) -> Unit
build_unconditional_branch(
Unit
merge_block)

      // 生成else_block的代码
      
?
builder.
(Unit) -> Unit
position_at_end(
Unit
else_block)
      let 
Unit
else_env = 
?
self.
() -> Unit
subenv()
      
Unit
else_stmts.
((Unit) -> Unit) -> Unit
each(
Unit
s => 
Unit
s.
(Unit) -> Unit
emitStmt(
Unit
else_env))
      let _ = 
?
builder.
(Unit) -> Unit
build_unconditional_branch(
Unit
merge_block)

      // 代码生成完毕后，builder的位置要在merge_block上
      
?
builder.
(Unit) -> Unit
position_at_end(
Unit
merge_block)

    }
    // ...
  }
}

生成的LLVM IR示例​

对于以下TinyMoonbit代码：

if x > 0 {
  y = x + 1;
} else {
  y = x - 1;
}

将生成类似这样的LLVM IR：

  %1 = load i32, ptr %x, align 4
  %2 = icmp sgt i32 %1, 0
  br i1 %2, label %if.then, label %if.else

if.then:                                          ; preds = %0
  %3 = load i32, ptr %x, align 4
  %4 = add i32 %3, 1
  store i32 %4, ptr %y, align 4
  br label %if.end

if.else:                                          ; preds = %0
  %5 = load i32, ptr %x, align 4
  %6 = sub i32 %5, 1
  store i32 %6, ptr %y, align 4
  br label %if.end

if.end:                                           ; preds = %if.else, %if.then
  ; 后续代码...

循环结构：while语句的实现​

循环的实现需要特别注意条件检查和循环体的正确连接：

fn Stmt::
(?, Env) -> Unit raise
emit(
?
self: Self, 
Env
env: 
struct Env {
  parent: Env?
  symbols: Map[String, Unit]
  codegen: CodeGen
  parser_function: ?
  llvm_function: ?
}
Env) -> 
Unit
Unit raise {
  let 
Unit
ctx = 
Env
env.
Unit
gen.
Unit
llvm_ctx
  let 
Unit
func = 
Env
env.
Unit
llvm_func
  let 
?
builder = 
Env
env.
Unit
gen.
?
builder
  match 
?
self {
    
(Unit, Unit) -> ?
While(
Unit
cond, 
Unit
body) => {
      // 生成三个块
      let 
Unit
cond_block = 
Unit
ctx.
(Unit) -> Unit
append_basic_block(.llvm_func)
      let 
Unit
body_block = 
Unit
ctx.
(Unit) -> Unit
append_basic_block(
Unit
llvm_func)
      let 
Unit
merge_block = 
Unit
ctx.
(Unit) -> Unit
append_basic_block(
Unit
llvm_func)

      // 首先无条件跳转到cond块
      let _ = 
?
builder.
(Unit) -> Unit
build_unconditional_branch(
Unit
cond_block)
      
?
builder.
(Unit) -> Unit
position_at_end(
Unit
cond_block)

      // 在cond块内生成代码，以及条件跳转指令
      let 
Unit
cond_val = 
Unit
cond.
() -> Unit
emit().
() -> Unit
into_int_value()
      let _ = 
?
builder.
(Unit, Unit, Unit) -> Unit
build_conditional_branch(
        
Unit
cond_val, 
Unit
body_block, 
Unit
merge_block,
      )
      
?
builder.
(Unit) -> Unit
position_at_end(
Unit
body_block)

      // 对body块生成代码，末尾需要一个无条件跳转指令，到cond块
      let 
Unit
body_env = 
?
self.
() -> Unit
subenv()
      
Unit
body.
((Unit) -> Unit) -> Unit
each(
Unit
s => 
Unit
s.
(Unit) -> Unit
emitStmt(
Unit
body_env))
      let _ = 
?
builder.
(Unit) -> Unit
build_unconditional_branch(
Unit
cond_block)

      // 代码生成结束以后，跳转到merge block
      
?
builder.
(Unit) -> Unit
position_at_end(
Unit
merge_block)
    }
    // ...
  }
}

生成的LLVM IR示例​

对于TinyMoonbit代码：

while i < 10 {
  i = i + 1;
}

将生成：

  br label %while.cond

while.cond:                                       ; preds = %while.body, %0
  %1 = load i32, ptr %i, align 4
  %2 = icmp slt i32 %1, 10
  br i1 %2, label %while.body, label %while.end

while.body:                                       ; preds = %while.cond
  %3 = load i32, ptr %i, align 4
  %4 = add i32 %3, 1
  store i32 %4, ptr %i, align 4
  br label %while.cond

while.end:                                        ; preds = %while.cond
  ; 后续代码...

**💡 控制流设计要点 **

1. 基本块的命名策略

​append_basic_block​ 函数同样有name​这个label argument。

// 使用描述性的块名称，便于调试和理解
let 
?
then_block = 
Unit
context.
(Unit, String) -> ?
append_basic_block(
Unit
func, 
String
name="if.then")
let 
?
else_block = 
Unit
context.
(Unit, String) -> ?
append_basic_block(
Unit
func, 
String
name="if.else")
let 
?
merge_block = 
Unit
context.
(Unit, String) -> ?
append_basic_block(
Unit
func, 
String
name="if.end")

2. 作用域管理

// 为每个分支和循环体创建独立的作用域
let 
?
branch_env = 
Unit
env.
() -> ?
sub_env()
branch_stmts.each( stmt => stmt.emit(branch_env) }

3. 构建器位置管理

末尾注意将指令构建器放到正确的基本块上。

// 始终确保构建器指向正确的基本块
builder.position_at_end(merge_block)
// 在这个块中生成指令...

---

第六章：从LLVM IR到机器代码​

在生成完整的LLVM IR之后，我们需要将其转换为目标机器的汇编代码。虽然llvm.mbt​提供了完整的目标机器配置API，但对于学习目的，我们可以使用更简便的方法。

使用llc工具链进行编译​

最直接的方法是将生成的LLVM IR输出到文件，然后使用LLVM工具链进行编译：

调用Module​的dump​函数即可，也可以使用println​函数。

let 
CodeGen
gen : 
struct CodeGen {
  parser_program: ?
  llvm_context: ?
  llvm_module: ?
  builder: ?
  llvm_functions: Map[String, ?]
}
CodeGen = ...
let 
?
prog = 
let gen : CodeGen
gen.
?
llvm_prog
prog.dump() // 更建议使用dump，会比println快一点，效果相同

// or println(prog)

完整的编译流程示例​

让我们看一个完整的从源代码到汇编代码的编译流程：

1. TinyMoonbit源代码

fn 
fn factorial(n : Int) -> Int
factorial(
Int
n: 
Int
Int) -> 
Int
Int {
  if 
Int
n 
fn Compare::op_le(x : Int, y : Int) -> Bool
<= 1 {
    return 1;
  }
  return 
Int
n 
fn Mul::mul(self : Int, other : Int) -> Int
Multiplies two 32-bit integers. This is the implementation of the *
operator for Int.
Parameters:

self : The first integer operand.
other : The second integer operand.
Returns the product of the two integers. If the result overflows the range of
Int, it wraps around according to two's complement arithmetic.
Example:
inspect(42 * 2, content="84")
inspect(-10 * 3, content="-30")
let max = 2147483647 // Int.max_value
inspect(max * 2, content="-2") // Overflow wraps around
* 
fn factorial(n : Int) -> Int
factorial(
Int
n 
fn Sub::sub(self : Int, other : Int) -> Int
Performs subtraction between two 32-bit integers, following standard two's
complement arithmetic rules. When the result overflows or underflows, it
wraps around within the 32-bit integer range.
Parameters:

self : The minuend (the number being subtracted from).
other : The subtrahend (the number to subtract).
Returns the difference between self and other.
Example:
let a = 42
let b = 10
inspect(a - b, content="32")
let max = 2147483647 // Int maximum value
inspect(max - -1, content="-2147483648") // Overflow case
- 1);
}

fn main() -> Unit {
  let 
Int
result: 
Int
Int = 
fn factorial(n : Int) -> Int
factorial(5);
  
(Int) -> Unit
print_int(
Int
result);
}

2. 生成的LLVM IR

; ModuleID = 'tinymoonbit'
source_filename = "tinymoonbit"

define i32 @factorial(i32 %0) {
entry:
  %1 = alloca i32, align 4
  store i32 %0, ptr %1, align 4
  %2 = load i32, ptr %1, align 4
  %3 = icmp sle i32 %2, 1
  br i1 %3, label %4, label %6

4:                                                ; preds = %entry
  ret i32 1

6:                                                ; preds = %entry
  %7 = load i32, ptr %1, align 4
  %8 = load i32, ptr %1, align 4
  %9 = sub i32 %8, 1
  %10 = call i32 @factorial(i32 %9)
  %11 = mul i32 %7, %10
  ret i32 %11
}

define void @main() {
entry:
  %0 = alloca i32, align 4
  %1 = call i32 @factorial(i32 5)
  store i32 %1, ptr %0, align 4
  %2 = load i32, ptr %0, align 4
  call void @print_int(i32 %2)
  ret void
}

declare void @print_int(i32 %0)

3. 使用LLC生成RISC-V汇编

# 生成llvm ir
moon run main --target native > fact.ll

# 生成RISC-V 64位汇编代码
llc -march=riscv64 -mattr=+m -o fact.s fact.ll

4. 生成的RISC-V汇编片段

factorial:
.Lfunc_begin0:
	.cfi_startproc
	addi	sp, sp, -32
	.cfi_def_cfa_offset 32
	sd	ra, 24(sp)
	.cfi_offset ra, -8
	sd	s0, 16(sp)
	.cfi_offset s0, -16
	addi	s0, sp, 32
	.cfi_def_cfa s0, 0
	sw	a0, -20(s0)
	lw	a0, -20(s0)
	li	a1, 1
	blt	a1, a0, .LBB0_2
	li	a0, 1
	j	.LBB0_3
.LBB0_2:
	lw	a0, -20(s0)
	lw	a1, -20(s0)
	addi	a1, a1, -1
	sw	a0, -24(s0)
	mv	a0, a1
	call	factorial
	lw	a1, -24(s0)
	mul	a0, a1, a0
.LBB0_3:
	ld	ra, 24(sp)
	ld	s0, 16(sp)
	addi	sp, sp, 32
	ret

---

结语​

通过本系列的两篇文章，我们完成了一个功能完整的编译器实现。尽管功能简单，但比较完整。从字符流的词法分析，到抽象语法树的构建，再到LLVM IR的生成和机器代码的输出。

回顾​

上篇：

• 基于模式匹配的优雅词法分析器
• 递归下降语法分析器的实现
• 完整的类型检查系统
• 环境链作用域管理

下篇：

• LLVM类型和值系统的深入理解
• SSA形式下的变量管理策略
• 控制流指令的正确实现
• 完整的代码生成流水线

Moonbit在编译器开发中的优势​

通过这个实践项目，我们深刻体会到了Moonbit在编译器构建领域的独特价值：

1. 表达力强大的模式匹配：极大简化了AST处理和类型分析的复杂度。
2. 函数式编程范式：不可变数据结构和纯函数使得编译器逻辑更加清晰可靠。
3. 现代化的类型系统：trait对象、泛型和错误处理机制提供了充分的抽象能力。
4. 优秀的工程特性：derive功能、JSON序列化等特性显著提升了开发效率。

结语​

编译器技术代表了计算机科学理论与工程实践的完美结合。通过Moonbit这一现代化的工具，我们能够以更加优雅和高效的方式探索这个古老而又充满活力的领域。

希望本系列文章能够为读者在编译器设计的道路上提供一个有力的帮助。

学习资源推荐

• Moonbit官方文档
• llvm.mbt文档
• llvm.mbt项目
• LLVM官方教程

---