Merge pull request #50 from morphis/f/extend-documentation

Extend documentation with various additional details

README.md

 # Anbox
 
 Anbox is container based approach to boot a full Android system on a
-regular Linux system like Ubuntu.
+regular GNU Linux system like Ubuntu.
 
 ## Overview
 
 Anbox uses Linux namespaces (user, pid, uts, net, mount, ipc) to run a
 full Android system in a container and provide Android applications on
-any platform.
+any GNU Linux based platform.
 
-Android inside the container has no direct access to any hardware. All
-hardware access is going through the anbox daemon. We're reusing what
-Android has implemented for the Qemu based emulator. The Android system
-inside the container uses different pipes to communicate with the host
-system and sends all hardware access commands through these. OpenGL
-rendering is provided through this.
+The Android inside the container has no direct access to any hardware.
+All hardware access is going through the anbox daemon on the host. We're
+reusing what Android implemented within the QEMU based emulator for Open
+GL ES accelerated rendering. The Android system inside the container uses
+different pipes to communicate with the host system and sends all hardware
+access commands through these.
 
 For more details have a look at the following documentation pages:
 
- * Android Hardware OpenGLES emulation design overview
+ * Android Hardware OpenGL ES emulation design overview
    (https://goo.gl/O2Yi6x)
- * Android Qemu fast pipes (https://goo.gl/jl4GeS)
+ * Android QEMU fast pipes (https://goo.gl/jl4GeS)
  * The Android "qemud" multiplexing daemon (https://goo.gl/DeYa5J)
- * Android Qemud services (https://goo.gl/W8Lx6t)
+ * Android qemud services (https://goo.gl/W8Lx6t)
+
+Anbox is currently suited for the desktop use case but can be used on
+mobile operating systems like Ubuntu Touch, Sailfish OS or Lune OS too.
+However as the mapping of Android applications is currently desktop specific
+this needs additional work to supported stacked window user interfaces too.
+
+The Android runtime environment ships with a minimal customized Android system
+image based on the [Android Open Source Project](https://source.android.com/).
+The used image is currently based on Android 7.1.1
 
 ## Installation
 
-As first step you need to install additional kernel drivers for the
-Android binder and ashmem subsystems. Those drivers are packaged as
-a DKMS package for Ubuntu 16.04 already. You can install them from
-a ppa with the following commands:
+The installation process currently consists of a few steps which will
+add additional components to your host system. These include
+
+ * Out-of-tree kernel modules for binder and ashmem as no distribution kernel
+   ships both enabled.
+ * A udev rule to set correct permissions for /dev/binder and /dev/ashmem
+ * A upstart job which starts the Anbox session manager as part of
+   a user session.
+
+To make this process as easy as possible we have bundled the necessary
+steps in a snap (see https://snapcraft.io) called "anbox-installer". The
+installer will perform all necessary steps. You can install it on a system
+providing support for snaps by running
 
 ```
- $ sudo apt install software-properties-common
- $ sudo add-apt-repository ppa:morphis/anbox-support
- $ sudo apt update
- $ sudo apt install anbox-modules-dkms
+$ snap install --classic anbox-installer
 ```
 
-Anbox is available as a snap in the public Ubuntu Store. Currently it
-is only available in the edge channel and requires to be installed in
-devmode as we don't have proper confinement for it in place yet.
-
-Anbox can be installed from the Ubuntu Store with
+Alternatively you can fetch the installer script via
 
 ```
-$ snap install --edge --devmode anbox
+$ wget https://raw.githubusercontent.com/anbox/anbox-installer/master/installer.sh -O anbox-installer
 ```
 
+Please note that we don't support any possible Linux distribution out there
+yet. Please have a look at the following chapter to see a list of supported
+distributions.
 
-Afterwards run it with
+To proceed the installation process simply called
 
 ```
-$ anbox
+$ anbox-installer
 ```
 
-After the first installation the container management service needs
-a few minutes to setup the container the first time before it is
-available.
+This will guide you through the installation process.
 
-Applications can be launched via the launch subcommand of the anbox
-binary. For example
+**NOTE:** Anbox is currently in a **pre-alpha development state**. Don't expect a
+fully working system for a production system with all features you need. You will
+for sure see bugs and crashes. If you do so, please don't hestitate and report them!
 
-```
-$ anbox launch --package com.android.settings
-```
+**NOTE:** The Anbox snap currently comes **completely unconfined** and is because of
+this only available from the edge channel. Proper confinement is a thing we want
+to achieve in the future but due to the nature and complexity of Anbox this isn't
+a simple task.
+
+## Supported Linux Distributions
 
-When installed as snap there will be also a desktop launcher available
-which will directly start the application viewer activity to give
-an overview of available Android applications and allows to start
-them.
+At the moment we officially support the following Linux distributions:
+
+ * Ubuntu 16.04 (xenial)
+
+Untested but likely to work:
+
+ * Ubuntu 14.04 (trusty)
+ * Ubuntu 16.10 (yakkety)
+ * Ubuntu 17.04 (zesty)
+
+## Install and Run Android Applications
 
 ## Build from source
 
-To build the Anbox runtime itself there is nothing special to know
-about. We're using cmake as build system.
+To build the Anbox runtime itself there is nothing special to know. We're using
+cmake as build system. A few build dependencies need to be present on your host
+system:
+
+ * libdbus
+ * google-mock
+ * google-test
+ * libboost
+ * libboost-filesystem
+ * libboost-log
+ * libboost-iostreams
+ * libboost-program-options
+ * libboost-system
+ * libboost-test
+ * libboost-thread
+ * libcap
+ * libdbus-cpp
+ * mesa (libegl1, libgles2)
+ * glib-2.0
+ * libsdl2
+ * libprotobuf
+ * protobuf-compiler
+ * lxc
+
+On an Ubuntu system you can install all build dependencies with the following
+command:
+
+```
+$ sudo apt install build-essential cmake cmake-data debhelper dbus google-mock \
+    libboost-dev libboost-filesystem-dev libboost-log-dev libboost-iostreams-dev \
+    libboost-program-options-dev libboost-system-dev libboost-test-dev \
+    libboost-thread-dev libcap-dev libdbus-1-dev libdbus-cpp-dev libegl1-mesa-dev \
+    libgles2-mesa-dev libglib2.0-dev libglm-dev libgtest-dev liblxc1 \
+    libproperties-cpp-dev libprotobuf-dev libsdl2-dev lxc-dev pkg-config \
+    protobuf-compiler
+```
+
+Afterwards you can build Anbox with
 
 ```
 $ mkdir build
@@ -83,7 +142,7 @@ $ cmake ..
 $ make
 ```
 
-That will build the whole stack. A simple
+A simple
 
 ```
 $ make install
@@ -91,25 +150,51 @@ $ make install
 
 will install the necessary bits into your system.
 
-## Copyright and Licensing
+If you want to build the anbox snap instead you can do this with the following
+steps:
+
+```
+$ mkdir android-images
+$ cp /path/to/android.img android-images/android.img
+$ snapcraft
+```
+
+The result will be a .snap file you can install on a system supporting snaps
+
+```
+$ snap install --dangerous --devmode anbox_1_amd64.snap
+```
 
-Anbox reuses code from other projects like the Android Qemu emulator.
-These projects are available in the external/ subdirectory with the
-licensing terms included.
+## Run Anbox
 
-The anbox source itself (in src/) is licensed under the terms of
-the GPLv3 license:
+Running Anbox from a local build requires a few more things you need to know
+about. Please have a look at the ["Runtime Setup"](docs/runtime-setup.md)
+documentation.
 
-Copyright (C) 2016 Simon Fels <morphis@gravedo.de>
+## documentation
 
-This program is free software: you can redistribute it and/or modify it
-under the terms of the GNU General Public License version 3, as published
-by the Free Software Foundation.
+You will find additional documentation for Anbox in the *docs* subdirectory
+of the project source.
+
+Interesting things to have a look at
+
+ * [Runtime Setup](docs/runtime-setup.md)
+ * [Build Android image](docs/build-android.md)
+
+## Reporting bugs
+
+If you have found an issue with Anbox, please [file a bug](https://github.com/anbox/anbox/issues/new).
+
+## Get in Touch
+
+If you want to get in contact with the developers please feel free to join the
+*#anbox* IRC channel on [FreeNode](https://freenode.net/).
+
+## Copyright and Licensing
 
-This program is distributed in the hope that it will be useful, but
-WITHOUT ANY WARRANTY; without even the implied warranties of
-MERCHANTABILITY, SATISFACTORY QUALITY, or FITNESS FOR A PARTICULAR
-PURPOSE.  See the GNU General Public License for more details.
+Anbox reuses code from other projects like the Android QEMU emulator. These
+projects are available in the external/ subdirectory with the licensing terms
+included.
 
-You should have received a copy of the GNU General Public License along
-with this program.  If not, see <http://www.gnu.org/licenses/>.
+The anbox source itself, if not stated differently in the relevant source files,
+is licensed under the terms of the GPLv3 license.

docs/build-android.md

+# Build Android Image
+
+For Anbox we're using a minimal customized version of Android but otherwise
+base all our work of a recent release of the [Android Open Source Project](https://source.android.com/).
+
+To rebuild the Android image you need first fetch all relevant sources. This
+will take quite a huge amount of your disk space (~40GB). AOSP recommends at
+least 100GB of free disk space. Have a look at [their](https://source.android.com/source/requirements.html) pages too.
+
+In general for building the Anbox Andorid image the instructions found on [the pages
+from the AOSP project](https://source.android.com/source/requirements.html) apply.
+We will not describe again here of how to build the Android system in general but
+only focus on the steps required for Anbox.
+
+## Fetch all relevant sources
+
+First setup a new workspace where you will download all sources too.
+
+```
+$ mkdir $HOME/anbox-work
+```
+
+Now initialize the repository by download the manifest and start fetching
+the sources:
+
+```
+$ cd $HOME/anbox-work
+$ repo init -u https://github.com/anbox/platform_manifests.git -b anbox
+$ repo sync -j4
+```
+
+This will take quite some time depending on the speed of your internet connection.
+
+## Build Android
+
+When all sources are successfully downloaded you can start building Android
+itself. Initialize the build by
+
+```
+$ lunch anbox_desktop_x86_64-userdebug
+```
+
+The complete list of supported build targets:
+
+ * anbox_desktop_x86_64-userdebug
+ * anbox_desktop_armv7a_arm-userdebug
+ * anbox_desktop_arm64-userdebug
+
+Now build everything with
+
+```
+$ make -j8
+```
+
+Once the build is done we need to take the results and create an image file
+suitable for Anbox.
+
+```
+$ cd $HOME/anbox-work/anbox
+$ scripts/create-package.sh \
+    $PWD/../out/target/product/x86_64/ramdisk.img \
+    $PWD/../out/target/product/x86_64/system.img
+```
+
+This will create an *android.img* file in the current directory.
+
+With this, you are now able to use your custom image within the Anbox runtime.
+
+## Run Anbox with self build android.img
+
+If you have Anbox installed on your system you need to stop it first. If you used
+the installer script and the snap you can do this via
+
+```
+$ initctl stop anbox
+$ sudo systemctl stop snap.anbox.container-manager
+```
+
+It is important that you stop both, the container manager and the session manager.
+
+Once both services are stopped you can start the container manager with your
+custom android.img file by running
+
+```
+$ datadir=$HOME/anbox-data
+$ mkdir -p $datadir/rootfs
+$ sudo anbox container-manager \
+    --android-image=/path/to/android.img \
+    --data-path=$datadir
+```
+
+This will start the container manager and setup the container rootfs inside the
+specified data path.
+
+```
+$ ls -alh $HOME/anbox-data
+total 20K
+drwxrwxr-x  5 ubuntu  ubuntu  4,0K Feb 22 08:04 .
+drwxrwxr-x 16 ubuntu  ubuntu  4,0K Feb 22 08:04 ..
+drwxr-xr-x  2 100000  100000 4,0K Feb 22 08:04 cache
+drwxr-xr-x  2 100000  100000 4,0K Feb 22 08:04 data
+drwxr-xr-x  2 root    root   4,0K Feb 22 08:04 rootfs
+```
+
+**NOTE:** If you look into the $HOME/anbox-data/rootfs directory you won't see
+anything as the container manager spawns up a private mount namespace which
+prevents anything from the outside to see its mount points.
+
+The *cache* and *data* directories are bind-mounted into the rootfs at *rootfs/data*
+and *rootfs/cache*.

docs/runtime-setup.md

+# Overview
+
+The Anbox runtime consists mainly of two separate instances:
+
+ * container manager
+ * session manager
+
+The container manager has the job of managing the container setup and maintenance
+during its lifetime. It has the responsibility to start the LXC environment we're
+using to run the Android system.
+
+The session manager runs inside the session of a user logged into the Linux system.
+It will communicate over several sockets with the Android instance running inside
+the container and provide integration with the Linux system. It also acts as a
+multiplexer to map Android applications into single windows on the desktop
+environment. Currently all application windows are owned by the same process
+(the session manager). The application logic itself is still in a separate process
+inside the Android container.
+
+The following picture shows an overview over the architecture:
+
+![Anbox architecture](architecture.png)
+
+## Application Mapping
+
+Android applications are mapped into single windows within the desktop environment.
+This is achieved by plugging into the Android hwcomposer HAL module which receives
+a set of layers to composite on a screen. Anbox tells SurfaceFlinger through its
+hwcomposer implementation to get a layer for each application and combines this with
+additional information it receives from the Android WindowManager to map individual
+layers to applications. For more details please look into the implementation at
+
+ * android/hwcomposer
+ * src/anbox/graphics/layer_composer.cpp
+ * src/anbox/wm/manager.cpp