Fairphone 5 - Build Instructions

Let’s get started on creating your very own Fairphone OS build! As Fairphone OS is largely based on the Android Open Source Project (AOSP), the steps to build are quite similar to building AOSP. So you might find the resources on the AOSP website helpful.

My code is compiling

Note

For browsing or downloading our ODM source tree, please refer to Fairphone 5 - ODM Android Source Code. You will also find more information about our different Fairphone 5 source trees there.

For building only the kernel, please refer to Fairphone 5 - Kernel Source Code.

Prepare the Build Environment

Before actually getting and building your own version of Fairphone OS, you should make sure that your system is properly set up to build it. You can follow this handy guide at the AOSP project site to set up your build environment.

Also please note that you will need about 500 GB of free disk space for sources and build output. For RAM we recommend to have at least 32 GB available.

Getting the Source

Now that your system is ready to build Fairphone OS, it’s time to download the source.

Installing repo

As Fairphone OS consists of many subprojects, we will use the repo tool to download the source code. It is very handy to install repo in a user local bin directory.

To install repo, follow the instructions on the AOSP website.

Register an account

We recommend that you register an account on our Gerrit to make contributions easier. Click on the register link using OpenID and upload an SSH key into your Gerrit account.

Initializing the repo and downloading the source tree

Fairphone 5 makes use of Qualcomm’s single system image (QSSI), thus two source trees are needed: QSSI (higher level Android system) and target (most of the device specific code, including the Linux kernel).

The following commands initialize the repo manifest for the Android 14 QSSI and target trees.

For Android 13, use the odm/public-build/13/fp5 branch instead.

mkdir fairphone_os && cd fairphone_os

mkdir qssi && cd qssi
repo init -u ssh://gerrit-public.fairphone.software:29418/manifest -b refs/heads/odm/public-build/14/fp5 -m qssi.xml
# or for http based access
# repo init -u https://gerrit-public.fairphone.software/manifest -b refs/heads/odm/public-build/14/fp5 -m qssi.xml
repo sync --detach --current-branch --no-tags
cd ..

mkdir target && cd target
repo init -u ssh://gerrit-public.fairphone.software:29418/manifest -b refs/heads/odm/public-build/14/fp5 -m target.xml
# or for http based access
# repo init -u https://gerrit-public.fairphone.software/manifest -b refs/heads/odm/public-build/14/fp5 -m target.xml
repo sync --detach --current-branch --no-tags

The first time you’ll do that it will take quite some time.

Getting the Binary Components

Unfortunately, not all components of Fairphone OS can be released as open source.

After downloading the Android source tree, you will need to manually download and extract the proprietary binary blobs. To download the blobs, please refer to Fairphone 5 - Binary Blobs Package.

After download, extract them in the source tree. There are separate blobs packages for QSSI vs. target trees.

# Insert the paths of the downloaded archives here.
cd fairphone_os
tar -xf .../path/to/FP5-QSSI-*-blobs.tgz
tar -xf .../path/to/FP5-target-*-blobs.tgz
# Unpack into the expected location in your Android source tree.
# Read and accept the license by pressing <y>.
./FP5-QSSI-*-blobs.sh --target qssi/device/fairphone/fp5-proprietary
./FP5-target-*-blobs.sh --target target/device/fairphone/fp5-proprietary

Build!

Finally, you have everything set to initiate the build process.

For building any Android version, run the following commands to initialize the build environment and trigger the builds.

Note: Make sure to use separate shells for the two trees. Keeping the envsetup.sh and lunch environment from one tree and then switching over to the other would break the build. To avoid this, for example as listed below we can open a new bash shell for every build and exit when the build is done.

bash
cd fairphone_os/qssi
. build/envsetup.sh
lunch qssi-userdebug
m
exit

bash
cd fairphone_os/target
. build/envsetup.sh
lunch fp5-userdebug
m
exit

Now you can watch some cat videos on YouTube until the compilation is done.

Flash!

Did compilation succeed without errors? That’s awesome, because now it’s time to flash your Fairphone 5.

You’ve build the complete Android software stack including Linux kernel. However, some firmware files are not part of the Android sources (“modem” and others). Therefore, it is useful to flash our latest official software release first and then flash your own software on top of it. You can do so by following the instructions on the support page. After downloading and extracting the factory package, edit the flashing script for your platform by setting AUTO_REBOOT and INTEGRITY_CHECK to false and run the flashing script.

After the script completes you can flash your build by running:

cd fairphone_os

fastboot --set-active=a

fastboot flash boot target/out/target/product/lahaina/boot.img
fastboot flash dtbo target/out/target/product/lahaina/dtbo.img
fastboot flash vendor_boot target/out/target/product/lahaina/vendor_boot.img
fastboot --disable-verification flash vbmeta target/out/target/product/lahaina/vbmeta.img

fastboot reboot fastboot
fastboot erase system && fastboot erase system_ext && fastboot erase product
fastboot flash system qssi/out/target/product/qssi/system.img
fastboot flash system_ext qssi/out/target/product/qssi/system_ext.img
fastboot flash product qssi/out/target/product/qssi/product.img
fastboot flash odm target/out/target/product/lahaina/odm.img
fastboot flash vendor target/out/target/product/lahaina/vendor.img
fastboot flash vbmeta_system qssi/out/target/product/qssi/vbmeta_system.img
fastboot reboot