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.
- Getting it
- Starting it
- The prompt
- The language
- Files
- Saving the world
- Threads
- Drawing
- Windows
- Applications
- Looking at the machine
- When something goes wrong
- 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 X | in the terminal: leave QEMU, whatever the machine is doing |
| Ctrl-A C | in the terminal: QEMU's own monitor, and back |
MEM=1G make run-aarch64 | a 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
make image, on macOS. It makesbuild/claraos.img, a disk with both kernels on it.- 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.
- 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. - Add a Serial device, mode "Built-in Terminal". The system talks there as well as on the screen, and you can type there.
- 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-pciand-device virtio-tablet-pci. The second is the pointer, which the window manager is worked with. - 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 processor | x86_64 or AArch64. One is used, however many the machine has. |
| Firmware | UEFI. The kernel is the program that the firmware starts: there is no boot loader between them. |
| Memory | 128 MiB is enough to start and to work. It is given 512 MiB unless you say otherwise. |
| A disk | A 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 type | A serial port, a virtio keyboard, or both. |
| A screen | The one the firmware sets up, if there is one. Without it everything is on the serial port. |
| A pointer | A 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
| Enter | ends the line |
| Backspace, Delete | takes back the last character of the line |
| Tab | a space |
| Ctrl-C | while you type: gives up the line, and the form it was part of. While a form is evaluated: stops it. |
| Ctrl-D | at 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.
- Numbers are integers of 63 bits. No larger integers, no ratios, no floating point.
loopis the plain one, a body that is repeated until areturn. Its keywords,forandcollectand the rest, are not there.do,dolistanddotimesare.formatknows~A,~S,~D,~%and~~.- The functions on sequences,
mapcar,find,remove-if,sortand the others, take lists.length,subseqandconcatenatetake strings as well. Of their keyword arguments there is:test, with:keyformember,assocandsort, and:initial-valueforreduce. defstructtakes a name and slots, and none of its options.- Conditions are handled by
handler-case. There is nohandler-bind, no restart and no debugger. - There are no hash tables, no classes and generic functions, and no
typep. - A package can be made, used when it is made, exported from, and deleted when no other uses it. Nothing is imported or shadowed afterwards.
eqandeqlare the same function. Letters change case as far as ASCII has them:(string-upcase "é")is"é".- A function can call itself some three thousand calls deep. Past that it is the error above, and not the end of the machine.
(declare (special ...))and&environmentare refused, and so are the reader's#.,#Sand#P.
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-exists | when there is a file of that name already |
|---|---|
:error | an error, which is what happens when nothing is said |
:supersede | the new file takes its place |
:append | what is written goes after what the file holds |
nil | no stream: open gives NIL, and nothing is written |
What to know about files as they are now:
- A file is text, in UTF-8. It is read whole when it is opened and written whole when it is closed, so it has to fit in memory, which a text does.
- A name can be 255 characters long and have spaces in it. It cannot have any of
" * : < > ? \ |in it, or end in a dot or a space. - Directories cannot be made, and a file cannot be renamed or moved. A new file goes into a directory that is there.
- There is no clock in the system, so every file it writes is dated the first of January 1980.
- The disk is a FAT volume, which other systems read. On macOS,
build/claraos.imgopens with a double click, and the files that ClaraOS wrote are in it.
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
- Functions, macros, structures, packages and conditions that were defined, and the values of variables, come back. So does the package that names were being read in.
- A special variable comes back with the value it has outside every
let, also when it was saved from inside one. - Threads do not come back. The world starts again at the prompt, and does not go on in the middle of what it was doing. A thread that was running is one that has been stopped, and a lock that was held is free.
- The window manager is running again when it was running, with one Listener window. The windows that were open do not come back.
- The devices are found again, as at every start. A world can be saved on one machine and started on another that has other devices, or another screen, as long as it is the same kind of processor.
- Files are on the disk either way, and have nothing to do with the image.
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 says | which means |
|---|---|
| it was saved on ARM64, and this machine is X86-64 | An image is for the kind of processor it was saved on. |
| it is not what was saved, by its checksum | The file was damaged, or changed, since it was written. |
| it is 775020 bytes long, and not as long as it says it is | The 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 does | Some other file has the image's name. |
| ClaraOS 0.0.14 saved it, with objects that are not laid out as they are here | The 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 name | The image was saved by a newer system than the one that is starting. |
| the machine has no memory for its heap | The 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
clara:make-threadstarts a function of no arguments in a thread of its own, andclara:join-threadwaits for it and gives what the function gave.- A thread that ends with an error says so on the console, and the error is what
join-threadthen reports. The other threads go on. - A lock is held by one thread at a time.
clara:with-lock-heldtakes it for the forms inside and gives it back whichever way they end. - An event counts how often it was signalled.
clara:wait-eventwaits until it has been, and takes one off the count. With a number of milliseconds as its second argument it waits no longer than that, and givesNILwhen the time ran out. (sleep 2)waits two seconds. The other threads run meanwhile.clara:destroy-threadtells a thread to stop, which it does at its next step, cleaning up on its way out.clara:interrupt-threadis Ctrl-C for one thread: what it computes, or waits for, ends with the conditionclara:keyboard-interrupt, which the thread can handle. A Listener window does this to its own thread when Ctrl-C is typed in it.
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.
clara.draw:allocate-surfacemakes a surface of so many pixels across and down, all of them black.clara.draw:surface-widthandclara.draw:surface-heightsay how large one is.clara.draw:colormakes a colour of its red, its green and its blue, each from 0 to 255. What it gives is a pixel as this machine's screen has them, a number, and that is what everything that draws takes.clara.draw:fill-rectangletakes a surface, the place of the rectangle's upper left corner, its width and its height, and a colour.clara.draw:draw-rectangletakes the same and draws the outline only, a pixel thick. A line along a row or a column is a rectangle that is one pixel high or wide.clara.draw:draw-textdraws a string in the console's font, in which every character is 8 pixels wide and 16 high, with the upper left corner of the first one at the place given. With one more colour after the first, the cells of the characters are filled with it, and without it only the characters themselves are drawn, over what was there.clara.draw:text-widthsays how wide a string will be.
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
- A rectangle of damage is a list: how far across and down it begins, how wide it is and how high.
clara.draw:take-damagegives the same list and leaves the surface without any, andclara.draw:add-damagecounts a part as drawn on, to have it shown again. clara.draw:copy-rectanglecopies a part of one surface to a place on another, or on the same one: the surface it comes from, the corner of the part, its width and height, then the surface it goes to and the corner there.clara.draw:draw-bitmapdraws a picture of one bit to the pixel. The picture is a vector of its rows from the top, each a number whose bits are the pixels of the row, and after it comes how many pixels wide it is. Where a bit is 1 the pixel takes the colour. With one more colour after it, the pixels whose bit is 0 take that; without, they stay as they were.(clara.draw:screen)is the screen as a surface, orNILon a machine without one. Whatever is drawn on it shows at once, and it keeps no damage.
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 window | brings 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 window | is where to take hold of it: press the button there, move, and let go. |
The x at the end of the title | closes the window, and ends the program in it. |
Applications | lists the applications there are. A click on a name starts one, and a click anywhere else puts the list away. |
| Alt and Tab | brings 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"
clara.windows:open-windowtakes a title and the width and height of the inside, in pixels, and gives the window, on top of the others and the colour of the console's paper. With:xand:yit goes where they say, and otherwise a step down and across from the one before. A window is 24 pixels wide or more.clara.windows:window-surfaceis what to draw on, andclara.windows:showputs on the screen what was drawn since the last time. It givesNILwhen there was nothing.clara.windows:move-windowmoves a window so that the corner of its inside is at a place on the screen, and gives the place it came to, which isclara.windows:window-positionfrom then on: a window stays below the bar, and never leaves the screen altogether.clara.windows:windowslists the windows from the top one down,clara.windows:focused-windowis the first of them, andclara.windows:raise-windowbrings one to the top.clara.windows:close-windowtakes a window off the screen and gives its memory back.
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)
:keyis called with the code of every character that is typed while the window has the focus.clara.windows:key-typedis what the keyboard's driver calls; here it stands in for a key.:pointeris called when a button of the pointer goes down or comes up on the inside of the window, with the place, counted from the corner of the inside, and the buttons that are down: 1 for the left one, 2 for the right, 4 for the middle.clara.windows:pointer-movedis what the drivers of mice and tablets call, with a place on the screen and the buttons.:closeis called when thexin the title is clicked, and a window that was given none has nox. It is for the function to see that the window is closed, by the thread that opened it.
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
clara.windows:next-eventgives what happened next, and waits when nothing has: for as long as it takes, or for so many milliseconds, after which it givesNIL.(:key 97)is a key,(:pointer 12 30 1)a button that went down or came up, with the place on the inside and the buttons, and(:close)a click on thex, which such a window always has.- A key is the code of the character it types. The keys that type none have codes too, past the last that a character can have, which is
char-code-limit:clara.input:+up+,+down+,+left+,+right+,+home+,+end+,+page-up+,+page-down+,+insert+, and+f1+for the first of the twelve function keys, with the others after it. Escape is 27, Delete 127, and a key that is typed with Alt held hasclara.input:+alt+added to its code. clara.windows:rename-windowgives a window another title.
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 character | goes in at the cursor. |
| Enter | begins a new line, as far in as the line it comes from. |
| Backspace, Delete | take 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. |
| Tab | spaces, up to the next column that is a multiple of eight. |
| The arrows | move the cursor by a character and by a line. |
| Home, End | the start and the end of the line. |
| Page Up, Page Down | a window's worth of lines up or down. |
| A click | puts the cursor where the pointer is. |
| Ctrl-S | saves the text in its file. A text that has no file yet is asked for a name. |
| Ctrl-O | asks for the name of another file, and the text becomes that of the file. |
| Ctrl-K | cuts 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-Y | puts back what Ctrl-K cut last, at the cursor, as often as it is typed. |
| Ctrl-E | evaluates 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 title | close 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:
- A file is its lines. It is saved with a new line after each, so a file that did not end in one has one afterwards. The line with nothing in it after the last is where the text ends.
- A character that the screen's font does not have shows as a box, a tab among them, and is kept as it is.
- There is no undo, nothing is searched for, and nothing can be marked: Ctrl-K and Ctrl-Y are how text is moved.
- What the forms of Ctrl-E print goes to the console, which is the serial port while the windows are on the screen. They are read in the package
COMMON-LISP-USERunless the text saysin-package. - Each editor window is a thread of its own with its own text. Two that have the same file open know nothing of each other.
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, End | pick another name. |
| Enter | goes 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 left | go to the directory that this one is in. |
| A click | picks the name it is on, and on the name that is picked does what Enter does. |
| Delete | asks whether the file that is picked is to be deleted, and y deletes it. Any other key does not. |
| Ctrl-R | reads the directory again: the window does not notice by itself what was written since. |
Ctrl-Q, the x in the title | close 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")
clara.windows:unload-applicationstops the application wherever it runs, which closes its windows, and deletes the packages that its file made: what the file defined is gone from the world, and the memory it took comes back. The application stays in the list, and the next launch loads the file as it is by then. That is how to try a change to an application: save the file, unload, launch.clara.windows:remove-applicationdoes the same and takes the name out of the list. It is also what takes out an application that was defined at a prompt, likeHello.- An application that fails, in its file or later, ends with its windows closed. The reason is said on the console, as for any thread:
error in #<THREAD "Greeting">:and what went wrong. - The editor and the browser are unloaded and launched again the same way, and
/clara/editor.lispcan be changed in the editor. - What an application is installed as is part of the world, and is saved with it. Whether its file has been loaded is too: a world that is saved after the editor was used starts with the editor in it.
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 see | What 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 full | A 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 full | Forms 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 off | The 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