***********************************************************************
Xmame/xmess frequently asked questions and installation guide
***********************************************************************

Created:          May 20, 1997 by Juan Antonio Marmnez
                  (jantonio@dit.upm.es)
Last update:      August 10, 1999 by Hans de Goede
                  (hans@highrise.nl)

NOTE: The most recent copy of this guide can be found on the xmame 
project homepage at http://x.mame.net

Contents
********
1. Xmame/xmess frequently asked questions
2. Compiling, setting up and starting xmame/xmess
3. Pending jobs
4. Mail
5. Compile notes for specific operating systems
6. Legal questions and copyrights
7. Who is who in the mame & mess projects?

***********************************************************************
1. Xmame frequently asked questions
***********************************************************************

What is mame?

      Mame is a arcade machine emulator. Started in 1997, by Nicola 
      Salmoria, mame started out as a series of emulators for 
      individual games. This series of emulators was combined into a 
      multiple game emulator format. This is the current form of 
      mame, no longer a one many show, there are over 100 
      contributors to the project.

      Mame was created by Nicola Salmoria.


What is mess?

      Mess is just like mame a virtual machine emulator, only it doesn't
      emulate arcade machines but other computers and consoles.


What is xmame/xmess?

      Xmame/xmess are the Unix/X11 ports of the mame and mess projects.
      It makes mame/mess available on *ix machines using the X11R6 X-Window
      system ( and SVGAlib/ggi/XF86-DGA too ).

      Mame was orginally ported by Allard Van Der Bas, Dick the 
      Ridder and Juan Antonio Marmnez.

      Xmame/xmess is currently maintained by Hans de Goede.


What are the differences between mame/mess and xmame/xmess?

      None significant.

      Xmame/xmess is based on the mame/mess source code.
      Due to technical reasons beyond the scope of this document, the
      mame/mess source may not compile under Unix. That why the xmame/xmess
      project exists. Each time mame/mess is updated, the code is tested 
      (and patched if needed) under Unix. This way xmame/xmess releases are
      always the same as their mame counterparts.

      There are no plans for the independent development of xmame/xmess.


What hardware and operating systems are supported?

      Xmame runs on both little endian and big endian CPU's, using aligned
      integer access if needed and is compatible with 64 bit CPU's.
      The current list of supported CPU's in the makefile is:
      -i386 + gnu-asm
      -i386 no asm
      -alpha
      -m68k
      -generic risc (powerpc, sparc, hppa, ibm)
      -generic risc, lsb-first (RISC (ultrix machines))
      -mips (generic risc + SGI compiler bug workarounds)
      
      Adding support for another cpu (if nescesarry) should be trivial.
      

      The following Unix platform's are specificly supported:
      -Linux 
      -FreeBSD
      -NetBSD
      -Solaris
      -OpenStep (currently broken)
      -Mac OS X (currently broken)
      -IRIX with sound using the dmedia package or the new al package
       (sound currently broken)
      -AIX (sound currently broken)
      -generic unix, no sound

      The generic unix entry should work for any reasonable standard Unix
      variant, but lacks sound since there is no single Unix sound standard.
      
      On all platforms zlib is now needed since the core uses it, if you
      don't have zlib use the included one by uncommenting the appropriate
      3 lines in makefile.unix.

      
      The following display methods are supported, X11 is the only one which
      works on all platforms, except for OpenStep / Mac OS X which only work
      with Openstep bitmaps:
      -X11 (X-windows)
      -svgalib
      -GGI (Generic Graphics Interface)
      -OpenGL using X11 for input
      -glide using X11 for input (3DFX)
      -glide using svgalib for input (3DFX)
      -OpenStep bitmaps (currently broken)
      -SDL (Simple Direct Medialayer)


      The following arch/os/display combinations are activly supported,
      please mail the maintainer of the arch/os/display combination for
      compilation and other arch/os/display specific problems. Mail
      hans@highrise.nl for generic (e.g. x11) problems.

      arch/os/display           maintainer

      i386/linux/x11 (+DGA)     Hans <hans@highrise.nl>
      i386/linux/svgalib        Hans <hans@highrise.nl>
      i386/linux/xgl            Hans <hans@highrise.nl>
      i386/linux/xfx            Hans <hans@highrise.nl>
      i386/linux/svgafx         Hans <hans@highrise.nl>
      i386/linux/ggi            Christian <cpg@aladdin.de>
      alpha/linux/x11           Christian <cpg@aladdin.de>
      alpha/digital unix/x11 *  Leandro <ldardini@usl4.toscana.it>
      powerpc/linux/x11         Andreas <sid@skater.htu.tuwien.ac.at>
      powerpc/linux/svgalib     Andreas <sid@skater.htu.tuwien.ac.at>
      i386/netbsd/x11           Dave <dave@dtsp.co.nz>
      alpha/netbsd/x11          Christian <cpg@aladdin.de>
      Sparc/Solaris/x11         Mathis <rosenhau@mailserv.sm.go.dlr.de>
      i386/Unixware7/x11     *  Richard <xmame@frogface.ddns.org>
      i386/openstep             Pete French <pete@toybox.twisted.org.uk>
      Sparc/SunOs            *  Saga <jolletx@cybercable.fr>
      
      * These are supported using the generic unix entry of the makefile,
        and thus lack sound.
        
      We are always looking for people willing to test and answer
      questions about xmame on a new arch/os/display. This takes very little
      work and could help other people tremendously. If you're interested
      mail hans@highrise.nl .


My system is supported but xmame/xmess give me errors and fails. Why?

      Xmame/xmess should run on 8bpp Pseudo Color displays and on 16, 24 and
      32bpp True Color displays. If your X-Server does not support any 
      of these display types, xmame/xmess will not run.

      You can verify your X-Server support by starting your X-Server 
      and running the xdpyinfo program. See the xdpyinfo manual page 
      for more information.


How do I enable XinputExtensions X11 based joystick in Xfree86?

      You need to edit XF86Config to enable the XInput section. See the 
      manual page for XF86Config.


How do I read a manual page?

      Easy. If you want to read the manual page for XF86Config, type:
      man XF86Config


Why doesn't my joystick handle diagonal movement correctly on my Intel 
x86 system?

      Xmame/xmess uses autocalibrating but you could try to use specific
      programs to calibrate it ( jscal that comes with joystick 
      module works fine.... )


What is the role of the xmamerc/xmessrc file?

      A normal xmame/xmess invocation looks like:

            xmame pacman -sound -nojoy -frameskip 2 -heightscale 3 \
            -widthscale 2

      Most of the time, you will want to use the same configuration for 
      each game. Xmame/xmess will read this file for default values for the 
      parameters that you can set. This way the only parameters you 
      need to express on the command line are the ones you want to 
      override.
      
      Another reason for xmamerc/xmessrc is keyboard remapping. Some Unix 
      keyboards are very different than their PC counterparts. To 
      compensate for the changes, xmame/xmess allows you to remap keys that 
      are not available on Unix keyboards to keys that are available.


What is the syntax of the xmamerc/xmessrc file.

      The syntax is quite simple:
      "keyword value"
      
      See doc/xmamerc.dist for most keywords. Allmost all commandline options
      can be used as keywords (without the -), use value 0 or 1 for commandline
      options which have a negating (-no<option>) counterpart.
      As usual lines begining with "#" are comments.
      
      You can also generate a configfile with all the current settings to
      use as a template by typing:
      "xmame -showconfig > ~/.xmame/xmamerc"


Where do roms, images, samples, highscores, configfiles, etc go?
	
    -Roms/Samples
	
      Xmame/xmess uses a ":" seperated rompath to find out which dirs
      to search for roms/samples.
      The default rompath is XMAMEROOT as defined in makefile.unix during
      compile.
      This is overwritten by any rompath in xmamerc/xmessrc.
      Which can be overwritten again with the -rompath commandline option.
       
      Xmame/xmess searches every dir in this path for roms/samples in the
      following way:
      <dir>/gamename.zip             (containing filename.ext)
      <dir>/gamename/filename.ext
      <dir>/gamename/filename.ext.gz (containing filename.ext)
      <dir>/gamename/filename.zip    (containing filename.ext)
      
      So letts say that we are searching for rom0001.1 which is part of
      pacman then xmame/xmess would search every dir in your rompath for:
      <dir>/pacman.zip               (containing rom0001.1)
      <dir>/pacman/rom0001.1
      <dir>/pacman/rom0001.1.gz      (containing rom0001.1)
      <dir>/pacman/rom0001.zip       (containing rom0001.1)

      Note: If your neogeo games can't find neogeo.rom put it in a dir
      called neogeo somewhere in your rompath, or put it in neogeo.zip
      somewhere in your rompath.

    -Read/write Diskette Images
      This section only applies to xmess emulations which support read/write
      diskette images and thus try to open the image read/write.

      Xmess first searches for read/write images with the name specified on
      the commandline:
      <path>/image.ext

      Where path is the path specified with the image on the commandline,
      this way absoulte and relative filenames can be used directly on
      the commandline for an image which is not in the rompath.

      Then xmess searches every dir in the rompath for roms/samples in the
      following way:
      <dir>/image.ext

      Note that (g)zipped images are not supported for r/w images.

    -Rom Cartridges/Read Only Diskette Images
      Xmess begins by searching for cartdriges/disks from the current dir in
      the following way:

      <path>/image.ext
      <path>/image.ext.gz            (containing image.ext)
      <path>/image.zip               (containing image.ext)

      Where path is the path specified with the image on the commandline,
      this way absoulte and relative filenames can be used directly on
      the commandline for an image which is not in the rompath.

      Then xmess searches every dir in the rompath for carts/images in the
      following way:
      <dir>/image.ext
      <dir>/image.ext.gz             (containing image.ext)
      <dir>/image.zip                (containing image.ext)

      Finally xmess searches the rompath as desribed above using the systemtype
      for gamename.
      
      So letts say we want to play mario.nes on the nes emulation of xmess.
      We would then type: "xmess nes mario.nes". Xmess then begins by
      searching the current dir for:

      mario.nes
      mario.nes.gz                   (containing mario.nes)
      mario.zip                      (containing mario.nes)

      After that xmess searches each dir in your rompath for:
      <dir>/mario.nes
      <dir>/mario.nes.gz             (containing mario.nes)
      <dir>/mario.zip                (containing mario.nes)

      And finally xmess searches each dir in your rompath for:
      <dir>/nes.zip                  (containing mario.nes)
      <dir>/nes/mario.nes
      <dir>/nes/mario.nes.gz         (containing mario.nes)
      <dir>/nes/mario.zip            (containing mario.nes)

      Since xmess first searches for cartridges/disks from the current dir
      you can also specify cartridges/disks not in your rompath for example:
      "xmess nes ../mario.nes"

      Xmess then searches for:
      ../mario.nes
      ../mario.nes.gz                (containing mario.nes)
      ../mario.zip                   (containing mario.nes)

      And will also search the rompath as described above with ../mario.nes
      as image name but this is not that usefull.

    - Artwork
      Xmame/xmess searches every dir in the rompath for artwork in the
      following way:
      <dir>/artwork.png
      <dir>/artwork.png.gz           (containing artwork.png)
      <dir>/artwork.zip              (containing artwork.png)

      Then xmame/xmess searches the rompath as in roms/samples.
      
      So letts say we want to play foo which uses bar.png.
      Xmame/xmess then begins searching each dir in your rompath for:
      <dir>/bar.png
      <dir>/bar.png.gz               (containing bar.png)
      <dir>/bar.zip                  (containing bar.png)

      And then xmame/xmess searches each dir in your rompath for:
      <dir>/foo.zip                  (containing bar.png)
      <dir>/foo/bar.png
      <dir>/foo/bar.png.gz           (containing bar.png)
      <dir>/foo/bar.zip              (containing bar.png)

    - Xmame configuration
      Xmame looks for the following configuration files and parses each one
      found, later parsed files can overwrite options in previously parsed
      files:
      XMAMEROOT/xmamerc
      XMAMEROOT/xmame-DISPLAY_METHODrc
      ${HOME}/.xmame/xmamerc
      ${HOME}/.xmame/xmame-DISPLAY_METHODrc
      ${HOME}/.xmame/rc/<gamename>rc
      -XMAMEROOT is defined during compile time, see makefile.unix.
      -DISPLAY_METHOD is the DISPLAY_METHOD for which xmame was compiled,
       this can be one of: x11, svgalib, ggi, xgl, xfx, svgafx, openstep,
       SDL .
      -For xmess of course replace xmame by xmess ;)
	  
    - Game configuration
      Game configuration files are kept on a per user base in:
      ${HOME}/.xmame/cfg/<game>.cfg resp ${HOME}/.xmess/cfg/<game>.cfg

    - Game state
      Game state files are kept on a per user base in:
      ${HOME}/.xmame/sta/<game>.sta resp ${HOME}/.xmess/sta/<game>.sta
      
    - NVram
      NVram files are kept on a per user base in:
      ${HOME}/.xmame/nvram/<game>.nv resp ${HOME}/.xmess/nvram/<game>.nv

    - Mem cards
      Mem cards files are kept on a per user base in:
      ${HOME}/.xmame/mem/<filename>.mem resp ${HOME}/.xmess/mem/<filename>.mem
      Where <filename> is given by the game-driver.

    - Screenshots
      Screenshots which can be made pry pressing F12 are saved as png files in
      the directory from where xmame is started (cwd).
      This can be overidden by the screenshotdir entry in xmamerc/xmessrc.
      Which can again be overidden by the -screenshotdir cmdline-option.
      They are saved as:
      <screenshotdir>/<game>xxxx.png
      Where xxxx is a number.
      
    - Highscore's
      Hi-scores are stored in XMAMEROOT as defined in makefile.unix when
      building. This can be overidden by the spooldir entry in xmamerc/xmessrc.
      Which can again be overidden by the -spooldir cmdline-option.

      So only give a drwxrwsr-x root games <spooldir>
      permission and setgid xmame/xmess to "games" to get it to work.
      Note this doesn't work with suid root versions (svgalib & XF86-DGA),
      suggestions welcome.
      For know use ${HOME}/.xmame or ${HOME}/.xmess as spooldir in 
      xmamerc/xmessrc for suid root versions.

    - cheat.dat
      If you want to use cheats mame needs to load cheat.dat to get cheat
      info. 
      The default is XMAMEROOT/cheat.dat . XMAMEROOT is set during
      compile-time, see makefile.unix. This can be overriden by the cheatfile
      entry in xmamerc if present, which can again be overiden by the
      cmdline-option -cheatfile.

    - history.dat
      If you want to display some nice background info on games mame needs to
      load history.dat.
      The default is XMAMEROOT/history.dat . XMAMEROOT is set during
      compile-time, see makefile.unix. This can be overriden by the historyfile
      entry in xmamerc if present, which can again be overiden by the
      cmdline-option -historyfile.

    - Input logs
      Input logs are saved / read under the name specified after the
      -record / -playback option, this name is relative to the current path.

    - It still can't find file's / store highscore's
      Type "xmame/xmess -showconfig|more" and check that the rompath and
      spooldir showed are correct and readable/writable. Otherwise recheck
      xmamerc/xmessrc. Remember that xmess also searches the
      current dir.


How do I start xmess/xmame ?

      To start xmame type:
        xmame [options] <gamename> [more options]

      For xmess type:
        xmess [options] <systemname> [more options] <disk/romimage(s)> [more options]

      All options are optional ;)
      Xmame/xmess supports most dos commandline-options (see readme.mame /
      readme.mess) as wel as a few of its own, type xmame -help|more for a
      complete list.

      With xmess some systems don't require a disk/romimage, but most do.


Why doesn't a game have sound?

      - First check that sound is working in other applications.
      - Check that sound is supported for the game that has no sound, 
        not all games have sound:

        For xmame take a look at gamelist.mame, is the sound for the game
        emulated?
        
        For xmess take a look at readme.mess is the sound for the system
        emulated?

      - Check the operating system support chart in the earlier part of 
        this file, does xmame/xmess support sound on your system?


My sound seems lagged? / My sound Clicks? /
What does -bufsize do?

      With the -bufsize commandline option / the bufsize configfile keyword
      you can specify the number of frames of audio to buffer. The default
      is 2 frames.

      This value should be ok for everyone, but if you still have problems
      read on.
      
      If the buffersize is to small, this causes the buffer to get empty
      between frames which in turn causes clicks/pauses in the sound. If this
      is the case highering the -bufsize value to for example 2.5 should help.
      
      If however you make the buffersize to large, then so much audio
      becomes buffered, that the sound could become lagged. E.g. you would
      here the coin drop sound 0.5 seconds after pressing the insert coin
      key. In this case lower the bufsize to for example 1.5 .
      
      Please lett me know if you need to change this setting, since I'm
      planning on removing it in a future release.

      
Why doesn't a game work?

      - Do you have the right roms or did you get checksum failures?
      Xmame version 0.34 and higher require PROM files that were not included
      in ROM images released before version 0.34. See the question on PROMs 
      below for more information.
      - For xmame check the file gamelist.mame to see if the game is playable.
      Just because a game is included doesn't mean it is working yet.
      - For xmess take a look at readme.mess maybe the system isn't emulated
      all that good yet.
      - Some games require sound support. If you don't have sound 
      support under your Unix or sound isn't supported by xmame/xmess under 
      your Unix, try the -fakesound command line parameter.


What are PROMs?

      PROMs contain game specific information that used to be built in 
      to mame in versions prior to 0.34. This information has been 
      extracted and is now included with new versions of ROM files for 
      games that require this information.

      If you want to use your current ROM files, you 
      can obtain just the PROM images in one large file at:
      http://mame.retrogames.com


Why is xmame/xmess slow?

      xmame/xmess is a compiled C program that is emulating hardware. 
      Software emulation of hardware always pays a speed penalty. Here 
      are some things you can do:

      - Try using the -frameskip command line parameter.
      - Try pressing F8 while running xmame/xmess to alter the frame rate.
      - Try disabling the throttle with the -nothrottle command line 
        parameter or by pressing F10 while running xmame/xmess.
      - While running xmame/xmess, press F11 to check the speed of xmame/xmess. 
        If you never get a display of 100%, you need a faster computer.

      You can also try recompiling xmame/xmess with more optimal settings,
      the following suggestions may not work or may not be appropriate
      on some machines and in some installations.  However, in cases
      where they do work, there can be a noticeable increase in overall
      performance of xmame/xmess.
      
      These "enhancements" simply require editing the makefile.unix that
      is distributed with xMame, and then recompiling the source.  If you
      are compiling the source for the second time you will need to do
      
      make -f makefile.unix clean
      make -f makefile.unix
      make -f makefile.unix install
      
      after editing the makefile.unix to show your new settings.
      
      SPEEDUP # 1 - Inline compiling
      ------------------------------
      Try enabling inline compiling by commenting and uncommenting the
      following lines:
      
      # IL    = '-DINLINE=static inline'
      IL     = -DINLINE=static
      
      SPEEDUP # 2 - Direct Graphics Access
      ------------------------------------
      For a big boost try enabling DGA by uncommenting these two
      lines:
      DGA     = -DUSE_DGA
      DGALIBS = -lXxf86dga -lXxf86vm
      
      Then start xmame as root, and press left-alt + home to switch to
      dga mode, that should be a lot faster, and doesn't need / use xsync ;)
      
      To get back to a window without exiting press left-alt + insert.
      
      The benefit of DGA is that it is Direct Graphics Access and as such
      writes directly to the framebuffer (Think directx versus GDI under
      windows). So it should be a tad faster, unless you've got a really
      really well accelerated X-server, which could be just as fast. Try
      pressing F11 to see the actual framerate, although it might be hardly
      noticable (visually atleast), it should give you some speed increase.
      
      Besides that it automaticly switches to the right mode and removes any
      window manager stuff, but that can be done without DGA too (I might at
      such a feature later, sine it allows easy fullscreen without running as
      root).
      
      And adding a 320x240 mode will most definatly get you a very nice
      fullscreen display at scale = 1 ;)
      
      Also see contrib/tools/modelines for a set of crazy modes made
      especially for xmame in DGA mode, they should work on any reasonable
      multisync, but don't use them on an old fixed-frequency (well if you
      can't resist trying I won't pay for a new one)
      
      SPEEDUP # 3 - NASM
      ------------------
      You can also try installing nasm and compiling the asm core, that helps
      a bit too.


Why do I get gz_open symbol not found while compiling?

      Xmame/xmess versions newer then 0.35 use zlib for some compression
      routines. Unfortunatly a lott of Linux distributions have an old
      version of zlib installed as /usr/X11R6/lib/libz.a
      And the new version installed as /usr/lib/libz.a. If this is the case
      its harmless to remove /usr/X11R6/lib/libz.a. If your not sure wether
      this is the case just move /usr/X11R6/lib/libz.a to another location.

      Removing or just moving /usr/X11R6/lib/libz.a should fix this problem.

      Also see: Why do I get zlib.h not found?


Why do I get zlib.h not found?

      Xmame/xmess versions newer then 0.35 use zlib for some compression
      routines.

      Zlib is standard on most Unix versions, for those who don't ship with
      zlib or ship with a too old version xmame/xmess now comes with a stripped
      down version of zlib. Uncomment the appropriate 3 lines in makefile.unix
      to use this.


What are the command line parameters for xmame/xmess?

      To see a list of available parameters, type:
      
      /usr/games/xmame -help | more

      Xmame/xmess supports most of the command line parameters as the DOS 
      version as well a some of its own.

      See the file readme.mame / readme.mess for more information about the
      command line parameters.


What keys does xmame/xmess use?

      Xmame/xmess uses the same key-bindings as the DOS version of mame:
      The following keys work in all emulators:
      `  or ~      Enter On screen display to change volume, brightness etc.          
      Tab          Enter configuration menu. Press Tab or Esc to get back to
                   the emulation.
      P            Pause
      F3           Reset
      F4           Show the game graphics. Use cursor keys to change set/color,
                   F4 or Esc to return to the emulation.
      F8           Reduce frame skip
      F9           Increase frameskip
      F10          Toggle speed throttling
      F10 + shift  Toggle idle sleeping
      F11          Toggle speed display
      F11 + shift  Toggle profiler display
      F12          Save a screen snapshot.
      ESC          Exit emulator

      Under X11 xmame can switch to and from different modes runtime:
      Key combi:          Warps you to:
      left-alt + insert   Normal window
      left-alt + home     DGA fullscreen mode

      Under X11 in a window you can also grab the mouse to be able to play with
      the mouse, press left-alt + page-down to grab the mouse, press it again
      to release it.


Where can I get the latest version of xmame/xmess?

      The xmame/xmess Home Page always has the most up to date version. The
      address is: http://x.mame.net


Where can I send fixes, bug reports, suggestions, or money?  :-) 

      See section 4 of this document.


***********************************************************************
2. Compiling, Setting Up and Starting xmame/xmess
***********************************************************************

Note:
This section is not a Unix tutorial. You need to know some basic 
Unix commands to compile and install xmame/xmess.

Requirements:
-GNU make is MANDATORY in ALL Systems, even if you use a different 
 compiler.
-On all platforms zlib is now needed since the core uses it.
-You are encouraged to use GNU development environment gcc, gmake gnu-
 ar. Lots of problems found due to the very permissive syntax in gcc, so
 if you use a strictly ANSI C compiler, you'll get lots of warnings, and
 if the version of xmame/xmess is not fully debugged, compilation errors.
-Xmame compilation breaks when using egcs-1.1.x or gcc-2.95, use
 -fno-strict-aliasing to fix it. gcc-2.95.1 does work with -fstrict-aliasing,
 and gives a nice speed increase.


Follow these steps to compile xmame/xmess:

1.  See section 5 for platform specific compiling information.
2.  Download the xmame/xmess source files archive.
3.  Move the xmame/xmess source files archive to a suitable work directory.     
    When you extract the archive, sub directories will be created under the 
    work directory.
4.  Rename the source files archive so its extension is .gz so gzip 
    doesn't complain. For example, change xmame-0.34b1.1.tgz to xmame-
    0.34b1.1.tar.gz
5.  Use gzip -d to uncompress the archive. For example, type:
      gzip -d xmame-0.34b1.1.tar.gz
6.  Extract the files with tar. For example, type:
      tar xvf xmame-0.34b1.1.tar
7.  After extracting the archive, change to the subdirectory created by 
    the extraction process. For example, after extracting the xmame-
    0.34b1.1.tar archive, a directory named xmame-0.34b1.1 is created. 
    Change to it. This directory is the top of the source tree.
8.  Edit the file makefile.unix and change the settings according to 
    your system. The default makefile.unix is pre configured to run under
    X11/Linux. Be careful editing this file.
    If you want to build for multiple display targets you can repeat steps
    8 - 11 as many times as wanted, no need todo a make clean.
8a. If you intend to compile in X11 joystick support:
    Type the following to see the available Xdevice list:
       make -f makefile.unix xlistdev
      ./xlistdev
8b. Choose the desired device and re-edit makefile.unix, setting the 
    option JSNAME with the correct device.
9.  Compile xmame/xmess by typing:
      make -f makefile.unix
10. If the compile fails, report the problem to the author.
11. To install xmame/xmess, type:
      make -f makefile.unix install
*** YOU MAY NEED TO BE root TO PERFORM STEP 11 ***
12. In your home directory, create a subdirectory called .xmame.
13. From the top of the source tree, copy the file doc/xmamerc.dist to 
    the ${HOME}/.xmame/xmamerc directory. (For xmess do this for xmessrc)
14. If desired copy xmamerc.dist to the global xmamerc location
    as "xmamerc" (For mess copy xmamerc.dist to xmessrc).
    The global xmamerc location is defined in makefile.unix.
15. Edit ${HOME}/.xmame/xmamerc to match your preferences.
    (For xmess edit ${HOME}/.xmess/xmessrc)
16. Be sure that DISPLAY and PATH enviromment variables are 
    set correctly.
17. Make sure your ROM images are installed.
18. Start X-Windows. (Unless you compiled for a different display method
    in which case you skip this step.)
19. Start xmame/xmess. For example:
      /usr/games/xmame.x11 dkong

If you have problems compiling, installing and starting xmame/xmess...

      * If you get an error about gz_open and a bunch of other
	functions not found during linking read:
	"Why do I get gz_open symbol not found while compiling?" in section 1.
      * Be sure that the rompath in your xmamerc/xmessrc is correct,
        see also:
        "What about directories, where should I put the ROM's and
        config files ?"
      * Check xmamerc/xmessrc: is it configured correctly?
      * Is the program in your PATH?
      * The svgalib/xf86_dga build of xmame/xmess requires setuid root.
        Are your permissions correct?
      * Check section 5 of this document for operating system specific
        notes. You may need to do something special for your operating 
        system.
      * Are you getting messages that you are missing files? Maybe you 
        are missing PROMs. See the question on PROM files in section 1 of 
        this document.
      * Check section 1.
      * See the file known.bugs for known problems.
      * Try asking the friendly folks at the newsgroup alt.game.mame to 
        see if anyone else has experienced the same problem as you.
      * Try mailing to the xmame mailinglist

If all else fails, send email to the current maintainer of the xmame/xmess 
project. See section 4 for email addresses. 


***********************************************************************
3. Pending Jobs
***********************************************************************

See doc/todo. If you think you can help with the todo list or you can make a
contribution that you feel is interesting, please send mail to the
xmame/xmess coordinator. See section 4 for mail information.


***********************************************************************
4. Mail
***********************************************************************

There is an official xmame/xmess mail List. All operations related to this 
list are performed via email to xmame-request@acm.csres.utexas.edu with a 
proper keyword in the body. Currently recognized commands are:

      subscribe      - subscribe to the list
      unsubscribe    - unsubscribe from the list

If you want to send a personal mail to the xmame/xmess coordinator, send to 
the address below. Everyone that contributes to xmame/xmess should subscribe 
to the xmame/xmess mail list.

      mailinglist:             xmame@acm.csres.utexas.edu
      xmame/xmess coordinator: hans@highrise.nl


***********************************************************************
5. Compile Notes for Specific Operating Systems
***********************************************************************

Linux i386
==========

      Linux i386 is the platform I (Hans) use, so xmame should compile without
      any hassles on Linux i386.
      
      Some bugs have been found and worked around when using gcc27x,
      please use egcs if available. If more gcc bugs popup egcs will be made
      mandatory, but I hope that won't be nescesarry.

      It has been reported that some SoundBlaster AWE32 cards do not 
      correctly manage get_freespace(). If so you'll get some audio_ioctl()
      calls failed messages in console, and if everything goes right a
      message that xmame/xmess is falling back to timer based audio. If this
      doesn't happen and sound isn't right try forcing timer based audio
      by starting xmame/xmess with -timer.
      
      Sb64/128pci cards (ensoniq 137x based cards) also do not correctly
      manage get_freespace(), unfortunatly this doesn't result in failed
      ioctl's instead they just ignore the calls. Xmame tries to autodetect
      this and to fall back to timer based audio. If this doesn't happen
      and sound isn't right try forcing timer based audio by starting
      xmame/xmess with -timer.

      Also, I've tested sound using the PC-Speaker driver module. It 
      works!! But needs -timer, again it should do this automagicly, but you
      know what todo if it doesn't.


      Distribution Specific Comments
      ------------------------------

      For S.u.S.E. distributions: Besides the gcc compiler and libc 
      libraries, which are both from the "d" series, other packages 
      need to be installed or the build will fail. If compiling for 
      svgalib, the svgalib package from series "d" installed. If 
      compiling for X-Windows, you must have xdevel package from series 
      "x" installed. These packages can be installed using the "yast" 
      utility included in the S.u.S.E. distribution. 

      Red Hat Linux is the operating system used by the author. xmame/xmess 
      should build correctly under Red Hat Linux.  :-)


Linux powerpc
=============

      Linux powerpc should work from now on, here's an email from:
      Andreas Varga <sid@skater.htu.tuwien.ac.at>, the linux/powerpc
      maintainer describing the nescesarry steps:

-------
Required changes to compile xmame 0.34b3.1 on Linux/PowerPC with SVGALIB
-------

makefile.unix:

- enable CFLAGS for linux/ppc
- enable DISPLAY_METHOD = svgalib
- enable ARCH = linux
- remove -lvgagl from LIBS.svgalib (only -lvga is required)

-------
Required changes to compile xmame 0.34b3.1 on Linux/PowerPC with X11
-------

makefile.unix:

- enable CFLAGS for linux/ppc
- enable DISPLAY_METHOD = x11
- enable ARCH = linux

--------------------------------------------------------------------------

Another thing... sound is not working, because sound drivers support is
currently under development in Linux/PPC kernels...there is an old driver
that is a hacked Soundblaster driver, and newer 2.1.1xx kernels have a
sound drivers based on Amiga DMA sound drivers... Once this issues are
settled there should be a full OSS-compatible driver... sound should work
then...

I can't speak about Joystick support... 

The original Linux/PPC target changes in makefile.unix were done by me,
but there are some other changes required to get it to compile...
Starting from October I will have some more time to work on this, and I'll
keep you updated...

Cheers,
Andreas


IRIX
====
      Use the generic unix arch for those machines that have no 
      sound support installed. ( xmame/xmess uses the dmedia package or
      the newer AL package on IRIX systems )

      Silicon Graphics provides several native compilers. xmame/xmess has 
      been compiled and tested with the normal cc. There were some problems
      with this when using -n32 for new style 32bit code. It does work
      when using -o32 for oldstyle 32 bit code. It should now also work
      with -n32 wich is much faster.

      The use of DCC is not recommended (anymore) since it's a c++ 
      compiler and thus won't even compile xmame/xmess out of the box due to
      uncasted malloc's. Changing all these malloc's would be crazy,
      esp since they are not only in the osd part, but also in the core
      which is not under our control. Besides that mame is normal
      c, so please compile it with a normal c compiler.

      Some problems have been reported using GNU linker. It's
      recommended that you use native one.


HPUX
====

      Use the generic unix arch. In HP-UX gcc and gnu-make is MANDATORY.


ULTRIX
======

      Use the generic unix arch.
      
      ( Notes reeived from Danny <dboxhoor@iso.vilspa.esa.es> )

      VERY IMPORTANT!!!
      The xmame/xmess CPU emulators access memory through pointers which are
      sometimes cast to illegal addresses - as far as the MIPS CPU is
      concerned. The Ultrix operating system is aware of that and fixes
      this "unaligned data access".

      Depending on your system setup, lots of warnings are generated
      for certain games. Fortunately these messages can be disabled by 
      executing the command "uac p 0" in the same shell where xmame/xmess 
      will be running.

      UPDATE: The new -DALIGN_INTS switch in the makefile fixes these
      unaligned accesses in the source which is probably a lot faster
      than hot fixing them in the kernel segfault handler.

      Use gnu make.

      Compile with the `c89' compiler. Though `gcc' has no problems 
      with compiling and optimizing xmame/xmess, the resulting `c89' 
      executable is faster on an empty machine (read: xmame can use all 
      cpu & memory without competing with other high priority 
      processes), so you can set `frameskip' to 1.

      When compiling with `c89 -O2' don't forget to also use `-Olimit 
      1000'. If 1000 is not enough, the compiler will tell you to 
      increase it.


SunOS & Solaris
===============

There are 2 relevant architecture options available in the makefile :
ARCH = generic : use this for old SunOs running on Sparcs, but a Sparc
                 running Solaris will usually handle this option too.
ARCH = solaris : this is the one you should use for Sparcs running
                 Solaris.

Currently sound is not supported under sunos.
The solaris arch does support audio.

If you are using Sun's OpenWindows implementation of X11, then make
sure that the X11INC and X11LIB variables in the X11 Options section
of the makefile are set properly. (There are already entries for the
standard OpenWin directory there that you can uncomment).
Of course, if you are compiling for X11 then you need to set these
variables properly, no matter what implementation of X11 you are
using!  :)

If you are using Sun's SunPro cc compiler, then the following
optimisation flags have been reported to be good :
   OPTFLAGS    = -fast -xO4 -native

Finally, there has been a case of the xmame compilation processes
breaking over the "ar" program. Most Solaris installations will
include a set of utilities that conform to the XPG4 standard, usually
in the "/usr/xpg4/bin" directory. The XPG4 version of "ar" should be
avoided like the plague. Ensure that the "/usr/ccs/bin" appears in
your path before the "/usr/xpg4/bin" directory and everything should
go smoothly.

PLEASE NOTE : there is currently not much support for SunOS/Solaris.
If you have any trouble, try to fix it yourself. If you succeed, send
a message to the mailing list detailing what you did. If you don't
succeed, send a message anyway and someone _may_ be able to help you.
Either way, this is the only way that problems with xmame on
SunOS/Solaris will get fixed.


Openstep
========

      Follow, the generic instructions for compiling xmame, but when
      editing the makefile do the following:
      -Do not use gcc, use the native CC gcc fails to link the special
       openstep libs properly.
      -Search for -lm and remove it and the -s on those lines, openstep not
       only doesn't need it but fails on it.


***********************************************************************
6. Legal issues and copyrights concerning mame/mess
***********************************************************************

The main issue involves ROM images. ROM images are protected under the
copyrights of their authors, and CANNOT be distributed in the same
package as xmame/xmess. Download any ROM images at your own risk and
responsibility.

xmame/xmess should be distributed under terms of the license in
doc/readme.mame

XInputExtensions based Joystick support. Source code is entirely pure 
hack work. No sample code, no info at all was found ( only library 
reference manual ) and is copyrighted by me (Juan Antonio Marmnez).
Use it under terms of GNU General Public License


**********************************************************************
7. Who is who in the mame/mess project?
**********************************************************************

Fathers of mame:              Nicola Salmoria     (General Mantainer)
                              Allard van der Bas
                              Mirko (Mix) Buffoni

Fathers of mess:              Brad Oliver 
                              Richard Bannister
                              Ben Bruscella       (current coordinator)

Original UNIX/X11 port:       Dick the Ridder, Juan Antonio Marmnez

Unix maintainer:              Hans de Goede

Lots of people helped us giving info, patches, ROM images, and improvements.
See credits.unix for some of the hero's who contributed to the unix port.
