# UI Packages

UIs (otherwise referred to as desktops or 'DE's) are the primary graphical way
that users interact with their systems. On postmarketOS, these UIs are packaged
in `postmarketos-ui-*` packages under `main/` in pmaports. The UI packages do not
include the projects that make up a UI, as those are instead packaged in
Alpine Linux's aports. The purpose of a UI package in postmarketOS is to
combine the individual components of a UI, alongside postmarketOS-specific
configuration, to create a functional out-of-the-box experience for users.

## How to add a new UI

To add a new UI, its components must first be packaged separately and
upstreamed to Alpine Linux's aports. Once this is complete, a new package
called `postmarketos-ui-<UI Name>` can be created under the `main/` directory
in pmaports. If there is more than one UI that uses the same configuration,
it is also possible to create a `postmarketos-base-ui-<UI Name>` package and
have the individual UIs depend upon it.

After adding a UI, add it to:
https://wiki.postmarketos.org/wiki/Category:Interface

## Unique APKBUILD variables and quirks

- **_pmb_groups**
  - Groups to which the default user should be added to during the
    installation.
- **_pmb_recommends**
  - Packages to install together with the UI, which can be uninstalled by the
     user.
- **_pmb_select**
  - Let `pmbootstrap init` display a prompt for each package in the given list
    of packages to choose which provider to use for each package.
- **_pmb_default**
  - Define the package to display as default during a `pmbootstrap init`
    `_pmb_select` prompt. Without this, the package with the highest priority
    will list as default .
- **pmb:drm**
  - Adding this to the `options` variable will mark the UI as requiring DRM
    support to function, hiding it from devices that do not support DRM on
    `pmbootstrap init`.
- **pkgdesc**
  - The same as a normal APKBUILD's `pkgdesc`, but it is also shown during
    `pmbootstrap init` beside the UI's name.

## Requirements for UI packages

- UIs are not required to support both OpenRC and systemd. While it is
  recommended to support both to allow user choice, it is up to the UI
  maintainers whether they support a service manager or not.
- UIs shall work out-of-the-box on first initialization, meaning that they
  should not require user intervention to start or require external
  configuration.
- UI packages shall attempt to comply with the upstream project's vision
  for the UI. This is excepted when changes are made to work better with a
  different device form-factor, to modify basic branding, or to comply with
  any other requirements.
- A UI shall be rejected if its inclusion would be a risk to community
  cohesion through the actions of the UIs upstream community, non-postmarketOS
  userbase, and/or other outstanding factors that make it obvious that a UI's
  inclusion would damage the project in some way.

## Recommendations for UI packages

- Only depend upon the minimal amount of packages needed to have a functional
  desktop as recommended by the upstream. For packages that are not core to
  the functionality of the desktop, these should be put into `_pmb_recommends`
  to allow the user to uninstall them if need-be.
- Create an `$pkgname-extras` subpackage to store the packages (usually apps)
  that are nice to have, but are not needed for a full experience of the
  desktop. Apps that could go here are multimedia apps, ebook readers, etc.
  Remember to put these packages in `_pmb_recommends` in the subpackage to
  allow the user to uninstall them.
- If a UI supports the ability to set a wallpaper, it is expected that the
  default wallpaper of postmarketOS is set by default. This is not a strict
  rule, as this is sometimes not possible due to technical constraints.
