BuildGuideAndroidNDK.md

   1 # How to use the Android NDK to build ArmNN
   2
   3 - [Introduction](#introduction)
   4 - [Download the Android NDK and make a standalone toolchain](#download-the-android-ndk-and-make-a-standalone-toolchain)
   5 - [Build the Boost C++ libraries](#build-the-boost-c---libraries)
   6 - [Build the Compute Library](#build-the-compute-library)
   7 - [Build Google's Protobuf library](#build-google-s-protobuf-library)
   8 - [Download TensorFlow](#download-tensorflow)
   9 - [Build ArmNN](#build-armnn)
  10 - [Build Standalone Sample Dynamic Backend](#build-standalone-sample-dynamic-backend)
  11 - [Run the ArmNN unit tests on an Android device](#run-the-armnn-unit-tests-on-an-android-device)
  12
  13
  14 ## Introduction
  15 These are step by step instructions for using the Android NDK to build ArmNN.
  16 They have been tested on a clean install of Ubuntu 18.04, and should also work with other OS versions.
  17 The instructions show how to build the ArmNN core library and the optional TensorFlow parser.
  18 All downloaded or generated files will be saved inside the `~/armnn-devenv` directory.
  19
  20 ## Download the Android NDK and make a standalone toolchain
  21
  22 * Download the Android NDK from [the official website](https://developer.android.com/ndk/downloads/index.html):
  23  ```bash
  24  mkdir -p ~/armnn-devenv/toolchains
  25  cd ~/armnn-devenv/toolchains
  26  # For Mac OS, change the NDK download link accordingly.
  27  wget https://dl.google.com/android/repository/android-ndk-r20b-linux-x86_64.zip
  28  unzip android-ndk-r20b-linux-x86_64.zip
  29  export NDK=~/armnn-devenv/android-ndk-r20b
  30  export NDK_TOOLCHAIN_ROOT=$NDK/toolchains/llvm/prebuilt/linux-x86_64
  31  export PATH=$NDK_TOOLCHAIN_ROOT/bin/:$PATH
  32
  33  # You may want to append the above export variables commands to your `~/.bashrc` (or `~/.bash_profile` in Mac OS).
  34  ```
  35
  36 * With the android ndk-20b, you don't need to use the make_standalone_toolchain script to create a toolchain for a specific version of android. Android's current preference is for you to just specify the architecture and operating system while setting the compiler and just use the ndk directory.
  37
  38 ## Build the Boost C++ libraries
  39
  40 * Download Boost version 1.64:
  41 ```bash
  42 mkdir ~/armnn-devenv/boost
  43 cd ~/armnn-devenv/boost
  44 wget https://dl.bintray.com/boostorg/release/1.64.0/source/boost_1_64_0.tar.bz2
  45 tar xvf boost_1_64_0.tar.bz2
  46 ```
  47
  48 * Build:
  49
  50         (Requires clang if not previously installed: `sudo apt-get install clang`)
  51
  52     Note: You can specify the 'Android_API' version you want. For example, if your ANDROID_API is 27 then the compiler will be aarch64-linux-android27-clang++.
  53 ```bash
  54 echo "using clang : arm : aarch64-linux-android<Android_API>-clang++ ;" > $HOME/armnn-devenv/boost/user-config.jam
  55 cd ~/armnn-devenv/boost/boost_1_64_0
  56 ./bootstrap.sh --prefix=$HOME/armnn-devenv/boost/install
  57 ./b2 install --user-config=$HOME/armnn-devenv/boost/user-config.jam \
  58  toolset=clang-arm link=static cxxflags=-fPIC \
  59  --with-test --with-log --with-program_options -j16
  60 ```
  61
  62 ## Build the Compute Library
  63 * Clone the Compute Library:
  64
  65         (Requires Git if not previously installed: `sudo apt install git`)
  66 ``` bash
  67 cd ~/armnn-devenv
  68 git clone https://github.com/ARM-software/ComputeLibrary.git
  69 ```
  70
  71 * Checkout ComputeLibrary branch:
  72 ```bash
  73 cd ComputeLibrary
  74 git checkout <branch_name>
  75 git pull
  76 ```
  77 For example, if you want to checkout release branch of 20.02:
  78 ```bash
  79 git checkout branches/arm_compute_20_02
  80 git pull
  81 ```
  82
  83 * Build:
  84
  85         (Requires SCons if not previously installed: `sudo apt install scons`)
  86 ```bash
  87 scons arch=arm64-v8a neon=1 opencl=1 embed_kernels=1 extra_cxx_flags="-fPIC" \
  88  benchmark_tests=0 validation_tests=0 os=android -j16
  89 ```
  90
  91 ## Build Google's Protobuf library
  92
  93 * Clone protobuf:
  94 ```bash
  95 mkdir ~/armnn-devenv/google
  96 cd ~/armnn-devenv/google
  97 git clone https://github.com/google/protobuf.git
  98 cd protobuf
  99 git checkout -b v3.12.0 v3.12.0
 100 ```
 101
 102 * Build a native (x86) version of the protobuf libraries and compiler (protoc):
 103
 104         (Requires cUrl, autoconf, llibtool, and other build dependencies if not previously installed: `sudo apt install curl autoconf libtool build-essential g++`)
 105 ```bash
 106 ./autogen.sh
 107 mkdir x86_build
 108 cd x86_build
 109 ../configure --prefix=$HOME/armnn-devenv/google/x86_pb_install
 110 make install -j16
 111 cd ..
 112 ```
 113
 114 * Build the arm64 version of the protobuf libraries:
 115 ```bash
 116 mkdir arm64_build
 117 cd arm64_build
 118 CC=aarch64-linux-android<Android_API>-clang \
 119 CXX=aarch64-linux-android<Android_API>-clang++ \
 120 CFLAGS="-fPIE -fPIC" \
 121     LDFLAGS="-llog -lz -lc++_static" \
 122    ../configure --host=aarch64-linux-android \
 123    --prefix=$HOME/armnn-devenv/google/arm64_pb_install \
 124    --enable-cross-compile \
 125    --with-protoc=$HOME/armnn-devenv/google/x86_pb_install/bin/protoc
 126 make install -j16
 127 cd ..
 128 ```
 129
 130 ## Download TensorFlow
 131 * Clone TensorFlow source code:
 132 ```bash
 133 cd ~/armnn-devenv/google/
 134 git clone https://github.com/tensorflow/tensorflow.git
 135     cd tensorflow/
 136     git checkout fcc4b966f1265f466e82617020af93670141b009
 137 ```
 138
 139 ## Build ArmNN
 140
 141 * Clone ArmNN source code:
 142 ```bash
 143 cd ~/armnn-devenv/
 144 git clone https://github.com/ARM-software/armnn.git
 145 ```
 146
 147 * Checkout ArmNN branch:
 148 ```bash
 149 cd armnn
 150 git checkout <branch_name>
 151 git pull
 152 ```
 153
 154 For example, if you want to checkout release branch of 20.02:
 155 ```bash
 156 git checkout branches/armnn_20_02
 157 git pull
 158 ```
 159
 160 * Generate TensorFlow protobuf definitions:
 161 ```bash
 162 cd ~/armnn-devenv/google/tensorflow
 163 ~/armnn-devenv/armnn/scripts/generate_tensorflow_protobuf.sh \
 164  $HOME/armnn-devenv/google/tf_pb $HOME/armnn-devenv/google/x86_pb_install
 165 ```
 166
 167 * Build ArmNN:
 168
 169         (Requires CMake if not previously installed: `sudo apt install cmake`)
 170 ```bash
 171 mkdir ~/armnn-devenv/armnn/build
 172 cd ~/armnn-devenv/armnn/build
 173 CXX=aarch64-linux-android<Android_API>-clang++ \
 174 CC=aarch64-linux-android<Android_API>-clang \
 175 CXX_FLAGS="-fPIE -fPIC" \
 176 cmake .. \
 177     -DCMAKE_ANDROID_NDK=$NDK \
 178     -DCMAKE_SYSTEM_NAME=Android \
 179     -DCMAKE_SYSTEM_VERSION=<Android_API> \
 180     -DCMAKE_ANDROID_ARCH_ABI=arm64-v8a \
 181     -DCMAKE_EXE_LINKER_FLAGS="-pie -llog -lz" \
 182     -DARMCOMPUTE_ROOT=$HOME/armnn-devenv/ComputeLibrary/ \
 183     -DARMCOMPUTE_BUILD_DIR=$HOME/armnn-devenv/ComputeLibrary/build \
 184     -DBOOST_ROOT=$HOME/armnn-devenv/boost/install/ \
 185     -DARMCOMPUTENEON=1 -DARMCOMPUTECL=1 -DARMNNREF=1 \
 186     -DTF_GENERATED_SOURCES=$HOME/armnn-devenv/google/tf_pb/ -DBUILD_TF_PARSER=1 \
 187     -DPROTOBUF_ROOT=$HOME/armnn-devenv/google/arm64_pb_install/
 188 ```
 189
 190 To include standalone sample dynamic backend tests, add the argument to enable the tests and the dynamic backend path to the CMake command:
 191
 192 ```bash
 193 -DSAMPLE_DYNAMIC_BACKEND=1 \
 194 -DDYNAMIC_BACKEND_PATHS=$SAMPLE_DYNAMIC_BACKEND_PATH
 195 # Where $SAMPLE_DYNAMIC_BACKEND_PATH is the path where libArm_SampleDynamic_backend.so library file is pushed
 196 ```
 197
 198  * Run the build
 199 ```bash
 200 make -j16
 201 ```
 202
 203 ## Build Standalone Sample Dynamic Backend
 204 * The sample dynamic backend is located in armnn/src/dynamic/sample
 205 ```bash
 206 mkdir build
 207 cd build
 208 ```
 209
 210 * Use CMake to configure the build environment, update the following script and run it from the armnn/src/dynamic/sample/build directory to set up the armNN build:
 211 ```bash
 212 #!/bin/bash
 213 CXX=aarch64-linux-android<Android_API>-clang++ \
 214 CC=aarch64-linux-android<Android_API>-clang \
 215 CXX_FLAGS="-fPIE -fPIC" \
 216 cmake \
 217 -DCMAKE_SYSTEM_NAME=Android \
 218 -DCMAKE_CXX_FLAGS=--std=c++14 \
 219 -DCMAKE_EXE_LINKER_FLAGS="-pie -llog" \
 220 -DCMAKE_MODULE_LINKER_FLAGS="-llog" \
 221 -DBOOST_ROOT=$HOME/armnn-devenv/boost/install \
 222 -DBoost_SYSTEM_LIBRARY=$HOME/armnn-devenv/boost/install/lib/libboost_system.a \
 223 -DARMNN_PATH=$HOME/armnn-devenv/armnn/build/libarmnn.so ..
 224 ```
 225
 226 * Run the build
 227 ```bash
 228 make
 229 ```
 230
 231 ## Run the ArmNN unit tests on an Android device
 232
 233
 234 * Push the build results to an Android device and make symbolic links for shared libraries:
 235   Currently adb version we have used for testing is 1.0.41.
 236 ```bash
 237 adb push libarmnnTfParser.so /data/local/tmp/
 238 adb push libarmnn.so /data/local/tmp/
 239     adb push libtimelineDecoder.so /data/local/tmp/
 240 adb push UnitTests /data/local/tmp/
 241 adb push $NDK/sources/cxx-stl/llvm-libc++/libs/arm64-v8a/libc++_shared.so /data/local/tmp/
 242 adb push $HOME/armnn-devenv/google/arm64_pb_install/lib/libprotobuf.so /data/local/tmp/libprotobuf.so.23.0.0
 243 adb shell 'ln -s libprotobuf.so.23.0.0 /data/local/tmp/libprotobuf.so.23'
 244 adb shell 'ln -s libprotobuf.so.23.0.0 /data/local/tmp/libprotobuf.so'
 245 ```
 246
 247 * Push the files needed for the unit tests (they are a mix of files, directories and symbolic links):
 248 ```bash
 249 adb shell mkdir -p /data/local/tmp/src/backends/backendsCommon/test/testSharedObject
 250 adb push -p ~/armnn-devenv/armnn/build/src/backends/backendsCommon/test/testSharedObject/* /data/local/tmp/src/backends/backendsCommon/test/testSharedObject/
 251
 252 adb shell mkdir -p /data/local/tmp/src/backends/backendsCommon/test/testDynamicBackend
 253 adb push -p ~/armnn-devenv/armnn/build/src/backends/backendsCommon/test/testDynamicBackend/* /data/local/tmp/src/backends/backendsCommon/test/testDynamicBackend/
 254
 255 adb shell mkdir -p /data/local/tmp/src/backends/backendsCommon/test/backendsTestPath1
 256 adb push -p ~/armnn-devenv/armnn/build/src/backends/backendsCommon/test/backendsTestPath1/* /data/local/tmp/src/backends/backendsCommon/test/backendsTestPath1/
 257
 258 adb shell mkdir -p /data/local/tmp/src/backends/backendsCommon/test/backendsTestPath2
 259 adb push -p ~/armnn-devenv/armnn/build/src/backends/backendsCommon/test/backendsTestPath2/Arm_CpuAcc_backend.so /data/local/tmp/src/backends/backendsCommon/test/backendsTestPath2/
 260 adb shell ln -s Arm_CpuAcc_backend.so /data/local/tmp/src/backends/backendsCommon/test/backendsTestPath2/Arm_CpuAcc_backend.so.1
 261 adb shell ln -s Arm_CpuAcc_backend.so.1 /data/local/tmp/src/backends/backendsCommon/test/backendsTestPath2/Arm_CpuAcc_backend.so.1.2
 262 adb shell ln -s Arm_CpuAcc_backend.so.1.2 /data/local/tmp/src/backends/backendsCommon/test/backendsTestPath2/Arm_CpuAcc_backend.so.1.2.3
 263 adb push -p ~/armnn-devenv/armnn/build/src/backends/backendsCommon/test/backendsTestPath2/Arm_GpuAcc_backend.so /data/local/tmp/src/backends/backendsCommon/test/backendsTestPath2/
 264 adb shell ln -s nothing /data/local/tmp/src/backends/backendsCommon/test/backendsTestPath2/Arm_no_backend.so
 265
 266 adb shell mkdir -p /data/local/tmp/src/backends/backendsCommon/test/backendsTestPath3
 267
 268 adb shell mkdir -p /data/local/tmp/src/backends/backendsCommon/test/backendsTestPath5
 269 adb push -p ~/armnn-devenv/armnn/build/src/backends/backendsCommon/test/backendsTestPath5/* /data/local/tmp/src/backends/backendsCommon/test/backendsTestPath5/
 270
 271 adb shell mkdir -p /data/local/tmp/src/backends/backendsCommon/test/backendsTestPath6
 272 adb push -p ~/armnn-devenv/armnn/build/src/backends/backendsCommon/test/backendsTestPath6/* /data/local/tmp/src/backends/backendsCommon/test/backendsTestPath6/
 273
 274 adb shell mkdir -p /data/local/tmp/src/backends/backendsCommon/test/backendsTestPath7
 275
 276 adb shell mkdir -p /data/local/tmp/src/backends/backendsCommon/test/backendsTestPath9
 277 adb push -p ~/armnn-devenv/armnn/build/src/backends/backendsCommon/test/backendsTestPath9/* /data/local/tmp/src/backends/backendsCommon/test/backendsTestPath9/
 278
 279 adb shell mkdir -p /data/local/tmp/src/backends/dynamic/reference
 280 adb push -p ~/armnn-devenv/armnn/build/src/backends/dynamic/reference/Arm_CpuRef_backend.so /data/local/tmp/src/backends/dynamic/reference/
 281
 282 # If the standalone sample dynamic tests are enabled, also push libArm_SampleDynamic_backend.so library file to the folder specified as $SAMPLE_DYNAMIC_BACKEND_PATH when ArmNN is built.
 283 # This is the example when $SAMPLE_DYNAMIC_BACKEND_PATH is specified as /data/local/tmp/dynamic/sample/:
 284
 285 adb shell mkdir -p /data/local/tmp/dynamic/sample/
 286 adb push -p ${WORKING_DIR}/armnn/src/dynamic/sample/build/libArm_SampleDynamic_backend.so /data/local/tmp/dynamic/sample/
 287 ```
 288
 289 * Run ArmNN unit tests:
 290 ```bash
 291 adb shell 'LD_LIBRARY_PATH=/data/local/tmp:/vendor/lib64:/vendor/lib64/egl /data/local/tmp/UnitTests'
 292 ```
 293 If libarmnnUtils.a is present in `~/armnn-devenv/armnn/build/` and the unit tests run without failure then the build was successful.