diff options
| -rw-r--r-- | src/kconf_update/README.kconf_update | 253 |
1 files changed, 1 insertions, 252 deletions
diff --git a/src/kconf_update/README.kconf_update b/src/kconf_update/README.kconf_update index 72509286..1a97c9ea 100644 --- a/src/kconf_update/README.kconf_update +++ b/src/kconf_update/README.kconf_update @@ -1,252 +1 @@ -README kconf_update - -Version: 1.1 -Author: Waldo Bastian <bastian@kde.org>, <bastian@suse.com> - -What it does -============ - -kconf_update is a tool designed to update config 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: -* The application may need to read more configuration files than strictly -needed, resulting in a slower startup. -* The application becomes bigger with code that will only be used once. - -kconf_update addresses these problems by offering a framework to update -configuration files without adding code to the application itself. - - -How it works -============ - -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/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 Id. When a -section describing a configuration change has been applied, the Id will be -stored in the file "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. - -File format of the update file -============================== - -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 and all of the keywords are case-sensitive, i.e. you -cannot say "key" instead of "Key" for example. - -Starting from KDE Frameworks 5 make sure to put Version=5 before the first "Id=" otherwise the upd file -will be skipped and the config file will not be updated. - -For the rest the file is parsed and executed sequentially from top to bottom. -Each line can contain one entry. The following entries are recognized: - - -Id=<id> - -With <id> identifying the group of update entries that follows. Once a group -of entries have been applied, their <id> is stored and this group of entries -will not be applied again. - - -File=<oldfile>,<newfile> -File=<oldfile> - -Specifies that configuration information is read from <oldfile> and written -to <newfile>. If you only specify <oldfile>, the information is read from -as well as written to <oldfile>. Note that if the file does not exist -at the time kconf_update first checks, no related update will be performed -(script won't be run at all, etc.). - - -Script=<script>[,<interpreter>] - -All entries from <oldfile> are piped into <script>. The output of script -is used as new entries for <newfile>. Existing entries can be deleted by -adding lines with "# DELETE [group]key" in the output of the script. -To delete a whole group use "# DELETEGROUP [group]". - -<script> should be installed into $(kde_datadir)/kconf_update, or -kconf_update will not be able to find it. It's also possible to install -kconf_update applications in $(kde_bindir)/kconf_update_bin, which opens the -door to kconf_update applications that are written in C++ and use Qt's -powerful string API instead. - -If Script was issued after a "Group" command the behavior is slightly -different: -All entries from <oldfile>/<oldgroup> are piped into <script>. The output -of script is used as new entries for <newfile>/<newgroup>, unless a different -group is specified with "[group]". Existing entries can be deleted from -<oldgroup> by adding lines with "# DELETE key" in the output of the script. -To delete <oldgroup> use "# DELETEGROUP". - -<interpreter> can be something like "perl". - -It is also possible to have a Script without specifying <oldfile> or -<newfile>. In that case the script is run but it will not be fed any input -and its output will simply be discarded. - -ScriptArguments=<arguments> - -If specified, the arguments will be passed to <script>. -IMPORTANT: It has to be specified before Script=. - -Group=<oldgroup>,<newgroup> -Group=<oldgroup> - -Specifies that configuration information is read from the group <oldgroup> -and written to <newgroup>. If you only specify <oldgroup>, the information -is read from as well as written to <oldgroup>. You can use <default> to -specify keys that are not under any group. -A group may be written either as "group" or as "[group]". The latter syntax -makes it possible to specify subgroups: "[group][subgroup]". - -RemoveGroup=<oldgroup> - -Specifies that <oldgroup> is removed entirely. This can be used -to remove obsolete entries or to force a revert to default values. - -Options=<option1>, <option2>, .... - -With this entry you can specify options that apply to the next "Script", -"Key" or "AllKeys" entry (only to the first!). Possible options are: - -- "copy" Copy the configuration item instead of moving it. This means that - the configuration item will not be deleted from <oldfile>/<oldgroup>. - -- "overwrite" Normally, a configuration item is not moved if an item with the - new name already exists. When this option is specified the old - configuration item will overwrite any existing item. - - -Key=<oldkey>,<newkey> -Key=<oldkey> - -Specifies that configuration information is read from the key <oldkey> -and written to <newkey>. If you only specify <oldkey>, the information -is read from as well as written to <oldkey>. - - -AllKeys - -Specifies that all configuration information in the selected group should -be moved (All keys). - -AllGroups - -Specifies that all configuration information from all keys in ALL -groups should be moved. - - -RemoveKey=<oldkey> - -Specifies that <oldkey> is removed from the selected group. This can be used -to remove obsolete entries or to force a revert to default values. - - -Example update file -=================== - -# This is comment -Version=5 -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 "kioslaverc" -and stores it into the file "kio_httprc". - -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. - - -Debugging and testing -===================== - -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. It also adds a group -for the script to $KDEHOME/share/config/kconf_updaterc. Just remove your -script entries from both your rcfile and kconf_updaterc, '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 - - -Common Problems -=============== - -* 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". - - -Have fun, -Waldo +https://techbase.kde.org/Development/Tools/Using_kconf_update |