AUIS Revival: Running ez on macOS/Darwin

This guide covers building and running ez and other AUIS applications from the andrew-6.4 revival checkout on macOS with XQuartz. It reflects the state of the revival as of mid-2026; consult porting-changelog.md for the history behind each decision.

For getting messages/cui working against a real IMAP/SMTP mail account, see mail-quickstart.md.

Prerequisites

XQuartz — the X11 server for macOS. Install via:

brew install --cask xquartz

Or download from xquartz.org. XQuartz must be running for any AUIS application to open a window. Modern XQuartz sets $DISPLAY automatically via a launchd socket (/private/tmp/com.apple.launchd.*/ org.xquartz:0); you do not normally need to set it by hand.

Build tools — Xcode Command Line Tools, plus:

brew install bison flex imake makedepend

- bison and flex: the build uses system versions (the vendored Andrew bison hangs on Darwin/arm64 — see porting-changelog.md 2026-06-29) - imake: required to regenerate Makefiles on a fresh checkout - makedepend: required for the make depend phase

Building

Incremental build (normal case)

From andrew-6.4/src/:

make dependInstall 2>&1 | tee ../dependInstall.log

A clean build produces 278 .do files and 602 headers with zero errors. -k is not needed; the tree is clean. Do not run concurrent builds.

Fresh checkout bootstrap

On a brand-new fossil clone with no existing build/ directory, the generated Makefiles and build/include/ tree do not yet exist. Follow the bootstrap sequence from src/README.ascii:

cd andrew-6.4/src

# Step 1: generate the top-level Makefile via imake
imake -I. -I./config -Timake.tmpl -s Makefile -DTOPDIR=.

# Step 2: World = make Makefiles (all subdirs) + make dependInstall
make World 2>&1 | tee ../dependInstall.log

make World regenerates all subdirectory Makefiles via imake, creates the build/ directory tree, builds all libraries and binaries, generates .ih/.eh headers from .ch class specs, and installs everything. On a working tree, make dependInstall is equivalent and faster (skips the Makefile regeneration step).

On a genuinely empty build/ (not just a fresh clone — also any time build/ has been deliberately wiped, e.g. to bisect an old revision), run ../revival/tools/prime-class-header first, before make World. overhead/class/Imakefile builds machdep before lib, but lib is what installs class.h into build/include/ — machdep/darwin/classproc.c needs it already there. This is invisible once build/ has existed for a while (which is every normal case), so it only bites the first make World against a truly empty tree. See porting-assessment.md → "Primary build environment" for the full writeup. Full recipe for testing a specific historical revision (fossil's mtimes make incremental rebuilds untrustworthy across checkouts): porting-assessment.md → "Fossil checkout timestamps make incremental rebuilds untrustworthy...".

Check for LP64 warnings before running new code paths:

grep "warning: cast to '.*\*' from smaller integer type" dependInstall.log

Any hit is a real bug (pointer-returning function called without a prototype, return value truncated to 32 bits). Fix with a local extern TYPE FunctionName(); declaration. See porting-changelog.md and porting-assessment.md §LP64 for the full pattern.

AndrewSetup settings

build/etc/AndrewSetup is a hand-authored site-config file, read at runtime by every AMS/ATK client (GetConfiguration, searching a fixed list of paths ending in ${ANDREWDIR}/etc/AndrewSetup — this revival's site.h points ANDREWDIR at the build tree, so no root access is needed and no other candidate path on this list exists). It is not a build artifact — no Imakefile creates, installs, or regenerates it — but it lives inside build/, so make Clean (or any other wipe of build/) deletes it silently along with everything else, with no error or warning that it's gone.

Run revival/tools/write-andrewsetup any time after a clean to recreate it (refuses to overwrite an existing file; pass -f to force). Current contents:

# AUIS revival local configuration
ThisDomain: fastmail.com

AMS_OnlyMail: No

• ThisDomain — the domain AMS stamps into outgoing From: headers (<unix-login>@<ThisDomain>; any From you type is replaced). Without it, mail goes out as you@your-machine.lan, which real SMTP providers refuse to relay externally. See mail-quickstart.md step 3.
• AMS_OnlyMail — boolean (Yes/No/1/0), defaults to Yes unless the tree is built with RUN_AMDS_ENV (this revival never defines it — see allsys.h). Yes hard-restricts the default "Expose New" startup folder view to $HOME/.MESSAGES only, excluding every other mspath root (e.g. an IMAP mirror) regardless of subscription status — the check happens before subscription is ever consulted. Sites that actually want bboards suppressed should leave this Yes; a personal single-user setup wants No. Full trace of how this was found: claude-history/ folder-visibility-REPORT.md.

Terminal setup — important

Always run AUIS binaries from native Terminal.app or iTerm2, not from a VS Code integrated terminal or any VS Code-attached shell.

VS Code's terminal inherits a Mach exception-port relationship that intercepts crash signals from child processes and never services them. Any AUIS binary that crashes while launched from a VS Code terminal will enter an unkillable UE (uninterruptible zombie) state that survives kill -9 and requires a reboot to clear. The same bug hides real crashes behind an apparently-hung process, making debugging impossible. Running from native Terminal.app, the same crash exits normally and can be caught by lldb. See porting-changelog.md 2026-06-30 for the full diagnosis.

Font path setup

AUIS needs its compiled fonts to be visible to the X server. The build places 40 PCF font files in build/X11fonts/. Add this directory to XQuartz's font path once per XQuartz session (it is lost when XQuartz quits):

xset fp+ /Users/wdc/src/AUIS/andrew-6.4/build/X11fonts
xset fp rehash

Why this is still needed even with Xft text rendering: the revival uses a hybrid font approach:

Rendering path	Font mechanism
Body text	Xft / fontconfig (client-side, no X font path needed)
Menus	Xft (phase 2, in progress as of 2026-07)
Symbol characters (bullets, math marks)	Andy symba*.pcf — X font path required
Cursor shapes	Andy cursor PCF — X font path required

The fonts.alias file in build/X11fonts/ maps Andy text font names (andysans, andytype) to standard Adobe Helvetica/Courier XLFD names already present in XQuartz, so no Andy text bitmap fonts need to be installed. The symba*.pcf files (5 sizes: 8, 10, 12, 16, 22 point) are custom CMU symbol fonts with no standard substitute — without them, bullet characters render as 7 and other symbol characters are wrong.

A future setup step may automate the xset fp+ call, either via a wrapper script or by installing the PCF files into XQuartz's default font path (/opt/X11/share/fonts/).

con10/con12 (console-app icon fonts) are not among the 40 PCF files make World installs, because MK_CONSOLE gates out all of atk/console (including console/fonts) and this revival leaves it off intentionally. These two fonts are referenced by things outside console too — e.g. ams/demo/d10's fad (animation) inset (see Test documents below) uses con10 for an icon — so their absence isn't just "the console app doesn't work," it silently breaks icon rendering elsewhere. Run ../revival/tools/install-console-fonts once per fresh/wiped build/ to build and install just these two fonts, without building the rest of console. See porting-assessment.md → "MK_CONSOLE being off silently breaks con10/con12..." for the full story.

Running ez

Change to the build/ directory and run:

cd /Users/wdc/src/AUIS/andrew-6.4/build
bin/ez -d                          # open a blank document
bin/ez -d doc/README.ez            # open an existing .ez file
bin/ez -d ~/src/AUIS/NEWSLETTERS/EZ/95Summer.ez   # richer test document

The -d flag prevents ez from forking to background, which is useful during development. Without -d, ez daemonizes and the shell returns immediately; crash output goes nowhere visible.

ez is a symlink to runapp, the generic AUIS application launcher. All ATK applications (help, bush, figure, table, etc.) are symlinks to the same binary.

Running help

cd /Users/wdc/src/AUIS/andrew-6.4/build
bin/helpa -d

Note the argument order: application name before flags (helpa -d, not -d helpa). The -d flag is parsed by app.c's ParseArgs after runapp has identified the target application; flags before the app name are not seen by the application.

Known issues (as of 2026-07)

Figure insets load but render incorrectly (messy screen). The figure .do object loads successfully via the dynamic class loader; the rendering bug is inside atk/figure/. Under investigation.

zip insets are not supported — ez will display an error for documents containing them (e.g., some contrib/mit/neos/doc/ files).

ness.gra bison extension — the Ness scripting language grammar uses a multi-character string token extension specific to the Andrew bison fork. The grammar does not build with system bison. Ness functionality is unavailable until this is resolved.

Debugging crashes

Use lldb from native Terminal.app:

cd /Users/wdc/src/AUIS/andrew-6.4/build
lldb bin/ez -- -d path/to/file.ez
(lldb) run
... wait for crash ...
(lldb) bt
(lldb) frame select N
(lldb) frame variable

When a new crash is encountered, check dependInstall.log for a -Wint-to-pointer-cast warning at the crashing function before assuming a new bug type — it is likely an LP64 missing-prototype truncation, the most common crash class in this codebase. See porting-assessment.md for all known LP64 bug patterns.

Test documents

Good ez test files, in order of increasing complexity:

File	What it tests
revival/testing.ez	text, note, calc, eq, table insets; used for the Media-menu regression-test checklist in roadmap.md ("ez application (menus)")
ams/demo/d10	fad (animation) inset; exercises the con10 console icon font — see Font path setup
doc/README.ez	Basic text, page break insets (bp/bpv)
src/contrib/mit/rtf2/test.ez	Rich paragraph styles, no insets
src/FAQ.ez	Long document, footnote insets
src/contrib/mit/neos/doc/history.ez	Raster image insets
src/contrib/mit/neos/doc/NEOS_stud.ez	6 rasters + zip inset
~/src/AUIS/NEWSLETTERS/EZ/95Summer.ez	Figure insets (messy, under investigation)
~/src/AUIS/NEWSLETTERS/EZ/92Sep.ez	Raster + footnote insets
~/src/AUIS/PAPERS/atk/Boren.CACM	Non-.ez format; full justification, multiple font sizes