Skip to content

[Android] update tutorial and provide a SDK setup tutorial #2879

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

Closed
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
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
19 changes: 15 additions & 4 deletions examples/demo-apps/android/LlamaDemo/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,12 +3,18 @@
This app demonstrates the use of the LLaMA chat app demonstrating local inference use case with ExecuTorch.

## Prerequisites
* Refer to [Setting up ExecuTorch](https://pytorch.org/executorch/stable/getting-started-setup) to set up the repo and dev environment.
* Download and install [Android Studio and SDK](https://developer.android.com/studio).
* Set up your ExecuTorch repo and environment if you haven’t done so by following the [Setting up ExecuTorch](https://pytorch.org/executorch/stable/getting-started-setup) to set up the repo and dev environment.
* Install [Java 17 JDK](https://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html).
* Install the [Android SDK API Level 34](https://developer.android.com/about/versions/14/setup-sdk) and
[Android NDK 25.0.8775105](https://developer.android.com/studio/projects/install-ndk).
* If you have Android Studio set up, you can install them with
* Android Studio Settings -> Language & Frameworks -> Android SDK -> SDK Platforms -> Check the row with API Level 34.
* Android Studio Settings -> Language & Frameworks -> Android SDK -> SDK Tools -> Check NDK (Side by side) row.
* Alternatively, you can follow [this guide](https://github.com/pytorch/executorch/blob/856e085b9344c8b0bf220a97976140a5b76356aa/examples/demo-apps/android/LlamaDemo/SDK.md) to set up Java/SDK/NDK with CLI.
* Supported Host OS: CentOS, macOS Sonoma on Apple Silicon.

```{note}
This demo app and tutorial has only been validated with arm64-v8a [ABI](https://developer.android.com/ndk/guides/abis), with NDK 25.
This demo app and tutorial has only been validated with arm64-v8a [ABI](https://developer.android.com/ndk/guides/abis), with NDK 25.0.8775105.
```

## Getting models
Expand All @@ -28,6 +34,11 @@ The demo app searches in `/data/local/tmp/llama` for .pte and .bin files as LLAM
## Build JNI library
1. Open a terminal window and navigate to the root directory of the `executorch`.
2. Set the following environment variables:
```{note}
<path_to_android_ndk> is the root for the NDK, which is usually under
~/Library/Android/sdk/ndk/XX.Y.ZZZZZ for macOS, and contains NOTICE and README.md.
We use <path_to_android_ndk>/build/cmake/android.toolchain.cmake for CMake to cross-compile.
```
```bash
export ANDROID_NDK=<path_to_android_ndk>
export ANDROID_ABI=arm64-v8a
Expand All @@ -40,7 +51,7 @@ popd
```
This is running the shell script [setup.sh](./setup.sh) which configures the required core ExecuTorch, LLAMA2, and Android libraries, builds them, and copy to jniLibs.

## Build Java app
## Build APK
### Alternative 1: Android Studio (Recommended)
1. Open Android Studio and select "Open an existing Android Studio project" to open examples/demo-apps/android/LlamaDemo.
2. Run the app (^R). This builds and launches the app on the phone.
Expand Down
94 changes: 94 additions & 0 deletions examples/demo-apps/android/LlamaDemo/SDK-quick-setup-guide.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
# Guide to set up Java/SDK/NDK for Android

Follow this doc if you haven't set up Java/SDK/NDK for Android development
already.
This doc provides a CLI tutorial to set them up. Otherwise, you can do the same
thing with Android Studio GUI.

## Set up Java 17
1. Download the archive from Oracle website.
Make sure you have read and agree with the terms and conditions from the website before downloading.
```bash
export DEV_HOME=<path-to-dev>
cd $DEV_HOME
```
Linux:
```bash
curl https://download.oracle.com/java/17/archive/jdk-17.0.10_linux-x64_bin.tar.gz -o jdk-17.0.10.tar.gz
```
macOS:
```bash
curl https://download.oracle.com/java/17/archive/jdk-17.0.10_macos-aarch64_bin.tar.gz -o jdk-17.0.10.tar.gz
```
2. Unzip the archive. The directory named `jdk-17.0.10` is the Java root directory.
```bash
tar xf jdk-17.0.10.tar.gz
```
3. Set `JAVA_HOME` and update `PATH`.

Linux:
```bash
export JAVA_HOME="$DEV_HOME"/jdk-17.0.10
export PATH="$JAVA_HOME/bin:$PATH"
```
macOS:
```bash
export JAVA_HOME="$DEV_HOME"/jdk-17.0.10.jdk/Contents/Home
export PATH="$JAVA_HOME/bin:$PATH"
```

Note: Oracle has tutorials for installing Java on
[Linux](https://docs.oracle.com/en/java/javase/17/install/installation-jdk-linux-platforms.html#GUID-4A6BD592-1840-4BB4-A758-4CD49E9EE88B)
and [macOS](https://docs.oracle.com/en/java/javase/17/install/installation-jdk-macos.html#GUID-E8A251B6-D9A9-4276-ABC8-CC0DAD62EA33).
Some Linux distributions has JDK package in package manager. For example, Debian users can install
openjdk-17-jdk package.

## Set up Android SDK/NDK
Android has a command line tool [sdkmanager](https://developer.android.com/tools/sdkmanager) which
helps users managing SDK and other tools related to Android development.

1. Go to https://developer.android.com/studio and download the archive from "Command line tools
only" section. Make sure you have read and agree with the terms and conditions from the website.

Linux:
```bash
curl https://dl.google.com/android/repository/commandlinetools-linux-11076708_latest.zip -o commandlinetools.zip
```
macOS:
```bash
curl https://dl.google.com/android/repository/commandlinetools-mac-11076708_latest.zip -o commandlinetools.zip
```
2. Unzip.
```bash
unzip commandlinetools.zip
```
3. Specify a root for Android SDK. For example, we can put it under `$DEV_HOME/sdk`.

```
mkdir -p $DEV_HOME/sdk
export ANDROID_HOME="$(realpath $DEV_HOME/sdk)"
# Install SDK 34
./cmdline-tools/bin/sdkmanager --sdk_root="${ANDROID_HOME}" --install "platforms;android-34"
# Install NDK
./cmdline-tools/bin/sdkmanager --sdk_root="${ANDROID_HOME}" --install "ndk;25.0.8775105"
# The NDK root is then under `ndk/<version>`.
export ANDROID_NDK="$ANDROID_HOME/ndk/25.0.8775105"
```

### (Optional) Android Studio Setup
If you want to use Android Studio and never set up Java/SDK/NDK before, or if
you use the newly installed ones, follow these steps to set Android Studio to use
them.

Copy these output paths to be used by Android Studio
```bash
echo $ANDROID_HOME
echo $ANDROID_NDK
echo $JAVA_HOME
```

Open a project in Android Studio. In Project Structure (File -> Project
Structure, or `⌘;`) -> SDK Location,
* Set Android SDK Location to the path of $ANDROID_HOME
* Set Android NDK Location to the path of $ANDROID_NDK
* Set JDK location (Click Gradle Settings link) -> Gradle JDK -> Add JDK... to the path of $JAVA_HOME