A hard-forked Moon runtime implemented in modern C++23, with ARC-driven memory management and an end-to-end .mn toolchain.
Moon is no longer just a renamed Lua build. It is a hard fork with different runtime goals, different defaults, and a different memory model.
| Area | Lua | Moon |
|---|---|---|
| Interpreter and scripts | lua, .lua |
moon, .mn |
| Module search defaults | share/lua, lib/lua |
share/moon, lib/moon |
| Memory management | Incremental/generational tracing GC | ARC-style reference counting with deterministic drains |
| Cycle handling | Reachability-based collector eventually reclaims cycles | Strong reference cycles leak unless code breaks them explicitly |
| GC controls | managelifecycle drives a real tracing collector |
Tracing-GC-only behaviors are retired or reduced; ARC behavior is covered by test_arc |
Lua's collector is a tracing GC: objects stay alive while reachable, and cycles are reclaimed when the collector finds them unreachable. Moon replaces that with ARC-style ownership. References are retained and released as values move through stack slots, tables, closures, upvalues, and API boundaries.
That shift has practical consequences:
- Deterministic reclamation: many objects are reclaimed as soon as the last strong reference disappears, instead of waiting for a future GC cycle.
- Cycles are the programmer's responsibility: tables, closures, userdata, or upvalues that strongly reference each other can leak if nothing breaks the cycle.
- Write paths matter: internal code must use ownership-aware helpers such as
moonLife_slotAssign,moonLife_slotInit, andMoonStackslot helpers instead of raw slot writes. - Some upstream Lua GC semantics no longer apply: tracing-GC state-machine tests and collector-mode edge cases are intentionally retired where they depend on mark/sweep behavior.
For a maintainers' view of the fork, see docs/MOON_VS_LUA.md.
Performance: 4.20s baseline (current machine) ✅
Converted: 19 structs → classes (100%)
Encapsulated: 19/19 classes fully private (100%) ✅
Macros Converted: ~500 (37% of convertible macros)
Enum Classes: All major enums converted (Phases 96-100) ✅
Code Coverage: 96.1% lines, 92.7% functions, 85.2% branches ✅
Build Status: Zero warnings with -Werror
Tests: All passing
Current Phase: 101 - CI/CD infrastructure complete
- Zero Performance Regression: Strict ≤3% tolerance enforced
- Automated CI/CD: GitHub Actions for builds, tests, and performance tracking
- Full C API Compatibility: Public API unchanged
- Modern C++23: CRTP, inline constexpr, enum classes
- Type Safety: Replaced macros with type-safe inline functions
- Encapsulation: Private fields with accessor methods
- Exception Handling: Modern C++ exceptions (replaced setjmp/longjmp)
- Clean Architecture: CRTP inheritance, organized source tree
Static polymorphism without vtable overhead:
template<typename Derived>
class ManagedBase {
public:
ManagedObject* next;
lu_byte tt;
lu_byte marked;
bool isWhite() const noexcept { return testbits(marked, WHITEBITS); }
bool isBlack() const noexcept { return testbit(marked, BLACKBIT); }
};
class Table : public ManagedBase<Table> { /* ... */ };
class TString : public ManagedBase<TString> { /* ... */ };All 9 GC-managed classes inherit from ManagedBase<Derived> for zero-cost abstraction.
Core Data Types:
- ✅
Table,TString,Proto,UpVal,Udata - ✅
CClosure,LClosure- Closure types
VM Internals:
- ✅
lua_State,global_State,CallInfo - ✅
ManagedObject,TValue- Base types
Compiler Types:
- ✅
FuncState,LexState,expdesc - ✅
LocVar,AbsLineInfo,Upvaldesc
Utilities:
- ✅
stringtable- String interning
- C++23 compatible compiler (GCC 13+ or Clang 16+)
- CMake 3.20+
# Configure and build
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
# Run tests
cd testes
../build/moon all.mn
# Expected output: "final OK !!!"cd testes
for i in 1 2 3 4 5; do
../build/moon all.mn 2>&1 | grep "total time:"
done
# Current machine baseline: 4.20s
# Target: ≤4.33s (3% tolerance)
# Historical baseline: 2.17s (different hardware)src/
├── objects/ - Core data types (Table, TString, Proto, UpVal)
├── core/ - VM core (ldo, lapi, ldebug, lstate)
├── vm/ - Bytecode interpreter
├── compiler/ - Parser and code generator
├── memory/ - GC and memory management
├── libraries/ - Standard libraries
├── auxiliary/ - Auxiliary library
├── serialization/ - Bytecode dump/undump
└── interpreter/ - Interactive interpreter
- docs/README.md - Current documentation hub, build commands, and archive policy
- CLAUDE.md - ⭐ Comprehensive AI assistant guide with repository context
- docs/MOON_VS_LUA.md - What changed in the Moon fork, especially memory management
- docs/ARC_PHASE1_STATUS.md - Active ARC implementation status and validation notes
- docs/MEMORY_MODERNIZATION.md - Current plan and boundary for replacing legacy manual memory-management style with modern C++ ownership
- docs/HISTORICAL_NOTES.md - Compressed summary of superseded conversion-era docs
- docs/archive/README.md - Archived phase write-ups and historical provenance
- 19/19 classes fully encapsulated with private fields and comprehensive accessors ✅
- 500+ macros converted to inline constexpr functions (37% of convertible)
- CRTP implementation across all 9 GC types for zero-cost polymorphism
- SRP refactoring complete - FuncState, global_State, Proto decomposed (6% faster!)
- Enum class conversion - All major enums modernized (Phases 96-100)
- GC modularization - Extracted LifecycleCore, GCMarking, GCCollector modules
- LuaStack centralization - Complete stack encapsulation (Phase 94)
- Zero API breakage - Full C API compatibility maintained
- Modern exception handling - C++ exceptions replace setjmp/longjmp
This is an experimental modernization project. The focus is on:
- Maintaining zero performance regression
- Preserving full C API compatibility
- Incremental, tested improvements
- Comprehensive benchmarking after every change
Strict performance enforcement:
- Every significant change must be benchmarked
- Current machine target: ≤4.33s (≤3% from 4.20s baseline)
- Historical baseline: 2.17s (different hardware)
- Immediate revert if performance degrades beyond tolerance
Same as Lua - see the official Lua repository for license details.
Note: This is a C++ modernization project, not the official Lua repository. For official Lua releases and support, visit Lua.org.