01_Application_Framework: 01_Introduction.md

This formats the entire page to at most 80 characters wide pagraphs.

Mentions that with 'needlefish' we started using gRPC and that we've
started to deprecate D-Bus, including the fact that we no longer spawn
directly applications, that we use system units for listing
applications. Most the of page is kept intact with those minor changes
being added.

Bug-AGL: SPEC-4700
Signed-off-by: Marius Vlad <marius.vlad@collabora.com>
Change-Id: Id19e6cea90fdbe9a6bd4eee851f83b9d0f800db5
Reviewed-on: https://gerrit.automotivelinux.org/gerrit/c/AGL/documentation/+/28521
Reviewed-by: Jan-Simon Moeller <jsmoeller@linuxfoundation.org>
Tested-by: Jan-Simon Moeller <jsmoeller@linuxfoundation.org>

1 files changed, 97 insertions, 71 deletions

diff --git a/docs/04_Developer_Guides/01_Application_Framework/01_Introduction.md b/docs/04_Developer_Guides/01_Application_Framework/01_Introduction.md
index 24d8c1a..e61e67f 100644
--- a/docs/04_Developer_Guides/01_Application_Framework/01_Introduction.md
+++ b/docs/04_Developer_Guides/01_Application_Framework/01_Introduction.md
@@ -4,49 +4,63 @@ 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.
+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 `needlefish` release, further changes have been added, including a gRPC
+interface, alongside a D-BUs one, as well as using systemd units to start
+applications.
+
 
 # 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.
+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.
+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
+- 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:
+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
 
-- [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, now in deprecated phase.
 
-- [D-Bus](https://www.freedesktop.org/wiki/Software/dbus/): inter-process communication
+- [gRPC](https://grpc.io/about): inter-process communication
 
 
 - [Desktop Entry specification](https://www.freedesktop.org/wiki/Specifications/desktop-entry-spec/):
-  application enumeration and startup
+  application enumeration and startup, now in deprecated phase, systemd being
+  the one would list out applications and handling start-up.
 
-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 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
 
@@ -54,56 +68,59 @@ moment, the Application Framework contains 2 such components:
 
 # 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.
+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.
+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.
+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`.
+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:
+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`.
+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.*
+*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`.
+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:
+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]
@@ -112,39 +129,48 @@ 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.
+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 used to promote 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
+which haven't transitioned yet to using gRPC.
 
-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:
+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
+- [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
+- [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
+- [GeoClue](https://gitlab.freedesktop.org/geoclue/geoclue/-/wikis/home):
+  geolocation
 
 # Application launcher service
 
-As mentioned above, the Application Framework follows the guidelines of the
+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.
+for application enumeration and startup, but now instead relies on systemd to
+provide that functionality indirectly, 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.
+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:
+`applaunchd` enumerates applications installed on the system and provides a
+D-bus (deprecated)/gRPC 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/).
+`applaunchd` is described with more details in
+[the following document](../02_Application_Startup/).