Skip to content

Building applications

tools/macapp.py compiles C sources with this SDK's headers and links them into an application, fat (68k and PowerPC) by default:

CLANG=path/to/clang python3 tools/macapp.py -o Hello.bin examples/hello.c
python3 tools/macapp.py --cpu 68k -o Hello68.bin examples/hello.c -- -DDEBUG
hmount disk.img && hcopy -m Hello.bin :Hello && humount

Flags after -- go to clang. The output is MacBinary II, for hfsutils' hcopy -m. --name, --creator and --size (the memory partition in KB) set the Finder name, the creator code and the SIZE resource; --carbon imports from CarbonLib first on PowerPC; --console window puts the C library's stdin, stdout and stderr in a window instead of files (see The C library). When a 68k program's data is out of the 16-bit PC-relative reach (a program over about 32 KB), tools/macapp.py compiles it again with -mcmodel=large, and says so; --large does that from the start. The runtime and C libraries are built that way, which costs about 1% in size.

The linkers it runs are in tools/link/ and can be used on their own:

  • codelink.py links the ELF objects that clang's m68k-apple-macos target makes, with start.S first, into one CODE 1 resource linked at address 0, followed by a table of the absolute pointers in it. CODE 0 is a one-entry jump table. At launch start.S adds the load address to each pointer, calls _FlushCodeCache where the trap exists (not on the 64K ROM, nor on System 6 on a Mac Plus or SE) and calls main. Code compiled as usual reaches its data PC-relative, within 32 KB; code compiled with -mcmodel=large uses 32-bit addresses, which start.S relocates, and can be any size. Calls are 32-bit either way.
  • peflink.py links the XCOFF objects that powerpc-apple-macos9 makes into a PEF application (a cfrg 0 resource, the PEF container in the data fork). Each imported call gets a glue stub that restores the TOC. It finds which shared library exports each name in imports.json (from Retro68's import libraries, by gen-imports.py; macos-exports.py makes one from a real System Folder and ROM). InterfaceLib wins a name that other libraries also export; CarbonLib and Apple;Carbon;Networking are imported weakly.
  • fatlink.py merges the two: the PowerPC code in the data fork, named by cfrg, and the 68k code in CODE. A Power Mac runs the PowerPC code and a 68k Mac runs CODE.

Both linkers take archives (.a) and link only the members a program needs. codelink.py lays out .preinit_array, .init_array and .fini_array and defines the __init_array_start-style symbols that the C library walks, so static constructors run on 68k. On PowerPC, clang names each object's constructors and destructors as AIX does (__sinit and __sterm functions, with the priority in the name), and peflink.py puts them in the same tables, in priority order. Not done yet in them: shared libraries (exports), and pattern-compressed PEF data.

The runtime library

clang calls helper functions for what the CPU cannot do in a few instructions: on the 68000, 32-bit multiply and divide (__mulsi3, __udivsi3, ...), and on both CPUs 64-bit divide, soft float on 68k (__adddf3, ...), conversions, and memcpy and memset for structure copies. runtime/build.sh builds them into libmacrt.a for each CPU, from compiler-rt's builtins and runtime/string.c (the mem* functions and the common str* ones):

CLANG=path/to/clang LLVM_SRC=path/to/clang-retro/llvm runtime/build.sh

It writes lib/m68k/libmacrt.a and lib/ppc/libmacrt.a, which tools/macapp.py links when they are there (--no-runtime leaves them out). Without the C library below, declare the <string.h> functions you use yourself, as tests/runtime.c does. Soft float is large on 68k and counts towards the 32 KB limit: tests/runtime.c, which uses float and double arithmetic and conversions, links to 20 KB.

tests/runtime.c checks each helper, and tests/fixmath.c the FixMath glue; tests/run.sh runs their 68k builds as a 68000 and a 68020 in tools/sim68k.py.

The C library

runtime/build-libc.sh builds picolibc (stdio, stdlib, string, math, setjmp, ...) for both CPUs, and the Mac layer under it in runtime/libc/:

CLANG=path/to/clang PICOLIBC_SRC=path/to/clang-retro/picolibc runtime/build-libc.sh

It needs meson and ninja, and writes lib/include (picolibc's headers) and lib/m68k and lib/ppc (libc.a, libmacos.a and libmacconsole.a). When they are there, tools/macapp.py compiles against those headers, links both archives before libmacrt.a, and starts the program at __crt_main, which runs the static constructors and calls exit(main(argc, argv)) with the application's name as argv[0]; --no-libc leaves the C library out. The Mac layer gives picolibc:

  • files over the File Manager: open, read, write, lseek, close, unlink and rename (into another folder too, with PBCatMove, on the same volume). Paths are POSIX (a/b is :a:b under the application's folder, /Disk/a is Disk:a, .. is the parent); a name with no / is used as a Mac path as it is. New files are TEXT/ttxt (set the globals _ftype and _fcreator to change that). Data is not converted: write \r for Mac line ends.
  • stdout and stderr written to the file "App Output" in the application's folder, with \n turned into \r, so SimpleText opens it. stdin reads the file "App Input" there, with \r turned into \n, and is at end of file when there is none. A program can define __mac_console_read (and __mac_console_write and __mac_console_close) itself to read and write elsewhere.
  • with tools/macapp.py --console window, a console window instead: stdout and stderr show in a window in Monaco 9 that opens on the first output or input, wraps at its width and scrolls up when full, and stdin reads the lines typed into it (Delete takes back a character; Command-D, Command-period or the close box is the end of input). Reading first flushes stdout, so a prompt with no newline shows. The window initializes the Toolbox when it opens, unless the program sets _console_toolbox to 0 first because it has done that itself. When the program ends, the window stays until a key is pressed or it is clicked.
  • malloc, calloc, realloc and free over NewPtr, SetPtrSize and DisposePtr, and aligned_alloc, posix_memalign and memalign, which take a larger block when NewPtr's is not aligned enough.
  • time and gettimeofday from GetDateTime, in UTC: the first call reads the time zone set in the Map control panel (ReadLocation) and, unless the environment has been set, sets TZ to that offset, so localtime gives the Mac's local time. The Mac knows no daylight saving rules, so times in the other season are an hour off.
  • exit and _exit through ExitToShell.
  • errno from File Manager and Memory Manager errors.

picolibc is built without debug information, since clang crashes writing it for XCOFF. The C library is large next to 32 KB: tests/libc.c, which uses stdio, strtod, qsort and localtime, links to about 54 KB of 68k code, so tools/macapp.py builds it with -mcmodel=large.

tests/libc.c checks it; tests/run.sh runs its 68k build as a 68000 and a 68020 in tools/sim68k.py --os, and its PowerPC build in tools/simppc.py; it runs tests/console.c with the console window in both too, typing a line into it.

Testing

  • tools/sim68k.py App.bin runs a 68k application on a 68k CPU emulator (the unicorn Python package) and prints each Toolbox trap it makes, with its arguments. Only a few traps are faked, so it checks code generation, relocation and stack balance for small programs, not drawing. --os fakes the Memory Manager and the File Manager's parameter-block calls with the files kept in memory, a PowerBook's _PMgrOp, the Sound Driver (an asynchronous write ends at the next trap, which first runs its completion routine as an interrupt would) and ReadLocation (a Mac in UTC-8) and PBGetCatInfo and PBCatMove (folders being the prefixes of the file names); --files prints the files the program left, and --input TEXT gives the C library's stdin that text. --keys TEXT gives a console window that text as key presses, then Command-period; the window's drawing calls are faked and DrawText prints the text drawn.
  • tools/simppc.py App.bin runs a PowerPC application on a PowerPC CPU emulator (unicorn too): it loads the PEF container, applies its relocations, and gives each imported InterfaceLib function a fake built on sim68k.py's (the Memory Manager, the File Manager, ReadLocation, DrawString, ExitToShell, the console window's calls, with --keys too). A program that calls any other import stops there. tests/run.sh runs the runtime, glue and C library tests in it.
  • tools/mame/ boots Apple's System disks in MAME (Systems 0.1 to 7.1) with an application in place of the Finder: mkroms.py makes ROM sets from dumps you own, matrix.py App.bin OUTDIR boots every System and screenshots each one, harddisk.sh boots System 7 from a hard disk image, mfs.py reads and writes the MFS 400K disks of Systems 0.1 to 2.0, dc42.py converts DiskCopy 4.2 images, and crashdump.lua writes the registers when an application crashes.
  • tools/qemu/boot-q800.sh boots System 7.6.1 or Mac OS 8.1 on QEMU's q800 from a copy of the install CD with the application on it (you supply a Quadra 800 ROM image). tools/qemu/boot.sh boots Mac OS 9 on QEMU's mac99 with a transfer disk. Mac OS 9.2.1 booted from its install CD (-boot d) does not mount a disk that hformat made, since it has no partition map; put that image in the second CD drive instead, from the monitor: change ide1-cd0 xfer.img raw. And tools/qemu/mon.py takes screenshots and clicks through the QEMU monitor.
  • For PowerPC on Mac OS 8.1 and earlier, use SheepShaver with an OldWorld ROM image (such as the beige G3's), with the install CD attached as a CD-ROM.