Yuan 编译器项目文档

Yuan 是一个基于 LLVM 的静态类型编译型语言实现。 仓库包含语言前端（词法、语法、语义）、LLVM IR 代码生成、运行时、标准库、测试与工具链。

• 前端链路可用：Lexer -> Parser -> Sema
• 后端链路可用：CodeGen -> LLVM IR -> Object -> Link
• 模块导入可用：@import + ModuleManager
• 当前仓库优先收敛稳定内核，避免规范长期领先实现

• 基础类型、函数、结构体、枚举、match
• 基础泛型与 @import 模块导入
• 显式错误返回 !T、expr!、expr! -> err { ... }
• 最小标准库闭环：std.io、std.fmt、std.mem、std.string、std.fs

• async/await 与异步运行时
• 运算符 trait 扩展能力
• 高阶 trait 生态（含关联类型等复杂约束）
• GUI、网络、OpenAI 相关标准库能力
• 依赖完整析构的资源型泛型容器

• include/yuan/：公开头文件（AST、Sema、CodeGen、Driver 等）
• src/：编译器核心实现
• runtime/：运行时（异步、FFI、格式化、OS/GUI 适配、HTTP）
• stdlib/：标准库 Yuan 源码
• tools/yuanc/：命令行编译器入口
• tools/yuanfilt/：符号反修饰工具
• tests/：单元测试、语言测试、stdlib 测试
• docs/：模块级实现文档
• docs/spec/：语言规范与约束

• CMake >= 3.16
• C++17 编译器（Clang/GCC/MSVC）
• LLVM 开发库（由 cmake/FindLLVM.cmake 发现）
• libcurl（用于运行时 HTTP 能力）

cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build -j

默认目标通常包括：

• yuanc（编译器）
• yuan_runtime（运行时库）
• 测试（当 YUAN_BUILD_TESTS=ON）

yuanc 常用示例：

# 仅语法/语义检查
./build/tools/yuanc/yuanc -fsyntax-only examples/snake_demo.yu

# 输出 LLVM IR
./build/tools/yuanc/yuanc -S -emit-llvm examples/snake_demo.yu

# 生成目标文件
./build/tools/yuanc/yuanc -c examples/snake_demo.yu

# 直接编译并链接可执行文件
./build/tools/yuanc/yuanc examples/snake_demo.yu -o snake_demo

# 输出 token / AST / pretty
./build/tools/yuanc/yuanc -dump-tokens examples/snake_demo.yu
./build/tools/yuanc/yuanc -ast-dump examples/snake_demo.yu
./build/tools/yuanc/yuanc -ast-print examples/snake_demo.yu

常用参数：

• -O0/-O1/-O2/-O3：优化等级
• -I：附加搜索路径（也用于模块包路径来源）
• --pkg-path：预编译包搜索路径
• --stdlib：指定标准库根路径
• --module-cache：模块缓存目录（默认 .yuan/cache）
• --project：指定或自动发现 project.yaml 项目配置

yupkg 提供类似 cargo 的基础命令（依赖支持 path + git）：

# 初始化项目
./build/tools/yupkg/yupkg init

# 构建（Debug/Release）
./build/tools/yupkg/yupkg build
./build/tools/yupkg/yupkg build --release

# 运行主程序
./build/tools/yupkg/yupkg run --release -- arg1 arg2

# 运行 tests/*.yu
./build/tools/yupkg/yupkg test

# 清理
./build/tools/yupkg/yupkg clean
./build/tools/yupkg/yupkg clean --all

project.yaml 扩展示例：

version: 1
package:
  name: demo
  version: "0.1.0"
dependencies:
  foo:
    path: ../foo
  bar:
    git: https://example.com/bar.git
    tag: v0.2.0
compile:
  optLevel: O2
  includePaths:
    - ./include

当前约束：

• @import("pkg") 指向包入口，@import("pkg.sub") 指向包内模块。
• 相对导入仅使用 ./ 和 ../。
• 不再依赖“裸名字优先按当前目录猜测”的导入行为。

ctest --test-dir build --output-on-failure

更多测试脚本见 tests/scripts/README.md。

1. Driver 读取输入并初始化 SourceManager/DiagnosticEngine
2. Lexer 产出 Token
3. Parser 构建 AST
4. Sema 建立符号表、解析类型并执行语义检查
5. CodeGen 将 AST 降低到 LLVM IR
6. 生成 .ll / .o 并链接为可执行文件

• 总索引：docs/README.md
• 语义分析：docs/Sema/README.md
• 代码生成：docs/CodeGen/README.md
• 语言规范：docs/spec/Yuan_Language_Spec.md

阅读建议：

• 把 docs/spec/Yuan_Language_Spec.md 视为当前稳定内核的主规范。
• 对 async、GUI、网络等能力，优先以实现与测试为准，它们仍处于实验层。

• 修改语义或后端行为时，同步更新对应文档。
• 行为变更请补充 tests/yuan/ 或 tests/unit/ 用例。
• 新增运行时能力（尤其 I/O、网络）时，建议提供最小可运行示例。