diff options
Diffstat (limited to 'kconf_update/README.kconf_update')
| -rw-r--r-- | kconf_update/README.kconf_update | 251 |
1 files changed, 0 insertions, 251 deletions
diff --git a/kconf_update/README.kconf_update b/kconf_update/README.kconf_update deleted file mode 100644 index c8229c735..000000000 --- a/kconf_update/README.kconf_update +++ /dev/null @@ -1,251 +0,0 @@ -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 -$TDEDIR/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. - -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>. - -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 is not portable to install -binary applications in $kde_datadir, so you have to stick with interpreted -scripts like sh or perl scripts. From KDE 3.2 onwards 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. - -A workaround for KDE 3.1.x and older is to install a .sh script in -$(kde_datadir) that contains a simple exec: - - exec "`tde-config --prefix`/bin/kconf_update_bin/my_update_app" - -This is equivalent to what KDE 3.2 can do directly, but of course the .upd -file now points to the .sh script instead of the binary application. - -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". - -Since KDE 3.3 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. - -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 -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 ~/.trinity/share/config/khellorc | khello_conf_update.sh - -(assuming khello_conf_update.sh is the kconf_update script and ~/.trinity is your -$TDEHOME). 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 $TDEHOME/share/apps/kconf_update/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 |