diff options
Diffstat (limited to 'build-tool/README.md')
| -rw-r--r-- | build-tool/README.md | 409 |
1 files changed, 409 insertions, 0 deletions
diff --git a/build-tool/README.md b/build-tool/README.md new file mode 100644 index 0000000000..30a1a20da7 --- /dev/null +++ b/build-tool/README.md @@ -0,0 +1,409 @@ +# Arm NN Build Tool +The **_Arm NN Build Tool_** provides a collection of **parameterized bash scripts** accompanied by a **Dockerfile** for building Arm NN and its dependencies, including **[Arm Compute Library (ACL)](https://github.com/ARM-software/ComputeLibrary/)**. +This tool replaces/supersedes the majority of the existing Arm NN build guides as a user-friendly way to build Arm NN from scratch. +The main benefit of building Arm NN from scratch is the ability to **exactly choose which components to build, targeted for your ML project**.<br> +The Arm NN Build Tool is tested on **x86_64 (Intel) and aarch64 (Arm) build hosts** for the **Ubuntu** platform. +Other host platforms such as Windows and Mac **should** work (with Docker installed), but have not been officially tested.<br> +At present, the tool supports **targeting Linux devices (from Ubuntu 18.04 onwards) on x86_64, aarch32 and aarch64** architectures.<br> +We recommend using the Arm NN Build Tool through the use of Docker. However, the scripts may be [executed directly on your machine](#build-arm-nn-without-docker) if desired. + +**If you already have Docker installed** and want to quickly build the Arm NN Dockerfile with some default build arguments, please follow the [Docker Build Steps](#docker-build-steps). + +* [Overview](#overview) +* [System Requirements](#system-requirements) +* [Install Docker](#install-docker) + * [Ubuntu / Linux](#ubuntu--linux) + * [Windows and Mac](#windows-and-mac) +* [Docker Build Arguments Reference](#docker-build-arguments-reference) + * [SETUP_ARGS](#setup_args) + * [BUILD_ARGS](#build_args) +* [Docker Build Steps](#docker-build-steps) +* [Build Arm NN Without Docker](#build-arm-nn-without-docker) +* [Advanced Usage](#advanced-usage) + * [Use custom Arm NN and ACL repository versions during build](#use-custom-arm-nn-and-acl-repository-versions-during-build) + * [Additional Docker Build Arguments](#additional-docker-build-arguments) + * [Inspect the contents of the Docker Image](#inspect-the-contents-of-the-docker-image) + * [Bind Mounts](#bind-mounts) + +## Overview +The Arm NN Build Tool consists of an official Arm NN **Dockerfile** with associated **scripts** for building Arm NN: +1. **```install-packages.sh```:** builds CMake from source and installs system-wide **apt packages** +2. **```setup-armnn.sh```:** downloads and builds Arm NN **dependencies** (e.g. Flatbuffers, TF Lite, Protobuf) +3. **```build-armnn.sh```:** builds Arm NN and ACL +4. **```common.sh```:** common variables and functions used by ```setup-armnn.sh``` and ```build-armnn.sh``` +5. **```validation.sh```:** validation of common command-line arguments to ```setup-armnn.sh``` and ```build-armnn.sh``` +6. **```docker-copy-to-host```:** helpful script to copy contents of a Docker Image to the host machine + +A **Dockerfile** is a text document which outlines the instructions for building a **Docker Image**. Running ```docker build``` +on the Arm NN Dockerfile will result in a Docker Image that contains: +1. The Ubuntu operating system +2. Installed system-wide packages required by Arm NN +3. Source code for Arm NN and its dependencies +4. The build for Arm NN and its dependencies + +All scripts except ```docker-copy-to-host.sh``` are used during the ```docker build``` process. + +The ```docker-copy-to-host.sh``` script creates a temporary [**Docker Container**](https://www.docker.com/resources/what-container/) which is required to retrieve files from the +Docker Image. A Docker Container is a **runtime** version of a Docker Image. It can be interacted with through a command-line +terminal, like a lightweight virtual machine (VM). The ```docker-copy-to-host.sh``` script is designed to run on the host +machine after ```docker build``` to copy the Arm NN build to the host. + +The **diagram below** outlines the operation of the Arm NN **Dockerfile** and the contents of the resulting **Docker Image** after +running ```docker build```. During ```docker build```, the provided **```SETUP_ARGS```** determine which of Arm NN's +dependencies to download and build. The **```BUILD_ARGS```** Docker argument determines which components of Arm NN to build. + +The resulting Docker Image contains the Arm NN build (along with everything required to build it) in the home directory ```/home/arm-user```. +There are two directories: **```source```** which contains the source code of Arm NN and its dependencies, and **```build```** +which contains the Arm NN build and the builds of each dependency of Arm NN. + +The **```armnn_aarch64_build.tar.gz``` tarball** in the home directory is a compressed archive of the Arm NN build which is located at ```/home/arm-user/build/armnn```. +The home directory also contains the **scripts** mentioned above (not pictured in the diagram), which are copied into the +Docker Image during the ```docker build``` process. + +<div align="center"> + <img src="dockerfile_armnn.png" class="center" alt="Arm NN Dockerfile" width="800"/> +</div> + +<br> + +**Benefits of using Docker:** +1. Run one ```docker build``` command instead of executing multiple scripts, saving developer time +2. Can easily manage multiple different build configurations at once, each in their own Docker Image +3. System packages are installed in the Docker Image only, isolated from the host machine +4. Build in the exact environment the Arm NN Team used during testing, ensuring consistency in builds +5. Allows Arm NN to be built on a wide range of hosts, as long as they support Docker + +**Disadvantages of using Docker:** +1. Requires the developer to install Docker on their host machine +2. Requires the developer to get familiar with Docker (this guide should help) +3. Possible incompatibilities/limitations if the host machine's Linux Kernel version is too different than that of the +base OS in the Docker Image. This is due to the fact that Docker Containers share the Linux Kernel of the host machine +(unlike VM's which each have their own Kernel). + +<br> + +## System Requirements +This guide will not provide the system requirements for installing Docker - please refer to the Docker documentation during installation. + +The built Docker Image has disk requirements of **less than 6GB**, depending on the Arm NN components chosen and whether +the build included a cross compile (i.e. building aarch64 on x86_64). Repeated builds may cause the total disk usage to increase +beyond 6GB. The ```docker images``` command shows the disk usage of each Docker Image. To view total disk space used by all +Docker Images and Docker Containers, use the command ```docker system df```. + +This Dockerfile was built on a **Ubuntu 18.04 host machine with Docker version 20.10.14**. We recommend using a host machine +with at least Ubuntu 18.04 and a similar Docker version, if possible. Other Linux distros such as **Debian** should also work as +long as the Docker version is similar to **20.10.14**. + +The build outputs from this Dockerfile have been tested on an **Odroid N2+ target device with Ubuntu 18.04** installed. The build outputs +should also work on newer versions of Ubuntu (and Debian) but this has not been exhaustively tested. + +To view the system packages that are installed during ```docker build```, please refer to the ```install-packages.sh``` script. + +<br> + +## Install Docker +Builds of the official Arm NN Dockerfile have been tested on the **Ubuntu 18.04** host platform. +Whilst other platforms have not been tested, Docker should be able to build the Arm NN Dockerfile on other platforms such as Windows and Mac. +On **Linux**, we recommend using **Docker Engine** which is used through the command-line interface (CLI). +For **Windows and Mac** users, **Docker Desktop** is available which allows the use of the CLI plus a graphical interface.<br> +This guide will **only** provide steps on using Docker through the use of the CLI and not Docker Desktop. + +### Ubuntu / Linux +For Ubuntu users, we recommend installing **Docker Engine** with the following steps from the Docker documentation:<br> +1. [Uninstall any old versions of Docker](https://docs.docker.com/engine/install/ubuntu/#uninstall-old-versions) +2. [Install using the repository](https://docs.docker.com/engine/install/ubuntu/#install-using-the-repository) +3. [Add user to Docker Unix Group](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user) (**recommended**: allows running of Docker commands **without ```sudo```**) + +Similar steps for installing Docker Engine on other Linux distributions can be found by clicking on your distro under the Server table on [this page](https://docs.docker.com/engine/install/#server). + +### Windows and Mac +We do not officially test the building of the Arm NN Dockerfile on Windows or Mac. However, it's likely that it will work if your system supports Docker. +For **Windows**, use the Docker Desktop download link on [this page](https://docs.docker.com/desktop/install/windows-install/). +For **Mac** users, please use the Docker Desktop download link on [this page](https://docs.docker.com/desktop/install/mac-install/). <br> +**Note:** we unfortunately cannot provide support for the installation of Docker and/or the use of the Arm NN Dockerfile on Windows and Mac platforms. + +<br> + +## Docker Build Arguments Reference +The following describes the ```docker build``` arguments that can be used to customize the Arm NN build. +Docker build arguments such as ```SETUP_ARGS``` and ```BUILD_ARGS``` are provided in the ```docker build``` as a ```--build-arg```. + +### SETUP_ARGS +These arguments are eventually passed to ```setup-armnn.sh``` which downloads and builds Arm NN dependencies. +For ease of use (but longer initial docker build), use ```--all``` to have all Arm NN dependencies available for use during Arm NN builds. +Repeated docker builds with the same ```SETUP_ARGS``` will skip the setup process (using [caching](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/#leverage-build-cache) of previous Docker build steps). +The ```SETUP_ARGS``` string should start and end with **double quotes** ```"```. + +| SETUP_ARGS | Description | +|-------------------|:-----------------------------------------------------------------------------------| +| --tflite-delegate | **flag:** setup dependencies for the Arm NN TF Lite Delegate | +| --tflite-parser | **flag:** setup dependencies for the Arm NN TF Lite Parser | +| --onnx-parser | **flag:** setup dependencies for the Arm NN ONNX parser | +| --all | **flag:** setup dependencies for all Arm NN components listed above | +| --target-arch= | **mandatory option:** specify a target architecture ```aarch64, aarch32, x86_64``` | + +**At least one component** (e.g. ```--tflite-delegate```) must be provided **or** else provide ```--all``` to setup dependencies for all components. + +**Examples:**<br> +Setup for aarch64 with all Arm NN dependencies:<br> +```SETUP_ARGS="--target-arch=aarch64 --all"``` + +Setup for aarch64 with TF Lite Delegate and TF Lite Parser dependencies only:<br> +```SETUP_ARGS="--target-arch=aarch64 --tflite-delegate --tflite-parser"``` + +<br> + +### BUILD_ARGS +The following arguments are given to ```build-armnn.sh``` and define which components of Arm NN to include in the build. +The ```BUILD_ARGS``` string should start and end with **double quotes** ```"```. + +| BUILD_ARGS | Description | +|---------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| --tflite-delegate | **flag:** build the Arm NN TF Lite Delegate component | +| --tflite-parser | **flag:** build the Arm NN TF Lite Parser component | +| --onnx-parser | **flag:** build the Arm NN ONNX parser component | +| --all | **flag:** build all Arm NN components listed above | +| --target-arch= | **mandatory option:** specify a target architecture ```aarch64, aarch32, x86_64``` | +| --neon-backend | **flag:** build Arm NN with the NEON backend (CPU acceleration from ACL) | +| --cl-backend | **flag:** build Arm NN with the OpenCL backend (GPU acceleration from ACL) | +| --ref-backend | **flag:** build Arm NN with the reference backend<br/>**Should be used for verification purposes only.<br/>Does not provide any performance acceleration.** | +| --debug | **flag:** build Arm NN (and ACL) with debug turned on (optional: defaults to off) | +| --armnn-cmake-args= | **option:** provide additional space-separated CMake arguments string for building Arm NN (optional)<br/>String should start and end with **single quotes** ```'```<br/>Please refer to **armnn/cmake/GlobalConfig.cmake** | +| --acl-scons-params= | **option**: provide additional space-separated scons parameters string for building ACL (optional)<br/>String should start and end with **single quotes** ```'```<br/>ACL provide [documentation](https://arm-software.github.io/ComputeLibrary/latest/how_to_build.xhtml#S1_1_build_options) for their build options | + + +**At least one component** (i.e. ```--tflite-delegate```, ```--tflite-parser```, ```--onnx-parser```) must be provided or else provide ```--all``` to build all Arm NN components.<br> +**A component given in ```BUILD_ARGS``` must also have been given in ```SETUP_ARGS``` previously**, or else Arm NN will fail to build.<br> +**At least one backend** (i.e. ```--neon-backend```, ```--cl-backend```, ```--ref-backend```) must be chosen.<br> + +**Examples:**<br> +Build for aarch64 with all Arm NN components, NEON enabled and OpenCL enabled:<br> +```BUILD_ARGS="--target-arch=aarch64 --all --neon-backend --cl-backend"``` + +Build for aarch64 with TF Lite Delegate, OpenCL enabled and additional ACL scons params:<br> +```BUILD_ARGS="--target-arch=aarch64 --tflite-delegate --cl-backend --acl-scons-params='compress_kernels=1 benchmark_examples=1'"``` + +Setup for aarch32 with all Arm NN dependencies, OpenCL enabled and additional Arm NN cmake args:<br> +```BUILD_ARGS="--target-arch=aarch32 --all --cl-backend --armnn-cmake-args='-DBUILD_SAMPLE_APP=1 -DBUILD_UNIT_TESTS=0'"``` + +**Example _valid_ combination of SETUP_ARGS and BUILD_ARGS:**<br> +``` +SETUP_ARGS="--target-arch=aarch64 --all" +BUILD_ARGS="--target-arch=aarch64 --tflite-delegate --neon-backend --cl-backend" +``` + +**Example _invalid_ combination of SETUP_ARGS and BUILD_ARGS:**<br> +``` +SETUP_ARGS="--target-arch=aarch64 --tflite-delegate" +BUILD_ARGS="--target-arch=aarch64 --all --neon-backend --cl-backend" +``` + +The example above is invalid since it tries to build all Arm NN components after **only** building the dependencies required by the TF Lite Delegate. + +<br> + +## Docker Build Steps + +First clone the Arm NN repo to obtain the build-tool. This automatically downloads the latest release version of Arm NN. +``` +git clone https://github.com/ARM-software/armnn.git armnn +``` +<br> + +Enter into the Arm NN build-tool directory where the Dockerfile and associated scripts are located. +``` +cd armnn/build-tool +``` +<br> + +Run the ```docker build```, which downloads and builds Arm NN and its dependencies. This process is isolated from the host machine's filesystem and the result is a Docker Image being created.<br> +Dockerfile arguments are provided using ```--build-arg```, the relative path to the Dockerfile is given with ```--file``` and the current directory is given with ```.```<br> +Provide a descriptive name for the Image with ```--tag``` in the form of ```image_name:tag``` (example given below). The backslashes ```\``` tell Bash to expect a continuation of the command on the next line. + +This example's choice of **[SETUP_ARGS](#setup_args)** and **[BUILD_ARGS](#build_args)** builds all Arm NN components with NEON and OpenCL accelerated backends for aarch64 target. +This process should take **less than an hour** with a modern machine but will vary depending on the arguments chosen and host machine specification. + +``` +docker build \ +--build-arg SETUP_ARGS="--target-arch=aarch64 --all" \ +--build-arg BUILD_ARGS="--target-arch=aarch64 --all --neon-backend --cl-backend" \ +--tag armnn:aarch64 \ +--file docker/Dockerfile . +``` + +<br> + +Arm NN and all of its dependencies are now built within a Docker Image. Built Docker images can be listed with ```docker images```. +``` +docker images + +REPOSITORY TAG IMAGE ID CREATED SIZE +armnn aarch64 cc623174fd98 7 seconds ago 5.02GB +``` + +<br> + +A tarball archive of the Arm NN build is located inside the Docker home directory (```/home/arm-user/```), named ```armnn_<target-arch>_build.tar.gz```. +If the ```--debug``` build flag is provided in the ```BUILD_ARGS``` above, the tarball will be named ```armnn_<target-arch>_build_debug.tar.gz```.<br> +The ```docker-copy-to-host.sh``` script will copy a file from the Docker Image (in arm-user's home directory) to the host machine.<br> +The script copies the tarball into a new directory on the host in ```build-tool/docker_output```. It takes two arguments: ```image_name:tag``` and ```filename```.<br> +The filename is a relative path from the home directory created inside the Docker Image (```/home/arm-user/```). +``` +./scripts/docker-copy-to-host.sh armnn:aarch64 armnn_aarch64_build.tar.gz +``` + +<br> + +This tarball can now be used for integration in an ML application. The method of extraction is given below.<br> +If the ```--target-arch``` chosen in the arguments above matches the host machine, the build can be tested locally (else copy the tarball to a remote device). +``` +cd docker_output + +# Extract the tarball into a directory called <target_arch>_build +# If --debug is enabled, the extracted build directory will be called <target_arch>_build_debug +tar -xzf armnn_aarch64_build.tar.gz +cd aarch64_build + +# Set LD_LIBRARY_PATH to the current aarch64_build directory (.) +export LD_LIBRARY_PATH=.; ./UnitTests + +# If the Arm NN TF Lite Delegate is built, we can also run DelegateUnitTests +cd delegate + +# Set LD_LIBRARY_PATH to the current delegate directory (.) and the aarch64_build directory (..) +export LD_LIBRARY_PATH=.:..; ./DelegateUnitTests +``` + +<br> + +**Note:** Repeated Docker builds may result in an accumulation of unwanted, dangling images. **To remove dangling images** (good practice), run the following command: ```docker image prune``` + +<br> + +## Build Arm NN without Docker +For ease of use, we recommend that the official Arm NN Dockerfile is used to build Arm NN. +If you'd like to build locally on a Ubuntu host machine without Docker, execute the build-tool scripts directly instead. +This involves running ```install-packages.sh``` followed by ```setup-armnn.sh``` and ```build-armnn.sh```. +The arguments for ```setup-armnn.sh``` and ```build-armnn.sh``` are very much the same as ```SETUP_ARGS``` and ```BUILD_ARGS```. +Please use ```--help``` for more specific information. + +``` +cd build-tool/scripts + +sudo ./install-packages.sh + +./setup-armnn.sh --target-arch=aarch64 --all +./build-armnn.sh --target-arch=aarch64 --all --neon-backend --cl-backend + +./setup-armnn.sh --help +./build-armnn.sh --help +``` + +<br> + +## Advanced Usage + +### Use custom Arm NN and ACL repository versions during build +By default, the docker build process (specifically, during ```build-armnn.sh```) will download the latest release versions of Arm NN and ACL. +If you'd like to use different versions during the build, check them out in the ```build-tool``` directory on the host (both must be provided).<br> +When providing custom repositories, the following ```docker build``` argument must be provided ```--build-arg BUILD_TYPE=dev```. +This will trigger Docker to copy the custom repos into the Docker Image during build. + +**Note:** the Arm NN version used for build-tool (Dockerfile and scripts) is not the same version of Arm NN that is used during the build. +This means that separate versions of Arm NN can be used for the build-tool and for building Arm NN itself.<br> +If you repeat the ```docker build``` process multiple times (e.g. with different ```BUILD_ARGS```), the setup process will be skipped as long as ```SETUP_ARGS``` remains the same. +``` +cd build-tool + +git clone https://github.com/ARM-software/armnn.git armnn +cd armnn +git checkout <branch or SHA> + +cd .. + +git clone https://github.com/ARM-software/ComputeLibrary.git acl +cd acl +git checkout <tag or SHA> + +cd .. + +# Example docker build with BUILD_TYPE=dev +docker build \ +--build-arg BUILD_TYPE=dev \ +--build-arg SETUP_ARGS="--target-arch=aarch64 --all" \ +--build-arg BUILD_ARGS="--target-arch=aarch64 --all --neon-backend --cl-backend" \ +--tag armnn:aarch64 \ +--file docker/Dockerfile . +``` + +<br> + +### Additional Docker Build Arguments + +#### UBUNTU_VERSION +The default base Image used during ```docker build``` is ```ubuntu:18.04```. Building Arm NN with this default image should be sufficient for a wide range of target devices. +To use a different Ubuntu base Image, provide ```UBUNTU_VERSION``` during ```docker build``` e.g. ```--build-arg UBUNTU_VERSION=20.04```. + +#### BUILD_TYPE +By default, ```BUILD_TYPE``` is set to ```production```. This means that the latest release versions of Arm NN and ACL are used during builds. +To use custom repositories as explained [above](#Use-custom-Arm-NN-and-ACL-repository-versions-during-build), provide ```--build-arg BUILD_TYPE=dev```. + +#### Additional SETUP_ARGS and BUILD_ARGS +The following are additional ```SETUP_ARGS``` and ```BUILD_ARGS``` that can be provided to the ```docker build```. + +| SETUP_ARGS / BUILD_ARGS | Description | +|-------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| --num-threads= | **option:** specify number of threads/cores to build Arm NN and its dependencies with (this defaults to number of online cores on the host)<br/>e.g. --num-threads=4 | +| -x | **flag:** enable shell tracing during setup-armnn.sh and build-armnn.sh script execution | + +#### USER_ID and GROUP_ID +By default, the Docker Image creates a user called ```arm-user``` with user/group ID of 1000. This ensures the build outputs can be used by a wide range of users on target devices.<br> +To provide a more specific user and group ID to be associated with the build, provide ```--build-arg USER_ID=XXXX``` and ```--build-arg GROUP_ID=YYYY```. + +<br> + +### Inspect the contents of the Docker Image +To inspect the full contents of the Docker Image, the Image must be run as a **Docker Container**. +A Container is a runtime version of the Image, like a **lightweight virtual machine** with its own filesystem. + +The following shows how to run a container with an interactive terminal based on a specified Docker Image ```image_name:tag```. +The ID of the generated container in this example is ```4da7c575a95a```. An ```ls``` command shows the contents of the ```/home/arm-user``` directory. +``` +docker run --interactive --tty armnn:aarch64 + +arm-user@4da7c575a95a:~$ ls +armnn_aarch64_build.tar.gz build build-armnn.sh common.sh setup-armnn.sh source validation.sh +``` +The ```source``` directory contains the downloaded dependencies for building Arm NN.<br> +The ```build``` directory contains the built Arm NN dependencies and the Arm NN build itself.<br> +The ```armnn_aarch64_build.tar.gz``` tarball is an archive of the build located at ```build/armnn/aarch64_build```.<br> +The scripts (e.g. ```build-armnn.sh```) in this directory can be run as you wish, changes will persist within the container but not the Docker Image. +To exit the docker container, run ```CTRL-D```. A list of Docker containers can be obtained with the following command: +``` +# --all shows both running and non-running containers +docker ps --all + +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +4da7c575a95a armnn:aarch64 "bash" 7 minutes ago Exited (0) 7 seconds ago pedantic_joliot +``` +To restart the same container (and any changes made to it) in a terminal again, use the following commands: +``` +# 4da7c575a95a in this case is the CONTAINER ID from above + +docker start 4da7c575a95a # restart container in background +docker attach 4da7c575a95a # re-attach to terminal + +# After exiting with CTRL-D +docker stop 4da7c575a95a +``` +To save space over time, stopped Docker containers can be deleted with the following command:<br> +```docker container prune```. + +<br> + +### Bind Mounts +**Bind Mounts** may be used to mount directories from the host machine to inside a Docker container. This could be useful when +frequently changing the contents of the Arm NN or ACL source repositories (in ```/home/arm-user/source```) between runs of +build-armnn.sh inside the container. Note that bind mounts are a feature that apply to runtime versions of Docker +images i.e. Docker Containers (```docker run```, not ```docker build```). +Please refer to the [Docker documentation for more information about bind mounts](https://docs.docker.com/storage/bind-mounts/).
\ No newline at end of file |