Installation of the Atari800 Emulator
--------------------------------------

Irrespective of whether you are going to compile the emulator yourself
or install a pre-compiled binary version you must obtain a copy of the
Operating System ROMs.

The ROM images are distributed within the PC Xformer 2.5 package (other
versions of this program do not contain the ROMs in a suitable format)
which can be downloaded from:-

http://prdownloads.sf.net/atari800/xf25.zip

If you are creating the ROM images yourself they should be copied from
the following locations:-

1. Atari BASIC (8192 bytes between $a000 and $bfff)
   Note: On a 400/800/1200XL system a BASIC cartridge must be inserted, and on
   other systems the built-in BASIC must be enabled by setting bit 1 of PORTB
   to 0.
2. Atari 400/800 OS (10240 bytes between $d800 and $ffff)
3. Atari XL/XE OS (16384 bytes between $c000 and $ffff)
   Note: If you are extracting the XL/XE OS you will find that the ROM area
   under the custom chip ($d000 to $d7ff) is mapped between $5000 and $57ff
   when bit 7 of PORTB is set to 1. I.e. you should set bit 7 of PORTB and
   then dump the memory out in the following order:- $c000 to $cfff,
   $5000 to $57ff and finally $d800 to $ffff.
4. Atari XEGS built-in game (8192 bytes between $a000 and $bfff)
   Note: the built-in game must be enabled by setting bit 1 of PORTB to 1 and
   bit 6 to 0.
5. Atari 5200 BIOS (2048 bytes between $f800 and $ffff)

The first time you run the emulator it will scan the current directory for
compatible ROMs and load them. At the same time, a new configuration file
will be created, with the new paths stored so the next time you run the
emulator the ROMs would be find automatically.

Compiling the Emulator
----------------------

The emulator can be compiled for the following systems (and probably
many others with a little work):-

1. X Window Version (including SUN OpenWindows) on a Unix Platform
   (prefer the SDL version)
2. CURSES version
3. Graphical Version for the Amiga (not maintained)
4. Graphical version for the Atari TT/Falcon and compatible computers
5. "simple" version (no graphics). Should be straightforward to configure
   for any 32-bit environment supporting ANSI C.
6. VGA Version for DOS
7. SDL (Linux/Unix, Windows, BeOS)
8. WinCE
9. Java (various platforms)
10. Static library version: libatari800

Installed zlib (compression library) enables building the emulator with
compressed statesave images support.

Installed libpng makes the emulator capable of generating screenshots in
the PNG format.

Installed libmp3lame enables MP3 audio to be saved in video and audio
files.

Building the Emulator on most platforms
---------------------------------------

1. Change your working dir to the atari800 path
2. Check if "configure" script is there. If it is skip to step 4.
3. Run "./autogen.sh" (make sure you have autoconf >= 2.5x installed).
4. Type "./configure".
5. Type "make".
6. Change directory to atari800/src
7. Install the emulator by typing "make install".

Please note it is also possible to build atari800 outside the source
directory. Just follow steps 1-3 and then call `configure' from your build
directory, i.e. ../atari800/configure if your build directory is located next
to atari800 source directory.

By default, the "configure" script attempts to auto-detect the best interfaces
available to use for emulating video and sound. It is also possible to
override autodetection and select a specific interface by appending the
"--with-video=<value>" and "--with-sound=<value>" options to the command
in step 4. Below is the list of available values for these options:  
a) Video interfaces (--with-video):
- dosvga: use direct access to VGA card, only under DOS/DJGPP
- sdl: use the Simple DirectMedia Library
- curses: use the curses library
- ncurses: use the ncurses library
- pdcurses: use the pdcurses library
- no: use only stdin/stdout for input/output. Supported on all platforms
b) Sound interfaces (--with-sound):
- win: use the WinMM library, only under Windows
- falcon: use Atari Falcon native sound
- dossb: use direct access to a Sound Blaster-compatible card, only under
  DOS/DJGPP
- sdl: use the Simple DirectMedia Library
- oss: use Open Sound System
- no: disable sound altogether. Supported on all platforms

Only the video and sound interfaces listed above are autodetected, but the
emulator also supports other ones. To build for a platform that is
not automatically detected, replace step 4 of the above instructions with:

4a. Type "./configure --target=help" for a list of supported platforms.
4b. Type "./configure --target=<YourTarget>" (choose from the list above)


Building the Emulator for Curses
--------------------------------

Follow the instruction above but note that you must be using the
System V Curses Library. BSD Curses is lacking a few functions and
will not work (nodelay, attron, attroff, keypad and curs_set).

Building the Emulator for DOS
-----------------------------

To compile, use DJGPP the DOS port of gcc, which can be got from
http://www.delorie.com/djgpp/. You will need complete environment
in order to configure and build the executables.
You may need zlib (compression library) to use compressed statesave images
and libpng for PNG screenshots. To build curses (text mode) version install
curses-compatible library (e.g. PDCurses) and add
"--with-video=pdcurses" when invoking "./configure".

Since the source code contains files with long file names, you must unpack
and compile the source on a filesystem supporting long file names (for example
VFAT of Windows95). An additional change of DJGPP setting is required:
open the DJGPP.ENV file in editor and change the LFN= line to LFN=y

1. Run "configure_dos.bat".
2. Run "make" and "make joycfg".
3. If everything went good you should have atari800.exe and joycfg.exe -
   copy them to destination directory.

Building the Emulator for Windows
---------------------------------

See DOC/BUILD.windows.

Building the Emulator for Falcon
--------------------------------

You need a recent GCC, for example 4.6.4, running on a filesystem with long
file names (either minixfs/ext2fs of MiNT, or VFAT of MagiC).

1. Type "./configure --target=falcon".
2. Type "make".
3. Copy atari800 to destination directory or try "make install".

You also can build the default target (by omitting the "--target" option)
with optional support for curses or SDL - see "Building the Emulator on most
platforms".

Building the Emulator for SDL
-----------------------------

1. Please install (and configure) SDL library (http://www.libsdl.org).
2. If you want to build an OpenGL-capable version, you'll need OpenGL headers
   installed. They should support OpenGL version 2.1 or later, ie. with support
   for the Pixel Buffer Object (PBO) extension. The result binary, however, will
   not require an OpenGL 2.1-capable video card - it will also support OpenGL
   1.1 video cards (PBOs simply won't be used), and machines without OpenGL
   support aat all (only software modes will be available).
3. Follow the instructions in the "Building the Emulator on most platforms"
   section above. NOTE: To be sure, force using SDL by adding
   "--with-video-input=sdl --with-sound=sdl" when calling "./configure".
   Otherwise the configure script may autodetect and use other libraries for
   video and audio.
4. When building on Windows, see DOC/BUILD.windows for additional notes.

Building the Emulator for Java using NestedVM
---------------------------------------------

1. Get and build NestedVM (nestedvm.ibex.org). make env.sh and unix_runtime.jar
2. source env.sh in the NestedVM directory.
3. Follow steps 1-5 of the "Building the Emulator on most platforms" section
   above, but when calling ./configure, add these two parameters:
   --host=mips-unknown-elf --disable-ide
   ie.
   ./configure --host=mips-unknown-elf --disable-ide
   You might want to add --enable-veryslow --disable-monitorbreak to the above.
   This should result in creation of the file named atari800.jar.
4. atari800.jar requires unix_runtime.jar in the same directory. Copy it from
   the NestedVM directory where you made it using "make unix_runtime.jar" as 
   stated above.
5. To run use: java -jar atari800.jar
Add -o UnixRuntime to the NestedVM compiler options to enable directory
browsing.
This requires changing Windows paths to the form: /c:/file in all configuration
files and on the command line.  It will look for .atari800.cfg in your
Windows home directory.
Applet version:
You must compile with -o UnixRuntime
Apply UnixRuntime.patch to NestedVM.
To use:
<APPLET CODE="atari800.class" WIDTH=672 HEIGHT=480 ARCHIVE="atari800.jar, unix_runtime.jar">
<PARAM name=args value="-config /resource/http://atari800_applet.cfg -xlxe_rom /resource/http://ospp.rom -basic_rom none -nobasic -nopatchall /resource/http://disk.atr">
</APPLET>
All files should have /resource/http:// in front of their names.
Edit atari800_applet.cfg and add /resource/http:// to all rom files, even those
you are not providing.
Legal distribution of Atari800 as an applet cannot include the OS and BASIC
ROM Files.  You can run without BASIC by using -basic_rom none and Thomas
Richter's Os++.

Building the libatari800 static library
---------------------------------------

The libatari800 target requires no external libraries and is platform
independent. It also has no user interface, as it's designed to be embedded
into another program that controls the operation of the emulator.

The build procedure is much the same as on most platforms, except for step 4:

4. Type "./configure --target=libatari800".

The resulting libatari800.a file can be linked with user programs to create an
embedded atari800 emulator.

Running on macOS
----------------

The macOS .dmg package contains an ad-hoc signed Atari800.app bundle.
Before launching it for the first time, right-click the app in Finder
and select "Open" to bypass Gatekeeper, then confirm the dialog.
The app will run normally afterwards. Alternatively, remove the
quarantine attribute from Terminal:

  xattr -dr com.apple.quarantine /Applications/Atari800.app

