Skip to content
Xila
Menu
TutorialsHow-toReferenceExplanationDemonstration
Tutorials
OverviewRun Xila nativelyRun Calculator in the browser
How-to guides
OverviewSet up developmentIntegrate a host applicationBuild a guestAdd a launcher shortcutRun a guestCreate a development packageSubmit a packageRun Xila with DockerValidate Xila changesContribute to CoreManage browser disksWrite documentation
Reference
OverviewHost APIGuest APIShellExperimental package formatDevelopment commandsWASM runtimeHeadless container runtimeGraphics bindings
Explanation
OverviewDevelopment environmentsBrowser storagePackage management architecture
Demonstration

Terminal (executable)

The terminal executable provides a graphical terminal window exposed as a character device and uses it to host the command-line shell.

Last updatedEdit page

The terminal executable provides a graphical terminal window exposed as a character device and uses it to host the command-line shell.

Role

Section titled “Role”
  • Bridges GUI events and text I/O semantics through a mounted /devices/standard_io/terminal device.
  • Launches /applications/executables/command_line_shell with terminal-backed stdin/stdout/stderr.

Startup and lifecycle

Section titled “Startup and lifecycle”
  1. Creates Terminal UI object (window, label display, text input).
  2. Mounts terminal object as /devices/standard_io/terminal character device.
  3. Opens Standard streams on that path.
  4. Executes command-line shell executable.
  5. Runs event loop until terminal window close/delete event.

Runtime integration points

Section titled “Runtime integration points”
  • virtual_file_system::mount_static for runtime device registration.
  • xila::executable::execute to start command-line shell child process.
  • graphics and LVGL for window/input rendering.
  • shared::utf8_chunks for buffered output write handling.

Data and control flow / VFS touchpoints

Section titled “Data and control flow / VFS touchpoints”
  • Write path: shell output -> /devices/standard_io/terminal -> DirectBaseOperations::write -> UI display append.
  • Read path: UI enter key -> validated input queue -> /devices/standard_io/terminal read by shell.
  • Control flow: parent terminal loop keeps processing events while child shell uses same device streams.

Concurrency and event-loop model

Section titled “Concurrency and event-loop model”
  • Terminal executable runs a periodic loop with sleep(20 ms) while polling handle_events.
  • The GUI owns RwLock<CriticalSectionRawMutex, Inner> state. Reads also use a per-open Waiter and a bounded WaitQueue<16> to register wakers instead of repeatedly polling when input is empty.

Failure semantics

Section titled “Failure semantics”
  • Device mount/open/execute failures return executable error and are logged + printed.
  • Resource contention on terminal locks maps to RessourceBusy / file_system::Error::RessourceBusy.

Contract vs implementation

Section titled “Contract vs implementation”
  • Contract: terminal executable exposes a character-device-backed text console and runs shell inside it.
  • Current implementation: LVGL window + textarea, mounted static device node /devices/standard_io/terminal, and shell child execution via executable runtime.

Operational limitations

Section titled “Operational limitations”
  • The input queue receives a line when Enter is pressed; no PTY or full ANSI terminal emulator is implemented. Output recognizes a small subset of ANSI-like clear/home sequences (ESC[2J and ESC[H) but not a general cursor/style parser.
  • UI/event loop cadence is fixed and may affect responsiveness under heavy output.

Device polling, input ownership and cleanup

Section titled “Device polling, input ownership and cleanup”

TerminalExecutable::new(vfs, task) constructs the executable without filesystem writes. Platforms seeds the native launcher descriptor under /configuration/shared/applications/shortcuts/. At runtime, Terminal::new(graphics::ffi_manager()) creates the window and text widgets, and the launcher leaks the resulting Terminal into 'static storage before mounting it as a character device at /devices/standard_io/terminal. The launcher opens the same device three times through Standard::open for stdin, stdout and stderr, then calls executable::execute(..., "/applications/executables/command_line_shell", ...).

I/O contract: the device is a contextual BaseOperations + CharacterDevice, not a direct character device. Each open context gets its own Waiter. An empty blocking read registers a waker in WaitQueue<16> and returns Poll::Pending; cancellation and close unregister pending reads. When Enter is pressed, input bytes plus \n enter the queue and registered readers are notified. Output runs through shared::utf8_chunks; invalid UTF-8 bytes are skipped rather than preserved byte for byte.

The terminal UI sleeps 20 ms between event-processing calls while the command-line shell is scheduled independently. print uses try-locks and returns RessourceBusy under contention; the device maps this to file_system::Error::RessourceBusy.

Current lifecycle limitation: the main executable ignores the returned shell JoinHandle; closing the window ends the terminal’s outer event loop, but this code does not explicitly unmount /devices/standard_io/terminal, free the leaked Terminal allocation, or join/terminate the shell child. Treat repeated mounts and window teardown as areas requiring dedicated lifecycle tests.

Source and API references

Section titled “Source and API references”

References

Section titled “References”

Alix ANNERAUDApache 2.0 License2026