QMC2 FAQ

From BATCOM-IT Services Wiki
Jump to: navigation, search

Frequently asked questions about QMC2

Contents


Building, installing and development

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 check out the latest revision of the source code, use the following command sequence (you have to check out the code only once!):

$ mkdir -p ~/src && cd ~/src
$ svn co https://svn.code.sf.net/p/qmc2/code/trunk 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, often not widely tested yet. We try to keep the SVN repository up to date with the latest developments in MAME's github repository. It can happen that a recent development revision of MAME is even required in order to run recent code from QMC2 SVN! So if you go this route we actually recommend to use the latest SVN revisions from both QMC2 and MAME.

See our current change-log for detailed information about recent changes in SVN.

To provide the community with good working combinations of QMC2 and MAME, we are striving hard to align QMC2 releases with MAME releases. Although we can't guarantee this in all cases, it's generally a nice approach for not-so-adventurous users and package maintainers. For quite some time now, we are releasing a new stable version each time a new stable MAME version gets released -- usually within hours or days!

Why aren't you using autoconf/automake (configure)?

Because QMC2 is a Qt based project. We use qmake instead which fits better in this environment and has equivalent functionality with regard to automatic platform configuration (and it's guaranteed to work everywhere where Qt can live).

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.

My (Linux/UNIX) 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 the README (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 building QMC2 with 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 for software requirements).

How do I know about the available make targets and build configuration options?

From the top-level QMC2 source directory, run

$ make help

to get a list of all available make targets.

Build configuration options including their active values are shown when you run

$ make config

Aren't there any binary packages on the net?

Yes. See http://qmc2.batcom-it.net/index.php/download/#binaries for a list of known packages.

This list may not be complete, though. If you know of any binary packages that are missing, please contact us!

Build and installation instructions for specific distributions

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

Although QMC2 will run out-of-the-box with the Qt libraries provided by these distributions, we always recommend to build Qt from source to circumvent potential issues of their Qt packages (see notes below, if applicable). In this case please follow the steps as described in the general build instructions which are basically the same for all distributions.

The distributions mentioned here are the ones we've successfully tested -- QMC2 includes distribution specific build rules for all of them. To activate these rules, you'll have to specify DISTCFG=1 on every call to make (you can alternatively set this as an environment variable or edit the Makefile to change the default which is DISTCFG=0).

The following instructions generally work for code from the SVN repository as well as for stable QMC2 releases (which are distributed as source code tar-balls). The reason why the examples use SVN is simply that the code is more up to date :). Just leave out step 2 if you're going to use a released tar-ball instead (in this case you could also leave out the installation of the SVN client, of course).

The details...

Debian

To build and install QMC2 from source (SVN) on

  • Debian GNU Linux 8

using their provided Qt packages, please follow these steps:

1. Install the required packages (including their dependencies)

$ sudo apt-get install subversion g++ libqt4-dev libsdl2-dev libphonon-dev libxmu-dev libqt4-sql-sqlite rsync

(replace libsdl2-dev with libsdl-dev for SDL1)

2. Either check out the source code from SVN

$ mkdir ~/src; cd ~/src
$ svn co https://svn.code.sf.net/p/qmc2/code/trunk qmc2
$ cd qmc2

or update the source code to the latest SVN revision

$ cd ~/src/qmc2
$ svn update

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

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

4. Clean up the source tree

$ make distclean DISTCFG=1

5. Optionally build & install QMC2 Arcade:

$ make arcade DISTCFG=1
$ sudo make arcade-install DISTCFG=1

Note that in order to run QMC2 Arcade you have to additionally install the shaders and particles modules, and qt-mobility for video snap support:

$ sudo apt-get install libqt4-declarative-shaders libqt4-declarative-particles qtmobility

6. Optionally build & install Qt CHDMAN GUI:

$ make qchdman DISTCFG=1
$ sudo make qchdman-install DISTCFG=1

7. Optionally convert & install the man-pages:

$ make man
$ sudo make man-install

Ubuntu

To build and install QMC2 from source (SVN) on

  • Ubuntu 14.04 (Trusty Tahr)
  • Ubuntu 14.10 (Utopic Unicorn)
  • Ubuntu 15.04 (Vivid Vervet)
  • Ubuntu 15.10 (Wily Werewolf)
  • Ubuntu 16.04 (Xenial Xerus)
  • Ubuntu 16.10 (Yakkety Yak)

using their provided Qt packages, please follow these steps:

1. Install the required packages (including their dependencies)

$ sudo apt-get install subversion g++ libqt4-dev libqtwebkit-dev libphonon-dev libsdl2-dev libxmu-dev libqt4-sql-sqlite rsync

(replace libsdl2-dev with libsdl-dev for SDL1)

2. Either check out the source code from SVN

$ mkdir ~/src; cd ~/src
$ svn co https://svn.code.sf.net/p/qmc2/code/trunk qmc2
$ cd qmc2

or update the source code to the latest SVN revision

$ cd ~/src/qmc2
$ svn update

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

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

4. Clean up the source tree

$ make distclean DISTCFG=1

5. Optionally build & install QMC2 Arcade:

$ make arcade DISTCFG=1
$ sudo make arcade-install DISTCFG=1

Note that in order to run QMC2 Arcade you have to additionally install the shaders and particles modules, and qt-mobility for video snap support:

$ sudo apt-get install libqt4-declarative-shaders libqt4-declarative-particles qtmobility-dev

6. Optionally build & install Qt CHDMAN GUI:

$ make qchdman DISTCFG=1
$ sudo make qchdman-install DISTCFG=1

7. Optionally convert & install the man-pages:

$ make man
$ sudo make man-install

openSUSE

To build and install QMC2 from source (SVN) on

  • openSUSE 13.1
  • openSUSE 13.2
  • openSUSE Leap 42.1
  • openSUSE Leap 42.2
  • openSUSE Factory
  • openSUSE Tumbleweed

using their provided Qt packages, follow these steps:

1. Install the required packages (including their dependencies)

$ su -
Password:
# zypper install subversion gcc make libqt4 libqt4-devel libqt4-x11 libSDL2-devel libkde4-devel libqt4-sql-sqlite rsync
# logout

(replace libSDL2-devel with libSDL-devel for SDL1)

Note:

  • The libkde4-devel package is only needed if you want to use Phonon features (built-in audio & video players). If you don't want to use it, make sure to add PHONON=0 on the make command line in step 3. and all Phonon features will be cut off from the build!

2. Either check out the source code from SVN

$ mkdir ~/src; cd ~/src
$ svn co https://svn.code.sf.net/p/qmc2/code/trunk qmc2
$ cd qmc2

or update the source code to the latest SVN revision

$ 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

4. Clean up the source tree

$ make distclean DISTCFG=1

5. Optionally build & install QMC2 Arcade:

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

Note that you have to additionally install qt-mobility for video snap support:

$ su -
Password:
# zypper install qt-mobility
# logout

6. Optionally build & install Qt CHDMAN GUI:

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

7. Optionally convert & install the man-pages:

$ make man
$ su
Password:
# make man-install
# logout

Note:

  • Some KDE4 styles that come with openSUSE cause troubles such as single-click activation of machines. Select a different GUI style or change the style settings!

Fedora

To build and install QMC2 from source (SVN) on

  • Fedora Release 24
  • Fedora Release 25
  • Fedora Release 26
  • Fedora Rawhide (27)

using their provided Qt packages, follow these steps:

1. Install the required packages (including their dependencies)

$ su -
Password:
# yum install subversion gcc-c++ qt4-devel qt-webkit-devel libXmu-devel SDL2-devel phonon-devel rsync
# logout

(replace SDL2-devel with SDL-devel for SDL1)

Note:

  • yum is deprecated in newer Fedora versions - replace yum in the above command line with dnf in this case!

2. Either check out the source code from SVN

$ mkdir ~/src; cd ~/src
$ svn co https://svn.code.sf.net/p/qmc2/code/trunk qmc2
$ cd qmc2

or update the source code to the latest SVN revision

$ 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

4. Clean up the source tree

$ make distclean DISTCFG=1

5. Optionally build & install QMC2 Arcade:

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

6. Optionally build & install Qt CHDMAN GUI:

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

Note that you have to additionally install qt-mobility for video snap support:

$ su -
Password:
# yum install qt-mobility
# logout

7. Optionally convert & install the man-pages:

$ make man
$ su
Password:
# make man-install
# logout

Arch Linux

To build and install QMC2 from source (SVN) on

  • Arch Linux

using their provided Qt packages, follow these steps:

1. Install the required packages (including their dependencies)

$ sudo pacman -S gcc qt4 phonon-qt4 rsync subversion sdl2 mesa qtwebkit

(replace sdl2 with sdl for SDL1)

2. Either check out the source code from SVN

$ mkdir ~/src; cd ~/src
$ svn co https://svn.code.sf.net/p/qmc2/code/trunk qmc2
$ cd qmc2

or update the source code to the latest SVN revision

$ cd ~/src/qmc2
$ svn update

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

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

4. Clean up the source tree

$ make distclean DISTCFG=1

5. Optionally build & install QMC2 Arcade:

$ make arcade DISTCFG=1
$ sudo make arcade-install DISTCFG=1

Note that video snap support in QMC2 Arcade will likely not work on Arch Linux as there doesn't seem to exist a qt-mobility package.

6. Optionally build & install Qt CHDMAN GUI:

$ make qchdman DISTCFG=1
$ sudo make qchdman-install DISTCFG=1 

7. Optionally convert & install the man-pages:

$ make man
$ sudo make man-install

Mac OS X

To build and install QMC2 from source (SVN) on

  • Mac OS X 10.6 (Snow Leopard)
  • Mac OS X 10.7 (Lion)
  • Mac OS X 10.8 (Mountain Lion)
  • Mac OS X 10.9 (Mavericks)
  • Mac OS X 10.10 (Yosemite)
  • Mac OS X 10.11 (El Capitan)
  • Mac OS X 10.12 (macOS Sierra)

follow these steps:

1. Install the required packages / frameworks

  • XCode: install Xcode from the Mac OS X install DVD and/or download/update it to the latest version -- note that we do no longer support building QMC2 through XCode itself (since this doesn't work in case of XCode 4+), but command line tools (make, gcc/g++ etc.) and libraries that come with it are still required!
  • SDL 2.0 framework: download and install the latest version of the SDL framework (SDL2-2.0.5.dmg)

Mac OS X 10.6 - 10.10:

Mac OS X 10.11 - 10.12:

  • Install Homebrew with the following command:
$ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
  • Once Homebrew's base packages are installed, install Qt 4.8 with the following command:
$ brew install qt4

2. Either check out the source code from SVN

$ mkdir ~/src; cd ~/src
$ svn co https://svn.code.sf.net/p/qmc2/code/trunk qmc2
$ cd qmc2

or update the source code to the latest SVN revision

$ cd ~/src/qmc2
$ svn update

3. Build and install QMC2 (the make rules will auto-detect that this is Mac OS X)

$ make
$ sudo make install

4. Clean up the source tree

$ sudo make distclean

5. Optionally build & install QMC2 Arcade:

$ make arcade
$ sudo make arcade-install
$ sudo make distclean

6. Optionally build & install Qt CHDMAN GUI:

$ make qchdman
$ sudo make qchdman-install
$ sudo make distclean

7. Optionally convert & install the man-pages (requires GNU awk (gawk) from MacPorts!):

$ make man
$ sudo make man-install

Note:

  • For universal builds (ppc/ppc64 and x86/x86_64 architectures combined) you have to add MAC_UNIVERSAL=1 to all make commands above!

Windows

To build / install / deploy QMC2 from source on Windows (XP, Vista, 7, 8, 8.1 and 10), please see here:

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

Yes, there's support for alternate icon sets. You cannot switch them on-the-fly, though, QMC2 needs them built-in (embedded in the binary).

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/circles
data/img/classic
data/img/crazy
data/img/crazy-black
data/img/cubes

The classic icon set is the default.

To rebuild 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
...

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 file names 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!

Is it possible to use distributed compilation (distcc / icecc) and/or a compiler cache (ccache)?

Yes. At least on Linux there's this option when you have distcc / icecc or ccache installed. All you have to do is set the make options DISTCC or CCACHE to 1, however, note that you cannot set both options to 1 at the same time (and if you do so both options will be automatically disabled again). Additionally, you can overwrite the commands behind it through the options DISTCC_CC / DISTCC_CXX and CCACHE_CC / CCACHE_CXX:

Example using ccache:

$ make -j5 CCACHE=1 CCACHE_CC='ccache cc' CCACHE_CXX='ccache c++'

Example using icecc (icecream):

$ make -j15 DISTCC=1 DISTCC_CC='icecc' DISTCC_CXX='icecc'

Or with distcc:

$ make -j15 DISTCC=1 DISTCC_CC='distcc cc' DISTCC_CXX='distcc c++'

Despite the restriction of not using DISTCC and CCACHE in parallel, these slightly more sophisticated command lines should still allow for doing this (both untested):

$ make -j15 CCACHE=1 CCACHE_CC='ccache icecc' CCACHE_CXX='ccache icecc'
$ make -j15 CCACHE=1 CCACHE_CC='ccache distcc cc' CCACHE_CXX='ccache distcc c++'

In case of using ccache, put the compiler-cache folder (~/.ccache) onto an SSD, or generally on fast storage, if possible!

Why is feature/bug XYZ not yet implemented/fixed or completed? When will it be done?

It will be done when it will be done :)! Seriously, please never ask a question like this to developers of a free open source fun project driven by volunteers in their free time. Thanks.

Of course it's OK to request new features, ask for the planned time line or road-map, report bugs (greatly appreciated!) etc., but whatever we might answer, it will always be just plans. We really care about what our users desire, but we can't promise anything, especially no finish dates. However, bugs will have the highest priority and -- if possible -- will be fixed ASAP.

Before you ask or report a bug, please always take a look at the current TODO list and our bug-tracking system!

You may also consider contributing or donating to the project, which both could help to speed things up :).

Otherwise, please consider reading Eric S. Raymond's great How To Ask Questions The Smart Way guide.

Usage, tips and tricks

How do I use the search feature?

The machine search is a normal Qt based wild-card 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 machines 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 machine titles that include words starting with the letter A.

Other wild-card characters such as * and ? may also be used. * will match anything while ? matches any single character. For example, ab*c will match any machine title that contains AB followed by a C, whereas ab?c will match any machine title 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 machine you want with very few keystrokes.

The search string is also matched against the machine-IDs (or short names). So in case of (former) MESS sets, for example, entering a search string like snes would also return valid results.

Since v0.34 the same search method is used for software-lists.

What image or video formats are supported for in-game screenshots (previews), flyers, icons etc.?

As per default, Portable Network Graphics (PNG) is the only image file format searched for by QMC2 for any artwork class. Since v0.40, optional support for additional image file formats has been added, including Windows Bitmap (BMP), Graphic Interchange Format (GIF), Joint Photographic Experts Group (JPG), Portable Bitmap (PBM), Portable Graymap (PGM), Portable Pixmap (PPM), Tagged Image File Format (TIFF), X11 Bitmap (XBM), X11 Pixmap (XPM), Scalable Vector Graphics (SVG) and Targa Image Format (TGA).

Icons are handled specifically and can be stored in any of the aforementioned image file formats, plus ICO format (*.ico) -- there is no default format.

Note that whenever QMC2 produces image files itself, only PNG format will be used.

Provided the relevant codecs are installed on your system, QMC2 can also play YouTube videos which you can attach to each machine individually (requires codecs for MP4 and/or FLV format). This feature includes support for any locally stored movie files as well as video snaps (requires codecs for MP4 and/or AVI format).

What do I have to do to make QMC2 access my image & icon collections?

QMC2 can handle images of in-game screen shots (previews), flyers, cabinets, control panels, marquees, title screens, PCBs, software snap-shots and icons stored in directories, ZIP- or 7z-archives. On top of that you can define as many additional artwork classes as you like since v0.58.

Every image file (or ZIP-/7z-member) must be named exactly as the corresponding lower-case machine's short name (or ID), followed by a valid lower-case file extension (i.e. .png for PNGs). For example, galaga.png or 1945kiii.png would be valid file names.

The use of ZIP- or 7z-archives requires a flat directory structure (= no sub-directories). This is generally also true for image folders, with the exception that for images stored in separate directories the direct use of screen shots created through MAME is supported as well, so QMC2 also tries to find images in sub-directories which are named as <machine-name>/<xxxx>.<fmt> (<xxxx> = 0000 - 9999, <fmt> = any supported and activated image format). The file with the highest number will be used first, but only if <machine-name>.<fmt> wasn't found in the base directory before.

Note that you shouldn't overwrite the default snapshot naming manually (through the emulator's snapname option) if you want QMC2 to find freshly produced in-game screen shots on-the-fly. We currently only support the default naming scheme of MAME for this (<machine-name>/<xxxx>.<fmt>).

Also, make sure that the access permissions to all image files and folders are set up correctly!

Software snap-shots need to be placed in a separate folder, ZIP- or 7z-archive. Its sub-directory structure has to reflect the software list names for which the respective images are valid. For instance, software snap-shots for the gamegear software list have to be stored in a gamegear sub-directory, and image files in that sub-directory must be named exactly as their entry names in the software list, followed by a valid extension (i.e. .png). Again, all file names need to be in lower-case letters. For instance, <software-artwork-folder>/gamegear/aladdin.jpg would be a valid name (provided JPGs are activated). This applies to both the folder- and the ZIP-/7z-based storage of software snaps (in case of a ZIP-/7z-archive <software-artwork-folder> is omitted, of course). Since v0.58 QMC2 will also find software images that are stored folder based when their naming follows the pattern <software-artwork-folder>/<software-list-name>/<software-name>/<xxxx>.<fmt>.

See Front end -> 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 machine list to also load the icons, though). If not, right-click an image and select refresh cache slot from the context-menu to reload the image.

For best performance, we recommend to store icons in a ZIP- or 7z-archive (with little to no compression, i.e. zip -0 icons.zip * or 7za a -mx=0 -ms=off -mhc=off icons.7z *), and to store all other images folder-based / as regular files!

Icons are usually small blobs of data, so reading one big (ZIP or 7z) file at once is usually faster than reading many little files in a row. And in contrast to previews, flyers etc. which are all loaded on demand (and stored in a least recently used image-cache), icons are pre-loaded in one step which has major impact on the start up performance of QMC2 (only when you're using icons, of course).

7-zip specific notes:

  • For image artwork you should disable solid blocks on archive creation (by using the 7za option -ms=off). 7-zip handles every file as its own block of LZMA compressed data in this mode, and this will allow QMC2 to make use of file/block indexes and to decompress contained images on demand. This has the drawback that the overall compression ratio is more like standard ZIP, but the good news is that decompression works even faster than with zipped images. The small prize you pay for this is really worth it! Also, memory consumption stays normal in this mode, that is, very big 7-zip archives created as a solid block will require the complete archive to be decompressed first (occupying the decompressed data's size in bytes of main memory) before the actual image data becomes available. This works but isn't advisable for our use case.
  • For the main GUI, icons should be compressed in 7z's default mode (as a solid block) because they are read all at once anyway.
  • QMC2 Arcade handles icons exactly in the same way as all other images and thus loads them on demand, so in case you're also using QMC2 Arcade it's probably better to use the next approach for icons:
  • Alternatively, choose a relatively small size for the solid blocks to get a better compression ratio while at the same time getting acceptable GUI response. The default size of 4 GB is definitely too high - you shouldn't exceed 16 MB.
  • The optional support for libarchive includes support for 7-zip archives as well, but when 7-zip archives were created with header compression turned on the archives will not be readable by QMC2 through this method. So make sure you turn it off - i. e. use 7za a -ms=off -mhc=off archive.7z * to create an image archive - or use the built-in support for 7-zip which reads those archives even with compressed headers.

When changing the global emulator options, QMC2 sometimes complains about an open machine-specific emulator configuration. What does this mean?

QMC2 uses two emulator configurations for each machine: the global setup and the machine-specific one. The global setup acts as a default configuration for all machines, whereas the machine-specific (or local) configuration may overwrite individual settings for the respective machine.

When you launch a machine or edit its configuration, QMC2 will process all settings in this hierarchical manner (global -> local) and thus open the configuration for the machine in question. It will be kept open until you select a different machine or change the machine-specific settings of another machine (which in this case will be opened instead of the previous machine).

Now, when you change the global emulator configuration while a machine-specific setup is currently open, you will have to decide what to do, because this will change the global defaults. QMC2 will ask you whether to keep the local setup as it is or to overwrite the local setup with the changed global defaults (or to revert the changes made -- don't apply). If unsure, answer with overwrite, because this is most likely what you are aiming to achieve :).

All emulator configurations -- both global and local -- will be saved in the user's QMC2 settings file (usually ~/.qmc2/qmc2.ini or ~/Library/Application Support/qmc2/qmc2.ini on Mac OS X) below the [<emulator>] section ([MAME] in case of MAME for example). See Configuration/Global/... for global settings and Configuration/<machinename>/... for machine-specific ones. Following the above guidelines of the hierarchical configuration scheme, only settings that are different than the respective default will be stored.

See also this FAQ.

I want to use other/older emulators for specific machines. Does QMC2 support that?

Yes. Since version 0.2.b13 we support so called foreign emulators on a per machine basis. That is, we assume MAME-like emulators which use the same machine IDs and ROM sets. It is mainly meant to drive older versions of MAME, specifically XMAME support has been revived through this new feature (though it's basically not limited to MAME).

Note, however, that QMC2's default emulator needs to be one of the officially supported set and that the configuration of foreign emulators is totally up to the user who needs to register each emulator with its (complete) command line options -- including a placeholder for the machine ID! If you omit the ID placeholder ($ID$) in the emulator registration, this mechanism will simply not work.

To add, copy or modify foreign emulators, go to the additional emulators tab in the emulator section of the global setup -- don't forget to apply/save the configuration changes when you're finished! Then select one of these registered emulators in any machine-specific emulator configuration and you're done!

Officially tested (and in this context supported) non-MAME foreign emulators include:

  • XMAME 0.106
  • RAINE 0.51.9

Note for X11 and Windows users:

  • Embedding of foreign emulators may only work correctly if they are close enough to current official versions of MAME (that is, SDLMAME on X11-platforms or 'genuine' MAME on Windows)!

How do I setup any devices to be hooked up to the emulator?

Select the machine you want to emulate, then change to its Devices detail-tab (upper-right) and set up the devices like this:

  • Optional, but recommended: Click the Configuration button and select Default device directory for '<machine-name>'... so you can point QMC2 to a primary directory where you have your cart/rom/bin/whatever files for the current system. This directory will later be presented to you when you browse for device files. You only need to do this once per system, of course (also, the default is to use the first ROM path).
  • Click the only enabled button right to the device name (which says Default configuration initially) to create a new empty device setup.
  • If you're going to use device files with speaking names, don't bother with setting up a name for the configuration... QMC2 will automatically do it for you!
  • From the (then enabled) list of vailable Device instances select the one (or more) you want to map a file to; when you click the browse button, the default directory from above will be used (if set), filtered by names that fit the contents of the Extensions column.
  • When you've selected the first file this way, QMC2 will suggest a configuration name (when the name hasn't been set before).
  • When you're done with the setup, click the save button (right-most tool button, now enabled as well).
  • The configuration will then be added to the list of Available device configurations and can be selected, edited and played (launched).

See also this section in the QMC2 guide!

There are just too many emulator configuration options, so it's hard to find the ones I want to set quickly. Is there an easy way to search for them?

Yes. Click into the tree widget which contains all the emulator configuration options and enter the string you want to search for. A small editor widget will pop up and all matches in the configuration tree will be high-lighted/expanded as you type. The widget closes when Escape is pressed or automatically after an idle time of 2 seconds.

This works for both the global and the machine-specific settings.

How do I backup / restore QMC2's configuration?

Backup:

  • Make sure that no instance of QMC2 is currently running.
  • Copy the configuration folder to a safe place.

Restore:

  • Make sure that no instance of QMC2 is currently running.
  • Overwrite the contents of the configuration folder with the contents of the backup.

There's really not more to it. It's actually sufficient to just make a backup copy of the file qmc2.ini. Everything else (except personal user data) will be recreated on demand.

See this section in the QMC2 guide for examples on backing up QMC2's complete configuration folder from the command line, and this adjacent section for finding out the actual location of that folder.

How come the ROM state of a machine is correct (or mostly correct) but the emulator still considers it bad when I start it?

That's probably a confusing situation, but can happen since MAME's invention of (referenced) device-sets. The actual machine ROMs are all good (or best available), but ROMs may still be wrong or missing for one or more of the required device-sets.

Since v0.39, the ROMAlyzer can help you find out such situations easily: after analyzing a set, right-click on the top-level item in the report -- if there are referenced device sets, the context-menu will offer an Analyze referenced devices item.

Will QMC2 automatically upgrade existing setups whenever a new version is installed and settings may have changed?

Yes, but we only guarantee this for the last 3 versions!

For example, when you install QMC2 0.70 settings from installations back until version 0.67 will be auto-migrated (usually during start-up). Settings from older versions may not be upgraded cleanly. That is, they will use the (current) default value, and obsolete settings won't be removed from qmc2.ini (this garbage doesn't really hurt, though).

The reason why we only support upgrades from one of the last 3 versions is mainly performance - the more history there is to keep & manage the longer it will take to start up.

Note that we also check for SVN revisions in order to find situations where upgrades may be necessary within a development cycle. The last-three-versions restriction only applies to released / final versions, though.

Of course, there are certain cases where this may not always be easy to accomplish. For instance, when a new column is inserted in any views, their header states have to be reset in order to ensure that the new column is visible. In such cases you will be informed by a corresponding message(-box).

Downgrades are not supported, and its behavior is undefined.

Also, note that most settings upgrades are only done by QMC2's main GUI! QMC2 Arcade shares many settings with the main GUI and will only upgrade those settings by itself which are specific to it. So whenever you install a new version of QMC2, make sure to first start the main GUI!

Troubleshooting

I'm having trouble to set up the emulator configuration. Am I missing something?

You may be missing some background information about how QMC2 handles the emulator configuration internally. Let's try to fill that gap...

General configuration handling

When QMC2 launches an emulator, it will pass all the configuration parameters that are different than their respective defaults as command line arguments. There is no need for any external configuration files like ~/.mame/mame.ini (in case of MAME for example).

QMC2 uses a so called emulator configuration template - an XML template file loaded into a map (dictionary) of emulator options - to support all available settings it knows about. Options which are not included in the template will not be available via QMC2 (though it can be easily enhanced with additional options). We are trying to keep up with the supported emulators and their latest versions; keep an eye on the template version reported in the front end log to make sure you're using an up to date configuration template. It uses the same versioning pattern as the emulator it supports.

If you would like to avoid any accidental mixture with external configuration files (mame.ini, <machinename>.ini, ...), you should set the value of readconfig to false (0). If this has been set, QMC2 will fully control the emulator configuration.

Using external configuration files

That said, it is still possible to use external configurations (and thus support unknown options out of the box). In fact, if you would like to use only external configuration files and not let QMC2 configure the emulators at all, just leave all emulator settings at their default values within QMC2 (both the global and the machine-specific ones -- see below). There's one exception, though: depending on your specific installation, you will most likely have to setup the (global) inipath parameter within QMC2 to make sure your ini's are found. Anyway, you will have to take care of these configuration files yourself, of course.

The value of readconfig should be set to true (1) in this case, which is the default.

You can also mix both approaches, but note that the command line options (= settings made with QMC2) have higher precedence!

Importing and exporting emulator settings

Another option is to make use of QMC2's ability to import and export emulator configuration files. Exported configurations will contain all available (known) options, regardless if they are at their default values or not. Settings imported from configuration files will overwrite those currently set in QMC2 selectively (that is, only options that are included in the imported file will be changed).

Warnings:

  • The export function will blindly overwrite any existing configuration files (create backups!).
  • The import function assumes a clean configuration syntax and may not be fail safe on malformed ini's (it's a fairly simple parser).

However, using this feature you are able to keep both worlds in sync and launch the emulators in the exact same way regardless if started via QMC2 or at the command line. It also provides an easy way to exchange machine settings between users and systems.

Global vs machine-specific settings

The global emulator options are used for all machines, which is obvious :). If a value is changed from its default (defined in the template) QMC2 will pass it to the emulator.

The same basically holds for any machine-specific options. The only difference is that if a setting has been made in the global configuration, this will be used as the new default.

For example, if you set flicker to 1.0 (default: 0.0) in the global settings, and to 2.0 in the machine-specific settings, -flicker 2.0 will be passed to the emulator. Any machine for which the flicker value hasn't been explicitly set will be called with -flicker 1.0.

How is the configuration stored?

All emulator settings are stored in QMC2's configuration file (qmc2.ini) - see the section for your emulator (for example the [MAME] section). Only options which were changed from their defaults get stored. QMC2 uses long option names which are compatible between command line and configuration files (i. e. scalemode and not sm).

You can pre-configure system-wide overwrites for any template-based defaults by storing them in /etc/qmc2/qmc2.ini on Linux/UNIX, or /Library/Application Support/qmc2/qmc2.ini on Mac OS X. System-wide pre-configuration is not supported (and not required) on Windows.

See also this FAQ.

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

Possible scenarios for this include:

Symptom 1: all machines are in an unknown state (state color: blue)

Probable reason 1a:

  • You didn't trigger a ROM check.

Solution 1a:

  • See Tools -> Check ROMs in the menu to trigger a ROM check.

Probable reason 1b:

  • The ROM state cache file cannot be read or written.

Solution 1b:

  • See Tools -> Options... -> Emulator -> Files / Directories -> ROM state cache and check your access permissions to that file.

Symptom 2: no machines were found (state color: gray)

Probable reason 2:

  • The ROM path isn't set up correctly.

Solution 2:

  • Check the rompath setting in your global emulator options (see Tools -> Options... -> Emulator -> Global configuration)! Open the Search paths sub-tree and change the rompath setting according to your local setup. Apply your changes and retry the ROM check!

Please also check the front-end log for FATAL or WARNING messages!

QMC2 Arcade repeatedly crashes when I click-select certain machines

In case you're using a filtered machine list then the most likely cause is that this file is not up to date. The validity of the data is assumed in order to allow for some optimizations; breaking this assumption can obviously lead to crashes. To fix it, please recreate / update the filtered machine list on the arcade mode setup dialog (part of the main GUI).

Otherwise, or if the update of the filtered machine list doesn't help, you might have found a bug - please report it at our bug tracking system.

When KDE4's effects are enabled (composite manager), QMC2 flickers when in full screen

Change your kwinrc file and disable UnredirectFullscreen:

$ vi ~/.kde4/share/config/kwinrc
...
[Compositing]
UnredirectFullscreen=false
...

See also: http://staff.blog.ui.ac.id/jp/2009/06/10/flicker-on-compositing-enabled-kde4/

This answer may be obsolete: No problems of this sort have been reported since 2009, and newer window managers / desktops have evolved since then, so the validity of this information is questionable at least :).

Miscellaneous FAQs

Rumors say that QMC2 loads slowly. Is that true?

It was fairly slow in the past, yes. But the good news is that this is no longer true for modern versions of QMC2 :)!

Typical initial loading times for qmc2-sdlmame (from cached data) on an I/O-optimized Linux 64-bit system should look similar to this number:

Number of systems / devices

Typical start-up time

37,326 ~1.5 seconds

The start-up performance was measured with QMC2 0.183 using MAME 0.183. Icons are loaded from the icon cache database.

To better compare this value with the performance you see on your system, here are some details of the computer which was used in the test:

MB ... ASUSTeK Computer INC. / M5A97 EVO R2.0
CPU .. AMD FX(tm)-8350 Eight-Core Processor (4 GHz)
RAM .. 32 GB (4x 8 GB Kingston / KHX1866C10D3/8G)
GPU .. NVIDIA Corporation GM206 (GeForce GTX 960)
SSD .. 1x 500 GB Samsung SSD 850 (OS and home folders)
HDD .. 2x 4 TB WDC WD40EFRX-68W (MAME ROMs, artwork and games)
OS ... openSUSE Tumbleweed x86_64 / kernel version 4.9.3 / gcc 6.2.1
FS ... ext4 (on LVM volumes)

Of course, the more data there is to load the longer it will take. Future versions of MAME will likely add (much) more systems, so loading times will grow over time (unless we find other ways to speed things up again).

Here's the front-end log from this start-up test:

13:15:02.237: M.A.M.E. Catalog / Launcher II v0.183, SVN r7968 (Qt 4.8.7, SDLMAME, Linux x86_64)
13:15:02.238: Phonon features enabled - using Phonon v4.9.0
13:15:02.238: SDL joystick support enabled - using SDL v2.0.5
13:15:02.239: processing global emulator configuration
13:15:02.240: creating template configuration map
13:15:02.241: template info: emulator = SDLMAME, version = 0.183, format = 0.2.9
13:15:02.401: image cache size set to 64 MB
13:15:02.456: emulator info: type = MAME, version = 0.183
13:15:02.456: 34054 supported (non-device) sets
13:15:02.457: loading catver.ini
13:15:02.486: shortcut map is clean
13:15:02.488: joystick map is clean
13:15:02.552: done (loading catver.ini, elapsed time = 00:00.095)
13:15:02.552: 11006 category / 37046 version records loaded
13:15:02.552: loading category.ini
13:15:02.555: done (loading category.ini, elapsed time = 00:00.003)
13:15:02.555: 1307 category records loaded
13:15:02.557: loading ROM state from cache
13:15:02.582: done (loading ROM state from cache, elapsed time = 00:00.025)
13:15:02.582: 37326 cached ROM states loaded
13:15:02.582: processing machine list
13:15:02.583: loading icons from cache database
13:15:03.000: done (loading icons from cache database, elapsed time = 00:00.415)
13:15:03.000: 11328 icons loaded
13:15:03.002: loading machine data from machine list cache
13:15:03.600: done (loading machine data from machine list cache, elapsed time = 00:00.598)
13:15:03.602: filling up rank cache from user data database '/home/rene/.qmc2/mame-user-data.db'
13:15:03.608: done (filling up rank cache from user data database '/home/rene/.qmc2/mame-user-data.db')
13:15:03.608: sorting machine list by rank in ascending order
13:15:03.740: restoring machine selection
13:15:03.749: done (processing machine list, elapsed time = 00:01.167)
13:15:03.749: 33984 machines, 70 BIOS sets and 3272 devices loaded
13:15:03.749: ROM state info: L:37326 C:33128 M:4184 I:4 N:10 U:0
13:15:03.750: loading favorites and play history
13:15:03.751: done (loading favorites and play history)
13:15:03.751: total start-up time: 00:01.514