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