99 lines
3.8 KiB
Markdown
99 lines
3.8 KiB
Markdown
# Use cartridges and run programs
|
|
|
|
A bay number identifies a physical slot, from `01` through `12`. It stays tied
|
|
to the slot rather than the order in which Linux discovers USB disks.
|
|
|
|
| Cartridge | Role |
|
|
| --- | --- |
|
|
| SYSTEM | Supplies the read-only operating system used at boot |
|
|
| PROGRAM | Supplies applications and their runtime dependencies |
|
|
| DATA | Stores your writable files at `/data` |
|
|
| ENVIRONMENT | Requests an installed desktop profile, such as WindowMaker |
|
|
|
|
## Inspect a bay
|
|
|
|
Insert the cartridge, then run:
|
|
|
|
```sh
|
|
fds bays
|
|
fds bay 01
|
|
```
|
|
|
|
USB discovery takes place asynchronously. `fds bay` shows its state, identity,
|
|
mount location, running process count and software catalogue. `fds --json bay 01`
|
|
returns structured details, including command aliases. `fds rescan` refreshes
|
|
the inventory. No application starts merely because a PROGRAM cartridge is inserted.
|
|
|
|
| State | Meaning and next action |
|
|
| --- | --- |
|
|
| EMPTY | No cartridge is detected |
|
|
| MOUNTED READ ONLY | Contents are available; PROGRAM commands can run |
|
|
| MOUNTED READ WRITE | DATA is active at `/data` |
|
|
| SAFE | Storage is released; remove the cartridge |
|
|
| PROTECTED | This cartridge supplies the running SYSTEM; shut down before removal |
|
|
| UNCONFIGURED | The physical slot needs a bay mapping |
|
|
| ERROR / AMBIGUOUS | Read the detail; correct the media or mapping before use |
|
|
|
|
## Run a software command
|
|
|
|
For the included hello/report cartridge:
|
|
|
|
```sh
|
|
hello 'Hello from my cartridge'
|
|
report
|
|
fds run 01 -- demo.hello:hello 'Hello from my cartridge'
|
|
```
|
|
|
|
Direct commands run in the foreground with your terminal, input/output streams,
|
|
arguments, working directory and exit code. Pipes and redirection work normally.
|
|
`fds run` starts a managed background program and prints its PID; its output is
|
|
written to `/run/log/cartridged/current`. Both forms run as the ordinary FDS user
|
|
and are tracked for cartridge removal.
|
|
|
|
New cartridges run directly from read-only payload partitions. They require no
|
|
program extraction or compilation on FDS. The stable `/run/fds/bin` directory is
|
|
already in the console and terminal PATH, so existing shells see inserted commands.
|
|
|
|
If cartridges export the same command name, the lowest numbered bay wins.
|
|
Within a bay, the first software selector in lexical order wins. System commands
|
|
appear earlier in PATH and retain their usual meanings. To select a specific
|
|
cartridge command, use its qualified alias:
|
|
|
|
```sh
|
|
b01:demo.hello:hello 'Explicit bay and software'
|
|
fds run 01 -- demo.hello:hello
|
|
```
|
|
|
|
Legacy PROGRAM media uses `b01:COMMAND` for a qualified direct alias. Commands
|
|
are removed on eject/unplug; a shared name falls back to the next available bay.
|
|
After the final cartridge is removed, a shell may remember the old executable
|
|
path; `hash -r` clears Bash's command cache.
|
|
|
|
## Eject safely
|
|
|
|
```sh
|
|
cd "$HOME"
|
|
fds eject 01
|
|
fds bay 01
|
|
```
|
|
|
|
Eject stops managed programs, flushes writable storage and releases its mounts.
|
|
Remove the cartridge after **SAFE** is reported. If eject fails, close files,
|
|
shells or extra mounts using that cartridge and retry. Never treat a timeout as
|
|
permission to pull writable media. Use `fds poweroff` to stop the whole computer;
|
|
swap the running SYSTEM only after shutdown.
|
|
|
|
The [control panel](desktop.md) provides the same safe-eject action. For writable
|
|
storage behavior, see [DATA and files](data.md).
|
|
|
|
## Configure physical bay numbering
|
|
|
|
Run `fds topology` with one identifiable USB device inserted in each slot in
|
|
turn. Record the controller/hub topology for both USB 2 and USB 3 connections,
|
|
then map those stable identities in the machine's `bays.toml`. Do not map
|
|
`/dev/sda` names or enumeration order. The emulator supplies its own known map.
|
|
|
|
Use [machine settings](internal-storage.md) to validate, export and install the
|
|
configuration. The detailed wiring/calibration procedure is in the
|
|
[hardware engineering reference](developer/cartridges.md).
|