### FAQ - v0.2.b2, 05-MAY-2008

### Questions

Build, installation and development issues

Q1.1: QMC2 needs Qt 4, but my (Linux) distribution only comes with Qt 3. What should I do about that?

Q1.2: Aren't there any binary packages on the net?

Q1.3: I want to be at the cutting edge of QMC2 development. How do I access your development code base?

Q1.4: Why aren't you using autoconf/automake (configure)?

Q1.5: My (Linux) distribution already comes with a binary Qt 4 package, but the build fails. It complains about a wrong version of qmake or can't find it. What's wrong?

Q1.6: How do I know about the available make targets and build configuration options?

Q1.7: Build and installation instructions for specific distributions

Q1.7.1: Ubuntu / Kubuntu 7.04, 7.10

Q1.7.2: openSUSE 10.3

Q1.7.3: Fedora release 8

Q1.8: The build fails due to compiler errors regarding the accessibleName property used in mameopt.cpp

Q1.9: The standard icons of QMC2 are boring. Can I use alternate icon sets?

Q1.10: How do I create an alternate icon set for QMC2?

Usage, tips & tricks

Q2.1: When the gamelist reloads, the insertion of games is fairly slow. Is there a way to somehow speed it up?

Q2.2: How do I use the search feature?

Q2.3: What are the typical CPU & memory requirements?

Q2.4: What image formats are supported for in-game screenshots (previews), flyers & icons?

Q2.5: What do I have to do to make QMC2 access my image & icon collections?

Miscellaneous FAQs, known bugs outside of QMC2 etc.

Q3.1: QMC2 doesn't determine the ROM state. What's wrong?

Q3.2: ROM state filtering takes veeeery long. What's up?

Q3.3: QMC2 crashes with a segmentation fault when I click the browse buttons of certain file settings (options dialog)

### Answers

Q1.1: QMC2 needs Qt 4, but my (Linux) distribution only comes with Qt 3. What should I do about that?

First of all, don't worry. Regardless if Qt 4 is already installed or not, Qt 3 and Qt 4 (as any versions of Qt) can be used in parallel. You only need to take care of some environment variables as described in the build instructions of readme.html.

If you need to build Qt 4 from source, please follow these steps:

1) Download the latest source archive of Qt 4.3.x from Trolltech's FTP server (ftp://ftp.trolltech.com/qt/source/), for example qt-x11-opensource-src-4.3.3.tar.gz.

2) Extract this tar-ball to a directory where you are going to build it, then configure and build it completely:

    # mkdir -p src && cd src
    # gzcat /tmp/qt-x11-opensource-src-4.3.3.tar.gz | tar xfv -
    # cd qt-x11-opensource-src-4.3.3
    # ./configure -platform linux-g++ -prefix /usr/local/lib/qt4
    # make

Exchange the values for -platform and -prefix with things that fit your needs (the example is for a 32-bit Linux distribution)!

3) Install the library (it will be installed to the prefix-directory specified on the configure command line!):

    # make install

This is VERY important for Qt 4 (whereas in case of Qt 3 this wasn't neccessary)!

Now, following the instructions of readme.html, you are able to build and use QMC2!!

Q1.2: Aren't there any binary packages on the net?

Binary packages for the Fedora / Fedora Core projects are available at:

- Dribble Repository - http://dribble.org.uk - thanks to Christopher Stone

Debian packages:

- Inofficial .deb packages - see forum thread at http://www.bannister.org/forums/ubbthreads.php?ubb=showflat&Number=27096 (the package appears not to be updated any longer)

Binary packages for FreeBSD are available through pkg_add:

- pkg_add -r qmc2

ZXMameCD - Armin Schmidhuber's cool MAME Live CD - uses QMC2 as its frontend:

- ZXMameCD - http://zxmamecd.worldofretro.net

RPM based distributions:

- Search QMC2 at rpm.pbone.net for several RPM based distributions - http://rpm.pbone.net/index.php3?search=qmc2&stat=3

Binary packages for other platforms or distributions may be available, but aren't known to us at the time of this writing.

Q1.3: I want to be at the cutting edge of QMC2 development. How do I access your development code base?

We are using Subversion (SVN) for the code repository during development.

To checkout the latest revision of the source code, use the following command sequence (you have to checkout the code only once!):

    $ mkdir -p ~/src && cd ~/src
    $ svn co https://qmc2.svn.sourceforge.net/svnroot/qmc2 qmc2
    $ cd qmc2 && make ...
    $ su
    Password:
    # make install

Later, if you need to update your local working copy, use the svn update command:

    $ cd ~/src/qmc2
    $ svn update
    $ make clean && make ...
    $ su
    Password:
    # make install

Please note that code from the SVN repository may be in an incomplete or even unstable state as it is code under development. At some point in time - when several new features were incorporated and the code base stabalizes again - we decide to pick a specific SVN release and publish it as the final release of a respective version. File releases should be more or less working fine and can be considered as stable, which does not neccessarily mean that they are bug-free :).

Q1.4: Why aren't you using autoconf/automake (configure)?

Because QMC2 is a Qt based project. We use qmake instead, which fits better in this case and has equivalent functionality in regard of automatic platform configuration.

Everything else - that is, build or installation commands which are outside the scope of how we use qmake - is under control of make rules and handled through architecture specific configuration files, which are stored in the arch/ directory.

See readme.html (multi-platform support) for more information!

Q1.5: My (Linux) distribution already comes with a binary Qt 4 package, but the build fails. It complains about a wrong version of qmake or can't find it. What's wrong?

The build configuration for your local setup is most likely wrong.

As discussed in readme.html (multi-platform support) you should either change the selected configuration (probably arch/Linux.cfg) to your local situation or make use of a distribution-specific configuration (if that exists).

To figure out what the right configuration file(name) for your OS & distribution is, run

    $ make os-detect

and note the configuration file(name) which is reported in the last line. Make sure it exists; if not, create this file (copy from another configuration or symbolically link to an existing one).

Now retry to build QMC2 with the use of the newly created distribution-specific configuration:

    $ make DISTCFG=1

If make is called this way, it will first try to load the global OS configuration settings from arch/`uname`.cfg (same as without DISTCFG=1) and then overwrite the settings with options specified in the distribution-specific configuration file (arch/`uname`/<distribution>.cfg). Obviously, you only need to overwrite those settings which are specific to your distribution and different from the global OS configuration.

Note that you have to specify DISTCFG=1 on every call to make if you need a distribution-specific setup, especially also for make install:

    # make install DISTCFG=1

If you want to know what settings will be used during the build, run

    $ make config [DISTCFG=1]

Also make sure by means of your OS or distribution (rpm, yum, apt, rug, pkginfo, whatever...) that the installed Qt 4 version is really sufficient (see readme.html for software requirements). You'll need the Qt 4 core libraries and the development packages.

Here's an example for an RPM-based distribution (openSUSE 10.3):

    # rpm -qa | grep libqt4
    libqt4-sql-4.3.1-23
    libqt4-x11-4.3.1-23
    libqt4-sql-sqlite-4.3.1-8
    libqt4-devel-doc-data-4.3.1-22
    libqt4-4.3.1-23
    libqt4-devel-doc-4.3.1-23
    libqt4-devel-4.3.1-23
    libqt4-qt3support-4.3.1-23
    libqt4-dbus-1-4.3.1-23
    libqt4-sql-mysql-4.3.1-8

Underlined packages are required for QMC2 to build and/or run. The library versions may differ, though (Qt 4.3.0 and above).

Q1.6: How do I know about the available make targets and build configuration options?

Run

    $ make help

for more information.

Q1.7: Build and installation instructions for specific distributions

This FAQ section lists the commands used to build QMC2 on several distributions which provide Qt 4 libraries themselves.

If you should have built Qt from source, please follow the steps in readme.html instead, which are basically the same for all OSs / distributions.

Q1.7.1: Ubuntu / Kubuntu 7.04, 7.10

To build and install QMC2 from source (SVN) on Ubuntu / Kubuntu 7.04 (Feisty Fawn, Debian 4.0) or 7.10 (Gutsy Gibbon, Debian lenny/sid) using their provided Qt 4.3 packages, follow these steps:

1) Install the required packages (including their dependencies)

    $ sudo apt-get install subversion g++ libqt4-dev

2) Either check out the source code from SVN

    $ mkdir ~/src; cd ~/src
    $ svn co https://qmc2.svn.sourceforge.net/svnroot/qmc2 qmc2
    $ cd qmc2

or update the source code to the latest SVN release

    $ cd ~/src/qmc2
    $ svn update

3) Build and install QMC2 with distribution-specific configuration turned on

    $ make DISTCFG=1
    $ sudo make install DISTCFG=1

Notes:

- Gutsy Gibbon comes with Qt 4.3.2, which is buggy. Please see Q3.2!

Q1.7.2: openSUSE 10.3

To build and install QMC2 from source (SVN) on openSUSE 10.3 using the provided Qt 4.3 packages, follow these steps:

1) Install the required packages (including their dependencies)

    $ su -
    Password:
    # zypper install subversion g++ libqt4 libqt4-devel libqt4-x11
    # logout

2) Either check out the source code from SVN

    $ mkdir ~/src; cd ~/src
    $ svn co https://qmc2.svn.sourceforge.net/svnroot/qmc2 qmc2
    $ cd qmc2

or update the source code to the latest SVN release

    $ cd ~/src/qmc2
    $ svn update

3) Build and install QMC2 with distribution-specific configuration turned on

    $ make DISTCFG=1
    $ su
    Password:
    # make install DISTCFG=1
    # logout

Q1.7.3: Fedora release 8

To build and install QMC2 from source (SVN) on Fedora release 8 using the provided Qt 4.3 packages, follow these steps:

1) Install the required packages (including their dependencies)

    $ su -
    Password:
    # yum install subversion gcc-c++ qt4 qt4-devel
    # logout

2) Either check out the source code from SVN

    $ mkdir ~/src; cd ~/src
    $ svn co https://qmc2.svn.sourceforge.net/svnroot/qmc2 qmc2
    $ cd qmc2

or update the source code to the latest SVN release

    $ cd ~/src/qmc2
    $ svn update

3) Build and install QMC2 with distribution-specific configuration turned on

    $ make DISTCFG=1
    $ su
    Password:
    # make install DISTCFG=1
    # logout

Q1.8: The build fails due to compiler errors regarding the accessibleName property used in mameopt.cpp

If you see compiler errors similar to the following, please make sure that Qt Accessibilty has been enabled in your version / build of Qt!

    mameopt.cpp: In member function 'virtual QWidget* MameOptionDelegate::createEditor(QWidget*, const QStyleOptionViewItem&, const QModelIndex&) const':
    mameopt.cpp:50: error: 'class QComboBox' has no member named 'setAccessibleName'
    mameopt.cpp:61: error: 'class QSpinBox' has no member named 'setAccessibleName'
    ...

Qt Accessibility is enabled by default and should really not harm in any way, but for strange and unknown reasons some binary Qt packages have it disabled. This has been seen on Gentoo, for example.

If this should be the case, please contact the package maintainer to change this and / or build Qt from source (recommended anyway :).

Q1.9: The standard icons of QMC2 are boring. Can I use alternate icon sets?

Yes. Since QMC2 v0.1.b11 there is support for alternate icon sets. You cannot switch them on-the-fly, though. QMC2 needs them built-in (most of them, only the ROM status icons are loaded dynamically).

Icon sets are stored below the data/img/ directory (data/img/<icon-set-directory>):

    $ cd ~/src/qmc2
    $ find data/img/ -maxdepth 1 -mindepth 1 -type d
    data/img/classic
    data/img/crazy-black
    data/img/crazy

The classic icon set is the default.

To rebuilt QMC2 with a different icon set, use the make command line option IMGSET as in the following example:

    $ make clean
    $ make IMGSET=crazy
    ...

Please don't forget to reinstall QMC2:

    $ su
    Password:
    # make install
    ...

Q1.10: How do I create an alternate icon set for QMC2?

Create a new directory below data/img/ for your icon set:

    $ cd ~/src/qmc2
    $ mkdir data/img/myIconSet

Create your icon images with any image creator / manipulator (i. e. The Gimp) and save them in PNG format. Make sure you use the exact same filenames as in the classic image set, and try to keep the icons the same size as their classic-pendants.

Images (from classic) you would like to reuse in your icon set don't need to be copied. Just create a symbolic link to its original:

    $ cd data/img/myIconSet
    $ ln -s ../classic/qt-logo.png qt-logo.png
    ...

If all went well, a simple rebuild of QMC2 with your image set as the value of the IMGSET parameter should do the trick:

    $ make clean
    $ make IMGSET=myIconSet
    ...

Don't forget to reinstall QMC2:

    $ su
    Password:
    # make install
    ...

Please send us your icon set so we can publish it with QMC2!

Q2.1: When the gamelist reloads, the insertion of games is fairly slow. Is there a way to somehow speed it up?

The short answer is yes :).

There are several ways to speed this up. The easiest and most effective is to hide the gamelist while reload is active (simply click on the Search tab for example and you'll get a tremendous speed-up).

The second thing to check is if you are sorting the gamelist while reload is active (see Frontend / Gamelist option Sort online); if so, disable it.

And last but not least - on the same configuration-page - there is an option called Responsiveness which lets you decide after how many game-insertions an update to the gamelist(-widget) is made. You will have to play with it.

Since QMC2 v0.1.b11, the analysed data from a gamelist reload is automatically cached and will be reused as long as the MAME version doesn't change. The result is a tremendous speed up for this process, which will be even greater if you set the responsiveness parameter a bit higher (250 - 500, for example).

Q2.2: How do I use the search feature?

The game search is a normal Qt based wildcard search that adds implicit globs (*) around each word which can be negated by using ^ for the start of a word or $ for using the end of the word.

For example, typing "s f z a j" results in "Street Fighter Zero 2 Alpha (Japan)". As you can see this allows you to navigate to specific games with a minimum number of keystrokes. If you want to find the "CV version" of space invaders, all you have to type is "s i cv".

To negate the use of the implicit glob from the start of a word use ^, and to negate it from the end of a word use $. For example, "^a" will match all games that start with the letter A.

Other wildcard characters such as * and ? may also be used. * will match anything while ? matches any single character. For example, "ab*c" will match any game that has an AB followed by a C, whereas "ab?c" will match any game that has an AB followed by some character and then a C.

Be sure to spend some time experimenting with the search feature, you will find that with practice you can navigate to any game you want with very few keystrokes.

Q2.3: What are the typical CPU & memory requirements?

Any recent x86 or x86_64 system should be okay for QMC2 and SDLMAME. It may look different on other platforms, though.

Regarding memory requirements, QMC2 typically uses 110 - 140 MB sustained resident memory. When reloading the gamelist, QMC2 additonally needs ~ 50 MB as a temporary buffer. The amount of memory required highly depends on the number of supported games and the sizes of the image and icon caches. So it may look different for you.

When using the ROMAlyzer to analyze ROMs and CHDs of all games, resident memory consumption can grow up to ~ 470 MB (the analysis report and log are stored in memory until they are cleared).

The numbers were measured with QMC2 0.2.b1 and SDLMAME 0.123u4 (7022 games).

Q2.4: What image formats are supported for in-game screenshots (previews), flyers & icons?

Portable Network Graphics (PNG) is the only image format supported by QMC2!

This is true for icons as well which are normally in ICO format - you'll need to convert them to PNGs before they can be used with QMC2.

Q2.5: What do I have to do to make QMC2 access my image & icon collections?

QMC2 can handle previews, flyers and icons stored in directories or ZIP archives.

Every image file (or ZIP entry) must be named exactly as the corresponding game's short name, followed by the lower-case file extension ".png" (for example galaga.png or 1945kiii.png).

The use of ZIP archives requires a flat directory structure (= no sub-directories!). This is true for image directories as well, with the exception of previews: to support the direct use of in-game screenshots created with MAME, QMC2 also tries to find preview images in sub-directories of the preview-directory which are named as <gamename>/XXXX.png (XXXX = 0000 - 9999). The file with the highest number will be used, but only if <gamename>.png wasn't found in the base preview-directory before. Note that for this to work, it is also required to setup the snapshot_directory of MAME to the directory where your previews are stored! See MAME -> Global configuration in the setup dialog to synchronize that.

Make sure the access permissions to all image files and directories are setup correctly!

See Frontend -> Files / Directories in the setup dialog to modify the image paths, apply your changes and the images should be available to QMC2 right away (you'll have to clear the icon cache and trigger a reload of the gamelist to also load the icons, though).

For best performance, we recommend to store icons in a ZIP archive, and to store previews & flyers directory based. Icons are usually small, so reading one big file at once is much faster than reading many little files. In contrast to previews or flyers which are loaded on demand (and stored in a least recently used cache), icons will be pre-loaded in one step, so it has major impact on the startup of QMC2.

Q3.1: QMC2 doesn't determine the ROM state. What's wrong?

There are at least three possible scenarios:

1. Symptom: all games are in an unknown state (blue)
   Probable reason: you didn't trigger a ROM check
   Solution: see Tools -> Check ROMs in the menu to trigger a ROM check.
2. Symptom: all games are in an unknown state (blue)
   Probable reason: the ROM state cache file cannot be read or written
   Solution: see Tools -> Options -> Frontend -> ROM state cache and check your access permissions to that file.
3. Symptom: no games were found (grey)
   Probable reason: the ROM path isn't setup correctly
   Solution: Check the rompath-setting in your global MAME options (see Tools -> Options -> MAME -> Global configuration)!
   For SDLMAME see Search paths.
   Apply your changes and retry the ROM check!

Please also check the frontend log for FATAL or WARNING messages!

Q3.2: ROM state filtering takes veeeery long. What's up?

You're most likely using Qt 4.3.2.

Qt 4.3.2 is known to have a bug which slows down the process of hiding items in a QTreeWidget (or QTreeView).

Use a different version of Qt! Trolltech promised to include the fix in Qt 4.3.3 and above (update: yes, the fix is included since!). A temporary fix for Qt 4.3.2 is available from the QMC2 homepage (http://www.mameworld.net/mamecat/)

Q3.3: QMC2 crashes with a segmentation fault when I click the browse buttons of certain file settings (options dialog)

You're most probably hitting a bug of Qt 4.3.x's QFileDialog class, which crashes when a hidden directory is passed to it (when a directory component of the file's path starts with a dot as in /home/user/.qmc2/qmc2.tmp).

As a workaround, you may either edit the file settings manually (and don't browse for these files) and / or change the corresponding directory names.

If you insist on using the file browsers, you'll have to wait for a fix for Qt 4.3.x which will hopefully be available soon.

The bug exists for at least these versions of Qt: 4.3.2 and 4.3.3 (not sure about 4.3.0 and 4.3.1, though). If you should be using a different version of Qt, please let us know!

Trolltech meanwhile confirmed the bug and fixed it for Qt 4.3.4!