How to develop a platform plugin

Anbox Cloud provides a platform SDK that allows the development of custom platform plugins for the Anbox runtime, for use cases where the default platforms don’t fit. For example, a custom platform can be used to integrate a custom streaming protocol with the Anbox runtime.

This guide assumes that all steps are run on an Ubuntu 22.04 machine that hosts the Anbox Cloud Appliance.

Preparation

A platform module must be built on the same version of Ubuntu as the Anbox runtime. This means that if you’re using one of the Anbox images based on Ubuntu 22.04 (for example, jammy:android12:arm64), you must build on Ubuntu 22.04.

However, if you’re running the Anbox Cloud Appliance on a machine with a different Ubuntu version, you can build the platform on a separate system (for example, in a LXD or docker container or on another machine).

To get started, you must first install the Anbox Platform SDK. To do so, follow the installation instructions.

Build the example platform

The Anbox Platform SDK comes with various examples that demonstrate different features. The following steps use the minimal example. Alternatively, choose the nvidia example if you’re working with NVIDIA GPUs and want to see graphical output.

To build the minimal platform example, run the following commands:

triplet=$(dpkg-architecture -qDEB_BUILD_MULTIARCH)
cmake \
    -G Ninja \
    -B build \
    -DCMAKE_PREFIX_PATH=../../lib/anbox-platform-sdk/ \
    -DCMAKE_INSTALL_LIBDIR=lib/${triplet} \
    -DCMAKE_INSTALL_PREFIX=/usr examples/minimal/
ninja -C build

The build process creates a platform_minimal.so module in the build directory.

Install the example platform

AMS allows launching Anbox containers in a special development mode, which is helpful when developing, for example, addons or platforms. In development mode, the Anbox runtime does not terminate the container when it detects failures or other problems.

To try out the minimal platform, complete the following steps:

Start a raw container with development mode turned on:
```
 amc launch --raw --devmode --instance-type=a4.3
```
If you chose the nvidia example, you must select an instance type that supports GPUs:
```
 amc launch --raw --devmode --instance-type=g4.3
```
The command prints out the ID of the container. Note down this ID; you will need it in the next step.

The start of the raw container takes some time, because it runs through the full bootstrap process before the container is ready to be used.

When the container is fully up and running, copy the platform_minimal.so module to it:

 id=<ID_of_the_container>
 triplet=$(dpkg-architecture -qDEB_BUILD_MULTIARCH)
 amc exec "${id}" mkdir "/usr/lib/${triplet}/anbox/platforms/minimal"
 lxc file push build/platform_minimal.so "ams-${id}/usr/lib/${triplet}/anbox/platforms/minimal/"

With the platform plugin present inside the container, configure the Anbox runtime to make use of it. For that, change the /var/lib/anbox/session.yaml configuration file within the container:
```
 cat << EOF | amc exec "${id}" tee /var/lib/anbox/session.yaml
 log-level: debug
 platform: minimal
 EOF
```
This command rewrites the Anbox runtime configuration to use the new minimal platform instead of the default one.

Restart Anbox inside the container:

 amc exec "${id}" -- systemctl restart anbox

When the Anbox runtime was restarted, verify from the container system log that it now uses the new minimal platform:
```
 amc logs "${id}"
```
Inside the log, there should be a line similar to the following:
```
 [ 2022-12-07 14:00:18] [anbox-session] [base_platform.cpp:34@create] Using platform 'minimal'
```
This line shows that the platform was successfully loaded and is in use by Anbox.

When developing a new platform, you can also directly invoke the Anbox runtime rather than start it via systemd. For that, stop the anbox.service unit first:

amc exec "${id}" -- systemctl stop anbox

Then start the Anbox runtime directly by running:

amc exec "${id}" -- anbox-starter

When you want to stop Anbox, you can use CTRL+C to send it the signal to terminate.

Package the platform

To ship the platform to actual containers via AMS, you must create an addon package that installs the platform into the container.

A very simple addon to install the created minimal platform looks as follows:

mkdir hooks
cat << EOF > hooks/pre-start
#!/bin/sh -ex

# Only run for base containers
[ "$CONTAINER_TYPE" = "regular" ] && exit0

# Install the platform plugin into the right location
# NOTE: Please adjust the path for the right architecture you're targeting
mkdir -p /usr/lib/aarch64-linux-gnu/anbox/platforms/minimal
cp "$ADDON_DIR"/platform_minimal.so /usr/lib/aarch64-linux-gnu/anbox/platforms/minimal/
EOF
chmod +x hooks/pre-start
tar cjf minimal-addon.tar.bz2 hooks platform_minimal.so

Load this addon into AMS so that it can be used by applications and containers:

amc addon add minimal minimal-addon.tar.bz2

When launching a container, you must explicitly specify the platform that the Anbox runtime inside the container should use with the --platform argument. If not specified, Anbox will use its default. To launch a container with the minimal platform, run the following command:

amc launch --raw --addon minimal --platform minimal

Last updated 23 days ago.

Help improve this document in the forum.