A guide on how to use Lindroid

Guide-of-Lindroid.md

An Unofficial Guide of Lindroid

Official Guide: https://t.me/linux_on_droid/1263

What is Lindroid?

Lindroid is an Android app that lets you run Linux in a container, with support for hardware-acceleration. Official group: https://t.me/linux_on_droid

How to Compile Lindroid?

1. Ensure your device has the necessary configurations:

   • Obtain a usable device configuration, kernel source, and ROM source code for your device.

2. Clone the necessary repositories Linux-on-droid repository:

   • Clone vendor_lindroid from to $ANDROID_BUILD_TOP/vendor/lindroid.

     git clone https://github.com/Linux-on-droid/vendor_lindroid vendor/lindroid
     

   • Clone external_lxc to $ANDROID_BUILD_TOP/external/lxc.

     git clone https://github.com/Linux-on-droid/external_lxc external/lxc
     

   • Clone libhybris to $ANDROID_BUILD_TOP/libhybris.

     git clone https://github.com/Linux-on-droid/libhybris libhybris
     

   • Pick the patch from https://gerrit.libremobileos.com/c/LMODroid/platform_frameworks_native/+/12936 to $ANDROID_BUILD_TOP/frameworks/native.

     cd $ANDROID_BUILD_TOP/frameworks/native
     wget https://github.com/LMODroid/platform_frameworks_native/commit/51b680f33b66e06b18725fdf9a54fa923c14a10b.patch
     git am 51b680f*.patch
     cd $ANDROID_BUILD_TOP
     

     If Android 13, use https://review.lineageos.org/c/LineageOS/android_frameworks_native/+/351543

     cd $ANDROID_BUILD_TOP/frameworks/native
     wget https://github.com/LineageOS/android_frameworks_native/commit/94dd1b1bda79e783b1610470a5284bb6f300340e.patch
     git am 94dd1b1*.patch
     cd $ANDROID_BUILD_TOP
     

3. Modify device configurations:

   • Add $(call inherit-product, vendor/lindroid/lindroid.mk) to your device's mk file.
   • Add BOARD_KERNEL_CMDLINE += androidboot.selinux=permissive or BOARD_BOOTCONFIG += androidboot.selinux=permissive for GKI devices to BoardConfig.mk.
   • Ensure SELinux is set to permissive mode for Lindroid.

4. Kernel configuration:

   • For non-GKI devices, refer to kernel configurations for enabling LXC/Docker support.

     Search keywords 'lxc docker android' in GitHub

   • Example kernel configurations provided by Lindroid developers include:

     CONFIG_SYSVIPC=y
     CONFIG_UTS_NS=y
     CONFIG_PID_NS=y
     CONFIG_IPC_NS=y
     CONFIG_USER_NS=y
     CONFIG_NET_NS=y
     CONFIG_CGROUP_DEVICE=y
     CONFIG_CGROUP_FREEZER=y
     

   • For GKI 5.10, refer to this source. For 5.15 and 6.1, explore the configurations accordingly.
   • I recommend that compile KernelSU simultaneously for root access (use v0.9.5 tag for non-GKI). Or use magisk etc.

5. Build your ROM using the userdebug variant:

   • Avoid using user variant for now.
   • If FCM (Framework Compatibility Matrix) errors occur, leading to OTA package build failure, manually modify configurations in the $ANDROID_BUILD_TOP/kernel/configs/[ANDROID VERSION]/[KERNEL VERSION]/ directory of the ROM source.

How to Use Lindroid?

1. Download and prepare the root filesystem

   • Download the pre-packaged Debian image from lindroid-rootfs releases or Lindroid website. Ensure that the folders (e.g., etc/, bin/, usr/...) in the archive are at the root level, not within an inner directory like rootfs/. If not, repack it.
   • Push it to /data/data/org.lindroid.ui/files/rootfs.tar.gz (rename to rootfs).
   • Open Lindroid and follow the prompts to create the container.

2. Configure your device

   • Ensure network connection, disable auto-rotate, set screen timeout to 30 minutes, and grant root access to shell in developer options.
   • Use adb shell or terminal to enter:

     su
     lxc_ls
     lxc_attach default
     /bin/bash -c "source /etc/profile && exec su - root"

   • Optionally, change Debian source mirrors for CN users:

     sed -i 's/deb.debian.org/mirrors.bfsu.edu.cn/g' /etc/apt/sources.list

   • Then upgrade all packages (Especially Kwin etc. from lindroid)

     apt update && apt-get -o Dpkg::Options::="--force-overwrite" full-upgrade

   • If there is a network error, try setting DNS server:

     echo "nameserver 8.8.8.8" > /etc/resolv.conf

3. Test and configure the graphical interface:

   • Test graphics with test_hwcomposer.
   • Start or restart SDDM service:

     systemctl restart sddm

   • If touch doesn't work, try:

     sudo setcap cap_dac_read_search+ep /usr/bin/startplasma-wayland
     sudo setcap cap_dac_read_search+ep /usr/bin/kwin_wayland
     sudo setcap cap_dac_read_search+ep /usr/bin/sddm

   • Use evtest to check for Lindroid virtual input devices. Adjust /dev/uinput permissions if needed and restart Lindroid in adb shell.

     su -c chmod 777 /dev/uinput
     am force-stop org.lindroid.ui

Some supplements:

• The most important thing is patience and waiting. SDDM usually starts one or two minutes after starting Lindroid. Please do not do anything during this period of black screen.
• XDG hack to run kwin manually:

  export XDG_RUNTIME_DIR=/tmp/runtime-lindroid
  mkdir -p $XDG_RUNTIME_DIR
  chmod 700 $XDG_RUNTIME_DIR
  

• Execute this command to get input:

  groupadd --gid 1004 android_input
  usermod -aG android_input lindroid
  usermod -aG android_input sddm
  

  Modify /etc/logind.conf to fix power button
  Restart systemd-logind on every login to run sddm
• Try:

  loginctl kill-user lindroid
  systemctl restart systemd-logind
  

  as root if sddm doesn't work
• Download this public-key.asc and push to /etc/apt/trusted.gpg.d/lindroid.asc to resolve the GPG warning of apt update
• Install kscreen to restore display settings, kinfocenter to restore about system option.

Notes:

• Default username and password are both lindroid.
• Subsequent usage may encounter touch issues; restart Lindroid, sddm and systemd-logind as needed.
• External keyboard/mouse is recommended. KDE Connect can help with remote control.
• There are also apps that can turn your other phone into a keyboard via Bluetooth.
• Strongly suggest SSH for better terminal experience.

This guide is a compilation of my personal exploration and guidance from Lindroid developers [Erfan Abdi, Luka, Nick].

Expect some initial issues, but it’s a promising start. Explore further on your own.

If you need more support, please join the official Lindroid group. Read the official #guide to get started

28/6/24

For lineage-21.0 branch (Android 14), it needs https://review.lineageos.org/c/LineageOS/android_frameworks_native/+/409935

it would be great if there is a video tutorial, PLEASE

For those who also want to build Lindroid on LineageOS, I created an organization for doing so at ease.
The instructions to build ROM can refer to page like https://wiki.lineageos.org/devices/rtwo/build/variant2/. However, instead of running

repo init -u https://github.com/LineageOS/android.git -b lineage-22.2 --git-lfs --no-clone-bundle

You should use the android repo from Linux-on-LineageOS instead,

repo init -u https://github.com/Linux-on-LineageOS/android.git -b lineage-22.2 --git-lfs --no-clone-bundle

Beside this, you can also use the linux-on-lineage-cicd docker image to build one automatically. Basically, it is a fork from docker-lineage-cicd. The example commands can be found at https://github.com/lineageos4microg/docker-lineage-cicd/wiki#examples.
For example:

docker run \
    -e "BRANCH_NAME=lineage-22.2" \
    -e "DEVICE_LIST=rtwo" \
    -e "WITH_GMS=false" \
    -v "/home/user/lineage:/srv/src" \
    -v "/home/user/zips:/srv/zips" \
    -v "/home/user/logs:/srv/logs" \
    -v "/home/user/cache:/srv/ccache" \
   linuxonlineageos/linux-on-lineage-cicd

Only Motorola X40 (rtwo) was tested. For other devices, they may not work as intended. You can fork the device related repository and fix the errors. PRs are welcome. :)