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