Differential D19779 Diff 54849 src/kconf_update/README.kconf_update

Changeset View

Standalone View

src/kconf_update/README.kconf_update

1	README kconf_update	1	https://techbase.kde.org/Development/Tools/Using_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	Starting from KDE Frameworks 5 make sure to put Version=5 before the first "Id=" otherwise the upd file
55	will be skipped and the config file will not be updated.
56
57	For the rest the file is parsed and executed sequentially from top to bottom.
58	Each line can contain one entry. The following entries are recognized:
59
60
61	Id=<id>
62
63	With <id> identifying the group of update entries that follows. Once a group
64	of entries have been applied, their <id> is stored and this group of entries
65	will not be applied again.
66
67
68	File=<oldfile>,<newfile>
69	File=<oldfile>
70
71	Specifies that configuration information is read from <oldfile> and written
72	to <newfile>. If you only specify <oldfile>, the information is read from
73	as well as written to <oldfile>. Note that if the file does not exist
74	at the time kconf_update first checks, no related update will be performed
75	(script won't be run at all, etc.).
76
77
78	Script=<script>[,<interpreter>]
79
80	All entries from <oldfile> are piped into <script>. The output of script
81	is used as new entries for <newfile>. Existing entries can be deleted by
82	adding lines with "# DELETE [group]key" in the output of the script.
83	To delete a whole group use "# DELETEGROUP [group]".
84
85	<script> should be installed into $(kde_datadir)/kconf_update, or
86	kconf_update will not be able to find it. It's also possible to install
87	kconf_update applications in $(kde_bindir)/kconf_update_bin, which opens the
88	door to kconf_update applications that are written in C++ and use Qt's
89	powerful string API instead.
90
91	If Script was issued after a "Group" command the behavior is slightly
92	different:
93	All entries from <oldfile>/<oldgroup> are piped into <script>. The output
94	of script is used as new entries for <newfile>/<newgroup>, unless a different
95	group is specified with "[group]". Existing entries can be deleted from
96	<oldgroup> by adding lines with "# DELETE key" in the output of the script.
97	To delete <oldgroup> use "# DELETEGROUP".
98
99	<interpreter> can be something like "perl".
100
101	It is also possible to have a Script without specifying <oldfile> or
102	<newfile>. In that case the script is run but it will not be fed any input
103	and its output will simply be discarded.
104
105	ScriptArguments=<arguments>
106
107	If specified, the arguments will be passed to <script>.
108	IMPORTANT: It has to be specified before Script=.
109
110	Group=<oldgroup>,<newgroup>
111	Group=<oldgroup>
112
113	Specifies that configuration information is read from the group <oldgroup>
114	and written to <newgroup>. If you only specify <oldgroup>, the information
115	is read from as well as written to <oldgroup>. You can use <default> to
116	specify keys that are not under any group.
117	A group may be written either as "group" or as "[group]". The latter syntax
118	makes it possible to specify subgroups: "[group][subgroup]".
119
120	RemoveGroup=<oldgroup>
121
122	Specifies that <oldgroup> is removed entirely. This can be used
123	to remove obsolete entries or to force a revert to default values.
124
125	Options=<option1>, <option2>, ....
126
127	With this entry you can specify options that apply to the next "Script",
128	"Key" or "AllKeys" entry (only to the first!). Possible options are:
129
130	- "copy" Copy the configuration item instead of moving it. This means that
131	the configuration item will not be deleted from <oldfile>/<oldgroup>.
132
133	- "overwrite" Normally, a configuration item is not moved if an item with the
134	new name already exists. When this option is specified the old
135	configuration item will overwrite any existing item.
136
137
138	Key=<oldkey>,<newkey>
139	Key=<oldkey>
140
141	Specifies that configuration information is read from the key <oldkey>
142	and written to <newkey>. If you only specify <oldkey>, the information
143	is read from as well as written to <oldkey>.
144
145
146	AllKeys
147
148	Specifies that all configuration information in the selected group should
149	be moved (All keys).
150
151	AllGroups
152
153	Specifies that all configuration information from all keys in ALL
154	groups should be moved.
155
156
157	RemoveKey=<oldkey>
158
159	Specifies that <oldkey> is removed from the selected group. This can be used
160	to remove obsolete entries or to force a revert to default values.
161
162
163	Example update file
164	===================
165
166	# This is comment
167	Version=5
168	Id=kde2.2
169	File=kioslaverc,kio_httprc
170	Group=Proxy Settings
171	Key=NoProxyFor
172	Key=UseProxy
173	Key=httpProxy,Proxy
174	Group=Cache Settings,Cache
175	Key=MaxCacheSize
176	Key=UseCache
177	Group=UserAgent
178	AllKeys
179	RemoveGroup=KDE
180	# End of file
181
182
183	The above update file extracts config information from the file "kioslaverc"
184	and stores it into the file "kio_httprc".
185
186	It reads the keys "NoProxyFor", "UseProxy" and "httpProxy" from the group
187	"Proxy Settings" in the "kioslaverc" file. If any of these options are present
188	they are written to the keys "NoProxyFor", "UseProxy" and "Proxy" (!) in
189	the group "Proxy Settings" in the "kio_httprc" file.
190
191	It also reads the keys "MaxCacheSize" and "UseCache" from the group
192	"Cache Settings" in the "kioslaverc" file and writes this information to the
193	keys "MaxCacheSize" and "UseCache" in the group "Cache" (!) in the
194	"kio_httprc" file.
195
196	Then it takes all keys in the "UserAgent" group of the file "kioslaverc"
197	and moves then to the "UserAgent" group in the "kio_httprc" file.
198
199	Finally it removes the entire "KDE" group in the kioslaverc file.
200
201
202	Debugging and testing
203	=====================
204
205	If you are developing a kconf_update script and want to test or debug it you
206	need to make sure kconf_update runs again after each of your changes. There
207	are a number of ways to achieve this.
208
209	The easiest is to not install the kconf_update script in the first place, but
210	manually call it through a pipe. If you want to test the update script for
211	your application KHello's config file khellorc, you can test by using
212
213	cat ~/.kde/share/config/khellorc \| khello_conf_update.sh
214
215	(assuming khello_conf_update.sh is the kconf_update script and ~/.kde is your
216	$KDEHOME). This is easier than making install every time, but has the obvious
217	downside that you need to 'parse' your script's output yourself instead of
218	letting kconf_update do it and check the resulting output file.
219
220	After 'make install' the kconf_update script is run by kded, but it does so
221	only once. This is of course the idea behind it, but while developing it can
222	be a problem. You can increase the revision number for each subsequent run
223	of 'make install' to force a new kconf_update run, but there's a better
224	approach that doesn't skyrocket the version number for a mediocre debug
225	session.
226
227	kded doesn't really ignore scripts that it has already run right away.
228	Instead it checks the affected config file every time a .upd file is added
229	or changed. The reason it still doesn't run again on your config file lies
230	in the traces kconf_update leaves behind: it adds a special config group
231	'[$Version]' with a key 'update_info'. This key lists all kconf_update
232	scripts that have already been run on this config file. It also adds a group
233	for the script to $KDEHOME/share/config/kconf_updaterc. Just remove your
234	script entries from both your rcfile and kconf_updaterc, 'make install',
235	and kconf_update will happily run your script again, without you having to
236	increase the version number.
237
238	If you want to know what kconf_update has been up to lately, have a look
239	at $KDEHOME/share/apps/kconf_update/log/update.log
240
241
242	Common Problems
243	===============
244
245	* kconf_update refuses to update an entry
246	If you change the value of an entry without changing the key or file,
247	make sure to tell kconf_update that it should overwrite the old entry
248	by adding "Options=overwrite".
249
250
251	Have fun,
252	Waldo