anbox-platform-sdk  1.13.0
Anbox Platform SDK API documentation
Creating a Platform Plugin

Anbox loads an external platform plugin through its internal platform integration. A platform plugin is always in the form of a dynamic library that is loaded by Anbox at runtime. Whenever loading a plugin, Anbox will go through the following steps to verify if the platform plugin is installed properly and implements the standards-compliant API.

  1. Verify existence of the platform plugin
    Anbox looks for existing platforms in the directory path
    /usr/lib/<target_triple>/anbox/platforms/<plugin_name>
    The plugin shared library (.so) and all its dependencies which are not part of the base OS must be installed there.
  2. Verify the platform specifies a correct plugin descriptor
    Anbox retrieves the platform plugin basic information from the given share file, such as the platform name or vendor. More importantly, the provided descriptor is used to check if the SDK API version the plugin specifies what Anbox requires.
  3. Verify all mandatory functions are exported
    Anbox examines if all required symbols are exported by the plugin.

If a platform fails verification, Anbox refuses to load it and will terminate with an error.

This page walks through how to create a platform plugin step-by-step. It's highly recommanded to review the examples before proceeding.

Preparation

The first requirement is to set up a proper development environment. In order to easily integrate the platform plugin into Anbox and avoid any ABI issues, the only available development environment is Ubuntu 18.04(64-bit). Using any other Ubuntu distributions is not recommended. Ubuntu 18.04 can be obtained from here.
The following build dependencies are needed to use the SDK.

$ sudo apt install build-essential cmake cmake-extras google-mock pkg-config \
libavcodec-dev libavformat-dev libelf-dev zlib1g-dev libegl1-mesa-dev

Create a CMake-based plugin project

The easiest way to build a plugin is to use the CMake (https://cmake.org/) build system for the plugin. A CMakeLists.txt file should be created and placed in the project root directory. In the plugin's CMakeLists.txt file, the SDK can be imported directly using find_package and setting the CMAKE_PREFIX_PATH to include a path to the SDK. Then the following target is imported and available to the rest of the cmake build process:

  • anbox-platform-sdk-internal - the SDK's interface library that must be linked against

The following is an example CMakeLists.txt which can be used to compile a plugin:

project(PLUGIN_PROJECT)
cmake_minimum_required(VERSION 3.1.3)
include(CTest)
enable_testing()
include(GNUInstallDirs)
if (NOT CMAKE_BUILD_TYPE)
message(STATUS "No build type selected, default to release")
set(CMAKE_BUILD_TYPE "release")
endif()
# Load the anbox-sdk cmake package
find_package(anbox-platform-sdk REQUIRED)
# Set platform plugin name. Please replace it with yours plugin name.
set(PLATFORM_PLUGIN_NAME "my-plugin")
# The path to platform plugin installation in Anbox
set(PLATFORM_INSTALL_DIR ${CMAKE_INSTALL_LIBDIR}/anbox/platforms/${PLATFORM_PLUGIN_NAME})
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -DPLATFORM_INSTALL_DIR=\\\"${CMAKE_INSTALL_PREFIX}/${PLATFORM_INSTALL_DIR}\\\"")
# Add the plugin target
set(PLUGIN_SOURCES ${PLATFORM_PLUGIN_NAME}_platform.cpp)
add_library(AnboxPlatformPlugin
SHARED ${PLUGIN_SOURCES})
# Link against the anbox-platform-sdk-internal library
target_link_libraries(AnboxPlatformPlugin PUBLIC
anbox-platform-sdk-internal)
# All platforms need to follow the naming scheme platform_<name>.so
set_target_properties(
AnboxPlatformPlugin PROPERTIES
OUTPUT_NAME platform_${PLATFORM_PLUGIN_NAME}
PREFIX ""
COMPILE_FLAGS "-std=c++14"
SUFFIX ".so"
INSTALL_RPATH "${CMAKE_INSTALL_PREFIX}/${PLATFORM_INSTALL_DIR}")
# Run the validation test suites against the platform implementation
# using the anbox-platform-tester executable from the sdk
# For all production ready platform plugin, all tests need to pass.
add_test(NAME CustomPlatformValidation
COMMAND ${ANBOX_PLATFORM_TESTER} ${CMAKE_CURRENT_BINARY_DIR}/platform_${PLATFORM_PLUGIN_NAME}.so)
# Install the platform plugin to the proper location in Anbox.
install(
TARGETS AnboxPlatformPlugin
LIBRARY DESTINATION ${PLATFORM_INSTALL_DIR}
)

A source file named <plugin_name>_platform.cpp is expected to reside in the project's root directory, alongside CMakeLists.txt. Below is how a platform plugin project layout looks like.

~/project_plugin$ tree
.
├── CMakeLists.txt
└── project_platform.cpp

This is the minimum required to start building an Anbox platform plugin. The example minimal platform provides a skeleton of raw platform plugin implementation that may be copied and modified for quicker development.

Build your platform plugin

As is shown in the CMakeLists.txt above, you have to specify CMAKE_PREFIX_PATH configuration setting where the Anbox Platform SDK is located via the CMake command-line interface. With it, CMake can easily find and include the SDK's interface library, header files and testing tool targets. You can run the following commands to build your plugin from the plugin's root directory.

$ cmake ./ -Bbuild -DCMAKE_PREFIX_PATH=<anbox-platform-sdk-path>
$ cd build
$ make -j$(nproc)

Test your platform plugin

The SDK supplies a tool called anbox-platform-tester which allows validation of platform plugin implementation. The anbox-platform-tester performs various tests to ensure the plugin is correctly implemented and behaves the way Anbox expect it to behave.
A platform plugin dynamic library can be tested with the anbox-platform-tester like this:

$ <path to anbox platform sdk>/bin/anbox-platform-tester <path to plugin>/platform_<platform name>.so

or simply run make test in the build directory.

$ CTEST_OUTPUT_ON_FAILURE=1 make && make test

The platform tester will print out a detailed report of the test results.

Note: A production ready platform plugin needs to pass all test cases without exceptions.