From 30fd3584fa9ed82fa5cf15fcdbb3c0fe60c91710 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 28 Dec 2025 18:39:55 +0000 Subject: [PATCH 1/2] Initial plan From 4c36df4e2d0d5bbc031a0b33e479417978e7d1bf Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 28 Dec 2025 18:43:53 +0000 Subject: [PATCH 2/2] Add release workflow and QEMU instructions for all major OS Co-authored-by: johndoe6345789 <224850594+johndoe6345789@users.noreply.github.com> --- .github/workflows/qemu-test.yml | 21 +- .github/workflows/release.yml | 236 +++++++++++++++++++++ QEMU_INSTRUCTIONS.md | 355 ++++++++++++++++++++++++++++++++ 3 files changed, 600 insertions(+), 12 deletions(-) create mode 100644 .github/workflows/release.yml create mode 100644 QEMU_INSTRUCTIONS.md diff --git a/.github/workflows/qemu-test.yml b/.github/workflows/qemu-test.yml index d9b9bc1..7b60813 100644 --- a/.github/workflows/qemu-test.yml +++ b/.github/workflows/qemu-test.yml @@ -42,18 +42,7 @@ jobs: - name: Create bootable image run: | - mkdir -p build/iso/EFI/BOOT - # Copy bootloader if it exists - if [ -f bootloader/bootx64.efi ]; then - cp bootloader/bootx64.efi build/iso/EFI/BOOT/ - else - echo "Bootloader not built yet, creating placeholder" - mkdir -p build/iso/EFI/BOOT - fi - # Copy kernel if it exists - if [ -f kernel/metalos.bin ]; then - cp kernel/metalos.bin build/iso/ - fi + make image - name: Start QEMU and capture screenshot run: | @@ -116,3 +105,11 @@ jobs: name: serial-log path: build/serial.log if-no-files-found: warn + + - name: Upload built disk image + if: always() + uses: actions/upload-artifact@v4 + with: + name: metalos-disk-image + path: build/metalos.img + if-no-files-found: warn diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..9e6adaa --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,236 @@ +name: Build and Release + +on: + push: + tags: + - 'v*' # Trigger on version tags like v1.0.0, v2.1.3, etc. + workflow_dispatch: # Allow manual triggering + +jobs: + build-and-release: + runs-on: ubuntu-latest + permissions: + contents: write # Required for creating releases + actions: write # Required for uploading artifacts + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Install build dependencies + run: | + sudo apt-get update + sudo apt-get install -y \ + build-essential \ + nasm \ + qemu-system-x86 \ + ovmf \ + mtools \ + xorriso + + - name: Build bootloader + run: | + cd bootloader + make || echo "Warning: Bootloader build incomplete (expected in early development)" + + - name: Build kernel + run: | + cd kernel + make || echo "Warning: Kernel build incomplete (expected in early development)" + + - name: Create bootable image + run: | + make image + + - name: Prepare release directory + run: | + mkdir -p release + + # Copy the bootable disk image + if [ -f build/metalos.img ]; then + cp build/metalos.img release/ + echo "✓ Copied metalos.img" + fi + + # Copy bootloader if it exists + if [ -f bootloader/bootx64.efi ]; then + cp bootloader/bootx64.efi release/ + echo "✓ Copied bootx64.efi" + fi + + # Copy kernel if it exists + if [ -f kernel/metalos.bin ]; then + cp kernel/metalos.bin release/ + echo "✓ Copied metalos.bin" + fi + + # Copy QEMU instructions + cp QEMU_INSTRUCTIONS.md release/ + echo "✓ Copied QEMU_INSTRUCTIONS.md" + + # Create README for the release + cat > release/README.md << 'EOF' + # MetalOS Release Package + + This package contains a compiled release of MetalOS. + + ## Contents + + - **metalos.img** - Bootable disk image (use with QEMU or write to USB) + - **bootx64.efi** - UEFI bootloader (standalone) + - **metalos.bin** - Kernel binary + - **QEMU_INSTRUCTIONS.md** - Detailed instructions for testing with QEMU on Windows, macOS, and Linux + - **README.md** - This file + + ## Quick Start + + ### Testing with QEMU + + The easiest way to test MetalOS is using QEMU. See **QEMU_INSTRUCTIONS.md** for detailed setup instructions for your operating system. + + **Quick command (Linux/macOS with QEMU and OVMF installed):** + ```bash + qemu-system-x86_64 \ + -bios /usr/share/OVMF/OVMF_CODE.fd \ + -drive format=raw,file=metalos.img \ + -m 512M \ + -serial stdio + ``` + + **Quick command (Windows with QEMU installed):** + ```cmd + "C:\Program Files\qemu\qemu-system-x86_64.exe" ^ + -bios "C:\Program Files\qemu\share\edk2-x86_64-code.fd" ^ + -drive format=raw,file=metalos.img ^ + -m 512M ^ + -serial stdio + ``` + + ### Creating a Bootable USB + + ⚠️ **WARNING**: This will erase all data on the USB drive! + + ```bash + # Linux/macOS (replace /dev/sdX with your USB device) + sudo dd if=metalos.img of=/dev/sdX bs=4M status=progress + sync + ``` + + ## System Requirements + + - **Architecture**: AMD64 (x86-64) + - **Boot Mode**: UEFI + - **Minimum RAM**: 512MB + - **Target Hardware**: Radeon RX 6600 GPU (for full functionality) + + ## Development Status + + MetalOS is currently under active development. See the repository for current status and roadmap. + + ## More Information + + - Repository: https://github.com/johndoe6345789/MetalOS + - Documentation: See the docs/ directory in the repository + - Issues: https://github.com/johndoe6345789/MetalOS/issues + + ## License + + See LICENSE file in the repository. + EOF + + echo "✓ Created README.md" + + # List contents + echo "" + echo "Release directory contents:" + ls -lh release/ + + - name: Create release archive + run: | + cd release + zip -r ../metalos-release.zip . + cd .. + + echo "" + echo "Release archive created:" + ls -lh metalos-release.zip + + # Show archive contents + echo "" + echo "Archive contents:" + unzip -l metalos-release.zip + + - name: Upload release artifact + uses: actions/upload-artifact@v4 + with: + name: metalos-release + path: metalos-release.zip + retention-days: 90 + + - name: Create GitHub Release + if: startsWith(github.ref, 'refs/tags/') + uses: softprops/action-gh-release@v1 + with: + files: | + metalos-release.zip + release/metalos.img + body: | + ## MetalOS Release ${{ github.ref_name }} + + This is an automated release of MetalOS. + + ### What's Included + + - **metalos-release.zip** - Complete release package with bootable image and QEMU instructions + - **metalos.img** - Bootable disk image (standalone) + + ### Testing with QEMU + + Download `metalos-release.zip`, extract it, and follow the instructions in `QEMU_INSTRUCTIONS.md` for your operating system (Windows, macOS, or Linux). + + ### Quick Start (Linux/macOS) + + ```bash + qemu-system-x86_64 \ + -bios /usr/share/OVMF/OVMF_CODE.fd \ + -drive format=raw,file=metalos.img \ + -m 512M \ + -serial stdio + ``` + + ### Quick Start (Windows) + + ```cmd + "C:\Program Files\qemu\qemu-system-x86_64.exe" ^ + -bios "C:\Program Files\qemu\share\edk2-x86_64-code.fd" ^ + -drive format=raw,file=metalos.img ^ + -m 512M ^ + -serial stdio + ``` + + For detailed setup instructions, see `QEMU_INSTRUCTIONS.md` in the release package. + + ### System Requirements + + - AMD64 (x86-64) architecture + - UEFI boot mode + - 512MB+ RAM + - QEMU with OVMF/EDK2 firmware for testing + + See the [repository](https://github.com/johndoe6345789/MetalOS) for more information. + draft: false + prerelease: false + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + - name: Upload individual artifacts for inspection + uses: actions/upload-artifact@v4 + with: + name: metalos-components + path: | + release/metalos.img + release/bootx64.efi + release/metalos.bin + release/QEMU_INSTRUCTIONS.md + release/README.md + retention-days: 30 diff --git a/QEMU_INSTRUCTIONS.md b/QEMU_INSTRUCTIONS.md new file mode 100644 index 0000000..66ffae4 --- /dev/null +++ b/QEMU_INSTRUCTIONS.md @@ -0,0 +1,355 @@ +# MetalOS - QEMU Testing Instructions + +This document provides instructions for testing MetalOS in QEMU on Windows, macOS, and Linux. + +## What You Need + +MetalOS is distributed as a bootable disk image (`metalos.img`) that can be run in QEMU with UEFI firmware support. This allows you to test the operating system without installing it on physical hardware. + +## Prerequisites + +You'll need to install: +1. **QEMU** - A virtual machine emulator +2. **OVMF/EDK2** - UEFI firmware for QEMU (Linux/macOS) or included with QEMU on Windows + +--- + +## Windows Instructions + +### Installing QEMU on Windows + +1. **Download QEMU for Windows**: + - Visit https://qemu.weilnetz.de/w64/ + - Download the latest installer (e.g., `qemu-w64-setup-*.exe`) + - Run the installer and follow the installation wizard + - Default installation path: `C:\Program Files\qemu` + +2. **Add QEMU to PATH** (optional but recommended): + - Right-click "This PC" → Properties → Advanced system settings + - Click "Environment Variables" + - Under "System variables", find "Path" and click "Edit" + - Click "New" and add: `C:\Program Files\qemu` + - Click "OK" to save + +### Running MetalOS in QEMU (Windows) + +**Option 1 - Using Command Prompt (cmd):** + +```cmd +cd path\to\metalos\release +"C:\Program Files\qemu\qemu-system-x86_64.exe" ^ + -bios "C:\Program Files\qemu\share\edk2-x86_64-code.fd" ^ + -drive format=raw,file=metalos.img ^ + -m 512M ^ + -serial stdio +``` + +**Option 2 - Using PowerShell:** + +```powershell +cd path\to\metalos\release +& "C:\Program Files\qemu\qemu-system-x86_64.exe" ` + -bios "C:\Program Files\qemu\share\edk2-x86_64-code.fd" ` + -drive format=raw,file=metalos.img ` + -m 512M ` + -serial stdio +``` + +**Option 3 - Using the provided batch script:** + +Create a file named `run_metalos.bat` in the same directory as `metalos.img`: + +```batch +@echo off +echo Starting MetalOS in QEMU... +"C:\Program Files\qemu\qemu-system-x86_64.exe" ^ + -bios "C:\Program Files\qemu\share\edk2-x86_64-code.fd" ^ + -drive format=raw,file=metalos.img ^ + -m 512M ^ + -serial stdio +pause +``` + +Then double-click `run_metalos.bat` to run MetalOS. + +### Troubleshooting (Windows) + +- **"qemu-system-x86_64 is not recognized"**: Make sure QEMU is installed and added to PATH, or use the full path to the executable. +- **"Could not open BIOS"**: The EDK2 firmware files come with QEMU on Windows. Check that the file exists at `C:\Program Files\qemu\share\edk2-x86_64-code.fd`. +- **Window closes immediately**: Add `pause` at the end of your batch script to see any error messages. + +--- + +## macOS Instructions + +### Installing QEMU on macOS + +**Using Homebrew** (recommended): + +```bash +# Install Homebrew if you haven't already +/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" + +# Install QEMU +brew install qemu +``` + +**Manual installation**: +- Download QEMU from https://www.qemu.org/download/#macos +- Follow the installation instructions + +### Installing OVMF (UEFI Firmware) on macOS + +OVMF firmware may need to be downloaded separately: + +```bash +# Option 1: Download from your package manager (if available) +brew install qemu # Usually includes firmware + +# Option 2: Download manually from EDK2 project +# Visit: https://github.com/tianocore/edk2/releases +# Download OVMF-X64 package and extract to a known location +``` + +### Running MetalOS in QEMU (macOS) + +**Using Terminal:** + +```bash +cd /path/to/metalos/release + +# If OVMF firmware is included with QEMU +qemu-system-x86_64 \ + -bios /usr/local/share/qemu/edk2-x86_64-code.fd \ + -drive format=raw,file=metalos.img \ + -m 512M \ + -serial stdio + +# If you downloaded OVMF manually +qemu-system-x86_64 \ + -drive if=pflash,format=raw,readonly=on,file=/path/to/OVMF_CODE.fd \ + -drive format=raw,file=metalos.img \ + -m 512M \ + -serial stdio +``` + +**Create a shell script for easy launching:** + +Create a file named `run_metalos.sh`: + +```bash +#!/bin/bash +echo "Starting MetalOS in QEMU..." +qemu-system-x86_64 \ + -bios /usr/local/share/qemu/edk2-x86_64-code.fd \ + -drive format=raw,file=metalos.img \ + -m 512M \ + -serial stdio +``` + +Make it executable and run: + +```bash +chmod +x run_metalos.sh +./run_metalos.sh +``` + +### Troubleshooting (macOS) + +- **"qemu-system-x86_64: command not found"**: Make sure QEMU is installed via Homebrew or the binary is in your PATH. +- **"Could not open firmware"**: Check the path to the OVMF firmware file. Common locations: + - `/usr/local/share/qemu/edk2-x86_64-code.fd` + - `/opt/homebrew/share/qemu/edk2-x86_64-code.fd` (Apple Silicon Macs) +- **Permission denied**: Run `chmod +x` on your shell script. + +--- + +## Linux Instructions + +### Installing QEMU on Linux + +**Ubuntu/Debian:** + +```bash +sudo apt-get update +sudo apt-get install qemu-system-x86 ovmf +``` + +**Fedora:** + +```bash +sudo dnf install qemu-system-x86 edk2-ovmf +``` + +**Arch Linux:** + +```bash +sudo pacman -S qemu-full edk2-ovmf +``` + +**Other distributions:** +- Use your distribution's package manager to install `qemu-system-x86` and `ovmf` or `edk2-ovmf` + +### Running MetalOS in QEMU (Linux) + +**Basic command:** + +```bash +cd /path/to/metalos/release + +qemu-system-x86_64 \ + -drive if=pflash,format=raw,readonly=on,file=/usr/share/OVMF/OVMF_CODE.fd \ + -drive format=raw,file=metalos.img \ + -m 512M \ + -serial stdio +``` + +**With graphical display (GTK):** + +```bash +qemu-system-x86_64 \ + -drive if=pflash,format=raw,readonly=on,file=/usr/share/OVMF/OVMF_CODE.fd \ + -drive format=raw,file=metalos.img \ + -m 512M \ + -serial stdio \ + -display gtk +``` + +**Create a shell script for easy launching:** + +Create a file named `run_metalos.sh`: + +```bash +#!/bin/bash +echo "Starting MetalOS in QEMU..." + +# Auto-detect OVMF firmware location +if [ -f /usr/share/OVMF/OVMF_CODE.fd ]; then + OVMF="/usr/share/OVMF/OVMF_CODE.fd" +elif [ -f /usr/share/ovmf/OVMF.fd ]; then + OVMF="/usr/share/ovmf/OVMF.fd" +elif [ -f /usr/share/edk2-ovmf/x64/OVMF_CODE.fd ]; then + OVMF="/usr/share/edk2-ovmf/x64/OVMF_CODE.fd" +elif [ -f /usr/share/qemu/ovmf-x86_64.bin ]; then + OVMF="/usr/share/qemu/ovmf-x86_64.bin" +else + echo "Error: OVMF firmware not found!" + echo "Install with: sudo apt-get install ovmf (Ubuntu/Debian)" + echo " or: sudo pacman -S edk2-ovmf (Arch)" + echo " or: sudo dnf install edk2-ovmf (Fedora)" + exit 1 +fi + +echo "Using OVMF firmware: $OVMF" + +qemu-system-x86_64 \ + -drive if=pflash,format=raw,readonly=on,file="$OVMF" \ + -drive format=raw,file=metalos.img \ + -m 512M \ + -serial stdio \ + -display gtk +``` + +Make it executable and run: + +```bash +chmod +x run_metalos.sh +./run_metalos.sh +``` + +### Troubleshooting (Linux) + +- **"qemu-system-x86_64: command not found"**: Install QEMU using your package manager. +- **"Could not open firmware"**: Install OVMF/EDK2 firmware package for your distribution. +- **"gtk initialization failed"**: You're in a headless environment. Remove `-display gtk` or use `-display none` or `-nographic`. +- **Permission issues**: Make sure you have read permissions for the firmware files and `metalos.img`. + +--- + +## QEMU Command Line Options Explained + +- **`-drive if=pflash,format=raw,readonly=on,file=OVMF_CODE.fd`**: Loads the UEFI firmware +- **`-bios edk2-x86_64-code.fd`**: Alternative way to load UEFI firmware (used on Windows) +- **`-drive format=raw,file=metalos.img`**: Loads the MetalOS disk image as a raw disk +- **`-m 512M`**: Allocates 512MB of RAM to the virtual machine +- **`-serial stdio`**: Redirects serial output to the terminal (useful for debugging) +- **`-display gtk`**: Uses GTK for the graphical window (Linux) +- **`-display none`**: Runs in headless mode (no graphics) +- **`-nographic`**: Disables graphical output entirely + +--- + +## Advanced Usage + +### Running with more memory: + +```bash +# Allocate 1GB of RAM instead of 512MB +qemu-system-x86_64 ... -m 1024M ... +``` + +### Enable KVM acceleration (Linux only): + +```bash +# Requires KVM kernel module +qemu-system-x86_64 ... -enable-kvm ... +``` + +### Debug mode: + +```bash +# Enable debug output +qemu-system-x86_64 ... -d int,cpu_reset ... +``` + +### GDB debugging: + +```bash +# Start QEMU with GDB server on port 1234 +qemu-system-x86_64 ... -s -S ... + +# In another terminal: +gdb +(gdb) target remote localhost:1234 +(gdb) continue +``` + +--- + +## Expected Behavior + +MetalOS is currently in early development. Depending on the development phase: + +- **Phase 1-2**: May boot to UEFI shell (this is normal during early development) +- **Phase 3+**: Should display kernel boot messages via serial output +- **Phase 7+**: Will eventually boot directly to a QT6 application + +Check the serial output (terminal/console) for boot messages and debug information. + +--- + +## Getting Help + +If you encounter issues: + +1. Check the troubleshooting section for your operating system above +2. Verify QEMU and OVMF/EDK2 are properly installed +3. Check the serial output for error messages +4. Visit the MetalOS repository: https://github.com/johndoe6345789/MetalOS + +--- + +## System Requirements + +- **CPU**: x86_64 (64-bit) processor +- **RAM**: Minimum 512MB free memory for the virtual machine +- **Disk**: ~100MB for QEMU and MetalOS files +- **OS**: Windows 10+, macOS 10.13+, or modern Linux distribution + +--- + +## Additional Resources + +- QEMU Documentation: https://www.qemu.org/docs/master/ +- OVMF/EDK2 Project: https://github.com/tianocore/edk2 +- MetalOS Repository: https://github.com/johndoe6345789/MetalOS