Copyright @copyright{} 2011 Henrik Tunedal, Michael Haas, John Sullivan
-Copyright @copyright{} 2013 David Black, Daniel Martí
+Copyright @copyright{} 2013 David Black
+
+Copyright @copyright{} 2013, 2014 Daniel Martí
@quotation
Permission is granted to copy, distribute and/or modify this document
@item
Ruby (debian packages ruby and rubygems)
@item
-Vagrant (unpackaged) Be sure to use 1.3.x because 1.4.x is completely broken
-(at the time of writing, the forthcoming 1.4.3 might work)
+Vagrant (unpackaged, tested on v1.4.3)
@item
Paramiko (debian package python-paramiko)
@item
get started:
@example
-git clone git://gitorious.org/f-droid/fdroidserver.git
+git clone https://gitlab.com/fdroid/fdroidserver.git
@end example
You now have lots of stuff in the fdroidserver directory, but the most
grab a copy of the data used by the main F-Droid repository:
@example
-git clone git://gitorious.org/f-droid/fdroiddata.git
+git clone https://gitlab.com/fdroid/fdroiddata.git
@end example
Regardless of the intended usage of the tools, you will always need to set
up some basic configuration details. This is done by creating a file called
@code{config.py} in the data directory. You should do this by copying the
-example file (@code{config.sample.py}) from the fdroidserver project to your
-data directory and then editing according to the instructions within.
+example file (@code{./examples/config.py}) from the fdroidserver project to
+your data directory and then editing according to the instructions within.
Once configured in this way, all the functionality of the tools is accessed
by running the @code{fdroid} command. Run it on its own to get a list of the
@item
Make a directory for your repository. This is the directory from which you
will do all the work with your repository. Create a config file there, called
-@code{config.py}, by copying the @code{config.sample.py} from the server
+@code{config.py}, by copying @code{./examples/config.py} from the server
project and editing it.
@item
Within that, make a directory called @code{repo} and put APK files in it.
unique identifier for that package.
See the Metadata chapter for details of what goes in the metadata file. All
-fields are relevant for binary APKs, EXCEPT for 'Build Version' entries, which
+fields are relevant for binary APKs, EXCEPT for @code{Build:} entries, which
should be omitted.
@enumerate
@item
-Include Build Version entries in the metadata files.
+Include Build entries in the metadata files.
@item
Run @code{fdroid build} to build any applications that are not already built.
@item
@code{--force} to force a build of a Disabled application, where normally it
would be completely ignored. Similarly a version that was found to contain
ELFs or known non-free libraries can be forced to build. See also —
-scanignore= and scandelete= in the Build Version section.
+@code{scanignore=} and @code{scandelete=} in the @code{Build:} section.
If the build was unsuccessful, you can find out why by looking at the output
in the logs/ directory. If that isn't illuminating, try building the app the
@menu
* Categories::
* License::
+* Auto Name::
* Name::
* Provides::
-* Auto Name::
* Web Site::
* Source Code::
* Issue Tracker::
* Maintainer Notes::
* Repo Type::
* Repo::
-* Build Version::
+* Build::
* AntiFeatures::
* Disabled::
* Requires Root::
* Archive Policy::
* Update Check Mode::
+* Update Check Ignore::
* Vercode Operation::
+* Update Check Name::
* Update Check Data::
* Auto Update Mode::
* Current Version::
@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 32 characters
-will ensure it fits even on the smallest screens.
+one line on the list of the F-Droid client, keeping it to within 50 characters
+will ensure it fits most screens.
@node Description
@section Description
and you want to use this srclib, then you have to set Repo to
@code{FooBar}.
-@node Build Version
-@section Build Version
+@node Build
+@section Build
-@cindex Build Version
+@cindex Build
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:
-@samp{Build Version:0.12,3,651696a49be2cd7db5ce6a2fa8185e31f9a20035}
+@samp{Build:1.2,12}
-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.
+The above specifies to build version 1.2, which has a version code of 12.
+The @code{commit=} parameter specifies the tag, commit or revision number from
+which to build it in the source repository. It is the only mandatory flag,
+which in this case could for example be @code{commit=v1.2}.
In addition to the three, always required, parameters described above,
further parameters can be added (in name=value format) to apply further
Normally this directory is changed to before building,
@item submodules=yes
-Use if the project (git only) has submodules - causes git submodule
-init and update to be executed after the source is cloned.
+Use if the project (git only) has submodules - causes @code{git submodule
+update --init --recursive} to be executed after the source is cloned.
+Submodules are reset and cleaned like the main app repository itself before
+each build.
@item init=xxxx
As for 'prebuild', but runs on the source code BEFORE any other processing
try enabling this option.
@item 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 @code{init=rm -rf bin/}; otherwise this
-parameter should do the trick.
-
-Please note that gradle builds should be using compilesdk=.
-
-@item 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.
-
-@item update=xxx
-By default, 'android update project' is used to generate or update the
+Specifies a particular SDK target for compilation, overriding the value
+defined in the code by upstream. This has different effects depending on what
+build system used — this flag currently affects Ant, Maven and Gradle projects
+only. Note that this does not change the target SDK in the
+AndroidManifest.xml, which determines the level of features that can be
+included in the build.
+
+In the case of an Ant project, it modifies project.properties of the app and
+possibly sub-projects. 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.
+
+@item update=<auto/dirs>
+By default, 'android update' is used in Ant builds to generate or update the
project and all its referenced projects. Specifying update=no bypasses that.
+Note that this is useless in builds that don't use Ant.
-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 '@code{auto}', which uses the paths used in the
-project.properties file to find out what project paths to update.
+Default value is '@code{auto}', which recursively uses the paths in
+project.properties to find all the subprojects 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 '@code{subdir}' parameter).
+Otherwise, the value can be a comma-separated list of directories in which to
+run 'android update' relative to the application directory.
@item encoding=xxxx
Adds a java.encoding property to local.properties with the given
If specified, the package version code in the AndroidManifest.xml is
replaced with the version code for the build. See also forceversion.
-@item rm=<relpath1;relpath2;...>
+@item rm=<path1>[,<path2>,...]
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 ';'.
+Multiple files/directories can be specified by separating them with ','.
Directories will be recursively deleted.
-@item 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.
-
-@item fixapos=yes
-Like fixtrans, but deals with an even older issue relating to
-'unescaped apostrophes' in translation strings.
-
-@item extlibs=a;b;c
-Specifies a list of external libraries (jar files) from the
+@item extlibs=<lib1>[,<lib2>,...]
+Comma-separated list of external libraries (jar files) from the
@code{build/extlib} library, which will be placed in the @code{libs} directory
-of the project. Separate items with semicolons.
+of the project.
+
+@item srclibs=[n:]a@@r,[n:]b@@r1,...
+Comma-separated list of source libraries or Android projects. Each item is of
+the form name@@rev where name is the predefined source library name and rev is
+the revision or tag to use in the respective source control.
-@item 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.
+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
+legacy practice @code{prebuild=echo "android.library.reference.1=$$somelib$$"
+>> project.properties}.
Each srclib has a metadata file under srclibs/ in the repository directory,
and the source code is stored in build/srclib/.
directory, but it could need tweaking if you've changed into another directory.
@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 without the extension. Each of
-these patches is applied to the code in turn.
+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.
@item 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.
+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'
+Note that nothing should be built 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 or produce binaries, use 'build'
instead.
You can use $$name$$ to substitute the path to a referenced srclib - see
the @code{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.
+android SDK and NDK directories, and Maven 3 executable respectively e.g.
for when you need to run @code{android update project} explicitly.
-@item scanignore=path1;path2;...
-Enables one or more files/paths to be exlcuded from the scan process.
+@item scanignore=<path1>[,<path2>,...]
+Enables one or more files/paths to be excluded 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.
-@item scandelete=path1;path2;...
+@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.
@item 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.
+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,
+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.
+android SDK and NDK directories, and Maven 3 executable respectively.
@item 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
+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 @code{jni} directory present.
-If the native code is being built by other means, you can specify
-@code{no} here to avoid that. However, if the native code is actually
-not required, remove the directory instead (using @code{prebuild} for
-example).
-
-@item 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>@..'.
+If the native code is being built by other means like a Gradle task, you
+can specify @code{no} here to avoid that. However, if the native code is
+actually not required or used, remove the directory instead (using
+@code{rm=jni} for example). Using @code{buildjni=no} when the jni code
+isn't used nor built will result in an error saying that native
+libraries were expected in the resulting package.
-@item maven=yes[@@<dir>]
-Build with maven instead of ant. Like gradle, an extra @@<dir> tells f-droid
-to run maven inside that relative subdirectory.
+@item gradle=<flavour1>[,<flavour2>,...]
+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.
-@item preassemble=<task1> <task2>
-Space-separated list of gradle tasks to be run before the assemble task
-in a gradle project build.
+@item maven=yes[@@<dir>]
+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.
-@item 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.
+@item preassemble=<task1>[,<task2>,...]
+List of Gradle tasks to be run before the assemble task in a Gradle project
+build.
-@item antcommand=xxx
-Specify an alternate ant command (target) instead of the default
+@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.
+@item output=path/to/output.apk
+To be used when app is built with a tool other than the ones natively
+supported, like GNU Make. The given path will be where the build= set of
+commands should produce the final unsigned release apk.
+
@item 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
a paragraph in the description to the conditions on which root may be
asked for and the reason for it.
+@node Archive Policy
+@section Archive Policy
+
+@cindex Archive Policy
+
+This determines the policy for moving old versions of an app to the archive
+repo, if one is configured. The configuration sets a default maximum number
+of versions kept in the main repo, after which older ones are moved to the
+archive. This app-specific policy setting can override that.
+
+Currently the only supported format is "n versions", where n is the number
+of versions to keep.
+
@node Update Check Mode
@section Update Check Mode
of doing so. Updates should be checked for manually. Use this, for example,
when deploying betas or patched versions; when builds are done in a directory
different to where the AndroidManifest.xml is; if the developers use the
-gradle build system and store version info in a separate file; if the
+Gradle build system and store version info in a separate file; if the
developers make a new branch for each release and don't make tags; or if you've
changed the package name or version code logic.
@item
Despite these caveats, it is the often the favourite update check mode.
It currently only works for git, hg, bzr and git-svn repositories. In the case
-of the latter, the repo URL must encode the path to the trunk and tags or else
-no tags will be found.
+of the latter, the repo URL must contain the path to the trunk and tags or
+else no tags will be found.
+
+Optionally append a regex pattern at the end - separated with a space - to
+only check the tags matching said pattern. Useful when apps tag non-release
+versions such as X.X-alpha, so you can filter them out with something like
+@code{.*[0-9]$} which requires tag names to end with a digit.
@item
@code{HTTP} - HTTP requests are used to determine the current version code and
version name. This is controlled by the @code{Update Check Data} field, which
again, rather than retrieving a different one.
@end itemize
-@node Update Check Data
-@section Update Check Data
-
-@cindex Update Check Data
-
-Used in conjunction with @code{Update Check Mode} for certain modes.
-
@node Vercode Operation
@section Vercode Operation
string will be passed to python's @code{eval} function.
Especially useful with apps that we want to compile for different ABIs, but
-whose vercodes don't always have trailing zeros. With @code{Vercode Operation}
-set at something like @code{%c*10 + 4}, we will be able to track updates and
-build three different versions of every upstream version.
+whose vercodes don't always have trailing zeros. For example, with
+@code{Vercode Operation} set at something like @code{%c*10 + 4}, we will be
+able to track updates and build up to four different versions of every
+upstream version.
-@node Archive Policy
-@section Archive Policy
+@node Update Check Ignore
+@section Update Check Ignore
-@cindex Archive Policy
+@cindex Update Check Ignore
-This determines the policy for moving old versions of an app to the archive
-repo, if one is configured. The configuration sets a default maximum number
-of versions kept in the main repo, after which older ones are moved to the
-archive. This app-specific policy setting can override that.
+When checking for updates (via @code{Update Check Mode}) this can be used to
+specify a regex which, if matched against the version name, causes that version
+to be ignored. For example, 'beta' could be specified to ignore version names
+that include that text.
-Currently the only supported format is "n versions", where n is the number
-of versions to keep.
+@node Update Check Name
+@section Update Check Name
+
+@cindex Update Check Name
+
+When checking for updates (via @code{Update Check Mode}) this can be used to
+specify the package name to search for. Useful when apps have a static package
+name but change it programmatically in some app flavors, by e.g. appending
+".open" or ".free" at the end of the package name.
+
+@node Update Check Data
+@section Update Check Data
+
+@cindex Update Check Data
+
+Used in conjunction with @code{Update Check Mode} for certain modes.
@node Auto Update Mode
@section Auto Update Mode
@enumerate
@item
-Use custom ant build steps to execute virtually anything as the user doing
+Use custom Ant build steps to execute virtually anything as the user doing
the build.
@item
Access the keystore.
With this base box available, you should then create @code{makebs.config.py},
-using @code{makebs.config.sample.py} as a reference - look at the settings and
+using @code{./examples/makebs.config.py} as a reference - look at the settings and
documentation there to decide if any need changing to suit your environment.
There is a path for retrieving the base box if it doesn't exist, and an apt
proxy definition, both of which may need customising for your environment.
~ianmdlvl / fdroidserver.git / blobdiff