Build for Pinephone
How to Build LuneOS for Pinephone (codename: Pinephone)
This Build LuneOS build walkthrough is auto-generated specifically for the Pinephone based on the device template at Template:device_Pinephone. You can find similar build instructions for every officially supported device. See here for more info.
These instructions will hopefully assist you to start with a stock Pinephone, unlock the bootloader (if necessary), and then download the required tools as well as the very latest source code for LuneOS (based on LG's Open webOS/webOS OSE operating system). Using these, you can build LuneOS from source code , and then install it to your device.
It is difficult to say how much experience is necessary to follow these instructions. While this guide is certainly not for the very very very beginner, these steps aren't too hard to follow either. Basic *nix knowledge will help and you should have no difficulties in following the instructions. Others might struggle with the most basic operations. People have different experiences, backgrounds etc therefore, it might be a good idea to read through the instructions to make sure you're comfortable with the steps.
All risk are for yourself, but also the benefits! It’s pretty satisfying to boot into a fresh operating system that you compiled yourself at home :) And once you’re an LuneOS-building expert, there will be no more need to wait for “nightly” builds from anyone. You can build it yourself from the source code to running it on a device. Now you can add features, fix bugs, add a translation or to build a new app or start porting to a new device! So many new possibilities!
What you will need
- A relatively recent computer (Linux, OS X, or Windows) with a reasonable amount of RAM (6GB or more is preferred for building WebKit) and about 70 GB of free storage. The less RAM you have, the longer
the build will take. Using SSDs results in faster builds than traditional hard drives.
- A micro USB cable (or another cable that can connect your device to your computer).
- A decent Internet connection & reliable power.
- Some familiarity with basic Linux operations and terminology. It would help if you’ve installed custom roms on other devices and are familiar with what a recovery image such as ClockworkMod is. It may also be useful to know some basic command line concepts such as
cdfor “change directory”, the concept of directory hierarchies, that in Linux they are separated by
If you are not used to using Linux, this is a good opportunity to learn. It’s free just download and run a virtual machine (VM) such as VirtualBox, then install a Linux distribution such as Ubuntu. This has been tested on Gentoo (shr-chroot) and Ubuntu-12.04/13.04/14.04/15.10/16.04 64 bits (amd64) and should work almost everywhere where valid toolchain is provided.
Create the virtual machine with at least 6GB of RAM (more RAM makes builds faster). Create a "dynamically allocated" virtual disk at least 70GB in size. If you have four processor cores in your host machine, create a VM with 2 CPUs, if six cores, a VM with 4 CPUs, and so forth.
You want to use a 64-bit version of Linux.
Using a VM allows Linux to run as a guest inside your host computer; a computer in a computer. If you hate Linux for whatever reason, you can always just uninstall and delete the whole thing. (You can find instruction by "Install Ubuntu inside VirtualBox on Windows" or look here for instructions)
If the window for the guest Linux is only 640x480, install "Guest Additions" from the Devices menu. Then, in the VM, click on System Settings, then Displays. Select a better display size.
Setup the build environment
Before you can build, you will need some tools. If you try to build without them, bitbake will fail a sanity check and tell you about what's missing, but not really how to get the missing pieces.
If your distribution is Ubuntu, you need to be running the bash shell. You can be sure you are running this shell by entering the following command and selecting "No" at the prompt:
$ sudo dpkg-reconfigure dash
The essential and graphical support packages you need for a supported Ubuntu or Debian distribution are shown in the following commands:
$ curl -sL https://deb.nodesource.com/setup_4.x | sudo bash - $ sudo apt-get install gawk wget git-core diffstat unzip texinfo \ build-essential chrpath libsdl1.2-dev xterm nodejs bzr
(Recently, building on 64-bit Ubuntu 16.04 also required apt-get install gcc-multilib g++-multilib.)
For other Linux distributions please have a look at the Yocto Project Quick Start guide.
The steps below will setup your build environment for a development build. If you want to build the latest release use ENV_NAME=stable instead but keep in mind that all new developed features need to go into testing first before they are submitted to stable.
$ cd into-your-build-directory $ mkdir webos-ports-env && cd webos-ports-env $ export ENV_NAME=testing $ wget https://raw.github.com/webOS-ports/webos-ports-setup/$ENV_NAME/Makefile $ make setup-webos-ports
This has been tested on Gentoo (shr-chroot) and Ubuntu-12.04/13.04/14.04/15.10/16.04 amd64/x64 and should work almost everywhere where valid toolchain is provided.
You need a lot of RAM to link QtWebEngine, make sure you have at least 6GB (it's OK when some of that is swap, because it's used only for short part of build). QtWebEngine needs so much ram to link because it's linking with debug symbols (huge files) which are stripped later in do_package after creating -dbg packages.
Make sure you're _not_ root, as the build will fail. If you SU in the middle, don't forget to set up env afresh (. setup-env)
To configure to build (notice '.' which is actually bash 'source' command):
$ cd into-your-build-directory/webos-ports-env/webos-ports $ . setup-env
To update metadata
# go one level up to the webos-ports-env dir $ cd .. $ make update # or if it shows warning about different bblayers.conf or layers.txt $ make update-conffiles && make update # you can also add UPDATE_CONFFILES_ENABLED = 1 to config.mk # if you never want to have any uncommited changes in your checkouts RESET_ENABLED = 1 in config.mk
# go back to the webos-ports dir to continue with the build process $ cd webos-ports
To build the luneos-dev-image for a device (pinephone):
$ MACHINE=pinephone bb luneos-dev-package
After the build completes, you will find your image in <build env>/tmp-glibc/deploy/images/pinephone/
Clean up the work directory
If you run out of disk space during a build, run the following command from the webos-ports directory, then build again:
$ rm -rf tmp-glibc # If you're building a version before Black tie the folder is called tmp-eglibc
This removes all build things but OE luckily has a copy of every build result in a cache folder called sstate-cache which you should keep to let OE quickly rebuild everything from the cache instead to do it from scratch (next build will be quite faster).
If you run out of space because of a too large sstate-cache folder you can clean it up to contain only the results for the latest component versions with the following command:
$ openembedded-core/scripts/sstate-cache-management.sh -L --cache-dir=sstate-cache -d -y
Adding Swap Space
To speed up the build, you can add extra 2GB of swap file like this:
$ dd if=/dev/zero of=swap_2gb.img bs=1024k count=2048 $ mkswap swap_2gb.img $ sudo swapon swap_2gb.img
If you want it permanently add it to your /etc/fstab. If the swap file is /var/swap_2gb.img, add the following lines to /etc/fstab:
# additional swap /var/swap_2gb.img swap swap sw 0 0
Speeding up the build
Bitbake automatically uses all of the processors assigned to your virtual machine and gives good result on a variety of systems. You can tune bitbake for modest improvements in build speed, but the correct parameters depend on whether builds are limited by processors, disk I/O, or network I/O. Edit webos-ports/conf/local.conf and uncomment the PARALLEL_MAKE and BB_NUMBER_THREADS lines.
PARALLEL_MAKE = "-j 4" BB_NUMBER_THREADS = "4"
Installing and running the image
Assuming the build completed without error (it will be obvious when it finishes).
Once you have built the image, you'll likely want to install it and run it on your Pinephone. See Testing LuneOS for Pinephone for further details on that process.
Remember: The file you want to sideload on your device is <build env>/tmp-glibc/deploy/images/pinephone/luneos-dev-package-pinephone.zip
If you also need the kernel, it's in <build env>/tmp-glibc/deploy/images/pinephone/uImage
Success! And next steps?
You've done it! Welcome to the club of people who can build their operating system from the source code! Hopefully you enjoyed the experience and are inspired to do more!
To rebuild after the source code has changed on GitHub,
- If you've logged in again to the virtual machine, run setup-env, as above
- Pull the latest code from GitHub by running
make update, as above
- Build, as above
To get assistance
- #webos-ports - Our IRC Channel on the Freenode Network.