@ -1,109 +1,105 @@
# Build PaddlePaddle for Android
# 构建Android平台上的PaddlePaddle库
There are two approaches to build PaddlePaddle for Android: using Docker and on Linux without Docker.
用户可通过如下两种方式， ：
- 基于Docker容器的编译方式
- 基于Linux交叉编译环境的编译方式
## Cross-Compiling Using Docker
## 基于Docker容器的编译方式
Docker能在所有主要操作系统（ ， ） ， ， ，
Docker-based cross-compiling is the recommended approach because Docker runs on all major operating systems, including Linux, Mac OS X, and Windows.
### 构建PaddlePaddle的Android开发镜像
我们把PaddlePaddle的交叉编译环境打包成一个镜像， ，
### Build the Docker Image
The following steps pack all the tools that we need to build PaddlePaddle into a Docker image.
```bash
```bash
$ git clone https://github.com/PaddlePaddle/Paddle.git
$ git clone https://github.com/PaddlePaddle/Paddle.git
$ cd Paddle
$ cd Paddle
$ docker build -t paddle:dev-android . -f Dockerfile.android
$ docker build -t username/paddle-android:dev . -f Dockerfile.android
```
### Build the Inference Library
We can run the Docker image we just created to build the inference library of PaddlePaddle for Android using the command below:
```bash
$ docker run -it --rm -v $PWD:/paddle -e "ANDROID_ABI=armeabi-v7a" -e "ANDROID_API=21" paddle:dev-android
```
```
The Docker image accepts two arguments `ANDROID_ABI` and `ANDROID_API` :
### 编译PaddlePaddle C-API库
构建好开发镜像后，
Android的Docker开发镜像向用户提供两个可配置的参数：
| Argument | Optional Values | Default |
| Argument | Optional Values | Default |
|-----------------|-------------------------|---------|
|-----------------|-------------------------|---------|
|`ANDROID_ABI` |`armeabi-v7a, arm64-v8a` | `armeabi-v7a` |
|`ANDROID_ABI` |`armeabi-v7a, arm64-v8a` | `armeabi-v7a` |
|`ANDROID_API` |`>= 21` | `21` |
|`ANDROID_API` |`>= 21` | `21` |
The ARM-64 architecture (`arm64-v8a`) requires at least level 21 of Android API.
- 编译`armeabi-v7a`，
```bash
The default entry-point of the Docker image, [`paddle/scripts/docker/build_android.sh` ](https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/scripts/docker/build_android.sh ) generates the [Android cross-compiling standalone toolchain ](https://developer.android.com/ndk/guides/standalone_toolchain.html ) based on the argument: `ANDROID_ABI` or `ANDROID_API` . For information about other configuration arguments, please continue reading.
$ docker run -it --rm -v $PWD:/paddle -e "ANDROID_ABI=armeabi-v7a" -e "ANDROID_API=21" username/paddle-android:dev
```
The above command generates and outputs the inference library in `$PWD/install_android` and puts third-party libraries in `$PWD/install_android/third_party` .
- 编译`arm64-v8a`，
```bash
$ docker run -it --rm -v $PWD:/paddle -e "ANDROID_ABI=arm64-v8a" -e "ANDROID_API=21" username/paddle-android:dev
```
## Cross-Compiling on Linux
执行上述`docker run`命令时，容器默认执行[paddle/scripts/docker/build_android.sh](https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/scripts/docker/build_android.sh)脚本。该脚本中记录了交叉编译Android版PaddlePaddle库常用的CMake配置， ， < 21 ` 时 ， Docker 容 器 中 将 默 认 使 用 ` Android API 21 ` 的 编 译 工 具 链 。 用 户 可 以 参 考 下 文 * * 配 置 交 叉 编 译 参 数 * * 章 节 ， 根 据 个 人 的 需 求 修 改 定 制 Docker 容 器 所 执 行 的 脚 本 。 编 译 安 装 结 束 之 后 ， PaddlePaddle 的 C-API 库 将 被 安 装 到 ` $ PWD / install_android ` 目 录 ， 所 依 赖 的 第 三 方 库 同 时 也 被 安 装 到 ` $ PWD / install_android / third_party ` 目 录 。
The Linux-base approach to cross-compile is to run steps in `Dockerfile.android` manually on a Linux x64 computer.
## 基于Linux交叉编译环境的编译方式
本文档将以Linux x86-64平台为例，
### Setup the Environment
### 准备交叉编译环境
To build for Android's, we need [Android NDK](
从源码交叉编译PaddlePaddle，
https://developer.android.com/ndk/downloads/index.html):
```bash
```bash
wget -q https://dl.google.com/android/repository/android-ndk-r14b-linux-x86_64.zip
wget -q https://dl.google.com/android/repository/android-ndk-r14b-linux-x86_64.zip
unzip -q android-ndk-r14b-linux-x86_64.zip
unzip -q android-ndk-r14b-linux-x86_64.zip
```
```
Android NDK includes everything we need to build the [*standalone toolchain* ](https://developer.android.com/ndk/guides/standalone_toolchain.html ), which in then used to build PaddlePaddle for Android. (We plan to remove the intermediate stage of building the standalone toolchain in the near future.)
Android NDK中包含了所有Android API级别、所有架构（ ） ，
- To build the standalone toolchain for `armeabi-v7a` and Android API level 21:
- 构建`armeabi-v7a`、 `Android API 21` 的独立工具链：
```bash
```bash
your/path/to/android-ndk-r14b-linux-x86_64/build/tools/make-standalone-toolchain.sh \
your/path/to/android-ndk-r14b-linux-x86_64/build/tools/make-standalone-toolchain.sh \
--arch=arm --platform=android-21 --install-dir=your/path/to/arm_standalone_toolchain
--arch=arm --platform=android-21 --install-dir=your/path/to/arm_standalone_toolchain
```
```
The generated standalone toolchain will be in `your/path/to/arm_standalone_toolchain` .
- To build the standalone toolchain for `arm64-v8a` and Android API level 21:
```bash
此命令将在`your/path/to/arm_standalone_toolchain`目录生成一套独立编译工具链， ， ，
your/path/to/android-ndk-r14b-linux-x86_64/build/tools/make-standalone-toolchain.sh \
--arch=arm64 --platform=android-21 --install-dir=your/path/to/arm64_standalone_toolchain
```
The generated standalone toolchain will be in `your/path/to/arm64_standalone_toolchain` .
- 构建`arm64-v8a`、 `Android API 21` 的独立工具链：
```bash
your/path/to/android-ndk-r14b-linux-x86_64/build/tools/make-standalone-toolchain.sh \
--arch=arm64 --platform=android-21 --install-dir=your/path/to/arm64_standalone_toolchain
```
**Please be aware that the minimum level of Android API required by PaddlePaddle is 21.**
此命令将在`your/path/to/arm64_standalone_toolchain`目录生成一套独立编译工具链， ， ，
### Cross-Compiling Arguments
注意：**PaddlePaddle要求使用的编译工具链所支持的Android API级别不小于21**。
CMake supports [choosing the toolchain ](https://cmake.org/cmake/help/v3.0/manual/cmake-toolchains.7.html#cross-compiling ). PaddlePaddle provides [`android.cmake` ](https://github.com/PaddlePaddle/Paddle/blob/develop/cmake/cross_compiling/android.cmake ), which configures the Android cross-compiling toolchain for CMake. `android.cmake` is not required for CMake >= 3.7, which support Android cross-compiling. PaddlePaddle detects the CMake version, for those newer than 3.7, it uses [the official version ](https://cmake.org/cmake/help/v3.7/manual/cmake-toolchains.7.html#cross-compiling ). ### 配置交叉编译参数
Some other CMake arguments you need to know: CMake系统对交叉编译提供了支持[cmake-toolchains](https://cmake.org/cmake/help/v3.0/manual/cmake-toolchains.7.html#cross-compiling)。为了简化cmake配置， ， ， ， ， ，
- `CMAKE_SYSTEM_NAME` must be `Android` . This tells PaddlePaddle's CMake system to cross-compile third-party dependencies. This also changes some other CMake arguments like `WITH_GPU=OFF` , `WITH_AVX=OFF` , `WITH_PYTHON=OFF` , and `WITH_RDMA=OFF` .
交叉编译Android版本的PaddlePaddle库时， ：
- `WITH_C_API` must be `ON` , to build the C-based inference library for Android.
- `CMAKE_SYSTEM_NAME` ， ， ， ， ， （
- `WITH_SWIG_PY` must be `OFF` because the Android platform doesn't support SWIG-based API.
- `WITH_C_API` ，必须设置为`ON`。在Android平台上只支持使用C-API来预测。
- `WITH_SWIG_PY` ，必须设置为`OFF`。在Android平台上不支持通过swig调用来训练或者预测。
Some Android-specific arguments: Android平台可选配置参数：
- `ANDROID_STANDALONE_TOOLCHAIN` : the absolute path of the Android standalone toolchain, or the path relative to the CMake build directory. PaddlePaddle's CMake extensions would derive the cross-compiler, sysroot and Android API level from this argument.
- `ANDROID_STANDALONE_TOOLCHAIN` ， ， ； ，
- `ANDROID_TOOLCHAIN` : could be `gcc` or `clang` . The default value is `clang` .
- `ANDROID_TOOLCHAIN` ，目标工具链。可设置`gcc/clang`，默认值为`clang`。
- For CMake >= 3.7, it should anyway be `clang` . For older versions, it could be `gcc` . - CMake 3.7以上，将会始终使用`clang`工具链；
- Android's official `clang` requires `glibc` >= 2.15. - Android官方提供的`clang`编译器要求系统支持`GLIBC 2.15`以上。
- `ANDROID_ABI` : could be `armeabi-v7a` or `arm64-v8a` . The default value is `armeabi-v7a` .
- `ANDROID_ABI` ，
- `ANDROID_NATIVE_API_LEVEL` : could be derived from the value of `ANDROID_STANDALONE_TOOLCHAIN` .
- `ANDROID_NATIVE_API_LEVEL` ， ，
- `ANROID_ARM_MODE` :
- `ANROID_ARM_MODE` ，
- could be `ON` or `OFF` , and defaults to `ON` , when `ANDROID_ABI=armeabi-v7a` ; - `ANDROID_ABI=armeabi-v7a` 时，可设置`ON/OFF`，默认值为`ON`；
- no need to specify when `ANDROID_ABI=arm64-v8a` . - `ANDROID_ABI=arm64-v8a` 时，不需要设置。
- `ANDROID_ARM_NEON` : indicates if to use NEON instructions.
- `ANDROID_ARM_NEON` ，
- could be `ON` or `OFF` , and defaults to `ON` , when `ANDROID_ABI=armeabi-v7a` ; - `ANDROID_ABI=armeabi-v7a` 时，可设置`ON/OFF`，默认值为`ON`；
- no need to specify when `ANDROID_ABI=arm64-v8a` . - `ANDROID_ABI=arm64-v8a` 时，不需要设置。
Other useful arguments: 其他配置参数：
- `USE_EIGEN_FOR_BLAS` : indicates if using Eigen. Could be `ON` or `OFF` , defaults to `OFF` .
- `USE_EIGEN_FOR_BLAS` ，
- `HOST_C/CXX_COMPILER` : specifies the host compiler, which is used to build the host-specific protoc and target-specific OpenBLAS. It defaults to the value of the environment variable `CC` , or `cc` .
- `HOST_C/CXX_COMPILER` ，
Some frequent configurations for your reference: 常用的cmake配置如下：
```bash
```bash
cmake -DCMAKE_SYSTEM_NAME=Android \
cmake -DCMAKE_SYSTEM_NAME=Android \
@ -129,25 +125,22 @@ cmake -DCMAKE_SYSTEM_NAME=Android \
..
..
```
```
用户还可根据自己的需求设置其他编译参数。比如希望最小化生成的库的大小，可以设置`CMAKE_BUILD_TYPE`为`MinSizeRel`；若希望最快的执行速度，则可设置`CMAKE_BUILD_TYPE`为`Release`。亦可以通过手动设置`CMAKE_C/CXX_FLAGS_MINSIZEREL/RELEASE`来影响PaddlePaddle的编译过程。
There are some other arguments you might want to configure. **性能TIPS**， ， ， ：
- 设置`CMAKE_BUILD_TYPE`为`Release`
- `CMAKE_BUILD_TYPE=MinSizeRel` minimizes the size of library.
- 使用`clang`编译工具链
- ` CMAKE_BUILD_TYPE-Release` optimizes the runtime performance.
- ` armeabi-v7a`时，设置`USE_EIGEN_BLAS=ON`， ； ，
Our own tip for performance optimization to use clang and Eigen or OpenBLAS:
### 编译和安装
- `CMAKE_BUILD_TYPE=Release`
- `ANDROID_TOOLCHAIN=clang`
- `USE_EIGEN_BLAS=ON` for `armeabi-v7a` , or `USE_EIGEN_FOR_BLAS=OFF` for `arm64-v8a` .
### Build and Install CMake配置完成后， ，
After running `cmake` , we can run `make; make install` to build and install.
```bash
make
Before building, you might want to remove the `third_party` and `build` directories including pre-built libraries for other architectures.
make install
```
After building， `CMAKE_INSTALL_PREFIX` , you will find three sub-directories: 注意： ， ，
- `include` : the header file of the inference library,
执行完安装命令后，`your/path/to/install`目录中会包含`include`、`lib`和`third_party`目录，其中`include`中包含C-API的头文件， ， ， ， ，
- `lib` : the inference library built for various Android ABIs,
- `third_party` : dependent third-party libraries built for Android.
Liu Yiqun
8 years ago