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.

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.

−

<code ini>

+

<syntaxhighlight lang="ini">

[Agent]

[Agent]

Id=defaultcalendar

Id=defaultcalendar

Type=akonadi_ical_resource

Type=akonadi_ical_resource

Name=Personal Calendar

Name=Personal Calendar

−

</code>

+

</syntaxhighlight>

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.

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.

Line 38:

Line 38:

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.

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.

−

<code ini>

+

<syntaxhighlight lang="ini">

[Settings]

[Settings]

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

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

AutosaveInterval=1

AutosaveInterval=1

−

</code>

+

</syntaxhighlight>

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: http://websvn.kde.org/trunk/KDE/kdepim/runtime/resources/ .

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: http://websvn.kde.org/trunk/KDE/kdepim/runtime/resources/ .

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.

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.

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.

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.

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: http://websvn.kde.org/trunk/KDE/kdepim/runtime/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.