update docs
This commit is contained in:
@@ -0,0 +1,215 @@
|
||||
# Desktop, programs, and networking
|
||||
|
||||
Development reference and historical context. For current operating instructions, use the [user manual](../README.md). Acceptance applies only to the source and artifacts identified in each record.
|
||||
|
||||
|
||||
[Documentation index](README.md) · [Cartridge guide](cartridges.md) · [DATA guide](data.md)
|
||||
|
||||
M8 software checks passed in the ARM virtual machine. The [validation report](m8-validation.md)
|
||||
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>`:
|
||||
|
||||
```sh
|
||||
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:
|
||||
|
||||
```sh
|
||||
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](data.md) 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](cartridges.md), with:
|
||||
|
||||
```toml
|
||||
[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](workstation.md). They
|
||||
contain metadata plus xz software bundles in payload partitions. In FDS:
|
||||
|
||||
```sh
|
||||
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:
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```sh
|
||||
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:
|
||||
|
||||
```sh
|
||||
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.
|
||||
|
||||
```sh
|
||||
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:
|
||||
|
||||
```sh
|
||||
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](https://xorg.freedesktop.org/archive/X11R7.7/doc/xproto/x11protocol.html)
|
||||
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](https://fontconfig.pages.freedesktop.org/fontconfig/fontconfig-user.html),
|
||||
so exporting the filesystem does not invalidate their directory timestamps.
|
||||
Reference in New Issue
Block a user