To compile MAME, you need a C++17 compiler and runtime library. We support building with GCC version 7.2 or later and clang version 6 or later. MAME should run with GNU libstdc++ version 7.2 or later.
Whenever you are changing build parameters, (such as switching between a SDL-based build and a native Windows renderer one, or adding tools to the compile list) you need to run a make REGENIE=1 to allow the settings to be regenerated. Failure to do this will cause you very difficult to troubleshoot problems.
If you want to add various additional tools to the compile, such as chdman, add a TOOLS=1 to your make command, like make REGENIE=1 TOOLS=1
You can do driver specific builds by using SOURCES=<driver> in your make command. For instance, building Pac-Man by itself would be make SOURCES=src/mame/drivers/pacman.cpp REGENIE=1 including the necessary REGENIE for rebuilding the settings.
Speeding up the compilation can be done by using more cores from your CPU. This is done with the -j parameter. Note: a good number to start with is the total number of CPU cores in your system plus one. An excessive number of concurrent jobs may increase compilation time. The optimal number depends on many factors, including number of CPU cores, available RAM, disk and filesystem performance, and memory bandwidth. For instance, make -j5 is a good starting point on a system with a quad-core CPU.
Debugging information can be added to a compile using SYMBOLS=1 though most users will not want or need to use this. This increases compile time and disk space used.
Putting all of these together, we get a couple of examples:
Rebuilding MAME for just the Pac-Man driver, with tools, on a quad-core (e.g. i5 or i7) machine:
make SOURCES=src/mame/drivers/pacman.cpp TOOLS=1 REGENIE=1 -j5
Rebuilding MAME on a dual-core (e.g. i3 or laptop i5) machine:
MAME for Windows is built using the MSYS2 environment. You will need Windows 7 or later and a reasonably up-to-date MSYS2 installation. We strongly recommend building MAME on a 64-bit system. Instructions may need to be adjusted for 32-bit systems.
A pre-packaged MSYS2 installation including the prerequisites for building MAME can be downloaded from the MAME Build Tools page.
After initial installation, you can update the MSYS2 environment using the pacman (Arch package manage) command.
By default, MAME will be built using native Windows OS interfaces for window management, audio/video output, font rendering, etc. If you want to use the portable SDL (Simple DirectMedia Layer) interfaces instead, you can add OSD=sdl to the make options. The main emulator binary will have an
sdlprefix prepended (e.g.
sdlmame.exe). You will need to install the MSYS2 packages for SDL 2 version 2.0.3 or later.
By default, MAME will include the native Windows debugger. To also include the portable Qt debugger, add USE_QTDEBUG=1 to the make options. You will need to install the MSYS2 packages for Qt 5.
You may also build MAME using a standard MSYS2 installation and adding the tools needed for building MAME. These instructions assume you have some familiarity with MSYS2 and the pacman package manager.
Install the MSYS2 environment from the MSYS2 homepage.
Download the latest version of the
mame-essentialspackage from the MAME package repository and install it using the pacman command.
Install packages necessary to build MAME. At the very least, you’ll need
For 64-bit builds you’ll need
For 32-bit builds you’ll need
For debugging you may want to install
To link using the LLVM linker (generally much faster than the GNU linker), you’ll need
mingw-w64-x86_64-libc++for 64-bit builds, or
mingw-w64-i686-libc++for 32-bit builds.
To build against the portable SDL interfaces, you’ll need
mingw-w64-x86_64-SDL2_ttffor 64-bit builds, or
mingw-w64-i686-SDL2_ttffor 32-bit builds.
To build the Qt debugger, you’ll need
mingw-w64-x86_64-qt5for 64-bit builds, or
mingw-w64-i686-qt5for 32-bit builds.
To build the HTML user/developer documentation, you’ll need
mingw-w64-x86_64-python-sphinxcontrib-svg2pdfconverterfor a 64-bit MinGW environment (or alternatively
mingw-w64-x86_64-python-sphinxcontrib-svg2pdfconvertera 32-bit MinGW environment).
To generate API documentation from source, you’ll need
If you plan to rebuild bgfx shaders and you want to rebuild the GLSL parser, you’ll need
For 64-bit builds, open MSYS2 MinGW 64-bit from the start menu, and set up the environment variables
MINGW32to an empty string (e.g. using the command export MINGW64=/mingw64 MINGW32= in the Bash shell).
For 32-bit builds, open MSYS2 MinGW 32-bit from the start menu, and set up the environment variables
MINGW64to an empty string (e.g. using the command export MINGW32=/mingw32 MINGW64= in the Bash shell).
For example you could use these commands to ensure you have the packages you need to compile MAME, omitting the ones for configurations you don’t plan to build for or combining multiple pacman commands to install more packages at once:
pacman -Syu pacman -S curl git make pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-libc++ mingw-w64-x86_64-lld mingw-w64-x86_64-python pacman -S mingw-w64-x86_64-SDL2 mingw-w64-x86_64-SDL2_ttf pacman -S mingw-w64-x86_64-qt5 pacman -S mingw-w64-i686-gcc mingw-w64-i686-libc++ mingw-w64-i686-lld mingw-w64-i686-python pacman -S mingw-w64-i686-SDL2 mingw-w64-i686-SDL2_ttf pacman -S mingw-w64-i686-qt5
You could use these commands to install the current version of the mame-essentials package and add the MAME package repository to your pacman configuration:
curl -O "https://repo.mamedev.org/x86_64/mame-essentials-1.0.6-1-x86_64.pkg.tar.xz" pacman -U mame-essentials-1.0.6-1-x86_64.pkg.tar.xz echo -e '\n[mame]\nInclude = /etc/pacman.d/mirrorlist.mame' >> /etc/pacman.conf
You can generate Visual Studio 2019 projects using make vs2019. The solution and project files will be created in
build/projects/windows/mame/vs2019by default (the name of the
buildfolder can be changed using the
BUILDDIRoption). This will always regenerate the settings, so REGENIE=1 is not needed.
Adding MSBUILD=1 to the make options will build the solution using the Microsoft Build Engine after generating the project files. Note that this requires paths and environment variables to be configured so the correct Visual Studio tools can be located; please refer to the Microsoft-provided instructions on using the Microsoft C++ toolset from the command line. You may find it easier to not use MSBUILD=1 and load the project file into Visual Studio’s GUI for compilation.
The MSYS2 environment is still required to generate the project files, convert built-in layouts, compile UI translations, etc.
MSYS2 uses the pacman tool from Arch Linux for package management. There is a page on the Arch Linux wiki with helpful information on using the pacman package management tool.
The MSYS2 environment includes two kinds of tools: MSYS2 tools designed to work
in a UNIX-like environment on top of Windows, and MinGW tools designed to work
in a more Windows-like environment. The MSYS2 tools are installed in
/usr/bin while the MinGW tools are installed in
/mingw32/bin (relative to the MSYS2 installation directory). MSYS2 tools
work best in an MSYS2 terminal, while MinGW tools work best in a Microsoft
The most obvious symptom of this is that arrow keys don’t work in interactive programs if you run them in the wrong kind of terminal. If you run MinGW gdb or python from an MSYS2 terminal window, command history won’t work and it may not be possible to interrupt an attached program with gdb. Similarly it may be very difficult to edit using MSYS2 vim in a Microsoft command prompt window.
MAME is built using the MinGW compilers, so the MinGW directories are included
earlier in the
PATH for the build environments. If you want to use an
interactive MSYS2 program from an MSYS2 shell, you may need to type the absolute
path to avoid using the MinGW equivalent instead.
MSYS2 gdb may have issues debugging MinGW programs like MAME. You may get better results by installing the MinGW version of gdb and running it from a Microsoft command prompt window to debug MAME.
GNU make supports both POSIX-style shells (e.g. bash) and the Microsoft cmd.exe
shell. One issue to be aware of when using the cmd.exe shell is that the
copy command doesn’t provide a useful exit status, so file copy tasks can
It is not possible to cross-compile a 32-bit version of MAME using 64-bit MinGW tools on Windows, the 32-bit MinGW tools must be used. This causes issues due to the size of MAME. It is not possible to link a full 32-bit MAME build including the SDL OS-dependent layer and the Qt debugger. GNU ld and lld will both run out of memory, leaving an output file that doesn’t work. It’s also impossible to make a 32-bit build with full local variable symbols. GCC may run out of memory, and certain source files may exceed the limit of 32,768 sections imposed by the PE/COFF object file format.
You’ll need a few prerequisites from your Linux distribution. Make sure you get SDL2 2.0.4 or later as earlier versions are buggy:
sudo dnf install gcc gcc-c++ SDL2-devel SDL2_ttf-devel libXi-devel libXinerama-devel qt5-qtbase-devel qt5-qttools expat-devel fontconfig-devel alsa-lib-devel pulseaudio-libs-devel
Compilation is exactly as described above in All Platforms.
To build the HTML user/developer documentation, you’ll need Sphinx, as well as the theme and the SVG converter:
sudo dnf install python3-sphinx python3-sphinx_rtd_theme python3-sphinxcontrib-rsvgconverter
The HTML documentation can be built with this command:
make -C docs SPHINXBUILD=sphinx-build-3 html
You’ll need a few prerequisites from your Linux distribution. Make sure you get SDL2 2.0.4 or later as earlier versions are buggy:
sudo apt-get install git build-essential python libsdl2-dev libsdl2-ttf-dev libfontconfig-dev libpulse-dev qt5-default
Compilation is exactly as described above in All Platforms. Note the Ubuntu Linux modifies GCC to enable the GNU C Library “fortify source” feature by default, which may cause issues compiling MAME (see Known Issues).
You’ll need a few prerequisites from your distro:
sudo pacman -S base-devel git sdl2 gconf sdl2_ttf gcc qt5
Compilation is exactly as described above in All Platforms.
You’ll need a few prerequisites to get started. Make sure you’re on OS X 10.14 Mojave or later for Intel Macs or macOS 11.0 Big Sur for Apple Silicon. You will need SDL2 2.0.4 or later for Intel or SDL2 2.0.14 on Apple Silicon. You’ll also need to install Python 3.
Install Xcode from the Mac App Store or ADC (AppleID required).
To find the corresponding Xcode for your MacOS release please visit xcodereleases.com to find the latest version of Xcode available to you.
Launch Xcode. It will download a few additional prerequisites. Let this run through before proceeding.
Once that’s done, quit Xcode and open a Terminal window.
Type xcode-select --install to install additional tools necessary for MAME (also available as a package on ADC).
Next you’ll need to get SDL2 installed.
Go to this site and download the macOS .dmg file
If the .dmg doesn’t open automatically, open it
Click “Macintosh HD” (or whatever your Mac’s hard disk is named) in the left pane of a Finder window, then open the Library folder and drag the SDL2.framework folder from the SDL disk image into the Frameworks folder. You will have to authenticate with your user password.
Now get Python 3 set up:
Scroll down to the “Files” section, and download the macOS version (called “macOS 64-bit universal2 installer” or similar).
Once the package downloads, open it and follow the standard installation process.
Finally to begin compiling, use Terminal to navigate to where you have the MAME source tree (cd command) and follow the normal compilation instructions from above in All Platforms.
First, download and install Emscripten 1.37.29 or later by following the instructions at the official site.
Once Emscripten has been installed, it should be possible to compile MAME out-of-the-box using Emscripten’s emmake tool. Because a full MAME compile is too large to load into a web browser at once, you will want to use the SOURCES parameter to compile only a subset of the project, e.g. (in the MAME directory):
emmake make SUBTARGET=pacmantest SOURCES=src/mame/drivers/pacman.cpp
The SOURCES parameter should have the path to at least one driver .cpp file. The make process will attempt to locate and include all dependencies necessary to produce a complete build including the specified driver(s). However, sometimes it is necessary to manually specify additional files (using commas) if this process misses something. e.g.
emmake make SUBTARGET=apple2e SOURCES=src/mame/drivers/apple2e.cpp,src/mame/machine/applefdc.cpp
The value of the SUBTARGET parameter serves only to differentiate multiple builds and need not be set to any specific value.
Other make parameters can also be used, e.g. -j for multithreaded compilation as described earlier.
When the compilation reaches the emcc phase, you may see a number of "unresolved symbol" warnings. At the moment, this is expected for OpenGL-related functions such as glPointSize. Any others may indicate that an additional dependency file needs to be specified in the SOURCES list. Unfortunately this process is not automated and you will need to search the source tree to locate the files supplying the missing symbols. You may also be able to get away with ignoring the warnings if the code path referencing them is not used at run-time.
If all goes well, a .js file will be output to the current directory. This file cannot be run by itself, but requires an HTML loader to provide it with a canvas to draw to and to pass in command-line parameters. The Emularity project provides such a loader.
There are example .html files in that repository which can be edited to point to your newly compiled MAME .js file and pass in whatever parameters you desire. You will then need to place all of the following on a web server:
The compiled MAME .js file
The compiled MAME .wasm file if using WebAssembly
The .js files from the Emularity package (loader.js, browserfs.js, etc.)
A .zip file with the ROMs for the MAME driver you would like to run (if any)
Any software files you would like to run with the MAME driver
An Emularity loader .html modified to point to all of the above
You need to use a web server instead of opening the local files directly due to security restrictions in modern web browsers.
If the result fails to run, you can open the Web Console in your browser to see any error output which may have been produced (e.g. missing or incorrect ROM files). A “ReferenceError: foo is not defined” error most likely indicates that a needed source file was omitted from the SOURCES list.
Compiling the documentation will require you to install several packages depending on your operating system.
On Windows, you’ll need a couple of packages from the MSYS2 environment. You can install these packages with
pacman -S mingw-w64-x86_64-librsvg mingw-w64-x86_64-python-sphinx mingw-w64-x86_64-python-sphinxcontrib-svg2pdfconverter
Note that no LaTeX packages currently exist for MSYS2 so you will not be able to generate a PDF file without using external tools.
On Debian/Ubuntu flavors of Linux, you’ll need python3-sphinx/python-sphinx and the python3-pip/python-pip packages:
sudo apt-get install python3-sphinx python3-pip pip3 install sphinxcontrib-svg2pdfconverter
On Debian, you’ll need to install the librsvg2-bin package:
sudo apt-get install librsvg2-bin
If you intend to make a PDF via LaTeX, you’ll need to install a LaTeX distribution such as TeX Live:
sudo apt-get install librsvg2-bin latexmk texlive texlive-science texlive-formats-extra
From this point you can do
make html or
make latexpdf from the docs
folder to generate the output of your choice. Typing
make by itself will
tell you all available formats. The output will be in the docs/build folder in
a subfolder based on the type chosen (e.g.
make html will create
docs/build/html with the output.)
This section summarises some of the more useful options recognised by the main makefile. You use these options by appending them to the make command, setting them as environment variables, or adding them to your prefix makefile. Note that in order to apply many of these settings when rebuilding, you need to set REGENIE=1 the first time you build after changing the option(s). Also note that GENie does not automatically rebuild affected files when you change an option that affects compiler settings.
Name of a makefile to include for additional options if found (defaults to useroptions.mak). May be useful if you want to quickly switch between different build configurations.
Set to change the name of the subfolder used for project files, generated sources, object files, and intermediate libraries (defaults to build).
Set to 1 to force project files to be regenerated.
Set to 1 to show full commands when using GNU make as the build tool. This option applies immediately without needing regenerate project files.
Set to 1 to skip the working tree scan and not attempt to embed a git revision description in the version string.
Set the C/Objective-C compiler command. (This sets the target C compiler command when cross-compiling.)
Set the C++/Objective-C++ compiler command. (This sets the target C++ compiler command when cross-compiling.)
Set the linker command. This is often not necessary or useful because the C or C++ compiler command is used to invoke the linker. (This sets the target linker command when cross-compiling.)
Set the Python interpreter command. You need Python 3.2 or later to build MAME.
Set to 1 to use separate host and target compilers and linkers, as required for cross-compilation. In this case, OVERRIDE_CC, OVERRIDE_CXX and OVERRIDE_LD set the target C compiler, C++ compiler and linker commands, while CC, CXX and LD set the host C compiler, C++ compiler and linker commands.
Set to 1 to build additional tools along with the emulator, including unidasm, chdman, romcmp, and srcclean.
Set to 1 to disable building the PortAudio sound output module.
Set to 1 to include the Qt debugger on platforms where it’s not built by default (e.g. Windows or macOS), or to 0 to disable it. You’ll need to install Qt development libraries and tools to build the Qt debugger. The process depends on the platform.
Set to 1 to disable treating compiler warnings as errors. This may be needed in marginally supported configurations.
Set to 0 to disable deprecation warnings (note that deprecation warnings are not treated as errors).
Set to 1 to enable runtime assertion checks and additional diagnostics. Note that this has a performance cost, and is most useful for developers.
Set optimisation level. The default is 3 to favour performance at the expense of larger executable size. Set to 0 to disable optimisation (can make debugging easier), 1 for basic optimisation that doesn’t have a space/speed trade-off and doesn’t have a large impact on compile time, 2 to enable most optimisation that improves performance and reduces size, or s to enable only optimisations that generally don’t increase executable size. The exact set of supported values depends on your compiler.
Set to 1 to include additional debugging symbols over the default for the target platform (many target platforms include function name symbols by default).
Numeric value that controls the level of detail in debugging symbols. Higher numbers make debugging easier at the cost of increased build time and executable size. The supported values depend on your compiler. For GCC and similar compilers, 1 includes line number tables and external variables, 2 also includes local variables, and 3 also includes macro definitions.
Additional command-line options to pass to the compiler and linker. This is useful for supplying code generation or ABI options, for example to enable support for optional CPU features.
Additional command-line options to pass to the compiler when compiling C source files.
Additional command-line options to pass to the compiler when compiling C++ source files.
Additional command-line options to pass to the compiler when compiling Objective-C source files.
Additional command-line options to pass to the compiler when compiling Objective-C++ source files.
SDL installation root directory for shared library style SDL.
Search path for SDL framework.
Set to 1 to use shared library style SDL on targets where framework is default.
Set to 1 to prefer the system installation of the Asio C++ asynchronous I/O library over the version provided with the MAME source.
Set to 1 to prefer the system installation of the Expat XML parser library over the version provided with the MAME source.
Set to 1 to prefer the system installation of the zlib data compression library over the version provided with the MAME source.
Set to 1 to prefer the system installation of the libjpeg image compression library over the version provided with the MAME source.
Set to 1 to prefer the system installation of the libFLAC audio compression library over the version provided with the MAME source.
Set to 1 to prefer the system installation of the embedded Lua interpreter over the version provided with the MAME source.
Set to 1 to prefer the system installation of the SQLITE embedded database engine over the version provided with the MAME source.
Set to 1 to prefer the system installation of the PortMidi library over the version provided with the MAME source.
Set to 1 to prefer the system installation of the PortAudio library over the version provided with the MAME source.
Set to 1 to prefer the version of SDL provided with the MAME source over the system installation. (This is enabled by default for Visual Studio and Android builds. For other configurations, the system installation of SDL is preferred.)
Set to 1 to prefer the system installation of the Julia utf8proc library over the version provided with the MAME source.
Set to 1 to prefer the system installation of the GLM OpenGL Mathematics library over the version provided with the MAME source.
Set to 1 to prefer the system installation of the Tencent RapidJSON library over the version provided with the MAME source.
Set to 1 to prefer the system installation of the pugixml library over the version provided with the MAME source.
GCC 7 for 32-bit x86 targets produces spurious out-of-bounds access warnings. Adding NOWERROR=1 to your build options works around this by not treating warnings as errors.
The GNU C Library has options to perform additional compile- and run-time
checks on string operations, enabled by defining the
preprocessor macro. This is intended to improve security at the cost of a
small amount of overhead. MAME is not secure software, and we do not
support building with
Some Linux distributions (including Gentoo and Ubuntu) have patched GCC to
1 as a built-in macro. This is problematic
for more projects than just MAME, as it makes it hard to disable the additional
checks (e.g. if you don’t want the performance impact of the run-time checks),
and it also makes it hard to define
2 if you want to
enable stricter checks. You should really take it up with the distribution
maintainers, and make it clear you don’t want non-standard GCC behaviour. It
would be better if these distributions defined this macro by default in their
packaging environments if they think it’s important, rather than trying to force
it on everything compiled on their distributions. (This is what Red Hat does:
_FORTIFY_SOURCE macro is set in the RPM build environment, and not by
distributing a modified version of GCC.)
If you get compilation errors in
bits/string_fortified.h you should first
ensure that the
_FORTIY_SOURCE macro is defined via the environment (e.g.
a CFLAGS or CXXFLAGS environment variable). You can check to see
_FORTIFY_SOURCE macro is a built-in macro with your version of
GCC with a command like this:
gcc -dM -E - < /dev/null | grep _FORTIFY_SOURCE
_FORTIFY_SOURCE is defined to a non-zero value by default, you can work
around it by adding -U_FORTIFY_SOURCE to the compiler flags (e.g. by using
the ARCHOPTS setting, or setting the CFLAGS and CXXFLAGS environment
MAME’s build system has basic support for cross-compilation. Set CROSS_BUILD=1 to enable separate host and target compilers, set OVERRIDE_CC and OVERRIDE_CXX to the target C/C++ compiler commands, and if necessary set CC and CXX to the host C/C++ compiler commands. If the target OS is different to the host OS, set it with TARGETOS. For example it may be possible to build a MinGW32 x64 build on a Linux host using a command like this:
make TARGETOS=windows PTR64=1 OVERRIDE_CC=x86_64-w64-mingw32-gcc OVERRIDE_CXX=x86_64-w64-mingw32-g++ OVERRIDE_LD=x86_64-w64-mingw32-ld MINGW64=/usr**
(The additional packages required for producing a standard MinGW32 x64 build on
a Fedora Linux host are
their dependencies. Non-standard builds may require additional packages.)
MAME may be built using the LLVM project’s “libc++” C++ Standard Library. The prerequisites are a working clang/LLVM installation, and the libc++ development libraries. On Fedora Linux, the necessary packages are libcxx, libcxx-devel, libcxxabi and libcxxabi-devel. Set the C and C++ compiler commands to use clang, and add -stdlib=libc++ to the C++ compiler and linker options. You could use a command like this:
env LDFLAGS=-stdlib=libc++ make OVERRIDE_CC=clang OVERRIDE_CXX=clang++ ARCHOPTS_CXX=-stdlib=libc++ ARCHOPTS_OBJCXX=-stdlib=libc++
The options following the make command may be placed in a prefix makefile if you want to use this configuration regularly, but LDFLAGS needs to be be set in the environment.
GCC may be built and installed to a custom location, typically by supplying the --prefix= option to the configure command. This may be useful if you want to build MAME on a Linux distribution that still uses a version of GNU libstdC++ that predates C++17 support. To use an alternate GCC installation to, build MAME, set the C and C++ compilers to the full paths to the gcc and g++ commands, and add the library path to the run-time search path. If you installed GCC in /opt/local/gcc72, you might use a command like this:
make OVERRIDE_CC=/opt/local/gcc72/bin/gcc OVERRIDE_CXX=/opt/local/gcc72/bin/g++ ARCHOPTS=-Wl,-R,/opt/local/gcc72/lib64
You can add these options to a prefix makefile if you plan to use this configuration regularly.