Cross Compiling and Build Systems

Cross-compiling is the process of creating executable code for a specific hardware platform on a completely different platform. Cross compiling is a crucial function for the LibreELEC project as:

  • It allows us to build 32-bit and 64-bit packages regardless of whether the build-host itself is 32-bit or 64-bit.
  • It allows us to build LibreELEC for a range of different CPU architectures like x86, ARM and aarch64.
  • It allows us to avoid dependencies on the compiler, libc and Linux kernel header versions of the build-host. We compile and then use our own versions.
  • It allows you to run any Linux distribution as your build host. As long as the build system runs the resulting LibreELEC image will be the same.
  • It allows you to use more powerful build hardware, i.e. no need to compile the RPi image on a very slow RPi.

The “build system” is a collection of scripts. It transforms the complex task of cross-compiling hundreds of interdependent source packages into a few simple commands, allowing experienced software developers and inexperienced hobbyist developers to create a bootable LibreELEC image.

Create a Build Host

This guide assumes Ubuntu 16.04.x (LTS) server as the build system OS. It is possible to use other Linux distributions like CentOS/Fedora and Debian to compile LibreELEC images but Ubuntu is simple for less experienced Linux users and is the distro we use for building official LibreELEC images. The server version is preferred because it the desktop version includes a load of software we do not need. Dedicated high-end build server hardware is nice but expensive. Many developers run their build server in a virtual machine on a laptop using vmware Workstation/Fusion or Sun VirtualBox (which is free). Another option is to enable the Docker add-on within LibreELEC and run an Ubuntu Docker Container.

Compile speed is mostly CPU and I/O dependent so a Core i7 CPU with 4x 3GHz cores and SSD will build faster than a Core i3 with 2x 1.8GHz cores and mechanical HDD. RAM usage is moderate: 4GB RAM is enough for normal build tasks; allocate 8GB if you can. The initial build process will consume at least 20-25GB of disk space. If you are sizing a virtual machine we recommend allocating 60-80GB to avoid the need to constantly prune sources/caches and free up space.

It's always good to have the latest updates applied

sudo apt update && sudo apt upgrade
sudo apt install gcc make git unzip wget xz-utils

If you have a github account and will push changes to your personal github repo you must configure git credentials

git config --global ""
git config --global "yourusername"

Further git authentication reading here

Clone the LibreELEC build system

cd ~
git clone

This creates a new folder in your home folder. The folder is the root folder of the build system. Switch to this folder:

cd ~/

Set the LibreELEC version to compile

The version to build is determined by your location (point in time) in the git revision history. After cloning sources you are on the “master” branch and at the “HEAD” of the revision history (the latest commit). If you want to create a current development build there is nothing to do. If you want to build a specific version or rewind to a specific commit (point in time) in the revision history do one of the following:

Checkout using a version tag, e.g. to build LibreELEC v7.0.2 use

git checkout 8.2.5

The git revision history will rewind to that tag.

Obtain the “git hash” for the specific commit that you want to build, e.g. 01b9aae84982d0dfb42a977537d9183935158bd3 and “checkout” the commit

git checkout 65136474fda5302f427f492d40da66645b125cf1

The git revision history will rewind to that commit git hash. You can use long (as above) or short form git hashes.

Choose the PROJECT and ARCH to compile

PROJECT and ARCH are set in the build command to define the target hardware to compile for. The following list shows PROJECT/ARCH for official builds:

64-bit x86 compatible device, e.g. Desktop PC, Intel NUC, ATOM)

PROJECT=Generic ARCH=x86_64

Raspberry Pi zero or 1:


Raspberry Pi 2 or 3:


HardKernel Odroid C2

PROJECT=Amlogic DEVICE=Odroid_C2 ARCH=arm


PROJECT=Amlogic DEVICE=LePotato ARCH=arm





WeTek Hub


WeTek Play 2

PROJECT=Amlogic DEVICE=WeTek_Play_2 ARCH=arm

WeTek Play


WeTek Core


Rockchip RK3328


Rockchip RK3288

PROJECT=Rockchip DEVICE=TinkerBoard ARCH=arm

Rockchip RK3399

PROJECT=Rockchip DEVICE=RK3399 ARCH=arm UBOOT_SYSTEM=rockpro64

64-bit x86 compatible device, e.g. Desktop PC, Intel NUC, ATOM)

PROJECT=Generic ARCH=x86_64

Raspberry Pi zero or 1:


Raspberry Pi 2 or 3:


HardKernel Odroid C2

PROJECT=Odroid_C2 ARCH=aarch64

WeTek Play


WeTek Play 2

PROJECT=WeTek_Play_2 ARCH=aarch64

WeTek Core


WeTek Hub

PROJECT=WeTek_Hub ARCH=aarch64

Freescale iMX6


VMware only. Virtualbox is now unsupported

PROJECT=Virtual ARCH=x86_64

Download package source code (optional)

The build system will automatically download package sources as needed, but this adds time to the first build (on average there are 380+ packages to download). The build system includes a tool to pre-fetch sources and identify packages with missing sources - occasionally an upstream project changes its download location and the URL must be updated.

Using PROJECT and ARCH run the download tool, e.g.

PROJECT=Generic ARCH=x86_64 tools/download-tool

Start compiling

Run this section as a normal user (not as root user or with using sudo)

In the example below we are compiling the Generic PROJECT for the x86_64 ARCH. Appending “make image” will generate an .img.gz file that can be written to USB/SD card media to create a new installation, and a .tar file for updating an existing installation.

PROJECT=Generic ARCH=x86_64 make image

On first run the built-system checks for missing host dependencies (tools needed during compilation) e.g.

Your system lacks the following tools needed to build LibreELEC bc gperf zip unzip makeinfo g++ mkfontscale mkfontdir bdftopcf xsltproc java /usr/include/ncurses.h You seem to use a ubuntu system would you like to install the needed tools ? (y/n) y

If prompted, answer “y” to allow packages to be installed.

The compiling process typically takes 9-12 hours on first run if you did not pre-fetch sources and 3-4 hours if you did.

Once the build completes the finished image will be in the ~/ directory.

To modify the name of the resulting image you can add to your your command line

PROJECT=Generic ARCH=x86_64 IMAGE_SUFFIX=your-name-here make image

The resulting images are named LibreELEC-Generic.x86_64-8.0.0-your-name-here.img.gz.

Compile Add-ons

Run this section as a normal user (not as root user or with using sudo)

Examples to compile add-ons.

Compile Tvheadend 4.2

PROJECT=Generic ARCH=x86_64 scripts/create_addon tvheadend42

Compile every game.libretro add-on

PROJECT=Generic ARCH=x86_64 scripts/create_addon game.*

Compile every Kodi binary add-on

PROJECT=Generic ARCH=x86_64 scripts/create_addon binary

Compile every LE add-on

PROJECT=Generic ARCH=x86_64 scripts/create_addon official

Compile every add-on

PROJECT=Generic ARCH=x86_64 scripts/create_addon all

Exclude add-ons

PROJECT=Generic ARCH=x86_64 scripts/create_addon all -game.* -official -pvr.hts

Log only errors to LE/build-dir/logs/*

PROJECT=Generic ARCH=x86_64 scripts/create_addon all --write-logs=errors

Show help and list every function

PROJECT=Generic ARCH=x86_64 scripts/create_addon --help

Moving back to master

To change from a specific version tag (e.g. 7.0.2) and change to the HEAD (latest commit) of the master branch, do

git checkout master
git pull

To discard local changes and reset everything to the current state of the LibreELEC repo, do

git fetch origin
git reset --hard origin/master

Cleaning up or dealing with odd errors

If you see strange or transient compilation errors start by cleaning existing sources for the failing package and clear ccache, e.g. to clean the linux package do

PROJECT=Generic ARCH=x86_64 scripts/clean linux

You can also remove all build directories (this keeps the ccache)

make clean

or just for one project

PROJECT=Generic ARCH=x86_64 make clean

To remove everything and ccache

make distclean

or just for one project

PROJECT=Generic ARCH=x86_64 make distclean

Debug build

To reduce image sizes the build system automatically strips debug symbols from most packages. If you need to include debug symbols and other common tools useful for advanced debugging pass additional configuration commands, e.g.

To create a debug build use

PROJECT=Generic ARCH=x86_64 DEBUG=yes make image

To also include valgrind add

PROJECT=Generic ARCH=x86_64 DEBUG=yes VALGRIND=yes make image

!! Warning !! The resulting image will be considerably larger than normal and you will need a minimum 512MB boot partition.

Builder Name and Version

If BUILDER_VERSION is present in /etc/os-release, eg. BUILDER_VERSION=123, this value will be included in the url instead of the normal devel-20180601153228-g89fe123 version that would otherwise be used.

This allows stats for the builder to be grouped by a version identifier they are more familiar with (or prefer to use).

When using a custom BUILDER_VERSION it's important to include a unique BUILDER_NAME in order to differentiate build statistics with the same version identifier but from different builders.

PROJECT=Generic ARCH=x86_64 BUILDER_NAME=somename BUILDER_VERSION=123 make image