Packaging

From postmarketOS
Jump to navigation Jump to search

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
usage: pmbootstrap newapkbuild [-h] [--folder FOLDER] [-n PKGNAME]
                               [-d PKGDESC] [-l LICENSE] [-u URL]
                               [-a | -C | -m | -p | -y] [-s] [-c] [-f]
                               PKGNAME[-PKGVER] | SRCURL

positional arguments:
  PKGNAME[-PKGVER] | SRCURL
                        set either the package name (optionally with the
                        PKGVER at the end, e.g. 'hello-world-1.0') or the
                        download link to the source archive

optional arguments:
  -h, --help            show this help message and exit
  --folder FOLDER       set postmarketOS aports folder (default: main)
  -n PKGNAME            set package name (only use with SRCURL)
  -d PKGDESC            set package description
  -l LICENSE            set package license identifier from
                        <https://spdx.org/licenses/>
  -u URL                set package URL
  -a                    create autotools package (use ./configure ...)
  -C                    create CMake package (assume cmake/ is there)
  -m                    create meson package (assume meson.build is there)
  -p                    create perl package (assume Makefile.PL is there)
  -y                    create python package (assume setup.py is there)
  -s                    use sourceforge source URL
  -c                    copy a sample init.d, conf.d and install script
  -f                    force even if directory already exists

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"

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