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 20.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 - C & C++ compiler
  10 - CMake
  11 - Boost C++ libraries
  12
  13 In the Ubuntu, you can easily install it with the following command.
  14
  15 ```
  16 $ sudo apt-get install cmake libboost-all-dev
  17 ```
  18
  19 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 https://github.com/Samsung/ONE/blob/master/infra/docker/focal/Dockerfile.
  20
  21 Here is a summary of it for runtime and related tools
  22
  23 ```
  24 $ sudo apt install \
  25 build-essential \
  26 clang-format-8 \
  27 cmake \
  28 doxygen \
  29 git \
  30 graphviz \
  31 hdf5-tools \
  32 lcov \
  33 libboost-all-dev \
  34 libhdf5-dev \
  35 python3 \
  36 python3-pip \
  37 scons \
  38 software-properties-common \
  39 unzip \
  40 wget
  41
  42 $ pip3 install yapf==0.22.0 numpy
  43
  44 ```
  45
  46 ## Build from source code, for Ubuntu
  47
  48 In a typical linux development environment, including Ubuntu, you can build the runtime with a simple command like this:
  49
  50 ```
  51 $ git clone https://github.com/Samsung/ONE.git one
  52 $ cd one
  53 $ ./nnfw configure
  54 $ ./nnfw build
  55 $ ./nnfw install
  56 ```
  57
  58 For easy build process, we provides `Makefile.template` makefile.
  59
  60 ```
  61 $ make -f Makefile.template
  62 ```
  63
  64 To release build the runtime, add the environment variable `BUILD_TYPE=release` to the build command as follows.
  65
  66 ```
  67 $ export BUILD_TYPE=release
  68 $ make -f Makefile.template
  69 ```
  70
  71 Or you can simply do something like this:
  72
  73 ```
  74 $ BUILD_TYPE=release make -f Makefile.template
  75 ```
  76
  77 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:
  78
  79 ```
  80 $ tree -L 2 ./Product
  81 ./Product
  82 ├── out -> /home/sjlee/star/one/Product/x86_64-linux.release/out
  83 └── x86_64-linux.release
  84     ├── obj
  85     └── out
  86
  87 5 directories, 3 files
  88
  89 $ tree -L 3 ./Product/out
  90 ./Product/out
  91 ├── bin
  92 │   ├── onert_run
  93 │   ├── tflite_comparator
  94 │   └── tflite_run
  95 ├── include
  96 │   ├── nnfw
  97 │   │   ├── NeuralNetworksEx.h
  98 │   │   ├── NeuralNetworksExtensions.h
  99 │   │   ├── NeuralNetworks.h
 100 │   │   ├── nnfw_experimental.h
 101 │   │   └── nnfw.h
 102 │   └── onert
 103 │       ├── backend
 104 │       ├── compiler
 105 │       ├── exec
 106 │       ├── ir
 107 │       └── util
 108 ├── lib
 109 │   ├── libbackend_cpu.so
 110 │   ├── libbackend_ruy.so
 111 │   ├── libneuralnetworks.so
 112 │   ├── libnnfw-dev.so
 113 │   └── libonert_core.so
 114 ├── nnapi-gtest
 115 │   ├── nnapi_gtest
 116 │   ├── nnapi_gtest.skip
 117 │   └── nnapi_gtest.skip.x86_64-linux.cpu
 118 ├── test
 119 │   ├── command
 120 │   │   ├── nnpkg-test
 121 │   │   ├── prepare-model
 122 │   │   ├── unittest
 123 │   │   └── verify-tflite
 124 │   ├── FillFrom_runner
 125 │   ├── list
 126 │   │   ├── benchmark_nnpkg_model_list.txt
 127 │   │   ├── nnpkg_test_list.armv7l-linux.acl_cl
 128 │   │   ├── nnpkg_test_list.armv7l-linux.acl_neon
 129 │   │   ├── nnpkg_test_list.armv7l-linux.cpu
 130 │   │   ├── tflite_comparator.aarch64.acl_cl.list
 131 │   │   ├── tflite_comparator.aarch64.acl_neon.list
 132 │   │   ├── tflite_comparator.aarch64.cpu.list
 133 │   │   ├── tflite_comparator.armv7l.acl_cl.list
 134 │   │   ├── tflite_comparator.armv7l.acl_neon.list
 135 │   │   ├── tflite_comparator.armv7l.cpu.list
 136 │   │   └── tflite_comparator.x86_64.cpu.list
 137 │   ├── models
 138 │   │   ├── run_test.sh
 139 │   │   └── tflite
 140 │   ├── nnpkgs
 141 │   │   └── FillFrom
 142 │   └── onert-test
 143 └── unittest
 144     ├── ndarray_test
 145     ├── nnfw_api_gtest
 146     ├── nnfw_api_gtest_models
 147     │   ├── add
 148     │   ├── add_invalid_manifest
 149     │   ├── add_no_manifest
 150     │   ├── if_dynamic
 151     │   ├── mobilenet_v1_1.0_224
 152     │   └── while_dynamic
 153     ├── nnfw_lib_misc_test
 154     ├── test_cker
 155     ├── test_onert_core
 156     ├── test_onert_frontend_nnapi
 157     └── tflite_test
 158
 159 26 directories, 42 files
 160
 161 ```
 162
 163 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).
 164
 165 ### Run test
 166
 167 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.
 168
 169 ```
 170 $ wget https://storage.googleapis.com/download.tensorflow.org/models/tflite/model_zoo/upload_20180427/inception_v3_2018_04_27.tgz
 171 $ tar zxvf inception_v3_2018_04_27.tgz ./inception_v3.tflite
 172 $ ls *.tflite
 173 inception_v3.tflite
 174 ```
 175
 176 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.
 177
 178 ```
 179 $ ./Product/out/bin/onert_run ./inception_v3.tflite
 180 Model Filename ./inception_v3.tflite
 181 ===================================
 182 MODEL_LOAD   takes 1.108 ms
 183 PREPARE      takes 0.190 ms
 184 EXECUTE      takes 183.895 ms
 185 - MEAN     :  183.895 ms
 186 - MAX      :  183.895 ms
 187 - MIN      :  183.895 ms
 188 - GEOMEAN  :  183.895 ms
 189 ===================================
 190 ```
 191 If you use `tflite_run` instead of `onert_run`, the model will be executed using Tensorflow lite, the basic framework for verification. From the previous build result, you can see that it is the path to the directory where `tflite_run` and `onert_run` are located.
 192
 193 If you come here without any problems, you have all of the basic environments for runtime development.
 194
 195 ## Build for Tizen
 196
 197 (Will be written)
 198
 199 ## Build using docker image
 200
 201 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.
 202
 203 - [Build using prebuilt docker image](how-to-build-runtime-using-prebuilt-docker-image.md)
 204
 205 ## How to cross-build runtime for different architecture
 206
 207 Please refer to the following document for the build method for architecture other than x86_64, which is the basic development environment.
 208
 209 - [Cross building for ARM](how-to-cross-build-runtime-for-arm.md)
 210 - [Cross building for AARCH64](how-to-cross-build-runtime-for-aarch64.md)
 211 - [Cross building for Android](how-to-cross-build-runtime-for-android.md)