Imported from alecksty/VML-tools (Release-win-x64-1.65.10/docs/AGENTS.md). Install upstream with npx skills add alecksty/VML-tools --skill docs. Copyright stays with the author.

VML 工具链 - 开发者指南

项目概述

VML（虚拟机语言）是一个基于 C# 的编译器工具链，采用"多前端 + 统一 IR + 多后端"架构。该项目目标为 .NET 10.0。

关键命令

构建和运行 (C#)

# 构建整个解决方案
dotnet build VMLToolchain.sln

# 运行主命令行工具
dotnet run --project VMLTool

# 运行全设备模拟器（主要运行环境）
dotnet run --project VMLEmulators\FullDevicesEmulator

# 运行控制台 VGA 显示（替代运行时）
dotnet run --project VMLEmulators\ConsoleEmulator -- -r <file>

# 运行并启用调试跟踪
dotnet run --project VMLEmulators\ConsoleEmulator -- -r <file> --debug

# 设置超时时间（秒，默认30，0=无限制）
dotnet run --project VMLEmulators\ConsoleEmulator -- -r <file> --timeout 60

# 单步调试
dotnet run --project VMLEmulators\ConsoleEmulator -- -s <file> --debug

构建和运行 (C 运行时 - 跨平台)

# 使用 Make (推荐 - Unix/macOS/Linux)
cd VMLRuntimeC
make              # 编译
./vmlrun          # 默认帮助

# 运行程序
./vmlrun program.vml    # VML 文本格式
./vmlrun program.vmb    # VMB 二进制格式
./vmlrun -d program.vml  # 调试模式
./vmlrun -v             # 显示版本

# 其他目标
make clean       # 清理
make debug      # 调试编译
make release   # 发布编译
make static    # 静态编译（适用于 Linux）
make install   # 安装到 /usr/local/bin

# 使用 CMake (跨平台)
mkdir build && cd build
cmake ..
make

打包 VML 文件 (VMLPackerC)

cd VMLPackerC

# 编译工具
make              # 编译 vmlpacker (VML->VMB)
make exe          # 编译 vmlexe (VMB->EXE)

# 打包 VML -> VMB
./vmlpacker input.vml output.vmb
./vmlpacker input.vml    # 自动生成 .vmb

# 打包 VMB -> 独立可执行文件
./vmlexe output.vmb myapp
./myapp

# 静态编译
make static             # 静态编译（适用于 Linux）

编译工作流

# 使用VMLTool编译 (插件架构) - 支持16种语言 (GCC风格标记格式)
vmltool input.c -o output.vml -x c                # GCC风格 -x
vmltool input.bas -o output.vml --lang basic       # 或 --lang
vmltool input.pas -o output.vml --lang pascal
vmltool input.ld -o output.vml --lang ladder
vmltool input.py -o output.vml --lang python
vmltool input.fth -o output.vml --lang forth
vmltool input.lua -o output.vml --lang lua
vmltool input.rs -o output.vml --lang rust
vmltool input.go -o output.vml --lang go
vmltool input.java -o output.vml --lang java
vmltool input.js -o output.vml --lang javascript
vmltool input.swift -o output.vml --lang swift
vmltool input.cs -o output.vml --lang csharp
vmltool input.cpp -o output.vml --lang cpp

# 或根据文件扩展名自动选择编译器
vmltool input.c -o output.vml
vmltool input.bas -o output.vml

# 汇编 VML
vmltool -a input.vml -o output.bin

# 转译 VML 到目标架构
vmltool -T input.vml -o output.asm -t 6502

# 运行 VML 程序
vmltool -r input.vml

测试

# Run VML library test
dotnet run --project VMLPrepares\CCompiler -I Lib/c Test\c\test_vmlib.c -o test_vmlib.vml
dotnet run --project VMLEmulators\ConsoleEmulator -- -r test_vmlib.vml

# Run C99 standard test
dotnet run --project VMLPrepares\CCompiler -I Lib/c Test\c\test_c99.c -o test_c99.vml
dotnet run --project VMLEmulators\ConsoleEmulator -- -r test_c99.vml

# 编译各语言测试
dotnet run --project VMLPrepares\BasicCompiler Test\test.bas -o test.vml
dotnet run --project VMLPrepares\PascalCompiler Test\test.pas -o test.vml
dotnet run --project VMLPrepares\PythonCompiler Test\test.py -o test.vml
dotnet run --project VMLPrepares\LuaCompiler Test\test.lua -o test.vml
dotnet run --project VMLPrepares\GoCompiler Test\test.go -o test.vml
dotnet run --project VMLPrepares\ForthCompiler Test\test.fth -o test.vml
dotnet run --project VMLPrepares\LadderCompiler Test\test.ld -o test.vml
dotnet run --project VMLPrepares\RustCompiler Test\test.rs -o test.vml
dotnet run --project VMLPrepares\CCompiler Test\test.c -o test.vml

# 运行生成的VML
dotnet run --project VMLEmulators\ConsoleEmulator -- -r test.vml

内置函数标准库

所有语言共用的内置函数统一放在 Lib/shared/builtins.vml 中：

各编译器通过内置函数分发转为 CALL vml_xxx，标准库在链接时通过 .include 机制自动加载。

标准库包含机制

所有实现 IFrontendCompilerEx 接口的编译器（C/BASIC/Pascal/Ladder/Python/Forth/Lua/Rust/Go）均支持 CompileFileWithIncludes 方法，编译时自动生成 .include 伪指令引用标准库，而不是将库代码内联链接到输出中。这使得：

• 输出文件更小，只包含用户代码
• 标准库由 VML 汇编器在运行时动态加载
• 支持共享库模式（通过 Lib/shared/ 目录）

架构说明

核心组件

• VMLAssembler：VML 汇编器（IR 生成器）- 将 VML 汇编解析为二进制格式
• VMLTranslators：多目标翻译器（6502、Z80、8051、ARM-CM、X86）
• CCompiler：C 语言编译器 - C → VML (see COMPLETION_DASHBOARD.md for actual completion)
• BasicCompiler：BASIC 语言编译器 - BASIC → VML (see COMPLETION_DASHBOARD.md for actual completion)
• PascalCompiler：Pascal 语言编译器 - Pascal → VML (see COMPLETION_DASHBOARD.md for actual completion)
• LadderCompiler：梯形图编译器 - Ladder → VML (see COMPLETION_DASHBOARD.md for actual completion)
• PythonCompiler：Python 语言编译器 - Python → VML (see COMPLETION_DASHBOARD.md for actual completion)
• ForthCompiler：Forth 语言编译器 - Forth → VML (see COMPLETION_DASHBOARD.md for actual completion)
• LuaCompiler：Lua 语言编译器 - Lua → VML (see COMPLETION_DASHBOARD.md for actual completion)
• RustCompiler：Rust 语言编译器 - Rust → VML (see COMPLETION_DASHBOARD.md for actual completion)
• GoCompiler：Go 语言编译器 - Go → VML (see COMPLETION_DASHBOARD.md for actual completion)
• JavaCompiler：Java 语言编译器 - Java → VML (see COMPLETION_DASHBOARD.md for actual completion)
• JavaScriptCompiler：JavaScript 语言编译器 - JavaScript → VML (see COMPLETION_DASHBOARD.md for actual completion)
• SwiftCompiler：Swift 语言编译器 - Swift → VML (see COMPLETION_DASHBOARD.md for actual completion)
• CSharpCompiler：C# 语言编译器 - C# → VML (see COMPLETION_DASHBOARD.md for actual completion)
• CppCompiler：C++ 语言编译器 - C++ → VML (see COMPLETION_DASHBOARD.md for actual completion，class/继承/vtable/运算符重载/模板/RAII/Lambda/智能指针/异常)
• VMLRuntime：C# 虚拟机运行时 - 执行 VML 字节码
• VMLRuntimeC：C 跨平台运行时 - Unix/macOS/Linux 可运行
• VMLPackerC：VML 打包工具
  • vmlpacker: VML → VMB (汇编到二进制)
  • vmlexe: VMB → 独立可执行文件
• Emulators/：运行环境
  • FullDevicesEmulator：全设备模拟器
  • ConsoleEmulator：控制台模拟器

VML 架构（统一 IR）

• 指令集：90+ 指令(LOAD/STORE、算术、逻辑、跳转、调用、三操作数 ADDS/SUBS/MULS、可变移位 SHLV/SHRV、架构内联 CHIPASM)
• 寄存器：R0-R15（R0=累加器，R13=SP，R14=BP，R15=RA）
• 内存布局：代码段（0x0000）、数据段、栈（向下增长）
• 类型系统：支持完整的 C99 类型，包括指针
• 指针算术：类型感知的偏移计算（char* 为 1 字节，int* 为 4 字节）
• 伪指令：.entry（起始地址）、.stack（栈顶）、.vectors（中断表）

重要约定

1. 栈方向：数组在栈上向下增长（arr[i] 使用 base - i*4）
2. 内存映射：使用特定地址的内存映射 I/O
3. 入口点：.entry 伪指令定义程序开始
4. 中文支持：编译器支持中文标识符和输出
5. 调用约定：C/C++ 支持三种调用约定（详见 CALLING_CONVENTIONS.md）
   • __cdecl（默认）：参数从右到左压栈，调用者清理栈。同时保存到 R1~R3
   • __stdcall：参数从左到右压栈，被调用者清理栈（epilogue 清理）
   • __fastcall：前 4 参数 R0~R3 从左到右，剩余参数从右到左压栈，调用者清理栈参数
6. 库链接：使用 -L 参数链接库文件，-I 用于包含路径

开发工作流

1. 始终使用 ConsoleEmulator 测试
2. 检查 合规性 - 使用 test_c99.c 作为参考
3. 在对 CCompiler 进行重大更改后运行 build_test.bat
4. 按照 Keep a Changelog 格式更新 CHANGELOG.md
5. 测试发布构建 - 使用 MakeRelease 脚本验证完整工具链功能
6. 验证跨平台兼容性 - 尽可能在 Windows、macOS 和 Linux 上测试

编译流程

C/BASIC/Pascal/Ladder/Python/Forth/Lua/Rust/Go/C#/Java/JavaScript/Swift/C++ 源文件 → 相应编译器 → VML 汇编 → VMLAssembler → VML 二进制
                                                              ↓
                                                      VMRuntime (执行)
                                                              ↓
                                                       VMLTranslators (6502/Z80/8051/ARM-CM/X86)