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

## Notification of updates

A repository may contain a special _update_notification_file_ that can
announce important changes to the user.  The IT OS will periodically
check this file and if it has changed, a icon will start blinking in
the statusbar.  Clicking on this icon will present information from
the update notification file and will let the user start the
Application Manager to actually perform the update.

The update notification file is a variant of the `.install` files used
for Single-Click-Installs:

    [update]
    name = Service Pack 12
    name[de_DE] = Lochstopfer 12
    version = ITOS_0.2007.21-5
    size = 3000

The `name` and `size` will be shown in the dialog in the following
context:

          - System update -

    Important system update available.
    Download and install now?

    <name>

    Storage required: <size>

        [ OK ]            [ Cancel ]

The `size` key is specified in 1024 byte units.  If it is omitted or
zero, the "Storage required" line will be omitted.

You can also specify the complete text of the dialog with the
`dialogtext` key.  The "Storage required" line will still be added or
not depending, as usual.

The `version` key is used to determine whether the update notification
file has changed or not.  It will not be shown to the user.  Versions
are simply compared as strings for equality.

When the user confirms the "System update" dialog, the Application
Manager will be started and will attempt to update all installed
packages that have the "system-update" flag set.

The IT OS currently tracks only one update notification file,
configured via the GConf key

    /apps/osso/hildon-update-notifier/url

In the future, the need for update notification files should go away.
The IT OS should be able to figure it all out from the packages in the
repository alone.
