## About Repositories for the Hildon Application Manager

### Basic repository setup

The Hildon Application Manager ("AM") can deal with any repository
that "apt-get" can understand.  However, the AM only shows 'user'
packages to the user.  A user packages is identified by being in the
"user" section; see [here](packaging.html).

Also, when adding a new repository manually, the AM provides default
values for certain parts of a sources.list line.  You might want to
take this into account when laying out your repository so that users
have it easy when configuring it.

The distribution will default to the symbolic name of the distribution
that is installed on the device.  This symbolic name is referred to as
${dist} in the sequel.  For maemo 2.0, this is "mistral"; for maemo
3.0, it is "bora".  The component list defaults to just "user".

Thus, unless you have a specific reason to use something else, it is
probably a good idea to have repositories that can be specified as

<pre>
deb URL ${dist} user
</pre>

so that the user only has to enter URL into the "New Catalogue"
dialog.

How to actually setup a repository is explained in the [Debian
Repository
HOWTO](http://www.debian.org/doc/manuals/repository-howto/repository-howto).


### Single-click install

THIS FEATURE IS NOT SUPPORTED IN THE IT 2006 RELEASE:

When you want users to be able to browse your repositories using the
AM, you need to provide instructions to the user about how to
configure your repository.  On a fundamental level, you need to tell
them what values to put into the "New repository" dialog.

This manual task can be automated by providing a file of mime type
"application/x-install-instructions" and have the user open it with
the AM.

Files with the extension ".install" are recognized by the Internet
Tablet OS to have the mime type "application/x-install-instructions",
but you might also need to configure your web server accordingly.

Such a .install file is a text file following the GKeyfile format, as
defined by glib.  An example would look like this:

<pre>
[install]
repo_name = Foo Catalogue
repo_deb  = deb http://foo.com/maemo mistral user
</pre>

Thus, it can contain information about a repository, and opening the
file will add the repository to `/etc/apt/sources.list` if it isn't
there already.  The existence check is based on a simple string
comparison without any intelligence: if you put two spaces in the
"deb" line instead of one, the strings are considered different.  This
test might get smarter in the future.

The .install file can also contain the name of one or more packages, like so:

<pre>
[install]
repo_name = Foo Catalogue
repo_deb  = deb http://foo.com/maemo mistral user
package   = foo-app
</pre>

Opening this file will attempt to install the package named "foo-app",
after adding the specified repository if it is not already configured.
There is no guarantee, tho, that the named package will actually be
downloaded from the given repository.  If the package is available
with a later version from other repositories that are listed in
sources.list, then it will be downloaded from there.

The "repo_name" entry is optional.  If you omit it, the repository
will have no name.  The name of a repository is only used in the UI;
it has no effect on functionality.

The "repo_deb" entry is not optional.  In fact, different releases of
maemo will use different key names so that you can control what
repository to use with what maemo release.  If the expected repo_deb
variant is not found in the .install file, an error message will be
displayed to the user.

You can also put more than one repository, separating them with semicolons.
Remember that, in case you put repository names, you should put the same
number of them. A complete example, with two repositories and two packages:

<pre>
[install]
repo_name  = Foo Catalogue;Bar Catalogue
repo_deb_3 = deb http://foo.com/maemo bora user;deb http://bar.com/maemo bora user
package    = foo-app
</pre>

Here is a table of the various key names:

<pre>
maemo 2.0:  repo_deb
maemo 3.0:  repo_deb_3
</pre>

Repository names can be translated, adding new entries for corresponding
locales:

<pre>
[install]
repo_name  = Foo Catalogue;Bar Catalogue
repo_name[es_ES] = Repositorio Foo;Repositorio Bar
repo_deb_3 = deb http://foo.com/maemo bora user;deb http://bar.com/maemo bora user
package    = foo-app
</pre>

### Single-click install from temporary repositories

THIS FEATURE IS NOT SUPPORTED IN THE IT 2006 RELEASE:

You can add a special attribute to a .install file, called "temporary". If a Single
click install file includes this parameter with a true value, it means that it will 
install its packages getting them exclusively from the repositories in the file:

<pre>
[install]
temporary  = true
repo_name  = Foo Catalogue;Bar Catalogue
repo_name[es_ES] = Repositorio Foo;Repositorio Bar
repo_deb_3 = deb http://foo.com/maemo bora user;deb http://bar.com/maemo bora user
package    = foo-app
</pre>

This file will install foo-app from the foo and bar catalogues just as if
they were the only repositories present in the sources.list.

### Integration with Backup/restore tool

Hildon Application Manager maintains a file with Single-click install format
at /var/lib/hildon-application-manager/applications.install, listing all the
installed user packages and repositories. This file is used by the backup tool
to restore the installed applications.

### Install applications from a memory card

Hildon Application Manager supports installing applications when user inserts
a specially formated memory card. If the memory card has a specially formated
Single-click install file called .auto.install in its root, this file will be
run from the application manager.

This file accepts a specific variation of the Single-click install file: it can
store more than one package. The format of the entries is:
<verbatim>
package = app1;app2
</verbatim>

### Disabling repositories

The AM lets the user edit parts of the contents of
/etc/apt/sources.list.  It recognizes lines marked with "deb", "#deb"
and a few special comments (see below) and preserves everything else.
A "deb" line is the usual specification for a source of binary
packages.  A "#deb" line is the same, but disabled.  When
enabling/disabling a repository, the AM switches between the "deb" and
"#deb" marker.

There must be no space between "#" and "deb" in the "#deb" marker for
it to be recognized by the Application installer.

### Repository names

THIS FEATURE IS NOT SUPPORTED IN THE IT 2006 RELEASE.

A repository can have a name for easier identification.  Names are
stored in /etc/apt/sources.list as a comment line of the form

<pre>
#maemo:name NAME
</pre>

This declaration applies to the next following 'deb' or '#deb' line.

You can also set translations of the name for different locales. The
proper translation will be shown by the application manager. You have
to add a line like this one:

<pre>
#maemo:name:LN TRANSLATED NAME
</pre>

For example, for getting a string translated to spanish (locale es_ES)
and Galician (locale gl_ES):

<pre>
#maemo:name:es_ES Repositorio de prueba
#maemo:name:gl_ES Repositorio de proba
#maemo:name Test catalogue
</pre>

### Marking a repository as essential

A "deb" or "#deb" line in /etc/apt/sources.list can be marked as
'essential'.  The AM will refuse to change or remove such a line.

The way to mark a line as essential is to put a line of the form
"#maemo:essential" before the line.  The "#maemo:essential" marker
must be on a line of its own, with no whitespace between "#" and
"maemo:essential".  The marker does not have to immediately precede
the "deb" or "#deb" line.

### Setting up a repository with certified packages

The AM can recognize certain parts of repositories as 'certified'.
Packages coming from those parts are installed without showing the big
fat warning dialog to the user.  (But that is the only difference
between certified parts and non-certified ones.)

The way to configure such a certified part is to specify a URI prefix;
all archive files downloaded from a location with that prefix are
considered certified if the corresponding Release file has been signed
and successfully verified.

The Release file can be signed by _any_ key known to apt to be
accepted for a certified part.  This is acceptable since only
known-good public keys are factory-configured and if the attacker has
enough access to the device to configure a key for his dns-spoofed
repository, he has breached the device already from our point of view.

The reason for basing the 'is-certified' test on a URI prefix instead
of on "deb" lines in sources.list, say, or (URI, Distribution,
Component) tuples is simplicity: The URI prefix test can be done very
easily, and without modifying libapt-pkg.  (It might or not might not
be a good idea to use pool/ directories for certified parts of a
repository.  It is probably simpler to not use them.)

The reason that any key is accepted when verifying the signature on
the Release file of a certified part is again simplicity and the
desire not to modify libapt-pkg at this point.  As far as I can see,
libapt-pkg does not remember which keys succeeded in verifying the
signature.  This could be improved in the future.

The list of URI prefixes of certified repository parts is contained in
the file /etc/hildon-application-manager/certified.list.  It consists
of lines of the forms

<pre>
uri-prefix URI-PREFIX
</pre>

where URI-PREFIX must not contain whitespace and must match the URI of
a downloaded package literally (i.e., no %xx escape expansion is done,
etc).  Everything after and including the first '#' in a line is
ignored.  Blank lines are allowed, of course.


