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.
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.
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
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.
Maybe related to the standardized StartupNotify?
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.
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.
The proposal for this key on the xdg mailing list.
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.