Submitting a package to F-Droid

Here’s what I needed to get a dev environment for F-Droid up and running on Ubuntu 16.10, using F-Droid server version 0.7.0 (commit id 8147f9235), so that I could submit a package for inclusion in the F-Droid repository.

Doing this is apparently the best way to get your own package into the repository, since you can provide a direct merge request for the metadata about your package, making it easy for the maintainers.

References:

Setup

Before you start, manually install the Android SDK at ~/Android/Sdk/ – see Download Android Studio. I installed version 23.0.2, but you will probably have a later one and may need to adjust the version number below.

Note: If you’re only planning to contribute a package I’m fairly certain you don’t need to install the Android SDK at all – you can just use the build server by running ./makebuildserver as I outline below.

Also before you start, if you want to contribute to the server project you should fork the F-Droid server project by going to gitlab.com/fdroid/fdroidserver and clicking Fork. When you’ve done that, the git clone command below will need to change to clone your own fork via SSH, instead of the HTTPS one cloning the main repo that is shown below. Do the same for the F-Droid data project, which holds the information about the packages in F-Droid. It’s the data project where you will want to make changes if you are submitting a package.

Run these commands:

# Prerequisites
sudo apt-get install openjdk-8-jdk subversion git git-svn mercurial bzr virtualbox ruby ruby-dev vagrant python3 python3-paramiko python3-pil python3-pyasn1-modules python3-clint
vagrant plugin install vagrant-cachier
ln -s ~/Android/Sdk/build-tools/23.0.2/aapt ~/Android/Sdk/platform-tools/

# Get the code
cd ~/code
git clone https://gitlab.com/fdroid/fdroidserver.git
git clone https://gitlab.com/fdroid/fdroiddata.git
echo 'export PATH="~/code/fdroidserver:$PATH"' >> ~/.profile
source ~/.profile

# Config
cd fdroiddata
cp ../fdroidserver/examples/config.py ./
chmod 0600 config.py
echo 'sdk_path = "$HOME/Android/Sdk"' >> config.py

# Set up Vagrant build box
cd ../fdroidserver
cp ./examples/makebuildserver.config.py ./
./makebuildserver
# Now wait several hours for this to finish

# Build a package (the F-Droid client) just to check it works
cd ../fdroiddata
mkdir repo
fdroid update --create-key
fdroid readmeta  # Should give no output if it worked
fdroid build --server org.fdroid.fdroid
# Again, this could take several hours!

Make your own package

Below I’m using my own package, Rabbit Escape, as an example. Its Android code is inside rabbit-escape-ui-android/app, whereas many programs will just have it directly in a directory called “app”.

Rabbit Escape also builds non-Android-specific Java and other things during its build, so your package may be simpler.

cd ../fdroiddata
fdroid import --url https://github.com/andybalaam/rabbit-escape --subdir rabbit-escape-ui-android/app

Now edit the new file that was created – in my case it was called metadata/net.artificialworlds.rabbitescape.txt.

I set the following info:

Provides:net.artificialworlds.rabbitescape
Categories:Games
License:GPLv2+
Author Name:Andy Balaam and the Rabbit Escape developers
Author Email:rabbitescape@artificialworlds.net
Web Site:http://artificialworlds.net/rabbit-escape
Source Code:https://github.com/andybalaam/rabbit-escape
Issue Tracker:https://github.com/andybalaam/rabbit-escape/issues

Name:Rabbit Escape
Summary:Lemmings-like puzzle/action game
Description:
140 levels of puzzling action!

blah blah blah
.

Repo Type:git
Repo:https://github.com/andybalaam/rabbit-escape
Binaries:https://github.com/andybalaam/rabbit-escape/releases/download/v%v/rabbit-escape-%v.apk

Build:0.10.1,101
    commit=v0.10.1
    subdir=rabbit-escape-ui-android/app
    gradle=paid
    build=cd ../.. && make android-pre

Auto Update Mode:Version v%v
Update Check Mode:Tags v\d+\.\d+(\.\d+)?
Current Version:0.10.1
Current Version Code:101

For more info, see the F-Droid manual.

And then checked it all worked with:

cd ../fdroiddata
fdroid lint net.artificialworlds.rabbitescape
fdroid readmeta
fdroid checkupdates net.artificialworlds.rabbitescape
fdroid rewritemeta net.artificialworlds.rabbitescape

When I got the version stuff right the checkupdates command printed:

INFO: Processing net.artificialworlds.rabbitescape...
INFO: ...updating to version 0.10.1 (101)
INFO: Finished.

Then I made sure it built OK:

fdroid build --server -v -l net.artificialworlds.rabbitescape

Actually, it didn’t work, and I decided I had to request a new package (sox) be installed in the build machine environment (in the fdroidserver project). The relevant commit is here: 19e372026. Actually though, after discussion with the F-Droid devs we agreed I’d be better off not using sox during the build, so I didn’t need this.

Side note: if you do end up needing to modify the build environment for F-Droid, make sure you delete the fdroiddata/buildserver directory when you re-try your build. That one had me stuck for a few days, with the old environment being used no matter what caches I cleared and vagrant commands I ran.

And now I was ready to request my package be included in F-Droid by committing and pushing the changes I had made to the fdroiddata project to my forked repo, and clicking the Merge Request button in the gitlab UI. My merge request is here: gitlab.com/fdroid/fdroiddata/merge_requests/1965

Android: using a TextView to show rich text in an AlertDialog

If you want to display a link or basic formatting in an AlertDialog on Android, you can do it by providing HTML.

The key parts you need are Html.fromHtml and TextView.setMovementMethod.

Make sure you pass the dialog’s context in to the constructor of the TextView, not the context of the current activity. Otherwise the colours in your TextView will be wrong and you may well end up with black text on a dark grey background.

AlertDialog dialog = new AlertDialog.Builder( activity )
    .setTitle( t( world.name ) )
    .setPositiveButton( "Yes!" )
    .setNeutralButton( "Maybe?" )
    .create();

TextView view = new TextView( dialog.getContext() );
view.setText( Html.fromHtml( "<b>foo</b> <a href='#'>bar</a>" ) );
view.setMovementMethod( LinkMovementMethod.getInstance() );
view.setPadding( 10, 10, 10, 10 );

dialog.setView( view );
dialog.show();

If you are on API level 11+, you can use AlertDialog.Builder’s getContext() method, so you don’t have to create the dialog until the end.

Code for detecting when you leave an Android app

Further to Detecting whether an Android app is stopping (or starting), I implemented code to decide when you are leaving or entering my game Rabbit Escape.

The relevant class is called Lifecycle2SoundEvents. (Yes, it’s a terrible name. Yes, I spent a long time trying to name it, and this is the best I came up with.)

And the tests, which are in TestLifecycle2SoundEvents, look like this:

@Test
public void Press_the_home_button_api10_causes_pause()
{
    Tester t = new Tester( activity1 );

    t.in.onSaveInstanceState( activity1 );
    t.in.onPause( activity1 );
    t.in.onStop( activity1 );

    // When we press home, we must at least pause (really we stop)
    t.assertPaused();
}

which I was reasonably pleased with, because they match my original blog post Order of Android Activity lifecycle events fairly well, without too much noise.

Detecting whether an Android app is stopping (or starting)

I am writing an Android app (called Rabbit Escape), and I want it to start playing music when the user enters the app, and stop when the user leaves.

Not as easy as it sounds because Android largely doesn’t think in apps, but Activities.

Update: real-life code for this is here: Code for detecting when you leave an Android app.

In my previous post Order of Android Activity lifecycle events I tracked the methods that get called on activities on my two test devices when the user does various actions. There was some variation between devices, but we can determine some useful rules.

First, let’s enumerate what we need to detect.

The user leaves by:

  • pressing “home” at any time
  • pressing the power button when the app is running
  • pressing “back” when in the first activity
  • launching an external activity (e.g. web browser)

The user enters by:

  • starting the app (e.g. from the home page, or the “running apps” panel)
  • pressing the power button when the app has been suspended
  • pressing “back” when in an external activity launched by us

From the previous post we can work out these rules:

  • When the user is entering, onResume is always called (on the activity that will be current)
  • When the user is leaving, onStop is always called (on the current activity), except when pressing the power button (to turn off) where you may only see an onPause call.
  • When the user is moving between activities, onResume is always called on the new activity, and onStop is always called on the old one. The onResume call is always before onStop

Thus, if we are OK with leaving ourselves running when the power button is pressed, we can detect leaving and entering the app using the code below.

If we need to stop something when the power button is pressed too, it seems we must be prepared to stop it when we receive onPause, and immediately restart it if we receive onResume, hoping that doesn’t cause a problem (e.g. a break in the music).

// All activities have these two methods:
@Override
public void onResume()
{
    super.onResume();
    LeavingOrEntering.activityResumed( this );
}

@Override
public void onStop()
{
    super.onStop();
    LeavingOrEntering.activityStopped( this );
}

// And we detect leaving and entering like this:
class LeavingOrEntering
{
    private static Activity currentActivity = null;

    public static void activityResumed( Activity activity )
    {
        if ( currentActivity == null )
        {
            // We were resumed and no-one else was running.
            notifyEntering() // Start the music!
        }
        currentActivity = activity;
    }

    public static void activityStopped( Activity activity )
    {
        assert currentActivity != null;

        if ( currentActivity == activity )  
        {
            // We were stopped and no-one else has been started.
            notifyLeaving(); // Stop the music!
        }
        currentActivity == null;
    }
}