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. - 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. - 8MB RAM (better 16MB) + some swap - Optionally, tcl7.4/tk4.0 or the X Forms library (version 0.80 or higher) 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-ggi : Build a version that uses GGI (Linux only) --with-asciiart : Build a version that uses ASCII "graphics" --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-ui : Build a user interface if possible (enabled by default) --enable-xfgui : For the X11 version, enable an alternate GUI using the X Forms library. The standard X GUI requires Tcl/Tk 7.4/4.0. --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 don't give any options affecting the GUI, configure will try to set up UAE to use the Tcl/Tk GUI. It needs to find the program "wish4.0" in the path to be able to do that. 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 (and the DGA) 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. Mouse and joystick emulation ============================ The X11 (non-DGA) version has one problem: There are two mouse pointers, the X mouse pointer and the Y mouse pointer. 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: 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 = 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).