# ArkOS

A Linux-based operating system built from scratch — designed to be easy to use, easy to compile, and open for customization.

See [ArkOS: Comprehensive System Architecture](arkos_architecture_guide.md) for more details

## ✨ Features

| Feature | Status |
|---------|--------|
| Custom BIOS bootloader (stage1 + stage2) | ✅ |
| VESA graphics boot animation (60 FPS expanding dot) | ✅ |
| UEFI bootloader with GOP animation | ✅ |
| Verified Boot (SHA256 key-signed OS binary) | ✅ |
| Native Swift splash screen via Linux framebuffer | ✅ |
| Linux kernel 7.0 with custom initramfs | ✅ |
| Raspberry Pi 4 Model B Support (ARM64) | ✅ |
| Prebuilt Clang/LLVM toolchain | ✅ |
| `.ark` configuration file format | ✅ |
| Android-style build system (`envsetup.sh` + `type` command) | ✅ |
| Cross-architecture test commands (UEFI/BIOS x86↔ARM64) | ✅ |
| Anti-aliased rounded corner rendering | ✅ |
| Optimized mouse cursor rendering | ✅ |
| CPU & RAM usage monitoring | ✅ |
| `arkrt` as Monolithic PID1 Service | ✅ |
| Declarative `ArkUI` Framework | ✅ |
| Service Manager | ✅ |
| Package Manager | 🔜 |

## Building

### Prerequisites

| Tool | Purpose |
|------|---------|
| `clang` (prebuilt, included) | C/C++ compilation (all architectures) |
| `swiftc` | Swift compilation |
| `nasm` | x86 assembly |
| `python3` | Boot image packing & signing |
| `qemu-system-x86_64` / `qemu-system-aarch64` | Testing & Emulation |
| `mkfs.ext4`, `mkfs.vfat`, `mtools`, `parted` | Disk image generation |
| `cpio`, `gzip` | Initramfs packing |

### Build & Run

```bash
cd arkos/

# Step 1: Source the build environment (like Android's envsetup.sh)
source envsetup.sh

# Step 2: Select your target architecture (like Android's lunch)
type arm64          # ARM64 target (Raspberry Pi 4)
type x86_64         # x86_64 target (PC / QEMU)

# Step 3: Build
make                # Full build for selected target
```

#### Cross-Architecture Testing

```bash
make test-uefi          # Test x86_64 UEFI (KVM on x86 host, TCG on ARM host)
make test-bios          # Test x86_64 BIOS (KVM on x86 host, TCG on ARM host)
make test-uefi-arm64    # Test ARM64 UEFI (KVM on ARM host, TCG on x86 host)
make test-bios-arm64    # Test ARM64 direct kernel boot
```

Test targets auto-detect the host CPU and use hardware acceleration (KVM) when possible, falling back to software emulation (TCG) for cross-architecture testing.

### Raspberry Pi 4 Flashing

To write the compiled ARM64 image to an SD card for real hardware:

```bash
sudo dd if=finished/rpi4/rpi4.img of=/dev/sdX bs=4M status=progress
sync
```

All compilation uses the prebuilt Clang/LLVM toolchain with target triples:
- x86_64: `clang --target=x86_64-linux-gnu`
- ARM64: `clang --target=aarch64-linux-gnu`

### Build Output

The build system shows modular progress:

```
╔══════════════════════════════════════╗
║       ArkOS Build System v4.0        ║
╚══════════════════════════════════════╝

[ 1/14] Cleaning previous build
[ 2/14] Creating staging directories
[ 3/14] Integrating frameworks
[ 4/14] Preparing boot files
...
[14/14] Generating disk images

╔══════════════════════════════════════╗
║          Build complete! ✓            ║
╚══════════════════════════════════════╝
```

### Output Images

All images are generated in `finished/` (or `finished/rpi4/` for ARM64):

| Image | Description |
|-------|-------------|
| `boot.img` | Bootloader + animation + kernel + initramfs |
| `sys.img` | System partition (frameworks, libraries) |
| `vend.img` | Vendor partition (DRM, keys, mirror info) |
| `vbk.img` | Verified Boot Key — bootloader verifies sys.img/vend.img signatures |
| `vbmeta.img` | Boot metadata — mount configuration (vbmeta.ark) |
| `dtbo.img` | Device tree blobs and overlays for the kernel |
| `rpi4.img` | *(ARM64 only)* Flashable SD card image combining all partitions |

## 📁 Project Structure

```
arkos/
├── boot/                    # Bootloader source & configs
│   ├── source/              # Assembly source (bootloader.asm, stage2.asm) and C source (bootloader.c)
│   │   └── animationframes/ # Pre-generated boot animation frames
│   ├── rpi4/                # RPi4 boot firmware and config
│   ├── initramfs.img        # Base initramfs image
│   └── *.ark                # Boot configuration files
├── envsetup.sh              # Android-style build environment setup
├── frameworks/              # OS frameworks (DRM, SwiftUI)
├── hardware/                # Hardware-specific configurations
│   └── rpi4/                # Raspberry Pi 4 config (.ark)
├── kernel/                  # Linux kernel source + prebuilt bzImage
├── prebuilts/               # Prebuilt toolchains and SDKs
│   ├── clang/               # LLVM/Clang 22 toolchain
│   ├── Swift/               # Precompiled Swift 6.3.2 runtime & stdlib
│   └── mimalloc.o           # Microsoft mimalloc memory allocator
├── system/                  # Core system components
│   ├── apps/                # System apps (setup_app)
│   ├── display/             # Display compositor (ui_daemon) and boot animation
│   ├── services/            # Service configuration definitions (.serve)
│   ├── sysroot/             # x86_64 system root
│   └── sysrootaarch64/      # ARM64 system root
├── vendor/                  # Vendor-specific files
│   ├── verify/              # Verified Boot keys & signing tools
│   ├── mirror/              # Mirror configuration
│   └── Widewine/            # DRM (Widevine) integration
├── arkrt/                   # ArkOS runtime monolithic daemon (PID1) and libraries
├── Makefile                 # Top-level build entry point
└── finished/                # Build output (generated)
```

## 🔐 Verified Boot

ArkOS implements a custom Verified Boot chain:

1. The build system reads the signing key from `vendor/verify/securebuild.ark`
2. `sign.py` computes `SHA256(KEY + arkrt_binary)` → `signature.bin`
3. At boot, `arkrt` recomputes the hash and compares against `signature.bin`
4. **Mismatch → Kernel Panic** (system halts with security warning)
5. **Match → Boot continues** starting the UI layer and Services

> ⚠️ Never commit your real signing key to a public repository. Use `vendor/verify/key.py` to generate new keys.

## 📄 License

See [LICENSE](LICENSE) for details.