summaryrefslogtreecommitdiffstatshomepage
path: root/docs/source/initialsetup
diff options
context:
space:
mode:
Diffstat (limited to 'docs/source/initialsetup')
-rw-r--r--docs/source/initialsetup/compilingmame.rst105
-rw-r--r--docs/source/initialsetup/configuringmame.rst77
-rw-r--r--docs/source/initialsetup/index.rst4
-rw-r--r--docs/source/initialsetup/installingmame.rst12
-rw-r--r--docs/source/initialsetup/mameintro.rst118
5 files changed, 248 insertions, 68 deletions
diff --git a/docs/source/initialsetup/compilingmame.rst b/docs/source/initialsetup/compilingmame.rst
index a00fc77460b..51d63588149 100644
--- a/docs/source/initialsetup/compilingmame.rst
+++ b/docs/source/initialsetup/compilingmame.rst
@@ -19,11 +19,11 @@ All Platforms
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 statement, like
+ *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 statement. For instance, building Pac-Man by itself would be
+ 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.
@@ -33,7 +33,7 @@ All Platforms
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
- bandwidh.* For instance, **make -j5** is a good starting point on a
+ bandwidth.* For instance, **make -j5** is a good starting point on a
system with a quad-core CPU.
* Debugging information can be added to a compile using *SYMBOLS=1*
@@ -160,7 +160,11 @@ Building with Microsoft Visual Studio
* Adding **MSBUILD=1** to the make options will build the solution using
the Microsoft Build Engine after generating the project files. Note that this
requires paths and environment variables to be configured so the correct
- Visual Studio tools can be located.
+ Visual Studio tools can be located; please refer to the Microsoft-provided
+ instructions on `using the Microsoft C++ toolset from the command line
+ <https://docs.microsoft.com/en-us/cpp/build/building-on-the-command-line>`_.
+ You may find it easier to not use **MSBUILD=1** and load the project file into
+ Visual Studio’s GUI for compilation.
* The MSYS2 environment is still required to generate the project files, convert
built-in layouts, compile UI translations, etc.
@@ -264,7 +268,8 @@ 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.
+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.
* Install **Xcode** from the Mac App Store or `ADC <https://developer.apple.com/download/more/>`_ (AppleID required).
* To find the corresponding Xcode for your MacOS release please visit `xcodereleases.com <https://xcodereleases.com>`_ to find the latest version of Xcode available to you.
@@ -275,9 +280,13 @@ Mojave or later for Intel Macs or macOS 11.0 Big Sur for Apple Silicon. You will
Next you’ll need to get SDL2 installed.
-* Go to `this site <http://libsdl.org/download-2.0.php>`_ and download the *Mac OS X* .dmg file
-* If the .dmg doesn’t auto-open, open it
-* Click “Macintosh HD” (your Mac’s hard disk) in the Locations sidebar of a **Finder** window, then open the **Library** folder and drag the **SDL2.framework** folder from the SDL disk image into the **Frameworks** folder. You will have to authenticate with your user password.
+* Go to `this site <http://libsdl.org/download-2.0.php>`_ and download the
+ *macOS* .dmg file
+* If the .dmg doesn’t open automatically, open it
+* Click “Macintosh HD” (or whatever your Mac’s hard disk is named) in the left
+ pane of a **Finder** window, then open the **Library** folder and drag the
+ **SDL2.framework** folder from the SDL disk image into the **Frameworks**
+ folder. You will have to authenticate with your user password.
Lastly to begin compiling, use Terminal to navigate to where you have the MAME
source tree (*cd* command) and follow the normal compilation instructions from
@@ -290,13 +299,13 @@ 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>`_
+instructions at the `official site <https://kripken.github.io/emscripten-site/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 compile
-is too large to load into a web browser at once, you will want to use the
-**SOURCES** parameter to compile only a subset of the project, e.g. (in the mame
-directory):
+out-of-the-box using Emscripten’s **emmake** tool. Because a full MAME
+compile is too large to load into a web browser at once, you will want to use
+the SOURCES parameter to compile only a subset of the project, e.g. (in the
+MAME directory):
.. code-block:: bash
@@ -316,12 +325,12 @@ The value of the **SUBTARGET** parameter serves only to differentiate multiple
builds and need not be set to any specific value.
Emscripten supports compiling to WebAssembly with a JavaScript loader instead of
-all-JavaScript, and in later versions this is actually the default. To force
+all-JavaScript, and in later versions this is actually the default. To force
WebAssembly on or off, add **WEBASSEMBLY=1** or **WEBASSEMBLY=0** to the make
-command line.
+command line, respectively.
-Other make parameters can also be used, e.g. **-j** for parallel compilation, as
-described earlier.
+Other make parameters can also be used, e.g. **-j** for multithreaded
+compilation as described earlier.
When the compilation reaches the emcc phase, you may see a number of
*"unresolved symbol"* warnings. At the moment, this is expected for
@@ -335,7 +344,8 @@ not used at run-time.
If all goes well, a **.js** file will be output to the current directory. This
file cannot be run by itself, but requires an HTML loader to provide it with a
canvas to draw to and to pass in command-line parameters. The
-`Emularity project <https://github.com/db48x/emularity>`_ provides such a loader.
+`Emularity project <https://github.com/db48x/emularity>`_ provides such a
+loader.
There are example **.html** files in that repository which can be edited to
point to your newly compiled MAME **.js** file and pass in whatever parameters
@@ -367,36 +377,61 @@ Compiling the Documentation
Compiling the documentation will require you to install several packages
depending on your operating system.
-On Debian/Ubuntu flavors of Linux, you’ll need python3-sphinx/python-sphinx
-and the python3-pip/python-pip packages, depending on whether you’re using
-Python 3 or Python 2::
+.. _compiling-docs-windows:
- sudo apt-get install python3-sphinx python3-pip
+Compiling the Documentation on Microsoft Windows
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-or::
+On Windows, you’ll need a couple of packages from the MSYS2 environment. You
+can install these packages with
- sudo apt-get install python-sphinx python-pip
+.. code-block:: bash
+
+ 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.
-You’ll then need to install the SVG handler::
+.. _compiling-docs-debian:
+Compiling the Documentation on Debian and Ubuntu
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+On Debian/Ubuntu flavors of Linux, you’ll need **python3-sphinx/python-sphinx**
+and the **python3-pip/python-pip** packages:
+
+.. code-block:: bash
+
+ sudo apt-get install python3-sphinx python3-pip
pip3 install sphinxcontrib-svg2pdfconverter
-or::
+or
+.. code-block:: bash
+
+ sudo apt-get install python-sphinx python-pip
pip install sphinxcontrib-svg2pdfconverter
depending on whether you’re using Python 3 or Python 2.
-If you intend on making a PDF via LaTeX, you’ll need to install a LaTeX
-distribution such as TeX Live::
+On Debian, you’ll need to install the **librsvg2-bin** package:
+
+.. code-block:: bash
+
+ sudo apt-get install librsvg2-bin
+
+If you intend to make a PDF via LaTeX, you’ll need to install a LaTeX
+distribution such as TeX Live:
+
+.. code-block:: bash
- sudo apt-get install latexmk texlive texlive-science texlive-formats-extra
+ sudo apt-get install librsvg2-bin latexmk texlive texlive-science texlive-formats-extra
-From this point, you can do **make html** or **make latexpdf** from the docs
-folder to generate the output of your choice. Typing **make** by itself will
-tell you all available formats. The output will be in the docs/build folder in
-a subfolder based on the type chosen (e.g. **make html** will create
-*docs/build/html* containing the output).
+From this point you can do ``make html`` or ``make latexpdf`` from the **docs**
+folder to generate the output of your choice. Typing ``make`` by itself will
+tell you all available formats. The output will be in the docs/build folder in
+a subfolder based on the type chosen (e.g. ``make html`` will create
+*docs/build/html* with the output.)
.. _compiling-options:
@@ -464,7 +499,7 @@ 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
+ 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.
diff --git a/docs/source/initialsetup/configuringmame.rst b/docs/source/initialsetup/configuringmame.rst
new file mode 100644
index 00000000000..3a0c8830cdf
--- /dev/null
+++ b/docs/source/initialsetup/configuringmame.rst
@@ -0,0 +1,77 @@
+Configuring MAME
+================
+
+.. contents:: :local:
+
+Getting Started: A Quick Preface
+--------------------------------
+
+Once you have MAME installed, the next step is to configure it. There are
+several ways to do this, and each will be covered in turn.
+
+If you are on Windows, the MAME executable will be called ``mame.exe``.
+
+If you are on Linux or MacOS, the MAME executable will be called ``mame``.
+
+
+Initial Setup: Creating mame.ini From Command Line on Windows
+-------------------------------------------------------------
+
+First, you will need to *cd* to the directory where you installed MAME into.
+If, for instance, you have MAME installed in ``C:\Users\Public\MAME`` you will
+need to type ``cd C:\Users\Public\MAME`` into the command prompt.
+
+Then you have MAME create the config file by typing ``mame64 -createconfig``
+or ``mame -createconfig`` depending on if you are using the 64-bit version of
+MAME or the 32-bit version.
+
+MAME will then create the ``mame.ini`` file in the MAME installation folder.
+This file contains the default configuration settings for a new MAME
+installation.
+
+
+Initial Setup: Creating mame.ini From Command Line on Linux or MacOS
+--------------------------------------------------------------------
+
+The steps for Linux and MacOS are similar to those of Windows. If you
+installed MAME using the package manager that came from a Linux distro, you will
+type ``mame64 -createconfig`` or ``mame -createconfig`` into your terminal
+of choice, depending on if you have a 64-bit version of MAME or a 32-bit
+one.
+
+If you have compiled from source or downloaded a binary package of MAME,
+you will ``cd`` into the directory you put the MAME files into.
+
+For instance, ``cd /home/myusername/mame``
+
+Then you will type ``./mame64 -createconfig`` or ``./mame -createconfig`` into
+your terminal of choice, depending on if you have a 64-bit version of MAME or a
+32-bit one.
+
+You can then need to edit the ``mame.ini`` file in your favorite text editor,
+e.g. *Notepad* on Windows or *vi* on Linux/MacOS, or you can change settings
+from inside of MAME.
+
+
+Initial Setup: Graphical Setup
+------------------------------
+
+This is the easiest way to get started. Start MAME by opening the MAME icon
+in the location where you installed it. This will be ``mame64.exe`` or
+``mame.exe`` on Windows, ``mame64`` or ``mame`` on Linux and macOS.
+
+Once MAME has started, you can either use your mouse to click on the
+**Configure Options** menu selection at the bottom center of your screen,
+or you can switch panes to the bottom one (default key is Tab), then press
+the menu accept button (default key is Return/Enter) to go into the
+Configuration menu.
+
+Choose **Save Configuration** to create the ``mame.ini`` file with default
+settings. From here, you can either continue to configure things from the
+graphical user interface or edit the ``mame.ini`` file in your favorite
+text editor.
+
+
+Configuring MAME
+----------------
+
diff --git a/docs/source/initialsetup/index.rst b/docs/source/initialsetup/index.rst
index bd3b3a0d80d..32319dd7367 100644
--- a/docs/source/initialsetup/index.rst
+++ b/docs/source/initialsetup/index.rst
@@ -1,7 +1,8 @@
Getting MAME prepared
---------------------
-This section covers initial preparation work needed to use MAME, including downloading and compiling MAME.
+This section covers initial preparation work needed to use MAME, including
+downloading MAME, compiling MAME from source, and configuring MAME.
.. toctree::
:titlesonly:
@@ -9,3 +10,4 @@ This section covers initial preparation work needed to use MAME, including downl
mameintro
installingmame
compilingmame
+ configuringmame
diff --git a/docs/source/initialsetup/installingmame.rst b/docs/source/initialsetup/installingmame.rst
index 3ace07ade80..c276b3d7a5c 100644
--- a/docs/source/initialsetup/installingmame.rst
+++ b/docs/source/initialsetup/installingmame.rst
@@ -4,10 +4,18 @@ Installing MAME
Microsoft Windows
-----------------
-You simply have to download the latest binary archive available from http://www.mamedev.org and to extract its content to a folder. You will end up with many files (below you will find explanations about some of these), and in particular ``MAME.EXE``. This is a command line program. The installation procedure ends here. Easy, isn't it?
+You simply have to download the latest binary archive available from
+http://www.mamedev.org and to extract its content to a folder. You will end up
+with many files (below you will find explanations about some of these), and in
+particular **mame.exe**. This is a command line program. The installation
+procedure ends here. Easy, isn’t it?
Other Operating Systems
-----------------------
-In this case, you can either look for pre-compiled (SDL)MAME binaries (e.g. in the repositories of your favorite Linux distro) which should simply extract all the needed files in a folder you choose, or compile the source code by yourself. In the latter case, see our section on :ref:`compiling-all`.
+In this case, you can either look for pre-compiled (SDL)MAME binaries (e.g. in
+the repositories of your favorite Linux distro) which should simply extract all
+the needed files in a folder you choose, or compile the source code by
+yourself. In the latter case, see our section on
+:ref:`compiling MAME <compiling-all>`.
diff --git a/docs/source/initialsetup/mameintro.rst b/docs/source/initialsetup/mameintro.rst
index b63a6b3beda..61be99b68a9 100644
--- a/docs/source/initialsetup/mameintro.rst
+++ b/docs/source/initialsetup/mameintro.rst
@@ -1,64 +1,122 @@
An Introduction to MAME
-=======================
+-----------------------
-MAME, formerly was an acronym which stood for Multi Arcade Machine Emulator, documents and reproduces through emulation the inner components of arcade machines, computers, consoles, chess computers, calculators, and many other types of electronic amusement machines. As a nice side-effect, MAME allows to use on a modern PC those programs and games which were originally developed for the emulated machines.
+MAME, formerly an acronym which stood for Multi Arcade Machine Emulator,
+documents and reproduces through emulation the inner components of arcade
+machines, computers, consoles, chess computers, calculators, and many other
+types of electronic amusement machines. As a nice side-effect, MAME allows to
+use on a modern PC those programs and games which were originally developed for
+the emulated machines.
-At one point there were actually two separate projects, MAME and MESS. MAME covered arcade machines, while MESS covered everything else. They are now merged into the one MAME.
+At one point there were actually two separate projects, MAME and MESS. MAME
+covered arcade video games, while MESS covered home and business systems. They
+are now merged into the one MAME.
-MAME is mostly programmed in C with some core components in C++. MAME can currently emulate over 32000 individual systems from the last 5 decades.
+MAME is written in C++ and can currently emulate over 32,000 individual systems
+from the last five decades.
Purpose of MAME
-===============
+---------------
-The primary purpose of MAME is to preserve decades of arcade, computer, and console history. As technology continues to rush forward, MAME prevents these important “vintage” systems from being lost and forgotten.
+The primary purpose of MAME is to preserve decades of arcade, computer, and
+console history. As technology continues to rush forward, MAME prevents these
+important “vintage” systems from being lost and forgotten.
Systems Emulated by MAME
-========================
-
-
-ProjectMESS contains a complete list of the systems currently emulated. As you will notice, being supported does not always mean that the status of the emulation is perfect. You may want
-
-1. to check the status of the emulation in the wiki pages of each system, accessible from the drivers page (e.g. for Apple Macintosh, from the page for the mac.c driver you can reach the pages for both **macplus** and **macse**),
-2. to read the corresponding **sysinfo.dat** entry in order to better understand which issues you may encounter while running a system in MAME (again, for Apple Macintosh Plus you have to check this entry).
-
-Alternatively, you can simply see the status by yourself, launching the system emulation and taking a look to the red or yellow warning screen which appears before the emulation starts, if any. Notice that if you have information which can help to improve the emulation of a supported system, or if you can directly contribute fixes and/or addition to the current source, you can follow the instructions at the contact page or post to the MAME Forums at http://forum.mamedev.org/
+------------------------
+
+The `Arcade Database <http://adb.arcadeitalia.net/>`_ contains a complete list
+of the systems currently emulated. As you will notice, being supported does not
+always mean that the status of the emulation is perfect. You may want
+
+1. to check the status of the emulation in the wiki pages of each system,
+ accessible from the drivers page (e.g. for Apple Macintosh, from the page for
+ the mac128.cpp driver you can reach the pages for both **macplus** and
+ **macse**),
+2. to read the corresponding **sysinfo.dat** entry in order to better understand
+ which issues you may encounter while running a system in MAME (again, for
+ Apple Macintosh Plus you have to check this entry).
+
+Alternatively, you can simply see the status by yourself, launching the system
+emulation and taking a look at the red or yellow warning screen which appears
+before the emulation starts, if any. Notice that if you have information which
+can help to improve the emulation of a supported system, or if you can directly
+contribute fixes and/or addition to the current source, you can do any of the
+following:
+
+* Send in a pull request (for code) or open an issue (information) on our
+ `GitHub page <https://github.com/mamedev/mame/>`_
+* Post the information or code on the
+ `MAME Forums <https://forum.mamedev.org/>`_
+* Follow the instructions on our
+ `contact page <https://www.mamedev.org/contact.html>`_
Supported OS
-============
-
-The current source code can be directly compiled under all the main OSes: Microsoft Windows (both with DirectX/BGFX native support or with SDL support), Linux, FreeBSD, and Mac OS X. Also, both 32-bit and 64-bit are supported, but be aware 64-bit often shows significant speed increases.
+------------
+The current source code can be directly compiled under all the main operating
+systems: Microsoft Windows (both with DirectX/BGFX native support or with SDL
+support), Linux, FreeBSD, and macOS.
System Requirements
-===================
+-------------------
-MAME is written in fairly generic C/C++, and has been ported to numerous platforms. Over time, as computer hardware has evolved, the MAME code has evolved as well to take advantage of the greater processing power and hardware capabilities offered.
+MAME is written in C++, and has been ported to numerous platforms. Over time, as
+computer hardware has evolved, the MAME code has evolved as well to take
+advantage of the greater processing power and hardware capabilities offered.
-The official MAME binaries are compiled and designed to run on a standard Windows-based system. The minimum requirements are:
+The official MAME binaries are compiled and designed to run on a standard
+Windows-based system. The minimum requirements are:
-* Intel Core series CPU or equivalent, at least 2.0 GHz
-* 32-bit OS (Vista SP1 or later on Windows, 10.9 or later on Mac)
+* Intel Core 2-series CPU or equivalent, at least 2.0 GHz
+* 64-bit OS (Windows 7 or later on Windows, macOS 10.9 or later on Mac)
* 4 GB RAM
* DirectX 9.0c for Windows
* A Direct3D, or OpenGL capable graphics card
-* Any DirectSound capable sound card/onboard audio
-Of course, the minimum requirements are just that: minimal. You may not get optimal performance from such a system, but MAME should run. Modern versions of MAME require more power than older versions, so if you have a less-capable PC, you may find that using an older version of MAME may get you better performance, at the cost of greatly lowered accuracy and fewer supported systems.
+Of course, the minimum requirements are just that: minimal. You may not get
+optimal performance from such a system, but MAME should run. Modern versions of
+MAME require more power than older versions, so if you have a less-capable PC,
+you may find that using an older version of MAME may get you better
+performance, at the cost of greatly lowered accuracy and fewer supported
+systems.
-MAME will take advantage of 3D hardware for compositing artwork and scaling the games to full screen. To make use of this, you should have a modern Direct3D 8-capable video card with at least 16MB of video RAM.
+MAME will take advantage of 3D hardware for compositing artwork and scaling
+displayed software to full screen. To make use of this, you should have at least
+a semi-modern computer with semi-modern 3D hardware made within the last five
+to ten years.
-HLSL or GLSL special effects such as CRT simulation will put a very heavy load on your video card, especially at higher resolutions. You will need a fairly powerful modern video card, and the load on your video card goes up exponentially as your resolution increases. If HLSL or GLSL are too intensive, try dropping your output resolution.
+HLSL or GLSL special effects such as CRT simulation will put a very heavy load
+on your video card, especially at higher resolutions. You will need a fairly
+powerful modern video card, and the load on your video card goes up
+exponentially as your resolution increases. If HLSL or GLSL are too intensive,
+try reducing your output resolution.
-Keep in mind that even on the fastest computers available, MAME is still incapable of playing some systems at full speed. The goal of the project isn't to make all system run speedy on your system; the goal is to document the hardware and reproduce the behavior of the hardware as faithfully as possible.
+Keep in mind that even on the fastest computers available, MAME is still
+incapable of playing some systems at full speed. The goal of the project isn’t
+to make all system run speedy on your system; the goal is to document the
+hardware and reproduce the behavior of the hardware as faithfully as possible.
BIOS Dumps and Software
-----------------------
-Most of the systems emulated by MAME requires a dump of the internal chips of the original system. These can be obtained by extracting the data from an original unit, or finding them (at your own risk) in the WorldWideWeb. Being copyrighted material, MAME does not come with any of these.
+Most of the systems emulated by MAME requires a dump of the internal chips of
+the original system. These can be obtained by extracting the data from an
+original unit, or finding them (at your own risk) on various place on the
+Internet. Being copyrighted material, MAME does not come with any of these.
+
+Also, you may want to find some software to be run on the emulated machine
+where it does not have internal software (e.g. some computers will need a
+disk to boot to an operating system).
-Also, you may want to find some software to be run on the emulated machine. Again, Google and other search engines are your best friends. MAME does not provide any software to be run on the emulated machines because it is very often (almost always, in the case of console software) copyrighted material.
+Again, Google and other search engines are your best friends. MAME does not
+provide any software in the MAME package to be run on the emulated machines
+because it is very often (almost always, in the case of console software)
+protected by copyright.
+The MAME team has been permitted to redistribute some old software, which can be
+found in the `ROMS section of the MAME site <https://www.mamedev.org/roms/>`_.