Compile

LibreELEC FAQs
LibreELEC FAQ - General FAQ Raspberry Pi FAQ - Raspberry Pi Specific FAQ Privacy Policy - Privacy policy FAQ

1 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.

2 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).

2.1 Choose Hardware

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.

2.2 Update the OS

It's always good to have the latest updates applied

sudo apt update && sudo apt upgrade

2.3 Install basic dependencies

sudo apt install gcc make git

2.4 Set the bash shell

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

2.5 Configure git

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

git config --global user.email "[email protected]"
git config --global user.name "yourusername"

Further git authentication reading here

3 Clone the LibreELEC build system

cd ~
git clone https://github.com/LibreELEC/LibreELEC.tv.git

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

cd ~/LibreELEC.tv

4 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:

4.1 Specific Version

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.

4.2 Specific Commit

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.

5 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 (for libreelec-8.0 branch):

PROJECT=RPi ARCH=arm

Raspberry Pi zero or 1 (for master branch):

PROJECT=RPi DEVICE=RPi ARCH=arm

Raspberry Pi 2 or 3 (for libreelec-8.0 branch):

PROJECT=RPi2 ARCH=arm

Raspberry Pi 2 or 3 (for master branch):

PROJECT=RPi DEVICE=RPi2 ARCH=arm

HardKernel Odroid C2

PROJECT=Odroid_C2 ARCH=aarch64

WeTek Play

PROJECT=WeTek_Play ARCH=arm

WeTek Play 2

PROJECT=WeTek_Play_2 ARCH=aarch64

WeTek Core

PROJECT=WeTek_Core ARCH=arm

WeTek Hub

PROJECT=WeTek_Hub ARCH=aarch64

Freescale iMX6 (with kernel 4.4 from xbian project)

PROJECT=imx6 ARCH=arm

Freescale iMX6 with kernel 3.14 from solidrun

PROJECT=imx6 ARCH=arm LINUX_VERSION=sr-3.14

VMware or Virtualbox (experimental)

PROJECT=Virtual ARCH=x86_64

6 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

Additionally, use PREFER_PACKAGE_MIRROR=yes to only download packages from the LibreELEC mirror (useful if upstream sources are serving HTML pages in place of package tarballs), e.g.

PREFER_PACKAGE_MIRROR=yes PROJECT=Generic ARCH=x86_64 tools/download-tool

The default is to download packages from the upstream source, and only download from the mirror if the upstream source is not available.

7 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 ~/LibreELEC.tv/target/ 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.

8 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

9 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
rm -rf /home/user/.ccache-libreelec/

You can also "make clean" all built sources

PROJECT=Generic ARCH=x86_64 make clean

10 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.

11 Installing

See: Installation