Generate comprehensive documentation site for GitHub Pages

ARCHITECTURE.md

@@ -0,0 +1,62 @@
+# System Architecture
+
+## Overview
+
+This repository contains the source code for a reconstruction of Macintosh System Software 7.1. It is designed to be cross-compiled on Linux targeting the Motorola 680x0 (m68k) architecture. The system follows the classic Macintosh "Toolbox" architecture, where the Operating System serves as a foundation for a rich set of user interface and system service APIs.
+
+## High-Level Diagram
+
+```mermaid
+graph TD
+    User[User] --> Finder[Finder / MiniFinder]
+    Finder --> Toolbox[Macintosh Toolbox]
+    Toolbox --> OS[Operating System Core]
+    OS --> Drivers[Device Drivers]
+    Drivers --> Hardware[Macintosh Hardware (m68k)]
+```
+
+## Core Components
+
+### 1. Operating System (OS)
+The kernel of the system, located in the `OS/` directory. It manages hardware resources and provides fundamental services:
+- **Memory Manager:** Manages the application heap and system memory.
+- **Process Manager:** Implements cooperative multitasking.
+- **File System (HFS):** Hierarchical File System support.
+- **Trap Dispatcher:** The mechanism that routes Toolbox calls to their implementations.
+
+### 2. Toolbox
+A collection of high-level APIs located across `OS/`, `Interfaces/`, and `Libs/`. It provides the building blocks for Macintosh applications:
+- **Window Manager:** Manages on-screen windows.
+- **Menu Manager:** Handles drop-down menus.
+- **QuickDraw:** The graphics primitive library.
+- **Event Manager:** Handles user input (mouse, keyboard).
+
+### 3. Drivers
+Located in `Drivers/`, these modules handle low-level hardware interaction:
+- **Sony:** Floppy disk driver.
+- **Video:** Display drivers.
+- **IOP/ADB:** Input/Output Processors and Apple Desktop Bus for peripherals.
+
+### 4. Build System
+The project uses a cross-compilation strategy:
+- **Host:** Linux.
+- **Toolchain:** MPW (Macintosh Programmer's Workshop) running under `empw` emulation.
+- **Configuration:** `.make` files in the `Make/` directory define dependencies and build rules.
+
+## Data Flow
+The system operates primarily on an event-driven model:
+1.  **Hardware Interrupts:** Input devices trigger interrupts.
+2.  **OS Event Queue:** The OS places these events into a queue.
+3.  **Event Loop:** The active application (e.g., Finder) polls `WaitNextEvent`.
+4.  **Dispatch:** The application processes the event and calls Toolbox functions to update the display or state.
+
+## Key Directories
+
+| Directory | Description |
+|-----------|-------------|
+| `OS/` | Core system components (Memory, Process, HFS). |
+| `Drivers/` | Hardware drivers. |
+| `Interfaces/` | Public SDK headers (C, Pascal, Assembly). |
+| `Internal/` | Private headers and stub implementations. |
+| `Make/` | Build configuration files. |
+| `Libs/` | Static libraries linked into the final system. |

README.md

@@ -0,0 +1,23 @@
+# Apple Mac OS 7.1 Source Code
+
+This repository contains the source code of Macintosh System Software 7.1 (m68k architecture). It is a reconstruction aimed at enabling cross-compilation on modern Linux systems.
+
+**Disclaimer:** This code is for research and educational purposes only.
+
+## Documentation
+
+Full documentation for this project is available in the `docs/` directory and can be browsed online (once GitHub Pages is enabled).
+
+*   [**Home**](docs/index.md)
+*   [**Getting Started**](docs/getting-started.md)
+*   [**Architecture**](docs/architecture.md)
+*   [**Development Guide**](docs/development-guide.md)
+
+## Quick Start
+
+1.  **Clone** this repository.
+2.  **Install Prerequisites:** `empw`, `hfsutils`, `build-essential`.
+3.  **Setup:** Run `./cross_compile.sh` to prepare the environment.
+4.  **Build:** Run `./build_system7.sh` to compile the system.
+
+See [Getting Started](docs/getting-started.md) for detailed instructions.

docs/_config.yml

@@ -0,0 +1,4 @@
+# Simple Jekyll configuration
+theme: jekyll-theme-minimal
+title: Mac OS 7.1 Source Docs
+description: Documentation for the Mac OS 7.1 Source Code Reconstruction

docs/architecture.md

@@ -0,0 +1,106 @@
+# System Architecture
+
+This document provides a detailed overview of the Macintosh System 7.1 architecture as implemented in this repository.
+
+## Architectural Style
+
+The system follows a **Monolithic Kernel** design combined with a **Toolbox** API layer.
+-   **Monolithic:** The core OS services (Memory, Process, File System) run in a single address space (privileged mode on 680x0).
+-   **Toolbox:** A rich library of high-level services (Windows, Menus, Controls) that applications link against or call via the Trap Dispatcher.
+-   **Cooperative Multitasking:** The Process Manager switches tasks only when an application explicitly yields control (e.g., calling `WaitNextEvent`).
+
+## Component Diagram
+
+```mermaid
+graph TB
+    subgraph User Space
+        App[Application]
+        Finder[Finder / MiniFinder]
+    end
+
+    subgraph Toolbox Layer
+        WM[Window Manager]
+        MM[Menu Manager]
+        QD[QuickDraw]
+        Dlg[Dialog Manager]
+    end
+
+    subgraph OS Layer
+        Trap[Trap Dispatcher]
+        PM[Process Manager]
+        Mem[Memory Manager]
+        HFS[File System (HFS)]
+        Res[Resource Manager]
+    end
+
+    subgraph Hardware Abstraction
+        Drivers[Device Drivers]
+        ADB[ADB Manager]
+        SCSI[SCSI Manager]
+    end
+
+    subgraph Hardware
+        CPU[m68k CPU]
+        RAM[Memory]
+        Disk[Disk Drive]
+        Video[Video Card]
+    end
+
+    App --> WM
+    App --> MM
+    App --> QD
+    Finder --> WM
+
+    WM --> Trap
+    MM --> Trap
+
+    Trap --> PM
+    Trap --> Mem
+    Trap --> Res
+
+    Res --> HFS
+    HFS --> SCSI
+    SCSI --> Drivers
+    Drivers --> Hardware
+```
+
+## Key Data Flows
+
+### Application Launch
+1.  **User Action:** User double-clicks an icon in the Finder.
+2.  **Finder:** Calls `LaunchApplication`.
+3.  **Process Manager:**
+    *   Allocates a partition in memory for the new application.
+    *   Loads the code segments (CODE resources) from the executable file.
+    *   Sets up the A5 world (globals and jump table).
+    *   Transfers control to the application's entry point.
+
+### Event Processing
+1.  **Hardware:** Mouse move or Key press triggers an interrupt.
+2.  **ISR:** Interrupt Service Routine stores raw event data.
+3.  **OS Event Manager:** Converts raw data into an `EventRecord` and places it in the System Event Queue.
+4.  **Application:** Calls `WaitNextEvent`.
+5.  **OS:** Moves the event from the System Queue to the Application's Event Queue and returns it to the app.
+6.  **Application:** Dispatches the event to the appropriate handler (e.g., `HandleClick`).
+
+## Module Interaction
+
+*   **Trap Dispatcher:** The central hub. All Toolbox calls (A-Traps) go through the dispatch table to find the implementation address in ROM or RAM.
+*   **Memory Manager:** Fundamental dependency. Almost every other module (Drivers, Toolbox, Process Mgr) needs to allocate memory blocks (pointers or handles).
+*   **Resource Manager:** The primary data loading mechanism. Code, dialogs, strings, and fonts are all loaded as resources.
+
+## Build Architecture
+
+The build system transforms source code into a "System" file (technically a suitcase of resources).
+
+```mermaid
+graph LR
+    Src[Source Code (.c, .p, .a)] --> Compiler[MPW Compilers]
+    Compiler --> Obj[Object Files (.o)]
+    Obj --> Linker[MPW Linker]
+    Linker --> CodeRes[CODE Resources]
+    ResSrc[Resource Definitions (.r)] --> Rez[Rez Compiler]
+    Rez --> Rsrc[Resource Files (.rsrc)]
+    CodeRes --> System[System File]
+    Rsrc --> System
+```

docs/configuration.md

@@ -0,0 +1,44 @@
+# Configuration
+
+This document explains the build configuration system for the repository.
+
+## Build System Overview
+The build is driven by MPW `Make` tools. Configuration is primarily defined in `.make` files located in the `Make/` directory.
+
+## Key Configuration Files
+
+### `Make/MainCode.Make` / `Make/Universal.make`
+The master makefile.
+*   **Defines:** Source directories, include paths, build options.
+*   **Rules:** How to compile C, Pascal, and Assembly files.
+*   **Link List:** The list of object files to link into the final system image.
+
+### `Make/Build.txt`
+Likely defines build versioning or specific build targets.
+
+## Environment Variables
+
+The `cross_compile.sh` and `build_system7.sh` scripts set up the following environment variables for `empw`:
+
+| Variable | Description |
+|----------|-------------|
+| `MPW` | Root of the MPW tools directory. |
+| `KS_MPW` | Alias for `MPW` (used by `empw`). |
+| `BuildResults` | Output directory for artifacts (`Build/`). |
+| `ObjDir` | Directory for intermediate object files. |
+| `AIncludes` | Path to public Assembly includes. |
+| `CIncludes` | Path to public C includes. |
+| `IntAIncludes` | Path to internal Assembly includes. |
+
+## Feature Flags and Defines
+Conditional compilation is handled via compiler flags passed in the Makefile (e.g., `-d DEBUG`).
+
+*   **debug:** Enables debug symbols and assertions.
+*   **uni:** Likely refers to "Universal" build (supporting multiple machines).
+
+## Patching
+The `patch_makefile.sh` script dynamically modifies `Make/MainCode.Make` to inject dependencies.
+*   **Mechanism:** Appends lines to the end of the file.
+*   **Purpose:** To add `MiniFinder.c.o`, `VirtualMemoryStub.c.o`, etc., without manually editing the complex makefile.
+
+To change the configuration manually, you can edit `Make/MainCode.Make` (carefully, preserving line endings and encoding) or modify the `patch_makefile.sh` script.

docs/data-models.md

@@ -0,0 +1,83 @@
+# Data Models
+
+This document outlines key data structures and memory models used in System 7.1.
+
+## Memory Models
+
+### The Heap
+Memory is divided into heaps.
+*   **System Heap:** Persistent memory for OS and Drivers.
+*   **Application Heap:** Volatile memory for the currently running application.
+
+**Data Types:**
+*   **Ptr:** A direct pointer to a block of memory.
+*   **Handle:** A pointer to a master pointer. Allows the Memory Manager to move the underlying block (relocate it) to reduce fragmentation without invalidating references.
+
+### Resources
+Data is often stored in the Resource Fork of a file.
+*   **Map:** Index of resources in the file.
+*   **Data:** The actual binary data.
+*   **Types:** 4-character codes (e.g., `'CODE'`, `'DLOG'`, `'WIND'`).
+
+## Core Entities
+
+### WindowRecord (`WindowPtr`)
+Represents a window on the screen.
+*   `port`: The graphics port (GrafPort) for drawing.
+*   `windowKind`: Type of window (dialog, desk accessory, etc.).
+*   `visible`: Boolean visibility flag.
+*   `refCon`: Arbitrary data storage for the application.
+
+### DialogRecord (`DialogPtr`)
+Extends WindowRecord for dialog boxes.
+*   `items`: Handle to the item list (controls, text).
+*   `textH`: Handle to the current text edit record.
+
+### EventRecord
+Represents a user or system event.
+*   `what`: Event type (mouseDown, keyDown, updateEvt).
+*   `message`: Event-specific data (key code, window pointer).
+*   `when`: Timestamp (ticks since boot).
+*   `where`: Mouse coordinates.
+*   `modifiers`: State of Shift, Cmd, Option keys.
+
+### File System Catalog
+*   **CatNode:** A node in the HFS B-Tree (File or Folder).
+*   **FInfo:** File metadata (Type, Creator, location).
+
+## Schema Diagram (Conceptual)
+
+```mermaid
+classDiagram
+    class EventRecord {
+        +int what
+        +long message
+        +long when
+        +Point where
+        +int modifiers
+    }
+
+    class WindowRecord {
+        +GrafPort port
+        +short windowKind
+        +boolean visible
+        +boolean hilited
+        +long refCon
+    }
+
+    class DialogRecord {
+        +WindowRecord window
+        +Handle items
+        +TEHandle textH
+    }
+
+    class FileInfo {
+        +OSType fdType
+        +OSType fdCreator
+        +short fdFlags
+        +Point fdLocation
+    }
+
+    DialogRecord --|> WindowRecord : Extends
+    EventRecord ..> WindowRecord : References
+```

docs/deployment.md

@@ -0,0 +1,49 @@
+# Deployment
+
+This guide explains how to deploy the built system artifacts.
+
+## Build Artifacts
+After a successful build, the `Build/` directory will contain:
+*   **System:** The main system file (resource suitcase).
+*   **Finder:** The Finder application (or MiniFinder if linked).
+*   **ROM Images:** (If applicable) ROM builds.
+
+## Deployment Targets
+
+### 1. Macintosh Emulator (Recommended)
+You can test the build using emulators like **Mini vMac**, **BasiliskII**, or **MAME**.
+
+**Steps:**
+1.  Create a blank HFS disk image using `hfsutils` (or `dd` and `mkfs.hfs`).
+    ```bash
+    dd if=/dev/zero of=System7.img bs=1M count=10
+    /usr/sbin/hformat -l "System 7" System7.img
+    ```
+2.  Copy the built `System` and `Finder` binaries into the image.
+    ```bash
+    hmount System7.img
+    hmkdir "System Folder"
+    hcopy Build/System ":System Folder:System"
+    hcopy Build/Finder ":System Folder:Finder"
+    # Bless the System Folder
+    hattrib -b ":System Folder"
+    humount
+    ```
+3.  Configure your emulator to mount `System7.img` as the boot drive.
+
+### 2. Real Hardware
+To deploy to a real Macintosh (e.g., SE/30, IIci):
+1.  Write the disk image to a floppy disk or SD card (scsi2sd).
+2.  Or, use a bridge machine to copy the files over LocalTalk/Ethernet.
+
+## Publishing Documentation
+This documentation site is designed to be published via **GitHub Pages**.
+
+### Setup
+1.  Go to the repository **Settings** on GitHub.
+2.  Navigate to **Pages**.
+3.  Under **Source**, select **Deploy from a branch**.
+4.  Select the **main** branch and the **/docs** folder.
+5.  Click **Save**.
+
+The site will be available at `https://<username>.github.io/<repo-name>/`.