docs/06_Component_Documentation/Application_Framework/01_Introduction.md

   1 ---
   2 title: Introduction
   3 ---
   4
   5 # Foreword
   6
   7 The AGL Application Framework is nothing new. However, the implementation used
   8 up until the `lamprey` release has been retired starting with the `marlin`
   9 release and replaced by a redesigned Application Framework one. However, this
  10 new implementation isn't a 1:1 replacement, and as such it doesn't provide all
  11 of the features of the previous Application Framework. Some of those will be
  12 added back over time, others have been discarded in favor of more modern and/or
  13 widely-used alternatives.
  14
  15 With the `needlefish` release, further changes have been added, including a
  16 [gRPC IPC](https://grpc.io/about), alongside a deprecated D-Bus one, as well as
  17 using as using systemd units as opposed on using
  18 [Desktop Entry specification](https://www.freedesktop.org/wiki/Specifications/desktop-entry-spec/)
  19 to list applications, and relies entirely on systemd to start application,
  20 rather than spawning them directly.
  21
  22 Once all platforms transitioned to gRPC, the D-Bus functionality will be
  23 removed entirely, mentioning it in only in documentation for history purposes.
  24
  25 # Introduction
  26
  27 As a provider of an integrated solution to build up on, AGL needs to define a
  28 reliable and well-specified method for managing the deployment and integration
  29 of applications and services, as well as the way they can interact with the
  30 rest of the system.
  31
  32 This is achieved by providing a common set of rules and components, known as
  33 the Application Framework. By ensuring conformity to those rules, application
  34 developers can have a good understanding of the requirements for creating and
  35 packaging applications targeting AGL-based systems. Likewise, system developers
  36 and integrators have a clear path for including such applications in AGL-based
  37 products.
  38
  39 The Application Framework's scope extends to the following areas:
  40 - system services integration and lifecycle management
  41 - user session management, including user-level applications and services
  42   lifecycle management
  43 - inter-process communication
  44
  45 In order to be as simple as possible and avoid any unneeded custom
  46 implementation, the Application Framework relies mainly on third-party
  47 technologies and/or software components, most of those being maintained under
  48 the [freedesktop.org](https://www.freedesktop.org) umbrella. Those include:
  49
  50
  51 - [systemd](https://www.freedesktop.org/wiki/Software/systemd/): system
  52   services and user session services management
  53
  54
  55 - [D-Bus](https://www.freedesktop.org/wiki/Software/dbus/): inter-process
  56   communication, with `needlefish' release deprecated phase.
  57
  58 - [gRPC](https://grpc.io/about): inter-process communication, new recommmended
  59   system-wide IPC, which should be used instead of D-Bus.
  60
  61
  62 - [Desktop Entry specification](https://www.freedesktop.org/wiki/Specifications/desktop-entry-spec/):
  63   application enumeration and startup, now in deprecated phase, systemd being
  64   the one would list out applications and handling start-up.
  65
  66 AGL also provides reference implementations whenever possible and relevant,
  67 located in the [meta-agl](../../04_Developer_Guides/02_AGL_Layers/02_meta_agl.md)
  68 layer under `meta-app-framework`. At the moment, the Application Framework
  69 contains 2 such components:
  70
  71 - `agl-session`: `systemd` unit files for user sessions management
  72
  73 - `applaunchd`: application launcher service
  74
  75 # Services management
  76
  77 Both system and user services are managed by `systemd`, which provides a number
  78 of important features, such as dependency management or service monitoring:
  79 when starting a service, `systemd` will ensure any other units this service
  80 depends on are available, and otherwise start those dependencies. Similarly,
  81 `systemd` can automatically restart a crashed service, ensuring minimal
  82 downtime.
  83
  84 `systemd` also provides an efficient first layer of security through its
  85 [sandboxing](https://www.freedesktop.org/software/systemd/man/systemd.exec.html#Sandboxing)
  86 and other security-related options.
  87
  88 It is also well integrated with D-Bus and can be used for a more fine-grained
  89 control over D-Bus activated services: by delegating the actual service startup
  90 to `systemd`, developers can take advantage of some of its advanced features,
  91 allowing for improved reliability and security.
  92
  93 Each service should be represented by a `systemd` unit file installed to the
  94 appropriate location. More details can be obtained from the [Creating a New
  95 Service](03_Creating_a_New_Service.md) document.
  96
  97 # User session management
  98
  99 Similarly, user sessions and the services they rely on are also managed by
 100 `systemd`.
 101
 102 AGL provides 2 `systemd` units:
 103
 104
 105 1\. `agl-session@.service` is a template system service for managing user
 106 sessions; it takes a username or UID as a parameter, creating a session for the
 107 desired user.  Instanciating this service can be achieved by enabling
 108 `agl-session@USER.service`, for example by executing the following command on a
 109 running system:
 110
 111 ```
 112 $ systemctl enable agl-session@USER.service
 113 ```
 114
 115 By default, AGL enables this service as `agl-session@agl-driver.service`,
 116 running as user `agl-driver`.
 117
 118 *Note: while you can create sessions for as many users as needed, only one
 119 instance of `agl-session@.service` is allowed per user.*
 120
 121
 122 2\. `agl-session.target` is a user target for managing user services and their
 123 dependencies. It is started by `agl-session@.service`.
 124
 125 By default, `agl-compositor` is part of this target. It is therefore
 126 automatically started for user `agl-driver`.
 127
 128 Any other service needed as part of the user session should similarly depend on
 129 this target by appending the following lines to their unit file:
 130
 131 ```
 132 [Install]
 133 WantedBy=agl-session.target
 134 ```
 135
 136 # Inter-process communication
 137
 138 In order to provide a "standard", language-independent IPC mechanism and avoid
 139 the need for maintaining custom bindings for each programming language to be
 140 used on top of AGL, the Application Framework used to promote the use of
 141 [D-Bus](https://www.freedesktop.org/wiki/Software/dbus/) as the preferred way
 142 for applications to interact with services. Starting with `needlefish` release,
 143 we instead switched to using [gRPC](https://grpc.io) for our system-wide IPC,
 144 with D-Bus being kept to provide functionality to services and application
 145 which haven't transitioned yet to using gRPC.
 146
 147 Most services already included in AGL provide one or several D-Bus interfaces,
 148 and can therefore interact with D-Bus capable applications and services
 149 without requiring any additional component. Those services include, among
 150 others:
 151
 152 - [ConnMan](https://git.kernel.org/pub/scm/network/connman/connman.git/):
 153   network connectivity
 154
 155 - [BlueZ](http://www.bluez.org/): Bluetooth connectivity
 156
 157 - [oFono](https://git.kernel.org/pub/scm/network/ofono/ofono.git): telephony
 158   and modem management
 159
 160 - [GeoClue](https://gitlab.freedesktop.org/geoclue/geoclue/-/wikis/home):
 161   geolocation
 162
 163 Similarly, we're in the phase of expanding various services to expose a
 164 gRPC interface.
 165
 166 # Application launcher service
 167
 168 The Application Framework used to follow the guidelines of the [Desktop Entry
 169 specification](https://www.freedesktop.org/wiki/Specifications/desktop-entry-spec/)
 170 for application enumeration and startup, but with the `needlefish` release
 171 instead it relies on systemd to provide that functionality, indirectly, by
 172 using the `applaunchd` application.
 173
 174 As no simple reference implementation exists for this part of the
 175 specification, AGL provides an application launcher service named `applaunchd`.
 176 This service is part of the default user session, and as such is automatically
 177 started on session startup. It can therefore be considered always available.
 178
 179 `applaunchd` enumerates applications installed on the system and provides a
 180 D-bus (deprecated)/gRPC interface for services and applications to:
 181 - query the list of available applications
 182 - request the startup and/or activation of a specific application
 183 - be notified when applications are started or terminated
 184
 185 `applaunchd` with the D-Bus interface is described with more details in
 186 [the following document](02_Application_Startup_Dbus.md).