Added directions for building gdext for Android

src/SUMMARY.md

@@ -24,6 +24,7 @@
   - [Compatibility and stability](toolchain/compatibility.md)
   - [Selecting a Godot version](toolchain/godot-version.md)
   - [Debugging](toolchain/debugging.md)
+  - [Export to Android](toolchain/export-android.md)
   - [Export to Web](toolchain/export-web.md)
 - [Recipes](recipes/index.md)
   - [Custom resources](recipes/custom-resources.md)

src/toolchain/export-android.md

@@ -0,0 +1,104 @@
+<!--
+ ~ Copyright (c) godot-rust; Bromeon and contributors.
+ ~ This Source Code Form is subject to the terms of the Mozilla Public
+ ~ License, v. 2.0. If a copy of the MPL was not distributed with this
+ ~ file, You can obtain one at https://mozilla.org/MPL/2.0/.
+-->
+
+# Export to Android
+
+NOTE: Keep track of where you install the Android Command Line Tools and JDK 17
+
+Exporting with gdext for Godot requires some of the same pieces that are required for building Godot from source.
+Specifically, the Android SDK Command Line Tools and JDK 17 as mentioned in Godot's documentation
+[here](https://docs.godotengine.org/en/stable/contributing/development/compiling/compiling_for_android.html#requirements)
+
+Once you have those installed, you then need to follow Godot's instructions for setting up the build system
+[here](https://docs.godotengine.org/en/stable/contributing/development/compiling/compiling_for_android.html#setting-up-the-buildsystem)
+
+As of writing this, it is not entirely clear if JDK 17 is required in order for Android Command Line Tools to function properly.
+It has not been not tested without it. To be safe, it is included in the documentation for now.
+
+
+## Compiling
+
+The environment variable `CLANG_PATH` is used by bindgen's clang-sys dependency. See also
+[clang-sys documentation](https://github.com/KyleMayes/clang-sys?tab=readme-ov-file#environment-variables)
+
+Set the environment variable `CLANG_PATH` to point to Android's build of clang. Example:
+
+```bash
+export CLANG_PATH = "{androidCliDirectory}/{androidCliVersion}/ndk/{ndkVersion}/toolchains/llvm/prebuilt/{hostMachineOs}/bin/clang"
+```
+
+Then set the `CARGO_TARGET_{targetTripleHere}_LINKER` to point to the Android linker for the Android triple you are targeting.
+You need to compile your gdext library for each Android triple individually. Possible targets can be found by running:
+
+```bash
+rustup target list
+```
+
+You can find the linkers in the Android CLI directory at:
+
+```text
+"{androidCliDirectory}/{androidCliVersion}/ndk/{ndkVersion}/toolchains/llvm/prebuilt/{hostMachineOs}/bin/{targetTripleHere}{androidVersion}"
+```
+
+As of writing this, the tested tuples are:
+
+| Tuple                       | Environment Variable                            | Godot Arch     | GDExtension Config            |
+| --------------------------- | ----------------------------------------------- | -------------- | ----------------------------- |
+| `aarch64-linux-android`     | `CARGO_TARGET_AARCH64_LINUX_ANDROID_LINKER`     | `arm64`        | `android.debug.arm64`         |
+| `x86_64-linux-android`      | `CARGO_TARGET_X86_64_LINUX_ANDROID_LINKER`      | `x86_64`       | `android.debug.x86_64`        |
+| `armv7-linux-androideabi`   | `CARGO_TARGET_ARMV7_LINUX_ANDROID_LINKER`       | `arm32`        | `android.debug.armeabi-v7a`   |
+| `i686-linux-android`        | `CARGO_TARGET_I686_LINUX_ANDROID_LINKER`        | `x86_32`       | `android.debug.x86`           |
+
+Notice how the environment variables are in all caps and the triple's "-" is replaced with "_"
+
+Make sure to add all of the triples you want to support to the ``rustup`` via:
+
+```bash
+rustup target add {androidTripleHere}
+```
+
+Example:
+
+```bash
+rustup target add aarch64-linux-android
+```
+
+Putting it all together, here is an example compiling for `aarch64-linux-android`. This is also probably the most common
+Android target as of the writing of this.
+
+Assuming 2 things:
+
+1. Android CLI is installed in the `$HOME` folder.
+2. Godot is still relying on Android ndk version: 23.2.8568313. Check
+[here](https://github.com/godotengine/godot/blob/4a0160241fd0c1e874e297f6b08676cf0761e5e8/platform/android/java/app/config.gradle#L14).
+3. The downloaded Android CLI version is: 11076708_latest (update this to be the version you downloaded).
+4. This is being ran on linux. Change the `linux-x86_64` folder in `CLANG_PATH` and `CARGO_TARGET_AARCH64_LINUX_ANDROID_LINKER`
+to be your host machine's operating system.
+5. You are targeting Android version 34.
+
+And here is what the commands look like running from a bash shell:
+
+```bash
+rustup target add aarch64-linux-android
+
+export CLANG_PATH="$HOME/android-cli/11076708_latest/ndk/23.2.8568313/toolchains/llvm/prebuilt/linux-x86_64/bin/clang"
+export CARGO_TARGET_AARCH64_LINUX_ANDROID_LINKER="$HOME/android-cli/11076708_latest/ndk/23.2.8568313/toolchains/llvm/prebuilt/linux-x86_64/bin/aarch64-linux-android34-clang"
+
+cargo build --target=aarch64-linux-android
+```
+
+And then you should find a built version of your GDExtension lib in:
+
+```text
+target/aarch64-linux-android/debug/{libNameHere}.so
+```
+
+Make sure to update your `.gdextension` file to point to the compiled lib. Example:
+
+```text
+android.debug.arm64="res://path/to/rust/lib/target/aarch64-linux-android/debug/{libNameHere}.so
+```