I’ve decided to do something a little bit different today in-between shooting videos for the YouTube channel, It’s something I have been meaning to get done for a while but haven’t found time for (unfortunately juggling The MXQ Project, family, kids and other work commitments isn’t the easiest thing in the world to do). In todays written, step-by-step, super-easy to follow tutorial I will be showing you how to compile a LibreELEC image that can be written to an SD card and ran from your Amlogic TV boxes using Kszaq’s source code. In this step-by-step guide will be compiling a LibreELEC image for use with an MXQ box (Amlogic S805, HD18Q model) but you can use this guide and apply it to devices that contain other Amlogic SOCs. You could even apply it to the Raspberry Pi or even your PC/Laptop just by changing a few small details, I will point those out as we come to them.
LibreELEC is a Linux based, open source operating system that is built for the sole purpose of running the Kodi media centre software. It is ideal for running on TV boxes as it takes up only tiny about of storage space and can run on a minimal amount of RAM.
LibreELEC allows us to compile the operating system for other hardware using a process called ‘Cross Compiling’, this basically allows us to use for example, a PC, to compile the system for a different device, in this case an MXQ box containing a HD18Q motherboard. It also works for other devices as well, for example, we can use a 32 bit PC to build a LibreELEC install for a 64 bit device and vice versa. Cross Compiling also lets us build LibreELEC for different CPU architectures such as x86, ARM and aarch64.
In the simplest terms this means we can build a LibreELEC image using much more powerful build host (more on that in a moment), e.g. we can use a PC to build a LibreELEC image that we can install onto an MXQ box, rather than have to use the MXQ box itself to compile everything as I’m sure is the case with certain other things. The same can be said for other devices such as the Raspberry Pi etc.
Setting up your ‘Build Host’
A Build host is basically the machine and setup you will be using to compile the operating system. Compiling a Linux based operating system such as LibreELEC will, in turn, require you to use a Linux based OS for the compiling procedure. For this tutorial I will be using Ubuntu 14.04 LTS. I recommend using Ubuntu as it is very user friendly and it is one of the more simple Linux distributions for less experienced users to get to grips with. However other Linux distros such as Debian and Fedora will work as well.
You do not have to physically install Linux onto your build host to follow along to this tutorial but If you wish to do install it either as your sole operating system or dual booting it alongside Windows then there are a myriad of different tutorials and methods available to you so I would suggest going to Google and searching how to do this. The other method, which is probably the easier way, is to set up what is known as a ‘Virtual Machine’ using a piece of software such as Virtual Box. This allows you to run the operating system ‘inside’ of your current operating system (assuming you are using Windows), again there are plenty of tutorials around that can teach you how to do this so just get onto Google and have a look. This tutorial is going to assume you have already got Linux up and running on your build host.
You are going to need around 20-25GB of free disk space if you have installed Linux to a partition on your computers hard drive, if you are using Virtual Box etc. then make sure to allocate around 70GB of space when setting up the virtual machine if possible as this will speed things up noticeably. Obviously it goes without saying that the better the specs of your build host, the faster everything will compile. You can usually get away with 4GB of RAM as that is enough to handle the build process but things will be quicker the more memory you have, and of course the faster you CPU the faster the build will be. It goes without saying that a Quad Core Intel i7 is going to compile faster than an old dual core 1.8ghz CPU.
Things you will need
Just to recap, here’s what you will need to get going with this tutorial.
- Computer with Linux installed or set up as a virtual machine
- Preferably some hardware to test out your final build i.e. the TV box you are compiling for
And that’s it really, so hopefully by the end of this guide you will have a working image to install onto your TV box and will have gained some knowledge about how things are compiled within Linux. So lets get started
Step 1: Update the OS
Open up a terminal window (CTRL+ALT+T on Ubuntu) and type the following command, press enter, enter your password then hit enter again.
sudo apt update && sudo apt upgrade
This function will update your operating system for you to make sure everything is up to date. It isn’t strictly required but it isn’t going to hurt to make sure everything is going to run as expected.
The terminal will quickly become your new best friend in any Linux distribution when doing things like this, it is where we will input all the commands when downloading and compiling from the source code. Sure, there are graphical user interfaces similar to Windows that allow you to do most of the usual things you would find yourself doing but if you are anything like me, then you will end up using the terminal for virtually everything! And to put that in perspective, I used Linux (more specifically Ubuntu) for the very first time just last year, and everything I have learned has more or less been self taught using tutorials like this and just plain old playing around.
Step 2: Install some basic dependencies
Once your OS has finished updating itself go ahead and type this command then hit enter:
sudo apt install gcc make git
This will install some things that are needed in order for us to compile.
Step 3: Setting the Bash Shell
After the dependencies have installed, type the following command and press enter:
sudo sudo-dpkg-reconfigure dash
The terminal will display a new window asking if you want to use ‘dash’ as the default system shell, just highlight ‘No’ and hit enter.
Step 4: Configuring Git (Optional)
If you have a GitHub account then you can follow this step and input your email and username, this will make things a bit easier in future if you ever want to ‘push’ your work to your own Git repo.
git config --global user.email "firstname.lastname@example.org"
git config --global user.name "yourusername"
Substitute the “your@email” for your GitHub email address and “yourusername” with your correct username.
Step 5: Cloning the LibreELEC build system
This is where we will ‘pull’ the source code from GitHub (notice the terminology where GitHub commands are concerned? Push = Upload & Pull = Download). The source code is everything we need to start compiling. For this tutorial we are compiling for an Amlogic TV box so we are using Kszaq’s LibreELEC source code, which means we are going to be cloning his GitHub repository rather than the official LibreELEC one.
Let’s make sure we are in the root folder by typing:
Next lets pull that source code. To do this type:
git clone https://github.com/kszaq/LibreELEC.tv.git
This may take a little while depending on your internet connection speed so be patient. In the mean time feel free to open your browser and head to the URL that we typed into the terminal, you will find all the files and folders that we are currently downloading. It’s a good idea to take a look through these at your leisure as it may give you a better understanding of the structure. Once cloning of the git repo has finished you may notice a new folder has been made in your root directory called ‘LibreELEC.tv’, this is now where all our source code is being stored and also where we will find our final build later on.
Go back to the terminal and type:
Step 6: Choosing a version to compile (optional)
By default we will compile the latest version of LibreELEC in accordance with when we downloaded the source code, meaning when we ‘pulled’ the source code from Kszaq’s repo it was the latest version at the time, but if for whatever reason you wish to compile an earlier version, then you can do this a couple of different ways. For example, in the terminal you can use the command below to compile a specfic version of the OS by typing: (replacing the 0’s with the specific version number).
git checkout 0.0.0.0
If, however, you wish to compile a specific commit of the source code, for example, an earlier revision that was ‘pushed’ to the repo, perhaps one that had a specific feature enabled or disabled you can type: (replacing the X’s with the specific ‘git hash’)
git checkout xxxxxxxxxxxxxx
I’m not going to go into any detail regarding git hashes etc. in this tutorial so let’s move on.
Step 7: Setting the PROJECT & ARCH
The PROJECT and ARCH defines the type of device we will be compiling for (in our case an S805 box), the PROJECT being the device itself and the ARCH being the architecture of the CPU that the device uses. Thankfully as we are using source code from Kszaq we have some predefined projects for Amlogic TV boxes, as well as the officially supported devices. Kszaq has also made his source code compatible with a few different motherboards, so we can add in an extra element to the command. As we are compiling for an All-black, MXQ S805 box with a HD18Q motherboard then we would type this:
PROJECT=S805 SYSTEM=HD18Q ARCH=arm
This means we are compiling for an Amlogic S805 box, for a device with a HD18Q motherboard and an ARM processor architecture & having done this we can rest assured that when it comes to compiling it will compile the correct kernel, drivers etc. that we need to run the OS correctly. Some projects, however, do not require the SYSTEM element to be added and can be set just using the PROJECT= and ARCH= commands. For example if you are compiling for a PC or Laptop the command would look like this:
Kszaq also provides us with 2 other alternative systems for S805 devices, if you have a standard MXQ such as the Beelink Model with the red stripe on the front then it would be SYSTEM=MXQ and for other S805 boxes that have 512mb of RAM then it’s SYSTEM=m201d. It can be very confusing with these generic devices that use similar branding. My advice would be to download a recent, pre-compiled version of LibreELEC from here, and test which of the 3 works for your box before continuing with this step.
Step 8: Downloading package source code (Recommended)
This step is entirely optional as these files will be downloaded automatically once the compiling procedure starts, however, it should be noted that performing this step now will actually speed things up dramatically during the final compiling process. There are around 380+ packages that will be downloaded during compiling so I would recommend doing it at this point, this way it will download only the packages required for the version you are compiling, rather than every package for every device. We are going to download source code for the packages using this terminal command:
PROJECT=S805 ARCH=arm tools/download-tool
Now go and grab some coffee and a snack (I recommend crumpets with cheese) and relax as this part can take a while depending on your connection speed.
Step 9: Let’s get compiling!
OK, so this is the step you’ve probably been waiting for, compiling your first build of LibreELEC, getting to this point is the good news, the bad news is that it can be a lengthy process depending on your build host and whether or not you completed the optional step of downloading the package source code (See Step 8). If you chose to complete Step 8 then the build time will on take around 3-4 hours on an average machine, possible even quicker, although if you didn’t download the package source code earlier it can take anywhere between 9 and 12 hours, which, let’s face it, is a long time. But if you are using a decent build host with plenty of RAM and a beefy CPU then it can be a much quicker process. Also don’t forget if anything were to go wrong or you wanted to compile again for a different device or whatever then it will be a much quicker process the second time around so don’t worry too much about messing up.
So to start the build type this into the terminal and hit enter (Remember to change the command depending on what device you are compiling for):
PROJECT=S805 SYSTEM=HD18Q ARCH=arm make image
So again, we are going to be waiting a while depending on your machine so I would recommend leaving your build host alone while this process completes as we don’t want to bog down the CPU and use even more RAM by multi-tasking while LibreELEC is compiling as it will just slow things down.
If everything goes well the completed image will be located in the ~/LibreELEC.tv/target/ directory, and will be a .img.gz archive. (If there were any errors, the terminal will inform you of them before stopping the process)
If you get any random errors the first thing I would suggest is ‘cleaning’ the built sources by typing:
PROJECT=S805 ARCH=arm make clean
This will clear up all the sources that were compiled in the first build and then you can just repeat Step 9 and try again. If you still have issues just leave us a comment on this post or in the forums and we will try and assist you as best we can.
So here’s a recap of what you have (hopefully) achieved over the course of this tutorial:
- Set up and configured our ‘Build Host’ for compiling
- Pulled LibreELEC source code from GitHub
- Set what version of LibreELEC we wished to compile
- Downloaded the package source code
- Compiled a working LibreELEC image ready for installation
So there you have it, you have learned how to successfully cross-compile an entire operating system for your TV Box. It seems like a daunting task when you first think about it, especially if you are a beginner with this sort of thing. If you want to learn how to install your new image then please refer to our dual booting tutorial here. Please let me know in the comments or in the forums what you thought of this tutorial and if it worked out properly for you.
If there is enough interest in this tutorial then I plan to create a short series of tutorials that will all tie together, such as making a companion video for this guide and even a tutorial on how to modify some source code in order to personalize your LibreELEC images with things like custom Kodi builds, add-ons etc.
Accompanying Video Tutorial Can Be Seen Below
Until next time