This is a tutorial for building an Android app using only Android SDK and development tools already available in Debian. Two examples are provided. The first example is a build of a minimal Android "Hello World" program using the make utility. It has been tested on Debian 10 (Buster). The second example is a build of the F-droid client app using gradle. It was originally tested on Debian 9.2 (Stretch), but requires updating to run on Debian Buster. Each example produces an Android application package file (.apk) which can be used to install the app on an Android device.

Terminology (for those new to Android development)

API Level - Apps interface to the Android OS via the Android Application Program Interface (API). The API is frequently updated (30 versions over 12 years). Each version is identified by the API Level, which is incremented by 1 from the previous version. API versions are generally backward compatible; an Android version that supports one API Level will run apps targeted at earlier API levels. A list of Android versions and corresponding API Levels can be found here and here

ART (Android Runtime) - is the virtual machine and runtime environment of Android 5.0 (API Level 21) and later versions. ART uses Dalvik bytecode. It implements selective precompilation of bytecode into the host device's native machine language to improve performance. Details here.

Dalvik - Android's original virtual machine, superseded by ART. Its bytecode is different from the JVM bytecode. Application build tools compile JVM bytecode into Dalvik bytecode which is saved in a .dex (Dalvik EXecutable), which is included in an APK file for installation on the target device.

APK (Android Package)- file format that packages an Android app for installation on a device; .apk is the usual file extension.

Gradle - a build utility used by many Android projects.

Currently there is only the target platform of API Level 23 packaged, so only apps targeted at android-23 can be built with only Debian packages. We will add more API platform packages via backports afterwards. Only Build-Tools 24.0.0 is available, but we will use the android-sdk-helper package so we won't need to modify the build scripts in order to use the SDK.

Hello World

On Debian Buster, install the following packages with apt (or Synaptic):

  • # apt install git make android-sdk android-sdk-platform-23

Check out the project with git and build it with make:

The build generates file helloworld.apk. Copying it to an Android device and opening it will install the app.

(Testing: Built from commit 39bf760e 2020-06-17 of the Git project using Debian Buster, then run on Cyanogenmod Android 4.4.4 and on Android 7.0. Also reported to be tested on Android 11.)

F-droid - Preparing the environment

  • # apt install android-sdk android-sdk-platform-23 git libgradle-android-plugin-java

Obs1: Git is the recommended method to obtain the source code of the android application.

Obs2: The last package is needed to meet the dependency of android-sdk-helper, which is not in stretch repositories yet

Get the android-sdk-helper from the testing repository

Right now, android-sdk-helper is not available in stretch backports, so we will have to add testing/buster repository.

Add Debian buster or later to your apt sources files (/etc/apt/sources.list etc).

The next step is to create/update apt preferences files (/etc/apt/preferences etc). This is where the apt pinning takes place. Normally, the highest version of an available package wins, but we will override that.

Create/edit the preferences file so it looks like this:

Package: *
Pin: release a=stable
Pin-Priority: 700

Package: *
Pin: release a=testing
Pin-Priority: 650

Note the descending values. Since Stable has the highest pin-priority, it will be installed preferentially over Testing.

Getting F-droid source code

Let's create a Git folder in your home directory and clone the F-droid source code into it

Adjustments

Some tweaks will be necessary so everything can work as expected

Accepting SDK license

To use the android-sdk you must accept its license. At the present moment there are some ways to do so, but none of them is perfect.

In this tutorial we'll clone a git repository containing all the needed licenses and copy them to the right location.

Note that this is a temporary solution. We can expect that in the future there will be offered an automatic solution for accepting the SDK license.

Define your SDK location

In the top folder of your app project, you need to create a file called local.properties that says where your SDK is. In our case, this file needs to have the following single line:

# SDK location
sdk.dir=/usr/lib/android-sdk

Disabling lint

Since the Lint in this version of Gradle Android Plugin is still problematic, running the :lint tasks might not work. They can be turned off editing the file build.gradle in the app folder.

Open this file with your prefered editor and search for the line that says abortOnError inside the lintOptions method. Then change it to false

Change Heap Size (in case gradle complains about the speed)

After you start builing your app with gradle you might get a warning like this:

To run dex in process, the Gradle daemon needs a larger heap.
It currently has 1024 MB.
For faster builds, increase the maximum heap size for the Gradle daemon to at least 1536 MB.
To do this set org.gradle.jvmargs=-Xmx1536M in the project gradle.properties.

If it happens to you, obey your computer and create the file gradle.properties in the root folder of your project and add the line

org.gradle.jvmargs=-Xmx1536M

Change locale (for some timezones)

There is currently an unexpected behaviour in F-droid building process that results into an error when the project is built in some timezones. If the gradle fails with the message

  • Execution failed for task ':app:testDebugUnitTest'

You can fix it by temporarily changing your timezone to GMT+1 with the command. Run the gradle command, and after everything is done remember to use this command again to return to your regular timezone.

  • # dpkg-reconfigure tzdata

Building the app

After you follow all the past steps, you probably will be able to build the project easily with the following command.

  • ~/Git/fdroidclient$ gradle build --init-script /usr/share/android-sdk-helper/init.gradle