# mikexwang/mini_jvm architecture

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

- Interactive diagram: https://gitdiagram.com/mikexwang/mini_jvm
- Repository: https://github.com/mikexwang/mini_jvm

## Overview

##### Project type and purpose
- This is a **mini Java Virtual Machine** implementation in C, aimed at resource-constrained devices (iOS, Android, embedded). It includes:
- A Java class library ported from CLDC1.1 (in `javalib/`)
- A C-based JVM engine (`mini_jvm/jvm/`) plus utilities (`mini_jvm/utils/`)
- A Swift iOS test harness (`mini_jvm/iostest/`)
- A minimal Java test suite (`javalib_test/`)

##### File structure
- Top-level:
- `javalib/` – Java source (foundation classes) + NetBeans build artifacts
- `javalib_test/` – Java test stubs + build files
- `mini_jvm/` – CMake project with subfolders:
– `jvm/` (core JVM source)
– `utils/` (data structures, memory-leak detector, charsets, containers)
– `iostest/` (Xcode Swift app for runtime verification)
- Configuration/build:
- `javalib/build.xml` – Ant build for Java classes
- `mini_jvm/CMakeLists.txt` – CMake for native code
- `.gitignore`/`.gitattributes`

##### README for insights
- Supports Java class file versions 5–8, threads (pthread), GC, JDWP remote debug, native methods, I/O, networking
- Build instructions:
- Java classes via NetBeans/Ant → output to `javalib/build/classes/`
- Native engine via CLion/CMake → `mini_jvm` executable/library
- iOS via Xcode Swift project linking `mini_jvm`

##### Main components
a. **Java Class Library (javalib)**
– Packages: `java.*`, `javax.*`, `com.sun.cldc.*`
b. **Java Test Suite (javalib_test)**
– Minimal stubs for test classes
c. **JVM Engine (mini_jvm/jvm)**
– Class Loader (`class_load.c`)
– Bytecode Interpreter (`interpreter.c`)
– Garbage Collector (`garbage.c`)
– Runtime support (`runtime.c`, `global.c`)
– Native method bridge (`java_native_*.c`)
– Debug interface (`jdwp.c`)
– Platform abstraction (`os_linux.c`, `os_win.c`)
d. **Utility Library (mini_jvm/utils)**
– Data containers: arraylist, hashtable, hashset, linkedlist, spinlock
– UTF-8 string handling
– Memory-leak detector (`cmem`)
– Compression/miniz
e. **iOS Swift Test App (mini_jvm/iostest)**
– Swift wrapper that embeds or calls the `mini_jvm` library
– UI layer (ViewController) to load/run a Java class
f. **Build/Toolchain**
– Java: NetBeans/Ant, JDK 1.8
– C: CMake, Clang/GCC, pthread
– Swift: Xcode, LLVM 9

##### Relationships and data flows
- **Build pipeline**
- Java sources → compiled to `.class` files → packaged under `javalib/build/classes/`
- C sources → compiled by CMake → produces `mini_jvm` binary (CLI or library)
- Swift project links against `mini_jvm` as a static/dynamic library
- **Runtime flow**
1. **Launcher** (CLI or Swift) invokes the JVM engine
2. **Class Loader** reads `.class` files from classpath
3. **Bytecode Interpreter** executes methods, invokes **native bridges** when needed
4. **Garbage Collector** reclaims memory periodically
5. **JDWP Module** opens a debug socket (port 8000) for remote debugger clients
6. **Thread Scheduler** maps Java threads to OS threads (pthreads)
7. **I/O & Network** calls flow through `java_native_io.c` → OS APIs

##### Architectural patterns & design principles
- **Modular separation**: class library vs. VM engine vs. utilities vs. test harness
- **Layered design**:
- Presentation (CLI or Swift UI)
- VM Runtime (loader → interpreter → GC → JNI)
- Native OS abstraction (pthread, socket, file system)
- **Plug-in/debug port**: JDWP layer sits between interpreter and network stack
- **Reusability**: utilities folder is shared code for containers and memory checks

- Clear component names and boundaries
- External interfaces (OS threads, file system, network)
- Build tools and outputs as ancillary artifacts

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Java Class Library
    subgraph "Java Class Library" 
        direction TB
        JSL_SRC["Source packages\n(javalib/src/java/…, javalib/src/javax/…, javalib/src/com/sun/cldc/)"]:::java
        JSL_BUILDXML["Build script\nbuild.xml"]:::java
        JSL_CLASSES["Compiled classes\n(build/classes/)"]:::java
    end

    %% Java Test Suite
    subgraph "Java Test Suite"
        direction TB
        JTS_SRC["Source stubs & tests\n(src/java/…, src/test/)"]:::java
        JTS_BUILDXML["Build script\nbuild.xml"]:::java
        JTS_CLASSES["Compiled tests\n(build/classes/)"]:::java
    end

    %% JVM Engine
    subgraph "JVM Engine (C)" 
        direction TB
        JE_ENTRY["Entry point\njvm.c/jvm_util.c"]:::c
        JE_LOADER["Class Loader\nclass_load.c"]:::c
        JE_INTERP["Bytecode Interpreter\ninterpreter.c"]:::c
        JE_GC["Garbage Collector\ngarbage.c/h"]:::c
        JE_RUNTIME["Runtime Support\nruntime.c, global.c"]:::c
        JE_NATIVE["Native Method Bridges\njava_native_io.c/.h,\njava_native_std.c/.h,\njava_native_reflect.c/.h"]:::c
        JE_JDWP["Debug Interface\njdwp.c/.h"]:::c
        JE_OS["Platform Abstraction\nos_linux.c, os_win.c"]:::c
    end

    %% Utility Library
    subgraph "Utility Library (C)" 
        direction TB
        UL_CONTAINERS["Containers\narraylist, hashtable, hashset,\nlinkedlist, pairlist"]:::c
        UL_SYNC["Synchronization\nspinlock"]:::c
        UL_UTF8["UTF-8 Strings\nutf8_string"]:::c
        UL_CMEM["Memory Detector\ncmem/"]:::c
        UL_MINIZ["Compression\nminiz/"]:::c
    end

    %% iOS Test App
    subgraph "iOS Swift Test App" 
        direction TB
        IOS_UI["Swift UI & Logic\nViewController.swift,\nAppDelegate.swift"]:::swift
        IOS_CBRIDGE["C Bridge\ninvokec.c"]:::c
        IOS_PROJ["Project Files\n.xcodeproj/"]:::swift
        IOS_TESTS["Tests & Resources\niostestTests/, UITests/"]:::swift
    end

    %% Build & Toolchain
    subgraph "Build & Toolchain"
        direction TB
        BT_CMAKE["CMake Configuration\nCMakeLists.txt"]:::external
        BT_GIT["Git Settings\n.gitignore, .gitattributes"]:::external
        BT_README["README.md"]:::external
    end

    %% Build pipeline
    JSL_SRC -->|".class files"| JSL_CLASSES
    JSL_BUILDXML -->|builds| JSL_CLASSES
    JTS_SRC -->|".class files"| JTS_CLASSES
    JTS_BUILDXML -->|builds| JTS_CLASSES
    BT_CMAKE -->|compiles C| JE_ENTRY

    %% Runtime invocation
    JE_ENTRY -->|"launch"| JE_LOADER
    JE_LOADER -->|"bytecode stream"| JE_INTERP
    JE_INTERP -->|"executes"| JE_RUNTIME
    JE_RUNTIME -->|"alloc/free"| JE_GC
    JE_INTERP -->|"invoke native"| JE_NATIVE
    JE_NATIVE -->|"OS calls"| JE_OS
    JE_OS -->|"pthread calls"| JE_ENTRY

    %% JDWP Debug Channel
    JE_JDWP -->|"JDWP packets"| Network[(TCP Socket)]:::external

    %% Swift linking
    IOS_CBRIDGE -->|"links"| JE_ENTRY
    IOS_UI -->|calls| IOS_CBRIDGE
    IOS_PROJ -->|contains| IOS_UI

    %% Classpath linkage
    JSL_CLASSES -->|"classpath"| JE_LOADER
    JTS_CLASSES -->|"classpath"| JE_LOADER

    %% Util library usage
    UL_CONTAINERS -->|used by| JE_RUNTIME
    UL_SYNC -->|used by| JE_OS
    UL_UTF8 -->|used by| JE_LOADER
    UL_CMEM -->|monitors| JE_ENTRY
    UL_MINIZ -->|compress| JE_RUNTIME

    %% Build tools grouping
    BT_GIT --> BT_README

    %% Click Events
    click JSL_SRC "https://github.com/mikexwang/mini_jvm/tree/master/javalib/src/"
    click JSL_BUILDXML "https://github.com/mikexwang/mini_jvm/blob/master/javalib/build.xml"
    click JSL_CLASSES "https://github.com/mikexwang/mini_jvm/tree/master/javalib/build/classes/"
    click JTS_SRC "https://github.com/mikexwang/mini_jvm/tree/master/javalib_test/src/"
    click JTS_BUILDXML "https://github.com/mikexwang/mini_jvm/blob/master/javalib_test/build.xml"
    click JTS_CLASSES "https://github.com/mikexwang/mini_jvm/tree/master/javalib_test/build/classes/"
    click JE_LOADER "https://github.com/mikexwang/mini_jvm/blob/master/mini_jvm/jvm/class_load.c"
    click JE_INTERP "https://github.com/mikexwang/mini_jvm/blob/master/mini_jvm/jvm/interpreter.c"
    click JE_GC "https://github.com/mikexwang/mini_jvm/blob/master/mini_jvm/jvm/garbage.c"
    click JE_RUNTIME "https://github.com/mikexwang/mini_jvm/blob/master/mini_jvm/jvm/runtime.c"
    click JE_NATIVE "https://github.com/mikexwang/mini_jvm/blob/master/mini_jvm/jvm/java_native_io.c"
    click JE_JDWP "https://github.com/mikexwang/mini_jvm/blob/master/mini_jvm/jvm/jdwp.c"
    click JE_OS "https://github.com/mikexwang/mini_jvm/blob/master/mini_jvm/jvm/os_linux.c"
    click JE_ENTRY "https://github.com/mikexwang/mini_jvm/blob/master/mini_jvm/jvm/jvm.c"
    click UL_CONTAINERS "https://github.com/mikexwang/mini_jvm/blob/master/mini_jvm/utils/arraylist.c"
    click UL_SYNC "https://github.com/mikexwang/mini_jvm/blob/master/mini_jvm/utils/spinlock.c"
    click UL_UTF8 "https://github.com/mikexwang/mini_jvm/blob/master/mini_jvm/utils/utf8_string.c"
    click UL_CMEM "https://github.com/mikexwang/mini_jvm/tree/master/mini_jvm/utils/cmem/"
    click UL_MINIZ "https://github.com/mikexwang/mini_jvm/tree/master/mini_jvm/utils/miniz/"
    click IOS_UI "https://github.com/mikexwang/mini_jvm/blob/master/mini_jvm/iostest/iostest/ViewController.swift"
    click IOS_CBRIDGE "https://github.com/mikexwang/mini_jvm/blob/master/mini_jvm/iostest/invokec.c"
    click IOS_PROJ "https://github.com/mikexwang/mini_jvm/tree/master/mini_jvm/iostest/iostest.xcodeproj/"
    click IOS_TESTS "https://github.com/mikexwang/mini_jvm/tree/master/mini_jvm/iostest/iostestTests/"
    click BT_CMAKE "https://github.com/mikexwang/mini_jvm/blob/master/mini_jvm/CMakeLists.txt"

    %% Styles
    classDef java fill:#cfe2f3,stroke:#2a6592,color:#0b3d91
    classDef c fill:#d9ead3,stroke:#6aa84f,color:#274e13
    classDef swift fill:#fce5cd,stroke:#e69138,color:#974f0c
    classDef external fill:#ebebeb,stroke:#a0a0a0,color:#333333
```
