diff options
| author |   Scott Murray <scott.murray@konsulko.com> | 2023-10-17 16:48:46 -0400 |
|---|---|---|
| committer |   Jan-Simon Moeller <jsmoeller@linuxfoundation.org> | 2023-11-09 17:16:45 +0000 |
| commit | 24c10f43f5691b32dc09f8eea7cfc1a679a6a3b1 (patch) | |
| tree | 861b82ecc1a2b3f2d1ca467bbd7425ee757a6e3e /docs/06_Component_Documentation/Application_Framework/01_Introduction.md | |
| parent | fe5a8e87f9f2c57ced90e898ebb1af10f92bcb35 (diff) | |
Update application framework documentationpike_16.0.4pike_16.0.3pike/16.0.4pike/16.0.316.0.416.0.3
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>
(cherry picked from commit 04ae05c69a1ee2934b139b179d15ba112ff18ab6)
Reviewed-on: https://gerrit.automotivelinux.org/gerrit/c/AGL/documentation/+/29362
Diffstat (limited to 'docs/06_Component_Documentation/Application_Framework/01_Introduction.md')
| -rw-r--r-- | docs/06_Component_Documentation/Application_Framework/01_Introduction.md | 174 |
1 files changed, 76 insertions, 98 deletions
diff --git a/docs/06_Component_Documentation/Application_Framework/01_Introduction.md b/docs/06_Component_Documentation/Application_Framework/01_Introduction.md index 1deaec4..41759da 100644 --- a/docs/06_Component_Documentation/Application_Framework/01_Introduction.md +++ b/docs/06_Component_Documentation/Application_Framework/01_Introduction.md @@ -4,75 +4,79 @@ title: Introduction # Foreword -The AGL Application Framework is nothing new. However, the implementation used -up until the `lamprey` release has been retired starting with the `marlin` -release and replaced by a redesigned Application Framework one. However, this -new implementation isn't a 1:1 replacement, and as such it doesn't provide all -of the features of the previous Application Framework. Some of those will be -added back over time, others have been discarded in favor of more modern and/or -widely-used alternatives. - -With the `needlefish` release, further changes have been added, including a -[gRPC IPC](https://grpc.io/about), alongside a deprecated D-Bus one, as well as -using as using systemd units as opposed on using -[Desktop Entry specification](https://www.freedesktop.org/wiki/Specifications/desktop-entry-spec/) -to list applications, and relies entirely on systemd to start application, -rather than spawning them directly. - -Once all platforms transitioned to gRPC, the D-Bus functionality will be -removed entirely, mentioning it in only in documentation for history purposes. +AGL has worked at providing the components of an application framework for many +years. However, the implementation used up until the `lamprey` release was retired +starting with the `marlin` release, and replaced with a redesigned one. +However, this new implementation does not aim to be a 1:1 replacement, and as such +it does not provide all of the features of the previous framework. Some of those +will be added back over time, while others have been discarded in favor of more +modern and/or widely-used alternatives. + +With the `needlefish` release, further evolution of the replacement framework included: + +- Using [gRPC IPC](https://grpc.io/about) for the application launcher API. + The interim D-Bus based API was deprecated at this time, and removed in the + `pike` release. +- Using only systemd unit metadata in the application launcher instead of using + [Desktop Entry specification](https://www.freedesktop.org/wiki/Specifications/desktop-entry-spec/) + to list applications, and relying entirely on systemd for the application + lifecycle, rather than spawning them directly. # Introduction -As a provider of an integrated solution to build up on, AGL needs to define a -reliable and well-specified method for managing the deployment and integration -of applications and services, as well as the way they can interact with the -rest of the system. +With a goal of being the provider of an integrated solution to build up on, it +is useful for AGL to define a reliable and well-specified method for managing +the deployment and integration of applications and services, as well as the way +they can interact with the rest of the system. This is achieved by providing a common set of rules and components, known as -the Application Framework. By ensuring conformity to those rules, application -developers can have a good understanding of the requirements for creating and -packaging applications targeting AGL-based systems. Likewise, system developers -and integrators have a clear path for including such applications in AGL-based -products. +the application framework. By documenting those rules, application developers can +have a good understanding of the requirements for creating and packaging applications +targeting AGL-based systems that leverage the upstream application framework components. +Likewise, system developers and integrators have a clear path for including such +applications in AGL-based products. + +The application framework's scope extends to the following areas: -The Application Framework's scope extends to the following areas: - system services integration and lifecycle management -- user session management, including user-level applications and services - lifecycle management +- user-level application lifecycle management - inter-process communication In order to be as simple as possible and avoid any unneeded custom -implementation, the Application Framework relies mainly on third-party -technologies and/or software components, most of those being maintained under -the [freedesktop.org](https://www.freedesktop.org) umbrella. Those include: - +implementation, the application framework relies mainly on third-party +technologies and/or software components. They include: - [systemd](https://www.freedesktop.org/wiki/Software/systemd/): system services and user session services management - -- [D-Bus](https://www.freedesktop.org/wiki/Software/dbus/): inter-process - communication, with `needlefish' release deprecated phase. - - [gRPC](https://grpc.io/about): inter-process communication, new recommmended system-wide IPC, which should be used instead of D-Bus. - -- [Desktop Entry specification](https://www.freedesktop.org/wiki/Specifications/desktop-entry-spec/): - application enumeration and startup, now in deprecated phase, systemd being - the one would list out applications and handling start-up. +Note that while there are many open source software projects in the desktop Linux +space using [D-Bus](https://www.freedesktop.org/wiki/Software/dbus/) for inter-process +communication, AGL has decided to avoid using it for new development projects for the +following reasons: + +- It has proven challenging in the past to manage dependencies between and the + start-up of system and per-user D-Bus services in AGL. +- Managing the security of D-Bus APIs involves the use of PolicyKit, which is + somewhat heavyweight and not widely understood. As well, providing D-Bus + access to applications running inside containers or other sandbox schemes can + be significantly more complicated than e.g. using gRPC with authorization token + access control. +- D-Bus is not widely used in application development ecosystems outside of desktop + Linux. This matters when engaging with application developers in newer ecosystems + such as web applications or Flutter. AGL also provides reference implementations whenever possible and relevant, located in the [meta-agl](../../04_Developer_Guides/02_AGL_Layers/02_meta_agl.md) -layer under `meta-app-framework`. At the moment, the Application Framework -contains 2 such components: +layer under `meta-app-framework`. At the moment, the application framework +contains two such components: - `agl-session`: `systemd` unit files for user sessions management - - `applaunchd`: application launcher service -# Services management +# Service Management Both system and user services are managed by `systemd`, which provides a number of important features, such as dependency management or service monitoring: @@ -86,62 +90,38 @@ downtime. and other security-related options. It is also well integrated with D-Bus and can be used for a more fine-grained -control over D-Bus activated services: by delegating the actual service startup -to `systemd`, developers can take advantage of some of its advanced features, -allowing for improved reliability and security. +control over D-Bus activated services. By delegating the actual service start-up +to `systemd`, developers can take advantage of its advanced features, 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](03_Creating_a_New_Service.md) document. +Service](../../04_Developer_Guides/03_Creating_a_New_Service.md) document. -# User session management +# User Session Management Similarly, user sessions and the services they rely on are also managed by -`systemd`. - -AGL provides 2 `systemd` units: - - -1\. `agl-session@.service` is a template system service for managing user -sessions; it takes a username or UID as a parameter, creating a session for the -desired user. Instanciating this service can be achieved by enabling -`agl-session@USER.service`, for example by executing the following command on a -running system: +`systemd`. Prior to the `pike` release, AGL used a user session for the +`agl-driver` user for the running of user facing applications, including the +compositor. This has been replaced with using system units that use the +`User` directive. The reason for this is two-fold: -``` -$ systemctl enable agl-session@USER.service -``` +- Several useful systemd sandboxing features are unavailable to user session + units, or would require the use of unprivileged namespace mounting. The + latter is not necessarily available in vendor BSP kernels, and the security + characteristics of it are still a matter of some debate. +- Encoding dependencies between user session and system units is sometimes + not straightforward or impossible. -By default, AGL enables this service as `agl-session@agl-driver.service`, -running as user `agl-driver`. +# Inter-process Communication -*Note: while you can create sessions for as many users as needed, only one -instance of `agl-session@.service` is allowed per user.* - - -2\. `agl-session.target` is a user target for managing user services and their -dependencies. It is started by `agl-session@.service`. - -By default, `agl-compositor` is part of this target. It is therefore -automatically started for user `agl-driver`. - -Any other service needed as part of the user session should similarly depend on -this target by appending the following lines to their unit file: - -``` -[Install] -WantedBy=agl-session.target -``` - -# Inter-process communication - -In order to provide a "standard", language-independent IPC mechanism and avoid +In order to provide a language-independent, "standard", IPC mechanism and avoid the need for maintaining custom bindings for each programming language to be -used on top of AGL, the Application Framework used to promote the use of +used on top of AGL, the application framework previously promoted the use of [D-Bus](https://www.freedesktop.org/wiki/Software/dbus/) as the preferred way for applications to interact with services. Starting with `needlefish` release, -we instead switched to using [gRPC](https://grpc.io) for our system-wide IPC, -with D-Bus being kept to provide functionality to services and application +this has changed to recommending [gRPC](https://grpc.io) for our system-wide IPC, +with D-Bus being kept to provide functionality to services and applications which haven't transitioned yet to using gRPC. Most services already included in AGL provide one or several D-Bus interfaces, @@ -160,27 +140,25 @@ others: - [GeoClue](https://gitlab.freedesktop.org/geoclue/geoclue/-/wikis/home): geolocation -Similarly, we're in the phase of expanding various services to expose a +Similarly, ongoing work involves expanding various services to expose a gRPC interface. -# Application launcher service +# Application Launcher Service The Application Framework used to follow the guidelines of the [Desktop Entry specification](https://www.freedesktop.org/wiki/Specifications/desktop-entry-spec/) -for application enumeration and startup, but with the `needlefish` release +for application enumeration and start-up, but with the `needlefish` release instead it relies on systemd to provide that functionality, indirectly, by using the `applaunchd` application. As no simple reference implementation exists for this part of the specification, AGL provides an application launcher service named `applaunchd`. This service is part of the default user session, and as such is automatically -started on session startup. It can therefore be considered always available. +started on session start-up. It can therefore be considered always available. `applaunchd` enumerates applications installed on the system and provides a -D-bus (deprecated)/gRPC interface for services and applications to: +gRPC interface for services and applications to: + - query the list of available applications -- request the startup and/or activation of a specific application +- request the start-up of a specific application - be notified when applications are started or terminated - -`applaunchd` with the D-Bus interface is described with more details in -[the following document](02_Application_Startup_Dbus.md). |