From 537b1f6318a841133e87d6cbb919ff9c6963bc97 Mon Sep 17 00:00:00 2001
From: Marius Vlad <marius.vlad@collabora.com>
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 <marius.vlad@collabora.com>
Change-Id: I08819725efa89afe0b44ff7e3146906c43ff40d0
(cherry picked from commit a6598a4a7f4e494108997340dbbc7095be514c7e)
Reviewed-on: https://gerrit.automotivelinux.org/gerrit/c/AGL/documentation/+/28538
Reviewed-by: Jan-Simon Moeller <jsmoeller@linuxfoundation.org>
Tested-by: Jan-Simon Moeller <jsmoeller@linuxfoundation.org>
---
 .../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

(limited to 'docs/04_Developer_Guides')

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