diff --git a/android/BuildInstructions.md b/android/BuildInstructions.md index 56bac698f180..0c4af11aadc2 100644 --- a/android/BuildInstructions.md +++ b/android/BuildInstructions.md @@ -17,6 +17,9 @@ the Gradle CLI or the Android Studio GUI. ## Build with provided container (recommended) +> __*NOTE:*__ Build with provided container is only supported on Linux and may not work on other +> platforms. + Building both the native libraries and Android project can easily be achieved by running the [containerized-build.sh](../building/containerized-build.sh) script, which helps using the correct tag and mounting volumes. The script relies on [podman](https://podman.io/getting-started/installation.html) @@ -54,14 +57,17 @@ directory configured in step 1: ../building/containerized-build.sh android --app-bundle ``` -## Build without* the provided container (not recommended) +## Build without* the provided container + +> __*NOTE:*__ This guide is only supported on Linux and may not work on other platforms, if you are +> using macOS please refer to [macOS build instructions](./docs/BuildInstructions.macos.md) Building without the provided container requires installing multiple Sdk:s and toolchains, and is -therefore not recommended. +therefore more complex. -*: A container is still used to build `wireguard-go` for Android since it requires a patched version -of `go`. See [this patch](https://git.zx2c4.com/wireguard-android/tree/tunnel/tools/libwg-go/goruntime-boottime-over-monotonic.diff) -for more information. +> __*\*:*__ A container is still used to build `wireguard-go` for Android since it requires a +> patched version of `go`. See [this patch](https://git.zx2c4.com/wireguard-android/tree/tunnel/tools/libwg-go/goruntime-boottime-over-monotonic.diff) +> for more information. ### Setup build environment These steps explain how to manually setup the build environment on a Linux system. @@ -83,18 +89,10 @@ Linux distro: - Install the JDK - **Linux** - ```bash sudo apt install zip openjdk-17-jdk ``` - **macOS** - - ```bash - brew install openjdk@17 - ``` - - Install the SDK The SDK should be placed in a separate directory, like for example `~/android` or `/opt/android`. @@ -134,24 +132,9 @@ Linux distro: - Configure Android cross-compilation targets and set up linker and archiver. This can be done by setting the following environment variables: - **Linux** - Add to `~/.bashrc` or equivalent: ``` export NDK_TOOLCHAIN_DIR="$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/linux-x86_64/bin" - ``` - - **macOS** - - Add to `~/.zshrc` or equivalent: - ``` - export NDK_TOOLCHAIN_DIR="$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/darwin-x86_64/bin" - ``` - - **Both platforms** - - Add the following to the same file as above: - ``` export AR_aarch64_linux_android="$NDK_TOOLCHAIN_DIR/llvm-ar" export AR_armv7_linux_androideabi="$NDK_TOOLCHAIN_DIR/llvm-ar" export AR_x86_64_linux_android="$NDK_TOOLCHAIN_DIR/llvm-ar" diff --git a/android/docs/BuildInstructions.macos.md b/android/docs/BuildInstructions.macos.md new file mode 100644 index 000000000000..f0af51b5ef50 --- /dev/null +++ b/android/docs/BuildInstructions.macos.md @@ -0,0 +1,88 @@ +# Build Instructions for macOS + +This document will guide you to setup your development environment on macOS. It has been +tested on a clean install of macOS Ventura 13.5.1 on a M2 MacBook. + +> __*WARNING:*__ This guide will not apply the [wireguard-go patch](https://git.zx2c4.com/wireguard-android/tree/tunnel/tools/libwg-go/goruntime-boottime-over-monotonic.diff) +> as done in Linux build instructions which may affect app performance. + +## 1. Install Prerequisites + +> __*NOTE:*__ Following instructions assume that you have [brew](https://brew.sh/) installed. + +If you do not have Android Studio installed, install it: +```bash +brew install --cask android-studio +``` + +Install the following packages: +```bash +brew install protobuf gcc go openjdk@17 rustup-init +``` + +> __*NOTE:*__ Ensure that you setup `openjdk@17` to be the active JDK, follow instructions in +> installation of openjdk@17 or use a tool like [jEnv](https://www.jenv.be/). + +Finish the install of `rustup`: +```bash +rustup-init +``` + +## 2. Install SDK Tools and Android NDK Toolchain +Open Android Studio -> Tools -> SDK Manager, and install `Android SDK Command-line Tools (latest)`. + +Install the necessary Android SDK tools +```bash +~/Library/Android/sdk/cmdline-tools/latest/bin/sdkmanager "platforms;android-33" "build-tools;30.0.3" "platform-tools" "ndk;25.2.9519653" +``` + +Install Android targets +```bash +rustup target add aarch64-linux-android armv7-linux-androideabi i686-linux-android x86_64-linux-android +``` + +Export the following environmental variables, and possibly store them for example in your +`~/.zprofile` or `~/.zshrc` file: +```bash +export ANDROID_HOME="$HOME/Library/Android/sdk" +export ANDROID_NDK_HOME="$ANDROID_HOME/ndk/25.2.9519653" +export NDK_TOOLCHAIN_DIR="$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/darwin-x86_64/bin" +export AR_aarch64_linux_android="$NDK_TOOLCHAIN_DIR/llvm-ar" +export AR_armv7_linux_androideabi="$NDK_TOOLCHAIN_DIR/llvm-ar" +export AR_x86_64_linux_android="$NDK_TOOLCHAIN_DIR/llvm-ar" +export AR_i686_linux_android="$NDK_TOOLCHAIN_DIR/llvm-ar" +export CC_aarch64_linux_android="$NDK_TOOLCHAIN_DIR/aarch64-linux-android26-clang" +export CC_armv7_linux_androideabi="$NDK_TOOLCHAIN_DIR/armv7a-linux-androideabi26-clang" +export CC_x86_64_linux_android="$NDK_TOOLCHAIN_DIR/x86_64-linux-android26-clang" +export CC_i686_linux_android="$NDK_TOOLCHAIN_DIR/i686-linux-android26-clang" +export CARGO_TARGET_AARCH64_LINUX_ANDROID_LINKER="$NDK_TOOLCHAIN_DIR/aarch64-linux-android26-clang" +export CARGO_TARGET_ARMV7_LINUX_ANDROIDEABI_LINKER="$NDK_TOOLCHAIN_DIR/armv7a-linux-androideabi26-clang" +export CARGO_TARGET_I686_LINUX_ANDROID_LINKER="$NDK_TOOLCHAIN_DIR/i686-linux-android26-clang" +export CARGO_TARGET_X86_64_LINUX_ANDROID_LINKER="$NDK_TOOLCHAIN_DIR/x86_64-linux-android26-clang" +``` + +## 4. Debug build +Run the build script in the root of the project to assemble all the native libraries and the app: + +```bash +./build-apk.sh --dev-build --no-docker +``` + +Once the build is complete you should receive a message looking similar to this: +``` +********************************** + + The build finished successfully! + You have built: + + 2023.5-dev-9ac934 + +********************************** +``` + +Your native binaries have now been built, any subsequent builds that does not have changes to the +native code can be done in Android Studio or using gradle. + +# Build options and configuration + +For configuring signing or options to your build continue with the general [build instructions](../BuildInstructions.md).