From ecccce4b62c048272dd48378cc05d7165746b83e Mon Sep 17 00:00:00 2001 From: Scott Murray Date: Tue, 10 Oct 2023 18:03:44 -0400 Subject: [PATCH] Move application framework section Move application framework section from "Developer Guides" to "Component Documentation" and fix all links. Bug-AGL: SPEC-4928 Signed-off-by: Scott Murray Change-Id: I6bb10908860860d6634b23f6a458959397a98e81 Reviewed-on: https://gerrit.automotivelinux.org/gerrit/c/AGL/documentation/+/29283 Reviewed-by: Jan-Simon Moeller Tested-by: Jan-Simon Moeller --- docs/06_Component_Documentation/01_AGL_components.md | 2 +- docs/06_Component_Documentation/02_agl_compositor.md | 2 +- docs/06_Component_Documentation/06_application_framework.md | 7 ------- .../Application_Framework}/01_Introduction.md | 6 +++--- .../Application_Framework}/02_Application_Startup.md | 8 ++++---- .../Application_Framework}/02_Application_Startup_Dbus.md | 6 +++--- .../Application_Framework}/03_Creating_a_New_Service.md | 2 +- .../04_Creating_a_New_Application_Dbus.md | 4 ++-- .../Application_Framework}/images/application_switching.msc | 0 .../Application_Framework}/images/application_switching.png | Bin .../Application_Framework}/images/start_and_activation.msc | 0 .../Application_Framework}/images/start_and_activation.png | Bin 12 files changed, 15 insertions(+), 22 deletions(-) delete mode 100644 docs/06_Component_Documentation/06_application_framework.md rename docs/{04_Developer_Guides/01_Application_Framework => 06_Component_Documentation/Application_Framework}/01_Introduction.md (97%) rename docs/{04_Developer_Guides/01_Application_Framework => 06_Component_Documentation/Application_Framework}/02_Application_Startup.md (96%) rename docs/{04_Developer_Guides/01_Application_Framework => 06_Component_Documentation/Application_Framework}/02_Application_Startup_Dbus.md (96%) rename docs/{04_Developer_Guides/01_Application_Framework => 06_Component_Documentation/Application_Framework}/03_Creating_a_New_Service.md (97%) rename docs/{04_Developer_Guides/01_Application_Framework => 06_Component_Documentation/Application_Framework}/04_Creating_a_New_Application_Dbus.md (96%) rename docs/{04_Developer_Guides => 06_Component_Documentation/Application_Framework}/images/application_switching.msc (100%) rename docs/{04_Developer_Guides => 06_Component_Documentation/Application_Framework}/images/application_switching.png (100%) rename docs/{04_Developer_Guides => 06_Component_Documentation/Application_Framework}/images/start_and_activation.msc (100%) rename docs/{04_Developer_Guides => 06_Component_Documentation/Application_Framework}/images/start_and_activation.png (100%) diff --git a/docs/06_Component_Documentation/01_AGL_components.md b/docs/06_Component_Documentation/01_AGL_components.md index 57dbe29..b36580d 100644 --- a/docs/06_Component_Documentation/01_AGL_components.md +++ b/docs/06_Component_Documentation/01_AGL_components.md @@ -24,4 +24,4 @@ title: AGL Components ### Lifecycle management -- [Application Framework](../../04_Developer_Guides/01_Application_Framework/01_Introduction/) +- [Application Framework](Application_Framework/01_Introduction.md) diff --git a/docs/06_Component_Documentation/02_agl_compositor.md b/docs/06_Component_Documentation/02_agl_compositor.md index c5221cb..9e62890 100644 --- a/docs/06_Component_Documentation/02_agl_compositor.md +++ b/docs/06_Component_Documentation/02_agl_compositor.md @@ -16,7 +16,7 @@ library, to control and signal back to the compositor when applications were started, among other things. Management of applications, starting, running and stopping them is done in AGL -with AppFW [Application Framework Management](../04_Developer_Guides/01_Application_Framework/01_Introduction.md), +with AppFW [Application Framework Management](Application_Framework/01_Introduction.md), which is an umbrella name to denote the suite of tools and daemons that handle all of that. It is integrated with systemd and with the current security model. Applications can use AppFW to hang off data, and to pass it down to diff --git a/docs/06_Component_Documentation/06_application_framework.md b/docs/06_Component_Documentation/06_application_framework.md deleted file mode 100644 index 1af8796..0000000 --- a/docs/06_Component_Documentation/06_application_framework.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Application Framework ---- - -# AppFW - -FIXME. diff --git a/docs/04_Developer_Guides/01_Application_Framework/01_Introduction.md b/docs/06_Component_Documentation/Application_Framework/01_Introduction.md similarity index 97% rename from docs/04_Developer_Guides/01_Application_Framework/01_Introduction.md rename to docs/06_Component_Documentation/Application_Framework/01_Introduction.md index 4084032..1deaec4 100644 --- a/docs/04_Developer_Guides/01_Application_Framework/01_Introduction.md +++ b/docs/06_Component_Documentation/Application_Framework/01_Introduction.md @@ -64,7 +64,7 @@ the [freedesktop.org](https://www.freedesktop.org) umbrella. Those include: 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/) +located in the [meta-agl](../../04_Developer_Guides/02_AGL_Layers/02_meta_agl.md) layer under `meta-app-framework`. At the moment, the Application Framework contains 2 such components: @@ -92,7 +92,7 @@ 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](../03_Creating_a_New_Service/) document. +Service](03_Creating_a_New_Service.md) document. # User session management @@ -183,4 +183,4 @@ D-bus (deprecated)/gRPC interface for services and applications to: - be notified when applications are started or terminated `applaunchd` with the D-Bus interface is described with more details in -[the following document](../02_Application_Startup_Dbus/). +[the following document](02_Application_Startup_Dbus.md). diff --git a/docs/04_Developer_Guides/01_Application_Framework/02_Application_Startup.md b/docs/06_Component_Documentation/Application_Framework/02_Application_Startup.md similarity index 96% rename from docs/04_Developer_Guides/01_Application_Framework/02_Application_Startup.md rename to docs/06_Component_Documentation/Application_Framework/02_Application_Startup.md index 56876a4..3cd7ca0 100644 --- a/docs/04_Developer_Guides/01_Application_Framework/02_Application_Startup.md +++ b/docs/06_Component_Documentation/Application_Framework/02_Application_Startup.md @@ -151,7 +151,7 @@ This can be useful, for example, when switching between graphical applications: Application start-up, activation and application switching are sometimes conflated into a single operation but underneath some of these are distinct steps, and a bit flaky in some circumstances. -The [AGL compositor](../../06_Component_Documentation/02_agl_compositor/) has +The [AGL compositor](../02_agl_compositor.md) has some additional events which one can use when creating an application start-up & switching scheme in different run-times. @@ -203,7 +203,7 @@ the following application state events: The `started` event can be used in correlation with the `StartApplication` method from `applaunchd` such that upon received the `started` even, it can explicitly activate that particular appid in order for the compositor to -display it. See [AGL compositor](../../06_Component_Documentation/02_agl_compositor/) +display it. See [AGL compositor](../02_agl_compositor.md) about how activation should be handled. *Note: These can only be received if by the client shell which binds to the @@ -229,7 +229,7 @@ they are a 1:1 match. Here's the state diagram for the Qt homescreen implementation of the application start-up: -![Application_start](../images/start_and_activation.png) +![Application_start](images/start_and_activation.png) ### Application switching @@ -241,7 +241,7 @@ application would basically call `StartApplication`. That would eventually reach the run-time/shell-client and have a handler that would ultimately activate the application ID. -![Application_switching](../images/application_switching.png) +![Application_switching](images/application_switching.png) *Note: In practice, the run-time/shell-client would subscribe to both `applaunchd` and to the AGL compositor, either Wayland native events, or using the gPRC-proxy diff --git a/docs/04_Developer_Guides/01_Application_Framework/02_Application_Startup_Dbus.md b/docs/06_Component_Documentation/Application_Framework/02_Application_Startup_Dbus.md similarity index 96% rename from docs/04_Developer_Guides/01_Application_Framework/02_Application_Startup_Dbus.md rename to docs/06_Component_Documentation/Application_Framework/02_Application_Startup_Dbus.md index 927b52f..f951e0e 100644 --- a/docs/04_Developer_Guides/01_Application_Framework/02_Application_Startup_Dbus.md +++ b/docs/06_Component_Documentation/Application_Framework/02_Application_Startup_Dbus.md @@ -5,7 +5,7 @@ title: Application Startup with D-Bus *Note: The that the D-Bus interface is in deprecation phase and for the time being only available for application & services that still rely on them. Once we migrate everything to gRPC, we will remove D-Bus IPC support. Please see -[Application Startup with gRPC](../02_Application_Startup/) for the latest +[Application Startup with gRPC](02_Application_Startup.md) for the latest information* # Introduction @@ -23,7 +23,7 @@ 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` +*Note: as mentioned [previously](01_Introduction.md), services are managed using `systemd` and are therefore not in the scope of this document.* # Application launcher service @@ -79,7 +79,7 @@ any valid string, it is highly recommended to use the "reverse DNS" convention i to avoid potential name collisions and ease D-Bus integration. The application ID is set in the desktop entry file itself for -[graphical applications](/04_Developer_Guides/03_Creating_a_New_Application_Dbus/#graphical-applications): +[graphical applications](04_Creating_a_New_Application_Dbus.md#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 diff --git a/docs/04_Developer_Guides/01_Application_Framework/03_Creating_a_New_Service.md b/docs/06_Component_Documentation/Application_Framework/03_Creating_a_New_Service.md similarity index 97% rename from docs/04_Developer_Guides/01_Application_Framework/03_Creating_a_New_Service.md rename to docs/06_Component_Documentation/Application_Framework/03_Creating_a_New_Service.md index 22e98ea..69bde48 100644 --- a/docs/04_Developer_Guides/01_Application_Framework/03_Creating_a_New_Service.md +++ b/docs/06_Component_Documentation/Application_Framework/03_Creating_a_New_Service.md @@ -40,7 +40,7 @@ WantedBy=agl-session.target ``` The `WantedBy=agl-session.target` indicates the service is part of the default AGL -user session, as mentioned in the [Application Framework](../01_Application_Framework/01_Introduction/#user-session-management) +user session, as mentioned in the [Application Framework](01_Introduction.md#user-session-management) documentation. The `Restart=on-failure` directive ensures the service will be automatically diff --git a/docs/04_Developer_Guides/01_Application_Framework/04_Creating_a_New_Application_Dbus.md b/docs/06_Component_Documentation/Application_Framework/04_Creating_a_New_Application_Dbus.md similarity index 96% rename from docs/04_Developer_Guides/01_Application_Framework/04_Creating_a_New_Application_Dbus.md rename to docs/06_Component_Documentation/Application_Framework/04_Creating_a_New_Application_Dbus.md index edee0dc..2ee6bdf 100644 --- a/docs/04_Developer_Guides/01_Application_Framework/04_Creating_a_New_Application_Dbus.md +++ b/docs/06_Component_Documentation/Application_Framework/04_Creating_a_New_Application_Dbus.md @@ -12,7 +12,7 @@ Applications are: - Graphical interface allowing user to interact with. Applications are executed by `applaunchd`, the AGL -[application launcher service](../01_Application_Framework/02_Application_Startup_Dbus/). +[application launcher service](02_Application_Startup_Dbus.md). # Basic requirements @@ -64,7 +64,7 @@ refer to the [graphical applications](#graphical-applications) section for more # D-Bus activation -Similarly to [services](../02_Creating_a_New_Service/#d-bus-activation), applications can +Similarly to [services](03_Creating_a_New_Service.md#d-bus-activation), applications can also be activated through D-Bus. Such applications must name their `.desktop` file after the D-Bus name they register. In addition, diff --git a/docs/04_Developer_Guides/images/application_switching.msc b/docs/06_Component_Documentation/Application_Framework/images/application_switching.msc similarity index 100% rename from docs/04_Developer_Guides/images/application_switching.msc rename to docs/06_Component_Documentation/Application_Framework/images/application_switching.msc diff --git a/docs/04_Developer_Guides/images/application_switching.png b/docs/06_Component_Documentation/Application_Framework/images/application_switching.png similarity index 100% rename from docs/04_Developer_Guides/images/application_switching.png rename to docs/06_Component_Documentation/Application_Framework/images/application_switching.png diff --git a/docs/04_Developer_Guides/images/start_and_activation.msc b/docs/06_Component_Documentation/Application_Framework/images/start_and_activation.msc similarity index 100% rename from docs/04_Developer_Guides/images/start_and_activation.msc rename to docs/06_Component_Documentation/Application_Framework/images/start_and_activation.msc diff --git a/docs/04_Developer_Guides/images/start_and_activation.png b/docs/06_Component_Documentation/Application_Framework/images/start_and_activation.png similarity index 100% rename from docs/04_Developer_Guides/images/start_and_activation.png rename to docs/06_Component_Documentation/Application_Framework/images/start_and_activation.png -- 2.16.6