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

For script compatibility we use the bash shell instead of the Ubuntu default (dash)

sudo dpkg-reconfigure dash

select no, to install bash as the default

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 7.0.2

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=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 or Virtualbox (experimental)

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.

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.