docs/3_Developer_Guides/1_Application_Framework/1_Introduction.md

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