# tgrysztar/fasm2 architecture

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

- Interactive diagram: https://gitdiagram.com/tgrysztar/fasm2
- Repository: https://github.com/tgrysztar/fasm2

## Overview

##### Project Type and Purpose
- This is an x86 assembler system – a compiler-like tool that assembles source code written in x86 assembly language. Its design emphasizes compatibility with fasm 1 (with some macro syntax changes) and supports multiple OS targets (DOS, Linux, macOS, and Windows).
- The project includes both the assembly “engine” (which reads, parses, and generates machine code) and an integrated set of headers and macros (in the “include” directory) that provide definitions for API calls, instruction sets, and other utilities.

##### Architectural Breakdown from the File Structure
- Executable Binaries: At the top level, you see executables (fasmg.exe, fasmg.x64, fasmgw.exe) and a command script (fasm2.cmd) that provide the command-line interfaces for different architectures or platforms.
- Examples: The “examples” folder holds various usage demonstrations showing how to employ the assembler in different environments (globstr, tetros, win64avx512). These examples indicate how users might integrate the assembler in real-life assembly coding scenarios.
- Directory: This dense directory holds various “inc” files which supply:
- API headers (e.g., kernel32, shell32, etc.)
- Encoding definitions, macro definitions, equates, file formats (COFF/ELF/PE/MACHO), and instruction set descriptions (e.g., SSE, AVX, MMX).
This component is akin to a standard library that the assembler utilizes to understand and expand source code.
- Source Directory: This is the heart of the assembler engine, broken down into several subcomponents:
- Core Processing Modules (“assembler.inc”, “expressions.inc”, “tables.inc”, “errors.inc”, etc.) – these are likely responsible for parsing the assembly source, managing symbols, computing expressions, and reporting errors.
- Platform-specific Backend Modules (in subdirectories such as “dos”, “linux”, “macos”, “windows”) – these modules tailor the assembly output and system calls to the target operating system.
- IDE Support Modules (under source/ide, including both common IDE code and Windows-specific modules) indicate an integrated development environment component, providing editing, navigation, and other UI-related capabilities.
- Additional libraries (source/libc) handle self-hosting aspects and system-level components likely needed during code generation or linkage.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Frontend Subgraph
    subgraph "Frontend"
        subgraph "CLI Launchers"
            cli1("fasmg.exe"):::cliExec
            cli2("fasmg.x64"):::cliExec
            cli3("fasmgw.exe"):::cliExec
            cli4("fasm2.cmd"):::cliExec
        end
        nodeIDE("IDE Integration"):::frontend
        nodeIDEWin("IDE Windows Module"):::frontend
    end

    %% Assembler Engine Subgraph
    subgraph "Assembler Engine"
        nodeParser("Assembler Parser"):::core
        nodeExpr("Expression Evaluator"):::core
        nodeSymbol("Symbol/Directive Handler"):::core
        nodeError("Error Reporting"):::core
    end

    %% Include Libraries
    subgraph "Include Libraries"
        includeLib("Include Library Headers"):::header
    end

    %% Platform-Specific Backends Subgraph
    subgraph "Platform-Specific Backends"
        nodeDOS("DOS Backend"):::backend
        nodeLinux("Linux Backend"):::backend
        nodeMac("macOS Backend"):::backend
        nodeWin("Windows Backend"):::backend

        subgraph "DOS Details"
            nodeDOSAsm("fasmg.asm"):::backendDetail
        end

        subgraph "Linux Details"
            nodeLinuxX64("x64 fasmg.asm"):::backendDetail
        end

        subgraph "macOS Details"
            nodeMacX64("x64 fasmg.asm"):::backendDetail
        end

        subgraph "Windows Details"
            nodeWinDLL("DLL fasmg.asm"):::backendDetail
        end
    end

    %% Examples Subgraph
    subgraph "Examples"
        nodeExamples("Examples/Demos"):::external
        nodeExampleGlob("globstr example"):::external
    end

    %% Connections from Frontend to Assembler Engine
    cli1 -->|"submits_source"| nodeParser
    cli2 -->|"submits_source"| nodeParser
    cli3 -->|"submits_source"| nodeParser
    cli4 -->|"submits_source"| nodeParser
    nodeIDE -->|"edits_and_submits"| nodeParser
    nodeIDEWin -->|"integrated_module"| nodeIDE

    %% Include Libraries provides definitions to Engine
    includeLib -- "provides_macros" --> nodeParser

    %% Assembler Engine Internal Pipeline
    nodeParser -->|"parses"| nodeExpr
    nodeExpr -->|"evaluates"| nodeSymbol
    nodeSymbol -->|"generates_output"| nodeError

    %% Assembler Engine outputs to Platform Backends
    nodeSymbol -->|"target_code"| nodeDOS
    nodeSymbol -->|"target_code"| nodeLinux
    nodeSymbol -->|"target_code"| nodeMac
    nodeSymbol -->|"target_code"| nodeWin

    %% Platform Backends Details
    nodeDOS --> nodeDOSAsm
    nodeLinux --> nodeLinuxX64
    nodeMac --> nodeMacX64
    nodeWin --> nodeWinDLL

    %% Examples integration
    nodeExamples -->|"demonstrates_usage"| nodeIDE
    nodeExamples --> nodeExampleGlob

    %% Click Events for Frontend
    click cli1 "https://github.com/tgrysztar/fasm2/blob/master/fasmg.exe"
    click cli2 "https://github.com/tgrysztar/fasm2/blob/master/fasmg.x64"
    click cli3 "https://github.com/tgrysztar/fasm2/blob/master/fasmgw.exe"
    click cli4 "https://github.com/tgrysztar/fasm2/blob/master/fasm2.cmd"
    click nodeIDE "https://github.com/tgrysztar/fasm2/tree/master/source/ide"
    click nodeIDEWin "https://github.com/tgrysztar/fasm2/blob/master/source/ide/windows/fasmg.inc"

    %% Click Events for Core Assembler Engine
    click nodeParser "https://github.com/tgrysztar/fasm2/blob/master/source/assembler.inc"
    click nodeExpr "https://github.com/tgrysztar/fasm2/blob/master/source/expressions.inc"
    click nodeSymbol "https://github.com/tgrysztar/fasm2/blob/master/source/tables.inc"
    click nodeError "https://github.com/tgrysztar/fasm2/blob/master/source/errors.inc"

    %% Click Events for Platform-Specific Backends
    click nodeDOS "https://github.com/tgrysztar/fasm2/tree/master/source/dos"
    click nodeDOSAsm "https://github.com/tgrysztar/fasm2/blob/master/source/dos/fasmg.asm"
    click nodeLinux "https://github.com/tgrysztar/fasm2/tree/master/source/linux"
    click nodeLinuxX64 "https://github.com/tgrysztar/fasm2/blob/master/source/linux/x64/fasmg.asm"
    click nodeMac "https://github.com/tgrysztar/fasm2/tree/master/source/macos"
    click nodeMacX64 "https://github.com/tgrysztar/fasm2/blob/master/source/macos/x64/fasmg.asm"
    click nodeWin "https://github.com/tgrysztar/fasm2/tree/master/source/windows"
    click nodeWinDLL "https://github.com/tgrysztar/fasm2/blob/master/source/windows/dll/fasmg.asm"

    %% Click Event for Include Libraries
    click includeLib "https://github.com/tgrysztar/fasm2/tree/master/include"

    %% Click Events for Examples
    click nodeExamples "https://github.com/tgrysztar/fasm2/tree/master/examples"
    click nodeExampleGlob "https://github.com/tgrysztar/fasm2/tree/master/examples/globstr"

    %% Class Definitions with Colors
    classDef frontend fill:#C8E6C9,stroke:#388E3C,stroke-width:2px;
    classDef cliExec fill:#AED581,stroke:#7CB342,stroke-width:2px;
    classDef core fill:#BBDEFB,stroke:#1976D2,stroke-width:2px;
    classDef backend fill:#C5E1A5,stroke:#558B2F,stroke-width:2px;
    classDef header fill:#F5F5F5,stroke:#BDBDBD,stroke-width:2px;
    classDef external fill:#FFECB3,stroke:#FFA000,stroke-width:2px;
    classDef backendDetail fill:#E6EE9C,stroke:#7CB342,stroke-width:2px;
```
