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.pylinks the ELF objects that clang'sm68k-apple-macostarget makes, withstart.Sfirst, 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 launchstart.Sadds the load address to each pointer, calls_FlushCodeCachewhere the trap exists (not on the 64K ROM, nor on System 6 on a Mac Plus or SE) and callsmain. Code compiled as usual reaches its data PC-relative, within 32 KB; code compiled with-mcmodel=largeuses 32-bit addresses, whichstart.Srelocates, and can be any size. Calls are 32-bit either way.peflink.pylinks the XCOFF objects thatpowerpc-apple-macos9makes into a PEF application (acfrg0 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 inimports.json(from Retro68's import libraries, bygen-imports.py;macos-exports.pymakes one from a real System Folder and ROM). InterfaceLib wins a name that other libraries also export; CarbonLib andApple;Carbon;Networkingare imported weakly.fatlink.pymerges the two: the PowerPC code in the data fork, named bycfrg, 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):
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/:
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,unlinkandrename(into another folder too, withPBCatMove, on the same volume). Paths are POSIX (a/bis:a:bunder the application's folder,/Disk/aisDisk:a,..is the parent); a name with no/is used as a Mac path as it is. New files areTEXT/ttxt(set the globals_ftypeand_fcreatorto change that). Data is not converted: write\rfor Mac line ends. stdoutandstderrwritten to the file "App Output" in the application's folder, with\nturned into\r, so SimpleText opens it.stdinreads the file "App Input" there, with\rturned into\n, and is at end of file when there is none. A program can define__mac_console_read(and__mac_console_writeand__mac_console_close) itself to read and write elsewhere.- with
tools/macapp.py --console window, a console window instead:stdoutandstderrshow in a window in Monaco 9 that opens on the first output or input, wraps at its width and scrolls up when full, andstdinreads 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 flushesstdout, so a prompt with no newline shows. The window initializes the Toolbox when it opens, unless the program sets_console_toolboxto 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,reallocandfreeoverNewPtr,SetPtrSizeandDisposePtr, andaligned_alloc,posix_memalignandmemalign, which take a larger block whenNewPtr's is not aligned enough.timeandgettimeofdayfromGetDateTime, in UTC: the first call reads the time zone set in the Map control panel (ReadLocation) and, unless the environment has been set, setsTZto that offset, solocaltimegives the Mac's local time. The Mac knows no daylight saving rules, so times in the other season are an hour off.exitand_exitthroughExitToShell.errnofrom 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.binruns a 68k application on a 68k CPU emulator (theunicornPython 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.--osfakes 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) andReadLocation(a Mac in UTC-8) andPBGetCatInfoandPBCatMove(folders being the prefixes of the file names);--filesprints the files the program left, and--input TEXTgives the C library'sstdinthat text.--keys TEXTgives a console window that text as key presses, then Command-period; the window's drawing calls are faked andDrawTextprints the text drawn.tools/simppc.py App.binruns a PowerPC application on a PowerPC CPU emulator (unicorntoo): it loads the PEF container, applies its relocations, and gives each imported InterfaceLib function a fake built onsim68k.py's (the Memory Manager, the File Manager,ReadLocation,DrawString,ExitToShell, the console window's calls, with--keystoo). A program that calls any other import stops there.tests/run.shruns 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.pymakes ROM sets from dumps you own,matrix.py App.bin OUTDIRboots every System and screenshots each one,harddisk.shboots System 7 from a hard disk image,mfs.pyreads and writes the MFS 400K disks of Systems 0.1 to 2.0,dc42.pyconverts DiskCopy 4.2 images, andcrashdump.luawrites the registers when an application crashes.tools/qemu/boot-q800.shboots System 7.6.1 or Mac OS 8.1 on QEMU'sq800from a copy of the install CD with the application on it (you supply a Quadra 800 ROM image).tools/qemu/boot.shboots Mac OS 9 on QEMU'smac99with a transfer disk. Mac OS 9.2.1 booted from its install CD (-boot d) does not mount a disk thathformatmade, since it has no partition map; put that image in the second CD drive instead, from the monitor:change ide1-cd0 xfer.img raw. Andtools/qemu/mon.pytakes 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.