Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[docs] Mobile doc updates #21605

Merged
merged 11 commits into from
Aug 15, 2024
Merged

[docs] Mobile doc updates #21605

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
5f73a94
update android build docs, remove some outdated info
edgchen1 Aug 2, 2024
b618c2e
remove references to mobile packages
edgchen1 Aug 2, 2024
ca4d2a5
update table.svelte
edgchen1 Aug 2, 2024
64a502d
update docs for mobile package ops
edgchen1 Aug 5, 2024
ecedd53
update onnx model opset updater description
edgchen1 Aug 5, 2024
b24a209
update model usability checker example output
edgchen1 Aug 6, 2024
6900c16
add aar binary size measurements
edgchen1 Aug 6, 2024
a8831c2
update measurements with build using more similar settings
edgchen1 Aug 6, 2024
0c77a29
Update docs/install/index.md
edgchen1 Aug 9, 2024
2d78756
Update docs/install/index.md
edgchen1 Aug 9, 2024
514307c
address comments
edgchen1 Aug 9, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 2 additions & 5 deletions docs/build/android.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,9 +81,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"`
* install the desired version, e.g., `sdkmanager --install "ndk;21.1.6352462"`
edgchen1 marked this conversation as resolved.
Show resolved Hide resolved
* 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
edgchen1 marked this conversation as resolved.
Show resolved Hide resolved

## Android Build Instructions

Expand Down Expand Up @@ -116,14 +115,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
View file
Open in desktop
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
View file
Open in desktop
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
45 changes: 12 additions & 33 deletions docs/install/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -147,20 +147,10 @@ dotnet add package Microsoft.AI.MachineLearning

## Install on web and mobile

Unless stated otherwise, the installation instructions in this section refer to pre-built packages that include support
for selected operators and ONNX opset versions based on the requirements of popular models. These packages may be
referred to as "mobile packages". If you use mobile packages, your model must only use the
supported [opsets and operators](../reference/operators/mobile_package_op_type_support_1.14.md).
The pre-built packages have full support for all ONNX opsets and operators.

Another type of pre-built package has full support for all ONNX opsets and operators, at the cost of larger binary size.
These packages are referred to as "full packages".

If the pre-built mobile package supports your model/s but is too large, you can create
a [custom build](../build/custom.md). A custom build can include just the opsets and operators in your model/s to reduce
the size.

If the pre-built mobile package does not include the opsets or operators in your model/s, you can either use the full
package if available, or create a custom build.
If the pre-built package is too large, you can create a [custom build](../build/custom.md).
A custom build can include just the opsets and operators in your model/s to reduce the size.

### JavaScript Installs

Expand Down Expand Up @@ -190,28 +180,22 @@ npm install onnxruntime-react-native

### Install on iOS

In your CocoaPods `Podfile`, add the `onnxruntime-c`, `onnxruntime-mobile-c`, `onnxruntime-objc`,
or `onnxruntime-mobile-objc` pod, depending on whether you want to use a full or mobile package and which API you want
to use.
In your CocoaPods `Podfile`, add the `onnxruntime-c` or `onnxruntime-objc` pod, depending on which API you want to use.

#### C/C++

```ruby
use_frameworks!

# choose one of the two below:
pod 'onnxruntime-c' # full package
#pod 'onnxruntime-mobile-c' # mobile package
pod 'onnxruntime-c'
```

#### Objective-C

```ruby
use_frameworks!

# choose one of the two below:
pod 'onnxruntime-objc' # full package
#pod 'onnxruntime-mobile-objc' # mobile package
pod 'onnxruntime-objc'
```

Run `pod install`.
Expand All @@ -238,19 +222,14 @@ In your Android Studio Project, make the following changes to:

```gradle
dependencies {
// choose one of the two below:
implementation 'com.microsoft.onnxruntime:onnxruntime-android:latest.release' // full package
//implementation 'com.microsoft.onnxruntime:onnxruntime-mobile:latest.release' // mobile package
implementation 'com.microsoft.onnxruntime:onnxruntime-android:latest.release'
}
```

#### C/C++

Download the [onnxruntime-android](https://mvnrepository.com/artifact/com.microsoft.onnxruntime/onnxruntime-android) (
full package) or [onnxruntime-mobile](https://mvnrepository.com/artifact/com.microsoft.onnxruntime/onnxruntime-mobile) (
mobile package) AAR hosted at MavenCentral, change the file extension from `.aar` to `.zip`, and unzip it. Include the
header files from the `headers` folder, and the relevant `libonnxruntime.so` dynamic library from the `jni` folder in
your NDK project.
Download the [onnxruntime-android](https://mvnrepository.com/artifact/com.microsoft.onnxruntime/onnxruntime-android) AAR hosted at MavenCentral, change the file extension from `.aar` to `.zip`, and unzip it.
Include the header files from the `headers` folder, and the relevant `libonnxruntime.so` dynamic library from the `jni` folder in your NDK project.

#### Custom build

Expand Down Expand Up @@ -438,9 +417,9 @@ below:
| WinML | [**Microsoft.AI.MachineLearning**](https://www.nuget.org/packages/Microsoft.AI.MachineLearning) | [ort-nightly (dev)](https://aiinfra.visualstudio.com/PublicPackages/_artifacts/feed/ORT-Nightly/NuGet/Microsoft.AI.MachineLearning/overview) | [View](https://docs.microsoft.com/en-us/windows/ai/windows-ml/port-app-to-nuget#prerequisites) |
| Java | CPU: [**com.microsoft.onnxruntime:onnxruntime**](https://search.maven.org/artifact/com.microsoft.onnxruntime/onnxruntime) | | [View](../api/java) |
| | GPU (CUDA/TensorRT): [**com.microsoft.onnxruntime:onnxruntime_gpu**](https://search.maven.org/artifact/com.microsoft.onnxruntime/onnxruntime_gpu) | | [View](../api/java) |
| Android | [**com.microsoft.onnxruntime:onnxruntime-mobile**](https://search.maven.org/artifact/com.microsoft.onnxruntime/onnxruntime-mobile) | | [View](../install/index.md#install-on-ios) |
| iOS (C/C++) | CocoaPods: **onnxruntime-mobile-c** | | [View](../install/index.md#install-on-ios) |
| Objective-C | CocoaPods: **onnxruntime-mobile-objc** | | [View](../install/index.md#install-on-ios) |
| Android | [**com.microsoft.onnxruntime:onnxruntime-android**](https://search.maven.org/artifact/com.microsoft.onnxruntime/onnxruntime-android) | | [View](../install/index.md#install-on-android) |
edgchen1 marked this conversation as resolved.
Show resolved Hide resolved
| iOS (C/C++) | CocoaPods: **onnxruntime-c** | | [View](../install/index.md#install-on-ios) |
| Objective-C | CocoaPods: **onnxruntime-objc** | | [View](../install/index.md#install-on-ios) |
edgchen1 marked this conversation as resolved.
Show resolved Hide resolved
| React Native | [**onnxruntime-react-native** (latest)](https://www.npmjs.com/package/onnxruntime-react-native) | [onnxruntime-react-native (dev)](https://www.npmjs.com/package/onnxruntime-react-native?activeTab=versions) | [View](../api/js) |
| Node.js | [**onnxruntime-node** (latest)](https://www.npmjs.com/package/onnxruntime-node) | [onnxruntime-node (dev)](https://www.npmjs.com/package/onnxruntime-node?activeTab=versions) | [View](../api/js) |
| Web | [**onnxruntime-web** (latest)](https://www.npmjs.com/package/onnxruntime-web) | [onnxruntime-web (dev)](https://www.npmjs.com/package/onnxruntime-web?activeTab=versions) | [View](../api/js) |
Expand Down
2 changes: 1 addition & 1 deletion docs/tutorials/mobile/deploy-ios.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,7 @@ Here's an example screenshot of the app:
pod install
```

The `Podfile` contains the `onnxruntime-mobile-objc` dependency, which is the pod containing the Objective C API.
The `Podfile` contains the `onnxruntime-objc` dependency, which is the pod containing the Objective C API.
edgchen1 marked this conversation as resolved.
Show resolved Hide resolved

At the end of this step, you should see a file called `ORTObjectDetection.xcworkspace` in the `mobile/examples/object_detection/ios` directory.

Expand Down
Loading
Loading