Lineageos

LineageOS Development

This skill covers LineageOS custom ROM development - from syncing sources to building and contributing.

Getting Started

Initialize Source

mkdir ~/lineage && cd ~/lineage

# Install repo (if needed)
mkdir -p ~/.bin
curl https://storage.googleapis.com/git-repo-downloads/repo > ~/.bin/repo
chmod a+x ~/.bin/repo
export PATH="$HOME/.bin:$PATH"

# Init LineageOS 21 (Android 14)
repo init -u https://github.com/LineageOS/android.git -b lineage-21.0 --git-lfs

# Sync
repo sync -c -j$(nproc) --force-sync --no-tags --no-clone-bundle

Build Commands

# Setup environment
source build/envsetup.sh

# Setup device (syncs device repos too)
breakfast <device>

# Build flashable ZIP
brunch <device>
# Or separately:
breakfast <device>
mka bacon

# Output: out/target/product/<device>/lineage-21.0-*-UNOFFICIAL-<device>.zip

---

Essential Commands

---

Device Trees

Required Files

device/<vendor>/<device>/
├── lineage_<device>.mk      # Product makefile
├── lineage.dependencies     # Repo dependencies
├── vendorsetup.sh           # Add to lunch
├── BoardConfig.mk           # Hardware config
├── device.mk                # Packages and configs
└── extract-files.sh         # Vendor blob extraction

lineage\_<device>.mk

# Inherit device
$(call inherit-product, device/vendor/device/device.mk)

# Inherit LineageOS common
$(call inherit-product, vendor/lineage/config/common_full_phone.mk)

PRODUCT_NAME := lineage_device
PRODUCT_DEVICE := device
PRODUCT_BRAND := Vendor
PRODUCT_MODEL := Device Name
PRODUCT_MANUFACTURER := Vendor

lineage.dependencies

[
  {
    "repository": "android_kernel_vendor_device",
    "target_path": "kernel/vendor/device"
  },
  {
    "repository": "android_device_vendor_device-common",
    "target_path": "device/vendor/device-common"
  },
  {
    "repository": "proprietary_vendor_device",
    "target_path": "vendor/device"
  }
]

---

repopick - Cherry-picking from Gerrit

# Single change
repopick 12345

# Multiple changes
repopick 12345 12346 12347

# By topic
repopick -t feature-topic

# With dependencies
repopick -Q 12345

# Force overwrite local changes
repopick -f 12345

# Show what would be picked
repopick -n 12345

Find Change Numbers

1. Go to https://review.lineageos.org 2. Search for changes 3. Change number is in the URL or displayed

---

Vendor Blobs

Extract from Device

cd device/vendor/device
./extract-files.sh

Extract from OTA/Factory Image

./extract-files.sh ~/Downloads/ota.zip

proprietary-files.txt Format

# Audio HAL
vendor/lib64/hw/audio.primary.platform.so
vendor/etc/audio_policy_configuration.xml

# With destination path
vendor/lib64/lib.so:vendor/lib64/libfoo.so

# From another device
vendor/lib64/lib.so|other_device

---

LineageOS Features

Trust Interface

Security dashboard showing device integrity:

# device.mk
PRODUCT_PACKAGES += \
    LineageTrust

LiveDisplay

Hardware-accelerated display tuning:

PRODUCT_PACKAGES += \
    lineage.livedisplay@2.0-service-sdm

Styles / Themes

System theming support:

PRODUCT_PACKAGES += \
    ThemePicker

---

Key Directories

---

Contributing

Setup Gerrit Access

git config --global review.review.lineageos.org.username <username>

Submit Change

# Create branch
repo start my-feature .

# Make changes
git add -A
git commit -m "subsystem: Short description

Detailed explanation.

Change-Id: <auto-generated>"

# Push for review
git push ssh://<username>@review.lineageos.org:29418/<project> HEAD:refs/for/<branch>

Commit Message Format

subsystem: Short description

Longer explanation wrapped at 72 characters.
Explain why, not what.

Change-Id: I1234567890abcdef...

---

Common Issues

Breakfast Fails - Missing Repos

# Re-sync device tree
repo sync device/vendor/device kernel/vendor/device vendor/device

Build Fails - SELinux

# Find denials
adb shell dmesg | grep "avc: denied"

# Generate policy (on host)
adb shell dmesg | audit2allow -p out/target/product/<device>/root/sepolicy

Missing Blobs

Check logcat for:

E linker: cannot find symbol...
E ServiceManager: Could not find service...

Add missing files to proprietary-files.txt and re-extract.

---

Quick Reference

# Full workflow
source build/envsetup.sh
breakfast cheeseburger
brunch cheeseburger

# Just kernel
mka bootimage

# Cherry-pick fix
repopick 12345

# Sync everything
repo sync -c -j$(nproc)

# Sync one project
repo sync packages/apps/Settings

# Clean build
m clean && brunch <device>

LineageOS Gerrit Workflow

Setup

SSH Key

# Generate key if needed
ssh-keygen -t ed25519 -C "your_email@example.com"

# Add to Gerrit:
# 1. Go to https://review.lineageos.org/settings/#SSHKeys
# 2. Add your public key

Git Config

git config --global user.email "your_email@example.com"
git config --global user.name "Your Name"
git config --global review.review.lineageos.org.username YOUR_GERRIT_USERNAME

Test Connection

ssh -p 29418 YOUR_USERNAME@review.lineageos.org

---

Submitting Changes

Create Branch

cd <project_directory>
repo start my-feature-branch .

Make Changes

# Edit files...
git add -A
git commit

Commit Message

component: Short summary (50 chars max)

Detailed explanation of the change. Wrap at 72 characters.
Explain the problem this solves and why this approach was chosen.

- Bullet points are OK
- Keep them concise

Test: Describe how you tested this
Bug: https://jira.lineageos.org/browse/XXXX (if applicable)

Change-Id: I1234567890abcdef (auto-generated, don't edit)

Push for Review

git push ssh://YOUR_USERNAME@review.lineageos.org:29418/LineageOS/<project> HEAD:refs/for/<branch>

# Example:
git push ssh://bliss@review.lineageos.org:29418/LineageOS/android_frameworks_base HEAD:refs/for/lineage-21.0

---

repopick Commands

Basic Usage

repopick <change_number>
repopick 12345

Multiple Changes

repopick 12345 12346 12347

By Topic

repopick -t my-topic

Options

Common Patterns

# Pick change and its dependencies
repopick -Q 12345

# Force pick (ignore local changes)
repopick -f 12345

# Preview without applying
repopick -n 12345

# Pick entire topic
repopick -t bluetooth-fixes

---

Updating Changes

Amend and Re-push

# Make more changes
git add -A
git commit --amend

# Push update (same Change-Id = same review)
git push ssh://YOUR_USERNAME@review.lineageos.org:29418/LineageOS/<project> HEAD:refs/for/<branch>

Rebase on Latest

repo sync .
git rebase lineage-21.0
# Resolve conflicts if any
git push ssh://... HEAD:refs/for/lineage-21.0

---

Code Review

Voting

Verified

---

Common Issues

Rejected - Not Up to Date

repo sync .
git rebase lineage-21.0
git push ...

Missing Change-Id

# Install hook
scp -p -P 29418 YOUR_USERNAME@review.lineageos.org:hooks/commit-msg .git/hooks/

# Amend to add Change-Id
git commit --amend

Merge Conflict

repo sync .
git rebase lineage-21.0
# Fix conflicts
git add <fixed_files>
git rebase --continue
git push ...

---

Project Names

Common projects and their paths:

Find project name:

cd <directory>
git remote -v
# Origin URL contains project name

---

Quick Reference

# Start work
repo start my-fix .

# Commit
git add -A && git commit

# Push
git push ssh://user@review.lineageos.org:29418/LineageOS/project HEAD:refs/for/lineage-21.0

# Pick someone else's change
repopick 12345

# Update your change
git commit --amend && git push ...