How to build ClaraOS, start it, and work at its prompt and in its windows.

This manual is for version 0.0.18. ClaraOS starts in a virtual machine, tests itself as it comes up, and ends at a prompt where what you type is Common Lisp: it is read, evaluated, and what it gives is printed. There is no shell and there are no commands apart from that. Listing a directory, writing a file and saving the whole system are Lisp forms like any other.

What the manual shows of the prompt was typed at a running kernel: the tests that every change has to pass type each of these sessions again and compare the answers. The front page says what ClaraOS is for and how far it has come.

  1. Getting it
  2. Starting it
  3. The prompt
  4. The language
  5. Files
  6. Saving the world
  7. Threads
  8. Drawing
  9. Windows
  10. Applications
  11. Looking at the machine
  12. When something goes wrong
  13. Everything that is defined

ClaraOS is built from its source, on macOS or on Linux. There is nothing to download but the repository, and nothing is installed on your computer: the result is a directory of files, and a disk image made of them, for a virtual machine to start from.

On macOS the tools come from Homebrew:

brew install llvm lld qemu sbcl

On Ubuntu they come from the distribution:

sudo apt install clang lld make qemu-system-x86 qemu-system-arm ovmf \
    qemu-efi-aarch64 netcat-openbsd sbcl python3 dosfstools

Then, on either:

git clone https://github.com/the-clara-os/clara-os
cd clara-os
make               # both kernels, and the Lisp files beside them
make test          # if you like: start every machine and check its answers

make takes a few seconds and leaves everything in build/. Building and running need clang, QEMU and Python 3, which macOS has with Apple's developer tools. SBCL and the rest of the list are for make test.

Under QEMU

make run-aarch64   # virtualized on Apple silicon: it starts at once
make run-x86_64    # emulated: the firmware takes a few seconds first

A window opens, which is the machine's screen, and the terminal you started it from becomes its serial port. Both show the same report as the machine comes up, and both end at the prompt. You can type in either: in the window on the machine's keyboard, in the terminal on its serial port.

Ctrl-A Xin the terminal: leave QEMU, whatever the machine is doing
Ctrl-A Cin the terminal: QEMU's own monitor, and back
MEM=1G make run-aarch64a machine with that much memory, where it has 512 MiB otherwise

The machine starts from a disk image, build/disk-aarch64.img or build/disk-x86_64.img, which is made of the files in build/esp the first time and kept from one run to the next. Files that you write are on it the next time, and so is a world that you saved. After the next make that changed something, the disk is made again and both are gone.

In UTM

  1. make image, on macOS. It makes build/claraos.img, a disk with both kernels on it.
  2. In UTM: New, then Virtualize on Apple silicon (the machine is AArch64) or Emulate (x86_64), operating system Other. Skip the ISO. Leave "UEFI Boot" checked. 512 MiB of memory is plenty.
  3. Remove the drive that UTM made. Then Drives, Import, build/claraos.img, with the interface VirtIO: that is the disk ClaraOS has a driver for. With any other interface the machine still starts, and has no files.
  4. Add a Serial device, mode "Built-in Terminal". The system talks there as well as on the screen, and you can type there.
  5. For typing in the screen's own window, add a keyboard that ClaraOS has a driver for. UTM gives a machine USB devices, which it does not have one for. Under QEMU, Arguments, add two: -device virtio-keyboard-pci and -device virtio-tablet-pci. The second is the pointer, which the window manager is worked with.
  6. Start.

UTM copies the disk into the virtual machine. To put a newer ClaraOS there, or to go back to a system that nothing was saved on, import build/claraos.img again in place of the drive.

What it needs of a machine

A processorx86_64 or AArch64. One is used, however many the machine has.
FirmwareUEFI. The kernel is the program that the firmware starts: there is no boot loader between them.
Memory128 MiB is enough to start and to work. It is given 512 MiB unless you say otherwise.
A diskA virtio disk with a FAT volume, of 12, 16 or 32 bits, behind either kind of table of partitions or without one. The volume it starts from is the one whose files it sees.
A place to typeA serial port, a virtio keyboard, or both.
A screenThe one the firmware sets up, if there is one. Without it everything is on the serial port.
A pointerA virtio mouse or tablet, for the window manager. Nothing else has a use for one.

It has no use yet for a network, for sound, for USB or for a clock.

What it says as it starts

The kernel reports what it finds and tests each part of itself before it uses it. On AArch64 under QEMU the report begins and ends like this:

ClaraOS: taking the machine from the firmware

ClaraOS 0.0.18 on aarch64: the machine is ours
exceptions: a vector table of our own at EL1, its handlers on a stack of their own
memory map: 33 regions
...
threads: self-test passed, 55 switches: by the timer, by choice, on a lock, asleep, woken, stopped
lisp: objects are tagged 64-bit words, in a heap at 0x0000400000000000 that begins with NIL
...
pci: 7 devices, by the configuration space at #x4010000000
...
input: 00:03.0 is a keyboard, QEMU Virtio Keyboard
disk: 00:02.0 has 72081 sectors of 512 bytes, 35 MiB
files: a FAT32 volume of 33 MiB on the disk 00:02.0, from its sector 2048 on
draw: a screen of 800 by 600 pixels
clara: reading the serial port and the keyboard: a form is evaluated, Ctrl-C stops it, Ctrl-D ends
> 

The lines that begin with pci:, input:, disk:, files: and draw: say what the machine has: its devices, the keyboards and pointers among them, its disks, the volume that names of files are looked up on, and the screen that pictures are shown on. A line that begins with panic: or exception: means the kernel has stopped. When something goes wrong has more about those.

Stopping it

Ctrl-D at the prompt ends the session. The kernel says clara: nothing more to do, halting and the machine stands still. Then close the window, or stop the virtual machine. Nothing is lost by stopping at any other moment either: a file is on the disk from the moment the form that wrote it has answered.

The prompt is > and a space. What you type after it is a form of Common Lisp. When the line holds a whole form, the form is evaluated and its value is printed, in the way it would have to be typed to mean the same thing. Then the prompt comes back.

> (+ 1 2)
3
> (list 1 "two" 'three #\4)
(1 "two" THREE #\4)
> (floor 17 5)
3
2
> (values)
> 'one "two" (+ 1 2)
ONE
"two"
3
> (list 1 2
        3)
(1 2 3)

A form that gives several values has each of them on a line of its own, and one that gives none has nothing. Several forms on a line are answered one after the other. A form that is not finished when the line ends goes on in the next line, after a prompt of two spaces, for as many lines as it takes.

Keys

Enterends the line
Backspace, Deletetakes back the last character of the line
Taba space
Ctrl-Cwhile you type: gives up the line, and the form it was part of. While a form is evaluated: stops it.
Ctrl-Dat the start of a line: ends the session, and the machine halts

That is all the editing there is. The arrow keys do nothing, and no line that was typed before can be called back. In a terminal on the serial port, the terminal's own copy and paste do what is missing: many forms can be pasted at once.

The keyboard is read as one of the United States, with Shift, Ctrl and Caps Lock, and a key that is held down repeats. What is typed on the serial port can be any character, as UTF-8. The screen shows the characters of ASCII, and a box for any other.

A Listener window has the same keys, with one difference: there Ctrl-D closes the window, and the machine goes on.

The screen holds 100 columns and 37 rows at 800 by 600 pixels, and what scrolls off its top is gone. The terminal on the serial port keeps whatever a terminal keeps.

Mistakes

A mistake costs a line. The system says what went wrong, in words, and the prompt comes back with everything as it was.

> (car 5)
error: CAR wants a list, and 5 is not one
> (no-such-function 1 2)
error: the function NO-SUCH-FUNCTION is not defined
> (loop)
Ctrl-C
error: interrupted from the keyboard

A form that does not end, like that (loop), runs until Ctrl-C stops it. So does one that waits for something that never comes.

The Lisp is a part of Common Lisp, and not a dialect of its own: what is here means what it means in any Common Lisp, and a program that keeps to this part runs elsewhere as it stands. If you know Common Lisp, read where it stops short and go on. If you do not, any introduction to it will do, for as far as this part goes.

It is an interpreter. A function is evaluated from its text every time it is called, so it is slow by the standards of a compiled Lisp, and quick enough to drive the machine it runs on: its console, its disks and its file system are written in it.

Functions, macros and variables

> (defun fact (n) (if (< n 2) 1 (* n (fact (- n 1)))))
FACT
> (fact 20)
2432902008176640000
> (mapcar #'fact '(1 2 3 4 5))
(1 2 6 24 120)
> (defun make-counter () (let ((n 0)) (lambda () (incf n))))
MAKE-COUNTER
> (let ((c (make-counter))) (funcall c) (funcall c) (funcall c))
3
> (defmacro unless-zero (n &body body) `(if (= ,n 0) nil (progn ,@body)))
UNLESS-ZERO
> (macroexpand-1 '(unless-zero x (/ 100 x)))
(IF (= X 0) NIL (PROGN (/ 100 X)))
T
> (defvar *depth* 0)
*DEPTH*
> (defun depth () *depth*)
DEPTH
> (list (let ((*depth* 1)) (depth)) (depth))
(1 0)

A function takes its arguments in the ways Common Lisp has: required ones, &optional ones with their defaults, the rest as a list, and by keyword. A macro can take a list apart in its own list of parameters. A variable that defvar or defparameter made is special: binding it with let changes what every function sees until the let is over, as *depth* shows above.

Numbers, text and lists

> (fact 21)
error: the result is an integer too large for a fixnum, and there are no larger integers yet
> (/ 7 2)
error: 7 divided by 2 is not an integer, and there are no ratios yet
> (floor 7 2)
3
1
> (string-upcase "Hello, world!")
"HELLO, WORLD!"
> (format nil "~A and ~S make ~D" "one" "two" 3)
"one and \"two\" make 3"
> (concatenate 'string "clara" "." "image")
"clara.image"
> (list (char "Clara" 0) (char-code #\C) (code-char 955) (length "four"))
(#\C 67 #\λ 4)
> (sort (list "pci" "Boot" "console" "FAT") #'string-lessp)
("Boot" "console" "FAT" "pci")
> (let ((v (vector 1 2 3))) (setf (aref v 1) 'x) v)
#(1 X 3)
> (reduce #'+ (remove-if #'oddp '(1 2 3 4 5 6)))
12
> (destructuring-bind (first second &rest others) (list 1 2 3 4 5 6) (list first second others))
(1 2 (3 4 5 6))
> (destructuring-bind (name (x y) &key (colour 'red)) '(dot (3 4)) (list name x y colour))
(DOT 3 4 RED)

A number is an integer of 63 bits, between -4611686018427387904 and 4611686018427387903. A result outside that is an error and not a wrong number, and so is a division that does not come out even: there are no larger integers, no fractions and no decimal numbers yet. A character is a Unicode code point, and a string holds any of them. destructuring-bind takes a list apart into variables, by a list of parameters like a macro's: lists within the list, and &optional, &rest and &key.

Structures and packages

> (defstruct point x (y 0))
POINT
> (let ((p (make-point :x 3))) (setf (point-y p) 4) p)
#S(POINT :X 3 :Y 4)
> (defpackage "PLAY" (:use "COMMON-LISP") (:export "BALL"))
#<PACKAGE "PLAY">
> (in-package "PLAY")
#<PACKAGE "PLAY">
> (list 'ball 'bat (symbol-package 'bat) 'cl-user::fact)
(BALL BAT #<PACKAGE "PLAY"> COMMON-LISP-USER::FACT)
> (in-package "COMMON-LISP-USER")
#<PACKAGE "COMMON-LISP-USER">

Names are read in the package that *package* holds, which is COMMON-LISP-USER when the system starts. What the system adds to Common Lisp is in the package CLARA, and is written with that name before it: clara:make-thread, clara:save-image.

Errors that a program handles

> (handler-case (/ 10 0) (division-by-zero () 'no-quotient))
NO-QUOTIENT
> (define-condition low-fuel (error) ((left :initarg :left :reader fuel-left)))
LOW-FUEL
> (handler-case (error 'low-fuel :left 3) (low-fuel (c) (fuel-left c)))
3
> (unwind-protect (car 5) (format t "cleaning up~%"))
cleaning up
error: CAR wants a list, and 5 is not one
> (ignore-errors (car 5))
NIL
#<TYPE-ERROR "CAR wants a list, and 5 is not one">
> (defun forever (n) (+ 1 (forever n)))
FOREVER
> (forever 1)
error: the stack is full: the forms are nested too deep, or a function calls itself without end

An error is a condition, with a type. handler-case takes the conditions whose type one of its clauses names, and unwind-protect cleans up whichever way its form is left. The system's own errors have Common Lisp's types where a program would want to tell them apart: type-error, division-by-zero, unbound-variable, undefined-function and their kin. A stack or a heap that is full, and Ctrl-C, are no errors: ignore-errors and a clause for error let them pass, and a clause for serious-condition takes them.

Where it stops short

What is refused is refused with an error that says so. Nothing is quietly taken for something else, so a program does not mean one thing here and another elsewhere.

Everything that is defined, at the end of this manual, is the whole list, by subject.

The system reads and writes the files of the disk it started from. The name of a file is a string: the directories that lead to it and then its own name, with a slash before each, as in "/clara/boot.lisp". Letters match in either case. There is no current directory: every name starts at the top of the volume.

What is there

> (directory "/*")
("/clara/" "/EFI/")
> (directory "/clara/*.lisp")
("/clara/boot.lisp" "/clara/console.lisp" "/clara/disk.lisp" "/clara/draw.lisp" "/clara/editor.lisp" "/clara/fat.lisp" "/clara/files.lisp" "/clara/font.lisp" "/clara/input.lisp" "/clara/listener.lisp" "/clara/pci.lisp" "/clara/self-test.lisp" "/clara/terminal.lisp" "/clara/virtio.lisp" "/clara/windows.lisp")
> (probe-file "/CLARA/Boot.Lisp")
"/CLARA/boot.lisp"
> (probe-file "/clara/nothing.lisp")
NIL

directory takes a pattern, in which * stands for any characters in the last part of the name, and gives the names that fit, a directory's with a slash at its end. probe-file gives the name of a file as the disk spells it, or NIL when there is none. The files in /clara are the system's own Lisp: the language's part that is written in Lisp, the console, the drivers, the file system and the window manager, and two that are not loaded until they are wanted, the applications editor.lisp and files.lisp. /EFI holds the kernels.

Reading and loading

> (with-open-file (in "/clara/listener.lisp") (list (read-line in) (read-line in)))
(";;;; listener.lisp: read, evaluate, print" ";;;;")
> (load "/clara/listener.lisp")
T

with-open-file opens a file for the forms inside it and closes it afterwards. read-line gives the next line, and at the end of the file it is an error, or the value you name: (read-line in nil 'done). load evaluates the forms of a file one after the other, as if they had been typed. When a form in it fails, the error says the file and the line.

Writing

> (with-open-file (out "/notes.txt" :direction :output)
    (format out "milk~%eggs~%"))
NIL
> (with-open-file (in "/notes.txt") (list (read-line in) (read-line in) (read-line in nil 'no-more)))
("milk" "eggs" NO-MORE)
> (with-open-file (out "/notes.txt" :direction :output) (write-line "bread" out))
error: OPEN: there is a file /notes.txt already, and :IF-EXISTS does not say :SUPERSEDE or :APPEND
> (with-open-file (out "/notes.txt" :direction :output :if-exists :append) (write-line "bread" out))
"bread"
> (with-open-file (out "/hello.lisp" :direction :output)
    (format out "(defun hello () (format t ~S))~%" "hello from a file~%"))
NIL
> (load "/hello.lisp")
T
> (hello)
hello from a file
NIL
> (delete-file "/notes.txt")
T
> (probe-file "/notes.txt")
NIL

A file is opened for writing with :direction :output, and whatever prints to a stream prints to it: format, write-line, print. The file is made when with-open-file is over. If the forms inside it fail, no file is made, and one that was there stays as it was.

:if-existswhen there is a file of that name already
:erroran error, which is what happens when nothing is said
:supersedethe new file takes its place
:appendwhat is written goes after what the file holds
nilno stream: open gives NIL, and nothing is written

What to know about files as they are now:

Everything that you define lives in the machine's memory, and is gone when the machine stops, unless you save it. clara:save-image writes the whole Lisp world to one file on the disk, as it is at that moment.

> (clara:save-image)
"/clara/clara.image"

The next time the machine starts, it finds that file and takes it for its world, in place of loading the Lisp files. The report says so:

lisp: the heap is an image: 1542 KiB that ClaraOS 0.0.18 saved, from clara.image on the boot volume

And at the prompt, what was defined is defined:

> (fact 10)
3628800
> (hello)
hello from a file
NIL
> (list (depth) (point-x (make-point :x 1)) (unless-zero 2 'two))
(0 1 TWO)
> (probe-file "/clara/clara.image")
"/clara/clara.image"

What comes back, and what does not

Saving again writes a new image in place of the old one. A world of this size takes a fraction of a second to save.

Going back to the files

> (delete-file "/clara/clara.image")
T

Without the image, the next start loads the Lisp files again, and the world is as new. A disk that nothing was saved on does the same: under QEMU, delete build/disk-aarch64.img and it is made anew; in UTM, import build/claraos.img again.

An image that is not taken

When the system cannot use an image, it says why in its report and starts from the Lisp files, as if there had been none. The image stays on the disk until it is deleted or saved over.

The report sayswhich means
it was saved on ARM64, and this machine is X86-64An image is for the kind of processor it was saved on.
it is not what was saved, by its checksumThe file was damaged, or changed, since it was written.
it is 775020 bytes long, and not as long as it says it isThe file is not whole: the machine stopped while it was being written, or it was cut short on the way.
it does not begin the way an image doesSome other file has the image's name.
ClaraOS 0.0.14 saved it, with objects that are not laid out as they are hereThe image is from a version whose memory was arranged otherwise. Images of other versions are taken as long as that has not changed.
it has the function FOO in C, and this kernel has none of that nameThe image was saved by a newer system than the one that is starting.
the machine has no memory for its heapThe world was saved on a machine with more memory.

A newer ClaraOS starts an older image, and what it has more of is there. What the older world defined in Lisp stays as it was saved, the system's own files included. To have those as the newer system has them, delete the image, start again, and save a new one.

One thing an image cannot be saved from is itself. A world in which something essential was redefined and then saved starts like that every time, and if it cannot get to its prompt it cannot delete its own image. The way out is a disk without the image: the two at the end of Going back to the files.

A thread is a function that runs beside the others. The prompt is one thread, the listener, and each keyboard and pointer has one. The names are those that Bordeaux Threads made usual, in the package CLARA.

> (clara:current-thread)
#<THREAD "listener">
> (clara:join-thread (clara:make-thread (lambda () (* 6 7)) :name "worker"))
42
> (defvar *jobs* 0)
*JOBS*
> (let ((lock (clara:make-lock)))
    (mapc #'clara:join-thread
          (mapcar (lambda (n) (clara:make-thread (lambda () (clara:with-lock-held (lock) (incf *jobs* n)))))
                  '(1 2 3)))
    *jobs*)
6
> (let ((bell (clara:make-event "bell")))
    (clara:make-thread (lambda () (sleep 1) (clara:signal-event bell)))
    (clara:wait-event bell))
T
> (clara:join-thread (clara:make-thread (lambda () (car 5)) :name "faulty"))
error in #<THREAD "faulty">: CAR wants a list, and 5 is not one
error: the thread #<THREAD "faulty"> ended with an error: CAR wants a list, and 5 is not one
> (defvar *spinner* (clara:make-thread (lambda () (do () (nil))) :name "spinner"))
*SPINNER*
> (clara:thread-alive-p *spinner*)
T
> (clara:destroy-thread *spinner*)
T
> (clara:join-thread *spinner*)
error: the thread #<THREAD "spinner"> was stopped

The threads take turns, a hundredth of a second each. One of them at a time is evaluating, on the one processor that the system uses, so threads keep the machine answering while something waits, and do not make a computation faster. Each thread has its own bindings of the special variables: one that it binds with let is bound for it alone. A thread costs about a mebibyte and a half of memory.

Pictures are drawn on surfaces. A surface is a rectangle of pixels in memory. The screen is one, and a program makes others, draws on them out of sight, and shows them on the screen when they are whole. The functions are in the package CLARA.DRAW. A place is counted in pixels from the upper left corner of a surface, first across and then down, and that corner is 0 and 0.

> (defvar *paper* (clara.draw:allocate-surface 160 80))
*PAPER*
> (defvar *ink* (clara.draw:color 232 227 244))
*INK*
> (defvar *red* (clara.draw:color 255 85 85))
*RED*
> (clara.draw:fill-rectangle *paper* 0 0 160 80 (clara.draw:color 30 27 46))
T
> (clara.draw:fill-rectangle *paper* 20 20 40 30 *red*)
T
> (clara.draw:draw-rectangle *paper* 10 10 140 60 *ink*)
T
> (clara.draw:draw-text *paper* 72 28 "Hello" *ink*)
T
> (clara.draw:show *paper* 600 40)
T

The last of these puts the picture on the screen, its corner 600 pixels across and 40 down. Until then nothing of it could be seen.

What lies outside

Nothing is drawn outside a surface, and it is no mistake to try: a rectangle that lies half outside is drawn half. Each function that draws gives T when it drew something and NIL when all of it lay outside. clara.draw:with-clip keeps the drawing of the forms inside it to a part of the surface.

> (clara.draw:fill-rectangle *paper* 150 70 100 100 *red*)
T
> (clara.draw:fill-rectangle *paper* 200 0 10 10 *red*)
NIL
> (clara.draw:with-clip (*paper* 0 0 96 80)
    (clara.draw:draw-text *paper* 72 48 "cut off" *red*))
T
> (list (= (clara.draw:pixel *paper* 30 30) *red*)
        (clara.draw:pixel *paper* 100 56) (clara.draw:pixel *paper* 160 0))
(T 1973038 NIL)

Of "cut off" the first three characters were drawn, up to the pixel 96 across. clara.draw:pixel gives the pixel at a place, or NIL when the surface has none there.

Showing what has changed

A surface remembers which parts of it were drawn on, as a few rectangles: its damage. clara.draw:show copies those parts to the screen and forgets them, so what goes to the screen is what has changed since the last time, however much or little that is. Here it is the three characters and the corner that were drawn since the picture was first shown.

> (clara.draw:damage *paper*)
((72 48 24 16) (150 70 10 10))
> (clara.draw:show *paper* 600 40)
T
> (clara.draw:show *paper* 600 40)
NIL
> (clara.draw:copy-rectangle *paper* 20 20 40 30 *paper* 110 44)
T
> (defvar *arrow*
    (vector #b1000000 #b1100000 #b1110000 #b1111000
            #b1111100 #b1100000 #b0010000))
*ARROW*
> (clara.draw:draw-bitmap *paper* 4 2 *arrow* 7 *ink*)
T
> (clara.draw:damage *paper*)
((4 2 7 7) (110 44 40 30))
> (clara.draw:show *paper* 600 40)
T

The console writes on the same screen. A picture that is shown there lies over the text, the lines that are written after it go over the picture where they meet it, and when the text moves up a line the picture moves up with it. So a picture stays where it was put only as long as nothing is printed. A picture that is to stay belongs in a window, and while the window manager runs the screen is its own: what is shown there directly is painted over the next time a window moves.

Memory

A surface takes four bytes for every pixel, 1875 KiB for one as large as a screen of 800 by 600, and that memory is not the heap's: nothing gives it back when the surface is no longer used. clara.draw:free-surface does, and after it the surface cannot be drawn on.

> (clara.draw:free-surface *paper*)
NIL
> (clara.draw:draw-text *paper* 0 0 "gone" *red*)
error: this surface was freed

A world that is saved keeps its surfaces and not their pixels. After the machine has started again, a surface from before is refused with this surface is of a machine that was switched off: make a new one, and draw the picture again. A function that draws it comes back with the world.

There is one font, in one size. There are no lines but those along a row or a column, no circles, and no colours that let what is under them show through.

The window manager puts windows on the screen: each is a surface that a program draws on, in a frame with its title. It takes the screen from the console, which goes on with the serial port, where the prompt stays as it was.

> (clara.windows:start)
T
> (mapcar #'clara.windows:window-title (clara.windows:windows))
("Listener")

The screen now shows a bar along its top, with Applications at its left-hand end and the system's name and version at the right; a window named Listener, with a prompt in it; and the pointer. It is worked like this:

A click on a windowbrings it to the top. The window on top has the focus: its frame is lit, and what is typed goes to it.
The title of a windowis where to take hold of it: press the button there, move, and let go.
The x at the end of the titlecloses the window, and ends the program in it.
Applicationslists the applications there are. A click on a name starts one, and a click anywhere else puts the list away.
Alt and Tabbrings the lowest window to the top, and so each window in its turn.

A Listener window is a prompt like the first one, with the same keys, except that Ctrl-D closes the window and Ctrl-C stops what that window is evaluating. Every listener is in the one world: what is defined in a window is defined at the serial port and in the next window. Each has a thread of its own, so one can compute while you type in another, and each is in a package of its own choosing.

It needs a keyboard and a pointer that the system has drivers for. make run-aarch64 gives the machine both; in UTM they are the two devices that are added by hand. With a keyboard alone, the Listener window still takes what is typed, and the functions below do what the pointer would.

A window of your own

The functions are in the package CLARA.WINDOWS. A window's inside is a surface, and is drawn on like any other. What was drawn reaches the screen with clara.windows:show, as far as the window can be seen behind the others.

> (defvar *window* (clara.windows:open-window "A window of my own" 240 120))
*WINDOW*
> (defvar *inside* (clara.windows:window-surface *window*))
*INSIDE*
> (clara.draw:fill-rectangle *inside* 20 20 80 60 *red*)
T
> (clara.draw:draw-text *inside* 112 44 "Hello" *ink*)
T
> (clara.windows:show *window*)
T
> (clara.windows:move-window *window* 400 300)
400
300
> (clara.windows:launch "Listener")
#<THREAD "Listener">
> (mapcar #'clara.windows:window-title (clara.windows:windows))
("Listener" "A window of my own" "Listener")
> (clara.windows:window-title (clara.windows:raise-window *window*))
"A window of my own"

A window belongs to the thread that opened it. That thread draws on it, shows it and closes it, and close-window from any other thread is an error for as long as the first one lives. Three functions can be given when a window is opened, for what happens to it meanwhile:

> (defvar *typed* nil)
*TYPED*
> (defvar *keys* (clara.windows:open-window "Keys" 160 40 :key (lambda (code) (push (code-char code) *typed*))))
*KEYS*
> (clara.windows:key-typed 97)
97
> *typed*
(#\a)
> (list (clara.windows:close-window *keys*) (clara.windows:close-window *window*))
(NIL NIL)

The three are called in the thread of the keyboard or of the mouse, not in the window's own. They should note what they were told, or signal an event, and leave the drawing to the thread that the window belongs to.

A window that is opened with :events t does that by itself: it keeps what happens to it, and its program asks for the next thing when it is ready for it, in its own thread, where it can draw.

> (defvar *heard* (clara.windows:open-window "Heard" 160 40 :events t))
*HEARD*
> (clara.windows:key-typed 97)
97
> (= (clara.windows:key-typed clara.input:+up+) (+ char-code-limit 1))
T
> (clara.windows:next-event *heard*)
(:KEY 97)
> (equal (clara.windows:next-event *heard*) (list :key clara.input:+up+))
T
> (clara.windows:next-event *heard* 100)
NIL
> (clara.windows:rename-window *heard* "Heard it")
"Heard it"
> (clara.windows:close-window *heard*)
NIL

Text in a window

A terminal is a window with a stream: what is written to the stream is drawn in the window, in rows that move up when the last one is full, and what is typed in the window comes back from the stream a line at a time. The package is CLARA.TERMINAL.

> (defvar *notes* (clara.terminal:open-terminal "Notes" :columns 40 :rows 8))
*NOTES*
> (format (clara.terminal:terminal-stream *notes*) "written from the serial port~%")
NIL
> (clara.terminal:clear *notes*)
NIL
> (clara.windows:close-window (clara.terminal:terminal-window *notes*))
NIL

clara.terminal:open-terminal takes a title and gives a terminal of 80 columns and 24 rows unless :columns and :rows say otherwise; :x, :y and :close are the window's. clara.terminal:terminal-stream is its stream, for format, write-line and read-line, and clara.terminal:terminal-window its window. clara.terminal:clear makes every row blank.

An application

An application is a name and a function. clara.windows:launch calls the function in a thread of its own and comes back with that thread once the application has its window. When the function is done, or its thread is stopped, the windows that the thread opened are closed for it.

> (clara.windows:define-application "Hello"
    (lambda ()
      (let ((terminal (clara.terminal:open-terminal "Hello" :columns 30 :rows 4)))
        (format (clara.terminal:terminal-stream terminal) "hello from an application~%")
        (sleep 2))))
"Hello"
> (clara.windows:applications)
("Listener" "Editor" "Files" "Hello")
> (clara:join-thread (clara.windows:launch "Hello"))
NIL

The window is there for two seconds, and goes with its application. From now on Hello is in the list under Applications, below the three that come with the system. Listener is clara.terminal:listener, the first application and the one that is launched when the window manager starts; Editor and Files are the subject of the next chapter.

Starting in it

A world that is saved while the window manager runs starts in it: the screen goes from the boot report straight to the windows.

> (clara:save-image)
"/clara/clara.image"

The report of the next start says so, in its last line before the prompt of the serial port:

windows: the window manager has the screen again, as it had when the world was saved
> (list (clara.windows:running-p) (mapcar #'clara.windows:window-title (clara.windows:windows)))
(T ("Listener"))
> (clara.windows:applications)
("Listener" "Editor" "Files" "Hello")
> (clara.windows:stop)
T

What is defined comes back, the applications among it. The windows that were open do not: a window is pixels and a thread, and an image has neither, so the window manager starts with one Listener, as it does the first time. clara.windows:stop ends the applications and gives the screen back to the console, cleared; a world that is saved after that starts at the console again.

A window is the size it was opened with. Alt and Tab is the one key that is the window manager's own: nothing on the keyboard opens the list of applications, moves a window or closes one, which the pointer does, and the pointer has one shape.

Two applications come with the system besides the Listener: an editor for text, and a browser for the files of the disk. Each is a file of Lisp on the boot volume, /clara/editor.lisp and /clara/files.lisp, which the system does not load as it starts. The file is loaded the first time its application is picked from Applications, or launched from a prompt, and the application can be unloaded again while everything else goes on.

The editor

Editor in the list opens a window with no text in it yet. From a prompt, the editor is launched with the name of a file, and the window has the file's name for its title:

> (find-package "CLARA.EDITOR")
NIL
> (clara.windows:launch "Editor" "/hello.lisp")
#<THREAD "Editor">
> (list (package-name (find-package "CLARA.EDITOR"))
        (clara.windows:window-title (clara.windows:focused-window)))
("CLARA.EDITOR" "/hello.lisp")

After the name, :columns and :rows say how large the text's part of the window is, in characters, and :x and :y where the window goes: (clara.windows:launch "Editor" "/hello.lisp" :columns 60 :rows 20). Without them it is 80 by 24, or what the screen has room for.

The window shows the text, with a bar under the place where what is typed goes in, and below the text a row that says which file this is, whether the text has changed since it was read or saved, and the line and the column of the cursor. That row is also where the editor says what it did, and where it asks for the name of a file.

A charactergoes in at the cursor.
Enterbegins a new line, as far in as the line it comes from.
Backspace, Deletetake out the character before the cursor, and the one at it. At the start and at the end of a line they join two lines.
Tabspaces, up to the next column that is a multiple of eight.
The arrowsmove the cursor by a character and by a line.
Home, Endthe start and the end of the line.
Page Up, Page Downa window's worth of lines up or down.
A clickputs the cursor where the pointer is.
Ctrl-Ssaves the text in its file. A text that has no file yet is asked for a name.
Ctrl-Oasks for the name of another file, and the text becomes that of the file.
Ctrl-Kcuts from the cursor to the end of the line, and at the end of a line the end itself. Typed several times in a row, it cuts as many lines.
Ctrl-Yputs back what Ctrl-K cut last, at the cursor, as often as it is typed.
Ctrl-Eevaluates the text, form by form, as load would: what it defines is defined, in every window. The row says how many forms there were, or what went wrong and in which line, where the cursor goes. Ctrl-C stops forms that do not end.
Ctrl-Q, the x in the titleclose the window.

While the row asks for a name, what is typed is the name: Enter hands it over, Backspace takes a character of it back, and Escape gives the question up. A name is a whole one, from the top of the volume, like /clara/notes.txt. A file that is not there yet is a new one, which the first Ctrl-S makes.

A text that has changed is not thrown away at the first asking. Ctrl-O, Ctrl-Q and the x say that the text is not saved, and do what they were asked when the same key comes again right after.

What to know about the editor as it is now:

Files

Files in the list opens a window on the top of the volume. From a prompt it can be told where to begin:

> (clara.windows:launch "Files" "/clara/")
#<THREAD "Files">
> (clara.windows:window-title (clara.windows:focused-window))
"Files in /clara/"

:columns, :rows, :x and :y after the name do for this window what they do for the editor's; it is 48 by 16 without them.

The window lists what the directory holds: the directories first, each with a slash at its end, then the files, and above them all ../, the way to the directory that this one is in. One name is picked, and shows the other way round.

The arrows up and down, Page Up, Page Down, Home, Endpick another name.
Entergoes into the directory that is picked, or opens the file that is picked in a new window of the editor.
Backspace, the arrow to the leftgo to the directory that this one is in.
A clickpicks the name it is on, and on the name that is picked does what Enter does.
Deleteasks whether the file that is picked is to be deleted, and y deletes it. Any other key does not.
Ctrl-Rreads the directory again: the window does not notice by itself what was written since.
Ctrl-Q, the x in the titleclose the window.

Every file opens in the editor, also one that is no text, which the editor says it cannot read. Directories are not made or deleted here, as they are not anywhere in the system yet, and the window shows names and no sizes or dates.

Applications in files

The launcher knows the editor and the browser by a name and the name of a file. clara.windows:install-application says so for any file, and the file itself says clara.windows:define-application for the function, under the same name, as its last form. Here is such a file, written from the prompt, a line of it to the string, so that this page can be tried as it stands; the editor is the place to write one.

> (defvar *greeting*
    '("(defpackage \"GREETING\" (:use \"COMMON-LISP\"))"
      "(in-package \"GREETING\")"
      "(defun greet (&optional (words \"Hello\"))"
      "  (let* ((window (clara.windows:open-window"
      "                  \"Greeting\" 200 48 :events t))"
      "         (inside (clara.windows:window-surface window)))"
      "    (clara.draw:draw-text inside 16 16 words"
      "                          (clara.draw:color 255 184 108))"
      "    (clara.windows:show window)"
      "    (loop"
      "      (when (equal (clara.windows:next-event window)"
      "                   '(:close))"
      "        (return)))))"
      "(clara.windows:define-application \"Greeting\" #'greet)"))
*GREETING*
> (with-open-file (out "/clara/greeting.lisp" :direction :output)
    (dolist (line *greeting*) (write-line line out)))
NIL
> (clara.windows:install-application "Greeting" "/clara/greeting.lisp")
"Greeting"
> (list (clara.windows:applications) (find-package "GREETING"))
(("Listener" "Editor" "Files" "Hello" "Greeting") NIL)
> (clara.windows:launch "Greeting" "Good morning")
#<THREAD "Greeting">
> (list (package-name (find-package "GREETING"))
        (clara.windows:window-title (clara.windows:focused-window)))
("GREETING" "Greeting")

Greeting was in the list at once, and nothing of it was in the world until it was launched: the file was loaded then, in the application's own thread, and its function called with what launch was given after the name. The window says Good morning and stays until its x is clicked. A second launch does not load the file again.

> (clara.windows:unload-application "Greeting")
"Greeting"
> (list (find-package "GREETING") (clara.windows:applications))
(NIL ("Listener" "Editor" "Files" "Hello" "Greeting"))
> (clara.windows:remove-application "Greeting")
"Greeting"
> (clara.windows:applications)
("Listener" "Editor" "Files" "Hello")

The drivers are Lisp, each in a package of its own, and what they know can be asked at the prompt.

> (list (clara.pci:location (car (clara.pci:devices))) (clara.pci:description (car (clara.pci:devices))))
("00:00.0" "a host bridge")
> (let ((entry (car (clara.fat:entries "/EFI/BOOT"))))
    (list (clara.fat:entry-name entry) (clara.fat:entry-directory-p entry) (> (clara.fat:entry-size entry) 100000)))
("BOOTAA64.EFI" NIL T)
> internal-time-units-per-second
100
(room)how long the heap is, how much of it is free, and how often it has been collected
*features*(:CLARA :ARM64) or (:CLARA :X86-64), which #+ and #- go by
(get-internal-real-time)the hundredths of a second since the machine started, which is all the time there is
(clara.pci:devices)the devices on the PCI bus. clara.pci:location and clara.pci:description say where one is and what it is.
(clara.disk:disks)the disks that have a driver. clara.disk:disk-name, clara.disk:disk-sectors and clara.disk:disk-read-only say more about one.
(clara.fat:volumes)the FAT volumes on those disks. Names of files are looked up on the first.
(clara.fat:entries "/clara")what a directory holds, with clara.fat:entry-name, clara.fat:entry-size and clara.fat:entry-directory-p for each entry
(clara.input:devices)the keyboards and pointers
(clara.input:pointer)where the pointer is, and which of its buttons are down, as three values. Nothing draws it yet.

Files from outside, and to it

The disk is an ordinary disk image with a FAT volume on it, and the computer that the virtual machine runs on can open it, while the machine is stopped. On macOS, double-click build/disk-aarch64.img in the Finder, or build/claraos.img for the one UTM was given. Put files there or take them, eject it, and start the machine. macOS leaves a few files of its own on such a volume, whose names begin with a dot. On Linux:

sudo mount -o loop,offset=1048576 build/disk-x86_64.img /mnt

Memory and devices by hand

The package CLARA.UNSAFE is what the drivers are written with: memory by its address, the I/O ports, page frames, and interrupts. It is there at the prompt as well, and it is called what it is. There is nothing between a Lisp program and the machine here but the language, and these functions are the way round the language: a wrong address written to is a mistake in the kernel itself.

> (let ((page (clara.unsafe:allocate-memory 1)))
    (setf (clara.unsafe:memory-32 page) #xC1A4A)
    (prog1 (list (clara.unsafe:memory-8 page) (clara.unsafe:memory-16 page))
      (clara.unsafe:free-memory page 1)))
(74 6730)
> (clara.unsafe:memory-8 0)
error: nothing is mapped at #x0

What you seeWhat it is, and what to do
The prompt does not come back.A form is still being evaluated, or is waiting. Ctrl-C stops it.
The firmware's own Shell> prompt, and no ClaraOS.The firmware found no disk with the kernel on it. Under QEMU, run make and start again. In UTM, see that the imported drive is there and is the only one.
disk: no disk that has a driver here, and directory finds nothing.The machine's drive is not a virtio disk. In UTM, set the drive's interface to VirtIO. The system runs without a disk, and can neither read files nor save.
Nothing happens when you type in UTM's window.The machine has no keyboard that ClaraOS has a driver for: the report says input: no keyboard and no mouse that has a driver here. Add the two QEMU arguments of In UTM, or type in the serial terminal.
On AArch64 in UTM, a line about the exception level, and then nothing.The machine is emulated and not virtualized, which starts the kernel in a mode it does not handle yet. Use Virtualize on Apple silicon, or emulate x86_64.
error: the heap is fullA computation used the memory there is. It has been stopped, what it held is free again, and the prompt is back. A machine with more memory holds more.
error: the stack is fullForms nested too deep, or a function that calls itself without end.
Boxes on the screen where characters should be.The screen's font has the characters of ASCII. The characters themselves are right, and show on the serial port.
A picture that was shown has text over it, or is no longer where it was put.The console writes on the same screen, and moves everything on it up with every new line: Showing what has changed. Show the picture again.
error: this surface is of a machine that was switched offThe surface was made before the world was saved, and its pixels were not saved with it. Make a new one and draw on that: Memory.
A file that was written is gone after make.Under QEMU the disk is made again whenever a build changed something. Keep what matters outside build/, by way of the host.
A window is gone that nobody closed, or an application's window never comes.The application failed, and its thread ended. The serial port has the reason, in a line that begins with error in #<THREAD. When the reason is in the application's file, mend the file and launch it again: Applications in files.
The arrow keys do nothing at a prompt.A line at a prompt is edited with Backspace alone. The arrows are for the editor and the browser.
lisp: clara.image is not resumed in the report.A saved world could not be used, and the reason follows on the same line: An image that is not taken.
A report that begins with exception: or panic:, and a machine that stands still.The kernel, or a driver, has failed, and has stopped the machine where it was. The report says what happened in words, where, and what was in every register. Start the machine again. What was saved or written to a file before is there. Then please say what you did, with the report: that is a bug in ClaraOS.

These are all the names that the system gives a meaning when it starts, by subject. Each means what it means in Common Lisp, as far as this Lisp goes. The lists are checked against the kernel and the system's Lisp files whenever this page is built, so nothing is missing from them and nothing is in them that is not there.

Defining

defun defmacro lambda function defvar defparameter defconstant defstruct copy-structure defsetf define-condition defpackage declare &optional &rest &key &allow-other-keys &aux &body &whole &environment special

The last two are names that the reader knows and the evaluator refuses.

Control

quote if when unless cond case ecase otherwise and or not progn prog1 let let* setq psetq setf incf decf push pop block return return-from tagbody go catch throw unwind-protect do do* dolist dotimes loop flet labels macrolet locally the eval-when

Functions and values

funcall apply identity functionp fboundp symbol-function eval macroexpand macroexpand-1 values values-list multiple-value-bind destructuring-bind multiple-value-call multiple-value-list multiple-value-prog1 multiple-value-setq nth-value

Numbers

+ - * / 1+ 1- = /= < <= > >= floor truncate mod rem abs max min expt evenp oddp zerop plusp minusp integerp numberp ash logand logior logxor lognot

Lists

cons car cdr caar cadr cdar cddr caddr cdddr cadddr first second third fourth rest last nth nthcdr list list* append reverse nreverse copy-list length endp null consp atom listp rplaca rplacd member assoc getf mapcar mapc mapcan reduce remove remove-if remove-if-not find find-if position every some sort eq eql equal

Characters, strings and vectors

char schar char-code code-char char= char< char-upcase char-downcase char-code-limit characterp string string= string-equal string-lessp string-upcase string-downcase stringp concatenate subseq vector make-array aref svref vectorp

Symbols and packages

t nil symbol-name symbol-package symbol-value symbol-plist get set boundp symbolp keywordp make-symbol gensym *gensym-counter* intern find-symbol export find-package package-name packagep make-package delete-package list-all-packages in-package *package*

Conditions

error warn signal handler-case ignore-errors make-condition condition serious-condition warning storage-condition simple-condition simple-error simple-warning simple-condition-format-control simple-condition-format-arguments type-error type-error-datum type-error-expected-type program-error control-error cell-error cell-error-name unbound-variable undefined-function arithmetic-error division-by-zero stream-error end-of-file parse-error reader-error

Printing and reading

format print prin1 princ prin1-to-string princ-to-string write-string write-char write-line terpri fresh-line finish-output force-output read-line read-from-string *standard-output* *standard-input* streamp make-string-output-stream get-output-stream-string with-output-to-string make-string-input-stream

Files

open close with-open-file probe-file directory delete-file load

The system

room sleep get-internal-real-time internal-time-units-per-second *features* lisp-implementation-type lisp-implementation-version

(lisp-implementation-type) is "ClaraOS", and (lisp-implementation-version) the version of the kernel.

The package CLARA

Threads, locks and events, the image, and two things for whoever writes a console or a file system: a stream made of two functions, and the way a file system tells the language that it is there.

clara:make-thread clara:current-thread clara:threadp clara:thread-name clara:thread-alive-p clara:all-threads clara:join-thread clara:destroy-thread clara:interrupt-thread clara:thread-yield clara:make-lock clara:acquire-lock clara:release-lock clara:with-lock-held clara:make-event clara:signal-event clara:wait-event clara:save-image clara:keyboard-interrupt clara:make-stream clara:provide-files

clara:keyboard-interrupt is the condition that Ctrl-C is.

The package CLARA.DRAW

Drawing says what each of these is for.

clara.draw:screen clara.draw:allocate-surface clara.draw:free-surface clara.draw:surface-p clara.draw:surface-width clara.draw:surface-height clara.draw:color clara.draw:pixel clara.draw:fill-rectangle clara.draw:draw-rectangle clara.draw:draw-text clara.draw:text-width clara.draw:draw-bitmap clara.draw:copy-rectangle clara.draw:with-clip clara.draw:damage clara.draw:take-damage clara.draw:add-damage clara.draw:show clara.draw:start

The packages CLARA.WINDOWS and CLARA.TERMINAL

Windows says what each of these is for. clara.windows:resume is what the system calls as it starts, for a world that was saved with the window manager running.

clara.windows:start clara.windows:stop clara.windows:running-p clara.windows:resume clara.windows:open-window clara.windows:close-window clara.windows:show clara.windows:window-p clara.windows:window-title clara.windows:window-surface clara.windows:window-position clara.windows:move-window clara.windows:raise-window clara.windows:rename-window clara.windows:next-event clara.windows:windows clara.windows:focused-window clara.windows:define-application clara.windows:install-application clara.windows:unload-application clara.windows:remove-application clara.windows:applications clara.windows:launch clara.windows:key-typed clara.windows:pointer-moved

clara.terminal:open-terminal clara.terminal:terminal-p clara.terminal:terminal-stream clara.terminal:terminal-window clara.terminal:clear clara.terminal:listener

The packages CLARA.EDITOR and CLARA.FILES

The two applications that are files. Each package is there once its application has been launched, and gone again when it is unloaded; the one name of each is the function that clara.windows:launch calls.

clara.editor:edit

clara.files:browse

The console, the drivers and the file system

Each of these is a file of Lisp in /clara with a package of its own, and these are the names that it lets the others use. Most are for the system itself: Looking at the machine has the ones that tell something at the prompt. A function named start is what the system calls as it starts, and is not for calling again.

clara.console:start clara.console:stop clara.console:write-text clara.console:read-text-line clara.console:use-serial clara.console:use-screen clara.console:make-console-stream clara.console:key-typed clara.console:read-edited-line clara.console:lend-screen clara.console:return-screen

clara.font:+width+ clara.font:+height+ clara.font:+first+ clara.font:+last+ clara.font:*glyphs*

clara.pci:start clara.pci:devices clara.pci:device-p clara.pci:device-bus clara.pci:device-slot clara.pci:device-part clara.pci:device-vendor clara.pci:device-id clara.pci:device-kind clara.pci:device-revision clara.pci:location clara.pci:description clara.pci:hex clara.pci:config-8 clara.pci:config-16 clara.pci:config-32 clara.pci:capabilities clara.pci:base-address clara.pci:map-registers clara.pci:enable clara.pci:message-interrupt

clara.virtio:device-type clara.virtio:open-device clara.virtio:start-device clara.virtio:device-p clara.virtio:device-pci clara.virtio:device-event clara.virtio:device-features clara.virtio:register-8 clara.virtio:register-16 clara.virtio:register-32 clara.virtio:open-queue clara.virtio:queue-p clara.virtio:queue-size clara.virtio:queue-add clara.virtio:queue-notify clara.virtio:queue-take

clara.input:start clara.input:devices clara.input:pointer clara.input:pointer-changed clara.input:set-pointer-limits clara.input:key-character clara.input:send-keys-to clara.input:send-pointer-to clara.input:*repeat-delay* clara.input:*repeat-interval* clara.input:+up+ clara.input:+down+ clara.input:+left+ clara.input:+right+ clara.input:+home+ clara.input:+end+ clara.input:+page-up+ clara.input:+page-down+ clara.input:+insert+ clara.input:+f1+ clara.input:+alt+

clara.disk:start clara.disk:disks clara.disk:disk-p clara.disk:disk-name clara.disk:disk-sectors clara.disk:disk-read-only clara.disk:read-sectors clara.disk:write-sectors clara.disk:*patience*

clara.fat:start clara.fat:volumes clara.fat:*volume* clara.fat:volume-p clara.fat:volume-disk clara.fat:volume-kind clara.fat:volume-first clara.fat:entries clara.fat:entry-p clara.fat:entry-name clara.fat:entry-short clara.fat:entry-directory-p clara.fat:entry-size clara.fat:names clara.fat:file-text clara.fat:read-file clara.fat:write-file clara.fat:remove-file

clara.listener:run clara.listener:answer clara.listener:read-and-answer clara.listener:answer-lines

The package CLARA.UNSAFE

For drivers. What can be read with one of the first seven can be written with setf.

clara.unsafe:memory-8 clara.unsafe:memory-16 clara.unsafe:memory-32 clara.unsafe:memory-64 clara.unsafe:port-8 clara.unsafe:port-16 clara.unsafe:port-32 clara.unsafe:fill-memory-32 clara.unsafe:copy-memory clara.unsafe:expand-bits-32 clara.unsafe:fill-rectangle-32 clara.unsafe:copy-rectangle-32 clara.unsafe:allocate-memory clara.unsafe:free-memory clara.unsafe:map-memory clara.unsafe:memory-string clara.unsafe:string-bytes clara.unsafe:string-memory clara.unsafe:heap-image clara.unsafe:interrupt-event clara.unsafe:message-interrupt clara.unsafe:pci-configuration clara.unsafe:framebuffer clara.unsafe:serial-device clara.unsafe:serial-byte clara.unsafe:serial-break clara.unsafe:keyboard-break clara.unsafe:take-screen clara.unsafe:give-screen