FAQ - v0.1.b10, 20-JUL-2007

Questions

1. 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 process 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?

2. 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?

3. Miscellaneous FAQs

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


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.2.x from Trolltech's FTP server (ftp://ftp.trolltech.com/qt/source/), for example qt-x11-opensource-src-4.2.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.2.3.tar.gz | tar xfv -
# cd qt-x11-opensource-src-4.2.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 Core project are available at:

Debian packages:

A binary package for FreeBSD is available through pkg_add:

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

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 Makefile 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 process 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 symbolicly 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.2):

# rpm -qa | grep -i libqt4
libqt4-sql-4.2.1-18
libqt4-sql-sqlite-4.2.1-7
libqt4-dbus-1-4.2.1-18
libqt4-sql-unixODBC-4.2.1-7
libqt4-devel-doc-4.2.1-18
libqt4-4.2.1-20
libqt4-devel-4.2.1-20
libqt4-devel-doc-data-4.2.1-7
libqt4-sql-mysql-4.2.1-7
libqt4-x11-4.2.1-20
libqt4-qt3support-4.2.1-18
libqt4-sql-postgresql-4.2.1-7

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


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

Run

$ make help

for more information.


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. But first of all you need to understand that the most time-consuming part of it is the insertion in the tree-widget itself (so the reason is GUI updates, not the internal management of the data).

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 (this setting is relevant for the reload of the entire gamelist and for pixmap updates caused by the preview-check). However, you will have to play with it (and get used to it).


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.


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. For XMAME, see File I/O.
    Apply your changes and retry the ROM check!

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