F-Droid Server
**************

This manual is for the F-Droid repository server tools.

Copyright © 2010, 2011, 2012 Ciaran Gultnieks Copyright © 2011 Henrik Tunedal, Michael Haas, John Sullivan

     Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

Overview
********

The F-Droid server tools provide various scripts, tools and data that are used to maintain the main F-Droid application repository. You can use these same tools to create your own additional or alternative repository for publishing, or to assist in creating, testing and submitting metadata to the main repository.

System Requirements
*******************

The system requirements for using the tools will vary depending on your intended usage. At the very least, you'll need:

  * GNU/Linux

  * Python 2.x

  * The Android SDK

If you intend to build applications from source you'll also need most, if not all, of the following:

  * All available SDK platforms and tools installed in the Android SDK, but *not* the proprietary components.

  * The Android NDK

  * Ant

  * Ant Contrib Tasks (Debian package ant-contrib)

  * Maven (Debian package maven2)

  * JavaCC (Debian package javacc)

  * VCS clients: svn, git, hg, bzr

  * A keystore for holding release keys. (Safe, secure and well backed up!)

If you intend to use the 'Build Server' system, for secure and clean builds (highly recommended), you will also need:

  * VirtualBox (debian package virtualbox-ose)

  * Ruby

  * Vagrant and Vagrant-snap

  * Paramiko (debian package python-paramiko)

Setup
*****

Because the tools and data will always change rapidly, you will almost certainly want to work from a git clone of the tools, which are designed to work in this way, with all associated data in a pre-defined directory structure below the main one. To get started:

     git clone git://gitorious.org/f-droid/fdroidserver.git
     cd fdroidserver

You will now be in the root directory of the tools. All the tasks associated with managing the repository and data are done from here.

Regardless of the intended usage of the tools, you will always need to set up some basic configuration details. This is done by creating a file called config.py which you should do by copying from config.sample.py and then editing according to the instructions within.

Simple Binary Repository
************************

If you want to maintain a simple repository hosting only binary APKs obtained and compiled elsewhere, the process is quite simple:

 1. Make a repo directory and put APK files in it.

 2. Run update.py.

 3. If it reports that any metadata files are missing, you can create them in the metadata directory and run it again.

 4. To ease creation of metadata files, run update.py with the -c option. It will create 'skeleton' metadata files that are missing, and you can then just edit them and fill in the details.

 5. Then, if you've changed things, run update.py again.

 6. Running update.py adds an Icons directory into the repo directory, and also creates the repository index (index.xml, and also index.jar if you've configured the system to use a signed index).

Following the above process will result in a repo directory, which you simply need to push to any HTTP (or preferably HTTPS) server to make it accessible.

While some information about the applications (and versions thereof) is retrieved directly from the APK files, most comes from the corresponding file in the metadata directory. The metadata file covering ALL versions of a particular application is named package.id.txt where package.id is the unique identifier for that package.

See the Metadata chapter for details of what goes in the metadata file. All fields are relevant for binary APKs, EXCEPT for 'Build Version' entries, which should be omitted.

Building Applications
*********************

Instead of (or as well as) including binary APKs from external sources in a repository, you can build them directly from the source code.

Using this method, it is is possible to verify that the application builds correctly, corresponds to the source code, and contains only free software. Unforunately, in the Android world, it seems to be very common for an application supplied as a binary APK to present itself as Free Software when in fact some or all of the following are true:

 1. The source code (either for a particular version, or even all versions!) is unavailable or incomplete.

 2. The source code is not capable of producing the actual binary supplied.

 3. The 'source code' contains binary files of unknown origin, or with proprietary licenses.

For this reason, source-built applications are the preferred method for the main F-Droid repository, although occasionally for technical or historical reasons, exceptions are made to this policy.

When building applications from source, it should be noted that you will be signing them (all APK files must be signed to be installable on Android) with your own key. When an application is already installed on a device, it is not possible to upgrade it in place to a new version signed with a different key without first uninstalling the original. This may present an inconvenience to users, as the process of uninstalling loses any data associated with the previous installation.

The process for managing a repository for built-from-source applications is very similar to that described in the Simple Binary Repository chapter, except now you need to:

 1. Include Build Version entries in the metadata files.

 2. Run build.py to build any applications that are not already built.

 3. Run publish.py to finalise packaging and sign any APKs that have been built.

Metadata
********

Information used by update.py to compile the public index comes from two sources, 1) the APK files in the repo directory, and 2) the metadata files in the metadata directory.

The metadata files are simple, easy to edit text files, always named as the application's package ID with '.txt' appended. The following sections describe the fields recognised within the file.

License
=======

The license for the application.

Common values:

  * GPLv2

  * GPLv2+

  * GPLv3

  * Apache2

  * MIT

  * BSD

Name
====

The name of the application. Normally, this field should not be present since the application's correct name is retrieved from the APK file. However, in a situation where an APK contains a bad or missing application name, it can be overridden using this.

Web Site
========

The URL for the application's web site.

Source Code
===========

The URL to view or obtain the application's source code. This should be something human-friendly. Machine-readable source-code is covered in the 'Repo' field.

Issue Tracker
=============

The URL for the application's issue tracker. Optional, since not all applications have one.

Donate
======

The URL to donate to the project. This could be the project's donate page if it has one, or perhaps even a direct PayPal link.

Summary
=======

A brief summary of what the application is.

Description
===========

A full description of the application. This can span multiple lines, and is terminated by a line containing a single '.'.

Repo Type
=========

The type of repository - for automatic building from source. If this is not specified, automatic building is disabled for this application. Possible values are:

  * git

  * svn

  * hg

  * bzr

Repo
====

The repository location. Usually a git: or svn: URL.

For a Subversion repo that requires authentication, you can precede the repo URL with username:password and those parameters will be passed as --username and --password to the SVN checkout command.

Build Version
=============

Any number of these fields can be present, each specifying a version to automatically build from source. The value is a comma-separated list. For example:

Build Version:0.12,3,651696a49be2cd7db5ce6a2fa8185e31f9a20035

The above specifies to build version 0.12, which has a version code of 3. The third parameter specifies the tag, commit or revision number from which to build it in the source repository.

If the commit version starts with a !, that version is not built. Instead, everything after the ! is used as a reason why it can't be built. The purpose of this feature is to allow non-buildable releases (e.g. the source is not published) to be flagged, so the scripts don't generate repeated messages about them. (And also to record the information for review later).

In addition to the three, always required, parameters described above, further parameters can be added (in name=value format) to apply further configuration to the build. These are:

subdir=<path>
     Specifies to build from a subdirectory of the checked out source code. Normally this directory is changed to before building, but there is a special case for SVN repositories where the URL is specified with a * at the end. See the documentation for the Repo field for more information.

bindir=<path>
     Normally the build output (apk) is expected to be in the bin subdirectory below the ant build files. If the project is configured to put it elsewhere, that can be specified here, relative to the base of the checked out repo.

oldsdkloc=yes
     The sdk location in the repo is in an old format, or the build.xml is expecting such. The 'new' format is sdk.dir while the VERY OLD format is sdk-location. Typically, if you get a message along the lines of: "com.android.ant.SetupTask cannot be found" when trying to build, then try enabling this option.

target=<target>
     Specifies a particular SDK target, when the source doesn't. This is likely to cause the whole build.xml to be rewritten, which is fine if it's a 'standard' android file or doesn't already exist, but not a good idea if it's heavily customised.

rm=<relpath>
     Specifies the relative path of file to delete before the build is done. The path is relative to the base of the build directory - i.e. the directory that contains AndroidManifest.xml.

antcommand=xxx
     Specify an alternate ant command (target) instead of the default 'release'.

forceversion=yes
     If specified, the package version in AndroidManifest.xml is replaced with the version number for the build as specified in recipe. Useful for cases when upstream repo missed to update it for specific tag, or to build an arbitrary revision.

forcevercode=yes
     If specified, the package vercode in the AndroidManifest.xml is replaced with the version code for the build. See also forceversion.

update=no
     By default, 'android update project' is used to generate or update the build.xml file. Specifying update=no bypasses that.

initfun=yes
     Enables a selection of mad hacks to make com.funambol.android build. Probably not useful for any other application.

buildjni=yes
     Enables building of native code via the ndk-build script before doing the main ant build.

submodules=yes
     Use if the project (git only) has submodules - causes git submodule init and update to be executed after the source is cloned.

encoding=xxxx
     Adds a java.encoding property to local.properties with the given value. Generally the value will be 'utf-8'. This is picked up by the SDK's ant rules, and forces the Java compiler to interpret source files with this encoding. If you receive warnings during the compile about character encodings, you probably need this.

prebuild=xxxx
     Specifies a shell command (or commands - chain with &&) to run before the build takes place. Backslash can be used as an escape character to insert literal commas, or as the last character on a line to join that line with the next. It has no special meaning in other contexts; in particular, literal backslashes should not be escaped.

novcheck=yes
     Don't check that the version name and code in the resulting apk are correct by looking at the build output - assume the metadata is correct. This takes away a useful level of sanity checking, and should only be used if the values can't be extracted.

fixtrans=yes
     Modifies any instances of string resources that use multiple formatting arguments, but don't use positional notation. For example, "Hello %s, %d" becomes "Hello %1$s, %2$d". Newer versions of the Android platform tools enforce this sensible standard. If you get error messages relating to that, you need to enable this.

fixapos=yes
     Like fixtrans, but deals with an even older issue relating to 'unescaped apostrophes' in translation strings.

maven=yes
     Build with maven instead of ant

patch=x
     Apply patch(es). 'x' names one (or more - comma-seperated) files within a directory below the metadata, with the same name as the metadata file but without the extension. Each of these patches is applied to the code in turn.

Another example, using extra parameters:

Build Version:1.09.03,10903,45,subdir=Timeriffic,oldsdkloc=yes

Use Built
=========

Set this to "Yes" to use built versions of the application for the repository. Currently, this just triggers update.py to copy the relevant apks and tarballs from the 'built' directory before updating the repo index.

AntiFeatures
============

This is optional - if present, it contains a comma-separated list of any of the following values, describing an AntiFeature the application has:

  * Ads - the application contains advertising

  * Tracking - the application tracks and reports your activity to somewhere

  * NonFreeNet - the application promotes a non-Free network service

  * NonFreeAdd - the application promotes non-Free add-ons

Disabled
========

If this field is present, the application does not get put into the public index. This allows metadata to be retained while an application is temporarily disabled from being published. The value should be a description of why the application is disabled.

Requires Root
=============

Set this optional field to "Yes" if the application requires root privileges to be usable. This lets the client filter it out if the user so desires.

GNU Free Documentation License
******************************

     [file fdl.texi not included]