65
edits
Difference between revisions of "Compiling ScummVM/Android"
Jump to navigation
Jump to search
→Configure and build ScummVM
Praetorian (talk | contribs) |
|||
| (13 intermediate revisions by 2 users not shown) | |||
| Line 2: | Line 2: | ||
This page describes how to build Android packages from the ScummVM source tree. | This page describes how to build Android packages from the ScummVM source tree. | ||
However, one can still attempt the manual way of setting up the Android toolchain(s), without using Docker containers, by following the logic and commands in our scripts for building the Docker images. It should be noted | While one can go through the process of manually installing and configuring the toolchains for the target Android architectures, as well as cross-compiling any third party libraries (again for each target architecture), currently ''the recommended method'' is to use a Docker container that can be built using scripts from our [https://github.com/scummvm/dockerized-bb Dockerised Buildbot repository]. This page will cover how to build ScummVM for the supported target Android architecture using the Docker container method. | ||
However, one can still attempt the manual way of setting up the Android toolchain(s), without using Docker containers, by following the logic and commands in our scripts for building the Docker images. It should be noted that the process of manually setting up the toolchains is ''considerably easy if the developer does not need any of the cross-compiled third party libraries'' that some of the game engines or functionalities of ScummVM depend on. | |||
= Preparatory work = | = Preparatory work = | ||
| Line 10: | Line 11: | ||
== On a Linux 64bit distribution == | == On a Linux 64bit distribution == | ||
This process requires running on a recent Linux 64bit distribution, eg. Ubuntu 16.04 LTS or higher (or equivalent). These instructions were tested on a host running Ubuntu x64 20.04 LTS. | |||
Install the <tt>git</tt> package in order to clone the ScummVM source code repository and keep it up-to-date, and also some additional packages to build the Docker toolchain containers: | Install the <tt>git</tt> package in order to clone the ScummVM source code repository and keep it up-to-date, and also some additional packages to build the Docker toolchain containers: | ||
<code>sudo apt-get update</code> | |||
<code>sudo apt-get upgrade</code> | |||
<code>sudo apt-get install git m4 make</code> | |||
Follow the instructions on the [https://docs.docker.com/engine/install/ubuntu/ official Docker documentation page to install the Docker Engine on Linux]. We tested with Docker Engine Community Edition 19.03.12, (build 48a66213fe) using containerd.io version 1.2.13 on Linux Ubuntu x64 20.04 LTS. | Follow the instructions on the [https://docs.docker.com/engine/install/ubuntu/ official Docker documentation page to install the Docker Engine on Linux]. We tested with Docker Engine Community Edition 19.03.12, (build 48a66213fe) using containerd.io version 1.2.13 on Linux Ubuntu x64 20.04 LTS. | ||
| Line 26: | Line 30: | ||
From the Linux bash shell do: | From the Linux bash shell do: | ||
<code>sudo apt-get update</code> | |||
<code>sudo apt-get upgrade</code> | |||
<code>sudo apt-get install git m4 make</code> | |||
*Important note: The instructions below assume that you are running the commands from a Linux bash shell. If you're on Windows, please make sure you '''always have Docker Desktop up and running before launching your Linux bash shell(s)'''. | *Important note: The instructions below assume that you are running the commands from a Linux bash shell. If you're on Windows, please make sure you '''always have Docker Desktop up and running before launching your Linux bash shell(s)'''. | ||
== On macOS == | |||
# If you don't already have Xcode command line tools, Xcode from the app store, then from the Terminal run: <code>xcode-select --install</code> | |||
# If you don't have homebrew installed, install it from https://brew.sh/, then from the Terminal, install docker with <code>brew install docker</code> | |||
# Install a docker server. The easiest one is probably [https://docs.docker.com/desktop/install/mac-install/ Docker Desktop] | |||
= Setting up the environment = | = Setting up the environment = | ||
| Line 36: | Line 48: | ||
From your Linux host shell do: | From your Linux host shell do: | ||
<code>mkdir -p ~/Workspace</code> | |||
<code>mkdir -p ~/Workspace/android-scummvm-bb/bshomes</code> | |||
<code>touch ~/Workspace/android-scummvm-bb/.bash_history</code> | |||
<code>sudo chmod o+rw ~/Workspace/android-scummvm-bb/.bash_history</code> | |||
Now clone the ScummVM repository: | Now clone the ScummVM repository: | ||
<code>cd ~/Workspace</code> | |||
<code>git clone https://github.com/scummvm/scummvm.git</code> | |||
Also clone the ScummVM dockerized buildbot repository and build the Docker containers: | Also clone the ScummVM dockerized buildbot repository and build the Docker containers: | ||
At this point the <code>docker images</code> command should return something like the following: | <code>git clone https://github.com/scummvm/dockerized-bb.git ~/Workspace/android-scummvm-bb/dockerized-bb</code> | ||
<code>cd ~/Workspace/android-scummvm-bb/dockerized-bb</code> | |||
<code>make toolchains/android/pull</code> | |||
At this point the <code>docker images</code> command should return something like the following; <code>toolchains/android</code> is the required image: | |||
<code>docker images</code> | |||
REPOSITORY TAG IMAGE ID CREATED SIZE | REPOSITORY TAG IMAGE ID CREATED SIZE | ||
toolchains/android latest 2005faedc472 22 minutes ago 3.9GB | toolchains/android latest 2005faedc472 22 minutes ago 3.9GB | ||
| Line 62: | Line 84: | ||
Now launch the Docker container shell: | Now launch the Docker container shell: | ||
<code>docker run -v ~/Workspace/scummvm:/data/scummvm -v ~/Workspace/android-scummvm-bb/bshomes:/data/bshomes/android -v ~/Workspace/android-scummvm-bb/.bash_history:/root/.bash_history -w /data/scummvm -it toolchains/android /bin/bash</code> | |||
= Compiling = | = Compiling = | ||
| Line 99: | Line 116: | ||
Also, after setting up these variables, run the following command: | Also, after setting up these variables, run the following command: | ||
<code>mkdir -p "${ANDROID_SDK_ROOT}" "${ANDROID_SDK_HOME}" "${GRADLE_USER_HOME}"</code> | |||
<code>cp -R "${RO_ANDROID_ROOT}"/sdk/licenses "${ANDROID_SDK_ROOT}"/licenses</code> | |||
*Important note: The above command is only required to be run once, since it sets up some required folders and copies required SDK licenses to the external mounted folders (on the host Linux, outside the container itself) | *Important note: The above command is only required to be run once, since it sets up some required folders and copies required SDK licenses to the external mounted folders (on the host Linux, outside the container itself) | ||
| Line 108: | Line 126: | ||
You should probably first make sure you are working with the latest ScummVM code. Please, run: | You should probably first make sure you are working with the latest ScummVM code. Please, run: | ||
<code>cd ~/Workspace/scummvm</code> | |||
<code>git pull</code> | |||
<u>From the Docker container shell</u>: | <u>From the Docker container shell</u>: | ||
Clean up any remnants folders from a previous build: | Clean up any remnants folders from a previous build: | ||
<code>rm -rf android_project</code> | |||
<code>rm -rf debug</code> | |||
<code>rm -rf release</code> | |||
=== '''Configure and build ScummVM''' === | === '''Configure and build ScummVM''' === | ||
Supported target architectures for the configure command (values for the <code>--host</code> switch parameter): | Supported target architectures for the configure command (values for the <code>--host</code> switch parameter): | ||
* <code>android-arm64-v8a</code> - for all new Android devices | * <code>android-arm64-v8a</code> - for all new Android devices | ||
*<code>android-arm-v7a</code> - for older Android devices | |||
* <code>android-x86</code> - ideal for emulator with 32bit images | * <code>android-x86</code> - ideal for emulator with 32bit images | ||
* <code>android-x86_64</code> - ideal for emulator with 64bit images | * <code>android-x86_64</code> - ideal for emulator with 64bit images or a Chromebook device | ||
==== '''For a debug build''' ==== | ==== '''For a debug build''' ==== | ||
First run a <code>make clean</code> and <code>configure</code> command from inside the local scummvm repository folder (you should be in there by default after running the <code>docker run</code> command). Choose one of the following commands based on the target android architecture: | First run a <code>make clean</code> and <code>configure</code> command from inside the local scummvm repository folder (you should be in there by default after running the <code>docker run</code> command). Choose one of the following commands based on the target android architecture: | ||
* < | * ''Target android-arm64-v8a:'' | ||
<code>CXX="ccache ${ANDROID_TOOLCHAIN}/bin/aarch64-linux-android21-clang++" PKG_CONFIG_LIBDIR="${ANDROID_TOOLCHAIN}/sysroot/usr/lib/aarch64-linux-android/21/pkgconfig" PATH=${PATH}:"${ANDROID_TOOLCHAIN}/sysroot/usr/bin/aarch64-linux-android/21" make clean; ./configure --enable-verbose-build --enable-all-engines --host=android-arm64-v8a --enable-debug</code> | |||
* ''Target android-arm-v7a:'' | |||
<code>CXX="ccache ${ANDROID_TOOLCHAIN}/bin/armv7a-linux-androideabi16-clang++" PKG_CONFIG_LIBDIR="${ANDROID_TOOLCHAIN}/sysroot/usr/lib/arm-linux-androideabi/16/pkgconfig" PATH=${PATH}:"${ANDROID_TOOLCHAIN}/sysroot/usr/bin/arm-linux-androideabi/16" make clean; ./configure --enable-verbose-build --enable-all-engines --host=android-arm-v7a --enable-debug</code> | |||
* | * ''Target android-x86:'' | ||
<code>CXX="ccache ${ANDROID_TOOLCHAIN}/bin/i686-linux-android16-clang++" PKG_CONFIG_LIBDIR="${ANDROID_TOOLCHAIN}/sysroot/usr/lib/i686-linux-android/16/pkgconfig" PATH=${PATH}:"${ANDROID_TOOLCHAIN}/sysroot/usr/bin/i686-linux-android/16" make clean; ./configure --enable-verbose-build --enable-all-engines --host=android-x86 --enable-debug</code> | |||
* ''Target android-x86_64:'' | |||
<code>CXX="ccache ${ANDROID_TOOLCHAIN}/bin/x86_64-linux-android21-clang++" PKG_CONFIG_LIBDIR="${ANDROID_TOOLCHAIN}/sysroot/usr/lib/x86_64-linux-android/21/pkgconfig" PATH=${PATH}:"${ANDROID_TOOLCHAIN}/sysroot/usr/bin/x86_64-linux-android/21" make clean; ./configure --enable-verbose-build --enable-all-engines --host=android-x86_64 --enable-debug</code> | |||
Finally, in order to start the build process for '''all the above target architectures''' cases run: | |||
<code>make -j$(nproc) androiddistdebug</code> | |||
If successful, the debug apk file will be created inside a <code>debug</code> subfolder in the ScummVM repository folder. The default name will be <code>ScummVM-debug.apk</code>. | If successful, the debug apk file will be created inside a <code>debug</code> subfolder in the ScummVM repository folder. The default name will be <code>ScummVM-debug.apk</code>. | ||
| Line 152: | Line 174: | ||
For instructions on how to create a debug signing certificate manually, if the developer wants to create it one their own for some reason, please refer to the [https://developer.android.com/studio/publish/app-signing#debugmode Android Developers instructions here]. | For instructions on how to create a debug signing certificate manually, if the developer wants to create it one their own for some reason, please refer to the [https://developer.android.com/studio/publish/app-signing#debugmode Android Developers instructions here]. | ||
==== '''For a release build''' ==== | ==== '''For a release build (which builds all engines)''' ==== | ||
First run a <code>make clean</code> and <code>configure</code> command from inside the local scummvm repository folder (you should be in there by default after running the <code>docker run</code> command). Choose one of the following commands based on the target android architecture: | First run a <code>make clean</code> and <code>configure</code> command from inside the local scummvm repository folder (you should be in there by default after running the <code>docker run</code> command). Choose one of the following commands based on the target android architecture: | ||
* < | * ''Target android-arm64-v8a:'' | ||
<code>CXX="ccache ${ANDROID_TOOLCHAIN}/bin/aarch64-linux-android21-clang++" PKG_CONFIG_LIBDIR="${ANDROID_TOOLCHAIN}/sysroot/usr/lib/aarch64-linux-android/21/pkgconfig" PATH=${PATH}:"${ANDROID_TOOLCHAIN}/sysroot/usr/bin/aarch64-linux-android/21" make clean; ./configure --enable-verbose-build --enable-all-engines --host=android-arm64-v8a --disable-debug --enable-release</code> | |||
* ''Target android-arm-v7a:'' | |||
<code>CXX="ccache ${ANDROID_TOOLCHAIN}/bin/armv7a-linux-androideabi16-clang++" PKG_CONFIG_LIBDIR="${ANDROID_TOOLCHAIN}/sysroot/usr/lib/arm-linux-androideabi/16/pkgconfig" PATH=${PATH}:"${ANDROID_TOOLCHAIN}/sysroot/usr/bin/arm-linux-androideabi/16" make clean; ./configure --enable-verbose-build --enable-all-engines --host=android-arm-v7a --disable-debug --enable-release</code> | |||
* ''Target android-x86:'' | |||
<code>CXX="ccache ${ANDROID_TOOLCHAIN}/bin/i686-linux-android16-clang++" PKG_CONFIG_LIBDIR="${ANDROID_TOOLCHAIN}/sysroot/usr/lib/i686-linux-android/16/pkgconfig" PATH=${PATH}:"${ANDROID_TOOLCHAIN}/sysroot/usr/bin/i686-linux-android/16" make clean; ./configure --enable-verbose-build --enable-all-engines --host=android-x86 --disable-debug --enable-release</code> | |||
* ''Target android-x86_64:'' | |||
<code>CXX="ccache ${ANDROID_TOOLCHAIN}/bin/x86_64-linux-android21-clang++" PKG_CONFIG_LIBDIR="${ANDROID_TOOLCHAIN}/sysroot/usr/lib/x86_64-linux-android/21/pkgconfig" PATH=${PATH}:"${ANDROID_TOOLCHAIN}/sysroot/usr/bin/x86_64-linux-androidd/21" make clean; ./configure --enable-verbose-build --enable-all-engines --host=android-x86_64 --disable-debug --enable-release</code> | |||
Finally, in order to start the build process for '''all the above target architectures''' cases run: | |||
<code>make -j$(nproc) androiddistrelease</code> | |||
If successful, the release apk file will be created inside a <code>release</code> subfolder in the ScummVM repository folder. | If successful, the release apk file will be created inside a <code>release</code> subfolder in the ScummVM repository folder. | ||
| Line 177: | Line 198: | ||
Please note that a release build must be signed with a non-debug key in order to be installed on a Android device. In order to sign a release build, assuming you have created a release keystore named <code>scummvm-release-key.keystore</code> and have put it in your <code>${ANDROID_SDK_HOME}</code> path on the host Linux (ie. here <code>~/Workspace/android-scummvm-bb/bshomes/sdk-home</code>), you will need to run a command like the following: | Please note that a release build must be signed with a non-debug key in order to be installed on a Android device. In order to sign a release build, assuming you have created a release keystore named <code>scummvm-release-key.keystore</code> and have put it in your <code>${ANDROID_SDK_HOME}</code> path on the host Linux (ie. here <code>~/Workspace/android-scummvm-bb/bshomes/sdk-home</code>), you will need to run a command like the following: | ||
<code>apksigner sign --ks ${ANDROID_SDK_HOME}/scummvm-release-key.keystore --out release/scummvm-release-signed.apk release/ScummVM-release-unsigned.apk</code> | <code>${ANDROID_SDK_BTOOLS}/apksigner sign --ks ${ANDROID_SDK_HOME}/scummvm-release-key.keystore --out release/scummvm-release-signed.apk release/ScummVM-release-unsigned.apk</code> | ||
== Installing the apk on an Android Device == | == Installing the apk on an Android Device == | ||
| Line 188: | Line 209: | ||
= Android Studio setup = | = Android Studio setup = | ||
After compiling | After the compiling process has concluded, one may find within the build directory (if used) a new directory called <tt>android-project.</tt> If following the above process, this folder will be inside the root folder of the locally cloned ScummVM source code repository. | ||
To enable debugging, after opening the <tt> | |||
This folder can be opened by Android Studio. C files are not yet available, but it is possible to edit the Java source files and debug both Java & native code (on an emulator or on a real device via an <tt>adb</tt> connection). | |||
To ''enable debugging'', after opening the <tt>android_project</tt> directory, please edit the <tt>android_project configuration</tt> (click on the dropdown arrow next to the configuration name and select <tt>Edit Configurations...</tt>), select the tab <tt>Debugger</tt>, and set field <tt>Debug type</tt> to <code>Dual</code>. | |||
= References = | = References = | ||
* [[Compiling_ScummVM/Docker#Using_the_docker_images | Using the Docker images]] | * [[Compiling_ScummVM/Docker#Using_the_docker_images | Using the Docker images]] | ||