docs/3_Developer_Guides/1_Application_Framework/2_Application_Startup.md

   1 ---
   2 title: Application Startup
   3 ---
   4
   5 # Introduction
   6
   7 At system runtime, it may be necessary for applications to start other applications
   8 on demand. Such actions can be executed in reaction to a user request, or they may
   9 be needed to perform a specific task.
  10
  11 In order to do so, running applications and services need an established way of
  12 discovering installed applications and executing those. The
  13 [Desktop Entry specification](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html)
  14 defines how applications can be discovered by using `.desktop` files, but there's no
  15 simple reference implementation for this function.
  16
  17 In order to provide a language-independent interface for applications and service to
  18 use, AGL includes `applaunchd`, a user service part of the default session.
  19
  20 *Note: as mentioned [previously](1_Introduction/), services are managed using `systemd`
  21 and are therefore not in the scope of this document.*
  22
  23 # Application launcher service
  24
  25 The purpose of `applaunchd` is to enumerate applications available on the system and
  26 provide a way for other applications to query this list and start those on demand.
  27 It is also able to notify clients of the startup and termination of applications it
  28 manages.
  29
  30 To that effect, `applaunchd` provides a D-Bus interface other applications can use
  31 in order to execute those actions.
  32
  33 *Note: `applaunchd` will only send notifications for applications it started; it isn't
  34 aware of applications started by other means (`systemd`, direct executable call...),
  35 and therefore can't send notifications for those.*
  36
  37 ## Application discovery
  38
  39 On startup, `applaunchd` inspects all `.desktop` files present under the `applications/`
  40 subfolder of any element of the `XDG_DATA_DIRS` environment variable, ignoring all entries
  41 containing either the `NoDisplay=true` or `Hidden=true` lines.
  42
  43 It then looks for the following keys:
  44 - `Terminal`
  45 - `DBusActivatable`
  46
  47 If the desktop entry file contains the `Terminal` key set to `true`, then the application
  48 is marked as a non-graphical one. As such, it won't be included in the applications list
  49 if the client requests only graphical applications.
  50
  51 If `DBusActivatable` is set to `true`, then the application is marked as D-Bus activated.
  52 Additionally, `applaunchd` will search for a corresponding D-Bus service file in case this
  53 line is missing. This is a workaround allowing D-Bus activated applications providing
  54 an incomplete desktop entry file (i.e missing the `DBusActivatable` key) to be
  55 identified as such.
  56
  57 ### Requirements for D-Bus activation
  58
  59 `applaunchd` will always start D-Bus activatable applications using D-Bus activation
  60 instead of executing the command line stated in the desktop entry file.
  61
  62 This is handled by calling the `Activate` method of the
  63 [org.freedesktop.Application](https://specifications.freedesktop.org/desktop-entry-spec/1.1/ar01s07.html)
  64 interface with an empty argument.
  65
  66 As a consequence, all D-Bus activatable applications **must** implement this D-Bus
  67 interface.
  68
  69 ## Application identifiers
  70
  71 Each application is identified by a unique Application ID. Although this ID can be
  72 any valid string, it is highly recommended to use the "reverse DNS" convention in order
  73 to avoid potential name collisions and ease D-Bus integration.
  74
  75 The application ID is set in the desktop entry file itself for
  76 [graphical applications](../3_Creating_a_New_Application/#graphical-applications):
  77 it is the value of the `StartupWMClass` field, which must be identical to the `app-id`
  78 advertised through the Wayland XDG toplevel protocol. In case this field is missing
  79 (as is usually the case for non-graphical application), the application ID will be the
  80 desktop entry file name, stripped from its `.desktop` extension.
  81
  82 ## D-Bus interface
  83
  84 The `applaunchd` D-Bus interface is named `org.automotivelinux.AppLaunch`. The object
  85 path for `applaunchd` is `/org/automotivelinux/AppLaunch`. The interface provides methods
  86 for the following actions:
  87 - retrieve the list of available applications; the client can choose to retrieve all
  88   available applications, or only those suitable for a graphical environment
  89 - request an application to be started
  90
  91 Moreover, signals are available for clients to be notified when an application has
  92 successfully started or its execution terminated.
  93
  94 ### Applications list
  95
  96 The `listApplications` method allows clients to retrieve the list of available applications.
  97 It takes one boolean argument named `graphical`:
  98 - if set to `true`, only applications suitable for graphical environments are returned
  99 - otherwise, the list contains all applications
 100
 101 This method returns an array of variants (type `av`), each element being a structure made up
 102 of 3 strings (type `(sss)`):
 103 - the application ID
 104 - the application's displayed name
 105 - the full path to the application icon file (or an empty string if no icon was specified in
 106   the application's desktop entry file)
 107
 108 ### Application startup request
 109
 110 Applications can be started by using the `start` method, passing the corresponding application
 111 ID as the only argument. This method doesn't return any data.
 112
 113 If the application is already running, `applaunchd` won't start another instance, but instead
 114 emit a `started` signal to notify clients the application is ready.
 115
 116 ### Status notifications
 117
 118 The `org.automotivelinux.AppLaunch` interface provides 2 signals clients can connect to:
 119 - `started` indicates an application has started
 120     - for D-Bus activated applications, it is emitted upon successful completion of the
 121       call to the `Activate` method of the `org.freedesktop.Application` interface
 122     - for other applications, this signal is emitted as soon as the child process has been
 123       successfully created
 124 - `terminated` is emitted when an application quits
 125
 126 Both signals have an additional argument named `appid`, containing the ID of the application
 127 affected by the event.
 128
 129 As mentioned above, the `started` signal is also emitted if `applaunchd` receives a request to
 130 start an already running application. This can be useful, for example, when switching between
 131 graphical applications:
 132 - the application switcher doesn't need to track the state of each application; instead, it can
 133   simply send a `start` request to `applaunchd` every time the user requests to switch to another
 134   application
 135 - the desktop environment then receives the `started` signal, indicating it should activate the
 136   window with the corresponding `app-id`
 137
 138 ## Testing
 139
 140 `applaunchd` can be manually tested using the `gdbus` command-line tool:
 141
 142 1. Query the application list (graphical applications only):
 143
 144 ```
 145 $ gdbus call --session --dest "org.automotivelinux.AppLaunch" \
 146                        --object-path "/org/automotivelinux/AppLaunch" \
 147                        --method "org.automotivelinux.AppLaunch.listApplications" \
 148                        true
 149 ```
 150
 151 This command will output something similar to what follows:
 152
 153 ```
 154 ([<('navigation', 'Navigation', '/usr/share/icons/hicolor/scalable/navigation.svg')>,
 155  <('settings', 'Settings', '/usr/share/icons/hicolor/scalable/settings.svg')>,
 156  <('dashboard', 'Dashboard', '/usr/share/icons/hicolor/scalable/dashboard.svg')>,
 157  <('hvac', 'HVAC', '/usr/share/icons/hicolor/scalable/hvac.svg')>,
 158  <('org.freedesktop.weston.wayland-terminal', 'Weston Terminal', '/usr/share/icons/Adwaita/scalable/apps/utilities-terminal-symbolic.svg')>],)
 159 ```
 160
 161 2. Request startup of the `org.freedesktop.weston.wayland-terminal` application:
 162
 163 ```
 164 $ gdbus call --session --dest "org.automotivelinux.AppLaunch" \
 165                        --object-path "/org/automotivelinux/AppLaunch" \
 166                        --method "org.automotivelinux.AppLaunch.start" \
 167                        "org.freedesktop.weston.wayland-terminal"
 168 ```
 169
 170 3. Monitor signals emitted by `applaunchd`:
 171
 172 ```
 173 $ gdbus monitor --session --dest "org.automotivelinux.AppLaunch"
 174 ```
 175
 176 This results in the following output when starting, then exiting, the
 177 `org.freedesktop.weston.wayland-terminal` application:
 178
 179 ```
 180 Monitoring signals from all objects owned by org.automotivelinux.AppLaunch
 181 The name org.automotivelinux.AppLaunch is owned by :1.4
 182 /org/automotivelinux/AppLaunch: org.automotivelinux.AppLaunch.started ('org.freedesktop.weston.wayland-terminal',)
 183 /org/automotivelinux/AppLaunch: org.automotivelinux.AppLaunch.terminated ('org.freedesktop.weston.wayland-terminal',)
 184 ```