Development Guide

Build guideXOS Server from source using the current bootloader, kernel, and QEMU workflow

On This Page

Development Requirements

guideXOS Server currently mixes Visual Studio-based bootloader work with MinGW-based kernel builds, so the recommended environment is still Windows with the following tools installed:

Required Software

Tool Version Purpose
Visual Studio 2022 or later Bootloader and solution builds
Git Latest Version control
MinGW-w64 64-bit toolchain Kernel builds and make workflow
MSBuild Current with Visual Studio Build the bootloader and Windows-hosted server app
QEMU Latest Primary validation target

Platform Support

  • Windows: ✅ Primary development platform
  • Linux: ⚠️ Possible for some components, but not the recommended path
  • macOS: ⚠️ Not the documented primary path

Development Setup

1. Install Visual Studio with C++ tooling

# Install Visual Studio Community or later
# Required workload:
# - Desktop development with C++

2. Install MinGW-w64

The kernel build expects a 64-bit MinGW toolchain such as the niXman builds. 

# Example install location
C:\mingw64

# Verify tools
g++ --version
mingw32-make --version

3. Clone the Repository

# Clone from GitLab
git clone https://gitlab.com/guideX/guidexos-server
cd guideXOS-Server

4. Install QEMU

# Example via Chocolatey
choco install qemu

# Or install manually and ensure qemu-system-x86_64 is on PATH

5. Optional: use the Windows-hosted server app

# The solution also contains guideXOSServer.vcxproj
# Use it for faster host-side UI and shell iteration when appropriate

Building guideXOS

The current documented workflow is centered on the UEFI bootloader, the multi-architecture kernel, and QEMU validation. For most contributors, use the top-level PowerShell script first.

🏛️ Legacy GRUB Boot
  • Historical path from earlier project phases
  • Useful as legacy context only
  • Not the primary current story
  • Prefer UEFI for current validation
🚀 UEFI Boot (New!)
  • ESP folder structure
  • Modern UEFI firmware
  • Custom bootloader
  • Direct kernel loading

🎨 Method 1: Visual Studio (Recommended)

The easiest way to build and test guideXOS is through Visual Studio's integrated build profiles.

A. Using Launch Profiles (One-Click Build + Run)

  1. Open guideXOS.sln in Visual Studio 2022
  2. Look for the dropdown menu next to the Start button (toolbar)
  3. Select your preferred target:
Profile Boot Method Use Case
QEMU Legacy GRUB Fast testing, development
QEMU with USB Legacy GRUB Testing USB device support
QEMU UEFI ⭐ UEFI Modern boot testing
VMware Legacy GRUB VMware Player/Workstation
VirtualBox Legacy GRUB Oracle VirtualBox
  1. Press F5 or click the Start button
  2. Visual Studio will automatically:
    • Build the kernel (.NET NativeAOT)
    • Run build scripts (for UEFI: build bootloader, convert to ELF, create ramdisk)
    • Launch the selected VM with your OS
💡 New QEMU UEFI Profile:

The "QEMU UEFI" profile builds the custom C++ bootloader, converts the kernel to ELF format, creates a ramdisk, and launches QEMU with OVMF firmware - all in one step!

B. Manual Build in Visual Studio

  1. Open guideXOS.sln
  2. Set configuration: Debug or Release
  3. Set platform: x64
  4. Build → Build Solution (or Ctrl+Shift+B)
  5. For Legacy: Output is bin\Debug\net7.0\win-x64\native\guideXOS.iso
  6. For UEFI: Run build.ps1 separately (see Method 2)

⚙️ Method 2: PowerShell Build Scripts

For UEFI builds or advanced scenarios, use the automated PowerShell build scripts.

Full UEFI Build

# Complete UEFI build
.\build.ps1

# This builds:
# 1. C++ UEFI bootloader (guideXOSBootLoader)
# 2. C# kernel with NativeAOT
# 3. Converts kernel PE → ELF64
# 4. Creates ramdisk image
# 5. Assembles ESP filesystem structure

# Output: ESP\ folder with BOOTX64.EFI, kernel.elf, ramdisk.img

Build Script Options

Command Description
.\build.ps1 Full build (bootloader + kernel + ramdisk)
.\build.ps1 -Clean Clean rebuild (removes previous build artifacts)
.\build.ps1 -SkipBootloader Skip C++ bootloader (use existing .efi)
.\build.ps1 -SkipKernel Skip kernel build (use existing binary)
.\build.ps1 -SkipRamdisk Skip ramdisk creation
.\build.ps1 -SkipConversion Skip PE→ELF conversion (manual conversion)

Environment Check

# Verify build environment
.\check_env.ps1

# Checks for:
# - Visual Studio 2022
# - .NET 7 SDK
# - Python 3.x
# - objcopy (MSYS2 or WSL)
# - QEMU (optional)
# - Project structure
# - Required ramdisk assets

💻 Method 3: Command Line (.NET CLI)

Legacy GRUB Build

# Build kernel only
dotnet build guideXOS/guideXOS.csproj -c Release

# Build and run in QEMU
dotnet build guideXOS/guideXOS.csproj /p:vm=qemu

# Build and run in VMware
dotnet build guideXOS/guideXOS.csproj /p:vm=vmware

# Build and run in VirtualBox
dotnet build guideXOS/guideXOS.csproj /p:vm=virtualbox

UEFI Build (One Command)

# Build everything and launch QEMU with UEFI
dotnet build guideXOS/guideXOS.csproj /p:vm=qemuuefi

# This automatically:
# 1. Builds the kernel
# 2. Runs build.ps1 (bootloader + conversion + ramdisk)
# 3. Launches QEMU with OVMF firmware

📦 External Build Dependencies

The build process relies on several external tools and files:

Required Tools

Tool Purpose Required For Install Command
MSBuild C++ bootloader compilation UEFI boot Included with Visual Studio
.NET 7 SDK C# kernel compilation (NativeAOT) Both winget install Microsoft.DotNet.SDK.7
Python 3.x Ramdisk builder script Both winget install Python.Python.3.12
objcopy PE → ELF kernel conversion UEFI boot MSYS2 or WSL (see below)
NASM Assembly compilation Legacy boot Place in Tools\nasm.exe
7-Zip Ramdisk archive creation Legacy boot Place in Tools\7-Zip\7z.exe
mkisofs ISO image creation Legacy boot Place in Tools\mkisofs.exe

Installing objcopy (UEFI Builds)

⚠️ Required for UEFI:

The kernel is built as PE format (Windows executable) but UEFI bootloader needs ELF format. objcopy performs this conversion.

Option 1: MSYS2 (Recommended for Windows)

# 1. Download MSYS2
https://www.msys2.org/

# 2. Install and open MSYS2 terminal

# 3. Install binutils (includes objcopy)
pacman -S mingw-w64-x86_64-binutils

# 4. Add to PATH
C:\msys64\mingw64\bin

Option 2: WSL (Windows Subsystem for Linux)

# 1. Install WSL
wsl --install

# 2. In WSL:
sudo apt install binutils

# 3. Use conversion script
chmod +x tools/convert_kernel_wsl.sh
./tools/convert_kernel_wsl.sh

Required Ramdisk Assets

The ramdisk contains essential system files. Place these in ramdisk_src\:

File Location Purpose
Cursor.png ramdisk_src\Images\ Default mouse cursor (16x16)
Grab.png ramdisk_src\Images\ Drag/grab cursor (16x16)
Busy.png ramdisk_src\Images\ Busy/loading cursor (16x16)
enludo.btf ramdisk_src\Fonts\ System bitmap font
💡 Finding Assets:

These files are in existing guideXOS ISO images. Extract them using 7-Zip or create placeholders for testing.

OVMF Firmware (UEFI Testing)

To test UEFI boot in QEMU, you need OVMF firmware: 

# Option 1: Download from EDK2 releases
https://github.com/tianocore/edk2/releases
# Extract and place OVMF.fd in repository root

# Option 2: Copy from QEMU installation
copy "C:\Program Files\qemu\share\edk2-x86_64-code.fd" OVMF.fd

🧪 Testing the Build

Legacy Boot Testing

# QEMU (manual)
qemu-system-x86_64.exe `
  -m 2048 `
  -smp 2 `
  -cdrom guideXOS\bin\Release\net7.0\win-x64\native\guideXOS.iso `
  -serial stdio `
  -netdev user,id=net0 `
  -device rtl8139,netdev=net0

# Or use Visual Studio profile (easier)
# Select "QEMU" from dropdown → Press F5

UEFI Boot Testing

# QEMU with UEFI firmware
qemu-system-x86_64.exe `
  -bios OVMF.fd `
  -drive file=fat:rw:ESP,format=raw `
  -m 1024M `
  -serial stdio `
  -no-reboot

# Or use Visual Studio profile
# Select "QEMU UEFI" from dropdown → Press F5

# Or use helper script
.\run_qemu.ps1

What to Look For

Indicator Meaning Status
GRUB menu appears Bootloader loaded ✅ Good
Kernel loading messages Kernel initializing ✅ Good
Teal gradient background Desktop started ✅ Good
Mouse cursor visible Input working ✅ Good
Black screen Boot failed or hung ❌ Problem
Red screen Early panic (UEFI) ❌ Problem
💡 Build Documentation:

For detailed troubleshooting and build process documentation, see:

  • BUILD_GUIDE.md - Complete build reference
  • IMPLEMENTATION_SUMMARY.md - Build automation overview
  • QUICK_REFERENCE.md - Command cheat sheet
  • VISUAL_STUDIO_UEFI.md - VS integration guide

Project Structure

guideXOS/
├── guideXOS/              # Main kernel project
│   ├── Kernel/            # Core kernel code
│   │   ├── Program.cs     # Entry point
│   │   ├── GDT.cs         # Global Descriptor Table
│   │   ├── IDT.cs         # Interrupt Descriptor Table
│   │   └── PageTable.cs   # Memory paging
│   ├── Drivers/           # Hardware drivers
│   │   ├── PCI.cs         # PCI bus
│   │   ├── IDE.cs         # IDE/SATA storage
│   │   ├── Intel825xx.cs  # Intel NIC
│   │   └── RTL8111.cs     # Realtek NIC
│   ├── Memory/            # Memory management
│   │   └── Allocator.cs   # Page allocator
│   ├── Network/           # Network stack
│   │   ├── IPv4.cs        # IP protocol
│   │   ├── TCP.cs         # TCP protocol
│   │   ├── UDP.cs         # UDP protocol
│   │   └── DHCP.cs        # DHCP client
│   ├── FileSystem/        # File system
│   │   ├── VFS.cs         # Virtual file system
│   │   └── Ramdisk.cs     # Ramdisk loader
│   ├── GUI/               # Graphical user interface
│   │   ├── WindowManager.cs
│   │   ├── Desktop.cs
│   │   └── Controls/      # UI controls
│   └── Apps/              # Built-in applications
│       ├── Console/       # Console application
│       ├── Notepad/       # Text editor
│       └── Paint/         # Graphics editor
├── Boot/                  # Bootloader
│   ├── EntryPoint.asm     # Assembly entry
│   └── grub.cfg           # GRUB config
├── Tools/                 # Build tools
│   ├── RamdiskBuilder/    # Creates ramdisk.img
│   └── ISOBuilder/        # Creates bootable ISO
├── ISO/                   # Build output
│   └── guideXOS.iso       # Final ISO image
└── Docs/                  # Documentation
    └── API/               # API reference

Key Files

File Purpose
Program.cs Main entry point, initializes all subsystems
EntryPoint.asm Assembly bootloader, sets up protected mode
guideXOS.csproj Project configuration with NativeAOT settings
build.ps1 Main build script
grub.cfg GRUB2 bootloader configuration

Contributing to guideXOS

How to Contribute

  1. Fork the repository on GitLab
  2. Create a feature branch: git checkout -b feature/my-feature
  3. Make your changes and test thoroughly
  4. Commit: git commit -m "Add my feature"
  5. Push: git push origin feature/my-feature
  6. Create a Merge Request on GitLab

Coding Guidelines

  • Code Style: Follow C# conventions, use PascalCase for public members
  • Memory Safety: Always Free() allocated memory
  • Documentation: Add XML comments for public APIs
  • Testing: Test in QEMU before submitting
  • Commits: Clear, descriptive commit messages

Areas Needing Contributions

  • 🔧 Drivers: USB, AHCI, NVMe, more network cards
  • 🌐 Network: IPv6 support, TLS/SSL
  • 📁 File System: Persistent storage (ext2, FAT32)
  • 🎨 GUI: More UI controls, themes
  • 📱 Applications: New apps (email client, music player)
  • ⚡ Performance: Optimization, profiling
  • 📖 Documentation: Tutorials, API docs

Communication

  • GitLab Issues: Report bugs, request features
  • Email: guide_X@live.com
  • Discussions: Use GitLab discussions for questions
🎉 Thank You!

Every contribution, big or small, helps make guideXOS better. Whether you fix a typo or implement a new driver, we appreciate your help!

Related Topics

Architecture

NativeAOT compilation
GitLab Repository

Browse source code
FAQ

Common questions