Merge pull request pytorch#566 from jeffxtang/mobile_build_lib_from_src

updates of the lib build from source for ios and android

Author: brianjo

_mobile/android.md

@@ -203,7 +203,7 @@ After that, the code processes the output, finding classes with the highest scor
 
 ## Building PyTorch Android from Source
 
-In some cases you might want to use a local build of pytorch android, for example you may build custom libtorch binary with another set of operators or to make local changes.
+In some cases you might want to use a local build of PyTorch android, for example you may build custom libtorch binary with another set of operators or to make local changes, or try out the latest PyTorch code.
 
 For this you can use `./scripts/build_pytorch_android.sh` script.
 ```
@@ -218,11 +218,11 @@ The workflow contains several steps:
 
 2\. Create symbolic links to the results of those builds:
 `android/pytorch_android/src/main/jniLibs/${abi}` to the directory with output libraries
-`android/pytorch_android/src/main/cpp/libtorch_include/${abi}` to the directory with headers. These directories are used to build `libpytorch.so` library that will be loaded on android device.
+`android/pytorch_android/src/main/cpp/libtorch_include/${abi}` to the directory with headers. These directories are used to build `libpytorch_jni.so` library, as part of the `pytorch_android-release.aar` bundle, that will be loaded on android device.
 
 3\. And finally run `gradle` in `android/pytorch_android` directory with task `assembleRelease`
 
-Script requires that Android SDK, Android NDK and gradle are installed.
+Script requires that Android SDK, Android NDK, Java SDK, and gradle are installed.
 They are specified as environment variables:
 
 `ANDROID_HOME` - path to [Android SDK](https://developer.android.com/studio/command-line/sdkmanager.html)
@@ -231,17 +231,20 @@ They are specified as environment variables:
 
 `GRADLE_HOME` - path to [gradle](https://gradle.org/releases/)
 
+`JAVA_HOME` - path to [JAVA JDK](https://www.oracle.com/java/technologies/javase-downloads.html#javasejdk)
 
-After successful build you should see the result as aar file:
+
+After successful build, you should see the result as aar file:
 
 ```
-$ find pytorch_android/build/ -type f -name *aar
-pytorch_android/build/outputs/aar/pytorch_android.aar
-pytorch_android_torchvision/build/outputs/aar/pytorch_android.aar
-libs/fbjni_local/build/outputs/aar/pytorch_android_fbjni.aar
+$ find android -type f -name *aar
+android/pytorch_android/build/outputs/aar/pytorch_android-release.aar
+android/pytorch_android_torchvision/build/outputs/aar/pytorch_android_torchvision-release.aar
 ```
 
-It can be used directly in android projects, as a gradle dependency:
+## Using the PyTorch Android Libraries Built from Source or Nightly
+
+First add the two aar files built above, or downloaded from the nightly built PyTorch Android repos at [here](https://oss.sonatype.org/#nexus-search;quick~pytorch_android) and [here](https://oss.sonatype.org/#nexus-search;quick~torchvision_android), to the Android project's `lib` folder, then add in the project's `build.gradle` file:
 ```
 allprojects {
     repositories {
@@ -251,32 +254,23 @@ allprojects {
     }
 }
 
-android {
-    ...
-    packagingOptions {
-        pickFirst "**/libfbjni.so"
-    }
-    ...
-}
-
 dependencies {
-    implementation(name:'pytorch_android', ext:'aar')
-    implementation(name:'pytorch_android_torchvision', ext:'aar')
-    implementation(name:'pytorch_android_fbjni', ext:'aar')
+
+    // if using the libraries built from source
+    implementation(name:'pytorch_android-release', ext:'aar')
+    implementation(name:'pytorch_android_torchvision-release', ext:'aar')
+
+    // if using the nightly built libraries downloaded above, for example the 1.8.0-snapshot on Jan. 21, 2021
+    // implementation(name:'pytorch_android-1.8.0-20210121.092759-172', ext:'aar')
+    // implementation(name:'pytorch_android_torchvision-1.8.0-20210121.092817-173', ext:'aar')
+
     ...
     implementation 'com.android.support:appcompat-v7:28.0.0'
-    implementation 'com.facebook.soloader:nativeloader:0.8.0'
-}
-```
-
-At the moment for the case of using aar files directly we need additional configuration due to packaging specific (`libfbjni.so` is packaged in both `pytorch_android_fbjni.aar` and `pytorch_android.aar`).
-```
-packagingOptions {
-    pickFirst "**/libfbjni.so"
+    implementation 'com.facebook.fbjni:fbjni-java-only:0.0.3'
 }
 ```
 
-Also we have to add all transitive dependencies of our aars. As `pytorch_android` depends on `com.android.support:appcompat-v7:28.0.0` and `com.facebook.soloader:nativeloader:0.8.0`, we need to add them. (In case of using maven dependencies they are added automatically from `pom.xml`).
+Also we have to add all transitive dependencies of our aars. As `pytorch_android` depends on `com.android.support:appcompat-v7:28.0.0` or `androidx.appcompat:appcompat:1.2.0`, we need to one of them. (In case of using maven dependencies they are added automatically from `pom.xml`).
 
 
 ## Custom Build

_mobile/ios.md

@@ -162,7 +162,7 @@ git submodule update --init --recursive
 
 ### Build LibTorch for iOS Simulators
 
-Open terminal and navigate to the PyTorch root directory. Run the following command
+Open terminal and navigate to the PyTorch root directory. Run the following command (if you already build LibTorch for iOS devices (see below), run `rm -rf build_ios` first):
 
 ```
 BUILD_PYTORCH_MOBILE=1 IOS_PLATFORM=SIMULATOR ./scripts/build_ios.sh
@@ -171,7 +171,7 @@ After the build succeeds, all static libraries and header files will be generate
 
 ### Build LibTorch for arm64 Devices
 
-Open terminal and navigate to the PyTorch root directory. Run the following command
+Open terminal and navigate to the PyTorch root directory. Run the following command (if you already build LibTorch for iOS simulators, run `rm -rf build_ios` first):
 
 ```
 BUILD_PYTORCH_MOBILE=1 IOS_ARCH=arm64 ./scripts/build_ios.sh
@@ -180,14 +180,25 @@ After the build succeeds, all static libraries and header files will be generate
 
 ### XCode Setup
 
-Open your project in XCode, copy all the static libraries as well as header files to your project. Navigate to the project settings, set the value **Header Search Paths** to the path of header files you just copied.
+Open your project in XCode, go to your project Target's `Build Phases` - `Link Binaries With Libraries`, click the + sign and add all the library files located in `build_ios/install/lib`. Navigate to the project `Build Settings`, set the value **Header Search Paths** to `build_ios/install/include` and **Library Search Paths** to `build_ios/install/lib`.
 
 In the build settings, search for **other linker flags**.  Add a custom linker flag below
 
 ```
 -all_load
 ```
- Finally, disable bitcode for your target by selecting the Build Settings, searching for **Enable Bitcode**, and set the value to **No**.
+
+To use the custom built libraries the project, replace `#import <LibTorch/LibTorch.h>` (in `TorchModule.mm`) which is needed when using LibTorch via Cocoapods with the code below:
+```
+#include "ATen/ATen.h"
+#include "caffe2/core/timer.h"
+#include "caffe2/utils/string_utils.h"
+#include "torch/csrc/autograd/grad_mode.h"
+#include "torch/csrc/jit/serialization/import.h"
+#include "torch/script.h"
+```
+
+Finally, disable bitcode for your target by selecting the Build Settings, searching for **Enable Bitcode**, and set the value to **No**.