maux
Star on GitHub Buy me a coffee

Dev

For a programmer who already knows 6502 assembly. There is no C compiler, so the library is the thing you program against: liba, whose routines are named and shaped after the libc functions they stand in for. Learn the handful below and most of a Unix program writes itself.

liba

liba is a directory of REL modules at /usr/lib/LIBA that ld -l a searches. A program names what it wants with ext and the linker pulls in the modules that define those names; the equates it includes live in /usr/inc. liba is built by nas, and a gate checks that a fresh build reproduces the tracked objects byte for byte (check-liba-pins).

        ext   PUTS,EXIT
        lda   #<msg
        ldx   #>msg
        sta   PTR0
        stx   PTR0+1
        ldx   #1              ;stdout
        jsr   PUTS

The file is the inclusion boundary, so a program pays for every routine in a module it touches, whether it calls it or not. make report-liba prints that bill per program and names the routines nobody reached.

The libc names it answers to

Same job, same name where the name survives six characters of Merlin label. Arguments arrive in registers and zero-page pointers rather than on a C stack, and each routine's own header comment is the contract.

libalibcWhat differs
STRLENstrlen16-bit, so a string over 255 bytes measures correctly
STRCMPstrcmpbyte for byte, 16-bit
STRCMPIstrcasecmpfolds a-z only; digits and punctuation untouched
STRCPYstrcpyterminator included
PUTSwritetakes an fd, not a stream; the NUL is not written
PUTCfputcbuffered per fd, line or full (SIOM_LINE, SIOM_FULL)
GETCgetcone raw byte; flushes every stream first
SIO_FLUSHfflushone fd; SIO_FLUSHALL for all of them
FCLOSEfcloseflushes, then closes
EXITexitflushes every stream; SC_EXIT is _exit
LSEEKlseekthe offset is 3 bytes, so a file reaches 16 MB
SC_PIPEpipewrites the two fds into your buffer
SC_DUP2dup2as in V6
SC_FDSTATisattyanswers what kind of object an fd holds
SC_BRK, SC_SBRKbrk, sbrkpage-granular; see below
GETENVgetenvENVNTH walks it the way environ does
OPTINIT, GETOPTgetoptOPTINIT takes the permitted letters first; OPTIND as usual
OPENDIR, RD_ADVANCE, CLOSEDIRopendir, readdir, closediralso serves the synthetic directories
RE_MATCHregexecbasic expressions only, no ERE; no separate compile step
HASMETA, GFOLDfnmatchthe shell's globbing primitives
PRNUM, PRHEX8, PRHEX16printfno format strings and no varargs: one routine per conversion

Where it is not libc

The nas dialect

nas is the native assembler. It accepts the Merlin-derived dialect this repository checks, and nothing is promised beyond that: it is not a claim to accept every Merlin macro or historical option. The limits below are house limits, inherited from Merlin-8 and held by the check-modules and check-dialect gates over every source in the tree. They are not errors that nas itself raises:

Usage: nas -o OUTPUT INPUT.S. The -o comes first; without it the output name is A.OUT. Success returns 0, a reported failure 1.

REL and ld

Objects are Merlin REL files, ProDOS file type $F8. An object is its code, then 4-byte fixup records, then a symbol list; the file's ProDOS aux type is its code length, so a REL moved without its metadata links to nothing. ld links modules and library directories (not archives; there is no ar), origin $0800 by default:

nas -o hello.o hello.s
ld -o hello hello.o -L /usr/lib -l a

PLASMA and the plasma cutter

maux runs David Schmenk's PLASMA: a word-oriented language compiled to bytecode for a small virtual machine. plasm is his compiler, running on the machine; plasma hello.mod runs a module it wrote. The L6 lesson on the Learn page compiles his own hello.pla that way. A PLASMA program has to be linked at launch: plasma reads the runtime, reads the module, relocates it and binds each name it imports, every time.

The plasma cutter, scripts/plascut.py, does that work once, on the host, and writes the result as a single flat BIN file that the kernel spawns like ls: the runtime and every module already relocated and bound, with a small table that puts the program's data back to its pristine state on a warm respawn. A cut program is the same module as the loaded one with its loading done in advance, not a different language or compiler. nas and plasm are shipped this way, and so is the HELLO of the L6 lesson, which is why make can start them once per file without paying for the link each time.

Measured on the emulator by the gate that checks the cutter, at revision 485672f5: one warm nas run over a small fixture (it assembles to 34 bytes, so this is the cost of loading, not of assembling) takes 1.65 million cycles cut against 5.95 million loaded through plasma NAS: 4.30 million cycles, 72 percent, saved on every launch. The cutting itself happens on the host, not on the machine.

make

make is a POSIX subset with no shell between it and the commands: macros ($(NAME), ${NAME}, $@ $< $* $?), double-suffix inference rules, .SUFFIXES, .SILENT, .IGNORE, .PRECIOUS, .DEFAULT, .POSIX, the @ - + recipe prefixes, and -e -i -k -n -p -q -r -S -s -t. It has no built-in rules, no single-suffix rules, no include, no :: rules, no parallelism. It reads either text convention.

Text

maux writes high-bit-set 7-bit ASCII ending in $8D and types such files $04. That is a maux ruling, not a property of the machine: standard ProDOS text is low ASCII ending in $0D, with the same type byte. The line-oriented tools read either convention, and a filter emits the convention its input arrived in, so running one over a file from a2til, tip or a NuFX archive does not leave a mixed file. nas and make read either too.

Underneath: calling the kernel

liba's SC_ routines are thin wrappers over this, and you rarely need it directly. The native door is JSR $FF00: the call number in Y, a pointer to the parameter block in A (low) and X (high), the result in A with carry set on failure. A call that takes no parameters, such as fork, ignores the pointer.

        lda   #<parms
        ldx   #>parms
        ldy   #SYS_FORK
        jsr   $FF00

The kernel is entered by that call or by an interrupt; both build the same six-byte frame on the process's own stack. A BRK in a user process is a SIGTRAP: the process is killed and the machine goes on. A BRK in the kernel halts it. The full contract is docs/SYSCALL.md.

42 calls are defined in the inc/sc.*.equ files, which the build reads. The low numbers are the kernel's process, descriptor, signal and terminal calls. The file calls start at $C0 and each is named for the ProDOS MLI call it carries. The comments in each file describe the call.

callnumberdefined in
SYS_SPAWN1inc/sc.proc.equ
SYS_EXIT2inc/sc.proc.equ
SYS_WAIT3inc/sc.proc.equ
SYS_PIPE4inc/sc.proc.equ
SYS_BRK5inc/sc.proc.equ
SYS_PSTAT6inc/sc.proc.equ
SYS_CLOCK7inc/sc.proc.equ
SYS_FORK8inc/sc.proc.equ
SYS_DUP29inc/sc.proc.equ
SYS_TICK10inc/sc.proc.equ
SYS_FDSTAT11inc/sc.proc.equ
SYS_TTYGEO12inc/sc.proc.equ
SYS_KILL13inc/sc.proc.equ
SYS_SIGNAL14inc/sc.proc.equ
SYS_SIGPEND15inc/sc.proc.equ
SYS_TTYMODE16inc/sc.proc.equ
SYS_TCSETFG17inc/sc.proc.equ
SYS_CONT18inc/sc.proc.equ
SYS_WAITJOB19inc/sc.proc.equ
SYS_STOP20inc/sc.proc.equ
SYS_VCSTAT21inc/sc.proc.equ
SYS_HALT22inc/sc.proc.equ
SYS_BYE23inc/sc.proc.equ
SYS_DEVLIST24inc/sc.proc.equ
SYS_VROOT25inc/sc.proc.equ
SYS_SLPUNTIL26inc/sc.proc.equ
SYS_CREAT$C0inc/sc.file.equ
SYS_UNLINK$C1inc/sc.file.equ
SYS_RENAME$C2inc/sc.file.equ
SYS_SFI$C3inc/sc.file.equ
SYS_GFI$C4inc/sc.file.equ
SYS_ONLINE$C5inc/sc.file.equ
SYS_SETPFX$C6inc/sc.file.equ
SYS_GETPFX$C7inc/sc.file.equ
SYS_OPEN$C8inc/sc.file.equ
SYS_READ$CAinc/sc.file.equ
SYS_WRITE$CBinc/sc.file.equ
SYS_CLOSE$CCinc/sc.file.equ
SYS_SET_MARK$CEinc/sc.file.equ
SYS_GET_MARK$CFinc/sc.file.equ
SYS_SET_EOF$D0inc/sc.file.equ
SYS_GET_EOF$D1inc/sc.file.equ