Gnome Desktop Entry Format extensions - bootlegged documentation

gnome-session-documentation.md

Gnome Desktop Entry Format extensions - bootlegged documentation

Note: if you work on desktop entry files, you should refresh them to see the results: Alt-F2 and run 'r' or 'restart' to restart gnome-shell. Otherwise changes might only work after you log out.

The desktop entry specification creates a standard for application launchers. Gnome adds several extensions to the format which are widely in use, but as far as I can tell undocumented. This is an attempt to document them so I can write my own autostart launchers for gnome. Pull requests are highly welcome.

There is a guide on gnome developer that explains basics about how to integrate an application with the desktop.

Autostart applications run when the user logs into the graphical desktop environment. All desktop managers make custom extensions to the format. This attempts just to cover the Gnome extensions, and won't repeat anything said in the autostart standard or the startup notification protocol.

Currently I have found code using these extensions in gnome-session. The following is what I have been able to determine from examining the source code. Definitions for the different extensions were found here. After writing most of this, I found this link which explains quite some things about autostarting and gnome-session rationale.

Gnome Session Manager logs information to the systemd log. It logs the following information (not exhaustive):

• When it starts an autostart app
• When it fails to start an autostart app
• When it can't stop an application in order to restart it
• When it skip's an application that is disabled by a condition
• Once the startup is successful, GSM will log: "Entering running phase"
• When it add autostart apps from directories

Note that other than .desktop, there are also .session and .directory files.

X-GNOME-Autostart-enabled

This seems to imply that this is deprecated. In any case it looks as if the Hidden property described in the autostart standard provides the same functionality.

X-GNOME-Autostart-Phase

The following phases are recognized by gnome-shell:

• EarlyInitialization
• DisplayServer
• Initialization
• WindowManager
• Panel
• Desktop
• Anything else, inlcuding a missing X-GNOME-Autostart-Phase property is considered to be in the "Application" phase.

I found a README explaining the different phases. Startup is divided into 7 phases (GsmManagerPhase):

• GSM_MANAGER_PHASE_STARTUP covers gnome-session's internal startup, which also includes starting gconfd and dbus-daemon (if it's not already running). Gnome-session starts up those explicitly because it needs them for its own purposes.
• GSM_MANAGER_PHASE_EARLY_INITIALIZATION is the first phase of "normal" startup (ie, startup controlled by .desktop files rather than hardcoding). It covers the possible installation of files in $HOME by gnome-initial-setup and must be done before other components such as gnome-keyring use those files.
• GSM_MANAGER_PHASE_INITIALIZATION covers low-level stuff like gnome-settings-daemon and at-spi-registryd, that need to be running very early (before any windows are displayed). Apps in this phase can make use of a D-Bus interface (org.gnome.SessionManager.Setenv) to set environment variables in gnome-session's environment. This can be used for things like $GTK_MODULES, $GNOME_KEYRING_SOCKET, etc
• GSM_MANAGER_PHASE_WINDOW_MANAGER includes window managers and compositing managers, and anything else that has to be running before any windows are mapped
• GSM_MANAGER_PHASE_PANEL includes anything that permanently takes up screen real estate (via EWMH struts). This is the first phase where things actually appear on the screen.
• GSM_MANAGER_PHASE_DESKTOP includes anything that draws directly on the desktop (eg, nautilus).
• GSM_MANAGER_PHASE_APPLICATION is everything else (normal apps, tray icons, etc)

The Gnome Session Manager is aware of a few other phases as can be seen here, but I don't think you can use them in autostart launchers:

• GSM_MANAGER_PHASE_RUNNING
• GSM_MANAGER_PHASE_QUERY_END_SESSION
• GSM_MANAGER_PHASE_END_SESSION
• GSM_MANAGER_PHASE_EXIT

X-GNOME-Provides

Allows applications to define a mutually exclusive role. Eg. if one application manages the desktop, a second one shouldn't be started with the same role. Common values are:

• panel
• windowmanager
• filemanager

I found more in depth documentation for required components.

X-GNOME-Autostart-startup-id

X-GNOME-Autostart-Notify

Maybe related to the standardized StartupNotify?

X-GNOME-AutoRestart

I have the impression that this means that if the application dies, it will be restarted automatically, much like the desktop manager gets restarted when it craches.

X-GNOME-DBus-Name

X-GNOME-DBus-Path

X-GNOME-DBus-Start-Arguments

X-GNOME-Autostart-discard-exec

From what I can gather here, it seems this is used by gnome-session internally in order to clear saved session data for applications after they have relaunched on login.

X-GNOME-Autostart-Delay (This one I found in Cinnamon-session of linux Mint)

X-GNOME-DocPath (Found in a gnome admin guide)

Specifies the help file to display when you choose Help on application-name from the menu item popup menu.

X-GNOME-Bugzilla-Bugzilla

X-GNOME-Bugzilla-Product

X-GNOME-Bugzilla-Component

X-GNOME-Bugzilla-Version

X-GNOME-WMName

X-GNOME-WMSettingsModule

Other keys that aren't gnome specific

Autostart-condition

The proposal for this key on the xdg mailing list.

StartupWMClass

Probably refers to the property that can be inspected with xprop. This property allows keeping the connection between running applications and their desktop files. You can check the window class of an application by running xprop and clicking on it's main window. For example if the program has an icon in it's executable alt-tab might show that icon rather than the one in your desktop file. It might also group different programs together wrongly like all java applications. Running a goolgle search for "gnome3 dash StartupWMClass" brings up quite some results. On certain applications you can add the --class command line argument (eg. firefox, and supposedly gtk apps) in order to separate the alt-tab icon.

Dependency of any of these extensions on a particular version of GNOME should be noted, so users avoid disappointment while trying to implement them in their .desktop files.

There are a lot of powerful extensions, something the Freedesktop spec seems to allow "X-something-something=y", but it should seriously be documented if they want developers to fully embrace Shell/GTK etc! GNOME 3 is now very good IMO, moves forward quickly still, so there are differences from Fedora 29 and Ubuntu 18.04 for instance, usually for the better now, finally.

Doing a clean install of Ubuntu 18.04, choosing "Minimal installation", excellent addition by Ubuntu, so I can use time to install stuff instead of uninstall lots of stuff and install stuff anyway, I ran "Ubuntu GNOME" 16.04 LTS, which if not was an official flavor, always officially pointed to at least, but now since Ubuntu uses GNOME 3 it isn't needed anymore, but the projects many leftovers gave Ubuntu developers a much easier transition. There are still traces like the GDM logo saying "Ubuntu GNOME" and the file name as well.

There are many BAD guides out there telling you how to get a "Vanilla GNOME" experience on Ubuntu, and most of them are basically just adding a GNOME Session and changing the GDM background, like this one.

Ubuntu's default installation I have just tried in a VM and before installing. Do not see any reason to use it over GNOME Vanilla THB, they should rather contribute to that, say collaborate to make a perfect macOS Dock, so stable so it can be an option in the Control Center, not just in GNOME Tweaks.

Think I used some guide to be sure, at least found the package vanilla-gnome-desktop on packages.ubuntu.com from comments, which does all the work basically. Replaces those Ubuntu mods you don't want like splash, colors, theme etc with stock GNOME. Some stupid GNOME packages gets installed like "Documents", "Calendar" (and not to forget "Weather", come on, web browser and my country's excellent state meteorology page > stupid simplified mimick iOS app), too-simple apps, only slightly useful for viewing if connecting a Google account for instance, but various of those are in the full Ubuntu installation also so.... Option splash removed in /etc/default/grub as always, and of course since with crazy fast right on motherboard NVMe it boots in 2 seconds even with excellent full featured in kernel amdgpu, just as fast as the Intel iGPU with fastboot option kernel option set...

So basically:

• Boot new installation with Ethernet cable connected.
• Do NOT log in so a lot of Ubuntu-only "crap" you'll later remove will be will be put in dconf and ~/.config dirs etc.
• Go to TTY with Ctrl + Alt + F1 and log in to CLI.
• Add proposed repo to APT, it has never caused any problems, just newer and better kernels and software, by adding to /etc/apt/sources.list = deb http://no.archive.ubuntu.com/ubuntu/ bionic-proposed multiverse main universe restricted (replace no with your country code).
• Update system even if done during installation, new packages will be in proposed, apt clean && apt update && apt dist-upgrade
• Install apt install vanilla-gnome-desktop.
• While your at it why not apt purge the packages that was installed and you don't want and doesn't uninstall other packages you want, and apt --purge autoremove afterwards of course, a power user would probably get rid of several annoying things like apport or at least disable it in /etc/default/apport. Disable Systemd services with systemctl disable x.service if you want the package but don't need a background service running all the time without any reason, like openvpn.service, or uninstall if not needed and not depends on other packages you want or critical system packages, several main packages can be deleted but some "x-package-data/common" that are also there and not marked as being not needed anymore for autoremove, if you try you'll see why, they depend on things from GDM to Gnome Shell or critical system packages.
• Install packages you typically use, like ubuntu-restricted-extras which depends on the package ubuntu-restricted-addons (the checkbox in installation for codecs etc), but more stuff like Windows fonts, and VLC, GIMP, various mandatory CLI commands for power users like screen etc.
• If you don't like the grey GRUB background which sticks until GDM if splash option is turned off, not a big deal if 24/7 or booting in 2 seconds like me, but I hated the weird frame, in /usr/share/plymouth/themes/ubuntu-gnome-logo/ubuntu-gnome-logo.grub, change first line to if background_color 0,0,0 ; then will change color GRUB color scheme to standard white text on black background and stick until login screen, GDM.
• If using a fixed IP, typically a mostly 24/7 setup with server services and want Network Up and Running ASAP and NOT GNOME Control Center controlled which does "who knows what" in the background with every change, so you don't want NetworkManager to do all crazy stuff you don't have control over. Especially if you are going to run Virtual Machines and use a bridge so VMs are not behind NAT, the new netplan in /etc/netplan is very easy to understand, no fancy stuff, easy syntax familiar to every power user, easy documentation found in Ubuntu Server Guide (18.04), but even better use netplan's own documentation, it's like 1 minute read of basic syntax and examples, describing easily what every option does with examples (for example how to set up a bridge, super easy), not typical overkill documentation written by developers who hates documenting (I am one of those but I document well and structured so even a "dumb Windows colleague" can fix/edit my project, it is very important). Libvirt has the same great documentation for VM XML files. You typically don't want to go there because often docs causes more questions than answers, and googling and Stack Overflow is easier, but these guys do it right. Plain and simple. A netplan change only requires sudo netplan apply. Done. Finally new projects, which are always a "oh no yet another, won't survive even to next LTS", are good and at least I can see no reason to get rid of this (in Ubuntu Server and Cloud Server images it is default since they are of course headless) with nice websites and easy documentation. Use Systemd systemctl to disable NetworkManager services (easy to find since they start with capital N), and let systemd-networkd do the job, as that one is set as your actual network manager in netplan's file. It's only a file like /etc/network/interfaces before, but much better syntax and documentation. If you hate local running DNS servers, since you run your own on LAN or simply want your system to use directly OpenDNS for instance, well the easiest is to just to make sure /etc/resolv.conf is NOT a symlink, so delete it and set it up as usual, and no service will touch it, at least not as long as you have disabled NetworkManager
• Reboot, sudo reboot which is the same as sudo systemctl reboot according to Systemd, into your new Clean, Vanilla GNOME Desktop running Ubuntu LTS with its extra benefits. Fedora is very nice now too, especially for checking the latest without going Arch Linux, use it on my MacBook but can't be a 24/7 developer/server machine with that many packages updated every week, like in between Ubuntu with proposed and Arch Linux, just that packages are much more likely to break something you set up, which an APT update never does in my experience.
• Oh, and make practical BASH aliases, if one-user system, ~/.bash_aliases, at least make cp, mv and rm interactive so it asks you before overwriting or deleting. Such things. And edit ``~/.screenrcto your liking, at least get rid of "welcome screen" every time and add much longer scrollback,man screen` or better google "man screen". Reading manpages in a browser, well, way nicer.

Yes, off-topic kind of I know, going to make an own GIST of this. Practical for me in the future...