From 120a2677992ea299eea5fb5cb0ed1081f76bb92c Mon Sep 17 00:00:00 2001 From: Vinod Ahuja Date: Sat, 19 Nov 2022 13:59:20 -0600 Subject: Updating File name and links in the documentation Updating documentation: 1. Renamed all the files and folder following 01-99 index numbering 2. Matched title name and file name 3. Inserted title in the files where ever missing 4. Updated all the reference links in the documentation Bug-AGL: [SPEC-4470] Signed-off-by: Vinod Ahuja Change-Id: Ib73e1f91107646e11b5b19ab6ead4080add506e4 Reviewed-on: https://gerrit.automotivelinux.org/gerrit/c/AGL/documentation/+/28170 Reviewed-by: Jan-Simon Moeller Tested-by: Jan-Simon Moeller --- .../01_Application_Framework/01_Introduction.md | 150 +++++++++++++++++ .../02_Application_Startup.md | 184 +++++++++++++++++++++ 2 files changed, 334 insertions(+) create mode 100644 docs/04_Developer_Guides/01_Application_Framework/01_Introduction.md create mode 100644 docs/04_Developer_Guides/01_Application_Framework/02_Application_Startup.md (limited to 'docs/04_Developer_Guides/01_Application_Framework') diff --git a/docs/04_Developer_Guides/01_Application_Framework/01_Introduction.md b/docs/04_Developer_Guides/01_Application_Framework/01_Introduction.md new file mode 100644 index 0000000..24d8c1a --- /dev/null +++ b/docs/04_Developer_Guides/01_Application_Framework/01_Introduction.md @@ -0,0 +1,150 @@ +--- +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. + +# 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. + +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's scope extends to the following areas: +- system services integration and lifecycle management +- user session management, including user-level applications and services lifecycle + management +- inter-process communication + +In order to be as simple as possible and avoid any unneded 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: + + +- [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 + + +- [Desktop Entry specification](https://www.freedesktop.org/wiki/Specifications/desktop-entry-spec/): + application enumeration and startup + +AGL also provides reference implementations whenever possible and relevant, located in +the [meta-agl](/04_Developer_Guides/02_AGL_Layers/02_meta_agl/) layer under `meta-app-framework`. At the +moment, the Application Framework contains 2 such components: + +- `agl-session`: `systemd` unit files for user sessions management + +- `applaunchd`: application launcher service + +# Services management + +Both system and user services are managed by `systemd`, which provides a number of +important features, such as dependency management or service monitoring: when starting +a service, `systemd` will ensure any other units this service depends on are available, +and otherwise start those dependencies. Similarly, `systemd` can automatically restart +a crashed service, ensuring minimal downtime. + +`systemd` also provides an efficient first layer of security through its +[sandboxing](https://www.freedesktop.org/software/systemd/man/systemd.exec.html#Sandboxing) +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. + +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. + +# 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: + +``` +$ systemctl enable agl-session@USER.service +``` + +By default, AGL enables this service as `agl-session@agl-driver.service`, running as +user `agl-driver`. + +*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 the need +for maintaining custom bindings for each programming language to be used on top of AGL, +the Application Framework promotes the use of [D-Bus](https://www.freedesktop.org/wiki/Software/dbus/) +as the preferred way for applications to interact with services. + +Most services already included in AGL provide one or several D-Bus interfaces, and can +therefore interact with D-Bus capable applications and services without requiring any +additional component. Those services include, among others: + +- [ConnMan](https://git.kernel.org/pub/scm/network/connman/connman.git/): network connectivity + +- [BlueZ](http://www.bluez.org/): Bluetooth connectivity + +- [oFono](https://git.kernel.org/pub/scm/network/ofono/ofono.git): telephony and modem + management + +- [GeoClue](https://gitlab.freedesktop.org/geoclue/geoclue/-/wikis/home): geolocation + +# Application launcher service + +As mentioned above, the Application Framework follows the guidelines of the +[Desktop Entry specification](https://www.freedesktop.org/wiki/Specifications/desktop-entry-spec/) +for application enumeration and startup. + +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. + +`applaunchd` enumerates applications installed on the system and provides a D-bus +interface for services and applications to: +- query the list of available applications +- request the startup and/or activation of a specific application +- be notified when applications are started or terminated + +`applaunchd` is described with more details in [the following document](../02_Application_Startup/). diff --git a/docs/04_Developer_Guides/01_Application_Framework/02_Application_Startup.md b/docs/04_Developer_Guides/01_Application_Framework/02_Application_Startup.md new file mode 100644 index 0000000..232f41e --- /dev/null +++ b/docs/04_Developer_Guides/01_Application_Framework/02_Application_Startup.md @@ -0,0 +1,184 @@ +--- +title: Application Startup +--- + +# Introduction + +At system runtime, it may be necessary for applications to start other applications +on demand. Such actions can be executed in reaction to a user request, or they may +be needed to perform a specific task. + +In order to do so, running applications and services need an established way of +discovering installed applications and executing those. The +[Desktop Entry specification](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html) +defines how applications can be discovered by using `.desktop` files, but there's no +simple reference implementation for this function. + +In order to provide a language-independent interface for applications and service to +use, AGL includes `applaunchd`, a user service part of the default session. + +*Note: as mentioned [previously](../01_Introduction/), services are managed using `systemd` +and are therefore not in the scope of this document.* + +# Application launcher service + +The purpose of `applaunchd` is to enumerate applications available on the system and +provide a way for other applications to query this list and start those on demand. +It is also able to notify clients of the startup and termination of applications it +manages. + +To that effect, `applaunchd` provides a D-Bus interface other applications can use +in order to execute those actions. + +*Note: `applaunchd` will only send notifications for applications it started; it isn't +aware of applications started by other means (`systemd`, direct executable call...), +and therefore can't send notifications for those.* + +## Application discovery + +On startup, `applaunchd` inspects all `.desktop` files present under the `applications/` +subfolder of any element of the `XDG_DATA_DIRS` environment variable, ignoring all entries +containing either the `NoDisplay=true` or `Hidden=true` lines. + +It then looks for the following keys: +- `Terminal` +- `DBusActivatable` + +If the desktop entry file contains the `Terminal` key set to `true`, then the application +is marked as a non-graphical one. As such, it won't be included in the applications list +if the client requests only graphical applications. + +If `DBusActivatable` is set to `true`, then the application is marked as D-Bus activated. +Additionally, `applaunchd` will search for a corresponding D-Bus service file in case this +line is missing. This is a workaround allowing D-Bus activated applications providing +an incomplete desktop entry file (i.e missing the `DBusActivatable` key) to be +identified as such. + +### Requirements for D-Bus activation + +`applaunchd` will always start D-Bus activatable applications using D-Bus activation +instead of executing the command line stated in the desktop entry file. + +This is handled by calling the `Activate` method of the +[org.freedesktop.Application](https://specifications.freedesktop.org/desktop-entry-spec/1.1/ar01s07.html) +interface with an empty argument. + +As a consequence, all D-Bus activatable applications **must** implement this D-Bus +interface. + +## Application identifiers + +Each application is identified by a unique Application ID. Although this ID can be +any valid string, it is highly recommended to use the "reverse DNS" convention in order +to avoid potential name collisions and ease D-Bus integration. + +The application ID is set in the desktop entry file itself for +[graphical applications](../3_Creating_a_New_Application/#graphical-applications): +it is the value of the `StartupWMClass` field, which must be identical to the `app-id` +advertised through the Wayland XDG toplevel protocol. In case this field is missing +(as is usually the case for non-graphical application), the application ID will be the +desktop entry file name, stripped from its `.desktop` extension. + +## D-Bus interface + +The `applaunchd` D-Bus interface is named `org.automotivelinux.AppLaunch`. The object +path for `applaunchd` is `/org/automotivelinux/AppLaunch`. The interface provides methods +for the following actions: +- retrieve the list of available applications; the client can choose to retrieve all + available applications, or only those suitable for a graphical environment +- request an application to be started + +Moreover, signals are available for clients to be notified when an application has +successfully started or its execution terminated. + +### Applications list + +The `listApplications` method allows clients to retrieve the list of available applications. +It takes one boolean argument named `graphical`: +- if set to `true`, only applications suitable for graphical environments are returned +- otherwise, the list contains all applications + +This method returns an array of variants (type `av`), each element being a structure made up +of 3 strings (type `(sss)`): +- the application ID +- the application's displayed name +- the full path to the application icon file (or an empty string if no icon was specified in + the application's desktop entry file) + +### Application startup request + +Applications can be started by using the `start` method, passing the corresponding application +ID as the only argument. This method doesn't return any data. + +If the application is already running, `applaunchd` won't start another instance, but instead +emit a `started` signal to notify clients the application is ready. + +### Status notifications + +The `org.automotivelinux.AppLaunch` interface provides 2 signals clients can connect to: +- `started` indicates an application has started + - for D-Bus activated applications, it is emitted upon successful completion of the + call to the `Activate` method of the `org.freedesktop.Application` interface + - for other applications, this signal is emitted as soon as the child process has been + successfully created +- `terminated` is emitted when an application quits + +Both signals have an additional argument named `appid`, containing the ID of the application +affected by the event. + +As mentioned above, the `started` signal is also emitted if `applaunchd` receives a request to +start an already running application. This can be useful, for example, when switching between +graphical applications: +- the application switcher doesn't need to track the state of each application; instead, it can + simply send a `start` request to `applaunchd` every time the user requests to switch to another + application +- the desktop environment then receives the `started` signal, indicating it should activate the + window with the corresponding `app-id` + +## Testing + +`applaunchd` can be manually tested using the `gdbus` command-line tool: + +1. Query the application list (graphical applications only): + +``` +$ gdbus call --session --dest "org.automotivelinux.AppLaunch" \ + --object-path "/org/automotivelinux/AppLaunch" \ + --method "org.automotivelinux.AppLaunch.listApplications" \ + true +``` + +This command will output something similar to what follows: + +``` +([<('navigation', 'Navigation', '/usr/share/icons/hicolor/scalable/navigation.svg')>, + <('settings', 'Settings', '/usr/share/icons/hicolor/scalable/settings.svg')>, + <('dashboard', 'Dashboard', '/usr/share/icons/hicolor/scalable/dashboard.svg')>, + <('hvac', 'HVAC', '/usr/share/icons/hicolor/scalable/hvac.svg')>, + <('org.freedesktop.weston.wayland-terminal', 'Weston Terminal', '/usr/share/icons/Adwaita/scalable/apps/utilities-terminal-symbolic.svg')>],) +``` + +2. Request startup of the `org.freedesktop.weston.wayland-terminal` application: + +``` +$ gdbus call --session --dest "org.automotivelinux.AppLaunch" \ + --object-path "/org/automotivelinux/AppLaunch" \ + --method "org.automotivelinux.AppLaunch.start" \ + "org.freedesktop.weston.wayland-terminal" +``` + +3. Monitor signals emitted by `applaunchd`: + +``` +$ gdbus monitor --session --dest "org.automotivelinux.AppLaunch" +``` + +This results in the following output when starting, then exiting, the +`org.freedesktop.weston.wayland-terminal` application: + +``` +Monitoring signals from all objects owned by org.automotivelinux.AppLaunch +The name org.automotivelinux.AppLaunch is owned by :1.4 +/org/automotivelinux/AppLaunch: org.automotivelinux.AppLaunch.started ('org.freedesktop.weston.wayland-terminal',) +/org/automotivelinux/AppLaunch: org.automotivelinux.AppLaunch.terminated ('org.freedesktop.weston.wayland-terminal',) +``` -- cgit 1.2.3-korg