From ea985430b03b53af3d102c530b81178eaa63ca66 Mon Sep 17 00:00:00 2001 From: Ciaran Gultnieks Date: Thu, 23 Feb 2012 14:32:35 +0000 Subject: [PATCH] Move docs to docs directory, and generate HTML --- README | 251 +------ fdl.texi => docs/fdl.texi | 0 docs/fdroid.html | 1214 +++++++++++++++++++++++++++++++ fdroid.texi => docs/fdroid.texi | 0 docs/makehtml.sh | 2 + 5 files changed, 1217 insertions(+), 250 deletions(-) rename fdl.texi => docs/fdl.texi (100%) create mode 100644 docs/fdroid.html rename fdroid.texi => docs/fdroid.texi (100%) create mode 100755 docs/makehtml.sh diff --git a/README b/README index a2f66f06..d56e5dc3 100644 --- a/README +++ b/README @@ -1,252 +1,3 @@ -=Basic instructions= -1. Copy config.sample.py to config.py and edit the path within accordingly - to point to the Android tools -2. Make a repo directory and put APK files in it -3. Run update.py -4. If it reports that any metadata files are missing, you can create them - in the metadata directory and run it again. -5. To ease creation of metadata files, run update.py with the -c option. It - will create 'skeleton' metadata files that are missing, and you can then - just edit them and fill in the details. -6. Then, if you've changed things, run update.py again. -7. Running update.py adds an Icons directory into the repo directory, and - also creates the repository index (index.xml). -8. Transfer the repo directory to the appropriate http server. The script - in upload.sh is an example of how to do this. +For documentation, please see the docs directory. -=Build System Requirements= - -To be able to auto-build packages, you're going to need: - -*GNU/Linux -*Python -*Android SDK with all SDK platforms (for all API versions) and tools -*Android NDK -*Ant -*Ant Contrib Tasks (Debian package ant-contrib) -*Maven (Debian package maven2) -*JavaCC (Debian package javacc) -*JDK (Debian package openjdk-6-jdk and openjdk-7-jdk) -*VCS clients: svn, git, hg, bzr -*A keystore for holding release keys. (Safe, secure and well backed up!) - -You then need to create a config.py (copy config.sample.py and follow the -instructions) to specify the locations of some of these things. - -==Building Apps== - -Run - - ./build.py -p goo.TeaTimer - -to test building apk files. They will be put in the repo directory. - -=MetaData= - -Information used by update.py to compile the public index comes from two -sources, 1) the APK files in the repo directory, and 2) the metadata files -in the metadata directory. - -The metadata files are simple, easy to edit text files, always named as the -application's package ID with '.txt' appended. Within the file, the following -fields are recognised: - -==License== - -The license for the application. - -Common values: GPLv2, GPLv2+, GPLv3, Apache2, MIT, BSD - -==Name== - -The name of the application. Normally, this field should not be present since the -application's correct name is retrieved from the APK file. However, in a situation -where an APK contains a bad or missing application name, it can be overridden -using this. - -==Web Site== - -The URL for the application's web site. - -==Source Code== - -The URL to view or obtain the application's source code. This should be -something human-friendly. Machine-readable source-code is covered in the -'Repo' field. - -==Issue Tracker== - -The URL for the application's issue tracker. Optional, since not all -applications have one. - -==Donate== - -The URL to donate to the project. This could be the project's donate page -if it has one, or perhaps even a direct PayPal link. - -==Summary== - -A brief summary of what the application is. - -==Description== - -A full description of the application. This can span multiple lines, and is -terminated by a line containing a single '.'. - -==Repo Type== - -The type of repository - for automatic building from source. If this is not -specified, automatic building is disabled for this application. Possible -values are: - - git, git-svn, svn, hg, bzr - -The git-svn option connects to an SVN repository, and you specify the URL in -exactly the same way, but git is used as a back-end. This is preferable for -performance reasons. - -==Repo== - -The repository location. Usually a git: or svn: URL. - -For a Subversion repo that requires authentication, you can precede the repo -URL with username:password@ and those parameters will be passed as --username -and --password to the SVN checkout command. (Doesn't work for git-svn). - -==Build Version== - -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. - -If the commit version starts with a !, that version is not built. Instead, -everything after the ! is used as a reason why it can't be built. 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). - -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: - - subdir= - Specifies to build from a subdirectory of the checked out - source code. Normally this directory is changed to before - building. - bindir= - 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.. - 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= - Specifies a particular SDK target, when the source doesn't. - 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. - rm= - Specifies the relative path of file to delete before the - build is done. The path is relative to the base of the - build directory - i.e. the directory that contains - AndroidManifest.xml. - antcommand=xxx - Specify an alternate ant command (target) instead of the - default 'release'. - forceversion=yes - If specified, the package version in AndroidManifest.xml is - replaced with the version number for the build as specified - in recipe. Useful for cases when upstream repo missed to - update it for specific tag, or to build an arbitrary revision. - forcevercode=yes - If specified, the package vercode in the AndroidManifest.xml is - replaced with the version code for the build. See also - forceversion. - update=xxx By default, 'android update project' is used to generate or - update the build.xml file. 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. - initfun=yes Enables a selection of mad hacks to make com.funambol.android - build. Probably not useful for any other application. - buildjni=yes Enables building of native code via the ndk-build script - before doing the main ant build. - submodules=yes Use if the project (git only) has submodules - causes git - submodule init and update to be executed after the source is - cloned. - 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. - 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. - init=xxxx As for 'prebuild', but runs on the source code BEFORE any - other processing takes place. - 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. - 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. - maven=yes Build with maven instead of ant - 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. - 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 (kept up to date using - version control) from a predefined set. 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 in source control to use. You can then also use - $$name$$ in the prebuild command to substitute the relative - path to the library directory. - -Another example, using extra parameters: - - Build Version:1.09.03,10903,45,subdir=Timeriffic,oldsdkloc=yes - -==AntiFeatures== - -This is optional - if present, it contains a comma-separated list of any of -the following values, describing an AntiFeature the application has: - - "Ads" - the application contains advertising - "Tracking" - the application tracks and reports your activity to somewhere - "NonFreeNet" - the application promotes a non-Free network service - "NonFreeAdd" - the application promotes non-Free add-ons - "NonFreeDep" - the application depends on another non-Free application (e.g. Google Maps) - -==Disabled== - -If this field is present, the application does not get put into the public -index. This allows metadata to be retained while an application is temporarily -disabled from being published. The value should be a description of why the -application is disabled. - -==Requires Root== - -Set this optional field to "Yes" if the application requires root -privileges to be usable. This lets the client filter it out if the -user so desires. diff --git a/fdl.texi b/docs/fdl.texi similarity index 100% rename from fdl.texi rename to docs/fdl.texi diff --git a/docs/fdroid.html b/docs/fdroid.html new file mode 100644 index 00000000..670722f5 --- /dev/null +++ b/docs/fdroid.html @@ -0,0 +1,1214 @@ + + +F-Droid Server Manual + + + + + + + + + + +

F-Droid Server Manual

+
+

Table of Contents

+ +
+ + + +
+ +

+Next: , +Up: (dir) + +
+ +

F-Droid Server

+ +

This manual is for the F-Droid repository server tools. + +

Copyright © 2010, 2011, 2012 Ciaran Gultnieks +Copyright © 2011 Henrik Tunedal, Michael Haas, John Sullivan + +

+Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 +or any later version published by the Free Software Foundation; +with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. +A copy of the license is included in the section entitled "GNU +Free Documentation License". +
+ + + +
+ +

+Next: , +Previous: Top, +Up: Top + +
+ +

1 Overview

+ +

The F-Droid server tools provide various scripts, tools and data that are used +to maintain the main F-Droid application repository. You can use these same +tools to create your own additional or alternative repository for publishing, +or to assist in creating, testing and submitting metadata to the main +repository. + +

+ +

+Next: , +Previous: Overview, +Up: Top + +
+ +

2 System Requirements

+ +

+The system requirements for using the tools will vary depending on your +intended usage. At the very least, you'll need: + +

    +
  • GNU/Linux +
  • Python 2.x +
  • The Android SDK +
+ +

If you intend to build applications from source you'll also need most, if not +all, of the following: + +

    +
  • All available SDK platforms and tools installed in the Android SDK, but *not* +the proprietary components. +
  • The Android NDK +
  • Ant +
  • Ant Contrib Tasks (Debian package ant-contrib) +
  • Maven (Debian package maven2) +
  • JavaCC (Debian package javacc) +
  • JDK (Debian package openjdk-6-jdk) +
  • VCS clients: svn, git, hg, bzr +
  • A keystore for holding release keys. (Safe, secure and well backed up!) +
+ +

If you intend to use the 'Build Server' system, for secure and clean builds +(highly recommended), you will also need: + +

    +
  • VirtualBox (debian package virtualbox-ose) +
  • Ruby +
  • Vagrant and Vagrant-snap +
  • Paramiko (debian package python-paramiko) +
+ +
+ +

+Next: , +Previous: System Requirements, +Up: Top + +
+ +

3 Setup

+ +

+Because the tools and data will always change rapidly, you will almost +certainly want to work from a git clone of the tools, which are designed to +work in this way, with all associated data in a pre-defined directory +structure below the main one. To get started: + +

     git clone git://gitorious.org/f-droid/fdroidserver.git
+     cd fdroidserver
+
+

You will now be in the root directory of the tools. All the tasks associated +with managing the repository and data are done from here. + +

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 +config.py which you should do by copying from config.sample.py +and then editing according to the instructions within. + +

+ +

+Next: , +Previous: Setup, +Up: Top + +
+ +

4 Simple Binary Repository

+ +

+If you want to maintain a simple repository hosting only binary APKs obtained +and compiled elsewhere, the process is quite simple: + +

    +
  1. Make a repo directory and put APK files in it. +
  2. Run update.py. +
  3. If it reports that any metadata files are missing, you can create them +in the metadata directory and run it again. +
  4. To ease creation of metadata files, run update.py with the -c +option. It will create 'skeleton' metadata files that are missing, and you can +then just edit them and fill in the details. +
  5. Then, if you've changed things, run update.py again. +
  6. Running update.py adds an Icons directory into the repo directory, and +also creates the repository index (index.xml, and also index.jar if you've +configured the system to use a signed index). +
+ +

Following the above process will result in a repo directory, which you +simply need to push to any HTTP (or preferably HTTPS) server to make it +accessible. + +

While some information about the applications (and versions thereof) is +retrieved directly from the APK files, most comes from the corresponding file +in the metadata directory. The metadata file covering ALL versions of a +particular application is named package.id.txt where package.id is the +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 +should be omitted. + +

+ +

+Next: , +Previous: Simple Binary Repository, +Up: Top + +
+ +

5 Building Applications

+ +

Instead of (or as well as) including binary APKs from external sources in a +repository, you can build them directly from the source code. + +

Using this method, it is is possible to verify that the application builds +correctly, corresponds to the source code, and contains only free software. +Unforunately, in the Android world, it seems to be very common for an +application supplied as a binary APK to present itself as Free Software +when in fact some or all of the following are true: + +

    +
  1. The source code (either for a particular version, or even all versions!) is +unavailable or incomplete. +
  2. The source code is not capable of producing the actual binary supplied. +
  3. The 'source code' contains binary files of unknown origin, or with proprietary +licenses. +
+ +

For this reason, source-built applications are the preferred method for the +main F-Droid repository, although occasionally for technical or historical +reasons, exceptions are made to this policy. + +

When building applications from source, it should be noted that you will be +signing them (all APK files must be signed to be installable on Android) with +your own key. When an application is already installed on a device, it is not +possible to upgrade it in place to a new version signed with a different key +without first uninstalling the original. This may present an inconvenience to +users, as the process of uninstalling loses any data associated with the +previous installation. + +

The process for managing a repository for built-from-source applications is +very similar to that described in the Simple Binary Repository chapter, +except now you need to: + +

    +
  1. Include Build Version entries in the metadata files. +
  2. Run build.py to build any applications that are not already built. +
  3. Run publish.py to finalise packaging and sign any APKs that have been built. +
+ +

To build a single version of a single application, you could run the +following: + +

     ./build.py -p org.fdroid.fdroid -c 16
+
+

This attempts to build version code 16 (which is version 0.25) of the F-Droid +client. If the build was succesful, two files will have been placed in the +unsigned directory: + +

     org.fdroid.fdroid_16.apk
+     org.fdroid.fdroid_16_src.tar.gz
+
+

The first is the (unsigned) APK. You could sign this with a debug key and push +it direct to your device or an emulator for testing. The second is a source +tarball containing exactly the source that was used to generate the binary. + +

If you were intending to publish these files, you could then run: + +

     ./publish.py
+
+

The source tarball would move to the repo directory (which is the +directory you would push to your web server). A signed and zip-aligned version +of the APK would also appear there, and both files would be removed from the +unsigned directory. + +

+ +

+Next: , +Previous: Building Applications, +Up: Top + +
+ +

6 Metadata

+ +

+Information used by update.py to compile the public index comes from two +sources, 1) the APK files in the repo directory, and 2) the metadata files +in the metadata directory. + +

The metadata files are simple, easy to edit text files, always named as the +application's package ID with '.txt' appended. The following sections describe +the fields recognised within the file. + +

+ +
+ +

+Next: , +Up: Metadata + +
+ +

6.1 License

+ +

+The license for the application. + +

Common values: + +

    +
  • ‘GPLv2’ + +
  • ‘GPLv2+’ + +
  • ‘GPLv3’ + +
  • ‘Apache2’ + +
  • ‘MIT’ + +
  • ‘BSD’ + +
+ +
+ +

+Next: , +Previous: License, +Up: Metadata + +
+ +

6.2 Name

+ +

+The name of the application. Normally, this field should not be present since the +application's correct name is retrieved from the APK file. However, in a situation +where an APK contains a bad or missing application name, it can be overridden +using this. + +

+ +

+Next: , +Previous: Name, +Up: Metadata + +
+ +

6.3 Web Site

+ +

+The URL for the application's web site. + +

+ +

+Next: , +Previous: Web Site, +Up: Metadata + +
+ +

6.4 Source Code

+ +

+The URL to view or obtain the application's source code. This should be +something human-friendly. Machine-readable source-code is covered in the +'Repo' field. + +

+ +

+Next: , +Previous: Source Code, +Up: Metadata + +
+ +

6.5 Issue Tracker

+ +

+The URL for the application's issue tracker. Optional, since not all +applications have one. + +

+ +

+Next: , +Previous: Issue Tracker, +Up: Metadata + +
+ +

6.6 Donate

+ +

+The URL to donate to the project. This could be the project's donate page +if it has one, or perhaps even a direct PayPal link. + +

+ +

+Next: , +Previous: Donate, +Up: Metadata + +
+ +

6.7 Summary

+ +

+A brief summary of what the application is. + +

+ +

+Next: , +Previous: Summary, +Up: Metadata + +
+ +

6.8 Description

+ +

+A full description of the application. This can span multiple lines, and is +terminated by a line containing a single '.'. + +

+ +

+Next: , +Previous: Description, +Up: Metadata + +
+ +

6.9 Repo Type

+ +

+The type of repository - for automatic building from source. If this is not +specified, automatic building is disabled for this application. Possible +values are: + +

    +
  • ‘git’ +
  • ‘svn’ +
  • ‘git-svn’ +
  • ‘hg’ +
  • ‘bzr’ +
+
+ +

+Next: , +Previous: Repo Type, +Up: Metadata + +
+ +

6.10 Repo

+ +

+The repository location. Usually a git: or svn: URL, for example. + +

The git-svn option connects to an SVN repository, and you specify the URL in +exactly the same way, but git is used as a back-end. This is preferable for +performance reasons, and also because a local copy of the entire history is +available in case the upstream repository disappears. (It happens!) + +

For a Subversion repo that requires authentication, you can precede the repo +URL with username:password and those parameters will be passed as --username +and --password to the SVN checkout command. (This works only for +plain svn and not for git-svn - one of the very few cases where using svn is +advisable). + +

+ +

+Next: , +Previous: Repo, +Up: Metadata + +
+ +

6.11 Build Version

+ +

+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. + +

If the commit version starts with a !, that version is not built. Instead, +everything after the ! is used as a reason why it can't be built. 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). + +

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: + +

+
subdir=<path>
Specifies to build from a subdirectory of the checked out source code. +Normally this directory is changed to before building, + +
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. + +
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, when the source doesn't. 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. + +
rm=<relpath>
Specifies the relative path of file to delete before the build is +done. The path is relative to the base of the build directory - i.e. +the directory that contains AndroidManifest.xml. + +
antcommand=xxx
Specify an alternate ant command (target) instead of the default +'release'. + +
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, or to build an arbitrary revision. + +

forcevercode=yes
If specified, the package version code in the AndroidManifest.xml is +replaced with the version code for the build. See also forceversion. + +
update=xxx
By default, 'android update project' is used to generate or update the +build.xml file. 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. + +

initfun=yes
Enables a selection of mad hacks to make com.funambol.android build. +Probably not useful for any other application. + +
buildjni=yes
Enables building of native code via the ndk-build script before doing +the main ant build. + +
submodules=yes
Use if the project (git only) has submodules - causes git submodule +init and update to be executed after the source is cloned. + +
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. + +
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. + +
init=xxxx
As for 'prebuild', but runs on the source code BEFORE any other processing +takes place. + +
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. + +
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. + +
maven=yes
Build with maven instead of ant + +
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. + +
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 (kept up to date using version control) +from a predefined set. 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 in source control to use. You can then also use $$name$$ in the +prebuild command to substitute the relative path to the library directory. + +

The available source libraries are current hard-coded in common.py. This will +later be data-driven. + +

+ +

Another example, using extra parameters: + +

‘Build Version:1.09.03,10903,45,subdir=Timeriffic,oldsdkloc=yes’ + +

+ +

+Next: , +Previous: Build Version, +Up: Metadata + +
+ +

6.12 AntiFeatures

+ +

+This is optional - if present, it contains a comma-separated list of any of +the following values, describing an AntiFeature the application has: + +

    +
  • ‘Ads’ - the application contains advertising. + +
  • ‘Tracking’ - the application tracks and reports your activity to +somewhere without your consent. + +
  • ‘NonFreeNet’ - the application promotes a non-Free network service. + +
  • ‘NonFreeAdd’ - the application promotes non-Free add-ons. + +
  • ‘NonFreeDep’ - the application depends on a non-Free application (e.g. +Google Maps) - i.e. it requires it to be installed on the device, but does not +include it. + +
+ +
+ +

+Next: , +Previous: AntiFeatures, +Up: Metadata + +
+ +

6.13 Disabled

+ +

+If this field is present, the application does not get put into the public +index. This allows metadata to be retained while an application is temporarily +disabled from being published. The value should be a description of why the +application is disabled. + +

+ +

+Previous: Disabled, +Up: Metadata + +
+ +

6.14 Requires Root

+ +

+Set this optional field to "Yes" if the application requires root +privileges to be usable. This lets the client filter it out if the +user so desires. + +

+ +

+Next: , +Previous: Metadata, +Up: Top + +
+ +

Appendix A GNU Free Documentation License

+ + +
Version 1.3, 3 November 2008
+ + + +
     Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
+     http://fsf.org/
+     
+     Everyone is permitted to copy and distribute verbatim copies
+     of this license document, but changing it is not allowed.
+
+
    +
  1. PREAMBLE + +

    The purpose of this License is to make a manual, textbook, or other +functional and useful document free in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. + +

    This License is a kind of “copyleft”, which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +

    We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + +

  2. APPLICABILITY AND DEFINITIONS + +

    This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The “Document”, below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as “you”. You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. + +

    A “Modified Version” of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +

    A “Secondary Section” is a named appendix or a front-matter section +of the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall +subject (or to related matters) and contains nothing that could fall +directly within that overall subject. (Thus, if the Document is in +part a textbook of mathematics, a Secondary Section may not explain +any mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +

    The “Invariant Sections” are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. + +

    The “Cover Texts” are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. + +

    A “Transparent” copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not “Transparent” is called “Opaque”. + +

    Examples of suitable formats for Transparent copies include plain +ascii without markup, Texinfo input format, LaTeX input +format, SGML or XML using a publicly available +DTD, and standard-conforming simple HTML, +PostScript or PDF designed for human modification. Examples +of transparent image formats include PNG, XCF and +JPG. Opaque formats include proprietary formats that can be +read and edited only by proprietary word processors, SGML or +XML for which the DTD and/or processing tools are +not generally available, and the machine-generated HTML, +PostScript or PDF produced by some word processors for +output purposes only. + +

    The “Title Page” means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, “Title Page” means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +

    The “publisher” means any person or entity that distributes copies +of the Document to the public. + +

    A section “Entitled XYZ” means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as “Acknowledgements”, +“Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” +of such a section when you modify the Document means that it remains a +section “Entitled XYZ” according to this definition. + +

    The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. + +

  3. VERBATIM COPYING + +

    You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +

    You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + +

  4. COPYING IN QUANTITY + +

    If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +

    If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +

    If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. + +

    It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + +

  5. MODIFICATIONS + +

    You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +

      +
    1. Use in the Title Page (and on the covers, if any) a title distinct +from that of the Document, and from those of previous versions +(which should, if there were any, be listed in the History section +of the Document). You may use the same title as a previous version +if the original publisher of that version gives permission. + +
    2. List on the Title Page, as authors, one or more persons or entities +responsible for authorship of the modifications in the Modified +Version, together with at least five of the principal authors of the +Document (all of its principal authors, if it has fewer than five), +unless they release you from this requirement. + +
    3. State on the Title page the name of the publisher of the +Modified Version, as the publisher. + +
    4. Preserve all the copyright notices of the Document. + +
    5. Add an appropriate copyright notice for your modifications +adjacent to the other copyright notices. + +
    6. Include, immediately after the copyright notices, a license notice +giving the public permission to use the Modified Version under the +terms of this License, in the form shown in the Addendum below. + +
    7. Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document's license notice. + +
    8. Include an unaltered copy of this License. + +
    9. Preserve the section Entitled “History”, Preserve its Title, and add +to it an item stating at least the title, year, new authors, and +publisher of the Modified Version as given on the Title Page. If +there is no section Entitled “History” in the Document, create one +stating the title, year, authors, and publisher of the Document as +given on its Title Page, then add an item describing the Modified +Version as stated in the previous sentence. + +
    10. Preserve the network location, if any, given in the Document for +public access to a Transparent copy of the Document, and likewise +the network locations given in the Document for previous versions +it was based on. These may be placed in the “History” section. +You may omit a network location for a work that was published at +least four years before the Document itself, or if the original +publisher of the version it refers to gives permission. + +
    11. For any section Entitled “Acknowledgements” or “Dedications”, Preserve +the Title of the section, and preserve in the section all the +substance and tone of each of the contributor acknowledgements and/or +dedications given therein. + +
    12. Preserve all the Invariant Sections of the Document, +unaltered in their text and in their titles. Section numbers +or the equivalent are not considered part of the section titles. + +
    13. Delete any section Entitled “Endorsements”. Such a section +may not be included in the Modified Version. + +
    14. Do not retitle any existing section to be Entitled “Endorsements” or +to conflict in title with any Invariant Section. + +
    15. Preserve any Warranty Disclaimers. +
    + +

    If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +

    You may add a section Entitled “Endorsements”, provided it contains +nothing but endorsements of your Modified Version by various +parties—for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +

    You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +

    The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + +

  6. COMBINING DOCUMENTS + +

    You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. + +

    The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +

    In the combination, you must combine any sections Entitled “History” +in the various original documents, forming one section Entitled +“History”; likewise combine any sections Entitled “Acknowledgements”, +and any sections Entitled “Dedications”. You must delete all +sections Entitled “Endorsements.” + +

  7. COLLECTIONS OF DOCUMENTS + +

    You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +

    You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + +

  8. AGGREGATION WITH INDEPENDENT WORKS + +

    A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an “aggregate” if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation's users beyond what the individual works permit. +When the Document is included in an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. + +

    If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document's Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. + +

  9. TRANSLATION + +

    Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. + +

    If a section in the Document is Entitled “Acknowledgements”, +“Dedications”, or “History”, the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. + +

  10. TERMINATION + +

    You may not copy, modify, sublicense, or distribute the Document +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense, or distribute it is void, and +will automatically terminate your rights under this License. + +

    However, if you cease all violation of this License, then your license +from a particular copyright holder is reinstated (a) provisionally, +unless and until the copyright holder explicitly and finally +terminates your license, and (b) permanently, if the copyright holder +fails to notify you of the violation by some reasonable means prior to +60 days after the cessation. + +

    Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. + +

    Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, receipt of a copy of some or all of the same material does +not give you any rights to use it. + +

  11. FUTURE REVISIONS OF THIS LICENSE + +

    The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +http://www.gnu.org/copyleft/. + +

    Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License “or any later version” applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. If the Document +specifies that a proxy can decide which future versions of this +License can be used, that proxy's public statement of acceptance of a +version permanently authorizes you to choose that version for the +Document. + +

  12. RELICENSING + +

    “Massive Multiauthor Collaboration Site” (or “MMC Site”) means any +World Wide Web server that publishes copyrightable works and also +provides prominent facilities for anybody to edit those works. A +public wiki that anybody can edit is an example of such a server. A +“Massive Multiauthor Collaboration” (or “MMC”) contained in the +site means any set of copyrightable works thus published on the MMC +site. + +

    “CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 +license published by Creative Commons Corporation, a not-for-profit +corporation with a principal place of business in San Francisco, +California, as well as future copyleft versions of that license +published by that same organization. + +

    “Incorporate” means to publish or republish a Document, in whole or +in part, as part of another Document. + +

    An MMC is “eligible for relicensing” if it is licensed under this +License, and if all works that were first published under this License +somewhere other than this MMC, and subsequently incorporated in whole +or in part into the MMC, (1) had no cover texts or invariant sections, +and (2) were thus incorporated prior to November 1, 2008. + +

    The operator of an MMC Site may republish an MMC contained in the site +under CC-BY-SA on the same site at any time before August 1, 2009, +provided the MMC is eligible for relicensing. + +

+ +
+ +

+Previous: GNU Free Documentation License, +Up: Top + +
+ +

Index

+ + + diff --git a/fdroid.texi b/docs/fdroid.texi similarity index 100% rename from fdroid.texi rename to docs/fdroid.texi diff --git a/docs/makehtml.sh b/docs/makehtml.sh new file mode 100755 index 00000000..9c8f7f45 --- /dev/null +++ b/docs/makehtml.sh @@ -0,0 +1,2 @@ +#!/bin/sh +makeinfo --html --no-split fdroid.texi