README - v0.2.b7, 09-MAR-2009

Contents

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

2. Build and installation instructions

3. Command line arguments and configuration

4. Game/machine list statistics, ROM status and the ROMAlyzer

5. GUI style plugins and style sheets

6. Short cuts, GUI control keys and joystick support

7. External tools and tool argument syntax

8. Multi-platform support

9. Contact

10. Contributing

11. License and copyright

12. Legal notice

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

M.A.M.E./M.E.S.S. Catalog / Launcher II - also referred to as QMC2 - is the successor of one of the first UNIX MAME GUI front ends 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 front end and CLI related MAME changes, which was a major deficiency of QMamecat. QMC2 now uses a template based emulator 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, QMC2 can be used for multiple emulators. Currently, SDLMAME and SDLMESS are supported.

XMAME support has been dropped since QMC2 0.2.b1 (use QMC2 0.1 if you still need XMAME!).

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/machine 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 emulator configuration scheme (defined through an external XML file)
• Cool editor for configuration of global and game/machine-specific emulator options, including a search function
• Support for all emulation-related extra information available through the emulator (displayed in a tree)
• Fast search function with automatic wildcard pattern matching
• Selectable sort criteria and order for game/machine list (description, name/ID, ROM state, year and manufacturer)
• Straightforward process management to control emulator processes
• Clear and full logging (separate front end and emulator logs)
• Cached ROM state verification, indicated as colored spheres in front of each game/machine description
• Verification of sample sets
• Game/machine image checks (icons, previews & flyers)
• Online display of current game/machine list and search result statistics
• Two game/machine list views: full detail and parent/clone hierarchy
• The GUI will always remain interactive even if heavy background processing is running
• Time-consuming background tasks can be stopped on demand at (nearly) any time
• Optional auto-save/restore of window layout and game/machine selection
• Multi-platform support (POSIX environment required)
• Fully multi-language capable - right now, translations exist for English (us), German (de), Polish (pl) and French (fr)
• Game/machine favorites management and play-history
• Online HTML documentation and browser
• Designed to be used for multiple emulators (currently SDLMAME and SDLMESS)
• Built-in support for GUI styles (KDE 4 / Qt 4 style plugins are supported)
• Automatic caching of analysed game/machine data to speed up processing
• Import & export emulator configurations
• All short cuts & GUI control keys can be remapped
• Removal of obsolete samples & image files (stored in directories or ZIP archives)
• Automatic caching of XML output from emulator
• Built-in ROMAlyzer to deeply analyze a game's/machine's ROMs and CHDs - inspired by Carsten Engel's ROMAlyzer script (see scripts/romalyzer.pl in source distribution)
• Optional use of OpenGL features (currently only preview & flyer image painting)
• Support for direct GUI control via analog and digital joysticks through SDL (Simple Directmedia Layer)
• Detailed game/machine information from MAME's history.dat game information database and MESS' sysinfo.dat machine information database
• Basically the same for mameinfo.dat as MAME's emulator information database (there's nothing like that for MESS)
• Support for MAME's output notifications via a named pipe (see emulator control panel)
• Built in audio player based on the Phonon API
• ROM status export to clipboard or file as ASCII, CSV or HTML
• Integrated MESS device configuration
• All variants of QMC2 can launch each other

2. Build and installation instructions

Please see this FAQ section for instructions on specific distributions.

Building the QMC2 binary

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 is generally prepared to support multiple emulators. You have to choose which target emulator you're going to use. SDLMAME is the default emulator. For other potential emulators, please use the following make command:

$ make [-jX] EMULATOR=<emulator-name>

Joystick support is optional (but enabled by default) and requires SDL - the Simple Directmedia Layer. If you would like to disable it, for example because SDL is not supported on your OS (huh?), you could use the JOYSTICK make command line option to do so:

$ make [-jX] JOYSTICK=0

If you are using Qt 4.4+, the QMC2 build system will automatically enable the use of Qt's Phonon integration for some multimedia functionality (like the built-in audio player). This feature is fully optional though and as it requires a working Phonon environment - especially a working backend API such as gstreamer - you can disable it at compile time. Use the PHONON make command line option to accomplish that:

$ make [-jX] PHONON=0

Note that nearly all (*) of the supported make command line options can be freely combined when make is called. See

$ make help

for more information.

(*) The only exceptions are DISTCC and CCACHE which cannot be enabled at the same time.

IMPORTANT NOTE

Pease never ever run qmake standalone -- when qmake is called directly, important settings may be missing in the resulting Makefile.qmake file. If you see strange errors like undeclared MAJOR / MINOR variables, this simply means you've run qmake yourself -- prior to version 0.2.b6 this even destroyed QMC2's Makefile, but that's at least avoided now by forcing qmake's output to be stored as Makefile.qmake in the project definition.

We've been asked about this so many times that we thought it would be necessary to make it absolutely clear that everything is controlled by make rules and thus you should only call make and nothing else!

Ending the rant here :).

Instead, qmake will be called by make and it will pass a lot of important arguments to qmake which depend on the local situation. On a clean source tree you'll see what's passed to qmake in the first line of the output (that is, if not called with QUIET=1). If you'd call qmake exactly this way it would work, though.

System wide installation

As soon as QMC2 has been compiled and linked completely, it's ready for use. There is basically 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.

However, 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/ on most *NIX or ~/Library/Application Support/qmc2/ on OS X):

$ su
Password:
# make install [EMULATOR=<emulator-name>]
# exit

The QMC2 binary will be named as qmc2-emulator (i.e. qmc2-sdlmame or qmc2-sdlmess), depending on the value of the EMULATOR make option. However, a symbolic link named qmc2 will created in the binary installation directory on make install which links to the binary file that was last installed.

The system-wide default configuration will be installed to /etc/qmc2/qmc2.ini or /etc/qmc2/qmc2.ini.new (if an older version of that file already exists). In case of an update, you should check /etc/qmc2/qmc2.ini.new for any new settings and add them to /etc/qmc2/qmc2.ini manually!

Note that in order to use the QMC2 variant launcher - one QMC2 variant can launch (or switch to) the other - it is required that all binaries are in your search path (including the runonce launcher wrapper)!

3. Command line arguments and configuration

Usage:

$ qmc2[-emulator] [qt4_arguments]

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

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

• -style=style, sets the application GUI style (setting this option has no effect!)
• -style style, is the same as listed above
• -stylesheet=stylesheet, sets the application style sheet. The value must be a path to a file that contains the style sheet. Note that relative URLs in the style sheet file are relative to the style sheet file's path.
• -stylesheet stylesheet, 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
• -reverse, sets the application's layout direction to Qt::RightToLeft
• -graphicssystem g_backend, sets the backend to be used for on-screen widgets and QPixmaps. Available options are raster and opengl.

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
• -im i_method, sets the input method server (equivalent to setting the XMODIFIERS environment variable)
• -inputstyle i_style, defines how the input is inserted into the given widget. E.g., onTheSpot makes the input appear directly in the widget, while overTheSpot makes the input appear in a box floating over the widget and is not inserted until the editing is done.

Notes on the configuration of QMC2:

• The user's configuration file will be stored as $HOME/.qmc2/qmc2.ini on most *NIX or ~/Library/Application Support/qmc2/qmc2.ini on OS X
• A system-wide default configuration can be used to pre-configure QMC2 for your users (common path: /etc/qmc2/qmc2.ini on most *NIX or /Library/Application Support/qmc2/qmc2.ini on OS X)
• If no configuration can be found for a specific option, hard-coded default values will be used for all front end settings (see code); default values for the emulator configuration are read from the current XML template (common path: /usr/local/share/qmc2/opt/<EMULATOR>/template.xml)
• If the path to the emulator's executable file has not been set (yet), QMC2 will assume that you are starting it for the first time (your setup is incomplete as long as this option hasn't been set!)
• Although it is recommended to edit the configuration with the built-in setup dialog, you may change it manually with any editor at your own risk; only do this if QMC2 is NOT currently running!

4. Game/machine list statistics, ROM status and the ROMAlyzer

Game/machine list statistics are shown in the lower-left corner of the main widget, below the game/machine list. The letters - and their colors - have the following meanings:

Letter	Icon / Color	Meaning
L	black	Number of Listed games/machines
C	green	Number of Correct games/machines (*)
M	yellowgreen	Number of Mostly correct games/machines (*)
I	red	Number of Incorrect games/machines (*)
N	grey	Number of games/machines which were Not found (*)
U	blue	Number of games/machines with an Unknown ROM status
S	brown	Number of game/machine-matches for the current Search-pattern (if any)

(*) only available if the ROM state has been checked

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

Individual ROM states are displayed in the game/machine list itself, indicated by colored sphere icons in front of each game/machine entry (see table above). When using the classic image set, BIOS ROMs will contain a white B in their ROM status icons and obviously cannot be run. Other (= non-default) image sets may indicate BIOS ROMs differently.

Depending on your hardware, ROM status determination may be 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 on most *NIX or ~/Library/Application Support/qmc2/qmc2.rsc on OS X). If QMC2 finds cached ROM state information in this file, it will read the states for each game/machine from the cache when the game/machine list is reloaded.

Unless the option AutoTriggerROMCheck (available since v0.1.b11) hasn't been activated, it is in your responsibility to trigger a re-check of the ROM states when anything changes (ROM images or MAME updates, for example). If the number of totally supported games/machines is different than the number of cached ROM states, QMC2 will log a warning to the front end log (and optionally trigger an automatic ROM check, if AutoTriggerROMCheck has been set).

Since v0.1.b10 QMC2 also supports individual ROM checks, so changes to only some games/machines 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/machines may have changed or have been added).

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

BTW, the words game and machine are used as synonyms within QMC2. The MAME variant prefers to operate on games, whereas the MESS variant operates on machines.

ROMAlyzer

Since v0.2.b1, there is also a so called ROMAlyzer which allows to deeply scan individual (or multiple) games/machines for their exact ROM state. This work was inspired by Carsten Engel's romalyzer.pl Perl script (see scripts/romalyzer.pl in the source distribution) - he also offered very helpful comments on ROM identification and how to handle CHDs. Thanks!

ROMAlyzer features & restrictions:

• Imitates MAME's way of finding ROMs, using their CRCs to identify them.
• Uses the XML game/machine data to compare (expected) checksums and sizes as well as to know which ROM & CHD files are required, if they need to be merged from other games/machines etc.
• ZIP-archived ROMs will be decompressed and their checksums will be recalculated on-the-fly (this will also identify ZIP-archives with an invalid file integrity).
• ROMs which are stored in game/machine-directories (not ZIP-archived) will be loaded to calculate their hashes.
• All required hash algorithms are supported: CRC(-32), SHA1 and MD5.
• CHDs (only v3+) are not yet decompressed, their header checksums are used instead (the provided hashes are for the uncompressed data).
• ROM and CHD files will never be fully loaded into memory, only small blocks of data are read for hash calculation and dropped directly afterwards.
• Long ROMAlyzer runs can be paused / resumed (or stopped) at nearly any time.

5. GUI style plugins and style sheets

GUI styles can be switched on-the-fly by explicitly selecting available style plugins from the respective combo-box in the setup dialog (see Front end -> GUI). If you installed additional style plugins to Qt, these will be available here as well.

The Default GUI style is system's default style.

KDE styles are supported if they were made for KDE 4 (Qt 4)!

Since v0.1.b11, support for style-specific custom color palettes (which can be setup with qtconfig) has been added. The default behavior of QMC2 is to use the default palette. You can disable this via the StandardColorPalette setting to use the customized color palette instead - if applicable (see Front end -> GUI in the configuration dialog).

Note that some add-on GUI styles may look ugly or be even buggy (as of this writing, some version of the Oxygen style for example is known to raise an X11 bug when the ROMAlyzer is opened initially). Don't ask for support if you know that this is the cause of your troubles! Please contact the style's developer(s) instead.

Qt style sheets can be used in conjunction with any GUI style. For now, the style sheet (a .qss file) can only be specified on the command line using the -stylesheet option. Note however that using a style sheet which changes the background brush of all QLabel's may render a few widgets unusable because their background colors cannot be changed dynamically after they have such a style sheet set. The most important one is the optional vertical game/machine status indicator (object name labelGameStatus).

See here for more information on Qt style sheets: http://doc.trolltech.com/4.5/stylesheet.html

6. Short cuts, GUI control keys and joystick support

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

Remapping short cuts and GUI control keys

Since v0.1.b11, QMC2 also supports remapping of all these short cuts and some special keys (cursor keys, tab, +/-, ...) needed for GUI control by key-strokes. It should be very handy for users of MAME cabinets with sticks that map their controls to key-strokes (X-Arcade controls for example). We hope it's useful for others as well :).

Joystick control

For users of (regular) analog or digital joysticks, there is direct support for joystick GUI control through SDL (Simple Directmedia Layer) since v0.2.b3. Simply enable joystick support on the respective configuration page, map any of the above functions or GUI control keys to joystick functions and you can start using a stick to control QMC2 right away.

Internally, joystick functions are mapped to active keyboard short cuts and/or GUI control keys. The corresponding key presses are emulated in software as soon as a mapped joystick function is recognized. This means that using a joystick to control the GUI will cause some additional events, but it doesn't hurt.

Key events for joystick mappings will always be sent to the widget which currently has focus, but only if the widget is one of QMC2. All other cases will be ignored, which means that it does not influence the emulator (or vice versa), although QMC2 still recognizes the joystick movements, button presses etc... it will just not react on them while the emulator (or any other application) has focus.

The only exception to this rule is when QMC2 is currently in joystick test- or calibration-mode. However, this can safely be used concurrently to a running emulator which uses the same stick (i. e. for debugging).

7. External tools and tool argument syntax

External tools like zip or rm are used for specific operations which weren't natively built into QMC2.

For example, to remove obsolete image files from ZIP archives, QMC2 uses an external zip-tool and passes the files to be removed on the argument list when the zip-tool is started. We recommend to use Info-ZIP's zip 2.31+ which is what we've tested. But it could be any zip program that supports the deletion of multiple entries from ZIP archives at once.

Similarly, a second tool is needed for the deletion of files within filesystems (when images are stored directory based, for example). We recommend rm from GNU coreutils 6.4+. This tool also needs to support the deletion of multiple files in one step.

Tools can have a single function or they can have multiple functions. For each function, an argument list has to be specified which defines the correct syntax for the command. Macros (like $MACRONAME$) can be used as placeholders and will be filled with real data before execution.

The following macros exist:

Everything else will be passed as literal text at the position where it's specified (see Front end -> Tools in setup dialog).

When external tools are started by QMC2, a simple tool-executor dialog will pop up to display the command and its output.

8. Multi-platform support

As the front end 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/MESS (or whatever emulator may be used) 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
ls: arch/test.cfg: No such file or directory
Qmake version: 1.07a (Qt 3.3.7)
Qmake is free software from Trolltech AS.
Error: Wrong QMake version. QMake version 2 (Qt 4) required!

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.3.cfg in case of an openSUSE 10.3 installation). 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 expected 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 greatly appreciated (see section 10.).

Thanks to Vas Crabb, QMC2 is now also supported on Mac OS X. See here for more information: http://www.bannister.org/forums/ubbthreads.php?ubb=showflat&Number=48449

Preliminary tests showed that it would even be possible to port it to Windows (we tried using Qt 4 for Windows and the MinGW compiler), but we are most likely not going to officially support this any time soon. The most important reason is that it would be too slow on this platform... we would have to write a non-POSIX port to get rid of the POSIX emulation of MinGW (which is the cause of the slowdown). This is expected to be fast enough, but it has never been tried by one of us.

9. Contact

Project homepage:

• http://qmc2.arcadehits.net/

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 greatly 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./M.E.S.S. Catalog / Launcher II
Copyright © 2006 - 2009 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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, 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

runonce --- GUI program-launching wrapper
Copyright © 2001 Jamie Zawinski, jwz@jwz.org

See copying.html for the GNU General Public License.

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 an emulator and / or this front end. The goal of emulators and its surrounding projects is educational and academic (of course, it's also fun :).

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

However, a hand full of ROM images has been released to the public for non-commercial use. For instance, free MAME compatible ROMs are available at http://mamedev.org/roms.