2 title: Creating a New Application
5 In the context of AGL, "applications" are usually considered to be standalone
6 user facing infotainment applications that can be started in addition to the
7 default "homescreen" or similar user interface that will always be present.
8 Such applications can be enumerated and executed with `applaunchd`, the AGL
9 [application launcher service](02_Application_Startup.md). The following
10 sections walk through what is required to add an application to an AGL image
11 that uses applaunchd, as well as discussion of developer conveniences that
12 AGL provides to simplify doing so in the Yocto build environment.
16 As described in the [applaunchd documentation](02_Application_Startup.md#application-discovery),
17 applications need to have a systemd system unit with a name matching the pattern `agl-app*@*.service`.
18 The portion of the unit name between `@` and `.service` is used as the application identifier
19 (see [Application Identifiers](02_Application_Startup.md#application-identifiers)).
20 The use of `@` in the unit filename indicates the use of a template unit, which `applaunchd`
21 assumes will be used for applications (see below). Template unit files are discussed in the
22 systemd unit file [man page](https://www.freedesktop.org/software/systemd/man/systemd.unit.html#Description).
24 The requirements on the unit file contents are:
26 - The `Description` field is used as the desired display name of the application.
27 It is recommended that this be kept short, ideally to one or two words, in order to
28 avoid issues when applications are listed in a UI.
29 - While not a hard requirement, ideally the `User` field is used to specify running
30 the application as a non-privileged user. In the AGL demonstration images, the
31 `agl-driver` user is used.
35 # Graphical Application Requirements
37 In addition, graphical applications need to comply with a few more requirements:
39 1. Each application must set a Wayland application ID appropriately as soon as its main window
41 2. The `app-id` used must match the application identifier specified in the systemd unit filename.
43 Doing so will ensure other software can associate the actual `app-id` to the proper application.
45 *Note: application ID's are set using the [XDG toplevel](https://wayland-book.com/xdg-shell-basics/xdg-toplevel.html)
48 # Application Templates
50 To provide a working example of application template units, AGL includes templates
51 for generic, Flutter, and web applications as part of the `applaunchd` recipe in the
52 `meta-app-framework` layer in [meta-agl](../../04_Developer_Guides/02_AGL_Layers/02_meta_agl.md).
53 If applaunchd is built into an image using the recipe, these templates will be available
54 for applications to use for their systemd units by creating a symlink that includes the
55 application identifier. To simplify this, a `BitBake` class named `agl-app` is included in
56 the layer for use in application recipes. The different templates and their configuration
57 will be discussed further in the following sections.
59 ## Generic Graphical Application Template
61 The `agl-app@.service` template unit is intended for simple standalone graphical applications.
62 It makes the following assumptions by default:
64 - The application executable name is the same as the application identifier, and the
65 executable is available via the default `PATH`.
66 - The application `Description` will be the application identifier.
67 - The application should run as the `agl-driver` user.
69 If using the `agl-app` class in a recipe (with `inherit agl-app`), these defaults can be
70 changed via the variables:
72 - `AGL_APP_NAME`: overrides the value of the `Description` field to set the desired
73 application display name.
74 - `AGL_APP_EXEC`: overrides the application executable name.
76 If set, these variables will trigger the generation of one or more systemd `drop-in`
77 override files by the logic in the `agl-app` class. The use of `drop-in` configuration
78 files is discussed in the systemd unit file [man page](https://www.freedesktop.org/software/systemd/man/systemd.unit.html#Description).
80 Additionally, the variable `AGL_APP_ID` may be used to override the assumption that the
81 application identifier is the same as the recipe name. If specified, its value should be
82 the desired application identifier.
84 The following is a partial example BitBake recipe using the template for an application named
89 SUMMARY = "foo application"
90 HOMEPAGE = "https://git.automotivelinux.org/apps/foo"
91 LICENSE = "Apache-2.0"
92 LIC_FILES_CHKSUM = "file://LICENSE;md5=ae6497158920d9524cf208c09cc4c984"
94 PV = "1.0+git${SRCREV}"
96 SRC_URI = "git://git.automotivelinux.org/apps/foo;protocol=https;branch=master"
105 <Other application build configuration>
108 Note that this assumes that the recipe is named `foo_git.bb`. If the recipe was instead named
109 something like `foo-app_git.bb`, then `AGL_APP_ID = "foo"` would need to be added.
111 ## Flutter Application Template
113 The `agl-app-flutter@.service` template unit is intended for Flutter graphical applications
114 that use the `flutter-auto` Flutter embedder. It makes the following assumptions by default:
116 - The Flutter application name in `pubspec.yaml` is the same as the application identifier,
117 and the application bundle will be installed under the directory:
119 /usr/share/flutter/<application identifier>/<Flutter version>/<Flutter runtime type>
123 /usr/share/flutter/flutter_hvac/3.3.7/release
126 - The application `Description` will be the application identifier.
127 - The application should run as the `agl-driver` user.
129 If using the `agl-app` class in a recipe (with `inherit agl-app`), the use of the Flutter
130 template can be triggered by setting the variable `AGL_APP_TEMPLATE` to `agl-app-flutter`,
131 and the above defaults can be changed via the variables:
133 - `AGL_APP_NAME`: overrides the value of the `Description` field to set the desired
134 application display name.
136 If set, this will trigger the generation of a systemd `drop-in` override file by the logic
137 in the `agl-app` class. The use of `drop-in` configuration files is discussed in the systemd
138 unit file [man page](https://www.freedesktop.org/software/systemd/man/systemd.unit.html#Description).
140 Additionally, the variable `AGL_APP_ID` may be used to override the assumption that the
141 application identifier is the same as the recipe name. If specified, its value should be
142 the desired application identifier and Flutter application / bundle name.
144 The following is an example BitBake recipe using the template for a Flutter application
149 SUMMARY = "Flutter foo application"
150 HOMEPAGE = "https://git.automotivelinux.org/apps/flutter-foo"
151 LICENSE = "Apache-2.0"
152 LIC_FILES_CHKSUM = "file://License.md;md5=f712ede8d4f845976061925d1416fc40"
154 PV = "1.0+git${SRCREV}"
156 SRC_URI = "git://git.automotivelinux.org/apps/flutter-foo;protocol=https;branch=master"
161 inherit flutter-app agl-app
163 PUBSPEC_APPNAME = "foo"
164 FLUTTER_APPLICATION_INSTALL_PREFIX = "/flutter"
166 AGL_APP_TEMPLATE = "agl-app-flutter"
170 Note that this assumes that the recipe is named `foo_git.bb`, and that the application name
171 in the Flutter `pubspec.yaml` is `foo`. If the recipe was instead named something like
172 `flutter-foo_git.bb`, then `AGL_APP_ID = "foo"` would need to be added.
174 ## Web Application Template
176 The `agl-app-web@.service` template unit is intended for web applications run using the
177 Web Application Manager (WAM) service. It makes the following assumptions by default:
179 - The web application bundle directory name is the same as the application identifier, and the
180 bundle will be installed in the directory hierarchy:
182 /usr/lib/wam_apps/<application identifier>
186 /usr/lib/wam_apps/webapps-hvac
188 - The application `Description` will be the application identifier.
189 - The application should run as the `agl-driver` user.
191 If using the `agl-app` class in a recipe (with `inherit agl-app`), the use of the Flutter
192 template can be triggered by setting the variable `AGL_APP_TEMPLATE` to `agl-app-web`,
193 and the above defaults can be changed via the variables:
195 - `AGL_APP_NAME`: overrides the value of the `Description` field to set the desired
196 application display name.
197 - `AGL_APP_WAM_DIR`: overrides the application bundle directory name. This can be used if
198 the application bundle name does not match the application identifier.
200 If set, these variables will trigger the generation of one or more systemd `drop-in`
201 override files by the logic in the `agl-app` class. The use of `drop-in` configuration
202 files is discussed in the systemd unit file [man page](https://www.freedesktop.org/software/systemd/man/systemd.unit.html#Description).
204 Additionally, the variable `AGL_APP_ID` may be used to override the assumption that the
205 application identifier is the same as the recipe name.
207 The following is a partial example BitBake recipe using the template for a web application
212 SUMMARY = "Web foo application"
213 HOMEPAGE = "https://git.automotivelinux.org/apps/web-foo"
214 LICENSE = "Apache-2.0"
215 LIC_FILES_CHKSUM = "file://LICENSE;md5=3b83ef96387f14655fc854ddc3c6bd57"
217 PV = "1.0+git${SRCREV}"
219 SRC_URI = "git://git.automotivelinux.org/apps/web-foo;protocol=https;branch=master"
226 AGL_APP_TEMPLATE = "agl-app-web"
229 <Other web application build configuration>
232 Note that this assumes that the recipe is named `foo_git.bb`. If the recipe was instead named
233 something like `foo-web_git.bb`, then `AGL_APP_ID = "foo"` would need to be added.