Skip to content

Cross Compiling BioGears for Android

Jump to bottom
Steven A White edited this page Jul 15, 2022 · 22 revisions

Cross compilation of Native C++ Libraries is an intermediate to expert skill that requires knowledge of the workings of compilers, linker, and system tool-chains in general. Android is a multi platform OS that can be deployed on over 5 processor architectures which further complicates the generation of documentation on how to generate Android builds. This documentation focuses on the generation of aarch64 builds fro targeting the majority of Android Mobile Phones. Targeting this platform requires familiarity with the Android Native Development Kit (NDK) and integration in to an APK requires familiarity of the Android Software Development Kit (SDK). Incorporating Bio Gears in to your own Android project is outside of scope of this documentation and we refer you to the following resources for learning how to make Android projects before attempting incorporation of a large project like BioGears in to your own project.

  1. Android NDK EXAMPLES
  2. Android Application Development

Instead this documentation focuses on the creation of Architecture appropriate binaries for libBioGears and its dependencies using the toolchain and compilers provided by the Android NDK. This documentation will call out specific versions of the Android NDK that were tested against the instructions. While other versions of the NDK should be able to compile BioGears for Android correctly, they are untested and may require additional instructional as compiler versions and header storage with in the NDK change over time. Additionally, methods of using CMake with the NDK are improving with each release and may be different then the NDKs referenced in these instructions. That said the NDK versions referenced in these instructions should provide compatible binaries for all Android phones up to 2022.

Warning: This documentation is intended for those failure with concepts of C++ and Mobile development. It assumes you are capable of setting up your own build environments and makes assumptions about your ability to manage your personal environment variables. This documentation is open source and does accept contributions to improve clarity

Requirements

  • Android NDK - android-ndk-r17c - Last GCC Release / Last gnustl release - June 2018
  • Android SDK - API Level 29 / 30 - 2019

Meta Build Scripts

CMakeLists.txt

For this documentation I will be referring to the BioGears MetaBuild CMakeLists.txt. The purpose of this file is to simplify gathering of all the required third party libraries needed to make a cross compilation. The script is attached to this documentation. This file was designed to assist Unreal Engine 4 in compiling BioGears as part of its own build process but can be used generically. It is an ongoing project and has mostly been tested for use with Windows cross compiling Android.

Example Use

 cmake -G "Unix Makefiles"  \
	-B "C:/biogears\build-android" \
	-S "C:/biogears" \
	-D CMAKE_BUILD_TYPE="Release" \ 
	-D CMAKE_MAKE_PROGRAM="C:/Program Files/Kitware/CMake/cmake.exe"
	-D CMAKE_TOOLCHAIN_FILE="%NDK_HOME%\build/cmake/" \
	-D ANDROID_STL="gnustl_shared" \
	-D ANDROID_CPP_FEATURES='rtti;exceptions' \
	-D ANDROID_ABI="arm64-v8a" \
        -D ANDROID_ARM_NEON="ON" \
	-D ANDROID_PLATFORM="android-24" \
	-D CMAKE_INSTALL_PREFIX="C:/biogears/install/android" \
	-D CMAKE_PREFIX_PATH="C:/biogears/external/windows" \
	-D CMAKE_FIND_ROOT_PATH="C:/biogears/install/android" \
	-D CMAKE_BUILD_TYPE="Release" \
	-D XERCES_C_transcoder="icu" \
	-D BG_META_PLATFORM="Android" \
	-D BG_META_ARCHITECTURE="arm64-v8a" \
	-D BG_META_CONFIGURATION="rel" \
	-D NATIVE_CODE_GENERATOR="Visual Studio 17 2022 Win64"

Instructions

Setting Up

No mater what system you are on you must first download the Android SDK and Android NDK. Due to changes in the STL and switch from g++ to clang. These instructions assume the use of the 17c NDK. Newer variants of the NDK should be able to build BioGears but some patches may be needed to other parts of the tool-chain. It is best if you do not install these components to your system, but instead create some Android folder on your system so you can manage multiple NDKs and SDKs. Create the following system variables

  • NDK_ROOT : Location of the folder named android-ndk-17c
  • SDK_ROOT : Location of the android SDK

Once this is done you will need to install the target API level and build tools for the Android SDK. This process has changed several times over the SDKs life time but can be done from the command line. The following instructions can be helpful if this is your first time using the SDK. Insttall API 30 and 29. You can save time by not installing any System Imageas they are only needed for emulation and are the largest components.

SDK Command Line SDK Gui

Building Third party Dependencies

BioGears Depends on the following projects

  • CodeSynthesisXSD
  • xerces-c
  • eigen

Of these the build requires Native executable for the Host of XSD and cross compiled libraries for xerces-c. Additionally the headers must be available to the cross compiler for all 3. When building xerces-c you need to know the available transcoder on the target system. On linux we default to the gnuiconv or libiconv, but for android we will need to make our own additional icu available.

The meta build will try to download native builds of XSD from the https://github.com/StevenAWhite/CodeSynthesisXSD-Binary.git. repository. This is currently supported for Linux and Windows, patches would be needed to support this for MacOS. It will additionally add icu from https://github.com/StevenAWhite/icu-cmake.git when targeting ANDROID and references it when building Xerces-C. If you choose to manually build these libraries you should compile them in the following order and install them in to the same location prior to building biogears

  1. XSD
  2. icu/gnuiconv
  3. xerces-c
  4. eigen

For each project you will need to configure a CMake by specifying the android-toolchain and android configuration manually.

    cmake-G "GNU Makefiles"
          -D CMAKE_TOOLCHAIN_FILE:<NDK_ROOT>/build/cmake/android.toolchain.cmake
          -D ANDROID_STL:gnustl_shared \
	  -D ANDROID_CPP_FEATURES:STRING="rtti;exceptions" \
          -D ANDROID_ABI:arm64-v8a \
          -D ANDROID_ARM_NEON:BOOL=ON \
          -D ANDROID_PLATFORM:android-29 \
          -D CMAKE_FIND_ROOT_PATH:/PATH/TO/TARGET/LIBS \
          -D CMAKE_PREFIX_PATH:/PATH/TO/NATIVE/EXEUTABLES \
          -D CMAKE_INSTALL_PREFIX:/PATH/TO/INSTALL/DIRECTORY

Verifying your Build

Verifying your build is simplest on linux where the file command can be used to verify the processor type of a .so file.

 file /mnt/e/burncare/ThirdParty/Artifacts/Android/arm64-v8a/rel/lib/libxerces-c-3.2.so
/mnt/e/burncare/ThirdParty/Artifacts/Android/arm64-v8a/rel/lib/libxerces-c-3.2.so: ELF 64-bit LSB shared object, ARM aarch64, version 1 (SYSV), dynamically linked, BuildID[sha1]=19f7fba7d8f5c6ba481ef3f3483103c716f4c8fe, with debug_info, not stripped

On Windows platforms you may need to install WSL/Cygwin or a windows port of File to verify the build. However, generally the extension of .so is enough to know you properly cross compiled to a non windows architecture, while on linux and macos care must be taken to ensure the resulting file is cross compiled as the file name does not change.

Other warnings

The Android DLL loader can be problematic. There are multiple ways to manually load DLLs in memory in your executable. Refer to System.loadLibrary(String library); for additional information, but remember that order of these loadLIbrary calls maters and can avoid errors. If your app crashes while loading DLLs you can refer to logcat for more information, but the usual resolution is to load the dlls in the same order as compiled. Typically

  1. icu
  2. xerces_c
  3. libbiogears_cdm
  4. libbiogears_io
  5. libbiogears
Clone this wiki locally