diff options
Diffstat (limited to 'docs/source/initialsetup')
-rw-r--r-- | docs/source/initialsetup/compilingmame.rst | 162 |
1 files changed, 99 insertions, 63 deletions
diff --git a/docs/source/initialsetup/compilingmame.rst b/docs/source/initialsetup/compilingmame.rst index 51c8d408fd8..a4559842b39 100644 --- a/docs/source/initialsetup/compilingmame.rst +++ b/docs/source/initialsetup/compilingmame.rst @@ -9,11 +9,11 @@ All Platforms ------------- * 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 or - libc++ version 7 or later. The initial release of any major version + support building with GCC version 10.3 or later and clang version 11 + or later. MAME should run with GNU libstdc++ version 10.3 or later or + libc++ version 11 or later. The initial release of any major version of GCC should be avoided. For example, if you want to compile MAME - with GCC 10, you should use version 10.3 or later. + with GCC 12, you should use version 12.1 or later. * Whenever you are changing build parameters, (for example changing optimisation settings, or adding tools to the compile list), or system @@ -86,10 +86,11 @@ Microsoft Windows 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. +32-bit systems. Building for 64-bit ARM (AArch64) requires a 64-bit ARM system +running Windows 11 or later. * A pre-packaged MSYS2 installation including the prerequisites for building - MAME can be downloaded from the `MAME Build Tools + MAME for 64-bit x86-64 can be downloaded from the `MAME Build Tools <http://mamedev.org/tools/>`_ page. * After initial installation, you can update the MSYS2 environment using the **pacman** (Arch package manage) command. @@ -98,7 +99,7 @@ building MAME on a 64-bit system. Instructions may need to be adjusted for 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 ``sdl`` prefix prepended (e.g. ``sdlmame.exe``). You - will need to install the MSYS2 packages for SDL 2 version 2.0.6 or later. + will need to install the MSYS2 packages for SDL 2 version 2.0.14 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. @@ -120,20 +121,7 @@ with MSYS2 and the **pacman** package manager. verification for this repository (``SigLevel = Never``). * Install packages necessary to build MAME. At the very least, you’ll need ``bash``, ``git``, ``make``. -* For 64-bit builds you’ll need ``mingw-w64-x86_64-gcc`` and - ``mingw-w64-x86_64-python``. -* For 32-bit builds you’ll need ``mingw-w64-i686-gcc`` and - ``mingw-w64-i686-python``. * For debugging you may want to install ``gdb``. -* To link using the LLVM linker (generally much faster than the GNU linker), - you’ll need ``mingw-w64-x86_64-lld`` and ``mingw-w64-x86_64-libc++`` for - 64-bit builds, or ``mingw-w64-i686-lld`` and ``mingw-w64-i686-libc++`` for - 32-bit builds. -* To build against the portable SDL interfaces, you’ll need - ``mingw-w64-x86_64-SDL2`` and ``mingw-w64-x86_64-SDL2_ttf`` for 64-bit builds, - or ``mingw-w64-i686-SDL2`` and ``mingw-w64-i686-SDL2_ttf`` for 32-bit builds. -* To build the Qt debugger, you’ll need ``mingw-w64-x86_64-qt5`` for 64-bit - builds, or ``mingw-w64-i686-qt5`` for 32-bit builds. * To build the HTML user/developer documentation, you’ll need ``mingw-w64-x86_64-librsvg``, ``mingw-w64-x86_64-python-sphinx``, ``mingw-w64-x86_64-python-sphinx_rtd_theme`` and @@ -146,18 +134,53 @@ with MSYS2 and the **pacman** package manager. ``mingw-w64-x86_64-texlive-latex-extra`` and ``mingw-w64-x86_64-texlive-fonts-recommended`` (or ``mingw-w64-i686-texlive-latex-extra`` and - ``mingw-w64-i686-texlive-fonts-recommended`` for a 32-but MinGW environment). + ``mingw-w64-i686-texlive-fonts-recommended`` for a 32-bit MinGW environment). * To generate API documentation from source, you’ll need ``doxygen``. * If you plan to rebuild bgfx shaders and you want to rebuild the GLSL parser, you’ll need ``bison``. -* For 64-bit builds, open **MSYS2 MinGW 64-bit** from the start menu, and set - up the environment variables ``MINGW64`` to ``/mingw64`` and ``MINGW32`` to 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 ``MINGW32`` to ``/mingw32`` and ``MINGW64`` to an - empty string (e.g. using the command **export MINGW32=/mingw32 MINGW64=** in - the Bash shell). + +The additional packages you’ll need depend on the CPU architecture you’re +building for. + +**64-bit x86-64** + +* You’ll need ``mingw-w64-x86_64-gcc`` and ``mingw-w64-x86_64-python``. +* To link using the LLVM linker (generally much faster than the GNU linker), + you’ll need ``mingw-w64-x86_64-lld``, ``mingw-w64-x86_64-llvm`` and + ``mingw-w64-x86_64-libc++``. +* To build against the portable SDL interfaces, you’ll need + ``mingw-w64-x86_64-SDL2`` and ``mingw-w64-x86_64-SDL2_ttf``. +* To build the Qt debugger, you’ll need ``mingw-w64-x86_64-qt5``. +* Open the **mingw64.exe** helper from the **msys64** installation folder or the + **MSYS2 MinGW 64-bit** shortcut from the start menu to start a Bash shell + configured with the correct paths and environment variables. + +**32-bit x86** + +* You’ll need ``mingw-w64-i686-gcc`` and ``mingw-w64-i686-python``. +* To link using the LLVM linker (generally much faster than the GNU linker), + you’ll need ``mingw-w64-i686-lld``, ``mingw-w64-i686-llvm`` and + ``mingw-w64-i686-libc++``. +* To build against the portable SDL interfaces, you’ll need + ``mingw-w64-i686-SDL2`` and ``mingw-w64-i686-SDL2_ttf``. +* To build the Qt debugger, you’ll need ``mingw-w64-i686-qt5``. +* Open the **mingw32.exe** helper from the **msys64** installation folder or the + **MSYS2 MinGW 32-bit** shortcut from the start menu to start a Bash shell + configured with the correct paths and environment variables. + +**64-bit ARM (AArch64)** + +* You’ll need ``mingw-w64-clang-aarch64-clang``, + ``mingw-w64-clang-aarch64-python`` and ``mingw-w64-clang-aarch64-gcc-compat``. +* To link using the LLVM linker (generally much faster than the GNU linker), + you’ll need ``mingw-w64-clang-aarch64-lld``, ``mingw-w64-clang-aarch64-llvm`` + and ``mingw-w64-clang-aarch64-libc++``. +* To build against the portable SDL interfaces, you’ll need + ``mingw-w64-clang-aarch64-SDL2`` and ``mingw-w64-clang-aarch64-SDL2_ttf``. +* To build the Qt debugger, you’ll need ``mingw-w64-clang-aarch64-qt5``. +* Open the **clangarm64.exe** helper from the **msys64** installation folder to + start a Bash shell configured with the correct paths and environment + variables. 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 @@ -166,12 +189,18 @@ 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-gcc mingw-w64-x86_64-python + pacman -S mingw-w64-x86_64-llvm mingw-w64-x86_64-libc++ mingw-w64-x86_64-lld 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-gcc mingw-w64-i686-python + pacman -S mingw-w64-i686-llvm mingw-w64-i686-libc++ mingw-w64-i686-lld pacman -S mingw-w64-i686-SDL2 mingw-w64-i686-SDL2_ttf pacman -S mingw-w64-i686-qt5 + pacman -S mingw-w64-clang-aarch64-clang mingw-w64-clang-aarch64-python mingw-w64-clang-aarch64-gcc-compat + pacman -S mingw-w64-clang-aarch64-lld mingw-w64-clang-aarch64-llvm mingw-w64-clang-aarch64-libc++ + pacman -S mingw-w64-clang-aarch64-SDL2 mingw-w64-clang-aarch64-SDL2_ttf + pacman -S mingw-w64-clang-aarch64-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 @@ -184,9 +213,9 @@ configuration:: Building with Microsoft Visual Studio ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -* You can generate Visual Studio 2019 projects using **make vs2019**. The +* You can generate Visual Studio 2022 projects using **make vs2022**. The solution and project files will be created in - ``build/projects/windows/mame/vs2019`` by default (the name of the ``build`` + ``build/projects/windows/mame/vs2022`` by default (the name of the ``build`` folder can be changed using the ``BUILDDIR`` option). This will always regenerate the settings, so **REGENIE=1** is *not* needed. * Adding **MSBUILD=1** to the make options will build the solution using @@ -210,10 +239,10 @@ 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 ``/ming64/bin`` and/or -``/mingw32/bin`` (relative to the MSYS2 installation directory). MSYS2 tools -work best in an MSYS2 terminal, while MinGW tools work best in a Microsoft -command prompt. +``/usr/bin`` while the MinGW tools are installed in ``/ming64/bin``, +``/mingw32/bin`` and/or ``/clangarm64/bin`` (relative to the MSYS2 installation +directory). MSYS2 tools work best in an MSYS2 terminal, while MinGW tools work +best in a Microsoft command prompt. 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 @@ -222,9 +251,9 @@ 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. +earlier in the ``PATH`` environment variable 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 @@ -233,16 +262,19 @@ 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 -fail silently. +fail silently. This may cause your build to appear to succeed while producing +incorrect results. 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. +to the size of MAME. It’s 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. + +A complete build of MAME including line number symbols exceeds the size limit +imposed by the PE file format and cannot be run. Workarounds include including +only a subset of the systems supported by MAME or extracting symbols to a +separate file and stripping excess symbols from the MAME executable. .. _compiling-fedora: @@ -251,10 +283,15 @@ Fedora Linux ------------ You’ll need a few prerequisites from your Linux distribution. Make sure you get -SDL2 2.0.6 or later as earlier versions lack required functionality:: +SDL 2 version 2.0.14 or later as earlier versions lack required functionality:: 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 +If you want to use the more efficient LLVM tools for archiving static libraries +and linking, you’ll need to install the corresponding packages:: + + sudo dnf install lld llvm + Compilation is exactly as described above in All Platforms. To build the HTML user/developer documentation, you’ll need Sphinx, as well as @@ -273,7 +310,7 @@ Debian and Ubuntu (including Raspberry Pi and ODROID devices) ------------------------------------------------------------- You’ll need a few prerequisites from your Linux distribution. Make sure you get -SDL2 2.0.6 or later as earlier versions lack required functionality:: +SDL 2 version 2.0.14 or later as earlier versions lack required functionality:: sudo apt-get install git build-essential python3 libsdl2-dev libsdl2-ttf-dev libfontconfig-dev libpulse-dev qtbase5-dev qtbase5-dev-tools qtchooser qt5-qmake @@ -299,9 +336,8 @@ Compilation is exactly as described above in All Platforms. Apple macOS ----------- -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.6 or later for Intel or SDL2 2.0.14 on Apple Silicon. You’ll also +You’ll need a few prerequisites to get started. Make sure you’re on macOS 11.0 +Big Sur or later. You will need SDL 2 version 2.0.14 or later. You’ll also need to install Python 3 – it’s currently included with the Xcode command line tools, but you can also install a stand-alone version or get it via the Homebrew package manager. @@ -317,7 +353,7 @@ package manager. * 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. +Next you’ll need to get SDL 2 installed. * Go to `this site <http://libsdl.org/download-2.0.php>`_ and download the *macOS* .dmg file @@ -349,7 +385,7 @@ above in All Platforms. Emscripten Javascript and HTML ------------------------------ -First, download and install Emscripten 2.0.25 or later by following the +First, download and install Emscripten 3.1.35 or later by following the instructions at the `official site <https://emscripten.org/docs/getting_started/downloads.html>`_. Once Emscripten has been installed, it should be possible to compile MAME @@ -559,6 +595,10 @@ Optional features TOOLS Set to **1** to build additional tools along with the emulator, including **unidasm**, **chdman**, **romcmp**, and **srcclean**. +EMULATOR + When set to **0**, the main emulator target will not be created. This is + intended to be used in conjunction with setting **TOOLS** to **1** to build + the additional tools without building the emulator. NO_OPENGL Set to **1** to disable building the OpenGL video output module. NO_USE_PORTAUDIO @@ -673,11 +713,6 @@ USE_SYSTEM_LIB_PORTMIDI USE_SYSTEM_LIB_PORTAUDIO Set to **1** to prefer the system installation of the PortAudio library over the version provided with the MAME source. -USE_BUNDLED_LIB_SDL2 - 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.) USE_SYSTEM_LIB_UTF8PROC Set to **1** to prefer the system installation of the Julia utf8proc library over the version provided with the MAME source. @@ -754,15 +789,16 @@ the Microsoft Windows SDK, you must do one of the following: Visual Studio project files. This will set the target Windows version to Windows 8 (6.2). The resulting binaries may not run on earlier versions of Windows. -* Install the DirectX SDL and configure the **osd_windows** project to search - the DirectX header/library paths before searching the Microsoft Windows SDK - paths. +* Install the `DirectX SDK <https://www.microsoft.com/en-US/download/details.aspx?id=6812>`_ (already included since Windows 8.0 SDK and + automatically installed with Visual Studio 2013 and later). Configure the + **osd_windows** project to search the DirectX header/library paths before + searching the Microsoft Windows SDK paths. The MSVC compiler produces spurious warnings about potentially uninitialised local variables. You currently need to add ``NOWERROR=1`` to the options passed to make when generating the Visual Studio project files. This stops warnings from being treated as errors. (MSVC seems to lack options to control which -specific warnings are treated as error, which other compilers support.) +specific warnings are treated as errors, which other compilers support.) .. _compiling-unusual: |