The F-droid Build Process

3 minute read

How the F-Droid submission/build process works.

There are two main git repositories involved in getting an app listed on F-Droid, fdroiddata and fdroidserver. You’ll need local, shallow clones (see below) of them both.

The fdroiddata repo

The fdroiddata repo stores metadata about all of the apps on F-Droid.

On a regular basis, F-Droid servers will run through each of the apps listed in the fdroiddata repo, specifically the /fdroiddata/metadata/ directory.

The metadata of each app will be read and used as instructions to build it on F-Droid’s side. It will then be available in the F-Droid app listings.

Basically, apps exist on F-Droid by having their YAML file available in this repo’s metadata directory:

  • Irrespective of F-Droid, Android apps have an applicationId in their build.gradle file, usually in the form of a reverse domain name eg com.example.appname
  • The YAML file must be named with that same app ID, eg /fdroiddata/metadata/com.example.appname.yml

As well as this metadata, your app can/should have extra metadata in its own repo https://f-droid.org/en/docs/Submitting_to_F-Droid_Quick_Start_Guide/. That is something you do inside your app alongside your own code so I haven’t gone into detail about it here as things are complicated enough

Getting your app’s metadata into the fdroiddata repo

F-Droid official instructions are here and you’ll need to refer to them for proper details.

Here I just want to give a high-level view to help wrap your head around how this all works. The general process is as follows:

  • On GitLab (you need a GitLab account if you want to submit an app to F-Droid), make a fork of the mainfdroiddata repo
  • On your dev machine, make a git shallow clone of your fork eg:
    git clone --depth=1 https:<PATH_TO_YOUR_FORK>
    A shallow clone retrieves only a small number of recent commits
  • Create a new branch for your app in your local clone eg:
    git checkout -b com.example.appname
  • Locally, copy a template of the metadata file and rename it to match your app eg:
    cp fdroiddata/templates/build-gradle.yml fdroiddata/metadata/com.example.appname.yml
  • Edit your metadata file to give instructions about how to build your app
  • Test that the app builds on your local machine (see below)
  • Once you’re happy that everything in your metadata file is ok, create a merge request on GitLab for the main repo to pull in your branch containing your new com.example.appname.yml file
  • When that merge request has been accepted, the official fdroiddata repo will contain your new metadata file, meaning next time F-Droid run their build process your app will be included and built

The fdroidserver repo

The fdroidserver repo contains the build tools that F-Droid use themselves to build all of the apps that they list.

Before submitting your merge request you want to be sure that you have created your metadata (as above) correctly and that the build process works. So you create a local copy of the fdroidserver repo in order to be able to complete the build process yourself. You only build your own app (luckily — building all of the apps on F-Droid would take days).

Explanation of how to use the build tools comes later in this series of articles.