Project:Android/tarball

This guide covers the installation of Gentoo Prefix on Android devices by using a precompiled stage3 tarball.

The CPU on the target device should be at least a ARMv7-A with FPU, consult list of arm cores if in doubt. It would be no problem if the device CPU was advertised as dual core or more, or released later than 2011. The device list may be helpful, too.

A rooted device is needed to install Gentoo. Because most Android system have noexec option set for user writable partitions, which prevents applications to be executed. At the same time, the possibility to run Gentoo on non-rooted devices is being explored.

Busybox newer than 1.17 will be needed. If you don't have that yet, it is recommended to use Stericson's version

Prepare the Gentoo Directory

Gentoo on Android hardcodes the directory prefix (also known as EPREFIX) at build time in many places, most notably the interpreter field of ELF and config files of portage. The precompiled stage3 tarball points its EPREFIX to /data/gentoo. Root privilege is required either to make a new directory in /data or to mount an ext4 partition at /data/gentoo. A minimum of 500MB free space is required, and 2GB is recommended.

/data/gentoo can be located either in internal flash (often mounted as ext3/ext4/f2fs at /data) or in a external SD card. To prepare the partitions on the SD card, follow the instructions on SDCard.

The tarball

64bit build

Consumer ARM devices have migrated to 64bit since 2013. As of 2018, the migration has completed. The 64bit ARM architecture is keyworded arm64 in Gentoo and is also referred to as AArch64 in gcc. If your device is running a 64bit kernel, a 64bit tarball is the best choice.

Date	Gcc	Binutils	Glibc	MD5
2020.07.04	10.1.0	2.34	2.31	47a9dbdb5734cdf35622ed63b76de811
2018.02.25	7.3.0	2.30	2.26	6e92ce77707df432ea0a645e575f5cef

32bit build

The 32bit ARM architecture was developed up to armv7. The 64bit ARM cpus usually provides 32bit compatibility ISA. Therefore the 32 tarballs can be used on almost all the devices.

Date	Gcc	Binutils	Glibc	MD5
2018.02.26	7.3.0	2.30	2.26	f8959aad5cb3ebf73340982453a3b348
2016.10.26	5.4.0	2.26	2.23	4036d9dcf56118ffedcbb81f0b1d312c
2014.12.10	4.9.2	2.24	2.20	091f0f744fd7f09b19d3e75483d37341
2013.10.03	4.7.3	2.23	2.17	9ead3a9e9125cb78a8a4e0a540ac1f19

Download the latest 64bit tarball (2020.07.04) or 32bit tarball (2018.02.26), and then extract it into the /data directory.

Tutorial

If you know how to do it, this section can be safely skipped.

Obtain an interactive root shell via adb, a terminal emulator (e.g. Termux), or dropbear:

user $su

Make sure to be in a directory of at least 500MB free space. Download and extract the tarball and verify:

root #

busybox wget http://distfiles.gentoo.org/experimental/prefix/arm/prefix-stage3-arm64-latest.tar.xz

root #

busybox tar -C /data -xf prefix-stage3-arm64-latest.tar.xz

root #

ls /data/gentoo*/startprefix

/data/gentoo64/startprefix

For 32bit tarball, replace prefix-stage3-arm64-latest.tar.xz with prefix-stage3-armv7a_hardfp-latest.tar.xz.

Start Gentoo

In a shell, execute:

root #/data/gentoo64/startprefix

Replace gentoo64 with gentoo for 32bit.

Failed to find the Prefix shell?

When the SHELL variable is defined to be something Prefix is unaware of, you will run into the following error:

root #/data/gentoo64/startprefix

Failed to find the Prefix shell, this is probably because you didn't emerge the shell tmp-mksh

To fix it, explicitly state that the Prefix bash should be used:

root #SHELL=/bin/bash /data/gentoo64/startprefix

Beyond

Congratulations! Now you have a full functional Gentoo on your favorite Android device. As long as you are familiar with Gentoo, you can unleash its power immediately. If not, the sections of Working with Gentoo and Working with Portage of the Gentoo Handbook are your good starting points. Please also report your installation.

Gentoo ebuild repository

Before compiling anything, choose a mirror

FILE ${EPREFIX}/etc/portage/repos.conf/gentoo.conf

sync-uri = rsync://rsync.gentoo.org/gentoo-portage # replace it with the closest mirror to you

Synchronize:

root #emaint sync -a

Note
To save space, the bare tarball does not include a repository checkout.

Symlink Hacks

Most of the ebuild still need /bin/sh, /usr/bin/env, /bin/pwd to build. Before having a solution, we have to live with symlinks of these binaries back to /data/gentoo64. This is handled by the startprefix script.

ssh Server

Terminal emulators from Android GUI are generally not good at handling key bindings. The adb shell defaults to a 80x24 terminal. To have a full-featured terminal, a real sshd server is necessary.

root #rc-update add sshd default

root #openrc default

Put your ssh public key into /data/gentoo/root/.ssh/authorized_keys. Be sure to set 700 and 600 permission bits to .ssh/ directory and authorized_keys file respectively.

Note
Wifi connection might become unstable after turning off android. Ethernet (software USB network adapters or hardware USB-OTG adapter) is relatively more reliable.

Out of Memory

Mobile devices do not usually have as much memory as workstations. Building big applications, such as gcc or clang could cost a lot of memory. The Android lowmemorykiller might kill the emerge building process if memory runs low.

Turn off Android

Once the ssh server is running, it is possible to turn off the Android runtime to save about 500MB of memory:

root #/system/bin/stop

Further stop remaining Android services, for example, mediaserver and adbd:

root #/system/bin/setprop ctl.stop media

root #/system/bin/setprop ctl.stop adbd

Disable the Android lowmemorykiller:

root #echo 0,0,0,0,0,0 > /sys/module/lowmemorykiller/parameters/minfree

Add Swap space

Adding a swap file or partition of similar size of system memory could ease up the memory shortage. See the discussion of swap and setting up of zram

gcc and ld

Let gcc and ld to trade time for memory. Remove -pipe from CFLAGS in /etc/portage/make.conf, and put -Wl and --no-keep-memory into the LDFLAGS variable.

FILE ${EPREFIX}/etc/portage/make.conflet gcc and ld save memory

# do not use -pipe here, as most embedded devices are memory hungry 
# do not write CFLAGS="${CFLAGS} ..." because the profile sets -pipe
# in CFLAGS
CFLAGS="-O2 -march=armv7-a -mcpu=cortex-a9 -mfpu=neon -funsafe-math-optimizations"
CXXFLAGS="${CFLAGS}" 
LDFLAGS="${LDFLAGS} -Wl,--no-keep-memory"

-pipe lets gcc use pipes rather than temporary files for communication between the various stages of compilation.
ld normally optimizes for speed over memory usage by caching the symbol tables of input files in memory. --no-keep-memory tells ld to instead optimize for memory usage, by rereading the symbol tables as necessary. This may be required if ld runs out of memory space while linking a large executable.