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

Creating an APKBUILD file

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 -cn $packagename

NOTE: order does matter.

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.

Some info/guidelines regarding the variables:

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

$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

test

Build the package

 cd $pkgname
 abuild checksum >> APKBUILD
 abuild

Add any custom configure option into proper line of build() section

Splitting packages

For packages that install man and info files, it's better to put these file in a separated $pkgname-doc package. Edit APKBUILD and add:

 subpackages="$pkgname-doc"

Be sure to put man files in /usr/share/man and info files in /usr/share/info. You need to re-run abuild to regenerate program and doc packages

Commit your work

Update you git repo, before adding new files:

 cd $aportsdir
 git pull git://dev.alpinelinux.org/aports
 git add extra/$pkgname/APKBUILD
 git commit -v -m'extra/$pkgname: new aport'

If your package belongs to core or testing, replace extra accordingly. Send the file 000x-extra-$pkgname-new-aport.patch in the current dir to alpine-devel@lists.alpinelinux.org