Browse Source

doc: add another dumpster truck of workarounds to the Android guide.

pull/638/head
Vladimír Vondruš 2 years ago
parent
commit
c389505270
  1. 91
      doc/platforms-android.dox

91
doc/platforms-android.dox

@ -55,16 +55,18 @@ for a cleaner setup.
- [android-ndk](https://aur.archlinux.org/packages/android-ndk/) - [android-ndk](https://aur.archlinux.org/packages/android-ndk/)
- [android-sdk-build-tools](https://aur.archlinux.org/packages/android-sdk-build-tools/) - [android-sdk-build-tools](https://aur.archlinux.org/packages/android-sdk-build-tools/)
- [android-sdk-platform-tools](https://aur.archlinux.org/packages/android-sdk-platform-tools/) - [android-sdk-platform-tools](https://aur.archlinux.org/packages/android-sdk-platform-tools/)
- [android-platform-24](https://aur.archlinux.org/packages/android-platform-24/) - [android-platform-29](https://aur.archlinux.org/packages/android-platform-29/)
- [android-sdk-cmake](https://aur.archlinux.org/packages/android-sdk-cmake/) - [android-sdk-cmake](https://aur.archlinux.org/packages/android-sdk-cmake/)
Gradle requires Android SDK version of CMake, which is currently at version Gradle requires Android SDK version of CMake, which is currently at version
3.10. See below for an experimental way to @ref platforms-android-system-cmake "use the system CMake" 3.10. See below for an experimental way to @ref platforms-android-system-cmake "use the system CMake"
instead. On the other hand, while it's possible to use the CMake from Android instead. On the other hand, while it's possible to use the CMake from Android
SDK to build Magnum itself, the following guide is written with CMake 3.16 and SDK to build Magnum itself, the following guide is written with CMake 3.20 and
newer in mind, which has Android NDK r19+ support built-in. In older versions newer in mind, which has Android NDK r22+ support built-in. CMake 3.16 to 3.19
you'd need to supply a toolchain file instead and the configuration values are supports only NDK until r21, in even older versions you'd need to supply a
different. toolchain file instead and the configuration values are different, see the
@ref platforms-android-cmake-too-old "related troubleshooting section" for more
information.
@section platforms-android-console Building and running console applications @section platforms-android-console Building and running console applications
@ -73,31 +75,15 @@ you have Magnum installed in the NDK path as described in @ref building-cross-an
build your project as below. Adapt paths to your system, Android ABI and build your project as below. Adapt paths to your system, Android ABI and
version and NDK location as needed. version and NDK location as needed.
<b></b>
@m_class{m-note m-warning}
@par
Unfortunately, CMake before version 3.20 needs extra help with
`CMAKE_FIND_ROOT_PATH` and `CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX` to
correctly find Android libraries, as shown below. Otherwise it falls back
to looking in native system locations. Again, adapt them to your system,
Android ABI and version and NDK location as needed.
@par
CMake 3.20 and newer [is now able to detect everything on its own](https://gitlab.kitware.com/cmake/cmake/-/merge_requests/5357)
and you don't need to supply these anymore.
@m_class{m-console-wrap} @m_class{m-console-wrap}
@code{.sh} @code{.sh}
mkdir build-android-arm64 && cd build-android-arm64 mkdir build-android-arm64 && cd build-android-arm64
cmake .. \ cmake .. \
-DCMAKE_SYSTEM_NAME=Android \ -DCMAKE_SYSTEM_NAME=Android \
-DCMAKE_SYSTEM_VERSION=24 \ -DCMAKE_SYSTEM_VERSION=29 \
-DCMAKE_ANDROID_ARCH_ABI=arm64-v8a \ -DCMAKE_ANDROID_ARCH_ABI=arm64-v8a \
-DCMAKE_ANDROID_STL_TYPE=c++_static \ -DCMAKE_ANDROID_STL_TYPE=c++_static \
-DCMAKE_FIND_ROOT_PATH=/opt/android-ndk/toolchains/llvm/prebuilt/linux-x86_64/sysroot \
-DCMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX=/aarch64-linux-android/24 \
-DCMAKE_BUILD_TYPE=Release -DCMAKE_BUILD_TYPE=Release
cmake --build . cmake --build .
@endcode @endcode
@ -421,11 +407,8 @@ x86_64 | &lt;nk&gt;/platforms/android-&lt;version&gt;/arch-x86_64/usr
After that, you can add the additional ABIs to the `abiFilters` list in your After that, you can add the additional ABIs to the `abiFilters` list in your
`build.gradle`. `build.gradle`.
For example, building Magnum for 32-bit and 64-bit ARM with SDK version 24 For example, building Magnum for 32-bit and 64-bit ARM with SDK version 29
could look like this. The same note regarding CMake 3.20 applies here --- on could look like this, assuming CMake 3.20+ being used.
versions before, you need the `CMAKE_FIND_ROOT_PATH` and
`CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX` variables as well (and have them in sync
with the ABI and API version level), on 3.20 and newer you can omit them.
@m_class{m-console-wrap} @m_class{m-console-wrap}
@ -433,13 +416,11 @@ with the ABI and API version level), on 3.20 and newer you can omit them.
mkdir build-android-arm && cd build-android-arm mkdir build-android-arm && cd build-android-arm
cmake .. \ cmake .. \
-DCMAKE_SYSTEM_NAME=Android \ -DCMAKE_SYSTEM_NAME=Android \
-DCMAKE_SYSTEM_VERSION=24 \ -DCMAKE_SYSTEM_VERSION=29 \
-DCMAKE_ANDROID_ARCH_ABI=armeabi-v7a \ -DCMAKE_ANDROID_ARCH_ABI=armeabi-v7a \
-DCMAKE_ANDROID_STL_TYPE=c++_static \ -DCMAKE_ANDROID_STL_TYPE=c++_static \
-DCMAKE_BUILD_TYPE=Release \ -DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX=<ndk>/toolchains/llvm/prebuilt/linux-x86_64/sysroot/usr \ -DCMAKE_INSTALL_PREFIX=<ndk>/toolchains/llvm/prebuilt/linux-x86_64/sysroot/usr
-DCMAKE_FIND_ROOT_PATH=<ndk>/toolchains/llvm/prebuilt/linux-x86_64/sysroot \
-DCMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX=/arm-linux-androideabi/24
cmake --build . --target install cmake --build . --target install
cd .. cd ..
@ -447,13 +428,11 @@ cd ..
mkdir build-android-arm64 && cd build-android-arm64 mkdir build-android-arm64 && cd build-android-arm64
cmake .. \ cmake .. \
-DCMAKE_SYSTEM_NAME=Android \ -DCMAKE_SYSTEM_NAME=Android \
-DCMAKE_SYSTEM_VERSION=24 \ -DCMAKE_SYSTEM_VERSION=29 \
-DCMAKE_ANDROID_ARCH_ABI=arm64-v8a \ -DCMAKE_ANDROID_ARCH_ABI=arm64-v8a \
-DCMAKE_ANDROID_STL_TYPE=c++_static \ -DCMAKE_ANDROID_STL_TYPE=c++_static \
-DCMAKE_BUILD_TYPE=Release \ -DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX=<ndk>/toolchains/llvm/prebuilt/linux-x86_64/sysroot/usr \ -DCMAKE_INSTALL_PREFIX=<ndk>/toolchains/llvm/prebuilt/linux-x86_64/sysroot/usr
-DCMAKE_FIND_ROOT_PATH=<ndk>/toolchains/llvm/prebuilt/linux-x86_64/sysroot \
-DCMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX=/aarch64-linux-android/24
cmake --build . --target install cmake --build . --target install
@endcode @endcode
@ -769,9 +748,47 @@ gradle build
@subsection platforms-android-cmake-too-old CMake or NDK is too old @subsection platforms-android-cmake-too-old CMake or NDK is too old
While the minimal CMake version that's required for building Magnum for Android While the minimal CMake version that's required for building Magnum for Android
is 3.7, NDK r19 and newer need at least CMake 3.16 to work. For older NDKs you is 3.7, NDK r22 and newer need at least CMake 3.20, and attempting to use CMake
might want to grab at least CMake 3.9.2, as it [fixes an issue with the Clang toolchain](https://gitlab.kitware.com/cmake/cmake/issues/17253). 3.19 or older with NDK r22+ will greet you with an error similar to the
following, as NDK r22 removed certain deprecated internal paths:
@m_class{m-console-wrap}
@code{.shell-session}
CMake Error at /usr/share/cmake-3.17/Modules/Platform/Android-Determine.cmake:176 (message):
Android: The API specified by CMAKE_SYSTEM_VERSION='29' does not exist in
the NDK. The directory:
/opt/android/sdk/ndk/22.1.7171670/platforms/android-29
does not exist.
Call Stack (most recent call first):
/usr/share/cmake-3.17/Modules/CMakeDetermineSystem.cmake:129 (include)
CMakeLists.txt:70 (project)
@endcode
NDK r19 to r21 need at least CMake 3.16 to work, and CMake before version 3.20
needs extra help with `CMAKE_FIND_ROOT_PATH` and
`CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX` to correctly find Android libraries,
otherwise it falls back to looking in native system locations. An example is
shown below, adapt them to your system, Android ABI and version NDK location
as needed.
@m_class{m-console-wrap}
@code{.sh}
cmake .. \
-DCMAKE_SYSTEM_NAME=Android \
-DCMAKE_SYSTEM_VERSION=29 \
-DCMAKE_ANDROID_ARCH_ABI=arm64-v8a \
-DCMAKE_ANDROID_STL_TYPE=c++_static \
-DCMAKE_FIND_ROOT_PATH=/opt/android-ndk/toolchains/llvm/prebuilt/linux-x86_64/sysroot \
-DCMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX=/aarch64-linux-android/29 \
-DCMAKE_BUILD_TYPE=Release
@endcode
For NDKs before r19 you might want to grab at least CMake 3.9.2, as it
[fixes an issue with the Clang toolchain](https://gitlab.kitware.com/cmake/cmake/issues/17253).
With NDK r18 and older you'll need to additionally supply With NDK r18 and older you'll need to additionally supply
`-DCMAKE_ANDROID_NDK_TOOLCHAIN_VERSION=clang`, on the other hand the `-DCMAKE_ANDROID_NDK_TOOLCHAIN_VERSION=clang`, on the other hand the
`-DCMAKE_FIND_ROOT_PATH` isn't needed --- CMake is able to figure out the paths `-DCMAKE_FIND_ROOT_PATH` isn't needed --- CMake is able to figure out the paths

Loading…
Cancel
Save