git/MetalOS
1
0
Fork 0
mirror of https://github.com/johndoe6345789/MetalOS.git synced 2026-04-24 13:45:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add release workflow and QEMU instructions for all major OS

Browse Source 
Co-authored-by: johndoe6345789 <224850594+johndoe6345789@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
2025-12-28 18:43:53 +00:00
parent 30fd3584fa
commit 4c36df4e2d
3 changed files with 600 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
.github/workflows/qemu-test.yml vendored
View File

@@ -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

236
.github/workflows/release.yml vendored Normal file
View File

@@ -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

355
QEMU_INSTRUCTIONS.md Normal file
View File

@@ -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