Merge branch 'docs' into 'master'

[fdroidserver.git] / docs / fdroid.texi

diff --git a/docs/fdroid.texi b/docs/fdroid.texi
index 76988d96f437d0487d9472f1496acdbb2bb33ad8..7b94dc69e3e2de4f62012308afdd3c6b3042dbd6 100644 (file)
--- a/docs/fdroid.texi
+++ b/docs/fdroid.texi
@@ -14,7 +14,9 @@ Copyright @copyright{} 2011 Henrik Tunedal, Michael Haas, John Sullivan
 
 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
@@ -122,8 +124,6 @@ vagrant-cachier plugin (unpackaged): `vagrant plugin install vagrant-cachier`
 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
@@ -491,6 +491,7 @@ The following sections describe the fields recognised within the file.
 * Maintainer Notes::
 * Repo Type::
 * Repo::
+* Binaries::
 * Build::
 * AntiFeatures::
 * Disabled::
@@ -706,7 +707,7 @@ A litecoin address for donating to the project.
 @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
@@ -778,6 +779,7 @@ values are:
 @item
 @samp{srclib}
 @end itemize
+
 @node Repo
 @section Repo
 
@@ -803,6 +805,20 @@ according srclib .txt file. For example if @code{scrlibs/FooBar.txt} exist
 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
 
@@ -929,7 +945,7 @@ the revision or tag to use in the respective source control.
 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}.
 
@@ -943,6 +959,31 @@ 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.
 
+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
@@ -1031,12 +1072,12 @@ adding them to 'ndk_paths' in your config file.
 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.