Aster Boese
fb74aa230e
Updates and replaces https://wiki.postmarketos.org/wiki/UI_specific_package, being a bit more specific as to what is expected out of a UI package and how exactly to create one. Signed-off-by: Aster Boese <asterboese@mailbox.org> Part-of: <https://gitlab.postmarketos.org/postmarketOS/pmaports/-/merge_requests/8720>
77 lines
3.7 KiB
Markdown
77 lines
3.7 KiB
Markdown
# 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.
|