Building cores is a 3-step process:
- Setup (you only need to do this once)
- Build the core (repeat as needed)
- Clone the core from GitHub if you haven't already
- Patch the core if needed
- Set emscripten env vars in your shell
- Build the core (will output a
.bcfile that will be used later)
- Clone RetroArch from GitHub if you haven't already
- Set emscripten env vars in your shell
- Copy the
.bcfiles from earlier into the RetroArch repo - Build RetroArch (this links the core(s))
- Copy the
.jsand.wasmfiles into the core directory in the webretro repo
You need to set up WSL2 if on windows, otherwise proceed to the next step. I use Debian 11 on WSL2.
Follow the instructions here to install WSL2.
Please note that any further terminal use in these instructions will need to use the bash shell. On windows, simply go to a command prompt or powershell and type bash
Follow the instructions here to install git.
Or on Debian or Ubuntu, simply type sudo apt install git
Ensure Python 3 is installed first.
On Debian or Ubuntu, simply type sudo apt install python3
Follow the instructions here to install the emsdk.
!!!!! DO NOT USE EMSDK TO INSTALL EMSCRIPTEN YET !!!!!
Or run these commands to install emsdk:
git clone https://github.com/emscripten-core/emsdk.git
cd emsdk
Now use emsdk to install emscripten (version: 2.0.15):
./emsdk install 2.0.15
./emsdk activate 2.0.15
Emscripten's library_webgl.js needs patching due to issue 4214. Without the patch some pretty strange graphics bugs can happen on 3D cores.
In the future I may work on a faster fix like the one mentioned here.
- CD into the emsdk directory
- Download
emscripten.patchand place it in the base directory of the emsdk repository - Run this command:
patch -u -p0 -i emscripten.patch
(Only do this step once)
Go to the core reference section and find the core that you want to build. If it is not listed, find it on GitHub and skip the checkout and patch step.
If the core is listed in core reference
Clone the repository and checkout to the specific commit that I built with:
git clone -n <REPOSITORY>
cd <REPOSITORY DIR>
git checkout <COMMIT SHA>
Cloning and checking out Nestopia as an example:
git clone -n https://github.com/libretro/nestopia
cd nestopia
git checkout a9e197f2583ef4f36e9e77d930a677e63a2c2f62
If the core is not listed in core reference
Just clone the repository:
git clone <REPOSITORY>
Cloning Nestopia as an example:
git clone https://github.com/libretro/nestopia
(Only do this step once)
If you found the core in core reference AND it has a listed patch file, follow these instructions to apply the patch. Otherwise, skip this step.
- CD into the core directory
- Download the provided patch file and place it in the base directory of the cloned core repository
- Run this command:
git apply <PATCHFILE>
Patching Mupen64Plus-Next as an example:
git apply mupen64plus_next.patch
See set emscripten environment variables
- CD into the core directory
- Locate the makefile, it's usually called
Makefile.libretroor justMakefile. Sometimes it is in subdirectories, look for ones with "libretro" in the name. - CD into the directory where the makefile is (or don't CD if the makefile is at the base directory of the core repository)
- Run this command:
emmake make -f <MAKEFILE> platform="emscripten"
Wait for the core to finish building. It may take up to a hour depending on the speed of your computer and the size of the core.
After the build is finished, you will be left with a .bc file. Save it for the next step.
Here are some examples:
Nestopia:
cd libretro
emmake make -f Makefile platform="emscripten"
Mupen64Plus-Next:
emmake make -f Makefile platform="emscripten"
Genesis Plus GX:
emmake make -f Makefile.libretro platform="emscripten"
(Only do this step once)
Clone the repository and checkout to the specific commit that I built with:
git clone -n https://github.com/libretro/RetroArch
cd RetroArch
git checkout 1f3fa0a35b0b572204911b9845391df62ab22b96
(Only do this step once)
- CD into the RetroArch directory
- Download
retroarch.patchand place it in the base directory of the RetroArch repository - Run this command:
git apply retroarch.patch
See set emscripten environment variables
Copy the .bc file(s) from earlier into the dist-scripts subdirectory of the RetroArch repository. You can link multiple cores at once with some exceptions: (see note)
it's important to note that cores that use different linker settings will need to be linked in separate groups, these include
- GLES3 (as opposed to GLES2) (
mupen64plus_next,parallel_n64,mednafen_psx_hw) (compile + link time) - different amounts of memory (
mupen64plus_next,mednafen_psx(_hw)) (link time) - Pthreads (
melondsif built with thread support) (compile + link time) - Asyncify (
mupen64plus_next,parallel_n64) (link time)
- CD into
RetroArch/dist-scripts - Run this command:
emmake ./dist-cores.sh emscripten
Wait for the build and linking to complete. The build usually takes around 5 minutes and linking can take up to 2 minutes per core.
The built .js and .wasm files will be in the pkg/emscripten subdirectory of the RetroArch repository.
Copy them into the cores directory of your webretro instance. You are done!
In order to use commands such as emmake, you first need to use the environment variables script provided with emsdk.
You need to call it with source, which is simply a period (.) in bash.
The command should look something like this (replace the path with the actual path to the script):
. path/to/emsdk/emsdk_env.sh
diff -u original.file modified.file > patch.patch
may have to edit the file to change the file path
If there are untracked files:
git add .
git diff --cached > patch.patch
git reset .
Otherwise:
git diff > patch.patch
git rev-parse HEAD
GitHub: https://github.com/libretro/a5200
Commit: 46035d00a5fb7ffd3a63172c2d0a8c6b6ae7efc1
Patch file: a5200.patch
Makefile path: ./Makefile
Extra notes:
GitHub: https://github.com/libretro/beetle-ngp-libretro
Commit: d4b1a533a4ee2b600771bca21b270c4c27e7440b
Patch file: mednafen_ngp.patch
Makefile path: ./Makefile
Extra notes:
GitHub: https://github.com/libretro/beetle-psx-libretro
Commit: f3dedf5372d6ca2b994268fecedd97e65cf86396
Patch file: mednafen_psx_hw.patch
Makefile path: ./Makefile
Extra notes: see pull #856. For building without HW, don't apply the patch.
GitHub: https://github.com/libretro/beetle-vb-libretro
Commit: 0b9ea3882e187bc1fe0daf3d258fde660798ed7e
Patch file: mednafen_vb.patch
Makefile path: ./Makefile
Extra notes:
GitHub: https://github.com/libretro/beetle-wswan-libretro
Commit: 16d96f64a32cbe1fa89c40b142298dbd007f2f4d
Patch file: mednafen_wswan.patch
Makefile path: ./Makefile
Extra notes:
GitHub: https://github.com/libretro/FreeChaF
Commit: 1030d5e64078767480cccef4c7e5539db4be31b9
Patch file: freechaf.patch
Makefile path: ./Makefile
Extra notes: FreeChaF has submodules, run this command after cloning/checkout: git submodule update --init
GitHub: https://github.com/libretro/FreeIntv
Commit: 295dd3c9e4b2d4f652f6a6a904afbe90a8187068
Patch file: freeintv.patch
Makefile path: ./Makefile
Extra notes:
GitHub: https://github.com/drhelius/Gearcoleco
Commit: b1dac72f99dca329620cfbc72909bc90dff1837f
Patch file: gearcoleco.patch
Makefile path: ./platforms/libretro/Makefile
Extra notes:
GitHub: https://github.com/libretro/Genesis-Plus-GX
Commit: 643163443db96ca89d1826422a414da3768b4641
Patch file: genesis_plus_gx.patch
Makefile path: ./Makefile.libretro
Extra notes:
GitHub: https://github.com/libretro/libretro-handy
Commit: 517bb2d02909271836604c01c8f09a79ad605297
Patch file: handy.patch
Makefile path: ./Makefile
Extra notes:
GitHub: https://github.com/libretro/melonds
Commit: 490a66a5834e23304addc9b16a2f95da6db9f061
Patch file: melonds.patch
Makefile path: ./Makefile
Extra notes:
GitHub: https://github.com/libretro/mgba
Commit: 5d48e0744059ebf38a4e937b256ffd5df4e0d103
Patch file: none
Makefile path: ./Makefile.libretro
Extra notes:
GitHub: https://github.com/libretro/mupen64plus-libretro-nx
Commit: 6e9dcd2cd9d23d3e79eaf2349bf7e9f25ad45bf1
Patch file: mupen64plus_next.patch
Makefile path: ./Makefile
Extra notes: Some of the patch was made by ToadKing in this commit (original commit).
GitHub: https://github.com/libretro/neocd_libretro
Commit: b7d96e794f2dfa500cba46c78cbc3c28349cfd05
Patch file: neocd.patch
Makefile path: ./Makefile
Extra notes: Patch adds necessary LZMA deps to statically linked build
GitHub: https://github.com/libretro/nestopia
Commit: a9e197f2583ef4f36e9e77d930a677e63a2c2f62
Patch file: nestopia.patch
Makefile path: ./libretro/Makefile
Extra notes:
GitHub: https://github.com/libretro/libretro-o2em
Commit: 641f06d67d192a0677ec861fcb731d3ce8da0f87
Patch file: o2em.patch
Makefile path: ./Makefile
Extra notes:
GitHub: https://github.com/libretro/opera-libretro
Commit: 5b382f8f24a645b171c4bb2220e7f7c5462671ce
Patch file: opera.patch
Makefile path: ./Makefile
Extra notes: Patch fixes wrong symbol type in libretro-common/file
GitHub: https://github.com/libretro/parallel-n64
Commit: b804ab1a199d6ff1f8fef4aa7dfcf663990e430b
Patch file: parallel_n64.patch
Makefile path: ./Makefile
Extra notes: Patch adds ToadKing's libco support
GitHub: https://github.com/libretro/prosystem-libretro
Commit: fbf62c3dacaac694f7ec26cf9be10a51b27271e7
Patch file: prosystem.patch
Makefile path: ./Makefile
Extra notes:
GitHub: https://github.com/libretro/snes9x
Commit: ae16176a18fa2a7d642be5d66dbe1926d9d08e90
Patch file: snes9x.patch
Makefile path: ./libretro/Makefile
Extra notes:
GitHub: https://github.com/libretro/stella2014-libretro
Commit: 1351a4fe2ca6b1f3a66c7db0df2ec268ab002d41
Patch file: stella2014.patch
Makefile path: ./Makefile
Extra notes:
GitHub: https://github.com/libretro/libretro-vecx
Commit: 141af284202c86ed0d4ce9030c76954a144287cf
Patch file: vecx.patch
Makefile path: ./Makefile.libretro
Extra notes:
GitHub: https://github.com/libretro/virtualjaguar-libretro
Commit: 263c979be4ca757c43fb525bd6f0887998e57041
Patch file: virtualjaguar.patch
Makefile path: ./Makefile
Extra notes:
GitHub: https://github.com/libretro/yabause
Commit: c7e02721eddb3de0ec7ae0d61e9e3afa5f586a62
Patch file: yabause.patch
Makefile path: ./yabause/src/libretro/Makefile
Extra notes:
GitHub: https://github.com/
Commit: SHA1
Patch file: patch.patch
Makefile path: ./Makefile
Extra notes: