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 <scott.murray@konsulko.com>
Change-Id: I6e0c0afcf571d9214df5300d2082b15fa3bb2a27
Reviewed-on: https://gerrit.automotivelinux.org/gerrit/c/AGL/documentation/+/29284
Reviewed-by: Jan-Simon Moeller <jsmoeller@linuxfoundation.org>
Tested-by: Jan-Simon Moeller <jsmoeller@linuxfoundation.org>

1 files changed, 144 insertions, 0 deletions

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}/* \
+"
+```