docs/workflow/building/coreclr/android.md
This documentation outlines developer workflows for CoreCLR on Android platforms.
Supported host systems for building CoreCLR for Android:
Supported target architectures:
[!NOTE] Prerequisites can also be downloaded and installed manually:
- An automated script as described in Testing Libraries on Android
- Downloading the archives:
- Android SDK - Download command-line tools and use
sdkmanagerto download the SDK.- Android NDK - Download NDK
Set the following environment variables:
export ANDROID_SDK_ROOT=<full-path-to-android-sdk>export ANDROID_NDK_ROOT=<full-path-to-android-ndk>To build CoreCLR runtime, libraries and tools for local development, run the following command from <repo-root>:
./build.sh clr.runtime+clr.alljits+clr.corelib+clr.nativecorelib+clr.tools+clr.packages+libs -os android -arch <x64|arm64> -c <Debug|Release>
To build CoreCLR runtime NuGet packages, run the following command from <repo-root>:
./build.sh clr.runtime+clr.alljits+clr.corelib+clr.nativecorelib+clr.tools+clr.packages+libs+host+packs -os android -arch <x64|arm64> -c <Debug|Release>
[!NOTE] The runtime packages will be located at:
<repo-root>/artifacts/packages/<configuration>/Shipping/
[!NOTE] The static CoreCLR runtime for static linking (
libcoreclr_static.a) is available in inner build artifacts but is not yet shipped in NuGet packages.
Building on Windows is not directly supported yet. However it is possible to use WSL2 for this purpose.
wsl --updatesudo snap install android-studio --classicapt install openjdk-21-jdk
export ANDROID_SDK_ROOT=<full-path-to-android-sdk>export ANDROID_NDK_ROOT=<full-path-to-android-ndk>To build CoreCLR runtime, libraries and tools, run the following command from <repo-root>:
./build.sh clr.runtime+clr.alljits+clr.corelib+clr.nativecorelib+clr.tools+clr.packages+libs -os android -arch <x64|arm64> -c <Debug|Release>
To demonstrate building and running an Android application with CoreCLR, we will use the HelloAndroid sample app.
A prerequisite for building and running samples locally is to have CoreCLR successfully built for desired Android platform.
To build HelloAndroid, run the following command from <repo_root>:
make BUILD_CONFIG=<Debug|Release> TARGET_ARCH=<x64|arm64> RUNTIME_FLAVOR=CoreCLR DEPLOY_AND_RUN=false run -C src/mono/sample/Android
On successful execution, the command will output the HelloAndroid.apk at:
<repo-root>artifacts/bin/AndroidSampleApp/<x64|arm64>/<Debug|Release>/android-<x64|arm64>/Bundle/bin/HelloAndroid.apk
To run the sample on an emulator, the emulator first needs to be up and running.
Creating an emulator (ADV - Android Virtual Device) can be achieved through Android Studio - Device Manager.
After its creation, the emulator needs to be booted up and running, so that we can run the HelloAndroid sample on it via:
make BUILD_CONFIG=<Debug|Release> TARGET_ARCH=<x64|arm64> RUNTIME_FLAVOR=CoreCLR DEPLOY_AND_RUN=true run -C src/mono/sample/Android
[!NOTE] Emulators can be also started from the terminal via:
$ANDROID_SDK_ROOT/emulator/emulator -avd <emulator-name>
The app can be run on an emulator running on the Windows host.
adb from the Android SDK in WSL2 with that from Windows
mv $ANDROID_SDK_ROOT/platform-tools/adb $ANDROID_SDK_ROOT/platform-tools/adb-origln -s /mnt/<path-to-sdk-on-host>/platform-tools/adb.exe $ANDROID_SDK_ROOT/platform-tools/adbadb corresponding to the Windows host:
export ADB_EXE_PATH=$ANDROID_SDK_ROOT/platform-tools/adbmake command as aboveTo demonstrate building and running tests on CoreCLR Android, we will use the Android.Device_Emulator.JIT.Test test project.
To build and run the test on Android with CoreCLR, run the following command from <repo_root>:
./dotnet.sh build -c <Debug|Release> src/tests/FunctionalTests/Android/Device_Emulator/JIT/Android.Device_Emulator.JIT.Test.csproj /p:TargetOS=android /p:TargetArchitecture=<x64|arm64> /t:Test /p:RuntimeFlavor=coreclr
[!NOTE] Similarly to the
HelloAndroidsample, the emulator needs to be up and running.
Managed debugging is currently not supported, but we can debug:
This can be achieved in Android Studio via Profile or Debug APK.
HelloAndroid sample app in Debug configuration targeting arm64 target architecture.libcoreclr.so.dbg into libcoreclr.so.so, the file is located at: <repo_root>/artifacts/bin/AndroidSampleApp/arm64/Debug/android-arm64/publish/libcoreclr.so.dbgProfile or Debug APK project..apk file (example: <repo_root>/artifacts/bin/AndroidSampleApp/arm64/Debug/android-arm64/Bundle/bin/HelloAndroid.apk)HelloAndroid->cpp->libcoreclr and double-click libcoreclr.so
Debug Symbols pane on the right, select Add<repo_root>/artifacts/bin/AndroidSampleApp/arm64/Debug/android-arm64/publish/libcoreclr.so.soHelloAndroid->cpp->libcoreclr
exports.cpp and set a breakpoint in coreclr_initialize function and launch the debug session
[!NOTE] Steps 5) through 8) can be omitted if the runtime is built without stripping debug symbols to a separate file (e.g.,
libcoreclr.so.dbg). This can be achieved by including-keepnativesymbols trueoption when building the runtime, e.g.,:./build.sh clr.runtime+clr.alljits+clr.corelib+clr.nativecorelib+clr.tools+clr.packages+libs -os android -arch <x64|arm64> -c Debug -keepnativesymbols true
Similar instructions for debugging Android apps with Mono runtime can be found here.
If multiple JDKs are installed on your system, you may encounter the following error:
`src/mono/msbuild/android/build/AndroidBuild.targets(237,5): error MSB4018: java.lang.NullPointerException: Cannot invoke String.length() because <parameter1> is null
when building the Android samples or functional tests.
To resolve this:
$> java -version
openjdk version "23.0.1" 2024-10-15
OpenJDK Runtime Environment Homebrew (build 23.0.1)
OpenJDK 64-Bit Server VM Homebrew (build 23.0.1, mixed mode, sharing)