Sprinter/mame
2
0
Fork 0
mirror of https://github.com/holub/mame synced 2025-04-19 07:00:31 +03:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

Make informational verbs a bit more consistent, reduce copy/pasted code, a slight performance improvement for reading localisation files, and more documentation clean-up/correction/clarification

Browse Source
This commit is contained in:
Vas Crabb 2019-01-04 01:12:02 +11:00
parent e82a4ee4c8
commit cba80b7182
5 changed files with 511 additions and 326 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

411
docs/source/commandline/commandline-all.rst
View File

@ -3,7 +3,6 @@
Universal Commandline Options
=============================
This section contains configuration options that are applicable to *all* MAME sub-builds (both SDL and Windows native).
@ -15,15 +14,66 @@ Commands include **mame** itself as well as various tools included with the MAME
Verbs are actions to take upon something with the command (e.g. **mame -validate pacman** has *mame* as a command and *-validate* as a verb)
Patterns
--------
Many verbs support the use of *patterns*, which are either a system or device short name (e.g. **a2600**, **zorba_kbd**) or a glob pattern that matches either (e.g. **zorba_\***)
Many verbs support the use of *patterns*, which are either a system or device
short name (e.g. **a2600**, **zorba_kbd**) or a glob pattern that matches either
(e.g. **zorba_\***).
Depending on the command you're using the pattern with, pattern matching may match systems or systems and devices. It is advised to put quotes around your patterns to avoid having your shell try to expand them against filenames. (e.g. **mame -validate "pac\*"**)
Depending on the command you're using the pattern with, pattern matching may
match systems or systems and devices. It is advised to put quotes around your
patterns to avoid having your shell try to expand them against filenames (e.g.
**mame -validate "pac\*"**).
.. _mame-commandline-paths:
File Names and Directory Paths
------------------------------
A number of options for specifying directories support multiple paths (for
for example to search for ROMs in multiple locations). MAME expects multiple
paths to be separated with semicolons (``;``).
MAME expands environment variable expressions in paths. The syntax used depends
on your operating system. On Windows, ``%`` (percent) syntax is used. For
example ``%APPDATA%\mame\cfg`` will expand the application data path for the
current user's roaming profile. On UNIX-like system (including macOS and
Linux), Bourne shell syntax is used, and a leading ``~`` expands to the current
user's home directory. For example, ``~/.mame/${HOSTNAME}/cfg`` expands to
a host-specific path inside the ``.mame`` directory in the current user's home
directory. Note that only simple variable substitutions are supported; more
complex expressions supported by Bash, ksh or zsh are not recognised by MAME.
Relative paths are resolved relative to the current working directory. If you
start MAME by double-clicking it in Windows Explorer, the working directory is
set to the folder containing the MAME executable. If you start MAME by
double-clicking it in the macOS Finder, it will open a Terminal window with the
working directory is set to your home directory (usually ``/Users/<username>``)
and start MAME.
If you want behaviour similar to what Windows Explorer provides on macOS, create
a script file containing these lines in the directory containing the MAME
executable (for example you could call it ``mame-here``)::
#!/bin/sh
cd "`dirname "$0"`"
exec ./mame64
You should be able to use any text editor. If you have a choice of file format
or line ending style, chose UNIX. I've assumed you're using a 64-bit release
build of MAME, but if you aren't you just need to change ``mame64`` to the name
of your MAME executable. Once you've created the file, you need to mark is as
executable. You can do this by opening a Terminal window, typing **chmod a+x**
followed by a space, dragging the file you created onto the window (this causes
Terminal to insert the full escaped path to the file), and then ensuring the
Terminal window is active and hitting **Return** (or **Enter**) on your
keyboard. You can close the Terminal window after doing this. Now if you
double-click the script in the Finder, it will open a Terminal windows, set the
working directory to the location of the script (i.e. the folder containing
MAME), and then start MAME.
Core Verbs
----------
@ -32,18 +82,20 @@ Core Verbs
**-help** / **-h** / **-?**
Displays current MAME version and copyright notice.
Displays current MAME version and copyright notice.
.. _mame-commandline-validate:
**-validate** / **-valid** [*<pattern>*]
Performs internal validation on one or more drivers and devices in the
system. Run this before submitting changes to ensure that you haven't
violated any of the core system rules.
Performs internal validation on one or more drivers and devices in the
system. Run this before submitting changes to ensure that you haven't
violated any of the core system rules.
If a pattern is specified, it will validate systems matching
the pattern, otherwise it will validate all systems and devices.
If a pattern is specified, it will validate systems matching the pattern,
otherwise it will validate all systems and devices. Note that if a pattern
is specified, it will be matched against systems only (not other devices),
and no device type validation will be performed.
@ -54,39 +106,44 @@ Configuration Verbs
**-createconfig** / **-cc**
Creates the default ``mame.ini`` file. All the configuration options
(not verbs) described below can be permanently changed by editing
this configuration file.
Creates the default ``mame.ini`` file. All the configuration options (not
verbs) described below can be permanently changed by editing this
configuration file.
.. _mame-commandline-showconfig:
**-showconfig** / **-sc**
Displays the current configuration settings. If you route this to a
file, you can use it as an INI file. For example, the command:
Displays the current configuration settings. If you route this to a file,
you can use it as an INI file. For example, the command:
**mame -showconfig >mame.ini**
**mame -showconfig > mame.ini**
is equivalent to **-createconfig**.
is equivalent to **-createconfig**.
.. _mame-commandline-showusage:
**-showusage** / **-su**
Displays a summary of all the command line options. For options that
are not mentioned here, the short summary given by "mame -showusage"
is usually sufficient.
Displays a summary of all the command line options. For options that are not
mentioned here, the short summary given by "mame -showusage" is usually
a sufficient description.
Frontend Verbs
--------------
Note: By default, all the '**-list**' verbs below write info to the screen. If you wish to write the info to a textfile instead, add this to the end of your command:
Note: By default, all the '**-list**' verbs below write info to the standard
output (usually the terminal/command window where you typed the command). If you
wish to write the info to a text file instead, add this to the end of your
command:
**> filename**
**>** *filename*
...where 'filename' is the textfile's path and name (e.g., list.txt).
where *filename* is the name of the file to save the output in (e.g.
``list.txt``). Note that if this file already exists, it will be completely
overwritten.
Example:
@ -97,45 +154,67 @@ Example:
.. _mame-commandline-listxml:
**-listxml** / **-lx** [*<pattern>*]
**-listxml** / **-lx** [*<pattern>*...]
List comprehensive details for all of the supported systems and drivers. The output is quite long, so it is usually better to redirect this into a file. The output is in XML format. By default all systems are listed; however, you can limit this list by specifying a *pattern* after the -listxml command.
List comprehensive details for all of the supported systems and devices in
XML format. The output is quite long, so it is usually better to redirect
this into a file. By default all systems are listed; however, you can limit
this list by specifying one or more *patterns* after the **-listxml** verb.
This XML output is typically imported into other tools (like graphical
front-ends and ROM managers), or processed with scripts query detailed
information.
.. _mame-commandline-listfull:
**-listfull** / **-ll** [*<pattern>*]
**-listfull** / **-ll** [*<pattern>*...]
Displays a list of system driver names and descriptions. By default all systems and devices are listed; however, you can limit this list by specifying a *pattern* after the **-listfull** command.
Displays a list of system driver names and descriptions. By default all
systems and devices are listed; however, you can limit this list by
specifying one or more *patterns* after the **-listfull** verb.
.. _mame-commandline-listsource:
**-listsource** / **-ls** [<*pattern>*]
**-listsource** / **-ls** [*<pattern>*...]
Displays a list of drivers and the names of the source files their system drivers are defined in. Useful for finding which driver a system runs on in order to fix bugs. By default all systems are listed; however, you can limit this list by specifying a *pattern* after the **-listsource** command.
Displays a list of system drivers/devices and the names of the source files
where they are defined. Useful for finding which driver a system runs on in
order to fix bugs. By default all systems and devices are listed; however,
you can limit this list by specifying one or more *pattern* after the
**-listsource** verb.
.. _mame-commandline-listclones:
**-listclones** / **-lc** [<*pattern*>]
**-listclones** / **-lc** [*<pattern>*]
Displays a list of clones. By default all clones are listed; however, you can limit this list by specifying a driver name or wildcard after the **-listsource** command.
Displays a list of clones. By default all clones are listed; however, you
can limit this list by specifying a *pattern* after the **-listsource**
verb. If a pattern is specified, MAME will list clones of systems that
match the pattern, as well as clones that match the pattern themselves.
.. _mame-commandline-listbrothers:
**-listbrothers** / **-lb** [<*pattern*>]
**-listbrothers** / **-lb** [*<pattern>*]
Displays a list of '*brothers*', or rather, other sets which are located in the same sourcefile as the system name searched for.
Displays a list of *brothers*, i.e. other systems that are defined in the
same source file as a system that matches the specified *pattern*.
.. _mame-commandline-listcrc:
**-listcrc** [<*pattern*>]
**-listcrc** [*<pattern>*...]
Displays a full list of CRCs of all ROM images referenced by the specified pattern of system or device names. If no pattern is specified, the results will be *all* systems and devices.
Displays a full list of CRCs and names of all ROM images referenced by
systems and devices matching the specified pattern(s). If no patterns are
specified, ROMs referenced by all supported systems and devices will be
included.
.. _mame-commandline-listroms:
**-listroms** / **-lr** [<*pattern*>]
**-listroms** / **-lr** [*<pattern>*...]
Displays a list of ROM images referenced by the specified pattern of system or device names. If no pattern is specified, the results will be *all* systems and devices.
Displays a list of ROM images referenced by supported systems/devices that
match the specified pattern(s). If no patterns are specified, the results
will include *all* supported systems and devices.
.. _mame-commandline-listsamples:
@ -222,30 +301,33 @@ OSD-related Options
**-uimodekey** [*keystring*]
Key used to toggle emulated keyboard on and off. Default setting is **SCRLOCK** on Windows, **Forward Delete** on Mac (use **FN-Delete** on laptop/compact keyboards).
Key used to enable/disable MAME keyboard controls when the emulated system
has keyboard inputs. The default setting is **Forward Delete** on macOS or
**SCRLOCK** on other operating systems (including Windows and Linux). Use
**FN-Delete** on Macintosh computers with notebook/compact keyboards.
.. _mame-commandline-uifontprovider:
**\-uifontprovider**
**-uifontprovider**
Chooses provider for UI font.
Chooses provider for UI font rendering.
On Windows, you can choose from: ``win``, ``dwrite``, ``none`` or ``auto``.
On Mac, you can choose from: ``osx`` or ``auto``.
On other platforms, you can choose from: ``sdl`` or ``auto``.
On Windows, you can choose from: ``win``, ``dwrite``, ``none`` or ``auto``.
On macOS, you can choose from: ``osx``, ``none`` or ``auto``.
On other platforms, you can choose from: ``sdl``, ``none`` or ``auto``.
Default setting is *auto*.
Default setting is ``auto``.
.. _mame-commandline-keyboardprovider:
**\-keyboardprovider**
**-keyboardprovider**
Chooses how MAME will get keyboard input.
On Windows, you can choose from: ``auto``, ``rawinput``, ``dinput``, ``win32``, or ``none``
On SDL, you can choose from: ``auto``, ``sdl``, ``none``
The default is *auto*. On Windows, auto will try rawinput with fallback to dinput. On SDL, auto will default to sdl.
The default is ``auto``. On Windows, ``auto`` will try ``rawinput`` with fallback to ``dinput``. On SDL, ``auto`` will default to ``sdl``.
.. _mame-commandline-mouseprovider:
@ -256,7 +338,7 @@ OSD-related Options
On Windows, you can choose from: ``auto``, ``rawinput``, ``dinput``, ``win32``, or ``none``
On SDL, you can choose from: ``auto``, ``sdl``, ``none``
The default is *auto*. On Windows, auto will try rawinput with fallback to dinput. On SDL, auto will default to sdl.
The default is ``auto``. On Windows, ``auto`` will try ``rawinput`` with fallback to ``dinput``. On SDL, ``auto`` will default to ``sdl``.
.. _mame-commandline-lightgunprovider:
@ -267,7 +349,7 @@ OSD-related Options
On Windows, you can choose from: ``auto``, ``rawinput``, ``win32``, or ``none``
On SDL, you can choose from: ``auto``, ``x11`` or ``none``
The default is *auto*. On Windows, auto will try rawinput with fallback to win32, or none if it doesn't find any. On SDL/Linux, auto will default to x11, or none if it doesn't find any. On other SDL, auto will default to none.
The default is ``auto``. On Windows, auto will try ``rawinput`` with fallback to ``win32``, or ``none`` if it doesn't find any. On SDL/Linux, ``auto`` will default to ``x11``, or ``none`` if it doesn't find any. On other SDL, ``auto`` will default to ``none``.
.. _mame-commandline-joystickprovider:
@ -278,9 +360,9 @@ OSD-related Options
On Windows, you can choose from: ``auto, ``winhybrid``, ``dinput``, ``xinput``, or ``none``
On SDL, you can choose from: ``auto``, ``sdl``, ``none``
The default is *auto*. On Windows, auto will default to dinput.
The default is ``auto``. On Windows, auto will default to ``dinput``.
Note that Microsoft XBox 360 and XBox One controllers will be happiest with ``winhybrid`` or ``xinput``. The ``winhybrid`` option supports a mix of DirectInput and XInput controllers at the same time. On SDL, auto will default to sdl.
Note that Microsoft XBox 360 and XBox One controllers will work best with ``winhybrid`` or ``xinput``. The ``winhybrid`` option supports a mix of DirectInput and XInput controllers at the same time. On SDL, auto will default to ``sdl``.
@ -297,7 +379,7 @@ OSD CLI Options
**\-listnetwork**
Create a list of available Network Adapters for use with emulation.
Create a list of available Network Adapters for use with emulation.
@ -323,25 +405,28 @@ Configuration Options
**-[no]readconfig** / **-[no]rc**
Enables or disables the reading of the config files. When enabled (which is the default), MAME reads the following config files in order:
Enables or disables the reading of the config files. When enabled (which is the default), MAME reads the following config files in order:
- mame.ini
- debug.ini (if the debugger is enabled)
- <driver>.ini (based on the source filename of the driver)
- vertical.ini (for systems with vertical monitor orientation)
- horizont.ini (for systems with horizontal monitor orientation)
- arcade.ini (for systems in source added with GAME() macro)
- console.ini (for systems in source added with CONS() macro)
- computer.ini (for systems in source added with COMP() macro)
- othersys.ini (for systems in source added with SYST() macro)
- vector.ini (for vector systems only)
- <parent>.ini (for clones only, may be called recursively)
- <systemname>.ini
- ``mame.ini``
- ``debug.ini`` (if the debugger is enabled)
- ``source/``\ *<driver>*\ ``.ini`` (based on the source filename of the driver)
- ``vertical.ini`` (for systems with vertical monitor orientation)
- ``horizont.ini`` (for systems with horizontal monitor orientation)
- ``arcade.ini`` (for systems in source added with ``GAME()`` macro)
- ``console.ini`` (for systems in source added with ``CONS()`` macro)
- ``computer.ini`` (for systems in source added with ``COMP()`` macro)
- ``othersys.ini`` (for systems in source added with ``SYST()`` macro)
- ``vector.ini`` (for vector systems only)
- *<parent>*\ ``.ini`` (for clones only, may be called recursively)
- *<systemname>*\ ``.ini``
(See :ref:`advanced-multi-CFG` for further details)
The settings in the later INIs override those in the earlier INIs.
So, for example, if you wanted to disable overlay effects in the vector systems, you can create a ``vector.ini`` with the "effect none" line in it, and it will override whatever effect value you have in your ``mame.ini``. The default is ON (**-readconfig**).
The settings in the later INIs override those in the earlier INIs. So, for
example, if you wanted to disable overlay effects in the vector systems, you
can create a ``vector.ini`` with line ``effect none`` in it, and it will
override whatever ``effect`` value you have in your ``mame.ini``. The
default is ON (**-readconfig**).
@ -352,79 +437,129 @@ Core Search Path Options
**-homepath** *<path>*
Specifies a path where the base 'plugins' folder is to be found. The default is '.' (that is, in the current working directory).
Specifies a path for Lua plugins to store data. The default is ``.`` (that
is, in the current working directory).
.. _mame-commandline-rompath:
**-rompath** / **-rp** *<path>*
**-rompath** / **-rp** / **-biospath** / **-bp** *<path>*
Specifies a list of paths within which to find ROM or hard disk images. Multiple paths can be specified by separating them with semicolons. The default is ``roms`` (that is, a directory "roms" in the same directory as the MAME executable).
Specifies one or more paths within which to find ROM or disk images.
Multiple paths can be specified by separating them with semicolons. The
default is ``roms`` (that is, a directory ``roms`` in the current working
directory).
.. _mame-commandline-hashpath:
**-hashpath** *<path>*
**-hashpath** / **-hash_directory** / **-hash** *<path>*
Specifies a list of paths within which to find Software List HASH files. Multiple paths can be specified by separating them with semicolons. The default is ``hash`` (that is, a directory "roms" in the same directory as the MAME executable).
Specifies one or more paths within which to find software definition files.
Multiple paths can be specified by separating them with semicolons. The
default is ``hash`` (that is, a directory ``hash`` in the current working
directory).
.. _mame-commandline-samplepath:
**-samplepath** / **-sp** *<path>*
Specifies a list of paths within which to find sample files. Multiple paths can be specified by separating them with semicolons. The default is ``samples`` (that is, a directory "samples" in the same directory as the MAME executable).
Specifies one or more paths within which to find audio sample files.
Multiple paths can be specified by separating them with semicolons. The
default is ``samples`` (that is, a directory ``samples`` in the current
working directory).
.. _mame-commandline-artpath:
**-artpath** *<path>* / **-artwork_directory** *<path>*
**-artpath** *<path>* *<path>*
Specifies a list of paths within which to find artwork files. Multiple paths can be specified by separating them with semicolons. The default is ``artwork`` (that is, a directory "artwork" in the same directory as the MAME executable).
Specifies one or more paths within which to find external layout and artwork
files. Multiple paths can be specified by separating them with semicolons.
The default is ``artwork`` (that is, a directory ``artwork`` in the current
working directory).
.. _mame-commandline-ctrlrpath:
**-ctrlrpath** / **-ctrlr_directory** *<path>*
**-ctrlrpath** *<path>*
Specifies a list of paths within which to find controller-specific configuration files. Multiple paths can be specified by separating them with semicolons. The default is ``ctrlr`` (that is, a directory "ctrlr" in the same directory as the MAME executable).
Specifies one or more paths within which to find default input configuration
files. Multiple paths can be specified by separating them with semicolons.
The default is ``ctrlr`` (that is, a directory ``ctrlr`` in the current
working directory).
.. _mame-commandline-inipath:
**-inipath** *<path>*
Specifies a list of paths within which to find .INI files. Multiple paths can be specified by separating them with semicolons. The default is ``.;ini`` (that is, search in the current directory first, and then in the directory "ini" in the same directory as the MAME executable).
Specifies one or more paths within which to find INI files. Multiple paths
can be specified by separating them with semicolons.
On Windows, the default is ``.;ini;ini/presets`` (that is, search in the
current directory first, then in the directory ``ini`` in the current
working directory, and finally the directory ``presets`` inside that
directory).
On macOS, the default is
``$HOME/Library/Application Support/mame;$HOME/.mame;.;ini`` (that is,
search the ``mame`` folder inside the current user's Application Support
folder, followed by the ``.mame`` folder in the current user's home
directory, then the current working directory, and finally the directory
``ini`` in the current working directory).
On other platforms (including Linux), the default is ``$HOME/.mame;.;ini``
(that is search the ``.mame`` directory in the current user's home
directory, followed by the current working directory, and finally the
directory ``ini`` in the current working directory).
.. _mame-commandline-fontpath:
**-fontpath** *<path>*
Specifies a list of paths within which to find .BDF font files. Multiple paths can be specified by separating them with semicolons. The default is ``.`` (that is, search in the current working directory).
Specifies one or more paths within which to find BDF (Adobe Glyph Bitmap
Distribution Format) font files. Multiple paths can be specified by
separating them with semicolons. The default is ``.`` (that is, search in
the current working directory).
.. _mame-commandline-cheatpath:
**-cheatpath** *<path>*
Specifies a list of paths within which to find .XML cheat files. Multiple paths can be specified by separating them with semicolons. The default is ``cheat`` (that is, a folder called 'cheat' located in the same directory as the as the MAME executable).
Specifies one or more paths within which to find XML cheat files. Multiple
paths can be specified by separating them with semicolons. The default is
``cheat`` (that is, a folder called ``cheat`` located in the current working
directory).
.. _mame-commandline-crosshairpath:
**-crosshairpath** *<path>*
Specifies a list of paths within which to find crosshair files. Multiple paths can be specified by separating them with semicolons. The default is ``crsshair`` (that is, a directory "crsshair" in the same directory as the MAME executable). If the crosshair is set to default in the menu, MAME will look for ``systemname\\cross#.png`` and then cross#.png in the specified crsshairpath, where # is the player number. Failing that, MAME will use built-in default crosshairs.
Specifies one or more paths within which to find crosshair image files.
Multiple paths can be specified by separating them with semicolons. The
default is ``crsshair`` (that is, a directory ``crsshair`` in the current
working directory).
.. _mame-commandline-pluginspath:
**-pluginspath** *<path>*
Specifies a list of paths within which to find Lua plugins for MAME.
Specifies one or more paths within which to find Lua plugins for MAME. The
default is ``plugins`` (that is, a directory ``plugins`` in the current
working directory).
.. _mame-commandline-languagepath:
**-languagepath** *<path>*
Specifies a list of paths within which to find language files for localized UI text.
Specifies one or more paths within which to find language files for
localized UI text. The default is ``language`` (that is, a directory
``language`` (that is, a directory ``language`` in the current working
directory).
.. _mame-commandline-swpath:
**-swpath** *<path>*
Specifies a path within which to find loose software to be used by emulation.
Specifies the default path from which to load loose software image files.
The default is ``sofware`` (that is, a directory ``software`` in the current
working directory).
Core Output Directory Options
@ -434,43 +569,75 @@ Core Output Directory Options
**-cfg_directory** *<path>*
Specifies a single directory where configuration files are stored. Configuration files store user configurable settings that are read at startup and written when MAME exits. The default is ``cfg`` (that is, a directory "cfg" in the same directory as the MAME executable). If this directory does not exist, it will be automatically created.
Specifies the directory where configuration files are stored. Configuration
files are read when starting MAME or when starting an emulated machine, and
written on exit. Configuration files preserve settings including input
assignment, DIP switch settings, bookkeeping statistics, and debugger window
arrangement. The default is ``cfg`` (that is, a directory ``cfg`` in the
current working directory). If this directory does not exist, it will be
created automatically.
.. _mame-commandline-nvramdirectory:
**-nvram_directory** *<path>*
Specifies a single directory where NVRAM files are stored. NVRAM files store the contents of EEPROM and non-volatile RAM (NVRAM) for systems which used this type of hardware. This data is read at startup and written when MAME exits. The default is ``nvram`` (that is, a directory "nvram" in the same directory as the MAME executable). If this directory does not exist, it will be automatically created.
Specifies the directory where NVRAM files are stored. NVRAM files store the
contents of EEPROM, non-volatile RAM (NVRAM), and other programmable devices
for systems that used this type of hardware. This data is read when
starting an emulated machine and written on exit. The default is ``nvram``
(that is, a directory ``nvram`` in the current working directory)). If this
directory does not exist, it will be created automatically.
.. _mame-commandline-inputdirectory:
**-input_directory** *<path>*
Specifies a single directory where input recording files are stored. Input recordings are created via the -record option and played back via the -playback option. The default is ``inp`` (that is, a directory "inp" in the same directory as the MAME executable). If this directory does not exist, it will be automatically created.
Specifies the directory where input recording files are stored. Input
recordings are created using the **-record** option and played back using
the **-playback** option. The default is ``inp`` (that is, a directory
``inp`` in the current working directory). If this directory does not exist,
it will be created automatically.
.. _mame-commandline-statedirectory:
**-state_directory** *<path>*
Specifies a single directory where save state files are stored. Save state files are read and written either upon user request, or when using the -autosave option. The default is ``sta`` (that is, a directory "sta" in the same directory as the MAME executable). If this directory does not exist, it will be automatically created.
Specifies the directory where save state files are stored. Save state files
are read and written either upon user request, or when using the
**-autosave** option. The default is ``sta`` (that is, a directory ``sta``
in the current working directory). If this directory does not exist, it
will be created automatically.
.. _mame-commandline-snapshotdirectory:
**-snapshot_directory** *<path>*
Specifies a single directory where screen snapshots are stored, when requested by the user. The default is ``snap`` (that is, a directory "snap" in the same directory as the MAME executable). If this directory does not exist, it will be automatically created.
Specifies the directory where screen snapshots and video recordings are
stored when requested by the user. The default is ``snap`` (that is, a
directory ``snap`` in the current working directory). If this directory does
not exist, it will be created automatically.
.. _mame-commandline-diffdirectory:
**-diff_directory** *<path>*
Specifies a single directory where hard drive differencing files are stored. Hard drive differencing files store any data that is written back to a hard disk image, in order to preserve the original image. The differencing files are created at startup with a system with a hard disk image. The default is ``diff`` (that is, a directory "diff" in the same directory as the MAME executable). If this directory does not exist, it will be automatically created.
Specifies the directory where hard drive difference files are stored. Hard
drive difference files store data that is written back to an emulated hard
disk, in order to preserve the original image file. The difference files
are created when starting an emulated system with a compressed hard disk
image. The default is ``diff`` (that is, a directory ``diff`` in the
current working directory). If this directory does not exist, it will be
created automatically.
.. _mame-commandline-commentdirectory:
**-comment_directory** *<path>*
Specifies a single directory where debugger comment files are stored. Debugger comment files are written by the debugger when comments are added to the disassembly for a system. The default is ``comments`` (that is, a directory "comments" in the same directory as the MAME executable). If this directory does not exist, it will be automatically created.
Specifies a directory where debugger comment files are stored. Debugger
comment files are written by the debugger when comments are added to the
disassembly for a system. The default is ``comments`` (that is, a directory
``comments`` in the current working directory). If this directory does not
exist, it will be created automatically.
@ -610,57 +777,97 @@ Core Performance Options
**-[no]autoframeskip** / **-[no]afs**
Automatically determines the frameskip level while you're running the system, adjusting it constantly in a frantic attempt to keep the system running at full speed. Turning this on overrides the value you have set for -frameskip below. The default is OFF (**-noautoframeskip**).
Dynamically adjust the frameskip level while you're running the system to
maintain full speed. Turning this on overrides the **-frameskip** setting
described below. This is off by default (**-noautoframeskip**).
.. _mame-commandline-frameskip:
**-frameskip** / **-fs** *<level>*
Specifies the frameskip value. This is the number of frames out of every 12 to drop when running. For example, if you say **-frameskip 2**, then MAME will display 10 out of every 12 frames. By skipping those frames, you may be able to get full speed in a system that requires more horsepower than your computer has. The default value is **-frameskip 0**, which skips no frames.
Specifies the frameskip value. This is the number of frames out of every 12
to drop when running. For example, if you specify **-frameskip 2**, MAME
will render and display 10 out of every 12 emulated frames. By skipping
some frames, you may be able to get full speed emulation for a system that
would otherwise be too demanding for your computer. The default value is
**-frameskip 0**, which skips no frames.
.. _mame-commandline-secondstorun:
**-seconds_to_run** / **-str** *<seconds>*
This option can be used for benchmarking and automated testing. It tells MAME to stop execution after a fixed number of seconds. By combining this with a fixed set of other command line options, you can set up a consistent environment for benchmarking MAME performance. In addition, upon exit, the **-str** option will write a screenshot called ``final.png`` to the system's snapshot directory.
This option tells MAME to automatically stop emulation after a fixed number
of seconds of emulated time have elapsed. This may be useful for
benchmarking and automated testing. By combining this with a fixed set of
other command line options, you can set up a consistent environment for
benchmarking MAME's emulation performance. In addition, upon exit, the
**-str** option will write a screenshot called ``final.png`` to the system's
snapshot directory.
.. _mame-commandline-nothrottle:
**-[no]throttle**
Configures the default thottling setting. When throttling is on, MAME attempts to keep the system running at the system's intended speed. When throttling is off, MAME runs the system as fast as it can. Note that the fastest speed is more often than not limited by your graphics card, especially for older systems. The default is ON (**-throttle**).
Enable or disable thottling emulation speed. When throttling is enabled,
MAME limits emulation speed to so the emulated system will not run faster
than the original hardware. When throttling is disabled, MAME runs the
emulation as fast as possible. Depending on your settings and the
characteristics of the emulated system, performance may be limited by your
CPU, graphics card, or even memory performance. The default is to enable
throttling (**-throttle**).
.. _mame-commandline-nosleep:
**-[no]sleep**
Allows MAME to give time back to the system when running with **-throttle**. This allows other programs to have some CPU time, assuming that the system isn't taxing 100% of your CPU resources. This option can potentially cause hiccups in performance if other demanding programs are running. The default is ON (**-sleep**).
When enabled along with **-throttle**, MAME will yield the CPU when
limiting emulation speed. This allows other programs to use CPU time,
assuming the main emulation thread isn't completely utilising a CPU core.
This option can potentially cause hiccups in performance if other demanding
programs are running. The default is on (**-sleep**).
.. _mame-commandline-speed:
**-speed** *<factor>*
Changes the way MAME throttles the emulated system such that it runs at some multiplier of the original speed. A <factor> of 1.0 means to run the system at its normal speed. A <factor> of 0.5 means run at half speed, and a <factor> of 2.0 means run at 2x speed. Note that changing this value affects sound playback as well, which will scale in pitch accordingly. The internal resolution of the fraction is two decimal places, so a value of 1.002 is the same as 1.0. The default is ``1.0``.
Changes the way MAME throttles the emulation so that it runs at some
multiple of the system's original speed. A *<factor>* of ``1.0`` means to
run the system at its normal speed, a *<factor>* of ``0.5`` means run at
half speed, and a *<factor>* of 2.0 means run at double speed. Note that
changing this value affects sound playback as well, which will scale in
pitch accordingly. The internal precision of the fraction is two decimal
places, so a *<factor>* of ``1.002`` is rounded to ``1.00``. The default is
``1.0`` (normal speed).
.. _mame-commandline-norefreshspeed:
**-[no]refreshspeed** / **-[no]rs**
Allows MAME to dynamically adjust the system's speed such that it does not exceed the slowest refresh rate for any targeted monitors in your system. Thus, if you have a 60Hz monitor and run a system that is actually designed to run at 60.6Hz, MAME will dynamically change the speed down to 99% in order to prevent sound hiccups or other undesirable side effects of running at a slower refresh rate. The default is OFF (**-norefreshspeed**).
Allows MAME to adjust the emulation speed so that the refresh rate of the
first emulated screen does not exceed the slowest refresh rate for any
targeted monitors in your system. Thus, if you have a 60Hz monitor and run
a system that is designed to run at 60.6Hz, MAME will reduce the emulation
speed to 99% in order to prevent sound hiccups or other undesirable side
effects of running at a slower refresh rate. The default is off
(**-norefreshspeed**).
.. _mame-commandline-numprocessors:
**-numprocessors** *<auto|value>* / **-np** *<auto|value>*
**-numprocessors** / **-np** **auto**\ \|\ *<value>*
Specify the number of processors to use for work queues. Specifying ``auto`` will use the value reported by the system or environment variable **OSDPROCESSORS**. To avoid abuse, this value is internally limited to 4 times the number of processors reported by the system. The default is ``auto``.
Specify the number of threads to use for work queues. Specifying ``auto``
will use the value reported by the system or environment variable
``OSDPROCESSORS``. This value is internally limited to four times the
number of processors reported by the system. The default is ``auto``.
.. _mame-commandline-bench:
**-bench** *[n]*
**-bench** *<n>*
Benchmark for *[n]* number of emulated seconds; implies the command string:
Benchmark for *<n>* emulated seconds. This is equivalent to the following
options:
**-str [n] -video none -sound none -nothrottle**
**-str** *<n>* **-video none -sound none -nothrottle**

8
docs/source/techspecs/layout_files.rst
View File

@ -1090,9 +1090,9 @@ when parameters are used, or recursively nested groups. The ``complay.py``
script is compatible with both Python 2.7 and Python 3 interpreters.
The ``complay.py`` script takes three parameters -- an input file name, an
output file name, and a base name for variables in the output::
output file name, and a base name for variables in the output:
python scripts/build/complay.py input [output [varname]]
**python scripts/build/complay.py** *<input>* [*<output>* [*<varname>*]]
The input file name is required. If no output file name is supplied,
``complay.py`` will parse and check the input, reporting any errors found,
@ -1104,6 +1104,6 @@ in case of an I/O error. If an output file name is specified, the file will be
created/overwritten on success or removed on failure.
To check a layout file for common errors, run the script with the path to the
file no check and no output file name or base variable name. For example::
file no check and no output file name or base variable name. For example:
python scripts/build/complay.py artwork/dino/default.lay
**python scripts/build/complay.py artwork/dino/default.lay**

414
src/frontend/mame/clifront.cpp
View File

@ -349,77 +349,20 @@ void cli_frontend::listxml(const std::vector<std::string> &args)
void cli_frontend::listfull(const std::vector<std::string> &args)
{
bool const iswild((1U != args.size()) || core_iswildstr(args[0].c_str()));
std::vector<bool> matched(args.size(), false);
auto const included = [&args, &matched] (char const *name) -> bool
{
if (args.empty())
return true;
bool result = false;
auto it = matched.begin();
for (std::string const &pat : args)
{
if (!core_strwildcmp(pat.c_str(), name))
{
result = true;
*it = true;
}
++it;
}
return result;
};
bool first = true;
auto const list_system_name = [&first] (device_type const &type)
auto const list_system_name = [] (device_type type, bool first)
{
// print the header
if (first)
osd_printf_info("Name: Description:\n");
first = false;
osd_printf_info("%-17s \"%s\"\n", type.shortname(), type.fullname());
};
// determine which drivers to output
driver_enumerator drivlist(m_options);
while (drivlist.next())
{
if (included(drivlist.driver().name))
{
list_system_name(drivlist.driver().type);
// if it wasn't a wildcard, there can only be one
if (!iswild)
break;
}
}
// try devices as well
if (iswild || first)
{
for (device_type type : registered_device_types)
{
if (included(type.shortname()))
{
list_system_name(type);
// if it wasn't a wildcard, there can only be one
if (!iswild)
break;
}
}
}
// return an error if none found
auto it = matched.begin();
for (std::string const &pat : args)
{
if (!*it)
throw emu_fatalerror(EMU_ERR_NO_SUCH_GAME, "No matching systems found for '%s'", pat.c_str());
++it;
}
apply_action(
args,
[&list_system_name] (driver_enumerator &drivlist, bool first)
{ list_system_name(drivlist.driver().type, first); },
[&list_system_name] (device_type type, bool first)
{ list_system_name(type, first); });
}
@ -430,16 +373,16 @@ void cli_frontend::listfull(const std::vector<std::string> &args)
void cli_frontend::listsource(const std::vector<std::string> &args)
{
const char *gamename = args.empty() ? nullptr : args[0].c_str();
// determine which drivers to output; return an error if none found
driver_enumerator drivlist(m_options, gamename);
if (drivlist.count() == 0)
throw emu_fatalerror(EMU_ERR_NO_SUCH_GAME, "No matching systems found for '%s'", gamename);
// iterate through drivers and output the info
while (drivlist.next())
osd_printf_info("%-16s %s\n", drivlist.driver().name, core_filename_extract_base(drivlist.driver().type.source()).c_str());
auto const list_system_source = [] (device_type type)
{
osd_printf_info("%-16s %s\n", type.shortname(), core_filename_extract_base(type.source()).c_str());
};
apply_action(
args,
[&list_system_source] (driver_enumerator &drivlist, bool first)
{ list_system_source(drivlist.driver().type); },
[&list_system_source] (device_type type, bool first)
{ list_system_source(type); });
}
@ -547,164 +490,92 @@ void cli_frontend::listbrothers(const std::vector<std::string> &args)
void cli_frontend::listcrc(const std::vector<std::string> &args)
{
const char *gamename = args.empty() ? nullptr : args[0].c_str();
// determine which drivers to output; return an error if none found
driver_enumerator drivlist(m_options, gamename);
if (drivlist.count() == 0)
throw emu_fatalerror(EMU_ERR_NO_SUCH_GAME, "No matching systems found for '%s'", gamename);
// iterate through matches, and then through ROMs
while (drivlist.next())
{
for (device_t const &device : device_iterator(drivlist.config()->root_device()))
{
for (tiny_rom_entry const *rom = device.rom_region(); rom && !ROMENTRY_ISEND(rom); ++rom)
apply_device_action(
args,
[] (device_t &root, char const *type, bool first)
{
if (ROMENTRY_ISFILE(rom))
for (device_t const &device : device_iterator(root))
{
// if we have a CRC, display it
uint32_t crc;
if (util::hash_collection(rom->hashdata).crc(crc))
osd_printf_info("%08x %-32s\t%-16s\t%s\n", crc, rom->name, device.shortname(), device.name());
for (tiny_rom_entry const *rom = device.rom_region(); rom && !ROMENTRY_ISEND(rom); ++rom)
{
if (ROMENTRY_ISFILE(rom))
{
// if we have a CRC, display it
uint32_t crc;
if (util::hash_collection(rom->hashdata).crc(crc))
osd_printf_info("%08x %-32s\t%-16s\t%s\n", crc, rom->name, device.shortname(), device.name());
}
}
}
}
}
}
});
}
//-------------------------------------------------
// listroms - output the list of ROMs referenced
// by a given game or set of games
// by matchign systems/devices
//-------------------------------------------------
void cli_frontend::listroms(const std::vector<std::string> &args)
{
bool const iswild((1U != args.size()) || core_iswildstr(args[0].c_str()));
std::vector<bool> matched(args.size(), false);
auto const included = [&args, &matched] (char const *name) -> bool
{
if (args.empty())
return true;
bool result = false;
auto it = matched.begin();
for (std::string const &pat : args)
{
if (!core_strwildcmp(pat.c_str(), name))
apply_device_action(
args,
[] (device_t &root, char const *type, bool first)
{
result = true;
*it = true;
}
++it;
}
return result;
};
bool first = true;
auto const list_system_roms = [&first] (device_t &root, char const *type)
{
// print a header
if (!first)
osd_printf_info("\n");
first = false;
// iterate through roms
bool hasroms = false;
for (device_t const &device : device_iterator(root))
{
for (const rom_entry *region = rom_first_region(device); region; region = rom_next_region(region))
{
for (const rom_entry *rom = rom_first_file(region); rom; rom = rom_next_file(rom))
{
// print a header
if (!hasroms)
osd_printf_info(
"ROMs required for %s \"%s\".\n"
"%-32s %10s %s\n",
type, root.shortname(), "Name", "Size", "Checksum");
hasroms = true;
// accumulate the total length of all chunks
int64_t length = -1;
if (ROMREGION_ISROMDATA(region))
length = rom_file_size(rom);
// start with the name
const char *name = ROM_GETNAME(rom);
osd_printf_info("%-32s ", name);
// output the length next
if (length >= 0)
osd_printf_info("%10u", unsigned(uint64_t(length)));
else
osd_printf_info("%10s", "");
// output the hash data
util::hash_collection hashes(ROM_GETHASHDATA(rom));
if (!hashes.flag(util::hash_collection::FLAG_NO_DUMP))
{
if (hashes.flag(util::hash_collection::FLAG_BAD_DUMP))
osd_printf_info(" BAD");
osd_printf_info(" %s", hashes.macro_string().c_str());
}
else
osd_printf_info(" NO GOOD DUMP KNOWN");
// end with a CR
// space between items
if (!first)
osd_printf_info("\n");
// iterate through roms
bool hasroms = false;
for (device_t const &device : device_iterator(root))
{
for (const rom_entry *region = rom_first_region(device); region; region = rom_next_region(region))
{
for (const rom_entry *rom = rom_first_file(region); rom; rom = rom_next_file(rom))
{
// print a header
if (!hasroms)
osd_printf_info(
"ROMs required for %s \"%s\".\n"
"%-32s %10s %s\n",
type, root.shortname(), "Name", "Size", "Checksum");
hasroms = true;
// accumulate the total length of all chunks
int64_t length = -1;
if (ROMREGION_ISROMDATA(region))
length = rom_file_size(rom);
// start with the name
const char *name = ROM_GETNAME(rom);
osd_printf_info("%-32s ", name);
// output the length next
if (length >= 0)
osd_printf_info("%10u", unsigned(uint64_t(length)));
else
osd_printf_info("%10s", "");
// output the hash data
util::hash_collection hashes(ROM_GETHASHDATA(rom));
if (!hashes.flag(util::hash_collection::FLAG_NO_DUMP))
{
if (hashes.flag(util::hash_collection::FLAG_BAD_DUMP))
osd_printf_info(" BAD");
osd_printf_info(" %s", hashes.macro_string().c_str());
}
else
osd_printf_info(" NO GOOD DUMP KNOWN");
// end with a CR
osd_printf_info("\n");
}
}
}
}
}
if (!hasroms)
osd_printf_info("No ROMs required for %s \"%s\".\n", type, root.shortname());
};
// determine which drivers to output
driver_enumerator drivlist(m_options);
// iterate through matches
while (drivlist.next())
{
if (included(drivlist.driver().name))
{
list_system_roms(drivlist.config()->root_device(), "driver");
// if it wasn't a wildcard, there can only be one
if (!iswild)
break;
}
}
if (iswild || first)
{
machine_config config(GAME_NAME(___empty), m_options);
machine_config::token const tok(config.begin_configuration(config.root_device()));
for (device_type type : registered_device_types)
{
if (included(type.shortname()))
{
device_t *const dev = config.device_add("_tmp", type, 0);
list_system_roms(*dev, "device");
config.device_remove("_tmp");
// if it wasn't a wildcard, there can only be one
if (!iswild)
break;
}
}
}
// return an error if none found
auto it = matched.begin();
for (std::string const &pat : args)
{
if (!*it)
throw emu_fatalerror(EMU_ERR_NO_SUCH_GAME, "No matching systems found for '%s'", pat.c_str());
++it;
}
if (!hasroms)
osd_printf_info("No ROMs required for %s \"%s\".\n", type, root.shortname());
});
}
@ -1427,6 +1298,7 @@ void cli_frontend::verifysoftware(const std::vector<std::string> &args)
}
/*-------------------------------------------------
getsoftlist - retrieve software list by name
-------------------------------------------------*/
@ -1560,6 +1432,105 @@ void cli_frontend::romident(const std::vector<std::string> &args)
}
//-------------------------------------------------
// apply_action - apply action to matching
// systems/devices
//-------------------------------------------------
template <typename T, typename U> void cli_frontend::apply_action(const std::vector<std::string> &args, T &&drvact, U &&devact)
{
bool const iswild((1U != args.size()) || core_iswildstr(args[0].c_str()));
std::vector<bool> matched(args.size(), false);
auto const included = [&args, &matched] (char const *name) -> bool
{
if (args.empty())
return true;
bool result = false;
auto it = matched.begin();
for (std::string const &pat : args)
{
if (!core_strwildcmp(pat.c_str(), name))
{
result = true;
*it = true;
}
++it;
}
return result;
};
// determine which drivers to output
driver_enumerator drivlist(m_options);
// iterate through matches
bool first(true);
while (drivlist.next())
{
if (included(drivlist.driver().name))
{
drvact(drivlist, first);
first = false;
// if it wasn't a wildcard, there can only be one
if (!iswild)
break;
}
}
if (iswild || first)
{
for (device_type type : registered_device_types)
{
if (included(type.shortname()))
{
devact(type, first);
first = false;
// if it wasn't a wildcard, there can only be one
if (!iswild)
break;
}
}
}
// return an error if none found
auto it = matched.begin();
for (std::string const &pat : args)
{
if (!*it)
throw emu_fatalerror(EMU_ERR_NO_SUCH_GAME, "No matching systems found for '%s'", pat.c_str());
++it;
}
}
//-------------------------------------------------
// apply_device_action - apply action to matching
// systems/devices
//-------------------------------------------------
template <typename T> void cli_frontend::apply_device_action(const std::vector<std::string> &args, T &&action)
{
machine_config config(GAME_NAME(___empty), m_options);
machine_config::token const tok(config.begin_configuration(config.root_device()));
apply_action(
args,
[&action] (driver_enumerator &drivlist, bool first)
{
action(drivlist.config()->root_device(), "driver", first);
},
[&action, &config] (device_type type, bool first)
{
device_t *const dev = config.device_add("_tmp", type, 0);
action(*dev, "device", first);
config.device_remove("_tmp");
});
}
//-------------------------------------------------
// find_command
//-------------------------------------------------
@ -1570,10 +1541,10 @@ const cli_frontend::info_command_struct *cli_frontend::find_command(const std::s
{
{ CLICOMMAND_LISTXML, 0, -1, &cli_frontend::listxml, "[pattern] ..." },
{ CLICOMMAND_LISTFULL, 0, -1, &cli_frontend::listfull, "[pattern] ..." },
{ CLICOMMAND_LISTSOURCE, 0, 1, &cli_frontend::listsource, "[system name]" },
{ CLICOMMAND_LISTSOURCE, 0, -1, &cli_frontend::listsource, "[system name]" },
{ CLICOMMAND_LISTCLONES, 0, 1, &cli_frontend::listclones, "[system name]" },
{ CLICOMMAND_LISTBROTHERS, 0, 1, &cli_frontend::listbrothers, "[system name]" },
{ CLICOMMAND_LISTCRC, 0, 1, &cli_frontend::listcrc, "[system name]" },
{ CLICOMMAND_LISTCRC, 0, -1, &cli_frontend::listcrc, "[system name]" },
{ CLICOMMAND_LISTDEVICES, 0, 1, &cli_frontend::listdevices, "[system name]" },
{ CLICOMMAND_LISTSLOTS, 0, 1, &cli_frontend::listslots, "[system name]" },
{ CLICOMMAND_LISTROMS, 0, -1, &cli_frontend::listroms, "[pattern] ..." },
@ -1622,6 +1593,11 @@ void cli_frontend::execute_commands(const char *exename)
// validate?
if (m_options.command() == CLICOMMAND_VALIDATE)
{
if (m_options.command_arguments().size() > 1)
{
osd_printf_error("Auxillary verb -validate takes at most 1 argument\n");
return;
}
validity_checker valid(m_options);
valid.set_validate_all(true);
const char *sysname = m_options.command_arguments().empty() ? nullptr : m_options.command_arguments()[0].c_str();

2
src/frontend/mame/clifront.h
View File

@ -67,6 +67,8 @@ private:
void verifysoftlist(const std::vector<std::string> &args);
// internal helpers
template <typename T, typename U> void apply_action(const std::vector<std::string> &args, T &&drvact, U &&devact);
template <typename T> void apply_device_action(const std::vector<std::string> &args, T &&action);
void execute_commands(const char *exename);
void display_help(const char *exename);
void output_single_softlist(FILE *out, software_list_device &swlist);

2
src/frontend/mame/language.cpp
View File

@ -72,7 +72,7 @@ void load_translation(emu_options &m_options)
{
std::string original = (const char *)data + buffer[original_table_offset + 2 * i + 1];
std::string translation = (const char *)data + buffer[translation_table_offset + 2 * i + 1];
g_translation.insert(std::pair<std::string, std::string>(original, translation));
g_translation.emplace(std::move(original), std::move(translation));
}
global_free_array(buffer);
}