Applications

Application Suite

guideXOS Server is transitioning from the older GXM-centered story toward an app-model-first world. The current repository contains built-in desktop applications, app manifest discovery fixtures, and a new `.gxapp` package format intended to carry binaries for multiple CPU architectures.

Application Story Today

🖥️ Desktop Applications

guideXOS screenshots and existing shell flows show a desktop-oriented OS with utilities such as:

• Console
• Notepad
• Clock
• Task Manager
• Device inventory and system utilities
• Start menu and desktop launch surfaces

📄 App Manifests

The repository includes manifest-based discovery fixtures for future external apps. One example is Apps/HelloWorld/app.json, which is intentionally used for manifest discovery even though the referenced ELF payloads are not present yet.

• App registry should still discover the manifest
• Desktop and launcher surfaces should list the app
• Launching it should return an explicit "manifest found but execution is not implemented yet" style response
• This avoids fake stubs that pretend support exists

📦 Universal Package Direction

Phase 8 planning defines a universal package model where one app package can hold optimized binaries for several architectures.

• ArchitectureDetector runtime API is planned to identify the host CPU
• UniversalAppLoader will select the correct binary from a package
• gxbuild is planned as the packaging and cross-build tool
• The SDK roadmap includes libc, system headers, and toolchains

GXAPP Format

The current canonical package format is .gxapp. It is not ZIP-based and it is intentionally kept simple, bounded, and fail-closed for loader and package-manager paths.

Container Layout

1. Header

Every package starts with a magic header and explicit entry count metadata.

magic         = GXAPP\r\n\x1A
formatVersion = 1
flags         = bit 0 set
entryCount    = number of records

2. Entries

Each entry stores a kind, architecture, path, and inline payload.

kind         = 1 metadata, 2 binary
architecture = CpuArchitecture enum value
path         = metadata.json or bin/<arch>/app.bin
data         = JSON metadata or native executable payload

Metadata Example

The current implementation requires a JSON metadata object like this:

{
  "format": "gxapp",
  "formatVersion": 1,
  "applicationName": "calculator",
  "version": "1.0.0",
  "requiredGuideXOSVersion": "1.0.0",
  "binaries": [
    { "architecture": "amd64", "path": "bin/amd64/app.bin", "entryPoint": "main" }
  ]
}

Validation and Limits

Roadmap Around Applications

The package format is only one piece of the story. The broader plan includes:

• Architecture detection APIs
• Universal application loader behavior
• gxbuild as the packaging and build CLI
• Developer SDK headers and libraries
• musl-based libc integration for portable userspace

Launching Applications

Method 1: App Registry and Desktop Surfaces

Built-in apps and discovered manifests should flow through the normal registry, launcher, and desktop listing paths.

App manifest or built-in registration
    ↓
AppRegistry discovers it
    ↓
Desktop / start menu surface lists it
    ↓
Launcher attempts normal app-model launch

Method 2: Console and Diagnostics

The shell remains a useful place to inspect what is registered and attempt launches during bring-up:

apps
launch <app-id>

// If a manifest exists but execution is not implemented yet,
// the system should fail explicitly instead of pretending success.

Method 3: Package Installation

When `.gxapp` installation is used, packages land under /system/apps after staged validation.

Method 4: Future cross-architecture loading

The long-range goal is for the runtime loader to choose the correct package binary for the active CPU architecture.

Related Topics