The maemo Extras catalogue and its dot-install files

(If you read this in Planet maemo, the formatting is farked up. Please read the original.)

Summary: A dot-install file for package “<goo>” in “maemo Extras” should
look like this:

[install]
repo_name = maemo Extras
repo_deb = deb http://repository.maemo.org/extras/ mistral free non-free
repo_deb_3 = deb http://repository.maemo.org/extras/ bora free non-free
catalogues = maemo-extras
package = <goo>

[maemo-extras]
name = maemo Extras
uri = http://repository.maemo.org/extras/
components = free non-free

The only variable here is “<goo>”, the rest should be copied verbatim.
Specifically, you should not list any other repository besides
“maemo-extras”. (And make sure you have the trailing slash in the uri.)

Read on if you are bored or want to know why.

The maemo Extras repository is hopefully becoming the central place
where everyody is putting his or her maemo packages. The need to
access other repositories will hopefull decrease as maemo Extras
continues to grow.

Ideally, a OS2008 user only needs to open the Application Manager,
enable the “maemo Extras” catalogue, and will find a nicely
categorized list of applications and other add-ons that are painless
to install (and a joy to use, and easy to keep up-to-date, and
uninstall cleanly, and … you get the point).

One important inredient to make this happen is to make sure that your
package does not depend on other packages that are not also in the
maemo Extras repository or available in the OS2008 images.

That should be a pretty obvious rule. Think about the “use case”
above: someone enables the “maemo Extras” catalogue and will then see
your package in the Application Manager. If it depends on some
library that is only available in the SDK repository, it will not be
installable.

Thus, if your package depends on packages that are not already in
“maemo Extras” (and are not on people’s devices by default), you need
to get those packages into “maemo Extras” as well. Specifically, the
SDK guys should make sure that all packages in the SDK that might be
useful on the device sould be in maemo Extras, and maemo Extras should
also be pre-configured in the SDK.

You should not make a dot-install file for your package that lists all
the catalogues that are needed to find all the needed packages.
Specifically, you should not list the SDK repositories when you happen
to pick up a dependency to a SDK-only package.

That was actually the thinking behind only allowing one repository in
the original dot-install file format: everything needed to install a
package should be in the same repository as the package itself, or in
one of the repositories that everybody has pre-configured anyway.
Everything else is too messy. I am still not completely happy that I
let myself being talk into allowing multiple repositories now.

What you should do, though, if you have a dot-install file for your
package, is to list the one catalogue that contains your package (and all its
dependencies).

Also, all dot-install files that refer to the same repository should
do so in the exact same way. This will ensure that the Application Manager
will not have confusing, duplicated entries in its list of catalogues.

These two rules should be followed for any repository, not just “maemo
Extras”. Ideally, the software that places new packages into a
repository should also generate the dot-install files for it, in a
consistent manner.

Let’s look a bit at the options you have when describing a catalogue
in a dot-install file.

From the beginning, the dot-install file format allowed you to specify
different repositories for different major releases of OS20XX. This
allows one to specify for what OS20XX release a certain package is
available, and if so, where. The basic idea is that a single
dot-install file can be given to any user, regardless of what OS20XX
release he or she is running.

With the old dot-install file format, you could list one repository
for OS2006, and/or one for OS2007. With the new format, there is a
bit more flexibility, and thus more choice.

You can now list multiple repositories, and for each one, you can
specify for which major OS200XX releases it is valid. It will be
ignored for all others. Also, for each repository, you can specify
the distribution part of its sources.list entry explicitly, or you can
let the Application Manager provide a default value.

Thus, the most general way to refer to a repository is to make it
valid for any OS20XX release, and to let the Application Manager
provide the distribution. Such a description looks like this:

[repo]
name = Foo
uri = http://foo.com/
components = main non-free

Note the absence of the “filter_dist” and “dist” keys.

By using this general form, you more or less promise that there will
be a repository on http://foo.com for the “chinook” distribution and
all future OS200XX distribution names, and that that repository will
have your package in it. (If you want to extend that promise to
“mistral” and “bora” in addition to “chinook”, see the beginning of
this text for how to do it.)

This is the preferred thing to do. The rest of the flexibility is
mostly useful in specialized cases that are best avoided.
Essentially, you can control the error messages shown by the
Application Manager a bit for the case that your package is not
available for the OS200XX version that the user is running. I’d say
it is best to leave it to the Application Manager to come up with an
appropriate error message. It might not be perfect right now, but it
should and can improve.

From that point of view, the new flexibility of
dot-install files looks like a bad idea. Try to avoid it.

Simplicity wins again, as always.