Development Guide

Build from source and contribute

Development Requirements

To build guideXOS from source, you'll need the following tools installed:

Required Software

Tool	Version	Purpose
.NET SDK	9.0 or later	C# compilation and NativeAOT
Visual Studio	2022 or later	IDE (optional, can use VS Code)
Git	Latest	Version control
NASM	2.15+	Assembly bootloader
QEMU	Latest	Testing (optional)

Platform Support

Windows: ✅ Fully supported (primary development platform)
Linux: ✅ Supported with some modifications
macOS: ⚠️ Possible but not tested

Development Setup

1. Install .NET 9 SDK

# Download from:
https://dotnet.microsoft.com/download/dotnet/9.0

# Verify installation
dotnet --version
# Should show: 9.0.x

2. Install Visual Studio 2022

Download from visualstudio.microsoft.com

Required workloads:

.NET desktop development
Desktop development with C++

3. Clone the Repository

# Clone from GitLab
git clone https://gitlab.com/guideX/guideXOS
cd guideXOS

4. Install NASM (Windows)

# Download from:
https://www.nasm.us/

# Add to PATH:
set PATH=%PATH%;C:\Program Files\NASM

5. Install QEMU (Optional)

# Download from:
https://www.qemu.org/download/#windows

# Or use Chocolatey:
choco install qemu

Building guideXOS

Build Process Overview

1. Build C# kernel with NativeAOT
    ↓
2. Assemble bootloader (EntryPoint.asm)
    ↓
3. Link kernel and bootloader
    ↓
4. Build ramdisk image
    ↓
5. Create ISO with GRUB2
    ↓
6. Test in QEMU or VM

Method 1: Visual Studio

Open guideXOS.sln in Visual Studio
Set build configuration to Release
Right-click solution → Build Solution
Output ISO: bin\Release\guideXOS.iso

Method 2: Command Line

# Navigate to source directory
cd guideXOS

# Build kernel
dotnet publish -c Release

# Build complete system (includes bootloader, ramdisk, ISO)
.\build.ps1

# Output: ISO\guideXOS.iso

Method 3: Individual Components

# 1. Build kernel
dotnet publish -c Release -r guidexos-x64

# 2. Assemble bootloader
nasm -f bin EntryPoint.asm -o boot.bin

# 3. Link (custom linker script)
link /subsystem:native /entry:Entry kernel.obj boot.bin

# 4. Build ramdisk
.\tools\RamdiskBuilder.exe

# 5. Create ISO
.\tools\MakeISO.bat

Testing the Build

# Run in QEMU
qemu-system-x86_64.exe ^
  -m 2048 ^
  -cdrom ISO\guideXOS.iso ^
  -device rtl8139,netdev=net0 ^
  -netdev user,id=net0

# Or use the test script
.\test.ps1

💡 Quick Tip:

Use .\build.ps1 -Quick to skip ramdisk and ISO generation during rapid development!

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

Fork the repository on GitLab
Create a feature branch: git checkout -b feature/my-feature
Make your changes and test thoroughly
Commit: git commit -m "Add my feature"
Push: git push origin feature/my-feature
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!