SageOS is a hybrid operating system that combines a low-level C kernel with a high-level, SageLang-driven runtime. It is designed to be modular, portable, and extensible across multiple architectures.

• Hybrid kernel architecture: C for performance, SageLang for system services, shell logic, and runtime extensions.
• Multi-architecture support: x64, ARM64, and RV64 ports are maintained as submodules under arch/.
• Custom SageLang runtime: A bespoke MetalVM interpreter enables safe SageLang execution inside the OS.
• Forked third-party networking stacks: lwip and mbedtls are integrated as custom submodule forks to support networking and security.

• Filesystem Support: FAT32, BTRFS (Read-only), and SWAP support across all virtual targets.
• Disk Drivers: Legacy ATA PIO (x64) and VirtIO-MMIO (ARM/RISCV) block drivers.
• Persistent Logging: Ring-buffered dmesg and persistent /fat32/BOOTLOG.TXT.
• SageShell: A unified interactive shell for all architectures with command history and tab-completion.
• VFS Bridge: A SageLang-driven virtual filesystem layer that mounts diverse backends seamlessly.

This repository is the central coordination point for SageOS development. It contains:

• sageos_build/: the shared system core and SageLang runtime.
• arch/: architecture-specific ports that reuse the core via nested submodules.
• docs/: project documentation and developer guides.
• examples/: sample SageLang programs and boot scripts.
• setup_submodules.sh: a trusted initializer that prevents infinite submodule recursion.

git clone https://github.com/Night-Traders-Dev/SageOS.git
cd SageOS
./setup_submodules.sh

Do not use git submodule update --init --recursive directly on the root repository. SageOS relies on ./setup_submodules.sh to properly configure local core references and disable redundant nested submodule clones.

• sageos_build/
  • kernel/: kernel boot flow, hardware abstraction, VFS bridge.
  • sage_lang/: SageLang compiler, runtime, and standard library support.
  • actual_sagelang_build/: host-side SageLang build utilities.
• arch/
  • x64/: x86_64 hardware and QEMU targets.
  • arm64/: ARM64 hardware and QEMU targets.
  • rv64/: RISC-V hardware and QEMU targets.
• docs/: documentation, architecture overviews, and guides.
• examples/: sample projects and demonstrations.
• scripts/: helper scripts and build utilities.

SageOS uses a nested submodule layout to share the core across ports while avoiding duplication.

• setup_submodules.sh initializes root submodules with --remote.
• It configures arch/*/core to reuse the local root repository as the core source.
• It disables redundant nested lwip and mbedtls updates inside architecture cores.

After pulling new changes:

git pull
./setup_submodules.sh

Build and run the OS with the management script.

./sageos.sh x64 virt build
./sageos.sh x64 virt run

./sageos.sh arm64 virt build
./sageos.sh arm64 virt run

./sageos.sh rv64 virt build
./sageos.sh rv64 virt run

Run the benchmark script in a local Python virtual environment to save build results and generate a history chart:

python3 -m venv .venv
.venv/bin/python -m pip install rich matplotlib
.venv/bin/python benchmark_build.py --clean

The script writes benchmark history to benchmark_history.json and saves benchmark_chart.png when matplotlib is available.

The virt builds (x64, arm64, rv64) use a shared virtual disk image virt.img. This image is automatically generated by scripts/gen_virt_disk.sh if it does not exist. It contains:

• Partition 1: FAT32 (64MB) - Mounted at /fat32. Used for BOOTLOG.TXT.
• Partition 2: BTRFS (128MB) - Mounted at /.
• Partition 3: SWAP (125MB) - Registered as a swap device.

./sageos.sh x64 lenovo_300e build

./sageos.sh x64 lenovo_300e run

./sageos.sh arm64 rpi4 run

## Documentation
- Read the root [SageOS Book](SageOS_Book.md) for architecture details and project philosophy.
- See `docs/README.md` for a documentation index and developer guide links.

## Porting Progress

- Many high-level system components have been ported to pure Sage (SageLang) and now run as embedded Sage scripts or VM modules: VFS high-level logic (RamFS/vfs router), most shell commands and utilities (neofetch, dmesg, sched, swap, etc.), and init/service orchestration scripts.
- The C kernel retains low-level primitives: hardware drivers, bootstrapping, the MetalVM interpreter, and performance-critical shims.
- To verify builds and run the test suite for virtual targets:
```bash
./sageos.sh x64 virt build
./sageos.sh arm64 virt build
./sageos.sh rv64 virt build
# Run test-suite inside a virt image via QEMU (manual):
# ./sageos.sh x64 virt run  # then run /etc/test_suite.sage from the shell

MIT License. See LICENSE.