evan
b9f7c9347c
The runtime has always called fields on the table main.lua returns, but @lua-global declared them as loose functions, so the stubs type-checked something that does not exist and read as "define a global". Callbacks are now @lua-app blocks that generate a class: App for the core contract, TouchHandlers and ButtonHandlers beside the namespaces they belong to. An app composes what it implements: ---@class PaintApp : App, TouchHandlers Names follow the rest of the surface: onTouchDown rather than on_touch_down, with the field names the runtime looks up renamed to match. @lua-field carries the plain fields (home, data) that were prose in a preamble before.
1.6 KiB
ESP32 Lua API Guidelines
This is a clean contract for repositories under the same owner's control. Choose the best shared API without preserving old names, signatures, or behavior; consumers migrate to the contract.
Every firmware implements all declarations under lua/api/core/. Optional hardware contracts
live under lua/api/features/, as one file or one directory per feature; sys.hasFeature(name)
guarantees the complete matching contract. Every namespace belongs to exactly one feature or to
core, so a feature is a provider pointer rather than a claim to validate: a panel is the screen
feature (screen and tree, including the saved rotation and theme), registered only when the
firmware supplies a GuiProvider, and calibration is touch.setCalibration().
Lua-language sources stay under lua/; C/C++ and the vendored interpreter stay under native/.
Apps are fully trusted; keep permissions and sandboxing out of scope.
Firmware commits dirty display content and owns panel refresh policy. Binding annotations under
native/src/bindings/ generate matching lua/api/ files; regenerate instead of editing files
marked generated. Callbacks are fields on the table an app returns, so a @lua-app block generates
a class an app composes (---@class PaintApp : App, TouchHandlers) rather than global functions. Each @lua-module/@lua-augment directive sits immediately above the
luaL_Reg table it describes, which is how one source declares several namespaces. This repository owns portable lua/lib/ modules; shared UI owns theme application and persistence. Use ble for BLE/GATT
and reserve bt for a future Classic Bluetooth contract.