maux builds an ordinary ProDOS 8 system program and then gets
out of its way. nas assembles it, ld links it at
$2000, ls -l says SYS, and
make test hands the whole machine over: ProDOS 8 loads the
program, the program lists the directory it is sitting in and waits for a key,
and QUIT brings back the shell that was waiting all along.
What it types
Everything it types, in order. A line starting with $ is a command at the shell, RET included; keys lines are single keystrokes to a program (RET, ESC and the control keys are named).
$ cd /tmp $ mkdir lssys; cd lssys $ cp /usr/src/examples/LSSYS/* . $ ls $ cat Makefile $ make $ ls -l LS.SYSTEM $ echo $? $ sort GOT $ cat WANT
Between steps it presses ^L to clear the screen.
What the captions say
- A ProDOS 8 program, written and built on maux.
- The Makefile is the test harness.
- `test` builds it, runs it under ProDOS, then compares.
- nas assembles, ld links a SYS file at $2000.
- SYS. ProDOS 8 loads it flat at $2000 and jumps there.
- Now maux gets out of the way.
- GOT is what ProDOS wrote. WANT is what maux's ls says.
The program knows nothing of maux
LS.SYSTEM calls the ProDOS MLI at $BF00 and the
monitor ROM's COUT, and nothing else. It finds its own prefix,
opens the directory like a file, reads it a block at a time, and walks the
entries: the high nibble of an entry's first byte is its storage type and the
low nibble its name length. That is the ProDOS 8 of 1983, not a maux API, so
the same file runs on a stock ProDOS 2.4 disk with no maux on it anywhere
— which is how it is also tested.
It writes the names it found to a file called GOT, in maux's
own text convention: high bit set, each line ended by $8D. So
maux's tools read what ProDOS wrote with no conversion step in between.
GOT is created only after the directory has been read, so it never
lists itself.
One screen, two owners
Watch the picture change shape when the farewell prints. maux runs the
console at 80 columns; bye puts the machine back the way a
ProDOS program expects to find it — text mode, page 1, no
80STORE, 40 columns, and the display handed back to the
motherboard — because a program written in 1983 is entitled to assume
all of that. The 40-column screen in the middle of this film is not a
rendering choice. It is the machine the tenant actually gets.
That is also why this is the one film here with a single display. Every other demo is filmed twice, on the IIe's own 80 columns and on a Videx UltraTerm. During the handover the card is not the selected display at all, so a card film would freeze on the farewell for the whole of the interesting part.
The Makefile is the test
The lesson's test rule is four lines: delete
GOT, run mkwant (which is just
ls | tr a-z A-Z > WANT, maux's own listing), bye
LS.SYSTEM, and run check, which sorts both files and
cmps them. Two programs that share no code, on two operating
systems, list the same directory and are made to agree about it. The exit
status of make is the verdict.
The gate that proves it
This film is made by site/demos/lssys.py. Run as assertions,
the same file is make check-demo-lssys, and it runs with the rest of the tests. It requires that the
copied directory holds the lesson's own files, in the order ls
prints them; that the Makefile on screen is the lesson's,
line for line, tabs included; that make prints the
nas command, nas's report and the ld command, in
that order, and nothing else; that ls -l calls the result
SYS; that the names ProDOS printed appear on the 40-column page
while the tenant owns the machine; that the rows of make test
come back in order, ending in sh check, with an exit status of
0; that GOT and WANT each hold exactly
the expected names; and that the host, reading the disk the machine wrote,
finds GOT to be maux text — every byte with its high bit
set, every line ended by $8D.
Lesson L7 under Learn walks through the same program with the source and the ProDOS directory format explained a line at a time, and links back to this film.
Transcript
The screen at every checkpoint the test checks, as the recorder saved it:
== mkdir prints nothing (t=9.8 s)
$ cd /tmp
$ mkdir lssys; cd lssys
$
== cp prints nothing (t=17.6 s)
$ cd /tmp
$ mkdir lssys; cd lssys
$ cp /usr/src/examples/LSSYS/* .
$
== ls (t=19.1 s)
$ cd /tmp
$ mkdir lssys; cd lssys
$ cp /usr/src/examples/LSSYS/* .
$ ls
check ls.s Makefile mkwant
$
== the copy holds the lesson files: check ls.s Makefile mkwant (t=19.1 s)
$ cd /tmp
$ mkdir lssys; cd lssys
$ cp /usr/src/examples/LSSYS/* .
$ ls
check ls.s Makefile mkwant
$
== the Makefile is the lesson's (TAB = 8 columns) (t=25.5 s)
$ cat Makefile
# make finds nas, ld and rm on PATH, as `sh -c` would (they live in /bin).
LS.SYSTEM: ls.o
ld -t FF -a 2000 -o LS.SYSTEM ls.o
ls.o: ls.s
nas -o ls.o ls.s
test: LS.SYSTEM
rm -f GOT
sh mkwant
bye LS.SYSTEM
sh check
clean:
rm -f LS.SYSTEM ls.o GOT WANT
$
== make runs nas then ld (t=43.9 s)
$ make
nas -o ls.o ls.s
nas: 423 bytes -> ls.o
ld -t FF -a 2000 -o LS.SYSTEM ls.o
$
== make echoes the nas line, nas reports, then the ld line (t=43.9 s)
$ make
nas -o ls.o ls.s
nas: 423 bytes -> ls.o
ld -t FF -a 2000 -o LS.SYSTEM ls.o
$
== ls -l LS.SYSTEM (t=46.9 s)
$ make
nas -o ls.o ls.s
nas: 423 bytes -> ls.o
ld -t FF -a 2000 -o LS.SYSTEM ls.o
$ ls -l LS.SYSTEM
SYS 1b - LS.SYSTEM
$
== ls -l says SYS: ProDOS 8 will boot it ('SYS 1b - LS.SYSTEM') (t=46.9 s)
$ make
nas -o ls.o ls.s
nas: 423 bytes -> ls.o
ld -t FF -a 2000 -o LS.SYSTEM ls.o
$ ls -l LS.SYSTEM
SYS 1b - LS.SYSTEM
$
== make test (tenant window) (t=64.3 s)
CHECK
LS.S
MAKEFILE
MKWANT
LS.O
LS.SYSTEM
WANT
== ProDOS listed the directory: CHECK LS.O LS.S LS.SYSTEM MAKEFILE MKWANT WANT (t=73.7 s)
$ make test
rm -f GOT
sh mkwant
bye LS.SYSTEM
Leaving maux for ProDOS...
Welcome back.
sh check
$
== make test: out to ProDOS and back (t=74.0 s)
$ make test
rm -f GOT
sh mkwant
bye LS.SYSTEM
Leaving maux for ProDOS...
Welcome back.
sh check
$
== make test succeeded (t=75.6 s)
$ make test
rm -f GOT
sh mkwant
bye LS.SYSTEM
Leaving maux for ProDOS...
Welcome back.
sh check
$ echo $?
0
$
== GOT holds exactly the names (t=82.6 s)
$ sort GOT
CHECK
LS.O
LS.S
LS.SYSTEM
MAKEFILE
MKWANT
WANT
$
== WANT holds exactly the same names (t=84.7 s)
$ sort GOT
CHECK
LS.O
LS.S
LS.SYSTEM
MAKEFILE
MKWANT
WANT
$ cat WANT
CHECK
LS.O
LS.S
LS.SYSTEM
MAKEFILE
MKWANT
WANT
$
== on the disk, GOT is maux text (high bit, $8D lines) and holds the 7 names (t=84.7 s)
$ sort GOT
CHECK
LS.O
LS.S
LS.SYSTEM
MAKEFILE
MKWANT
WANT
$ cat WANT
CHECK
LS.O
LS.S
LS.SYSTEM
MAKEFILE
MKWANT
WANT
$