# xharbour-org/xharbour architecture

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

- Interactive diagram: https://gitdiagram.com/xharbour-org/xharbour
- Repository: https://github.com/xharbour-org/xharbour

## Overview

##### Project type and purpose
- xHarbour is a compiler and runtime for the Clipper/xBase language (an xBase superset).
- It includes: a source‐code compiler (front-end + back-end), a virtual machine (VM) that executes P-code, and extensive runtime libraries (RTL) for data, I/O, GUI, RDD drivers, etc.

##### File structure
- Top-level:
- build scripts and config (Makefile, buildxbuilder.sh, config/)
- contrib/ — third-party libraries (FreeImage, GD, zlib, SQLite, etc.)
- / — public headers and API definitions
- source/ — compiler, codepage, common, VM, runtime (rtl), RDD drivers, ODBC, CGI, etc.
- tests/ — automated test suites
- Patterns:
- MVC-style separation of compiler phases under source/compiler
- VM core under source/vm
- Runtime libraries under source/rtl, source/common, source/rdd
- Platform abstraction via config/* and per-OS code under source/rtl/*

##### README insights
- Confirms full compiler + runtime, cross-platform (Windows, Linux, MacOS).
- Build tools drive compiler toolchain selection and target platform.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & Configuration Layer
    subgraph "Build & Configuration Layer"
        Makefile["Makefile"]:::build
        BuildScripts["buildxbuilder.sh / bin/"]:::build
        ConfigDir["config/"]:::build
    end
    Makefile -->|invokes| BuildScripts
    BuildScripts -->|reads| ConfigDir

    %% Compilation Pipeline
    subgraph "Compiler Front-End" 
        Lexical["hbslex.c"]:::compiler
        Parsing["hbparse*.c"]:::compiler
        Ident["hbident.c"]:::compiler
        MainFE["hbmain.c"]:::compiler
    end
    ConfigDir -->|configures| Lexical
    Lexical -->|token stream| Parsing
    Parsing -->|AST| Ident
    Ident -->|symbols| MainFE

    subgraph "Intermediate Representation (P-Code Generator)"
        GenC["genc.c"]:::compiler
        PCode["hbpcode.c"]:::compiler
        PCStat["hbpcstat.c"]:::compiler
    end
    MainFE -->|semantic tree| GenC
    GenC -->|P-Code| PCode
    PCode -->|stats| PCStat

    subgraph "Compiler Back-End"
        GenCC["gencc.c"]:::compiler
        GenCC1["gencc1.c"]:::compiler
        GenObj["gencobj.c"]:::compiler
        GenHRB["genhrb.c"]:::compiler
    end
    PCStat -->|intermediate| GenCC
    GenCC --> GenCC1
    GenCC1 --> GenObj
    GenObj --> GenHRB
    GenHRB -->|"executable/library"| Output["P-Code Executable/Library"]:::compiler

    %% Runtime & VM
    subgraph "Virtual Machine (VM)"
        HVM["hvm.c"]:::runtime
        Runner["runner.c"]:::runtime
        GC["garbage.c"]:::runtime
        Debug["debug.c"]:::runtime
        Thread["thread.c"]:::runtime
    end
    Output -.->|loads P-Code| HVM
    HVM --> Runner
    Runner --> GC
    Runner --> Debug
    Runner --> Thread

    subgraph "Runtime Libraries (RTL)"
        CoreMem["hbmem.c"]:::runtime
        CorePrint["hbprintf.c"]:::runtime
        HighArray["arrayblk.prg"]:::runtime
        HighFile["file.c"]:::runtime
        HighGT["gt.c"]:::runtime
        GUIWin["gtwin/"]:::runtime
        GUIQT["gtQTc/"]:::runtime
    end
    Runner -.->|calls RTL| CoreMem
    Runner -.-> CorePrint
    CorePrint -.-> HighArray
    CorePrint -.-> HighFile
    CorePrint -.-> HighGT
    HighGT -.-> GUIWin
    HighGT -.-> GUIQT

    subgraph "Data Drivers (RDD)"
        DBF1["dbf1.c"]:::runtime
        DBFCDX["dbfcdx/"]:::runtime
        BMD["bmdbfcdx/"]:::runtime
    end
    Runner -.->|data| DBF1
    Runner -.-> DBFCDX
    Runner -.-> BMD

    subgraph "Codepages & Localization"
        CP1252["cp1252.c"]:::runtime
        UC1251["uc1251.c"]:::runtime
        MSGDE["msgde.c"]:::runtime
        MSGEN["msgen.c"]:::runtime
    end
    Runner -.-> CP1252
    Runner -.-> UC1251
    Runner -.-> MSGDE
    Runner -.-> MSGEN

    subgraph "ODBC & Networking"
        ODBC["odbc.c / todbc.prg"]:::runtime
        TIP["httpcln.prg / base64.c"]:::runtime
    end
    Runner -.-> ODBC
    Runner -.-> TIP

    subgraph "External Libraries (contrib)"
        ZLib["zlib/"]:::external
        FreeImage["freeimage/"]:::external
        SQLite["sqlite/"]:::external
    end
    Runner -.-> ZLib
    Runner -.-> FreeImage
    Runner -.-> SQLite

    %% Tests & Samples
    subgraph "Tests & Samples"
        Tests["tests/"]:::external
        Samples["samples/"]:::external
    end
    Tests -->|compile & run| MainFE
    Tests -->|test runtime| HVM
    Samples -->|demonstrate| Output

    %% Legend
    subgraph Legend
        B["Build/Config"]:::build
        C["Compiler"]:::compiler
        R["Runtime/VM"]:::runtime
        E["External"]:::external
        Solid["Solid arrow: compile-time"]:::legend
        Dashed["Dashed arrow: runtime"]:::legend
    end

    %% Click Events
    click Makefile "https://github.com/xharbour-org/xharbour/tree/main/./Makefile"
    click BuildScripts "https://github.com/xharbour-org/xharbour/blob/main/./buildxbuilder.sh"
    click ConfigDir "https://github.com/xharbour-org/xharbour/tree/main/./config/"
    click Lexical "https://github.com/xharbour-org/xharbour/blob/main/source/compiler/hbslex.c"
    click Parsing "https://github.com/xharbour-org/xharbour/blob/main/source/compiler/hbparse.c"
    click Ident "https://github.com/xharbour-org/xharbour/blob/main/source/compiler/hbident.c"
    click MainFE "https://github.com/xharbour-org/xharbour/blob/main/source/compiler/hbmain.c"
    click GenC "https://github.com/xharbour-org/xharbour/blob/main/source/compiler/genc.c"
    click PCode "https://github.com/xharbour-org/xharbour/blob/main/source/compiler/hbpcode.c"
    click PCStat "https://github.com/xharbour-org/xharbour/blob/main/source/compiler/hbpcstat.c"
    click GenCC "https://github.com/xharbour-org/xharbour/blob/main/source/compiler/gencc.c"
    click GenCC1 "https://github.com/xharbour-org/xharbour/blob/main/source/compiler/gencc1.c"
    click GenObj "https://github.com/xharbour-org/xharbour/blob/main/source/compiler/gencobj.c"
    click GenHRB "https://github.com/xharbour-org/xharbour/blob/main/source/compiler/genhrb.c"
    click HVM "https://github.com/xharbour-org/xharbour/blob/main/source/vm/hvm.c"
    click Runner "https://github.com/xharbour-org/xharbour/blob/main/source/vm/runner.c"
    click GC "https://github.com/xharbour-org/xharbour/blob/main/source/vm/garbage.c"
    click Debug "https://github.com/xharbour-org/xharbour/blob/main/source/vm/debug.c"
    click Thread "https://github.com/xharbour-org/xharbour/blob/main/source/vm/thread.c"
    click CoreMem "https://github.com/xharbour-org/xharbour/blob/main/source/common/hbmem.c"
    click CorePrint "https://github.com/xharbour-org/xharbour/blob/main/source/common/hbprintf.c"
    click HighArray "https://github.com/xharbour-org/xharbour/blob/main/source/rtl/arrayblk.prg"
    click HighFile "https://github.com/xharbour-org/xharbour/blob/main/source/rtl/file.c"
    click HighGT "https://github.com/xharbour-org/xharbour/blob/main/source/rtl/gt.c"
    click GUIWin "https://github.com/xharbour-org/xharbour/tree/main/source/rtl/gtwin/"
    click GUIQT "https://github.com/xharbour-org/xharbour/tree/main/source/rtl/gtQTc/"
    click DBF1 "https://github.com/xharbour-org/xharbour/blob/main/source/rdd/dbf1.c"
    click DBFCDX "https://github.com/xharbour-org/xharbour/tree/main/source/rdd/dbfcdx/"
    click BMD "https://github.com/xharbour-org/xharbour/tree/main/source/rdd/bmdbfcdx/"
    click CP1252 "https://github.com/xharbour-org/xharbour/blob/main/source/codepage/cp1252.c"
    click UC1251 "https://github.com/xharbour-org/xharbour/blob/main/source/codepage/uc1251.c"
    click MSGDE "https://github.com/xharbour-org/xharbour/blob/main/source/lang/msgde.c"
    click MSGEN "https://github.com/xharbour-org/xharbour/blob/main/source/lang/msgen.c"
    click ODBC "https://github.com/xharbour-org/xharbour/blob/main/source/odbc/odbc.c"
    click TIP "https://github.com/xharbour-org/xharbour/blob/main/source/tip/httpcln.prg"
    click ZLib "https://github.com/xharbour-org/xharbour/tree/main/contrib/zlib/"
    click FreeImage "https://github.com/xharbour-org/xharbour/tree/main/contrib/freeimage/"
    click SQLite "https://github.com/xharbour-org/xharbour/tree/main/contrib/sqlite/"
    click Tests "https://github.com/xharbour-org/xharbour/tree/main/tests/"
    click Samples "https://github.com/xharbour-org/xharbour/tree/main/samples/"

    %% Styles
    classDef build fill:#ffeb99,stroke:#333,stroke-width:1px
    classDef compiler fill:#99ccff,stroke:#333,stroke-width:1px
    classDef runtime fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef external fill:#ffcc99,stroke:#333,stroke-width:1px
    classDef legend fill:#f0f0f0,stroke:#999,stroke-width:1px,stroke-dasharray: 2 2
```
