BritneyDOS Go SDK

First-class Go SDK for native BritneyDOS applications.

This repository is intentionally separate from BritneyDOS itself. Applications import stable Go packages from this module while BritneyDOS implementation details and the native JSON protocol remain behind the SDK boundary.

Status

v0.7.0 adds BritneyGUI Native API 1.5 multiline editing, keyboard/mouse modifiers, clipboard, and asynchronous file-dialog bindings for BritneyDOS 0.37.0. API 1.3 and 1.4 GUI applications remain source-compatible.

The SDK now uses BritneyDOS itself for:

• runtime detection and API negotiation (hello)
• system information and uptime
• physical/swap memory status
• network interface/DNS/gateway status
• installed package list and package details
• whole-file reads/writes and directory/stat/mkdir/remove/rename operations
• BritneyDOS shell environment reads/writes
• captured synchronous and asynchronous native processes
• event subscriptions, timers, process-completion events, and filesystem-change notifications
• BritneyGUI windows, retained drawing, native controls, menus, message boxes, typed events, and callback-driven application loops

The SDK uses no cgo and has no third-party dependencies.

Compatibility behavior

The SDK deliberately distinguishes BritneyDOS from normal Linux development:

• If BRITNEYDOS_API is present, OS-backed calls use it. A broken API is returned as an error where the public function can report errors; the SDK does not silently drop down to Linux implementation details.
• If BRITNEYDOS_API is absent, the Linux/bootstrap backend remains available for development and older BritneyDOS native environments where an equivalent local operation exists.
• environment.Get, environment.Lookup, and environment.List retain their v0.1 signatures and therefore cannot return transport errors. New GetE, LookupE, and ListE functions provide strict error-aware access.

Native API compatibility

BritneyDOS	Native API	SDK functionality
0.32.0+	1.0+	runtime, system, memory, network status, package list
0.33.0+	1.1+	filesystem services, shell environment, managed processes, package details
0.34.0+	1.2+	event subscriptions, timers, process completion, filesystem watches
0.35.0+	1.3+	BritneyGUI windows, drawing, buttons, dialogs, keyboard/mouse events
0.36.0+	1.4+	labels, text boxes, checkboxes, radios, list boxes, menus, focus and callback-friendly control events

API 1.3 is backward-compatible with API 1.0, 1.1, and 1.2.

Packages

Package	Purpose
britneydos	Runtime detection, API negotiation, capabilities and SDK/runtime versions
console	Console input/output, clear screen, terminal title
environment	BritneyDOS shell environment plus process-scoped drive/root values
event	Native API 1.2 subscriptions, timers, process completion, and filesystem changes
fs	DOS-aware filesystem operations, mostly backed by Native API 1.1
gui	BritneyGUI Native API 1.3/1.4 windows, drawing, controls, menus, dialogs, typed events and application loops
process	Interactive local processes plus Native API managed/captured processes
system	BritneyDOS OS, architecture, hostname, boot mode and uptime
memory	BritneyDOS physical/swap memory status
network	BritneyDOS interface/DNS/gateway status plus HTTP GET/downloads
packages	Installed BritneyDOS package database and package detail lookup
bdostime	Clock, sleep and ticker helpers

Requirements

For all v0.6 native features:

• BritneyDOS 0.36.0 or newer
• BritneyDOS Native Application API 1.4
• Go 1.22 or newer

The bootstrap development backend works on Linux without BritneyDOS for operations that have a safe local equivalent.

Quick start inside BritneyDOS

C:\>DEV NEW GO HELLOSDK
C:\>CD C:\DEV\HELLOSDK
C:\DEV\HELLOSDK>go get github.com/Starstreak/BritneyDOS-Go-SDK@v0.7.0

package main

import (
    "fmt"

    bdos "github.com/Starstreak/BritneyDOS-Go-SDK"
    bdosfs "github.com/Starstreak/BritneyDOS-Go-SDK/fs"
    "github.com/Starstreak/BritneyDOS-Go-SDK/memory"
    "github.com/Starstreak/BritneyDOS-Go-SDK/system"
)

func main() {
    if err := bdos.Require(); err != nil {
        panic(err)
    }

    info, err := system.Info()
    if err != nil {
        panic(err)
    }
    mem, err := memory.Get()
    if err != nil {
        panic(err)
    }
    entries, err := bdosfs.ReadDir(`C:\DEV`)
    if err != nil {
        panic(err)
    }

    fmt.Printf("%s %s, API %s\n", info.Name, info.Version, bdos.APIVersion())
    fmt.Printf("Memory load: %.1f%%\n", mem.Load)
    fmt.Printf("C:\\DEV contains %d entries\n", len(entries))
}

Build and run with BritneyDOS's self-hosted tools:

C:\DEV\HELLOSDK>DEV BUILD
C:\DEV\HELLOSDK>BIN\HELLOSDK.EXE

On BritneyDOS 0.36.0 the SDK should report API 1.4 and bridge api-v1.

Native filesystem operations

Whole-file and directory helpers automatically use Native API 1.1 when it is available:

data, err := bdosfs.ReadFile(`C:\CONFIG\APP.TXT`)
err = bdosfs.WriteFile(`C:\DATA\OUT.BIN`, data, 0644)
entries, err := bdosfs.ReadDir(`C:\DATA`)
info, err := bdosfs.Stat(`C:\DATA\OUT.BIN`)
err = bdosfs.MkdirAll(`C:\DATA\CACHE`, 0755)
err = bdosfs.Rename(`C:\DATA\OLD.TXT`, `C:\DATA\NEW.TXT`)
err = bdosfs.Remove(`C:\DATA\NEW.TXT`)

ReadFile and WriteFile automatically chunk large files to the API 1.1 512 KiB transfer size. ReadDir paginates large directories.

fs.Open, fs.Create, fs.Resolve and fs.Chdir remain process-local because Native API 1.1 does not expose streaming file descriptors or a per-client current-directory object. Relative API-backed paths still follow fs.Chdir because the SDK converts them to absolute DOS paths before sending them to BritneyDOS.

Native API 1.1 owns file permissions. The perm argument on API-backed WriteFile, Mkdir, and MkdirAll is retained for Go source compatibility but is not transmitted to BritneyDOS 0.33.0.

BritneyDOS environment

The environment package now talks to the BritneyDOS shell:

value, defined, err := environment.LookupE("MY_SETTING")
err = environment.Set("MY_SETTING", "hello")
values, err := environment.ListE()
err = environment.Unset("MY_SETTING")

This means an API-backed environment.Set changes the BritneyDOS shell environment rather than merely editing the current Go process's Linux environment. BritneyDOS protects read-only values such as BRITNEYDOS_API and BRITNEYDOS_API_VERSION.

CurrentDrive, Root, and DOSPath remain process-scoped values because they describe the current native child rather than global shell state.

Managed processes

Interactive processes continue to use the normal streaming interface:

err := process.Run("EDITOR.EXE", `C:\README.TXT`)

For OS-managed captured processes, use Native API 1.1:

result, err := process.RunResult("TOOL.EXE", "--version")
if err != nil {
    panic(err)
}
fmt.Print(string(result.Stdout))
fmt.Println("Exit:", result.ExitCode)

Options map directly to the language-neutral BritneyDOS process service:

result, err := process.RunResultWithOptions("TOOL.EXE", process.Options{
    Dir: `C:\DEV`,
    Env: map[string]string{"MODE": "test"},
    Timeout: 10 * time.Second,
}, "--check")

Asynchronous captured processes use process.start and process.wait:

p, err := process.StartManaged("TOOL.EXE", "--long-job")
if err != nil {
    panic(err)
}
result, err := p.Wait()

BritneyDOS 0.33.0 captures up to 1 MiB each of stdout and stderr. Result reports truncation. API 1.1 does not yet provide remote stdin streaming or process kill, so Start, Run, and StartWithIO intentionally remain local/interactive operations.

Package details

info, err := packages.Info("GO")
if err != nil {
    panic(err)
}
fmt.Println(info.Name, info.Version, info.SHA256)
for _, file := range info.Files {
    fmt.Println(file)
}

Events and timers

BritneyDOS 0.34.0 exposes Native API 1.2 event queues. A Go application can subscribe and block efficiently until the OS delivers an event:

subscription, err := event.Subscribe(event.TimerFired, event.ProcessCompleted)
if err != nil {
    panic(err)
}
defer subscription.Close()

timer, err := subscription.NewTimer(time.Second, true)
if err != nil {
    panic(err)
}
defer timer.Cancel()

for {
    result, err := subscription.Wait(10 * time.Second)
    if err != nil {
        panic(err)
    }
    if result.TimedOut {
        continue
    }
    if result.Dropped != 0 {
        fmt.Printf("warning: %d events dropped\n", result.Dropped)
    }
    fmt.Println(result.Event.Type)
}

Wait(0) waits indefinitely. Poll(limit) reads queued events without blocking. BritneyDOS uses bounded event queues, so both methods expose the OS-reported drop count instead of hiding overflow.

Known event payloads have typed helpers:

switch e.Type {
case event.TimerFired:
    fired, err := e.AsTimerFired()
case event.ProcessCompleted:
    completed, err := e.AsProcessCompleted()
case event.FilesystemChanged:
    change, err := e.AsFilesystemChanged()
}

Filesystem watching uses DOS paths and can be recursive:

watch, err := event.WatchFilesystem(`C:\DATA`, true, 500*time.Millisecond)
if err != nil {
    panic(err)
}
defer watch.Close()

Native API 1.2 filesystem notifications are snapshot-based. A rename can therefore appear as a remove plus create, and an overflow action means the application should explicitly rescan the watched tree.

To observe process.completed, create the subscription before starting the managed process. Captured stdout/stderr remains available through the process package rather than being duplicated into the event queue.

BritneyGUI

BritneyDOS 0.36.0 exposes Native API 1.4. The gui package keeps the API 1.3 drawing/button interface source-compatible and adds typed native controls plus a callback-driven application loop.

app := gui.NewApp()
win, err := app.NewWindow(gui.WindowOptions{Title: "Hello", Width: 640, Height: 400})
if err != nil {
    panic(err)
}
defer win.Close()

name, err := win.NewTextBox(gui.TextBoxOptions{ID: "name", X: 30, Y: 60, Width: 240})
if err != nil {
    panic(err)
}
remember, _ := win.NewCheckBox(gui.CheckBoxOptions{ID: "remember", Text: "Remember me", X: 30, Y: 110})
button, _ := win.NewButton(gui.ButtonOptions{ID: "hello", Text: "Hello", X: 30, Y: 160, Width: 100, Height: 30})

button.OnClick(func() {
    text, _ := name.Text()
    _, _ = win.MessageBox(gui.MessageBoxOptions{Title: "Hello", Message: "Hello, " + text + "!"})
})
remember.OnChange(func(checked bool) {
    fmt.Println("remember:", checked)
})
win.OnKey(func(key gui.Key) {
    if key.Key == "escape" {
        app.Quit()
    }
})

win.Present()
name.Focus()
if err := app.Run(); err != nil {
    panic(err)
}

API 1.4 controls are exposed as Label, TextBox, CheckBox, RadioButton, ListBox, and Menu. Controls support removal, visibility, enabled state and keyboard focus where applicable. Text boxes expose Text/SetText, checkboxes and radio buttons expose Checked, and list boxes expose Selection/SetSelection.

App.Run dispatches typed GUI events to registered callbacks. Low-level Window.Wait, Window.Poll, and Window.Dispatch remain available for applications that prefer an explicit event loop. Existing API 1.3 drawing and button programs still work on BritneyDOS 0.35.0; API 1.4 controls return gui.ErrControlsRequired on older systems.

Drawing remains retained: Clear resets the client display list, FillRect and DrawText append drawing operations, and Present redraws the complete window and server-managed controls. BritneyDOS currently owns one top-level GUI session at a time.

Runtime and capabilities

runtime := bdos.Runtime()
fmt.Println(runtime.Version)
fmt.Println(runtime.API)
fmt.Println(runtime.Capabilities)

if bdos.HasFeature("fs.read") {
    // Native API 1.1 filesystem service is available.
}

Other languages

The SDK mirrors BritneyDOS's language-neutral Native API rather than moving OS behavior into Go-only services. This keeps the on-wire application platform usable by future non-Go SDKs without duplicating operating-system functionality.

Development on regular Linux

When BRITNEYDOS_API is absent, existing system, memory, network, filesystem, environment and interactive process helpers retain their Linux development behavior where practical. BritneyDOS-only managed-process and package database calls require the Native API.

BritneyGUI editor APIs

BritneyDOS 0.37.0 / Native API 1.5 adds a native multiline editor:

editor, err := win.NewTextArea(gui.TextAreaOptions{
    ID:     "document",
    X:      20,
    Y:      50,
    Width:  680,
    Height: 420,
})
if err != nil {
    panic(err)
}

editor.OnChange(func(state gui.TextAreaState) {
    fmt.Println("cursor:", state.Cursor)
})

Cursor and selection offsets are Unicode rune indexes rather than UTF-8 byte offsets. TextArea.State, SetText, Select, Focus, enable/disable, visibility and removal all use the Native API.

Typed key and mouse events expose Ctrl, Alt, and Shift, so application shortcuts are straightforward:

win.OnKey(func(key gui.Key) {
    if key.Ctrl && key.Key == "s" {
        saveDocument()
    }
})

The API 1.5 clipboard is session-validated and independent of X11/Wayland:

_ = win.SetClipboardText("Hello")
text, _ := win.ClipboardText()
_ = win.ClearClipboard()

File dialogs are asynchronous and integrate with App.Run():

_, err := win.OpenFileDialog(gui.FileDialogOptions{
    Title:      "Open",
    Path:       `C:\DOCUMENTS`,
    Extensions: []string{".txt", ".md"},
}, func(result gui.FileDialogResult) {
    if result.Selected() {
        fmt.Println(result.Path)
    }
})

SaveFileDialog uses the same callback model and supports a default Filename.

Examples

• examples/hello
• examples/sysinfo
• examples/files
• examples/network
• examples/packages
• examples/process
• examples/events
• examples/gui

examples/sysinfo is the basic API smoke test. examples/files exercises the API 1.1 directory service automatically on BritneyDOS 0.33.0+, examples/process runs an arbitrary native executable through the managed process API, and examples/events verifies API 1.2 subscription/timer delivery. examples/gui is the first application written against the high-level BritneyGUI Go package rather than the raw JSON API.

Test

go test ./...
go vet ./...
CGO_ENABLED=0 go test ./...

Repository/module path

The module currently uses:

github.com/Starstreak/BritneyDOS-Go-SDK

If your repository uses a different module path, change the module line and imports consistently. The versioned updater bundle detects the target module path and substitutes it into updated source files automatically.

License

MIT, matching the SDK's existing license.