back to the beginning

Building and installing LineageOS 15.1 on Essential PH-1

Last updated: 2018-11-27

LineageOS is an alternate version of the Android operating system for your phone. Rather than building it yourself the first time, I recommend you use the image provided by invisblek. However, his image includes Google apps by default. If you want to experience life without Google's apps you will have to build LineageOS yourself. If you do choose to build it yourself, you can also install the Google apps at any time.

Moving from stock Android to LineageOS or back again will require restoring your phone to factory settings. YOU WILL LOSE ALL YOUR DATA. YOU MUST COPY ANYTHING YOU VALUE OFF OF THE PHONE.

LineageOS 15.1 is still in development and some features are not working.

LineageOS features still not working (most notable for me):


To flash back to stock:

If you want to remove LineageOS and return to stock Android follow the instructions here:

Essential stock firmware and rom dumps


Required resources:

A quality USB cable and not the one provided with your phone.

Official TWRP 3.2.3-0 for Essential PH-1

This will take a lot of disk space. A repo sync with all the other tools that get downloaded will require 180 GB space by the time you are finished building.

Websites for information and resources:

LineageOS 15.1 for the Essential PH-1 (mata) invisiblek's installation notes

Prerequisites and required software:

All instructions assume you are running Linux. These instructions are for Ubuntu with minimum version of 16.04.

  1. Prepare build environment
  2. You will need to install proper ADB (Android Debugging Bridge) tools for your platform. For Ubuntu 18.04 this is as simple as running

    sudo apt install adb

    If your distribution provides out of date tools you can obtain them directly from Google.

    Install the tools from Google:

    unzip platform-tools-latest-linux.zip -d ~

    To add these tools to your path add the following to ~/.profile

    # add Android SDK platform tools to path
    if [ -d "$HOME/platform-tools" ] ; then
    PATH="$HOME/platform-tools:$PATH"
    fi

    Run the following command to update your shell:

    source ~/.profile

  3. Install the build tools
  4. Note that with Ubuntu 18.04 libesd0-dev is not available. Just delete the last item and install the rest of the tools.

    sudo apt install bc bison build-essential ccache curl flex g++-multilib gcc-multilib git gnupg gperf imagemagick lib32ncurses5-dev lib32readline-dev lib32z1-dev liblz4-tool libncurses5-dev libsdl1.2-dev libssl-dev libwxgtk3.0-dev libxml2 libxml2-utils lzop pngcrush rsync schedtool squashfs-tools xsltproc zip zlib1g-dev libesd0-dev

    Also install a Java Development Kit

    sudo apt install openjdk-8-jdk

  5. Download the git-repo tool
  6. mkdir -p ~/bin
    curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
    chmod a+x ~/bin/repo

  7. Download the LineageOS repository
  8. Note: You can use a base directory somewhere else. Mine is on a 240 GB SSD that I connect through a USB 3 enclosure.

    mkdir -p ~/android/lineage
    cd ~/android/lineage
    repo init -u https://github.com/LineageOS/android.git -b lineage-15.1
    repo sync
    source build/envsetup.sh
    breakfast mata

    Note: mata is the code name for the Essential PH-1. If you see other tutorials for building LineageOS you can follow their instructions but use mata where necessary. I suggest you look up another tutorial since I am leaving out instructions on using ccache. Apparently it can speed up your build but I did not want to commit even more disk space to the project. My desktop has 32 GB of ram and I felt the build was fast enough.

  9. Configure jack and root
  10. jack is required for building android 8.1 and LineageOS 15.1.

    Run the following command from your shell and add it to ~/.bashrc so it is set up for future use.

    export ANDROID_JACK_VM_ARGS="-Dfile.encoding=UTF-8 -XX:+TieredCompilation -Xmx4G"

    If you want to build root into your LineageOS image then also run the following and also add it to ~./bashrc

    export WITH_SU=true
  11. Add the Muppets
  12. We will use the muppets repository to bring in all the extra bits required for the mata build rather than obtain them from the phone itself.

    Add the following bit to the file located at ~/android/lineage/.repo/local_manifests/roomservice.xml

    <project name="TheMuppets/proprietary_vendor_essential" path="vendor/essential" />

Build LineageOS:

  1. Build commands:
  2. In the future consider all of the above are things you don't have to do next time. Anytime you want to build just start here. You only have to run repo sync when you want to make sure you have the lastest code. We need to run it now to pull stuff in from the Muppets.

    cd ~/android/lineage
    repo sync (on rebuilding I received error; see below)
    croot
    brunch mata

    repo sync error: Because of changes upstream, I had to rebuild using "repo sync --force-sync" (you will see this instructed in the output from the build), and "source build/envsetup.sh" before I could "croot".

  3. Installation files
  4. Once you manage an error free build you can quickly go to the directory where your LineageOS image is located by typing this:cd $OUT cd $OUT

    In the folder there is is a file named lineage-15.1-20180601-UNOFFICIAL-mata.zip. The name will be based on the date you built LineageOS.

    There is also a boot.img that you can use to install Magisk if you want to gain root that way at a later time.


Installing LineageOS

Items labeled FIRST TIME are also required for first time installations of LineageOS. If you are upgrading then do the items marked UPGRADE.

  1. FIRST TIME: Unlock the boot loader
  2. Installing LineageOS will require you have an unlocked boot loader. You only have to do this the first time.

  3. FIRST TIME: Wipe phone
  4. If you are coming from stock you will have to wipe your phone with this command (it will ensure the phone is erased):

    sudo fastboot -w

  5. UPGRADE: Turn on adb debugging
  6. Settings - System - Developer options - USB debugging

    Connect your phone to your computer with a USB cable and give your computer permission to do USB debugging with your phone.

  7. UPGRADE: Disable lock screen code
  8. Settings - Security - Screen Lock - None

    If you forget to unlock your phone before you do the next steps you will have to reboot your phone and turn off the lock screen.

  9. Reboot to recovery
  10. Type the following in your shell and wait for the phone to restart (your phone may prompt for permission):

    sudo adb reboot-bootloader

    To verify you can access the phone type:

    sudo fastboot devices

    If you see a device with the label "unathorized" you forgot to give your computer permission to access your phone through the adb interface.

  11. UPGRADE: Switch slots
  12. If you are upgrading from a previous build of LineageOS then you can install to the second slot. If something goes wrong you will still be able to boot into your old version. sudo fastboot getvar current-slot
    sudo fastboot set_active other

  13. Install TWRP
  14. TWRP gets written to the boot partition.

    sudo fastboot flash boot twrp-3.2.3-0-mata.img
    sudo fastboot reboot

    After a few moments TWRP will start.

  15. Push images to device
  16. We need to push the OS image to the phone (the exact filename may vary):

    adb push lineage-15.1-date-UNOFFICIAL-mata.zip /sdcard/

    This new version of TWRP can fail to allow touch input. If something goes wrong and you need to restart the phone depress the volume down button while the phone reboots.

    You can just flash Lineage to it:

    (NOTE: I had to unplug/replug my phone before each of these commands on upgrading. Hopefully digitizer works properly later.)

    adb shell twrp sideload
    adb sideload lineage-15.1-date-UNOFFICIAL-mata.zip

    Otherwise there is a way to get digitizer to work at

    If you want to root with Magisk you also need to push Magisk to the phone as above but with the correct filename version.

    If you want to install gapps then download and push them to the phone as well.

  17. Flash desired images (you can only do this if you were able to push the image to the /sdcard/ and the digitizer is working)
  18. Once TWRP starts slide the switch and press the INSTALL button.

    Note: TWRP has a button to select if you want flash an .img or a .zip file. You have to use it to see the boot.img file and later the Magisk file on the /sdcard partion of your phone.

    Note: In TWRP you need to use the back button as well as the interface buttons for navigation.

    Use TWRP to select and flash the LineageOS image.

    Use TWRP to select and install gapps if desired.

    Use TWRP to select and install Magisk if desired.

  19. Reboot the phone without installing TWRP
  20. There is no need to have TWRP installed as an app on your phone.

    If digitizer is working you can use on screen commands to reboot. Otherwise "adb reboot bootloader" and press the power button to start the phone.

  21. FIRST TIME: Boot loop
  22. If you phone boot loops or takes more than a few minutes to start into LineageOS then boot to recovery and reset to factory.

    To boot to recovery hold the volume up button down until the recovery menu appears. Use the volume buttons to select factory reset and the power button to execute. This will reset the phone and it will start properly.

  23. Disable USB debugging
  24. Settings - System - Developer options - USB debugging

    It is safest to keep USB debugging disabled until you need it. Go to the developer options menu in settings and disable it.

  25. Re-enable your lockscreen
  26. Settings - Security - Screen Lock

back to the beginning