Documentation for writing GNOME Shell extensions

Question

I've been asked to customise the layout of the GNOME 3 desktop. Apparently the way to do that is by writing an "extension".

I've managed to do some of the things I wanted to do, but I feel utterly starved of information. I cannot find any useful documentation anywhere. I've wasted entire days of my life frantically googling every imaginable search term in a desperate attempt to find useful information.

The GNOME website has hundreds of extensions for download. These are not trivial 3-liners; they're sophisticated pieces of code. It defies belief that anybody could write these without documentation explaining how to do it.

Please, can somebody tell me where the actual documentation is? So far, the best I've managed to do is take apart existing extensions trying to track down the magic command that does the specific bit I'm interested in. (Not an easy task!)

Command names, object paths, example programs, anything would be helpful!

Answer 1

An extensive list of references can be found on the Gnome Developer - API Reference page.

I used the following for my extension, but your use may vary:

• GTK+ 3
  GTK+ is the primary library used to construct user interfaces in GNOME applications. It provides user interface controls and signal callbacks to control user interfaces.

• GDK 3
  GDK is an intermediate layer which isolates GTK+ from the details of the windowing system.

• Clutter
  Clutter is a GObject based library for creating fast, visually rich, graphical user interfaces.

• GObject Introspection
  GObject Introspection is striving to provide a middleware layer between (GObject based) C libraries and language bindings.

• Shell
  Shell Reference Manual

• St
  St - Shell Toolkit - is the GNOME Shell's custom Clutter-based toolkit that defines useful actors. Some of these actors, such as StBoxLayout and StBin implement various layout options.

• Icon Theme Specification
  This freedesktop.org specification describes a common way to store icon themes.

NOTE: These last two are very helpful in finding visual element parameters!

• PyGTK
  PyGTK is GTK+ for Python. This reference contains a chapter for each Python PyGTK module (that corresponds to the underlying GTK+ library) containing the class descriptions.

• PyGObject
  PyGObject is a Python extension module that gives clean and consistent access to the entire GNOME software platform through the use of GObject Introspection. Specifically speaking, it is Python Bindings for GLib, GObject, GIO and GTK+.
  This reference contains a chapter for each PyGObject module containing the class descriptions.

Answer 2

I have recently dug into it myself. The documentation is usually sparse or outdated. Here are some sources which helped me to get started (and through development):

• Basic Stuff
• Basic stuff on development
• Step-by-step tutorial
• Unofficial documentation for the JavaScript bindings of many libraries
• The sources of the gnome-shell's JavaScript bindings
• Explanation of the St (Shell Toolkit) Ui-Toolkit components.
• Some unofficial guidelines to get your extension on extensions.gnome.org

Since the documentation is nearly unavailable (or up to date), you'll need to do a lot of source-reading. I linked the gnome-shell sources above (the JavaScript part) which is a good start when diving into parts that are not covered by the In-official documentation (which is the most complete thing you'll find).

What's also particular helpful is checking extensions.gnome.org for extensions which do similar things to what you want to create, and look at their sources (most of them are open-source on GitHub or Bitbucket. You can also install them and find the sources under ~/.local/share/gnome-shell/extensions/).

When searching for something to use or more documentation on a particular function, you can also consult manuals for bindings in different languages (thought the parameters and return-values might not match).

---

Last but not least, here is some debugging advice:

LookingGlass is not particularly helpful. It only shows one line of an exception (the description) and only if they occur at startup time (when your extension is first started).

For full StackTraces and runtime-exceptions, consult the ~/.xsession-errors-file. It might be very long and bloated. I use this handy script to read it:

# Grabs the last session-errors from the current X11 session.
# This includes full Stack-Trace of gnome-shell-extension errors.
# See https://live.gnome.org/GnomeShell/Extensions/StepByStepTutorial#lookingGlass
tail -n100 ~/.cache/gdm/session.log | less

Note that since Gnome 3.6, if you are using gdm as display manager, the current session log is the file ~/.cache/gdm/session.log.

On some newer distros using systemd, you can get the error logs with:

journalctl -f /usr/bin/gnome-session

For debugging the prefs-part of your extension, you can launch the preferences by using the gnome-shell-extension-prefs-tool from a terminal, to see any exception-output on the console (you can also call the tool like gnome-shell-extension-prefs [uuid], to directly show your extensions preferences).

Since there is currently no real way of debugging with breakpoints (there is, but it's tricky), you can log on the console for quick checking, use the print()-function. You will see the output as mentioned above (either in the sessions-error file or on the terminal when starting gnome-shell-extension-prefs-tool).

---

Although it might be a little hard to get into it, the extension framework is quite powerful. Have fun!

---

I wrote a Blog-Post with somewhat greater detail, which can be found here: Making Gnome-Shell Extensions