# pietroalbini/plinky architecture

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

- Interactive diagram: https://gitdiagram.com/pietroalbini/plinky
- Repository: https://github.com/pietroalbini/plinky

## Overview

##### Project Type and Purpose
- plinky is a systems‐level, command‐line ELF linker (compiler‐toolchain component) targeting x86 and x86-64 Linux.
- It’s structured as a Rust “workspace” with multiple crates providing:
- The main linker binary (plinky)
- ELF parsing & writing (plinky_elf)
- Archive reading (.a files) (plinky_ar)
- pkg‐config emulation (plinky_pkg_config)
- Diagnostics & pretty‐printing (plinky_diagnostics)
- Macros & utilities (plinky_macros, plinky_utils)
- A test harness (plinky_test_harness)

##### Key Architectural Components
a. CLI Frontend (plinky crate)
- Modules: cli::lexer, cli::parser
- Entry point: main.rs → parser → builds a CliInput structure
b. Input Loaders
- plinky_ar: reads .a archives, exposes object file streams
- plinky_pkg_config: simulates pkg‐config to discover linker flags
- plinky_elf: reads individual ELF object files, yields in‐memory representations
c. Intermediate Representation (plinky/src/repr)
- Uniform in‐memory model of segments, sections, symbols, relocations
d. Linker Core (plinky/src/linker.rs & passes/)
- Passes pipeline:
1. load_inputs (read objects, merge archives, run pkg‐config)
2. analyze_relocations, convert_modes
3. merge_sections, deduplicate, layout sections & segments
4. generate_dynamic, build_elf (sections, symbols, string tables, hash tables)
5. inject symbol table, GC sections, RELRO/stack flags
6. write_to_disk
e. Diagnostics & Debugging
- plinky_diagnostics: builders, contexts, widgets render errors/warnings
- debug_print: visual inspect of in‐memory ELF layout and GC data
f. Utilities & Macros
- plinky_utils: common algorithms (bitfields, Jaro similarity, shell quoting)
- plinky_macros / plinky_macros_quote: custom derive & parser utilities

##### Interactions & Data Flow
- User invokes `plinky` CLI → parse flags/inputs
- plinky uses plinky_pkg_config to expand –l flags
- plinky_ar opens archives → yields object file paths/streams
- plinky_elf parses each ELF object → yields ReprObject structs
- Passes sequentially transform a global ReprProgram:
- load_inputs → merge sections → analyze relocations → layout segments
- build_elf → produces final ELF bytes
- write_to_disk writes the output executable
- On errors, plinky_diagnostics formats and emits diagnostics

##### Architectural Patterns & Principles
- Modular crate decomposition (single‐responsibility crates)
- Pipeline/chain‐of‐responsibility for linker passes
- Clear separation between parsing, representation, transformation, and emission
- No heavy external build/run‐time dependencies (self‐contained)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External
    FS["File System"]:::external
    PKGDATA["pkg-config Data"]:::external

    %% Input Providers
    subgraph "Input Providers"
        PC["plinky_pkg_config"]:::crate
        AR["plinky_ar"]:::crate
    end

    %% Core Libraries
    subgraph "Core Libraries"
        ELF["plinky_elf"]:::crate
        subgraph "plinky (Linker)"
            CLI["CLI Frontend"]:::crate
            REPR["Intermediate Repr"]:::crate
            subgraph "Passes Pipeline"
                P1["1. load_inputs"]:::pass
                P2["2. analyze_relocations"]:::pass
                P3["3. merge_sections"]:::pass
                P4["4. layout_segments"]:::pass
                P5["5. build_elf"]:::pass
                P6["6. write_to_disk"]:::pass
            end
            DP["Debug Print"]:::crate
            DIAG["Diagnostics"]:::crate
        end
    end

    %% Support
    subgraph "Support Crates"
        DIAGLIB["plinky_diagnostics"]:::utils
        UTILS["plinky_utils"]:::utils
        MACROS["plinky_macros"]:::utils
        QUOTE["plinky_macros_quote"]:::utils
        TEST["plinky_test_harness"]:::utils
    end

    %% Data Flow
    User["User"]:::external
    User -->|"invokes plinky"| CLI
    CLI -->|"expand flags"| PC
    PC -->|"flags"| CLI
    CLI -->|"reads archives"| AR
    AR -->|"streams"| CLI
    CLI -->|"parses ELF"| ELF
    ELF -->|"ReprObject"| REPR
    REPR --> P1
    P1 --> P2
    P2 --> P3
    P3 --> P4
    P4 --> P5
    P5 --> P6
    P6 --> FS
    P1 -->|errors| DIAG
    DIAG --> DIAGLIB
    CLI --> DIAGLIB
    CLI --> UTILS
    CLI --> MACROS
    CLI --> QUOTE
    TEST --> CLI

    %% Click events plinky
    click CLI "https://github.com/pietroalbini/plinky/blob/main/plinky/src/main.rs"
    click CLI "https://github.com/pietroalbini/plinky/blob/main/plinky/src/cli/mod.rs"
    click CLI "https://github.com/pietroalbini/plinky/blob/main/plinky/src/cli/lexer.rs"
    click CLI "https://github.com/pietroalbini/plinky/blob/main/plinky/src/cli/parser.rs"
    click ELF "https://github.com/pietroalbini/plinky/blob/main/plinky_elf/src/lib.rs"
    click AR "https://github.com/pietroalbini/plinky/blob/main/plinky_ar/src/lib.rs"
    click PC "https://github.com/pietroalbini/plinky/blob/main/plinky_pkg_config/src/lib.rs"
    click PC "https://github.com/pietroalbini/plinky/blob/main/plinky_pkg_config/src/lexer.rs"
    click PC "https://github.com/pietroalbini/plinky/blob/main/plinky_pkg_config/src/parser.rs"
    click PC "https://github.com/pietroalbini/plinky/blob/main/plinky_pkg_config/src/discover.rs"
    click PC "https://github.com/pietroalbini/plinky/blob/main/plinky_pkg_config/src/template.rs"
    click PC "https://github.com/pietroalbini/plinky/blob/main/plinky_pkg_config/src/types.rs"
    click DIAGLIB "https://github.com/pietroalbini/plinky/blob/main/plinky_diagnostics/src/diagnostic.rs"
    click DIAGLIB "https://github.com/pietroalbini/plinky/blob/main/plinky_diagnostics/src/builder.rs"
    click DIAGLIB "https://github.com/pietroalbini/plinky/blob/main/plinky_diagnostics/src/widgets/group.rs"
    click DIAGLIB "https://github.com/pietroalbini/plinky/blob/main/plinky_diagnostics/src/widgets/hex_dump.rs"
    click DIAGLIB "https://github.com/pietroalbini/plinky/blob/main/plinky_diagnostics/src/widgets/quoted_text.rs"
    click DIAGLIB "https://github.com/pietroalbini/plinky/blob/main/plinky_diagnostics/src/widgets/table.rs"
    click DIAGLIB "https://github.com/pietroalbini/plinky/blob/main/plinky_diagnostics/src/widgets/text.rs"
    click UTILS "https://github.com/pietroalbini/plinky/blob/main/plinky_utils/src/lib.rs"
    click UTILS "https://github.com/pietroalbini/plinky/blob/main/plinky_utils/src/bitfields.rs"
    click UTILS "https://github.com/pietroalbini/plinky/blob/main/plinky_utils/src/jaro_similarity.rs"
    click UTILS "https://github.com/pietroalbini/plinky/blob/main/plinky_utils/src/posix_shell.rs"
    click UTILS "https://github.com/pietroalbini/plinky/blob/main/plinky_utils/src/quote.rs"
    click UTILS "https://github.com/pietroalbini/plinky/blob/main/plinky_utils/src/ints.rs"
    click UTILS "https://github.com/pietroalbini/plinky/blob/main/plinky_utils/src/filters_parser.rs"
    click UTILS "https://github.com/pietroalbini/plinky/blob/main/plinky_utils/src/raw_types.rs"
    click UTILS "https://github.com/pietroalbini/plinky/blob/main/plinky_utils/src/tempdir.rs"
    click MACROS "https://github.com/pietroalbini/plinky/blob/main/plinky_macros/src/utils.rs"
    click MACROS "https://github.com/pietroalbini/plinky/blob/main/plinky_macros/src/error.rs"
    click MACROS "https://github.com/pietroalbini/plinky/blob/main/plinky_macros/src/parser/attributes.rs"
    click MACROS "https://github.com/pietroalbini/plinky/blob/main/plinky_macros/src/parser/types.rs"
    click MACROS "https://github.com/pietroalbini/plinky/blob/main/plinky_macros/src/parser/utils.rs"
    click MACROS "https://github.com/pietroalbini/plinky/blob/main/plinky_macros/src/derives/bitfield.rs"
    click MACROS "https://github.com/pietroalbini/plinky/blob/main/plinky_macros/src/derives/display.rs"
    click MACROS "https://github.com/pietroalbini/plinky/blob/main/plinky_macros/src/derives/error.rs"
    click MACROS "https://github.com/pietroalbini/plinky/blob/main/plinky_macros/src/derives/getters.rs"
    click MACROS "https://github.com/pietroalbini/plinky/blob/main/plinky_macros/src/derives/raw_type.rs"
    click QUOTE "https://github.com/pietroalbini/plinky/blob/main/plinky_macros_quote/src/lib.rs"
    click TEST "https://github.com/pietroalbini/plinky/blob/main/plinky_test_harness/src/lib.rs"
    click TEST "https://github.com/pietroalbini/plinky/blob/main/plinky_test_harness/src/steps/ar.rs"
    click TEST "https://github.com/pietroalbini/plinky/blob/main/plinky_test_harness/src/steps/asm.rs"
    click TEST "https://github.com/pietroalbini/plinky/blob/main/plinky_test_harness/src/steps/c.rs"
    click TEST "https://github.com/pietroalbini/plinky/blob/main/plinky_test_harness/src/steps/dir.rs"
    click TEST "https://github.com/pietroalbini/plinky/blob/main/plinky_test_harness/src/steps/ld.rs"
    click TEST "https://github.com/pietroalbini/plinky/blob/main/plinky_test_harness/src/steps/rename.rs"
    click TEST "https://github.com/pietroalbini/plinky/blob/main/plinky_test_harness/src/steps/rust.rs"
    click TEST "https://github.com/pietroalbini/plinky/blob/main/plinky_test_harness/src/template/lexer.rs"
    click TEST "https://github.com/pietroalbini/plinky/blob/main/plinky_test_harness/src/template/parser.rs"
    click TEST "https://github.com/pietroalbini/plinky/blob/main/plinky_test_harness/src/template/functions.rs"
    click TEST "https://github.com/pietroalbini/plinky/blob/main/plinky_test_harness/src/template/serde.rs"
    click TEST "https://github.com/pietroalbini/plinky/blob/main/plinky_test_harness/src/utils.rs"
    click TEST "https://github.com/pietroalbini/plinky/blob/main/plinky_test_harness/src/tests.rs"

    %% Styles
    classDef crate fill:#cce5ff,stroke:#004085,color:#004085;
    classDef pass fill:#d4edda,stroke:#155724,color:#155724;
    classDef utils fill:#fff3cd,stroke:#856404,color:#856404;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    class CLI,REPR,ELF,PC,AR,DIAGLIB,UTILS,MACROS,QUOTE,TEST crate;
    class P1,P2,P3,P4,P5,P6 pass;
    class FS,PKGDATA,User external;
```
