Application Development Approaches

Comparing Built-in Apps, GXM Native Apps, and GXM Scripts

Overview

guideXOS provides three distinct approaches for creating applications, each optimized for different scenarios:

Approach 1: Built-in Apps (Native C#)

Description

Applications written in C# and compiled directly into the guideXOS kernel binary. These apps have full access to all OS internals and are loaded at boot time.

Architecture

guideXOS Binary
??? Kernel/
??? GUI/
??? Drivers/
??? DefaultApps/        ? Built-in apps here
    ??? Notepad.cs
    ??? Calculator.cs
    ??? Paint.cs
    ??? ImageViewer.cs
    ??? FileManager.cs
    ??? TaskManager.cs

Code Example

// DefaultApps/MyApp.cs
using guideXOS.GUI;
using guideXOS.FS;

namespace guideXOS.DefaultApps {
    internal class MyApp : Window {
        public MyApp(int x, int y) : base(x, y, 600, 400) {
            Title = "My Application";
            IsResizable = true;
            ShowInTaskbar = true;
            // Full access to OS internals
            var files = Directory.GetFiles("/");
            // Custom rendering, events, logic
        }
        
        public override void OnDraw() {
            base.OnDraw();
            // Direct framebuffer access
            Framebuffer.Graphics.DrawRectangle(X + 10, Y + 10, 200, 100, 0xFFFFFFFF, 2);
        }
    }
}

Deployment

1. Add MyApp.cs to DefaultApps/
2. Register in OS/App.cs switch statement
3. Rebuild entire guideXOS binary
4. Rebuild ISO image
5. Reboot to test changes

? Advantages

• Full API Access: Direct access to kernel, drivers, memory
• Maximum Performance: Compiled to native code, no interpretation overhead
• Type Safety: Compile-time type checking prevents runtime errors
• Advanced Features: Custom controls, animations, effects
• Complex Logic: Implement sophisticated algorithms and state machines
• Deep Integration: Can modify OS behavior, hook into system events
• Debugging: Full C# debugging support in Visual Studio

? Disadvantages

• Larger Binary: Every app increases OS size (~50-100KB per app)
• Slow Updates: Must rebuild entire OS for any change
• No Modularity: Apps cannot be updated independently
• Long Build Times: Full OS rebuild takes 5-15 minutes
• No User Customization: Users cannot modify apps
• High Barrier: Requires C# knowledge and OS source code
• Tight Coupling: Apps tied to specific OS version

?? Use Cases

Approach 2: GXM Native Apps (Compiled Binary)

Description

Applications written in C# and compiled to native code using NativeAOT, then packaged as .gxm files. These apps are loaded dynamically at runtime.

Architecture

Development:
MyApp/
??? MyApp.cs          ? Your C# code
??? MyApp.csproj
??? Program.cs

Build Process:
1. Compile with NativeAOT ? MyApp.exe (native binary)
2. Package with GXMPackager ? MyApp.gxm
3. Deploy to Ramdisk/Programs/

Runtime:
guideXOS loads MyApp.gxm ? Executes in user mode

Code Example

// MyApp.cs
using System;

namespace MyApp {
    public class Program {
        [UnmanagedCallersOnly(EntryPoint = "main")]
        public static int Main() {
            // Custom logic here
            // NOTE: Limited API access (no direct OS internals)
            // Must use syscalls or provided interfaces
            
            // Example: Basic calculation
            int result = 5 + 3;
            return result;
        }
    }
}

// Build:
// dotnet publish -c Release -r win-x64 --self-contained
// GXMPackager.exe MyApp.exe MyApp.gxm --entry 0x1000

Deployment

1. Write C# application
2. Compile with NativeAOT: dotnet publish -c Release -r win-x64 --self-contained
3. Package: GXMPackager.exe MyApp.exe MyApp.gxm --entry 0x1000
4. Copy MyApp.gxm to Ramdisk/Programs/
5. Rebuild ISO (to include new file in Ramdisk)
6. Boot and run from console or Start Menu

? Advantages

• Modular Distribution: Apps distributed as separate files
• Smaller OS: Apps not compiled into OS binary
• Independent Updates: Update apps without rebuilding OS
• Full C# Power: Write complex logic in C#
• Native Performance: Compiled to native code
• Version Independence: Apps can target different OS versions
• Third-party Apps: Developers can distribute apps without OS source

? Disadvantages

• Limited API Access: No direct access to OS internals (security boundary)
• Syscall Overhead: Must use syscalls for OS features
• Complex Build: Requires NativeAOT setup and configuration
• Large Binary Size: NativeAOT output can be 5-20MB per app
• Debugging Challenges: Harder to debug than built-in apps
• Entry Point Management: Must specify RVA correctly
• Still Requires Rebuild: ISO must be rebuilt to deploy

?? Use Cases

Approach 3: GXM Script Apps (Declarative)

Description

Applications defined using a simple text-based scripting language with pipe-delimited commands. Scripts are interpreted at runtime by GXMLoader.cs.

Architecture

Development:
notepad.txt           ? Simple text script

Script Format:
WINDOW|Title|Width|Height
LABEL|Text|X|Y
BUTTON|Id|Text|X|Y|Width|Height
ONCLICK|Id|Action|Argument

Build Process:
GXMPackager.exe notepad.txt notepad.gxm --script notepad.txt

Runtime:
GXMLoader.cs reads script ? Creates GXMScriptWindow ? Displays UI

Script Example

WINDOW|Notepad|700|460
RESIZABLE|true
TASKBAR|true
MAXIMIZE|true
MINIMIZE|true
TOMBSTONE|true
STARTMENU|true
TEXTBOX|1|10|40|680|370|
BUTTON|100|Save As...|10|420|88|28
BUTTON|101|Open...|108|420|72|28
BUTTON|102|New|190|420|60|28
BUTTON|103|Close|260|420|72|28
ONCLICK|100|SAVEDIALOG|notes.txt
ONCLICK|101|OPENDIALOG|
ONCLICK|102|CLEAR|1
ONCLICK|103|CLOSE|
LABEL|guideXOS Notepad - Type your notes here|10|10

Deployment

1. Create myapp.txt with script commands
2. Package: GXMPackager.exe myapp.txt myapp.gxm --script myapp.txt
3. Copy myapp.gxm to Ramdisk/Programs/
4. Rebuild ISO
5. Launch from Start Menu or console

? Advantages

• ?? Ultra-Fast Development: No compilation, just edit text
• ?? Simple Syntax: No programming knowledge required
• ?? Rapid Iteration: Edit ? Package ? Test in seconds
• ?? User Customization: Users can modify UI without coding
• ?? Tiny File Size: Scripts are 1-5KB (vs. MB for compiled apps)
• ?? UI Prototyping: Test layouts quickly
• ?? Easy to Learn: Simple command reference
• ?? Community Friendly: Anyone can create apps

? Disadvantages

• Limited Logic: No complex algorithms or calculations
• Predefined Controls Only: BUTTON, LABEL, TEXTBOX, LIST, DROPDOWN
• No Custom Rendering: Cannot draw pixels directly
• Action Limitations: Only predefined actions (NOTIFY, CLOSE, OPENAPP, etc.)
• No State Management: Limited to simple event handlers
• Runtime Interpretation: Slight parsing overhead
• No Type Safety: Errors only caught at runtime

?? Use Cases

Supported Commands

Supported Actions

• NOTIFY|Message - Show notification
• CLOSE| - Close window
• OPENAPP|AppName - Launch another app
• SAVEDIALOG|DefaultFile - Open save dialog
• OPENDIALOG| - Open file dialog
• CLEAR|ControlId - Clear control content

Feature Comparison Matrix

When to Use Each Approach

Hybrid Development Strategy

The most effective approach is to use a hybrid strategy that leverages the strengths of each method:

Recommended Distribution

Example: Calculator as Hybrid App

The Calculator demonstrates how to combine approaches:

WINDOW|Calculator|320|420
RESIZABLE|false
BUTTON|1|7|20|80|60|50
BUTTON|2|8|90|80|60|50
...
BUTTON|16|=|20|320|200|50
ONCLICK|1|CALCULATE|7
ONCLICK|16|CALCULATE|EQUALS

else if(action == "CALCULATE") {
    // Implement calculation logic
    if(arg == "EQUALS") {
        double result = PerformCalculation();
        win.UpdateLabel("display", result);
    } else {
        AddToCalculation(arg);
    }
}

Benefits: Fast UI iteration + powerful calculation logic

Extending GXM Scripts

To make GXM scripts more powerful, add new actions to Kernel/Misc/GXMLoader.cs:

// Example: Add CANVAS for Paint app
else if(StringEquals(cmd,"CANVAS")) {
    // CANVAS|Id|X|Y|Width|Height
    win.AddCanvas(id, x, y, w, h);
}

// Example: Add IMAGE for Image Viewer
else if(StringEquals(cmd,"IMAGE")) {
    // IMAGE|Id|Path|X|Y
    win.LoadAndDisplayImage(id, path, x, y);
}

// Example: Add CALCULATE action
else if(action == "CALCULATE") {
    // Perform arithmetic
    double result = Calculate(operation, value1, value2);
    win.UpdateLabel(labelId, result.ToString());
}

Migration Guide

Converting Built-in App to GXM Script

Example: Migrating Notepad

// DefaultApps/Notepad.cs
internal class Notepad : Window {
    private string _text;
    private bool _dirty;
    
    public Notepad(int x, int y) 
        : base(x, y, 700, 460) {
        Title = "Notepad";
        IsResizable = true;
        ShowInTaskbar = true;
        // ... 300 lines of code
    }
    
    public override void OnDraw() {
        // Custom rendering
    }
    
    public override void OnInput() {
        // Event handling
    }
}

// OS/App.cs
case "Notepad":
    _apps[i].AppObject = new Notepad(300, 200);
    b = true;
    break;

WINDOW|Notepad|700|460
RESIZABLE|true
TASKBAR|true
MAXIMIZE|true
MINIMIZE|true
TOMBSTONE|true
STARTMENU|true
TEXTBOX|1|10|40|680|370|
BUTTON|100|Save As...|10|420|88|28
BUTTON|101|Open...|108|420|72|28
BUTTON|102|New|190|420|60|28
BUTTON|103|Close|260|420|72|28
ONCLICK|100|SAVEDIALOG|notes.txt
ONCLICK|101|OPENDIALOG|
ONCLICK|102|CLEAR|1
ONCLICK|103|CLOSE|
LABEL|guideXOS Notepad|10|10

// OS/App.cs
case "Notepad":
    b = LaunchGXMFromFile(
        "Programs/notepad.gxm", 
        _apps[i].Icon
    );
    break;

Result: 300 lines of C# ? 15 lines of script! ?

Migration Checklist

1. ? Identify apps suitable for GXM scripts (UI-driven, simple logic)
2. ? Create .txt script with WINDOW, controls, events
3. ? Package with GXMPackager
4. ? Copy to Ramdisk/Programs/
5. ? Update App.cs to use LaunchGXMFromFile()
6. ? Test functionality
7. ? Remove old .cs file from DefaultApps/
8. ? Rebuild OS (smaller binary!)

Apps Successfully Migrated to GXM Scripts

Development Workflow Comparison

Built-in App Workflow

1. Edit .cs file in DefaultApps/
2. Build entire OS (5-15 minutes)
3. Build ISO (2-5 minutes)
4. Boot VM
5. Test app
6. Find bug
7. Repeat steps 1-6

Total iteration time: 15-30 minutes

GXM Script Workflow

1. Edit .txt file
2. Run: build-all.ps1 (10 seconds)
3. Run: deploy.ps1 (30 seconds)
4. Boot VM (if not running)
5. Test app
6. Find issue
7. Repeat steps 1-3

Total iteration time: 1-2 minutes (15x faster!)

Performance Benchmarks

Best Practices

Future Enhancements

Planned GXM Script Features

• ?? CANVAS - Drawing area for Paint app
• ??? IMAGE - Display images in Image Viewer
• ?? CALCULATE - Arithmetic for Calculator
• ?? MENUBAR - Menu bar support
• ?? TOOLBAR - Toolbar widget
• ?? STATUSBAR - Status bar at bottom
• ?? THEME - Color theme support
• ?? VAR - Variable storage and logic
• ?? IF/ELSE - Conditional execution
• ?? LOOP - Iteration support

Summary

See Also

• Applications Overview
• GXM Packager Documentation
• GXM Script Reference
• Development Guide
• GUI System