LOADER.SYSTEM - an Apple][ ProDOS 8 loader for cc65 programs (Oliver Schmidt)
=============================================================================


Background
----------

Apple][ ProDOS 8 system programs (filetype SYS) are always loaded into memory
starting at location $2000. This poses the problem of how to make efficient
use of the memory in the range $0800-$2000. The usual approach of relocation
has two downsides:
- Relocating e.g. 30 kB from $2000-$9800 to $0800-$8000 takes a considerable
  amount of time.
- Really large programs just don't fit into memory when loaded starting at
  location $2000.

The relocation can be eliminated by loading the major part(s) of the program
from disk right to the final location by a rather small system program.

LOADER.SYSTEM is such a small program. In fact it's so small that it fits into
a single block in the ProDOS 8 file system making it a so-called seedling file,
which are loaded really fast. LOADER.SYSTEM can load cc65 programs into memory
anywhere in the range $0800-$BB00 (44,75 kB).


Usage
-----

Link the cc65 program to the start address $0800 (or any other address) and
store it as binary program (filetype BIN). This is in fact no different from
a binary program to be run by BASIC.SYSTEM's BRUN command in the usual way.

If however the cc65 program isn't run by BASIC.SYSTEM but is rather run by
LOADER.SYSTEM then it behaves like a system program which means:
- It uses memory up to the ProDOS 8 system global page located at $BF00.
- It supports the ProDOS 8 startup file mechanism (mapped to argv[1]).
- It quits to the ProDOS 8 dispatcher.

Obviously LOADER.SYSTEM has to be told which cc65 program to run. Unfortunately
the ProDOS 8 dispatcher has no notion of system program parameters so the usual
approach would have been to make LOADER.SYSTEM bring up yet another menu to
select the cc65 program to run.

But to allow to select the cc65 program directly from the ProDOS 8 dispatcher
anyway LOADER.SYSTEM detects the path to the cc65 program from its own path by
just removing the '.SYSTEM' from its name. So if you want to run the cc65
program MYPROGRAM you'll need a copy of LOADER.SYSTEM in the same directory
being renamed to MYPROGRAM.SYSTEM.

This means you will end up with a copy of LOADER.SYSTEM for every cc65 program
to be run by it. But as LOADER.SYSTEM is a ProDOS 8 seedling file using up only
a single block in the ProDOS 8 file system this should be no issue.


Build
-----

In case you want to build 'loader.system' from the source code yourself you can
do so using the following commands:

ca65 loader.s
ld65 -C loader.cfg -o loader.system loader.o


Installation
------------

The file 'loader.system' as generated by the cc65 linker with the command above
does NOT include the 4-byte address/length header that is generated for Apple][
programs by default. This is because ProDOS 8 system programs are always loaded
into memory starting at location $2000.

The recommended way to transfer 'loader.system' from your native file system to
a ProDOS 8 file system disk image is to use AppleCommander which is available at
http://applecommander.sourceforge.net/

If you want to put the file 'loader.system' onto a disk image 'mydisk.dsk' as
system program MYPROGRAM.SYSTEM you can do so using the following command:

java -jar ac.jar -p mydisk.dsk MYPROGRAM.SYSTEM sys < loader.system