Project Overview

To understand Droid Overlay internal structure you should have good knowledge of following principles:

• Unix basics
• FHS
• Installation prefix
• Sysroot/build sysroot
• GCC usage, CFLAGS
• Makefile syntax

Following concepts are useful, but not crucial:

• Multilib
• Dynamic linker
• Autoconf usage

Terminology

Following two terms will be used from now on:

Bootstrap system

Android system which Droid Overlay is installed on.

Combined system

GNU/Linux computer, running cross toolchain.

GNU software

Software under FSF-approved free licenses (sorry, BSD).

Rationale

Goals

Android lacks many thing, including spirit of freedom, free drivers and even descent C library. Despite this facts it is still the most popular handheld OS, mainly due to rich and well documented API, several clever design choices and effective marketing. This makes it the most suitable for it's main target auditory - application developers. Droid Overlay project is based on acceptance of this truth. It aims at fulfilling wishes of the rest of Android userbase: casual users, wishing for cheap and high-quality software and hackers, who want to use their devices for more advanced activities.

Approach

Historically-proven way to fulfill aforementioned goals is creation of GNU distribution. Unlike already existing ports of various distribution to ARM platform Droid Overlay acknowledges lack of free hardware drivers and impossibility of sharing proprietary driver code between different versions of Linux kernel. It attempts to work around this limitation by delegation of such task to existing system (Android) and creation of independent file hierarchy, containing userspace-only GNU distribution. Note, that due to tolerable difference between Android and mainline kernel, it could be theoretically possible to create and use dynamically-loadable kernel modules, but such use-case is still to be explored.

Caveats

Visible simplicity of described solution resulted in several independent attempts to adopt described approach. All of them has at least one of following disadvantages:

1. Statical linking
2. Non-free codebase
3. No longterm support and updates
4. Closed development
5. Small package base
6. Lacking or improperly implemented integration with Android

Humorously Android itself is subject to 3rd, 4th and occasionally 2nd issues. There are several more-or-less obvious reasons for such situation:

No APIs for native applications

This issue is logically derived from enforced usage of managed code and can only be resolved by porting of all GNU software starting from C library level.

Undocumented file system layout

This issue is caused by freedom to build any possible layout, granted to device manufacturers by Google. They are not obligated to follow File Hierarchy Standard or any other common layout and use this freedom quite often. Application developers should get all fixed paths, including location of Android OS tree (usually it is in /system) from managed APIs in android.os.Environment.

Low device capabilities

This issue can not be resolved. It is completely ignored by Droid Overlay. In particular, DRM-ed devices, which does not allow owner to gain root access would not be officially supported.

Implementation

In order to coexist with arbitrary file hierarchy Droid Overlay, in somewhat similar manner to Gentoo Prefix, attempts to install it's files into fixed FHS-compatible subtree. This is achieved by using sysroot and installation prefix. Majority of GNU software have such support or it can be added easily. Created system can share some file with parent system by using symbolic links. Attempt to reuse existing libraries (at least OpenGL ES and several other, documented as part of public API) meets several obstacles:

• Bionic is incompatible with glibc and lacks lot of functions, which requires lot of patching and usage of replacement routines, for example from gnulib
• Dynamically compiled libraries have linker path hardcoded and won't load with different linker because of binary incompatibility
• Dynamic linkers of Bionic and glibc can not be used separately from their C libraries or combined in single process
• More new and feature-rich Bionic versions are tied to newer versions of kernel and packages may require severe modifications to be compatible with many versions

All these problems may be potentially solved by using multilib and other workarounds, but those won't be implemented on initial stages of project.

In order to use more up-to-date software and simplify transition between versions Droid Overlay derives it's packages from Arch Linux ARM package base. In turn most ALARM packages are based on ones from Arch Linux. Unfortunately Droid Overlay have to modify some Arch Linux packages, but there is ongoing work to reduce this number.

Droid Overlay does not modify Arch Linux package creation/management tools, but instead uses wrappers to make cross-compilation and side-by-side installation of created packages possible. These wrappers use separate configuration files, set number of shell variables, including $PATH and $CC, and use other means to avoid genuine PKGBUILD modification.