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.

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
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
edgchen1 marked this conversation as resolved.
Show resolved Hide resolved
* 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
Loading