Develop applications in SlOS

Open a workbench

The launcher creates a fresh private developer VM with an editor, the develop client and a loopback compiler worker. It prints the terminal attachment and worker-configuration commands. Enter the printed configuration command in the guest before your first build.

# In an existing SlOS checkout on Linux
make ARCH=x86_64 DOOM=0 development-console
# For an ARM64 guest:
make ARCH=aarch64 BOARD=qemu_virt DOOM=0 development-console

The C path uses the native or cross GNU toolchain and the freestanding SlOS SDK. To build Hew, supply an existing compiler, its matching standard library and the matching native freestanding runtime:

make ARCH=x86_64 DOOM=0 development-console \
  DEVELOPMENT_HEW=/absolute/path/to/hew \
  DEVELOPMENT_HEW_STD=/absolute/path/to/matching/std \
  DEVELOPMENT_HEW_RUNTIME=/absolute/path/to/x86_64/runtime

Keep this worker on a trusted local machine or LAN. Its authenticated HTTP connection is plaintext; it is not an internet-facing build sandbox. Neither credentials nor an old worker endpoint should be copied from an interrupted session.

Start with a small program

init creates a project without overwriting existing source. The C starter prints a greeting; open it in the editor, save it, then build and run:

exec /develop.elf init /home/hello
exec editor /home/hello/main.c
exec /develop.elf build /home/hello
exec /develop.elf run /home/hello

#include "slos.h"
int main(void) {
    puts("Hello from SlOS native C");
    return 0;
}

A Hew starter creates a real counter actor. Its two request/reply calls print 10 and 15:

exec /develop.elf init /home/counter hew
exec editor /home/counter/main.hew
exec /develop.elf build /home/counter
exec /develop.elf run /home/counter

actor Counter {
    var total: i64 = 0;
    receive fn add(x: i64) -> i64 {
        total = total + x;
        total
    }
}
fn main() {
    let c = spawn Counter;
    println(c.add(10).expect("actor reply"));
    println(c.add(5).expect("actor reply"));
}

sources.txt lists the project-local sources in submission order. Include the C translation units and headers, or main.hew and all local Hew imports. Use separate C and Hew projects. The worker uses a fixed build recipe rather than executing an uploaded Makefile or arbitrary command.

The guest checks the returned source identity and native ELF before installing it. Hew builds also retain identities for the compiler, library, runtime and SDK inputs. run waits for the actual child and reports its exit status.

Keep the edit, the error and the last good program

A compiler error leaves the last successfully installed application available. diagnostics revisits the checked compiler response; edit opens the first safe source-and-line location. status distinguishes current source edits, compiler feedback and the selected program.

exec /develop.elf status /home/counter
exec /develop.elf diagnostics /home/counter
exec /develop.elf edit /home/counter
exec /develop.elf rollback /home/counter

rollback verifies and selects the previous build. It does not undo current source edits or restore application data. Saved programs can run without the compiler worker after a clean reboot.

The editor preserves ASCII, tabs and line endings, including a missing final newline, within 128 KiB and 4096 logical lines. Oversize or unsupported files are refused rather than truncated. There is no undo or persistent unsaved-buffer recovery.

A damaged or interrupted delivery cannot replace checked earlier feedback. If new diagnostics could not be saved, the client prints a not-retained warning and stops publication. Keep that terminal text: it may not be available to diagnostics later.

Example: an expense ledger

The two-module Hew ledger adds immutable expense IDs, integer-cent amounts and categories. List entries or total a category. Its records live under /home/expenses, separately from the project's program versions.

exec /develop.elf run /home/ledger -- add lunch-1101 1245 food
exec /develop.elf run /home/ledger -- add bus-1101 350 travel
exec /develop.elf run /home/ledger -- list
exec /develop.elf run /home/ledger -- total food

The example was operated in native x86-64 and AArch64 guests: source was entered in the guest, a new version was built, a bad edit was diagnosed, and the earlier program was selected without losing expenses or the edit. After clean resume, the saved program read the same data with the worker stopped.

Identical resubmissions are duplicates; changing an existing ID is refused. The ledger has 64 lifetime IDs and one writer, with no deletion or encryption. It is a small application example, not financial accounting software.

Example: a persistent actor job queue

The Hew queue stores jobs and immutable results while two supervised actor workers calculate sums of squares. An installed service manager can start the selected program at boot. A transient worker failure retries with a replacement; a permanent failure is retained after three attempts.

# With the queue project and installed service manager prepared
exec /develop.elf build /home/jobqueue
exec service configure queue jobqueue
exec service enable
exec service status
exec /develop.elf run /home/jobqueue -- submit jobqueue report-1 100
exec /develop.elf run /home/jobqueue -- await jobqueue report-1
exec /develop.elf run /home/jobqueue -- jobs jobqueue

Operand 100 produces 338350. Repeating the same job ID returns its existing record; changing its operand or mode is refused. Pause accepts pending work, resume processes it, and drain finishes existing work while refusing new IDs.

Stop the service before editing, rebuilding or rolling back its project. Restarting selects the verified program while retaining queue data under /queues/NAME. Code rollback does not erase jobs or current source edits.

A real 24-hour workload on each native QEMU target exercised queued-work recovery across clean reboots and transient and permanent worker failures. That is bounded application operation, not an arbitrary power-loss guarantee. The queue has 128 lifetime immutable job IDs, two resident workers and one client operation at a time.

These ledger and queue sections are application examples, not video replays. For recorded multi-node work and failure recovery, watch the distributed renderer and durable debugger.

Installed workspace: inputs, reports and program versions

The separate installed report application accepts a canonical expense TSV file and keeps an immutable input snapshot. Each row contains a category, a tab and integer cents. Enter this small file, with a newline after each row:

food	125
travel	200
food	75

# With the report workspace installed
exec editor /expenses.tsv
report accept 1 /expenses.tsv
report run 1
report status 1
cat /workbench/runs/1/report.tsv
bundle versions

The report totals 400 cents: food 200, travel 200 and tools 0. Changing the original input after acceptance does not change the accepted work. Status distinguishes completed, pending and blocked runs; working files remain under /workbench.

The Hew bundle manager validates and activates immutable program versions. Stop the VM before offline installation or update. A rejected update retains the previous usable installation; verified rollback changes code selection while preserving work and unrelated files. This is a bounded single-writer workspace, not a transactional package manager.

The report accepts eight run slots and bounded inputs; its optional HTTP service belongs on a trusted local network. report recover checks eligible pending runs without rerunning completed reports. Use report --help and bundle --help for the installed version's commands. The manual and Hew command toolbox explain command selection and related utilities.

Return to saved work

For an ordinary handoff, save your files, run fsck and halt, then reopen the stopped session. The launcher checks that the guest requested shutdown and that the disk and boot provider are unchanged.

# In SlOS, after saving your work:
fsck
halt
# On the host, using the session directory printed by the launcher:
make ARCH=x86_64 DOOM=0 development-console \
  DEVELOPMENT_SESSION=/owned/private-parent/stopped-session

An interrupted session is not silently resumed. Read-only project rescue can export checked saved source, compiler feedback and selected/previous builds from an independently stopped, readable volume. If SlFS v2 has a committed update awaiting replay, explicit recovery boots only a new byte-exact copy with the original session's captured kernel. The interrupted original remains unchanged.

# For a readable, independently stopped original
make ARCH=x86_64 DOOM=0 development-rescue \
  DEVELOPMENT_SESSION=/owned/private-parent/interrupted-session \
  DEVELOPMENT_RESCUE_PROJECT=/home/demo \
  DEVELOPMENT_RESCUE_DESTINATION=/owned/private-parent/new-project-bundle

# If genuine pending v2 redo requires replay, use a different fresh bundle:
make ARCH=x86_64 DOOM=0 development-recover \
  DEVELOPMENT_SESSION=/owned/private-parent/interrupted-session \
  DEVELOPMENT_RESCUE_PROJECT=/home/demo \
  DEVELOPMENT_RESCUE_DESTINATION=/owned/private-parent/new-recovery-bundle

Import that checked export to continue in a fresh workbench:

# Start a new session from an existing checked project export
make ARCH=x86_64 DOOM=0 development-console \
  DEVELOPMENT_IMPORT_PROJECT=/owned/private-parent/project-bundle

Import preserves verified project files, current saved edits and installed build choices. It creates a new v2 volume and new worker credentials. Configure the new worker before rebuilding; do not combine import with DEVELOPMENT_SESSION.

Pending candidates are not promoted or copied as authority. An explicit run-saved PROJECT can verify and execute only the installed selection in an already readable guest while preserving pending evidence. It does not repair a filesystem or permit unsafe original-session resume.

Project recovery excludes unrelated application data, credentials and unsaved editor buffers. For example, a ledger project export does not bring along /home/expenses, and a queue export does not restore /queues/NAME. Keep the original private and backed up; corrupt or ambiguous inputs are refused.