MeshulaLab Framework

Application framework using a Studio-Activity-Provider architecture pattern.

MeshulaLab enables developers to build modular, composable applications with clean separation of concerns, event-driven programming, and comprehensive undo/redo support.

Features

• Studio-Activity-Provider Architecture - Modular design with clear separation between workspace configuration (Studios), UI/functionality (Activities), and data/services (Providers)
• Cross-Platform - Supports macOS, iOS, Windows, Linux, and WebAssembly via Emscripten
• Event-Driven - CSP (Communicating Sequential Processes) engine for reactive programming
• Transaction System - Built-in undo/redo with journaling
• Immediate Mode UI - Built on Dear ImGui for rapid development
• Hot-Reloadable Plugins - Dynamic plugin system with C ABI

Architecture

MeshulaLab uses a Studio-Activity-Provider pattern:

• Studios - Workspace configurations that define which Activities and Providers are active
• Activities - Discrete, composable UI/functionality modules
• Providers - Singleton services that supply data and functionality
• Orchestrator - Central coordinator managing lifecycle and dependencies

┌─────────────────────────────────────────────────┐
│ Studios │ ← Workspace Configurations
├─────────────────────────────────────────────────┤
│ Activities │ ← UI/Functionality Modules
├─────────────────────────────────────────────────┤
│ Providers │ ← Data/Service Layer
├─────────────────────────────────────────────────┤
│ Orchestrator │ ← Core Coordination
├─────────────────────────────────────────────────┤
│ CSP Engine (ZeroMQ / Web Workers) │ ← Event System
├─────────────────────────────────────────────────┤
│ Transaction/Journal System │ ← Undo/Redo
├─────────────────────────────────────────────────┤
│ Platform Layer (RGFW / SDL2 / Native) │ ← OS/Graphics APIs
└─────────────────────────────────────────────────┘

Example: Minimal Application

#include "Core/App.h"#include "Core/StudioCore.hpp"#include "Studios/Minimal/MinimalStudio.hpp"
int main(int argc, char** argv) {
 MeshulaLab::App app;
 app.init();
 auto studio = std::make_unique<MinimalStudio>();
 app.loadStudio(std::move(studio));
 app.run();
 app.shutdown();
 return 0;
}

Quick Start

Prerequisites

• CMake 3.20 or later
• C++20 compatible compiler:
  • macOS: Xcode 13+ (Apple Clang)
  • Windows: Visual Studio 2022
  • Linux: GCC 11+ or Clang 13+
  • Emscripten: Latest emsdk

Build and Run

# Clone the repository
git clone https://codeberg.org/meshula/MeshulaLab.git
cd MeshulaLab
# Configure and build
mkdir build
cd build
cmake ..
cmake --build .
# Run the demo
./MeshulaLab

Quick Start Scripts

# Setup (first time only)
./scripts/setup.sh
# Build
./scripts/build.sh
# Run
./build/bin/Studiola

Platform-Specific Builds

macOS

cmake -B build
cmake --build build
./build/MeshulaLab.app/Contents/MacOS/MeshulaLab

iOS

cmake -B build-ios -G Xcode -DCMAKE_SYSTEM_NAME=iOS
open build-ios/MeshulaLab.xcodeproj

Windows

cmake -B build
cmake --build build --config Debug
.\build\Debug\MeshulaLab.exe

Linux

cmake -B build
cmake --build build
./build/MeshulaLab

WebAssembly (Emscripten)

# Setup Emscripten environment
source $EMSDK/emsdk_env.sh
# Configure for Emscripten
mkdir build-emsc
cd build-emsc
emcmake cmake .. -DCMAKE_BUILD_TYPE=Release
# Build an example
cmake --build . --target minimal-app
# Run in browser (auto-opens)
cd bin
python3 serve.py minimal-app.html
# Or use the convenience script
./run_minimal-app.sh

Available Emscripten Examples:

• minimal-app - Full MeshulaLab app with AppMenu and Preferences
• wasm-demo - Simple demo with interactive UI
• MeshulaLabTests - Test suite (runs in browser console)

Note: The Emscripten build uses a lightweight Web Worker-based CSP implementation instead of ZeroMQ, maintaining the same API while working within browser constraints.

Documentation

Complete documentation is available in the docs/ directory:

• Getting Started - Quick start guide (5 minutes)
• Architecture Overview - Framework design and patterns
• API Reference - Complete API documentation
• Tutorials - Step-by-step guides
• Documentation Index - Full documentation table of contents

Quick Links

• Your First Application
• Core Concepts
• Creating Activities
• Creating Providers
• Working with Events
• Undo/Redo Support

Examples

The examples/ directory contains complete example projects:

• minimal-app - Minimal application with AppMenu and Preferences (works on all platforms including web!)
• wasm-demo - Simple WebAssembly demo with interactive UI
• custom-activity - Creating a custom Activity
• custom-provider - Creating a custom Provider
• plugin-system - Dynamic plugin loading (desktop only)
• multi-studio - Multiple Studios with switching

Running Web Examples

All examples can be built for WebAssembly:

cd build-emsc
cmake --build . --target minimal-app
cd bin
python3 serve.py minimal-app.html

The server provides:

• CORS headers for WebAssembly + SharedArrayBuffer
• Auto-reload on file changes
• Professional loading UI with progress indicator
• Colored request logging

Project Structure

MeshulaLab/
├── src/
│ ├── Core/ # Core interfaces and orchestrator
│ ├── Platform/ # Platform abstraction
│ ├── UI/ # UI utilities
│ ├── Activities/ # Sample Activities
│ ├── Providers/ # Sample Providers
│ ├── Studiola/ # The main application
│ └── Studios/ # Sample Studios
├── ext/ # Third-party dependencies
├── examples/ # Example projects
├── tests/ # Unit and integration tests
└── docs/ # Documentation

Building From Source

CMake Options

option(MESHULALAB_BUILD_EXAMPLES "Build examples" ON)option(MESHULALAB_BUILD_TESTS "Build tests" ON)option(MESHULALAB_USE_SYSTEM_LIBS "Use system libraries when available" OFF)option(MESHULALAB_ENABLE_SCRIPTING "Enable scripting support (s7)" ON)

Example Build

cmake -B build \
 -DMESHULALAB_BUILD_EXAMPLES=ON \
 -DMESHULALAB_BUILD_TESTS=ON \
 -DCMAKE_BUILD_TYPE=Release
cmake --build build

Testing

# Build with tests
cmake -B build -DMESHULALAB_BUILD_TESTS=ON
cmake --build build
# Run tests
cd build
ctest

Dependencies

MeshulaLab includes the following vendored dependencies:

• Dear ImGui (MIT) - Immediate mode GUI
• ImPlot (MIT) - Plotting library (optional)
• SDL2 (zlib) - Window/input management (Emscripten)
• ZeroMQ (MPL-2.0) - Message passing (desktop only)
• s7 Scheme (BSD) - Scripting (optional)
• Clay (MIT) - immediate-mode UI layout library by Nic Barker

License: zlib

Library Structure:

• MeshulaLabCore - UI-independent core library (orchestration, events, transactions)
• MeshulaLabUI - UI utilities and custom widgets (depends on ImGui)
• Activities, Studios, and Examples link to both Core and UI as needed

Platform-Specific:

• Desktop builds use RGFW + ZeroMQ
• Emscripten builds use SDL2 + Web Workers (no ZeroMQ)
• All platforms share the same MeshulaLab API

See ext/README.md and resources/emscripten/README.md for complete dependency information.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

Development

# Format code
./scripts/format.sh
# Run tests
./scripts/test.sh

License

MeshulaLab is licensed under the BSD License. See LICENSE for details.

Third-party dependencies have their own licenses. See ext/README.md for details.

Credits

Created by Nick Porcino

Built with:

• Dear ImGui by Omar Cornut
• ImPlot by Evan Pezent
• RGFW by ColleagueRiley
• ZeroMQ by the ZeroMQ community
• s7 Scheme by Bill Schottstaedt