Creating an Alpine package: Difference between revisions

Revision as of 10:31, 5 March 2017

Requirements

To build a package for Alpine Linux you need an Alpine Linux installation. Check the Installation page to see all available installation options.

Setup your system and account

The alpine-sdk is a metapackage that pulls in the most essential packages used to build new packages. Also install and configure a way to elevate privileges, such as sudo or doas, and an editor, such as vi, nano, micro.

# apk add alpine-sdk

This would be a good time to create a normal user account for you to work in. To make life easier later, it's a good idea to add this user to the wheel group; operations that require superuser privileges can now be done with sudo or doas.

The aports tree is in git so before we clone it, let's configure git.

Configure your global git config

Configure your name and email address in git. This name and email address will show up in all your commits:

$ git config --global user.name "Your Full Name" $ git config --global user.email "your@email.address"

Using git config without --global let you configure other details for a specific git repository.

Refer Development using git to grasp basics of Git operations.

Configure abuild

Abuild needs to be configured for both the system and user.

Edit the file /etc/abuild.conf as per requirements. Most of the defaults can be left alone, unless you are developing for a custom platform, in which case the comments in the file should guide you. The one field to edit is PACKAGER, so that you can get credit (or blame) for packages you create.

In order to use abuild command The user executing abuild must be a member of the abuild group:

# addgroup <yourusername> abuild

Note: Remember to logout and login again for the group change to have effect.

For abuild a public/private rsa key pair is needed. The abuild-keygen command from abuild package generates and configures the security keys.

$ doas abuild-keygen -a -i

abuild-keygen options

-a Set PACKAGER_PRIVKEY=<generated key> in abuild.conf
-i Install public key into /etc/apk/keys using sudo
-h Show this help
-n Non-interactive. Use defaults
-q Quiet mode

Getting some help

It might be wise to start by checking what the abuild program can/cannot do.

abuild -h

Creating an APKBUILD file

Use a template APKBUILD

To create the actual APKBUILD file newapkbuild can serve you a template to start with. It will create a directory with the given package name, place an example/template APKBUILD file to the given directory, and fill some variables if those are provided. Please check the package policies page about naming details.

If you doubt to which repository your package belongs to you can safely use testing. Building package in your aports/testing directory is not mandatory but this way the package is already at the right place.

The newapkbuild tool, which is installed as part of the abuild package, can generate a new APKBUILD template to use as a starting point. The manual page (available via man newapkbuild) describes all options for newapkbuild.

If you doubt to which repository your package belongs to you can safely use testing. Building package in your aports/testing directory is not mandatory but this way the package is already at the right place.

Tip: Follow the package naming conventions mentioned in package policies while choosing a packagename.

The following command will create a directory with the given package name, place an example/template APKBUILD file in the directory, and fill some variables if those are provided.

newapkbuild packagename

If you are creating a daemon package which needs initd scripts you can add the -c option as follows:

newapkbuild -c packagename

This will copy the sample initd and confd files to the build directory. A third file sample.install file will be copied as well (we will discuss this later on).

Note: On older Alpine systems, abuild -c -n packagename was the way to create APKBUILD files. The 'packagename' was a parameter to the -n option so order of -c and -n matters.

apkbuild-cpan simplifies the creation of perl packages from CPAN and apkbuild-pypi ease the generation of APKBUILD files for python packages from PyPi.

If you are create a daemon package which needs initd scripts you can add the -c making it:

newapkbuild -c packagename

This will copy the sample initd and confd files to the build directory.
A third file sample.install file will be copied as well (we will discuss this later on).

Modify your APKBUILD

Edit APKBUILD and fill in the needed info (especially pkgname, pkgver, pkgdesc, url, license, depends and source).

If you are going to use any of the variables for directories like $pkgdir, always make sure they are double quoted like:

"$pkgdir"/somedir

This will prevent issues with spaces/special characters in the future.

Note: If you like syntax highlighting we suggest you to install vim. We have setup vim to recognize the APKBUILD file as a bash scripts so its easier to read them.

APKBUILD variables/functions

source

The source variable is not only used to list the remote source files to fetch, it is also used to list the local files that abuild will need in order to build the apk. Examples of such local files include: init.d files, conf.d files, install files (see install variable), patches, and all other necessary files.

Here are few things to note:

When you are finished adding local and/or remote files to source, you can execute the following command to add their checksums to the APKBUILD file:

abuild checksum

Note: When later updating the content of source, or updating a file that is listed in source, you must also update their checksums again with the same command.

When the remote file is hosted at SourceForge, it's best to specify the special mirrors link used by SourceForge:

http://downloads.sourceforge.net/$pkgname/$pkgname-$pkgver.tar.gz

(or similar depending on the package).

When the remote filename is not specified in the URI (ie, does not end in '/software-1.0.tar.gz'), such as:

http://oss.example.org/?get=software&ver=1.0

You must prepend '${pkgname}-${pkgver}.tar.gz::' to the protocol, like so:

source="${pkgname}-${pkgver}.tar.gz::http://oss.example.org/?get=software&ver=1.0"

This causes the file to be saved as software-1.0.tar.gz where abuild can use it, instead of ?get=software&ver=1.0, where abuild cannot use it.

Some projects didn't provide a release tarball. Beware that some git services (gitweg, cgit, …?) doesn’t provide stable tarballs, so when you point source to an tarball like http://repo.or.cz/w/gitstats.git/snapshot/ad7efbb9399e60cee6cb217c6b47e604174a8093.tar.gz, then you will run into issues because the checksum changes when downloading on the build system. This is not a problem on GitHub, GitLab and other decent services provides, they provide stable tarballs.

abuild currently supports the following protocols for remote file retrieval:
- http
- https
- ftp

abuild currently supports the following archive types/archive file extensions:
- .tar.gz / .tgz
- .tar.bz2
- .tar.lzma
- .tar.xz
- .zip

depends & makedepends

Depends are the actual running dependencies that a package would need when it is running. Makedepends are only needed when you are building a package. If you set a package, in depends you do not need to add it to makedepends as well. The best way to find out what the depends and makedepends of a package are is to RTFM.

No kidding, lots of important information can be found it the package INSTALL and README file (or the likes). Another good way is the run ./configure --help from the source directory to see which options are needed for configure to finish without errors. If you do not yet have a source directory you can create one with the command:

abuild unpack

Running configure will also show you how you can disable a specific option for this package. A good example is for instance "--disable-nls" which will disable native language support and thus does not depend on gettext (libiconv, glib, ...).

Alpine likes to keep things small, so we try to disable as much as possible without losing too many features. The exact disable/enable options are decided the package builder but please try to follow Alpine's design concept as much as possible.

An easy way of quickly finding out the build info for a package is to check Arch Linux (Alpine package management and build scripts are similar) or Gentoo Linux ebuilds (previous versions of Alpine were based on Gentoo).

After the package is successfully compiled and created we should make sure it didn't link to any package that is not present in the $depends variable. We do this by using scanelf. If scanelf is not yet installed on your system you can do that by installing pax-utils.

scanelf -nR pkg

An example output of libcurl would be:

ET_DYN libssl.so.0.9.8,libcrypto.so.0.9.8,libz.so.1,libc.so.0,ld-uClibc.so.0 pkg/usr/lib/libcurl.so.4.1.1

You can see the needed files and should be able to find out which file belongs to which package.

license

The license tag must reflect the license of the source code. Please check the source tarball for COPYING, LICENSE, or other files with names that indicates that it contains licensing information. Beside the license file most developer include headers in the source code files with licensing details. Please use the short name and the release number in the license tag, e.g

Short name	Full name
GPL2	GNU General Public License Version 2.0
LGPL2+	GNU Lesser General Public License Version 2.1
ASL 2.0	Apache License Version 2.0
BSD	BSD License
MIT	MIT license
MPL 2.0	Mozilla Public License v2.0
ZPL 2.0	Zope Public License v 2.0
PHP	PHP License v3.0
zlib	zlib/libpng License

For the GNU General Public License the '+' means or (at your option) any later version. which covers future releases of that license. We skip the v because it's obvious that the number shows the version. If you are unsure about the short name of a license, please check the resources below for additional information.

If a package has a special/custom license we need to provide it with the release. Because we want to save space and don't like to have licenses all over our system we have decided to include the license in the doc subpackage. Please follow the following guidelines to add a proper license. Locate the license file inside the source package. Add the doc subpackage to the $subpackages variable as follows:

subpackages="$pkgname-doc"

Add a similar line to the following to your package() function, depending on the license description file:

install -Dm644 COPYING "$pkgdir"/usr/share/licenses/$pkgname/COPYING

If you follow these steps then abuild will automatically add the license to the package-doc apk for you.

arch

The package architecture(s) to build for. This can be one of: x86, x86_64, all, or noarch, where all means all architectures, and noarch means it's architecture-independent (ie, a pure-python package).

Tip: To determine if your APKBUILD can use noarch, build the package for your architecture and then run "scanelf -R pkg" from the directory that the APKBUILD resides in, in order to scan for ELF files in the ./pkg directory. If you do NOT get output from this, then noarch can be used.

url

Website address for the program. This is usefully later on when either finding documentation or other information about the package.

pkgdesc

A brief, one line, description of what the package does. Useful for the package management system. It should start with a capital letter and does not end with a period.

Here is an example from apk_info for the OpenSSH client package:

pkgdesc="Port of OpenBSD's free SSH release - client"

pkgver

Provide the release number of the package you are building.

pkgrel

The $pkgrel versioning is made so if you change something to your APKBUILD file without changing the actual $pkgver you can higer pkgrel so apk tools will detect it as an update. For instance if you forget to add a dependency you can add it afterward and you can +1 pkgver so apk finds this update and add the missing dependency. When there's an upstream version changes, we reset the pkgrel to 0.

pkgname

The base name of the package you are creating. For Freeswitch 1.0.6, you would use "freeswitch"

install

There are 6 different kinds of install scripts. Each script is called with the $pkgname.<action> where <action> is one of the following:

$pkgname.pre-install

This script is executed before package is installed. Typical use is when package needs a group and a user to be created. For example:

#!/bin/sh

addgroup -S clamav 2>/dev/null
adduser -S -D -H -s /bin/false -G clamav -g clamav clamav 2>/dev/null

exit 0

Note the exit 0 at the end. If the script exits with failure (if the user already exist), the package will not be installed and apk add will exit with failure.

$pkgname.post-install

This script is executed after package is installed. Can be used to generate font cache and similar.

$pkgname.pre-upgrade

Same as pre-install but is executed before upgrading/downgrading/reinstalling an already installed package. Note that exiting with failure will not cause apk to exit with failure, but will mark the package as broken.

$pkgname.post-upgrade

Same as post-install but is executed after upgrading/downgrading/reinstalling an already installed package.

$pkgname.pre-deinstall

This script is executed before uninstalling a package. If script exits with failure apk will not uninstall the package.

$pkgname.post-deinstall

This script is executed after a package have been uninstalled. Can be used to update font caches and restore busybox links. For example:

#!/bin/sh
busybox --install -s

If the package have an pre-install and post-install script the APKBUILD should have the install variable defined:

...
install="$pkgname.pre-install $pkgname.post-install"

...

subpackages

$subpackages are made to split up the normal "make install" into separate packages. The most common subpackages we use are doc and dev. Because we like to keep our target system small we move documentation and development files (only needed when building packages) into separate packages. To use the specific program a user only need to install the base apk without package-doc or package-dev, but if he wants to read the manual he will need to install package-doc.

The easiest way to find out if you need to use -dev and -doc is to first build the package without these options set and wait until the build finishes. When its finished you should have a pkg directory which is the fake root directory. Inside this directory you will see the structure as how it would be installed in / on the target system.

To see if you need the -dev package you can run the following cmd:

find pkg/usr/ -name '*.[acho]' -o -name '*.la'

If this returns any files you need to include the -dev package.

To see if you need the -doc package you can run the following cmd:

find pkg/usr/share -name doc -o -name man -o -name info -o -name html -o -name sgml -o -name licenses

If this returns any directories you need to include the -doc package.

Custom subpackages

Some software additionally has non-essential files that do not qualify as either documentation or development content. These files should be placed in their own, specialized subpackage(s). Some packages include large test suites which are only needed in specific circumstances or binaries which have depends which we prefer not to install. To handle those we create our own package/function. In the APKBUILD below the build() function we create another function:

test() {
       mkdir -p "$subpkgdir"/usr
       mv "$pkgdir"/usr/package-test "$subpkgdir"/usr/
}

We also need to add the package info to $subpackages variable:

subpackages="$pkgname-doc $pkgname-dev $pkgname-test"

After we finish building the package you should see another apk called packagename-test.apk which includes the files which we moved to the $subpkgdir dir.

The above mentioned variables can also be used in our custom function. If we want for instance to build the test() function with perl support we would add:

depends="perl"
makedepends="perl-dev"

If we would install the base package it would not install perl, but if we install the package-test package it would.

Patches

Please make sure you always submit human readable patches. Way's to create them are:

directory compare:

diff -urp original_directory new_directory > filename.patch

file compare:

diff -up original.file new.file > filename.patch

Because multiple patches can patch the same file, we could create offset for the next patch. To make sure we always patch in a specified way we should number the patches as followed:

10-patch1.patch 20-patch2.patch 30-patch3.patch

This way we are always sure patch 1 is first and if we want to add additional patches between them we can use 11,12,21,22...

Add names of the patch files to the source variable. If you haven't declared custom prepare function, then it's all what you need to do. Otherwise call default_prepare in your prepare function, for example:

prepare() {
	default_prepare || return 1

	# do your stuff
}

Note: Some older packages contain for loop in the prepare function to apply patches. This is not needed anymore, patches are handled by default_prepare.

Configure options

Alpine has some default configure options we set by default. We use /usr for prefix to make sure everything is installed with /usr in front of it. If you notice that anything is installed in the wrong directory please run

./configure --help

and see if you can set the correct location.

We are not covering the depend switches here we have discussed this already in the depend section.

Tip: Common steps for building package contain ./configure, make and make install. Everyone of them should be enclosed by || return 1 to check exit status. Otherwise even if previous step fails e.g. ./configure, next will be launched e.g. make. This complicates identifying the point where the build breaks. The same applies to installing additional files.

Make options

If you notice weird problems when compiling or installing the package with make/make install you could try to disable parallel building/installing. A normal make line would be:

make || return 1

To disable parallel we use:

make -j1 || return 1

We can use the same for make install.

Because we do not want to install the package in our build environment but we want to install it in a fake root directory we need to tell 'make install' to use another destination directory instead of '/'. We do this by setting a variable when we execute make install as followed:

make DESTDIR="$pkgdir" install

Please note that some Makefiles do not support this variable and will always install software in '/'. To make sure you do not mess up your build system NEVER run your build system as root but always use a custom user and sudo when needed. If by accident the Makefile does not support DESTDIR variable it will fail to install in our build system system directories.

builddir

If you used newapkbuild to create your APKBUILD file, you must specify the path to your unpacked sources. Inside the sections during the prepare/build/install process builddir is used. Most of the time a combination of $srcdir and $pkgname-$pkgver will work. When not, check the /src directory or the source tarball for the right string. Especially when you are working with automatically generated tarballs (like from github and gitorious), this needs to be adjusted.

builddir="$srcdir"/$pkgname-$pkgver

Additional files

If you want/need to install additional files not mentioned above you can use the following cmd (this is an example of a conf file):

install -Dm644 doc/$pkgname.conf "$pkgdir"/etc/$pkgname.conf

Build the package

If you did not already create the checksums as mentioned above you can do so now:

cd $pkgname abuild checksum

It's about time we build our package. Because a build system should never have all the package installed to prevent linking to packages we don't want it to link we use a abuild recursively with the -r switch. It will install all dependency's from your repository and builds it, afterwards it will uninstall all those depending packages again. You could also use the -R switch which would build your package including the dependency packages.

abuild -r

Commit your work

After you successfully build your package you can submit your APKBUILD to Alpine's git repository.

Update your git repo, before adding new files:

cd $aportsdir git pull

This should pull all the changes made by others into you local git repo.

When you think you are ready you can add your files to git:

NOTE: when using our github repo, you can create PR's for each package. Please squash all commits into a single one per PR.

cd $aportsdir git add testing/$pkgdir (include any other files needed for the build; $pkgname.install...) git commit

In the commit message, add the following (remove the comments in the last four lines):

# Please enter the commit message for your changes #[snip] # testing/$pkgname: new aport # this will be the subject line # a blank line $pkgurl # homepage of project $pkgdesc # a one line description

Or you could add the following to your `aports/.git/hooks/prepare-commit-msg` to automatically generate the commit message:

#!/bin/sh
case "$2,$3" in
  ,|template,)
    if git status --porcelain | grep -q '^A. APKBUILD'; then
      meta() { git diff --staged | grep "^+$1" | sed 's/.*="\?//;s/"$//';}
      cat > "$1" <<EOF
testing/$(meta pkgname): new aport

$(meta url)
$(meta pkgdesc)
EOF
    else
      git status --porcelain | sed -n 's/...\(.*\)\/APKBUILD/\1: /p;T;q' > "$1"
    fi;;
esac

Now your changes are only available locally in your repository.

Because you do not have push rights to the Alpine aports repository you need to create a pull request to Alpine's mirror on GitHub (read instructions here).

Alternatively you can also create a diff (patch) of the changes you made and send this patch to the alpine-aports mailinglist.

To create a diff patch:

git format-patch HEAD^

or if you have sprunge, you can create a link to your patch for convenience

git format-patch HEAD^ --stdout | sprunge

Send a patch

git send-email will do that for you.