## 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).

### Package domains

The AM classifies the package repositories into 'domains' and upgrades
to already installed packages must (usually) come from the same domain
that the package was originally installed from.

Also, some domains are considered 'certified', and installing packages
from these domains will not show the big fat warning dialog to the
user.

Repositories are associated with domains based on the key that they
have been signed with.  Multiple repositories that have been signed
with the same key will thus automatically belong to the same domain.

Domains have a 'trust level' associated with them.  Domains with a
higher trust level are considered to dominate other domains and the AM
will allow a package to silently move from a domain to a dominating
one.

Domains are configured in /etc/hildon-application-manager/domains
using a simple XML format:

    <domains>
     <domain>
      <name>demodomain</name>
      <key>ABCDEFABCDEFABCDEFABCDEFABCDEFABCDEF</key>
      <trust-level>2</trust-level>
      <default/>
      <certified/>
     </domain>
    <domains>

The `key` element specifies the fingerprint of the key that defines
this domain.  You can list more than one key for a single domain; it
will then be association with repositories that have been signed with
any of the keys.

When a domain is marked as `default`, every installed package that
isn't already known to belong to a certain domain is put into this
domain.

There are two implicitly defined domains: `signed` and `unsigned`.
Repositories that are signed but have no explicitly defined domain
associated with them are put into the `signed` domain.  The rest is
put into the `unsigned` domain.

The `signed` domain has a trust level of one, the `unsigned` domain
has a trust level of zero.  If there is no other default domain,
`signed` will be the default domain.

The AM logs domain changes in "Tools > Log".  When a package is about
to change its domain, the AM will usually abort its installation.  In
red-pill mode, it will ask whether to continue.

Currently, a signature that could not be verified is treated the same
as no signature.

You can use the `hildon-application-manager-config` utility to add,
change and remove domains.

For backwards compatibility, a domain can list one or more URIs
instead of key fingerprints.  Such a domain will be associated with a
repository that is signed with any key and uses that URI in its
sources.list configuration.  Use the `uri` element to specify URIs in
domain configuration snippets.  Don't use this mechanism for new
repositories; it is better to create unique keys instead.
