Skip to content

Commit

Permalink
[docs] Mobile doc updates (#21605)
Browse files Browse the repository at this point in the history
### Description
<!-- Describe your changes. -->

- Update Android build instructions.
- Remove references to "mobile" packages with reduced operators and
minimal build which have been removed in 1.19.
  In particular, these packages:
  - onnxruntime-mobile-c/objc (iOS)
  - onnxruntime-mobile (Android)

https://edgchen1.github.io/onnxruntime/docs/

### Motivation and Context
<!-- - Why is this change required? What problem does it solve?
- If it fixes an open issue, please link to the issue here. -->

Update and remove obsolete documentation.
  • Loading branch information
edgchen1 authored Aug 15, 2024
1 parent bd060ab commit 2920978
Show file tree
Hide file tree
Showing 13 changed files with 117 additions and 158 deletions.
18 changes: 8 additions & 10 deletions docs/build/android.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,8 @@ The SDK and NDK packages can be installed via Android Studio or the sdkmanager c
Android Studio is more convenient but a larger installation.
The command line tools are smaller and usage can be scripted, but are a little more complicated to setup. They also require a Java runtime environment to be available.

Generally, you'll want to use the latest stable NDK version. We'll refer to the version that you use as `<NDK version>` from here on.

Resources:

* [API levels](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html)
Expand All @@ -36,16 +38,15 @@ Resources:
2. Install any additional SDK Platforms if necessary

* File->Settings->Appearance & Behavior->System Settings->Android SDK to see what is currently installed
* Note that the SDK path you need to use as --android_sdk_path when building ORT is also on this configuration page
* Note that the SDK path you need to use as `--android_sdk_path` when building ORT is also on this configuration page
* Most likely you don't require additional SDK Platform packages as the latest platform can target earlier API levels.

3. Install an NDK version

* File->Settings->Appearance & Behavior->System Settings->Android SDK
* 'SDK Tools' tab
* Select 'Show package details' checkbox at the bottom to see specific versions. By default the latest will be installed which should be fine.
* The NDK path will be the 'ndk/{version}' subdirectory of the SDK path shown
* e.g. if 21.1.6352462 is installed it will be {SDK path}/ndk/21.1.6352462
* The NDK path will be the `ndk/<NDK version>` subdirectory of the SDK path shown

### sdkmanager from command line tools

Expand Down Expand Up @@ -81,9 +82,8 @@ Resources:
* Install the NDK
* Find the available NDK versions by running `sdkmanager --list`
* Install
* you can install a specific version or the latest (called 'ndk-bundle') e.g. `sdkmanager --install "ndk;21.1.6352462"`
* NDK path in our example with this install would be `.../Android/ndk/21.1.6352462`
* NOTE: If you install the ndk-bundle package the path will be `.../Android/ndk-bundle` as there's no version number
* install the desired version, e.g., `sdkmanager --install "ndk;<NDK version>"`
* NDK path in our example with this install would be `.../Android/ndk/<NDK version>`

## Android Build Instructions

Expand All @@ -98,7 +98,7 @@ The [Ninja](https://ninja-build.org/) generator needs to be used to build on Win
e.g. using the paths from our example
```
./build.bat --android --android_sdk_path .../Android --android_ndk_path .../Android/ndk/21.1.6352462 --android_abi arm64-v8a --android_api 27 --cmake_generator Ninja
./build.bat --android --android_sdk_path .../Android --android_ndk_path .../Android/ndk/<NDK version> --android_abi arm64-v8a --android_api 27 --cmake_generator Ninja
```
### Cross compiling on Linux and macOS
Expand All @@ -116,14 +116,12 @@ To build on Windows with `--build_java` enabled you must also:
* set JAVA_HOME to the path to your JDK install
* this could be the JDK from Android Studio, or a [standalone JDK install](https://www.oracle.com/java/technologies/javase-downloads.html)
* e.g. Powershell: `$env:JAVA_HOME="C:\Program Files\Java\jdk-15"` CMD: `set JAVA_HOME=C:\Program Files\Java\jdk-15`
* install [Gradle version 6.8.3](https://gradle.org/install/) and add the directory to the PATH
* e.g. Powershell: `$env:PATH="$env:PATH;C:\Gradle\gradle-6.6.1\bin"` CMD: `set PATH=%PATH%;C:\Gradle\gradle-6.6.1\bin`
* run the build from an admin window
* the Java build needs permissions to create a symlink, which requires an admin window
#### Note: Proguard rules for R8 minimization Android app builds to work
For Android consumers using the library with R8-minimized builds, currently you need to add the following line to your `proguard-rules.pro` file inside your Android project to use package `com.microsoft.onnxruntime:onnxruntime-android` (for Full build) or `com.microsoft.onnxruntime:onnxruntime-mobile` (for Mobile build) to avoid runtime crashes:
For Android consumers using the library with R8-minimized builds, currently you need to add the following line to your `proguard-rules.pro` file inside your Android project to use package `com.microsoft.onnxruntime:onnxruntime-android` to avoid runtime crashes:
```
-keep class ai.onnxruntime.** { *; }
Expand Down
28 changes: 14 additions & 14 deletions docs/build/custom.md
Original file line number Diff line number Diff line change
Expand Up @@ -157,7 +157,7 @@ Find them [here](https://github.com/microsoft/onnxruntime/tags).

## Custom build packages

In this section, `ops.config` is a [configuration file](../reference/operators/reduced-operator-config-file.md) that specifies the opsets, op kernels, and types to include. See the configuration file used by the pre-built mobile packages at [tools/ci_build/github/android/mobile_package.required_operators.config](https://github.com/microsoft/onnxruntime/blob/main/tools/ci_build/github/android/mobile_package.required_operators.config).
In this section, `ops.config` is a [configuration file](../reference/operators/reduced-operator-config-file.md) that specifies the opsets, op kernels, and types to include.

### Web

Expand All @@ -182,9 +182,9 @@ To produce pods for an iOS build, use the [build_and_assemble_apple_pods.py](htt

This will do a custom build and create the pod package files for it in /path/to/staging/dir.

The build options are specified with the file provided to the `--build-settings-file` option. See the current build options used by the pre-built mobile package at [tools/ci_build/github/apple/default_mobile_ios_framework_build_settings.json](https://github.com/microsoft/onnxruntime/blob/main/tools/ci_build/github/apple/default_mobile_ios_framework_build_settings.json). You can use this file directly.
The build options are specified with the file provided to the `--build-settings-file` option. See the current build options used by the pre-built package at [tools/ci_build/github/apple/default_full_apple_framework_build_settings.json](https://github.com/microsoft/onnxruntime/blob/main/tools/ci_build/github/apple/default_full_apple_framework_build_settings.json). You can use this file directly.

The reduced set of ops in the custom build is specified with the file provided to the `--include_ops_by_config` option. See the current op config used by the pre-built mobile package at [tools/ci_build/github/android/mobile_package.required_operators.config](https://github.com/microsoft/onnxruntime/blob/main/tools/ci_build/github/android/mobile_package.required_operators.config) (Android and iOS pre-built mobile packages share the same config file). You can use this file directly.
The reduced set of ops in the custom build is specified with the [configuration file](../reference/operators/reduced-operator-config-file.md) provided to the `--include_ops_by_config` option. This is optional.

The default package does not include the training APIs. To create a training package, add `--enable_training_apis` in the build options file provided to `--build-settings-file` and add the `--variant Training` option when calling `build_and_assemble_apple_pods.py`.

Expand All @@ -202,15 +202,15 @@ To produce pods for an iOS build, use the [build_and_assemble_apple_pods.py](htt

3. Use the local pods.

For example, update the Podfile to use the local onnxruntime-mobile-objc pod instead of the released one:
For example, update the Podfile to use the local onnxruntime-objc pod instead of the released one:

```diff
- pod 'onnxruntime-mobile-objc'
+ pod 'onnxruntime-mobile-objc', :path => "/path/to/staging/dir/onnxruntime-mobile-objc"
+ pod 'onnxruntime-mobile-c', :path => "/path/to/staging/dir/onnxruntime-mobile-c"
- pod 'onnxruntime-objc'
+ pod 'onnxruntime-objc', :path => "/path/to/staging/dir/onnxruntime-objc"
+ pod 'onnxruntime-c', :path => "/path/to/staging/dir/onnxruntime-c"
```

Note: The onnxruntime-mobile-objc pod depends on the onnxruntime-mobile-c pod. If the released onnxruntime-mobile-objc pod is used, this dependency is automatically handled. However, if a local onnxruntime-mobile-objc pod is used, the local onnxruntime-mobile-c pod that it depends on also needs to be specified in the Podfile.
Note: The onnxruntime-objc pod depends on the onnxruntime-c pod. If the released onnxruntime-objc pod is used, this dependency is automatically handled. However, if a local onnxruntime-objc pod is used, the local onnxruntime-c pod that it depends on also needs to be specified in the Podfile.

### Android

Expand All @@ -236,23 +236,23 @@ Note: In the steps below, replace `<ORT version>` with the ONNX Runtime version

Specify the ONNX Runtime version you want to use with the `--onnxruntime_branch_or_tag` option. The script uses a separate copy of the ONNX Runtime repo in a Docker container so this is independent from the containing ONNX Runtime repo's version.
The build options are specified with the file provided to the `--build_settings` option. See the current build options used by the pre-built mobile package at [tools/ci_build/github/android/default_mobile_aar_build_settings.json](https://github.com/microsoft/onnxruntime/blob/main/tools/ci_build/github/android/default_mobile_aar_build_settings.json).
The build options are specified with the file provided to the `--build_settings` option. See the current build options used by the pre-built package at [tools/ci_build/github/android/default_full_aar_build_settings.json](https://github.com/microsoft/onnxruntime/blob/main/tools/ci_build/github/android/default_full_aar_build_settings.json).
The reduced set of ops in the custom build is specified with the file provided to the `--include_ops_by_config` option. See the current op config used by the pre-built mobile package at [tools/ci_build/github/android/mobile_package.required_operators.config](https://github.com/microsoft/onnxruntime/blob/main/tools/ci_build/github/android/mobile_package.required_operators.config).
The reduced set of ops in the custom build is specified with the [configuration file](../reference/operators/reduced-operator-config-file.md) provided to the `--include_ops_by_config` option.
The `--build_settings` and `--include_ops_by_config` options are both optional and will default to what is used to build the pre-built mobile package. Not specifying either will result in a package like the pre-built mobile package.
The `--build_settings` and `--include_ops_by_config` options are both optional and will default to what is used to build the pre-built package. Not specifying either will result in a package like the pre-built package.
2. Use the local custom Android AAR package.
For example, in an Android Studio project:
a. Copy the AAR file from `/path/to/working/dir/output/aar_out/<build config, e.g., Release>/com/microsoft/onnxruntime/onnxruntime-mobile/<ORT version>/onnxruntime-mobile-<ORT version>.aar` to the project's `<module name, e.g., app>/libs` directory.
a. Copy the AAR file from `/path/to/working/dir/output/aar_out/<build config, e.g., Release>/com/microsoft/onnxruntime/onnxruntime-android/<ORT version>/onnxruntime-android-<ORT version>.aar` to the project's `<module name, e.g., app>/libs` directory.

b. Update the project's `<module name>/build.gradle` file dependencies section:
```diff
- implementation 'com.microsoft.onnxruntime:onnxruntime-mobile:latest.release'
+ implementation files('libs/onnxruntime-mobile-<ORT version>.aar')
- implementation 'com.microsoft.onnxruntime:onnxruntime-android:latest.release'
+ implementation files('libs/onnxruntime-android-<ORT version>.aar')
```
### Python
Expand Down
4 changes: 2 additions & 2 deletions docs/get-started/with-obj-c.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,15 +16,15 @@ ONNX Runtime provides an Objective-C API for running ONNX models on iOS devices.

## Supported Versions

iOS 11+.
See iOS [compatibility info](../reference/compatibility.md).

## Builds

The artifacts are published to CocoaPods.

| Artifact | Description | Supported Platforms |
|-|-|-|
| onnxruntime-mobile-objc | CPU and CoreML | iOS |
| onnxruntime-objc | CPU and CoreML | iOS |

Refer to the [installation instructions](../install/index.md#install-on-ios).

Expand Down
Loading

0 comments on commit 2920978

Please sign in to comment.