GNOME: Manage extensions
Mats Tage Axelsson takes you on a tour through the inner workings of the GNOME extension system.
Mats Tage Axelsson takes you on a tour through the all the details of Gnome extensions – finding them, installing them and even how to build your own.
Let’s dive into Gnome extensions! Gnome is a big system, so it’s worth understanding which parts do what. The main pieces are
Glib, GTK+ and Gnome-shell. Glib contains all the core libraries for developing Gnome applications. These libraries are divided further into I/O handling, text handling and even a webkit2 interface to handle web browsers and other similar jobs.
GTK+ is the graphical user interface toolkit. With it you design the user interface and connect to the Glib library. This toolkit has official bindings to Gnome for C++, Python, Vala and of course Javascript, so if you plan to make full applications for Gnome, you’re already on your way. Gnome Shell is what is truly interesting to us. It is the part that provides functions to switch windows, launch applications and see notifications. It also creates the Top Bar, this is where you can see most extensions. Some just change the behaviour of Gnome, but the interesting ones are on the Top Bar.
Gnome-shell is written mainly in Javascript using bindings to the underlying layers. This is why, as we’ll see later, all extensions are written in Javascript accessing a number of classes. When you get serious about Gnome development, you will learn the details of Mutter, Clutter and Opengl. These are lower in the stack and support all your code. However, when you create extensions you only need to know the Javascript classes that are in the Gnome-shell code.
Most of this tutorial is about how to handle existing extensions, but you may want to follow along with the development example at the end. You just need the latest Gnome Desktop and, if you are so inclined, an IDE for Javascript.
Getting started
The Gnome extension framework is actually a Javascript class designed to interface with the parts of Gnome. This is why you need an IDE for Javascript; the most relevant choice is Builder. This is developed specifically for Gnome but you can also set up your favourite Javascript workflow. In Emacs, you are well advised to install and use Jslint. The main class is part of the standard install and will be called upon by any extension you write.
There are three ways of adding extensions: using the GNOME website, using the package manager, or creating your own. The latter also applies to use extensions from Git-based sources and the like. Gnome has its own website for extensions at https:// extensions.gnome.org, so you should start looking there. There are thousands of extensions. If you scour the internet, you can also find extensions hosted on Github or people’s own websites – though you’ll need to be wary about installing insecure packages. Most of the time, though, the extension developers have a website that redirects you to GNOME’S own site. When creating your own, you have the option of using ready links that come with Builder. You can also use any Git-based solutions.
The two standard ways of installing an extension are to use the package manager or https://extensions. gnome.org. The tweaks package also has support for listing extensions and will hand you over to the software centre to remove any extensions.
The software centre sets your local extensions – this means that you are the only one that can use them. On most systems you are the only user anyway, but this also affects upgrades. A local extension will not be upgraded by your package manager, so you need to be aware of this.
If you have the correct extension for your browser –
Chrome or Firefox – you can install it right there in the browser. You also have a list where you can change
settings and remove extensions. If your browser doesn’t support the GNOME page, you still have options. You can download the extension: the standard format is a packed file that you unpack into your extensions directory. Some extension archives are not named the way the directory should be named, so you may have to create it. For example:
$ mkdir vim-alttab@kokong.info
$ cd vim-alttab@kokong.info
$ unzip ~/Downloads/vim-alttabkokong.info.v1.shellextension.zip
Now you can activate the extension in tweaks or the gnome-shell-extension-prefs. Have patience though – it does not always show up immediately. The safest bet is to log out and log back in. If you start from a terminal, you can see the install log, helping you to identify problems. One of the directories where you have extensions is under the ‘local’ user (~/.local/ shared/gnome-shell/extensions). This is where you have your own extensions – each user has their own.
System extensions are stored elsewhere in /usr/ share/gnome-shell/extensions/. The documentation mentions /usr/local/share/gnome-shell/ extensions, but this is not usually used by distributions. Here you will see all extensions that you have installed by default during the distribution’s install or upgrade. You can also see the others that you have added using your package manager.
Other directories that you need to be aware of are for error log files. Seasoned Linux users may look for
~/.xsession-errors. Before you use it, check the date when it was last modified, as GNOME has discontinued use of this file. With Systemd, though, you can check everything with journalctl:
$ journalctl /usr/bin/gnome-shell
You can scroll and search the resultant output vimstyle. The log file itself you can find in /var/log/syslog.
This is a common file for the whole system, which is why it’s better to use systemd to do the filtering.
Earlier, we found and downloadthe vim-alttab@ kokong.info extension and unpacked it. Look inside it: the files that an extension needs are determined by a standard. The minimum required files are metadata. json and extension.js. They are also packed as a zip file and installed to one of the mentioned locations.
Once installed, there is one directory for each extension. The alttabkokong extension has the two files README.MD and COPYING. The reason is that the extension only adds a few keys to the standard, so it needs only a single Javascript file. When you have an extension with a few more features, there will naturally be more files. Good practice is to have an icons directory for your icons, a locale directory for languages and a schemas directory for any settings the extension needs.
Now examine what the main files do. The file that defines the extension is metadata.json. One simple but powerful extension is Argos, and its metadata.json
looks like this:
{
“_generated”: “Generated by Sweettooth, do not edit”,
“description”: “Create Gnome Shell extensions in seconds”, “name”: “Argos”,
“shell-version”: [
“3.32”
],
“url”: “https://github.com/p-e-w/argos”, “uuid”: “argos@pew.worldwidemann.com”, “version”: 3
}
Each developer needs to choose a globally unique identity for the uuid value. Most likely, you will use the name of the Git server where you host it to create your unique value.
The next required file is extension.js. Here you decide what should happen when you initiate, enable and disable the extension. For clarity, the functions you put in there are named exactly that. Any code that is needed, you just add to the code. If the extension uses preferences then you need to also add prefs.js. This is where you design your preferences widget and set all preferences that the extension needs. If you don’t include it, the extension will still work, but without a preferences window. The file contains an initialisation and a widget builder section.
When you install a new extension or have created one yourself, you need to check it for stability. One important aspect to consider is that any extension executes as a class inside gnome-shell. This means that an extension can stop you from successfully logging in to the desktop. To counter this, you need
to be prepared to use a virtual console to solve problems. If you cannot solve it, you can remove the extension by moving it out of the extensions directory. Open a terminal and list the log:
$ journalctl -f -o cat /usr/bin/gnome-shell
If you are still running the regular desktop, you can see this info with the same command. You also have some other options. One is to use a command line to start the preferences program. The output of gnomeshell-extension-prefs shows the Js-log about gnomeshell, which can help. For example, you can see which extensions are installed twice and if an extension does not start, some details may show up here.
You also have Looking Glass at your disposal. To start this, use the command interpreter with the Alt+f2 keyboard shortcut. Looking Glass opens with the Evaluator window open. You have two more windows; Windows and Extensions.
The Evaluator window is a Javascript console where you can run simple scripts. Windows shows the windows, where you can see what classes exist and what each window can do. Open it and click a window name to see all classes that are available. In the Extensions window, you can see all extensions, check for errors and follow a link to the source code. There is also a link to the web page for the extension. This is a great way to get started correcting any faults.
Extensions can be installed as local, for your user only, or as system extensions. The differences aren’t that relevant on a personal system, but it can help to know them. System extensions are ones you installed with the package manager or manually to the /usr/ share/gnome-shell/extensions/ directory. This is important when you start looking at how they behave and when you have performance issues. During start-up start, Gnome looks in your /home directory and ignores the second copy in your system directory. This way you can change an extension for one user before you set it as the default for the system.
If you want to make your own extension, you need some programming skills. Javascript is the most useful language to use. You can use C for much of Gnome, but for extensions, you’ll want to stick to Javascript. To start a new extension project, use the built-in command-line tool:
$ gnome-shell-extension-tool --create-extension
This tool asks you for the name of your extension. Make it short, as it will show on the Top Bar. The script creates an extension directory with the basic files you need to get started. When the script finishes you are presented with the builder, which opens extension.js.
You can also open it in another editor or IDE.
The default extension is a ‘Hello world’ one which you should be able to start immediately by calling gnome-shell-extension-prefs. You will need to change this code, of course, and one way to go about this is to use other peoples’ code. Find an extension, download it and have a look at the code. Copy some of it and modify, give the original developer acknowledgement and you’re good to go.
When you examine the sample code that is created, look for the mandatory parts: init() , enable() and disable() . These three must always be in the code, but it’s up to you to decide what happens in these functions. If you do it wrong, you may not be able to log in after you have added the extension – see the earlier description for how to fix that.
You may want to test some changes, but before you do, make sure you can see what is happening. Open a separate terminal and use journalctl to keep track of events, like this:
$ journalctl -f -o /usr/bin/gnome-shell
The f option indicates that all logging information should be output to this screen. At the top of the code, you can see the all-important imports. These get the functions you need to build your extension. Start with the top imports, const St = imports.gi.st and const
Main = imports.ui.main – the code uses this in the
_showhello() function. function _showhello() { if (!text) { text = new St.label({ style_class: ‘helloworld-label’, text: “Hello World!” }); Main.uigroup.add_actor(text); }
The label call is included in the Shell Tool ( St ) package, but you can use many others. Definitions are available in the documentation at https://developer. gnome.org/st/stable. Next, you see Main.uigroup. add_actor , which adds an ‘actor’. Everything that happen in Gnome code has a ‘stage’ and an ‘actor’. The stage is the desktop or a window hosting an application. In this code, the actor is a text. The object text has a number of functions available.
Immediately below, the opacity function sets the opacity of the text. To place the text you use the set_ position function. Since you want to put it at the correct place on the screen, the code fetches the layoutmanager.primarymonitor function that contains the data about the monitor. When the code sets the position, it will use monitor 0.
At the end of this function, the code uses Tweener functions to control the animation. Tweener is built for Actionscript 2 and 3, but is easy to import and use for Gnome. It acts as a bunch of methods that you can run on other objects. The methods are there for animating transitions depending on the state. The documentation is available at http://bit.ly/lxf258tweener.
Read and adapt
A simple example is the pop-up menu code in the Gnome shell extension reference on Github. This code is heavily commented and an excellent resource. You can use it to understand the concepts that you need to use for your own projects. In the Popupmenu example (http://bit.ly/lxf258extension), you can see what each library does in one sentence. This makes it easier to find what you may be looking for.
You see that Shell Tools ( imports.gi.st ) is for you to create UI elements, and Clutter is to create the layout. This also shows that Main ( imports.ui.main ) is the instance where everything is – the root, if you like, where all other elements are created. Because it is very common to have them, Panelmenu and Popupmenu also exist as a method that you can add features to.
Further down, you are invited to program using object-orientated methods. The first thing is to import lang ( imports.lang ) to make classes available. Here, you also see what a class is made of. Mandatory parts are Name: , the same as the class name, while Extends: points out the class you are extending. The two main functions are _init and _destroy . Note the underscores in the name of these functions that are used to distinguish them from the init function of the entire extension.
With the example at http://bit.ly/lxf258keeper, you are quickly introduced to the Glib and Gio libraries that help you access files. The Gda libraries are also available for data sources including databases, LDAP directories and mail servers. Here you can also see that the main loop is a major concept in Gnome. This is where all events are handled for Glib and GTK+, and it is how you interact with everything else in Gnome.
The code also uses the clipboard from the Shell Tools, showing just a single case of what you can do with these useful tools. You can also see how the extension uses the Gda.connection functions to handle a database. In the _setupdb function, you pick the provider and the strings for using a database, open a database and handle data in it. Going through welldocumented code while comparing to what the documentation says is an excellent way to get acquainted with any architecture.
Since you are looking at Gnome extensions, you are probably interested in making your desktop look good. There are many themes to download for Gnome; a
Gnome-shell theme is just a CSS file so you can open any and check out how it works. You can of course pick any theme and start changing it around. The most important part is ‘stage’ – all the others are aptly named classes.
Extensions in Gnome are powerful tools that can produce notifications, start applications and tweak the behaviour of the desktop. They can also be a curse, disturbing your own focus, causing instability of the system and lowering performance.
With this in mind, choose your extensions wisely and be prepared to ditch them when problems occur. Don’t let these warnings discourage you from exploring their potential, though – as long as you follow the advice, Gnome is a great productivity tool.