From Gentoo Wiki
Jump to: navigation, search
Gentoo Prefix on Android Devices
Description Gentoo on Android aims to provide desktop experience on Android mobile devices. This project deploys Gentoo Prefix, a variant of Gentoo that installs in a directory prefix, along with Android, sharing the same Linux kernel.
Project email
IRC channel #gentoo-prefix
No lead election date set
(and inherited member(s))
Parent Project Gentoo Prefix
Project listing

This project is about bringing Gentoo users and developers home to their mobile devices. It aims to produce an environment indifferent to that of desktop computers. It strives to liberate the computers in our pockets with Gentoo philosophy and style, as an ultimate response to Free Software Foundation(FSF)'s concerns on the freedom for mobile computing.


The mobile devices today become more powerful than desktop computers 10 years ago. As the hardware performance boosts, the software becomes a flexible part of the system. The pursuit of software freedom on desktop computers carries naturally to mobile ones.

FSF has recognized the freedom for mobile computing early on. With a GPL-licensed Linux kernel and a Apache-licensed userland, Android is a big step forward for the smartphones, tablets and multimedia centers. At the same time, as FSF points out, there is still a long way to go to regain full control of our own devices.

Vendors have put effort to make their source code open. However, it is rather challenging to figure out exactly how to build from the source a usable system. Patches for Linux kernels from vendors should be tracked. The proprietary binary blobs to drive certain hardware should be carefully analyzed and documented. The bootloaders and flashing tools vary across vendors and impose artificial restrictions for either practical or profit reasons.

LineageOS (forked from Project cyanogenmod) is another step forward in that its build system, finely version controlled, tracks the details needed to build a working system. The development cycle of cyanogenmod is to cross compile, flash the image and test. This is the common practice in "ROM" development in the Android community. Although originally meaning Read-Only Memory, "ROM" in the Android context means the partitions of flash memory that hold the Linux kernel and the Android userland. The same practice is taken by vendor-specific Android variants, and the original Android Open Source Project. The ROMs ease the software distribution of big vendors to have every single device install exactly the same partition images. But unfortunately for users, ROMs impose artificial restrictions in updating and tinkering the system.

With the advancement of mobile computing power, native compiling right on the device becomes feasible. It is possible to introduce package management to ROM developments, to bring the flexibility of Android apps to Android ROMs. This makes development and porting more direct and easier. With the help of an additional GNU userland, the development and test on the mobile devices will be no different from developing desktop computer applications: our phone becomes more hackable and more enjoyable to tweak with.

Gentoo is good at managing building recipes with utmost clarity and elegance by its Portage/Ebuild package management system. Ebuilds are the most suitable installation documentations that are able to be executed and verified to work. Gentoo has the potential to make native development environment for mobile devices a reality.

To achieve our ultimate goal of mobile computation freedom, three stages are required. First, a set of tools familiar to a GNU/Linux user should be installed by Gentoo Prefix. Second, the Linux kernel should be recompiled and customized using the Gentoo Prefix tools by the user. Finally, GNU userland should be able to access input/output peripherals (like HDMI video/audio output, USB keyboard, etc.) and have an X window system. Android and GNU userlands should be integrated by message passing interfaces and framebuffer copying and sharing.

Gentoo Prefix

The development of Android does not happen in Android itself, but in the software development kit(SDK) elsewhere. When the end product is compiled and distributed, the only feasible way to change the system is to flash the whole partition again with another customized whole partition image.

This step is to provide a new way of development by deploying a powerful environment, Gentoo Prefix, into the mobile device that feels natural to every UNIX user.

Gentoo Prefix installs an instance of Gentoo in to a directory prefix, along with Android userland, sharing the same Linux kernel. Because Android system usually sits in /system directory, it is possible to install a native Gentoo into root directory /. But since / is managed by initramfs in Android, the actual native Gentoo has to be installed to another directory and symlinked back to /. To avoid such a burden, Gentoo Prefix is preferred. Furthermore, Gentoo Prefix has the potential to be deployed with a normal user on non-rooted devices.

Anything available in Gentoo is in Gentoo Prefix. A set of toolchain, an editor and a shell are especially useful for further development, debugging, and hacking.


You can either install by the precompiled stage3 tarball or, if brave enough, by building the Gentoo on Android manually.


The device list records all the device test results, compiled by users.

Linux kernel

Android has deep (and sometimes in-house) customizations to the official Linux kernel. Third party vendors further customize the Android source. These sources scatters over the Internet. Using ebuilds to track patchsets and customized sources is the Gentoo-preferred way to handle this complexity.

When necessary, the ebuilds should acknowledge the fact that a set of git repositories are mananged by the repo tool, and leverage the information in repo metadata. The kernel ebuilds should also refer to LineageOS build recipies either manually or automatically.

For every supported device, a set of default kernel config should be provided along with the kernel source and patchset. Portage should be able to compile a usable custom kernel from the ebuilds. To run the custom kernels, a bootloader unlocked device is necessary.

Display sharing

After gaining full control of the kernel, we could develop something new and cool.

Webtop (dead) from Motorola makes use of the HDMI output for their X servers. In such systems SurfaceFlinger of Android and X independently use two framebuffers, which in turn, relies on two independent graphics outputs, namely local display and HDMI. Products following the similar concept include ASUS Padfone, Microsoft Continuum and Samsung DeX. Discontinued efforts include Ubuntu for android and Remix OS.

It is also very helpful to have local display shared between SurfaceFlinger and X. HDMI output with an external monitor is not always available, and X on local display will become an interesting application on a Android tablet.

The feature can be realized by hacking framebuffer in the kernel. Write a framebuffer multiplexer: a void framebuffer driver, which can either drop the data written into it or forward the data to another framebuffer. Controlling this framebuffer multiplexer via sysfs will allow userland to select the real source of a framebuffer.

The Graphics Architecture of Chromium OS offers an interesting option. It could render Android graphics and X, all sharing the same display. It makes this option more viable for the fast that Chromium OS is built by Gentoo portage.

Userland integration

Motorola has demonstrated a revolutionary concept to have GNU and Android integrated together. Its Webtop product, until version 2.0, features a Ubuntu GNU userland running aside Android and introduced a data-exchange mechanism. In Webtop, the user is presented with an Ubuntu environment and has access to the Android system at the same time.

The Webtop 2.0 system has several closed-source components to carry out data-exchange between GNU and Android. It would very nice to have tools with the same purpose available as free software.

With Gentoo Prefix tools and a customizable kernel, we will reverse engineer the existing integration mechanism and write free alternatives.


We are currently looking for users interested in helping the project with these jobs:
Embedded Kernel HackerMaintain the kernel ebuilds for mobile devices.Experience with kernel and embedded
Android DeveloperDevelop a solution of Wayland based on Android graphic drivers based on libhybris, preferrably sharing framebuffer with Android.Familiar with Gentoo Prefix (and its RAP variant), and Android. Familiar with X11 and Wayland. Experience with

See Also

  1. Android FAQ