# pawn-lang/compiler architecture

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

- Interactive diagram: https://gitdiagram.com/pawn-lang/compiler
- Repository: https://github.com/pawn-lang/compiler

## Overview

##### Project Overview and Purpose
- This project is a modified version of the Pawn 3.2.3664 compiler with bug fixes and enhancements aimed primarily at the SA-MP community. It is essentially a language compiler that transforms Pawn source code into executable byte-code through an embedded AMX (abstract machine).
- The project contains not just the language compiler (pawncc) but also the runtime execution engine (AMX VM) and supportive tooling (such as demo examples, tests, documentation, and build configuration).

##### Identifying the Main Components
a. Compiler Front-End:
– Located in the source/compiler folder.
– Handles reading Pawn source code, lexical analysis (e.g., files like sc1.c–sc7.c), parsing, and building the syntactic/semantic structures.
– Involves symbol handling (as seen with tests relating to symbols) and source code scanning.
b. Compiler Back-End:
– In the same source/compiler folder, along with code generation components (pawncc.c, libpawnc.c, etc.) that produce the executable output.
– Manages the translation of the parsed code into intermediate representations and eventually into AMX byte-code.
c. AMX Runtime (Virtual Machine):
– Housed in source/amx which includes amx.c, amx.h, along with numerous supportive files handling different aspects (e.g., debugging, file and process operations, fixed-point, floating-point).
– Contains modules for execution (including JIT components such as amxjitr.asm and amxjits.asm) and even a dedicated runner in the pawnrun folder.
d. Supporting Libraries and Includes:
– The include directory provides various header files that define constants, default behaviors, and utility routines (e.g., core.inc, string.inc).
e. Testing and Examples:
– The examples directory and source/compiler/tests folder provide a set of sample Pawn scripts and tests to ensure the compiler operates as expected.
f. Documentation and Build Configurations:
– The doc and xml folders, along with various configuration files (like CMakeLists.txt, Travis CI, AppVeyor configuration files), relate to code documentation, toolchain setup, and continuous integration.

##### Relationships and Interactions
- The flow starts with the user’s Pawn source code (often derived from examples or real projects) that is processed by the compiler front-end.
- The front-end feeds the parsed information to the back-end which compiles the input into AMX byte-code.
- The generated byte-code is then executed by the AMX VM engine.
- There are clear interactions (data flow) between:
– Source Code → Compiler Front-End (scanning/parsing)
– Compiler Front-End → Compiler Back-End (semantic analysis, symbol resolution)
– Back-End → AMX VM (code generation and linking to runtime)
- Auxiliary routines (from include and support libraries) are used throughout this cycle.
- The testing modules ensure these interactions function correctly and detect any regression issues.

##### Architectural Patterns and Design Principles
- The project separates the concerns between compilation and execution. The distinction between the “compiler” (source/compiler) and the “runtime engine” (source/amx) allows for modular development.
- The design suggests layered architecture where the front-end, middle-end (semantic analysis), and back-end (code generation) are separate components.
- There is a heavy emphasis on modularity and testability – as seen in the extensive tests for different language features and error cases.

##### Final Checklist for the Principal Software Engineer
– Ensure that all elements (major modules, build systems, and documentation/testing components) are included.
– Provide labels that reference the specific files or directories when possible (for example, “source/compiler – core compiler logic” and “source/amx – runtime engine”).
– Be detailed but structured, separating each logical block rather than creating a single monolithic block.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Pawn Source Code (Pawn scripts)"]:::input

    subgraph "Compilation Pipeline"
        B["Compiler Front-End (Lexer/Parser: sc1.c–sc7.c, sc.h, sclist.c, scstate.c, scstub.c, scvars.c)"]:::compiler
        C["Semantic Analysis & IR"]:::compiler
        D["Compiler Back-End (pawncc.c, libpawnc.c, pawndisasm.c, pawnruns.c)"]:::compiler
        E["AMX Virtual Machine (Runtime & JIT: amx.c, amx.h, amxdbg.c, amxjitr.asm, amxjits.asm)"]:::runtime
    end

    F["Utility Libraries & Headers (include)"]:::utility

    subgraph "Testing & Examples"
        G1["Examples (Pawn scripts)"]:::testing
        G2["Tests (e.g., __emit*.pwn, gh_*, run_tests.py)"]:::testing
    end

    H["Documentation & Build/CI (doc, xml, CMakeLists.txt, .travis.yml, appveyor.yml, .github)"]:::documentation

    A -->|"process"| B
    B -->|"parse"| C
    C -->|"analyze"| D
    D -->|"generate_bytecode"| E

    F ---|"supports"| B
    F ---|"supports"| D

    G1 -->|"seed_input"| A
    G2 -->|"validate"| B
    G2 -->|"validate"| D

    H ---|"guides"| D
    H ---|"guides"| E

    click B "https://github.com/pawn-lang/compiler/tree/master/source/compiler"
    click D "https://github.com/pawn-lang/compiler/tree/master/source/compiler"
    click E "https://github.com/pawn-lang/compiler/tree/master/source/amx"
    click F "https://github.com/pawn-lang/compiler/tree/master/include"
    click G1 "https://github.com/pawn-lang/compiler/tree/master/examples"
    click G2 "https://github.com/pawn-lang/compiler/tree/master/source/compiler/tests"
    click H "https://github.com/pawn-lang/compiler/tree/master/doc"

    classDef input fill:#cccccc,stroke:#333,stroke-width:2px;
    classDef compiler fill:#ffcccc,stroke:#990000,stroke-width:2px;
    classDef runtime fill:#cce5ff,stroke:#003366,stroke-width:2px;
    classDef utility fill:#ccffcc,stroke:#008000,stroke-width:2px;
    classDef testing fill:#ffe6cc,stroke:#cc6600,stroke-width:2px;
    classDef documentation fill:#e6ccff,stroke:#660099,stroke-width:2px;
```
