docs/howto/how-to-build-runtime.md

   1 # How to Build Runtime
   2
   3 This document is based on the system where Ubuntu Desktop Linux 18.04 LTS is installed with default settings, and can be applied in other environments without much difference. For reference, the development of our project started in the Ubuntu Desktop Linux 16.04 LTS environment.
   4
   5 ## Build requirements
   6
   7 If you are going to build this project, the following modules must be installed on your system:
   8
   9 - CMake
  10 - Boost C++ libraries
  11
  12 In the Ubuntu, you can easily install it with the following command.
  13
  14 ```
  15 $ sudo apt-get install cmake libboost-all-dev
  16 ```
  17
  18 If your linux system does not have the basic development configuration, you will need to install more packages. A list of all packages needed to configure the development environment can be found in the https://github.com/Samsung/ONE/blob/master/infra/docker/Dockerfile.1804 file.
  19
  20 Here is a summary of it
  21
  22 ```
  23 $ sudo apt install \
  24 build-essential \
  25 clang-format-3.9 \
  26 cmake \
  27 doxygen \
  28 git \
  29 graphviz \
  30 hdf5-tools \
  31 lcov \
  32 libatlas-base-dev \
  33 libboost-all-dev \
  34 libgflags-dev \
  35 libgoogle-glog-dev \
  36 libgtest-dev \
  37 libhdf5-dev \
  38 libprotobuf-dev \
  39 protobuf-compiler \
  40 pylint \
  41 python3 \
  42 python3-pip \
  43 python3-venv \
  44 scons \
  45 software-properties-common \
  46 unzip \
  47 wget
  48
  49 $ mkdir /tmp/gtest
  50 $ cd /tmp/gtest
  51 $ cmake /usr/src/gtest
  52 $ make
  53 $ sudo mv *.a /usr/lib
  54
  55 $ pip install yapf==0.22.0 numpy
  56
  57 ```
  58
  59 ## Build from source code, for Ubuntu
  60
  61 In a typical linux development environment, including Ubuntu, you can build the runtime with a simple command like this:
  62
  63 ```
  64 $ git clone https://github.com/Samsung/ONE.git one
  65 $ cd one
  66 $ cp -n Makefile.template Makefile; make install
  67 ```
  68
  69 Unfortunately, the debug build on the x86_64 architecture currently has an error. To solve the problem, you must use gcc version 9 or higher. Another workaround is to do a release build rather than a debug build. This is not a suitable method for debugging during development, but it is enough to check the function of the runtime. To release build the runtime, add the environment variable `BUILD_TYPE=release` to the build command as follows.
  70
  71 ```
  72 $ export BUILD_TYPE=release
  73 $ make install
  74 ```
  75
  76 Or you can simply do something like this:
  77
  78 ```
  79 $ BUILD_TYPE=release make install
  80 ```
  81
  82 The build method described here is a `native build` in which the build environment and execution environment are same. So, this command creates a runtime binary targeting the current build architecture, probably x86_64, as the execution environment. You can find the build output in the ./Product folder as follows:
  83
  84 ```
  85 $ tree -L 2 ./Product
  86 ./Product
  87 ├── obj -> /home/sjlee/star/one/Product/x86_64-linux.debug/obj
  88 ├── out -> /home/sjlee/star/one/Product/x86_64-linux.debug/out
  89 └── x86_64-linux.debug
  90     ├── BUILD
  91     ├── CONFIGURE
  92     ├── INSTALL
  93     ├── obj
  94     └── out
  95
  96 5 directories, 3 files
  97
  98 $ tree -L 3 ./Product/out
  99 ./Product/out
 100 ├── bin
 101 │   ├── nnapi_test
 102 │   ├── nnpackage_run
 103 │   ├── tflite_loader_test_tool
 104 │   └── tflite_run
 105 ├── include
 106 │   ├── nnfw
 107 │   │   ├── NeuralNetworksEx.h
 108 │   │   ├── NeuralNetworksExtensions.h
 109 │   │   ├── NeuralNetworks.h
 110 │   │   ├── nnfw_dev.h
 111 │   │   └── nnfw.h
 112 │   └── onert
 113 │       ├── backend
 114 │       ├── compiler
 115 │       ├── exec
 116 │       ├── ir
 117 │       ├── misc
 118 │       └── util
 119 ├── lib
 120 │   ├── libbackend_cpu.so
 121 │   ├── libcircle_loader.so
 122 │   ├── libneuralnetworks.so
 123 │   ├── libnnfw-dev.so
 124 │   ├── libnnfw_lib_benchmark.so
 125 │   ├── libnnfw_lib_misc.a
 126 │   ├── libonert_core.so
 127 │   └── libtflite_loader.so
 128 ├── tests
 129 │   ├── FillFrom_runner
 130 │   ├── nnpkgs
 131 │   │   └── FillFrom
 132 │   └── scripts
 133 │       ├── benchmark_nnapi.sh
 134 │       ├── benchmark_nnpkg.sh
 135 │       ├── common.sh
 136 │       ├── framework
 137 │       ├── list
 138 │       ├── print_to_json.sh
 139 │       ├── test-driver.sh
 140 │       ├── test_framework.sh
 141 │       ├── test_scheduler_with_profiling.sh
 142 │       └── unittest.sh
 143 ├── unittest
 144 │   ├── nnapi_gtest
 145 │   ├── nnapi_gtest.skip
 146 │   ├── nnapi_gtest.skip.noarch.interp
 147 │   ├── nnapi_gtest.skip.x86_64-linux.cpu
 148 │   ├── test_compute
 149 │   ├── test_onert
 150 │   ├── test_onert_backend_cpu_common
 151 │   ├── test_onert_frontend_nnapi
 152 │   └── tflite_test
 153 └── unittest_standalone
 154     └── nnfw_api_gtest
 155
 156 19 directories, 36 files
 157
 158 ```
 159
 160 Here, let's recall that the main target of our project is the arm architecture. If you have a development environment running Linux for arm on a device made of an arm CPU, such as Odroid-XU4, you will get a runtime binary that can be run on the arm architecture with the same command above. This is the simplest way to get a binary for an arm device. However, in most cases, native builds on arm devices are too impractical as they require too long. Therefore, we will create an executable binary of an architecture other than x86_64 through a `cross build`. For cross-build method for each architecture, please refer to the corresponding document in the following section, [How to cross-build runtime for different architecture](#how-to-cross-build-runtime-for-different-architecture).
 161
 162 ### Run test
 163
 164 The simple way to check whether the build was successful is to perform inference of the NN model using the runtime. The model to be used for the test can be obtained as follows.
 165
 166 ```
 167 $ wget https://storage.googleapis.com/download.tensorflow.org/models/tflite/model_zoo/upload_20180427/inception_v3_2018_04_27.tgz
 168 $ tar zxvf inception_v3_2018_04_27.tgz ./inception_v3.tflite
 169 $ ls *.tflite
 170 inception_v3.tflite
 171 ```
 172
 173 The result of running the inception_v3 model using runtime is as follows. Please consider that this is a test that simply checks execution latency without considering the accuracy of the model.
 174
 175 ```
 176 $ USE_NNAPI=1 LD_LIBRARY_PATH="./Product/out/lib/:$LD_LIBRARY_PATH" ./Product/out
 177 /bin/tflite_run ./inception_v3.tflite
 178 nnapi function 'ANeuralNetworksModel_create' is loaded from './Product/out/lib/libneuralnetworks.so'
 179 nnapi function 'ANeuralNetworksModel_addOperand' is loaded from './Product/out/lib/libneuralnetworks.so'
 180 nnapi function 'ANeuralNetworksModel_setOperandValue' is loaded from './Product/out/lib/libneuralnetworks.so'
 181 nnapi function 'ANeuralNetworksModel_addOperation' is loaded from './Product/out/lib/libneuralnetworks.so'
 182 nnapi function 'ANeuralNetworksModel_identifyInputsAndOutputs' is loaded from './Product/out/lib/libneuralnetworks.so'
 183 nnapi function 'ANeuralNetworksModel_finish' is loaded from './Product/out/lib/libneuralnetworks.so'
 184 nnapi function 'ANeuralNetworksCompilation_create' is loaded from './Product/out/lib/libneuralnetworks.so'
 185 nnapi function 'ANeuralNetworksCompilation_finish' is loaded from './Product/out/lib/libneuralnetworks.so'
 186 input tensor indices = [317,]
 187 nnapi function 'ANeuralNetworksExecution_create' is loaded from './Product/out/lib/libneuralnetworks.so'
 188 nnapi function 'ANeuralNetworksExecution_setInput' is loaded from './Product/out/lib/libneuralnetworks.so'
 189 nnapi function 'ANeuralNetworksExecution_setOutput' is loaded from './Product/out/lib/libneuralnetworks.so'
 190 nnapi function 'ANeuralNetworksExecution_startCompute' is loaded from './Product/out/lib/libneuralnetworks.so'
 191 nnapi function 'ANeuralNetworksEvent_wait' is loaded from './Product/out/lib/libneuralnetworks.so'
 192 nnapi function 'ANeuralNetworksEvent_free' is loaded from './Product/out/lib/libneuralnetworks.so'
 193 nnapi function 'ANeuralNetworksExecution_free' is loaded from './Product/out/lib/libneuralnetworks.so'
 194 ... run 1 takes 183.895 ms
 195 output tensor indices = [316(max:905),]
 196 ===================================
 197 MODEL_LOAD   takes 1.108 ms
 198 PREPARE      takes 0.190 ms
 199 EXECUTE      takes 183.895 ms
 200 - MEAN     :  183.895 ms
 201 - MAX      :  183.895 ms
 202 - MIN      :  183.895 ms
 203 - GEOMEAN  :  183.895 ms
 204 ===================================
 205 nnapi function 'ANeuralNetworksCompilation_free' is loaded from './Product/out/lib/libneuralnetworks.so'
 206 nnapi function 'ANeuralNetworksModel_free' is loaded from './Product/out/lib/libneuralnetworks.so'
 207 ```
 208 Here, `USE_NNAPI=1` means that **ONE** runtime is used for model inference. If omitted, the model will be executed using Tensorflow lite, the basic framework for verification. `LD_LIBRARY_PATH="./Product/out/lib/:$LD_LIBRARY_PATH"` specifies the location of the runtime library to be used for testing. From the previous build result, you can see that it is the path to the directory where `libneuralnetworks.so` and `libonert_core.so` are located.
 209
 210 If you come here without any problems, you have all of the basic environments for runtime development.
 211
 212 ## Build for Tizen
 213
 214 (Will be written)
 215
 216 ## Build using docker image
 217
 218 If your development system is not a linux environment like Ubuntu, but you can use docker on your system, you can build a runtime using a pre-configured docker image. Of course, you can also build a runtime using a docker image in a ubuntu environment, without setting up a complicated development environment. For more information, please refer to the following document.
 219
 220 - [Build using prebuilt docker image](how-to-build-runtime-using-prebuilt-docker-image.md)
 221
 222 ## How to cross-build runtime for different architecture
 223
 224 Please refer to the following document for the build method for architecture other than x86_64, which is the basic development environment.
 225
 226 - [Cross building for ARM](how-to-cross-build-runtime-for-arm.md)
 227 - [Cross building for AARCH64](how-to-cross-build-runtime-for-aarch64.md)
 228 - [Cross building for Android](how-to-cross-build-runtime-for-android.md)