# Debugging
# Basic Debugging
Some distributions may require you to be part of a
systemd
user group to access logs. On systems that are not usingsystemd
, logs may be written to~/.xsession-errors
.
Basic debugging and logging is an important part of developing any software. GJS has a number of built in global functions, although not all of them are useful for extensions.
# Logging
// Log a string, usually to `journalctl`
log('a message');
// Log an Error() with a stack trace and optional prefix
try {
throw new Error('An error occurred');
} catch (e) {
logError(e, 'ExtensionError');
}
// Print a message to stdout
print('a message');
// Print a message to stderr
printerr('An error occured');
2
3
4
5
6
7
8
9
10
11
12
13
14
15
When writing extensions, print()
and printerr()
are not particularly useful since we won't have easy access to gnome-shell
's stdin
and stderr
pipes. You should generally use log()
and logError()
and watch the log in a new terminal with journalctl
:
$ journalctl -f -o cat /usr/bin/gnome-shell
# GJS Console
Similar to Python, GJS also has a console you can use to test things out. However, you will not be able to access live code running in the gnome-shell
process or import JS modules from GNOME Shell, since this a separate process.
$ gjs-console
gjs> log('a message');
Gjs-Message: 06:46:03.487: JS LOG: a message
gjs> try {
.... throw new Error('An error occurred');
.... } catch (e) {
.... logError(e, 'ConsoleError');
.... }
(gjs-console:9133): Gjs-WARNING **: 06:47:06.311: JS ERROR: ConsoleError: Error: An error occurred
@typein:2:16
@<stdin>:1:34
2
3
4
5
6
7
8
9
10
11
12
13
# Recovering from Fatal Errors
Despite the fact that extensions are written in JavaScript, the code is executed in the same process as gnome-shell
so fatal programmer errors can crash GNOME Shell in a few situations. If your extension crashes GNOME Shell as a result of the init()
or enable()
hooks being called, this can leave you unable to log into GNOME Shell.
If you find yourself in this situation, you may be able to correct the problem from a TTY:
Switch to a free TTY and log in
You can do so, for example, by pressing
Ctrl
+Alt
+F4
. You may have to cycle through theF#
keys.Start
journalctl
as above$ journalctl -f -o cat /usr/bin/gnome-shell
1Switch back to GDM and log in
After your log in fails, switch back to the TTY running
journalctl
and see if you can determine the problem in your code. If you can, you may be able to correct the problem usingnano
orvim
from the command-line.
If you fail to diagnose the problem, or you find it easier to review your code in a GUI editor, you can simply move your extension directory up one directory. This will prevent your extension from being loaded, without losing any of your code:
$ mv ~/.local/share/gnome-shell/extensions/example@shell.gnome.org ~/.local/share/gnome-shell/