additional documentation on compiling MAME (nw)

docs/source/initialsetup/compilingmame.rst

@@ -1,7 +1,9 @@
 Compiling MAME
 ==============
 
-.. _compiling-MAME:
+.. contents:: :local:
+
+.. _compiling-all:
 
 All Platforms
 -------------
@@ -29,6 +31,8 @@ Rebuilding MAME on a dual-core (e.g. i3 or laptop i5) machine:
 |
 
 
+.. _compiling-windows:
+
 Microsoft Windows
 -----------------
 
@@ -43,6 +47,8 @@ Here are specific notes about compiling MAME for Microsoft Windows.
 * Make sure you get SDL 2 2.0.3 or 2.0.4 as earlier versions are buggy.
 
 
+.. _compiling-fedora:
+
 Fedora Linux
 ------------
 
@@ -53,6 +59,8 @@ You'll need a few prerequisites from your distro. Make sure you get SDL2 2.0.3 o
 Compilation is exactly as described above in All Platforms.
 
 
+.. _compiling-ubuntu:
+
 Debian and Ubuntu (including Raspberry Pi and ODROID devices)
 -------------------------------------------------------------
 
@@ -63,6 +71,8 @@ You'll need a few prerequisites from your distro. Make sure you get SDL2 2.0.3 o
 Compilation is exactly as described above in All Platforms.
 
 
+.. _compiling-arch:
+
 Arch Linux
 ----------
 
@@ -73,6 +83,8 @@ You'll need a few prerequisites from your distro.
 Compilation is exactly as described above in All Platforms.
 
 
+.. _compiling-macos:
+
 Apple Mac OS X
 --------------
 
@@ -104,6 +116,8 @@ It's possible to get MAME working from 10.6, but a bit more complicated:
 |
 
 
+.. _compiling-emscripten:
+
 Emscripten Javascript and HTML
 ------------------------------
 
@@ -139,3 +153,256 @@ There are example .html files in that repository which can be edited to point to
 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-options:
+
+Useful Options
+--------------
+
+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.
+
+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.
+BUILDDIR
+   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.
+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.
+IGNORE_GIT
+   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.
+OVERRIDE_CXX
+   Set the C++/Objective-C++ compiler command.
+PYTHON_EXECUTABLE
+   Set the Python interpreter command.  You need Python 2.7 or Python 3 to build
+   MAME.
+
+Optional features
+~~~~~~~~~~~~~~~~~
+
+TOOLS
+   Set to **1** to build additional tools along with the emulator, including
+   **unidasm**, **chdman**, **romcmp**, and **srcclean**.
+NO_USE_PORTAUDIO
+   Set to **1** to disable building the PortAudio sound output module.
+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.
+
+Compilation options
+~~~~~~~~~~~~~~~~~~~
+
+NOWERROR
+   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).
+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.
+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.
+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).
+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.
+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.
+ARCHOPTS_C
+   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.
+ARCHOPTS_OBJC
+   Additional command-line options to pass to the compiler when compiling
+   Objecive-C source files.
+ARCHOPTS_OBJCXX
+   Additional command-line options to pass to the compiler when compiling
+   Objecive-C++ source files.
+
+Library/framework locations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+SDL_INSTALL_ROOT
+   SDL installation root directory for shared library style SDL.
+SDL_FRAMEWORK_PATH
+   Search path for SDL framework.
+USE_LIBSDL
+   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.
+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.
+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.
+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.
+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.
+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.
+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.
+USE_SYSTEM_LIB_PORTMIDI
+   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.)
+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.
+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.
+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.
+USE_SYSTEM_LIB_PUGIXML
+   Set to **1** to prefer the system installation of the pugixml library over
+   the version provided with the MAME source.
+
+
+.. _compiling-issues:
+
+Known Issues
+------------
+
+Issues with specific compiler versions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* GCC 5 for Linux reports spurious errors on encountering deprecation warnings.
+  Adding **DEPRECATED=0** to your build options works around this by disabling
+  deprecation warnings.
+* MinGW GCC 7 for Windows i386 produces spurious out-of-bounds access warnings.
+  Adding **NOWERROR=1** to your build options works around this by disabling
+  deprecation warnings.
+* Initial versions of GNU libstdc++ 6 have a broken ``std::unique_ptr``
+  implementation.  If you encounter errors with ``std::unique_ptr`` you need to
+  upgrade to a newer version of libstdc++ that fixes the issue.
+
+GNU C Library fortify source feature
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The GNU C Library has options to perform additional compile- and run-time
+checks on string operations, enabled by defining the ``_FORTIFY_SOURCE``
+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 ``_FORTIFY_SOURCE`` defined.
+
+Some Linux distributions (including Gentoo and Ubuntu) have patched GCC to
+define ``_FORTIFY_SOURCE`` 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 ``_FORTIFY_SOURCE`` to ``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:
+the ``_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
+whether the ``_FORTIFY_SOURCE`` macro is a built-in macro with your version of
+GCC with a command like this:
+
+**gcc -dM -E - | grep _FORTIFY_SOURCE**
+
+If ``_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
+variables.
+
+
+.. _compiling-unusual:
+
+Unusual Build Configurations
+----------------------------
+
+Using libc++ on Linux
+~~~~~~~~~~~~~~~~~~~~~
+
+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.
+
+Using a GCC/GNU libstdc++ installation in a non-standard location on Linux
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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++14 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/gcc63, you might use a command like this:
+
+**make OVERRIDE_CC=/opt/local/gcc63/bin/gcc OVERRIDE_CXX=/opt/local/gcc63/bin/g++ ARCHOPTS=-Wl,-R,/opt/local/gcc63/lib64**
+
+You can add these options to a prefix makefile if you plan to use this
+configuration regularly.

scripts/src/osd/sdl_cfg.lua

@@ -89,7 +89,7 @@ if BASE_TARGETOS=="unix" then
 					backtick(sdlconfigcmd() .. " --cflags | sed 's:/SDL2::'"),
 				}
 			end
-			end
+		end
 	else
 		buildoptions {
 			backtick(sdlconfigcmd() .. " --cflags"),