Difference between revisions of "Compiling ScummVM/Android"

From ScummVM :: Wiki
Jump to navigation Jump to search
(→‎Precompiled binaries: -- updated link to archive)
 
(36 intermediate revisions by 6 users not shown)
Line 1: Line 1:
= Compiling ScummVM for Android =
= Compiling ScummVM for Android =


This page describes how you build Android packages from the ScummVM source tree.  For help compiling this on Windows, see the separate article, [[Compiling ScummVM/Android (on Windows)]].
This page describes how to build Android packages from the ScummVM source tree.


= Mandatory tools =
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.


* [http://developer.android.com/sdk/index.html Android SDK] r09 as of this writing
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.
* [http://developer.android.com/sdk/ndk/index.html Android NDK] r5b as of this writing


Use the SDK Manager to install:
= Preparatory work =
* Android SDK Tools
* Android SDK Platform-tools
* SDK Platform Android 4.0, API 14


Set the <tt>ANDROID_SDK</tt> environment variable to the root directory of the SDK, and <tt>ANDROID_NDK</tt> to the root directory of the NDK.
== On a Linux 64bit distribution ==


= Optional libraries =
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.
* [http://svn.xiph.org/branches/lowmem-branch/Tremor/ Tremor] (lowmem branch) to play ''.ogg'' audio files
* [http://www.underbit.com/products/mad/ MAD] to play ''.mp3'' audio files
* [http://flac.sourceforge.net/ FLAC] to play lossless ''.flac'' files


Again, you have two options:
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:


== Precompiled binaries ==
<code>sudo apt-get update</code>


Get [http://sourceforge.net/projects/scummvm/files/build/3rd-android-4.tar.bz2/download this archive] and extract it to e.g. <tt>/opt/android</tt>.
<code>sudo apt-get upgrade</code>


== Build the libraries yourself ==
<code>sudo apt-get install git m4 make</code>


Here's a a simple script to set up a shell for crosscompiling:
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.


#!/bin/sh
== On Windows 10 (version 1904 or higher) using WSL2 ==
 
PREFIX=${ANDROID_NDK}/toolchains/arm-linux-androideabi-4.4.3/prebuilt/linux-x86/bin/arm-linux-androideabi-
Please, follow the instructions on the [https://docs.docker.com/docker-for-windows/wsl/ official Docker documentation page to install the Docker Engine on Windows 10 using WSL2]. This process requires rebooting your PC at least a couple of times. The instructions also link to appropriate documentation on how to enable WSL on Windows and install a Linux distribution from the Windows Store. These instructions were tested with the Ubuntu 20.04 LTS app installed.
export CC=${PREFIX}gcc
 
export CXX=${PREFIX}g++
After enabling WSL2, and running Docker Desktop (with WSL integration), launch a bash shell for your installed Linux distribution by running the respective Windows app (here, Ubuntu 20.04 LTS). You can launch multiple bash shells by running the Linux distribution app multiple times.
export AS=${PREFIX}gcc
 
export LD=${PREFIX}gcc
From the Linux bash shell do:
export AR=${PREFIX}ar cru
 
export RANLIB=${PREFIX}ranlib
<code>sudo apt-get update</code>
export STRIP=${PREFIX}strip
export OBJCOPY=${PREFIX}objcopy
export MACHDEP="--sysroot=$ANDROID_NDK/platforms/android-4/arch-arm -g -mandroid -mthumb-interwork"
export CFLAGS="${MACHDEP} -Os -Wall -mandroid -msoft-float -march=armv5te -mtune=xscale"
export CXXFLAGS="${CFLAGS}"
export LDFLAGS="${MACHDEP}"
echo "./configure --host=arm --prefix=/opt/android/3rd-android-4-armeabi"


Save it to a file (like <tt>android-4-eabi.sh</tt>) and run
<code>sudo apt-get upgrade</code>


. ./android-4-eabi.sh
<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)'''.


in your shell. Build systems should now use the correct tools.
== On macOS ==


=== Tremor ===
# 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]


Get a SVN checkout (r17852. as of this writing):
= Setting up the environment =
In this step we will fetch the latest code from the ScummVM source code repository, and create a few additional folders and files that will help in the building process and/or improve its ease of use (eg. by maintaining the history of submitted commands).


svn co http://svn.xiph.org/trunk/Tremor
From your Linux host shell do:


configure it:
<code>mkdir -p ~/Workspace</code>


./autogen.sh --host=arm --prefix=/opt/android/3rd-android-4-armeabi --enable-low-accuracy --enable-64kHz-limit
<code>mkdir -p ~/Workspace/android-scummvm-bb/bshomes</code>


and finally build & install it:
<code>touch ~/Workspace/android-scummvm-bb/.bash_history</code>


make
<code>sudo chmod o+rw ~/Workspace/android-scummvm-bb/.bash_history</code>
make install


=== MAD ===
Now clone the ScummVM repository:


Get a tarball of the latest stable version [http://sourceforge.net/projects/mad/files/libmad/ here] (v0.15.1b as of this writing) and extract it.
<code>cd ~/Workspace</code>


configure it:
<code>git clone https://github.com/scummvm/scummvm.git</code>


./autogen.sh --host=arm --prefix=/opt/android/3rd-android-4-armeabi --enable-speed --enable-fpm=arm --disable-aso
Also clone the ScummVM dockerized buildbot repository and build the Docker containers:


and finally build & install it:
<code>git clone https://github.com/scummvm/dockerized-bb.git ~/Workspace/android-scummvm-bb/dockerized-bb</code>


make
<code>cd ~/Workspace/android-scummvm-bb/dockerized-bb</code>
make install


=== FLAC ===
<code>make toolchains/android/pull</code>


Get a tarball of the latest stable version [http://flac.sourceforge.net/download.html here] (v1.2.1 as of this writing) and extract it.
At this point the <code>docker images</code> command should return something like the following; <code>toolchains/android</code> is the required image:


configure it:
<code>docker images</code>
REPOSITORY                  TAG      IMAGE ID      CREATED            SIZE
toolchains/android          latest    2005faedc472  22 minutes ago      3.9GB
toolchains/android-common  latest    c726cca9065b  About an hour ago  30kB
toolchains/common          latest    c751ec410582  About an hour ago  24.7kB


./configure --prefix=/opt/android/3rd-android-4-armeabi --disable-largefile --disable-thorough-tests --disable-doxygen-docs --disable-xmms-plugin --disable-cpplibs --disable-ogg --disable-oggtest --disable-rpath
*Important note: From time to time, you may need get updates from our Dockerized buildbot code (using <code>git pull</code>) and rebuild the toolchain containers, in order to make use of the latest improvements and any additional third party cross-compiled libraries.


and build & install the required parts:
= Launch the Docker container =


make -C src/libFLAC
Now launch the Docker container shell:
make -C src/libFLAC install
make -C include install


<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 =


The Android port can be compiled with the <tt>configure</tt> script.
== Set the environment variables ==
The following commands are meant to be run from <u>the Docker Container shell</u>:
 
First, make sure that the required environment variables are set with the correct values:
export RO_ANDROID_ROOT=/opt/android \
ANDROID_EXTERNAL_ROOT=/data/bshomes/android \
HOST_TAG=linux-x86_64
 
Then run:
export ANDROID_NDK_ROOT=${RO_ANDROID_ROOT}/ndk \
ANDROID_TOOLCHAIN=${RO_ANDROID_ROOT}/ndk/toolchains/llvm/prebuilt/linux-x86_64 \
ANDROID_SDK_ROOT=${ANDROID_EXTERNAL_ROOT}/sdk \
ANDROID_SDK_HOME=${ANDROID_EXTERNAL_ROOT}/sdk-home \
GRADLE_USER_HOME=${ANDROID_EXTERNAL_ROOT}/gradle \
ANDROID_SDK_BTOOLS_VERSION=29.0.3
 
*Important note 1: The above command reflects the SDK build tools version installed by the container at the time of writing. This version string may need updating if the container is updated to set up a more recent version of the SDK build tools.
*Important note 2: Essentially, the set up of the SDK build tools path as an environmental variable, which is appended to the <code>$PATH</code> environemental variable below, is required only for running the <code>apksigner</code> command to sign a release build manually.
 
Additionally, run:
export ANDROID_SDK_TOOLS=${ANDROID_SDK_ROOT}/tools \
ANDROID_SDK_BTOOLS=${ANDROID_SDK_ROOT}/build-tools/${ANDROID_SDK_BTOOLS_VERSION} \
PATH=${ANDROID_SDK_TOOLS}:${ANDROID_SDK_BTOOLS}:${PATH} \
NDK_LOG=1 \
LC_ALL=C \
CCACHE_COMPRESS=1
 
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)
 
== Configuring and Compiling ScummVM ==
<u>From your Linux host</u> (ie. not from within the Container shell):
 
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>:
 
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''' ===
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-arm-v7a</code> - for older Android devices
* <code>android-x86</code> - ideal for emulator with 32bit images
* <code>android-x86_64</code> - ideal for emulator with 64bit images or a Chromebook device
 
==== '''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:
 
* ''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>.
 
A debug build will be signed ''automatically'' by an auto-generated debug certificate. This certificate will be created by default inside a <code>.android</code> subfolder in your <code>${ANDROID_SDK_HOME}</code> path, which here is the host path: <tt>~/Workspace/android-scummvm-bb/bshomes/sdk-home/.android/</tt>. The debug keystore is named appropriately <code>debug.keystore</code>.
 
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 (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:
 
* ''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.
 
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>${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 ==
The quickest way to install a debug apk or a signed release apk on your Android Device is to use the <code>Profile or Debug APK</code> functionality of Android Studio.
 
* Important note: On Windows 10, you'll likely have Android Studio set up on the Windows host side. Hence, you will need to copy your apk from the Linux WSL2 environment to a Windows accessible folder. Since WSL2 mounts Windows folders by default under <code>/mnt/</code>, you could run from your Linux host (ie. not from inside the Docker Container) something similar to the following:


Set the <tt>ANDROID_SDK</tt> environment variable to the root directory of the SDK, and <tt>ANDROID_NDK</tt> to the root directory of the NDK. Add the directory of the toolchain binaries from the NDK to your <tt>PATH</tt>. This directory differs, on Linux its <tt>$ANDROID_NDK/toolchains/arm-linux-androideabi-4.4.3/prebuilt/linux-x86/bin</tt>.
<code>cp release/scummvm-release-signed.apk /mnt/c/scummvm-android-apks/</code>


The most basic way to accomplish this is to run:
= Android Studio setup  =


./configure --host=android --enable-plugins --default-dynamic
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.
make


The script supports various arguments, which you can use to en- or disable features, see <tt>./configure --help</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).


If you want support for additional libraries, you need cross-compiled binaries.
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>.
If you followed the [[#Optional libraries|above description]] and have those libraries in <tt>/opt/android/3rd-android-4-armeabi</tt>, the <tt>configure</tt> command line would look like this:


./configure --host=android --enable-plugins --default-dynamic --with-tremor-prefix=/opt/android/3rd-android-4-armeabi --with-mad-prefix=/opt/android/3rd-android-4-armeabi --with-flac-prefix=/opt/android/3rd-android-4-armeabi
= References =
* [[Compiling_ScummVM/Docker#Using_the_docker_images | Using the Docker images]]

Latest revision as of 10:25, 10 January 2024

Compiling ScummVM for Android

This page describes how to build Android packages from the ScummVM source tree.

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 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

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 git 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:

sudo apt-get update

sudo apt-get upgrade

sudo apt-get install git m4 make

Follow the instructions on the 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.

On Windows 10 (version 1904 or higher) using WSL2

Please, follow the instructions on the official Docker documentation page to install the Docker Engine on Windows 10 using WSL2. This process requires rebooting your PC at least a couple of times. The instructions also link to appropriate documentation on how to enable WSL on Windows and install a Linux distribution from the Windows Store. These instructions were tested with the Ubuntu 20.04 LTS app installed.

After enabling WSL2, and running Docker Desktop (with WSL integration), launch a bash shell for your installed Linux distribution by running the respective Windows app (here, Ubuntu 20.04 LTS). You can launch multiple bash shells by running the Linux distribution app multiple times.

From the Linux bash shell do:

sudo apt-get update

sudo apt-get upgrade

sudo apt-get install git m4 make

  • 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

  1. If you don't already have Xcode command line tools, Xcode from the app store, then from the Terminal run: xcode-select --install
  2. If you don't have homebrew installed, install it from https://brew.sh/, then from the Terminal, install docker with brew install docker
  3. Install a docker server. The easiest one is probably Docker Desktop

Setting up the environment

In this step we will fetch the latest code from the ScummVM source code repository, and create a few additional folders and files that will help in the building process and/or improve its ease of use (eg. by maintaining the history of submitted commands).

From your Linux host shell do:

mkdir -p ~/Workspace

mkdir -p ~/Workspace/android-scummvm-bb/bshomes

touch ~/Workspace/android-scummvm-bb/.bash_history

sudo chmod o+rw ~/Workspace/android-scummvm-bb/.bash_history

Now clone the ScummVM repository:

cd ~/Workspace

git clone https://github.com/scummvm/scummvm.git

Also clone the ScummVM dockerized buildbot repository and build the Docker containers:

git clone https://github.com/scummvm/dockerized-bb.git ~/Workspace/android-scummvm-bb/dockerized-bb

cd ~/Workspace/android-scummvm-bb/dockerized-bb

make toolchains/android/pull

At this point the docker images command should return something like the following; toolchains/android is the required image:

docker images

REPOSITORY                  TAG       IMAGE ID       CREATED             SIZE
toolchains/android          latest    2005faedc472   22 minutes ago      3.9GB
toolchains/android-common   latest    c726cca9065b   About an hour ago   30kB
toolchains/common           latest    c751ec410582   About an hour ago   24.7kB
  • Important note: From time to time, you may need get updates from our Dockerized buildbot code (using git pull) and rebuild the toolchain containers, in order to make use of the latest improvements and any additional third party cross-compiled libraries.

Launch the Docker container

Now launch the Docker container shell:

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

Compiling

Set the environment variables

The following commands are meant to be run from the Docker Container shell:

First, make sure that the required environment variables are set with the correct values:

export RO_ANDROID_ROOT=/opt/android \
ANDROID_EXTERNAL_ROOT=/data/bshomes/android \
HOST_TAG=linux-x86_64

Then run:

export ANDROID_NDK_ROOT=${RO_ANDROID_ROOT}/ndk \
ANDROID_TOOLCHAIN=${RO_ANDROID_ROOT}/ndk/toolchains/llvm/prebuilt/linux-x86_64 \
ANDROID_SDK_ROOT=${ANDROID_EXTERNAL_ROOT}/sdk \
ANDROID_SDK_HOME=${ANDROID_EXTERNAL_ROOT}/sdk-home \
GRADLE_USER_HOME=${ANDROID_EXTERNAL_ROOT}/gradle \
ANDROID_SDK_BTOOLS_VERSION=29.0.3
  • Important note 1: The above command reflects the SDK build tools version installed by the container at the time of writing. This version string may need updating if the container is updated to set up a more recent version of the SDK build tools.
  • Important note 2: Essentially, the set up of the SDK build tools path as an environmental variable, which is appended to the $PATH environemental variable below, is required only for running the apksigner command to sign a release build manually.

Additionally, run:

export ANDROID_SDK_TOOLS=${ANDROID_SDK_ROOT}/tools \
ANDROID_SDK_BTOOLS=${ANDROID_SDK_ROOT}/build-tools/${ANDROID_SDK_BTOOLS_VERSION} \
PATH=${ANDROID_SDK_TOOLS}:${ANDROID_SDK_BTOOLS}:${PATH} \
NDK_LOG=1 \
LC_ALL=C \
CCACHE_COMPRESS=1

Also, after setting up these variables, run the following command:

mkdir -p "${ANDROID_SDK_ROOT}" "${ANDROID_SDK_HOME}" "${GRADLE_USER_HOME}"

cp -R "${RO_ANDROID_ROOT}"/sdk/licenses "${ANDROID_SDK_ROOT}"/licenses

  • 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)

Configuring and Compiling ScummVM

From your Linux host (ie. not from within the Container shell):

You should probably first make sure you are working with the latest ScummVM code. Please, run:

cd ~/Workspace/scummvm

git pull

From the Docker container shell:

Clean up any remnants folders from a previous build:

rm -rf android_project

rm -rf debug

rm -rf release

Configure and build ScummVM

Supported target architectures for the configure command (values for the --host switch parameter):

  • android-arm64-v8a - for all new Android devices
  • android-arm-v7a - for older Android devices
  • android-x86 - ideal for emulator with 32bit images
  • android-x86_64 - ideal for emulator with 64bit images or a Chromebook device

For a debug build

First run a make clean and configure command from inside the local scummvm repository folder (you should be in there by default after running the docker run command). Choose one of the following commands based on the target android architecture:

  • Target android-arm64-v8a:

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

  • Target android-arm-v7a:

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

  • Target android-x86:

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

  • Target android-x86_64:

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


Finally, in order to start the build process for all the above target architectures cases run:

make -j$(nproc) androiddistdebug

If successful, the debug apk file will be created inside a debug subfolder in the ScummVM repository folder. The default name will be ScummVM-debug.apk.

A debug build will be signed automatically by an auto-generated debug certificate. This certificate will be created by default inside a .android subfolder in your ${ANDROID_SDK_HOME} path, which here is the host path: ~/Workspace/android-scummvm-bb/bshomes/sdk-home/.android/. The debug keystore is named appropriately debug.keystore.

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 Android Developers instructions here.

For a release build (which builds all engines)

First run a make clean and configure command from inside the local scummvm repository folder (you should be in there by default after running the docker run command). Choose one of the following commands based on the target android architecture:

  • Target android-arm64-v8a:

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

  • Target android-arm-v7a:

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

  • Target android-x86:

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

  • Target android-x86_64:

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


Finally, in order to start the build process for all the above target architectures cases run:

make -j$(nproc) androiddistrelease

If successful, the release apk file will be created inside a release subfolder in the ScummVM repository folder.

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 scummvm-release-key.keystore and have put it in your ${ANDROID_SDK_HOME} path on the host Linux (ie. here ~/Workspace/android-scummvm-bb/bshomes/sdk-home), you will need to run a command like the following:

${ANDROID_SDK_BTOOLS}/apksigner sign --ks ${ANDROID_SDK_HOME}/scummvm-release-key.keystore --out release/scummvm-release-signed.apk release/ScummVM-release-unsigned.apk

Installing the apk on an Android Device

The quickest way to install a debug apk or a signed release apk on your Android Device is to use the Profile or Debug APK functionality of Android Studio.

  • Important note: On Windows 10, you'll likely have Android Studio set up on the Windows host side. Hence, you will need to copy your apk from the Linux WSL2 environment to a Windows accessible folder. Since WSL2 mounts Windows folders by default under /mnt/, you could run from your Linux host (ie. not from inside the Docker Container) something similar to the following:

cp release/scummvm-release-signed.apk /mnt/c/scummvm-android-apks/

Android Studio setup

After the compiling process has concluded, one may find within the build directory (if used) a new directory called android-project. If following the above process, this folder will be inside the root folder of the locally cloned ScummVM source code repository.

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 adb connection).

To enable debugging, after opening the android_project directory, please edit the android_project configuration (click on the dropdown arrow next to the configuration name and select Edit Configurations...), select the tab Debugger, and set field Debug type to Dual.

References