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 *JavaCC (Debian package javacc)
  29 *VCS clients: svn, git, hg, bzr
  30 *A keystore for holding release keys. (Safe, secure and well backed up!)
  31
  32 You then need to create a config.py (copy config.sample.py and follow the
  33 instructions) to specify the locations of some of these things.
  34 Also make sure the SDK tools - found in $SDK/tools/ - are in your $PATH.
  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 ==Summary==
  75
  76 A brief summary of what the application is.
  77
  78 ==Description==
  79
  80 A full description of the application. This can span multiple lines, and is
  81 terminated by a line containing a single '.'.
  82
  83 ==Repo Type==
  84
  85 The type of repository - for automatic building from source. If this is not
  86 specified, automatic building is disabled for this application. Possible
  87 values are:
  88
  89   git, svn, hg, bzr
  90
  91 ==Repo==
  92
  93 The repository location. Usually a git: or svn: URL.
  94
  95 Normally the repository is checked out once for the application, then moved
  96 to a particular revision/commit/tag for each build version. For an SVN
  97 repository though, this behaviour can be changed by appending a * to the
  98 repository URL - in this case the repository is checked out once per build
  99 version, with the subdir parameter in place of the *. This can be beneficial
 100 when dealing with very large SVN repositories.
 101
 102 For a Subversion repo that requires authentication, you can precede the repo
 103 URL with username:password@ and those parameters will be passed as --username
 104 and --password to the SVN checkout command.
 105
 106 ==Build Version==
 107
 108 Any number of these fields can be present, each specifying a version to
 109 automatically build from source. The value is a comma-separated list.
 110 For example:
 111
 112     Build Version:0.12,3,651696a49be2cd7db5ce6a2fa8185e31f9a20035
 113
 114 The above specifies to build version 0.12, which has a version code of 3.
 115 The third parameter specifies the tag, commit or revision number from
 116 which to build it in the source repository.
 117
 118 In addition to the three, always required, parameters described above,
 119 further parameters can be added (in name=value format) to apply further
 120 configuration to the build. These are:
 121
 122  subdir=<path>   - Specifies to build from a subdirectory of the checked out
 123                    source code. Normally this directory is changed to before
 124                    building, but there is a special case for SVN repositories
 125                    where the URL is specified with a * at the end. See the
 126                    documentation for the Repo field for more information.
 127  bindir=<path>   - Normally the build output (apk) is expected to be in the
 128                    bin subdirectory below the ant build files. If the project
 129                    is configured to put it elsewhere, that can be specified
 130                    here, relative to the base of the checked out repo..
 131  oldsdkloc=yes   - The sdk location in the repo is in an old format, or the
 132                    build.xml is expecting such. The 'new' format is sdk.dir
 133                    while the VERY OLD format is sdk-location. Typically, if
 134                    you get a message along the lines of:
 135                         "com.android.ant.SetupTask cannot be found"
 136                    when trying to build, then try enabling this option.
 137  target=<target> - Specifies a particular SDK target, when the source doesn't.
 138                    This is likely to cause the whole build.xml to be rewritten,
 139                    which is fine if it's a 'standard' android file or doesn't
 140                    already exist, but not a good idea if it's heavily
 141                    customised.
 142  rm=<relpath>    - Specifies the relative path of file to delete before the
 143                    build is done. The path is relative to the base of the
 144                    build directory - i.e. the directory that contains
 145                    AndroidManifest.xml.
 146  antcommand=xxx  - Specify an alternate ant command (target) instead of the
 147                    default 'release'.
 148  insertversion=x - If specified, the pattern 'x' in the AndroidManifest.xml is
 149                    replaced with the version number for the build.
 150  insertvercode=x - If specified, the pattern 'x' in the AndroidManifest.xml is
 151                    replaced with the version code for the build.
 152  update=no         By default, 'android update project' is used to generate or
 153                    update the build.xml file. Specifying update=no bypasses
 154                    that.
 155  initfun=yes       Enables a selection of mad hacks to make com.funambol.android
 156                    build. Probably not useful for any other application.
 157  buildjni=yes      Enables building of native code via the ndk-build script before
 158                    doing the main ant build.
 159
 160 Another example, using extra parameters:
 161
 162     Build Version:1.09.03,10903,45,subdir=Timeriffic,oldsdkloc=yes
 163
 164 ==Use Built==
 165
 166 Set this to "Yes" to use built versions of the application for the repository.
 167 Currently, this just triggers update.py to copy the relevant apks and tarballs
 168 from the 'built' directory before updating the repo index.
 169
 170 ==AntiFeatures==
 171
 172 This is optional - if present, it contains a comma-separated list of any of
 173 the following values, describing an AntiFeature the application has:
 174
 175   "Ads" - the application contains advertising
 176   "Tracking" - the application tracks and reports your activity to somewhere
 177   "NonFreeNet" - the application promotes a non-Free network service
 178   "NonFreeAdd" - the application promotes non-Free add-ons
 179
 180 ==Disabled==
 181
 182 If this field is present, the application does not get put into the public
 183 index. This allows metadata to be retained while an application is temporarily
 184 disabled from being published. The value should be a description of why the
 185 application is disabled.
 186