Creating an Alpine package

DRAFT

This document assumes that you have a working build environment, or use a diskbased alpine installation.

The APKBUILDs

The abuild script reads the APKBUILD and executes the steps needed to create a package.

The aports tree

The aports tree is a directory tree with many APKBUILDs. Those files are used when building alpine from source.

Installing and configuring the alpine-sdk

The alpine-sdk is a metapackage that pulls in the most essinsial packages used to build new packages. To install those packages:

NOTE: if you used the build environment howto, you already have alpine-sdk installed.

apk add alpine-sdk

The aports tree is in git so before we can clone the aports tree we need to install and configure git. We need to tell git our name and email.

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

Now we can clone the aports tree.

 git clone git://dev.alpinelinux.org/aports

Before we are going to create APKBUILD files we need to setup abuild to our system/user. Please edit the file abuild.conf to your likings.

 vim /etc/abuild.conf

Creating an APKBUILD file

General info

APKBUILD files are read by the abuild program mentioned above. To see what abuilld can/cannot do you can execute:

abuild -h

To create the actual APKBUILD file abuild has the option -n (new). It will simply copy an example APKBUILD file to the given directory and fill some variables. If you are create a daemon package which needs initd scripts you can add the -c making it:

abuild -c -n packagename

NOTE: The packagename is a parameter to the -n option so order of -c and -n matters.

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).

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 directory's like $pkgdir always make sure they are double quoted like:

"$pkgdir"/somedir

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

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

Source is not only the link from which abuild will fetch the source, it should also hold all files abuild needs to build the apk. This could mean initd file, confd file, install file, patches or any other file needed. When you are finished adding them you can execute the following cmd to add checksum's to the APKBUILD file:

abuild checksum

Another thing to note is when a package is using sourceforge as hosting, if so you should add special mirrors link used by sf:

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

(or similar depending on the package).

Currently abuild support the following archives/extensions:

*.tar.gz, *.tgz, *.tar.bz2, *.tar.lzma, *.zip

depends & makedepends

Depends are the actual running dependencies which a package would need when you are using it. 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 anymore. The best way to find out what depends and makedepeds are of a package 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 src directory you can create one by doing:

abuild unpack

It 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 loosing to many features. The exact disable/enable options are decided the package builder but please try to follow Alpines design concept as much as possible.

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

Search ebuilds

Gentoo CVS

Archlinux packages

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

scanelf -nR pkg

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

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 into the doc subpackage. Please follow the following guideline to add a proper license. Locate the license file inside the source package. Add to $subpackages variable the following:

subpackages="$pkgname-doc"

And add a similar line to your build() function depending on the license:

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

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

url

editme

pkgdesc

editme

pkgver

editme

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.

pkgname

editme

install

The install file is a script which will be execute by apk-tools when you are install,deinstall,update a package. An example of using it is when you need to add a user/group to the system. The install file will only be run on the actual install so it will only add the user and group to the target system and not to the build system when we are building it. Another good example is displaying a message to the user when installing a package.

Please remember, commands specified in the build() function in APKBUILD will be run on both build system and target system.

Please check the sample install file for syntax.

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 applications will have except doc and dev files other non needed at run time files which we want to separate away from the base package. 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

If you are going to use multiple patches for a single package, the preferred way to handle those is a loop and numbering the patches.

for i in "$srcdir"/*.patch; do
       msg "Applying ${i}"
       patch -p0 -i $i || return 1
done

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...

Configure options

Alpine has some default configure options we set by default. We use /usr for prefix to make sure everyting 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.

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 customer 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.

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

Its about time we build our package. Because a build system should never have all the package installed to prevent linking to packages we dont 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 git repository.

Update you 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:

cd $apkbuilddir
git add APKBUILD
git commit

Now your changes are only available locally in your repo. Because you do not have push rights to the alpine repo you need to create diff (patch) of the changes you made:

git format-patch -1

Where -1 sets how many commits you want to go back (mostly this is 1). This should create a patch called 0001......patch.

An easy way to send this patch to the list is with an program called 'email'.

apk_add email

to send to the mailing list you would do:

email -a 0001...patch alpine-devel@lists.alpinelinux.org

And provide a subject and body after you execute the above cmd.

If you doubt to which repo your package belongs to you can safely use extra. If you are not sure your package works at all you need to use testing.