This document describes how to set up the build environment and build the app. For testing, see TESTING.md.
Before diving into developing, please first read CONTRIBUTING.md for general contribution hints and conventions.
Please follow all steps precisely. If you run into troubles, ask on one of the communication channels for help
When checking out deltachat-android, make sure also to check out the subproject deltachat-core-rust:
$ git clone --recursive https://github.com/deltachat/deltachat-android
or later by git submodule update --init --recursive. If you do this in your
home directory, this results in the folder ~/deltachat-android which is just fine.To generate/update the JSON-RPC bindings (ex. chat.delta.rpc.* package)
install Rust tooling (read sections below) and the dcrpcgen tool
then generate the code running the script:
./scripts/update-rpc-bindings.sh
The repository contains Nix development environment
described in flake.nix file.
If you don’t have Nix installed,
the easiest way is to follow the Lix installation instructions
as this results in a setup with Flakes feature enabled out of the box
and can be cleanly uninstalled with /nix/nix-installer uninstall once you don’t need it anymore.
Once you have Nix with Flakes feature set up start the development environment shell:
nix develop
Nix development environment contains Rust with cross-compilation toolchains and Android SDK.
To build an APK run the following 2 steps.
Note that the first step may take some time to build for all architectures. You can optionally read
the first comment block in the ndk-make.sh script
for pointers on how to build for a specific architecture.
$ scripts/ndk-make.sh
$ ./gradlew assembleDebug
Resulting APK files can be found in
build/outputs/apk/gplay/debug/ and
build/outputs/apk/foss/debug/.
Another way to build APK is to use provided Dockerfile
with Docker or Podman.
Podman is a drop-in replacement for Docker that does not require root privileges.
If you don’t have Docker or Podman setup yet, read how to setup Podman below. If you don’t want to use Docker or Podman, read how to manually install the build environment.
First, build the image deltachat-android by running
podman build --build-arg UID=$(id -u) --build-arg GID=$(id -g) . -t deltachat-android
or
docker build --build-arg UID=$(id -u) --build-arg GID=$(id -g) . -t deltachat-android
Then, run the image:
podman run --userns=keep-id -it --name deltachat -v $(pwd):/home/app:z -w /home/app localhost/deltachat-android
or
docker run -it --name deltachat -v $(pwd):/home/app:z -w /home/app localhost/deltachat-android
You can leave the container with Ctrl+D or by typing exit and re-enter it with
docker start -ia deltachat or podman start -ia deltachat.
Within the container, install toolchains and build the native library:
deltachat@6012dcb974fe:/home/app$ scripts/install-toolchains.sh
deltachat@6012dcb974fe:/home/app$ scripts/ndk-make.sh
Then, build an APK:
deltachat@6012dcb974fe:/home/app$ ./gradlew assembleDebug
Executing ./gradlew assembleDebug inside the container fails with The SDK directory '/home/user/Android/Sdk' does not exist.:
The problem is that Android Studio (outside the container) automatically creates a file local.properties with a content like sdk.dir=/home/username/Android/Sdk,
so, Gradle-inside-the-container looks for the Sdk at /home/username/Android/Sdk, where it can’t find it.
You could:
sdk.dir./gradlew assembleDebug from outside the container (however, there may be incompatibility issues if different versions are installed inside and outside the container)Running the image fails with ERRO[0000] The storage 'driver' option must be set in /etc/containers/storage.conf, guarantee proper operation.:
In /etc/containers/storage.conf, replace the line: driver = "" with: driver = "overlay".
You can also set the driver option to something else, you just need to set it to something.
Read about possible options here.
These instructions were only tested on a Manjaro machine so far. If anything doesn’t work, please open an issue.
First, Install Podman.
Then, if you want to run Podman without root, run:
sudo touch /etc/subgid
sudo touch /etc/subuid
sudo usermod --add-subuids 165536-231072 --add-subgids 165536-231072 yourusername
(replace yourusername with your username).
See https://wiki.archlinux.org/index.php/Podman#Rootless_Podman for more information.
To setup build environment manually:
Then, in both cases, install Rust using rustup
and Rust toolchains for cross-compilation by executing scripts/install-toolchains.sh.
Then, configure ANDROID_NDK_ROOT environment variable to point to the Android NDK
installation directory e.g. by adding this to your .bashrc:
export ANDROID_NDK_ROOT=${HOME}/Android/Sdk/ndk/[version] # (or wherever your NDK is) Note that there is no `/` at the end!
export PATH=${PATH}:${ANDROID_NDK_ROOT}/toolchains/llvm/prebuilt/linux-x86_64/bin/:${ANDROID_NDK_ROOT}
After that, call scripts/ndk-make.sh in the root directory to build core-rust.
You can then run the project in Android Studio.
With chance, that’s it :) - if not, read on how to set up a proper development environment.
Some libs required by Android Studio may be missing on 64 bit Linux machines
Source], so for Ubuntu execute
$ sudo apt-get install libc6:i386 libncurses5:i386 libstdc++6:i386 lib32z1 libbz2-1.0:i386
and for Fedora execute
$ sudo yum install zlib.i686 ncurses-libs.i686 bzip2-libs.i686.
Download Android Studio from https://developer.android.com (android-studio-ide-…-linux.zip)
and unpack the archive which contains a single folder called android-studio;
move this folder e.g. to ~/android-studio.
To launch Android Studio for the first time, open a terminal, navigate to
~/android-studio/bin, execute ./studio.sh and use all the standard values
from the wizard.
Android Studio now asks you if you want to open an existing project;
choose ~/deltachat-android as created in the “Build” chapter (Android Studio starts to
build the project, however, there are some steps missing before this will
succeed).
If components are missing, click on the corresponding error message and install eg. required SDKs and the “Build-Tools” (you should also find the option at “Tools / Android / SDK Manager / SDK Platforms”). Now the build should succeed - but the app still misses the native part.
Download Android NDK from
NDK Archives
and extract the archive containing a single folder
called something like android-ndk-r23b-linux; move this folder e.g. to ~/android-ndk.
Export the folder path to your environment as ANDROID_NDK_ROOT and add it to PATH.
You can achieve this e.g. by adding this to your .bashrc
export ANDROID_NDK_ROOT=${HOME}/android-ndk
export PATH=${PATH}:${ANDROID_NDK_ROOT}/toolchains/llvm/prebuilt/linux-x86_64/bin/:${ANDROID_NDK_ROOT}
$ANDROID_NDK_ROOT/ndk-stack --sym obj/local/armeabi-v7a --dump crash.txt > decoded.txt
obj/local/armeabi-v7a is the extracted path from deltachat-gplay-release-X.X.X.apk-symbols.zip file from https://download.delta.chat/android/symbols/
Replace armeabi-v7a by the correct architecture the logs come from (can be guessed by trial and error)
Because the app uses code minification (ProGuard/R8), Java stack traces in crash reports are obfuscated.
To decode them, use retrace with the mapping.txt file that is included in the symbols zip:
retrace mapping.txt crash.txt > decoded-crash.txt
mapping.txt is extracted from the same deltachat-gplay-release-X.X.X.apk-symbols.zip file available at https://download.delta.chat/android/symbols/