maux
Star on GitHub Buy me a coffee

L6. hello, world, in PLASMA

Learn / L6

Goal: compile a program in PLASMA, a small language that compiles to bytecode, with the compiler running on the machine itself, run it, and then run the same program again as a single file cut by the plasma cutter.

What you need

L1 (you can edit a file with vi) and L5 (you can write a Makefile). The files are on the disk in /usr/src/examples/HELLOPLA; this lesson types them, because typing a program is how you learn it.

Where the program comes from

The program is not ours. It is src/samplesrc/hello.pla from PLASMA, written by David Schmenk (github.com/dschmenk/PLASMA, MIT licence, Copyright © 2010-2022 David Schmenk), and it is here byte for byte, with his indentation and his line continuations. A check compares our copy with his file at the PLASMA version maux builds against, and fails the build if a byte differs. The licence text is in man licenses.

The files

Six lines. include pulls in the declarations of the runtime, puts prints a string, and a backslash at the end of a line continues the statement on the next one. done ends the module.

examples/hellopla/hello.pla — on the disk as /usr/src/examples/HELLOPLA/hello.pla
include "inc/cmdsys.plh"

puts( \
     "Hello, world.\n" \
    )
done

The Makefile is maux's own. PLASMA's compiler exits with success even when it reports an error, and make runs each line without a shell, so the rule removes the old module first and lists the new one afterwards: ls fails if the module is not there, and that stops make. Each indented line starts with a TAB.

examples/hellopla/Makefile — on the disk as /usr/src/examples/HELLOPLA/Makefile
hello.mod: hello.pla
	rm -f hello.mod
	plasm hello.pla hello.mod
	ls hello.mod
clean:
	rm -f hello.mod

The session

Typed in vi, a key at a time, then built and run. Near the end it runs HELLO, the cooked copy of the same program that came on the disk, from /usr/src/examples/HELLOPLA.

$ mkdir /tmp/l6
$ cd /tmp/l6
$ vi hello.pla
[ in vi: press i, type the program shown above, press ESC, then type :wq and press RETURN ]
$ cat hello.pla
include "inc/cmdsys.plh"

puts( \
     "Hello, world.\n" \
    )
done
$ cmp hello.pla /usr/src/examples/HELLOPLA/hello.pla
$ vi Makefile
[ in vi: press i, type the Makefile shown above (each indented line starts with a TAB), press ESC, then :wq and RETURN ]
$ cat Makefile
hello.mod: hello.pla
        rm -f hello.mod
        plasm hello.pla hello.mod
        ls hello.mod
clean:
        rm -f hello.mod
$ make
rm -f hello.mod
plasm hello.pla hello.mod
PLASMA Compiler v2.21
Data+Code buffer size = $021A


DATA:....1 bytes
INIT:22 bytes

Total bytes compiled: 23
ls hello.mod
hello.mod
$ ls -l
$FE       55 -                hello.mod
TXT       70 -                hello.pla
TXT      103 -                Makefile
$ plasma hello.mod
Hello, world.
$ make
$ /usr/src/examples/HELLOPLA/HELLO
Hello, world.
$ ls -l /usr/src/examples/HELLOPLA
BIN    10953 2000-01-01 00:00 HELLO
TXT       70 2000-01-01 00:00 hello.pla
TXT      103 2000-01-01 00:00 Makefile

What just happened

plasm compiled hello.pla into hello.mod, a relocatable module (type $FE). It reported 23 bytes: a program of this kind is tiny, and so is the compiler's room. plasm fits programs of a few hundred bytes of code and data, enough for hello, world and a sieve, and the manual page says where the limit is. plasma hello.mod then ran it: plasma starts the PLASMA virtual machine, loads the runtime, reads the module, resolves the names it imports and runs it. All of that happens again on every launch.

The plasma cutter

/usr/src/examples/HELLOPLA/HELLO is the same program with the loading already done. It was made on the host, not on the machine, by plascut, the plasma cutter: it does what plasma does at launch (read the runtime and the module, relocate, bind every import) once, and writes the result as one flat BIN file that the shell starts like any command. Nothing is left to resolve when it runs. The module it cuts is the one plasm writes (the host compiler is run without its optimizer, as plasm has none), and the file on the disk is checked against a fresh cut of David Schmenk's hello.pla, so it cannot drift from the source.

The film times them, in cycles of the emulated machine, from the moment RETURN is pressed to the moment the output appears: plasma hello.mod the first time, 1.19 to 1.33 million; the cut ./hello the first time, 0.85 to 0.92 million; and ./hello run again, 0.24 million. (The first run of anything pays to bring its file in from the disk. The figures are to the nearest slice of the recorder's clock, about a sixth of a million cycles.) For this program the cut file saves 0.27 to 0.48 million cycles on the first run.

The saving is the loading, so it grows with how much a program has to load: small for this one, larger for nas, which is shipped cut and which make starts again for every file. In the gate that checks the cutter, one warm nas run on a small fixture (it assembles to 34 bytes) takes 1.65 million cycles cut against 5.95 million loaded through plasma NAS: 4.30 million cycles, 72 percent less, at revision 485672f5. nas, plasm and this HELLO are all cut programs.

Try next

Change the message and run make again. Does it rebuild? It compares the modification times ProDOS keeps, and the one-minute rule from L5 applies, so a change made within a minute of the last build can be skipped; touch hello.pla is the way out. Then break the source on purpose and see what plasm prints and what the Makefile does about it. Finally compare ls -l of HELLO and hello.mod: what type is each?

← make | All lessons | A ProDOS program, tested with bye →