The GNOME Shell extension design is designed to give a high degree of power to the parts of the GNOME interface managed by the shell, such as window management and application launching. It simply loads arbitrary JavaScript and CSS. This gives developers a way to make many kinds of changes and share those changes with others, without having to patch the original source code and recompile it, and somehow distribute the patched code.

The extension system is a replacement for the "applets" or "widgets" system of GNOME 2. Extensions can add their own items to the top panel, but they can also do much more: adding a custom search provider, for instance. For more information, see this post.

Available Extensions

There is a large collection of extensions at the GNOME Shell Extensions repository website. If you have a recent version of GNOME Shell (3.2), you should just be able to flip the switch on a compatible extension's page to turn it on. If you have any trouble, use the link at the bottom of the page to file a bug report.

Creating an Extension

First, you should get familiar with GNOME Shell's builtin developer console. It has a tab to show installed extensions, and any errors that occur while loading an extension are in the "Errors" tab. (Though later runtime exceptions are not yet caught).

GNOME Shell comes with an interactive extension creator, runnable from a Unix terminal. It starts you off with a sample extension:

gnome-shell-extension-tool --create-extension

The beginnings of a FAQ dealing with how to do various extension-related things in Javascript is available here.

Anatomy of an extension

When creating an extension, you must pick a uuid. This is a globally-unique identifier for your extension, similar in form to an email address, but need not be an actual email address. An extension, when installed on the filesystem, is a directory whose name is the same as your extension's uuid. In order to prevent certain attacks, the uuid must follow guidelines. See UUID Guidelines for more information.

Inside the directory, the bare bones of an extension are two files, metadata.json and extension.js. The content of a metadata.json looks like this:

  "uuid": "myextension@myname.example.com",
  "name": "My Cool Extension",
  "description": "Make windows burst into flame",
  "url": "http://example.com/~myname/myextension",
  "shell-version": [ "3.2.2" ]

The extension.js file is simply a JavaScript file; it must however have a function called init, which will be invoked at most once directly after your source JS file is loaded. You should modify all user interfaces in a separate enable function, and remove all custom functionality in a disable function. For more information, see Finnbarr's post on updating GNOME Shell Extensions to 3.2.

You may optionally include a stylesheet file, stylesheet.css.

So an extension will typically look like this:


Extension Preferences

Since version 3.3.5, Extensions may be configured in a consistent manner using the gnome-shell-extension-prefs tool. To hook into it, provide a simple javascript file called prefs.js. It must contain a function labeled buildPrefsWidget, which should return some sort of GTK+ widget. Whatever is returned from there will be inserted into the Preferences widget screen. Beyond that, a function named init may also be provided, and will be invoked after the file is loaded but before buildPrefsWidget is invoked.

Writing an extension

There is now a comprehensive overview of writing a Shell extension on the Writing page.

However, writing a Shell extension covers many topics; you will want to see Development at a minimum. Specific to extensions, you will likely employ two primary techniques for hooking into the shell core.

  • GObject signals: For controlling the user interface, hooking into signals is flexible and non-destructive.
  • Monkey patching

There are also several older tutorials that may be of some help:

Extension installation locations

Extensions can be installed per-user in ~/.local/share/gnome-shell/extensions, or systemwide in /usr/share/gnome-shell/extensions and /usr/local/share/gnome-shell/extensions.

Viewing installed extensions

Enabling extensions

  • You can enable and disable extensions on https://extensions.gnome.org/local/

  • Per-user and systemwide extensions have to be enabled before they can be used. You can do this with the GSettings key, org.gnome.shell.enabled-extensions, or several tools that manipulate this GSettings key, such as GNOME Tweak Tool or a recent version of gnome-shell-extension-tool.

  • For code changes to become effective, you need to reload the GNOME Shell by pressing Alt-F2 and entering r.

Uninstalling extensions

Debugging extensions

On systemd-based systems (like Debian), you can see error and log output of extensions using journalctl /usr/bin/gnome-shell -f. On other systems, logs might be written to ~/.xsession-errors.

You can log messages from an extension into this log for informational or debugging purposes using log(msg).

Projects/GnomeShell/Extensions (last edited 2019-05-16 00:11:18 by AndyHolmes)