M.A.M.E. Catalog / Launcher II Documentation - README

### README - v0.70, 30-NOV-2016

### Contents

1. What is the M.A.M.E. Catalog / Launcher II?
2. Build and installation instructions
3. Command line arguments and configuration
4. Machine list statistics, ROM status and the ROMAlyzer
5. Short cuts, GUI control keys and joystick support
6. External tools and tool argument syntax
7. Multi-platform support
8. Contact
9. Contributing
10. License and copyright
11. 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 UNIX M.A.M.E. 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.

By the beginning of March 2006, we started to build QMC2 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 and countless hours of work, QMC2 today is not only a stable, feature-rich and fast multi-platform GUI front-end for M.A.M.E. but also a fully-featured ROM manager for this emulator (and its derivatives, older versions of MAME or even foreign emulators when they use the same/similar XML syntax) through the built-in ROMAlyzer.

See the incomplete feature list for more details.

### 2. Build and installation instructions

Please see this section in the QMC2 wiki and/or this FAQ for build and installation instructions.

### 3. Command line arguments and configuration

Usage example (for Linux/UNIX and Mac OS X, the binary is called `qmc2-mame.exe` on Windows):

    $ qmc2-sdlmame [-config_path <path>] [-cc] [-tc] [-r] [-h|-?|-help] [qt_arguments]

Arguments in detail:

- -config_path: See configuration path below!
- -cc: This command line option will instruct QMC2 to clear (remove) all emulator related cache files while starting up in order to forcibly reload this data from the emulator.
- -tc: Specifying this option on the command line will perform a template check against the current default emulator (if set), printing its output to stdout, and exit before actual start-up occurs.
- -r: The reconfigure option will rerun the setup wizard / welcome dialog before starting. This allows you to update or correct the most important emulator settings in an easy way.
- -h|-?|-help: Shows a brief command line usage help.
- qt_arguments: See the QApplication class reference for details on what Qt arguments are available (note, however, that some of these arguments are useless since QMC2 will overwrite them with its saved ini-settings).

Configuration path

When the -config_path option is specified on the command line, QMC2 will use this directory instead of the default 'dot-path' (see configuration notes below). Note that it's in your responsibility to copy/move the data to its desired place prior to starting QMC2 when this option is set, otherwise QMC2 will start over (which may be wanted behavior, though). Also, any settings that may have inherited the previous dot-path will have to be changed manually (probably by editing qmc2.ini, but take care).

Notes on the configuration of QMC2

UNIX and Mac OS X:

- The user's configuration file will be stored as ~/.qmc2/qmc2.ini on UNIX, or as ~/Library/Application Support/qmc2/qmc2.ini on Mac OS X.
- A system-wide default configuration can be used to pre-configure QMC2 for your users (common paths: /etc/qmc2/qmc2.ini on UNIX, or /Library/Application Support/qmc2/qmc2.ini on Mac OS X).

Windows:

- The user's configuration file will be stored as %USERPROFILE%\.qmc2\qmc2.ini on Windows.
- A system-wide default configuration for all users isn't supported (yet).
- All paths need to be specified POSIX-like, that is backslashes ("\", Windows) become slashes ("/", POSIX) within QMC2 -- so don't be surprised when you see paths like C:/some/directory (instead of C:\some\directory) in QMC2, because that's how it's supposed to look like :)! The only exception is the command displayed on the emulator control panel (and in the front end log) because it may be copied to clipboard and reused on the command line directly (which wouldn't work with slashes in path names).

All platforms:

- 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 (default paths: /usr/local/share/qmc2/opt/<EMULATOR>/template.xml on UNIX, /Library/Application Support/qmc2/opt/<EMULATOR>/template.xml on Mac OS X, and data\opt\<EMULATOR>\template.xml on Windows).
- 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 considered 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, though!

### 4. Machine list statistics, ROM status and the ROMAlyzer

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

Letter | Color | Icon | Meaning / Description
L | black | -- | Number of Listed machines This is the overall number of machines the emulator supports.
C* | green |  | Number of Correct machines All dumps exist emulator-wise; they also exist in your local collection, and their header checksums are the expected ones. The machine will most likely work fine (provided its driver is mature enough).
M* | yellow-green |  | Number of Mostly correct machines One or more dumps are missing or bad (emulator-wise), but your collection has all (correct) dumps that are available. The machine may not work (as expected), but most of the time it will run fine (provided its driver is mature enough).
I* | red |  | Number of Incorrect machines One or more dumps in your collection are bad (there may also be missing or bad dumps emulator-wise). The machine may not work, and most of the time it won't.
N* | grey |  | Number of machines which were Not found One or more required dumps are missing in your collection (there may also be missing or bad dumps emulator-wise). The machine will not work.
U | blue |  | Number of machines with an Unknown ROM status The ROM state of the respective machine hasn't been checked yet (or something went wrong during the check, or the check was prematurely interrupted).
S | chocolate | -- | Number of machine-matches for the current Search-pattern (if any)
T | sandybrown | -- | Number of sets currently Tagged

*: These numbers are only available when 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 machine list itself, indicated by colored sphere icons in front of each machine entry (see table above). When using the classic image set, BIOS ROMs will contain a white B in their ROM status icons. Device ROMs contain a white D and cannot run standalone. Other (= non-default) image sets may indicate BIOS and device 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: ~/.qmc2/<emulator>.rsc on UNIX, ~/Library/Application Support/qmc2/<emulator>.rsc on Mac OS X, or %USERPROFILE%\.qmc2\<emulator>.rsc on Windows). If QMC2 finds cached ROM state information in this file, it will read the states for each machine from the cache when the machine list is reloaded.

Unless the option AutoTriggerROMCheck 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). If the number of totally supported machines (by the emulator) 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).

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

ROM states can be used to filter and/or sort the detailed machine list (a.k.a. the master list). Please note that as a matter of principle the ROM state filter can't be applied to the hierarchical parent/clone view of the machine list, because the display of clones depends on the display of their parents. The optional views 'by version' and 'by category' (which are only available when the use of catver.ini and/or MESS category.ini has been enabled) are also not filtered.

ROMAlyzer

Since v0.2.b1, there is also a so called ROMAlyzer which allows to deeply scan individual (or multiple) 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!

Please refer to the ROMAlyzer section in our wiki for detailed information!

### 5. Short cuts, GUI control keys and joystick support

Many functions in QMC2 can be accessed via short cut key-sequences which can be remapped freely. See this section in our wiki for a list of the available short cuts and their default key sequences.

Beside this list, remapping includes some special keys (like all cursor keys, page up/down, tab, +/-, ...) that are required for GUI control through key-strokes. The ability to remap key sequences should be very handy for users of MAME cabinets with sticks that map their controls to key-strokes (X-Arcade controls for example). Of course, 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.

However, there are two exceptions to this rule:

- For embedded emulators, mixing / sharing the joystick control between QMC2 and an emulator is not supported (well, not recommended)
- When QMC2 is in joystick test- or calibration-mode, it will not only receive all joystick events, but also react on them with widget updates. This is not really a problem and could be used for debugging purposes, but should normally be avoided because it eats some CPU cycles for no real use.

### 6. External tools and tool argument syntax

External tools are used for specific operations which aren't natively built into QMC2.

For instance, to remove obsolete or corrupt image files from ZIP or 7z archives, QMC2 uses an external program (zip or 7za) and passes the files to be removed on the argument list when the tool is started.

A third and more generic tool - the so called ROM tool - can be used to call any program or script which does some external processing based on the machine's ID and/or its long name (description). It's completely up to you what this tool might do... ideally, it should have some ROM management / ROM related functionality, though :).

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:

Macro | Will be replaced with... | Valid tools
$ARCHIVE$ | ... the currently processed ZIP or 7z archive's file name (fully qualified) | Zip tool, 7-zip tool
$FILELIST$ | ... the currently processed list of files ("file1 file2 ..." - fully qualified) | Zip tool, 7-zip tool
$ID$ | ... the ID of the currently selected machine | ROM tool
$DESCRIPTION$ | ... the long name (or description) of the currently selected machine | ROM tool

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

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

### 7. Multi-platform support

As the front end code has been designed with portability in mind, QMC2 should work on any UNIX or UNIX-like platform, on Mac OS X and meanwhile also on Windows, provided Qt 4 and (SDL)MAME 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 8.). 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 9.).

### 8. Contact

Project homepage:

- http://qmc2.batcom-it.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

Bug tracking system:

- http://tracker.batcom-it.net/view_all_bug_page.php?project_id=1

Individual team members:

- http://wiki.batcom-it.net/index.php?title=Development_team_and_contributors

### 9. 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
- Useful feedback and ideas

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.

### 10. License and copyright

QMC2 - M.A.M.E. Catalog / Launcher II
Copyright © 2006 - 2016 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.

See copying.html for the GNU General Public License.

3rd party software used in this project

zlib 1.2.8
Copyright © 1995 - 2013 Jean-loup Gailly and Mark Adler. All rights reserved.
http://zlib.net/

minizip
Copyright © 1998 - 2010 Gilles Vollant. All rights reserved.
Copyright © 2013 - 2016 Nathan Moinvaziri. All rights reserved.
http://github.com/nmoinvaz/minizip

The Ghostbusters Logo
Copyright © 1984 Columbia Pictures Industries, Inc. All rights reserved.

HTML editor from Qt Labs / graphics-dojo
Copyright © 2011 The Qt Project. All rights reserved.
http://qt.gitorious.org/qt-labs/graphics-dojo

PDF.js -- JavaScript / HTML5 PDF rendering library
Copyright © 2012 - 2016 Mozilla Foundation. All rights reserved.
https://github.com/mozilla/pdf.js

txt2man 1.5 -- text to man page converter script
Copyright © 2001 - 2003 Marc Vertes. All rights reserved.
http://mvertes.free.fr/txt2man/txt2man

LZMA SDK 9.22 -- LZMA (7-zip) data compression/decompression library
Copyright © 1999 - 2012 Igor Pavlov. All rights reserved.
http://www.7-zip.org/sdk.html

Subset of the QtFtp add-on for Qt 5
Copyright © 2012 - 2013 Digia Plc. All rights reserved.
http://code.qt.io/cgit/qt/qtftp.git/

### 11. 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.