This file documents the details relevant to the Unix versions of UAE. General
information can be found in the file "README"

System requirements
===================

UAE will run on most Unix systems, and by now most of the portability issues
have been sorted out. However, since I am developing UAE using Linux, you may
encounter problems from time to time. If this happens, let me know as soon as
possible so these can be fixed in the next release.

These are the requirements for getting the Unix version to run:
  - X11, or SVGAlib if you are using Linux.
  - 8MB RAM (better 16MB) + some swap
  - The 386 is the only CPU that UAE will not run on. You need a 486 or
    higher if you want to use an Intel CPU.
  - an ANSI C compiler. Do not use a K&R compiler, otherwise you risk getting
    incorrect code. GCC is _strongly_ recommended, preferrably version 2.95.3.
  - Optionally, the gtk library, available from ftp.gimp.org, and a pthreads
    library.


Compilation
===========

To build UAE, first unpack it to an appropriate directory (e.g. /usr/src/uae
on a Linux system). The simple way to proceed is to type "configure; make", 
after that has completed you should have a working X11 version of UAE. Ignore
warnings if you get them.

However, you should probably have a look at some of the compile-time options
found in "config.h" before you do this. There are some things you can change
there so that the resulting executable will perform better on your machine.
Each of the options in that file has a description. You can edit config.h to
suit your needs; and then do "configure; make" afterwards.

When running configure, there are a few options that you can use to
influence configure's decision as to what kind of display should be used.
The following displays are available:
  - Standard X11, in a window. This is the default.
  - X11/DGA. This runs full-screen and is somewhat faster than the normal X11
    code. You need a recent (>= version 3.2) XFree86 X server.
  - SVGAlib. This is only available on Linux systems. It is the default if X11
    is not found by configure.
  - ncurses character output. This is the last resort.

Type "configure --help" to get a list of options that configure understands.
The following are likely to be useful:
  --without-x        : Don't use X11 as target.
  --with-svgalib     : Build a version that uses SVGAlib (Linux only)
  --with-asciiart    : Build a version that uses ASCII "graphics"
  --enable-sound     : If a sound system is found that UAE knows about, sound
                       emulation will be compiled in.
  --enable-profiling : Build a much slower version of the emulator (if you 
                       don't know what it's for, you don't want it)
  --enable-dga       : If your X server supports the DGA extension, use it
  --enable-vidmode   : If your X server supports the VidMode extension, use
                       it. This enables the emulator to switch to low
                       resolutions such as 320x256 or 400x300 if you have
		       defined ModeLines for them.
  --enable-ui        : Build a user interface if possible (enabled by default)
  --enable-threads   : Build UAE multithreaded on systems that support it.
                       Note that there is very little thread support in UAE at
		       the moment.
  --enable-penguins  : Enable some additional threads which only make sense on
                       SMP (symmetric multi penguin) machines. If you have a
		       single-CPU machine, you don't want to use this option.
Note that there is a corresponding "--disable-xxx" for each "--enable-xxx"
option, and a "--without-yyy" for each "--with-yyy".

Both the SVGAlib and the DGA version run full-screen, i.e. you can't run other
programs at the same time very well. You also need to be root to run either of
these two versions.
Making UAE suid root is _not_ a particularly good idea if you care about the
security of your system.

If you are not sure whether you have an SMP machine, you don't have one.


Run-time options
================

The X11 version (without DGA) of UAE understands these special command-line
options:
  -L     : Use "low-bandwidth" mode, which can reduce the amount of data
           transferred between UAE and the X server. That's particularly an
	   advantage when these are running on two different machines in a
	   network.
  -T     : Use the MIT-SHM extension. This may not be available on all
           machines, and it will not work if UAE and the X server are not
	   running on the same machine.
	   In all other configurations, turning on this option will give you
	   a huge speed improvement.
  -x     : Turn off the X11 mouse cursor for the UAE window. Personally, I
           find that seeing the X cursor helps, but that's a matter of taste.

The SVGAlib version understands the following command-line option:
  -x     : Turn off linear frame buffer support, even if it is available.
           Unless linear mode doesn't work properly, you don't want to disable
	   it, because UAE is much faster if it can draw into a linear
	   frame buffer.


Keyboard mappings
=================


You can exit the SVGAlib version by pressing the F12 key.
PgUp/PgDn emulate the right/left Amiga keys. In the SVGAlib version, F11 will
bring you back to the user interface screen so you can change disks during the
emulation.

The X11 version needs some help to figure out how to map keys: You'll have to
tell it the keyboard language with the "-l" commandline option. Several
languages ("us", "se", "de", "fr", "es", "it") are supported. If you have
a different keyboard, patches to make UAE work with it are appreciated.

In the X11 version, there are several key combinations that invoke some
behaviour:
  F12+'q': Quit the emulation.
  F12+'g': "Grab" the mouse, so it won't leave the UAE window.  Use the same
           combination to ungrab the mouse.
  F12+'i': Toggle graphics updates on/off.  Same as ScrollLock.
  F12+'p': Toggle sound interpolation method.  This is useful for determining
           the differences between interpolation methods.
  F12+'m': Toggle between alternative mouse pointer emulation methods; either
           follow-mouse or dont-care.
  F12+'+' (keypad plus sign): Increase frame rate (fewer frames displayed).
  F12+'-' (keypad minus sign): Decrease frame rate (more frames displayed).


Mouse and joystick emulation
============================

The X11 (non-DGA) version has one problem: There are two mouse pointers, the
X11 mouse pointer and the mouse pointer in the emulator window. You can work
that way, but you get confused quickly.
The solution in previous (0.6.8 and before) versions of UAE was a small piece
of code that looked at the position of sprite 0 on the screen and tried to
generate mouse movements in an emulated hardware port. That worked reasonably
well, but had several problems.
The new solution is to use a small Amiga program which is called "mousehack".
You will find this in the "amiga" subdirectory. Put it into the directory that
you use for harddisk emulation so that you can run it from the emulator. Then
put the command "run >NIL: mousehack" at the top of your startup-sequence. UAE
will detect when this program is running and use the improved mouse pointer
positioning method. (Don't run this program on old versions of UAE)
If the program is not running, you get the old behaviour - almost. By default,
the emulator will no longer try to keep Amiga and X mouse pointers at the same
position, because that led to problems in the past. You can toggle this
behaviour with F12.
(If you just added "run mousehack" to your startup-sequence, that would have
the effect that the initial CLI window would be impossible to close.
Unfortunately, redirecting output to >NIL: disables all error messages that
mousehack can give you - so if it does not work, try running it by hand
without the >NIL: redirection.)

If you find a program in which the mouse pointer does not move at all if you
use the X11 version, start that program with mousehack _not_ running
(Magnetic Scrolls adventures are known to need this, for example).

The SVGAlib and DGA versions are not affected by any of this (and pressing F12
exits those versions).

If you use Linux and have the joystick driver kernel module, "configure"
should automatically enable support for it. UAE calibrates the joystick
automatically. Turn it a few times on startup to get the calibration done. 


Harddisk emulation
==================

Please read the appropriate sections in the file "README" on how to use the
filesystem emulation. There are a few Unix-specific things about it, though.

If you want to execute files located on a native filesystem, they need to have
the x permission bit set. That can be done in Unix by "chmod +x file" or in
AmigaDOS with "protect file rwed".
You should set aside a whole directory tree for AmigaOS files, and not use it
from Unix in any way if you can avoid it. Changing permissions/owners,
creating symbolic links and doing other stuff that AmigaOS does not know about
is a good way to confuse the emulator and the emulated software. E.g. it's
possible to have a symlink pointing at a mounted CD-ROM. The emulator would
see that as a directory inside which it gets "read only filesystem" errors,
and wouldn't know what to do about it. Avoid this sort of thing. It's best to
start with an empty harddisk emulation directory and install software there
only from within the emulation.
The following setup can also lead to problems:
  -m dh0:/foo -m dh1:/foo/bar
Please take care that the filesystems you mount don't overlap each other
(another great reason not to use symbolic links within them).


Printing
========

If you give UAE the "-p lpr" option, output for the parallel port will be
piped to lpr, which will in turn print it. You should use the Postscript
printer driver on the Amiga side (since UAE relies on the ^D character at
the end of the Postscript output).
Note that I never tried this myself, so you're on your own.


Transferring things over the serial port
========================================

There's an easy way to use a null-modem cable without terminal software if
you use Linux (and probably other Unices). You can do

  transdisk >SER: <options>

on the Amiga to copy the data directly to the serial port. Before that, do

  cat /dev/ttyS1 >df0.adf
  
on your Linux box to receive the data (it may be ttyS0 on your system, or
another number, depending on which serial port you are using). When the Amiga
is done transferring, hit ^C on the PC to interrupt the cat program. To make
this work, you need to use the same settings for the serial port on both
sides. This is done with the Preferences program on the Amiga (this is split
into several programs from Kickstart 2.0 upwards, you'll find a program called
"serial" in the Prefs directory of your Workbench disk). On the Linux side,
use the stty program. "man stty" will give you the manpage describing how to
use it.
To be on the safe side, set the speed to a low value (2400 baud). Turn off
Xon/Xoff, but enable RTS/CTS.
I use the following command myself:

  stty 19200 parenb -cstopb cread clocal crtscts -istrip -inlcr -icrnl -opost
    -onlcr -parodd -isig -icanon -iexten raw cs8 </dev/ttyS1

which is probably overkill, but you never know :)
This maps to 19200 baud, 8 bits, even parity, one stop bit, which you have to
set in the Amiga preferences.


Using the Linux AFFS filesystem
===============================

If you use Linux with a kernel version >= 2.0.7 and version 2.5k of the mount
program, you can do
   mount df0.adf /mnt -t affs -o loop
to mount disk image df0.adf at the mount point /mnt. This is much more
convenient than using the "readdisk" program.

You'll need to enable support for the Amiga filesystem and the loop device
when configuring and compiling the kernel (say yes to the "Ask about
experimental drivers" question at the start).