jyapayne/anbox
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

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

Browse source 
Extend documentation with various additional details
This commit is contained in:
Simon Fels 2017-02-22 17:07:24 +01:00 • committed by GitHub
commit b1a9dee78f
4 changed files with 291 additions and 61 deletions
Download patch file Download diff file Expand all files Collapse all files

205
README.md
View file

@ -1,80 +1,139 @@
# Anbox # Anbox
Anbox is container based approach to boot a full Android system on a 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 ## Overview
Anbox uses Linux namespaces (user, pid, uts, net, mount, ipc) to run a Anbox uses Linux namespaces (user, pid, uts, net, mount, ipc) to run a
full Android system in a container and provide Android applications on 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 The Android inside the container has no direct access to any hardware.
hardware access is going through the anbox daemon. We're reusing what All hardware access is going through the anbox daemon on the host. We're
Android has implemented for the Qemu based emulator. The Android system reusing what Android implemented within the QEMU based emulator for Open
inside the container uses different pipes to communicate with the host GL ES accelerated rendering. The Android system inside the container uses
system and sends all hardware access commands through these. OpenGL different pipes to communicate with the host system and sends all hardware
rendering is provided through this. access commands through these.
For more details have a look at the following documentation pages: For more details have a look at the following documentation pages:
* Android Hardware OpenGL ES emulation design overview * Android Hardware OpenGL ES emulation design overview
(https://goo.gl/O2Yi6x) (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) * 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 ## Installation
As first step you need to install additional kernel drivers for the The installation process currently consists of a few steps which will
Android binder and ashmem subsystems. Those drivers are packaged as add additional components to your host system. These include
a DKMS package for Ubuntu 16.04 already. You can install them from
a ppa with the following commands: * 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 $ snap install --classic anbox-installer
$ sudo add-apt-repository ppa:morphis/anbox-support
$ sudo apt update
$ sudo apt install anbox-modules-dkms
``` ```
Anbox is available as a snap in the public Ubuntu Store. Currently it Alternatively you can fetch the installer script via
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
``` ```
$ 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 This will guide you through the installation process.
a few minutes to setup the container the first time before it is
available.
Applications can be launched via the launch subcommand of the anbox **NOTE:** Anbox is currently in a **pre-alpha development state**. Don't expect a
binary. For example 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!
``` **NOTE:** The Anbox snap currently comes **completely unconfined** and is because of
$ anbox launch --package com.android.settings 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.
When installed as snap there will be also a desktop launcher available ## Supported Linux Distributions
which will directly start the application viewer activity to give
an overview of available Android applications and allows to start At the moment we officially support the following Linux distributions:
them.
* 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 ## Build from source
To build the Anbox runtime itself there is nothing special to know To build the Anbox runtime itself there is nothing special to know. We're using
about. We're using cmake as build system. 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 $ mkdir build
@ -83,7 +142,7 @@ $ cmake ..
$ make $ make
``` ```
That will build the whole stack. A simple A simple
``` ```
$ make install $ make install
@ -91,25 +150,51 @@ $ make install
will install the necessary bits into your system. will install the necessary bits into your system.
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
```
## Run Anbox
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.
## documentation
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 ## Copyright and Licensing
Anbox reuses code from other projects like the Android Qemu emulator. Anbox reuses code from other projects like the Android QEMU emulator. These
These projects are available in the external/ subdirectory with the projects are available in the external/ subdirectory with the licensing terms
licensing terms included. included.
The anbox source itself (in src/) is licensed under the terms of The anbox source itself, if not stated differently in the relevant source files,
the GPLv3 license: is licensed under the terms of the GPLv3 license.
Copyright (C) 2016 Simon Fels <morphis@gravedo.de>
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.
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.
You should have received a copy of the GNU General Public License along
with this program. If not, see <http://www.gnu.org/licenses/>.

BIN
docs/architecture.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 29 KiB

110
docs/build-android.md Normal file
View file

@ -0,0 +1,110 @@
# 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*.

35
docs/runtime-setup.md Normal file
View file

@ -0,0 +1,35 @@
# 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