From 537b1f6318a841133e87d6cbb919ff9c6963bc97 Mon Sep 17 00:00:00 2001 From: Marius Vlad Date: Wed, 22 Feb 2023 11:56:16 +0200 Subject: 01_Application_Framework: Migrate new service and new application creation This moves out 03_Creating_a_New_Service and 04_Creating_a_New_Application under Application Framework folder, as they don't really make sense being outside of it, when in fact they are referring quite a lot to the Application Framework, being dependent on the D-Bus IPC. Bug-AGL: SPEC-4700 Signed-off-by: Marius Vlad Change-Id: I08819725efa89afe0b44ff7e3146906c43ff40d0 (cherry picked from commit a6598a4a7f4e494108997340dbbc7095be514c7e) Reviewed-on: https://gerrit.automotivelinux.org/gerrit/c/AGL/documentation/+/28538 Reviewed-by: Jan-Simon Moeller Tested-by: Jan-Simon Moeller --- .../01_Application_Framework/01_Introduction.md | 2 +- .../03_Creating_a_New_Service.md | 151 +++++++++++++++++++++ .../04_Creating_a_New_Application.md | 135 ++++++++++++++++++ .../02_Creating_a_New_Service.md | 151 --------------------- .../03_Creating_a_New_Application.md | 135 ------------------ 5 files changed, 287 insertions(+), 287 deletions(-) create mode 100644 docs/04_Developer_Guides/01_Application_Framework/03_Creating_a_New_Service.md create mode 100644 docs/04_Developer_Guides/01_Application_Framework/04_Creating_a_New_Application.md delete mode 100644 docs/04_Developer_Guides/02_Creating_a_New_Service.md delete mode 100644 docs/04_Developer_Guides/03_Creating_a_New_Application.md diff --git a/docs/04_Developer_Guides/01_Application_Framework/01_Introduction.md b/docs/04_Developer_Guides/01_Application_Framework/01_Introduction.md index e61e67f..5c38907 100644 --- a/docs/04_Developer_Guides/01_Application_Framework/01_Introduction.md +++ b/docs/04_Developer_Guides/01_Application_Framework/01_Introduction.md @@ -86,7 +86,7 @@ allowing for improved reliability and security. Each service should be represented by a `systemd` unit file installed to the appropriate location. More details can be obtained from the [Creating a New -Service](/04_Developer_Guides/02_Creating_a_New_Service/) document. +Service](../03_Creating_a_New_Service/) document. # User session management diff --git a/docs/04_Developer_Guides/01_Application_Framework/03_Creating_a_New_Service.md b/docs/04_Developer_Guides/01_Application_Framework/03_Creating_a_New_Service.md new file mode 100644 index 0000000..22e98ea --- /dev/null +++ b/docs/04_Developer_Guides/01_Application_Framework/03_Creating_a_New_Service.md @@ -0,0 +1,151 @@ +--- +title: Creating a New Service +--- + +Services are software running in the background and providing, as their name suggests, +various services to other software: access to specific system hardware, connectivity +management, and network servers. Services can be split into 2 categories: + +- **System services:** those usually run as a privileged user and make use of shared system + resources which they should have exclusive access to + +- **User services:** such services run as part of an unprivileged user's session and can + only be called by said user + +# Basic requirements + +The only mandatory requirement is that service packages provide a `.service` file +so they can be properly managed by `systemd`. This file must be installed to a specific +location, determined by the service type (system or user): + +- `/usr/lib/systemd/system/` for system services + +- `/usr/lib/systemd/user/` for user services + +Below is an example of a simple user service, running in a graphical session and +therefore requiring a compositor to be already running before the service starts: + +``` +[Unit] +Requires=agl-compositor.service +After=agl-compositor.service + +[Service] +Type=simple +ExecStart=/usr/bin/homescreen +Restart=on-failure + +[Install] +WantedBy=agl-session.target +``` + +The `WantedBy=agl-session.target` indicates the service is part of the default AGL +user session, as mentioned in the [Application Framework](../01_Application_Framework/01_Introduction/#user-session-management) +documentation. + +The `Restart=on-failure` directive ensures the service will be automatically +restarted by `systemd` in case it crashes. + +More details about `systemd` service files can be found in the +[systemd documentation](https://www.freedesktop.org/software/systemd/man/systemd.service.html). + +# D-Bus activation + +Services can also provide a D-Bus interface. In this case, they need not be started +on system boot (or user session startup in the case of user services) but can be +automatically started only when a client sends a request to the D-Bus name the service +registers. + +D-Bus activated services must name their `systemd` service file `dbus-NAME.service` +where `NAME` is the D-Bus name registered by the service. This file must include the +following lines: + +``` +[Service] +Type=dbus +BusName=NAME +ExecStart=/path/to/executable +``` + +In addition, they must provide a D-Bus service file named `NAME.service` and installed +to one of the following locations: + +- `/usr/share/dbus-1/system-services` for system services + +- `/usr/share/dbus-1/services` for user services + +The contents of the D-Bus service file must be the following: + +``` +[D-BUS Service] +Name=NAME +Exec=/path/to/executable +SystemdService=dbus-NAME.service +``` + +This ensures the service can be safely activated through D-Bus and no conflict will occur +between `systemd` and the D-Bus daemon. + +More details about D-Bus activation can be found in the +[D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html#message-bus-starting-services), +under the "Message Bus Starting Services (Activation)" section. + +# Services startup + +For D-Bus activated services, no additional action is required as those will be automatically +started whenever needed. Other services, however, need a few more steps in order to be +executed on system or session startup. + +## System services + +System services can take advantage of the Yocto `systemd` class which automates the process of +enabling such services. + +1\. Ensure the recipe inherits from the `systemd` class: + +``` +inherit systemd +``` + +2\. Declare the system services that needs to be enabled on boot: + +``` +SYSTEMD_SERVICE:${PN} = "NAME.service" +``` + +3\. Ensure the `FILES` variable includes the systemd service directory the corresponding +file will be installed to: + +``` +FILES:${PN} = "\ + ... + ${systemd_system_unitdir}/* \ +" +``` + +## User services + +The `systemd` class doesn't provide an equivalent mechanism for user services. This must +therefore be done manually as part of the package's install process. + +1\. Make the service a part of the user session: + +``` +do_install:append() { + install -d ${D}${systemd_user_unitdir}/agl-session.target.wants + ln -s ../NAME.service ${D}${systemd_user_unitdir}/agl-session.target.wants/NAME.service +} +``` + +This ensures `agl-session.target` depends on `NAME.service`, the latter being therefore +automatically started on session creation. + +2\. Ensure the `FILES` variable includes the systemd service directory the corresponding +file will be installed to: + +``` +FILES:${PN} = "\ + ... + ${systemd_user_unitdir}/* \ +" +``` diff --git a/docs/04_Developer_Guides/01_Application_Framework/04_Creating_a_New_Application.md b/docs/04_Developer_Guides/01_Application_Framework/04_Creating_a_New_Application.md new file mode 100644 index 0000000..014069d --- /dev/null +++ b/docs/04_Developer_Guides/01_Application_Framework/04_Creating_a_New_Application.md @@ -0,0 +1,135 @@ +--- +title: Creating a New Application +--- + +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](../01_Application_Framework/02_Application_Startup/). + +# 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](../02_Creating_a_New_Service/#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.* diff --git a/docs/04_Developer_Guides/02_Creating_a_New_Service.md b/docs/04_Developer_Guides/02_Creating_a_New_Service.md deleted file mode 100644 index 22e98ea..0000000 --- a/docs/04_Developer_Guides/02_Creating_a_New_Service.md +++ /dev/null @@ -1,151 +0,0 @@ ---- -title: Creating a New Service ---- - -Services are software running in the background and providing, as their name suggests, -various services to other software: access to specific system hardware, connectivity -management, and network servers. Services can be split into 2 categories: - -- **System services:** those usually run as a privileged user and make use of shared system - resources which they should have exclusive access to - -- **User services:** such services run as part of an unprivileged user's session and can - only be called by said user - -# Basic requirements - -The only mandatory requirement is that service packages provide a `.service` file -so they can be properly managed by `systemd`. This file must be installed to a specific -location, determined by the service type (system or user): - -- `/usr/lib/systemd/system/` for system services - -- `/usr/lib/systemd/user/` for user services - -Below is an example of a simple user service, running in a graphical session and -therefore requiring a compositor to be already running before the service starts: - -``` -[Unit] -Requires=agl-compositor.service -After=agl-compositor.service - -[Service] -Type=simple -ExecStart=/usr/bin/homescreen -Restart=on-failure - -[Install] -WantedBy=agl-session.target -``` - -The `WantedBy=agl-session.target` indicates the service is part of the default AGL -user session, as mentioned in the [Application Framework](../01_Application_Framework/01_Introduction/#user-session-management) -documentation. - -The `Restart=on-failure` directive ensures the service will be automatically -restarted by `systemd` in case it crashes. - -More details about `systemd` service files can be found in the -[systemd documentation](https://www.freedesktop.org/software/systemd/man/systemd.service.html). - -# D-Bus activation - -Services can also provide a D-Bus interface. In this case, they need not be started -on system boot (or user session startup in the case of user services) but can be -automatically started only when a client sends a request to the D-Bus name the service -registers. - -D-Bus activated services must name their `systemd` service file `dbus-NAME.service` -where `NAME` is the D-Bus name registered by the service. This file must include the -following lines: - -``` -[Service] -Type=dbus -BusName=NAME -ExecStart=/path/to/executable -``` - -In addition, they must provide a D-Bus service file named `NAME.service` and installed -to one of the following locations: - -- `/usr/share/dbus-1/system-services` for system services - -- `/usr/share/dbus-1/services` for user services - -The contents of the D-Bus service file must be the following: - -``` -[D-BUS Service] -Name=NAME -Exec=/path/to/executable -SystemdService=dbus-NAME.service -``` - -This ensures the service can be safely activated through D-Bus and no conflict will occur -between `systemd` and the D-Bus daemon. - -More details about D-Bus activation can be found in the -[D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html#message-bus-starting-services), -under the "Message Bus Starting Services (Activation)" section. - -# Services startup - -For D-Bus activated services, no additional action is required as those will be automatically -started whenever needed. Other services, however, need a few more steps in order to be -executed on system or session startup. - -## System services - -System services can take advantage of the Yocto `systemd` class which automates the process of -enabling such services. - -1\. Ensure the recipe inherits from the `systemd` class: - -``` -inherit systemd -``` - -2\. Declare the system services that needs to be enabled on boot: - -``` -SYSTEMD_SERVICE:${PN} = "NAME.service" -``` - -3\. Ensure the `FILES` variable includes the systemd service directory the corresponding -file will be installed to: - -``` -FILES:${PN} = "\ - ... - ${systemd_system_unitdir}/* \ -" -``` - -## User services - -The `systemd` class doesn't provide an equivalent mechanism for user services. This must -therefore be done manually as part of the package's install process. - -1\. Make the service a part of the user session: - -``` -do_install:append() { - install -d ${D}${systemd_user_unitdir}/agl-session.target.wants - ln -s ../NAME.service ${D}${systemd_user_unitdir}/agl-session.target.wants/NAME.service -} -``` - -This ensures `agl-session.target` depends on `NAME.service`, the latter being therefore -automatically started on session creation. - -2\. Ensure the `FILES` variable includes the systemd service directory the corresponding -file will be installed to: - -``` -FILES:${PN} = "\ - ... - ${systemd_user_unitdir}/* \ -" -``` diff --git a/docs/04_Developer_Guides/03_Creating_a_New_Application.md b/docs/04_Developer_Guides/03_Creating_a_New_Application.md deleted file mode 100644 index 014069d..0000000 --- a/docs/04_Developer_Guides/03_Creating_a_New_Application.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -title: Creating a New Application ---- - -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](../01_Application_Framework/02_Application_Startup/). - -# 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](../02_Creating_a_New_Service/#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.* -- cgit 1.2.3-korg