Project:Android/tarball

This guide covers the installation of Gentoo RAP 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. 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 RAP 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 previledge 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
Download the tarball (2016.10.26), and then extract it into /data.

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

Obtain an interactive shell by adb or terminal emulater (or dropbear), and become root:

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

Start Gentoo
In a shell, execute

Failed to find the Prefix shell?
When SHELL is defined to be something Prefix is unaware of, you will run into the following error

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

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.

Portage Tree Sync
Before compiling anything, sync the latest tree.

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/gentoo. 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.

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

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.

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

Disable the Android lowmemorykiller.

Add Swap
Adding a swap file or partition of similar size of system memory could ease up the memory shortage.

gcc and ld
Let gcc and ld to trade time for memory. Remove -pipe from CFLAGS, and put -Wl,--no-keep-memory into LDFLAGS.


 * -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.