Skip to content
This repository has been archived by the owner on Oct 19, 2022. It is now read-only.

Development Setup for Android

Jump to bottom
Daniel edited this page May 29, 2020 · 10 revisions

This page describes how to set up a development environment for testing the OX COI Messenger app in a local Android emulator.

Prerequisites

The prerequisites section so far only describes Debian Linux. You are welcome to add descriptions for other operating systems.

The main prerequisites are:

  • Git to access the source code,
  • A C development toolchain to compile some native dependencies (see plugin wiki),
  • A Rust development toolchain to compile DeltaChat Core (see plugin wiki),
  • Android Studio with Flutter support to compile the app,
  • A hypervisor to accelerate the emulation of Android devices or a connected physical device.

Debian Linux

This setup assumes Debian 10. Other versions and other Debian-based distributions should work pretty much the same. Other Linux distributions might need to use a different package manager and maybe slightly different package names.

Git, the C tool-chain and the KVM hypervisor can be installed from the main package repository. Also, curl is needed to install the Rust tool-chain.

sudo apt install git build-essential libvirt-daemon curl

Android Studio

It might actually be possible to build and run the app entirely from the command line and/or using packages from Debian repositories. Any experience reports or documentation are welcome. But for now, the full Android Studio from Google is going to be used here.

Download Android Studio from https://developer.android.com/studio and unpack it somewhere you'll be able to find later. Start Android Studio from the unpacked directory with

android-studio/bin/studio.sh

Android SDK

On first run, the Android Studio Setup Wizard will start automatically and offer to download an SDK and other components. The rest of the documentation will assume a standard install, but the only important option is the path of the SDK Folder, which is displayed on the Verify Settings page. It defaults to $HOME/Android/Sdk and is used to run various command line tools, as seen below.

The last page of the Setup Wizard contains a link to installation instructions for the hypervisor for your platform. Since KVM was installed as the very first step above, it should already work. To verify this, use the following command:

$HOME/Android/Sdk/emulator/emulator -accel-check

The expected output is:

accel:
0
KVM (version 12) is installed and usable.
accel

After the Setup Wizard is finished, the Welcome to Android Studio window is displayed. Further configuration will be done via the Configure menu in the bottom right. If you already opened a project, the same entries are available in the Tools menu instead.

Android Virtual Device (AVD)

Use the Android Virtual Device Manager to create an Android virtual device by selecting Configure/Tools → AVD Manager → Create Virtual Device… On the first two pages, you can select any device and image, but latest versions are recommended. The system image probably needs to be downloaded first. After finishing the creation, the virtual device can be launched from the Your VirtualDevices page by clicking on the green Play button.

Flutter

Install Flutter by following instructions on https://flutter.dev/docs/get-started/install. To get a perfect score in the output of the flutter doctor command, follow these steps after unpacking the SDK and adding it to your PATH:

flutter config --no-analytics
flutter doctor --android-licenses

Install Flutter support in Android Studio by selecting Configure/Tools → Plugins → Flutter → Install. This should also install Dart support. Restart the IDE afterwards.

Now launch the created Android device from the AVD Manager and run

flutter doctor

It should not find any issues.

Source Code

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.

cd $GIT
git clone https://github.com/open-xchange/ox-coi.git
git clone https://github.com/open-xchange/flutter-deltachat-core.git

The ox-coi repository contains a submodule (utils), which isn't required for the local development. It's okay if it fails updating, as the given submodule URL isn't available for the public. The submodule is used for CI tasks only.

Flutter Only

If you are not going to work on DeltaChat Core or any other Rust code, then you can let Git submodules and setup.developmentWithoutCore.sh take care of downloading the necessary code and binaries:

cd $GIT/flutter-deltachat-core
git submodule update --init --recursive
cd $GIT/ox-coi/tools

Setup for Android only:

 ./setup.developmentWithoutCore.sh android latest

Setup for iOS only:

 ./setup.developmentWithoutCore.sh ios latest

Setup for both:

 ./setup.developmentWithoutCore.sh all latest

The second parameter defines which binaries should be downloaded. Available ones are listed here. Every tag since 0.500.1 contains the necessary binaries and can be used.

Setup for both with tag:

 ./setup.developmentWithoutCore.sh all 0.600.2

Rust and Flutter

If, on the other hand, you want to test Rust code which you modified locally, then you should have a look into the plugin wiki (Local rust core changes).

Building

Once all app related installation steps from above are complete, head over to the plugin repository wiki and take care of compiling the rust core. If you already have an up and running Rust setup just perform the following steps.

cd $GIT/flutter-deltachat-core/

Build for Android only:

./build-dcc.sh android

Build for iOS only:

./build-dcc.sh ios

Build for both:

./build-dcc.sh all

This will take some time the first time, since everything is built for 1-5 supported target platforms (Android 32bit and 64bit for each ARM and Intel and one universal package for iOS).

In the mean time, open the $GIT/ox-coi project in Android Studio. If it's the first time, several notifications will pop up:

  • Welcome to Flutter! is just polite spyware: select No thanks.
  • Frameworks Detected has only one option: Configure. It opens a dialog. Just select OK there.
  • 'Packages get' has not been run appears at the top of the automatically opened editor for main.dart: select Get dependencies.

If you miss any notification pop-ups, they can be found again in the Event Log in the bottom right corner.

For now, one more manual one-time adjustment is necessary: Select Run → Edit Configurations… and in the configuration for main.dart find the setting Build flavor and enter the value development.

Run preparations

To execute the now ready code the following additional steps are required.

Customer setup

Execute $GIT/ox-coi/tools/setup.loadCustomer.sh with a repository containing all relevant information. The repository must have the following folder and file structure.

  • Android Firebase configuration: android/app/google-services.json
  • iOS Firebase configuration: ios/OX Coi/Firebase/GoogleService-Info-Development.plist
  • iOS Firebase configuration: ios/OX Coi/Firebase/GoogleService-Info-Production.plist
  • Customer information file: README.md

More information in regards to Firebase can be found here.

Running

Before launching the app, several checks are useful to avoid most frequent errors:

  • Check that the Rust build finished without errors (is required)
  • Ensure that the virtual Android device is running or a physical device is connected
  • Select the Android device in the Flutter Device Selection drop-down in the toolbar

Finally, you can launch the app by selecting either the green Run or the Debug button in the toolbar.

On repeated runs, the build-dcc.sh step is only necessary whenever any local Rust code was modified. The Flutter parts are built automatically before the updated app is launched.

Logging

The app logs automatically to the console, but it also creates log files. Those are accessible via the Files app on iOS (they are in the OX COI specific user visible folder) and on Android they are located in Android/data/com.openxchange.oxcoi/files/logs (could differ on different devices). To map the logged iOS device name to a real device, please compare with https://gist.github.com/adamawolf/3048717.

Clone this wiki locally