Building LineageOS GSI on Standard Targets

Starting with version 23.0 (Android 16 QPR0), LineageOS developers added official build targets that simplify GSI compilation without needing third-party patches from TrebleDroid. This also applies to any custom ROMs based on LineageOS source code.

System Requirements

RAM: Minimum 32 GB (64 GB+ recommended)
Storage: SSD with at least 350 GB free space
OS: Debian or Arch Linux based distribution
Source: LineageOS-based Android source tree
Network: Fast and stable internet connection for repo sync

1. Environment Setup

Debian / Ubuntu Environment Setup

Configure Sudo Privileges

Switch to root and grant sudo permissions to your user account:

su
sudo adduser your_username sudo

Reboot your system to apply group permission changes.

Install Build Dependencies

On Debian and Ubuntu systems, use the OrangeFox environment setup script:

cd ~
sudo apt install git aria2 -y
git clone https://gitlab.com/OrangeFox/misc/scripts
cd scripts
sudo bash setup/android_build_env.sh

Configure ZRAM

Install systemd-zram-generator:

sudo apt install systemd-zram-generator

Edit the configuration file /etc/systemd/zram-generator.conf:

[zram0]
zram-size = ram
compression-algorithm = zstd

(Note: Ubuntu 24.04 may require Linux Kernel 6.12 or newer).

Arch Linux Environment Setup

Install Build Dependencies

On Arch Linux, install lineageos-devel from the AUR using yay:

sudo pacman -S --needed git base-devel && git clone https://aur.archlinux.org/yay-bin.git && cd yay-bin && makepkg -si
yay -Sy lineageos-devel

Configure ZRAM

Install zram-generator and configure /etc/systemd/zram-generator.conf:

[zram0]
zram-size = ram
compression-algorithm = zstd

Shell Setup (ZSH & Oh My Zsh)

It is highly recommended to configure ZSH with auto-suggestions for terminal productivity:

Install zsh using your package manager:

sudo apt install zsh   # Debian / Ubuntu
# or
yay -Sy zsh            # Arch Linux

Set ZSH as your default shell:
```
chsh -s $(which zsh)
```

Install Oh My Zsh:

sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"
cp ~/.oh-my-zsh/templates/zshrc.zsh-template ~/.zshrc

Install syntax highlighting and auto-suggestions plugins:

git clone https://github.com/zsh-users/zsh-syntax-highlighting.git "$HOME/.zsh-syntax-highlighting" --depth 1
echo "source $HOME/.zsh-syntax-highlighting/zsh-syntax-highlighting.zsh" >> "$HOME/.zshrc"

git clone https://github.com/zsh-users/zsh-autosuggestions ~/.oh-my-zsh/custom/plugins/zsh-autosuggestions

Edit ~/.zshrc: Set theme to xiong-chiamiov-plus and add zsh-autosuggestions to plugins array:
```
ZSH_THEME="xiong-chiamiov-plus"
plugins=(git zsh-autosuggestions)
```
Reload configuration:
```
source ~/.zshrc
```

2. Syncing Source Code

Create a directory for your ROM source code:

mkdir rom
cd rom
git lfs install

Initialize the LineageOS repository (for example, LineageOS 23.2):

repo init -u https://github.com/LineageOS/android.git -b lineage-23.2 --git-lfs

Synchronize the source code:

repo sync --force-sync --optimized-fetch --no-tags --no-clone-bundle --prune -j4

3. Google Certification & GApps Integration

Fix Play Integrity / Google Certification

Edit vendor/lineage/build/target/product/lineage_gsi_arm64.mk in your source tree:

Locate:

PRODUCT_NAME := lineage_gsi_arm64
PRODUCT_DEVICE := generic_arm64

Add the following properties:

PRODUCT_BRAND := google
PRODUCT_SYSTEM_BRAND := google
PRODUCT_MODEL := Generic System

Include MindTheGApps

To build with GApps included, add the following line to lineage_gsi_arm64.mk:

$(call inherit-product-if-exists, vendor/gapps/arm64/arm64-vendor.mk)

Then clone the MindTheGApps repository into vendor/gapps:

git clone https://gitlab.com/MindTheGapps/vendor_gapps.git vendor/gapps -b baklava --depth=1

4. EROFS Filesystem & ADB Fixes

To build GSI with the EROFS filesystem, add the following lines to vendor/lineage/build/target/product/lineage_gsi_arm64.mk:

GSI_FILE_SYSTEM_TYPE := erofs
BOARD_EROFS_COMPRESSOR := lz4hc,9

If duplicate adb secure rules cause build failures, set:

WITH_ADB_INSECURE := true

5. Compilation Process

Initialize the build environment:

. build/envsetup.sh

Configure ccache to speed up future builds:

export USE_CCACHE=1
export CCACHE_EXEC=/usr/bin/ccache
export CCACHE_DIR=~/ccache
ccache -M 60G -F 0
export CCACHE_COMPRESS=1

Select the GSI build target (lineage_gsi_arm64-bp4a-userdebug):

breakfast lineage_gsi_arm64-bp4a-userdebug -j4
make installclean
make systemimage -j4

Once compilation completes, the output image will be saved at: out/target/product/generic_arm64/system.img