9.5 KiB
Desktop, programs, and networking
Development reference and historical context. For current operating instructions, use the user manual. Acceptance applies only to the source and artifacts identified in each record.
Documentation index · Cartridge guide · DATA guide
M8 software checks passed in the ARM virtual machine. The validation report records desktop, program and networking evidence. Raspberry Pi video output and Dasung display quality remain deferred physical checks.
What starts when you boot
FDS opens its ordinary-user console first. Xorg, WindowMaker, and the DHCP client are installed in SYSTEM but are absent from the boot bundle. Dasung control remains in the base boot bundle, including when no desktop is running.
The default graphical backend is Xorg on virtual terminal 2, using its built-in modesetting driver. The physical keyboard and pointer use libinput. Console access remains on the original terminal. There is no display manager. Physical VC4 output, monitor resolution, and E-Ink appearance still require Pi testing.
Start and stop the desktop
At FDS>:
fds profiles
fds profile activate windowmaker
fds profiles
Activation is asynchronous. The second status command reports the selected
profile and an activation-to-ready duration once WindowMaker is ready. This
measurement starts at the activation request, so time spent deciding when to
start the desktop is excluded. fds boot-profile also records the first desktop
readiness event for the boot. Neither measure includes firmware or power-on.
The desktop opens an FDS terminal. Right-click its white background to open the menu, launch another terminal, enable/disable Ethernet, or return to the console. To stop it from either a terminal or the console:
fds profile deactivate
Stopping the desktop closes its terminal and all processes descended from its
session. Save work first. Files in /home/fds survive desktop restarts during the
same boot; the home directory is still temporary and disappears at shutdown.
Use DATA for persistent files. Removing an active DATA cartridge also
stops the desktop before flushing DATA, because desktop applications may use it.
fds-profile status, fds-profile activate windowmaker, and
fds-profile deactivate provide the standalone static helper interface.
ENVIRONMENT cartridges
An ENVIRONMENT cartridge is a read-only EROFS partition named FDS_ENVIRONMENT.
Its FDS/CARTRIDGE.TOML uses the documented manifest format, with:
[activation]
profile = "windowmaker"
When exactly one eligible ENVIRONMENT cartridge is present, the daemon requests WindowMaker after console readiness. The graphical runtime comes from SYSTEM; the cartridge provides a declarative request, never a privileged executable. Unknown profile names do not execute anything. If several eligible cartridges arrive together, select a profile explicitly instead of relying on bay ordering.
Eject its bay with fds eject N. The desktop stops before SAFE is reported.
Surprise removal also stops its associated desktop. Manually deactivating while
the cartridge remains inserted suppresses automatic reactivation until removal
and reinsertion. A manually started desktop is independent of ENVIRONMENT media.
A cartridge-service restart reevaluates mounted media and retires old optional
sessions; this is a maintenance operation, not a way to preserve desktop jobs.
E-Ink defaults
fds-eink installs the WindowMaker policy and Terminus fonts: a white background,
black text and borders, grayscale controls, outline movement/resizing, no
animations, no blinking decorations, no app-icon bounce, no dock, no compositor,
and no periodically updating clock. X11 compositing is disabled. The terminal
uses black on white and a nonblinking cursor.
Defaults are copied into the ordinary user's ~/GNUstep/Defaults at the first
session. Later sessions preserve edits there. They are temporary unless you
explicitly store a copy on DATA. The authoritative image defaults live in
/usr/share/fds/eink; edit their package sources and rebuild SYSTEM to change the
machine-wide defaults.
Font caches and X11 font indexes are generated while building the image. An active X server's keyboard map is session state, generated only on desktop activation. That is separate from global boot-time cache generation.
Launch a software cartridge
Build current software cartridges on a Linux workstation. They contain metadata plus xz software bundles in payload partitions. In FDS:
fds bay 4
fds run 4 -- demo.hello:hello
fds eject 4
Use the software id and command listed by fds bay. The guest verifies and
extracts the bundle into a read-only temporary cache, then starts it as UID 1000.
There are no guest software build hooks.
Legacy PROGRAM compatibility
Existing PROGRAM media contains a read-only EROFS partition named FDS_PROGRAM, metadata
in FDS/CARTRIDGE.TOML, and its self-contained application files:
app/bin/editor
app/lib/
app/share/
FDS validates and mounts it at /run/fds/apps/<cartridge-id>. Insertion does not
run anything, and the mount initially disallows execution. To launch an executable
named editor from bay 4:
fds cartridge 4
fds run 4 -- editor
Use a simple executable name from app/bin, followed by that program's arguments.
The daemon enables read-only execution and starts it as UID 1000, with no added
privileges. Executable paths must remain within the cartridge's app directory.
Programs receive FDS_APP, a PATH including app/bin, LD_LIBRARY_PATH including
app/lib, and XDG_DATA_DIRS including app/share. Bundled libraries can also use
an executable-relative RPATH. FDS does not resolve dependencies across cartridges.
Programs are background jobs. Graphical programs can use the active authenticated X display. Standard output/error goes to the bounded, temporary cartridge log:
tail /run/log/cartridged/current
fds bay 4
fds eject 4
The bay status reports managed processes. Eject stops the whole process group,
including forked descendants, before unmounting. The existing DATA form remains
fds run N -- /absolute/system/command arguments, using /data as its working
directory. DATA itself remains mounted with execution disabled.
Ethernet on demand
External networking is off until explicitly requested or a mapped USB Ethernet cartridge produces a real network interface. Interfaces are associated with their USB ancestors; a descriptive label alone does not start networking. Wi-Fi setup is not implemented by this Ethernet policy. The local loopback interface is always up for applications on the same machine; it does not enable external traffic.
fds network on
fds profiles
ip -brief address
ip route
fds network off
Enabling networking starts DHCP without waiting for a lease. An absent server
cannot delay FDS>. Explicit activation selects available Ethernet interfaces;
automatic activation selects interfaces under mapped cartridge USB devices.
Stopping networking stops DHCP, brings the managed interfaces down, and clears
temporary DNS settings. This initial profile uses IPv4 DHCP; it disables kernel
IPv6 autoconfiguration on those interfaces. After an explicit stop, an inserted Ethernet
cartridge remains suppressed until it is removed, or you enable networking again.
Leases, DNS settings, and logs live under /run; nothing makes SYSTEM writable.
/etc/resolv.conf points to /run/fds/resolv.conf. Inspect
/run/log/network/current when an address is missing.
Development and troubleshooting
The production console image includes the real desktop stack. The development image adds Xvfb and X11 diagnostics for a virtual display without a connected GPU:
make rootfs PROFILE=development
make desktop-test
The test creates its own disposable image selecting Xvfb; the normal development image still selects Xorg. Never mistake an Xvfb pass for Pi graphics verification. Changing the SYSTEM image profile requires building that rootfs first; the image builder rejects a profile label that disagrees with its embedded identity.
If desktop activation fails, fds profiles reports it. Read
/run/log/xserver/current and /run/log/desktop/current, then deactivate before
retrying. Xorg's detailed log is /run/log/xserver/Xorg.0.log. X access requires
an authority cookie readable only by root and the FDS group; do not use xhost +
or disable access control as a workaround.
Dependency rationale: Xorg supplies the display server and modesetting driver;
libinput supplies keyboard/pointer input; WindowMaker supplies window management;
Terminus and fontconfig supply the typography; xterm supplies a terminal; the static FDS helper
observes X11 property events for readiness without polling delays; xset/xsetroot apply the
static session settings. Xvfb, xdotool, xwd, xwininfo, xdpyinfo, xprop, and xauth are
optional development diagnostics. fds-dhcpcd builds the pinned upstream DHCP
client with privilege separation and volatile state paths, omitting its runit
service files. All FDS control helpers remain static Rust/musl binaries.
The readiness observer uses the X11 core protocol and establishes its property subscription before launching the window manager. Font caches are generated with the image's normalized timestamp, following fontconfig's reproducible-cache support, so exporting the filesystem does not invalidate their directory timestamps.