Readme.md
1# Libretro wrapper for Kodi's Game API
2
3This add-on provides a wrapper that allows Libretro cores to be loaded as game add-ons. Libretro cores are shared libraries that use the Libretro API, so the wrapper is responsible for translating function calls between the Libretro API and the Game API.
4
5This add-on depends on the Game API, which was added in Kodi 18 (Leia).
6
7[](LICENSE.md)
8[](https://travis-ci.org/kodi-game/game.libretro/branches)
9[](https://dev.azure.com/teamkodi/kodi-game/_build/latest?definitionId=25&branchName=Matrix)
10[](https://jenkins.kodi.tv/blue/organizations/jenkins/kodi-game%2Fgame.libretro/branches/)
11<!--- [](https://ci.appveyor.com/project/kodi-game/game-libretro) -->
12
13## Loading mechanism
14
15In Kodi, a game add-on can import another game add-on in its `addon.xml` file. The imported add-on will be loaded instead of the actual add-on, and it is given the original add-on's path as a parameter. If multiple game add-ons are imported, the first will be loaded and given the list of imports, starting with itself and ending with the original game add-on.
16
17Using this strategy, Libretro cores import game.libretro, so Kodi loads game.libretro's library in place of the libretro core and passes it the path to the core. game.libretro in turns loads the Libretro core and begins translating function calls to and from the core.
18
19## Building
20
21Building this add-on requires Kodi's internal CMake-based build system for binary add-ons. If you are cross-compiling or just packaging the add-on, it is recommended that you use the Makefile provided with Kodi.
22
23The Makefile will download, build and install the add-on and its dependencies. There is no need to manually clone the add-on if Kodi's source is available.
24
25The version fetched by Kodi's build system is defined by a text file included with Kodi at [project/cmake/addons/addons/game.libretro](https://github.com/garbear/xbmc/tree/retroplayer-15.2/project/cmake/addons/addons/game.libretro) or fetched from the [binary add-ons repo](https://github.com/xbmc/repo-binary-addons) specified in [cmake/addons/bootstrap/repositories/binary-addons.txt](https://github.com/xbmc/xbmc/blob/master/cmake/addons/bootstrap/repositories/binary-addons.txt).
26
27### Building on Linux
28
29First, make sure Kodi's add-on build system is installed somewhere. You can perform a system install (to `/usr/local`) or a local install (I prefer `$HOME/kodi`). Specify this when you build Kodi:
30
31```shell
32./bootstrap
33./configure --prefix=$HOME/kodi
34make
35make install
36```
37
38Now, run the Makefile with the path to the build system:
39
40```shell
41cd tools/depends/target/binary-addons
42make PREFIX=$HOME/kodi ADDONS="game.libretro"
43```
44
45You can specify multiple add-ons, and wildcards are accepted too. For example, `ADDONS="pvr.*"` will build all pvr add-ons.
46
47On Linux this performs a cross-compile install, so to package the add-on you'll need to copy the library and add-on files manually:
48
49```shell
50mkdir game.libretro
51cp -r $HOME/kodi/share/kodi/addons/game.libretro/ .
52cp -r $HOME/kodi/lib/kodi/addons/game.libretro/ .
53```
54
55To rebuild the add-on or compile a different one, clean the build directory:
56
57```shell
58make clean
59```
60
61### Building on OSX
62
63Building on OSX is similar to Linux, but all the paths are determined for you. This command will download, build and install the add-on to the `addons/` directory in your Kodi repo:
64
65```shell
66cd tools/depends/target/binary-addons
67make ADDONS="game.libretro"
68```
69
70### Building on Windows
71
72First, download and install [CMake](http://www.cmake.org/download/).
73
74To compile on windows, open a command prompt at `tools\buildsteps\win32` and run the script:
75
76```
77make-addons.bat install game.libretro
78```
79
80## Developing
81
82When developing, compiling from a git repo is more convenient than repeatedly pushing changes to a remote one for Kodi's Makefile.
83
84### Developing on Linux
85
86The add-on requires several dependencies to build properly. Like Kodi's build system, you can perform a system install or a local one.
87
88With these dependencies in place, the add-on can be built:
89
90```shell
91git clone https://github.com/kodi-game/game.libretro.git
92cd game.libretro
93mkdir build
94cd build
95cmake -DCMAKE_BUILD_TYPE=Debug \
96 -DCMAKE_PREFIX_PATH=$HOME/kodi \
97 -DCMAKE_INSTALL_PREFIX=$HOME/workspace/kodi/addons \
98 -DPACKAGE_ZIP=1 \
99 ..
100make
101make install
102```
103
104where `$HOME/workspace/kodi` symlinks to the directory you cloned Kodi into.
105
106### Developing on Windows
107
108This instructions here came from this helpful [forum post](http://forum.kodi.tv/showthread.php?tid=173361&pid=2097898#pid2097898).
109
110First, open `tools\windows\prepare-binary-addons-dev.bat` and change `-DCMAKE_BUILD_TYPE=Debug ^` to `-DCMAKE_BUILD_TYPE=Release ^`.
111
112Open a command prompt at `tools\windows` and run the script:
113
114```shell
115prepare-binary-addons-dev.bat game.libretro
116```
117
118Open `cmake\addons\build\kodi-addons.sln` and build the solution. This downloads the add-on from the version specified in its text file (see above) and creates a Visual Studio project for it. If the build fails, try running it twice.
119
120This should package and copy the add-on to the `addons/` directory. If not, you can try opening the solution `cmake\addons\build\<addon-id>-prefix\src\<addon-id>-build\<addon-id>.sln` and building the INSTALL project or, worse case, copy by hand.
121
){kind=link}
){kind=link}