Homemade Tiny OS

Homemade Tiny OS is a Tiny OS simulation project that runs in host user space.
Its goal is not to build a fake system that only works for screenshots, but a miniature operating system project with real internal state, clear module boundaries, persistence, test constraints, and room for continuous extension.

This project does not aim for bare-metal boot or pretend to be a real kernel. It focuses on questions such as:

• how a virtual disk is initialized, expanded, and persisted
• how the file system organizes paths, directory entries, and inodes
• how processes and the scheduler are modeled
• how the Shell routes user input into internal system call interfaces
• how errors, permissions, observability, and recovery are built up step by step

Project Positioning

This is both a teaching-oriented and an engineering-oriented project.

It should preserve strong operating-system learning value while avoiding the trap of rebuilding everything from scratch for its own sake.

So the basic principles are:

• core operating-system abstractions must be implemented by the project itself
• mature libraries may be used for general-purpose low-level capabilities that are not the teaching focus
• no third-party library should directly swallow the whole file system, scheduler, or Shell

For example:

• an index structure such as a B+ Tree can use a mature library
• but the directory indexing interface, VFS, path resolution, block mapping, and persistence strategy must all be defined and controlled by this project

Current Stage

Current project progress:

• Phase 1: project skeleton and test baseline, completed
• Phase 2: expandable virtual disk and block device, in progress
• Phase 3 and later: see docs/

For the detailed roadmap, see:

• Overall PRD
• Task List
• Project Tree
• Git Workflow
• Quick Start

Design Principles

1. TDD First

The project is intended to move forward with test-driven development by default:

1. write the test first
2. implement the minimum solution
3. refactor after the test turns green

A feature without corresponding tests should not be considered stably complete.

2. User-Space Simulation, but Internal State Must Be Real

Shell commands must not fake functionality by calling host commands.
For example:

• do not use os.system("ls") to pretend you implemented ls
• do not treat the host file system directly as the Tiny OS file system

All user-visible behavior should land in Tiny OS's own internal objects and APIs.

3. Expand in Small Steps and Avoid Overwriting the Host Disk

The virtual disk uses:

• a small initial capacity
• fixed-step expansion
• a clear hard upper limit
• expansion only when needed

This preserves the realism of a growing disk while avoiding uncontrolled writes to the host SSD.

Runtime Artifacts and Virtual Disk Locations

The "disk" in this project is not a real host partition, but an image file managed by Tiny OS itself.

By default:

• manually started examples use tinyos.disk in the project root
• demo scripts under scripts/ write disk files into scripts/.artifacts/
• automated tests under tests/ write disk files into tests/.artifacts/

The repository ignores these runtime disk artifacts by default:

• tinyos.disk
• *.disk
• tests/.artifacts/

That means virtual disks stay in the local debugging environment and are not committed by mistake.

For more detailed guidance, including:

• which .disk files are used by different scripts
• how these disk files should be cleaned up
• which persistent states are affected if they are deleted

See the "Virtual Disk Location and Cleanup" section in QUICKSTART.md.

Recommended Directory Structure

See project-tree.md for the current target structure.

The core layout is roughly:

Homemade-Tiny-OS/
├── docs/
├── src/
│   └── tinyos/
│       ├── kernel/
│       ├── storage/
│       ├── vfs/
│       ├── memory/
│       ├── shell/
│       └── observability/
└── tests/
    ├── unit/
    ├── integration/
    └── e2e/

Phase Roadmap

Phase 1: Project Skeleton and Test Baseline

Goals:

• stabilize the package structure
• stabilize the configuration object
• stabilize a unified error model
• establish a minimal test baseline

Phase 2: Expandable Virtual Disk and Block Device

Goals:

• create disk images
• support repeated open operations
• provide fixed-block read/write
• support growth by fixed increments
• reject requests beyond the hard limit

Phase 3: Virtual File System and Metadata Indexing

Goals:

• path resolution
• inodes and directory entries
• file read/write
• directory index integration
• persistence and recovery

Phase 4: Process Scheduling, Shell, and System Introspection

Goals:

• cooperative scheduler
• Shell REPL
• ps, kill, top, sysstat, dmesg

Phase 5: Reliability, Permissions, and Extensibility

Goals:

• permission model
• out-of-space protection
• consistency and recovery
• plugin-style command extensions

Development Workflow

Environment Requirements

• Python 3.13+

Local Testing

The project currently uses the standard-library unittest runner as the most stable default entry point:

python3 -B -m unittest discover -s tests -p 'test_*.py'

If needed later, pytest can be added to improve the developer experience, but the mainline test path should not depend on a complicated external environment.

Git Commit Rhythm

Recommended commit granularity:

• commit after one phase is completed
• commit after a key group of tests turns green
• commit after an important interface is stabilized

Do not mix a large number of unrelated changes into one commit.

See git-workflow.md for more detailed rules.

What Is Already Implemented

At the current stage, the project already includes:

• the base src layout
• TinyOSConfig
• a unified error hierarchy
• the ExpandableVirtualDisk skeleton and the Phase 2 development entry point
• VirtualFileSystem / KernelScheduler / Shell / KernelStats skeletons
• the Phase 1 unit-test baseline

Immediate Next Focus

The next most important step is to make storage/disk.py a stable foundational block-device layer.
If this layer is unstable, the later VFS, persistence, and recovery work will all become unstable as well.

Documentation Index

• Tiny OS PRD
• Project Tree
• Task List
• Git Workflow
• Phase 1
• Phase 2
• Phase 3
• Phase 4
• Phase 5