- 1 Cross Compiling and Build Systems
- 2 Create a Build Host
- 3 Clone the LibreELEC build system
- 4 Set the LibreELEC version to compile
- 5 Choose the PROJECT and ARCH to compile
- 6 Download package source code (optional)
- 7 Start compiling
- 8 Moving back to master
- 9 Cleaning up or dealing with odd errors
- 10 Debug build
- 11 Installing
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"
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:
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)
Raspberry Pi zero or 1 (for libreelec-8.0 branch):
Raspberry Pi zero or 1 (for master branch):
PROJECT=RPi DEVICE=RPi ARCH=arm
Raspberry Pi 2 or 3 (for libreelec-8.0 branch):
Raspberry Pi 2 or 3 (for master branch):
PROJECT=RPi DEVICE=RPi2 ARCH=arm
HardKernel Odroid C2
WeTek Play 2
Freescale iMX6 (with kernel 4.4 from xbian project)
Freescale iMX6 with kernel 3.14 from solidrun
PROJECT=imx6 ARCH=arm LINUX_VERSION=sr-3.14
VMware or Virtualbox (experimental)
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.