diff options
Diffstat (limited to 'docs/source/initialsetup/compilingmame.rst')
-rw-r--r-- | docs/source/initialsetup/compilingmame.rst | 404 |
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: |