docs/06_Component_Documentation/Application_Framework/03_Creating_a_New_Application.md

   1 ---
   2 title: Creating a New Application
   3 ---
   4
   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.
  13
  14 # Basic Requirements
  15
  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).
  23
  24 The requirements on the unit file contents are:
  25
  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.
  32
  33 Blah blah icon...
  34
  35 # Graphical Application Requirements
  36
  37 In addition, graphical applications need to comply with a few more requirements:
  38
  39 1. Each application must set a Wayland application ID appropriately as soon as its main window
  40 is created.
  41 2. The `app-id` used must match the application identifier specified in the systemd unit filename.
  42
  43 Doing so will ensure other software can associate the actual `app-id` to the proper application.
  44
  45 *Note: application ID's are set using the [XDG toplevel](https://wayland-book.com/xdg-shell-basics/xdg-toplevel.html)
  46 Wayland interface.*
  47
  48 # Application Templates
  49
  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.
  58
  59 ## Generic Graphical Application Template
  60
  61 The `agl-app@.service` template unit is intended for simple standalone graphical applications.
  62 It makes the following assumptions by default:
  63
  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.
  68
  69 If using the `agl-app` class in a recipe (with `inherit agl-app`), these defaults can be
  70 changed via the variables:
  71
  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.
  75
  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).
  79
  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.
  83
  84 The following is a partial example BitBake recipe using the template for an application named
  85 `foo`:
  86
  87 ```text
  88
  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"
  93
  94 PV = "1.0+git${SRCREV}"
  95
  96 SRC_URI = "git://git.automotivelinux.org/apps/foo;protocol=https;branch=master"
  97 SRCREV = "abcdef012"
  98
  99 S = "${WORKDIR}/git"
 100
 101 inherit agl-app
 102
 103 AGL_APP_NAME = "Foo"
 104
 105 <Other application build configuration>
 106 ```
 107
 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.
 110
 111 ## Flutter Application Template
 112
 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:
 115
 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:
 118   ```text
 119   /usr/share/flutter/<application identifier>/<Flutter version>/<Flutter runtime type>
 120   ```
 121   For example:
 122   ```text
 123   /usr/share/flutter/flutter_hvac/3.3.7/release
 124   ```
 125
 126 - The application `Description` will be the application identifier.
 127 - The application should run as the `agl-driver` user.
 128
 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:
 132
 133 - `AGL_APP_NAME`: overrides the value of the `Description` field to set the desired
 134   application display name.
 135
 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).
 139
 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.
 143
 144 The following is an example BitBake recipe using the template for a Flutter application
 145 named `foo`:
 146
 147 ```text
 148
 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"
 153
 154 PV = "1.0+git${SRCREV}"
 155
 156 SRC_URI = "git://git.automotivelinux.org/apps/flutter-foo;protocol=https;branch=master"
 157 SRCREV = "abcdef012"
 158
 159 S = "${WORKDIR}/git"
 160
 161 inherit flutter-app agl-app
 162
 163 PUBSPEC_APPNAME = "foo"
 164 FLUTTER_APPLICATION_INSTALL_PREFIX = "/flutter"
 165
 166 AGL_APP_TEMPLATE = "agl-app-flutter"
 167 AGL_APP_NAME = "Foo"
 168 ```
 169
 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.
 173
 174 ## Web Application Template
 175
 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:
 178
 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:
 181   ```
 182   /usr/lib/wam_apps/<application identifier>
 183   ```
 184   For example:
 185   ```
 186   /usr/lib/wam_apps/webapps-hvac
 187   ```
 188 - The application `Description` will be the application identifier.
 189 - The application should run as the `agl-driver` user.
 190
 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:
 194
 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.
 199
 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).
 203
 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.
 206
 207 The following is a partial example BitBake recipe using the template for a web application
 208 named `foo`:
 209
 210 ```text
 211
 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"
 216
 217 PV = "1.0+git${SRCREV}"
 218
 219 SRC_URI = "git://git.automotivelinux.org/apps/web-foo;protocol=https;branch=master"
 220 SRCREV = "abcdef012"
 221
 222 S = "${WORKDIR}/git"
 223
 224 inherit agl-app
 225
 226 AGL_APP_TEMPLATE = "agl-app-web"
 227 AGL_APP_NAME = "Foo"
 228
 229 <Other web application build configuration>
 230 ```
 231
 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.