OrionOS/README.md

# OrionOS

A BeOS-inspired Linux desktop built from scratch in C. Custom window manager, panel, app launcher, settings panel, package manager, and graphical installer — all running on Arch Linux, shipped as a bootable ISO.

---

## What it is

OrionOS is a complete desktop environment built on X11/Xlib with a dark navy aesthetic. It ships as a bootable ISO you can try live or install to disk. Every shell component is written in native C with no toolkit dependency — just Xlib and Xft.

### Components

| Binary | Name | Description |
|--------|------|-------------|
| `orionwm` | OrionWM | Stacking window manager — titlebars, 3-button decorations, snap-to-edge, Alt+Tab switcher |
| `oriondeskbar` | OrionDeskbar | Sidebar panel — clock, task list, workspace switcher, XEMBED system tray, CPU/RAM status |
| `orionlauncher` | OrionLauncher | App launcher — reads `.desktop` files, category tabs, live search |
| `nebula` | Nebula | Settings panel — Display, Appearance, Input, and About tabs |
| `orionpkg` | OrionPkg | Package manager — lists available updates, runs `pacman -Syu` with live log |
| `orioninstall-gui` | Installer | Graphical installer wizard — disk, timezone, keyboard, user, progress |
| `orionwallpaper` | Wallpaper | Sets or restores the desktop wallpaper |

---

## Building the ISO

**Requirements:** Docker Desktop (Mac/Windows/Linux)

```bash
./build-iso.sh
```

Output: `dist/orionos-YYYYMMDD.iso`

The build runs entirely inside a Docker container — no Arch Linux install required on the host. First build downloads ~700 MB of packages and takes 10–20 minutes. Subsequent builds are faster thanks to Docker layer caching.

### What the build does

1. Starts from `archlinux:latest`
2. Installs `archiso` and all build tools
3. Compiles all OrionOS binaries inside the container
4. Assembles an archiso profile with the full package set
5. Bakes in the Plymouth boot splash (dark navy + accent blue)
6. Produces a hybrid ISO bootable on UEFI and legacy BIOS hardware

---

## Flashing to USB

**Balena Etcher (recommended):** https://etcher.balena.io — drag the ISO, pick the USB, flash.

**Command line:**
```bash
# Find your USB drive
diskutil list          # macOS
lsblk                  # Linux

# Flash (replace diskN / sdX)
sudo dd if=dist/orionos-*.iso of=/dev/diskN bs=4m   # macOS
sudo dd if=dist/orionos-*.iso of=/dev/sdX  bs=4M    # Linux
```

---

## Booting

Boot from the USB. OrionOS starts the live desktop automatically.

- **Live user:** `orion` / **Password:** `orionos`
- **Intel Mac:** Hold `Option` at startup to select the USB boot device
- **WiFi:** `broadcom-wl` driver loads automatically
- **Trackpad:** tap-to-click and two-finger natural scroll enabled by default
- **Audio:** PipeWire + SOF firmware for Intel HDA

---

## Installing to disk

Right-click the desktop → **App Launcher** → find **Install OrionOS**, or run `sudo orioninstall-gui` from a terminal.

The wizard walks through:

1. **Disk selection** — lists all disks ≥ 4 GB with model and size
2. **Timezone & Keyboard** — searchable timezone list (37 zones), 20 keyboard layouts
3. **User account** — hostname, username, password
4. **Review** — erase warning before anything is written
5. **Installing** — live progress bar and log output
6. **Done** — reboot prompt

The installer auto-detects UEFI vs legacy BIOS and sets up `systemd-boot` or GRUB accordingly.

---

## Desktop usage

### Right-click menu

Right-click anywhere on the desktop:

| Item | Action |
|------|--------|
| App Launcher | Open the application grid |
| Terminal | Launch Alacritty |
| File Manager | Open Thunar |
| Text Editor | Open Mousepad |
| Web Browser | Open Firefox |
| System Monitor | `htop` in a terminal |
| Volume Control | pavucontrol |
| System Settings | Open Nebula |
| Software Updates | Open OrionPkg |
| Display Settings | arandr |
| Change Wallpaper | Reset to default wallpaper |
| Restart OrionWM | Restart the window manager |
| Quit OrionOS | End the session |

### Keyboard shortcuts

| Shortcut | Action |
|----------|--------|
| `Alt + F1` | Open app launcher |
| `Alt + F4` | Close focused window |
| `Alt + F9` | Minimize focused window |
| `Alt + F10` | Toggle maximize |
| `Alt + Tab` | Visual window switcher |
| `Super + ←` | Snap window left half |
| `Super + →` | Snap window right half |
| `Super + ↑` | Maximize window |
| `Super + ↓` | Restore window |
| `Super + S` | Open Nebula (System Settings) |
| `PrintScreen` | Full screenshot → `~/Pictures` |
| `Shift + PrintScreen` | Region screenshot → `~/Pictures` |
| `XF86MonBrightness↑↓` | Screen brightness |
| `XF86AudioMute` | Toggle mute |
| `XF86AudioLowerVolume` | Volume down |
| `XF86AudioRaiseVolume` | Volume up |

---

## Settings (Nebula)

Open with **Super+S**, right-click → **System Settings**, or `nebula &`.

| Tab | Controls |
|-----|---------|
| Display | Resolution (cycles via xrandr), DPI (96/144), Brightness |
| Appearance | Reset wallpaper, open ~/Pictures, shows active theme info |
| Input | Key repeat delay + rate, tap-to-click, natural scrolling |
| About | Version, component list, platform info |

Changes are staged and applied when you click **Apply** (or press Enter).

---

## Software Updates (OrionPkg)

Open with right-click → **Software Updates** or `orionpkg &`.

- Runs `checkupdates` on launch to list available upgrades
- Shows package name, current version, and new version
- **Update All** runs `pkexec pacman -Syu` with a live log and progress bar
- **Refresh** re-checks without restarting the app

---

## Included software

| Category | Application |
|----------|-------------|
| Browser | Firefox |
| Office | OnlyOffice |
| Files | Thunar |
| Terminal | Alacritty |
| Video | mpv |
| Images | Viewnior |
| PDF | Evince |
| Text editor | Mousepad |
| Audio | PipeWire, pavucontrol |
| Network | NetworkManager, nm-applet |
| Bluetooth | bluez, blueman |
| Compositor | picom |
| Notifications | dunst |
| Clipboard | parcellite (tray icon + history) |
| Screenshots | scrot |
| Icons | Papirus Dark |

---

## Building from source

Requires an Arch Linux system (or container) with `libx11`, `libxft`, and `fontconfig` development headers.

```bash
make          # build all components
make install  # install to /usr/local (run as root)
```

Individual components:

```bash
make -C wm        # orionwm
make -C deskbar   # oriondeskbar
make -C launcher  # orionlauncher
make -C nebula    # nebula
make -C orionpkg  # orionpkg
make -C installer # orioninstall-gui + orioninstall
```

---

## Project layout

```
OS/
├── wm/               orionwm — window manager (C/Xlib)
├── deskbar/          oriondeskbar — panel (C/Xlib/Xft)
├── launcher/         orionlauncher — app grid (C/Xlib/Xft)
├── nebula/           nebula — settings panel (C/Xlib/Xft)
├── orionpkg/         orionpkg — package manager GUI (C/Xlib/Xft)
├── installer/
│   ├── orioninstall-gui.c  graphical installer wizard
│   └── orioninstall        backend install script
├── themes/
│   ├── OrionOS/      GTK 2/3 theme
│   ├── picom.conf    compositor config
│   └── orionwallpaper  wallpaper setter script
├── iso/
│   └── docker/
│       ├── Dockerfile      Arch Linux-based ISO builder image
│       └── entrypoint.sh   full build pipeline
├── build-iso.sh      one-command ISO build
└── Makefile
```

---

## Component naming

OrionOS components are named after stars in the Orion constellation.

| Name | Role |
|------|------|
| **OrionWM** | Window manager |
| **OrionDeskbar** | The panel (three icons like Orion's belt) |
| **Nebula** | Settings panel |
| **Rigel** *(planned)* | Native file manager |

Release names follow Orion's belt stars: **v1 Mintaka**, v2 Alnitak, v3 Alnilam.

---

## License

MIT