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