Packaging: Difference between revisions
mention build and checksum |
|||
Line 83: | Line 83: | ||
* <code>pkgrel</code>: Alpine/postmarketOS package release number. Starts at 0 (zero). Always increment <code>pkgrel</code> when making updates to an aport; reset <code>pkgrel</code> to 0 (zero) when incrementing <code>pkgver</code>. | * <code>pkgrel</code>: Alpine/postmarketOS package release number. Starts at 0 (zero). Always increment <code>pkgrel</code> when making updates to an aport; reset <code>pkgrel</code> to 0 (zero) when incrementing <code>pkgver</code>. | ||
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: | |||
* <code>linux-*</code> packages: We always set the <code>pkgver</code> 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 <code>pkgrel</code> 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 <code>_gitYYYYMMDD</code> suffix (see "Packaging git commits" above). | * <code>linux-*</code> packages: We always set the <code>pkgver</code> 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 <code>pkgrel</code> 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 <code>_gitYYYYMMDD</code> suffix (see "Packaging git commits" above). | ||
* <code>device-*</code> packages: This was not done consistently in the past, but it makes sense to update the <code>pkgver</code> when anything but the <code>APKBUILD</code> was changed. Because that is essentially the version of the software being packaged. | * <code>device-*</code> packages: This was not done consistently in the past, but it makes sense to update the <code>pkgver</code> when anything but the <code>APKBUILD</code> was changed. Because that is essentially the version of the software being packaged. |
Revision as of 11:28, 23 October 2018
This page explains how to create packages in postmarketOS, so they can be built with the usual pmbootstrap build hello-world
.
Quick start
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
General information
This section is hard to read, feel free to rewrite. |
- Please read this section from our upstream friends wiki (which we should also extend and improve)
- Please always package the latest version of a software (unless it is impossible because of software that depends on it, but try to avoid that!)
- Please do not copy maintainers/contributors from the other packages to your new ports (so they won't get annoyed by questions for pmOS/Alpine packages!). Instead please credit them in the commit messages (maybe with a link to the original build recipe)
- Alpine Linux uses
musl
as libc, notglibc
. Never addglibc
as dependency. - Alpine uses busybox'
sh
for building packages. Do not use bash specific features. - Manpages and other documentation goes into an extra -doc package in Alpine, and abuild will complain if the main package contains them. The solution is to add this:
subpackages="$pkgname-doc"
(more info) - You can look up the exact meaning of every variable and function in the APKBUILD Reference
- Set up the git hook from the development guide article to automatically verify checksums in your APKBUILDs and therefore making your life easier
- How to create a patch when packaging software
Beware of legacy APKBUILDs
Alpine's program to build packages, abuild
evolves constantly. But the APKBUILDs sometimes lack behind. Some APKBUILDs still have the following, which is unnecessary:
|| return 1
statements after every line (e.g.make || return 1
is not needed anymore, usemake
instead)- a custom
prepare()
function that does nothing but apply patches (more information)) - not using the
builddir
variable to point to the extracted source location (usually:builddir="$srcdir/$pkgname-$pkgver"
)
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 andapk
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 theAPKBUILD
(e.g. in thebuilddir
), 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 incrementpkgrel
when making updates to an aport; resetpkgrel
to 0 (zero) when incrementingpkgver
.
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 thepkgver
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 thepkgrel
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 thepkgver
when anything but theAPKBUILD
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
}
Porting packages from Arch Linux
Arch Linux' PKBUILD
format is similar to APKBUILD
of Alpine. If you don't know how to package a new program, check out how Arch does it.
Find the package
Search here, click the package name, click on "Source Files" on the top right. A git repo with the PKGBUILD
and all other files (such as patches) appears.
Differences between APKBUILDs and PKGBUILDs
APKBUILD
s do not have the arrays from bash, use flat strings instead- There's no
optdepends
-doc
subpackages (see above)APKBUILD
has different options (!makeflags won't work, but it has !strip and !check)