Return to README CVS log

Up to [UNIX Amiga Emulator] / uae / docs / unix

Annotation of uae/docs/unix/README, revision 1.1

1.1     ! root        1: This file documents the details relevant to the Unix versions of UAE. General
        !             2: information can be found in the file "README"
        !             3: 
        !             4: System requirements
        !             5: ===================
        !             6: 
        !             7: UAE will run on most Unix systems, and by now most of the portability issues
        !             8: have been sorted out. However, since I am developing UAE using Linux, you may
        !             9: encounter problems from time to time. If this happens, let me know as soon as
        !            10: possible so these can be fixed in the next release.
        !            11: 
        !            12: These are the requirements for getting the Unix version to run:
        !            13:   - X11, or SVGAlib if you are using Linux.
        !            14:   - 8MB RAM (better 16MB) + some swap
        !            15:   - The 386 is the only CPU that UAE will not run on. You need a 486 or
        !            16:     higher if you want to use an Intel CPU.
        !            17:   - an ANSI C compiler. Do not use a K&R compiler, otherwise you risk getting
        !            18:     incorrect code. GCC is _strongly_ recommended. Don't use versions of GCC
        !            19:     older than 2.7.2.
        !            20:   - Optionally, the gtk library, available from ftp.gimp.org, and a pthreads
        !            21:     library.
        !            22: 
        !            23: For reference, this is my system configuration:
        !            24:   OS: Linux 2.0.33
        !            25:   CPU: AMD-K6-233
        !            26:   RAM: 32MB
        !            27:   X11: version 3.3.2
        !            28:   Compiler: egcs-1.0.1
        !            29:   Libraries: glibc-2.0.6 (includes libpthread), gtk-0.99.3
        !            30: If you have the same configuration, and it doesn't run, you're doing something
        !            31: wrong ;)
        !            32: 
        !            33: 
        !            34: Compilation
        !            35: ===========
        !            36: 
        !            37: To build UAE, first unpack it to an appropriate directory (e.g. /usr/src/uae
        !            38: on a Linux system). The simple way to proceed is to type "configure; make", 
        !            39: after that has completed you should have a working X11 version of UAE. Ignore
        !            40: warnings if you get them.
        !            41: 
        !            42: However, you should probably have a look at some of the compile-time options
        !            43: found in "config.h" before you do this. There are some things you can change
        !            44: there so that the resulting executable will perform better on your machine.
        !            45: Each of the options in that file has a description. You can edit config.h to
        !            46: suit your needs; and then do "configure; make" afterwards.
        !            47: 
        !            48: When running configure, there are a few options that you can use to
        !            49: influence configure's decision as to what kind of display should be used.
        !            50: The following displays are available:
        !            51:   - Standard X11, in a window. This is the default.
        !            52:   - X11/DGA. This runs full-screen and is somewhat faster than the normal X11
        !            53:     code. You need a recent (>= version 3.2) XFree86 X server.
        !            54:   - SVGAlib. This is only available on Linux systems. It is the default if X11
        !            55:     is not found by configure.
        !            56:   - ncurses character output. This is the last resort.
        !            57: 
        !            58: Type "configure --help" to get a list of options that configure understands.
        !            59: The following are likely to be useful:
        !            60:   --without-x        : Don't use X11 as target.
        !            61:   --with-svgalib     : Build a version that uses SVGAlib (Linux only)
        !            62:   --with-ggi         : Build a version that uses GGI (Linux only)
        !            63:   --with-asciiart    : Build a version that uses ASCII "graphics"
        !            64:   --enable-sound     : If a sound system is found that UAE knows about, sound
        !            65:                        emulation will be compiled in.
        !            66:   --enable-profiling : Build a much slower version of the emulator (if you 
        !            67:                        don't know what it's for, you don't want it)
        !            68:   --enable-dga       : If your X server supports the DGA extension, use it
        !            69:   --enable-vidmode   : If your X server supports the VidMode extension, use
        !            70:                        it. This enables the emulator to switch to low
        !            71:                        resolutions such as 320x256 or 400x300 if you have
        !            72:                       defined ModeLines for them.
        !            73:   --enable-ui        : Build a user interface if possible (enabled by default)
        !            74:   --enable-threads   : Build UAE multithreaded on systems that support it.
        !            75:                        Note that there is very little thread support in UAE at
        !            76:                       the moment.
        !            77:   --enable-penguins  : Enable some additional threads which only make sense on
        !            78:                        SMP (symmetric multi penguin) machines. If you have a
        !            79:                       single-CPU machine, you don't want to use this option.
        !            80: Note that there is a corresponding "--disable-xxx" for each "--enable-xxx"
        !            81: option, and a "--without-yyy" for each "--with-yyy".
        !            82: 
        !            83: Both the SVGAlib and the DGA version run full-screen, i.e. you can't run other
        !            84: programs at the same time very well. You also need to be root to run either of
        !            85: these two versions.
        !            86: Making UAE suid root is _not_ a particularly good idea if you care about the
        !            87: security of your system.
        !            88: 
        !            89: If you are not sure whether you have an SMP machine, you don't have one.
        !            90: 
        !            91: 
        !            92: Run-time options
        !            93: ================
        !            94: 
        !            95: The X11 version (without DGA) of UAE understands these special command-line
        !            96: options:
        !            97:   -L     : Use "low-bandwidth" mode, which can reduce the amount of data
        !            98:            transferred between UAE and the X server. That's particularly an
        !            99:           advantage when these are running on two different machines in a
        !           100:           network.
        !           101:   -T     : Use the MIT-SHM extension. This may not be available on all
        !           102:            machines, and it will not work if UAE and the X server are not
        !           103:           running on the same machine.
        !           104:           In all other configurations, turning on this option will give you
        !           105:           a huge speed improvement.
        !           106:   -x     : Turn off the X11 mouse cursor for the UAE window. Personally, I
        !           107:            find that seeing the X cursor helps, but that's a matter of taste.
        !           108: 
        !           109: The SVGAlib version understands the following command-line option:
        !           110:   -x     : Turn off linear frame buffer support, even if it is available.
        !           111:            Unless linear mode doesn't work properly, you don't want to disable
        !           112:           it, because UAE is much faster if it can draw into a linear
        !           113:           frame buffer.
        !           114: 
        !           115: 
        !           116: Keyboard mappings
        !           117: =================
        !           118: 
        !           119: You can exit the SVGAlib (and the DGA) version by pressing the F12 key.
        !           120: PgUp/PgDn emulate the right/left Amiga keys. In the SVGAlib version, F11 will
        !           121: bring you back to the user interface screen so you can change disks during the
        !           122: emulation.
        !           123: 
        !           124: The X11 version needs some help to figure out how to map keys: You'll have to
        !           125: tell it the keyboard language with the "-l" commandline option. Several
        !           126: languages ("us", "se", "de", "fr", "es", "it") are supported. If you have
        !           127: a different keyboard, patches to make UAE work with it are appreciated.
        !           128: 
        !           129: 
        !           130: Mouse and joystick emulation
        !           131: ============================
        !           132: 
        !           133: The X11 (non-DGA) version has one problem: There are two mouse pointers, the
        !           134: X11 mouse pointer and the mouse pointer in the emulator window. You can work
        !           135: that way, but you get confused quickly.
        !           136: The solution in previous (0.6.8 and before) versions of UAE was a small piece
        !           137: of code that looked at the position of sprite 0 on the screen and tried to
        !           138: generate mouse movements in an emulated hardware port. That worked reasonably
        !           139: well, but had several problems.
        !           140: The new solution is to use a small Amiga program which is called "mousehack".
        !           141: You will find this in the "amiga" subdirectory. Put it into the directory that
        !           142: you use for harddisk emulation so that you can run it from the emulator. Then
        !           143: put the command "run >NIL: mousehack" at the top of your startup-sequence. UAE
        !           144: will detect when this program is running and use the improved mouse pointer
        !           145: positioning method. (Don't run this program on old versions of UAE)
        !           146: If the program is not running, you get the old behaviour - almost. By default,
        !           147: the emulator will no longer try to keep Amiga and X mouse pointers at the same
        !           148: position, because that led to problems in the past. You can toggle this
        !           149: behaviour with F12.
        !           150: (If you just added "run mousehack" to your startup-sequence, that would have
        !           151: the effect that the initial CLI window would be impossible to close.
        !           152: Unfortunately, redirecting output to >NIL: disables all error messages that
        !           153: mousehack can give you - so if it does not work, try running it by hand
        !           154: without the >NIL: redirection.)
        !           155: 
        !           156: If you find a program in which the mouse pointer does not move at all if you
        !           157: use the X11 version, start that program with mousehack _not_ running
        !           158: (Magnetic Scrolls adventures are known to need this, for example).
        !           159: 
        !           160: The SVGAlib and DGA versions are not affected by any of this (and pressing F12
        !           161: exits those versions).
        !           162: 
        !           163: If you use Linux and have the joystick driver kernel module, "configure"
        !           164: should automatically enable support for it. UAE calibrates the joystick
        !           165: automatically. Turn it a few times on startup to get the calibration done. 
        !           166: 
        !           167: 
        !           168: Harddisk emulation
        !           169: ==================
        !           170: 
        !           171: Please read the appropriate sections in the file "README" on how to use the
        !           172: filesystem emulation. There are a few Unix-specific things about it, though.
        !           173: 
        !           174: If you want to execute files located on a native filesystem, they need to have
        !           175: the x permission bit set. That can be done in Unix by "chmod +x file" or in
        !           176: AmigaDOS with "protect file rwed".
        !           177: You should set aside a whole directory tree for AmigaOS files, and not use it
        !           178: from Unix in any way if you can avoid it. Changing permissions/owners,
        !           179: creating symbolic links and doing other stuff that AmigaOS does not know about
        !           180: is a good way to confuse the emulator and the emulated software. E.g. it's
        !           181: possible to have a symlink pointing at a mounted CD-ROM. The emulator would
        !           182: see that as a directory inside which it gets "read only filesystem" errors,
        !           183: and wouldn't know what to do about it. Avoid this sort of thing. It's best to
        !           184: start with an empty harddisk emulation directory and install software there
        !           185: only from within the emulation.
        !           186: The following setup can also lead to problems:
        !           187:   -m dh0:/foo -m dh1:/foo/bar
        !           188: Please take care that the filesystems you mount don't overlap each other
        !           189: (another great reason not to use symbolic links within them).
        !           190: 
        !           191: 
        !           192: Printing
        !           193: ========
        !           194: 
        !           195: If you give UAE the "-p lpr" option, output for the parallel port will be
        !           196: piped to lpr, which will in turn print it. You should use the Postscript
        !           197: printer driver on the Amiga side (since UAE relies on the ^D character at
        !           198: the end of the Postscript output).
        !           199: Note that I never tried this myself, so you're on your own.
        !           200: 
        !           201: 
        !           202: Transferring things over the serial port
        !           203: ========================================
        !           204: 
        !           205: There's an easy way to use a null-modem cable without terminal software if
        !           206: you use Linux (and probably other Unices). You can do
        !           207: 
        !           208:   transdisk >SER: <options>
        !           209: 
        !           210: on the Amiga to copy the data directly to the serial port. Before that, do
        !           211: 
        !           212:   cat /dev/ttyS1 >df0.adf
        !           213:   
        !           214: on your Linux box to receive the data (it may be ttyS0 on your system, or
        !           215: another number, depending on which serial port you are using). When the Amiga
        !           216: is done transferring, hit ^C on the PC to interrupt the cat program. To make
        !           217: this work, you need to use the same settings for the serial port on both
        !           218: sides. This is done with the Preferences program on the Amiga (this is split
        !           219: into several programs from Kickstart 2.0 upwards, you'll find a program called
        !           220: "serial" in the Prefs directory of your Workbench disk). On the Linux side,
        !           221: use the stty program. "man stty" will give you the manpage describing how to
        !           222: use it.
        !           223: To be on the safe side, set the speed to a low value (2400 baud). Turn off
        !           224: Xon/Xoff, but enable RTS/CTS.
        !           225: I use the following command myself:
        !           226: 
        !           227:   stty 19200 parenb -cstopb cread clocal crtscts -istrip -inlcr -icrnl -opost
        !           228:     -onlcr -parodd -isig -icanon -iexten raw cs8 </dev/ttyS1
        !           229: 
        !           230: which is probably overkill, but you never know :)
        !           231: This maps to 19200 baud, 8 bits, even parity, one stop bit, which you have to
        !           232: set in the Amiga preferences.
        !           233: 
        !           234: 
        !           235: Using the Linux AFFS filesystem
        !           236: ===============================
        !           237: 
        !           238: If you use Linux with a kernel version >= 2.0.7 and version 2.5k of the mount
        !           239: program, you can do
        !           240:    mount df0.adf /mnt -t affs -o loop
        !           241: to mount disk image df0.adf at the mount point /mnt. This is much more
        !           242: convenient than using the "readdisk" program.
        !           243: 
        !           244: You'll need to enable support for the Amiga filesystem and the loop device
        !           245: when configuring and compiling the kernel (say yes to the "Ask about
        !           246: experimental drivers" question at the start).

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.