#llvm.mbt: LLVM 22 bindings for MoonBit

#Features

• A typed IR-building API for contexts, modules, types, values, functions, basic blocks, instructions, attributes, data layouts, bitcode, and the LLVM interpreter.
• Low-level bindings for broader llvm-c functionality, including analysis, bitcode and IR readers/writers, execution engines, ORC/LLJIT, linking, targets, target machines, and transforms.
• Upstream LLVM code generation targets bundled into each distributed artifact.
• A reproducible native dependency: the archive URL, file size, and SHA-256 digests are fixed in build.js.
• A shared cache under $MOON_HOME/cache/lib/llvm.mbt, so MoonBit projects using the same artifact do not download separate LLVM copies.

#Requirements and supported hosts

• Node.js available in PATH, because Moon runs build.js with Node.js;
• a normal native C/C++ toolchain available as cc.

• tar with XZ support;
• HTTPS access to the project's GitHub Release.

#Installation

moon add Kaida-Amethyst/llvm

import {
  "Kaida-Amethyst/llvm/IR" @llvm,
}

preferred_target = "native"

moon check --target native
moon test --target native

#How the LLVM dependency is installed

1. selects the artifact matching the host;
2. checks $MOON_HOME/cache/lib/llvm.mbt/22.1.0-r1/<platform>/sha256-<digest>;
3. downloads the archive from the LLVM 22.1.0 Release when the cache is absent;
4. verifies the archive SHA-256, extracts it atomically, and verifies the manifest and libLLVM-mbt.a SHA-256;
5. supplies the include and linker flags to Moon's native build.

#Quick start

///|
test "build an integer addition function" {
  let ctx = @llvm.Context::new()
  let mod = ctx.addModule("example")
  let builder = ctx.createBuilder()
  let i32_ty = ctx.getInt32Ty()
  let function_ty = ctx.getFunctionType(i32_ty, [i32_ty, i32_ty])
  let function = mod.addFunction(function_ty, "add")
  let entry = function.addBasicBlock(name="entry")
  guard function.getArg(0) is Some(lhs) else {
    fail("missing lhs")
  }
  guard function.getArg(1) is Some(rhs) else {
    fail("missing rhs")
  }
  builder.setInsertPoint(entry)
  let sum = builder.createAdd(lhs, rhs, name="sum")
  builder.createRet(sum) |> ignore
  inspect(
    function,
    content=(
      #|define i32 @add(i32 %0, i32 %1) {
      #|entry:
      #|  %sum = add i32 %0, %1
      #|  ret i32 %sum
      #|}
      #|
    ),
  )
}

#Developing llvm.mbt

moon check --target native
moon test --target native
moon info
moon fmt

• IR/ contains the higher-level MoonBit API.
• internal/raw/ contains the module-private LLVM-C bindings and native wrapper.
• build.js manages the pinned LLVM artifact and shared cache.
• Generated .mbti files describe each package's public interface.

#中文说明

#功能

• 提供带类型的 IR 构造 API，覆盖上下文、模块、类型、值、函数、基本块、指令、 属性、数据布局、bitcode 和 LLVM 解释器。
• 提供范围更广的底层 llvm-c 绑定，包括分析、bitcode 与 IR 读写、 执行引擎、ORC/LLJIT、链接、Target、TargetMachine 和变换接口。
• 每个平台的分发产物都包含上游 LLVM 代码生成目标。
• 原生依赖可复现：build.js 中固定了压缩包 URL、文件大小和 SHA-256。
• 使用 $MOON_HOME/cache/lib/llvm.mbt 作为共享缓存；同一台机器上的多个 MoonBit 项目不需要分别下载同一份 LLVM。

#环境要求与支持平台

• PATH 中存在 Node.js，因为 Moon 使用 Node.js 运行 build.js；
• 可通过 cc 调用的常规原生 C/C++ 工具链。

• 支持 XZ 的 tar；
• 能够通过 HTTPS 访问本项目的 GitHub Release。

#安装

moon add Kaida-Amethyst/llvm

import {
  "Kaida-Amethyst/llvm/IR" @llvm,
}

preferred_target = "native"

moon check --target native
moon test --target native

#LLVM 依赖如何安装

1. 根据宿主平台选择对应产物；
2. 检查 $MOON_HOME/cache/lib/llvm.mbt/22.1.0-r1/<platform>/sha256-<digest>；
3. 缓存不存在时，从 LLVM 22.1.0 Release 下载压缩包；
4. 校验压缩包 SHA-256，原子化解压，并校验清单和 libLLVM-mbt.a 的 SHA-256；
5. 把 include 与链接参数交给 Moon 的 native 构建流程。

#快速开始

///|
test "构造整数加法函数" {
  let ctx = @llvm.Context::new()
  let mod = ctx.addModule("example")
  let builder = ctx.createBuilder()
  let i32_ty = ctx.getInt32Ty()
  let function_ty = ctx.getFunctionType(i32_ty, [i32_ty, i32_ty])
  let function = mod.addFunction(function_ty, "add")
  let entry = function.addBasicBlock(name="entry")
  guard function.getArg(0) is Some(lhs) else {
    fail("缺少 lhs")
  }
  guard function.getArg(1) is Some(rhs) else {
    fail("缺少 rhs")
  }
  builder.setInsertPoint(entry)
  let sum = builder.createAdd(lhs, rhs, name="sum")
  builder.createRet(sum) |> ignore
  inspect(
    function,
    content=(
      #|define i32 @add(i32 %0, i32 %1) {
      #|entry:
      #|  %sum = add i32 %0, %1
      #|  ret i32 %sum
      #|}
      #|
    ),
  )
}

#开发 llvm.mbt

moon check --target native
moon test --target native
moon info
moon fmt

• IR/ 存放较高层的 MoonBit API。
• internal/raw/ 存放模块私有的 LLVM-C binding 与 native wrapper。
• build.js 管理固定版本的 LLVM 产物和共享缓存。
• 自动生成的 .mbti 文件描述每个 package 的公开接口。