Next: AntiFeatures, Previous: Repo, Up: Metadata [Contents][Index]
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.
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 (roughly in order of application):
disable=<message>
Disables this build, giving a reason why. (For backwards compatibility, this can also be achieved by starting the commit ID with ’!’)
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).
If an apk has already been built, disabling causes it to be deleted once
fdroid update
is run; this is the procedure if ever a version has to
be replaced.
subdir=<path>
Specifies to build from a subdirectory of the checked out source code. Normally this directory is changed to before building,
submodules=yes
Use if the project (git only) has submodules - causes git submodule init and update to be executed after the source is cloned.
init=xxxx
As for ’prebuild’, but runs on the source code BEFORE any other processing takes place.
You can use $$SDK$$, $$NDK$$ and $$MVN3$$ to substitute the paths to the android SDK and NDK directories, and maven 3 executable respectively.
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 for compilation, overriding the
project.properties of the app and possibly sub-projects. Note that this does
not change the target SDK in the AndroidManifest.xml — the level of features
that can be included in the build. 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. If you get an
error about invalid target, first try init=rm -rf bin/
; otherwise this
parameter should do the trick.
Please note that gradle builds should be using compilesdk=.
compilesdk=<level>
Practically accomplishes the same that target= does when used in ant and maven projects. compilesdk= is used rather than target= so as to not cause any more confusion. It only takes effect on gradle builds in the build.gradle file, thus using it in any other case is not wise.
update=xxx
By default, ’android update project’ is used to generate or update the project and all its referenced projects. 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.
Default value is ’auto
’, which uses the paths used in the
project.properties file to find out what project paths to update.
Otherwise, value can be a semicolon-separated list of directories in
which to run ’android update project’ relative to the main
application directory (which may include ’subdir
’ parameter).
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.
forceversion=yes
If specified, the package version in AndroidManifest.xml is replaced with the version name for the build as specified in the metadata.
This is useful for cases when upstream repo failed to update it for specific tag; to build an arbitrary revision; to make it apparent that the version differs significantly from upstream; or to make it apparent which architecture or platform the apk is designed to run on.
forcevercode=yes
If specified, the package version code in the AndroidManifest.xml is replaced with the version code for the build. See also forceversion.
rm=<relpath1;relpath2;...>
Specifies the relative paths of files or directories to delete before the build is done. The paths are relative to the base of the build directory - i.e. the root of the directory structure checked out from the source respository - not necessarily the directory that contains AndroidManifest.xml.
Multiple files/directories can be specified by separating them with ’;’. Directories will be recursively deleted.
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.
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 or Android projects. 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 or tag in source control to use.
Each srclib has a metadata file under srclibs/ in the repository directory, and the source code is stored in build/srclib/. Repo Type: and Repo: are specified in the same way as for apps; Subdir: can be a comma separated list, for when directories are renamed by upstream; Update Project: updates the projects in the working directory and one level down; Prepare: can be used for any kind of preparation: in particular if you need to update the project with a particular target. You can then also use $$name$$ in the init/prebuild/build command to substitute the relative path to the library directory, but it could need tweaking if you’ve changed into another directory.
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.
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.
The command runs using bash.
Note that nothing should be build during this prebuild phase - scanning of the code and building of the source tarball, for example, take place after this. For custom actions that actually build things, use ’build’ instead.
You can use $$name$$ to substitute the path to a referenced srclib - see
the srclib
directory for details of this.
You can use $$SDK$$, $$NDK$$ and $$MVN3$$ to substitute the paths to the
android SDK and NDK directories, and maven 3 executable respectively e.g.
for when you need to run android update project
explicitly.
scanignore=path1;path2;...
Enables one or more files/paths to be exlcuded from the scan process. This should only be used where there is a very good reason, and probably accompanied by a comment explaining why it is necessary.
When scanning the source tree for problems, matching files whose relative paths start with any of the paths given here are ignored.
scandelete=path1;path2;...
Similar to scanignore=, but instead of ignoring files under the given paths, it tells f-droid to delete the matching files directly.
build=xxxx
As for ’prebuild’, but runs during the actual build phase (but before the main ant/maven build). Use this only for actions that do actual building. Any prepartion of the source code should be done using ’init’ or ’prebuild’.
Any building that takes place before build= will be ignored, as either ant, mvn or gradle will be executed to clean the build environment right before build= (or the final build) is run.
You can use $$SDK$$, $$NDK$$ and $$MVN3$$ to substitute the paths to the android SDK and NDK directories, and maven 3 executable respectively.
buildjni=[yes|no|<dir list>]
Enables building of native code via the ndk-build script before doing the main ant build. The value may be a list of directories relative to the main application directory in which to run ndk-build, or ’yes’ which corresponds to ’.’ . Using explicit list may be useful to build multi-component projects.
The build and scan processes will complain (refuse to build) if this
parameter is not defined, but there is a jni
directory present.
If the native code is being built by other means, you can specify
no
here to avoid that. However, if the native code is actually
not required, remove the directory instead (using prebuild
for
example).
gradle=<flavour>[@<dir>]
Build with gradle instead of ant, specifying what flavour to assemble. If <flavour> is ’yes’, ’main’ or empty, no flavour will be used. Note that this will not work on projects with flavours, since it will build all flavours and there will be no ’main’ build. If @<dir> is attached to <flavour>, then the gradle tasks will be run in that directory. This might be necessary if gradle needs to be run in the parent directory, in which case one would use ’gradle=<flavour>..’.
maven=yes[@<dir>]
Build with maven instead of ant. Like gradle, an extra @<dir> tells f-droid to run maven inside that relative subdirectory.
preassemble=<task1> <task2>
Space-separated list of gradle tasks to be run before the assemble task in a gradle project build.
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. Not yet implemented for gradle.
antcommand=xxx
Specify an alternate ant command (target) instead of the default ’release’. It can’t be given any flags, such as the path to a build.xml.
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.
Another example, using extra parameters:
‘Build Version:1.09.03,10903,45,subdir=Timeriffic,oldsdkloc=yes’
Next: AntiFeatures, Previous: Repo, Up: Metadata [Contents][Index]