1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
|
im-config for Debian Osamu Aoki <osamu@debian.org>
NOTE: This source code is managed using dgit-maint-merge strategy.
=======================================================================
! Basic design of im-config framework
=======================================================================
1. If an reasonable and single set of input method (IM) packages is
installed, im-config framework activates desirable IM dynamically
adjusted for all users by default. (recommended situation)
2. If several reasonable sets of IM packages are installed, im-config
framework activates the most reasonable one dynamically for all
users by default. (The locale setting, desktop environment (DE)
choice and other factors are taken into account.)
3. The im-config framework provides a reasonably simple GUI
configuration menu program as the im-config command. You can always
start this GUI configuration menu by executing "im-config" from the
console shell prompt. This command can be started from the GUI
menu, too. This shell script is internationalized via gettext.sh.
Selected user configuration can override the system default
configuration. Menu should normally show only available input
methods on the system.
4. Evolution history of im-config configuration mechanism
It was simpler when only the classic X11 DE on sysV-init was its
target and no autostarted GUI programs were addressed.
Then, in order to keep setting up of environment variables for GUI
programs at 70-priority while moving the starting of daemons to
90-priority, the delayed execution is enabled by using $STARTUP
value.
In order to use single configuration file such as 21_ibus.rc in
/usr/share/im-config/data/ used both for setting IM environment
variables and for starting daemon, following variables are used.
* "$IM_CONFIG_PHASE" = 1 for IM environment variable setting
* "$IM_CONFIG_PHASE" = 2 for daemon program starting
In order to avoid conflict with user selected set up, many checks
are added to make this complicated and convoluted.
Lastly, modification to support wayland and systemd systems made
im-config framework to call 70im-config_launch multiple times.
(I recall this bad coding stile was motivated to get easier freeze
exception by changing fewer lines.)
With 0.59 release, multiple calls to 70im-config_launch is removed
and evaluated how to address https://bugs.debian.org/1052005.
The conclusion is stop doing anything for wayland as mentioned in
README.Debian.
Start-up process parses several hook configuration files.
** /etc/11/Xsession.d/70im-config_launch
This call sets: IM_CONFIG_ENTRY=xsession
If im-config package is removed but not yet purged, this
70im-config_launch script exists and may cause trouble. So run this
only when im-launch exists (im-config package is installed).
If any of the following IM activation related variables are set,
this 70im-config_launch script keeps its hands off.
* "$XMODIFIERS"
* "$GTK_IM_MODULE"
* "$QT_IM_MODULE"
* "$CLUTTER_IM_MODULE"
* "$SDL_IM_MODULE"
Otherwise:
- Set $IM_CONFIG_PHASE" = 1
- Source share/im-config_setting
- Set environment variables
Update $STARTUP for im-launch stared in 99x11-common_start
** /etc/11/Xsession.d/99x11-common_start
- This calls im-launch via $STARTUP
- Set "$IM_CONFIG_PHASE" = 2 in im-launch
- Source share/im-config_setting
- Start IM daemon
Here, im-launch is very careful. It checks if any of the IM
activation related variables are changed. If it detects changes then
it doesn't start IM daemon.
** /etc/profile.d/im-config_wayland.sh
** /etc/xdg/autostart/im-launch.desktop
Disabled by making these as place holder files
* GNOME on Wayland needed these but no more.
* KDE on Wayland doesn't need these.
* Others, recommend manual configuration
5. Configuration files for the system start-up
* ~/.xinputrc --- (user specific)
* /etc/X11/xinit/xinputrc --- (system wide for root)
* /usr/share/im-config/data/*.rc --- (IM specific preset values)
6. GUI configuration program to set up configuration files
* /usr/bin/im-config
This program provides stable GUI API for other programs
to interact nicely with im-config framework
* /etc/default/im-config
- Configuration files for the im-config default settings
* /usr/share/im-config/data/*.conf
- IM specific preset values selected by menu
7. Both user specific and system wide configuration files for the
im-config package via common im-config_setting are sourced as POSIX
shell scripts to perform 2 different tasks:
* Set Environment variables: called with "$IM_CONFIG_PHASE" = 1
* XMODIFIERS --- for XIM protocol
* GTK_IM_MODULE --- for GTK library
* QT_IM_MODULE --- for QT library
* ...
* Start daemon and GUI programs: called with "$IM_CONFIG_PHASE" = 2
* daemon --- provide XIM / dbus server
* GUI programs --- tray/ program etc.
If these configuration files are generated by the GUI/CUI im-config
program, they gave 3 lines like:
---
# im-config(8) generated on Sun, 30 Mar 2014 02:45:02 +0900
run_im ibus
# im-config signature: d57688c8151277a0c25d15aa0523da6b -
---
run_im function looks for corresponding file to its argument "ibus",
which is /usr/share/im-config/data/21_ibus.rc , and source it.
The shell comment line contains signature to allow detection of
manual modifications by /usr/bin/im-config which offers the menu
configuration system. The menu configuration system honors such
changes.
=======================================================================
! How To Configure Input Method with im-config
=======================================================================
If you wish to override system default,
For user configuration ~/.xinputrc, execute as:
$ im-config
For system wide /etc/X11/xinit/xinputrc, execute as:
$ sudo im-config
For system default:
$ sudo -e /etc/default/im-config
Under current GNOME, type im-config after pressing SUPER(Windows)-key
does the trick of starting the im-config GUI program.
The default input method (IM) mode of im-config was simple but is a bit
complicated now. Let me explain by going through its historical
evolution.
The IM_CONFIG_DEFAULT_MODE=auto choose the highest priority available
IM.
The IM_CONFIG_DEFAULT_MODE=none choose none of the available IM.
So the initial default IM mode choices were: auto, none
Since people setting CJKV locale environment may want auto mode while
people setting non-CJKV locale environment may want none mode, the
locale environment dependent automatic default IM mode
IM_CONFIG_DEFAULT_MODE=cjkv was added to choose auto or none based on
LANG environment variable value dynamically. Actual locales which
qualify are defined in CJKV_LOCALES variable.
With this, the default IM mode choices were: cjkv, auto, none
Since modern DEs such as GNOME (both classic X and new wayland)
integrate ibus as IM while providing panel GUI in its own desktop
environment, im-config hook scripts needs to be disabled for ibus on
such DEs. Such DEs to keep hands off are defined in DESKTOP_SETUP_IBUS
variable in the /etc/default/im-config.
DESKTOP_SETUP_IBUS='GNOME'
=======================================================================
! Extra features used by previous Ubuntu defaults
=======================================================================
The locale dependent package priority order override for auto mode is
provided via IM_CONFIG_PREFERRED_RULE variable in the
/etc/default/im-config.
For example:
IM_CONFIG_PREFERRED_RULE='zh_CN,fcitx5'
This means for zh_CN.* locale (LC_CTYPE), fcitx5 is chosen as the first
choice over normal ibus if both are installed. In order to keep package
priority of ibus over other IMs for DEs which integrate ibus tightly to
DE, DEs specified by DESKTOP_SETUP_IBUS (namely real GNOME) are excluded
to reorder using IM_CONFIG_PREFERRED_RULE.
Please note CJKV_LOCALES, DESKTOP_SETUP_IBUS, and
IM_CONFIG_PREFERRED_RULE can have multiple values. Some values can be
preceded by "-" to indicate exclusion. Please make sure to separate
them with ":" (colon).
=======================================================================
! How all these fit together
=======================================================================
none mode meaning:
~~~~~~~~~~~~~~~~~~
Do nothing for IM by im-config hooks and leave IM to desktop hooks.
If im-config interfare with new highly integrated desktop or any
fancy custom set up, this is what you want to set up.
auto mode meaning:
~~~~~~~~~~~~~~~~~~
This mode is default mode as installed.
Initialization system for the activated IM choice:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
ibus fcitx5, uim, SCIM
Desktop
GNOME NONE im-config hooks
MATE im-config hooks im-config hooks
KDE im-config hooks im-config hooks
LXQt im-config hooks im-config hooks
XFCE im-config hooks im-config hooks
Here, "NONE" means im-config framework does nothing for setting up IM
and leave such configuration to GNOME.
Although GNOME sets up itself for ibus, you can use fcitx5, too.
When set of ibus IM packages are not installed and set of fcitx5 IM
packages are installed as IM framework, fcitx5 accepts setting for ibus
to allow keyborad input.
Listing of GNOME in "$DESKTOP_SETUP_IBUS" defined in
/etc/default/im-config set GNOME for NONE via code in 21_ibus.rc.
If your Desktop becomes as integrated as GNOME, set im-config setting to
"none".
IM package activation priority order for auto mode:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Chinese (zh_*) Non-Chinese
Desktop
GNOME NONE NONE
MATE fcitx5 -> ibus ibus -> fcitx5
KDE fcitx5 -> ibus ibus -> fcitx5
LXQt fcitx5 -> ibus ibus -> fcitx5
XFCE fcitx5 -> ibus ibus -> fcitx5
Here, the higher priority IM is listed on the left side.
-- This is set by echo_auto_selected_im function of xinputrc.common file
using DESKTOP_SETUP_IBUS and IM_CONFIG_PREFERRED_RULE
defined in the /etc/default/im-config.
cjkv mode behavior (currently not used by default by any distro):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Debian Ubuntu Debian/Ubuntu
en/fr/... en/fr/... zh/ja/...
Desktop
GNOME NONE NONE NONE
MATE none auto auto
KDE none auto auto
LXQt none auto auto
XFCE none auto auto
-- This is set by CJKV_LOCALES, CJKV_DEFAULT_DESKTOP
in echo_cjkv_selected_im function of xinputrc.common file
-- This will be removed soon.
=======================================================================
! New input method support
=======================================================================
If you are interested to add a new input method support, please send me a
start up code as *.rc and its matching *.conf for /usr/share/im-config/data
by reporting to the BTS of the im-config package using reportbug(1).
*.rc files contain the start up code for the input method. It contains 2
parts:
IM_CONFIG_PHASE = 1 : export required environment variables to the programs
* launched via /etc/X11/Xsession.d/70im-config_launch for X and
* launched via /etc/profile.d/im-config_wayland.sh for wayland
IM_CONFIG_PHASE = 2 : daemon/GUI start up code called from im-launch
* launched via setting $STARTUP in /etc/X11/Xsession.d/70im-config_launch
for classic X system.
* via /etc/xdg/autostart/im-launch.desktop for wayland system
which is active only under wayland system.
*.conf files contain the definition of following variables and functions:
Variables:
IM_CONFIG_SHORT Short description of the im-config configuration.
IM_CONFIG_LONG Long description of the im-config configuration.
Sctipts are encouraged to use following internal variables.
IM_CONFIG_LC_CTYPE Practically LC_CTYPE/LANG
IM_CONFIG_CURRENT_DESKTOP Practically XDG_CURRENT_DESKTOP
Functions:
package_menu
return true if required packages exist for menu listing level: 00-89
package_auto
return true if required packages exist for auto selection level: 10-79
package_menu and package_auto use package_status function which returns true if
the package given in its argument is installed.
To test your proposed change, download the latest source by:
$ git clone --branch devel \
https://salsa.debian.org/input-method-team/im-config.git
Here, the "devel" branch is meant for everyone to commit changes. "master",
"upstream", and "pristine-tar" branches are used to record the uploaded
package by the maintainer with:
$ gbp import-dsc --pristine-tar ../im-config*.dsc
After above operation, I merge "master" branch to "devel" branch for
my easy tracking of changes on the gitk screen.
If you have debmake installed, you can make Debian package from "devel" branch
with:
$ make package
(I may move to use dgit workflow soon.)
=======================================================================
! Note on source structure
=======================================================================
This im-config package consists of 2 parts:
* run time -- hook & desktop as IM framework
* configuration time -- im-config (GUI/CUI) command
Here are summary of each file usages.
RUNTIME CONFIG
hook & desktop im-config
as IM framework command
share/initializer INCLUDED INCLUDED
share/xinputrc.common.in INCLUDED INCLUDED
share/im-config.common NOT-INCLUDED INCLUDED
share/im-config_setting INCLUDED not-used
data/*.rc (contents) used not used
data/*.rc (file name) used used
data/*.conf (package_auto) used used
data/*.conf (others) not used used
-- Osamu Aoki <osamu@debian.org>, Mon Mar 2 03:19:14 PM UTC 2026
# vim: set tw=72 sts=4 sw=4 ai si et:
|
