Installation instructions can be found below as well.
These instructions will also likely work for the Pixel 3a XL aka bonito with some modification.
There are two ways to build, the easy way and the hard way. The easy way uses a docker image as the build environment and applies functionality patches and optionally patches for microg support. This is the recommend way as the build dependency versions your linux distro provides may cause unexpected issues.
The hard way requires you to set up your own build environment and apply the patches manually. You may want to choose this route if you want to familiarize yourself with AOSP, lineaseos, and the build process. If you choose this route I suggest using Debian Stretch.
At the bottom of this page are some troubleshooting and debug instructions
Required for both the easy and hard ways the platform tools provided by distros is often wayyyy out of date. We have to grab the binaries ourselves.
get adb and fastboot from google https://dl.google.com/android/repository/platform-tools-latest-linux.zip
cd to your home directory, and extract them: unzip platform-tools-latest-linux.zip -d ~
and add them to your path by adding the following to your ~/.profile
# add Android SDK platform tools to path
if [ -d "$HOME/platform-tools" ] ; then
PATH="$HOME/platform-tools:$PATH"
fi
and run source ~/.profile
This uses https://github.com/SolidHal/docker-lineage-cicd/ which automates the build.
Install docker for your OS. Instructions can be found on the docker website.
clone a copy of the repo
cd ~/
mkdir lineage-docker-solidhal
cd lineage-docker-solidhal
git clone https://github.com/SolidHal/docker-lineage-cicd.git .
and build the docker image
docker build --tag solidhal/docker-lineage-cicd .
Now clone a copy of this repo if you haven't already
cd ~/
mkdir lineage-sargo
cd lineage-sargo
git clone https://github.com/SolidHal/Build-lineageos-sargo.git .
make the directories we will pass into the docker:
mkdir src zips logs ccache
and the a directory for your signing keys. If you already have these, you can skip this step
mkdir ~/.android-certs
now we can build.
build_sargo.sh builds lineageos with support for signature spoofing and other location providers both of which are required for microg and unifiedNLP support.
It also includes the f-droid privileged extension, which allows f-droid to be used without the "unknown sources" permission and allows for a cleaner app install process.
The script before.sh in userscripts applies a handful of patches to fix a bootloop, improve battery life, and fix bluetooth
If all of that sounds good, you can build by running
./build_sargo.sh
this will take over an hour most likely, especially the first time.
you can watch the progress by reading the logs in logs.
The repo log is the process of syncing all of the repos. When that is complete, a second log in the logs/sargo directory will track the build progress.
when the build is complete, you can find the lineageos zip and the boot.img in zips/sargo
Install instructions can be found farther down this readme
if you don't have any interest in microg, you can remove SIGNATURE_SPOOFING and SUPPORT_UNIFIEDNLP.
Additional environment variables can be added to the script to further customize the build. See https://github.com/SolidHal/docker-lineage-cicd/ for a list
This is more difficult, as you have to setup the environment yourself. It is also less reliable as build dependencies can cause unknown issues depending on the version your distro provides.
Basing these instructions off of https://wiki.lineageos.org/devices/sailfish/build with modifications for the pixel 3a aka sargo
Note that while the pixel 3a is codenamed sargo, it is very closely related to the pixel 3a XL codenamed bonito. Because of this,
most of the files we care about are actually under bonito directories. This is important to keep in mind if you want to modify this process.
In my experience, over 16GB of RAM + swap is needed to build. I have 16GB of ram but my first build failed because I only had 2GB of swap :( If you get a random failure in the build process, because something was "killed" low memeory is likely why I needed over 8GB of swap, ended up using 16GB
Guides all over the internet can tell you how to grow your swap, but to start you can check it with:
free -h
You also need about 150-200GB of free disk space.
install the repo command
curl https://storage.googleapis.com/git-repo-downloads/repo > /usr/bin/repo
chmod a+x /usr/bin/repo
make and enter a desired source directory
cd ~/android/lineage
repo init -u https://github.com/LineageOS/android.git -b lineage-17.1
and now let repo grab all of the sources
repo sync
if that fails, you may have to run the following to clear any conflicts:
repo sync --force-sync
now download the device specific config and kernel:
source build/envsetup.sh
breakfast sargo
these are unfortunately required, there is no android phone without some proprietary blobs. we have to specifiy them explicitly because they are not provided by lineageos for potential copyright issues.
add the following to .repo/local_manifests/muppets.xml
<?xml version="1.0" encoding="UTF-8"?>
<manifest>
<project name="TheMuppets/proprietary_vendor_google" path="vendor/google" remote="github" />
</manifest>
and run repo sync
to get the proprietary blobs.
now to patch in signature spoofing and add the fdroid privileged extension:
include the fdroid privileged extension in the build. This combined with the fdroid.apk will allow us to securely install microg from the supported fdroid repo. information on this process can be found here: https://gitlab.com/fdroid/privileged-extension/#f-droid-privileged-extension
make a file called fdroid_extension.xml in .repo/local_manifests and add the following to it:
<?xml version="1.0" encoding="UTF-8"?>
<manifest>
<remote name="fdroid" fetch="https://gitlab.com/fdroid/" />
<project path="packages/apps/F-DroidPrivilegedExtension"
name="privileged-extension.git" remote="fdroid"
revision="refs/tags/0.2.11" />
</manifest>
note that when fdroid privileged extension is updated the revision (0.2.11) will need to be updated to build the new version into lineageos
now run repo sync again to pull in the fdroid privileged extension files
Next to actually include it in the build, add F-DroidPrivilegedExtension to the PRODUCT_PACKAGES list in device/google/bonito/device-common.mk
PRODUCT_PACKAGES += \
F-DroidPrivilegedExtension \
after bootup, we can then install fdroid, and then installing the microg apks from there. This is the "supported" method of microg inclusion. This also provides the benefit of having a microg-free ROM if desired.
NOTE: if you run repo sync after this point, you will have to re apply the patches
_Patches can be found in the following places Signature Spoofing: _
to take advantage of microg, we need to allow signature spoofing.
The patch can be found here https://github.com/SolidHal/docker-lineage-cicd/tree/master/src/signature_spoofing_patches
cd frameworks/base/core
patch -p1 < sig_spoofing_patch/android_frameworks_base-Q.patch
The patch can be found here https://github.com/SolidHal/docker-lineage-cicd/tree/master/src/location_services_patches
cd frameworks/base/core`
patch -p1 < location_patch/android_frameworks_base-Q.patch
there is one patch to prevent a bootloop that has not yet been merged. Lets cherry pick it now.
cd kernel/google/msm-4.9
git fetch "https://github.com/LineageOS/android_kernel_google_msm-4.9" refs/changes/27/263927/2 && git cherry-pick FETCH_HEAD
bluetooth is currently broken due to hal_bluetooth_default lacking some permissions, cherry pick the patch. This may get merged, making this step unnecessary:
cd device/google/bonito
git fetch "https://github.com/LineageOS/android_device_google_bonito" refs/changes/45/268545/1 && git cherry-pick FETCH_HEAD
this may also get merged at some point
cd kernel/google/msm-4.9
git fetch "https://github.com/LineageOS/android_kernel_google_msm-4.9" refs/changes/40/263940/1 && git cherry-pick FETCH_HEAD
Now we can get back to building.
setup ccache, I highly recommend this. Android takes a very long time to build (>1 hour). This greatly speeds up subsequent builds:
run:
export USE_CCACHE=1
and add that line to your ~/.bashrc
and choose a size for your ccache. The wiki recommends 50G but I went with 75G to be safe.
ccache -M 75G
And finally, start the build. This will take a while.
croot
brunch sargo
you can find the build results in $OUT which is
croot
cd out/target/product/sargo
inside you'll find the lineage-17.1-XXXXXXXX-UNOFFICIAL-sargo.zip
Plug your phone into you computer, power it off, and hold down power + volume down to boot into the bootloader
make sure your bootloader is unlocked. You can unlock it by running:
fastboot flashing unlock
accept the bootloader unlock, and reboot into bootloader
Now to flash the recovery image we built, which is part of the boot.img
for the hard way, the boot.img is located in ``out/target/product/sargofor the easy way it is along with your lineageos image inzips`
flash boot.img by running:
fastboot flash boot boot.img
reboot into the bootloader and boot into recovery by using volume up or volume down in the bootloader
Do a factory wipe of user data to avoid any issues.
Next choose Apply update from adb
Locate your built lineageos.zip and sideload it
adb sideload lineage-17.1*.zip
it will get stuck at 47% for a bit, just give it a few minutes When it is done, you will be back at the android recovery screen choose "Reboot System Now"
Right now you need an alpha version of fdroid to function with the privileged extension on Android 10
get version 1.8-alpha1 or newer
Once installed, add the microg fdroid repo. A quick search will lead you to it.
Install microg services core, microg services framework proxy, fakestore, and a unified nlp backend.
I found for installing microg services, I still had to give fdroid unknown sources permission. This doesn't seem to happen with any other app from fdroid.
Open the microg app, give it the permissions it requests and then in the self check tap "system grants signature spoofing permission" and grant it signature spoofing
Now we have to grant unified nlp location permissions. This is done easily from adb root
enable adb and root adb in developer options, plug in your phone, and run:
adb root
adb shell
then run the following in the adb shell
pm grant com.google.android.gms android.permission.ACCESS_FINE_LOCATION
pm grant com.google.android.gms android.permission.ACCESS_COARSE_LOCATION
Finally, grant the fakestore signature spoofing permissions
pm grant com.android.vending android.permission.FAKE_PACKAGE_SIGNATURE
and reboot your phone you can now disable developer options
Further troubleshooting information can be found here https://old.reddit.com/r/MicroG/wiki/issues
useful for debugging bootloops, provides access to adb functions like adb logcat right away.
TODO
to build a debug eng image on lineageos do the following:
TARGET_BUILD_TYPE=debug breakfast sargo eng
TARGET_BUILD_TYPE=debug brunch sargo eng
sideload the lineage-17.1-XXXXXXXX-UNOFFICIAL-sargo.zip like a usual build
sargo is an A/B device, so you can flash either slot_a or slot_b by adding _b to the partition
example for boot:
fastboot flash boot_a boot.img
fastboot flash boot_b boot.img
at some point, I got stuck where I couldn't get into recovery from the bootloader.
to get out I took the following from out/target/product/sargo and flashed them.
flash boot.img, dtbo.img, vbmeta.img
fastboot flash boot boot.img
fastboot flash dtbo dtbo.img
fastboot flash vbmeta vbmeta.img
fastboot reboot bootloader
then use the volume keys to choose "recovery" and boot to recovery
wipe the data and system partitions
To test if selinux is at fault, you can apply the selinux-permissive.patch, build, and see if it is fixed
check if selinux is permissive or enforcing:
adb root
adb shell
getenforce
in permissive mode, it will log the requests that would be denied if enforcing you can see all of the requests the sepolicy has denied by running
adb shell dmesg | grep denied
find the policy file, which end in .te in device/<manufacturer>/<board>/sepolicy or sepolicy-lineage
you can used the old audit2allow.perl, which will turn the denieds into policies to add the the policy file
get the perl script:
wget https://github.com/OpenDarwin-CVS/SEDarwin/raw/master/sedarwin7/src/sedarwin/policycoreutils/audit2allow/audit2allow.perl
give it execution permissions:
sudo chmod +x audit2allow.perl
and then run it like this:
adb shell dmesg | grep denied | perl ~/android/audit2allow.perl
this page has some information, but some of it is outdated right now https://source.android.com/security/selinux/implement
the latest factory image for the 3a from here https://developers.google.com/android/images
extract and run flash-all.sh
tried to setup debug using somgthing like this: https://groups.google.com/forum/#!topic/mozilla.dev.b2g/epQ6qhIFZ50 unpacking the boot.img with with this https://github.com/xiaolu/mkbootimg_tools but that didn't work https://source.android.com/compatibility/vts/vts-on-gsi