# mikepopoloski/slang architecture

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

- Interactive diagram: https://gitdiagram.com/mikepopoloski/slang
- Repository: https://github.com/mikepopoloski/slang

## Overview

##### Project type and purpose
- slang is a compiler‐style library and toolchain for SystemVerilog. It provides:
- A core C++ library for lexing, parsing, semantic analysis, diagnostics, and elaboration of SystemVerilog code
- A standalone command-line executable (“slang”) for compile/lint workflows
- Python bindings (pyslang) that expose core functionality to Python
- A suite of auxiliary tools (reflect, rewriter, tidy, hier, threadtest) built on the core library
- Unit and regression tests validating the core and tools
- Purpose: serve as a fast, robust front end for editors, linters, simulators, synthesis tools, or standalone code-analysis utilities.

##### File structure
- Top‐level CMake files drive building:
- CMakeLists.txt, CMakePresets.json, cmake/…
- /slang & source/… – core C++ library modules (driver, parsing, syntax, AST, analysis, diagnostics, numeric, text, util)
- bindings/python – pybind11‐style wrappers exposing C++ APIs to Python
- tools/… – individual small executables built against the library
- pyslang/… – Python package structure (docs, examples, tests)
- tests/… – C++ unit tests (gtests) and SV regression files
- external/… – header‐only dependencies (thread pool, expected, Boost‐style containers, IEEE VPI headers)
- scripts/… – codegen and ancillary maintenance scripts
- docs/… – Doxygen/Doxygen-inspired API and user manuals

##### README for architecture clues
- Core modules: lexing, parsing, type checking, elaboration
- Executable entry point for CLI workflows
- Python “ScriptSession” and “SyntaxTree” API abstractions
- Use cases: syntax checking, AST JSON dump, editor server, code generation

##### Final checklist
- Core library sub-modules and compiler pipeline stages
- How each executable or tool depends on the core library
- Build system orchestrating all targets
- External dependencies and code-gen scripts if relevant

## Diagram (Mermaid)

```mermaid
graph TB
    %% Core Library Modules
    subgraph "Core Library"
        direction TB
        Driver["Driver & SourceLoader"] 
        Preproc["Preprocessor & Lexer"]
        Parser["Parser"]
        SyntaxTree["SyntaxTree"]
        AST["AST & Semantic Analysis"]
        Diagnostics["Diagnostics Engine"]
        NumText["Numeric & Text Utilities"]
        Utils["Utility Modules"]
    end

    %% Executables & Tools
    subgraph "Executables & Tools"
        direction TB
        SlangCLI["slang CLI"] 
        Reflect["reflect"]
        Rewriter["rewriter"]
        Tidy["tidy"]
        Hier["hier"]
        ThreadTest["threadtest"]
    end

    %% Python Bindings
    subgraph "Python Bindings"
        direction TB
        PyBind["pybind11 Wrappers"]
    end

    %% Python Package
    subgraph "Python Package"
        direction TB
        PyPkg["pyslang Package & Tests"]
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        External["Header-only Libs & VPI"]
    end

    %% Tests
    subgraph "Test Suite"
        direction TB
        CppTests["C++ Unit Tests (gtest)"]
        SVTests["SV Regression Tests"]
        PyTests["Python pytest Suite"]
    end

    %% Build System
    Build["Build System (CMake & Presets)"]

    %% Pipeline Flow
    Driver -->|includes & links| Preproc
    Preproc -->|tokenizes| Parser
    Parser -->|builds AST| SyntaxTree
    SyntaxTree -->|semantic analysis| AST
    AST -->|reports| Diagnostics

    %% Utilities
    External -->|provides| Utils
    Utils -->|used by| Driver
    Utils -->|used by| Preproc
    Utils -->|used by| Parser
    Utils -->|used by| AST
    NumText -->|used by| AST
    Diagnostics -->|formats| NumText

    %% Executable Dependencies
    SlangCLI -->|link & call| Driver
    Reflect -->|uses| AST
    Rewriter -->|uses| AST
    Tidy -->|uses| Diagnostics
    Hier -->|uses| AST
    ThreadTest -->|uses| Utils

    %% Python Bindings
    PyBind -->|pybind11 call| Driver
    PyBind -->|pybind11 call| AST
    PyBind -->|pybind11 call| Diagnostics

    %% Python Package API
    PyPkg -->|wraps| PyBind
    PyPkg -->|uses| SyntaxTree
    PyPkg -->|uses| ScriptSession["ScriptSession API"]

    %% Tests invocations
    CppTests -->|exercise| Driver
    CppTests -->|exercise| AST
    SVTests -->|cli regression| SlangCLI
    PyTests -->|exercise| PyPkg

    %% Build orchestration
    Build -->|compiles| Driver
    Build -->|compiles| SlangCLI
    Build -->|compiles| Reflect
    Build -->|compiles| Rewriter
    Build -->|compiles| Tidy
    Build -->|compiles| Hier
    Build -->|compiles| ThreadTest
    Build -->|builds| PyBind
    Build -->|packages| PyPkg
    Build -->|runs| CppTests
    Build -->|runs| SVTests
    Build -->|runs| PyTests

    %% Click Events
    click Driver "https://github.com/mikepopoloski/slang/tree/master/include/slang/driver/"
    click Preproc "https://github.com/mikepopoloski/slang/tree/master/include/slang/parsing/"
    click Parser "https://github.com/mikepopoloski/slang/blob/master/include/slang/parsing/Parser.h"
    click SyntaxTree "https://github.com/mikepopoloski/slang/blob/master/include/slang/syntax/SyntaxTree.h"
    click AST "https://github.com/mikepopoloski/slang/tree/master/include/slang/ast/"
    click AST "https://github.com/mikepopoloski/slang/tree/master/include/slang/analysis/"
    click Diagnostics "https://github.com/mikepopoloski/slang/tree/master/include/slang/diagnostics/"
    click NumText "https://github.com/mikepopoloski/slang/tree/master/include/slang/numeric/"
    click NumText "https://github.com/mikepopoloski/slang/tree/master/include/slang/text/"
    click Utils "https://github.com/mikepopoloski/slang/tree/master/include/slang/util/"
    click SlangCLI "https://github.com/mikepopoloski/slang/blob/master/tools/driver/slang_main.cpp"
    click Reflect "https://github.com/mikepopoloski/slang/tree/master/tools/reflect/"
    click Rewriter "https://github.com/mikepopoloski/slang/tree/master/tools/rewriter/"
    click Tidy "https://github.com/mikepopoloski/slang/tree/master/tools/tidy/"
    click Hier "https://github.com/mikepopoloski/slang/tree/master/tools/hier/"
    click ThreadTest "https://github.com/mikepopoloski/slang/tree/master/tools/threadtest/"
    click PyBind "https://github.com/mikepopoloski/slang/tree/master/bindings/python/"
    click PyPkg "https://github.com/mikepopoloski/slang/tree/master/pyslang/"
    click CppTests "https://github.com/mikepopoloski/slang/tree/master/tests/unittests/"
    click SVTests "https://github.com/mikepopoloski/slang/tree/master/tests/regression/"
    click External "https://github.com/mikepopoloski/slang/tree/master/external/"
    click Build "https://github.com/mikepopoloski/slang/blob/master/CMakeLists.txt"

    %% Styles
    classDef library fill:#D0E4F5,stroke:#3182bd
    classDef executables fill:#D5F5D5,stroke:#239a3b
    classDef bindings fill:#FAD7A0,stroke:#d97706
    classDef external fill:#EAECEE,stroke:#6c757d
    classDef tests fill:#FCF3CF,stroke:#b7950b
    classDef build fill:#E8DAEF,stroke:#6f42c1

    class Driver,Preproc,Parser,SyntaxTree,AST,Diagnostics,NumText,Utils library
    class SlangCLI,Reflect,Rewriter,Tidy,Hier,ThreadTest executables
    class PyBind bindings
    class PyPkg,PyTests tests
    class CppTests,SVTests tests
    class External external
    class Build build
```
