Customizing the GNOME Shell menu

The GNOME Shell (GNOME 3) menu, is customized using the alacarte application.  Install this application if you wish to edit the menu.  If you want to know more about how the menu works in order to write a script to manage it, or do things that alacarte can’t do, then read on.

The freedesktop standard:

The GNOME shell menu is based on the standard freedesktop menuing system, which has 2 levels of abstraction:

– The menu “layout”, specified in .menu files (XML format).
– The menu “content”, specified in .directory (sub-category) and .desktop (item or “launcher”) files. .directory and .desktop files are both in config file format, and similar in content.

In GNOME shell, the menu is accessible under Activities.  There is only 1 menu (called Applications).  Menu sub-categories may not be enabled, they may appear on the right of the menu items, or they may be enabled using a GNOME shell extension.

Update: Menus also support “folders“.  Rather than configuring this in the .directory files themselves, there is a dconf setting org.gnome.desktop.app-folders folder-children, that controls which sub-categories are actually folders.

The file system:

The default “all users” menu can be found in:

– Layout: /etc/xdg/menus
– Content: /usr/share/desktop-directories and /usr/share/applications (per $XDG_DATA_DIRS)
The default menu is constructed from files included in each individual installed application package.

For custom / user-specific menus, the local override is:
– Layout: ~/.config/menus
– Content: ~/.local/share/desktop-directories and ~/.local/share/applications (per $XDG_DATA_HOME)
Menu customization files are managed by the alacarte application.

Update: Package applications such as Flatpak and Snap add locations to the $XDG_* environment variables.

This is roughly how the menu is built in memory:

  • The default .menu files specify the main menu, and the .directory files to use for sub-category labels etc.
  • They also specify which .desktop files to use for sub-category content using a filters (search) mechanism that specifies the “Categories” they belong to.  Basically, .desktop files contain a line listing Categories they belong to, and they are included in sub-category listings based on the filter for each sub-category.  For example, the “Office” sub-category contains all .desktop items that list “Office” as one of their Categories.
  • Then the user-specific .menu files specify overrides to the default menu – they actually say things like exclude, include, and move, meaning “take the default menu, and make the following changes to it” (called a “merge” strategy).
  • Finally, user-specific .directory and .desktop files override the default content.  These local files are basically copies of the originals, but with local customizations.

Changes to .desktop files are reflected instantly; changes to .directory and .menu files require a restart of the GNOME Shell.  The menu build appears to be very fault-tolerant, resorting to the default content of an item or sub-category whenever an error (such as file not found) is encountered.

The menuing system actually centers around the .desktop files.  Each application installation package provides one of these files to essentially “register” the application in the system.  The same .desktop files are also used in application launchers outside the menu, such as the dash favourites, and the gnome session (applications automatically launched when you log in); see files in ~/.config/gnome-session/saved-session, /etc/xdg/autostart and ~/.config/autostart.

This setup is both centralized and flexible, but has some drawbacks.  Mainly:

  • Custom / user-specific .desktop files are copies of the original files, modified as needed.  This means that if the original .desktop files are updated during package updates, then the changes in those files are not reflected locally.  So for example, if you customize a menu item label, then alacarte creates a copy of the .desktop file, makes 1 modification to it, and because of that, future updates to say, the tooltip for the application, will not be applied.
  • alacarte doesn’t currently support all the features of the menu, so only simple changes can be made using the GUI tool.  For advanced customization, use your text editor.
  • alacarte doesn’t always make changes in the most efficient manner, so you’ll often find multiple .desktop files for the same application, reflecting multiple changes that you’ve made over time.
  • alacarte doesn’t offer a command-line interface, and I haven’t seen any other option to help with scripting.

Menu sharing:

A common question is how to set up a custom “all users” menu for systems that have multiple users.  The typical solutions are:
1. Modify the default menu files.  The main drawbacks to this are:
– Requires root access to maintain the menu
– Changes can only be made manually, as alacarte won’t help with this
– Running something like rpm -V will result in errors
– Accordingly, package updates will behave unpredictably
– I would only use this option if the changes planned are very minor
2. Create a custom menu somewhere centralized (eg, /usr/local/menu):
– Requires root access to maintain the menu
– Changes can only be made manually, as alacarte won’t help with this
– Package updates won’t be reflected in the custom menu (although symbolic links can be used to slightly mitigate this for files that aren’t customized)
– Requires a change in each user’s environment variables ($XDG_*) to let GNOME know where the custom menu is
– This option makes sense if the menu is very custom

Leave a Reply

Your email address will not be published. Required fields are marked *