2013-08-13, 18:46
RetroPlayer can now be used in an embedded linux environment via OpenELEC.
Download builds
Builds can be found in the Builds thread
Changelog
Compile from source
Updating sources
Hacking on OpenELEC
The OpenELEC repo is laid out in several folders. The important ones are:
Handling conflicting patches
OpenELEC carries additional patches for Kodi. Because the OpenELEC team lives on the bleeding edge, many of the patches are pull requests waiting to be reviewed/merged. RetroPlayer is a large patch, so occasionally it will clash with one of OpenELEC's patches. In this case, the conflicting patch must be hunted down in the packages/mediacenter/kodi/patches/ folder and removed. For example, see dc0cdb5.
Handling additional Kodi dependencies
Kodi has an extensive build system that can provide all of its dependencies, as well as binary add-ons. This build system isn't used. Instead, OpenELEC's shell scripts replace all of this functionality. This means that all additional dependencies and binary add-ons must have their own package in the packages/ folder.
Adding binary add-ons
Before I talk about libretro cores, I'll explain peripheral.joystick. The following instructions apply to OpenELEC 5.95.4:
Adding libretro cores
To explain libretro cores, I'll use game.libretro.mupen64plus as an example.
Start by reviewing the general structure of a libretro-based game add-on in the Porting libretro cores to Kodi thread.
Next, follow the binary add-on build steps above for game.libretro.mupen64plus.
You'll recall from the libretro cores thread that the libretro core is defined as a dependency for game.libretro.mupen64plus (see depends/common/mupen64plus). OpenELEC imports the build_addon() macro from Kodi's binary add-on build system, but it doesn't handle add-on depends. This means that we must add the libretro core as an additional package for the OpenELEC build system.
Well there you go, OpenELEC is a powerful build system with an incredibly steep learning curve, probably because the thing is 100% shell script. Adding RetroPlayer required 3,000 lines of bash. Think about that. Every 100 lines of code creates 1 bug. I've hit far more than 30 typos/snafus over the few years I've been doing OpenELEC retroplayer builds, so this would appear an underestimate. If you design your own build system, please try to avoid heavy use of copy-paste and prefer declarative syntaxes over imperative ones.
Download builds
Builds can be found in the Builds thread
Changelog
- 2015-09-02: Updated to RetroPlayer based on Kodi 15.1 on OpenELEC 6.0 beta 4 (5.95.4)
- 2014-07-04: Updated to RetroPlayer based on XBMC 13.1 on OpenELEC 4.0.6
- 2014-05-26: Updated to RetroPlayer based on XBMC 13.0 on OpenELEC 4.0.0
- 2013-09-12: Updated to RetroPlayer PR candidate based on XBMC 12-alpha7 on OpenELEC 3.2.0
Compile from source
- Clone my OpenELEC fork: https://github.com/garbear/OpenELEC.tv
- cd into tools/mkpkg and run ./mkpkg_kodi-retroplayer and ./mkpkg_retroplayer
- ./mkpkg_kodi-retroplayer will download and package the latest RetroPlayer from https://github.com/garbear/xbmc
- ./mkpkg_retroplayer will download and package all libretro cores and their game add-on wrappers at their master version
- ./mkpkg_kodi-retroplayer will download and package the latest RetroPlayer from https://github.com/garbear/xbmc
- (optional) Verify sources have been packaged. cd into sources/ and inspect archives
- Compile OpenELEC for the chosen project and architecture, e.g. time PROJECT=Generic ARCH=x86_64 make release
Updating sources
- Make sure your OpenELEC repo is on the default branch
- Currently retroplayer-5.95.4. You can check the default branch here
- Currently retroplayer-5.95.4. You can check the default branch here
- Make sure your OpenELEC repo is up-to-date
- Example: git pull --rebase (the --rebase avoids merge errors in case I force push)
- If git says "Cannot pull with rebase: You have unstaged changes. Please commit or stash them", run git stash and try again
- Example: git pull --rebase (the --rebase avoids merge errors in case I force push)
- Run ./mkpkg_kodi-retroplayer to update RetroPlayer archive in the sources/ folder
- If ./mkpkg_kodi-retroplayer yields merge errors, remove tools/mkpkg/kodi-retroplayer-15.1.git/ and try again
- If ./mkpkg_kodi-retroplayer yields merge errors, remove tools/mkpkg/kodi-retroplayer-15.1.git/ and try again
- Run ./mkpkg_retroplayer to update libretro cores, game add-ons and peripheral add-ons
- (optional) Run git diff. This will show you all the package versions that have been updated
Hacking on OpenELEC
The OpenELEC repo is laid out in several folders. The important ones are:
- build.OpenELEC-Generic.x86_64-5.95.4/
- The build.XXXXX folders contain the compiled packages. If a package is misbehaving, you can force a rebuild by deleting its folder here
- The build.XXXXX folders contain the compiled packages. If a package is misbehaving, you can force a rebuild by deleting its folder here
- packages/
- This defines all the packages, their versions, and build instructions
- Kodi is defined in packages/mediacenter/kodi. This package shows off many of the features of the OpenELEC build system, including patches and OS files
- Binary add-ons require an extra definition. Add their package name to packages/virtual/mediacenter/package.mk. If a binary add-on fails to compile, comment it out in this file
- This defines all the packages, their versions, and build instructions
- sources/
- OpenELEC looks here for packaged sources
- If the source doesn't exist, OpenELEC will try to download from the OpenELEC server
- RetroPlayer isn't hosted on the OpenELEC server. This is why ./mkpkg_kodi-retroplayer and ./mkpkg_retroplayer were created
- OpenELEC looks here for packaged sources
- scripts/
- This is the OpenELEC build system itself. Much of my OpenELEC knowledge has come from reading the sources
- This is the OpenELEC build system itself. Much of my OpenELEC knowledge has come from reading the sources
Handling conflicting patches
OpenELEC carries additional patches for Kodi. Because the OpenELEC team lives on the bleeding edge, many of the patches are pull requests waiting to be reviewed/merged. RetroPlayer is a large patch, so occasionally it will clash with one of OpenELEC's patches. In this case, the conflicting patch must be hunted down in the packages/mediacenter/kodi/patches/ folder and removed. For example, see dc0cdb5.
Handling additional Kodi dependencies
Kodi has an extensive build system that can provide all of its dependencies, as well as binary add-ons. This build system isn't used. Instead, OpenELEC's shell scripts replace all of this functionality. This means that all additional dependencies and binary add-ons must have their own package in the packages/ folder.
Adding binary add-ons
Before I talk about libretro cores, I'll explain peripheral.joystick. The following instructions apply to OpenELEC 5.95.4:
- Create packages/mediacenter/kodi-binary-addons/peripheral.joystick/package.mk
First, the package must be defined. The variables are self explanatory. PKG_VERSION should point to the hash of the master branch. Fortunately, this hash is sed'ed to whatever version is placed in the sources/ directory by the mkpkg_retroplayer script.
The build instructions in package.mk look like this:
Code:configure_target() {
cmake -DCMAKE_TOOLCHAIN_FILE=$CMAKE_CONF \
-DCMAKE_INSTALL_PREFIX=/usr \
-DCMAKE_MODULE_PATH=$SYSROOT_PREFIX/usr/lib/kodi \
-DCMAKE_PREFIX_PATH=$SYSROOT_PREFIX/usr \
..
}
addon() {
mkdir -p $ADDON_BUILD/$PKG_ADDON_ID/
cp -PR $PKG_BUILD/.install_pkg/usr/share/kodi/addons/$PKG_NAME/* $ADDON_BUILD/$PKG_ADDON_ID/
cp -PL $PKG_BUILD/.install_pkg/usr/lib/kodi/addons/$PKG_NAME/*.so $ADDON_BUILD/$PKG_ADDON_ID/
}
Where does the configure step come from? View the readme at https://github.com/kodi-game/peripheral.joystick . You can see that the cmake step is adapted from the instructions in the readme.
The addon() step is a result of Kodi's binary add-on build system. Open peripheral.joystick's CMakeLists.txt and scroll to the bottom.You'll see the line
Code:build_addon(peripheral.joystick JOYSTICK DEPLIBS)
The build_addon() macro invokes Kodi's binary add-on build system. At least part of it (more on this later). The cp commands copy the output of this macro to the correct OpenELEC directory.
- Edit packages/virtual/mediacenter/package.mk
OK, so the package is defined. We must tell OpenELEC that Kodi depends on this add-on so that it'll be built. This is accomplished by editing packages/virtual/mediacenter/package.mk and adding the line
Code:PKG_DEPENDS_TARGET="$PKG_DEPENDS_TARGET peripheral.joystick"
- Create tools/mkpkg/mkpkg_peripheral.joystick
Now OpenELEC will include peripheral.joystick in the build. However, it'll try to download a source archive from the OpenELEC server, which obviously doesn't exist. To solve this, we'll copy/paste/modify another binary add-on's script to create our own at tools/mkpkg/mkpkg_peripheral.joystick. This script will:
- Clone peripheral.joystick
- Archive the sources into peripheral.joystick-XXXXXXX.tar.xz
- Copy the archive to sources/peripheral.joystick/peripheral.joystick-XXXXXXX.tar.xz
- Create a .md5 and .url file. If either of these is missing or not EXACTLY as they should be, OpenELEC will ignore the source archive and attempt (and fail) to download from sources.openelec.tv.
- Update the version hash using sed in peripheral.joystick's package.mk from earlier. If the version was updated, you can view this using git diff
- Clone peripheral.joystick
- Edit tools/mkpkg/mkpkg_retroplayer
Finally, so that peripheral.joystick will be updated along with the other retroplayer add-ons, edit the file tools/mkpkg/mkpkg_retroplayer and add the line
Code:./mkpkg_peripheral.joystick
Adding libretro cores
To explain libretro cores, I'll use game.libretro.mupen64plus as an example.
Start by reviewing the general structure of a libretro-based game add-on in the Porting libretro cores to Kodi thread.
Next, follow the binary add-on build steps above for game.libretro.mupen64plus.
You'll recall from the libretro cores thread that the libretro core is defined as a dependency for game.libretro.mupen64plus (see depends/common/mupen64plus). OpenELEC imports the build_addon() macro from Kodi's binary add-on build system, but it doesn't handle add-on depends. This means that we must add the libretro core as an additional package for the OpenELEC build system.
- Create packages/mediacenter/kodi-binary-addons/libretro-mupen64plus/package.mk.
The build instructions in package.mk now look like this:
Code:make_target() {
make
}
makeinstall_target() {
mkdir -p $INSTALL/usr/lib
cp $PKG_LIBPATH $INSTALL/usr/lib/$PKG_LIBNAME
echo "set($PKG_LIBVAR $INSTALL/usr/lib/$PKG_LIBNAME)" > $SYSROOT_PREFIX/usr/$PKG_NAME-config.cmake
}
Similar to game.libretro.mupen64plus, these are derived from commands in the depend's CMakelists.txt. The make_target() function is equal to the build command for linux from CMakeLists.txt (for release build, ${LIBRETRO_DEBUG} is empty):
Code:elseif("${CORE_SYSTEM_NAME}" STREQUAL "linux")
set(BUILD_COMMAND make ${LIBRETRO_DEBUG})
This depends on the build command for the core. For example, see FCEUmm's CMakeLists.txt. The linux build command is
Code:elseif("${CORE_SYSTEM_NAME}" STREQUAL "linux")
set(BUILD_COMMAND make -f Makefile.libretro ${LIBRETRO_DEBUG})
and the corresponding make_target() in packages/mediacenter/kodi-binary-addons/libretro-fceumm/package.mk is:
Code:make_target() {
make -f Makefile.libretro
}
Now for makeinstall_target(). The lines
Code:PKG_LIBNAME="mupen64plus_libretro.so"
PKG_LIBPATH="$PKG_LIBNAME"
PKG_LIBVAR="MUPEN64PLUS_LIB"
cp $PKG_LIBPATH $INSTALL/usr/lib/$PKG_LIBNAME
are derived from the install command in CMakeLists.txt:
Code:#install the generated shared library
install(FILES ${PROJECT_SOURCE_DIR}/mupen64plus_libretro${CMAKE_SHARED_LIBRARY_SUFFIX}
DESTINATION ${CMAKE_INSTALL_PREFIX}/lib)
You'll see that:
- $PKG_LIBPATH is equal to mupen64plus_libretro${CMAKE_SHARED_LIBRARY_SUFFIX}
- $INSTALL/usr/lib/$PKG_LIBNAME is equal to ${CMAKE_INSTALL_PREFIX}/lib/mupen64plus_libretro${CMAKE_SHARED_LIBRARY_SUFFIX}
Another variation is if a core's output .so is in a subdirectory. For example, from Nestopia's CMakeLists.txt, the build command is
Code:elseif("${CORE_SYSTEM_NAME}" STREQUAL "linux")
set(BUILD_COMMAND make -C libretro ${LIBRETRO_DEBUG})
make -C libretro outputs to a subfolder named "libretro". Correspondingly, the install command looks like (notice the extra "libretro"):
Code:#install the generated shared library
install(FILES ${PROJECT_SOURCE_DIR}/libretro/nestopia_libretro${CMAKE_SHARED_LIBRARY_SUFFIX} DESTINATION ${CMAKE_INSTALL_PREFIX}/lib)
and the $PKG_LIBPATH in packages/mediacenter/kodi-binary-addons/libretro-nestopia/package.mk is defined as such:
Code:PKG_LIBNAME="nestopia_libretro.so"
PKG_LIBPATH="libretro/$PKG_LIBNAME"
Finally, The line echo "set($PKG_LIBVAR $INSTALL/usr/lib/$PKG_LIBNAME)" > $SYSROOT_PREFIX/usr/$PKG_NAME-config.cmake (which generates libretro-mupen64plus-config.cmake) is the bash equivalent of:
Code:# write the mupen64plus-config.cmake script
file(WRITE ${CMAKE_INSTALL_PREFIX}/libretro-mupen64plus-config.cmake "set(MUPEN64PLUS_LIB
${CMAKE_INSTALL_PREFIX}/lib/mupen64plus_libretro${CMAKE_SHARED_LIBRARY_SUFFIX})")
- $PKG_LIBPATH is equal to mupen64plus_libretro${CMAKE_SHARED_LIBRARY_SUFFIX}
- Create packages/mediacenter/kodi-binary-addons/libretro-mupen64plus/patches
Remember how OpenELEC doesn't build add-on depends and we need to do everything ourselves? Copy the patches from depends/common/mupen64plus/ to packages/mediacenter/kodi-binary-addons/libretro-mupen64plus/patches/
- Edit packages/virtual/mediacenter/package.mk and add the line:
Code:PKG_DEPENDS_TARGET="$PKG_DEPENDS_TARGET libretro-mupen64plus"
- Create tools/mkpkg/mkpkg_libretro-mupen64plus
- Edit tools/mkpkg/mkpkg_retroplayer and add the line:
Code:./mkpkg_libretro-mupen64plus
Well there you go, OpenELEC is a powerful build system with an incredibly steep learning curve, probably because the thing is 100% shell script. Adding RetroPlayer required 3,000 lines of bash. Think about that. Every 100 lines of code creates 1 bug. I've hit far more than 30 typos/snafus over the few years I've been doing OpenELEC retroplayer builds, so this would appear an underestimate. If you design your own build system, please try to avoid heavy use of copy-paste and prefer declarative syntaxes over imperative ones.
