diff options
Diffstat (limited to 'docs/source/initialsetup')
-rw-r--r-- | docs/source/initialsetup/compilingmame.rst | 138 | ||||
-rw-r--r-- | docs/source/initialsetup/index.rst | 11 | ||||
-rw-r--r-- | docs/source/initialsetup/installingmame.rst | 13 | ||||
-rw-r--r-- | docs/source/initialsetup/mameintro.rst | 64 |
4 files changed, 226 insertions, 0 deletions
diff --git a/docs/source/initialsetup/compilingmame.rst b/docs/source/initialsetup/compilingmame.rst new file mode 100644 index 00000000000..889658bb29e --- /dev/null +++ b/docs/source/initialsetup/compilingmame.rst @@ -0,0 +1,138 @@ +Compiling MAME +============== + +.. _compiling-MAME: + +All Platforms +------------- + +* 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 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 **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 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: the maximum number you should use is the number of cores your CPU has, plus one. No higher than that will speed up the compilation, and may in fact slow it down.* For instance, **make -j5** on a quad-core CPU will provide optimal speed. + +* Debugging information can be added to a compile using *SYMBOLS=1* though most users will not want or need to use this. + +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** +| + + +Microsoft Windows +----------------- + +Here are specific notes about compiling MAME for Microsoft Windows. + +* Refer to `the MAME tools site <http://mamedev.org/tools/>`_ for the latest toolkit for getting MAME compiled on Windows. + +* You will need to download the toolset from that link to begin. Periodically, these tools are updated and newer versions of MAME from that point on will **require** updated tools to compile. + +* You can do compilation on Visual Studio 2015 (if installed on your PC) by using **make vs2015**. This will always regenerate the settings, so **REGENIE=1** is *not* needed. + +* Make sure you get SDL 2 2.0.3 or 2.0.4 as earlier versions are buggy. + + +Fedora Linux +------------ + +You'll need a few prerequisites from your distro. Make sure you get SDL2 2.0.3 or 2.0.4 as earlier versions are buggy. + +**sudo yum install gcc gcc-c++ SDL2-devel SDL2_ttf-devel libXinerama-devel qt5-qtbase-devel qt5-qttools expat-devel fontconfig-devel** + +Compilation is exactly as described above in All Platforms. + + +Debian and Ubuntu (including Raspberry Pi and ODROID devices) +------------------------------------------------------------- + +You'll need a few prerequisites from your distro. Make sure you get SDL2 2.0.3 or 2.0.4 as earlier versions are buggy. + +**sudo apt-get install git build-essential libsdl2-dev libsdl2-ttf-dev libfontconfig-dev qt5-default** + +Compilation is exactly as described above in All Platforms. + + +Arch Linux +---------- + +You'll need a few prerequisites from your distro. + +**sudo pacman -S base-devel git sdl2 gconf sdl2_ttf gcc qt5** + +Compilation is exactly as described above in All Platforms. + + +Apple Mac OS X +-------------- + +You'll need a few prerequisites to get started. Make sure you're on OS X 10.9 Mavericks or later. You will NEED SDL2 2.0.4 for OS X. + +* Install **Xcode** from the Mac App Store +* Launch **Xcode**. It will download a few additional prerequisites. Let this run through before proceeding. +* Once that's done, quit **Xcode** and open a **Terminal** window +* Type **xcode-select --install** to install additional tools necessary for MAME + +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' (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 + +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 above in All Platforms. + +It's possible to get MAME working from 10.6, but a bit more complicated: + +* You'll need to install clang-3.7, ld64, libcxx and python27 from MacPorts +* Then add these options to your make command or useroptions.mak: + +| +| OVERRIDE_CC=/opt/local/bin/clang-mp-3.7 +| OVERRIDE_CXX=/opt/local/bin/clang++-mp-3.7 +| PYTHON_EXECUTABLE=/opt/local/bin/python2.7 +| ARCHOPTS=-stdlib=libc++ +| + + +Emscripten Javascript and HTML +------------------------------ + +First, download and install Emscripten by following the 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): + +**emmake make SUBTARGET=pacmantest SOURCES=src/mame/drivers/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 necessary to produce a complete build including the specified driver(s). However, sometimes it is necessary to manually specify additional files (using commas) if this process misses something. E.g.: + +**emmake make SUBTARGET=apple2e SOURCES=src/mame/drivers/apple2e.cpp,src/mame/machine/applefdc.cpp** + +The value of the SUBTARGET parameter serves only to differentiate multiple builds and need not be set to any specific value. + +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 OpenGL-related functions such as glPointSize. Any others may indicate that an additional dependency file needs to be specified in the SOURCES list. Unfortunately this process is not automated and you will need to search the source tree to locate the files supplying the missing symbols. You may also be able to get away with ignoring the warnings if the code path referencing them is 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 output to and pass in command-line parameters. The `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 filename and pass in whatever parameters you desire. You will then need to place all of the following on a web server: + +* The compiled MAME .js file +* The .js files from the Emularity package (loader.js, browserfs.js, etc.) +* A .zip file with the ROMs for the MAME driver you would like to run (if any) +* Any software files you would like to run with the MAME driver +* An Emularity loader .html modified to point to all of the above + +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. diff --git a/docs/source/initialsetup/index.rst b/docs/source/initialsetup/index.rst new file mode 100644 index 00000000000..bd3b3a0d80d --- /dev/null +++ b/docs/source/initialsetup/index.rst @@ -0,0 +1,11 @@ +Getting MAME prepared +--------------------- + +This section covers initial preparation work needed to use MAME, including downloading and compiling MAME. + +.. toctree:: + :titlesonly: + + mameintro + installingmame + compilingmame diff --git a/docs/source/initialsetup/installingmame.rst b/docs/source/initialsetup/installingmame.rst new file mode 100644 index 00000000000..fefaad06543 --- /dev/null +++ b/docs/source/initialsetup/installingmame.rst @@ -0,0 +1,13 @@ +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? + + +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-mame`.
\ No newline at end of file diff --git a/docs/source/initialsetup/mameintro.rst b/docs/source/initialsetup/mameintro.rst new file mode 100644 index 00000000000..03577da2595 --- /dev/null +++ b/docs/source/initialsetup/mameintro.rst @@ -0,0 +1,64 @@ +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. + +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. + +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. + + +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. + + +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/ + + +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. + + +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. + +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) +* 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. + +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. + +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. + +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. + +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. + |