summaryrefslogtreecommitdiffstatshomepage
path: root/docs/source/initialsetup/compilingmame.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/source/initialsetup/compilingmame.rst')
-rw-r--r--docs/source/initialsetup/compilingmame.rst404
1 files changed, 255 insertions, 149 deletions
diff --git a/docs/source/initialsetup/compilingmame.rst b/docs/source/initialsetup/compilingmame.rst
index f5be3a636f9..0df34f5d12b 100644
--- a/docs/source/initialsetup/compilingmame.rst
+++ b/docs/source/initialsetup/compilingmame.rst
@@ -9,48 +9,74 @@ 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.
-
-* 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
+ 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 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
+ drivers sources are added, removed, or renamed, the project files need
+ to be regenerated. You can do this by adding **REGENIE=1** to the
+ make arguments, or updating the modification time of the makefile (for
+ example using the **touch** command). Failure to do this may cause
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.
+* You can build an emulator for a subset of the systems supported by
+ MAME by using *SOURCES=<driver>,...* in your make command. For
+ example
+ **make SUBTARGET=pacem SOURCES=src/mame/pacman/pacman.cpp REGENIE=1**
+ would build an emulator called *pacem* including the system drivers
+ from the source file pacman.cpp (*REGENIE=1* is specified to ensure
+ project files are regenerated). You can specify folders to include
+ their entire contents, and you can separate multiple files/folders
+ with commas. You can also omit the *src/mame/* prefix in many cases.
+
+ If you encounter linking errors after changing the included sources,
+ delete the static libraries for the subtarget from the build folder.
+ For the previous example on Windows using GCC, these would be in
+ *build/mingw-gcc/bin/x64/Release/mame_pacem* by default.
+
+* On a system with multiple CPU cores, compilation can be sped up by
+ compiling multiple source files in parallel. This is done with the
+ **-j** parameter. For instance, **make -j5** is a good starting point
+ on a system with a quad-core CPU.
+
+ *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 will
+ increase compilation time, particularly if the compiler jobs exhaust
+ available memory. The optimal number depends on many factors,
+ including number of CPU cores, available RAM, disk and filesystem
+ performance, and memory bandwidth.*
* 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.
+ compile time and disk space used. Note that a full build of MAME
+ including internal debugging symbols will exceed the maximum size for
+ an executable on Windows, and will not be possible to run without
+ first stripping the symbols.
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::
make -j3
+Rebuilding MAME for just the Pac-Man and Galaxian families of systems,
+with tools, on a quad-core (e.g. i5 or i7) machine::
+
+ make SUBTARGET=pacem SOURCES=src/mame/pacman,src/mame/galaxian TOOLS=1 REGENIE=1 -j5
+
+Rebuilding MAME for just the Apple II systems, compiling up to six
+sources in parallel::
+
+ make SUBTARGET=appulator SOURCES=apple/apple2.cpp,apple/apple2e.cpp,apple/apple2gs.cpp REGENIE=1 -j6
+
.. _compiling-windows:
@@ -72,7 +98,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.3 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.
@@ -89,8 +115,9 @@ with MSYS2 and the **pacman** package manager.
* Download the latest version of the ``mame-essentials`` package from the
`MAME package repository <https://repo.mamedev.org/x86_64/>`_ and install it
using the **pacman** command.
-* Add the ``mame`` repository to ``/etc/pacman.conf`` using
- ``/etc/pacman.d/mirrorlist.mame`` for locations.
+* Add the ``mame`` package repository to ``/etc/pacman.conf`` using
+ ``/etc/pacman.d/mirrorlist.mame`` for locations, and disable signature
+ 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
@@ -115,6 +142,11 @@ with MSYS2 and the **pacman** package manager.
``mingw-w64-i686-python-sphinx``, ``mingw-w64-i686-python-sphinx_rtd_theme``
and ``mingw-w64-x86_64-python-sphinxcontrib-svg2pdfconverter`` a 32-bit MinGW
environment).
+* To build the PDF documentation, you’ll additionally need
+ ``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).
* 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``.
@@ -147,7 +179,7 @@ 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
+ echo -e '\n[mame]\nInclude = /etc/pacman.d/mirrorlist.mame\nSigLevel = Never' >> /etc/pacman.conf
Building with Microsoft Visual Studio
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -219,10 +251,15 @@ Fedora Linux
------------
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::
+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
@@ -241,9 +278,9 @@ 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.4 or later as earlier versions are buggy::
+SDL 2 version 2.0.14 or later as earlier versions lack required functionality::
- sudo apt-get install git build-essential python libsdl2-dev libsdl2-ttf-dev libfontconfig-dev libpulse-dev qt5-default
+ 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
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
@@ -257,7 +294,7 @@ Arch Linux
You’ll need a few prerequisites from your distro::
- sudo pacman -S base-devel git sdl2 gconf sdl2_ttf gcc qt5
+ sudo pacman -S base-devel git sdl2_ttf python libxinerama libpulse alsa-lib qt5-base
Compilation is exactly as described above in All Platforms.
@@ -267,10 +304,11 @@ 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.4 or later for Intel or SDL2 2.0.14 on Apple Silicon. You’ll also
-need to install Python 3.
+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.
* Install **Xcode** from the Mac App Store or
`ADC <https://developer.apple.com/download/more/>`_ (AppleID required).
@@ -283,7 +321,7 @@ need to install Python 3.
* 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
@@ -293,12 +331,13 @@ Next you’ll need to get SDL2 installed.
**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:
+If you don’t already have it, get Python 3 set up:
-* Go to the `official Python site <https://www.python.org/>`_ and click the link
- to the download page for the current version (this was
- `Python 3.10.0 <https://www.python.org/downloads/release/python-3100/>`_ at
- the time of writing).
+* Go to the official Python site, navigate to the
+ `releases for macOS <https://www.python.org/downloads/macos/>`_, and click the
+ link to download the installer for the latest stable release (this was
+ `Python 3.10.4 <https://www.python.org/ftp/python/3.10.4/python-3.10.4-macos11.pkg>`_
+ at the time of writing).
* 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
@@ -314,8 +353,8 @@ above in All Platforms.
Emscripten Javascript and HTML
------------------------------
-First, download and install Emscripten 1.37.29 or later by following the
-instructions at the `official site <https://kripken.github.io/emscripten-site/docs/getting_started/downloads.html>`_.
+First, download and install Emscripten 2.0.25 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
out-of-the-box using Emscripten’s **emmake** tool. Because a full MAME
@@ -325,7 +364,7 @@ MAME directory):
.. code-block:: bash
- emmake make SUBTARGET=pacmantest SOURCES=src/mame/drivers/pacman.cpp
+ emmake make SUBTARGET=pacmantest SOURCES=src/mame/pacman/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
@@ -335,7 +374,7 @@ commas) if this process misses something. e.g.
.. code-block:: bash
- emmake make SUBTARGET=apple2e SOURCES=src/mame/drivers/apple2e.cpp,src/mame/machine/applefdc.cpp
+ emmake make SUBTARGET=apple2e SOURCES=src/mame/apple/apple2e.cpp,src/devices/machine/applefdc.cpp
The value of the **SUBTARGET** parameter serves only to differentiate multiple
builds and need not be set to any specific value.
@@ -405,8 +444,12 @@ 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.
+If you intend to make a PDF via LaTeX, you’ll need to install a LaTeX
+distribution such as TeX Live:
+
+.. code-block:: bash
+
+ pacman -S mingw-w64-x86_64-texlive-fonts-recommended mingw-w64-x86_64-texlive-latex-extra
.. _compiling-docs-debian:
@@ -458,160 +501,198 @@ Overall build options
~~~~~~~~~~~~~~~~~~~~~
PREFIX_MAKEFILE
- 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.
+ 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.
BUILDDIR
- Set to change the name of the subfolder used for project files, generated
- sources, object files, and intermediate libraries (defaults to **build**).
+ Set to change the name of the subfolder used for project files, generated
+ sources, object files, and intermediate libraries (defaults to **build**).
REGENIE
- Set to **1** to force project files to be regenerated.
+ Set to **1** to force project files to be regenerated.
VERBOSE
- 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 show full commands when using GNU make as the build tool.
+ This option applies immediately without needing regenerate project files.
IGNORE_GIT
- Set to **1** to skip the working tree scan and not attempt to embed a git
- revision description in the version string.
+ Set to **1** to skip the working tree scan and not attempt to embed a git
+ revision description in the version string.
Tool locations
~~~~~~~~~~~~~~
OVERRIDE_CC
- 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.)
OVERRIDE_CXX
- 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.)
OVERRIDE_LD
- 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 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.)
PYTHON_EXECUTABLE
- Set the Python interpreter command. You need Python 3.2 or later to build
- MAME.
+ Set the Python interpreter command. You need Python 3.2 or later to build
+ MAME.
CROSS_BUILD
- 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 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.
+
+Including subsets of supported systems
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+SUBTARGET
+ Set emulator subtarget to build. Some pre-defined subtargets are provided,
+ using Lua scripts in *scripts/target/mame* and system driver filter files in
+ *src/mame*. User-defined substargets can be created using the **SOURCES**
+ or **SOURCEFILTER** option.
+SOURCES
+ Specify system driver source files and/or folders to include. Usually used
+ in conjunction with the **SUBTARGET** option. Separate multiple
+ files/folders with commas.
+SOURCEFILTER
+ Specify a system driver filter file. Usually used in conjunction with the
+ **SUBTARGET** option. The filter file can specify source files to include
+ system drivers from, and individual system drivers to include or exclude.
+ There are some example system driver filter files in the *src/mame* folder.
Optional features
~~~~~~~~~~~~~~~~~
TOOLS
- Set to **1** to build additional tools along with the emulator, including
- **unidasm**, **chdman**, **romcmp**, and **srcclean**.
+ 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
- Set to **1** to disable building the PortAudio sound output module.
+ Set to **1** to disable building the PortAudio sound output module and the
+ PortAudio library.
+NO_USE_PULSEAUDIO
+ Set to **1** to disable building the PulseAudio sound output module on
+ Linux.
+USE_WAYLAND
+ Set to **1** to include support for bgfx video output with the Wayland
+ display server.
+USE_TAPTUN
+ Set to **1** to include the tap/tun network module, or set to **0** to
+ disable building the tap/tun network module. The tap/tun network module is
+ included by default on Windows and Linux.
+USE_PCAP
+ Set to **1** to include the pcap network module, or set to **0** to disable
+ building the pcap network module. The pcap network module is included by
+ default on macOS and NetBSD.
USE_QTDEBUG
- 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 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.
Compilation options
~~~~~~~~~~~~~~~~~~~
NOWERROR
- Set to **1** to disable treating compiler warnings as errors. This may be
- needed in marginally supported configurations.
+ Set to **1** to disable treating compiler warnings as errors. This may be
+ needed in marginally supported configurations.
DEPRECATED
- Set to **0** to disable deprecation warnings (note that deprecation warnings
- are not treated as errors).
+ Set to **0** to disable deprecation warnings (note that deprecation warnings
+ are not treated as errors).
DEBUG
- 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 to **1** to enable runtime assertion checks and additional diagnostics.
+ Note that this has a performance cost, and is most useful for developers.
OPTIMIZE
- 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 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.
SYMBOLS
- Set to **1** to include additional debugging symbols over the default for the
- target platform (many target platforms include function name symbols by
- default).
+ Set to **1** to include additional debugging symbols over the default for
+ the target platform (many target platforms include function name symbols by
+ default).
SYMLEVEL
- 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.
+ 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.
ARCHOPTS
- 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 and linker. This is
+ useful for supplying code generation or ABI options, for example to enable
+ support for optional CPU features.
ARCHOPTS_C
- 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.
ARCHOPTS_CXX
- 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.
ARCHOPTS_OBJC
- 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.
ARCHOPTS_OBJCXX
- 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.
Library/framework locations
~~~~~~~~~~~~~~~~~~~~~~~~~~~
SDL_INSTALL_ROOT
- SDL installation root directory for shared library style SDL.
+ SDL installation root directory for shared library style SDL.
SDL_FRAMEWORK_PATH
- Search path for SDL framework.
+ Search path for SDL framework.
USE_LIBSDL
- Set to **1** to use shared library style SDL on targets where framework is
- default.
+ Set to **1** to use shared library style SDL on targets where framework is
+ default.
USE_SYSTEM_LIB_ASIO
- 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 Asio C++ asynchronous
+ I/O library over the version provided with the MAME source.
USE_SYSTEM_LIB_EXPAT
- 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 Expat XML parser
+ library over the version provided with the MAME source.
USE_SYSTEM_LIB_ZLIB
- 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 zlib data compression
+ library over the version provided with the MAME source.
+USE_SYSTEM_LIB_ZSTD
+ Set to **1** to prefer the system installation of the Zstandard data
+ compression library over the version provided with the MAME source.
USE_SYSTEM_LIB_JPEG
- 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 libjpeg image
+ compression library over the version provided with the MAME source.
USE_SYSTEM_LIB_FLAC
- 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 libFLAC audio
+ compression library over the version provided with the MAME source.
USE_SYSTEM_LIB_LUA
- 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 embedded Lua
+ interpreter over the version provided with the MAME source.
USE_SYSTEM_LIB_SQLITE3
- 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 SQLITE embedded
+ database engine over the version provided with the MAME source.
USE_SYSTEM_LIB_PORTMIDI
- 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 PortMidi library over
+ the version provided with the MAME source.
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.)
+ Set to **1** to prefer the system installation of the PortAudio library over
+ the version provided with the MAME source.
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.
+ Set to **1** to prefer the system installation of the Julia utf8proc library
+ over the version provided with the MAME source.
USE_SYSTEM_LIB_GLM
- 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 GLM OpenGL Mathematics
+ library over the version provided with the MAME source.
USE_SYSTEM_LIB_RAPIDJSON
- 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 Tencent RapidJSON
+ library over the version provided with the MAME source.
USE_SYSTEM_LIB_PUGIXML
- Set to **1** to prefer the system installation of the pugixml 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.
.. _compiling-issues:
@@ -661,6 +742,31 @@ 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
variables.
+Issues affecting Microsoft Visual Studio
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Microsoft introduced a new version of XAudio2 with Windows 8 that’s incompatible
+with the version included with DirectX for prior Windows versions at the API
+level. Newer versions of the Microsoft Windows SDK include headers and libraries
+for the new version of XAudio2. By default, the target Windows version is set to
+Windows Vista (6.0) when compiling MAME, which prevents the use of this version
+of the XAudio2 headers and libraries. To build MAME with XAudio2 support using
+the Microsoft Windows SDK, you must do one of the following:
+
+* Add ``MODERN_WIN_API=1`` to the options passed to make when generating the
+ 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.
+
+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.)
+
.. _compiling-unusual: