User:Dinominant/Gentoo on Android

From Gentoo Wiki
Jump to:navigation Jump to:search

Gentoo on Android

A common saying is the best camera is the one with you so therefore the best computer for Gentoo is the one with you. That is most likely your Android cell phone. Unfortunately most Android phones are locked in various ways and have further security/business policies which limit access/usability/repairability for users. This renders a typical installation via the Gentoo Handbook impossible.

As a software developer, special tools exist and additional access is required to debug and install software on Android. This will be used to deploy Gentoo allowing it for use as a development environment and other workflows.

Gentoo Linux can be installed on an updated and non-rooted Android device.


  • A Linux host computer, preferably Gentoo Linux
  • QEMU
  • Android Studio
  • An Android cell phone (root access is not required). The Apple App Store explicitly bans emulators, so all Apple iOS devices are insufficient.

Host Computer Setup

The host computer will be used to prepare the aarch64 virtual machine since it is much faster than compilation on an actual cell phone. Then it will be transferred to the phone via adb.

  1. Setup QEmu on your computer.
    1. Hardware acceleration for guest virtual machines is not required.
    2. /etc/portage/package.use/qemu app-emulation/qemu qemu_softmmu_targets_aarch64 qemu_softmmu_targets_arm qemu_softmmu_targets_i386 qemu_softmmu_targets_x86_64 qemu_user_targets_aarch64 qemu_user_targets_arm qemu_user_targets_i386 qemu_user_targets_x86_64 spice static-user tci

Create the Virtual Machine

  1. This step is mostly automated and requires lots of time to compile software.
  2. Verify your host system has enough free space and sufficient power to complete this task
  3. It may take several days to compile everything.
    1. Create a 32GB flat image file at /mnt/gentoo.img dd if=/dev/zero bs=1000000 count=0 seek=32000 of=/mnt/gentoo.img
    2. loop mount that image file at /mnt/gentoo
    3. Install Gentoo aarch64 on that image file at /mnt/gentoo
    4. Then convert the gentoo.img file to gentoo.qcow2 just prior to pushing the image to the phone to save space
  5. gentooinstall -a aarch64 -d /mnt/gentoo -t "Canada/Mountain"
  6. chroot /mnt/gentoo /bin/bash
    1. This step is important and will enable virtio and plan9 support. virio improves performance and plan9 allows guest VM read+write access to the Android host directories.
    2. emerge a kernel such as sys-kernel/gentoo-sources or sys-kernel/vanilla-sources
    3. Use an existing kernel config such as 5.4.109-aarch64 or generate a new one with kernelseeds --enable-all-menuconfig --enable-all-modules
    4. Compile the kernel: cd /usr/src/linux && make && make modules_install

Enable Developer Options on Android

  1. Go to Settings and tap "About device" or "About phone"
  2. Tap "Software information" if this option is listed
  3. Scroll down and tap "Build number" seven times

Upload and Start Gentoo


FILE /data/local/tmp/


nohup ./qemu-system-aarch64 \
        -machine virt -cpu max -smp cpus=1,sockets=1,cores=1 -m 1024 \
        -kernel "$VMDIR/phone01-vmlinuz-5.4.109" -append 'root=/dev/vda1 mitigations=off' \
        -nographic \
        -drive file="$VMDIR/phone01.qcow2",format=qcow2,if=virtio \
        -nic user,model=virtio,id=eth0,hostfwd=tcp::10022-:22 \
        -virtfs local,path=/,mount_tag=root,security_model=none,id=root \
        -virtfs local,path=$INTERNAL,mount_tag=internal,security_model=none,id=internal \
        -virtfs local,path=$SDCARD,mount_tag=sdcard,security_model=none,id=sdcard \
        -virtfs local,path=$QEMUDIR,mount_tag=qemudir,security_model=none,id=qemudir \
        > phone01.stdout 2> phone01.stderr < /dev/null &

# mount -t 9p -o trans=virtio,version=9p2000.L external /mnt/external
# mount -t 9p -o trans=virtio,version=9p2000.L internal /mnt/internal

Connect your phone to your computer via a data and charging USB cable

Push files to /data/local/tmp

root #ls /data/local/tmp

adb shell into the phone and start the virtual machine!

If you exit from the shell, the virtual machine will continue to run until the phone is powered off or rebooted. Shell back into restart the VM, possibly once per month after each software update forces a reboot. The /data/local/tmp directory is not purged during reboots or system updates. However this could change one day -- and if the android developers should NOT make that change without providing a different persistent storage location, so backup often.

Mount some of the phone directories in the VM. Those mount points can then be re-exported via sshfs to yet another system, and re-exported again if required. This will grant wireless and secure read+write access to the phone data without having to connect the phone.

FILE /etc/fstab
root  /mnt/root  9p  trans=virtio,version=9p2000.L,noatime,nodiratime,multidevs=remap  0 0
internal  /mnt/internal  9p  trans=virtio,version=9p2000.L,noatime,nodiratime,multidevs=remap  0 0
sdcard  /mnt/sdcard  9p  trans=virtio,version=9p2000.L,noatime,nodiratime,multidevs=remap  0 0
qemudir  /mnt/qemudir  9p  trans=virtio,version=9p2000.L,noatime,nodiratime,multidevs=remap  0 0