How To build libdeltachat.a (Delta Chat Core)

Preparations

libdeltachat.a is based on and built from the Delta Chat Core (DCC). Sometimes you need to build your own version based on a specific branch or with your own additions.

Rust

To build your own version of libdeltachat.a you should have installed the Rust tool chain before. You can check if it's installed by simply execute the command:

rustc --version

If you see something like this:

$ ~ rustc --version
rustc 1.36.0 (a53f9df32 2019-07-03)

there is nothing more to do regarding installing the Rust tool chain. If no Rust installation exists please continue reading.

At the time of writing, the Rust tool-chain requires the nightly build and cross-compilation, so it cannot be installed from the package repository yet (even from sid). Instead, install rustup by following the instructions on https://rustup.rs/. When prompted, customize the installation and select the nightly toolchain. Letting rustup modify the PATH variable is not likely to work, since it modifies $HOME/.profile, which is not (supposed to be) used by terminal emulators in graphical environments. Instead, add the $HOME/.cargo/bin directory to your PATH manually by adding the following line to the end of your $HOME/.bashrc:

source "$HOME/.cargo/env"

Targets

Rust needs a set of targets to build the actual core, please add the required targets for your platform after navigating in the DCC sub module.

cd delta_chat_core
rustup target add aarch64-linux-android armv7-linux-androideabi i686-linux-android x86_64-linux-android # Android
rustup target add aarch64-apple-ios x86_64-apple-ios # iOS

Cargo configuration

The source code of the app is distributed over several Git repositories. Currently, they expect to be checked out into the same parent directory. This parent directory will be referred to as $GIT from now on. Rust needs to know where to find some Android-specific tools. These are configured in $GIT/.cargo/config:

paths = ["tokio-imap", "tokio-imap/imap-proto", "rust-imap"]

[target.armv7-linux-androideabi]
ar     = "arm-linux-androideabi-ar"
linker = "armv7a-linux-androideabi21-clang"

[target.aarch64-linux-android]
ar     = "aarch64-linux-android-ar"
linker = "aarch64-linux-android21-clang"

[target.i686-linux-android]
ar     = "i686-linux-android-ar"
linker = "i686-linux-android21-clang"

[target.x86_64-linux-android]
ar     = "x86_64-linux-android-ar"
linker = "x86_64-linux-android21-clang"

The first line contains relative paths and is only necessary if locally modified dependencies of deltachat-core-rust are used. The path to the local deltachat-core-rust itself was specified by the symlink in Local rust core changes. Currently, this method of overwriting dependencies prints a warning, and might stop working in the future. Cargo issue #6713 hopefully provides a better solution until then.

The rest of the file relies on the PATH entries added in Native Development Kit (NDK) and can be put in any other directory where Cargo will find it, e.g. in particular $HOME/.cargo/config.

Additional tools and environment adjustments

To be able to build for specific platforms some tools must be installed beside the Rust tool chain.

Android

Android requires an installation of the NDK. You can either manually download it or install it via the Android Studio SDK manager. It's preferable to use Android Studio as it provides numerous tools to simplify managing the tooling around the Android platform.

Native Development Kit (NDK)

Launch the SDK Manger from within Android Studio by selecting Configure/Tools → SDK Manager. In the tab SDK Tools, select NDK (Side by side) and install it. After the download is finished, the log window should contain a line like

Installing NDK (Side by side) 20.1.5948944 in /home/…/Android/Sdk/ndk/20.1.5948944

This installation directory, and its subdirectory toolchains/llvm/prebuilt/linux-x86_64/bin need to be added to your PATH (the path differs depending on the platform, you have to adjust it accordingly, e.g. toolchains/llvm/prebuilt/darwin-x86_64/bin for macOS), e.g. by adding something like the following to $HOME/.bashrc:

export PATH="$PATH:$HOME/Android/Sdk/ndk/20.1.5948944"
export PATH="$PATH:$HOME/Android/Sdk/ndk/20.1.5948944/toolchains/llvm/prebuilt/linux-x86_64/bin"

Build Delta Chat Core

Update the repository and initialize the sub repository which contains the Delta Chat Core.

git pull
git submodule update --init --recursive

Execute the shell script in the root folder with the correct parameters.

Build for Android only:

./build-dcc.sh android

Build for iOS only:

./build-dcc.sh ios

Build for both:

./build-dcc.sh all

Now the shell script build-dcc.sh is executed. So, this will take a while. You can standup to have a break, walk into the kitchen to grab a Coffee|Tea|Glas of Water|WhiskeyLemon Soda|Whatever, or you browse to Cancer Research Institute to donate for cancer research.

If the build script is done and everything is fine, then you should read something like that in your terminal:

-- Build succeeded --

That's all building libdeltachat.a. The library is placed in the appropriate directories for the given platforms. Leave it there, open Xcode or Android Studio and start using the plugin.

Errors

If an error occurs the script should give a hint how to fix the actual problem. If this is the case please proceed with executing the given hint. If the cargo build process itself fails, please verify your rust / cargo configuration is setup correctly.

Local rust core changes

If you want to test Rust code which you modified locally, then you also need check out the corresponding Rust sources, preferably into the same directory:

git clone -b coi-metadata https://github.com/open-xchange/deltachat-core-rust.git
git clone -b interruptible-idle https://github.com/open-xchange/rust-imap.git
git clone -b metadata https://github.com/open-xchange/tokio-imap.git

The branches might change in the future, and you will of course use other branches while working on your code. If you are not going to modify a dependency, then you don't need to check it out.

To use the checked out sources in the app, replace the Git submodule with a symlink to the separate workspace:

cd $GIT/flutter-deltachat-core
rmdir delta_chat_core
ln -s ../delta_chat_core

Take care to never commit this change to Git!