Skip to content

Commit 9db83e7

Browse files
belikhbelikh
authored
Merge pull request #5 from belikh/docs-site-generation-14544479219713522191
Generate comprehensive documentation site for GitHub Pages
2 parents 2f722d4 + 5eaab32 commit 9db83e7

17 files changed

Lines changed: 730 additions & 5 deletions

‎ARCHITECTURE.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# System Architecture
2+
3+
## Overview
4+
5+
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.
6+
7+
## High-Level Diagram
8+
9+
```mermaid
10+
graph TD
11+
User[User] --> Finder[Finder / MiniFinder]
12+
Finder --> Toolbox[Macintosh Toolbox]
13+
Toolbox --> OS[Operating System Core]
14+
OS --> Drivers[Device Drivers]
15+
Drivers --> Hardware[Macintosh Hardware (m68k)]
16+
```
17+
18+
## Core Components
19+
20+
### 1. Operating System (OS)
21+
The kernel of the system, located in the `OS/` directory. It manages hardware resources and provides fundamental services:
22+
- **Memory Manager:** Manages the application heap and system memory.
23+
- **Process Manager:** Implements cooperative multitasking.
24+
- **File System (HFS):** Hierarchical File System support.
25+
- **Trap Dispatcher:** The mechanism that routes Toolbox calls to their implementations.
26+
27+
### 2. Toolbox
28+
A collection of high-level APIs located across `OS/`, `Interfaces/`, and `Libs/`. It provides the building blocks for Macintosh applications:
29+
- **Window Manager:** Manages on-screen windows.
30+
- **Menu Manager:** Handles drop-down menus.
31+
- **QuickDraw:** The graphics primitive library.
32+
- **Event Manager:** Handles user input (mouse, keyboard).
33+
34+
### 3. Drivers
35+
Located in `Drivers/`, these modules handle low-level hardware interaction:
36+
- **Sony:** Floppy disk driver.
37+
- **Video:** Display drivers.
38+
- **IOP/ADB:** Input/Output Processors and Apple Desktop Bus for peripherals.
39+
40+
### 4. Build System
41+
The project uses a cross-compilation strategy:
42+
- **Host:** Linux.
43+
- **Toolchain:** MPW (Macintosh Programmer's Workshop) running under `empw` emulation.
44+
- **Configuration:** `.make` files in the `Make/` directory define dependencies and build rules.
45+
46+
## Data Flow
47+
The system operates primarily on an event-driven model:
48+
1. **Hardware Interrupts:** Input devices trigger interrupts.
49+
2. **OS Event Queue:** The OS places these events into a queue.
50+
3. **Event Loop:** The active application (e.g., Finder) polls `WaitNextEvent`.
51+
4. **Dispatch:** The application processes the event and calls Toolbox functions to update the display or state.
52+
53+
## Key Directories
54+
55+
| Directory | Description |
56+
|-----------|-------------|
57+
| `OS/` | Core system components (Memory, Process, HFS). |
58+
| `Drivers/` | Hardware drivers. |
59+
| `Interfaces/` | Public SDK headers (C, Pascal, Assembly). |
60+
| `Internal/` | Private headers and stub implementations. |
61+
| `Make/` | Build configuration files. |
62+
| `Libs/` | Static libraries linked into the final system. |

‎README.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Apple Mac OS 7.1 Source Code
2+
3+
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.
4+
5+
**Disclaimer:** This code is for research and educational purposes only.
6+
7+
## Documentation
8+
9+
Full documentation for this project is available in the `docs/` directory and can be browsed online (once GitHub Pages is enabled).
10+
11+
* [**Home**](docs/index.md)
12+
* [**Getting Started**](docs/getting-started.md)
13+
* [**Architecture**](docs/architecture.md)
14+
* [**Development Guide**](docs/development-guide.md)
15+
16+
## Quick Start
17+
18+
1. **Clone** this repository.
19+
2. **Install Prerequisites:** `empw`, `hfsutils`, `build-essential`.
20+
3. **Setup:** Run `./cross_compile.sh` to prepare the environment.
21+
4. **Build:** Run `./build_system7.sh` to compile the system.
22+
23+
See [Getting Started](docs/getting-started.md) for detailed instructions.

‎README.txt‎

Lines changed: 0 additions & 5 deletions
This file was deleted.

‎docs/_config.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Simple Jekyll configuration
2+
theme: jekyll-theme-minimal
3+
title: Mac OS 7.1 Source Docs
4+
description: Documentation for the Mac OS 7.1 Source Code Reconstruction

‎docs/architecture.md‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
# System Architecture
2+
3+
This document provides a detailed overview of the Macintosh System 7.1 architecture as implemented in this repository.
4+
5+
## Architectural Style
6+
7+
The system follows a **Monolithic Kernel** design combined with a **Toolbox** API layer.
8+
- **Monolithic:** The core OS services (Memory, Process, File System) run in a single address space (privileged mode on 680x0).
9+
- **Toolbox:** A rich library of high-level services (Windows, Menus, Controls) that applications link against or call via the Trap Dispatcher.
10+
- **Cooperative Multitasking:** The Process Manager switches tasks only when an application explicitly yields control (e.g., calling `WaitNextEvent`).
11+
12+
## Component Diagram
13+
14+
```mermaid
15+
graph TB
16+
subgraph User Space
17+
App[Application]
18+
Finder[Finder / MiniFinder]
19+
end
20+
21+
subgraph Toolbox Layer
22+
WM[Window Manager]
23+
MM[Menu Manager]
24+
QD[QuickDraw]
25+
Dlg[Dialog Manager]
26+
end
27+
28+
subgraph OS Layer
29+
Trap[Trap Dispatcher]
30+
PM[Process Manager]
31+
Mem[Memory Manager]
32+
HFS[File System (HFS)]
33+
Res[Resource Manager]
34+
end
35+
36+
subgraph Hardware Abstraction
37+
Drivers[Device Drivers]
38+
ADB[ADB Manager]
39+
SCSI[SCSI Manager]
40+
end
41+
42+
subgraph Hardware
43+
CPU[m68k CPU]
44+
RAM[Memory]
45+
Disk[Disk Drive]
46+
Video[Video Card]
47+
end
48+
49+
App --> WM
50+
App --> MM
51+
App --> QD
52+
Finder --> WM
53+
54+
WM --> Trap
55+
MM --> Trap
56+
57+
Trap --> PM
58+
Trap --> Mem
59+
Trap --> Res
60+
61+
Res --> HFS
62+
HFS --> SCSI
63+
SCSI --> Drivers
64+
Drivers --> Hardware
65+
```
66+
67+
## Key Data Flows
68+
69+
### Application Launch
70+
1. **User Action:** User double-clicks an icon in the Finder.
71+
2. **Finder:** Calls `LaunchApplication`.
72+
3. **Process Manager:**
73+
* Allocates a partition in memory for the new application.
74+
* Loads the code segments (CODE resources) from the executable file.
75+
* Sets up the A5 world (globals and jump table).
76+
* Transfers control to the application's entry point.
77+
78+
### Event Processing
79+
1. **Hardware:** Mouse move or Key press triggers an interrupt.
80+
2. **ISR:** Interrupt Service Routine stores raw event data.
81+
3. **OS Event Manager:** Converts raw data into an `EventRecord` and places it in the System Event Queue.
82+
4. **Application:** Calls `WaitNextEvent`.
83+
5. **OS:** Moves the event from the System Queue to the Application's Event Queue and returns it to the app.
84+
6. **Application:** Dispatches the event to the appropriate handler (e.g., `HandleClick`).
85+
86+
## Module Interaction
87+
88+
* **Trap Dispatcher:** The central hub. All Toolbox calls (A-Traps) go through the dispatch table to find the implementation address in ROM or RAM.
89+
* **Memory Manager:** Fundamental dependency. Almost every other module (Drivers, Toolbox, Process Mgr) needs to allocate memory blocks (pointers or handles).
90+
* **Resource Manager:** The primary data loading mechanism. Code, dialogs, strings, and fonts are all loaded as resources.
91+
92+
## Build Architecture
93+
94+
The build system transforms source code into a "System" file (technically a suitcase of resources).
95+
96+
```mermaid
97+
graph LR
98+
Src[Source Code (.c, .p, .a)] --> Compiler[MPW Compilers]
99+
Compiler --> Obj[Object Files (.o)]
100+
Obj --> Linker[MPW Linker]
101+
Linker --> CodeRes[CODE Resources]
102+
ResSrc[Resource Definitions (.r)] --> Rez[Rez Compiler]
103+
Rez --> Rsrc[Resource Files (.rsrc)]
104+
CodeRes --> System[System File]
105+
Rsrc --> System
106+
```

‎docs/configuration.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Configuration
2+
3+
This document explains the build configuration system for the repository.
4+
5+
## Build System Overview
6+
The build is driven by MPW `Make` tools. Configuration is primarily defined in `.make` files located in the `Make/` directory.
7+
8+
## Key Configuration Files
9+
10+
### `Make/MainCode.Make` / `Make/Universal.make`
11+
The master makefile.
12+
* **Defines:** Source directories, include paths, build options.
13+
* **Rules:** How to compile C, Pascal, and Assembly files.
14+
* **Link List:** The list of object files to link into the final system image.
15+
16+
### `Make/Build.txt`
17+
Likely defines build versioning or specific build targets.
18+
19+
## Environment Variables
20+
21+
The `cross_compile.sh` and `build_system7.sh` scripts set up the following environment variables for `empw`:
22+
23+
| Variable | Description |
24+
|----------|-------------|
25+
| `MPW` | Root of the MPW tools directory. |
26+
| `KS_MPW` | Alias for `MPW` (used by `empw`). |
27+
| `BuildResults` | Output directory for artifacts (`Build/`). |
28+
| `ObjDir` | Directory for intermediate object files. |
29+
| `AIncludes` | Path to public Assembly includes. |
30+
| `CIncludes` | Path to public C includes. |
31+
| `IntAIncludes` | Path to internal Assembly includes. |
32+
33+
## Feature Flags and Defines
34+
Conditional compilation is handled via compiler flags passed in the Makefile (e.g., `-d DEBUG`).
35+
36+
* **debug:** Enables debug symbols and assertions.
37+
* **uni:** Likely refers to "Universal" build (supporting multiple machines).
38+
39+
## Patching
40+
The `patch_makefile.sh` script dynamically modifies `Make/MainCode.Make` to inject dependencies.
41+
* **Mechanism:** Appends lines to the end of the file.
42+
* **Purpose:** To add `MiniFinder.c.o`, `VirtualMemoryStub.c.o`, etc., without manually editing the complex makefile.
43+
44+
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‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# Data Models
2+
3+
This document outlines key data structures and memory models used in System 7.1.
4+
5+
## Memory Models
6+
7+
### The Heap
8+
Memory is divided into heaps.
9+
* **System Heap:** Persistent memory for OS and Drivers.
10+
* **Application Heap:** Volatile memory for the currently running application.
11+
12+
**Data Types:**
13+
* **Ptr:** A direct pointer to a block of memory.
14+
* **Handle:** A pointer to a master pointer. Allows the Memory Manager to move the underlying block (relocate it) to reduce fragmentation without invalidating references.
15+
16+
### Resources
17+
Data is often stored in the Resource Fork of a file.
18+
* **Map:** Index of resources in the file.
19+
* **Data:** The actual binary data.
20+
* **Types:** 4-character codes (e.g., `'CODE'`, `'DLOG'`, `'WIND'`).
21+
22+
## Core Entities
23+
24+
### WindowRecord (`WindowPtr`)
25+
Represents a window on the screen.
26+
* `port`: The graphics port (GrafPort) for drawing.
27+
* `windowKind`: Type of window (dialog, desk accessory, etc.).
28+
* `visible`: Boolean visibility flag.
29+
* `refCon`: Arbitrary data storage for the application.
30+
31+
### DialogRecord (`DialogPtr`)
32+
Extends WindowRecord for dialog boxes.
33+
* `items`: Handle to the item list (controls, text).
34+
* `textH`: Handle to the current text edit record.
35+
36+
### EventRecord
37+
Represents a user or system event.
38+
* `what`: Event type (mouseDown, keyDown, updateEvt).
39+
* `message`: Event-specific data (key code, window pointer).
40+
* `when`: Timestamp (ticks since boot).
41+
* `where`: Mouse coordinates.
42+
* `modifiers`: State of Shift, Cmd, Option keys.
43+
44+
### File System Catalog
45+
* **CatNode:** A node in the HFS B-Tree (File or Folder).
46+
* **FInfo:** File metadata (Type, Creator, location).
47+
48+
## Schema Diagram (Conceptual)
49+
50+
```mermaid
51+
classDiagram
52+
class EventRecord {
53+
+int what
54+
+long message
55+
+long when
56+
+Point where
57+
+int modifiers
58+
}
59+
60+
class WindowRecord {
61+
+GrafPort port
62+
+short windowKind
63+
+boolean visible
64+
+boolean hilited
65+
+long refCon
66+
}
67+
68+
class DialogRecord {
69+
+WindowRecord window
70+
+Handle items
71+
+TEHandle textH
72+
}
73+
74+
class FileInfo {
75+
+OSType fdType
76+
+OSType fdCreator
77+
+short fdFlags
78+
+Point fdLocation
79+
}
80+
81+
DialogRecord --|> WindowRecord : Extends
82+
EventRecord ..> WindowRecord : References
83+
```

‎docs/deployment.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Deployment
2+
3+
This guide explains how to deploy the built system artifacts.
4+
5+
## Build Artifacts
6+
After a successful build, the `Build/` directory will contain:
7+
* **System:** The main system file (resource suitcase).
8+
* **Finder:** The Finder application (or MiniFinder if linked).
9+
* **ROM Images:** (If applicable) ROM builds.
10+
11+
## Deployment Targets
12+
13+
### 1. Macintosh Emulator (Recommended)
14+
You can test the build using emulators like **Mini vMac**, **BasiliskII**, or **MAME**.
15+
16+
**Steps:**
17+
1. Create a blank HFS disk image using `hfsutils` (or `dd` and `mkfs.hfs`).
18+
```bash
19+
dd if=/dev/zero of=System7.img bs=1M count=10
20+
/usr/sbin/hformat -l "System 7" System7.img
21+
```
22+
2. Copy the built `System` and `Finder` binaries into the image.
23+
```bash
24+
hmount System7.img
25+
hmkdir "System Folder"
26+
hcopy Build/System ":System Folder:System"
27+
hcopy Build/Finder ":System Folder:Finder"
28+
# Bless the System Folder
29+
hattrib -b ":System Folder"
30+
humount
31+
```
32+
3. Configure your emulator to mount `System7.img` as the boot drive.
33+
34+
### 2. Real Hardware
35+
To deploy to a real Macintosh (e.g., SE/30, IIci):
36+
1. Write the disk image to a floppy disk or SD card (scsi2sd).
37+
2. Or, use a bridge machine to copy the files over LocalTalk/Ethernet.
38+
39+
## Publishing Documentation
40+
This documentation site is designed to be published via **GitHub Pages**.
41+
42+
### Setup
43+
1. Go to the repository **Settings** on GitHub.
44+
2. Navigate to **Pages**.
45+
3. Under **Source**, select **Deploy from a branch**.
46+
4. Select the **main** branch and the **/docs** folder.
47+
5. Click **Save**.
48+
49+
The site will be available at `https://<username>.github.io/<repo-name>/`.

0 commit comments

Comments
 (0)