diff --git a/BUILDING.md b/BUILDING.md index 64bfbf5b88..bdeac3684f 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -242,6 +242,12 @@ foremost for `arm64-v8a`. To build Android on Windows machines, see [android/Windows.md](android/Windows.md). +#### Important: SDK location + +Either ensure your `ANDROID_HOME` environment variable is set or make sure the root project +contains a `local.properties` file with the `sdk.dir` property pointing to your installation of +the Android SDK. + #### Easy Android build The easiest way to build Filament for Android is to use `build.sh` and the @@ -251,8 +257,45 @@ The easiest way to build Filament for Android is to use `build.sh` and the ./build.sh -p android release ``` +To build a sample (such as `android/samples/sample-hello-triangle`) for an ARM 64-bit phone, you would run +```shell +./build.sh -p android -q arm64-v8a -k sample-hello-triangle release +``` + +The output APK can be found in `android/samples/sample-hello-triangle/build/outputs/apk/release/sample-hello-triangle-release-unsigned.apk` + Run `build.sh -h` for more information. +#### Android Studio + +You must use the latest stable release of Android Studio. + +The Android build of filament is separated into java/kotlin client APIs, a layer of jni bindings +that bridges java/kotlin with native code, and Filament and other component code that have been compiled +into architecture-specific libraries. Our default Android Studio gradle setup can compile java/kotlin and +the jni bindings for you, but it will treat the filament libraries as already compiled and present on +the system. + +Therefore, before compiling the sample app or any other targets, you must +make sure that the native filament libraries have been compiled and are located at a prescribed location +so that the jni bindings can link against them. You can do so by using the easy build script + +```shell +./build.sh -p android release -q arm64-v8a +``` + +Note that the above step will also install host machine tools into prescribed locations. These tools are +required for compiling Filament assets such as materials and environment maps. + +Now we are ready to compile the apps. To open the project, point Studio to the `android` folder. +After opening the project and syncing with Gradle, select the sample of your choice +using the drop-down widget in the toolbar. Additionally, you will need to select a deployment target. +By doing so, Android Studio will automatically try to compile the app only for that specific +device's architecture. So if you are targeting a new Pixel phone, make sure that the step above +(compiling the library) is targeting ARM 64-bit (`-q arm64-v8a` ), and if you are running the app on +an emulator on a Linux machine with an x86 64-bit chipset, you would indicate (`-q x86_64`) in the above step. + + #### Manual builds Invoke CMake in a build directory of your choice, inside of filament's directory. The commands diff --git a/android/samples/README.md b/android/samples/README.md index cdfc93e2e2..c87ccafcd9 100644 --- a/android/samples/README.md +++ b/android/samples/README.md @@ -80,54 +80,12 @@ frame and the external texture are perfectly synchronized. ![Stream Test](../../docs/images/samples/sample_stream_test.jpg) -## Prerequisites +## Building Samples Before you start, make sure to read [Filament's README](../../README.md). You need to be able to compile Filament's native library and Filament's AAR for this project. The easiest way to proceed is to install all the required dependencies and to run the following commands at the root of the -source tree: +source tree. -```shell -./build.sh -p desktop -i release -./build.sh -p android release -``` +To build the samples, please follow the steps described in [BUILDING.md](../../BUILDING.md#android) -This will build all the native components and the AAR required by this sample application. - -If you do not use the build script, you must set the `filament_tools_dir` property when invoking -Gradle, either from the command line or from `local.properties`. This property must point to the -distribution/install directory for desktop (produced by make/ninja install). This directory must -contain `bin/matc` and `bin/cmgen`. - -Example: -```shell -./gradlew -Pfilament_tools_dir=../../dist-release assembleDebug -``` - -## Important: SDK location - -Either ensure your `ANDROID_HOME` environment variable is set or make sure the root project -contains a `local.properties` file with the `sdk.dir` property pointing to your installation of -the Android SDK. - -## Compiling - -### Android Studio - -You must use the latest stable release of Android Studio. To open the project, point Studio to the -`android` folder. After opening the project and syncing to gradle, select the sample of your choice -using the drop-down widget in the toolbar. - -To compile and run each sample make sure you have selected the appropriate build variant -(arm7, arm8, x86 or x86_64). If you are not sure you can simply select the "universal" -variant which includes all the other ones. - -### Command Line - -From the `android` directory in the project root: - -```shell -./gradlew :samples:sample-hello-triangle:installDebug -``` - -Replace `sample-hello-triangle` with your preferred project. diff --git a/build.sh b/build.sh index 387c6b38e7..ecabc0fb1f 100755 --- a/build.sh +++ b/build.sh @@ -556,11 +556,14 @@ function build_android { archive_android "Release" fi + local root_dir=$(pwd) + pushd android > /dev/null if [[ "${ISSUE_DEBUG_BUILD}" == "true" ]]; then ./gradlew \ -Pcom.google.android.filament.dist-dir=../out/android-debug/filament \ + -Pcom.google.android.filament.tools-dir=${root_dir}/out/debug/filament \ -Pcom.google.android.filament.abis=${ABI_GRADLE_OPTION} \ ${VULKAN_ANDROID_GRADLE_OPTION} \ ${WEBGPU_ANDROID_GRADLE_OPTION} \ @@ -573,6 +576,7 @@ function build_android { ./gradlew \ -Pcom.google.android.filament.dist-dir=../out/android-debug/filament \ + -Pcom.google.android.filament.tools-dir=${root_dir}/out/debug/filament \ -Pcom.google.android.filament.abis=${ABI_GRADLE_OPTION} \ ${WEBGPU_ANDROID_GRADLE_OPTION} \ :filamat-android:assembleDebug @@ -581,6 +585,7 @@ function build_android { for sample in ${ANDROID_SAMPLES}; do ./gradlew \ -Pcom.google.android.filament.dist-dir=../out/android-debug/filament \ + -Pcom.google.android.filament.tools-dir=${root_dir}/out/debug/filament \ -Pcom.google.android.filament.abis=${ABI_GRADLE_OPTION} \ ${MATOPT_GRADLE_OPTION} \ :samples:${sample}:assembleDebug @@ -613,6 +618,7 @@ function build_android { if [[ "${ISSUE_RELEASE_BUILD}" == "true" ]]; then ./gradlew \ -Pcom.google.android.filament.dist-dir=../out/android-release/filament \ + -Pcom.google.android.filament.tools-dir=${root_dir}/out/release/filament \ -Pcom.google.android.filament.abis=${ABI_GRADLE_OPTION} \ ${VULKAN_ANDROID_GRADLE_OPTION} \ ${WEBGPU_ANDROID_GRADLE_OPTION} \ @@ -625,6 +631,7 @@ function build_android { ./gradlew \ -Pcom.google.android.filament.dist-dir=../out/android-release/filament \ + -Pcom.google.android.filament.tools-dir=${root_dir}/out/release/filament \ -Pcom.google.android.filament.abis=${ABI_GRADLE_OPTION} \ ${WEBGPU_ANDROID_GRADLE_OPTION} \ :filamat-android:assembleRelease @@ -633,6 +640,7 @@ function build_android { for sample in ${ANDROID_SAMPLES}; do ./gradlew \ -Pcom.google.android.filament.dist-dir=../out/android-release/filament \ + -Pcom.google.android.filament.tools-dir=${root_dir}/out/release/filament \ -Pcom.google.android.filament.abis=${ABI_GRADLE_OPTION} \ ${MATOPT_GRADLE_OPTION} \ :samples:${sample}:assembleRelease