KDE PIM/Akonadi/Firstrun

Akonadi Firstrun

This page documents the Akonadi Firstrun framework and how to use it to customize initial Akonadi setups.

What is Akonadi Firstrun?

Akonadi Firstrun allows you to automatically set up Akonadi agents. The most common use case is to provide an initial setup for new users.

Akonadi Firstrun is easily customizable, allowing distributions and system administrators to provide an optimized setup for their users.

How does it work?

The agents Akonadi Firstrun sets up as well as their configuration are defined by description files. These are searched for in $KDEDIR/share/apps/akonadi/firstrun and $KDEHOME/share/apps/akonadi/firstrun (exact paths may vary depending on your distribution).

When starting a Akonadi application, Firstrun checks if there is a description file that has not been executed yet and, if so, does that. This means that starting the first Akonadi application will create the intial agents as well as that you can add additional description files later on to augment existing setups.

Which Firstrun description has already been processed is stored in $KDEHOME/share/config/akonadi-firstrunrc, removing entries there will re-process the corresponding setup instructions. This can be useful for testing/debugging.

How do I create a Akonadi Firstrun description file?

A Akonadi Firstrun description file uses the normal ini file syntax known from KDE config files. It also supports some of the KConfigXT/Kiosk features such as evaluating environment variables in setting values.

Agent creation

A description files consists of two sections. The first one defines which type of agent should be created, the following example creates a iCal file resource.

[Agent]
Id=defaultcalendar
Type=akonadi_ical_resource
Name=Personal Calendar

Besides the Type key, the Id one is most important in this section. The value defined there is used to determine if a description file has been executed already. This means moving or renaming a description file will not execute it again, changing the Id value does however. This can be useful when description files evolve over time.

Agent configuration

The second section defines the settings for the agent that just has been created. The available settings depend on the agent type of course, the following example configures two settings of an iCal file resource.

[Settings]
Path[$e]=~/.kde/share/apps/korganizer/std.ics
AutosaveInterval=1

The available settings are defined by the .kcfg file of the resource. These should be installed to $KDEDIR/share/config.kcfg. If this is not the case you find those files as part of the agent source code, for those shipped with KDE SC for example here: https://projects.kde.org/projects/kde/kdepim-runtime/repository/revisions/master/show/resources .

Note that unlike agent creation, configuration of agents requires support by the agent itself. More precisely it needs to expose it settings to D-Bus (below /Settings). While all agents shipped as part of KDE SC do this, it is not guaranteed to be supported by all 3rd-party agents.