### README - v0.1.b10, 20-JUL-2007

### Contents

1. What is the M.A.M.E. Catalog / Launcher II?

2. Build instructions

3. Command line arguments and configuration

4. Gamelist statistics and ROM status

5. GUI style plugins

6. Shortcuts

7. How to create diffs and install patches

8. Multi-platform support

9. Contact

10. Contributing

11. License and copyright

12. Legal notice

### 1. What is the M.A.M.E. Catalog / Launcher II?

M.A.M.E. Catalog / Launcher II - also referred to as QMC2 - is the successor of one of the first XMAME GUI frontends available on this planet called QMamecat (derived from MAMECAT, which was text-only).

QMamecat was based upon Qt 2; its development was frozen in 2003. QMC2 has been rebuilt from scratch as a Qt 4 project. Parts of the design and code were inspired by its predecessor, but it's not just a remake. We tried to make the new design as flexible as possible to minimize dependencies from frontend- and CLI-related MAME changes, which was a major deficiency of QMamecat. QMC2 now uses a template based MAME configuration scheme, which can easily be enhanced with additional command line options (defined in an XML template file).

As a result of this flexible design, we are able to support multiple MAME targets - currently XMAME and SDLMAME!

QMC2's current major features include:

- Extremely fast preview- & flyer- image support, optionally smoothly scaled (PNG images, buffered in a resizable LRU-cache)
- Support for game icons (also PNG images), fast (pre-)caching mechanism
- Icons, preview- & flyer-images can either be stored as individual files in respective directories or they can be combined and compressed in ZIP archives
- Easily extensible template-based MAME configuration scheme (defined through an external XML file)
- Cool editor for configuration of global and game-specific MAME command line options, with search function
- Support for all emulation-related extra information available through MAME (displayed in a tree)
- Fast search function with wild-card pattern matching
- Selectable sort criteria and order for gamelist (game description, ROM state, year and manufacturer)
- Straightforward process management to control emulator processes
- Clear and full logging (separate frontend- and MAME-logs)
- Cached ROM state verification, indicated as colored spheres in front of each game description
- Verification of sample sets
- Game image checks (icons, previews & flyers)
- Online display of current gamelist, ROM status and search result statistics
- Two gamelist views: full game detail and parent/clone hierarchy
- GUI will always remain interactive, so you may configure or play MAME (etc.) even if heavy background-processing is active
- Time-consuming background tasks can be stopped on demand at (nearly) any time
- Optional auto-save/restore of window layout and game selection
- Multi-platform support
- Fully multi-language capable - translations exist for english (native) and german
- Game favorites management and play-history
- Online HTML-documentation and browser
- Support for XMAME and SDLMAME (default)
- Built-in support for GUI styles / style plugins

### 2. Build instructions

Software requirements:

Software requirement | Where to get
Qt 4.2.0+ | http://www.trolltech.com/
GNU make 3.8+ | http://www.fsf.org/
zlib 1.2.3+ | http://www.zlib.net/
SDLMAME 0.109+ XMAME 0.104+ | http://rbelmont.mameworld.info/?page_id=163 http://x.mame.net/

Uncompress and untar the source distribution archive:

    $ bzip2 -d qmc2-<version>.tar.bz2
    $ tar xvf qmc2-<version>.tar

Make sure that the environment is setup correctly:

    $ cd qmc2
    $ export QTDIR=/your/qt4/installation/directory

At this point, you may have to create (or adjust) an OS-dependent configuration file, if your platform should not be in the list of tested operating environments; see section 8. for more details.

Now you are ready to run the build process:

    $ make

If you have an SMP system, you should better run make in jobserver mode, this is completely safe and much faster. For example:

    $ make -j3

(replace "3" with "#CPUs + 1")

QMC2 supports both XMAME and SDLMAME, but not at the same time (at run-time, that is). You have to choose which MAME target you're going to use. SDLMAME is the default MAME target. For XMAME, please use the following make command:

    $ make [-jX] MAME=XMAME

As soon as QMC2 has been compiled and linked completely, it's ready for use. There is no need to explicitly install QMC2 as it has been designed to work fully self-contained. Even the data-directory can be kept locally, which works well.

It's still advisable to install QMC2 system-wide (you have to do this as root). The user's configuration and his data will be kept locally (in $HOME/.qmc2/):

    $ su
    Password:
    # make install [MAME=XMAME]
    # exit

See

    $ make help

for more information.

### 3. Command line arguments and configuration

Usage:

    $ qmc2 [qt4_arguments]

QMC2 does not provide any arguments except those inherited by Qt 4.

Here's the list of all optional Qt 4 arguments quoted from http://doc.trolltech.com/4.2/qapplication.html#QApplication

- -style= style, sets the application GUI style. Possible values are `cde`, `motif`, `windows`, `plastique` and `cleanlooks`. If you compiled Qt with additional styles or have additional styles as plugins, these will also be available to the `-style` command line option. This argument will only be regarded if the style setting of QMC2 is set to Default!
- -style style, is the same as listed above
- -session= session, restores the application from an earlier session
- -session session, is the same as listed above
- -widgetcount, prints debug message at the end about number of widgets left undestroyed and maximum number of widgets existed at the same time

The X11 version of Qt also supports some traditional X11 command line options (please note that some of these arguments are useless as they will be overwritten with QMC2's configuration settings):

- -display display, sets the X display (default is $DISPLAY)
- -geometry geometry, sets the client geometry of the first window that is shown
- -fn or `-font` font, defines the application font. The font should be specified using an X logical font description
- -bg or `-background` color, sets the default background color and an application palette (light and dark shades are calculated)
- -fg or `-foreground` color, sets the default foreground color
- -btn or `-button` color, sets the default button color
- -name name, sets the application name
- -title title, sets the application title
- -visual `TrueColor`, forces the application to use a TrueColor visual on an 8-bit display
- -ncols count, limits the number of colors allocated in the color cube on an 8-bit display, if the application is using the QApplication::ManyColor color specification. If count is 216 then a 6x6x6 color cube is used (i.e. 6 levels of red, 6 of green, and 6 of blue); for other values, a cube approximately proportional to a 2x3x1 cube is used
- -cmap, causes the application to install a private color map on an 8-bit display

Notes:

- The configuration file will be stored as $HOME/.qmc2/qmc2.ini. Although it's recommended to edit the configuration with the built-in options dialog, you may still change it manually on your own risk as long as QMC2 is not currently running.

### 4. Gamelist statistics and ROM status

Gamelist statistics are shown in the lower-left corner of the main widget, below the gamelist. The letters - and their colors - have the following meanings:

Letter | Icon / Color | Meaning

L

black

Number of Listed games

C

| green

Number of Correct games (only available if ROM status has been checked)

M

| yellow-green

Number of Mostly correct games (only available if ROM status has been checked)

I

| red

Number of Incorrect games (only available if ROM status has been checked)

N

| grey

Number of games which were Not found (only available if ROM status has been checked)

U

| blue

Number of games with an Unknown ROM status

S

brown

Number of game-matches for the current Search-pattern (if any)

If any statistical number is yet undetermined, a question mark (?) is shown instead.

Individual ROM states are displayed in the gamelist itself, indicated by colored sphere icons in front of each game entry (see table above).

The process of ROM status determination is a very time-consuming task, so it's not started automatically. You have to explicitly trigger a ROM check (see Tools menu) at least once. To speed up this process for future runs, ROM states are cached in an external ROM state cache file (default: $HOME/.qmc2/qmc2.rsc). If QMC2 finds cached ROM state information in this file, it will read the states for each game from the cache when the gamelist is reloaded.

It's in your responsibility to trigger a re-check of the ROM states when anything changes (ROM images or MAME updates). However, if the number of totally supported games is different than the number of cached ROM states, QMC2 will log a warning (see frontend log).

Since v0.1.b10 QMC2 also supports individual ROM checks, so changes to only some games of your collection do not force you to fully re-check every ROM. For MAME updates there is no way around it, though (unless you know which games may have changed or have been added).

ROM states can also be used to filter and/or sort the gamelist. Please note that as a matter of principle the ROM state filter cannot be applied to the hierarchical parent / clone view (of the gamelist), because the display of clones depends on the display of their parents.

Notes:

- The words game and ROM are used as synonyms within QMC2!

### 5. GUI style plugins

GUI styles can either be selected on the command line (-style, see section 3.) if the GUI style setting is setup as "Default" or by explicitly selecting a style / style plugin from the respective combo-box in the options-widget.

### 6. Shortcuts

Several functions (or actions in Qt technical jargon :) can be accessed via shortcut key-sequences. The following table lists all of them:

Shortcut | Function
CTRL+P | Play the currently selected game (start emulation)
CTRL+F | Copy the currently selected game to the list of favorites
CTRL+R | Reload the entire gamelist
CTRL+X | Stop any active processing, otherwise exit QMC2
CTRL+O | Open the options dialog
CTRL+T | Housekeeping: recreate template configuration map (needed if the XML options template changes at run-time)
CTRL+I | Housekeeping: clear image cache
CTRL+N | Housekeeping: clear icon cache
CTRL+H | QMC2 documentation browser
CTRL+A | About QMC2: version, license etc.
CTRL+Q | About Qt: version, license etc.
CTRL+S | Check current game's ROM state individually and update its state in the ROM state cache
CTRL+1 | Check ROM states for all games in your collection and recreate the ROM state cache from scratch
CTRL+2 | Check sample set for games that need samples
CTRL+3 | Check preview images for existance & accessability
CTRL+4 | Check flyer images for existance & accessability
CTRL+5 | Check icon images for existance & accessability
F5 | View gamelist with full detail
F6 | View parent/clone hierarchy

### 7. How to create diffs and install patches

This information is mainly for developers.

Creating a unified diff:

    $ diff -urN qmc2-<old> qmc2-<new> > qmc2-<old>-<new>.patch

Don't forget to do a "make clean", or even better "make dist", before creating a patch!

Patching the older version:

    $ cd qmc2-<old>
    $ patch -p1 < qmc2-<old>-<new>.patch

Note that GNU diff/patch is required!

### 8. Multi-platform support

As the frontend-code has been designed with full POSIX-portability in mind, QMC2 should work on any UNIX or UNIX-like platform, provided Qt 4 and SDLMAME (or XMAME) are supported on this platform as well.

However, you may have to create or adopt the corresponding OS-specific configuration file, which is arch/`uname`.cfg. If it does not exist nor fit your local situation, the build will most likely fail:

    $ make ARCH=test
    Makefile:52: arch/test.cfg: No such file or directory
    make: *** No rule to make target `arch/test.cfg'.  Stop.

Note that by using the ARCH-variable on the make command line, you could easily specify a local configuration, even if a system configuration file already exists for your platform. Take the one that comes nearest to your system configuration and change it to your needs.

Since v0.1.b10, there's an alternative method which will help to solve distribution-specific build problems. Let's say you wanted to use the Qt 4 packages provided by your distribution and you know that the version is sufficient. So, instead of just considering Linux as the OS name (or architecture), also consider the local differences of this type of setup:

    $ make DISTCFG=1

If make is called this way, the QMC2 build process will try to figure out what the exact name and release of your OS / distribution is. It will load the OS-specific configuration just as before (i.e. arch/Linux.cfg), but it will overwrite the OS configuration settings with the distribution-specific configuration settings (i.e. arch/Linux/openSUSE_10.2_(i586).cfg). This means that only differences to the global OS configuration need to be placed in this file.

Of course, this mechanism requires that a specific configuration file for your OS / distribution exists. If not, the build will fail. Create the required file (see output from make or run make os-detect to figure out the correct name of the configuration file) and try again!

In case of any trouble, feel free to contact us (see section 9.). Please attach the output of make os-detect in this case!

Also, please send us your configuration file if you try QMC2 on other platforms / distributions than the ones included in the arch/ or arch/<os-name>/ directories. Regardless if you are successful or not, any help is very much appreciated (see section 10.).

We are especially interested to hear how it works on Mac OS X; it's expected to run, but no one reported back yet. It may even run on Cygwin with SDLMAME for Windows (we are most likely not going to officially support this any time soon, although it'd be cool :).

### 9. Contact

Project homepage:

- http://www.mameworld.net/mamecat/

Development site:

- http://sourceforge.net/projects/qmc2

QMC2 development mailing list:

- qmc2-devel@lists.sourceforge.net (subscribers only)
- https://lists.sourceforge.net/lists/listinfo/qmc2-devel

### 10. Contributing

Help and contributions are very much appreciated. Following are the most important areas where we need your support:

- beta testing, bug hunting
- documentation
- translations (application and documentation)
- graphics / GUI design

If you think you can help us in one or more of these areas, please contact us!

We are using SourceForge.net as our open-source development platform. If you intend to become a QMC2 developer, note that you're required to use SVN (Subversion).

See credits.html for a list of contributers.

### 11. License and copyright

QMC2 - M.A.M.E. Catalog / Launcher II
Copyright © 2006 - 2007 R. Reucher, Germany, All Rights Reserved

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the license, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

Third party software used in this project:

Minizip 1.01e
Copyright © 1998-2005 Gilles Vollant, http://www.winimage.com/zLibDll/minizip.html, info@winimage.com.

See copying.html.

### 12. Legal notice

Please note that you are required to have permission to use or to be the legal owner of any ROM images you are going to run through M.A.M.E. and / or this frontend. The goal of M.A.M.E. and its surrounding projects (like QMC2) is educational and academic (of course, it's also fun :).

We do NOT and will NEVER encourage or support any type of illegal use!