This chapter lists every command that the KDOS source tree itself installs on the target system,
with a one-line description, the directory it is installed in, and a link to the chapter that
documents it in full. It closes with the scripts and make targets a contributor runs on the
build machine. Use it to find out what a kdos-* name is, where it lives, or where to read more;
it is a lookup table, not an explanation, and assumes you have met the vocabulary in
The programs or the glossary.
Software built from ports/core/ (bash, foot, podman, mpv and the rest) is upstream’s, and
upstream’s manual pages describe it; the ports catalogue lists every port by
shelf, with its phase. This index lists what this repository writes: the programs under src/,
the scripts under fs/, and the handful of wrapper scripts that a port recipe writes into its
package. Each entry below matches the source that installs it. The one exception is
the upstream commands the boot path and the book name,
which init and the service scripts run by name.
KDOS installs its own commands into six directories. Compiled programs from src/ go in
/usr/bin, and the root daemons go in /usr/sbin. The session scripts from fs/, kdos and the
other session-side names of the ksvc binary, and the kdos-appbox names go in /usr/local/bin,
which precedes /usr/bin on the PATH that /etc/profile sets. kdos-bootctl is a name of the
same ksvc binary but is in /usr/bin, because the initramfs build copies it by path.
| Directory | What is there |
|---|---|
/usr/bin |
kdos-shell and its 54 other names, kdos-comp, kdos-term, kdos-res, kdos-lock, kdos-record, kdos-boxsock, kdos-pack, kdos-splash, kdos-theme, kdos-bb, kinstall, kpkg and its four other names, kdos-bootctl, the daemon clients, the two setuid helpers, and the wrapper scripts ports write |
/usr/sbin |
The five root daemons, and ksvc with its second name service |
/usr/local/bin |
kdos and the other session-side names of the ksvc binary, kdos-appbox with kdos-box, xdg-open and one shim per boxed application, and the session scripts from fs/ |
/usr/local/sbin |
kdos-getty, which /etc/inittab runs on tty1 and tty2, and kdos-login, which it runs on tty1 |
/usr/lib, /usr/libexec/kdos |
xdg-desktop-portal-kdos, started by D-Bus; kdos-boxinit, which runs inside a box |
Many of the commands below are one binary installed under several names. The binary reads the
name it was started by (the basename of argv[0]) and behaves as that command, so no shell
wrapper sits anywhere in the chain. kdos-shell, ksvc and kpkg also accept the command name
as the first argument when they are started under a name their table does not hold, such as the
build output’s own name: kdos-tools service list behaves as service list. Under a listed name,
including kdos-shell and kpkg, the first argument is an ordinary argument.
| Binary | Installed as | Names it answers to | Where the name table lives |
|---|---|---|---|
kdos-shell |
/usr/bin/kdos-shell |
55 | src/desktop/kdos-shell/main.c |
ksvc (the kdos-tools port) |
/usr/sbin/ksvc |
12 | src/system/kdos-tools/main.c |
kpkg |
/usr/bin/kpkg |
5 | src/system/kdos-kpkg/main.c |
kdos-appbox |
/usr/local/bin/kdos-appbox |
3 fixed, plus one per application | src/system/kdos-appbox/main.c |
kdos-powerd |
/usr/sbin/kdos-powerd |
2: kdos-powerd and its client kdos-power |
src/daemons/kdos-powerd/build.sh (the symlink) |
kdos-mountd |
/usr/sbin/kdos-mountd |
2: kdos-mountd and its client kdos-mount |
src/daemons/kdos-mountd/build.sh (the symlink) |
kdos-energyd |
/usr/sbin/kdos-energyd |
2: kdos-energyd and its client kdos-energy |
src/daemons/kdos-energyd/build.sh (the symlink) |
The twelve names of the ksvc binary are kdos, ksvc, service, kdos-getty,
kdos-bootctl, kdos-shot, kdos-banner, kdos-fetch-app, kdos-fetch-static, kdos-sfx,
kdos-mpctl and kdos-share. The five names of kpkg are kpkg, kpkgadd, kpkgdel,
kpkgbuild and kpkgdepends; kpkg itself is built and installed by
script/phases/10_bootstrap/120_kpkg.sh rather than by a port.
The three fixed kdos-appbox names are kdos-appbox, kdos-box and xdg-open. Any other name
the binary is started under is taken as an application shim: a symlink in /usr/local/bin
named after the application and pointing at kdos-appbox, which is what makes scribus an ordinary
command. The build writes one such link per application in a pack the medium carries
(script/phases/70_image/030_launchers.sh, through kdos-appbox genlaunchers); the default medium
carries no packs, so it ships none. An application you install gets its shim in ~/.local/bin instead. See
the program map.
kdos commandkdos is the single entry point to the system’s own tools. It has 30 subcommands, plus help,
which prints them grouped by the question each answers. It is installed as
/usr/local/bin/kdos, a name of the ksvc binary. Each subcommand below links to its section of
The kdos command.
| Subcommand | Does |
|---|---|
kdos help |
Every command, grouped by the question it answers; also -h and --help |
kdos version |
Kernel, C library, userland, session and accent; also -V |
kdos status |
What this machine is and what it is running |
kdos doctor |
Check for the faults known to occur on KDOS, each reported as ok, warn or skip; --json, --cve |
kdos theme [NAME] |
Switch the accent (next, prev and list too); style FILE applies a style file, --audit checks the generated colours, --preview ACCENT previews one |
kdos settings [PAGE] |
The control centre, or one of its nine pages: appearance, panel, desktop, hardware, session, input, apps, boxes, system |
kdos menu summon ROUTE |
Open the palette on a named place; toggle [ROUTE] opens or closes it |
kdos panel toggle |
Put the panel away and bring it back |
kdos toggle [NAME] |
stay-awake, night-light, dnd: list, flip or set |
kdos notify TEXT [BODY] |
Raise a toast; --time, --battery, --dismiss, --dismiss-all, --raise, --dnd |
kdos remind TIME TEXT |
A toast later, delivered once (in 20m, at 15:30, tomorrow 9); also ls, clear, --ask, fire ID |
kdos app |
Applications: list, search, info, groups, install, launch, remove, export, import, and tui add/rm/ls for terminal programs |
kdos trash FILE… |
The freedesktop trash from a prompt; --list, --restore NAME, --rm NAME, --empty [-y] |
kdos places [add DIR [NAME]] |
The places column the desktop shows |
kdos thumb FILE… |
A thumbnail in the shared freedesktop cache; --path FILE, --ppm FILE OUT |
kdos speech |
The transcription models: list, get NAME, where, remove NAME |
kdos share [FILE…] |
Send files to another machine over croc; --clipboard sends the clipboard |
kdos hey |
Ask the compositor: list, outputs, boxes (each with --json), and run ACTION ID |
kdos why PATH\|PORT |
What provides this, and the recorded reason it is the way it is |
kdos explain [TOPIC] |
The recorded reasons, browsable |
kdos oracle |
One recorded lesson, picked for today |
kdos sandbox [PROFILE] -- CMD |
Run a native program under Landlock; --read, --write, --no-network, --tcp, --explain |
kdos appid |
Whether launcher identifiers match the identifiers windows present |
kdos restarts |
Which running processes still use code an upgrade replaced or removed |
kdos stutter |
Why a frame was late, and which process was busy |
kdos march |
Measure per-machine optimisation (probe, run PORT…) and read the recorded verdicts (report) |
kdos cve |
Which pinned versions carry known vulnerabilities, from an offline database |
kdos update |
check (--json writes the panel’s badge, --fetch fetches first), fetch (the newest signed ports tree into /ports), apply (fetch the sources and build what is behind), and theme for the per-user artwork |
kdos rebuild WORKDIR |
Rebuild the image from the sources on the medium; --dry-run, --iso-only |
kdos clone [DEV] |
Copy this medium to another device, verified by read-back |
kdos persist |
Report the live session’s persistence store; create [DEV] makes one |
A surface is one window or popup of the desktop. All 55 names below are the kdos-shell
binary in /usr/bin (the binary itself and 54 symlinks to it), and they reach 54 distinct
programs: kdos-launcher and kdos-palette are one search program that shows only applications
when started as kdos-launcher or with --apps. All but two of the 54 open a surface of their
own; kdos-mediad raises its toasts through kdos-notifyd, and kdos-ascii is a filter that
writes text to standard output. Every surface is drawn as a grid of character
cells and handed to the compositor as an ordinary Wayland surface; the frame around a window is
drawn by the compositor.
| Command | What it does | Documented in |
|---|---|---|
kdos-shell |
The panel | kdos-shell |
kdos-start |
The Start menu | kdos-shell |
kdos-launcher |
The palette showing applications only | kdos-shell |
kdos-palette |
One search over windows, applications, routes, settings pages, files and key chords (keyboard shortcuts) | kdos-shell |
kdos-menu |
The applications, places, system and window menus | kdos-shell |
kdos-desk |
The desktop and its icons | kdos-shell |
kdos-pick |
The file chooser and browser | kdos-shell |
kdos-peek |
What is in a file, without starting its application | kdos-shell |
kdos-find |
Files by name or contents, applications and recent files | kdos-shell |
kdos-pix |
One picture, and the folder it is in | kdos-shell |
kdos-rec |
Record a microphone, watch the level, transcribe it | kdos-shell |
kdos-ascii |
Render a picture as characters | kdos-shell |
kdos-run |
The run box | kdos-shell |
kdos-prompt |
Yes or no, answered by exit status; --input asks for a line instead |
kdos-shell |
kdos-notify |
The notification centre | kdos-shell |
kdos-notifyd |
The notification daemon | kdos-shell |
kdos-mediad |
Removable-media toasts, with Open and Eject | kdos-shell |
kdos-netagent |
The NetworkManager secret agent | kdos-shell |
kdos-osd |
The volume, microphone and brightness bezel | kdos-shell |
kdos-cal |
The calendar | kdos-shell |
kdos-display |
Screen configuration | kdos-shell |
kdos-keys |
The keybinding card | kdos-shell |
kdos-teams |
The window list | kdos-shell |
kdos-saver |
The screen saver, started by Super+Shift+L or by hand; the idle sequence does not start it |
kdos-shell |
kdos-about |
What this machine is | kdos-shell |
kdos-style |
The accent on one page, the font on the other | kdos-shell |
kdos-calc |
The calculator, through qalc |
kdos-shell |
kdos-chars |
The character map | kdos-shell |
kdos-connect |
A folder on another machine, over SMB | kdos-shell |
kdos-traymenu |
A tray item’s own com.canonical.dbusmenu menu, as cells |
kdos-shell |
kdos-contacts |
The address book, through khard |
kdos-shell |
kdos-disks |
Disks: mount, unlock, SMART, partition, write an image, erase | kdos-shell |
kdos-print |
Printers: what is set up, what is on the network | kdos-shell |
kdos-time |
The time zone, the clock, and whether the clock is right | kdos-shell |
kdos-users |
The accounts, and which one tty1 logs in automatically |
kdos-shell |
kdos-update |
What is behind, what is vulnerable, which root slot is live | kdos-shell |
kdos-store |
What this machine can build, and one tick to build it | kdos-shell |
kdos-firewall |
Which services answer the network | kdos-shell |
kdos-backup |
What is in the restic repository, one key to add to it, and a restore view | kdos-shell |
kdos-burn |
A folder or an image onto a CD, DVD or Blu-ray, and the disc checked | kdos-shell |
kdos-verify |
Files against a checksum list or a par2 set, and par2’s repair | kdos-shell |
kdos-note |
The scratch pad | kdos-shell |
kdos-slit |
The slit: a narrow column of small status gadgets (dockapps) at the right edge of each screen, off unless comp.conf sets slit = yes |
kdos-shell |
kdos-doc |
The documentation viewer | kdos-shell |
kdos-settings |
The control centre | kdos-shell |
kdos-openwith |
Choose a handler for a file | kdos-shell |
kdos-audio |
Audio devices | kdos-shell |
kdos-net |
Networking | kdos-shell |
kdos-bt |
Bluetooth | kdos-shell |
kdos-devices |
Cameras, microphones, removable media | kdos-shell |
kdos-clip |
Clipboard history: with no argument the daemon, with --pick the picker |
kdos-shell |
kdos-status |
The popup behind the panel’s overflow chevron | kdos-shell |
kdos-tip |
Tooltips | kdos-shell |
kdos-ime |
The input-method candidate window, as cells | kdos-shell |
kdos-trash |
What was deleted, and the way back | kdos-shell |
The full option list of every surface is in Command lines. The options most often typed by hand are these:
| Command | Flags |
|---|---|
kdos-prompt |
--message TEXT, --yes LABEL, --no LABEL; exits 0 for yes, 1 for no and 254 when cancelled. --input makes it a one-row box: the typed line on standard output with exit 0, or exit 254 and nothing printed |
kdos-palette |
--apps shows applications only, as kdos-launcher does; --route NAME opens with a route already typed |
kdos-menu |
applications, places or system; --windows APP_ID and --winmenu APP_ID list one application’s windows, the second with the window controls |
kdos-pick |
--save, --directory, --multiple, --browse [DIR], --dir DIR, --name NAME, --filter 'Label:*.png *.jpg' |
kdos-settings |
--page NAME, one of the nine page names above |
kdos-style |
--page accent or --page font opens either page directly |
kdos-display |
--list prints the outputs and exits; --apply re-applies ~/.config/kdos/displays.conf with no window |
kdos-rec |
--input hw:C,D picks the capture device; --fixture DIR, --meter FILE and --write OUT are test inputs |
kdos-traymenu |
SERVICE PATH; also --name, --at X Y, --at-bottom X Y, and the test inputs --open ID and --pick ID |
Every surface except kdos-ascii, kdos-ime, kdos-mediad and kdos-netagent also takes
--dump to print one frame as text with no display; see
Rendering one frame with no display.
| Command | Installed in | What it does | Documented in |
|---|---|---|---|
kdos-comp |
/usr/bin |
The compositor, a fork of labwc | kdos-comp |
kdos-desktop |
/usr/local/bin |
Start a session from a tty | The session |
kdos-desktop-start |
/usr/local/bin |
Bring up PipeWire, WirePlumber and the PulseAudio shim, run the compositor in the foreground, and start the portals once its socket exists | The session |
kdos-session-save |
/usr/local/bin |
Write what is running to $XDG_STATE_HOME/kdos/session, so the next login can restore it |
The session |
kdos-lock |
/usr/bin |
The lock screen, through ext-session-lock-v1 |
The daemons |
kdos-boxsock |
/usr/bin |
One tagged compositor socket per box, so the compositor knows which box a window came from; kdos-boxsock BOX [INSTANCE] |
The daemons |
xdg-desktop-portal-kdos |
/usr/lib |
The portal backend for the FileChooser, Settings, AppChooser and Access interfaces; started by D-Bus | The session |
kdos-record |
/usr/bin |
Record the desktop through the ScreenCast portal; run it again to stop | The session |
kdos-shot |
/usr/local/bin |
Screenshots through grim and slurp: region (the default), screen (also full), qr |
The kdos command |
kdos-updatedb |
/usr/local/bin |
Rebuild this user’s own plocate index, scoped to $HOME |
Configuration |
While kdos-record runs, its process id is in $XDG_RUNTIME_DIR/kdos/screencast.pid; the next
invocation reads that file to stop the recording. The panel’s SCR privacy lamp does not read the
file: it counts PipeWire ScreenCast nodes, so it lights for any screen share. The binding is
Alt+Print in the shipped rc.xml.
kdos-shot saves to ~/Pictures/Screenshots (or under $XDG_PICTURES_DIR) and copies the
picture to the clipboard. window is accepted and behaves as region. kdos-shot qr captures to
the runtime directory, decodes a QR code in the picture onto the clipboard and deletes the
picture, so a pairing token never reaches the disk.
The daemons are installed in /usr/sbin and started from /etc/init.d. Three of them have a
client, which is the daemon’s own binary under a second name, a symlink in /usr/bin, so a daemon
and its client are always the same version.
| Command | What it does | Documented in |
|---|---|---|
kdos-powerd |
Suspend, power-off, reboot, and the system settings a desktop user may change | The daemons |
kdos-power |
Suspend, power off or reboot, as kdos-powerd’s client |
The daemons |
kdos-mountd |
The removable-media daemon: disks, LUKS, SMB shares, SMART | The daemons |
kdos-mount |
Mount and unmount removable media, as kdos-mountd’s client |
The daemons |
kdos-energyd |
Per-application energy attribution: which application is using the processor’s power | The daemons |
kdos-energy |
The per-application energy report; --json, ping |
The daemons |
kdos-oomd |
The memory-pressure daemon, which spares the desktop | The daemons |
kdos-packd |
The pack daemon, the only program that mounts a pack | The daemons |
kdos-power takes these forms:
kdos-power [--no-lock] suspend|poweroff|reboot|ping
kdos-power timezone Area/City
kdos-power autologin USER|off
kdos-power firewall list|SERVICE on|off
kdos-power accent SCHEME
kdos-mount takes nine verbs:
| Verb | Does |
|---|---|
list |
The devices the daemon offers, one numbered row each |
mount N, unmount N, smart N |
Act on row N of list |
shares |
The network shares that are connected |
browse |
The hosts that answer an mDNS and a NetBIOS broadcast sent for this call, as name<TAB>address rows |
krb5 SERVER SHARE USER DOMAIN |
Mount a share with the Kerberos ticket kinit already obtained; - means no user or no domain |
ping |
Whether the daemon is answering |
subscribe |
Print changed whenever the list changes; never exits |
No form takes a device or a mount point: the daemon decides both. The daemon’s socket answers
fifteen verbs, the nine above plus eject, close, unlock, format, cifs and disconnect,
which kdos-disks and kdos-connect send. The full protocol is in
Filesystem and IPC.
A box is the container an application runs in; see the glossary.
| Command | Installed in | What it does | Documented in |
|---|---|---|---|
kdos-appbox |
/usr/local/bin |
Launch, install and export boxed applications; generate launchers | kdos-appbox |
kdos-box |
/usr/local/bin |
Manage boxes: create, enter, freeze, export, snapshot, profile | kdos-appbox |
xdg-open |
/usr/local/bin |
Open a file or a link with its handler | kdos-appbox |
xdg-terminal-exec |
/usr/local/bin |
Run a command in a foot window, for Terminal=true handlers launched through GLib |
kdos-appbox |
kdos-boxinit |
/usr/libexec/kdos |
Process 1 inside a pack box | Packs and boxes |
kdos-openarchive |
/usr/local/bin |
Extract, with ouch, an archive mc cannot browse as a directory, beside the archive |
kdos-shell |
kdos-pack |
/usr/bin |
Build, sign, re-stamp, index and diff packs | Packs and boxes |
kdos-podman-api |
/usr/bin |
Run a container client against this account’s Podman API socket, starting podman system service when nothing answers on it |
Configuration |
kdos-appbox takes run, open, catalogue, install, uninstall, store, import,
export, warmup, status, list, apps and genlaunchers, with the global options
-b/--box NAME and -v/--verbose. kdos-box takes list, create, enter, run, apps,
export, unexport, freeze, import, clone, snapshot, snapshots, rollback, start,
stop, restart, remove, profile and gc.
kdos-pack takes build, assemble, info, imagehash, uuid, image, extract-meta,
verify, sign, restamp, index, delta, apply and keygen.
All five names are one binary in /usr/bin.
| Command | What it does | Documented in |
|---|---|---|
kpkg |
The package manager | Packaging |
kpkgadd |
Install a package file | Packaging |
kpkgdel |
Remove a package | Packaging |
kpkgbuild |
Build the port in the current directory into a package, without installing it | Packaging |
kpkgdepends |
Print the resolved install order | Packaging |
kpkg takes install (also i), remove (also r), list (also l, with --json), info
(with --json), check (packages by name, or --all), meta, fetch (the sources a port lacks, from the archive and then upstream), verify (and verify --repro), keygen, sign FILE KEY, index (with --sign KEY),
verify-index, verify-pkg, delta, apply-delta, binhost, store gc DIR MAX-SIZE and
help, and the options
--root PATH, --keep-cache and -f/--force. install also takes
--build-only, which builds exactly the named ports into the package cache and installs nothing,
and --commit, which installs what --build-only built; see
Building apart from installing.
store gc deletes package store entries, least
recently used first, until the store fits MAX-SIZE (bytes, or a K, M, G or T suffix).
kpkg help describes each.
kpkg help also lists update, which kpkg does not implement: kpkg update prints the usage
text and exits 1. kdos update is the command that updates the system; see
Updating a machine.
| Command | Installed in | What it does | Documented in |
|---|---|---|---|
kdos-splash |
/usr/bin |
The boot splash | Boot and init |
kdos-bootctl |
/usr/bin |
A/B root slot selection and confirmation, each slot’s kernel on the ESP, and the colours of the boot menu and text consoles | Boot and init |
kdos-getty |
/usr/local/sbin |
Load the console font and palette onto a VT, then run a getty: kdos-getty TTY GETTY [ARGS…] |
Boot and init |
kdos-login |
/usr/local/sbin |
Hand tty1 to agetty, logging in automatically when /etc/kdos/login.conf names an account |
Boot and init |
kdos-banner |
/usr/local/bin |
The login banner | Boot and init |
ksvc |
/usr/sbin |
The service supervisor | Administration |
service |
/usr/sbin |
The same supervisor, under the conventional name | Administration |
kinstall |
/usr/bin |
The installer | kinstall |
/etc/inittab runs kdos-getty tty1 kdos-login tty1 on the first console and
kdos-getty tty2 /sbin/agetty --noclear tty2 38400 linux on the second.
ksvc (and service) takes list, status NAME, start NAME, stop NAME, restart NAME,
enable NAME, disable NAME and help, the commands a person types. The init scripts also call
supervise, stop-supervised NAME and check NAME, through /etc/init.d/service_helper. See
ksvc and service.
kdos-bootctl takes:
kdos-bootctl status [--json]
kdos-bootctl select [a|b]
kdos-bootctl mark-good
kdos-bootctl crypt FS-UUID
kdos-bootctl set-slot a|b UUID [LUKS-UUID]
kdos-bootctl try a|b [N]
kdos-bootctl deploy ROOT [a|b]
kdos-bootctl palette [ACCENT]
kdos-bootctl theme [--print] ACCENT
These come from ports, not from this repository, and upstream’s manual pages describe them. They
are listed because /etc/inittab, the service scripts, the initramfs build and this book’s
procedures call them by name. /sbin is a link to /usr/sbin.
| Command | Installed in | Port | What it does | Documented in |
|---|---|---|---|---|
init |
/sbin |
sysvinit |
PID 1: reads /etc/inittab, runs rcS, keeps the consoles and changes runlevel |
Boot and init |
telinit |
/sbin |
sysvinit |
Ask init for another runlevel: 0 powers off, 6 reboots, S is single-user |
Boot and init |
runlevel |
/sbin |
sysvinit |
Print the previous and the current runlevel | Boot and init |
shutdown |
/sbin |
sysvinit |
Power off or reboot, now or at a time, through init | Boot and init |
halt, poweroff, reboot |
/sbin |
sysvinit |
Change to runlevel 0 or 6, or with -f stop the machine at once |
Boot and init |
killall5 |
/sbin |
sysvinit |
Signal every process outside the caller’s session | Boot and init |
sulogin |
/sbin |
util-linux |
Ask for root’s password on the console and give a shell, for single-user mode | Boot and init |
getent |
/usr/bin |
musl-utils |
Look an entry up in passwd, group, hosts and the other name databases |
Packaging |
getconf |
/usr/bin |
musl-utils |
Print a system configuration value, such as _NPROCESSORS_ONLN |
Packaging |
iconv |
/usr/bin |
musl-utils |
Convert text between character encodings | Packaging |
cpio |
/usr/bin |
cpio |
Write and read cpio archives; the initramfs is one | Boot and init |
which |
/usr/bin |
which |
Print the full path of a command | Packaging |
xxd |
/usr/bin |
tinyxxd |
Hex dump a file, or turn a dump back into bytes with -r |
Packaging |
ping |
/usr/bin |
iputils |
Send ICMP echo requests, as any user and with no setuid bit, through the ICMP sockets net.ipv4.ping_group_range opens |
The security model |
arping |
/usr/bin |
iputils |
Send ARP requests on a link; needs root | Packaging |
mkpasswd |
/usr/bin |
whois |
Hash a password for /etc/shadow or useradd -p; name the method, -m sha512crypt, because with musl’s crypt the default is DES |
Packaging |
tracepath |
/usr/bin |
iputils |
Trace the path to a host and the MTU along it, with no privilege | Packaging |
| Command | Installed in | What it does | Documented in |
|---|---|---|---|
kdos-res |
/usr/bin |
The resource monitor | kdos-res |
kdos-term |
/usr/bin |
The terminal | kdos-term |
kdos-bb |
/usr/bin |
The ASCII-art demo | kdos-bb |
kdos-theme |
/usr/bin |
Generate the GTK, icon and cursor themes for an accent: gtk, icons, cursors, accents |
Theming |
kdos-share |
/usr/local/bin |
Send files to another machine over croc; with no file, kdos-pick asks for one |
The kdos command |
kdos-sfx |
/usr/local/bin |
Sound effects: login, notify, error, degauss; --route prints the output it would use |
The kdos command |
kdos-mpctl |
/usr/local/bin |
Music control: toggle, stop, next, prev to mpd or an MPRIS player; now and watch from mpd |
The kdos command |
kdos-fetch-app |
/usr/local/bin |
Install an application from another distribution into a distrobox; --box, --image, --remove |
The kdos command |
kdos-fetch-static |
/usr/local/bin |
Fetch one static binary and verify it: kdos-fetch-static NAME URL SHA256 |
The kdos command |
kdos-syncthing |
/usr/bin |
Syncthing, given a LAN-only configuration the first time it runs | Administration |
update-ca-certificates |
/usr/bin |
Rewrite /etc/ssl/cert.pem from the Mozilla bundle and the local roots in /etc/ca-certificates/trust-source/anchors/; --root DIR |
Security model |
sfeed-read |
/usr/bin |
Open sfeed_curses on every feed under ~/.sfeed/feeds, or say how to fetch some when there are none |
The sfeed port’s build.sh |
ldconfig |
/usr/sbin |
Exits 0 and changes nothing: musl’s loader keeps no cache, so there is nothing to rebuild; it answers makefiles and install scripts that run it | Configuration |
kdos-syncthing, update-ca-certificates, sfeed-read, ldconfig and kdos-podman-api are
shell scripts that a port recipe writes into its package (the syncthing, ca-certificates,
sfeed, musl and podman ports), not programs under src/.
kdos-term takes -e (also --exec), --title, --app-id, --font, --size WxH, --float,
-D DIR (also --working-directory), --tty and --dump WxH. Everything after -- is the
command to run. Its configuration is ~/.config/kdos/term.conf.
kdos-mpctl watch writes $XDG_RUNTIME_DIR/kdos/nowplaying and waits in mpd’s idle; it
reconnects when mpd restarts. The session starts one per login once an mpd configuration file
exists.
Two of KDOS’s own binaries are setuid root, each doing one thing an unprivileged process cannot.
Both are in /usr/bin and installed mode 4755. The image’s whole setuid inventory is in
The security model.
| Command | What it does | Documented in |
|---|---|---|
kdos-checkpass |
Check the caller’s own password against /etc/shadow, for kdos-lock |
The security model |
kdos-resctl |
For kdos-res: signal PID TERM\|KILL\|STOP\|CONT, renice PID N, and dmi to read the hardware table; the caller must be in wheel |
The security model |
These run on the machine KDOS is built on, from the top of the repository, and never ship on the
target. How KDOS is built follows them in the order a build
uses them, from make fetch to a bootable ISO.
| Target | What it does | Documented in |
|---|---|---|
make fetch |
Download and verify every recipe’s sources; after it, make build needs no network |
Developing |
make fetch-check |
Check offline that every source is present and matches its hash | Developing |
make build |
The whole build, in the container; BUILD_ARGS reaches the orchestrator |
Developing |
make snapshots |
List the phase snapshots | Developing |
make updates |
Run ports/update over every port; PORTUP_ARGS narrows it |
Developing |
make run, make rundisk |
Boot the ISO, or build/kdos.qcow2, in a virtual machine with plain graphics |
Developing |
make run-hw, make rundisk-hw |
The same with hardware-accelerated graphics, through testing/qemu-hw/ |
Developing |
make debug-boot |
Boot the built kernel and initramfs directly, with the serial console on the terminal | Developing |
make cleandisk, make cleanbuild, make clean |
Replace the test disk; empty build/ except snapshots, ccache, pkgstore and keys; empty it except keys |
Developing |
make help |
List every target with a one-line description | Developing |
make publish, publish-dry, publish-check, publish-plan, publish-describe, publish-rehome, publish-retire, publish-orphans |
ports/publish and its modes over the source archive’s sources-<N> volumes; PORTS and PUBLISH_ARGS narrow them |
Developing |
make freeze, make release, make release-publish |
The system release for TAG: sources.sha256, a draft with the ISO and signed SHA256SUMS, then public and Latest |
Developing |
make check, preflight, selftest, selftest-asan, docscheck, phaseclosure |
The checks that stand in for a build; check runs the four that need no built tree |
Developing |
make depdrift, make debuginfo, make unowned, make linkcheck, make entrycheck |
Audit build/fs for undeclared same-phase link dependencies, shipped DWARF, unowned files, run-time references that do not resolve, or dangling links and dead entries |
Developing |
make quick, make rig-image, make devdeps-image |
The fast loop, and the containers it and the rig run in | Testing |
KDOS_RES (default 1920x1080) sets the virtual screen for make run, rundisk,
run-hw and rundisk-hw.
| Command | What it does | Documented in |
|---|---|---|
ports/fetch [--check] [--tree DIR] [PORT…] |
What make fetch runs: each source from the port directory, the cache, the sources archive or upstream, generating a vendor bundle where one must be made. A port is named by its bare name on any shelf, and a name that is no port fails the run |
Developing |
ports/publish [--dry-run \| --check] [--history] [PORT…] |
Upload sources the archive lacks into the volume sources-<N> that ports/shelves gives the shelf that owns them, as <shelf>--<file> (in parts past 1,900 MiB), spilling into another volume when that one is full, and write their lines into ports/sources.idx. --plan gives every shelf without a volume one; --describe rewrites the releases’ titles and notes; --rehome [PORT…] moves files into the volume and name of the shelf their port now sits on and, once the index is pushed, deletes the old copies; --retire deletes the emptied src-<shelf> releases of the older layout and their tags; --orphans lists index lines no recipe names, and --orphans --prune=yes-delete deletes the unprotected ones; --freeze TAG attaches a release’s hash list. Ports are named as for ports/fetch |
Writing ports |
ports/publish --release TAG [--iso PATH] [--key PATH \| --unsigned] [--publish] [--dry-run] |
Put the system release TAG on kunaldawn/kdos: the ISO (in parts from 1,900 MiB), sources.sha256, the recipe tree kdos-ports.tar.xz with its signature, a signed SHA256SUMS and the public key, as a draft until --publish makes it public and Latest |
Developing |
script/hooks/pre-push |
Refuse a push that breaks the ports layout, or names a source the archive lacks; enabled with git config core.hooksPath script/hooks |
Writing ports |
kdosbuild [--fresh] [--restore PHASE] [--continue-from PHASE] [--phases LIST] [--steps LIST] [--rebuild LIST] [--plan] [--snapshot] [--no-snapshot] [--full-snapshots] [--port-jobs N] [--plain] [--json] [--list] [--delete PHASE] |
The build orchestrator, compiled from src/devtools/kdosbuild/ by script/kdosbuild.sh, which make build runs with BUILD_ARGS. --port-jobs N builds up to N ports of a package phase at once, by dependency level |
The build system |
script/chroot/enter.sh |
A root shell, or one command, inside a built tree, for inspection by hand | The build system |
ports/update |
Check ports for newer upstream releases; compiles and runs kdos-portup |
Writing ports |
kdos-portup |
The version checker ports/update runs, from src/devtools/kdos-portup/, compiled to ports/.portup |
Writing ports |
ports/hackage-vendor |
The Hackage downloader ports/fetch runs to make a Haskell port’s vendor bundle |
Writing ports |
testing/preflight.sh |
55 checks over the wiring of the tree | Testing |
testing/debuginfo.py [--root ROOT] [--threshold BYTES] [--files] |
Sum the .debug_* and .zdebug* sections of every ELF file under a built root’s usr/ by owning package, and fail above the threshold (1 MiB) outside the ghc -debug runtimes |
Testing |
testing/unowned.py [--root ROOT] [--fs DIR] [--all] |
List the files of a built root no package and no fs/ path provides |
Testing |
testing/linkcheck.py [--root ROOT] [--all] |
Fail on a DT_NEEDED owned outside the consumer’s depends, an interpreter that does not resolve, or OpenSSL 3 and 4 in one process; warn on a bare python shebang |
Testing |
testing/entrycheck.py [--root ROOT] |
Fail on a dangling symlink, a desktop or D-Bus Exec= that does not resolve, a visible Icon= with no icon, or a udev program that does not exist |
Testing |
testing/bookcounts.py |
Recompute the port counts on the three pages that state them and check every ports-catalogue row against its recipe; docscheck.sh runs it |
Testing |
testing/phaseclosure.py |
Check that every package phase installs exactly the ports its list names; preflight runs it | Writing ports |
testing/selftest.sh |
The library and consumer suite, with the goldens | Testing |
testing/docscheck.sh |
This book: dead links, historical phrasing, the page contract, and through testing/bookcounts.py the port counts |
Testing |
testing/devdeps-image.sh |
Build the kdos-devdeps image and run the self-test in it, with nothing skipped |
Testing |
testing/rig-image.sh |
Build the kdos-qemu-py rig image |
Testing |
testing/vnc-shot.py |
Boot, drive and photograph a real session | Testing |
testing/quick.sh, testing/quickpatch.sh |
Rebuild ports and patch them into a booted ISO’s in-memory overlay | Testing |
testing/qemu-audio.sh |
Pick a working QEMU audio backend for the run targets and the rig | Testing |
testing/usability.sh |
Drive the desktop with the pointer and chords, as a person would, and leave a numbered contact sheet to check against testing/usability.md |
Testing |
testing/bios-boot.sh |
Boot the ISO with no UEFI firmware | Testing |
testing/packlane.sh |
The pack lane (installing signed packs into a box) end to end on a booted machine | Testing |
testing/install-to-disk.sh |
Run the installer into a disk image | Testing |
testing/appsweep.sh |
Launch every catalogue application | Testing |
testing/appreport.sh |
Report on what the sweep found | Testing |
testing/appbox-smoke.sh |
Check that every boxed application’s launcher starts something | Testing |
testing/hostcheck.sh |
Check that the binary a caller resolves by name is the one that can do the job | Testing |
testing/oomd-fire.sh |
Put a booted machine under real memory pressure and read kdos-oomd’s kill count |
Testing |
testing/prepare_base.py, testing/test_runner.py |
Build a minimal root filesystem image and build single ports against it; report_gen.py summarises the results |
Testing |
testing/bootcheck/ |
Scripted boots with no display: start QEMU, run a command on the serial console, type | Testing |
testing/qemu-hw/ |
The containerised QEMU with accelerated graphics behind make run-hw |
Testing |
ksvc binary in fullPart VI — Reference, chapter 39. Previous: 38. The ports catalogue · Contents · Next: 40. Configuration