kconf_update/README.kconf_update

   1 README kconf_update
   2
   3 Version: 1.1
   4 Author: Waldo Bastian <bastian@kde.org>, <bastian@suse.com>
   5
   6 What it does
   7 ============
   8
   9 kconf_update is a tool designed to update config files. Over time applications
  10 sometimes need to rearrange the way configuration options are stored. Since
  11 such an update shouldn't influence the configuration options that the user
  12 has selected, the application must take care that the options stored in the
  13 old way will still be honored.
  14
  15 What used to happen is that the application looks up both the old and the
  16 new configuration option and then decides which one to use. This method has
  17 several drawbacks:
  18 * The application may need to read more configuration files than strictly
  19 needed, resulting in a slower startup.
  20 * The application becomes bigger with code that will only be used once.
  21
  22 kconf_update addresses these problems by offering a framework to update
  23 configuration files without adding code to the application itself.
  24
  25
  26 How it works
  27 ============
  28
  29 Applications can install so called "update files" under
  30 $KDEDIR/share/apps/kconf_update. An update file has ".upd" as extension and
  31 contains instructions for transferring/converting configuration information
  32 from one place to another.
  33
  34 Updating the configuration happens automatically, either when KDE gets started
  35 or when kded detects a new update file in the above mentioned location.
  36
  37 Update files are separated into sections. Each section has an Id. When a
  38 section describing a configuration change has been applied, the Id will be
  39 stored in the file "kconf_updaterc". This information is used to make sure
  40 that a configuration update is only performed once.
  41
  42 If you overwrite an existing update file with a new version that contains a
  43 new section, only the update instructions from this extra section will be
  44 performed.
  45
  46 File format of the update file
  47 ==============================
  48
  49 Empty lines or lines that start with '#' are considered comments.
  50 Commas (,) are used to seperate fields and may not occur as part
  51 of any field and all of the keywords are case-sensitive, i.e. you
  52 cannot say "key" instead of "Key" for example.
  53
  54 For the rest the file is parsed and executed sequentially from top to bottom.
  55 Each line can contain one entry. The following entries are recognized:
  56
  57
  58 Id=<id>
  59
  60 With <id> identifying the group of update entries that follows. Once a group
  61 of entries have been applied, their <id> is stored and this group of entries
  62 will not be applied again.
  63
  64
  65 File=<oldfile>,<newfile>
  66 File=<oldfile>
  67
  68 Specifies that configuration information is read from <oldfile> and written
  69 to <newfile>. If you only specify <oldfile>, the information is read from
  70 as well as written to <oldfile>. Note that if the file does not exist
  71 at the time kconf_update first checks, no related update will be performed
  72 (script won't be run at all, etc.).
  73
  74
  75 Script=<script>[,<interpreter>]
  76
  77 All entries from <oldfile> are piped into <script>. The output of script
  78 is used as new entries for <newfile>. Existing entries can be deleted by
  79 adding lines with "# DELETE [group]key" in the output of the script.
  80 To delete a whole group use "# DELETEGROUP [group]".
  81
  82 <script> should be installed into $(kde_datadir)/kconf_update, or
  83 kconf_update will not be able to find it. It is not portable to install
  84 binary applications in $kde_datadir, so you have to stick with interpreted
  85 scripts like sh or perl scripts. From KDE 3.2 onwards it's also possible
  86 to install kconf_update applications in $(kde_bindir)/kconf_update_bin,
  87 which opens the door to kconf_update applications that are written in C++
  88 and use Qt's powerful string API instead.
  89
  90 A workaround for KDE 3.1.x and older is to install a .sh script in
  91 $(kde_datadir) that contains a simple exec:
  92
  93     exec "`kde-config --prefix`/bin/kconf_update_bin/my_update_app"
  94
  95 This is equivalent to what KDE 3.2 can do directly, but of course the .upd
  96 file now points to the .sh script instead of the binary application.
  97
  98 If Script was issued after a "Group" command the behavior is slightly
  99 different:
 100 All entries from <oldfile>/<oldgroup> are piped into <script>. The output
 101 of script is used as new entries for <newfile>/<newgroup>, unless a different
 102 group is specified with "[group]". Existing entries can be deleted from
 103 <oldgroup> by adding lines with "# DELETE key" in the output of the script.
 104 To delete <oldgroup> use "# DELETEGROUP".
 105
 106 <interpreter> can be something like "perl".
 107
 108 Since KDE 3.3 it is also possible to have a Script without specifying
 109 <oldfile> or <newfile>. In that case the script is run but it will not be
 110 fed any input and its output will simply be discarded.
 111
 112 ScriptArguments=<arguments>
 113
 114 If specified, the arguments will be passed to <script>.
 115 IMPORTANT: It has to be specified before Script=.
 116
 117 Group=<oldgroup>,<newgroup>
 118 Group=<oldgroup>
 119
 120 Specifies that configuration information is read from the group <oldgroup>
 121 and written to <newgroup>. If you only specify <oldgroup>, the information
 122 is read from as well as written to <oldgroup>. You can use <default> to
 123 specify keys that are not under any group.
 124
 125 RemoveGroup=<oldgroup>
 126
 127 Specifies that <oldgroup> is removed entirely. This can be used
 128 to remove obsolete entries or to force a revert to default values.
 129
 130 Options=<option1>, <option2>, ....
 131
 132 With this entry you can specify options that apply to the next "Script",
 133 "Key" or "AllKeys" entry (only to the first!). Possible options are:
 134
 135 - "copy" Copy the configuration item instead of moving it. This means that
 136          the configuration item will not be deleted from <oldfile>/<oldgroup>.
 137
 138 - "overwrite" Normally, a configuration item is not moved if an item with the
 139          new name already exists. When this option is specified the old
 140          configuration item will overwrite any existing item.
 141
 142
 143 Key=<oldkey>,<newkey>
 144 Key=<oldkey>
 145
 146 Specifies that configuration information is read from the key <oldkey>
 147 and written to <newkey>. If you only specify <oldkey>, the information
 148 is read from as well as written to <oldkey>.
 149
 150
 151 AllKeys
 152
 153 Specifies that all configuration information in the selected group should
 154 be moved (All keys).
 155
 156 AllGroups
 157
 158 Specifies that all configuration information from all keys in ALL
 159 groups should be moved.
 160
 161
 162 RemoveKey=<oldkey>
 163
 164 Specifies that <oldkey> is removed from the selected group. This can be used
 165 to remove obsolete entries or to force a revert to default values.
 166
 167
 168 Example update file
 169 ===================
 170
 171 # This is comment
 172 Id=kde2.2
 173 File=kioslaverc,kio_httprc
 174 Group=Proxy Settings
 175 Key=NoProxyFor
 176 Key=UseProxy
 177 Key=httpProxy,Proxy
 178 Group=Cache Settings,Cache
 179 Key=MaxCacheSize
 180 Key=UseCache
 181 Group=UserAgent
 182 AllKeys
 183 RemoveGroup=KDE
 184 # End of file
 185
 186
 187 The above update file extracts config information from the file "kioslaverc"
 188 and stores it into the file "kio_httprc".
 189
 190 It reads the keys "NoProxyFor", "UseProxy" and "httpProxy" from the group
 191 "Proxy Settings" in the "kioslaverc" file. If any of these options are present
 192 they are written to the keys "NoProxyFor", "UseProxy" and "Proxy" (!) in
 193 the group "Proxy Settings" in the "kio_httprc" file.
 194
 195 It also reads the keys "MaxCacheSize" and "UseCache" from the group
 196 "Cache Settings" in the "kioslaverc" file and writes this information to the
 197 keys "MaxCacheSize" and "UseCache" in the group "Cache" (!) in the
 198 "kio_httprc" file.
 199
 200 Then it takes all keys in the "UserAgent" group of the file "kioslaverc"
 201 and moves then to the "UserAgent" group in the "kio_httprc" file.
 202
 203 Finally it removes the entire "KDE" group in the kioslaverc file.
 204
 205
 206 Debugging and testing
 207 =====================
 208
 209 If you are developing a kconf_update script and want to test or debug it you
 210 need to make sure kconf_update runs again after each of your changes. There
 211 are a number of ways to achieve this.
 212
 213 The easiest is to not install the kconf_update script in the first place, but
 214 manually call it through a pipe. If you want to test the update script for
 215 your application KHello's config file khellorc, you can test by using
 216
 217     cat ~/.kde/share/config/khellorc | khello_conf_update.sh
 218
 219 (assuming khello_conf_update.sh is the kconf_update script and ~/.kde is your
 220 $KDEHOME). This is easier than making install every time, but has the obvious
 221 downside that you need to 'parse' your script's output yourself instead of
 222 letting kconf_update do it and check the resulting output file.
 223
 224 After 'make install' the kconf_update script is run by kded, but it does so
 225 only once. This is of course the idea behind it, but while developing it can
 226 be a problem. You can increase the revision number for each subsequent run
 227 of 'make install' to force a new kconf_update run, but there's a better
 228 approach that doesn't skyrocket the version number for a mediocre debug
 229 session.
 230
 231 kded doesn't really ignore scripts that it has already run right away.
 232 Instead it checks the affected config file every time a .upd file is added
 233 or changed. The reason it still doesn't run again on your config file lies
 234 in the traces kconf_update leaves behind: it adds a special config group
 235 '[$Version]' with a key 'update_info'. This key lists all kconf_update
 236 scripts that have already been run on this config file. Just remove your
 237 file's entry, 'make install', and kconf_update will happily run your script
 238 again, without you having to increase the version number.
 239
 240 If you want to know what kconf_update has been up to lately, have a look
 241 at $KDEHOME/share/apps/kconf_update/update.log
 242
 243
 244 Common Problems
 245 ===============
 246
 247 * kconf_update refuses to update an entry
 248 If you change the value of an entry without changing the key or file,
 249 make sure to tell kconf_update that it should overwrite the old entry
 250 by adding "Options=overwrite".
 251
 252
 253 Have fun,
 254 Waldo