X-Git-Url: https://gerrit.automotivelinux.org/gerrit/gitweb?a=blobdiff_plain;f=docs%2F06_Component_Documentation%2FApplication_Framework%2F04_Creating_a_New_Application_Dbus.md;fp=docs%2F06_Component_Documentation%2FApplication_Framework%2F04_Creating_a_New_Application_Dbus.md;h=0000000000000000000000000000000000000000;hb=04ae05c69a1ee2934b139b179d15ba112ff18ab6;hp=2ee6bdf7af13e0b8eed4a143a8affc157e0c0524;hpb=ecccce4b62c048272dd48378cc05d7165746b83e;p=AGL%2Fdocumentation.git diff --git a/docs/06_Component_Documentation/Application_Framework/04_Creating_a_New_Application_Dbus.md b/docs/06_Component_Documentation/Application_Framework/04_Creating_a_New_Application_Dbus.md deleted file mode 100644 index 2ee6bdf..0000000 --- a/docs/06_Component_Documentation/Application_Framework/04_Creating_a_New_Application_Dbus.md +++ /dev/null @@ -1,139 +0,0 @@ ---- -title: Creating a New Application with D-bus activation ---- - -*Note: The that the D-Bus interface is in deprecation phase and for the time -being only available for application & services that still rely on them. Once -we migrate everything to gRPC, we will remove D-Bus IPC support.* - -Applications are: - -- Software designed to perform a specific task during a limited amount of time. -- Graphical interface allowing user to interact with. - -Applications are executed by `applaunchd`, the AGL -[application launcher service](02_Application_Startup_Dbus.md). - -# Basic requirements - -In order to be enumerated by `applaunchd`, applications must provide the a `.desktop` file, as -defined by the [Desktop Entry specification](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html). - -The desktop entry file should be installed to `/usr/share/applications` (or the `applications` -sub-directory of any entry present in the `XDG_DATA_DIRS` environment variable) and have a -meaningful name. It is considered good practice to use reverse-DNS notation for the desktop -entry file name, following the recommendations of the [D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names): -- this avoids potential name collisions with other desktop entry files -- it makes it easier to enable [D-Bus activation](#d-bus-activation) during the application - development cycle if needed -- for [graphical applications](#graphical-applications), it ensures the chosen Wayland `app-id` - will be unique - -Such a file must contain at least the following keys: -- `Type`: desktop entry type, must be set to `Application` -- `Name`: application name, as it should be displayed in menus and application launchers -- `Exec`: full path to the main executable - -Below is an example of a minimal desktop entry file: - -``` -[Desktop Entry] -Type=Application -Name=Example Application -Exec=/usr/bin/example-app -``` - -Graphical applications must also provide an `Icon` entry pointing to the application icon. -The value for this entry must either be the full path to the icon's file or, for icons part -of an existing [icon theme](https://specifications.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html), -the name of an element of this theme. - -In addition, a number of optional fields can be used to change how `applaunchd` will consider the -application: -- `Version`: version of the Desktop Entry Specification the file conforms to, must be `1.5` -- `Hidden`: boolean value, if `true` the application is always ignored by `applaunchd` and - won't be listed nor executed -- `Terminal`: boolean value, if `true` the application is excluded when requesting the list of - graphical applications from `applaunchd` -- `DBusActivatable`: boolean value, must be `true` for [D-Bus activated applications](#d-bus-activation) -- `Implements`: list of D-Bus interfaces the application implements, only used for D-Bus activated - applications. - -Finally, graphical applications may also define the `StartupWMClass` key in some cases. Please -refer to the [graphical applications](#graphical-applications) section for more information. - -# D-Bus activation - -Similarly to [services](03_Creating_a_New_Service.md#d-bus-activation), applications can -also be activated through D-Bus. - -Such applications must name their `.desktop` file after the D-Bus name they register. In addition, -this file must contain the following entries: - -``` -DBusActivatable=true -Implements=IFACE1;IFACE2;... -``` - -Where `IFACEn` are the names of the D-Bus interfaces the application implements. - -In addition, they must provide a D-Bus service file named `NAME.service` and installed -to `/usr/share/dbus-1/services`. - -The contents of the D-Bus service file must be the following: - -``` -[D-BUS Service] -Name=NAME -Exec=/path/to/executable -``` - -For example, an application registering the `org.automotivelinux.Example` D-Bus name -and implementing the `org.automotivelinux.Example.Search1` and `org.automotivelinux.Example.Execute1` -interfaces would provide the following files: - -* Desktop entry (`/usr/share/applications/org.automotivelinux.Example.desktop`): - -``` -[Desktop Entry] -Type=Application -Version=1.5 -Name=Example Application -Exec=/usr/bin/example-app -Icon=example-icon -Terminal=false -DBusActivatable=true -Implements=org.automotivelinux.Example.Search1;org.automotivelinux.Example.Execute1 -``` - -* D-Bus service file (`/usr/share/dbus-1/services/org.automotivelinux.Example.service`): - -``` -[D-BUS Service] -Name=org.automotivelinux.Example -Exec=/usr/bin/example-app -``` - -*Note: in addition to their own D-Bus interface, D-Bus activated applications must also -implement the `org.freedesktop.Application` interface as defined in the -[Desktop Entry specification](https://specifications.freedesktop.org/desktop-entry-spec/1.1/ar01s07.html).* - -# Graphical applications - -In addition, graphical applications need to comply with a few more requirements: - -1\. Each application must set a Wayland application ID appropriately as soon as its main window -is created. - -2\. The `app-id` must be specified in the desktop entry file by adding the following line: - -``` -StartupWMClass=APP_ID -``` - -3\. The desktop entry file must be named `APP_ID.desktop`. - -Doing so will ensure other software can associate the actual `app-id` to the proper application. - -*Note: application ID's are set using the [XDG toplevel](https://wayland-book.com/xdg-shell-basics/xdg-toplevel.html) -Wayland interface.*