Packaging

This page explains how to create packages in postmarketOS, so they can be built with the usual.

General information

 * Read the
 * Don't add  lines in pmaports
 * Don't copy maintainers from the other packages to packages you add (e.g. when temporarily forking them from Alpine).
 * Use  to lint your package
 * Alpine uses busybox'  for building packages. Do not use bash specific features.
 * If the software doesn't have a proper release yet, ask upstream to make a release.

Generate a template
Create a template for a new package called  in  :

We pass the arguments to from Alpine, which has lots of parameters to quickly customize the templates it generates. It is even possible to just specify the URL and let it download the tarball and automatically recognize the build system, package name and version:

For reference, see the full help output:

Remember to update the checksums after changing the sources:

Packaging git commits
Only package git commits when necessary. Stable releases are preferred. Consider asking upstream to tag releases. source="$pkgname-$_commit.tar.gz::https://github.com/ORG/NAME/archive/$_commit.tar.gz"
 * : We use the following format:, e.g.   (that makes it easy to see how old the commit is and   is able to upgrade the package properly when the next release, e.g.  , comes out)
 * Save the git commit in a variable  and use it throughout the   (e.g. in the  ), so it's easy to update it.
 * The should be saved with the   in the filename. For GitHub links, this means:

Subpackages
In some cases it's required to split up a package. For example if some files are not required unless specific software exists. With the  variable it's possible to define split functions that will run after the   function to move specific files to a subpackage. Abuild provides a few helper functions that automatically do some common split operations. Some of these are,  ,   and. The abuild output will usually contain a warning telling you to add these subpackages when those files are detected in the main package.

Sometimes you need to add custom subpackages, these can be defined with. Here's an example:

It's not required that the files in the split functions are installed by package first. It's possible to create split functions that create completely independent packages by taking files from $srcdir instead of $pkgdir

OpenRC subpackages
Alpine Linux and postmarketOS packages that provide openrc related files should have an  subpackage. To add such a package, just put  in. abuild will then use the default function to split the appropriate files into the subpackage, and to install the subpackage automatically if  is installed.

When to depend on -openrc subpackages
OpenRC is always installed in postmarketOS, meaning the  subpackage always gets installed automatically if the main package is installed.

Nevertheless, packages that enable OpenRC services in their post-install scripts must depend on the  subpackages. Only that way the order is guaranteed, otherwise the post-install script may run before the  subpackage is installed and then fail.

Example:

enables  in its post-install script. Therefore it must depend on.

When should pkgver/pkgrel get increased?
Whenever you update a package, it must have a new version. A version consists of. The says:


 * : The version of the software being packaged.
 * : Alpine/postmarketOS package release number. Starts at 0 (zero). Always increment  when making updates to an aport; reset   to 0 (zero) when incrementing.

As a general rule, whenever a change is made to upstream sources, pkgver should be increased. When packaging-related files (APKBUILD, any post-install scripts, patch files to upstream sources, etc) are changed, pkgrel should be increased.

A special case are packages without upstream sources (e.g. main/postmarketos-base), where the source files are included in the package directory. In those cases, the packaged sources should be treated as upstream sources, and the pkgver should increase when they are edited.

Other special cases, where this is not so obvious:
 * packages: We always set the  to the kernel version number and only increase it when the kernel source code has a new version number. All kernel config changes only increase the   number. In the case, that the linux kernel sources need to be updated, but the kernel version was not changed (Android kernel forks often do this), we can add a   suffix (see "Packaging git commits" above).
 * packages: This was not done consistently in the past, but it makes sense to update the  when anything but the   was changed. Because that is essentially the version of the software being packaged.

How to change versions when changing a package multiple times in one MR?
Each commit that changes an apkbuild has to increase pkgver/rel. So it should be fine if pkgrel in a single MR changed several times from -r1 to -r4 for example. (See .)

Note that CI currently expects the pkgrel to release by one in a MR, use CI tag  in the commit message of the last commit if it was increased multiple times. Creating a patch to fix this in CI scripts and editing this wiki page afterwards is welcome.

Guidelines for packaging patches

 * The release branches (v21.03 etc.) should be a snapshot of edge (master branch), therefore all patches that are desired on release branches need to be on edge too.
 * The maintenance effort for patches must be reasonable.
 * Patches must align with our principles.
 * Having patches that make software align to our principles are desired, even if they cannot be upstreamed.
 * Device specific patches/hacks should be contained in the device package, if possible. Or self-contained and affect only the patched package, if possible.
 * Upstream patches (if they can be upstreamed) as we add them to pmaports. Link to where the patch is being upstreamed in the packaged patch.
 * Each patch must have a meaningful description (explanation what it does and why it is needed).

Should my package be in postmarketOS or Alpine?
You should submit to and maintain your package in Alpine's aports instead of postmarketOS if possible, so more people can use it.

Exceptions:
 * packages that are needed for postmarketOS and will not get accepted in Alpine (example: waydroid-image)
 * packages that override configs from alpine (usually these go in postmarketos-* packages)
 * packages with postmarketOS branding (e.g. mobile-config-firefox mentions pmOS on the start page)
 * packages with postmarketOS specific hooks (osk-sdl triggers initramfs rebuild)
 * packages that define services to get enabled (usually in postmarketos-ui-* packages)
 * cross compiler related / old gcc versions (everything in cross/, see )
 * packages starting with: device-*, linux-*, firmware-*, soc-* (everything in device/)
 * device specific forks of packages (e.g. u-boot)
 * when upstreaming a package to alpine means it can't be moved out of aports/testing (e.g. crust depends on cross compiler pkg from testing)
 * packages used in pmOS testsuites (main/hello-world*)

Note that packages are initially submitted to the "testing" dir of Alpine's aports, and as soon as they are built and tested, you are expected to make another merge request that moves the package to the "community" dir. This is also important for postmarketOS, because without having your package in "community", it will not become available in the stable releases of Alpine.

Device specific quirks
Device specific quirks should be in device specific packages, if they only affect one device. If they affect more than one device:
 * udev rules:
 * since they only run on specific kernel modules, they are unlikely to cause problems with other devices that don't need them
 * so as long as they don't cause problems with devices that don't need the quirk, put them in postmarketos-base
 * this is consistent with how udev rules are done in general, by other packages (example)
 * we decided for now that it's not worth the overhead of creating a separate (sub)package for these lighweight udev rules
 * for other quirks: a subpackage (postmarketos-quirks-... or devicepkg-quirk-...? see )
 * at time of writing, this is just a proposal
 * create a quirks package, and one subpackage per quirk
 * let other devices that need them depend on these quirks
 * (nothing depends on the main quirks package)

Outdated config.sub/config.guess from autotools
In case the  or   are outdated, change the APKBUILD's prepare block to the following:

Related

 * How to create a patch when packaging software