diff --git a/README.md b/README.md index 7aee100..f5bc58f 100644 --- a/README.md +++ b/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 - -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 . +The anbox source itself, if not stated differently in the relevant source files, +is licensed under the terms of the GPLv3 license. diff --git a/docs/architecture.png b/docs/architecture.png new file mode 100644 index 0000000..4dcaf12 Binary files /dev/null and b/docs/architecture.png differ diff --git a/docs/build-android.md b/docs/build-android.md new file mode 100644 index 0000000..7f4b76e --- /dev/null +++ b/docs/build-android.md @@ -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*. diff --git a/docs/runtime-setup.md b/docs/runtime-setup.md new file mode 100644 index 0000000..8f07eeb --- /dev/null +++ b/docs/runtime-setup.md @@ -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