# Android ## Introduction ApertusVR is a cross platform library, which means, we support various operating systems, included Android, as well. The following guide will go through a step-by-step tutorial on how you can build the source code for Android using a Windows PC. ![](https://4044724383-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LEyKyxZqxfQ560k-THK%2F-MGNDNmS3xyVu_L_utd-%2F-MGNGk6m0gKqqQsBSfoO%2Fimage.png?alt=media\&token=2c18f63e-e21d-4f98-8ec7-00c52a156915) If you are new to Android development, we highly recommend you to read the official [Android documentations](https://developer.android.com/docs). From now on, we will assume, that you are familiar, at least with the basics. ## Requirements For the cross compilation process, you have to obtain the following softwares: * [Android Studio](https://developer.android.com/studio) v. 3.6 or later versions (any other tools related with Android Studio will be discussed in the *Configuring Android Studio* section) * [Git](https://git-scm.com/) for Windows ## Download Android build source. Just like the other parts of the library, the Android source files are [hosted on GitHub](https://github.com/MTASZTAKI/ApertusVR). To obtain it, you have to make a folder for it on your personal Windows device. In this tutorial we will assume, that your chosen folder is **C:\ApertusVR**. Clone the default branch from[ ApertusVR github](https://github.com/MTASZTAKI/ApertusVR): `$ git clone https://github.com/MTASZTAKI/ApertusVR.git` If everything worked properly, you should see something similar to the picture below ![C:\ApertusVR\\](https://4044724383-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LEyKyxZqxfQ560k-THK%2F-MGNDNmS3xyVu_L_utd-%2F-MGNRAOL0NUDrEn1-YQK%2Fimage.png?alt=media\&token=e251e089-dc13-4bf0-a723-81ec73bddb9d) For building from source you will have to build the `apertusvr` and the `filamentRender` modules separately. We will discuss both of them and the setting up of Android S tudio in the following paragraphs. ## Configuring Android Studio For Android Studio to work properly, you will need the following toolsets: 1. Android SDK 2. Android NDK ### Android SDK ApertusVR supports Android 6.0 (Marshmallow) or higher versions. In correlation with this, the library works with API level 23, or later releases. This implies, that according to the [SDK Platform release notes](https://developer.android.com/studio/releases/platforms), the minimum requirement is: * Android SDK Platform-tools r23 * Android SDK Tools 24.3.4 If Android Studio does not find any of the Android SDK versions, it will offer you to download the latest release. This may not be the version you want (e.g. your debugging Anroid device only supports former versions), so you can also download other releases in **Settings > System Settings > Android SDK > SDK Tools**. ### Android NDK The ApertusVR library is written in C++, which means, in order to build on Android, we use the native language toolset provided by Google, called *Android NDK* (native developement kit). For more information see the official [Android NDK documentation](https://developer.android.com/ndk). The version we use is **21.0.611369**. You can download it with Android Studio's [SDK Manager](https://developer.android.com/studio/intro/update#sdk-manager). Go **Settings > Appearance & Behavior > System Settings > Android SDK > SDK Tools**. Then click **Show Package Details** in the bottom right corner. Choose **NDK (Side by side) 21.0.611369**, but do not click on Apply yet. ApertusVR uses [CMake](https://cmake.org/) as its main build tool. Good news is that Android Studio accidentally has support for CMake projects too. In order to use it, on the same page where you picked the NDK version, you can mark the appropriate CMake version, which is **3.10.2**. ![NDK and CMake in the Android SDK manager.](https://4044724383-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LEyKyxZqxfQ560k-THK%2F-MGNDNmS3xyVu_L_utd-%2F-MGNRa7aOBQTbG7guvd9%2Fimage.png?alt=media\&token=a9ce3c95-00f1-496b-a1e8-864afc79d32e) Then click Apply, and wait until the install finishes. ## Building the ApertusVR library If you deployed everything as discussed above, we can actually start to build our source files. However, before we dive into it, we will go through some important notes, which helps you understand the build process. ### Project structure Now if you open the **C:\ApertusVR\plugins\languageAPI\\** folder, you should see something like this: ![C:\ApertusVR\plugins\languageAPI\\](https://4044724383-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LEyKyxZqxfQ560k-THK%2F-MGNDNmS3xyVu_L_utd-%2F-MGNSsE4byuu-PjRSUvY%2Fimage.png?alt=media\&token=d48fc2ce-9717-4050-a34a-19ffa8f6f33a) Here the most important for us, is the **java** subfolder, which contains the Android Studio project. Let's see what we can find in it! Open Android Studio, and go **File > Open**, then navigate to the project folder, and click Ok to open the project file. When it is opened, it may takes some time for Android Studio to configure the project. If it is done, open the left panel called **1:Project:** ![](https://4044724383-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LEyKyxZqxfQ560k-THK%2F-MGNDNmS3xyVu_L_utd-%2F-MGNU0EgmZ2gc_A9p-lL%2Fimage.png?alt=media\&token=88529689-6f75-457a-8b48-2cf38755c3ea) If it is not in Android view, change it: ![](https://4044724383-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LEyKyxZqxfQ560k-THK%2F-MGNDNmS3xyVu_L_utd-%2F-MGNVtNbkgOQei_M0hVF%2Fimage.png?alt=media\&token=3e380e9d-dcf9-4a8d-accd-c9dee0062b71) Now we can see how the project structure actually looks like. The following lines will explain what you see on the right picture. The `apertusvr`Android library containing java (and c++) files. This librarie will become Android archive files (\*.aar), similar to a Java archive file (\*.jar). It contains the ApertusCore C++ library, and the consisting [JNI](https://developer.android.com/training/articles/perf-jni)-binds and wrappers. If you are not familiar with the ApertusVR architecture, check out the [Developers/Architecture](https://apertus.gitbook.io/vr/developers/architecture) chapter in the documentation. The module embraces the whole ApertusVR C++ project, which consists of shared libraries. These shared libs are all linked against the `apeJNIStarter`, which is also a shared library. Then `apeJNIStarter` and `apeJNIPlugin` (the library which implements the JNI-binds) are loaded in the ApertusJNI class file with Java's `System.loadLibrary()`. ### Dependencies In this subsection we discuss what are the dependencies of the Android build, and what you should know about them. ApertusVR is dependent on several 3rd party libraries. The three most important for ApertusCore are the followings: * [cURL](https://curl.haxx.se/) * [RakNet](http://www.jenkinssoftware.com/) * [Zip](https://github.com/kuba--/zip) And we use the mentioned Filament engine for rendering. All of them are included as a prebuilt library except RakNet, which was added as a subdirectory in the CMake project. The prebuilt C++ library dependencies are stored in the **ApertusVR\androidx\libs** folder. Note that, because cURL is dependent on the [OpenSSL library](https://www.openssl.org/), you can find its prebuilt \*.so files in the libs folder too.\ If you want your own build (e.g. you need a specific version) you have to build them for each supported Android ABI. To do that follow the instructions in OpenSSL's and cURL's github repository: {% embed url="" %} {% embed url="" %} You can also build your own Zip version for Android. The easiest way to do it, is with CMake and [Ninja](https://ninja-build.org/), by providing a toolchain file for cross-compiling (the same you use for the ApertusVR-Android) build, e.g. the **android.toolchain.cmake** file in the **...\AndroidSdk\ndk\\\\build\cmake** folder. ![](https://4044724383-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LEyKyxZqxfQ560k-THK%2F-MDEr-Lk_FH5szC2nmyN%2F-MDErYko98jN5l7fT3hM%2Fcmake-ninja.png?alt=media\&token=473f462c-4aa4-4a1a-9f17-d16932cf7502) ![](https://4044724383-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LEyKyxZqxfQ560k-THK%2F-MDEr-Lk_FH5szC2nmyN%2F-MDEraSrWid_Ec6xHHgS%2Fcmake-ninja2.png?alt=media\&token=0a4c9512-403b-4c61-a2a0-fdc29d757138) Then you should manually set the CMake flags for a specific ABI, generate, then repeate with an other ABI... Then you can obtain the builds using Ninja. Lastly, Filament is included as an Android archive file, you can find it in: **ApertusVR\plugins\render\apefilamentrender\libs\\**. If you want newer version, you have to replace what you found in this folder, then modify the `build.gradle` file (see in the next subsection). ### Gradle Android Studio uses the build automation tool called *Gradle*. We will only discuss what we need to build the source code, but further information about the build tool can be found on the [official website](https://gradle.org/). For each existing component of our project (e.g. libraries) we have a corresponding `build.gradle` file. Other than that, we also have a `build.gradle` file for the whole project, where you can configure options for all modules globally. And lastly there is a `settings.gradle` file, where you can modify the project settings (e.g. including other modules). You can see these on the picture below. ![](https://4044724383-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LEyKyxZqxfQ560k-THK%2F-MGNDNmS3xyVu_L_utd-%2F-MGNZV4wAohn4Ep-mx9Y%2Fimage.png?alt=media\&token=9da8e9cf-cc2f-43b5-9688-e5e8326c3ddf) What is most important for us, in the first place is the `build.gradle (ApertusVR)`. If you open it, you should see in the `allprojects` configuration that there's a variable called `buildDir`. Currently it looks like this: ```groovy allprojects { repositories { google() jcenter() } buildDir = "c:/ApertusVR/build/android/${rootProject.name}/${project.name}" } ``` Here you can see, that the basic configuration is that the build directory of your project will be **C:\ApertusVR\build\android**. If you want your built files put somewhere else, you should set this variable to point to the appropriate directory. So, if you want your build files to be at **D:\FooBar\\**, then type `buildDir = "d:/FooBar/${rootProject.name}/${project.name}"`. #### CMake and NDK As you know, the ApertusVR library is written in C++14, and we use CMake for build automation. When you look at the `build.gradle (:apertusvr)` file, you should see the following commands: ```groovy externalNativeBuild { cmake { path file('../../../CMakeLists.txt') } } ``` This tells Gradle, that we want to include a CMake project into our Android library, but we also have to tell Gradle where is our root **CMakeLists.txt** file. If, for some reason you want to change the project structure, you should modify this for Gradle, to be able to find the CMake project, which builds the ApertusVR C++ library. If it is done, then the rest of the native build is only depends on the CMake project. The second thing, you should pay attention to, is in the `defaultConfig`: ```groovy externalNativeBuild { cmake { cppFlags "-std=c++14" } } ndk { abiFilters 'arm64-v8a', 'armeabi-v7a', 'x86' } ``` With these commands, we tell Gradtle, that: * We want C++14 version support of STL for our native C++ project. * Our native project only works with 'arm64-v8a', 'armeabi-v7a' and 'x86' [ABI](https://developer.android.com/ndk/guides/abis) filters. **SDK version** As it has been said, basically we support AndroidSDK version 23 and higher. You can change this per module in the defualtConfig: ```groovy defaultConfig { //... minSdkVersion 23 targetSdkVersion 29 //... } ``` #### Dependencies in Filamnetrender First you need to open the `filamentrender` module: Open Android Studio, and go **File > Open**, then navigate to the project folder **C:\ApertusVR\plugins\render\filamentRender**, and click Ok to open the project file. When it is opened, it may takes some time for Android Studio to configure the project. If it is done, open the left panel called **1:Project:** The 3rd party JVM dependencies used by the modules (like Filament) are included with the `api` command. E.g. in the Filament case it looks like this in `build.gradle(:apefilamentrender)` ```groovy dependencies { //... api(name: 'filament-20200403-android', ext: 'aar') api(name: 'apertusvr-091-android', ext: 'aar') } ``` If you want to add other dependencies, or change Filament to a new version, you have to copy it's \*.aar file into the **.../\/libs/** folder, or if you want to use other folder, you have to change the `flatDir` in `build.gradle(ApertusVR-Android)`: ```groovy allprojects { repositories { // ... flatDir { dirs 'libs' } } // ... } ``` ### Start the build If you configured both `apertusvr` and `filamentRender` projects for your own wish, based on the text below, you can finally start the build by clicking **Build > Make Project** (or by using the small green hammer) for both. First you will need to build `apertusvr`. You will get several warning during the build process, but you shouldn't bother yourself with them, they won't cause any runtime misbehaviour. So if you see something similar like on the picture below, your build is fine: ![](https://4044724383-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LEyKyxZqxfQ560k-THK%2F-MCq1NKdMSWnzomIJYEE%2F-MCq3vAxt6Uxbm6DG1lX%2FBUILD_SUCCESFUL.png?alt=media\&token=024e431e-4d95-4fcc-a0b5-db1d279260ab) If the build is successful then you need to copy the generated .aar file from here: **C:\ApertusVR\build\android\ApertusVR\apertusvr\outputs\aar\\** \ into here: \ **C:\ApertusVR\plugins\render\filamentRender\apefilamentrender\libs**\ and rename it to `apertusvr-091-android`. However, there's one thing remaining before you can enjoy the pleasures of programming with ApertusVR on Android. ### Debugging Everything you need to know about debugging is here: {% content-ref url="../installation/android-install" %} [android-install](https://apertus.gitbook.io/vr/installation/android-install) {% endcontent-ref %}