# thephd/sol2 architecture

> Architecture diagram of the GitHub repository thephd/sol2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thephd/sol2
- Repository: https://github.com/thephd/sol2

## Overview

##### Project Type and Purpose
- sol2 is an open-source, header-only C++ library that provides bindings between C++ and Lua (all versions 5.1+, including LuaJIT and MoonJIT).
- It is not a standalone application but a library/toolkit used to embed and manipulate Lua scripts in C++ code.
- Core goals: zero‐overhead abstractions, easy integration (drag-and-drop single header), rich feature set for user types, containers, error handling, coroutines, etc.

##### File Structure Analysis
- Top-Level:
- /sol — the entire public C++ API (~300+ headers).
- single/ — scripts and CMake config to produce a single consolidated header.
- cmake/, meson.build, CMakeLists.txt — build system configurations (CMake modules, Meson).
- examples/ — dozens of sample applications demonstrating each feature, organized by topic.
- tests/ — exhaustive test suite subdivided into categories (config, coroutines, environment, run_time, regression, etc.).
- documentation/ — Sphinx/Doxygen sources, theme, tutorials, API reference.
- scripts/ — shell/Python scripts for building, testing, packaging on Linux/macOS.
- .github/workflows — CI definitions for Ubuntu, macOS, Windows.

##### README Insights
- Emphasizes header-only distribution, C++17 requirement, supported compilers, and opt-in testing of Lua builds.
- Mentions the “single header” generation via single.py or CMake target.
- Points to ReadTheDocs for user-facing docs and GitHub Actions for CI.

a. Main Components
1. Public API (include/sol)
2. Build System
- CMake (primary)
- Meson (alternative)
- Python/ shell scripts for packaging (single.py, scripts/*.sh)
3. Examples Suite
4. Test Harness
5. Documentation Generator
- Sphinx (documentation/source)
- Doxygen (documentation/Doxyfile.in)
6. Continuous Integration
- GitHub Actions (Windows, macOS, Linux)
7. External Dependencies
- Lua / LuaJIT (auto-built in tests)
- ReadTheDocs (for hosted docs)

b. Relationships and Interactions
- The Build System consumes the Public API headers plus CMakeLists.txt to configure:
- Library installation targets
- Single‐header bundle generation
- Example build targets
- Test targets (driven by SOL2_TESTS flags)
- Tests execute against:
- Built sol2 library
- Auto-built Lua (local or system)
- Documentation Generator reads API headers and rst sources to emit HTML/PDF, then pushes to ReadTheDocs.
- CI pipelines trigger:
- Build + install
- Single header generation
- Example compilation and execution
- Test suite runs
- Documentation build validation
- GitHub Actions orchestrates across OS runners, reports back status badges.

c. Architectural Patterns and Principles
- Header-only library pattern (zero runtime dependency).
- Modular CMake structure (cmake/Includes + cmake/Modules).
- Single‐source‐of‐truth for packaging (generate sol2_single_header from include/sol).
- Continuous verification (CI + tests + examples + docs in one repo).
- Separation of concerns:
- API vs. examples vs. tests vs. docs vs. packaging.

d. Key Technologies, Frameworks, Libraries
- CMake 3.x (project configuration, targets)
- Python3 (single.py & documentation requirements.txt)
- Meson (optional build)
- Sphinx + reStructuredText (HTML docs)
- Doxygen (API reference)
- GitHub Actions (CI)
- Bash/Batch scripting for cross-platform commands
- Lua, LuaJIT (embedded as dependency in tests)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core API
    subgraph "Code Artifacts"
        direction TB
        API["Public API\n(include/sol)"]:::code
        Examples["Examples Suite\n(examples/)"]:::code
        Tests["Test Harness\n(tests/)"]:::code
    end

    %% Build System
    subgraph "Build System" 
        direction TB
        CMakeCore["CMake Core\n(CMakeLists.txt + cmake/)"]:::tool
        Meson["Meson Build\n(meson.build + meson_options.txt)"]:::tool
        Scripts["Packaging Scripts\n(scripts/ + single/single.py)"]:::tool
        SingleHeader["Single-Header Generator\n(single/CMakeLists.txt + single/single.py)"]:::tool
    end

    %% Documentation
    subgraph "Documentation Generator"
        direction TB
        Sphinx["Sphinx\n(documentation/source/)"]:::doc
        Doxygen["Doxygen\n(documentation/Doxyfile.in)"]:::doc
    end

    %% Continuous Integration
    subgraph "CI & External"
        direction TB
        CI["GitHub Actions\n(.github/workflows/)"]:::ci
        Lua["Lua / LuaJIT"]:::external
        ReadTheDocs["ReadTheDocs"]:::external
    end

    %% Relationships
    API -->|"consumed by"| CMakeCore
    API -->|"input to"| SingleHeader
    API -->|"imported by"| Examples
    API -->|"linked in"| Tests

    CMakeCore -->|"generates"| SingleHeader
    CMakeCore -->|"configures build of"| Examples
    CMakeCore -->|"configures tests in"| Tests
    Meson -.->|"alternative build"| API

    Scripts -->|"package header"| SingleHeader

    Tests -->|"auto-builds"| Lua
    Examples -->|"requires"| Lua

    API & documentation_source["rst & headers"]:::invis --> Sphinx
    API --> Doxygen

    Sphinx -->|"outputs HTML/PDF"| ReadTheDocs
    Doxygen -->|"outputs API reference"| ReadTheDocs

    CI -->|"invokes"| CMakeCore
    CI -->|"runs"| Meson
    CI -->|"executes"| Scripts
    CI -->|"builds docs via"| Sphinx
    CI -->|"validates"| Tests
    CI -->|"reports to"| ReadTheDocs

    %% Click Events
    click API "https://github.com/thephd/sol2/tree/develop/include/sol"
    click CMakeCore "https://github.com/thephd/sol2/blob/develop/CMakeLists.txt"
    click CMakeCore "https://github.com/thephd/sol2/tree/develop/cmake/"
    click Meson "https://github.com/thephd/sol2/blob/develop/meson.build"
    click Meson "https://github.com/thephd/sol2/blob/develop/meson_options.txt"
    click Scripts "https://github.com/thephd/sol2/tree/develop/scripts/"
    click Scripts "https://github.com/thephd/sol2/blob/develop/single/single.py"
    click SingleHeader "https://github.com/thephd/sol2/blob/develop/single/CMakeLists.txt"
    click SingleHeader "https://github.com/thephd/sol2/blob/develop/single/single.py"
    click Examples "https://github.com/thephd/sol2/tree/develop/examples/"
    click Tests "https://github.com/thephd/sol2/tree/develop/tests/"
    click Tests "https://github.com/thephd/sol2/blob/develop/tests/CMakeLists.txt"
    click Sphinx "https://github.com/thephd/sol2/tree/develop/documentation/source/"
    click Doxygen "https://github.com/thephd/sol2/blob/develop/documentation/Doxyfile.in"
    click CI "https://github.com/thephd/sol2/blob/develop/.github/workflows/ubuntu.yml"
    click CI "https://github.com/thephd/sol2/blob/develop/.github/workflows/macos.yml"
    click CI "https://github.com/thephd/sol2/blob/develop/.github/workflows/windows.yml"
    click Lua "https://github.com/thephd/sol2/tree/develop/cmake/Packages/FindLua"
    click Lua "https://github.com/thephd/sol2/tree/develop/cmake/Packages/FindLuaJIT"
    click ReadTheDocs "https://github.com/thephd/sol2/tree/develop/Dockerfile"

    %% Styles
    classDef code fill:#BBDEFB,stroke:#0D47A1,color:#0D47A1;
    classDef tool fill:#C8E6C9,stroke:#1B5E20,color:#1B5E20;
    classDef doc fill:#FFE0B2,stroke:#E65100,color:#E65100;
    classDef ci fill:#E1BEE7,stroke:#4A148C,color:#4A148C;
    classDef external fill:#F5F5F5,stroke:#9E9E9E,color:#616161;
    classDef invis stroke:none,fill:none;
```
