How thephd/sol2 works
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)