README

   1 =Basic instructions=
   2
   3 1. Copy config.sample.py to config.py and edit the path within accordingly
   4    to point to the Android tools
   5 2. Make a repo directory and put APK files in it
   6 3. Run update.py
   7 4. If it reports that any metadata files are missing, you can create them
   8    in the metadata directory and run it again.
   9 5. To ease creation of metadata files, run update.py with the -c option. It
  10    will create 'skeleton' metadata files that are missing, and you can then
  11    just edit them and fill in the details.
  12 6. Then, if you've changed things, run update.py again.
  13 7. Running update.py adds an Icons directory into the repo directory, and
  14    also creates the repository index (index.xml).
  15 8. Transfer the repo directory to the appropriate http server. The script
  16    in upload.sh is an example of how to do this.
  17
  18 =Build System Requirements=
  19
  20 To be able to auto-build packages, you're going to need:
  21
  22 *Linux
  23 *Python
  24 *A fully functional Android SDK with all SDK platforms and tools
  25 *The Android NDK
  26 *Ant
  27 *Ant Contrib Tasks (Debian package ant-contrib)
  28 *Maven (Debian package maven2)
  29 *JavaCC (Debian package javacc)
  30 *VCS clients: svn, git, hg, bzr
  31 *A keystore for holding release keys. (Safe, secure and well backed up!)
  32
  33 You then need to create a config.py (copy config.sample.py and follow the
  34 instructions) to specify the locations of some of these things.
  35
  36 =MetaData=
  37
  38 Information used by update.py to compile the public index comes from two
  39 sources, 1) the APK files in the repo directory, and 2) the metadata files
  40 in the metadata directory.
  41
  42 The metadata files are simple, easy to edit text files, always named as the
  43 application's package ID with '.txt' appended. Within the file, the following
  44 fields are recognised:
  45
  46 ==License==
  47
  48 The license for the application.
  49
  50 Common values: GPLv2, GPLv2+, GPLv3, Apache2, MIT, BSD
  51
  52 ==Name==
  53
  54 The name of the application. Normally, this field should not be present since the
  55 application's correct name is retrieved from the APK file. However, in a situation
  56 where an APK contains a bad or missing application name, it can be overridden
  57 using this.
  58
  59 ==Web Site==
  60
  61 The URL for the application's web site.
  62
  63 ==Source Code==
  64
  65 The URL to view or obtain the application's source code. This should be
  66 something human-friendly. Machine-readable source-code is covered in the
  67 'Repo' field.
  68
  69 ==Issue Tracker==
  70
  71 The URL for the application's issue tracker. Optional, since not all
  72 applications have one.
  73
  74 ==Donate==
  75
  76 The URL to donate to the project. This could be the project's donate page
  77 if it has one, or perhaps even a direct PayPal link.
  78
  79 ==Summary==
  80
  81 A brief summary of what the application is.
  82
  83 ==Description==
  84
  85 A full description of the application. This can span multiple lines, and is
  86 terminated by a line containing a single '.'.
  87
  88 ==Repo Type==
  89
  90 The type of repository - for automatic building from source. If this is not
  91 specified, automatic building is disabled for this application. Possible
  92 values are:
  93
  94   git, svn, hg, bzr
  95
  96 ==Repo==
  97
  98 The repository location. Usually a git: or svn: URL.
  99
 100 For a Subversion repo that requires authentication, you can precede the repo
 101 URL with username:password@ and those parameters will be passed as --username
 102 and --password to the SVN checkout command.
 103
 104 ==Build Version==
 105
 106 Any number of these fields can be present, each specifying a version to
 107 automatically build from source. The value is a comma-separated list.
 108 For example:
 109
 110     Build Version:0.12,3,651696a49be2cd7db5ce6a2fa8185e31f9a20035
 111
 112 The above specifies to build version 0.12, which has a version code of 3.
 113 The third parameter specifies the tag, commit or revision number from
 114 which to build it in the source repository.
 115
 116 If the commit version starts with a !, that version is not built. Instead,
 117 everything after the ! is used as a reason why it can't be built. The
 118 purpose of this feature is to allow non-buildable releases (e.g. the source
 119 is not published) to be flagged, so the scripts don't generate repeated
 120 messages about them. (And also to record the information for review later).
 121
 122 In addition to the three, always required, parameters described above,
 123 further parameters can be added (in name=value format) to apply further
 124 configuration to the build. These are:
 125
 126  subdir=<path>   - Specifies to build from a subdirectory of the checked out
 127                    source code. Normally this directory is changed to before
 128                    building, but there is a special case for SVN repositories
 129                    where the URL is specified with a * at the end. See the
 130                    documentation for the Repo field for more information.
 131  bindir=<path>   - Normally the build output (apk) is expected to be in the
 132                    bin subdirectory below the ant build files. If the project
 133                    is configured to put it elsewhere, that can be specified
 134                    here, relative to the base of the checked out repo..
 135  oldsdkloc=yes   - The sdk location in the repo is in an old format, or the
 136                    build.xml is expecting such. The 'new' format is sdk.dir
 137                    while the VERY OLD format is sdk-location. Typically, if
 138                    you get a message along the lines of:
 139                       "com.android.ant.SetupTask cannot be found"
 140                    when trying to build, then try enabling this option.
 141  target=<target> - Specifies a particular SDK target, when the source doesn't.
 142                    This is likely to cause the whole build.xml to be rewritten,
 143                    which is fine if it's a 'standard' android file or doesn't
 144                    already exist, but not a good idea if it's heavily
 145                    customised.
 146  rm=<relpath>    - Specifies the relative path of file to delete before the
 147                    build is done. The path is relative to the base of the
 148                    build directory - i.e. the directory that contains
 149                    AndroidManifest.xml.
 150  antcommand=xxx  - Specify an alternate ant command (target) instead of the
 151                    default 'release'.
 152  insertversion=x - If specified, the pattern 'x' in the AndroidManifest.xml is
 153                    replaced with the version number for the build.
 154  insertvercode=x - If specified, the pattern 'x' in the AndroidManifest.xml is
 155                    replaced with the version code for the build.
 156  update=no         By default, 'android update project' is used to generate or
 157                    update the build.xml file. Specifying update=no bypasses
 158                    that.
 159  initfun=yes       Enables a selection of mad hacks to make com.funambol.android
 160                    build. Probably not useful for any other application.
 161  buildjni=yes      Enables building of native code via the ndk-build script
 162                    before doing the main ant build.
 163  submodules=yes    Use if the project (git only) has submodules - causes git
 164                    submodule init and update to be executed after the source is
 165                    cloned.
 166  encoding=xxxx     Adds a java.encoding property to local.properties with the
 167                    given value. Generally the value will be 'utf-8'. This is
 168                    picked up by the SDK's ant rules, and forces the Java
 169                    compiler to interpret source files with this encoding. If
 170                    you receive warnings during the compile about character
 171                    encodings, you probably need this.
 172  prebuild=xxxx     Specifies a shell command (or commands - chain with &&) to
 173                    run before the build takes place. Backslash can be used
 174                    as an escape character to insert literal commas, or as the
 175                    last character on a line to join that line with the next.
 176                    It has no special meaning in other contexts; in particular,
 177                    literal backslashes should not be escaped.
 178  novcheck=yes      Don't check that the version name and code in the resulting
 179                    apk are correct by looking at the build output - assume the
 180                    metadata is correct. This takes away a useful level of
 181                    sanity checking, and should only be used if the values can't
 182                    be extracted.
 183  fixtrans=yes      Modifies any instances of string resources that use multiple
 184                    formatting arguments, but don't use positional notation. For
 185                    example, "Hello %s, %d" becomes "Hello %1$s, %2$d". Newer
 186                    versions of the Android platform tools enforce this sensible
 187                    standard. If you get error messages relating to that, you
 188                    need to enable this.
 189  fixapos=yes       Like fixtrans, but deals with an even older issue relating
 190                    to 'unescaped apostrophes' in translation strings.
 191  maven=yes         Build with maven instead of ant
 192  patch=x           Apply patch(es). 'x' names one (or more - comma-seperated)
 193                    files within a directory below the metadata, with the same
 194                    name as the metadata file but without the extension. Each of
 195                    these patches is applied to the code in turn.
 196
 197 Another example, using extra parameters:
 198
 199     Build Version:1.09.03,10903,45,subdir=Timeriffic,oldsdkloc=yes
 200
 201 ==AntiFeatures==
 202
 203 This is optional - if present, it contains a comma-separated list of any of
 204 the following values, describing an AntiFeature the application has:
 205
 206   "Ads" - the application contains advertising
 207   "Tracking" - the application tracks and reports your activity to somewhere
 208   "NonFreeNet" - the application promotes a non-Free network service
 209   "NonFreeAdd" - the application promotes non-Free add-ons
 210
 211 ==Disabled==
 212
 213 If this field is present, the application does not get put into the public
 214 index. This allows metadata to be retained while an application is temporarily
 215 disabled from being published. The value should be a description of why the
 216 application is disabled.
 217
 218 ==Requires Root==
 219
 220 Set this optional field to "Yes" if the application requires root
 221 privileges to be usable. This lets the client filter it out if the
 222 user so desires.