@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
* 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
@item target=<target>
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
+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
+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=xxx
-By default, 'android update project' is used to generate or update the
+@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 recursively uses the paths in
+project.properties to find all the subprojects to update.
-Default value is '@code{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 '@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;
-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.
+@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.
-For ant projects, you can optionally append a number with a colon at the
+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}.
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 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 maven=yes[@@<dir>]
-Build with maven instead of ant. Like gradle, an extra @@<dir> tells f-droid
-to run maven inside that relative subdirectory.
+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 preassemble=<task1> <task2>
-Space-separated list of gradle tasks to be run before the assemble task
-in a gradle project build.
+@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
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
able to track updates and build up to four different versions of every
upstream version.
+@node Update Check Ignore
+@section Update Check Ignore
+
+@cindex Update Check Ignore
+
+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.
+
+@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
@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