# dslab-epfl/chef-symbex-lua architecture

> Architecture diagram of the GitHub repository dslab-epfl/chef-symbex-lua, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dslab-epfl/chef-symbex-lua
- Repository: https://github.com/dslab-epfl/chef-symbex-lua

## Overview

##### Project type and purpose
- This is the Lua 5.2.2 language implementation—a small-footprint, embeddable scripting language interpreter and compiler.
- It provides both an interactive interpreter (`lua`) and a bytecode compiler (`luac`), plus the core VM, standard libraries, documentation, and build/test tooling under `chef`.

##### File structure
- Top-level:
- `src/` – C source code for the core: lexer, parser, bytecode generator, VM, standard libraries, C API.
- `doc/` – HTML man pages and user manual.
- `chef/` – Python and Lua scripts to drive tests, coverage analysis, and target-language transpilation.
- Makefiles at top and in `src/` & `chef/` for building C binaries and running tooling.
- Naming conventions: modules in `src/l*.c` for each subsystem (e.g., `llex.c` for lexical analysis, `lparser.c` for parsing, `lvm.c` for the virtual machine).
- Build and deployment: classic GNU Make; no external services.

##### README for additional insights
- Confirms version and points to `doc/readme.html` for installation and licensing.

##### Detail
- Header/API boundary between `src/` modules and external C applications.
- Both runtime flow (execution) and offline build/test flow (`chef`).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Frontends
    subgraph "Command-line Frontends"
        Lua["lua (Interpreter)"]:::module
        Luac["luac (Compiler)"]:::module
    end

    %% Source
    Source["Source Code / REPL Input"]:::pipeline

    %% Compilation Pipeline
    subgraph "Compiler Pipeline"
        LEXER["Lexer (llex.c)"]:::module
        PARSER["Parser (lparser.c)"]:::module
        BYTEGEN["Bytecode Generator (lcode.c)"]:::module
        DUMPER["Bytecode Dumper (lundump.c)"]:::module
        BytecodeArtifact["Bytecode Artifact"]:::artifact
    end

    %% Runtime
    subgraph "Runtime VM"
        VM["VM (lvm.c)"]:::module
        GC["Garbage Collector (lgc.c)"]:::module
        API["Embedding API (lua.h, lauxlib.h)"]:::module
        VM --> GC
        API --> VM
    end

    %% Standard Libraries
    subgraph "Standard Libraries"
        Baselib["Base (lbaselib.c)"]:::module
        Tabl["Table (ltablib.c)"]:::module
        Strlib["String (lstrlib.c)"]:::module
        Mathlib["Math (lmathlib.c)"]:::module
        IOLib["I/O (liolib.c)"]:::module
        Coro["Coroutine (lcorolib.c)"]:::module
        DebugLib["Debug (ldebug.c)"]:::module
        Bitlib["Bit Ops (lbitlib.c)"]:::module
        OSLib["OS (loslib.c)"]:::module
        Loadlib["Loading (loadlib.c)"]:::module
        Symbex["Symbolic Exec (lsymbexlib.c)"]:::module
        VM --> Baselib
        VM --> Tabl
        VM --> Strlib
        VM --> Mathlib
        VM --> IOLib
        VM --> Coro
        VM --> DebugLib
        VM --> Bitlib
        VM --> OSLib
        VM --> Loadlib
        VM --> Symbex
    end

    %% Embedding Host
    HostApp["C Host Application"]:::external
    HostApp --> API

    %% Chef Build & Test
    subgraph "Build & Test Tooling (chef)"
        MakeChef["chef/Makefile.chef"]:::tooling
        AnalyzeCov["analyze_coverage.py"]:::tooling
        LuaRunner["lua_runner.py"]:::tooling
        Targets["targets/"]:::tooling
        MakeChef --> AnalyzeCov
        MakeChef --> LuaRunner
        MakeChef --> Targets
    end

    %% Documentation
    subgraph "Documentation (doc)"
        Manual["manual.html"]:::doc
        Contents["contents.html"]:::doc
        LuaMan["lua.1"]:::doc
        LuacMan["luac.1"]:::doc
        Readme["readme.html"]:::doc
    end

    %% Build Makefiles
    MakeTop["Makefile"]:::tooling
    MakeCore["src/Makefile"]:::tooling
    MakeTop --> MakeCore
    MakeTop --> MakeChef

    %% Flows
    Lua --> Source
    Luac --> Source
    Source --> LEXER --> PARSER --> BYTEGEN --> DUMPER --> BytecodeArtifact
    BytecodeArtifact --> VM
    Luac --> BytecodeArtifact

    %% Click Events
    click Lua "https://github.com/dslab-epfl/chef-symbex-lua/blob/master/src/lua.c"
    click Luac "https://github.com/dslab-epfl/chef-symbex-lua/blob/master/src/luac.c"
    click LEXER "https://github.com/dslab-epfl/chef-symbex-lua/blob/master/src/llex.c"
    click PARSER "https://github.com/dslab-epfl/chef-symbex-lua/blob/master/src/lparser.c"
    click BYTEGEN "https://github.com/dslab-epfl/chef-symbex-lua/blob/master/src/lcode.c"
    click DUMPER "https://github.com/dslab-epfl/chef-symbex-lua/blob/master/src/lundump.c"
    click VM "https://github.com/dslab-epfl/chef-symbex-lua/blob/master/src/lvm.c"
    click GC "https://github.com/dslab-epfl/chef-symbex-lua/blob/master/src/lgc.c"
    click API "https://github.com/dslab-epfl/chef-symbex-lua/blob/master/src/lua.h"
    click Baselib "https://github.com/dslab-epfl/chef-symbex-lua/blob/master/src/lbaselib.c"
    click Tabl "https://github.com/dslab-epfl/chef-symbex-lua/blob/master/src/ltablib.c"
    click Strlib "https://github.com/dslab-epfl/chef-symbex-lua/blob/master/src/lstrlib.c"
    click Mathlib "https://github.com/dslab-epfl/chef-symbex-lua/blob/master/src/lmathlib.c"
    click IOLib "https://github.com/dslab-epfl/chef-symbex-lua/blob/master/src/liolib.c"
    click Coro "https://github.com/dslab-epfl/chef-symbex-lua/blob/master/src/lcorolib.c"
    click DebugLib "https://github.com/dslab-epfl/chef-symbex-lua/blob/master/src/ldebug.c"
    click Bitlib "https://github.com/dslab-epfl/chef-symbex-lua/blob/master/src/lbitlib.c"
    click OSLib "https://github.com/dslab-epfl/chef-symbex-lua/blob/master/src/loslib.c"
    click Loadlib "https://github.com/dslab-epfl/chef-symbex-lua/blob/master/src/loadlib.c"
    click Symbex "https://github.com/dslab-epfl/chef-symbex-lua/blob/master/src/lsymbexlib.c"
    click MakeTop "https://github.com/dslab-epfl/chef-symbex-lua/tree/master/Makefile"
    click MakeCore "https://github.com/dslab-epfl/chef-symbex-lua/tree/master/src/Makefile"
    click MakeChef "https://github.com/dslab-epfl/chef-symbex-lua/blob/master/chef/Makefile.chef"
    click AnalyzeCov "https://github.com/dslab-epfl/chef-symbex-lua/blob/master/chef/analyze_coverage.py"
    click LuaRunner "https://github.com/dslab-epfl/chef-symbex-lua/blob/master/chef/lua_runner.py"
    click Targets "https://github.com/dslab-epfl/chef-symbex-lua/tree/master/chef/targets/"
    click Manual "https://github.com/dslab-epfl/chef-symbex-lua/blob/master/doc/manual.html"
    click Contents "https://github.com/dslab-epfl/chef-symbex-lua/blob/master/doc/contents.html"
    click LuaMan "https://github.com/dslab-epfl/chef-symbex-lua/blob/master/doc/lua.1"
    click LuacMan "https://github.com/dslab-epfl/chef-symbex-lua/blob/master/doc/luac.1"
    click Readme "https://github.com/dslab-epfl/chef-symbex-lua/blob/master/doc/readme.html"

    %% Styles
    classDef module fill:#f9f,stroke:#333,stroke-width:1px;
    classDef pipeline fill:#bbf,stroke:#333,stroke-width:1px;
    classDef artifact fill:#bfb,stroke:#333,stroke-width:1px,shape:cylinder;
    classDef external fill:#fcc,stroke:#333,stroke-width:1px,shape:cloud;
    classDef tooling fill:#ffebcc,stroke:#333,stroke-width:1px;
    classDef doc fill:#ccf,stroke:#333,stroke-width:1px,shape:parallelogram;
```
