From: Vinod Ahuja Date: Mon, 12 Sep 2022 22:22:20 +0000 (-0500) Subject: Improving Developer 3_Developer_Guides X-Git-Tag: 14.91.0~8 X-Git-Url: https://gerrit.automotivelinux.org/gerrit/gitweb?a=commitdiff_plain;h=0a3b4ca17dd1eeab7f15cdfb590656377c996501;p=AGL%2Fdocumentation.git Improving Developer 3_Developer_Guides Worked on creating new services and applications. 1. Removed Fixme file 2. Formatted some text and numbering 3. Fixed some broken links. Bug-AGL: [SPEC-4470] Signed-off-by: Vinod Ahuja Change-Id: If3f9a171faff8466bd6d141f9537cd98468fadbb Reviewed-on: https://gerrit.automotivelinux.org/gerrit/c/AGL/documentation/+/27993 Reviewed-by: Jan-Simon Moeller Tested-by: Jan-Simon Moeller --- diff --git a/docs/3_Developer_Guides/0_FIXME.md b/docs/3_Developer_Guides/0_FIXME.md deleted file mode 100644 index e69de29..0000000 diff --git a/docs/3_Developer_Guides/2_Creating_a_New_Service.md b/docs/3_Developer_Guides/2_Creating_a_New_Service.md index 7974d00..0fb2453 100644 --- a/docs/3_Developer_Guides/2_Creating_a_New_Service.md +++ b/docs/3_Developer_Guides/2_Creating_a_New_Service.md @@ -4,10 +4,12 @@ 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, network servers... They can be split into 2 categories: -- system services: those usually run as a privileged user and make use of shared system +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 + +- **User services:** such services run as part of an unprivileged user's session and can only be called by said user # Basic requirements @@ -15,7 +17,9 @@ management, network servers... They can be split into 2 categories: 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 @@ -36,7 +40,7 @@ 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](1_Application_Framework/1_Introduction/#user-session-management) +user session, as mentioned in the [Application Framework](../1_Application_Framework/1_Introduction/#user-session-management) documentation. The `Restart=on-failure` directive ensures the service will be automatically @@ -65,7 +69,9 @@ 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: @@ -95,19 +101,19 @@ executed on system or session startup. 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: +1\. Ensure the recipe inherits from the `systemd` class: ``` inherit systemd ``` -2. Declare the system services that needs to be enabled on boot: +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 +3\. Ensure the `FILES` variable includes the systemd service directory the corresponding file will be installed to: ``` @@ -122,7 +128,7 @@ FILES:${PN} = "\ 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: +1\. Make the service a part of the user session: ``` do_install:append() { @@ -134,7 +140,7 @@ do_install:append() { 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 +2\. Ensure the `FILES` variable includes the systemd service directory the corresponding file will be installed to: ``` diff --git a/docs/3_Developer_Guides/3_Creating_a_New_Application.md b/docs/3_Developer_Guides/3_Creating_a_New_Application.md index c98cf1c..ed89ecc 100644 --- a/docs/3_Developer_Guides/3_Creating_a_New_Application.md +++ b/docs/3_Developer_Guides/3_Creating_a_New_Application.md @@ -2,11 +2,13 @@ title: Creating a New Application --- -Applications are either software designed to perform a specific task during a limited amount of -time, or graphical applications presenting the user with an interface they can interact with. +Applications are: -Such applications are executed by `applaunchd`, the AGL -[application launcher service](1_Application_Framework/2_Application_Startup/). +- 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](../1_Application_Framework/2_Application_Startup/). # Basic requirements @@ -58,7 +60,7 @@ refer to the [graphical applications](#graphical-applications) section for more # D-Bus activation -Similarly to [services](2_Creating_a_New_Service.md/#d-bus-activation), applications can +Similarly to [services](../2_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, @@ -116,16 +118,16 @@ implement the `org.freedesktop.Application` interface as defined in the 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 +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: +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`. +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.