A professional-grade Linux distribution built on Debian bookworm.
Kernel 6.6.x. Wayland compositor (Sway). Custom shell (QShell). Custom dashboard (qdash).
qosx/
├── Makefile # Build orchestrator. All commands go through here.
├── version.txt # Single source of version truth.
├── .gitignore
│
├── config/
│ ├── kernel/
│ │ └── kernel.config # Kernel .config — tracked in git.
│ ├── grub/
│ │ └── grub.cfg # GRUB bootloader config.
│ └── branding/
│ └── os-release # /etc/os-release content.
│
├── kernel/ # Kernel source downloaded here (not in git).
│
├── rootfs/
│ ├── overlay/ # Files copied verbatim into rootfs after bootstrap.
│ │ ├── etc/
│ │ │ ├── apt/ # apt sources + config
│ │ │ ├── systemd/ # systemd units + overrides
│ │ │ ├── network/ # systemd-networkd configs
│ │ │ ├── sway/ # Sway compositor config
│ │ │ ├── sudoers.d/ # sudo rules
│ │ │ ├── skel/ # Default user home files
│ │ │ ├── hostname
│ │ │ ├── hosts
│ │ │ └── issue # TTY banner
│ │ └── usr/
│ │ ├── local/bin/ # Custom binaries (qsh, qdash)
│ │ └── share/qosx/ # Wallpaper, assets
│ ├── build/ # Generated rootfs (not in git)
│ └── modules/ # Kernel modules staging (not in git)
│
├── packages/
│ ├── packages.list # Declarative package list — edit this to add packages.
│ ├── qshell/ # QShell .deb package source
│ │ ├── DEBIAN/
│ │ │ ├── control
│ │ │ └── postinst
│ │ └── usr/local/bin/qsh # Replace with compiled Rust binary
│ └── qdash/
│ ├── DEBIAN/
│ │ └── control
│ └── usr/local/bin/qdash # Replace with compiled musl binary
│
├── scripts/
│ ├── build-kernel.sh # Downloads, compiles, installs kernel
│ ├── build-rootfs.sh # Runs debootstrap, installs packages, applies overlay
│ ├── build-packages.sh # Builds qshell + qdash into .deb files
│ ├── install-graphics.sh # Installs Wayland/Mesa/Sway stack into rootfs
│ ├── build-image.sh # Assembles bootable .img (GPT + GRUB + rootfs)
│ ├── build-iso.sh # Wraps .img into bootable .iso (squashfs + xorriso)
│ ├── test-boot.sh # Headless QEMU boot test — exits 0 on success
│ └── run-qemu.sh # Interactive QEMU launch with Wayland GUI
│
├── ci/
│ ├── pipeline.yml # GitHub Actions workflow
│ └── gitea-pipeline.yml # Gitea Actions workflow (self-hosted)
│
├── repo/
│ ├── conf/
│ │ ├── distributions # reprepro config for custom .deb repo
│ │ └── options
│ ├── pool/ # Built .deb files land here (not in git)
│ └── dists/ # Generated by reprepro (not in git)
│
├── output/
│ ├── img/ # Final .img artifacts land here
│ └── iso/ # Final .iso artifacts land here
│
└── docs/
├── BUILD.md # How to build from scratch
├── ARCHITECTURE.md # System architecture reference
├── CONTRIBUTING.md # How to contribute
└── RELEASES.md # Release history and versioning policy
sudo apt update && sudo apt install -y \
debootstrap qemu-system-x86 qemu-utils \
grub-pc-bin grub-efi-amd64-bin mtools \
parted dosfstools e2fsprogs xorriso \
build-essential bc flex bison libssl-dev \
libelf-dev libncurses-dev dwarves \
reprepro gnupg2 git make wget curl ovmfgit clone https://github.com/qubasehq/qosx.git
cd qosxsudo make allOr build stages individually:
sudo make kernel # Compile Linux 6.6.x
sudo make rootfs # Bootstrap Debian rootfs
make packages # Build qshell + qdash .deb files
sudo make graphics # Install Wayland + Mesa + Sway into rootfs
sudo make image # Assemble .img disk image
sudo make iso # Wrap into bootable .iso
make test # Headless boot test (exits 0 = pass)
make run # Launch QEMU interactively with GUImake run
# or directly:
scripts/run-qemu.sh output/img/qosx-dev.imgDefault credentials: babu / qosx
SSH forwarded to host port 2222: ssh babu@localhost -p 2222
Edit packages/packages.list. One package per line. Commit the change.
The build pipeline installs everything declared in that file. Nothing else enters the image.
echo "htop" >> packages/packages.list
git add packages/packages.list
git commit -m "packages: add htop"Place your compiled binary at the correct path inside the package directory:
packages/qshell/usr/local/bin/qsh ← your Rust binary
packages/qdash/usr/local/bin/qdash ← your musl binary
Then run:
make packagesThe build system packages them into .deb files and includes them in the image.
The kernel config lives at config/kernel/kernel.config.
It is tracked in git. Every kernel config change is a reviewable commit.
cd kernel/linux-6.6.30
make menuconfig
cp .config ../../config/kernel/kernel.config
cd ../..
git add config/kernel/kernel.config
git commit -m "kernel: enable CONFIG_XYZ"
make kernelCopy the pipeline file to GitHub Actions:
mkdir -p .github/workflows
cp ci/pipeline.yml .github/workflows/build.yml
git add .github/workflows/build.yml
git commit -m "ci: add build pipeline"
git pushEvery push to main triggers:
kernel → rootfs → packages → image → iso → boot test → release
Every stage is gated. If any stage fails, the pipeline stops.
Artifacts are stored per-commit. The artifact that passes tests is the artifact that ships.
| Bump | When |
|---|---|
| Major (1.x → 2.x) | Architectural change. Incompatible with previous. |
| Minor (1.0 → 1.1) | New feature. Backwards compatible. |
| Patch (1.0.0 → 1.0.1) | Bug fix or security patch only. |
Tag a release:
git tag -a v1.0.0 -m "QOSX 1.0.0"
git push origin v1.0.0The pipeline detects the tag and uploads artifacts to the GitHub Release automatically.
Everything in rootfs/overlay/ is copied verbatim into the rootfs after debootstrap.
Directory structure mirrors the target filesystem exactly.
To change a system file: edit it in overlay/, commit, rebuild.
Never edit files directly inside rootfs/build/ — that directory is ephemeral and gets wiped on every build.
Every build sets SOURCE_DATE_EPOCH from the last git commit timestamp.
This means two clean builds from the same commit produce byte-identical output.
To verify:
sha256sum output/img/qosx-*.img
# rebuild
sudo make clean && sudo make all
sha256sum output/img/qosx-*.img
# hashes must match