#moonbit-libyue

• Ubuntu 24.04 Xfce
• Ubuntu 24.04 GNOME
• Ubuntu 24.04 KDE
• Deepin 25
• OpenKylin 3
• Windows 10 / 11 (first verified 2026-09, full showcase runs; see docs/adaptation.md)
• macOS

#Yue

#Three-Layer Architecture

┌─────────────────────────────────────────────┐
│ Consumers (examples/*)                      │  Pure MoonBit, zero platform code
├─────────────────────────────────────────────┤
│ MoonBit library (yue/)                      │  Unified API: types, closures,
│                                             │  encoding, platform probing and
│                                             │  fallback — all absorbed here
├─────────────────────────────────────────────┤
│ Platform layer (shim/ + vendor/libyue)      │  Thinnest C ABI (mechanical
│                                             │  translation) + libyue absorbing
│                                             │  win/linux/macos differences
└─────────────────────────────────────────────┘

1. If MoonBit can solve it, it stays out of C/C++ — string UTF-16↔UTF-8 conversion, the closure keep-alive registry, error enums, and tray fallback logic all live in yue/.
2. The C++ shim only translates ABI — shim/yue_mbt.cpp maps function-by-function to shim/include/yue_mbt.h, with no business logic.
3. Platform differences converge in two stages — what libyue already unifies (windows, widgets) is used directly; what libyue does not expose (e.g. Linux tray backend probing, where it only logs on dlopen failure) is supplemented by shim probing interfaces, and the MoonBit layer translates them into a unified Result / is_supported() semantics.

#Layout

yue/                 MoonBit library package
  ffi.mbt            Private extern "c" declarations (native backend only)
  types.mbt          Widget type definitions (Window/Label/View handles and wrappers)
  app.mbt            App lifecycle: init / run / quit
  view.mbt           Common View capabilities + callback registry (focus/enable/style/drag)
  widgets.mbt        Basic and composite widgets (Button/Entry/Slider/Picker/ComboBox/ProgressBar/Popover…)
  browser.mbt        Embedded browser (WebView)
  menu.mbt           Menu bar / popup menu / menu items
  dialog.mbt         File open/save dialogs
  text_edit.mbt      Multiline text editor
  tab.mbt            Tab control
  table.mbt          Table + data model bridge accepting MoonBit traits
  painter.mbt        2D drawing (Painter / offscreen Canvas)
  misc.mbt           Group / Scroll / Separator / Clipboard / MessageBox
  color.mbt          Color utilities (pure MoonBit)
  geometry.mbt       Geometry value types (pure MoonBit)
  error.mbt          Structured errors
  events.mbt         Event system (mouse/keyboard, modifier normalization, VKEY constants, click tracking)
  button.mbt         Button / single-line Entry (Checkbox/Radio/Password)
  props.mbt          L1 props constructors (X::make / apply_style)
  declarative.mbt    L2 declarative nodes (Node/mount/vbox/label/…)
  store.mbt          L3 reactive Store (subscribe / map / bind_label)
  tray.mbt           Unified tray API
  traybus/           Pure-MoonBit DBus + StatusNotifierItem protocol stack (Linux tray)
    wire.mbt         DBus wire format codec
    bus.mbt          Session bus connection, SASL EXTERNAL handshake, message dispatch
    sni.mbt          SNI protocol implementation
    detect.mbt       Desktop environment detection (XDG_CURRENT_DESKTOP)
    icon.mbt         Procedurally generated tray bitmap (no image assets or decoders)
    sys.mbt          fd-level syscall surface (all forwarded via shim)
shim/                C ABI wrapper layer (yue_mbt.cpp + include/yue_mbt.h) + CMakeLists
scripts/prepare.py   Pinned-version libyue download + static library build (link flags are owned by prebuild.py)
scripts/prebuild.py  Moon build hook: emits per-OS link config, propagated to all dependents
scripts/postadd.py   Auto-triggered on `moon add` for the first native build
examples/            15 examples: hello / editor / browser / drawing / table / widgets /
                     drag_source / drag_destination / floating_heart /
                     auto_height_edit / showcase / misc / advanced / events / layout
.agents/skills/      MoonBit skill library

#Quick Start

#Ubuntu 24.04

sudo apt install build-essential cmake pkg-config \
  libgtk-3-dev libpango1.0-dev libfontconfig1-dev libx11-dev \
  libwebkit2gtk-4.1-dev

moon run examples/hello

#Windows (10/11, x64)

1. Install the MoonBit toolchain (PowerShell):

irm https://cli.moonbitlang.com/install/powershell.ps1 | iex

2. Install CMake and the MSVC C++ toolchain (winget, or install the equivalent components via the VS Installer):

winget install Kitware.CMake
winget install Microsoft.VisualStudio.2022.BuildTools -e --override "--quiet --wait --norestart --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"

3. Add the ATL component (libyue's Windows sources include ATL headers such as atldef.h, which are not installed by default; needs elevation):

Start-Process -FilePath 'C:\Program Files (x86)\Microsoft Visual Studio\Installer\setup.exe' -ArgumentList 'modify','--installPath','"C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools"','--add','Microsoft.VisualStudio.Component.VC.ATL','--quiet','--norestart' -Verb RunAs -Wait

4. Build and run. On Windows moon looks for cl on PATH when compiling native code, so run it from the "x64 Native Tools Command Prompt for VS 2022", or call vcvars64.bat first:

call "C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvars64.bat"
python3 scripts\prepare.py
moon run examples/hello

moon test

#Notes

• The current binding surface is roughly 320 ABI functions (324 extern "c" declarations in yue/ffi.mbt): App/Lifetime, Window, common View capabilities and drag & drop, Container/Label/Button/Entry/TextEdit, Slider/Picker/ComboBox/ProgressBar/Tab/Group/Scroll/Separator/DatePicker/GifPlayer, Browser, Menu/MenuBar, Table + model bridge, Painter/Canvas, Tray/Notification/GlobalShortcut/Clipboard/MessageBox/Popover/FileDialog, Screen/Appearance/Locale/Cursor. New widgets follow the established pattern: add a mechanical translation function in the shim → add the extern in ffi.mbt → add the type and methods in a new *.mbt.
• Known limitations, ABI pitfalls and per-platform adaptation lessons live in AGENTS.md and docs/adaptation.md instead of this README. The Linux tray design — motivation, architecture, backend fallback, desktop compatibility, debugging — is documented separately in docs/tray.md (Chinese). The widget API quick reference (including upstream pitfalls) lives in docs/components.md; the declarative layer — X::make props constructors, Node/mount render trees and Store reactive bindings — in docs/declarative.md.
• Shim/vendor changes or a re-run of prepare.py require forcing a relink: moon clean, or delete the linked executable — see docs/relink.md (Chinese).
• Documentation index: docs/README.md.

#References

• libyue documentation: https://libyue.com/docs/latest/cpp/guides/getting_started.html
• Lua bindings (architectural reference): lua_yue/ in github.com/yue/yue
• MoonBit skill library: .agents/skills/ (moonbit-c-binding, make-moonbit-c-bindings)
• AI collaboration rules: AGENTS.md · platform adaptation experience: docs/adaptation.md