Development/Tools/Using kconf update - Revision history

Albert Astals Cid: fix || -> |

2012-09-08T13:45:59Z

fix || -> |

Nicolas17: update to new syntaxhighlighter

2011-06-29T19:31:44Z

update to new syntaxhighlighter

Nicolas17: update to new syntaxhighlighter

2011-06-29T19:30:56Z

update to new syntaxhighlighter

TMG: /* File format of the update file */

2007-07-17T20:12:25Z

‎File format of the update file

TMG: /* File format of the update file */

2007-07-17T20:04:38Z

‎File format of the update file

TMG: /* How it works */

2007-07-17T19:47:02Z

‎How it works

TMG: /* How it works */

2007-07-17T19:44:31Z

‎How it works

TMG: /* File format of the update file */ sync

2007-07-17T19:40:38Z

‎File format of the update file: sync

TMG: cosmetic changes

2007-07-17T19:36:53Z

cosmetic changes

Show changes

Winterz: cleanup

2007-07-17T17:57:24Z

cleanup

@@ Line 122: / Line 122: @@
 </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}}.
 It reads the keys "NoProxyFor", "UseProxy" and "httpProxy" from the group "Proxy Settings" in the {{path|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 {{path|kio_httprc}} file.

@@ Line 141: / Line 141: @@
 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 {{path|khellorc}}, you can test by using
-<code bash>
+<syntaxhighlight lang="bash">
 cat ~/.kde/share/config/khellorc | khello_conf_update.sh
-</code>
+</syntaxhighlight>
 (assuming {{path|khello_conf_update.sh}} is the kconf_update script and {{path|~/.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.

@@ Line 104: / Line 104: @@
 == Example update file ==
-<code ini>
+<syntaxhighlight lang="ini">
 # This is comment
@@ Line 120: / Line 120: @@
 RemoveGroup=KDE
 # End of file
-</code>
+</syntaxhighlight>
 The above update file extracts config information from the file {{path||kioslaverc}} and stores it into the file {{path||kio_httprc}}.

@@ Line 44: / Line 44: @@
 :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
+: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
@@ Line 51: / Line 51: @@
 :<_script> should be installed into {{path|$(kde_datadir)/kconf_update}}, or kconf_update will not be able to find it.
-:It is not portable to install binary applications in {{path|$kde_datadir}}, so you have to stick with interpreted scripts like shell or perl scripts. To make your scripts compatible with Windows, you should not use shell scripts.
+:It is not portable to install binary applications in {{path|$kde_datadir}}, so you have to stick with interpreted scripts like shell or perl. To make your scripts compatible with Windows, you should not use shell scripts.
 :It is also possible to install kconf_update applications in {{path|$(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.

@@ Line 22: / Line 22: @@
 ==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.
+Empty lines or lines that start with '#' are considered comments.
 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:
- Id=<id>
+*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.
+: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. This ID has to be unique.
- File=<oldfile>,<newfile>
+*File=<oldfile>,<newfile>
- File=<oldfile>
+*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).
+:Specifies that configuration information is read from <oldfile> and written to <newfile>.
-  Script=<_script>[,<interpreter>]
+*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]".
+:All entries from <oldfile> are piped into <_script>.
-<_script> should be installed into {{path|$(kde_datadir)/kconf_update}}, or kconf_update will not be able to find it. It is not portable to install binary applications in {{path|$kde_datadir}}, so you have to stick with interpreted scripts like shell or perl scripts.
+:<_script> should be installed into {{path|$(kde_datadir)/kconf_update}}, or kconf_update will not be able to find it.
-It is also possible to install kconf_update applications in {{path|$(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.
+:It is also possible to install kconf_update applications in {{path|$(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".
+:If the ''Script'' command 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
-<interpreter> can be something like "perl".
+:<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.
+: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>
+*ScriptArguments=<arguments>
-If specified, the arguments will be passed to <_script>. IMPORTANT: Specify the ScriptArguments '''before''' the script.
+:If specified, the arguments will be passed to <_script>. IMPORTANT: Specify the ScriptArguments '''before''' the ''Script'' command.
- Group=<oldgroup>,<newgroup>
+*Group=<oldgroup>,<newgroup>
- Group=<oldgroup>
+*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.
+: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>
+*RemoveGroup=<oldgroup>
-Specifies that <oldgroup> is removed entirely. This can be used to remove obsolete entries or to force a revert to default values.
+: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>, ....
+*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:
+:With this entry you can specify options that apply to the next ''Script'' command, ''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>.
+::- "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.
+::- "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>,<newkey>
- Key=<oldkey>
+*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>.
+: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
+*AllKeys
-Specifies that all configuration information in the selected group should be moved (All keys).
+:Specifies that all configuration information in the selected group should be moved (All keys).
- AllGroups
+*AllGroups
-Specifies that all configuration information from all keys in ALL groups should be moved.
+:Specifies that all configuration information from all keys in '''all''' groups should be moved.
- RemoveKey=<oldkey>
+*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.
+: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.
 <code ini>
 # This is comment
 Id=kde2.2
 File=kioslaverc,kio_httprc
@@ Line 114: / Line 131: @@
 Finally it removes the entire "KDE" group in the {{path|kioslaverc}} file.
 ==Debugging and testing==

@@ Line 13: / Line 13: @@
 ==How it works==
-Applications can install so called "update files" under {{path|$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.
+Applications can install so called ''update files'' under {{path|$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 <tt>kded</tt> 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 {{path|$KDEHOME/share/config/kconf_updaterc}}. This information is used to make sure that a configuration update is only performed once.
+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 {{path|$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.

@@ Line 6: / Line 6: @@
 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 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.
- 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.
+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.
+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.
+Updating the configuration happens automatically, either when KDE gets started or when kded detects a new update file in the above mentioned location.
- 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.
+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.
 ==File format of the update file==
@@ Line 40: / Line 37: @@
 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.
+<_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:
@@ Line 50: / Line 47: @@
 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".
+<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.
@@ Line 71: / Line 68: @@
 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>.
+"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.
+"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>
@@ Line 92: / Line 89: @@
 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
+<pre>Example update file
 # This is comment
 Id=kde2.2
@@ Line 107: / Line 104: @@
 RemoveGroup=KDE
 # End of file
 The above update file extracts config information from the file "kioslaverc" and stores it into the file "kio_httprc".