trunk/docs/emscripten.txt
| r0 | r253194 | |
|---|
| 1 | Compiling MAME to JavaScript via Emscripten |
| 2 | =========================================== |
| 3 | |
| 4 | First, download and install Emscripten by following the instructions at the |
| 5 | official site: |
| 6 | |
| 7 | https://kripken.github.io/emscripten-site/docs/getting_started/downloads.html |
| 8 | |
| 9 | Once Emscripten has been installed, it should be possible to compile MAME |
| 10 | out-of-the-box using Emscripten's 'emmake' tool. Because a full MAME compile is |
| 11 | too large to load into a web browser at once, you will want to use the SOURCES |
| 12 | parameter to compile only a subset of the project, e.g. (in the mame directory): |
| 13 | |
| 14 | emmake make SUBTARGET=pacmantest SOURCES=src/mame/drivers/pacman.cpp |
| 15 | |
| 16 | The SOURCES parameter should have the path to at least one driver .cpp file. |
| 17 | The make process will attempt to locate and include all dependencies necessary |
| 18 | to produce a complete build including the specified driver(s). However, |
| 19 | sometimes it is necessary to manually specify additional files (using commas) if |
| 20 | this process misses something. E.g.: |
| 21 | |
| 22 | emmake make SUBTARGET=apple2e SOURCES=src/mame/drivers/apple2e.cpp,src/mame/machine/applefdc.cpp |
| 23 | |
| 24 | The value of the SUBTARGET parameter serves only to differentiate multiple |
| 25 | builds and need not be set to any specific value. |
| 26 | |
| 27 | Other make parameters can also be used, e.g. -j for multithreaded compilation. |
| 28 | |
| 29 | When the compilation reaches the emcc phase, you may see a number of "unresolved |
| 30 | symbol" warnings. At the moment, this is expected for OpenGL-related functions |
| 31 | such as glPointSize. Any others may indicate that an additional dependency file |
| 32 | needs to be specified in the SOURCES list. Unfortunately this process is not |
| 33 | automated and you will need to search the source tree to locate the files |
| 34 | supplying the missing symbols. You may also be able to get away with ignoring |
| 35 | the warnings if the code path referencing them is not used at run-time. |
| 36 | |
| 37 | If all goes well, a .js file will be output to the current directory. This file |
| 38 | cannot be run by itself, but requires an HTML loader to provide it with a canvas |
| 39 | to output to and pass in command-line parameters. The Emularity project provides |
| 40 | such a loader: |
| 41 | |
| 42 | https://github.com/db48x/emularity |
| 43 | |
| 44 | There are example .html files in that repository which can be edited to point |
| 45 | to your newly compiled MAME js filename and pass in whatever parameters you |
| 46 | desire. You will then need to place all of the following on a web server: |
| 47 | |
| 48 | * The compiled MAME .js file |
| 49 | * The .js files from the Emularity package (loader.js, browserfs.js, etc.) |
| 50 | * A .zip file with the ROMs for the MAME driver you would like to run (if any) |
| 51 | * Any software files you would like to run with the MAME driver |
| 52 | * An Emularity loader .html modified to point to all of the above |
| 53 | |
| 54 | You need to use a web server instead of opening the local files directly due to |
| 55 | security restrictions in modern web browsers. |
| 56 | |
| 57 | If the result fails to run, you can open the Web Console in your browser to see |
| 58 | any error output which may have been produced (e.g. missing or incorrect ROM |
| 59 | files). A "ReferenceError: foo is not defined" error most likely indicates that |
| 60 | a needed source file was omitted from the SOURCES list. |