freepascal.compiler/rtl/macos/README

Welcome to the MacOS port of FreePascal (FPC)
==============================================

It is considered under construction, at the moment.

Most of the programs in demo/text works.

Prerequisites:
--------------
Please note that compiling must be done on a platform
supported by FPC, either in Darwin (MacOS X) or e g on
Windows or Linux.

MPW (or ToolServer, but the rest of the description consider doing it
from MPW) must be installed on the target Macintosh.
It can be downloaded from Apple Computer, see
ftp://ftp.apple.com/developer/Tool_Chest/Core_Mac_OS_Tools/MPW_etc./

Compiling on host:
------------------
When compiling for target MacOS, use FPC as for other
operating systems with these options:

-Tmacos # target macos
-st	# dont generate executable, link on target

If make is used, add OPT=-st OS_TARGET=macos (on foreign platforms
CPU_TARGET=powerpc must also be added)

Note that one must first build the RTL by issuing make in rtl/macos, with
the above options, to be able to buld other programs. (Currently only
system.pp and som OS independant units are available)

You might also want to add option -a, then the link script will not delete
not needed files, in particular the assembler files (*.s). This can be
useful if there are problems with the link script and you want to rerun it.

Assembling and linking on target:
---------------------------------
In case that host and target machine is different, transfer the produced
files, that is assembler files (*.s) and link script *_ppas, to the host.

On the target, use MPW to assemble and link the output from FreePascal by
executing the link script (which is an MPW script), with its directory
as current directory. Unfortunatelly the link script does not have the
proper mac file type, so this has to be fixed first e. g with
the MPW command SetFile.

Example: To build Hello World, execute:

Directory HD:Projekt:FreePascal:fpc:rtl:macos
SetFile -c 'MPS ' -t 'TEXT' system_ppas
system_ppas	#executes the script
Directory HD:Projekt:FreePascal:fpc:demo:text
SetFile -c 'MPS ' -t 'TEXT' hello_ppas
hello_ppas	#executes the script


Note on the compiler implementation
===================================

Global variables
----------------
Currently all global variables are indirect, that is the entry in
the TOC is always a pointer to data. (In the future small data items
may be stored directly in the TOC)

Thus all references to globals are via a construct like:
lwz rX, yyy[TC](r2)  ;loads a pointer to a global into rX

Debugging
----------
-g is considered under construction.

When -g has been fixed, some debugging should be possible in
Power Mac Debugger 2.1, can be downloaded from Apple,
ftp://ftp.apple.com/developer/Tool_Chest/Core_Mac_OS_Tools
/MPW_etc./Debuggers/Power_Mac_Debugger.sit.hqx


It should be possible to see source code
but it will not be possible to examine variables.
One can of course examine registers, especially
at entry and exit point where the parameter lists is stored
in registers, according to the calling conventions.

A suggestion is to do the main debugging in GDB in the Darwin version of the
program.