=Basic instructions=

1. Copy config.sample.py to config.py and edit the path within accordingly
   to point to the Android tools
2. Make a repo directory and put APK files in it
3. Run update.py
4. If it reports that any metadata files are missing, you can create them
   in the metadata directory and run it again.
5. 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.
6. Then, if you've changed things, run update.py again.
7. Running update.py adds an Icons directory into the repo directory, and
   also creates the repository index (index.xml).
8. Transfer the repo directory to the appropriate http server. The script
   in upload.sh is an example of how to do this.

=Build System Requirements=

To be able to auto-build packages, you're going to need:

*Linux
*Python
*Android SDK with all SDK platforms (for all API versions) and tools
*Android NDK
*Ant
*Ant Contrib Tasks (Debian package ant-contrib)
*Maven (Debian package maven2)
*JavaCC (Debian package javacc)
*JDK (Debian package openjdk-6-jdk and openjdk-7-jdk)
*VCS clients: svn, git, hg, bzr
*A keystore for holding release keys. (Safe, secure and well backed up!)

You then need to create a config.py (copy config.sample.py and follow the
instructions) to specify the locations of some of these things.

==Building Apps==

Run

  ./build.py -p goo.TeaTimer

to test building apk files. They will be put in the repo directory.

=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. Within the file, the following
fields are recognised:

==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, git-svn, svn, hg, bzr
 
The git-svn option connects to an SVN repository, and you specify the URL in
exactly the same way, but git is used as a back-end. This is preferable for
performance reasons.

==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. (Doesn't work for git-svn).

==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.
 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=xxx	   By default, 'android update project' is used to generate or
                   update the build.xml file. Specifying update=no bypasses
                   that. Specifiying update=force forces rebuilding of the
		   build.xml file at the same time - this is frequently needed
		   with r14 of the Android platform tools. Be aware of any
		   customisations in build.xml when using update=force.
 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.
 init=xxxx	   As for 'prebuild', but runs on the source code BEFORE any
 		   other processing takes place.
 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.
 extlibs=a;b;c     Specifies a list of external libraries (jar files) from the
                   build/extlib library, which will be placed in the libs
		   directory of the project. Separate items with semicolons.
 srclibs=a@r;b@r1  Specifies a list of source libraries (kept up to date using
                   version control) from a predefined set. Separate items with
		   semicolons, and each item is of the form name@rev where name
		   is the predefined source library name and rev is the
		   revision in source control to use. You can then also use
		   $$name$$ in the prebuild command to substitute the relative
		   path to the library directory.

Another example, using extra parameters:

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

==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
  "NonFreeDep" - the application depends on another non-Free application (e.g. Google Maps)

==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.