mirror of
https://gitlab.com/fdroid/fdroidserver.git
synced 2024-09-17 10:40:12 +02:00
Some more work on the documentation
This commit is contained in:
parent
c43e3dae71
commit
20b30c64f7
258
fdroid.texi
258
fdroid.texi
@ -7,7 +7,7 @@
|
|||||||
@copying
|
@copying
|
||||||
This manual is for the F-Droid repository server tools.
|
This manual is for the F-Droid repository server tools.
|
||||||
|
|
||||||
Copyright @copyright{} 2010, 2011 Ciaran Gultnieks
|
Copyright @copyright{} 2010, 2011, 2012 Ciaran Gultnieks
|
||||||
Copyright @copyright{} 2011 Henrik Tunedal, Michael Haas, John Sullivan
|
Copyright @copyright{} 2011 Henrik Tunedal, Michael Haas, John Sullivan
|
||||||
|
|
||||||
@quotation
|
@quotation
|
||||||
@ -39,100 +39,198 @@ Free Documentation License".
|
|||||||
@end ifnottex
|
@end ifnottex
|
||||||
|
|
||||||
@menu
|
@menu
|
||||||
* Basic instructions::
|
* Overview::
|
||||||
* Build System::
|
* System Requirements::
|
||||||
* MetaData::
|
* Setup::
|
||||||
|
* Simple Binary Repository::
|
||||||
|
* Building Applications::
|
||||||
|
* Metadata::
|
||||||
* GNU Free Documentation License::
|
* GNU Free Documentation License::
|
||||||
* Index::
|
* Index::
|
||||||
@end menu
|
@end menu
|
||||||
|
|
||||||
@node Basic instructions
|
@node Overview
|
||||||
@chapter Basic instructions
|
@chapter 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.
|
||||||
|
|
||||||
|
|
||||||
|
@node System Requirements
|
||||||
|
@chapter System Requirements
|
||||||
|
|
||||||
@cindex instructions, basic
|
|
||||||
@cindex installation
|
@cindex installation
|
||||||
|
|
||||||
|
The system requirements for using the tools will vary depending on your
|
||||||
@enumerate
|
intended usage. At the very least, you'll need:
|
||||||
|
|
||||||
@item
|
|
||||||
Copy config.sample.py to config.py and edit the path within accordingly
|
|
||||||
to point to the Android tools
|
|
||||||
|
|
||||||
@item
|
|
||||||
Make a repo directory and put APK files in it
|
|
||||||
|
|
||||||
@item
|
|
||||||
Run update.py
|
|
||||||
|
|
||||||
@item
|
|
||||||
If it reports that any metadata files are missing, you can create them
|
|
||||||
in the metadata directory and run it again.
|
|
||||||
|
|
||||||
@item
|
|
||||||
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.
|
|
||||||
|
|
||||||
@item
|
|
||||||
Then, if you've changed things, run update.py again.
|
|
||||||
|
|
||||||
@item
|
|
||||||
Running update.py adds an Icons directory into the repo directory, and
|
|
||||||
also creates the repository index (index.xml).
|
|
||||||
|
|
||||||
@item
|
|
||||||
Transfer the repo directory to the appropriate http server. The script
|
|
||||||
in upload.sh is an example of how to do this.
|
|
||||||
|
|
||||||
@end enumerate
|
|
||||||
|
|
||||||
@node Build System
|
|
||||||
@chapter Build System Requirements
|
|
||||||
|
|
||||||
@cindex requirements, build system
|
|
||||||
|
|
||||||
To be able to auto-build packages, you're going to need:
|
|
||||||
|
|
||||||
@itemize @bullet
|
@itemize @bullet
|
||||||
|
|
||||||
@item
|
@item
|
||||||
GNU/Linux
|
GNU/Linux
|
||||||
|
|
||||||
@item
|
@item
|
||||||
Python
|
Python 2.x
|
||||||
|
|
||||||
@item
|
@item
|
||||||
A fully functional Android SDK with all SDK platforms and tools
|
The Android SDK
|
||||||
|
|
||||||
@item
|
|
||||||
The Android NDK
|
|
||||||
|
|
||||||
@item
|
|
||||||
Ant
|
|
||||||
|
|
||||||
@item
|
|
||||||
Ant Contrib Tasks (Debian package ant-contrib)
|
|
||||||
|
|
||||||
@item
|
|
||||||
Maven (Debian package maven2)
|
|
||||||
|
|
||||||
@item
|
|
||||||
JavaCC (Debian package javacc)
|
|
||||||
|
|
||||||
@item
|
|
||||||
VCS clients: svn, git, hg, bzr
|
|
||||||
|
|
||||||
@item
|
|
||||||
A keystore for holding release keys. (Safe, secure and well backed up!)
|
|
||||||
|
|
||||||
@end itemize
|
@end itemize
|
||||||
|
|
||||||
You then need to create a config.py (copy config.sample.py and follow the
|
If you intend to build applications from source you'll also need most, if not
|
||||||
instructions) to specify the locations of some of these things.
|
all, of the following:
|
||||||
|
|
||||||
@node MetaData
|
@itemize @bullet
|
||||||
@chapter MetaData
|
@item
|
||||||
|
All available SDK platforms and tools installed in the Android SDK, but *not*
|
||||||
|
the proprietary components.
|
||||||
|
@item
|
||||||
|
The Android NDK
|
||||||
|
@item
|
||||||
|
Ant
|
||||||
|
@item
|
||||||
|
Ant Contrib Tasks (Debian package ant-contrib)
|
||||||
|
@item
|
||||||
|
Maven (Debian package maven2)
|
||||||
|
@item
|
||||||
|
JavaCC (Debian package javacc)
|
||||||
|
@item
|
||||||
|
VCS clients: svn, git, hg, bzr
|
||||||
|
@item
|
||||||
|
A keystore for holding release keys. (Safe, secure and well backed up!)
|
||||||
|
@end itemize
|
||||||
|
|
||||||
|
If you intend to use the 'Build Server' system, for secure and clean builds
|
||||||
|
(highly recommended), you will also need:
|
||||||
|
|
||||||
|
@itemize @bullet
|
||||||
|
@item
|
||||||
|
VirtualBox (debian package virtualbox-ose)
|
||||||
|
@item
|
||||||
|
Ruby
|
||||||
|
@item
|
||||||
|
Vagrant and Vagrant-snap
|
||||||
|
@item
|
||||||
|
Paramiko (debian package python-paramiko)
|
||||||
|
@end itemize
|
||||||
|
|
||||||
|
|
||||||
|
@node Setup
|
||||||
|
@chapter Setup
|
||||||
|
|
||||||
|
@cindex setup, installation
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
@example
|
||||||
|
git clone git://gitorious.org/f-droid/fdroidserver.git
|
||||||
|
cd fdroidserver
|
||||||
|
@end example
|
||||||
|
|
||||||
|
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
|
||||||
|
@code{config.py} which you should do by copying from @code{config.sample.py}
|
||||||
|
and then editing according to the instructions within.
|
||||||
|
|
||||||
|
|
||||||
|
@node Simple Binary Repository
|
||||||
|
@chapter Simple Binary Repository
|
||||||
|
|
||||||
|
@cindex binary
|
||||||
|
|
||||||
|
If you want to maintain a simple repository hosting only binary APKs obtained
|
||||||
|
and compiled elsewhere, the process is quite simple:
|
||||||
|
|
||||||
|
@enumerate
|
||||||
|
@item
|
||||||
|
Make a repo directory and put APK files in it.
|
||||||
|
@item
|
||||||
|
Run @code{update.py}.
|
||||||
|
@item
|
||||||
|
If it reports that any metadata files are missing, you can create them
|
||||||
|
in the @code{metadata} directory and run it again.
|
||||||
|
@item
|
||||||
|
To ease creation of metadata files, run @code{update.py} with the @code{-c}
|
||||||
|
option. It will create 'skeleton' metadata files that are missing, and you can
|
||||||
|
then just edit them and fill in the details.
|
||||||
|
@item
|
||||||
|
Then, if you've changed things, run @code{update.py} again.
|
||||||
|
@item
|
||||||
|
Running @code{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).
|
||||||
|
@end enumerate
|
||||||
|
|
||||||
|
Following the above process will result in a @code{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 @code{metadata} directory. The metadata file covering ALL versions of a
|
||||||
|
particular application is named @code{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.
|
||||||
|
|
||||||
|
|
||||||
|
@node Building Applications
|
||||||
|
@chapter 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:
|
||||||
|
|
||||||
|
@enumerate
|
||||||
|
@item
|
||||||
|
The source code (either for a particular version, or even all versions!) is
|
||||||
|
unavailable or incomplete.
|
||||||
|
@item
|
||||||
|
The source code is not capable of producing the actual binary supplied.
|
||||||
|
@item
|
||||||
|
The 'source code' contains binary files of unknown origin, or with proprietary
|
||||||
|
licenses.
|
||||||
|
@end enumerate
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
@enumerate
|
||||||
|
@item
|
||||||
|
Include Build Version entries in the metadata files.
|
||||||
|
@item
|
||||||
|
Run build.py to build any applications that are not already built.
|
||||||
|
@item
|
||||||
|
Run publish.py to finalise packaging and sign any APKs that have been built.
|
||||||
|
@end enumerate
|
||||||
|
|
||||||
|
@node Metadata
|
||||||
|
@chapter Metadata
|
||||||
|
|
||||||
@cindex metadata
|
@cindex metadata
|
||||||
|
|
||||||
@ -142,7 +240,7 @@ in the metadata directory.
|
|||||||
|
|
||||||
The metadata files are simple, easy to edit text files, always named as the
|
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
|
application's package ID with '.txt' appended. The following sections describe
|
||||||
the fields recogognised within the file.
|
the fields recognised within the file.
|
||||||
|
|
||||||
@menu
|
@menu
|
||||||
* License::
|
* License::
|
||||||
|
Loading…
Reference in New Issue
Block a user