# VML **Repository Path**: aleckstygit/vml ## Basic Information - **Project Name**: VML - **Description**: VML是一个虚拟汇编语言中间层,前端多种语言,后端多种单片机,还可以独立打包,都可以转译!所以几乎可以在任何平台运行 (后端可能需要设备汇编工具链支持)。 - **Primary Language**: C# - **License**: Not specified - **Default Branch**: master - **Homepage**: https://tansuoyz.com/vml/ - **GVP Project**: No ## Statistics - **Stars**: 14 - **Forks**: 0 - **Created**: 2026-04-08 - **Last Updated**: 2026-11-21 ## Categories & Tags **Categories**: scripting-language **Tags**: VML ## README ![alt text](images/logo.png) # VML 工具链 > **当前版本: v1.66.536** | 🔧 36 个项目 · 0 错误 0 警告 · 全量测试 4642/4642 | **28/28 语言** | **24/24 后端** | **网页(解释/AOT·WebGL2 3D·下位机)** | **桌面三平台(Windows/macOS/Linux·SDL2+OpenGL)** | **ESP32 / ESP-Mosaico / 微雪 S3-LCD-1.47** | **M5Stack Cardputer Zero(aarch64 Linux)** | **小喵掌机(ESP32+ST7735)** | **STM32 / GBA / NDS / 3DS** | **64 位 QEMU(LA64/MIPS64/PPC64LE/s390x)** | **ISA v1.12 / SYSCALL v2.7** > > [更新日志](CHANGELOG.md) | [开发者指南](AGENTS.md) | [完成度仪表板](COMPLETION_DASHBOARD.md) | [交接文档](docs/HANDOVER.md) | [文档目录](docs/) ## 项目简介 VML(Virtual Machine Language)是一种虚拟机汇编语言,本项目实现了一个完整的"多前端 + 统一 IR + 多后端"编译器工具链。 ### 核心组件 - **28 语言编译器** → VML 汇编 (全部 🟢 生产可用) - **24 后端翻译器** → 目标架构汇编 (6502/Z80/8051/AVR/PIC/MSP430/PIC24/ARM-CM/ARM32/ARM64/Xtensa/x86/MIPS/MIPS64EL/RISC-V/68000/PowerPC/PowerPC64LE/LoongArch64/s390x/SPARC/JVM/.NET/Wasm) - **VML 汇编器** — VML 文本 ↔ VMB 二进制 - **C# 运行时** — 完整 CPU 模拟 + MMIO + 50+ SYSCALL - **C 跨平台运行时** — vmlrun, 107/107 opcodes + VMB v2 / v2.2(WayCoder 互通)+ 64位完整支持 + 自加载 EXE - **EXE 打包** — VML → VMB → 独立可执行文件 (vmlrun + VMB 尾部追加) - **控制台/VGA 全设备模拟器** — 运行和调试 VML 程序 - **多平台宿主** — 网页(解释/转译/设备端下位机)、桌面(Windows/macOS/Linux)、ESP32/ESP-Mosaico、微雪 ESP32-S3-LCD-1.47、**M5Stack Cardputer Zero(树莓派 Zero 级,AOT/解释器/设备包三形态)**、小喵掌机、STM32、GBA/NDS/3DS、64 位 QEMU 裸机(见[目标平台](#目标平台)) - **全语言测试** — `test_start_all.ps1` 一键测试 28 语言编译运行 ### 🆕 v1.66.528–532 新特性 **新增 4 个 64 位平台后端(v1.66.528)** - **LoongArch64 / MIPS64EL / PowerPC64LE / s390x**,后端 20 → 24;共享基类 `Translator64bit` - 四平台均提供 QEMU 裸机一键脚本,并与本机 C 直跑做逐字节差分 (`bash Scripts/qemu/run_diff.sh `,4/4 PASS) - 接入细节见 [64 位 QEMU 裸机接入](docs/QEMU_INTEGRATION.md) **ESP32-S3 下位机 + Web 设备端(v1.66.529–532)** - **微雪 ESP32-S3-LCD-1.47** 移植:1945 Xtensa 直译 ≈28 fps,1945/2048/五子棋/马里奥全部跑通 - 三种固件形态:`device`(解释器 + TF 卡 / WiFi 网页上传 / VDL TCP 传输,动态 load VMB)、 `interp-pack`(打包 VMB 的单程序固件)、`native`(Xtensa 直译机器码) - **Web 端同时是下位机**:`/device/ping|put|run|state` HTTP 契约 + TCP 二进制 VDL(7878), `device.html` 设备页(文件列表、runId 变化自动运行、`viewer` 在线判定) - 与 **WayCoder 上位机互通**:VMB v2.2(`tag 0x05` 间接读写)、手机推送 2.87 MB 的 1945 产物,浏览器 **237 fps 满屏**(`nonblack=32915` 与本机编译一致) - 设备页嵌入模式全屏 + 顶部锚点校验;配套 `tools/e2e_device.js`、`probe_frame.js`、`shot_device.js` ### 28 种语言编译器 | 语言(源文件) | 状态 | 编译器 | 标准库 | 方言 | |------|:----:|--------|:------:|------| | C (C99) — `.c` | 🟢 生产可用 | CCompiler | Lib/c/ (34 文件) + SQLite | — | | BASIC — `.bas` | 🟢 生产可用 | BasicCompiler | Lib/basic/ | 10 方言 (QBasic/TurboBasic/FreeBasic/TrueBasic/PureBasic/ChipBasic/MiniBasic/GW-BASIC/PowerBASIC/VisualBasic) | | Pascal — `.pas` | 🟢 生产可用 | PascalCompiler | Lib/pascal/ | 6 方言 (Turbo Pascal/Delphi/FreePascal/ISO/UCSD/Oberon) | | Python — `.py` | 🟢 生产可用 | PythonCompiler | Lib/python/ | — | | Lua — `.lua` | 🟢 生产可用 | LuaCompiler | Lib/lua/ | — | | Forth — `.fth` | 🟢 生产可用 | ForthCompiler | Lib/forth/ | — | | Rust — `.rs` | 🟢 生产可用 | RustCompiler | Lib/rust/ | — | | Go — `.go` | 🟢 生产可用 | GoCompiler | Lib/go/ | — | | Ladder — `.ld` | 🟢 生产可用 | LadderCompiler | Lib/ladder/ | — | | C# — `.cs` | 🟢 生产可用 | CSharpCompiler | Lib/csharp/ | — | | Java — `.java` | 🟢 生产可用 | JavaCompiler | Lib/java/ | — | | JavaScript — `.js` | 🟢 生产可用 | JavaScriptCompiler | Lib/javascript/ | — | | TypeScript — `.ts` | 🟢 生产可用 | TypeScriptCompiler(类型擦除 → JS 后端) | Lib/typescript/ | — | | Swift — `.swift` | 🟢 生产可用 | SwiftCompiler | Lib/swift/ | — | | C++98 — `.cpp` | 🟢 生产可用 | CppCompiler | Lib/cpp/ | — | | Kotlin — `.kt` | 🟢 生产可用 | KotlinCompiler | Lib/kotlin/ | — | | Scheme — `.scm` | 🟢 生产可用 | SchemeCompiler | Lib/scheme/ | — | | Ruby — `.rb` | 🟢 生产可用 | RubyCompiler | Lib/ruby/ | — | | Dart — `.dart` | 🟢 生产可用 | DartCompiler | Lib/dart/ | — | | ObjC — `.m` | 🟢 生产可用 | ObjCCompiler | Lib/objc/ | — | | R — `.r` | 🟢 生产可用 | RCompiler | Lib/r/ | — | | D — `.d` | 🟢 生产可用 | DCompiler | Lib/d/ | — | | Fortran — `.f90` | 🟢 生产可用 | FortranCompiler | Lib/fortran/ | — | | Ada — `.adb` / `.ads` / `.ada` | 🟢 生产可用 | AdaCompiler | Lib/ada/ | — | | COBOL — `.cob` / `.cbl` | 🟢 生产可用 | CobolCompiler | Lib/cobol/ | — | | dBase — `.prg` | 🟢 生产可用 | DBaseCompiler | Lib/dbase/ | — | | Perl — `.pl` / `.pm` | 🟢 生产可用 | PerlCompiler | Lib/perl/ | — | | PHP — `.php` | 🟢 生产可用 | PhpCompiler | Lib/php/ | — | > **全部 28/28 🟢 生产可用** | 预处理: 21/28 | CLI -D/-U: 21/28 | 每语言 35+ 个 .vml 库文件 > > **方言系统**: BASIC 10 方言 + Pascal 6 方言,全部 ≥90% 完成度。通过 `--basictype` / `--pascaltype` CLI 选项切换,每方言自动注入预定义宏 (`__QBASIC__` / `__FREEBASIC__` / `__TURBOPASCAL__` 等)。详见 [BASIC 方言规范](VMLPrepares/BasicCompiler/BASIC_LANGUAGE_SPEC.md) / [Pascal 关键字清单](VMLPrepares/PascalCompiler/ALL_KEYWORDS.md)。 ### 方言系统 VML 的 BASIC 和 Pascal 编译器支持多种历史方言,通过 CLI 选项切换: **BASIC — 10 方言** (`--basictype`) | 方言 | 宏定义 | 完成度 | 关键字 | 特色 | |------|--------|:------:|:------:|------| | **QBasic** (默认) | `__QBASIC__` | 92% | ~70 | 图形/游戏 (GORILLAS/NIBBLES) | | **TurboBasic** | `__TURBOBASIC__` | 90% | ~68 | 结构化编程 (DO/LOOP/FUNCTION) | | **FreeBasic** | `__FREEBASIC__` | 90% | ~76 | CLASS/OOP/ENUM/PTR/CAST | | **TrueBasic** | `__TRUEBASIC__` | 90% | ~62 | ANSI/ISO 标准, MAT/ZER/CON | | **PureBasic** | `__PUREBASIC__` | 90% | ~68 | PROCEDURE/INTERFACE/NEW | | **ChipBasic** | `__CHIPBASIC__` | 90% | ~57 | MCU GPIO (PINMODE/DIGITALWRITE/DIGITALREAD) | | **MiniBasic** | `__MINIBASIC__` | 90% | ~15 | 教学最小子集 | | **GW-BASIC** | `__GWBASIC__` | 90% | ~70 | BLOAD/BSAVE/DEF FN/行号 | | **PowerBASIC** | `__POWERBASIC__` | 90% | ~70 | REGISTER/FASTPROC/THREADED | | **VisualBasic** | `__VISUALBASIC__` | 90% | ~75 | Private/Public/With/Optional/ParamArray | > **99 关键字清单**, 81 已实现 (82%) · CLASS/CONSTRUCTOR/METHOD 代码生成完成 (Phase 1+2) · ENUM 值代入 · GPIO 跨平台运行时库 **Pascal — 6 方言** (`--pascaltype`) | 方言 | 宏定义 | 完成度 | 语句数 | 特色 | |------|--------|:------:|:------:|------| | **Turbo Pascal** (默认) | `__TURBOPASCAL__` | 92% | 72/78 | object 旧式OOP/absolute/asm | | **Delphi** | `__DELPHI__` | 90% | 85/95 | class/constructor/property/try/for-in | | **FreePascal** | `__FREEPASCAL__` | 92% | 87/95 | 最完整, overload/default参数 | | **ISO Pascal** | `__ISOPASCAL__` | 92% | 48/52 | ANSI 标准最小子集 | | **UCSD Pascal** | `__UCSDPASCAL__` | 93% | 50/54 | unit/uses 模块系统 | | **Oberon** | `__OBERON__` | 91% | 42/46 | MODULE/IMPORT (Wirth 系) | > **105 代码生成目标**, 87 已实现 (83%) · class/constructor/destructor · for/in 枚举语法 · record/set/file · Crt 单元 ```bash # 使用示例 vmltool input.bas --basictype freebasic -o output.vml # FreeBasic 方言 vmltool input.pas --pascaltype delphi -o output.vml # Delphi 方言 ``` ### 24 个后端翻译器 | 架构 | 字长 | 目标平台 | |------|:----:|---------| | 6502 | 8位 | Apple II / C64 / NES | | Z80 | 8位 | CP/M / ZX Spectrum | | 8051 | 8位 | STC / AT89 系列 | | AVR | 8位 | Arduino / ATmega | | PIC | 8位 | Microchip MCU | | MSP430 | 16位 | TI 低功耗 MCU | | PIC24 | 16位 | Microchip 16位 | | ARM Cortex-M | 32位 | STM32 / ESP32 等嵌入式 | | ARM32 | 32位 | ARMv7 嵌入式 / 树莓派 | | ARM64 | 64位 | Apple Silicon / 服务器 | | Xtensa | 32位 | ESP32(小喵掌机) | | x86 | 32/64位 | 通用 PC | | MIPS | 32位 | 网络设备 / 教学 | | RISC-V | 32位 | 开源 CPU | | SPARC | 32位 | 工作站 | | PowerPC | 32位 | 嵌入式 / 游戏机 | | PowerPC64LE | 64位 | Power8 / 服务器(QEMU pseries) | | LoongArch64 | 64位 | 龙芯 3A / LA464(QEMU virt) | | MIPS64EL | 64位 | 龙芯 / MIPS64R2(QEMU loongson3-virt) | | s390x | 64位 | IBM Z(QEMU s390-ccw-virtio) | | 68000 | 32位 | 复古计算 | | JVM | 32位 | Java 平台 | | .NET | 32位 | CLR 平台 | | Wasm | 32位 | Web 浏览器(解释 / AOT) | ## 目标平台 同一份源码经「前端 → VML → 汇编/翻译」后,可以运行在下列平台;UI、输入、文件与 外设语义由同一份 C 运行时(VMLRuntimeC)提供,因此**换平台不改源码**。 | 平台 | 执行方式 | 图形能力 | 一键脚本 / 产物 | |------|----------|----------|------------------| | 网页 Web | 解释(VMB + wasm)/ 转译(VML → wasm 机器码 + Worker)/ **设备端下位机** | Canvas 2D 矢量 + **WebGL2 真 3D** | `run_vml_on_web.sh` → `web/vml-web/dist/`;设备端 `device.html` + `tools/serve.py`(HTTP/VDL) | | 桌面 Windows | 解释 / 转译 | SDL2 矢量 + OpenGL 真 3D | `run_vml_on_desktop.sh --platform win` → `dist/win/<名>/` | | 桌面 macOS | 解释 / 转译 | 同上 | `--platform macos` → `dist/macos/<名>/VMLGame.app` | | 桌面 Linux | 解释 / 转译 | 同上 | `--platform linux` → `dist/linux/<名>/`(`run.sh`) | | ESP32 / ESP-Mosaico | 解释(VMB)/ AOT(`-t riscv-host`) | 板载 480×480 屏、触摸、IMU、音频 | `run_vml_on_mosaico.sh` → `vml_mosaico.bin` | | 微雪 ESP32-S3-LCD-1.47 | 解释 / Xtensa 直译(`device` / `interp-pack` / `native` 三形态) | 板载 LCD、WiFi 传输、TF 卡 | `run_vml_on_s3lcd147.sh`(Windows 用 `.ps1`)→ 固件 + 烧录 | | M5Stack Cardputer Zero | 解释 / **真 ARM64 AOT** / 设备包(HTTP+VDL) | ST7789v3 320×170、TCA8418 46 键、fbdev+evdev | `run_vml_on_cardputer_zero.sh`(另见 [docs/CARDPUTER_ZERO.md](docs/CARDPUTER_ZERO.md)) | | 小喵掌机 | 解释 / AOT(Xtensa 直译)/ **运行时(TF+WiFi+动态加载)** | ST7735 160×128、5×7 字库、蜂鸣器 | `run_vml_on_xiaomiao.sh --mode runtime` → 固件 + 烧录(见 [docs/XIAOMIAO_RUNTIME.md](docs/XIAOMIAO_RUNTIME.md)) | | STM32F429I-DISCOVERY | 解释 / ARM-CM 直译 | LTDC 240×320 + STMPE811 触摸 | `run_vml_on_stm32f429.sh` → `app.bin` | | GBA / NDS·DSi / 3DS | ARM 直译 | 原生帧缓冲 | `run_vml_on_gba.sh` / `run_vml_on_nds.sh` / `run_vml_on_3ds.sh` | | QEMU RISC-V(裸机) | 解释 / AOT | UART / 帧缓冲 | `run_vml_on_qemu_riscv.sh`(见 docs/BENCH_OPS.md) | ### 通用前置(所有平台) | 依赖 | 用途 | macOS | Ubuntu / Debian | |------|------|-------|-----------------| | .NET SDK **10.0** | 构建全部前端/后端/VMLTool | `brew install --cask dotnet-sdk` | 按 安装 | | Git | 获取源码 | `xcode-select --install` | `sudo apt install git` | | C 编译器 | 构建运行时/宿主 | `xcode-select --install` | `sudo apt install build-essential` | 首次构建: ```bash dotnet build VMLToolchain.sln # 0 错误 0 警告 bash gen_all_vml.sh # 重建 Lib/**/*.vml(共享库 + 语言包装器) ``` > 下面每个平台都给出:**依赖 → 一键脚本 → 1945 实例**。示例源码位于 > `Examples/ESP32/Mosaico/mobile_apps_cpp/1945.cpp`(C++,28 种语言均可)。 --- ### 一、网页 Web(解释 + 转译两种模式) #### 依赖 | 依赖 | 用于 | macOS | Ubuntu / Debian | |------|------|-------|-----------------| | clang(wasm32)+ wasm-ld | 编译 C 运行时为 wasm | `xcode-select --install`;若 Apple clang 无 wasm32:`brew install llvm lld` | `sudo apt install clang lld` | | wabt(`wat2wasm`) | **仅转译模式**:WAT → wasm | `brew install wabt` | `sudo apt install wabt` | | Node.js 20+(可选) | 无头自检 `--check`、构建工具 | `brew install node` | `sudo apt install nodejs npm` | | Python 3 | 本地静态服务器(自带 COOP/COEP) | 系统自带 | `sudo apt install python3` | #### 编译与运行 ```bash # 解释执行:源码 → VMB → 浏览器里的 C 运行时(wasm) bash Scripts/run_vml_on_web.sh <源码> --mode interp # 转译执行:VML → wasm 机器码 + AOT glue(Worker + SharedArrayBuffer) bash Scripts/run_vml_on_web.sh <源码> --mode aot # 只构建 / 自定义输出 / 无头检查 60 帧 bash Scripts/run_vml_on_web.sh <源码> --mode aot --build-only --out /tmp/web1945 bash Scripts/run_vml_on_web.sh <源码> --mode aot --check 60 ``` 产物在 `web/vml-web/dist/`(或 `--out` 指定目录):`index.html`、`vml_web.js`、 解释模式的 `vml_web.wasm + game.vmb`,或转译模式的 `program.wasm + glue.wasm + vml_aot_worker.js`。脚本会启动本地服务,浏览器打开提示的地址即可(默认 8000)。 #### 示例:编译 1945 ```bash # 1) 安装依赖(macOS) xcode-select --install brew install wabt node # 2) 解释版:构建并打开浏览器 bash Scripts/run_vml_on_web.sh Examples/ESP32/Mosaico/mobile_apps_cpp/1945.cpp --mode interp # 3) 转译版(另开目录,避免覆盖解释版产物) bash Scripts/run_vml_on_web.sh Examples/ESP32/Mosaico/mobile_apps_cpp/1945.cpp \ --mode aot --out /tmp/web1945_aot --check 60 # 期望最后一行:{"result":"frames","frames":60,"nonblack":32915,...} ``` > 3D 示例:`solar3d.c` 用 `--mode aot` 时由 WebGL2 渲染;URL 加 `?nogpu3d` > 可强制回退软件光栅做对照。 --- ### 二、桌面 Windows / macOS / Linux #### 依赖 | 构建机 → 目标 | 工具链 / 库 | 安装 | |---------------|-------------|------| | macOS → macOS | Xcode CLT、SDL2、SDL2_ttf | `xcode-select --install`;`brew install sdl2 sdl2_ttf` | | macOS / Linux → Windows(交叉) | mingw-w64 | macOS:`brew install mingw-w64`;Ubuntu:`sudo apt install gcc-mingw-w64` | | Linux → Linux | gcc、pkg-config、SDL2/SDL2_ttf 开发包 | `sudo apt install build-essential pkg-config libsdl2-dev libsdl2-ttf-dev` | | Windows(MSYS2) | mingw-w64 gcc + SDL2 | `pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-SDL2 mingw-w64-x86_64-SDL2_ttf` | > Windows 目标首次构建时,`build_sdl_player.sh` 会自动下载 SDL2 MinGW 开发包 > (缓存在 `~/.cache/vml/sdl2-mingw`),无需手工安装。macOS/Linux 产物必须在 > 对应系统上构建;Windows 产物可在 macOS/Linux 上交叉构建。 #### 编译与打包 ```bash # macOS:本机窗口 + .app 打包 bash Scripts/run_vml_on_desktop.sh <源码> --platform macos [--check 120] # Windows:单目录产物(exe + game.vmb + README),可交叉构建 bash Scripts/run_vml_on_desktop.sh <源码> --platform win --arch 64 # Linux:目录(vmlgame + game.vmb + 内嵌 libSDL2 + run.sh) bash Scripts/run_vml_on_desktop.sh <源码> --platform linux ``` | 目标 | 产物 | 运行 | |------|------|------| | macOS | `dist/macos/<名>/VMLGame.app` | 双击(或 `open`) | | Windows | `dist/win/<名>/`:`vmlgame.exe`(静态链接 SDL2)+ `game.vmb` + `README.txt` | 整个目录拷到 Win11,双击 exe | | Linux | `dist/linux/<名>/`:`vmlgame` + `game.vmb` + `libSDL2-2.0.so.0` + `run.sh` | `./run.sh` | #### 示例:编译 1945 ```bash # macOS:安装依赖 → 构建 → 启动 brew install sdl2 sdl2_ttf bash Scripts/run_vml_on_desktop.sh Examples/ESP32/Mosaico/mobile_apps_cpp/1945.cpp \ --platform macos --check 60 open dist/macos/1945/VMLGame.app # Windows(在 macOS/Linux 上交叉构建) brew install mingw-w64 # Ubuntu: sudo apt install gcc-mingw-w64 bash Scripts/run_vml_on_desktop.sh Examples/ESP32/Mosaico/mobile_apps_cpp/1945.cpp \ --platform win --arch 64 # 产物:dist/win/1945/,把整个目录拷到 Windows,双击 vmlgame.exe ``` > 桌面宿主与手机/网页共用 `vml_ui` / `vml_mosaic` / `vml_3d`:2D 走矢量几何, > 3D 走 OpenGL;`--headless` 走软件光栅,保证差分与冒烟口径不变。 > 差分自测:`bash Scripts/sdl_diff_selftest.sh`(11/11)。 --- ### 三、ESP32 / ESP-Mosaico(真机固件) #### 依赖 | 依赖 | 说明 | 获取 | |------|------|------| | ESP-IDF **6.1+**(支持 ESP32-S31) | 提供 `idf.py`、`riscv32-esp-elf-gcc`、esptool | 克隆 ESP-IDF 后执行 `./install.sh`;用 `MOSAICO_IDF_PATH` 指向它 | | raylib-lite-engine | 官方 Board 组件(LCD/触摸/BSP) | 用 `MOSAICO_ENGINE` 指向引擎仓库根目录 | | USB 串口驱动 | CP210x/CH34x 等 | 按开发板说明安装 | ```bash # 典型环境准备(路径按实际调整) git clone --recursive https://github.com/espressif/esp-idf.git ~/esp/esp-idf-s31 cd ~/esp/esp-idf-s31 && ./install.sh && . ./export.sh export MOSAICO_IDF_PATH=~/esp/esp-idf-s31 export MOSAICO_ENGINE=~/mospico-src/raylib-lite-engine-main ``` #### 编译 / 烧录 ```bash # AOT(默认):VML → riscv-host 直译 → riscv32 gcc → 固件 bash Scripts/run_vml_on_mosaico.sh <源码> # 解释执行:VMB 嵌入固件,VMLRuntimeC 逐条执行 bash Scripts/run_vml_on_mosaico.sh <源码> --mode interp # 只构建 / 不烧录 / 烧录后抓串口 / 指定串口 bash Scripts/run_vml_on_mosaico.sh <源码> --build-only bash Scripts/run_vml_on_mosaico.sh <源码> --no-flash bash Scripts/run_vml_on_mosaico.sh <源码> --monitor 30 --port /dev/cu.usbmodem* ``` 产物:`Examples/ESP32/Mosaico/firmware/build_aot/vml_mosaico.bin`(或 `build_interp/`);脚本默认构建后直接 `idf.py flash` 并抓串口日志。 #### 示例:编译 1945 ```bash bash Scripts/run_vml_on_mosaico.sh Examples/ESP32/Mosaico/mobile_apps_cpp/1945.cpp --mode aot # 如需先确认能否编译(不接板子): bash Scripts/run_vml_on_mosaico.sh Examples/ESP32/Mosaico/mobile_apps_cpp/1945.cpp \ --mode aot --build-only ``` > 外设覆盖 `#1000–#1459`(显示/触控/音频/IMU/电池/网络等)与 `#2000+` > 原生矩阵/向量计算;与 C# VM、官方 Host 模拟器三端一致。 > 详见 [docs/MOSAICO.md](docs/MOSAICO.md)。 --- ### 四、小喵掌机(ESP32-D0WD + ST7735 160×128) #### 依赖 | 依赖 | 说明 | 获取 | |------|------|------| | ESP-IDF(Xtensa) | `idf.py`、`xtensa-esp-elf-gcc`、esptool | 推荐 **6.1**(`IDF_PATH` 指向它);5.5 需 `./install.sh esp32` | | Python 3 | 串口监视脚本 | 系统自带 | | USB 串口驱动 | 开发板串口 | 按板子说明安装 | ```bash cd ~/esp/esp-idf && ./install.sh esp32 && . ./export.sh ``` #### 编译 / 烧录 ```bash bash Scripts/run_vml_on_xiaomiao.sh <源码> # AOT(默认)+ 烧录 + 串口 bash Scripts/run_vml_on_xiaomiao.sh <源码> --mode interp # 解释执行 bash Scripts/run_vml_on_xiaomiao.sh <源码> --build-only # 只构建 bash Scripts/run_vml_on_xiaomiao.sh <源码> --no-flash # 只构建不烧录 bash Scripts/run_vml_on_xiaomiao.sh <源码> --monitor 30 --port /dev/cu.usbserial-* # 运行时固件(解释器 + TF/WiFi + 动态加载;首次分区表变更需 --erase) bash Scripts/run_vml_on_xiaomiao.sh --mode runtime --erase ``` 产物:`Examples/ESP32/Xiaomiao/build_mac/`(macOS)或 `build/`(Linux)下的 `vml_1945_xiaomiao.bin`;解释模式在 `build_interp/`。串口默认自动查找 `/dev/cu.usbmodem*`,可用 `--port` 指定。 #### 示例:编译 1945 ```bash bash Scripts/run_vml_on_xiaomiao.sh Examples/ESP32/Mosaico/mobile_apps_cpp/1945.cpp # 只验证编译链(不接板子) bash Scripts/run_vml_on_xiaomiao.sh Examples/ESP32/Mosaico/mobile_apps_cpp/1945.cpp --build-only ``` > 同一份 `1945.cpp` 源码零改动:原生编译约 29 fps,VML 解释约 2.5–4.5 fps, > Xtensa 直译约 9.4 fps。逻辑画布 320×256 → 物理 160×128,自带 5×7 小字库, > GPIO14 蜂鸣器 LEDC 音效。 **运行时模式(v1.66.535+,v1.66.536 完善协议)**:固件不含程序;手机经 UDP 7879 发现 → 6 位配对码换令牌 → HTTP `/device/put`(或 VDL TCP 7878) 流式写入 TF 卡(无卡回落内部 Flash)→ 自动运行;`/device/run` 支持 `force` 抢占, `/device/state` 回报 `runId/lastExit`,`/device/options` 控制自动覆盖/自动运行。 掌机端短按 B 重扫、**长按 B 删除**、程序内长按 B 回选单; 设备端还提供 `/device/frame`(PPM 截图)、`/device/key`、`/device/touch` 远程调试接口。 细节见 [docs/XIAOMIAO_RUNTIME.md](docs/XIAOMIAO_RUNTIME.md)。 --- ### 四·五、M5Stack Cardputer Zero(aarch64 Linux) 树莓派 Zero 级掌机(RP3A0/BCM2837、512 MB、ST7789v3 320×170 无触摸、TCA8418 46 键), 跑 Raspberry Pi OS / Debian arm64。三种包 + 宿主模拟器,**同一份 BSP** (`VMLFast/VMLRuntimeC/bsp/cardputer_zero/`),源码零改动。 | 形态 | 命令 | 产物 | |------|------|------| | 宿主模拟器 | `build_cardputer_host.sh` | `build/cardputer/vmlcard`(headless/脚本按键/PPM) | | ① 目标代码 | `run_vml_on_cardputer_zero.sh --mode aot --src <源码> --lima` | 真 AArch64 ELF(ET_EXEC、地址 <4GB、无解释器) | | ② 解释器 + VMB | `--mode interp --vmb game.vmb [--pi cardputer.local]` | `bin/vml-cardputer` + `programs/` + systemd | | ③ 设备包 | `--mode device --pi cardputer.local` | launcher + HTTP `/device/*` 8080 + VDL 7878 | 依赖:**zig**(`brew install zig`,交叉 `aarch64-linux-musl` 静态链接)或 Pi 上的 `aarch64-linux-gnu-gcc`;运行验证用 **Lima**(`Scripts/lima/cardputer.yaml`)。 官方没有 Cardputer Zero 模拟器,社区 QEMU 补丁需要自建 QEMU + 1.8GB 镜像, 本仓库改用「宿主模拟器 + Lima」两级验证——屏幕/键盘最终在真机验收。 ```bash # 宿主 320×170 自检 + 帧转储 bash Scripts/build_cardputer_host.sh build/cardputer/vmlcard --selftest build/cardputer/vmlcard --headless --frames 60 --dump-dir /tmp/cz --dump-every 1 game.vmb # AOT(Lima 里跑真 aarch64 二进制) bash Scripts/build_cardputer_aot.sh Examples/ESP32/Mosaico/mobile_apps/breakout.c \ --out dist/cardputer-zero/aot/breakout limactl start --name=cardputer Scripts/lima/cardputer.yaml bash Scripts/run_vml_on_cardputer_zero.sh --mode aot \ --src Examples/ESP32/Mosaico/mobile_apps/breakout.c --lima --frames 60 # 设备包契约(本机 16 项) bash Scripts/test_cardputer_device.sh ``` 关键约束:VML 调用帧 4 字节 vs AArch64 `sp` 16 字节对齐 → HostMode 用 **x24** 作 VML 栈指针;数据段发完切回 `.text`(否则 NX);`byte[]/short[]` 真实宽度; `-no-pie` 且所有地址 <4GB。细节见 [docs/CARDPUTER_ZERO.md](docs/CARDPUTER_ZERO.md) 与 [docs/AOT_ARM64_LINUX.md](docs/AOT_ARM64_LINUX.md)。 --- ### 五、其他已验证平台(STM32 / GBA / NDS / 3DS / QEMU) | 平台 | 依赖 | 编译 / 运行 | 产物与实测 | |------|------|-------------|------------| | STM32F429I-DISCOVERY | Arm GNU Toolchain(`arm-none-eabi-gcc`)、STM32CubeProgrammer(`STM32_Programmer_CLI`) | `bash Scripts/run_vml_on_stm32f429.sh <源码> --mode interp 或 aot [--flash]`;用 `ARM_TOOLCHAIN` 指定工具链 `bin` 目录 | `build_stm32f429/app.bin` / `app.elf`;1945 ARM-CM 直译约 **34.5 fps**(解释约 3.1 fps) | | GBA(ARM7TDMI) | `arm-none-eabi-gcc`、libmgba(`brew install mgba`)、`sips` | `bash Scripts/run_vml_on_gba.sh <源码> --frames 120 --keep` | `.gba` ROM + 截图;1945 约 0.5 fps(移植链路验证) | | NDS / DSi(ARM946E-S) | `arm-none-eabi-gcc`、`python3`、melonDS 核心(首次自动构建) | `bash Scripts/run_vml_on_nds.sh <源码> [--dsi] --keep` | `.nds` ROM + 主屏截图;DS 3.5 fps / DSi 7.6 fps | | 3DS(ARM11) | `clang`、`python3`、`git`、`brew`(首次自动构建 SDK 与 Azahar 运行器) | `bash Scripts/run_vml_on_3ds.sh <源码> --keep` | `.3dsx` + 上屏截图;1945 约 **34.8 fps**(可玩) | | QEMU RISC-V virt(裸机) | `riscv64-elf-gcc`(或 `riscv64-unknown-elf-gcc`)、`qemu-system-riscv32` | `bash Scripts/run_vml_on_qemu_riscv.sh <源码或.vml> [--fpu] [--direct]` | 裸机 ELF 在 QEMU 运行;整数 AOT 快 1.5–4×,`--fpu` 开硬件浮点 | > 上述脚本均支持 `--help`;板级差异(屏幕尺寸、按键、触摸)在 > `VMLFast/VMLRuntimeC/include/boards/` 与各移植文档中说明。 --- ### 六、64 位服务器 / 指令集裸机(LoongArch64 / MIPS64EL / PowerPC64LE / s390x) 四个后端的共同模型:**内存寄存器文件 + 原生 SP/BP + 4 字节 VML 调用帧**, SYSCALL 由翻译器 footer 自带(不依赖 BIOS/FDT),另提供 bump 分配器与控制台回读。 | 平台 | 工具链依赖 | QEMU 机器 / 启动方式 | 运行脚本 | |------|------------|----------------------|----------| | LoongArch64(LA464) | Homebrew `llvm`(clang 23,支持 `loongarch64`)、`lld`、`qemu-system-loongarch64` | `-M virt -cpu la464`,`-kernel` 直接启动 ELF;控制台 ns16550(`0x1fe001e0`) | `bash Scripts/run_vml_on_qemu_loongarch64.sh <源码或.vml>` | | MIPS64EL(MIPS64R2) | 同上(clang 支持 `mips64el`)、`qemu-system-mips64el` | `-M loongson3-virt -cpu Loongson-3A4000 -m 512M`;代码链接在 KSEG0 `0xffffffff80200000` | `bash Scripts/run_vml_on_qemu_mips64el.sh <源码或.vml>` | | PowerPC64LE(Power8) | 同上(clang 支持 `ppc64le`)、`qemu-system-ppc64`、`python3` | `-M pseries`,`-S` 停复位 + gdbstub 置 PC/MSR[SF,LE](SLOF 不直启裸机 ELF) | `bash Scripts/run_vml_on_qemu_ppc64le.sh <源码或.vml>` | | s390x(z196) | 同上(clang 支持 `systemz`)、`qemu-system-s390x`、`python3` | `-M s390-ccw-virtio -cpu max`,`-kernel` 直接启动 ELF | `bash Scripts/run_vml_on_qemu_s390x.sh <源码或.vml>` | 安装/编译与 1945 示例: ```bash # 依赖(macOS) brew install llvm lld qemu # 以 LoongArch64 为例:源码 → VML → LA64 汇编 → 裸机 ELF → QEMU bash Scripts/run_vml_on_qemu_loongarch64.sh Examples/c/hello.c --timeout 15 # 带计算/差分语义的探针(整数/64 位/双精度/指针/分配器) bash Scripts/run_vml_on_qemu_loongarch64.sh Scripts/qemu/diff_probe.c --timeout 20 # 四平台差分(本机 cc 直跑 vs VML→QEMU 逐字节比对) bash Scripts/qemu/run_diff.sh loongarch64 bash Scripts/qemu/run_diff.sh mips64el bash Scripts/qemu/run_diff.sh ppc64le bash Scripts/qemu/run_diff.sh s390x ``` 输出与控制台回读: - LoongArch64 / MIPS64EL:ns16550 UART 直接输出到终端(`-nographic`)。 - PowerPC64LE / s390x:无控制台;footer 把 `puts/putc` 写进环形缓冲 (PPC:`0x01002000` 小端字数 + `0x01002004` 数据;s390x:同址但**大端**字数), 运行脚本经 QMP 回读并打印。 - 退出标志:四平台均写 `VMLD` 到完成地址(LA64/MIPS `0x01001000` 虚拟物理、 PPC `0x01001000`、s390x `0x00101000`,见 `docs/QEMU_INTEGRATION.md`)。 限制:目前的 QEMU 运行路径只验证**计算/控制流/字符串/分配器**; 矢量 UI(`vml_ui`)与 3D(`vml_3d`)需要平台帧缓冲宿主,尚未接到这四个后端。 ## 支持的文件格式(能力矩阵) > 列含义:**编辑**=IDE 内语法高亮编辑;**编译**=`vmltool`/IDE 有对应前端;**运行**=编译为 VML/VMB 后由模拟器执行; > **预览**=IDE 内可视化预览;**播放**=媒体文件播放;**其他**=补充说明。✅=支持,❌=不支持。 | 文件类型 | 扩展名 | 支持编辑 | 支持编译 | 支持运行 | 支持预览 | 支持播放 | 支持其他 | |----------|--------|:--------:|:--------:|:--------:|:--------:|:--------:|----------| | C | `.c` / `.h` | ✅ | ✅ | ✅ | ❌ | ❌ | `.h` 为头文件 | | BASIC | `.bas` | ✅ | ✅ | ✅ | ❌ | ❌ | 10 方言(`--basictype`) | | Pascal | `.pas` | ✅ | ✅ | ✅ | ❌ | ❌ | 6 方言(`--pascaltype`) | | Python | `.py` | ✅ | ✅ | ✅ | ❌ | ❌ | — | | Lua | `.lua` | ✅ | ✅ | ✅ | ❌ | ❌ | — | | Forth | `.fth` | ✅ | ✅ | ✅ | ❌ | ❌ | — | | Rust | `.rs` | ✅ | ✅ | ✅ | ❌ | ❌ | — | | Go | `.go` | ✅ | ✅ | ✅ | ❌ | ❌ | — | | Ladder | `.ld` | ✅ | ✅ | ✅ | ❌ | ❌ | — | | C# | `.cs` | ✅ | ✅ | ✅ | ❌ | ❌ | — | | Java | `.java` | ✅ | ✅ | ✅ | ❌ | ❌ | — | | JavaScript | `.js` | ✅ | ✅ | ✅ | ❌ | ❌ | — | | TypeScript | `.ts` | ✅ | ✅ | ✅ | ❌ | ❌ | 类型擦除后走 JS 后端;参数属性/`#private`/`for...in`/全运算符;`?.`/`??`/namespace 报错 | | Swift | `.swift` | ✅ | ✅ | ✅ | ❌ | ❌ | — | | C++ | `.cpp`(`.hpp`/`.cc`/`.cxx`) | ✅ | ✅ | ✅ | ❌ | ❌ | C++98 子集 | | Kotlin | `.kt`(`.kts`) | ✅ | ✅ | ✅ | ❌ | ❌ | — | | Scheme | `.scm`(`.ss`/`.sls`) | ✅ | ✅ | ✅ | ❌ | ❌ | — | | Ruby | `.rb` | ✅ | ✅ | ✅ | ❌ | ❌ | — | | Dart | `.dart` | ✅ | ✅ | ✅ | ❌ | ❌ | — | | ObjC | `.m` | ✅ | ✅ | ✅ | ❌ | ❌ | — | | R | `.r`(`.R`) | ✅ | ✅ | ✅ | ❌ | ❌ | — | | D | `.d` | ✅ | ✅ | ✅ | ❌ | ❌ | — | | Fortran | `.f90`(`.f`/`.f95`/`.for`) | ✅ | ✅ | ✅ | ❌ | ❌ | — | | Ada | `.adb` / `.ads` / `.ada` | ✅ | ✅ | ✅ | ❌ | ❌ | — | | COBOL | `.cob` / `.cbl` | ✅ | ✅ | ✅ | ❌ | ❌ | 固定格式 | | dBase | `.prg` | ✅ | ✅ | ✅ | ❌ | ❌ | — | | Perl | `.pl` / `.pm` | ✅ | ✅ | ✅ | ❌ | ❌ | — | | PHP | `.php` | ✅ | ✅ | ✅ | ❌ | ❌ | — | | VML 文本汇编 | `.vml` | ✅ | ✅ | ✅ | ❌ | ❌ | 编译=翻译到 18 后端;可汇编为 `.vmb` | | VML 二进制 | `.vmb` | ❌ | ❌ | ✅ | ❌ | ❌ | 汇编器产物 | | 目标架构汇编 | `.s` / `.asm` / `.avr` / `.pic` / `.i51` / `.a51` / `.6502` / `.z80` / `.arm` / `.x86` / `.mips` / `.riscv` / `.m68k` / `.ppc` / `.sparc` / `.msp430` / `.pic24` / `.jasm` / `.il` / `.wat` / `.wasm` | ✅ | ❌ | ❌ | ❌ | ❌ | 后端产物,可交 `VMLToHex` 烧录 | | 烧录 / 可执行产物 | `.hex` / `.bin` / `.com` / `.s19` / `.elf` / `.exe` / `.bat` | ❌ | ✅ | ❌ | ❌ | ❌ | `vmltool -f` 生成;用于烧录/部署 | | 项目文件 | `.vmlproj` | ✅ | ❌ | ❌ | ❌ | ❌ | IDE 项目(文件树/保存) | | 截图 | `.bmp` | ❌ | ❌ | ❌ | ❌ | ❌ | 模拟器**导出** 320×200 24-bit BMP(`--screenshot`) | | 录音 | `.wav` | ❌ | ❌ | ❌ | ❌ | ❌ | 模拟器**仅录制** 44100Hz 16-bit mono PCM(`--record-audio`) | | 音频(播放) | `.wav` / `.mp3` / `.flac` / `.ogg` | ❌ | ❌ | ❌ | ❌ | ❌ | **不支持播放**:无媒体解码/播放通路 | | 视频(播放) | `.mp4` / `.avi` / `.mkv` / `.mov` | ❌ | ❌ | ❌ | ❌ | ❌ | **不支持播放** | | 图片(预览) | `.png` / `.jpg` / `.gif` / `.bmp` | ❌ | ❌ | ❌ | ❌ | ❌ | IDE 暂无图片预览 | > 说明:声音只有 PC 扬声器的**实时蜂鸣**(`Console.Beep`,`speaker` 设备),不是媒体文件播放。 > 如需让 VML 程序"播放"音频,只能自行编写驱动扬声器的 VML 代码;模拟器不解析外部音视频文件。 ## 快速使用 ```bash # 编译(自动根据扩展名识别语言) vmltool input.c -o program.vml # C → VML vmltool input.py -o program.vml # Python → VML vmltool input.java -o program.vml # Java → VML # 编译 + 链接共享库 vmltool input.c -o program.vml -l parserexp -L Lib/shared # 运行 vmltool -r program.vml # VML → HEX 烧录 vmltool -c program.vml -o firmware.hex -t arm-cm # 构建: 0 错误 0 警告 dotnet build VMLToolchain.sln # Shell 自动补全 source Scripts/vmltool-completion.bash # Bash . Scripts/vmltool-completion.ps1 # PowerShell ``` ## MCU/OS 双模式 + 字符串编码 | 模式 | 默认编码 | 字符串类型 | 输出 SYSCALL | |:-----|:--------|:----------|:------------| | MCU (默认) | UTF-8 | `.string` | #1 | | OS | UTF-16LE | `.wstring` | #391 | **三层字符串**: `.string`(8-bit char*) / `.wstring`(16-bit wchar_t*) / `.ustring`(32-bit char32_t*) **语言适配**: Java/C#/JS/Kotlin/Swift/Python/Go 在 OS 模式自动使用 `.wstring`,MCU 模式退化为 `.string` **预定义宏**: `VML_WSTRING` — OS 模式自动 `#define VML_WSTRING 1` ## 共享库 ``` Lib/shared/ — 跨语言通用库 (每语言 Lib// 含相同副本) 字符串: string wstring ustring (三层字符串操作) 字符: ctype wchar uchar (字符分类+转换) 格式化: printf wprintf uprintf (格式化输出) 输入: scanf wscanf uscanf (格式化输入) 输出: io printx (I/O + 全类型打印) 表达式: parserexp parserexpf (整数/浮点表达式解析) 数学: math float softdouble softfloat softint64 系统: os file network memory device convert ... ``` ## 示例 ```bash # 跨语言表达式解析示例 (28 语言) Examples//parserexp_demo.* # 整数表达式: parserexp("2+3*4") = 14 Examples//parserexpf_demo.* # 浮点表达式: parserexpf("2.5+3*1.5") = 7.0 # SQLite 编译测试 (255K行 C 源文件) test/c/sqlite/sqlite_r0_test.c # MCU 模式: open→CREATE→INSERT→SELECT→close dotnet run --project VMLTool -- test/c/sqlite/sqlite_r0_test.c -o sqlite.vml # 编译器测试 (28 语言 × 基础测试) test/compiler_tests// # 每语言 Hello World + 语法测试 ``` ## 项目结构 ``` vml/ ├── VMLAssembler/ # VML 汇编器 (.wstring/.ustring 伪指令) ├── VMLTranslators/ # 20 目标架构转译器 ├── VMLPrepares/ # 28 语言编译器 │ ├── CompilerBase/ # LexerBase · ParserBase · CodeGeneratorBase · TypedCodeGen · CLikeCodegen · OopCodegen │ │ # ExpressionManager · StatementManager · VarMemManager · RegisterManager · Preprocessor │ ├── CCompiler/ # C99 🟢 生产可用 │ ├── CppCompiler/ # C++98 │ ├── [Basic|Pascal|Python|Lua|Forth|Rust|Go|...]/ # 所有编译器 ├── VMLRuntime/ # C# 虚拟机 (SYSCALL #1-394) ├── VMLFast/VMLRuntimeC/ # C 跨平台运行时(解释器 + 2D/3D 图形 + wasm/SDL 宿主) ├── VMLFast/VMLPackerC/ # C 打包工具 ├── VMLEmulators/ # ConsoleEmulator + FullDevicesEmulator (Avalonia) ├── VMLTool/ # CLI 主工具 (vmltool) ├── VMLIde/ # Avalonia IDE ├── VMLToHex/ # HEX/ELF/BIN 烧录生成 ├── VMLTests/ # xUnit 测试 (4595 tests, 6 Trait 类别) ├── VMLPlugins/ # 插件接口 + PluginManager ├── web/vml-web/ # 网页宿主(解释 / AOT 转译,矢量 + WebGL2 3D) ├── Scripts/ # 构建/运行/测试/移植脚本(web、桌面、ESP32、STM32、GBA/NDS/3DS) ├── tools/ # GenLib / GenDyn / GenDev ├── Lib/ # 标准库 (28 语言 × 35+ 文件 + shared/) ├── Examples/ # 跨语言示例代码 ├── test/compiler_tests/ # 编译器基础测试 (28 语言) ├── docs/ # ISA/SYSCALL/ROADMAP 等文档 └── VMLToolchain.sln # 解决方案 ``` ## 文档 - [指令集规范](docs/VML_ISA_SPEC.md) — ISA v1.12(寄存器 @ 硬切换 / 64 位补缺指令 / .wstring / .ustring) - [系统调用规范](docs/SYSCALL_SPEC.md) — SYSCALL v2.2 (#391-394) - [完成度仪表板](COMPLETION_DASHBOARD.md) - [更新日志](CHANGELOG.md) - [路线图](docs/ROADMAP.md) - [开发者指南](AGENTS.md) - [网页宿主说明](web/vml-web/README.md) — 解释/AOT、矢量渲染、WebGL2 3D - [桌面三平台宿主](docs/DESKTOP_SDL.md) — Windows/macOS/Linux、SDL2 + OpenGL - [M5Stack Cardputer Zero](docs/CARDPUTER_ZERO.md) — 三包、宿主模拟器、Lima、HTTP/VDL - [AOT → ARM64 Linux](docs/AOT_ARM64_LINUX.md) — HostMode、x24 栈、地址模型 - [ESP-Mosaico 接入](docs/MOSAICO.md) — 显示/输入/运行与外设 - [STM32F429 移植](docs/STM32F429.md) · [GBA 移植](docs/GBA.md) - [64 位 QEMU 裸机接入](docs/QEMU_INTEGRATION.md) — LoongArch64 / MIPS64EL / PowerPC64LE / s390x ## 许可证 MIT License