# nickwanninger/alaska architecture

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

- Interactive diagram: https://gitdiagram.com/nickwanninger/alaska
- Repository: https://github.com/nickwanninger/alaska

## Overview

##### Major Components
- Compiler Front-End & Driver: Represented by the “compiler” directory. This contains the compiler executables in the “bin” folder, compiler header files under “include” and “ldscripts,” and build configuration via CMakeLists.txt. Emphasize that Alaska is designed to work as a drop-in replacement for clang.
- Compiler Passes & Optimizations: Under “compiler/passes” and “compiler/lib” you have custom passes (e.g., normalization, type inference, translation printer) that extend the compiler’s behavior. Identify these as a set of optimization and transformation modules which integrate with the front-end.
- Runtime System: Indicate the “runtime” directory as the module responsible for memory management. It contains “core” (which implements fundamental functions such as heap, thread cache, and object allocation), “include” for header definitions, “rt” for the runtime library glue code, and even specialized modules like “sim” and “yukon” for target-specific functionality.
- Test Suite: The huge “test” directory serves as the regression and correctness test bed. Represent it as a separate component which validates the behavior of both the compiler and the runtime.
- Tools & Utilities: Located in “tools,” include benchmarking notebooks, build scripts (e.g. for RISC-V and Yukon), and plotting utilities. These support building, profiling, and performance evaluation.
- Build & Dependency Management: Capture the build system (Makefile, CMakeLists.txt) and note the dependency management options (nix flakes, “make deps”) which are important for ensuring the correct versions of clang, llvm 16, and gclang are in use.

##### Relationships and Data Flow
- The Compiler Component consumes source code from the user and, using the custom passes (performing type inference, pointer flow analysis, and other translations), produces an executable that is instrumented to use handle‐based memory.
- The runtime system is linked (statically or dynamically) during compilation and at load time (via LD_PRELOAD for Yukon configurations) to provide actual memory management services.
- The build system (with CMake and nix) orchestrates the compilation of both the compiler modules and the runtime library.
- Tools interact with both the built compiler and runtime library to benchmark, test, and optimize performance.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Clearly divide the compiler’s transformation passes from the runtime’s memory management functionalities.

##### Relevant Technologies and Frameworks
- Integration with LLVM infrastructure (clang, llvm 16) and gclang.
- Build and dependency management tools such as CMake/Make and Nix.
- For the runtime, show the production of shared libraries (e.g., runtime/libyukon.so.2) and the dynamic linking process.

##### Final Touches
- Annotations that mention dependency on clang/llvm16, usage of gclang, and specific notes about the Yukon build for RISCV.
- Components are interconnected in a way that visually presents the entire project lifecycle: from code input to compilation (with custom compiler passes) to runtime memory management, and finally to testing and performance evaluation using the provided tools.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Nodes
    SC("Source Code Input"):::input

    %% Compiler Layer
    subgraph "Compiler Layer"
        CF("Compiler Front-End & Driver"):::compiler
        CP1("Compiler Passes"):::compiler
        CP2("Compiler Lib Extensions"):::compiler
        BIN("Instrumented Executable\n(Handle-based Memory)"):::binary
    end

    %% Runtime Layer
    subgraph "Runtime Layer"
        RT1("Core Memory Management"):::runtime
        RT2("Header Definitions (Include)"):::runtime
        RT3("Runtime Library Glue Code"):::runtime
        RT4("Sim Module"):::runtime
        RT5("Yukon Module"):::runtime
    end

    %% Build & Dependency Management
    subgraph "Build & Management"
        BUILD("Build System\n(CMake, Make, Nix)"):::build
    end

    %% Tools & Testing
    subgraph "Tools & Testing"
        TOOLS("Tools & Utilities\n(Benchmark, Scripts)"):::tools
        TEST("Test Suite"):::test
    end

    %% Connections - Compiler Flow
    SC -->|"compiles"| CF
    CF -->|"invokes"| CP1
    CF -->|"invokes"| CP2
    CP1 -->|"generates"| BIN
    CP2 -->|"generates"| BIN

    %% Connections - Runtime Flow
    BIN -->|"links to"| RT1
    RT1 -->|"defines"| RT2
    RT1 -->|"connects to"| RT3
    RT1 -->|"interfaces with"| RT4
    RT1 -->|"interfaces with"| RT5

    %% Build System Relationships
    BUILD -->|"orchestrates"| CF
    BUILD -->|"orchestrates"| RT1

    %% Tools & Testing Relationships
    TOOLS -->|"analyzes"| CF
    TOOLS -->|"monitors"| RT1
    TEST -->|"validates"| CF
    TEST -->|"validates"| RT1

    %% Annotations for integration with clang/llvm16/gclang
    CF ---|"drop-in_for_clang"| CP1
    BUILD ---|"dependency_management"| CP2

    %% Click Events for Compiler Components
    click CF "https://github.com/nickwanninger/alaska/tree/main/compiler/"
    click CP1 "https://github.com/nickwanninger/alaska/tree/main/compiler/passes/"
    click CP2 "https://github.com/nickwanninger/alaska/tree/main/compiler/lib/"

    %% Click Events for Runtime Components
    click RT1 "https://github.com/nickwanninger/alaska/tree/main/runtime/core/"
    click RT2 "https://github.com/nickwanninger/alaska/tree/main/runtime/include/"
    click RT3 "https://github.com/nickwanninger/alaska/tree/main/runtime/rt/"
    click RT4 "https://github.com/nickwanninger/alaska/tree/main/runtime/sim/"
    click RT5 "https://github.com/nickwanninger/alaska/tree/main/runtime/yukon/"
    click RT1 "https://github.com/nickwanninger/alaska/tree/main/runtime/"

    %% Click Events for Build & Dependency Management
    click BUILD "https://github.com/nickwanninger/alaska/blob/main/CMakeLists.txt"
    click BUILD "https://github.com/nickwanninger/alaska/blob/main/compiler/CMakeLists.txt"
    click BUILD "https://github.com/nickwanninger/alaska/blob/main/runtime/CMakeLists.txt"
    click BUILD "https://github.com/nickwanninger/alaska/tree/main/Makefile"
    click BUILD "https://github.com/nickwanninger/alaska/blob/main/flake.nix"
    click BUILD "https://github.com/nickwanninger/alaska/blob/main/flake.lock"

    %% Click Events for Tools & Test Suite
    click TOOLS "https://github.com/nickwanninger/alaska/tree/main/tools/"
    click TEST "https://github.com/nickwanninger/alaska/tree/main/test/"
    click TEST "https://github.com/nickwanninger/alaska/tree/main/runtime/test/"

    %% Style Classes
    classDef compiler fill:#FFD700,stroke:#DAA520,stroke-width:2px;
    classDef runtime fill:#ADD8E6,stroke:#00008B,stroke-width:2px;
    classDef build fill:#90EE90,stroke:#006400,stroke-width:2px;
    classDef tools fill:#FFB6C1,stroke:#FF69B4,stroke-width:2px;
    classDef input fill:#D3D3D3,stroke:#696969,stroke-width:2px;
    classDef binary fill:#FFA500,stroke:#FF4500,stroke-width:2px;
    classDef test fill:#E6E6FA,stroke:#800080,stroke-width:2px;
```
