MAME Build Tools

Introduction

The standard environment for building MAME on Windows consists of:

• The MSYS2 environment (a Linux-like POSIX compatibility layer
• The MinGW GCC or clang compiler and libraries
• Various utilities including Git, Python and GNU Make

You can create a suitable environment by installing MSYS2, and then installing the necessary additional packages using the pacman package manager command.

Our main source code repository is hosted on GitHub (https://github.com/mamedev/mame.git), so you’ll need to check out a copy. Various optional features are disabled by default, but can be by passing additional arguments to the make command. Optional features may require additional MSYS2 packages to be installed. For more information on compiling MAME, see the relevant page on our documentation site.

Installation and building

Installation

First, download a copy of the MSYS2 environment from their web site and install it. Note that the MSYS2 environment requires a 64-bit edition of Windows 10 1809 or later for x86 or ARM. After installing the MSYS2 environment, open one of the MSYS2 shells so you can start installing packages.

You will always need to install Git, GNU Make, and the diff/patch utilities:

pacman -S git make diffutils patch

The additional packages you will need depend on the environment you will be using to build MAME. If you’re using an x86 system, you can use the UCRT64 environment. This gives you a choice of the GCC and clang compilers. You can also use the CLANG64 environment, although this limits you to using the clang compiler, and some additional tools may not be available. If you’re using an ARM system, you should use the CLANGARM64 environment.

If you’re using the UCRT64 environment, you should install Python and the LLVM tools used for archiving static libraries and linking:

pacman -S mingw-w64-ucrt-x86_64-{python,libc++,llvm,llvm-tools,lld,gdb}

If you’ll be building with the GCC compiler, install it as well:

pacman -S mingw-w64-ucrt-x86_64-gcc

If you’ll be building with the clang compiler, install it as well:

pacman -S mingw-w64-ucrt-x86_64-clang

If you’re using the CLANG64 environment, you should install Python, the LLVM tools used for archiving static libraries and linking, clang, and the GCC compatibility wrapper:

pacman -S mingw-w64-clang-x86_64-{python,libc++,llvm,llvm-tools,lld,gdb,clang,gcc-compat}

If you’re using the CLANGARM64 environment, you should install Python, the LLVM tools used for archiving static libraries and linking, clang, and the GCC compatibility wrapper:

pacman -S mingw-w64-clang-aarch64-{python,libc++,llvm,llvm-tools,lld,lldb,clang,gcc-compat}

After installing the required packages, an important thing is to set up Git first:

git config --global core.autocrlf true

And if you are contributor:

git config --global user.email youremail@something.com

git config --global user.name "Firstname Lastname"

About shells

The shell you should use depends on the environment you’re using to build MAME:

• ucrt64.exe for the 64-bit x86 UCRT64 environment
• clang64.exe for the 64-bit x86 CLANG64 environment
• clangarm64.exe for the 64-bit ARM CLANGARM64 environment

If you want to use the MSYS2 tools in a Windows Command Prompt, first open the appropriate type of MSYS2 shell as listed above, then start the Windows Command Prompt using the aptly named start command:

start cmd

This will start a Command Prompt that inherits the environment and working directory from the MSYS2 shell.

For more information about MSYS2, see MSYS2-Introduction.

Building

Then, to download the MAME source inside your MSYS2 home directory:

git clone https://github.com/mamedev/mame.git

Alternatively, locate your existing source tree (drives are mapped to hidden directories /c etc. under the virtual root):

cd /c/Projects/mame

And finally to build, if you’re using the GCC compiler:

make

Or if you’re using the clang compiler:

make OVERRIDE_CC=clang OVERRIDE_CXX=clang++

Updating build tools

Similar to package managers on Linux like apt-get, yum etc. MSYS2 can automatically update packages for fixes, security updates etc. To update all installed packages to current, run the following command from an MSYS2 shell:

pacman -Sy

pacman -S bash pacman msys2-runtime --needed

Next, exit the shell and restart MSYS2.

Finally, once back at the shell, execute:

pacman -Su

Debugging

If you’re using the UCRT64 or CLANG64 environment on an x86 system, you can debug MAME using GDB. If you’re on an ARM system using the CLANGARM64 environment, you can debug MAME using LLDB (GDB is not available).

Note that MinGW GDB and LLDB work best in a Windows Command Prompt shell, and you will experience various issues if you attempt to run them from an MSYS2 shell directly. Start a Windows Command Prompt that inherits the environment from the MSYS2 shell using the start command:

start cmd

Then in the Windows Command Prompt, you can load MAME (or another program) into GDB:

gdb mame.exe

You can also use the --arg option to specify command line arguments for the program under test:

gdb --arg mame.exe -window -nomax -verbose galaga

Or if you’re using LLDB:

lldb mame.exe

LLDB assumes arguments following the name of the program should be passed on to it:

lldb mame.exe -window -nomax -verbose galaga

GDB provides a manual, but if you’re a beginner, you may be better served by searching for a tutorial. For more information about debugging with LLDB, see their web site.

Optional additional packages

See our compiling documentation for information on additional packages needed for optional features.