Jump to content

Packaging

From postmarketOS Wiki
Revision as of 15:07, 8 April 2021 by MartijnBraam (talk | contribs) (Add amove docs)

This page explains how to create packages in postmarketOS, so they can be built with the usual pmbootstrap build hello-world.

General information

  • Read the APKBUILD_Reference
  • Don't add # Contributor: lines in pmaports (pmaports#543)
  • Don't copy maintainers from the other packages to packages you add (e.g. when temporarily forking them from Alpine).
  • Use pmbootstrap lint to lint your package
  • Alpine uses busybox' sh for building packages. Do not use bash specific features.

Generate a template

Create a template for a new package called mynewpackage in aports/main:

$ pmbootstrap newapkbuild mynewpackage
[21:34:27] Create /home/user/code/pmbootstrap/aports/main/mynewpackage
[21:34:27] Done

We pass the arguments to newapkbuild 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:

$ pmbootstrap newapkbuild "https://github.com/alpinelinux/abuild/archive/v3.1.0.tar.gz"

For reference, see the full help output:

$ pmbootstrap newapkbuild -h

Remember to update the checksums after changing the sources:

$ pmbootstrap checksum hello-world

Packaging git commits

Only package git commits when necessary. Stable releases are preferred. Consider asking upstream to tag releases.

  • pkgver: We use the following format: $lastrelease_gitYYYYMMDD, e.g. 1.0_git20171101 (that makes it easy to see how old the commit is and apk is able to upgrade the package properly when the next release, e.g. 1.1, comes out)
  • Save the git commit in a variable _commit=.... and use it throughout the APKBUILD (e.g. in the builddir), so it's easy to update it.
  • The source should be saved with the $_commit in the filename. For GitHub links, this means:
 source="$pkgname-$_commit.tar.gz::https://github.com/ORG/NAME/archive/$_commit.tar.gz"

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 subpackages= variable it's possible to define split functions that will run after the package() 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 $pkgname-dev, $pkgname-doc, $pkgname-openrc and $pkgname-static. 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 $pkgname-coolname:functionname. Here's an example:

# some variables skipped for smaller example
pkgname=hello-world
pkgver=1
arch="all"
subpackages="$pkgname-example:example"
source="main.c example.c Makefile"

build() {
	cd "$srcdir"
	make
}

package() {
	# The package will install /usr/bin/main and /usr/bin/example for this example
	make install DEST="$pkgdir"
}

example() {
	# This function is called after package() and will move files from the main package to the subpackage

	amove usr/share/example

	# The amove command is a utility that basically does this but with more error checking:
	mv $pkgdir/usr/share/example $subpkgdir/usr/share/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 -openrc subpackage [1]. To add such a package, just put $pkgname-openrc in subpackages. abuild will then use the default function to split the appropriate files into the subpackage, and to install the subpackage automatically if openrc is installed.

When to depend on -openrc subpackages

OpenRC is always installed in postmarketOS, meaning the -openrc 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 -openrc subpackages. Only that way the order is guaranteed, otherwise the post-install script may run before the -openrc subpackage is installed and then fail [2].

Example:

postmarketos-ui-phosh enables iio-sensor-proxy in its post-install script. Therefore it must depend on iio-sensor-proxy-openrc.

When should pkgver/pkgrel get increased?

Whenever you update a package, it must have a new version. A version consists of $pkgver-r$pkgrel. The APKBUILD_Reference says:

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

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.

Edge cases are packages without upstream sources (ex. gr. main/postmarketos-mkinitfs), 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:

  • linux-* packages: We always set the pkgver 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 pkgrel 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 _gitYYYYMMDD suffix (see "Packaging git commits" above).
  • device-* packages: This was not done consistently in the past, but it makes sense to update the pkgver when anything but the APKBUILD was changed. Because that is essentially the version of the software being packaged.

Outdated config.sub/config.guess from autotools

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

prepare() {
	default_prepare
	update_config_sub
	update_config_guess
}

Guidelines for packaging patches

  • The stable channel should be a snapshot of edge, therefore all patches that are desired on stable 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).

Related