#MoonLLVM – A Tiny, Friendly Companion to LLVM

• Easy to read and reason about
• Fast to compile and start
• Great for learning IR, compiler construction, and LLVM’s internal design
• Designed to interoperate closely with the official LLVM via llvm.mbt

#Key Ideas

#Tiny LLVM, Written in MoonBit

• Pure MoonBit implementation: MoonLLVM re-implements much of LLVM’s data structures and IR-building APIs directly in MoonBit.
• Multiple backends: Because it is written in MoonBit, MoonLLVM itself can be compiled to:
  • Native
  • WebAssembly
  • JavaScript
• No heavyweight dependency: You can generate LLVM IR without installing the full LLVM toolchain.

Need to generate assembly or machine code? For that, MoonLLVM works hand‑in‑hand with MoonMIR, a separate library that takes IR to target-specific assembly.

#Designed as the Best Companion to LLVM, Not a Competitor

MoonLLVM = The best complement to LLVM for MoonBit developers.

1. Aligned APIs with llvm.mbt: The public APIs of MoonLLVM are intentionally kept very similar to those of llvm.mbt (the MoonBit bindings to real LLVM via llvm-c). In many cases, you can switch from MoonLLVM to real LLVM by simply updating your moon.pkg.json imports. (The reverse direction may not always work.)
   • We maintain hundreds of test cases to ensure this compatibility.

2. Interoperable IR & Bitcode (in progress):
   • Today, MoonLLVM can emit .ll LLVM IR that is accepted by the official LLVM toolchain (opt, llc, etc.).
   • We are actively working on:
     1. Emitting .bc LLVM bitcode that the LLVM toolchain can understand and compile.
     2. Parsing LLVM IR text (first fully for MoonLLVM‑generated .ll, then partially for upstream LLVM IR).
     3. Decoding/encoding LLVM bitcode (first for MoonLLVM‑generated .bc, then partially for upstream LLVM bitcode).

3. C++‑inspired API design:
   • Both MoonLLVM and llvm.mbt closely mirror the original LLVM C++ API design.
   • This means:
     • If you know LLVM C++ APIs, you will feel at home.
     • In many cases, you can almost translate MoonLLVM code back to C++ LLVM code one‑to‑one.

#Performance & Developer Experience

• Fast compilation & startup: In realistic scenarios, using MoonLLVM currently gives about 7× faster compile and startup times compared to using upstream LLVM via llvm.mbt (measured in our own experiments).
• Still room to grow: We have an ongoing roadmap of performance improvements to make it even faster.

• Rapid prototyping of languages and IRs
• Interactive tools
• In‑browser / embedded compilation scenarios

#Clean Architecture, Made for Learning and Hacking

• Flatter structure: fewer layers of indirection, more direct data flows.
• More documentation & explanations: many modules include rich comments and examples.
• Doc tests: many docs include runnable examples; they are part of our test suite.
• High code quality: written with readability and clarity in mind, not C++ template wizardry.

• Learning LLVM IR and compiler passes
• Experimenting with IR transforms
• Teaching compiler courses in MoonBit

#Highly Modular, Built to Stay Lightweight

• MoonLLVM: IR data structures and core APIs
• MoonMIR: lowers LLVM‑like IR to target assembly (e.g., riscv64, aarch64, and more)
• Future planned components as separate libraries:
  • IR parser
  • Bitcode encoder/decoder
  • Pass framework
  • Assembler
  • Linker
  • Debugging utilities

• If you only need IR construction, you just depend on MoonLLVM — often just a few hundred KB in a Wasm/JS build.
• For browser or embedded environments, you can pick exactly the pieces you need, keeping your binary small and focused.

#Deliberate Simplicity: Not All Features, Not All Platforms

• All of LLVM’s targets
• All corner‑case features (e.g., C’s VLA, scalable vector types, very exotic platforms)

• Avoid a lot of complexity and fragile edge cases
• Keep the code base much easier to understand
• Focus on the most useful subset for most MoonBit use cases

#Relationship to Other MoonBit Compiler Projects

• llvm.mbt MoonBit bindings to real LLVM 19 via llvm-c.
  • Use this when you need full upstream LLVM power: all targets, all optimizations, all tools.
  • MoonLLVM is designed to align with its APIs and interoperate via IR and bitcode.

• MoonMIR MoonBit implementation of the lowering pipeline from LLVM‑style IR to assembly (currently riscv64 and aarch64, with more planned).
  • Use MoonMIR alongside MoonLLVM when you want to go all the way from IR to assembly in pure MoonBit.

• MiniMoonbit2025 A serious, non‑toy subset language of MoonBit, featuring:
  • Basic operations, control flow, structs, ADTs, pattern matching
  • Good error messages
  • Backends to LLVM IR, aarch64, and riscv64 assembly It serves as a concrete, real‑world example of building a compiler front‑end on top of MoonLLVM + MoonMIR — including complex examples like ray tracing, SVD, and even a Lisp interpreter.

#Current Status

• Build LLVM‑style IR (modules, functions, basic blocks, instructions, types, etc.)
• Print .ll text that is accepted by the LLVM toolchain
• Interoperate conceptually with llvm.mbt by sharing similar APIs

• Emit .bc bitcode (planned)
• Parse upstream LLVM IR in full generality (partial support planned)
• Include a built‑in assembler / linker / debugger — these will live in separate libraries (MoonMIR, future assembler, linker, etc.)

#Getting Started

#Installation

moon update
moon add Kaida-Amethyst/MoonLLVM

#Minimal Example

fn main {
  // 1. Set up the context and IR builder.
  let ctx = @IR.Context::new()
  let mod = ctx.addModule("demo")
  let builder = IRBuilder::new()

  // 2. Define the function type: i32 add(i32, i32).
  let i32_t = ctx.getInt32Ty()
  let f_type = ctx.getFunctionType(i32_t, [i32_t, i32_t])

  // 3. Add the function to the module and create an entry block.
  let f = mod.addFunction(f_type, "add")
  let bb = f.addBasicBlock(name="entry")
  builder.setInsertPoint(bb)

  // 4. Get the function args and name them.
  let x = f.getArg(0).unwrap()
  x.setName("x")
  let y = f.getArg(1).unwrap()
  y.setName("y")

  // 5. Create the add instruction and return.
  let sum = builder.createAdd(x, y, name="sum")
  builder.createRet(sum)

  // 6. Print the generated LLVM IR.
  println(mod)
}

moon run main.mbt > add.ll

llc -o add.s add.ll

#Roadmap

1. C compiler mbtcc built on MoonLLVM
2. Assembler & linker as standalone, MoonBit‑native components
3. Bitcode (.bc) support: emit, decode, and re‑encode bitcode
4. LLVM IR parser with strong support for MoonLLVM‑generated IR and partial support for upstream IR
5. Solid support for mainstream targets: x86_64, aarch64, riscv64
6. Continuous improvement:
   • Better documentation and tutorials
   • Higher test coverage (including doc tests)
   • Faster build and execution times

#MoonLLVM —— 轻量但强大的 LLVM 好伙伴

Back to English

🌟 MoonBit 开发者眼中，最舒服、最易懂的 LLVM 补充。

• 体积小、结构清晰、代码可读性高；
• 编译和启动速度非常快（目前实测比通过 llvm.mbt 使用真 LLVM 快约 7 倍左右）；
• 非常适合作为：教学、研究、原型开发、浏览器/嵌入式上的轻量编译平台。

#核心理念

#Tiny LLVM，纯 MoonBit 实现

• 纯 MoonBit 实现： 直接在 MoonBit 中实现 LLVM 的各类数据结构和 IR 构造 API。
• 多种后端： MoonLLVM 自身可以被编译到：
  • 原生（Native）
  • WebAssembly
  • JavaScript
• 无需庞大依赖： 生成 IR 不需要在本地安装完整的 LLVM 工具链。

需要生成汇编 / 机器码？ 请搭配 MoonMIR 使用，它是一个用 MoonBit 实现的后端管线，可以把 IR 降成具体架构的汇编代码。

#MoonLLVM 的愿景：LLVM 的最佳「补充」，而不是对手

与 LLVM 紧密互操作的轻量伙伴，为 MoonBit 生态补齐「好读、好学、好改」的那一块。

1. 接口设计与 llvm.mbt 高度一致：
   • MoonLLVM 的 API 设计刻意与 llvm.mbt 保持相似。
   • 多数情况下，只需要修改 moon.pkg.json 中的 imports，就能把后端从 MoonLLVM 换成真 LLVM。（反过来未必总是成立。）
   • 为此我们会维护上百个测试用例，保证两者行为尽可能一致。

2. IR / 字节码互操作（进行中）：
   • 当前，MoonLLVM 生成的 .ll IR 已经可以被官方 LLVM 工具链（opt, llc 等）识别并编译。
   • 正在推进的方向包括：
     1. 产出能够被 LLVM 工具链识别的 .bc 字节码；
     2. IR 解析：优先支持解析 MoonLLVM 自己生成的 .ll，并逐步兼容一部分真 LLVM 生成的 IR；
     3. 字节码 decode / encode：首先支持 MoonLLVM 自己生成的 .bc，随后支持部分真 LLVM 的字节码。

3. 模仿原版 C++ API 的接口设计：
   • MoonLLVM 和 llvm.mbt 的接口设计都高度模仿 原版 C++ LLVM API。
   • 这意味着：
     • 熟悉 LLVM C++ 的开发者可以很快上手；
     • 很多 MoonLLVM 项目基本可以「一对一」翻译回 C++ 版本的 LLVM 代码。

#性能与开发体验

• 编译 & 启动更快： 当前实测，在同等场景下，使用 MoonLLVM 的编译/启动速度大约是通过 llvm.mbt 使用真 LLVM 的 7 倍左右。
• 还有优化空间： 我们已经在规划一系列提速计划，未来会继续挖潜。

• 快速语言原型、IR 原型开发；
• 交互式工具、REPL；
• 浏览器 / 嵌入式环境中的轻量编译器。

#内部架构更扁平、更好读，非常适合学习和研究

• 结构更扁平： 少一点间接层，更直接的数据流。
• 更多文档和注释： 关键模块都有详尽说明。
• 文档即测试： 许多文档中的示例是可运行的 doc test，直接纳入测试体系。
• 代码质量高、可读性优先： 避免 C++ 模板魔法那种「非人类可读」写法。

• 学习 LLVM IR 和编译器 Pass 的教材；
• 编译原理课程的实战项目；
• 用 MoonBit 来研究 LLVM 内部结构和设计思想的入口。

#更加模块化：按需引入，极致轻量

• MoonLLVM： 只负责 LLVM 风格 IR 的数据结构与构造 API；
• MoonMIR： 负责将 IR 降到具体平台的汇编（目前支持 riscv64 / aarch64 等）；
• 未来的组件会尽可能做成独立的 MoonBit 库，例如：
  • Pass 框架；
  • IR Parser；
  • Bytecode 编解码器；
  • Assembler；
  • Linker；
  • 调试工具等。

• 只需要 IR？那就只 add MoonLLVM，在浏览器/Wasm/嵌入式环境下可能只有几百 KB。
• 真正需要生成汇编时，再视需要引入 MoonMIR 和相关组件。
• 不像真 LLVM 那样「要用一点东西，就要拉一大坨依赖、编半天」。

#有意做减法：不追求全平台、不追求所有特性

• C 语言的 VLA（变长数组）；
• 非常复杂的 Scalable Vector 类型；
• 各种极为偏门的目标架构。

• 更低的复杂度；
• 更容易读懂和维护的代码；
• 更贴合大多数 MoonBit 使用场景的实践体验。

#与其他 MoonBit 编译项目的关系

• llvm.mbt 使用 llvm-c 构建的真 LLVM 19 的 MoonBit binding。
  • 当你需要真 LLVM 的全部能力（所有平台、所有优化、成熟的工具链）时，请使用它。
  • MoonLLVM 的接口设计和它高度对齐，并通过 IR / 字节码与其协作。

• MoonMIR 用 MoonBit 实现的，从 LLVM 风格 IR 到汇编的后端管线（目前支持 riscv64, aarch64 等）。
  • 当你需要从 MoonLLVM 的 IR 一路编到汇编时，和 MoonMIR 搭配使用即可。

• MiniMoonbit2025 一个并不「玩具」的 MoonBit 语言子集，拥有：
  • 基本运算、控制流；
  • 结构体、ADT、模式匹配；
  • 友好的错误提示；
  • LLVM IR / aarch64 / riscv64 汇编后端。 它展示了如何基于 MoonLLVM + MoonMIR 搭建一个可以运行严肃例子的编译器（包括光线追踪、SVD 分解、Lisp 解释器等），非常适合作为学习范例与真实项目参考。

#当前状态

• 构建 LLVM 风格的 IR（模块、函数、基本块、指令、类型等）；
• 打印出可以被 LLVM 工具链接受的 .ll 文本；
• 在设计上与 llvm.mbt 保持高度一致，方便互相迁移。

• .bc 字节码的产出；
• 对真 LLVM IR 的全面解析（会从支持 MoonLLVM 自身 IR 开始，逐步扩展）；
• 内建的 assembler / linker / debugger（这些会作为独立库存在，例如 MoonMIR 及后续组件）。

#快速上手

#安装

moon update
moon add Kaida-Amethyst/MoonLLVM

#简单示例

fn main {
  // 1. 创建上下文和 IR builder。
  let ctx = @IR.Context::new()
  let mod = ctx.addModule("demo")
  let builder = ctx.createBuilder()

  // 2. 定义函数类型：i32 add(i32, i32)。
  let i32_t = ctx.getInt32Ty()
  let f_type = ctx.getFunctionType(i32_t, [i32_t, i32_t])

  // 3. 向模块中添加函数并创建入口基本块。
  let f = mod.addFunction(f_type, "add")
  let bb = f.addBasicBlock(name="entry")
  builder.setInsertPoint(bb)

  // 4. 获取参数并命名。
  let x = f.getArg(0).unwrap()
  x.setName("x")
  let y = f.getArg(1).unwrap()
  y.setName("y")

  // 5. 创建加法指令和返回指令。
  let sum = builder.createAdd(x, y, name="sum")
  let _ = builder.createRet(sum)

  // 6. 打印生成的 LLVM IR。
  println(mod)
}

moon run main.mbt > add.ll

llc -o add.s add.ll

#未来规划

1. 基于 MoonLLVM 的 C 编译器：mbtcc
2. Assembler 与 Linker： 以独立库形式提供的 MoonBit 原生汇编器与链接器
3. Bytecode 支持： 产出 / decode / encode .bc 字节码
4. LLVM IR Parser： 优先支持 MoonLLVM 自己生成的 IR，逐步兼容更多真 LLVM IR
5. 主流平台支持完善： 包括 x86_64、aarch64 和 riscv64
6. 进一步打磨：
   • 更好的文档与教程；
   • 更高的测试覆盖率（含 doc test）；
   • 更快的编译和运行速度。