docs/06_Component_Documentation/Application_Framework/04_Creating_a_New_Application_Dbus.md

   1 ---
   2 title: Creating a New Application with D-bus activation
   3 ---
   4
   5 *Note: The that the D-Bus interface is in deprecation phase and for the time
   6 being only available for application & services that still rely on them. Once
   7 we migrate everything to gRPC, we will remove D-Bus IPC support.*
   8
   9 Applications are:
  10
  11 -  Software designed to perform a specific task during a limited amount of time.
  12 -  Graphical interface allowing user to interact with.
  13
  14 Applications are executed by `applaunchd`, the AGL
  15 [application launcher service](02_Application_Startup_Dbus.md).
  16
  17 # Basic requirements
  18
  19 In order to be enumerated by `applaunchd`, applications must provide the a `.desktop` file, as
  20 defined by the [Desktop Entry specification](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html).
  21
  22 The desktop entry file should be installed to `/usr/share/applications` (or the `applications`
  23 sub-directory of any entry present in the `XDG_DATA_DIRS` environment variable) and have a
  24 meaningful name. It is considered good practice to use reverse-DNS notation for the desktop
  25 entry file name, following the recommendations of the [D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names):
  26 - this avoids potential name collisions with other desktop entry files
  27 - it makes it easier to enable [D-Bus activation](#d-bus-activation) during the application
  28   development cycle if needed
  29 - for [graphical applications](#graphical-applications), it ensures the chosen Wayland `app-id`
  30   will be unique
  31
  32 Such a file must contain at least the following keys:
  33 - `Type`: desktop entry type, must be set to `Application`
  34 - `Name`: application name, as it should be displayed in menus and application launchers
  35 - `Exec`: full path to the main executable
  36
  37 Below is an example of a minimal desktop entry file:
  38
  39 ```
  40 [Desktop Entry]
  41 Type=Application
  42 Name=Example Application
  43 Exec=/usr/bin/example-app
  44 ```
  45
  46 Graphical applications must also provide an `Icon` entry pointing to the application icon.
  47 The value for this entry must either be the full path to the icon's file or, for icons part
  48 of an existing [icon theme](https://specifications.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html),
  49 the name of an element of this theme.
  50
  51 In addition, a number of optional fields can be used to change how `applaunchd` will consider the
  52 application:
  53 - `Version`: version of the Desktop Entry Specification the file conforms to, must be `1.5`
  54 - `Hidden`: boolean value, if `true` the application is always ignored by `applaunchd` and
  55   won't be listed nor executed
  56 - `Terminal`: boolean value, if `true` the application is excluded when requesting the list of
  57   graphical applications from `applaunchd`
  58 - `DBusActivatable`: boolean value, must be `true` for [D-Bus activated applications](#d-bus-activation)
  59 - `Implements`: list of D-Bus interfaces the application implements, only used for D-Bus activated
  60   applications.
  61
  62 Finally, graphical applications may also define the `StartupWMClass` key in some cases. Please
  63 refer to the [graphical applications](#graphical-applications) section for more information.
  64
  65 # D-Bus activation
  66
  67 Similarly to [services](03_Creating_a_New_Service.md#d-bus-activation), applications can
  68 also be activated through D-Bus.
  69
  70 Such applications must name their `.desktop` file after the D-Bus name they register. In addition,
  71 this file must contain the following entries:
  72
  73 ```
  74 DBusActivatable=true
  75 Implements=IFACE1;IFACE2;...
  76 ```
  77
  78 Where `IFACEn` are the names of the D-Bus interfaces the application implements.
  79
  80 In addition, they must provide a D-Bus service file named `NAME.service` and installed
  81 to `/usr/share/dbus-1/services`.
  82
  83 The contents of the D-Bus service file must be the following:
  84
  85 ```
  86 [D-BUS Service]
  87 Name=NAME
  88 Exec=/path/to/executable
  89 ```
  90
  91 For example, an application registering the `org.automotivelinux.Example` D-Bus name
  92 and implementing the `org.automotivelinux.Example.Search1` and `org.automotivelinux.Example.Execute1`
  93 interfaces would provide the following files:
  94
  95 * Desktop entry (`/usr/share/applications/org.automotivelinux.Example.desktop`):
  96
  97 ```
  98 [Desktop Entry]
  99 Type=Application
 100 Version=1.5
 101 Name=Example Application
 102 Exec=/usr/bin/example-app
 103 Icon=example-icon
 104 Terminal=false
 105 DBusActivatable=true
 106 Implements=org.automotivelinux.Example.Search1;org.automotivelinux.Example.Execute1
 107 ```
 108
 109 * D-Bus service file (`/usr/share/dbus-1/services/org.automotivelinux.Example.service`):
 110
 111 ```
 112 [D-BUS Service]
 113 Name=org.automotivelinux.Example
 114 Exec=/usr/bin/example-app
 115 ```
 116
 117 *Note: in addition to their own D-Bus interface, D-Bus activated applications must also
 118 implement the `org.freedesktop.Application` interface as defined in the
 119 [Desktop Entry specification](https://specifications.freedesktop.org/desktop-entry-spec/1.1/ar01s07.html).*
 120
 121 # Graphical applications
 122
 123 In addition, graphical applications need to comply with a few more requirements:
 124
 125 1\. Each application must set a Wayland application ID appropriately as soon as its main window
 126 is created.
 127
 128 2\. The `app-id` must be specified in the desktop entry file by adding the following line:
 129
 130 ```
 131 StartupWMClass=APP_ID
 132 ```
 133
 134 3\. The desktop entry file must be named `APP_ID.desktop`.
 135
 136 Doing so will ensure other software can associate the actual `app-id` to the proper application.
 137
 138 *Note: application ID's are set using the [XDG toplevel](https://wayland-book.com/xdg-shell-basics/xdg-toplevel.html)
 139 Wayland interface.*