Debug fcitx5

Print logs

This is a common way to debug something that you can attach to it. FCITX_INFO() is a convenient macro for print out information. It is a thin wrapper around std::ostream. It supports not only all types supported by std::ostream, but also common Standard C++ containers and Fcitx own types such as fcitx::RawConfig, fcitx::Color, fcitx::Key, etc.

The logging with in Fcitx also provides log category so you may explicitly enable certain log only when you want to debug.

GDB or other debuggers

Debugging Fcitx is no different from debugging other C/C++ programs. The only thing that makes it special is that Fcitx is an input method and you need keyboard typing working to do runtime debug like gdb.

So, either you run gdb within an application that is input method disabled, or you want to disable certain addon that talks to your terminal.

Start an input method disabled terminal

1. Start a terminal with XMODIFIERS set to some random values, XMODIFIERS=@im=none xterm (or other terminal that uses XIM) 2. Within the xterm, start Fcitx that with correct XMODIFIERS. Fcitx will read the XMODIFIERS from the environment to set its own value, but right now xterm will have XMODIFIERS=@im=none, so you need to override it again to make it mismatch with XMODIFIERS value of xterm. That will make xterm fail to connect to the Fcitx XIM server.

Start Fcitx with certain frontend disabled

If your environment is set up correctly and you are using a Gtk/Qt based terminal, such as konsole/gnome-terminal, you can also start Fcitx with dbusfrontend disabled, so it will not talk to Gtk/Qt im module. gdb --args fcitx5 --disable=dbusfrontend -r

You should still be able to use a XIM application to test, such as xterm.

Start Fcitx within a nested X server

This special procedure is useful when you want to debug something that requires you to type a sequence of keys. This is because whenever you switch to a different window, the input method will receives focus out and that will commonly reset the state of input method. In that case, it may prevent you from reproducing the issue that requires a sequence of interactions.

Using a nested X server, such as Xephyr, will prevent the focus out event to be generated.

Xephyr :1 &
DISPLAY=:1 openbox & #Start a window manager
DISPLAY=:1 xterm & #Start a XIM application
DISPLAY=:1 gdb --args fcitx --disable dbusfrontend -r # Start Fcitx with dbus frontend disabled

Use fcitx test addons to reproduce the issue or write new test cases

By default, Fcitx will come with a few test addons that is designed to generate synthetic user interaction. fcitx::setupTestingEnvironment provides a easy way to setup required environment variables to run a special testing only fcitx instance.

Usually, you would need to create an event dispatcher to execute some code after Fcitx is initialized. You can check testunicode as a reference.

You may also want to explicitly enable only required addons to limit the testing scope.