Resolution ][ Build Instructions
================================

The Resolution ][ package includes source code, 6502 binary images,
Apple ][ memory dumps, and Apple ][ disk images. Refer to the README.txt
file in each subdirectory for more information about their contents.

All binary versions of Resolution ][ are built with a program start
address of Hex $6100 (Decimal 24832) and a variable table address of
Hex $6000 (Decimal 24576). Because of the limited amount of memory
accessible to an Apple ][ computer in a given moment, these defaults may
not be desirable for some applications. In this case, it is possible
to rebuild Resolution ][ to reside in different memory locations.
Rebuilding Resoltion ][ is also necessary if you wish to modify the
source code.

Building the Resolution ][ source code requires an MS-DOS, Windows,
Macintosh, or UNIX system capable of running the xa65 cross-assembler package
(available at http://www.tu-chemnitz.de/~fachat/c64/xa/index.html).
Currently, Resolution ][ can NOT be built on an Apple ][ machine unless
the syntax for all directives in the source code is changed to match
the format recognized by Apple ][ assemblers.

Follow the steps below to build Resolution ][:

1. Before building Resolution ][, visit the xa65 home page listed above and
   download the latest version of xa65. Configure and install xa65 according
   to the directions provided by the package.

2. Modify the default values in src/defs.asm to match the needs of your
   application. In particular, modify the program_start value to change
   the program start address and modify the write_area value to change
   the variable table address.

3. Type the following commands:

   cd src
   xa -C -v -M main.asm -o ../resii.bin

   This command builds the Resolution ][ binary into a 6502 binary image
   named resii.bin.

4. If you wish to convert the 6502 binary image to an Apple ][ memory
   dump, build the applehexdump utility found in the tools folder.
   This memory dump allows you to transfer the Resolution ][ binary
   from a workstation to an Apple ][ machine, or to manually type the
   Resolution ][ opcodes using the Apple ][ machine language monitor.

   Type the following commands:

   cd ..
   gcc tools/applehexdump.c -o applehexdump

   Substitute the gcc command above with the C compiler installed on
   your MS-DOS, Windows, or UNIX system.

   To create the memory dump file, type the following command:

   ./applehexdump resii.bin start_address > resii.dmp

   where start_address is the Resolution ][ program start address in
   hex. For example, to create a memory dump file for a Resolution ][
   binary built with the starting address of Hex $4000, type the
   following command:

   ./applehexdump resii.bin 4000 > resii.dmp

5. Transfer the Resolution ][ binary image or memory dump to your
   Apple ][ machine or emulator. Transferring files to Apple ][
   machines or emulators is presently beyond the scope of this document.
   File transfer methods and may vary depending on the source workstation
   and the target Apple ][ hardware or emulator.
   
6. If desired, rebuild the Resolution ][ test program using the
   following commands:

   cd src
   xa -C -v -M test.asm -o ../test.bin
   cd ..
   ./applehexdump test.bin start_address > test.dmp

   where start_address is the Resolution ][ test program start address
   in hex. You may transfer the test program binary image or memory
   dump to your Apple ][ machine or emulator.

   The Resolution ][ test program consists of a set of test drivers
   for displaying various images on the double-high-resolution display.
   The AppleSoft BASIC program included with the Resolution ][ disk images
   demonstrate the use of these test drivers. Access these test drivers by
   calling one of the entries in the jump table that starts at the test
   program start address.

7. If you are using DOS 3.3 or ProDOS, determine the length of the
   Resolution ][ binary image (resii.bin file) on the source workstation.
   On the target Apple ][ machine or emulator, save the Resolution ][
   binary image to disk using the following command:

   BSAVE RESOLUTIONII,A$start_address,Lresii_length

   where start_address is the Resolution ][ test program start address
   in hex and resii_length is the length of the Resolution ][ binary
   image in bytes. For example, to save a copy of Resolution ][ starting
   at address Hex $4000 with a length of 1573 bytes, type the
   following command:

   BSAVE RESOLUTIONII,A$4000,L1573

You should now be ready to develop applications with Resolution ][.