Extend documentation with various additional details
This commit is contained in:
Simon Fels
parent
d30e8f1a74
commit
bae6bfef3f
4 changed files with 291 additions and 61 deletions
207
README.md
207
README.md
|
|
@ -1,80 +1,139 @@
|
|||
# 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.
|
||||
|
||||
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.
|
||||
## Supported Linux Distributions
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
|
||||
Anbox reuses code from other projects like the Android Qemu emulator.
|
||||
These projects are available in the external/ subdirectory with the
|
||||
licensing terms included.
|
||||
Anbox reuses code from other projects like the Android QEMU emulator. These
|
||||
projects are available in the external/ subdirectory with the licensing terms
|
||||
included.
|
||||
|
||||
The anbox source itself (in src/) 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/>.
|
||||
The anbox source itself, if not stated differently in the relevant source files,
|
||||
is licensed under the terms of the GPLv3 license.
|
||||
|
|
|
|||
BIN
docs/architecture.png
Normal file
BIN
docs/architecture.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 29 KiB |
110
docs/build-android.md
Normal file
110
docs/build-android.md
Normal 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
35
docs/runtime-setup.md
Normal 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:
|
||||
|
||||
|
||||
|
||||
## 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
|
||||
Loading…
Add table
Add a link
Reference in a new issue