(→File format of the update file) |
(update to new syntaxhighlighter) |
||
| Line 104: | Line 104: | ||
== Example update file == | == Example update file == | ||
| − | < | + | <syntaxhighlight lang="ini"> |
# This is comment | # This is comment | ||
| Line 120: | Line 120: | ||
RemoveGroup=KDE | RemoveGroup=KDE | ||
# End of file | # End of file | ||
| − | </ | + | </syntaxhighlight> |
The above update file extracts config information from the file {{path||kioslaverc}} and stores it into the file {{path||kio_httprc}}. | The above update file extracts config information from the file {{path||kioslaverc}} and stores it into the file {{path||kio_httprc}}. | ||
| Note |
|---|
| The text for this document was lifted from the source file kdelibs/kconf_update/README.kconf_update. It is reprinted here so that we have a description outside of the source code, and so we can add more example update scripts. |
Contents |
kconf_update is a tool designed to update configuration files. Over time applications sometimes need to rearrange the way configuration options are stored. Since such an update shouldn't influence the configuration options that the user has selected, the application must take care that the options stored in the old way will still be honored.
What used to happen is that the application looks up both the old and the new configuration option and then decides which one to use. This method has several drawbacks:
kconf_update addresses these problems by offering a framework to update configuration files without adding code to the application itself.
Applications can install so called update files under $KDEDIR/share/apps/kconf_update. An update file has .upd as extension and contains instructions for transferring and converting configuration information from one place to another.
Updating the configuration happens automatically, either when KDE gets started or when kded detects a new update file in the above mentioned location.
Update files are separated into sections. Each section has an unique ID. When a section describing a configuration change has been applied, the ID will be stored in the file $KDEHOME/share/config/kconf_updaterc. This information is used to make sure that a configuration update is only performed once.
If you overwrite an existing update file with a new version that contains a new section, only the update instructions from this extra section will be performed.
Empty lines or lines that start with '#' are considered comments. Commas are used to seperate fields and may not occur as part of any field. All of the keywords are case-sensitive.
The remainder of the file is parsed and executed sequentially from top to bottom. Each line can contain one entry. The following entries are recognized:
# DELETE [group]key
# DELETEGROUP [group]
# DELETE key
# DELETEGROUP
# This is comment Id=kde2.2 File=kioslaverc,kio_httprc Group=Proxy Settings Key=NoProxyFor Key=UseProxy Key=httpProxy,Proxy Group=Cache Settings,Cache Key=MaxCacheSize Key=UseCache Group=UserAgent AllKeys RemoveGroup=KDE # End of file
The above update file extracts config information from the file and stores it into the file .
It reads the keys "NoProxyFor", "UseProxy" and "httpProxy" from the group "Proxy Settings" in the kioslaverc file. If any of these options are present they are written to the keys "NoProxyFor", "UseProxy" and "Proxy" (!) in the group "Proxy Settings" in the kio_httprc file.
It also reads the keys "MaxCacheSize" and "UseCache" from the group "Cache Settings" in the kioslaverc file and writes this information to the keys "MaxCacheSize" and "UseCache" in the group "Cache" (!) in the kio_httprc file.
Then it takes all keys in the "UserAgent" group of the file "kioslaverc" and moves then to the "UserAgent" group in the kio_httprc file.
Finally it removes the entire "KDE" group in the kioslaverc file.
The best way to learn how to write scripts and update files is to look at existing ones, for example the ones of KMail.
If you are developing a kconf_update script and want to test or debug it you need to make sure kconf_update runs again after each of your changes. There are a number of ways to achieve this.
The easiest is to not install the kconf_update script in the first place, but manually call it through a pipe. If you want to test the update script for your application KHello's config file khellorc, you can test by using
cat ~/.kde/share/config/khellorc | khello_conf_update.sh
(assuming khello_conf_update.sh is the kconf_update script and ~/.kde is your $KDEHOME). This is easier than making install every time, but has the obvious downside that you need to 'parse' your script's output yourself instead of letting kconf_update do it and check the resulting output file.
After 'make install' the kconf_update script is run by kded, but it does so only once. This is of course the idea behind it, but while developing it can be a problem. You can increase the revision number for each subsequent run of 'make install' to force a new kconf_update run, but there's a better approach that doesn't skyrocket the version number for a mediocre debug session.
kded doesn't really ignore scripts that it has already run right away. Instead it checks the affected config file every time a .upd file is added or changed. The reason it still doesn't run again on your config file lies in the traces kconf_update leaves behind: it adds a special config group '[$Version]' with a key 'update_info'. This key lists all kconf_update scripts that have already been run on this config file. Just remove your file's entry, 'make install', and kconf_update will happily run your script again, without you having to increase the version number.
If you want to know what kconf_update has been up to lately, have a look at $KDEHOME/share/apps/kconf_update/log/update.log
kconf_update refuses to update an entry
If you change the value of an entry without changing the key or file, make sure to tell kconf_update that it should overwrite the old entry by adding "Options=overwrite".
KDE TechBase 