gnome-extensions

Caution

The legacy configuration format, which uses a part of the extension download URL to declare extensions to install, is still supported. However, it is advised to migrate to new configuration, since it offers the benefits of a clearer configuration & automatic installation of the latest extension version compatible with the GNOME version in the image. The new configuration format is showcased below in detail.

The gnome-extensions module can be used to install Gnome extensions inside system directory.
It also supports uninstallation as well, for extensions which are not installed through OS package manager.

This module is universally compatible with all distributions which ship Gnome, as it’s not tied to specific distribution packaging format for installing extensions.

Almost all Gnome extensions are compatible for installation.

Thanks to https://extensions.gnome.org which provides releases of extensions as zips, it is very easy to maintain this module configuration.

What does this module do?

• It checks the current Gnome version of your image
• It parses the extension name input from module recipe file
• It processes the jsquery from https://extensions.gnome.org using the extension name input,
  which contains useful info about latest extension version compatible with Gnome version of your image
• Download archive URL is formed based on the info above
• Downloaded extension archive is then extracted to temporary directory
• All of its extracted files are copied to the appropriate final directories
  (/usr/share/gnome-shell/extensions, /usr/share/glib-2.0/schemas, & /usr/share/locale)
• Gschema is finally compiled to include the copied extensions schemas to its database

Uninstallation step is performed similarly, except it obviously removes files from the mentioned final directories.

Usage

Extension Installation

By default, latest extension version compatible with Gnome version of your image, is installed.

How to install extensions using the module:

1. Go to https://extensions.gnome.org or preferably Extension Manager application
2. Search for the extension that you want to install and open its extension page
3. If browsing through https://extensions.gnome.org, select the correct GNOME shell version, which matches the GNOME shell version of your image
   • The command gnome-shell --version can be used to get the GNOME version of a running system. If there is no GNOME shell version of the extension that matches the GNOME version of your image, that means that extension is not compatible
4. Copy the extension name & input it in module recipe (it is case-sensitive, so be sure that you copied it correctly)

An extension might need additional system dependencies in order to function.
In that case, you should install the required dependencies before the gnome-extensions module is ran.
Information about the required dependencies (if any) are usually on the extension’s page.

Extension Uninstallation

Extension uninstallation can be useful to uninstall extensions from the base image,
which are not installed through OS package manager (like extensions installed from gnome-extensions module).

However, if extensions in the base image are installed through OS package manager, than they should be removed through it instead.

How to uninstall extensions using the module:

1. Go to Gnome Extensions app, https://extensions.gnome.org/local/ or Extension Manager application
2. List of installed system extensions should be presented
3. Copy the extension name & input it in module recipe (it is case-sensitive, so be sure that you copied it correctly)

Known issues

Some extensions use extension-only gschemas.compiled file location

This is a rarity, but some extensions might have this issue, due to the way they are programmed with hard-coded gschema locations.
Most extensions which follow Gnome extension standards don’t have this issue.

Standard location for global gschema.compiled file is:
/usr/share/glib-2.0/schemas/gschema.compiled

Those problematic extensions explicitly ask for this extension-only location instead:
/usr/share/gnome-shell/extensions/$EXT_UUID/schemas/gschemas.compiled

If you get the error similar to this one (Fly-Pie extension example):

GLib.FileError: Failed to open file “/usr/share/gnome-shell/extensions/[email protected]/schemas/gschemas.compiled”: open() failed: No such file or directory

Then please open the issue in BlueBuild Modules GitHub repo with the affecting extension, as it’s trivial to fix.
https://github.com/blue-build/modules/issues/new

Some extensions published in https://extensions.gnome.org are hard-coded to user locations

Those type of extensions are fixed to these locations (… indicates further folders):

• /usr/local/share/... (local system location)
• $HOME/.local/share/... (user location)

Those locations are not writable in build-time.

/usr/share/... is the standard location for system Gnome extensions, as outlined in “What does this module do?” section.

That means that the extension has build instructions for packagers to build the extension either system-wide or user-wide.

While some extensions might not have this limit even with the instructions above, some extensions might have.

GSConnect from https://extensions.gnome.org has this limitation & requires the system version of the extension to make it work successfully.
Those system versions are usually provided by the system packagers.

So the solution is to install the extension from system repository instead if available.

In this scenario, you will notice the extension error similar to this when trying to run it (notice the explicit request to /usr/local/share/... location):

GLib.FileError: Failed to open file “/usr/local/share/glib-2.0/schemas/gschemas.compiled”: open() failed: No such file or directory

Example configuration

type: gnome-extensions
install:
  - Night Theme Switcher
  - Blur my Shell # Notice how extension is named "Blur my Shell" & not "Blur My Shell"?
                  # Name is case-sensitive, so check if extension name is typed correctly
  - AppIndicator and KStatusNotifierItem Support
  - 307 # Dash-to-Dock
        # https://extensions.gnome.org/extension/307/dash-to-dock/
        # You can also specify PK ID number from the extension URL,
        # if you encounter the scenario where there are multiple extensions with the same name.
        # You don't need to look & search for this scenario, since module will automatically fail & inform you to put PK ID number instead
uninstall:
  - GSConnect # Uninstall step here should be used only for the extensions
              # which are not installed through OS package manager in the base image,
              # like extensions installed from gnome-extensions module

Configuration options

install: (optional array)

List of GNOME extensions to install. (case sensitive extension names or extension IDs from https://extensions.gnome.org/)

Possible values: undefined, undefined

uninstall: (optional array)

List of system GNOME extensions to uninstall. Only use this to remove extensions not installed by your package manager. Those extensions should be uninstalled using the package manager instead.