Copyright @copyright{} 2013 David Black
-Copyright @copyright{} 2013, 2014 Daniel MartÃ
+Copyright @copyright{} 2013, 2014, 2015 Daniel MartÃ
+
+Copyright @copyright{} 2015 Boris Kraut
@quotation
Permission is granted to copy, distribute and/or modify this document
@item
Vagrant (unpackaged, tested on v1.4.3)
@item
+vagrant-cachier plugin (unpackaged): `vagrant plugin install vagrant-cachier`
+@item
Paramiko (debian package python-paramiko)
@item
Imaging (debian package python-imaging)
-@item
-Magic (debian package python-magic)
@end itemize
On the other hand, if you want to build the apps directly on your system
the metadata files in the metadata directory.
@end enumerate
-The metadata files are simple, easy to edit text files, always named as the
-application's package ID with '.txt' appended.
-
-Note that although the metadata files are designed to be easily read and
-writable by humans, they are also processed and written by various scripts.
-They are capable of rewriting the entire file when necessary. Even so,
-the structure and comments will be preserved correctly, although the order
-of fields will be standardised. (In the event that the original file was
-in a different order, comments are considered as being attached to the field
-following them). In fact, you can standardise all the metadata in a single
-command, without changing the functional content, by running:
+The original metadata files are simple, easy to edit text files,
+always named as the application's package ID with '.txt' appended.
+Additionally, you can use JSON, XML, or YAML for app metadata, using
+the same fields as the original '.txt' format.
+
+Note that although the metadata files are designed to be easily read
+and writable by humans, they are also processed and written by various
+scripts. The original '.txt' format can be automatically cleaned up
+when necessary. The structure and comments will be preserved
+correctly, although the order of fields will be standardised. (In the
+event that the original file was in a different order, comments are
+considered as being attached to the field following them). In fact,
+you can standardise all the '.txt' metadata in a single command,
+without changing the functional content, by running:
@example
fdroid rewritemeta
@end example
+Or just run it on a specific app:
+
+@example
+fdroid rewritemeta org.adaway
+@end example
+
The following sections describe the fields recognised within the file.
@menu
* Maintainer Notes::
* Repo Type::
* Repo::
+* Binaries::
* Build::
* AntiFeatures::
* Disabled::
@cindex Summary
A brief summary of what the application is. Since the summary is only allowed
-one line on the list of the F-Droid client, keeping it to within 50 characters
+one line on the list of the F-Droid client, keeping it to within 80 characters
will ensure it fits most screens.
@node Description
@item
@samp{srclib}
@end itemize
+
@node Repo
@section Repo
and you want to use this srclib, then you have to set Repo to
@code{FooBar}.
+@node Binaries
+@section Binaries
+
+@cindex Binaries
+
+The location of binaries used in verification process.
+
+If specified, F-Droid will verify the output apk file of a build against the
+one specified. You can use %v and %c to point to the version name and version
+code of the current build. To verify the F-Droid client itself you could use:
+@code{Binaries:https://f-droid.org/repo/org.fdroid.fdroid_%c.apk}
+
+F-Droid will use upstream binaries if the verification succeeded.
+
@node Build
@section Build
For Ant projects, you can optionally append a number with a colon at the
beginning of a srclib item to automatically place it in project.properties as
a library under the specified number. For example, if you specify
-@code{1:somelib@@1.0}, f-droid will automatically do the equivalent of the
+@code{1:somelib@@1.0}, F-Droid will automatically do the equivalent of the
legacy practice @code{prebuild=echo "android.library.reference.1=$$somelib$$"
>> project.properties}.
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.
+Currently srclibs are necessary when upstream uses jar files or pulls
+dependencies from non-trusted repositories. While there is no guarantee that
+those binaries are free and correspondent to the source code, F-Droid allows
+the following known repositories until a source-built alternative is available:
+
+@itemize @bullet
+
+@item
+@samp{mavenCentral} - the original repo, hardcoded in Maven and Gradle.
+
+@item
+@samp{jCenter} - hardcoded in Gradle, this repo by Bintray tries to provide
+easier handling. It should sync with mavenCentral from time to time.
+
+@item
+@samp{OSS Sonatype} - maintained by the people behind mavenCentral, this
+repository focuses on hosting services for open source project binaries.
+
+@item
+@samp{JitPack.io} - builds directly from Github repositories. However,
+they do not provide any option to reproduce or verify the resulting
+binaries. Builds pre-release versions in some cases.
+
+@end itemize
+
@item 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
paths start with any of the paths given here are ignored.
@item 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.
+When running the scan process, any files that trigger errors - like binaries -
+will be removed. It acts just like scanignore=, but instead of ignoring the
+files, it removes them.
+
+Useful when a source code repository includes binaries or other unwanted files
+which are not needed for the build. Instead of removing them manually via rm=,
+using scandelete= is easier.
@item build=xxxx
As for 'prebuild', but runs during the actual build phase (but before the
Build with Gradle instead of Ant, specifying what flavours to use. Flavours
are case sensitive since the path to the output apk is as well.
-If only one flavour is given and it is 'yes' or 'main', no flavour will be
-used. Note that for projects with flavours, you must specify at least one
-valid flavour since 'yes' or 'main' will build all of them separately.
+If only one flavour is given and it is 'yes', no flavour will be used.
+Note that for projects with flavours, you must specify at least one
+valid flavour since 'yes' will build all of them separately.
@item maven=yes[@@<dir>]
-Build with Maven instead of Ant. An extra @@<dir> tells f-droid to run Maven
+Build with Maven instead of Ant. An extra @@<dir> tells F-Droid to run Maven
inside that relative subdirectory. Sometimes it is needed to use @@.. so that
builds happen correctly.
List of Gradle tasks to be run before the assemble task in a Gradle project
build.
+@item gradleprops=<prop1>[,<prop2>,...]
+List of Gradle properties to pass via the command line to Gradle. A property
+can be of the form @code{foo} or of the form @code{key=value}.
+
+For example: @code{gradleprops=enableFoo,someSetting=bar} will result in
+@code{gradle -PenableFoo -PsomeSetting=bar}.
+
@item antcommands=<target1>[,<target2>,...]
Specify an alternate set of Ant commands (target) instead of the default
'release'. It can't be given any flags, such as the path to a build.xml.