You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
252 lines
9.4 KiB
252 lines
9.4 KiB
README tdeconf_update
|
|
|
|
Version: 1.1
|
|
Author: Waldo Bastian <bastian@kde.org>, <bastian@suse.com>
|
|
|
|
What it does
|
|
============
|
|
|
|
tdeconf_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.
|
|
|
|
tdeconf_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/tdeconf_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 "tdeconf_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)/tdeconf_update, or
|
|
tdeconf_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 tdeconf_update applications in $(kde_bindir)/tdeconf_update_bin,
|
|
which opens the door to tdeconf_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/tdeconf_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=tdeioslaverc,tdeio_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 "tdeioslaverc"
|
|
and stores it into the file "tdeio_httprc".
|
|
|
|
It reads the keys "NoProxyFor", "UseProxy" and "httpProxy" from the group
|
|
"Proxy Settings" in the "tdeioslaverc" 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 "tdeio_httprc" file.
|
|
|
|
It also reads the keys "MaxCacheSize" and "UseCache" from the group
|
|
"Cache Settings" in the "tdeioslaverc" file and writes this information to the
|
|
keys "MaxCacheSize" and "UseCache" in the group "Cache" (!) in the
|
|
"tdeio_httprc" file.
|
|
|
|
Then it takes all keys in the "UserAgent" group of the file "tdeioslaverc"
|
|
and moves then to the "UserAgent" group in the "tdeio_httprc" file.
|
|
|
|
Finally it removes the entire "KDE" group in the tdeioslaverc file.
|
|
|
|
|
|
Debugging and testing
|
|
=====================
|
|
|
|
If you are developing a tdeconf_update script and want to test or debug it you
|
|
need to make sure tdeconf_update runs again after each of your changes. There
|
|
are a number of ways to achieve this.
|
|
|
|
The easiest is to not install the tdeconf_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 tdeconf_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 tdeconf_update do it and check the resulting output file.
|
|
|
|
After 'make install' the tdeconf_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 tdeconf_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 tdeconf_update leaves behind: it adds a special config group
|
|
'[$Version]' with a key 'update_info'. This key lists all tdeconf_update
|
|
scripts that have already been run on this config file. Just remove your
|
|
file's entry, 'make install', and tdeconf_update will happily run your script
|
|
again, without you having to increase the version number.
|
|
|
|
If you want to know what tdeconf_update has been up to lately, have a look
|
|
at $TDEHOME/share/apps/tdeconf_update/update.log
|
|
|
|
|
|
Common Problems
|
|
===============
|
|
|
|
* tdeconf_update refuses to update an entry
|
|
If you change the value of an entry without changing the key or file,
|
|
make sure to tell tdeconf_update that it should overwrite the old entry
|
|
by adding "Options=overwrite".
|
|
|
|
|
|
Have fun,
|
|
Waldo
|