Instructions for releasing Android Apps
Finally, you will learn how to assemble the app, run the tests, and how to choose the right artifacts when installing or publishing the apps.
- Java 11+ (OpenJDK versions work).
- Android SDK, and optionally Android Studio.
adbcommand for debugging and get the logs.
- The source code. To run all the tests in the CHT Android app you need to clone also the submodules:
git clone --recurse-submodules https://github.com/medic/cht-android.git.
- If you are going to build a new flavor (CHT Android), you also need to have installed:
Gradle is also used but it’s downloaded and installed in the user space the first time
make is executed. You can also build and launch the app with Android Studio.
Bellow are the instructions of how to install and setup some of the tools required.
Java 11+ needs to be installed. The
bin/ folder of the JDK must added into the
$PATH environment variable, and it’s recommended to have
$JAVA_HOME pointing to the JDK folder as well.
To install different versions of Java and without the need to have root permissions, checkout Sdkman!, if you are familiar with tools like
rvm, this tool is pretty much the same for Java, and the command takes care of adding the selected JDK to the
$PATH variable and to set the
$JAVA_HOME variable when switching across different versions.
Android Studio and the SDK
Android Studio is the full package: the IDE based on IntelliJ IDEA, the Android SDK and the SDK Manager with the UI to manage different packages visually, while the SDK alone only includes the command line tools like the
You don’t need the IDE to build the app or to install a “debug” version in a device, or get the logs, but it’s recommended if you also want to debug the app or modify the code.
- Android Studio: download from https://developer.android.com/studio
- Command line tools only: download from https://developer.android.com/studio#command-tools
If you install Android Studio it’s still recommended to download and setup the command line tools separately to be able to use them without the IDE.
The binary folder of the command also need to be added to the
$ANDROID_HOME pointing to the root of the SDK. Moreover, the SDK requires to be stored in the
$ANDROID_HOME and inside a folder called
Here are the steps from the command line you can follow to install the CLI tools once downloaded the zip file:
mkdir -p Android/Sdk/cmdline-tools unzip commandlinetools-linux-7583922_latest.zip mv cmdline-tools/ Android/Sdk/cmdline-tools/latest/
Then, to add the environment variables required, you can add the following to your
export ANDROID_HOME="$HOME/Android/Sdk" export PATH="$PATH:$ANDROID_HOME/cmdline-tools/latest/bin"
Old SDK distributions used to have it pre-packaged, now you have to install it separately. Once installed SDK following the steps above, you can install the latest version of
sdkmanager --install platform-tools
If you also installed Android Studio you can use the SDK Manager instead.
Finally edit again the
$PATH environment variable to add the adb path:
This tool is used automatically by the Android SDK for signing APKs, and to check the certificate of a given APK, so chances are that after installing the SDK following the steps above you already have it installed, but not configured in the
$PATH that is needed to manually check APKs signature.
The CLI is part of other CLI tolls under the
build-tools package, and multiple build tools package can be installed, so check what versions you have under the
$ANDROID_HOME/build-tools folder, and add the most up to date to the
$PATH folder. E.g. if you have the version 30.0.3 installed in you computer, apksigner should be installed at
$ANDROID_HOME/build-tools/30.0.3/apksigner, so add the
$ANDROID_HOME/build-tools/30.0.3 folder to the
In case you don’t have it installed or want to install a newer version, checkout the versions available with
sdkmanager --list. You will see a table with a list of installed and available packages, not just the build tools.
To install the version 31.0.0:
sdkmanager --install 'build-tools;31.0.0'. Then update or add it to the
Only CHT Android
make targets support the flavor as
make flavor=[Flavor] [task], where
[Flavor] is the branded version with the first letter capitalized. The
[task] is the action to execute:
The default value for
Unbranded, e.g. executing
make deploy will assemble and install that flavor, while executing
make flavor=Medicmobilegamma deploy will do the same for the Medicmobilegamma brand.
See the Makefile for more details.
Build and assemble
To build and assemble the apps within the console use:
The command above builds and assembles the debug and release APKs of the apps, and for the CHT-Android project the Unbranded flavor is built and assembled by default.
Each APK will be generated and stored in
build/outputs/apk/[flavor]/[debug|release]/, for example after assembling the Medicmobilegamma flavor with
make flavor=Medicmobilegamma assemble, the release versions of the APKs generated are stored in
To assemble other flavors, use the following command:
make flavour=[Flavor] assemble. See the Flavor selection section for more details about
To create the
.aab bundle file, use
make bundle, although signed versions are generated when releasing, and the Play Store requires the AAB to be signed with the right key.
To clean the APKs and compiled resources:
To execute unit tests and static analysis, run:
To generate a unit test coverage report, run:
Find the generated report in:
Only CHT Android
To only execute the linter checks, run:
Only CHT Android
The UI tests run on a device.
- Uninstall previous versions of the app, otherwise an
InstallException: INSTALL_FAILED_VERSION_DOWNGRADEcan cause tests to fail.
- Select English as default language in the device.
- Ensure you meet all the Requirements.
Only CHT Android
The project has bash tests that verify the Make targets used to create and manage the keystores used to sign the apps. Use
make test-bash-keystore to run them. In CI they are executed in Linux and MacOS VMs.
If you get an error like
make: ./src/test/bash/bats/bin/bats: Command not found, it’s because you cloned the project without the
--recurse-submodules git argument. Execute first
git submodule update --init to clone
the submodules within the cht-android folder.
Connecting to the server locally
Only CHT Android
Refer to the CHT Core Developer Guide.
The Android Studio can be used to build and launch the app instead. Be sure to select the right flavor from the Build Variants dialog (see Change the build variant). To launch the app in an emulator, you need to uncomment the code that has the strings for the
x86 or the
x86_64 architecture in the
include sections of the
When building the app there are two output formats you can use: Android App Bundle or APK.
Android App Bundles
Only CHT Android
The publish script in CI produces multiple AABs for publishing to the Google Play Store, so the generated
.aab files need to be uploaded instead of the
.apk files if the Play Store require so. Old apps published for the first time before Aug 1, 2021 can be updated with the APK format.
If distributing AABs via the Play Store, upload all AABs and it will automatically choose the right one for the target device. The AABs are named as follows:
For compatibility with a wide range of devices, the publish script in CI produces multiple APKs. The two variables are the instruction set used by the device’s CPU, and the supported Android version. When sideloading the application, it is essential to pick the correct APK or the application may crash.
If distributing APKs via the Play Store, upload all APKs and it will automatically choose the right one for the target device.
To help you pick which APK to install, you can find information about the version of Android and the CPU in the About section of the phone’s settings menu.
The APKs are named as follows:
|Instruction set||Android version||Notes|
|5+||Preferred. Use this APK if possible.|
|5+||Built as support for older devices, ignore if possible.|
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.