maux
Star on GitHub Buy me a coffee

A typo, caught

Watch / typo

Filmed on the Apple IIe 80-column display. The same session on the Videx UltraTerm: same keys, same text.

The Videx UltraTerm was an 80-column video card for the Apple IIe, with its own video memory and character generator, real hardware scrolling and more screen modes than the IIe's own 80 columns. This demo runs on either display; the UltraTerm film shows the original Videx UltraTerm, emulated.

A build error, read and fixed the old way. The film copies the hello example, changes one letter in vi (jsr PUTS becomes jsr PUTZ), and runs make, which fails. nas has said what is wrong, on make's screen, but it scrolls away. Run alone, with its complaints sent to a file, it keeps them: nas hello.s 2> ERRS, and cat ERRS reads them again, the label, the file and the line. vi goes straight to that line, the letter is put back, and make builds a program that says hello, world.

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 typo; cd typo
$ cp /usr/src/examples/HELLO/hello.s /usr/src/examples/HELLO/Makefile .
$ vi hello.s
  keys: /jsr<RET>$rZ<ESC>:wq<RET>
$ make
$ nas hello.s 2> ERRS
$ cat ERRS
$ ls
$ vi hello.s
  keys: :35<RET>$rS<ESC>:wq<RET>
$ cmp hello.s /usr/src/examples/HELLO/hello.s
$ make
$ ./hello

What the captions say

  1. A typo in a working program, and the old-school way to find it.
  2. One wrong letter: PUTS becomes PUTZ.
  3. nas has said what is wrong, but it will scroll away.
  4. Run it alone, and 2> keeps its complaints in a file you can read again.
  5. 2> is file descriptor 2, standard error. Version 7's shell already had it.
  6. ed answers a bad command with one ?. nas names the label, the file and the line.
  7. This failure leaves no hello.o, so make has no stale one to trust.
  8. The error says line 35. vi can go straight there: :35 and RET.
  9. cmp says nothing: the file is the lesson's again, byte for byte.
  10. make assembles with nas, then links with ld.
  11. Edit, assemble, read the errors, edit: the loop, at one megahertz.

What nas says, and where

An unknown label is reported as nas: unknown label PUTZ (hello.s line 35), followed by nas: pass 2 failed. Both lines go to standard error, file descriptor 2, so 2> catches them and the screen stays quiet; the success line, nas: 32 bytes -> hello.o, goes to standard output. The line number counts from 1 in the file named in the parentheses, which is what vi counts, so :35 lands on the mistake. (vi +35 is not accepted here, so the film types the colon form.)

Why there is no make clean

The film runs with the clock card off, so every file has one date, and with a clock card ProDOS would date files only to the minute. Either way make can miss an edit that came soon after a build. It does not matter here: this failure (an unknown label, found in the second pass, before the object file is opened) leaves no hello.o, which the film shows with ls, so after the repair make has nothing stale to trust.

The old ways

The captions lean on two Unix facts. The Bourne shell of Version 7 already redirected a file descriptor chosen by a leading digit, as in 2>&1: see the V7 sh(1) page. And the V7 ed(1) page lists its diagnostics: ? for errors in commands, and ?name for an inaccessible file.

The gate that proves it

This film is made by site/demos/typo.py. Run as assertions, the same file is make check-demo-typo, and it runs with the rest of the tests, on both displays. The line number comes from the host reading the lesson's hello.s, so the film cannot drift from the lesson. It requires that make prints the nas command, nas's two lines and make's own failure line; that nas hello.s 2> ERRS prints nothing to the screen; that ERRS holds exactly the two lines, with the right file and line; that no hello.o is left; that after the repair cmp against the lesson's file is silent; and that the rebuilt program says hello, world. The checks themselves were tested: with nas replaced by a copy of true, with a line added at the top of the lesson's file, and with the film expecting the wrong line, it fails at the row that checks make's output.

Transcript

The screen at every checkpoint the test checks, as the recorder saved it:

== cp prints nothing (t=21.2 s)
$ cd /tmp
$ mkdir typo; cd typo
$ cp /usr/src/examples/HELLO/hello.s /usr/src/examples/HELLO/Makefile .
$

== the jsr line now says PUTZ (t=32.7 s)
            jsr   PUTZ
            lda   #0
            jsr   EXIT

MSG         asc   'hello, world',0D,00
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~

== make fails (t=45.1 s)
$ make
nas -o hello.o hello.s
nas: unknown label PUTZ (hello.s line 35)
nas: pass 2 failed
make: command failed
$

== make echoes nas, nas reports the label and the line, then make says a command failed (t=45.1 s)
$ make
nas -o hello.o hello.s
nas: unknown label PUTZ (hello.s line 35)
nas: pass 2 failed
make: command failed
$

== nas prints nothing to the screen (t=64.1 s)
$ nas hello.s 2> ERRS
$

== ERRS holds the label, the file and the line (t=72.0 s)
$ nas hello.s 2> ERRS
$ cat ERRS
nas: unknown label PUTZ (hello.s line 35)
nas: pass 2 failed
$

== ls (t=79.8 s)
$ nas hello.s 2> ERRS
$ cat ERRS
nas: unknown label PUTZ (hello.s line 35)
nas: pass 2 failed
$ ls
ERRS      hello.s   Makefile
$

== this failure left no hello.o behind (t=79.8 s)
$ nas hello.s 2> ERRS
$ cat ERRS
nas: unknown label PUTZ (hello.s line 35)
nas: pass 2 failed
$ ls
ERRS      hello.s   Makefile
$

== line 35 is on the screen, with the typo (t=98.8 s)
*
* The string is plain 7-bit ASCII (single quotes) ending in CR
* ($0D) and then NUL: PUTS stops at the NUL. maux's console
* takes it in either polarity.
*
* This file is staged on the release disk as MAUX TEXT (high
* bit set, lines ended by $8D), exactly what `vi` writes. nas
* reads that or ProDOS-standard text (low ASCII, $0D) alike, so
* edit it with `vi` and run `nas` on it: nothing to convert.
*---------------------------------------------------------------
            rel
            lst   off
PUTS        ext
EXIT        ext
            put   /usr/inc/sc.fd.equ
            put   /usr/inc/zp.equ

START       lda   #<MSG
            sta   PTR0
            lda   #>MSG
            sta   PTR0+1
            ldx   #FD_STDOUT
            jsr   PUTZ

== the line says PUTS again (t=99.3 s)
*
* The string is plain 7-bit ASCII (single quotes) ending in CR
* ($0D) and then NUL: PUTS stops at the NUL. maux's console
* takes it in either polarity.
*
* This file is staged on the release disk as MAUX TEXT (high
* bit set, lines ended by $8D), exactly what `vi` writes. nas
* reads that or ProDOS-standard text (low ASCII, $0D) alike, so
* edit it with `vi` and run `nas` on it: nothing to convert.
*---------------------------------------------------------------
            rel
            lst   off
PUTS        ext
EXIT        ext
            put   /usr/inc/sc.fd.equ
            put   /usr/inc/zp.equ

START       lda   #<MSG
            sta   PTR0
            lda   #>MSG
            sta   PTR0+1
            ldx   #FD_STDOUT
            jsr   PUTS

== and no line says PUTZ (t=99.3 s)
*
* The string is plain 7-bit ASCII (single quotes) ending in CR
* ($0D) and then NUL: PUTS stops at the NUL. maux's console
* takes it in either polarity.
*
* This file is staged on the release disk as MAUX TEXT (high
* bit set, lines ended by $8D), exactly what `vi` writes. nas
* reads that or ProDOS-standard text (low ASCII, $0D) alike, so
* edit it with `vi` and run `nas` on it: nothing to convert.
*---------------------------------------------------------------
            rel
            lst   off
PUTS        ext
EXIT        ext
            put   /usr/inc/sc.fd.equ
            put   /usr/inc/zp.equ

START       lda   #<MSG
            sta   PTR0
            lda   #>MSG
            sta   PTR0+1
            ldx   #FD_STDOUT
            jsr   PUTS

== cmp says nothing: the file is the lesson's (t=110.7 s)
$ cmp hello.s /usr/src/examples/HELLO/hello.s
$

== make runs nas then ld (t=144.7 s)
$ make
nas -o hello.o hello.s
nas: 32 bytes -> hello.o
ld -o hello hello.o -L /usr/lib -l a
$

== make echoes the nas line, nas reports, then the ld line (t=144.7 s)
$ make
nas -o hello.o hello.s
nas: 32 bytes -> hello.o
ld -o hello hello.o -L /usr/lib -l a
$

== it prints hello, world (t=147.0 s)
$ ./hello
hello, world
$