# vigna/fastutil architecture

> Architecture diagram of the GitHub repository vigna/fastutil, 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/vigna/fastutil
- Repository: https://github.com/vigna/fastutil

## Overview

##### Main Components
- Core Library Components: Represent the core data structures (lists, maps, sets, queues, etc.) and algorithms that fastutil provides. You might group these by type (e.g., “Primitive Collections,” “Object Collections” and “Big Arrays/Lists”).
- Driver/Preprocessor Module: Show the “drv” directory and related scripts (like gencsource.sh) that generate the Java sources. This is a critical subsystem because fastutil uses a C preprocessor to customize and generate its source code.
- Build and Packaging Infrastructure: Illustrate the build tools and scripts (Ant’s build.xml, makefile, Ivy’s ivy.xml, Maven POM files, bnd scripts) which collectively manage compiling, testing, and packaging into different jars (fastutil-core.jar and fastutil.jar). Also include the split.sh script used for creating the two jar distributions.
- Testing Suite: Include the “test” directory as a distinct component, highlighting unit tests for the various data structures and utilities provided by the library.
- Integration/Examples and Additional Artifacts: Optionally, highlight the “guava” tests and any integration tests in the “src/it” directory that demonstrate interoperability with other libraries.

- Link the Testing Suite to the Core Library to denote that tests validate the performance and correctness of all data structures and algorithms.

##### Architectural Patterns and Design Principles
- The separation-of-concerns is clearly visible—the library code is generated separately from the driver (code generation) and then built and packaged using a well-defined build system.
- Modular design: fastutil splits its distribution into two jars so that its “core” functionalities and additional utilities are separated for convenience in dependency management.
- Use of code generation via conditional compilation: this can be shown as a pre-build stage that produces the optimized, type-specific Java code from more generic drivers.

##### Relevant Technologies and Tools
- Java: The programming language and runtime.
- Apache Ant / Maven / Ivy: For building, dependency management, and packaging.
- Bnd: For OSGi packaging of components.
- Shell Scripts (gencsource.sh, split.sh, find-deps.sh): For code generation and dependency analysis.
- JUnit (and Hamcrest): For unit testing.
- JDeps: As noted in the README, used in the dependency analysis for generating a custom jar.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Driver/Preprocessor Layer
    subgraph "Driver/Preprocessor Layer"
        A("Driver/Preprocessor (drv)"):::driver
    end

    %% Core Library Layer
    subgraph "Core Library Layer"
        B("Core Library (src/it/unimi/dsi/fastutil)"):::core
    end

    %% Build and Packaging Layer
    subgraph "Build and Packaging Layer"
        subgraph "Build Tools"
            C1("Ant Build (build.xml)"):::build
            C2("Make Build (makefile)"):::build
            C3("Ivy Config (ivy.xml)"):::build
            C4("Maven Core (pom-core-model.xml)"):::build
            C5("Maven Model (pom-model.xml)"):::build
            C6("Split Script (split.sh)"):::build
            C7("Bnd Scripts (bnd)"):::build
        end
        E("Build Process Completed"):::build
        D("Packaged JARs (fastutil-core.jar, fastutil.jar)"):::build
    end

    %% Testing Layer
    subgraph "Testing Layer"
        T("Test Suite (test/it/unimi/dsi/fastutil)"):::test
        I("Integration Tests (guava/it/unimi/dsi/fastutil)"):::integration
    end

    %% Arrows depicting flow
    A -->|"generates"| B
    B -->|"compiles"| C1
    B -->|"compiles"| C2
    B -->|"compiles"| C3
    B -->|"compiles"| C4
    B -->|"compiles"| C5
    B -->|"compiles"| C6
    B -->|"compiles"| C7
    C7 -->|"aggregates"| E
    E -->|"packages"| D
    E -->|"runs"| T
    T -->|"feedback"| E
    E -->|"integration"| I

    %% Click Events
    click A "https://github.com/vigna/fastutil/tree/master/drv"
    click B "https://github.com/vigna/fastutil/tree/master/src/it/unimi/dsi/fastutil"
    click C1 "https://github.com/vigna/fastutil/blob/master/build.xml"
    click C2 "https://github.com/vigna/fastutil/tree/master/makefile"
    click C3 "https://github.com/vigna/fastutil/blob/master/ivy.xml"
    click C4 "https://github.com/vigna/fastutil/blob/master/pom-core-model.xml"
    click C5 "https://github.com/vigna/fastutil/blob/master/pom-model.xml"
    click C6 "https://github.com/vigna/fastutil/blob/master/split.sh"
    click C7 "https://github.com/vigna/fastutil/tree/master/bnd"
    click T "https://github.com/vigna/fastutil/tree/master/test/it/unimi/dsi/fastutil"
    click I "https://github.com/vigna/fastutil/tree/master/guava/it/unimi/dsi/fastutil"

    %% Styles
    classDef driver fill:#bbf,stroke:#333,stroke-width:2px;
    classDef core fill:#f9c,stroke:#333,stroke-width:2px;
    classDef build fill:#afa,stroke:#333,stroke-width:2px;
    classDef test fill:#ff9,stroke:#333,stroke-width:2px;
    classDef integration fill:#fcc,stroke:#333,stroke-width:2px;
```
