QMamecat README
---------------

v0.44, 21-FEB-2003

Contents

1) What is QMamecat ?
2) How to obtain the latest version
3) Prerequisites and installing QMamecat
4) Preview images
5) Command line options
6) QMamecat settings
7) Catalog and ROM-status cache format
8) ROM status
9) Printing
10) Contacting the author(s)
11) Special notes for new versions of QMamecat
12) Bugs and restrictions
13) How to create diffs and install patches
14) License

1) What is QMamecat ?

   QMamecat stands for "Qt-based M.A.M.E. Catalog/Launcher" and this already
   says what it is :).

   It consists of these programs:

   - qmamecat		Qt based X-Mame launcher (main application)
   - qmsetup		Qt based setup wizard
   - qmmapkey-x11	Qt based X11 key-event mapper
   - catgen		simple catalog generator

   Note that QMamecat is available only for the UNIX-port of M.A.M.E. (aka
   X-Mame), so if you are a DOS/Win/Mac/whatever-MAME user, please use a
   different MAME launcher for one of those OSs. Have a look at the official
   MAME project homepage (http://www.mame.net/) which lists some of
   them.
   
2) How to obtain the latest version

   QMamecat has its own homepage where new versions are made available for
   download, but please note that the location may change at any point in the
   future. In this case we will post a message to the xmame mailing-list to
   inform you...

   The current URL is http://www.mameworld.net/mamecat/ (english) or
   http://www.mameworld.net/mamecat/german/ (german) !

3) Prerequisites and installing QMamecat

   Prerequisites:

   for qmamecat, qmsetup and qmmapkey-*:

   - Qt library (3.1.0 or above) - if you don't have it you can get it from
     Troll Tech (http://www.trolltech.com/ or ftp://ftp.trolltech.com/qt/source)

   - the env. variable QTDIR _MUST_ be setup correctly to compile & link
   
   for all:

   - C++ compiler/linker plus ar and ranlib utilities
   - GNU make
   - the environment variable HOME must be setup correctly to run QMamecat
   - xmame-0.34rc1.1 or above (better: xmame-0.60.1 or above)

   FreeBSD users might need to symbolically link /usr/X11R6/include/X11 to
   /usr/include/X11:

   ln -s /usr/X11R6/include/X11 /usr/include/X11

   Compilation and installation:

   Simply enter

   gmake

   in the top-level directory. If it shouldn't compile and link properly,
   cd into the presets directory, and type

   cp make.defaults make.`uname`

   (or cp make.defaults make.`uname`-`hostname` if you need host-local
   adjustments)

   and edit the newly created file to suite your needs. Go back to the top-
   level directory and try again.

   If you may want to recompile the man-page, add the correct path to groff to 
   the GROFF definition in the corresponding presets/make.`uname` file (or 
   make.defaults directly). But as a groff-compiled version of the man-page
   already exists in the doc directory, this should normally not be neccessary.

   After successful compile & link, enter (as root)

   gmake install

   and you should be fine. You should now be able to start QMamecat by entering

   qmamecat (see note below !).

   Other useful make targets are:

   gmake dist		creates two source tar distribution files in
			the parent directory:
			qmamecat-<version>.tar.[gz|bz2]

   gmake clean		cleans up the build tree recursively

   gmake shared		creates shared binaries (same as "gmake", but relinked
			with shared libraries)

   gmake bindist-shared	creates two dynamically linked (shared) binary
			tar distribution files in the parent directory:
			qmamecat-<version>-<uname>-<arch>-shared.tar.[gz|bz2]

   gmake static		creates static binaries (same as "gmake", but relinked
			with static libraries)

   gmake bindist-static	creates two statically linked binary tar
			distribution files in the parent directory:
			qmamecat-<version>-<uname>-<arch>-static.tar.[gz|bz2]

   gmake bindist	alias for "gmake bindist-shared"

   gmake fulldist	creates ALL distribution files in the parent directory
			(same as "gmake bindist-shared && gmake bindist-static
			&& gmake dist")

   Compiler & linker switches:

   gmake QT_MT=1	link against libqt-mt instead of libqt (default)

   gmake DEBUG=n	compile with debug symbols for gdb (n=1) or even
			additional logging (n=2) (DEBUG=2 should be used with
			caution !)

   gmake ARCH=<arch>	define ARCH variable (disables auto-determination via
			ARCH=`uname`) - for developers only !

   NOTE: Before you start, we recommend you get xmame working correctly first !
   It will basically work, but as the catalog will not be correctly created
   and the ROM-status will not be determined, the result won't be very useful. 
   If you still decide to use QMamecat BEFORE xmame is correctly installed,
   use the "-r" option on the next start of QMamecat (after xmame IS working) !

   At the first start of QMamecat a setup wizard - qmsetup - will be launched 
   and you will be asked for the path to xmame; please enter (or browse) the 
   FULLY QUALIFIED PATH INCLUDING THE NAME OF THE EXECUTABLE.
   QMamecat will then automatically create a startup catalog for you. Note
   that this requires (at least) catgen to be in your path (which should be the
   case when you use "gmake install") !

   The startup configuration is done with the defaults described in section 6, 
   except for <mame_executable>, which you entered before. You may want to
   change some of the options, for example to enable the preview-image support.

   For more information on how to enable preview images, please see next
   section. 

   Please also read sections 11 and 12 for known bugs and restrictions !

4) Preview images

   If you wish to enable the preview images you will have to copy the images to
   the directory specified in qmamecatrc (option <preview_dir>). 

   Additionally you will have to set the option <show_preview> to enable this
   function !

   PNG snaphots created by X-Mame are natively supported; other image formats
   include XPM, GIF and BMP.

   Preview image filenames must be the same as their corresponding rom-images
   or <rom>0000.<ext> (up to <rom>0004.<ext>); the extension should reflect the
   image format (at least one of the above format abbreviations must be used
   (in lower-case letters !) for QMamecat to find the image) !

   For example: the preview image file for "galaga" would be a file named
   "galaga.png" or "galaga0000.png" (up to "galaga0004.png"); the 
   extension could be different, of course...

   Note that files without the "000x" snapshot-suffix are found first !

   If you store several images of a game with different image formats 
   (extensions), QMamecat will only display the one which it finds first. 
   Let's say you have 2 files for "galaga", i.e. "galaga.png" and "galaga.xpm",
   in this case QMamecat will only display "galaga.png" ! 

   The complete current order is PNG -> XPM -> GIF -> BMP ! This does also 
   apply if snapshot-suffixes (<rom>000x.<ext>) are used.

   When the extension does not specify the "real" image format, QMamecat will
   try to guess it (this is a nice feature of Qt's QPixmap class :-)... if it
   can't find the image file or validate the image format, a transparent image
   with the text "no image found" will be displayed instead.

   Since v0.28 zip-compressed previews are also supported ! The current 
   implementation accepts ONE big zip-file for ALL preview-images. This file has
   to be specified in the option <compressed_preview_file> and the option 
   <use_compressed_previews> has to be enabled (see section 6 for more details).

   ZIP is currently the only supported (de)compression method !

   Note that all rules stated above do also apply if you use zip-compressed 
   previews.

   If you are using the previews that we publish on our homepage, we do NOT
   recommend to archive them in a ZIP, because the PNG format already compresses
   the images very well, the ZIP file might even be bigger than the individual
   PNG files and the perfomance will be degraded a bit (especially when checking
   the previews).
   On the other hand, using just one file instead of thousands will save you a
   lot of inodes. And even on a midrange system you won't recognize it much.

5) Command line options

   The following command line options are currently available for QMamecat:

   -r            forces recreation of the ROM-status cache (should be used if
                 you install new ROMs - note that removing the ROM status cache
                 file or "refreshing" the gamelist from within QMamecat (ctrl-r)
                 has the EXACT SAME effect !)
   -h or -?      shows a usage help and exits

   Additional switches derived from QApplication:
   
   [-display disp] [-geometry geom] [-fn fnt] [-font fnt] [-bg bgcol]
   [-background bgcol] [-fg fgcol] [-foreground fg_col] [-name name]
   [-title title] [-style=guistyle] [-ncols ncols] [-visual TrueColor]
   [-cmap] [-nograb] [-sync]

   See the man-page of QApplication(3qt) for a full description of these
   switches !

6) QMamecat settings

   QMamecat stores its settings using Qt's QSettings class. Under UNIX, you'll
   find the settings in $HOME/.qt/qmamecatrc, under Windows (TM) it will be
   stored in the registry (despite that there's no port to Windows yet :).

   If it can't find its settings, a minimum configuration will be requested from
   the user (it only needs the path to xmame for this) and defaults will be used
   for the rest of the options.

   Also, if an option doesn't exist in the config file or its value is missing,
   the default value will be used for this option.

   The individual options and their defaults can be found in
   src/common/options.cc. Look for the option_info array, I'm not going to
   include and describe them here again as they are fairly self-explanatory :).

   You better leave the settings-file untouched and edit all settings
   from within QMamecat's options-dialog(s).

7) Catalog and ROM-status cache format

   Catalog format:

   Every entry (one for each game, one per line) has the following form:

   <rom><rating>[<remarks>][<gameopts>]

   <rom>           the rom-image name
   <rating>        expresses your personal opinion about the game (a decimal
                   value: 0 - 6); the way you interprete this is controlled by
                   some of the settings of the QMamecat configuration (see 
                   section 6)
   <remarks>       free-form text for personal remarks (optional)
   <gameopts>      specifies game-specific options which are passed to X-Mame
                   only for *this* game (optional); if you want to pass options
                   to *each* game, please use the <mame_options> setting in
                   qmamecatrc instead (see section 6)

   The file qmamecat.cat.sample (in this directory) contains a sample catalog.

   ROM-status cache format:

   Every entry (one for each game, one per line) has the following form:

   <rom> <rom_availability_flag> <rom_status>

   <rom>                    the rom-image name
   <rom_availability_flag>  1 or 0 (for "available" or "not available")
   <rom_status>             the numeric (internal) representation of the
                            rom-status

   NOTE: You should never edit this file manually !

8) ROM status

   Since v0.27 a "ROM status" is determined if you enable the option 
   <thorough_romcheck> (which will cause QMamecat to use the -verifyroms option
   of xmame to analyze the ROM-status thoroughly at startup and at every 
   "refresh" !).

   Since v0.39 <thorough_romcheck> is ALWAYS enabled and you cannot change it
   "externally". That is, <thorough_romcheck> is no longer an option, although
   it still exists in the options-struct...

   Note that this feature requires xmame 0.34rc1.1 (or above) to work properly,
   because it relies on the output of "-verifyroms" which has been changed a bit
   since this (xmame) version. If you use <thorough_romcheck> with an older
   xmame version, the analysis may not be correct ! See also section 3.

   The status-abbreviations and their meanings are:

   NA  'N'ot 'A'pplicable = unknown ROM-status (this will be displayed, if 
       <thorough_romcheck> is disabled or the ROM-status could not be 
       determined, for example because it is a game that does not have an
       explicit rom-set like "pong" !)
   CO  'CO'rrect = the ROM image is correct and should work fine
   MW  'M'ay 'W'ork = the ROM image is incorrect, but may work (most of the time
       only the checksum is incorrect)
   IN  'IN'correct = the ROM image is incorrect or corrupted and will definitely
       NOT work
   NF  'N'ot 'F'ound = there is no ROM-image for this game in your ROM-path
       (you should check your ROM-path, if you think it should be available)

9) Printing

   Since v0.30 a print function has been added. The generated output is
   postscript; if you don't have a postscript printer, make sure you have a
   filter setup for your printer. We recommend "apsfilter", which you can get
   from ftp.suse.com !

10) Contacting the author(s)

   Bug reports and questions specific to QMamecat should be sent to
   mamecat@umrk.dyndns.org directly, not to the xmame mailing-list.
   Feel free to send us any suggestions for enhancements and take a look at the
   CREDITS file to see who is responsible for which part of QMamecat - however,
   we prefer mail to mamecat@umrk.dyndns.org, because this will guarantee that
   ANY team member will be reached.

   Also, we would like to maintain a list of known working platforms/
   configurations, so please drop us a note even if you are successful. 
   Tell us under which circumstances (OS, OS-release etc.) you were successful,
   we will then add you to a list on the QMamecat homepage, so that someone with
   a similar configuration would be able to contact you... we cannot test on any
   potential target-platform.

11) Special notes for new versions of QMamecat

   This section is mainly for those who already used QMamecat prior to "THIS"
   release. It offers some notes about changes that might affect an earlier 
   installation and/or changes in "code-behaviour" you should be aware of.

   v0.44

   - Qt 2 is no longer supported - please update to Qt 3.1.0 or above ! For more
     information about a parallel installation of Qt 2 and Qt 3, please see the
     FAQ !

   - The old font-specification method has been replaced with Qt's way of
     handling fonts; due to this, all fonts are reset to default-fonts when you
     upgrade to v0.44 ! The new settings dialog makes it easy to reconfigure
     your fonts.

   - The settings dialog has been totally redesigned, so get used to it; but we
     think it's a great improvement.

   - We support 9 different GUI-styles now (default: Platinum-style).

   - To better support FreeBSD and other platforms, the ROM status parser has
     been changed to use a pipe instead of fork() & file I/O (which was a
     serious hack anyway :). Generally, this should make QMamecat even more
     platform-independent.

   - The catalog format has been slightly changed; QMamecat will update the
     catalog to the new format automatically, but this REQUIRES that catgen is
     in your path (the NEW version, of course) !

   - Emulator processes are no longer fork()'ed directly, instead there is a new
     process management system, which is based upon QProcess. The new emulator
     control dialog (see "View" -> "Emulators...") is the user-interface for it.

   - The search-widget is a combo box now, displaying the current list of
     matches for the entered/substituted string.

   - ANY changes to the window layout are recognized now; QMamecat will ask you
     to save the layout if applicable.

   - A complex dialog to edit MAME options (general and game-specific) has been
     added. This includes new binaries (qmmapkey-*) for xmame display-target
     dependent key-mappings.

   - The settings are now totally managed by Qt (QSettings class) for better
     platform-independance and flexibility (future enhancements). As a result,
     ALL settings will be reset as if QMamecat was newly installed ! However, an
     existing catalog and/or ROM status cache can be used without problems, if
     you didn't change their location and file names ($HOME/.xmame/mamecat.cat
     and $HOME/.xmame/mamecat.rsc).

12) Bugs and restrictions

   - Please NEVER EVER iconify QMamecat (or switch to another virtual desktop),
     while it is doing ANY intensive analysis AND showing a progress-dialog - it
     most likely will freeze or even crash QMamecat !!!

     We don't know yet what the reason is, but suspect a Qt bug. This has been
     seen with Qt 2 and 3 on different platforms (Linux, SunOS) and window
     managers (KDE, CDE) !

   - If you change between internal/external preview TOO FAST, the position of
     the external window might not be determined correctly. As this can only
     happen by holding down the accelerator keysequence ALT+I and with a very
     short key repeat rate, this bug can be considered of minor importance...

   - The style management isn't perfect. In some rare cases the menubar is
     redrawn incorrectly when switching styles on-the-fly (esp. when the SGI
     style was selected before). We don't know the reason, but suspect a Qt
     and/or style plugin bug. This can be fixed by restarting QMamecat.

   - When "Metal (fancy)" style is selected, the sample color buttons are not
     colored (every other style does it correctly).

   - Changes to the window layout (resize, move) during startup are not
     recognized; after the gamelist has been loaded completely, it works fine.
     We know the reason, but fixing this would require too many changes (and
     isn't worth it).

13) How to create diffs and install patches

   This information is mainly for developers.

   Creating a unified diff:
 
   diff -urN -X qmamecat-<new_version>/doc/diff.exclude qmamecat-<old_version>
        qmamecat-<new_version> > qmamecat-<old_version>-<new_version>.patch
 
   Patching the older version:
 
   cd qmamecat-<old_version>
   patch -p1 < qmamecat-<old_version>-<new_version>.patch

   GNU diff/patch is required !

14) License

   QMamecat is distributed under the GNU General Public License (version 2 and
   above). For more information please take a look at the file COPYING (should
   be in this directory; if not, write to the Free Software Foundation, Inc.,
   59 Temple Place, Suite 330, Boston, MA 02111-1307, USA).

   The unzip-code (unzip.[ch], inflate.[ch] and types.h in src/unzip) has been
   taken from xmame's source. AFAIK, the original code is copyrighted by Mark 
   Adler - if this is wrong or we are missing somebody, please let us know !!!

   Code for the "fancy" styles wood and metal is based upon the Qt 3 example
   "themes" and as such it is originally copyrighted by Trolltech AS ! But its
   freely redistributable.

Have fun,

The QMamecat-Team
