From 04ae05c69a1ee2934b139b179d15ba112ff18ab6 Mon Sep 17 00:00:00 2001 From: Scott Murray Date: Tue, 17 Oct 2023 16:48:46 -0400 Subject: Update application framework documentation Changes: - Moved "Creating a New Service" page back over to "Developer Guides" since it is not application framework specific. - Removed obsolete applaunchd D-Bus configuration documentation now that the functionality has been completely removed as of Pike. - Updated the application framework introduction discussion around protocols to document preference for gRPC over D-Bus for AGL projects. - Updated "Creating a New Application" documentation to document the requirements for having applications usable with applaunchd, as well as using the application templates, with BitBake recipe examples. - Added "Application Sandboxing" section that documents the existing example configurations and discusses other potential configuration options for systemd. Bug-AGL: SPEC-4928 Signed-off-by: Scott Murray Change-Id: I6e0c0afcf571d9214df5300d2082b15fa3bb2a27 Reviewed-on: https://gerrit.automotivelinux.org/gerrit/c/AGL/documentation/+/29284 Reviewed-by: Jan-Simon Moeller Tested-by: Jan-Simon Moeller --- .../03_Creating_a_New_Service.md | 144 +++++++++++++++++++++ 1 file changed, 144 insertions(+) create mode 100644 docs/04_Developer_Guides/03_Creating_a_New_Service.md (limited to 'docs/04_Developer_Guides') diff --git a/docs/04_Developer_Guides/03_Creating_a_New_Service.md b/docs/04_Developer_Guides/03_Creating_a_New_Service.md new file mode 100644 index 0000000..858715d --- /dev/null +++ b/docs/04_Developer_Guides/03_Creating_a_New_Service.md @@ -0,0 +1,144 @@ +--- +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 system service that requires the 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 +``` + +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}/* \ +" +``` -- cgit 1.2.3-korg