Difference between revisions of "Projects/PIM/Akonadi/Firstrun"

< Projects‎ | PIM‎ | Akonadi
Jump to: navigation, search
(How do I create a Akonadi Firstrun description file?)
(update to new syntaxhighlight syntax)
 
(2 intermediate revisions by one user not shown)
Line 14: Line 14:
  
 
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.
 
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? ==
 
== 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.
 
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.
 
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.
 +
 +
=== 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.
 
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/ .
 +
 
 +
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.
  
 
[[Category:PIM]] [[Category:Akonadi]]
 
[[Category:PIM]] [[Category:Akonadi]]

Latest revision as of 21:00, 29 June 2011

Contents

[edit] Akonadi Firstrun

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

[edit] 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.

[edit] 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.

[edit] 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.

[edit] 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.

[edit] 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: 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.


This page was last modified on 29 June 2011, at 21:00. This page has been accessed 2,984 times. Content is available under Creative Commons License SA 3.0 as well as the GNU Free Documentation License 1.2.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V.Legal