Alpine Linux - User contributions [en]

User:Mattx86/qwn:Enabling ccache

2011-04-05T06:33:42Z

Mattx86:

''"ccache is a compiler cache. It speeds up recompilation by caching previous compilations and detecting when the same compilation is being done again. Supported languages are C, C++, Objective-C and Objective-C++."''

To enable ccache, first install ccache:
{{Cmd|apk add ccache}}

Next, add it to your path by placing the following in your <code>~/.profile</code> (<code>ash</code>) or <code>~/.bash_profile</code> (<code>bash</code>).
<pre>export PATH="/usr/lib/ccache/bin:$PATH"</pre>

User:Mattx86/qwn:Enabling ccache

2011-04-05T04:33:23Z

Mattx86: Created page with "''"ccache is a compiler cache. It speeds up recompilation by caching previous compilations and detecting when the same compilation is being done again. Supported languages are C,..."

''"ccache is a compiler cache. It speeds up recompilation by caching previous compilations and detecting when the same compilation is being done again. Supported languages are C, C++, Objective-C and Objective-C++."''

To enable ccache, first install ccache:
{{Cmd|apk add ccache}}

Next, add it to your path by placing the following in your <code>~/.profile</code> for <code>ash</code> or <code>~/.bash_profile</code> for <code>bash</code>.
<pre>export PATH="/usr/lib/ccache/bin:$PATH"</pre>

User:Mattx86

2011-04-05T04:22:31Z

Mattx86:

* My personal pages:
** [[User:Mattx86/Bash Profile]]
** [[User:Mattx86/tmux config]]
** [[User:Mattx86/Alpine Fresh Installation]] (mostly outdated)

* My quick wiki notes:
** [[User:Mattx86/qwn:Install x86-2.1.5 and Upgrade to x86_64-edge]]
** [[User:Mattx86/qwn:Switching from Alpine Standard/Mini to Alpine VServer]]
** [[User:Mattx86/qwn:Renaming a network interface]]
** [[User:Mattx86/qwn:Enabling APK Caching]]
** [[User:Mattx86/qwn:Enabling ccache]]

* Wiki draft pages:
** [[User:Mattx86/Obtaining Alpine Linux]]

APKBUILD Reference

2011-04-05T03:30:33Z

Mattx86: /* subpackages */ added note about split functions with hyphens

APKBUILDs are the scripts that are created in order to build Alpine packages using the [[abuild]] tool.

This page is intended to serve as a reference for creating APKBUILDs; if this is your first time creating a package for Alpine Linux, please see [[Creating an Alpine package]].

= Legend =
The following notes will assist you in understanding this document.

In description text:
* If a variable is not prefixed with a ''$'', it will be represented by italics (i.e., ''srcdir'' ).
* Functions will also be represented by italics, but will also end with a pair of parentheses (i.e., ''build()'' ).
* Shell commands will be represented by italics and bold type (i.e., '''''abuild checksum''''').

= Variables =
{{Note|Variables that contain a path (e.g. ''$srcdir'' and ''$pkgdir'') should always be quoted using double quotes (i.e., ''"$srcdir"''). This is done to prevent things from breaking, should the user have the APKBUILD in a directory path that contains spaces.}}
{{Note|All arbitrary variable and function names should be prefixed with an underscore character ( _ ) to avoid name clashes with the internals of abuild (i.e., ''_builddir'').}}

== abuild-defined variables ==
The following variables are defined by abuild:

==== startdir ====
: The directory where the APKBUILD script is.
==== srcdir ====
: The directory where sources, from the ''source'' variable, are downloaded to and unpacked to.
==== pkgdir ====
: This directory should contain the files for the main package. For example, a normal [http://en.wikipedia.org/wiki/GNU_build_system autotools] package would have '''''make DESTDIR="$pkgdir" install''''' in the ''package()'' function.
==== subpkgdir ====
: This directory should contain the files for a subpackage. This variable should only be used from subpackage functions.

== User-defined variables ==
The following variables should be defined by the user:
==== arch ====
: Package architecture(s) to build for. Can be one of: '''x86, x86_64, all''', or '''noarch''', where '''all''' means all architectures, and '''noarch''' means it's architecture-independent (e.g., a pure-python package).
: {{Tip|To determine if your APKBUILD can use '''noarch''': First specify '''all''' and then build the package by executing '''''abuild -r'''''. Watch the output towards the end for warnings saying that '''noarch''' can be used. If the main package and all subpackages, if you have any subpackages, give a warning saying that '''noarch''' can be used, then you can use '''noarch'''.}}
==== depends ====
: Run-time dependency package(s) that are not shared-object dependencies. Shared objects dependencies are auto-detected and should not be specified here.
==== depends_dev ====
: Run-time dependency package(s) for the '''$pkgname-dev''' subpackage.
==== install ====
: There are 6 different types of install scripts. Install scripts are named '''$pkgname.action''', where '''action''' can be: '''pre-install, post-install, pre-upgrade, post-upgrade, pre-deinstall''', or '''post-deinstall'''. For example, if ''pkgname'' is set to '''mypackage''' and ''install'' is set to '''$pkgname.post-install''', then a script named '''mypackage.post-install''' must exist along-side the APKBUILD.

: First, a few notes regarding install scripts:
<blockquote>{{Note|When using install scripts, ''$install'' should be included in ''source'' so that checksums can be generated and used for the install scripts specified in ''install''. For example:
<pre>
install="$pkgname.pre-install $pkgname.post-install"
source="http://....
$install"
</pre>}}
{{Note|Always use <code>/bin/sh</code> for the command-line interpreter on the [http://en.wikipedia.org/wiki/Shebang_%28Unix%29 shebang line] of your install scripts.}}</blockquote>

The following are the different types of install scripts in detail:

===== $pkgname.pre-install =====
: This script is executed ''before installing'' the package. Typical use is when the package needs a user/group to be created. For example:
<blockquote><pre>
#!/bin/sh
adduser -H -s /bin/false -D clamav 2>/dev/null
exit 0
</pre>
{{Note|If the script exits with a failure (e.g., if the user already exists), the package will not be installed and <code>apk</code> will exit with failure, hence the '''''exit 0''''' at the end.}}</blockquote>

===== $pkgname.post-install =====
: This script is executed ''after installing'' the package.

===== $pkgname.pre-upgrade =====
: This script is executed ''before upgrading'' the package.

===== $pkgname.post-upgrade =====
: This script is executed ''after upgrading'' the package.

===== $pkgname.pre-deinstall =====
: This script is executed ''before uninstalling'' the package.
: {{Note|If the script exits with failure, <code>apk</code> will not uninstall the package.}}

===== $pkgname.post-deinstall =====
: This script is executed ''after uninstalling'' the package.

==== license ====
: License(s) for the package.
==== makedepends ====
: Build-time dependency package(s).
==== md5sums ====
: Checksums for the files/URLs listed in ''source''. The checksums are normally generated and updated by executing '''''abuild checksum''''' and should be the last item in the APKBUILD.
==== options ====
: Build-time options for the package. Can be: '''!strip''' - to avoid stripping symbols from binaries.
==== pkgdesc ====
: A brief, one-line description of what the package does.

: Here's an example from the OpenSSH client package:
: <pre>pkgdesc="Port of OpenBSD's free SSH release - client"</pre>
==== pkggroups ====
: System group(s) to be created during build-time. System group(s) should also be created in the '''[[APKBUILD Reference#.24pkgname.pre-install|$pkgname.pre-install]]''' script, so that the system group(s) are also created prior to package installation for run-time use.
==== pkgname ====
: The name of the package. All letters should be lowercase.
: {{Note|When creating an APKBUILD of a module or library for another package, we use some common package prefixes, such as: ''lua-'', ''perl-'', ''php-'', and ''py-''. Search aports for other common prefixes.}}

==== pkgrel ====
: Alpine package release number. Starts at 0 (zero). Always increment ''pkgrel'' when making updates to an aport; reset ''pkgrel'' to 0 (zero) when incrementing ''pkgver''.
==== pkgusers ====
: System user(s) to be created during build-time. System user(s) should also be created in the '''[[APKBUILD Reference#.24pkgname.pre-install|$pkgname.pre-install]]''' script, so that the system user(s) are also created prior to package installation for run-time use.
==== pkgver ====
: The version of the software being packaged.
==== replaces ====
: Package(s) that this package replaces. This package will "take over" files owned by packages listed in the ''replaces'' variable. This is useful when files move from one sub-/package to another, or when a package gets renamed.
==== 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 [[APKBUILD Reference#install|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:
:: {{Cmd|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:
:: <pre>http://downloads.sourceforge.net/$pkgname/$pkgname-$pkgver.tar.gz</pre>
:: (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:
:: <pre>http://oss.example.org/?get=software&ver=1.0</pre>
:: You must prepend 'saveas-' to the protocol and append '/software-1.0.tar.gz' (for instance) to the end of the URI, like so:
:: <pre>saveas-http://oss.example.org/?get=software&ver=1.0/software-1.0.tar.gz</pre>
:: 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.

:* 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

==== subpackages ====
: Subpackages built from this APKBUILD. abuild will parse this variable and try to find a subpackage split function. The split function must ''move'' files that do not belong in the main package, from ''$pkgdir'' to ''$subpkgdir''. Files and directories can also be ''copied'' from ''$startdir'' and ''$srcdir'' to ''$subpkgdir''.

: The split function can be specified in 1 of 3 different methods:
:# subpkgname:'''splitfunc'''
:# $pkgname-'''splitfunc'''
:# '''splitfunc'''

: {{Note|Split function names '''cannot''' use hyphens; use the first method above if the subpackage name contains a hyphen (-) character, like this: ''subpkg-name:subpkg_name'', where '''''subpkg-name''''' is the name of the '''subpackage''' and '''''subpkg_name''''' is the name of the '''subpackage's split function'''.}}

: {{Tip|For more information, see the [[APKBUILD Reference#Subpackages_Example|Subpackages Example]].}}

==== url ====
: The homepage for the package. This is to help users find upstream documentation and other information regarding the package.

= Functions =
{{Note|All functions should consider the current working directory as undefined, and should therefore use the [[APKBUILD Reference#abuild-defined_variables|abuild-defined directory variables]] to their advantage.}}

== abuild-defined functions ==
The following functions are provided by abuild and can be overridden:

==== fetch() ====
: Downloads remote sources listed in ''source'' to ''SRCDEST'' (''SRCDEST'' is configured in ''/etc/abuild.conf'') and creates symlinks in ''$srcdir''.
==== unpack() ====
: Unpacks .tgz, .tar.gz, .tar.bz2, .tar.lzma, .tar.xz, and .zip archives in ''$srcdir'' to ''$srcdir''.
==== dev() ====
: Subpackage function for the '''$pkgname-dev''' package. Without specifying a custom ''dev()'' function, abuild will call it's internal ''dev()'' function, which in turn calls ''default_dev()'', which will move ''"$pkgdir"/usr/include'', ''*.a'', ''*.la'' and similar files to ''$subpkgdir''.
==== doc() ====
: Subpackage function for the '''$pkgname-doc''' package. Without specifying a custom ''doc()'' function, abuild will call it's internal ''doc()'' function, which in turn calls ''default_doc()'', which will move ''"$pkgdir"/usr/share/doc'', ''"$pkgdir"/usr/share/man'' and similar to ''$subpkgdir''.

== User-defined functions ==
The following functions should be defined by the user:

==== prepare() ====
: '''''Optional''.''' Used for build preparation: patches, etc, should be applied here. This function is available for your convenience.
==== build() ====
: '''Required.''' This is the compilation stage. This function will be called as the current user (unless the ''package()'' function is missing - for compatibility reasons). If no compilation is needed, this function can contain a single line: '''''return 0'''''
==== package() ====
: '''Required.''' This is the packaging stage. Here, the built application and support files should be installed into '''$pkgdir'''. If this is a metapackage, this function can contain a single line: '''''mkdir -p "$pkgdir" && return 0'''''

{{Note|Building in fakeroot will reduce performance for parallel builds dramatically. It is for this reason that we split the build and package process into two separate functions.}}

= Examples =
The following APKBUILD examples will assist you in understanding how to create an APKBUILD.

== Subpackages Example ==
Consider the following APKBUILD snippet:
pkgname="foo"
subpackages="$pkgname-dev $pkgname-doc py-$pkgname:pysub libfoo"

It will ...
* create the following 5 packages:
# foo (main)
# foo-dev (sub)
# foo-doc (sub)
# py-foo (sub)
# libfoo (sub)

* using the following 5 package functions (respectively) to fill them with files:
# ''package()'': will be provided by the user (and can make use of the ''$pkgdir'' variable).
# ''dev()'': will be provided by abuild unless we override it, by providing our own ''dev()'' function (which can make use of the ''$subpkgdir'' variable).
# ''doc()'': will be provided by abuild unless we override it, by providing our own ''doc()'' function (which can make use of the ''$subpkgdir'' variable).
# ''pysub()'': will be provided by the user (and can make use of the ''$subpkgdir'' variable).
# ''libfoo()'': will be provided by the user (and can make use of the ''$subpkgdir'' variable).

== Simple APKBUILD ==
Simple APKBUILD with -doc subpackage, using abuild's default ''doc()'' function:
<pre>
# Maintainer: Natanael Copa <ncopa@alpinelinux.org>
pkgname=m4
pkgver=1.4.15
pkgrel=0
pkgdesc="GNU macro processor"
url="http://www.gnu.org/software/m4"
depends=
arch="all"
license="GPL"
subpackages="m4-doc"
source="ftp://ftp.gnu.org/gnu/m4/$pkgname-$pkgver.tar.gz
gnulib-uclibc.patch"

_builddir="$srcdir"/$pkgname-$pkgver
prepare() {
cd "$_builddir"
patch -p1 -i "$srcdir"/gnulib-uclibc.patch
}

build() {
cd "$_builddir"
./configure --prefix=/usr
make
}

package() {
cd "$_builddir"
make install DESTDIR="$pkgdir"
}

md5sums="5649a2e593b6c639deae9e72ede777dd m4-1.4.15.tar.gz
20a7dedec0e9e0ee7107e33e798ffdbe gnulib-uclibc.patch"
</pre>

== APKBUILD with Multiple Subpackages ==
A more complex APKBUILD with -doc, -dev and python subpackages:
<pre>
# Contributor: Carlo Landmeter <clandmeter at gmail>
# Maintainer: Carlo Landmeter <clandmeter at gmail>
pkgname=libxml2
pkgver=2.7.8
pkgrel=0
pkgdesc="XML parsing library, version 2"
url="http://www.xmlsoft.org/"
arch="all"
license="MIT"
depends=
depends_dev="zlib-dev python-dev"
makedepends="zlib-dev python-dev"
subpackages="$pkgname-doc $pkgname-dev py-$pkgname:py $pkgname-utils"
source="ftp://ftp.xmlsoft.org/${pkgname}/${pkgname}-${pkgver}.tar.gz
largefile64.patch"

options="!strip"

_builddir="$srcdir/$pkgname-$pkgver"
prepare() {
cd "$_builddir"
for _i in "$srcdir"/*.patch; do
patch -p1 -i "$_i"
done
}

build() {
cd "$_builddir"
./configure --prefix=/usr \
--sysconfdir=/etc \
--mandir=/usr/share/man \
--infodir=/usr/share/info
make
}

package() {
cd "$_builddir"
make -j1 DESTDIR="$pkgdir" install
install -Dm644 COPYING "$pkgdir"/usr/share/licenses/$pkgname/COPYING
}

py() {
cd "$_builddir"
pkgdesc="$pkgname python bindings"
install -d "$subpkgdir"/usr/lib
mv "$pkgdir"/usr/lib/python* "$subpkgdir"/usr/lib/
}

utils() {
pkgdesc="XML utilities"
replaces="libxml2"
mkdir -p "$subpkgdir"/usr
mv "$pkgdir"/usr/bin "$subpkgdir"/usr/
}

md5sums="8127a65e8c3b08856093099b52599c86 libxml2-2.7.8.tar.gz
5ad4915665608ebfa5b89f7908467a72 largefile64.patch"
</pre>

User:Mattx86/qwn:Enabling APK Caching

2011-03-24T04:08:02Z

Mattx86:

To enable the caching of downloaded APKs, do the following steps.

Create the cache directory and symlink:
{{Cmd|mkdir -p /var/cache/apk
ln -s /var/cache/apk /etc/apk/cache}}

Next, update apk in order to initialize the cache:
{{Cmd|apk update}}

User:Mattx86/qwn:Enabling APK Caching

2011-03-24T04:06:15Z

Mattx86: Created page with "Create the cache directory and symlink: {{Cmd|mkdir -p /var/cache/apk ln -s /var/cache/apk /etc/apk/cache}} Next, update apk in order to initialize the cache: {{Cmd|apk update}}"

Create the cache directory and symlink:
{{Cmd|mkdir -p /var/cache/apk
ln -s /var/cache/apk /etc/apk/cache}}

Next, update apk in order to initialize the cache:
{{Cmd|apk update}}

User:Mattx86

2011-03-24T03:55:57Z

Mattx86:

* My personal pages:
** [[User:Mattx86/Bash Profile]]
** [[User:Mattx86/tmux config]]
** [[User:Mattx86/Alpine Fresh Installation]] (mostly outdated)

* My quick wiki notes:
** [[User:Mattx86/qwn:Install x86-2.1.5 and Upgrade to x86_64-edge]]
** [[User:Mattx86/qwn:Switching from Alpine Standard/Mini to Alpine VServer]]
** [[User:Mattx86/qwn:Renaming a network interface]]
** [[User:Mattx86/qwn:Enabling APK Caching]]

* Wiki draft pages:
** [[User:Mattx86/Obtaining Alpine Linux]]

User:Mattx86/qwn:Renaming a network interface

2011-03-15T10:42:18Z

Mattx86: Created page with "Supppose I had an interface named <code>eth3</code> and I want to rename it as <code>neweth3</code>. Start out by specifying: {{Cmd|auto neweth3 iface neweth3 inet static}} Fol..."

Supppose I had an interface named <code>eth3</code> and I want to rename it as <code>neweth3</code>.

Start out by specifying:
{{Cmd|auto neweth3
iface neweth3 inet static}}

Followed by the <code>address</code>, <code>netmask</code>, <code>gateway</code>, etc., and then add this line:
{{Cmd|pre-up nameif -s neweth3 00:11:22:33:44:55}}

This sets the interface name to <code>neweth3</code>, where the MAC address of the interface is <code>00:11:22:33:44:55</code>.

Here's a full example:
{{Cmd|auto neweth3
iface neweth3 inet static
address 10.100.100.1
netmask 255.255.255.0
network 10.100.100.0
broadcast 10.100.100.255
pre-up nameif -s neweth3 00:11:22:33:44:55}}

User:Mattx86

2011-03-15T10:28:46Z

Mattx86:

* My personal pages:
** [[User:Mattx86/Bash Profile]]
** [[User:Mattx86/tmux config]]
** [[User:Mattx86/Alpine Fresh Installation]] (mostly outdated)

* My quick wiki notes:
** [[User:Mattx86/qwn:Install x86-2.1.5 and Upgrade to x86_64-edge]]
** [[User:Mattx86/qwn:Switching from Alpine Standard/Mini to Alpine VServer]]
** [[User:Mattx86/qwn:Renaming a network interface]]

* Wiki draft pages:
** [[User:Mattx86/Obtaining Alpine Linux]]

User:Mattx86/qwn:Switching from Alpine Standard/Mini to Alpine VServer

2011-03-15T10:26:39Z

Mattx86: Created page with "<pre> Switching from Alpine Standard/Mini to Alpine VServer ----------------------------------------------------- # apk add linux-vserver util-vserver # vi /boot/extlinux.conf ..."

<pre>
Switching from Alpine Standard/Mini to Alpine VServer
-----------------------------------------------------

# apk add linux-vserver util-vserver
# vi /boot/extlinux.conf
* copy and paste grsec configuration
* change grsec to vserver in the copied grsec configuration
* change default line to vserver
* save and exit
# reboot

Creating a vserver template:
# mkdir /tmp/vstpl
# apk add --initdb --root /tmp/vstpl --repositories-file /etc/apk/repositories --keys-dir /etc/apk/keys -U alpine-base
# chroot /tmp/vstpl /sbin/rc-update add syslog boot
* the vserver .. build command seems to add syslog to the boot runlevel, so this may be unnecessary.
# cd /tmp/vstpl && tar -czf /tmp/vstpl.tar.gz *
# rm /tmp/vstpl -rf

Creating a vserver guest:
# vserver guest1 build --interface eth0:192.168.1.26/24 --hostname guest1 -m template -- -t /tmp/vstpl.tar.gz -d alpine

Starting the vserver guest:
# vserver guest1 start
* I need to see why this happens:
mount: permission denied (are you root?)
mount: permission denied (are you root?)

Entering the vserver guest:
# vserver guest1 enter
</pre>

User:Mattx86

2011-03-15T10:26:01Z

Mattx86:

* My personal pages:
** [[User:Mattx86/Bash Profile]]
** [[User:Mattx86/tmux config]]
** [[User:Mattx86/Alpine Fresh Installation]] (mostly outdated)

* My quick wiki notes:
** [[User:Mattx86/qwn:Install x86-2.1.5 and Upgrade to x86_64-edge]]
** [[User:Mattx86/qwn:Switching from Alpine Standard/Mini to Alpine VServer]]

* Wiki draft pages:
** [[User:Mattx86/Obtaining Alpine Linux]]

User:Mattx86/qwn:Install x86-2.1.5 and Upgrade to x86 64-edge

2011-03-15T10:24:45Z

Mattx86:

The eventual goal with this document is to show how to upgrade a production 32-bit Alpine Linux installation to 64-bit.

<pre>
Installing Alpine 2.1.5 and upgrading to Edge 64-bit
----------------------------------------------------

# setup-alpine
# setup-disk
# wget http://dl-4.alpinelinux.org/alpine/edge/releases/x86_64/alpine-edge-110310-x86_64.iso
# mkdir /media/iso
# mount -t loop /root/alpine-edge-110310-x86_64.iso /media/iso
# mount /dev/sda3 /mnt
# mount /dev/sda1 /mnt/boot
# vi /mnt/etc/apk/repositories
* remove cdrom listing if present
* add http://dl-4.alpinelinux.org/alpine/edge/x86_64/main/
* add http://dl-4.alpinelinux.org/alpine/edge/x86_64/testing/
* save and exit
# apk add --allow-untrusted --root /mnt --repositories-file /etc/apk/repositories --keys-dir /etc/apk/keys -Uaf upgrade
* as many times necessary to get past the upgrade script errors
# cp /media/iso/boot/grsec.gz /mnt/boot/initramfs-2.6.37.2-grsec
# cd /mnt/boot
# rm initramfs-2.6.35.11-grsec
# rm initramfs-grsec
# ln -s initramfs-2.6.37.2-grsec initramfs-grsec
# rm vmlinuz-grsec
# ln -s vmlinuz-2.6.37.2-grsec vmlinuz-grsec
# cd /
# umount /media/iso
# umount /mnt/boot
# umount /mnt
# reboot

After reboot:
# apk fix -r `cat /var/lib/apk/world`
# apk -Ua upgrade
</pre>

User:Mattx86/qwn:Install x86-2.1.5 and Upgrade to x86 64-edge

2011-03-15T10:24:23Z

Mattx86: Created page with "The eventual goal with this document is to show how to upgrade a production 32-bit Alpine Linux installation to 64-bit. <pre> Installing Alpine 2.1.5 and upgrading to Edge 64-bi..."

The eventual goal with this document is to show how to upgrade a production 32-bit Alpine Linux installation to 64-bit.

<pre>
Installing Alpine 2.1.5 and upgrading to Edge 64-bit
----------------------------------------------------

# setup-alpine
# setup-disk
# wget http://dl-4.alpinelinux.org/alpine/edge/releases/x86_64/alpine-edge-110310-x86_64.iso
# mkdir /media/iso
# mount -t loop /root/alpine-edge-110310-x86_64.iso /media/iso
# mount /dev/sda3 /mnt
# mount /dev/sda1 /mnt/boot
# vi /mnt/etc/apk/repositories
* remove cdrom listing if present
* add http://dl-4.alpinelinux.org/alpine/edge/x86_64/main/
* add http://dl-4.alpinelinux.org/alpine/edge/x86_64/testing/
* save and exit
# apk add --allow-untrusted --root /mnt --repositories-file /etc/apk/repositories --keys-dir /etc/apk/keys -Uaf upgrade
* as many times necessary to get paste the upgrade script errors
# cp /media/iso/boot/grsec.gz /mnt/boot/initramfs-2.6.37.2-grsec
# cd /mnt/boot
# rm initramfs-2.6.35.11-grsec
# rm initramfs-grsec
# ln -s initramfs-2.6.37.2-grsec initramfs-grsec
# rm vmlinuz-grsec
# ln -s vmlinuz-2.6.37.2-grsec vmlinuz-grsec
# cd /
# umount /media/iso
# umount /mnt/boot
# umount /mnt
# reboot

After reboot:
# apk fix -r `cat /var/lib/apk/world`
# apk -Ua upgrade
</pre>

User:Mattx86

2011-03-15T10:16:23Z

Mattx86:

Configure Networking

2011-03-15T10:07:13Z

Mattx86: Added note, stating that the loopback configuration must appear first in the interfaces configuration.

This page will assist you in setting up networking on Alpine Linux.
{{Note|You must be logged in as root in order to perform the actions on this page.}}

= Setting System Hostname =
To set the system hostname, do something like the following:
{{Cmd|echo "hostname.domain.com" > /etc/hostname}}

Then, to activate the change, do the following:
{{Cmd|hostname -F /etc/hostname}}

If you're using IPv6, you should also add the following special IPv6 addresses to your <code>/etc/hosts</code> file:
<pre>::1 localhost ipv6-localhost ipv6-loopback
fe00::0 ipv6-localnet
ff00::0 ipv6-mcastprefix
ff02::1 ipv6-allnodes
ff02::2 ipv6-allrouters
ff02::3 ipv6-allhosts</pre>

{{Tip|If you are going to use automatic IP configuration, such as IPv4 DHCP or IPv6 Stateless Autoconfiguration, you can skip ahead to [[#Configuring_DNS|Configuring DNS]]. Otherwise, if you are going to use a static IPv4 or IPv6 address, continue below.}}

For a static IP configuration, it's common to also add the machine's hostname you just set (above) to the <code>/etc/hosts</code> file.

Here's an IPv4 example:
<pre>192.168.1.150 hostname.domain.com</pre>

And here's an IPv6 example:
<pre>2001:470:ffff:ff::2 hostname.domain.com</pre>

= Configuring DNS =
{{Tip|'''For users of IPv4 DHCP:''' Please note that <code>/etc/resolv.conf</code> will be completely overwritten with any nameservers provided by DHCP. Also, if DHCP does not provide any nameservers, then <code>/etc/resolv.conf</code> will still be overwritten, but will not contain any nameservers!}}

For using a static IP and static nameservers, use one of the following examples.

For IPv4 nameservers, edit your <code>/etc/resolv.conf</code> file to look like this: 
The following example uses [http://en.wikipedia.org/wiki/Google_Public_DNS Google's Public DNS servers].
nameserver 8.8.8.8
nameserver 8.8.4.4

For IPv6 nameservers, edit your <code>/etc/resolv.conf</code> file to look like this: 
The following example uses [http://www.he.net/ Hurricane Electric's] public DNS server.
nameserver 2001:470:20::2
You can also use Hurricane Electric's public DNS server via IPv4:
nameserver 74.82.42.42

{{Tip|If you decide to use Hurricane Electric's nameserver, be aware that it is 'Google-whitelisted'. What does this mean? It allows you access to many of Google's services via IPv6. (Just don't add other, non-whitelisted, nameservers to <code>/etc/resolv.conf</code> — ironically, such as Google's Public DNS Servers.) Read [http://www.google.com/intl/en/ipv6/ here] for more information.}}

= Enabling IPv6 (Optional) =

If you use IPv6, do the following to enable IPv6 for now and at each boot:
{{Cmd|modprobe ipv6
echo "ipv6" >> /etc/modules}}

= Interface Configuration =

== Loopback Configuration (Required) ==
{{Note|The loopback configuration must appear first in <code>/etc/network/interfaces</code> to prevent networking issues.}}
To configure loopback, add the following to a new file <code>/etc/network/interfaces</code>:
<pre>auto lo
iface lo inet loopback</pre>

The above works to setup the IPv4 loopback address (127.0.0.1), and the IPv6 loopback address (<code>::1</code>) — if you enabled IPv6.

== Ethernet Configuration ==
For the following Ethernet configuration examples, we will assume that you are using Ethernet device <code>eth0</code>.

=== Initial Configuration ===
Add the following to the file <code>/etc/network/interfaces</code>, above any IP configuration for <code>eth0</code>:
<pre>auto eth0</pre>

=== IPv4 DHCP Configuration ===
Add the following to the file <code>/etc/network/interfaces</code>, below the <code>auto eth0</code> definition:
<pre>iface eth0 inet dhcp</pre>

=== IPv4 Static Address Configuration ===
Add the following to the file <code>/etc/network/interfaces</code>, below the <code>auto eth0</code> definition:
<pre>iface eth0 inet static
address 192.168.1.150
netmask 255.255.255.0
gateway 192.168.1.1</pre>

=== IPv6 Stateless Autoconfiguration ===
Add the following to the file <code>/etc/network/interfaces</code>, below the <code>auto eth0</code> definition:
<pre>iface eth0 inet6 manual
pre-up echo 1 > /proc/sys/net/ipv6/conf/eth0/accept_ra</pre>

{{Tip|The "inet6 manual" method is available in busybox 1.17.3-r3 and later.}}

=== IPv6 Static Address Configuration ===
Add the following to the file <code>/etc/network/interfaces</code>, below the <code>auto eth0</code> definition:
<pre>iface eth0 inet6 static
address 2001:470:ffff:ff::2
netmask 64
gateway 2001:470:ffff:ff::1
pre-up echo 0 > /proc/sys/net/ipv6/conf/eth0/accept_ra</pre>

== Example: Dual-Stack Configuration ==
This example shows a dual-stack configuration.
<pre>auto lo
iface lo inet loopback

auto eth0

iface eth0 inet static
address 192.168.1.150
netmask 255.255.255.0
gateway 192.168.1.1

iface eth0 inet6 static
address 2001:470:ffff:ff::2
netmask 64
gateway 2001:470:ffff:ff::1
pre-up echo 0 > /proc/sys/net/ipv6/conf/eth0/accept_ra</pre>

= Firewalling with iptables and ip6tables =
== Install iptables/ip6tables ==
* To install iptables:
: {{Cmd|apk add iptables}}

* To install ip6tables:
: {{Cmd|apk add ip6tables}}

* To install the man pages for iptables and ip6tables:
: {{Cmd|apk add iptables-doc}}

== Configure iptables/ip6tables ==
{{ Tip| Good examples of how to write iptables rules can be found at the Linux Home Networking Wiki http://www.linuxhomenetworking.com/wiki/index.php/Quick_HOWTO_:_Ch14_:_Linux_Firewalls_Using_iptables }}

== Save Firewall Rules ==

=== For iptables ===
# Set iptables to start on reboot
#* {{ Cmd| rc-update add iptables }}
# Write the firewall rules to disk
#* {{ Cmd| /etc/init.d/iptables save}}
# If you use Alpine Local Backup:
## Add the firewall rules to Alpine Local Backup
##* {{ Cmd| lbu add /var/lib/iptables/rules-save }}
## Save the configuration
##* {{ Cmd| lbu ci }}

=== For ip6tables ===
# Set ip6tables to start on reboot
#* {{ Cmd| rc-update add ip6tables }}
# Write the firewall rules to disk
#* {{ Cmd| /etc/init.d/ip6tables save}}
# If you use Alpine Local Backup:
## Add the firewall rules to Alpine Local Backup
##* {{ Cmd| lbu add /var/lib/ip6tables/rules-save }}
## Save the configuration
##* {{ Cmd| lbu ci }}

= Activating Changes and Testing Connectivity =
Changes made to <code>/etc/network/interfaces</code> can be activated by running:
{{Cmd|/etc/init.d/networking restart}}
If you did not get any errors, you can now test that networking is configured properly by attempting to ping out:
{{Cmd|ping www.google.com}}
<pre>PING www.l.google.com (74.125.47.103) 56(84) bytes of data.
64 bytes from yw-in-f103.1e100.net (74.125.47.103): icmp_seq=1 ttl=48 time=58.5 ms
64 bytes from yw-in-f103.1e100.net (74.125.47.103): icmp_seq=2 ttl=48 time=56.4 ms
64 bytes from yw-in-f103.1e100.net (74.125.47.103): icmp_seq=3 ttl=48 time=57.0 ms
64 bytes from yw-in-f103.1e100.net (74.125.47.103): icmp_seq=4 ttl=48 time=60.2 ms
^C
--- www.l.google.com ping statistics ---
4 packets transmitted, 4 received, 0% packet loss, time 3007ms
rtt min/avg/max/mdev = 56.411/58.069/60.256/1.501 ms</pre>

For an IPv6 traceroute (<code>traceroute6</code>), you will first need to install the <code>iputils</code> package:
{{Cmd|apk add iputils}}

Then run <code>traceroute6</code>:
{{Cmd|traceroute6 ipv6.google.com}}
<pre>traceroute to ipv6.l.google.com (2001:4860:8009::67) from 2001:470:ffff:ff::2, 30 hops max, 16 byte packets
1 2001:470:ffff:ff::1 (2001:470:ffff:ff::1) 3.49 ms 0.62 ms 0.607 ms
2 * * *
3 * * *
4 pr61.iad07.net.google.com (2001:504:0:2:0:1:5169:1) 134.313 ms 95.342 ms 88.425 ms
5 2001:4860::1:0:9ff (2001:4860::1:0:9ff) 100.759 ms 100.537 ms 89.907 ms
6 2001:4860::1:0:5db (2001:4860::1:0:5db) 115.563 ms 102.946 ms 106.191 ms
7 2001:4860::2:0:a7 (2001:4860::2:0:a7) 101.754 ms 100.475 ms 100.512 ms
8 2001:4860:0:1::c3 (2001:4860:0:1::c3) 99.272 ms 111.989 ms 99.835 ms
9 yw-in-x67.1e100.net (2001:4860:8009::67) 101.545 ms 109.675 ms 99.431 ms</pre>

User:Mattx86/Bash Profile

2011-01-26T12:27:09Z

Mattx86:

Here's the <code>~/.bash_profile</code> that I use:

<pre>
# Aliases
alias sudo='sudo ' # sudo: make aliases work
alias nano='nano -wcAiLS' # nano: -w: don't wrap long lines
# -c: constantly show cursor position
# -A: enable smart home key
# -i: automatically indent new lines
# -L: don't add newlines to the ends of files
# -S: scroll by line instead of half-screen
alias apk='apk --progress' # apk: show progress bar

# Shell Options
shopt -s checkwinsize

# Color Definitions for .bashrc
COL_YEL="\[\e[1;33m\]"
COL_GRA="\[\e[0;37m\]"
COL_WHI="\[\e[1;37m\]"
COL_GRE="\[\e[1;32m\]"
COL_RED="\[\e[1;31m\]"

# Bash Prompt
if test "$UID" -eq 0 ; then
_COL_USER=$COL_RED
_p=" #"
else
_COL_USER=$COL_GRE
_p=">"
fi
COLORIZED_PROMPT="${_COL_USER}\u${COL_WHI}@${COL_YEL}\h${COL_WHI}:\w${_p} \[\e[m\]"
case $TERM in
*term | rxvt | screen )
PS1="${COLORIZED_PROMPT}\[\e]0;\u@\h:\w\007\]" ;;
linux )
PS1="${COLORIZED_PROMPT}" ;;
* )
PS1="\u@\h:\w${_p} " ;;
esac
</pre>

{{Tip|Be sure to symlink <code>.bashrc</code> to <code>.bash_profile</code>.}}

User:Mattx86/Bash Profile

2011-01-26T11:40:03Z

Mattx86:

Here's the <code>~/.bash_profile</code> that I use:

<pre>
# Aliases
alias sudo='sudo ' # sudo: make aliases work
alias nano='nano -wc' # nano: -w: don't wrap long lines
# -c: constantly show cursor position
alias apk='apk --progress' # apk: show progress bar

# Shell Options
shopt -s checkwinsize

# Color Definitions for .bashrc
COL_YEL="\[\e[1;33m\]"
COL_GRA="\[\e[0;37m\]"
COL_WHI="\[\e[1;37m\]"
COL_GRE="\[\e[1;32m\]"
COL_RED="\[\e[1;31m\]"

# Bash Prompt
if test "$UID" -eq 0 ; then
_COL_USER=$COL_RED
_p=" #"
else
_COL_USER=$COL_GRE
_p=">"
fi
COLORIZED_PROMPT="${_COL_USER}\u${COL_WHI}@${COL_YEL}\h${COL_WHI}:\w${_p} \[\e[m\]"
case $TERM in
*term | rxvt | screen )
PS1="${COLORIZED_PROMPT}\[\e]0;\u@\h:\w\007\]" ;;
linux )
PS1="${COLORIZED_PROMPT}" ;;
* )
PS1="\u@\h:\w${_p} " ;;
esac
</pre>

{{Tip|Be sure to symlink <code>.bashrc</code> to <code>.bash_profile</code>.}}

User:Mattx86

2011-01-25T07:58:47Z

Mattx86:

* My personal pages:
** [[User:Mattx86/Bash Profile]]
** [[User:Mattx86/tmux config]]
** [[User:Mattx86/Alpine Fresh Installation]] (mostly outdated)

* Wiki draft pages:
** [[User:Mattx86/Obtaining Alpine Linux]]

User:Mattx86

2011-01-25T07:58:23Z

Mattx86:

* My personal pages:
** [[User:Mattx86/Alpine Fresh Installation]] (mostly outdated)
** [[User:Mattx86/Bash Profile]]
** [[User:Mattx86/tmux config]]

* Wiki draft pages:
** [[User:Mattx86/Obtaining Alpine Linux]]

User:Mattx86/tmux config

2011-01-25T07:41:47Z

Mattx86: Created page with "The following is the <code>~/.tmux.conf</code> file I use: <pre> # Basic settings bind z source-file ~/.tmux.conf # Reload tmux config (Ctrl+b, z) set -g history-limit 1000 set..."

The following is the <code>~/.tmux.conf</code> file I use:

<pre>
# Basic settings
bind z source-file ~/.tmux.conf # Reload tmux config (Ctrl+b, z)
set -g history-limit 1000
set-window-option -g mode-keys vi

# Window panes
unbind %
bind | split-window -h # Split window horizontally (Ctrl+b, |) (i.e., hold Ctrl, hit 'b', and then get the pipe character)
bind - split-window -v # Split window vertically (Ctrl+b, -) (i.e., hold Ctrl, hit 'b', and then hit the minus key)
bind-key C-u resize-pane -U # Resize window up (Ctrl+b, u) (i.e., hold Ctrl and alternate hitting 'b' and 'u')
bind-key C-d resize-pane -D # Resize window down (Ctrl+b, d) (similar)
bind-key C-l resize-pane -L # Resize window left (Ctrl+b, l) (similar)
bind-key C-r resize-pane -R # Resize window right (Ctrl+b, r) (similar)
set -g mouse-select-pane off
set -g pane-active-border-fg green
set -g pane-active-border-bg default

# Status bar
set -g status-bg black
set -g status-fg white
#set -g status-left '#[fg=green]#(whoami)#[default]@#[fg=yellow]#H#[default]'
set -g status-left ''
set -g status-left-length 0
set -g status-right-length 60
set -g status-right '#[fg=cyan]#(whoami)@#H#[default] #[fg=yellow]#(cut -d " " -f 1-3 /proc/loadavg)#[default] #[bg=blue]%a %b %d, %H:%M#[default]'
set-window-option -g window-status-current-bg black
set-window-option -g window-status-current-fg green
set -g status-justify centre

# Remote Terminal: Window title
set-option -g set-titles on
set-option -g set-titles-string '#S:#I.#P #T'
set-window-option -g automatic-rename on

# Remote Terminal: Enable mouse scrolling from, e.g., gnome-terminal.
# The alternative is to enter tmux copy mode (Ctrl+b, [), and then use
# the PgUp/PgDn/Arrow keys. When done, quit copy mode (q).
set -g terminal-overrides 'xterm*:smcup@:rmcup@'
</pre>

User:Mattx86

2011-01-25T07:37:12Z

Mattx86: Added link to my 'tmux config' page

* My personal pages:
** [[User:Mattx86/Alpine Fresh Installation]]
** [[User:Mattx86/Bash Profile]]
** [[User:Mattx86/tmux config]]

* Wiki draft pages:
** [[User:Mattx86/Obtaining Alpine Linux]]

APKBUILD Reference

2011-01-18T01:09:22Z

Mattx86: /* install */

APKBUILDs are the scripts that are created in order to build Alpine packages using the [[abuild]] tool.

This page is intended to serve as a reference for creating APKBUILDs; if this is your first time creating a package for Alpine Linux, please see [[Creating an Alpine package]].

= Legend =
The following notes will assist you in understanding this document.

In description text:
* If a variable is not prefixed with a ''$'', it will be represented by italics (i.e., ''srcdir'' ).
* Functions will also be represented by italics, but will also end with a pair of parentheses (i.e., ''build()'' ).
* Shell commands will be represented by italics and bold type (i.e., '''''abuild checksum''''').

= Variables =
{{Note|Variables that contain a path (e.g. ''$srcdir'' and ''$pkgdir'') should always be quoted using double quotes (i.e., ''"$srcdir"''). This is done to prevent things from breaking, should the user have the APKBUILD in a directory path that contains spaces.}}
{{Note|All arbitrary variable and function names should be prefixed with an underscore character ( _ ) to avoid name clashes with the internals of abuild (i.e., ''_builddir'').}}

== abuild-defined variables ==
The following variables are defined by abuild:

==== startdir ====
: The directory where the APKBUILD script is.
==== srcdir ====
: The directory where sources, from the ''source'' variable, are downloaded to and unpacked to.
==== pkgdir ====
: This directory should contain the files for the main package. For example, a normal [http://en.wikipedia.org/wiki/GNU_build_system autotools] package would have '''''make DESTDIR="$pkgdir" install''''' in the ''package()'' function.
==== subpkgdir ====
: This directory should contain the files for a subpackage. This variable should only be used from subpackage functions.

== User-defined variables ==
The following variables should be defined by the user:
==== arch ====
: Package architecture(s) to build for. Can be one of: '''x86, x86_64, all''', or '''noarch''', where '''all''' means all architectures, and '''noarch''' means it's architecture-independent (e.g., a pure-python package).
: {{Tip|To determine if your APKBUILD can use '''noarch''': First specify '''all''' and then build the package by executing '''''abuild -r'''''. Watch the output towards the end for warnings saying that '''noarch''' can be used. If the main package and all subpackages, if you have any subpackages, give a warning saying that '''noarch''' can be used, then you can use '''noarch'''.}}
==== depends ====
: Run-time dependency package(s) that are not shared-object dependencies. Shared objects dependencies are auto-detected and should not be specified here.
==== depends_dev ====
: Run-time dependency package(s) for the '''$pkgname-dev''' subpackage.
==== install ====
: There are 6 different types of install scripts. Install scripts are named '''$pkgname.action''', where '''action''' can be: '''pre-install, post-install, pre-upgrade, post-upgrade, pre-deinstall''', or '''post-deinstall'''. For example, if ''pkgname'' is set to '''mypackage''' and ''install'' is set to '''$pkgname.post-install''', then a script named '''mypackage.post-install''' must exist along-side the APKBUILD.

: First, a few notes regarding install scripts:
<blockquote>{{Note|When using install scripts, ''$install'' should be included in ''source'' so that checksums can be generated and used for the install scripts specified in ''install''. For example:
<pre>
install="$pkgname.pre-install $pkgname.post-install"
source="http://....
$install"
</pre>}}
{{Note|Always use <code>/bin/sh</code> for the command-line interpreter on the [http://en.wikipedia.org/wiki/Shebang_%28Unix%29 shebang line] of your install scripts.}}</blockquote>

The following are the different types of install scripts in detail:

===== $pkgname.pre-install =====
: This script is executed ''before installing'' the package. Typical use is when the package needs a user/group to be created. For example:
<blockquote><pre>
#!/bin/sh
adduser -H -s /bin/false -D clamav 2>/dev/null
exit 0
</pre>
{{Note|If the script exits with a failure (e.g., if the user already exists), the package will not be installed and <code>apk</code> will exit with failure, hence the '''''exit 0''''' at the end.}}</blockquote>

===== $pkgname.post-install =====
: This script is executed ''after installing'' the package.

===== $pkgname.pre-upgrade =====
: This script is executed ''before upgrading'' the package.

===== $pkgname.post-upgrade =====
: This script is executed ''after upgrading'' the package.

===== $pkgname.pre-deinstall =====
: This script is executed ''before uninstalling'' the package.
: {{Note|If the script exits with failure, <code>apk</code> will not uninstall the package.}}

===== $pkgname.post-deinstall =====
: This script is executed ''after uninstalling'' the package.

==== license ====
: License(s) for the package.
==== makedepends ====
: Build-time dependency package(s).
==== md5sums ====
: Checksums for the files/URLs listed in ''source''. The checksums are normally generated and updated by executing '''''abuild checksum''''' and should be the last item in the APKBUILD.
==== options ====
: Build-time options for the package. Can be: '''!strip''' - to avoid stripping symbols from binaries.
==== pkgdesc ====
: A brief, one-line description of what the package does.

: Here's an example from the OpenSSH client package:
: <pre>pkgdesc="Port of OpenBSD's free SSH release - client"</pre>
==== pkggroups ====
: System group(s) to be created during build-time. System group(s) should also be created in the '''[[APKBUILD Reference#.24pkgname.pre-install|$pkgname.pre-install]]''' script, so that the system group(s) are also created prior to package installation for run-time use.
==== pkgname ====
: The name of the package. All letters should be lowercase.
: {{Note|When creating an APKBUILD of a module or library for another package, we use some common package prefixes, such as: ''lua-'', ''perl-'', ''php-'', and ''py-''. Search aports for other common prefixes.}}

==== pkgrel ====
: Alpine package release number. Starts at 0 (zero). Always increment ''pkgrel'' when making updates to an aport; reset ''pkgrel'' to 0 (zero) when incrementing ''pkgver''.
==== pkgusers ====
: System user(s) to be created during build-time. System user(s) should also be created in the '''[[APKBUILD Reference#.24pkgname.pre-install|$pkgname.pre-install]]''' script, so that the system user(s) are also created prior to package installation for run-time use.
==== pkgver ====
: The version of the software being packaged.
==== replaces ====
: Package(s) that this package replaces. This package will "take over" files owned by packages listed in the ''replaces'' variable. This is useful when files move from one sub-/package to another, or when a package gets renamed.
==== 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 [[APKBUILD Reference#install|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:
:: {{Cmd|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:
:: <pre>http://downloads.sourceforge.net/$pkgname/$pkgname-$pkgver.tar.gz</pre>
:: (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:
:: <pre>http://oss.example.org/?get=software&ver=1.0</pre>
:: You must prepend 'saveas-' to the protocol and append '/software-1.0.tar.gz' (for instance) to the end of the URI, like so:
:: <pre>saveas-http://oss.example.org/?get=software&ver=1.0/software-1.0.tar.gz</pre>
:: 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.

:* 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

==== subpackages ====
: Subpackages built from this APKBUILD. abuild will parse this variable and try to find a subpackage split function. The split function must ''move'' files that do not belong in the main package, from ''$pkgdir'' to ''$subpkgdir''. Files and directories can also be ''copied'' from ''$startdir'' and ''$srcdir'' to ''$subpkgdir''.

: The split function can be specified in 1 of 3 different ways:
:# subpkgname:'''splitfunc'''
:# $pkgname-'''splitfunc'''
:# '''splitfunc'''

: For more information, see the [[APKBUILD Reference#Subpackages_Example|Subpackages Example]].

==== url ====
: The homepage for the package. This is to help users find upstream documentation and other information regarding the package.

= Functions =
{{Note|All functions should consider the current working directory as undefined, and should therefore use the [[APKBUILD Reference#abuild-defined_variables|abuild-defined directory variables]] to their advantage.}}

== abuild-defined functions ==
The following functions are provided by abuild and can be overridden:

==== fetch() ====
: Downloads remote sources listed in ''source'' to ''SRCDEST'' (''SRCDEST'' is configured in ''/etc/abuild.conf'') and creates symlinks in ''$srcdir''.
==== unpack() ====
: Unpacks .tgz, .tar.gz, .tar.bz2, .tar.lzma, .tar.xz, and .zip archives in ''$srcdir'' to ''$srcdir''.
==== dev() ====
: Subpackage function for the '''$pkgname-dev''' package. Without specifying a custom ''dev()'' function, abuild will call it's internal ''dev()'' function, which in turn calls ''default_dev()'', which will move ''"$pkgdir"/usr/include'', ''*.a'', ''*.la'' and similar files to ''$subpkgdir''.
==== doc() ====
: Subpackage function for the '''$pkgname-doc''' package. Without specifying a custom ''doc()'' function, abuild will call it's internal ''doc()'' function, which in turn calls ''default_doc()'', which will move ''"$pkgdir"/usr/share/doc'', ''"$pkgdir"/usr/share/man'' and similar to ''$subpkgdir''.

== User-defined functions ==
The following functions should be defined by the user:

==== prepare() ====
: '''''Optional''.''' Used for build preparation: patches, etc, should be applied here. This function is available for your convenience.
==== build() ====
: '''Required.''' This is the compilation stage. This function will be called as the current user (unless the ''package()'' function is missing - for compatibility reasons). If no compilation is needed, this function can contain a single line: '''''return 0'''''
==== package() ====
: '''Required.''' This is the packaging stage. Here, the built application and support files should be installed into '''$pkgdir'''. If this is a metapackage, this function can contain a single line: '''''mkdir -p "$pkgdir" && return 0'''''

{{Note|Building in fakeroot will reduce performance for parallel builds dramatically. It is for this reason that we split the build and package process into two separate functions.}}

= Examples =
The following APKBUILD examples will assist you in understanding how to create an APKBUILD.

== Subpackages Example ==
Consider the following APKBUILD snippet:
pkgname="foo"
subpackages="$pkgname-dev $pkgname-doc py-$pkgname:pysub libfoo"

It will ...
* create the following 5 packages:
# foo (main)
# foo-dev (sub)
# foo-doc (sub)
# py-foo (sub)
# libfoo (sub)

* using the following 5 package functions (respectively) to fill them with files:
# ''package()'': will be provided by the user (and can make use of the ''$pkgdir'' variable).
# ''dev()'': will be provided by abuild unless we override it, by providing our own ''dev()'' function (which can make use of the ''$subpkgdir'' variable).
# ''doc()'': will be provided by abuild unless we override it, by providing our own ''doc()'' function (which can make use of the ''$subpkgdir'' variable).
# ''pysub()'': will be provided by the user (and can make use of the ''$subpkgdir'' variable).
# ''libfoo()'': will be provided by the user (and can make use of the ''$subpkgdir'' variable).

== Simple APKBUILD ==
Simple APKBUILD with -doc subpackage, using abuild's default ''doc()'' function:
<pre>
# Maintainer: Natanael Copa <ncopa@alpinelinux.org>
pkgname=m4
pkgver=1.4.15
pkgrel=0
pkgdesc="GNU macro processor"
url="http://www.gnu.org/software/m4"
depends=
arch="all"
license="GPL"
subpackages="m4-doc"
source="ftp://ftp.gnu.org/gnu/m4/$pkgname-$pkgver.tar.gz
gnulib-uclibc.patch"

_builddir="$srcdir"/$pkgname-$pkgver
prepare() {
cd "$_builddir"
patch -p1 -i "$srcdir"/gnulib-uclibc.patch
}

build() {
cd "$_builddir"
./configure --prefix=/usr
make
}

package() {
cd "$_builddir"
make install DESTDIR="$pkgdir"
}

md5sums="5649a2e593b6c639deae9e72ede777dd m4-1.4.15.tar.gz
20a7dedec0e9e0ee7107e33e798ffdbe gnulib-uclibc.patch"
</pre>

== APKBUILD with Multiple Subpackages ==
A more complex APKBUILD with -doc, -dev and python subpackages:
<pre>
# Contributor: Carlo Landmeter <clandmeter at gmail>
# Maintainer: Carlo Landmeter <clandmeter at gmail>
pkgname=libxml2
pkgver=2.7.8
pkgrel=0
pkgdesc="XML parsing library, version 2"
url="http://www.xmlsoft.org/"
arch="all"
license="MIT"
depends=
depends_dev="zlib-dev python-dev"
makedepends="zlib-dev python-dev"
subpackages="$pkgname-doc $pkgname-dev py-$pkgname:py $pkgname-utils"
source="ftp://ftp.xmlsoft.org/${pkgname}/${pkgname}-${pkgver}.tar.gz
largefile64.patch"

options="!strip"

_builddir="$srcdir/$pkgname-$pkgver"
prepare() {
cd "$_builddir"
for _i in "$srcdir"/*.patch; do
patch -p1 -i "$_i"
done
}

build() {
cd "$_builddir"
./configure --prefix=/usr \
--sysconfdir=/etc \
--mandir=/usr/share/man \
--infodir=/usr/share/info
make
}

package() {
cd "$_builddir"
make -j1 DESTDIR="$pkgdir" install
install -Dm644 COPYING "$pkgdir"/usr/share/licenses/$pkgname/COPYING
}

py() {
cd "$_builddir"
pkgdesc="$pkgname python bindings"
install -d "$subpkgdir"/usr/lib
mv "$pkgdir"/usr/lib/python* "$subpkgdir"/usr/lib/
}

utils() {
pkgdesc="XML utilities"
replaces="libxml2"
mkdir -p "$subpkgdir"/usr
mv "$pkgdir"/usr/bin "$subpkgdir"/usr/
}

md5sums="8127a65e8c3b08856093099b52599c86 libxml2-2.7.8.tar.gz
5ad4915665608ebfa5b89f7908467a72 largefile64.patch"
</pre>

APKBUILD Reference

2011-01-18T01:05:53Z

Mattx86:

APKBUILDs are the scripts that are created in order to build Alpine packages using the [[abuild]] tool.

This page is intended to serve as a reference for creating APKBUILDs; if this is your first time creating a package for Alpine Linux, please see [[Creating an Alpine package]].

= Legend =
The following notes will assist you in understanding this document.

In description text:
* If a variable is not prefixed with a ''$'', it will be represented by italics (i.e., ''srcdir'' ).
* Functions will also be represented by italics, but will also end with a pair of parentheses (i.e., ''build()'' ).
* Shell commands will be represented by italics and bold type (i.e., '''''abuild checksum''''').

= Variables =
{{Note|Variables that contain a path (e.g. ''$srcdir'' and ''$pkgdir'') should always be quoted using double quotes (i.e., ''"$srcdir"''). This is done to prevent things from breaking, should the user have the APKBUILD in a directory path that contains spaces.}}
{{Note|All arbitrary variable and function names should be prefixed with an underscore character ( _ ) to avoid name clashes with the internals of abuild (i.e., ''_builddir'').}}

== abuild-defined variables ==
The following variables are defined by abuild:

==== startdir ====
: The directory where the APKBUILD script is.
==== srcdir ====
: The directory where sources, from the ''source'' variable, are downloaded to and unpacked to.
==== pkgdir ====
: This directory should contain the files for the main package. For example, a normal [http://en.wikipedia.org/wiki/GNU_build_system autotools] package would have '''''make DESTDIR="$pkgdir" install''''' in the ''package()'' function.
==== subpkgdir ====
: This directory should contain the files for a subpackage. This variable should only be used from subpackage functions.

== User-defined variables ==
The following variables should be defined by the user:
==== arch ====
: Package architecture(s) to build for. Can be one of: '''x86, x86_64, all''', or '''noarch''', where '''all''' means all architectures, and '''noarch''' means it's architecture-independent (e.g., a pure-python package).
: {{Tip|To determine if your APKBUILD can use '''noarch''': First specify '''all''' and then build the package by executing '''''abuild -r'''''. Watch the output towards the end for warnings saying that '''noarch''' can be used. If the main package and all subpackages, if you have any subpackages, give a warning saying that '''noarch''' can be used, then you can use '''noarch'''.}}
==== depends ====
: Run-time dependency package(s) that are not shared-object dependencies. Shared objects dependencies are auto-detected and should not be specified here.
==== depends_dev ====
: Run-time dependency package(s) for the '''$pkgname-dev''' subpackage.
==== install ====
: There are 6 different types of install scripts. Install scripts are named '''$pkgname.action''', where '''action''' can be: '''pre-install, post-install, pre-upgrade, post-upgrade, pre-deinstall''', or '''post-deinstall'''. For example, if ''pkgname'' is set to '''mypackage''' and ''install'' is set to '''$pkgname.post-install''', then a script named '''mypackage.post-install''' must exist along-side the APKBUILD.

: First, a few notes regarding install scripts:
<blockquote>{{Note|When using install scripts, ''$install'' should be included in ''source'' so that checksums can be generated and used for the install scripts specified in ''install''. For example:
<pre>
install="$pkgname.pre-install $pkgname.post-install"
source="http://....
$install"
</pre>}}
{{Note|Always use <code>/bin/sh</code> for the command-line interpreter on the [http://en.wikipedia.org/wiki/Shebang_%28Unix%29 shebang line] of your install scripts.}}</blockquote>

The following are the different types of install scripts in detail:

===== $pkgname.pre-install =====
: This script is executed ''before'' the package is installed. Typical use is when the package needs a user/group to be created. For example:
<blockquote><pre>
#!/bin/sh
adduser -H -s /bin/false -D clamav 2>/dev/null
exit 0
</pre>
{{Note|If the script exits with a failure (e.g., if the user already exists), the package will not be installed and <code>apk</code> will exit with failure, hence the '''''exit 0''''' at the end.}}</blockquote>

===== $pkgname.post-install =====
: This script is executed ''after'' the package is installed.

===== $pkgname.pre-upgrade =====
: This script is executed ''before upgrading'' the package.

===== $pkgname.post-upgrade =====
: This script is executed ''after upgrading'' the package.

===== $pkgname.pre-deinstall =====
: This script is executed ''before uninstalling'' the package.
: {{Note|If the script exits with failure, <code>apk</code> will not uninstall the package.}}

===== $pkgname.post-deinstall =====
: This script is executed ''after uninstalling'' the package.

==== license ====
: License(s) for the package.
==== makedepends ====
: Build-time dependency package(s).
==== md5sums ====
: Checksums for the files/URLs listed in ''source''. The checksums are normally generated and updated by executing '''''abuild checksum''''' and should be the last item in the APKBUILD.
==== options ====
: Build-time options for the package. Can be: '''!strip''' - to avoid stripping symbols from binaries.
==== pkgdesc ====
: A brief, one-line description of what the package does.

: Here's an example from the OpenSSH client package:
: <pre>pkgdesc="Port of OpenBSD's free SSH release - client"</pre>
==== pkggroups ====
: System group(s) to be created during build-time. System group(s) should also be created in the '''[[APKBUILD Reference#.24pkgname.pre-install|$pkgname.pre-install]]''' script, so that the system group(s) are also created prior to package installation for run-time use.
==== pkgname ====
: The name of the package. All letters should be lowercase.
: {{Note|When creating an APKBUILD of a module or library for another package, we use some common package prefixes, such as: ''lua-'', ''perl-'', ''php-'', and ''py-''. Search aports for other common prefixes.}}

==== pkgrel ====
: Alpine package release number. Starts at 0 (zero). Always increment ''pkgrel'' when making updates to an aport; reset ''pkgrel'' to 0 (zero) when incrementing ''pkgver''.
==== pkgusers ====
: System user(s) to be created during build-time. System user(s) should also be created in the '''[[APKBUILD Reference#.24pkgname.pre-install|$pkgname.pre-install]]''' script, so that the system user(s) are also created prior to package installation for run-time use.
==== pkgver ====
: The version of the software being packaged.
==== replaces ====
: Package(s) that this package replaces. This package will "take over" files owned by packages listed in the ''replaces'' variable. This is useful when files move from one sub-/package to another, or when a package gets renamed.
==== 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 [[APKBUILD Reference#install|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:
:: {{Cmd|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:
:: <pre>http://downloads.sourceforge.net/$pkgname/$pkgname-$pkgver.tar.gz</pre>
:: (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:
:: <pre>http://oss.example.org/?get=software&ver=1.0</pre>
:: You must prepend 'saveas-' to the protocol and append '/software-1.0.tar.gz' (for instance) to the end of the URI, like so:
:: <pre>saveas-http://oss.example.org/?get=software&ver=1.0/software-1.0.tar.gz</pre>
:: 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.

:* 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

==== subpackages ====
: Subpackages built from this APKBUILD. abuild will parse this variable and try to find a subpackage split function. The split function must ''move'' files that do not belong in the main package, from ''$pkgdir'' to ''$subpkgdir''. Files and directories can also be ''copied'' from ''$startdir'' and ''$srcdir'' to ''$subpkgdir''.

: The split function can be specified in 1 of 3 different ways:
:# subpkgname:'''splitfunc'''
:# $pkgname-'''splitfunc'''
:# '''splitfunc'''

: For more information, see the [[APKBUILD Reference#Subpackages_Example|Subpackages Example]].

==== url ====
: The homepage for the package. This is to help users find upstream documentation and other information regarding the package.

= Functions =
{{Note|All functions should consider the current working directory as undefined, and should therefore use the [[APKBUILD Reference#abuild-defined_variables|abuild-defined directory variables]] to their advantage.}}

== abuild-defined functions ==
The following functions are provided by abuild and can be overridden:

==== fetch() ====
: Downloads remote sources listed in ''source'' to ''SRCDEST'' (''SRCDEST'' is configured in ''/etc/abuild.conf'') and creates symlinks in ''$srcdir''.
==== unpack() ====
: Unpacks .tgz, .tar.gz, .tar.bz2, .tar.lzma, .tar.xz, and .zip archives in ''$srcdir'' to ''$srcdir''.
==== dev() ====
: Subpackage function for the '''$pkgname-dev''' package. Without specifying a custom ''dev()'' function, abuild will call it's internal ''dev()'' function, which in turn calls ''default_dev()'', which will move ''"$pkgdir"/usr/include'', ''*.a'', ''*.la'' and similar files to ''$subpkgdir''.
==== doc() ====
: Subpackage function for the '''$pkgname-doc''' package. Without specifying a custom ''doc()'' function, abuild will call it's internal ''doc()'' function, which in turn calls ''default_doc()'', which will move ''"$pkgdir"/usr/share/doc'', ''"$pkgdir"/usr/share/man'' and similar to ''$subpkgdir''.

== User-defined functions ==
The following functions should be defined by the user:

==== prepare() ====
: '''''Optional''.''' Used for build preparation: patches, etc, should be applied here. This function is available for your convenience.
==== build() ====
: '''Required.''' This is the compilation stage. This function will be called as the current user (unless the ''package()'' function is missing - for compatibility reasons). If no compilation is needed, this function can contain a single line: '''''return 0'''''
==== package() ====
: '''Required.''' This is the packaging stage. Here, the built application and support files should be installed into '''$pkgdir'''. If this is a metapackage, this function can contain a single line: '''''mkdir -p "$pkgdir" && return 0'''''

{{Note|Building in fakeroot will reduce performance for parallel builds dramatically. It is for this reason that we split the build and package process into two separate functions.}}

= Examples =
The following APKBUILD examples will assist you in understanding how to create an APKBUILD.

== Subpackages Example ==
Consider the following APKBUILD snippet:
pkgname="foo"
subpackages="$pkgname-dev $pkgname-doc py-$pkgname:pysub libfoo"

It will ...
* create the following 5 packages:
# foo (main)
# foo-dev (sub)
# foo-doc (sub)
# py-foo (sub)
# libfoo (sub)

* using the following 5 package functions (respectively) to fill them with files:
# ''package()'': will be provided by the user (and can make use of the ''$pkgdir'' variable).
# ''dev()'': will be provided by abuild unless we override it, by providing our own ''dev()'' function (which can make use of the ''$subpkgdir'' variable).
# ''doc()'': will be provided by abuild unless we override it, by providing our own ''doc()'' function (which can make use of the ''$subpkgdir'' variable).
# ''pysub()'': will be provided by the user (and can make use of the ''$subpkgdir'' variable).
# ''libfoo()'': will be provided by the user (and can make use of the ''$subpkgdir'' variable).

== Simple APKBUILD ==
Simple APKBUILD with -doc subpackage, using abuild's default ''doc()'' function:
<pre>
# Maintainer: Natanael Copa <ncopa@alpinelinux.org>
pkgname=m4
pkgver=1.4.15
pkgrel=0
pkgdesc="GNU macro processor"
url="http://www.gnu.org/software/m4"
depends=
arch="all"
license="GPL"
subpackages="m4-doc"
source="ftp://ftp.gnu.org/gnu/m4/$pkgname-$pkgver.tar.gz
gnulib-uclibc.patch"

_builddir="$srcdir"/$pkgname-$pkgver
prepare() {
cd "$_builddir"
patch -p1 -i "$srcdir"/gnulib-uclibc.patch
}

build() {
cd "$_builddir"
./configure --prefix=/usr
make
}

package() {
cd "$_builddir"
make install DESTDIR="$pkgdir"
}

md5sums="5649a2e593b6c639deae9e72ede777dd m4-1.4.15.tar.gz
20a7dedec0e9e0ee7107e33e798ffdbe gnulib-uclibc.patch"
</pre>

== APKBUILD with Multiple Subpackages ==
A more complex APKBUILD with -doc, -dev and python subpackages:
<pre>
# Contributor: Carlo Landmeter <clandmeter at gmail>
# Maintainer: Carlo Landmeter <clandmeter at gmail>
pkgname=libxml2
pkgver=2.7.8
pkgrel=0
pkgdesc="XML parsing library, version 2"
url="http://www.xmlsoft.org/"
arch="all"
license="MIT"
depends=
depends_dev="zlib-dev python-dev"
makedepends="zlib-dev python-dev"
subpackages="$pkgname-doc $pkgname-dev py-$pkgname:py $pkgname-utils"
source="ftp://ftp.xmlsoft.org/${pkgname}/${pkgname}-${pkgver}.tar.gz
largefile64.patch"

options="!strip"

_builddir="$srcdir/$pkgname-$pkgver"
prepare() {
cd "$_builddir"
for _i in "$srcdir"/*.patch; do
patch -p1 -i "$_i"
done
}

build() {
cd "$_builddir"
./configure --prefix=/usr \
--sysconfdir=/etc \
--mandir=/usr/share/man \
--infodir=/usr/share/info
make
}

package() {
cd "$_builddir"
make -j1 DESTDIR="$pkgdir" install
install -Dm644 COPYING "$pkgdir"/usr/share/licenses/$pkgname/COPYING
}

py() {
cd "$_builddir"
pkgdesc="$pkgname python bindings"
install -d "$subpkgdir"/usr/lib
mv "$pkgdir"/usr/lib/python* "$subpkgdir"/usr/lib/
}

utils() {
pkgdesc="XML utilities"
replaces="libxml2"
mkdir -p "$subpkgdir"/usr
mv "$pkgdir"/usr/bin "$subpkgdir"/usr/
}

md5sums="8127a65e8c3b08856093099b52599c86 libxml2-2.7.8.tar.gz
5ad4915665608ebfa5b89f7908467a72 largefile64.patch"
</pre>

APKBUILD Reference

2011-01-17T08:55:04Z

Mattx86: /* pkgname */

APKBUILDs are the scripts that are created in order to build Alpine packages using the [[abuild]] tool.

This page is intended to serve as a reference for creating APKBUILDs; if this is your first time creating a package for Alpine Linux, please see [[Creating an Alpine package]].

= Legend =
The following notes will assist you in understanding this document.

In description text:
* If a variable is not prefixed with a ''$'', it will be represented by italics (i.e., ''srcdir'' ).
* Functions will also be represented by italics, but will also end with a pair of parentheses (i.e., ''build()'' ).
* Shell commands will be represented by italics and bold type (i.e., '''''abuild checksum''''').

= Variables =
{{Note|Variables that contain a path (e.g. ''$srcdir'' and ''$pkgdir'') should always be quoted using double quotes (i.e., ''"$srcdir"''). This is done to prevent things from breaking, should the user have the APKBUILD in a directory path that contains spaces.}}
{{Note|All arbitrary variable and function names should be prefixed with an underscore character ( _ ) to avoid name clashes with the internals of abuild (i.e., ''_builddir'').}}

== abuild-defined variables ==
The following variables are defined by abuild:

==== startdir ====
: The directory where the APKBUILD script is.
==== srcdir ====
: The directory where sources, from the ''source'' variable, are downloaded to and unpacked to.
==== pkgdir ====
: This directory should contain the files for the main package. For example, a normal [http://en.wikipedia.org/wiki/GNU_build_system autotools] package would have '''''make DESTDIR="$pkgdir" install''''' in the ''package()'' function.
==== subpkgdir ====
: This directory should contain the files for a subpackage. This variable should only be used from subpackage functions.

== User-defined variables ==
The following variables should be defined by the user:
==== arch ====
: Package architecture(s) to build for. Can be one of: '''x86, x86_64, all''', or '''noarch''', where '''all''' means all architectures, and '''noarch''' means it's architecture-independent (e.g., a pure-python package).
: {{Tip|To determine if your APKBUILD can use '''noarch''': First specify '''all''' and then build the package by executing '''''abuild -r'''''. Watch the output towards the end for warnings saying that '''noarch''' can be used. If the main package and all subpackages, if you have any subpackages, give a warning saying that '''noarch''' can be used, then you can use '''noarch'''.}}
==== depends ====
: Run-time dependency package(s) that are not shared-object dependencies. Shared objects dependencies are auto-detected and should not be specified here.
==== depends_dev ====
: Run-time dependency package(s) for the '''$pkgname-dev''' subpackage.
==== install ====
: There are 6 different types of install scripts. Install scripts are named '''$pkgname.action''', where '''action''' can be: '''pre-install, post-install, pre-upgrade, post-upgrade, pre-deinstall''', or '''post-deinstall'''. For example, if ''pkgname'' is set to '''mypackage''' and ''install'' is set to '''$pkgname.post-install''', then a script named '''mypackage.post-install''' must exist along-side the APKBUILD.

: First, a few notes regarding install scripts:
<blockquote>{{Note|When using install scripts, ''$install'' should be included in ''source'' so that checksums can be generated and used for the install scripts specified in ''install''. For example:
<pre>
install="$pkgname.pre-install $pkgname.post-install"
source="http://....
$install"
</pre>}}
{{Note|Always use <code>/bin/sh</code> for the command-line interpreter on the [http://en.wikipedia.org/wiki/Shebang_%28Unix%29 shebang line] of your install scripts.}}</blockquote>

The following are the different types of install scripts in detail:

===== $pkgname.pre-install =====
: This script is executed ''before'' the package is installed. Typical use is when the package needs a user/group to be created. For example:
<blockquote><pre>
#!/bin/sh
adduser -H -s /bin/false -D clamav 2>/dev/null
exit 0
</pre>
{{Note|If the script exits with a failure (e.g., if the user already exists), the package will not be installed and <code>apk</code> will exit with failure, hence the '''''exit 0''''' at the end.}}</blockquote>

===== $pkgname.post-install =====
: This script is executed ''after'' the package is installed.

===== $pkgname.pre-upgrade =====
: This script is executed ''before upgrading'' the package.

===== $pkgname.post-upgrade =====
: This script is executed ''after upgrading'' the package.

===== $pkgname.pre-deinstall =====
: This script is executed ''before uninstalling'' the package.
: {{Note|If the script exits with failure, <code>apk</code> will not uninstall the package.}}

===== $pkgname.post-deinstall =====
: This script is executed ''after uninstalling'' the package.

==== license ====
: License(s) for the package.
==== makedepends ====
: Build-time dependency package(s).
==== md5sums ====
: Checksums for the files/URLs listed in ''source''. The checksums are normally generated and updated by executing '''''abuild checksum''''' and should be the last item in the APKBUILD.
==== options ====
: Build-time options for the package. Can be: '''!strip''' - to avoid stripping symbols from binaries.
==== pkgdesc ====
: A brief, one-line description of what the package does.

: Here's an example from the OpenSSH client package:
: <pre>pkgdesc="Port of OpenBSD's free SSH release - client"</pre>
==== pkggroups ====
: System group(s) to be created during build-time. System group(s) should also be created in the '''[[APKBUILD Reference#.24pkgname.pre-install|$pkgname.pre-install]]''' script, so that the system group(s) are also created prior to package installation for run-time use.
==== pkgname ====
: The name of the package. All letters should be lowercase.
: {{Note|When creating an APKBUILD of a module or library for another package, we use some common package prefixes, such as: ''lua-'', ''perl-'', ''php-'', and ''py-''. Search aports for other common prefixes.}}

==== pkgrel ====
: Alpine package release number. Starts at 0 (zero). Always increment ''pkgrel'' when making updates to an aport; reset ''pkgrel'' to 0 (zero) when incrementing ''pkgver''.
==== pkgusers ====
: System user(s) to be created during build-time. System user(s) should also be created in the '''[[APKBUILD Reference#.24pkgname.pre-install|$pkgname.pre-install]]''' script, so that the system user(s) are also created prior to package installation for run-time use.
==== pkgver ====
: The version of the software being packaged.
==== replaces ====
: Package(s) that this package replaces. This package will "take over" files owned by packages listed in the ''replaces'' variable. This is useful when files move from one sub-/package to another, or when a package gets renamed.
==== 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 [[APKBUILD Reference#install|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:
:: {{Cmd|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:
:: <pre>http://downloads.sourceforge.net/$pkgname/$pkgname-$pkgver.tar.gz</pre>
:: (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:
:: <pre>http://oss.example.org/?get=software&ver=1.0</pre>
:: You must prepend 'saveas-' to the protocol and append '/software-1.0.tar.gz' (for instance) to the end of the URI, like so:
:: <pre>saveas-http://oss.example.org/?get=software&ver=1.0/software-1.0.tar.gz</pre>
:: 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.

:* 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

==== subpackages ====
: Subpackages built from this APKBUILD. abuild will parse this variable and try to find a subpackage split function. The split function must ''move'' files that do not belong in the main package, from ''$pkgdir'' to ''$subpkgdir''. Files and directories can also be ''copied'' from ''$startdir'' and ''$srcdir'' to ''$subpkgdir''.

: The split function can be specified in 1 of 3 different ways:
:# subpkgname:'''splitfunc'''
:# $pkgname-'''splitfunc'''
:# '''splitfunc'''
==== url ====
: The homepage for the package. This is to help users find upstream documentation and other information regarding the package.

= Functions =
{{Note|All functions should consider the current working directory as undefined, and should therefore use the [[APKBUILD Reference#abuild-defined_variables|abuild-defined directory variables]] to their advantage.}}

== abuild-defined functions ==
The following functions are provided by abuild and can be overridden:

==== fetch() ====
: Downloads remote sources listed in ''source'' to ''SRCDEST'' (''SRCDEST'' is configured in ''/etc/abuild.conf'') and creates symlinks in ''$srcdir''.
==== unpack() ====
: Unpacks .tgz, .tar.gz, .tar.bz2, .tar.lzma, .tar.xz, and .zip archives in ''$srcdir'' to ''$srcdir''.
==== dev() ====
: Subpackage function for the '''$pkgname-dev''' package. Without specifying a custom ''dev()'' function, abuild will call it's internal ''dev()'' function, which in turn calls ''default_dev()'', which will move ''"$pkgdir"/usr/include'', ''*.a'', ''*.la'' and similar files to ''$subpkgdir''.
==== doc() ====
: Subpackage function for the '''$pkgname-doc''' package. Without specifying a custom ''doc()'' function, abuild will call it's internal ''doc()'' function, which in turn calls ''default_doc()'', which will move ''"$pkgdir"/usr/share/doc'', ''"$pkgdir"/usr/share/man'' and similar to ''$subpkgdir''.

== User-defined functions ==
The following functions should be defined by the user:

==== prepare() ====
: '''''Optional''.''' Used for build preparation: patches, etc, should be applied here. This function is available for your convenience.
==== build() ====
: '''Required.''' This is the compilation stage. This function will be called as the current user (unless the ''package()'' function is missing - for compatibility reasons). If no compilation is needed, this function can contain a single line: '''''return 0'''''
==== package() ====
: '''Required.''' This is the packaging stage. Here, the built application and support files should be installed into '''$pkgdir'''. If this is a metapackage, this function can contain a single line: '''''mkdir -p "$pkgdir" && return 0'''''

{{Note|Building in fakeroot will reduce performance for parallel builds dramatically. It is for this reason that we split the build and package process into two separate functions.}}

= Examples =
The following APKBUILD examples will assist you in understanding how to create an APKBUILD.

== Subpackages Example ==
Consider the following APKBUILD snippet:
pkgname="foo"
subpackages="$pkgname-dev $pkgname-doc py-$pkgname:pysub libfoo"

It will ...
* create the following 5 packages:
# foo (main)
# foo-dev (sub)
# foo-doc (sub)
# py-foo (sub)
# libfoo (sub)

* using the following 5 package functions (respectively) to fill them with files:
# ''package()'': will be provided by the user (and can make use of the ''$pkgdir'' variable).
# ''dev()'': will be provided by abuild unless we override it, by providing our own ''dev()'' function (which can make use of the ''$subpkgdir'' variable).
# ''doc()'': will be provided by abuild unless we override it, by providing our own ''doc()'' function (which can make use of the ''$subpkgdir'' variable).
# ''pysub()'': will be provided by the user (and can make use of the ''$subpkgdir'' variable).
# ''libfoo()'': will be provided by the user (and can make use of the ''$subpkgdir'' variable).

== Simple APKBUILD ==
Simple APKBUILD with -doc subpackage, using abuild's default ''doc()'' function:
<pre>
# Maintainer: Natanael Copa <ncopa@alpinelinux.org>
pkgname=m4
pkgver=1.4.15
pkgrel=0
pkgdesc="GNU macro processor"
url="http://www.gnu.org/software/m4"
depends=
arch="all"
license="GPL"
subpackages="m4-doc"
source="ftp://ftp.gnu.org/gnu/m4/$pkgname-$pkgver.tar.gz
gnulib-uclibc.patch"

_builddir="$srcdir"/$pkgname-$pkgver
prepare() {
cd "$_builddir"
patch -p1 -i "$srcdir"/gnulib-uclibc.patch
}

build() {
cd "$_builddir"
./configure --prefix=/usr
make
}

package() {
cd "$_builddir"
make install DESTDIR="$pkgdir"
}

md5sums="5649a2e593b6c639deae9e72ede777dd m4-1.4.15.tar.gz
20a7dedec0e9e0ee7107e33e798ffdbe gnulib-uclibc.patch"
</pre>

== APKBUILD with Multiple Subpackages ==
A more complex APKBUILD with -doc, -dev and python subpackages:
<pre>
# Contributor: Carlo Landmeter <clandmeter at gmail>
# Maintainer: Carlo Landmeter <clandmeter at gmail>
pkgname=libxml2
pkgver=2.7.8
pkgrel=0
pkgdesc="XML parsing library, version 2"
url="http://www.xmlsoft.org/"
arch="all"
license="MIT"
depends=
depends_dev="zlib-dev python-dev"
makedepends="zlib-dev python-dev"
subpackages="$pkgname-doc $pkgname-dev py-$pkgname:py $pkgname-utils"
source="ftp://ftp.xmlsoft.org/${pkgname}/${pkgname}-${pkgver}.tar.gz
largefile64.patch"

options="!strip"

_builddir="$srcdir/$pkgname-$pkgver"
prepare() {
cd "$_builddir"
for _i in "$srcdir"/*.patch; do
patch -p1 -i "$_i"
done
}

build() {
cd "$_builddir"
./configure --prefix=/usr \
--sysconfdir=/etc \
--mandir=/usr/share/man \
--infodir=/usr/share/info
make
}

package() {
cd "$_builddir"
make -j1 DESTDIR="$pkgdir" install
install -Dm644 COPYING "$pkgdir"/usr/share/licenses/$pkgname/COPYING
}

py() {
cd "$_builddir"
pkgdesc="$pkgname python bindings"
install -d "$subpkgdir"/usr/lib
mv "$pkgdir"/usr/lib/python* "$subpkgdir"/usr/lib/
}

utils() {
pkgdesc="XML utilities"
replaces="libxml2"
mkdir -p "$subpkgdir"/usr
mv "$pkgdir"/usr/bin "$subpkgdir"/usr/
}

md5sums="8127a65e8c3b08856093099b52599c86 libxml2-2.7.8.tar.gz
5ad4915665608ebfa5b89f7908467a72 largefile64.patch"
</pre>

APKBUILD Reference

2011-01-17T08:50:10Z

Mattx86: /* Variables */

APKBUILDs are the scripts that are created in order to build Alpine packages using the [[abuild]] tool.

This page is intended to serve as a reference for creating APKBUILDs; if this is your first time creating a package for Alpine Linux, please see [[Creating an Alpine package]].

= Legend =
The following notes will assist you in understanding this document.

In description text:
* If a variable is not prefixed with a ''$'', it will be represented by italics (i.e., ''srcdir'' ).
* Functions will also be represented by italics, but will also end with a pair of parentheses (i.e., ''build()'' ).
* Shell commands will be represented by italics and bold type (i.e., '''''abuild checksum''''').

= Variables =
{{Note|Variables that contain a path (e.g. ''$srcdir'' and ''$pkgdir'') should always be quoted using double quotes (i.e., ''"$srcdir"''). This is done to prevent things from breaking, should the user have the APKBUILD in a directory path that contains spaces.}}
{{Note|All arbitrary variable and function names should be prefixed with an underscore character ( _ ) to avoid name clashes with the internals of abuild (i.e., ''_builddir'').}}

== abuild-defined variables ==
The following variables are defined by abuild:

==== startdir ====
: The directory where the APKBUILD script is.
==== srcdir ====
: The directory where sources, from the ''source'' variable, are downloaded to and unpacked to.
==== pkgdir ====
: This directory should contain the files for the main package. For example, a normal [http://en.wikipedia.org/wiki/GNU_build_system autotools] package would have '''''make DESTDIR="$pkgdir" install''''' in the ''package()'' function.
==== subpkgdir ====
: This directory should contain the files for a subpackage. This variable should only be used from subpackage functions.

== User-defined variables ==
The following variables should be defined by the user:
==== arch ====
: Package architecture(s) to build for. Can be one of: '''x86, x86_64, all''', or '''noarch''', where '''all''' means all architectures, and '''noarch''' means it's architecture-independent (e.g., a pure-python package).
: {{Tip|To determine if your APKBUILD can use '''noarch''': First specify '''all''' and then build the package by executing '''''abuild -r'''''. Watch the output towards the end for warnings saying that '''noarch''' can be used. If the main package and all subpackages, if you have any subpackages, give a warning saying that '''noarch''' can be used, then you can use '''noarch'''.}}
==== depends ====
: Run-time dependency package(s) that are not shared-object dependencies. Shared objects dependencies are auto-detected and should not be specified here.
==== depends_dev ====
: Run-time dependency package(s) for the '''$pkgname-dev''' subpackage.
==== install ====
: There are 6 different types of install scripts. Install scripts are named '''$pkgname.action''', where '''action''' can be: '''pre-install, post-install, pre-upgrade, post-upgrade, pre-deinstall''', or '''post-deinstall'''. For example, if ''pkgname'' is set to '''mypackage''' and ''install'' is set to '''$pkgname.post-install''', then a script named '''mypackage.post-install''' must exist along-side the APKBUILD.

: First, a few notes regarding install scripts:
<blockquote>{{Note|When using install scripts, ''$install'' should be included in ''source'' so that checksums can be generated and used for the install scripts specified in ''install''. For example:
<pre>
install="$pkgname.pre-install $pkgname.post-install"
source="http://....
$install"
</pre>}}
{{Note|Always use <code>/bin/sh</code> for the command-line interpreter on the [http://en.wikipedia.org/wiki/Shebang_%28Unix%29 shebang line] of your install scripts.}}</blockquote>

The following are the different types of install scripts in detail:

===== $pkgname.pre-install =====
: This script is executed ''before'' the package is installed. Typical use is when the package needs a user/group to be created. For example:
<blockquote><pre>
#!/bin/sh
adduser -H -s /bin/false -D clamav 2>/dev/null
exit 0
</pre>
{{Note|If the script exits with a failure (e.g., if the user already exists), the package will not be installed and <code>apk</code> will exit with failure, hence the '''''exit 0''''' at the end.}}</blockquote>

===== $pkgname.post-install =====
: This script is executed ''after'' the package is installed.

===== $pkgname.pre-upgrade =====
: This script is executed ''before upgrading'' the package.

===== $pkgname.post-upgrade =====
: This script is executed ''after upgrading'' the package.

===== $pkgname.pre-deinstall =====
: This script is executed ''before uninstalling'' the package.
: {{Note|If the script exits with failure, <code>apk</code> will not uninstall the package.}}

===== $pkgname.post-deinstall =====
: This script is executed ''after uninstalling'' the package.

==== license ====
: License(s) for the package.
==== makedepends ====
: Build-time dependency package(s).
==== md5sums ====
: Checksums for the files/URLs listed in ''source''. The checksums are normally generated and updated by executing '''''abuild checksum''''' and should be the last item in the APKBUILD.
==== options ====
: Build-time options for the package. Can be: '''!strip''' - to avoid stripping symbols from binaries.
==== pkgdesc ====
: A brief, one-line description of what the package does.

: Here's an example from the OpenSSH client package:
: <pre>pkgdesc="Port of OpenBSD's free SSH release - client"</pre>
==== pkggroups ====
: System group(s) to be created during build-time. System group(s) should also be created in the '''[[APKBUILD Reference#.24pkgname.pre-install|$pkgname.pre-install]]''' script, so that the system group(s) are also created prior to package installation for run-time use.
==== pkgname ====
: The name of the package. All letters should be lowercase.
: {{Tip|When creating an APKBUILD of a module or library for another package, we use some common package prefixes, such as: ''lua-'', ''perl-'', ''php-'', and ''py-''. Search aports for other common prefixes.}}
==== pkgrel ====
: Alpine package release number. Starts at 0 (zero). Always increment ''pkgrel'' when making updates to an aport; reset ''pkgrel'' to 0 (zero) when incrementing ''pkgver''.
==== pkgusers ====
: System user(s) to be created during build-time. System user(s) should also be created in the '''[[APKBUILD Reference#.24pkgname.pre-install|$pkgname.pre-install]]''' script, so that the system user(s) are also created prior to package installation for run-time use.
==== pkgver ====
: The version of the software being packaged.
==== replaces ====
: Package(s) that this package replaces. This package will "take over" files owned by packages listed in the ''replaces'' variable. This is useful when files move from one sub-/package to another, or when a package gets renamed.
==== 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 [[APKBUILD Reference#install|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:
:: {{Cmd|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:
:: <pre>http://downloads.sourceforge.net/$pkgname/$pkgname-$pkgver.tar.gz</pre>
:: (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:
:: <pre>http://oss.example.org/?get=software&ver=1.0</pre>
:: You must prepend 'saveas-' to the protocol and append '/software-1.0.tar.gz' (for instance) to the end of the URI, like so:
:: <pre>saveas-http://oss.example.org/?get=software&ver=1.0/software-1.0.tar.gz</pre>
:: 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.

:* 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

==== subpackages ====
: Subpackages built from this APKBUILD. abuild will parse this variable and try to find a subpackage split function. The split function must ''move'' files that do not belong in the main package, from ''$pkgdir'' to ''$subpkgdir''. Files and directories can also be ''copied'' from ''$startdir'' and ''$srcdir'' to ''$subpkgdir''.

: The split function can be specified in 1 of 3 different ways:
:# subpkgname:'''splitfunc'''
:# $pkgname-'''splitfunc'''
:# '''splitfunc'''
==== url ====
: The homepage for the package. This is to help users find upstream documentation and other information regarding the package.

= Functions =
{{Note|All functions should consider the current working directory as undefined, and should therefore use the [[APKBUILD Reference#abuild-defined_variables|abuild-defined directory variables]] to their advantage.}}

== abuild-defined functions ==
The following functions are provided by abuild and can be overridden:

==== fetch() ====
: Downloads remote sources listed in ''source'' to ''SRCDEST'' (''SRCDEST'' is configured in ''/etc/abuild.conf'') and creates symlinks in ''$srcdir''.
==== unpack() ====
: Unpacks .tgz, .tar.gz, .tar.bz2, .tar.lzma, .tar.xz, and .zip archives in ''$srcdir'' to ''$srcdir''.
==== dev() ====
: Subpackage function for the '''$pkgname-dev''' package. Without specifying a custom ''dev()'' function, abuild will call it's internal ''dev()'' function, which in turn calls ''default_dev()'', which will move ''"$pkgdir"/usr/include'', ''*.a'', ''*.la'' and similar files to ''$subpkgdir''.
==== doc() ====
: Subpackage function for the '''$pkgname-doc''' package. Without specifying a custom ''doc()'' function, abuild will call it's internal ''doc()'' function, which in turn calls ''default_doc()'', which will move ''"$pkgdir"/usr/share/doc'', ''"$pkgdir"/usr/share/man'' and similar to ''$subpkgdir''.

== User-defined functions ==
The following functions should be defined by the user:

==== prepare() ====
: '''''Optional''.''' Used for build preparation: patches, etc, should be applied here. This function is available for your convenience.
==== build() ====
: '''Required.''' This is the compilation stage. This function will be called as the current user (unless the ''package()'' function is missing - for compatibility reasons). If no compilation is needed, this function can contain a single line: '''''return 0'''''
==== package() ====
: '''Required.''' This is the packaging stage. Here, the built application and support files should be installed into '''$pkgdir'''. If this is a metapackage, this function can contain a single line: '''''mkdir -p "$pkgdir" && return 0'''''

{{Note|Building in fakeroot will reduce performance for parallel builds dramatically. It is for this reason that we split the build and package process into two separate functions.}}

= Examples =
The following APKBUILD examples will assist you in understanding how to create an APKBUILD.

== Subpackages Example ==
Consider the following APKBUILD snippet:
pkgname="foo"
subpackages="$pkgname-dev $pkgname-doc py-$pkgname:pysub libfoo"

It will ...
* create the following 5 packages:
# foo (main)
# foo-dev (sub)
# foo-doc (sub)
# py-foo (sub)
# libfoo (sub)

* using the following 5 package functions (respectively) to fill them with files:
# ''package()'': will be provided by the user (and can make use of the ''$pkgdir'' variable).
# ''dev()'': will be provided by abuild unless we override it, by providing our own ''dev()'' function (which can make use of the ''$subpkgdir'' variable).
# ''doc()'': will be provided by abuild unless we override it, by providing our own ''doc()'' function (which can make use of the ''$subpkgdir'' variable).
# ''pysub()'': will be provided by the user (and can make use of the ''$subpkgdir'' variable).
# ''libfoo()'': will be provided by the user (and can make use of the ''$subpkgdir'' variable).

== Simple APKBUILD ==
Simple APKBUILD with -doc subpackage, using abuild's default ''doc()'' function:
<pre>
# Maintainer: Natanael Copa <ncopa@alpinelinux.org>
pkgname=m4
pkgver=1.4.15
pkgrel=0
pkgdesc="GNU macro processor"
url="http://www.gnu.org/software/m4"
depends=
arch="all"
license="GPL"
subpackages="m4-doc"
source="ftp://ftp.gnu.org/gnu/m4/$pkgname-$pkgver.tar.gz
gnulib-uclibc.patch"

_builddir="$srcdir"/$pkgname-$pkgver
prepare() {
cd "$_builddir"
patch -p1 -i "$srcdir"/gnulib-uclibc.patch
}

build() {
cd "$_builddir"
./configure --prefix=/usr
make
}

package() {
cd "$_builddir"
make install DESTDIR="$pkgdir"
}

md5sums="5649a2e593b6c639deae9e72ede777dd m4-1.4.15.tar.gz
20a7dedec0e9e0ee7107e33e798ffdbe gnulib-uclibc.patch"
</pre>

== APKBUILD with Multiple Subpackages ==
A more complex APKBUILD with -doc, -dev and python subpackages:
<pre>
# Contributor: Carlo Landmeter <clandmeter at gmail>
# Maintainer: Carlo Landmeter <clandmeter at gmail>
pkgname=libxml2
pkgver=2.7.8
pkgrel=0
pkgdesc="XML parsing library, version 2"
url="http://www.xmlsoft.org/"
arch="all"
license="MIT"
depends=
depends_dev="zlib-dev python-dev"
makedepends="zlib-dev python-dev"
subpackages="$pkgname-doc $pkgname-dev py-$pkgname:py $pkgname-utils"
source="ftp://ftp.xmlsoft.org/${pkgname}/${pkgname}-${pkgver}.tar.gz
largefile64.patch"

options="!strip"

_builddir="$srcdir/$pkgname-$pkgver"
prepare() {
cd "$_builddir"
for _i in "$srcdir"/*.patch; do
patch -p1 -i "$_i"
done
}

build() {
cd "$_builddir"
./configure --prefix=/usr \
--sysconfdir=/etc \
--mandir=/usr/share/man \
--infodir=/usr/share/info
make
}

package() {
cd "$_builddir"
make -j1 DESTDIR="$pkgdir" install
install -Dm644 COPYING "$pkgdir"/usr/share/licenses/$pkgname/COPYING
}

py() {
cd "$_builddir"
pkgdesc="$pkgname python bindings"
install -d "$subpkgdir"/usr/lib
mv "$pkgdir"/usr/lib/python* "$subpkgdir"/usr/lib/
}

utils() {
pkgdesc="XML utilities"
replaces="libxml2"
mkdir -p "$subpkgdir"/usr
mv "$pkgdir"/usr/bin "$subpkgdir"/usr/
}

md5sums="8127a65e8c3b08856093099b52599c86 libxml2-2.7.8.tar.gz
5ad4915665608ebfa5b89f7908467a72 largefile64.patch"
</pre>

APKBUILD Reference

2011-01-17T06:16:43Z

Mattx86:

APKBUILDs are the scripts that are created in order to build Alpine packages using the [[abuild]] tool.

This page is intended to serve as a reference for creating APKBUILDs; if this is your first time creating a package for Alpine Linux, please see [[Creating an Alpine package]].

= Legend =
The following notes will assist you in understanding this document.

In description text:
* If a variable is not prefixed with a ''$'', it will be represented by italics (i.e., ''srcdir'' ).
* Functions will also be represented by italics, but will also end with a pair of parentheses (i.e., ''build()'' ).
* Shell commands will be represented by italics and bold type (i.e., '''''abuild checksum''''').

= Variables =
{{Note|Variables that contain a path (e.g. ''$srcdir'' and ''$pkgdir'') should always be quoted using double quotes (i.e., ''"$srcdir"''). This is done to prevent things from breaking, should the user have the APKBUILD in a directory path that contains spaces.}}
{{Tip|All arbitrary variable and function names should be prefixed with an underscore character ( _ ) to avoid name clashes with the internals of abuild (i.e., ''_builddir'').}}

== abuild-defined variables ==
The following variables are defined by abuild:

==== startdir ====
: The directory where the APKBUILD script is.
==== srcdir ====
: The directory where sources, from the ''source'' variable, are downloaded to and unpacked to.
==== pkgdir ====
: This directory should contain the files for the main package. For example, a normal [http://en.wikipedia.org/wiki/GNU_build_system autotools] package would have '''''make DESTDIR="$pkgdir" install''''' in the ''package()'' function.
==== subpkgdir ====
: This directory should contain the files for a subpackage. This variable should only be used from subpackage functions.

== User-defined variables ==
The following variables should be defined by the user:
==== arch ====
: Package architecture(s) to build for. Can be one of: '''x86, x86_64, all''', or '''noarch''', where '''all''' means all architectures, and '''noarch''' means it's architecture-independent (e.g., a pure-python package).
: {{Tip|To determine if your APKBUILD can use '''noarch''': First specify '''all''' and then build the package by executing '''''abuild -r'''''. Watch the output towards the end for warnings saying that '''noarch''' can be used. If the main package and all subpackages, if you have any subpackages, give a warning saying that '''noarch''' can be used, then you can use '''noarch'''.}}
==== depends ====
: Run-time dependency package(s) that are not shared-object dependencies. Shared objects dependencies are auto-detected and should not be specified here.
==== depends_dev ====
: Run-time dependency package(s) for the '''$pkgname-dev''' subpackage.
==== install ====
: There are 6 different types of install scripts. Install scripts are named '''$pkgname.action''', where '''action''' can be: '''pre-install, post-install, pre-upgrade, post-upgrade, pre-deinstall''', or '''post-deinstall'''. For example, if ''pkgname'' is set to '''mypackage''' and ''install'' is set to '''$pkgname.post-install''', then a script named '''mypackage.post-install''' must exist along-side the APKBUILD.

: First, a few notes regarding install scripts:
<blockquote>{{Note|When using install scripts, ''$install'' should be included in ''source'' so that checksums can be generated and used for the install scripts specified in ''install''. For example:
<pre>
install="$pkgname.pre-install $pkgname.post-install"
source="http://....
$install"
</pre>}}
{{Note|Always use <code>/bin/sh</code> for the command-line interpreter on the [http://en.wikipedia.org/wiki/Shebang_%28Unix%29 shebang line] of your install scripts.}}</blockquote>

The following are the different types of install scripts in detail:

===== $pkgname.pre-install =====
: This script is executed ''before'' the package is installed. Typical use is when the package needs a user/group to be created. For example:
<blockquote><pre>
#!/bin/sh
adduser -H -s /bin/false -D clamav 2>/dev/null
exit 0
</pre>
{{Note|If the script exits with a failure (e.g., if the user already exists), the package will not be installed and <code>apk</code> will exit with failure, hence the '''''exit 0''''' at the end.}}</blockquote>

===== $pkgname.post-install =====
: This script is executed ''after'' the package is installed.

===== $pkgname.pre-upgrade =====
: This script is executed ''before upgrading'' the package.

===== $pkgname.post-upgrade =====
: This script is executed ''after upgrading'' the package.

===== $pkgname.pre-deinstall =====
: This script is executed ''before uninstalling'' the package.
: {{Note|If the script exits with failure, <code>apk</code> will not uninstall the package.}}

===== $pkgname.post-deinstall =====
: This script is executed ''after uninstalling'' the package.

==== license ====
: License(s) for the package.
==== makedepends ====
: Build-time dependency package(s).
==== md5sums ====
: Checksums for the files/URLs listed in ''source''. The checksums are normally generated and updated by executing '''''abuild checksum''''' and should be the last item in the APKBUILD.
==== options ====
: Build-time options for the package. Can be: '''!strip''' - to avoid stripping symbols from binaries.
==== pkgdesc ====
: A brief, one-line description of what the package does.

: Here's an example from the OpenSSH client package:
: <pre>pkgdesc="Port of OpenBSD's free SSH release - client"</pre>
==== pkggroups ====
: System group(s) to be created during build-time. System group(s) should also be created in the '''[[APKBUILD Reference#.24pkgname.pre-install|$pkgname.pre-install]]''' script, so that the system group(s) are also created prior to package installation for run-time use.
==== pkgname ====
: The name of the package. All letters should be lowercase.
: {{Tip|When creating an APKBUILD of a module or library for another package, we use some common package prefixes, such as: ''lua-'', ''perl-'', ''php-'', and ''py-''. Search aports for other common prefixes.}}
==== pkgrel ====
: Alpine package release number. Starts at 0 (zero). Always increment ''pkgrel'' when making updates to an aport; reset ''pkgrel'' to 0 (zero) when incrementing ''pkgver''.
==== pkgusers ====
: System user(s) to be created during build-time. System user(s) should also be created in the '''[[APKBUILD Reference#.24pkgname.pre-install|$pkgname.pre-install]]''' script, so that the system user(s) are also created prior to package installation for run-time use.
==== pkgver ====
: The version of the software being packaged.
==== replaces ====
: Package(s) that this package replaces. This package will "take over" files owned by packages listed in the ''replaces'' variable. This is useful when files move from one sub-/package to another, or when a package gets renamed.
==== 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 [[APKBUILD Reference#install|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:
:: {{Cmd|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:
:: <pre>http://downloads.sourceforge.net/$pkgname/$pkgname-$pkgver.tar.gz</pre>
:: (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:
:: <pre>http://oss.example.org/?get=software&ver=1.0</pre>
:: You must prepend 'saveas-' to the protocol and append '/software-1.0.tar.gz' (for instance) to the end of the URI, like so:
:: <pre>saveas-http://oss.example.org/?get=software&ver=1.0/software-1.0.tar.gz</pre>
:: 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.

:* 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

==== subpackages ====
: Subpackages built from this APKBUILD. abuild will parse this variable and try to find a subpackage split function. The split function must ''move'' files that do not belong in the main package, from ''$pkgdir'' to ''$subpkgdir''. Files and directories can also be ''copied'' from ''$startdir'' and ''$srcdir'' to ''$subpkgdir''.

: The split function can be specified in 1 of 3 different ways:
:# subpkgname:'''splitfunc'''
:# $pkgname-'''splitfunc'''
:# '''splitfunc'''
==== url ====
: The homepage for the package. This is to help users find upstream documentation and other information regarding the package.

= Functions =
{{Note|All functions should consider the current working directory as undefined, and should therefore use the [[APKBUILD Reference#abuild-defined_variables|abuild-defined directory variables]] to their advantage.}}

== abuild-defined functions ==
The following functions are provided by abuild and can be overridden:

==== fetch() ====
: Downloads remote sources listed in ''source'' to ''SRCDEST'' (''SRCDEST'' is configured in ''/etc/abuild.conf'') and creates symlinks in ''$srcdir''.
==== unpack() ====
: Unpacks .tgz, .tar.gz, .tar.bz2, .tar.lzma, .tar.xz, and .zip archives in ''$srcdir'' to ''$srcdir''.
==== dev() ====
: Subpackage function for the '''$pkgname-dev''' package. Without specifying a custom ''dev()'' function, abuild will call it's internal ''dev()'' function, which in turn calls ''default_dev()'', which will move ''"$pkgdir"/usr/include'', ''*.a'', ''*.la'' and similar files to ''$subpkgdir''.
==== doc() ====
: Subpackage function for the '''$pkgname-doc''' package. Without specifying a custom ''doc()'' function, abuild will call it's internal ''doc()'' function, which in turn calls ''default_doc()'', which will move ''"$pkgdir"/usr/share/doc'', ''"$pkgdir"/usr/share/man'' and similar to ''$subpkgdir''.

== User-defined functions ==
The following functions should be defined by the user:

==== prepare() ====
: '''''Optional''.''' Used for build preparation: patches, etc, should be applied here. This function is available for your convenience.
==== build() ====
: '''Required.''' This is the compilation stage. This function will be called as the current user (unless the ''package()'' function is missing - for compatibility reasons). If no compilation is needed, this function can contain a single line: '''''return 0'''''
==== package() ====
: '''Required.''' This is the packaging stage. Here, the built application and support files should be installed into '''$pkgdir'''. If this is a metapackage, this function can contain a single line: '''''mkdir -p "$pkgdir" && return 0'''''

{{Note|Building in fakeroot will reduce performance for parallel builds dramatically. It is for this reason that we split the build and package process into two separate functions.}}

= Examples =
The following APKBUILD examples will assist you in understanding how to create an APKBUILD.

== Subpackages Example ==
Consider the following APKBUILD snippet:
pkgname="foo"
subpackages="$pkgname-dev $pkgname-doc py-$pkgname:pysub libfoo"

It will ...
* create the following 5 packages:
# foo (main)
# foo-dev (sub)
# foo-doc (sub)
# py-foo (sub)
# libfoo (sub)

* using the following 5 package functions (respectively) to fill them with files:
# ''package()'': will be provided by the user (and can make use of the ''$pkgdir'' variable).
# ''dev()'': will be provided by abuild unless we override it, by providing our own ''dev()'' function (which can make use of the ''$subpkgdir'' variable).
# ''doc()'': will be provided by abuild unless we override it, by providing our own ''doc()'' function (which can make use of the ''$subpkgdir'' variable).
# ''pysub()'': will be provided by the user (and can make use of the ''$subpkgdir'' variable).
# ''libfoo()'': will be provided by the user (and can make use of the ''$subpkgdir'' variable).

== Simple APKBUILD ==
Simple APKBUILD with -doc subpackage, using abuild's default ''doc()'' function:
<pre>
# Maintainer: Natanael Copa <ncopa@alpinelinux.org>
pkgname=m4
pkgver=1.4.15
pkgrel=0
pkgdesc="GNU macro processor"
url="http://www.gnu.org/software/m4"
depends=
arch="all"
license="GPL"
subpackages="m4-doc"
source="ftp://ftp.gnu.org/gnu/m4/$pkgname-$pkgver.tar.gz
gnulib-uclibc.patch"

_builddir="$srcdir"/$pkgname-$pkgver
prepare() {
cd "$_builddir"
patch -p1 -i "$srcdir"/gnulib-uclibc.patch
}

build() {
cd "$_builddir"
./configure --prefix=/usr
make
}

package() {
cd "$_builddir"
make install DESTDIR="$pkgdir"
}

md5sums="5649a2e593b6c639deae9e72ede777dd m4-1.4.15.tar.gz
20a7dedec0e9e0ee7107e33e798ffdbe gnulib-uclibc.patch"
</pre>

== APKBUILD with Multiple Subpackages ==
A more complex APKBUILD with -doc, -dev and python subpackages:
<pre>
# Contributor: Carlo Landmeter <clandmeter at gmail>
# Maintainer: Carlo Landmeter <clandmeter at gmail>
pkgname=libxml2
pkgver=2.7.8
pkgrel=0
pkgdesc="XML parsing library, version 2"
url="http://www.xmlsoft.org/"
arch="all"
license="MIT"
depends=
depends_dev="zlib-dev python-dev"
makedepends="zlib-dev python-dev"
subpackages="$pkgname-doc $pkgname-dev py-$pkgname:py $pkgname-utils"
source="ftp://ftp.xmlsoft.org/${pkgname}/${pkgname}-${pkgver}.tar.gz
largefile64.patch"

options="!strip"

_builddir="$srcdir/$pkgname-$pkgver"
prepare() {
cd "$_builddir"
for _i in "$srcdir"/*.patch; do
patch -p1 -i "$_i"
done
}

build() {
cd "$_builddir"
./configure --prefix=/usr \
--sysconfdir=/etc \
--mandir=/usr/share/man \
--infodir=/usr/share/info
make
}

package() {
cd "$_builddir"
make -j1 DESTDIR="$pkgdir" install
install -Dm644 COPYING "$pkgdir"/usr/share/licenses/$pkgname/COPYING
}

py() {
cd "$_builddir"
pkgdesc="$pkgname python bindings"
install -d "$subpkgdir"/usr/lib
mv "$pkgdir"/usr/lib/python* "$subpkgdir"/usr/lib/
}

utils() {
pkgdesc="XML utilities"
replaces="libxml2"
mkdir -p "$subpkgdir"/usr
mv "$pkgdir"/usr/bin "$subpkgdir"/usr/
}

md5sums="8127a65e8c3b08856093099b52599c86 libxml2-2.7.8.tar.gz
5ad4915665608ebfa5b89f7908467a72 largefile64.patch"
</pre>

APKBUILD Reference

2011-01-17T06:13:04Z

Mattx86: /* install */

APKBUILDs are the scripts that are created in order to build Alpine packages using the [[abuild]] tool.

This page is intended to serve as a quick reference for creating APKBUILDs; if this is your first time creating a package for Alpine Linux, please see [[Creating an Alpine package]].

= Legend =
The following notes will assist you in understanding this document.

In description text:
* If a variable is not prefixed with a ''$'', it will be represented by italics (i.e., ''srcdir'' ).
* Functions will also be represented by italics, but will also end with a pair of parentheses (i.e., ''build()'' ).
* Shell commands will be represented by italics and bold type (i.e., '''''abuild checksum''''').

= Variables =
{{Note|Variables that contain a path (e.g. ''$srcdir'' and ''$pkgdir'') should always be quoted using double quotes (i.e., ''"$srcdir"''). This is done to prevent things from breaking, should the user have the APKBUILD in a directory path that contains spaces.}}
{{Tip|All arbitrary variable and function names should be prefixed with an underscore character ( _ ) to avoid name clashes with the internals of abuild (i.e., ''_builddir'').}}

== abuild-defined variables ==
The following variables are defined by abuild:

==== startdir ====
: The directory where the APKBUILD script is.
==== srcdir ====
: The directory where sources, from the ''source'' variable, are downloaded to and unpacked to.
==== pkgdir ====
: This directory should contain the files for the main package. For example, a normal [http://en.wikipedia.org/wiki/GNU_build_system autotools] package would have '''''make DESTDIR="$pkgdir" install''''' in the ''package()'' function.
==== subpkgdir ====
: This directory should contain the files for a subpackage. This variable should only be used from subpackage functions.

== User-defined variables ==
The following variables should be defined by the user:
==== arch ====
: Package architecture(s) to build for. Can be one of: '''x86, x86_64, all''', or '''noarch''', where '''all''' means all architectures, and '''noarch''' means it's architecture-independent (e.g., a pure-python package).
: {{Tip|To determine if your APKBUILD can use '''noarch''': First specify '''all''' and then build the package by executing '''''abuild -r'''''. Watch the output towards the end for warnings saying that '''noarch''' can be used. If the main package and all subpackages, if you have any subpackages, give a warning saying that '''noarch''' can be used, then you can use '''noarch'''.}}
==== depends ====
: Run-time dependency package(s) that are not shared-object dependencies. Shared objects dependencies are auto-detected and should not be specified here.
==== depends_dev ====
: Run-time dependency package(s) for the '''$pkgname-dev''' subpackage.
==== install ====
: There are 6 different types of install scripts. Install scripts are named '''$pkgname.action''', where '''action''' can be: '''pre-install, post-install, pre-upgrade, post-upgrade, pre-deinstall''', or '''post-deinstall'''. For example, if ''pkgname'' is set to '''mypackage''' and ''install'' is set to '''$pkgname.post-install''', then a script named '''mypackage.post-install''' must exist along-side the APKBUILD.

: First, a few notes regarding install scripts:
<blockquote>{{Note|When using install scripts, ''$install'' should be included in ''source'' so that checksums can be generated and used for the install scripts specified in ''install''. For example:
<pre>
install="$pkgname.pre-install $pkgname.post-install"
source="http://....
$install"
</pre>}}
{{Note|Always use <code>/bin/sh</code> for the command-line interpreter on the [http://en.wikipedia.org/wiki/Shebang_%28Unix%29 shebang line] of your install scripts.}}</blockquote>

The following are the different types of install scripts in detail:

===== $pkgname.pre-install =====
: This script is executed ''before'' the package is installed. Typical use is when the package needs a user/group to be created. For example:
<blockquote><pre>
#!/bin/sh
adduser -H -s /bin/false -D clamav 2>/dev/null
exit 0
</pre>
{{Note|If the script exits with a failure (e.g., if the user already exists), the package will not be installed and <code>apk</code> will exit with failure, hence the '''''exit 0''''' at the end.}}</blockquote>

===== $pkgname.post-install =====
: This script is executed ''after'' the package is installed.

===== $pkgname.pre-upgrade =====
: This script is executed ''before upgrading'' the package.

===== $pkgname.post-upgrade =====
: This script is executed ''after upgrading'' the package.

===== $pkgname.pre-deinstall =====
: This script is executed ''before uninstalling'' the package.
: {{Note|If the script exits with failure, <code>apk</code> will not uninstall the package.}}

===== $pkgname.post-deinstall =====
: This script is executed ''after uninstalling'' the package.

==== license ====
: License(s) for the package.
==== makedepends ====
: Build-time dependency package(s).
==== md5sums ====
: Checksums for the files/URLs listed in ''source''. The checksums are normally generated and updated by executing '''''abuild checksum''''' and should be the last item in the APKBUILD.
==== options ====
: Build-time options for the package. Can be: '''!strip''' - to avoid stripping symbols from binaries.
==== pkgdesc ====
: A brief, one-line description of what the package does.

: Here's an example from the OpenSSH client package:
: <pre>pkgdesc="Port of OpenBSD's free SSH release - client"</pre>
==== pkggroups ====
: System group(s) to be created during build-time. System group(s) should also be created in the '''[[APKBUILD Reference#.24pkgname.pre-install|$pkgname.pre-install]]''' script, so that the system group(s) are also created prior to package installation for run-time use.
==== pkgname ====
: The name of the package. All letters should be lowercase.
: {{Tip|When creating an APKBUILD of a module or library for another package, we use some common package prefixes, such as: ''lua-'', ''perl-'', ''php-'', and ''py-''. Search aports for other common prefixes.}}
==== pkgrel ====
: Alpine package release number. Starts at 0 (zero). Always increment ''pkgrel'' when making updates to an aport; reset ''pkgrel'' to 0 (zero) when incrementing ''pkgver''.
==== pkgusers ====
: System user(s) to be created during build-time. System user(s) should also be created in the '''[[APKBUILD Reference#.24pkgname.pre-install|$pkgname.pre-install]]''' script, so that the system user(s) are also created prior to package installation for run-time use.
==== pkgver ====
: The version of the software being packaged.
==== replaces ====
: Package(s) that this package replaces. This package will "take over" files owned by packages listed in the ''replaces'' variable. This is useful when files move from one sub-/package to another, or when a package gets renamed.
==== 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 [[APKBUILD Reference#install|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:
:: {{Cmd|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:
:: <pre>http://downloads.sourceforge.net/$pkgname/$pkgname-$pkgver.tar.gz</pre>
:: (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:
:: <pre>http://oss.example.org/?get=software&ver=1.0</pre>
:: You must prepend 'saveas-' to the protocol and append '/software-1.0.tar.gz' (for instance) to the end of the URI, like so:
:: <pre>saveas-http://oss.example.org/?get=software&ver=1.0/software-1.0.tar.gz</pre>
:: 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.

:* 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

==== subpackages ====
: Subpackages built from this APKBUILD. abuild will parse this variable and try to find a subpackage split function. The split function must ''move'' files that do not belong in the main package, from ''$pkgdir'' to ''$subpkgdir''. Files and directories can also be ''copied'' from ''$startdir'' and ''$srcdir'' to ''$subpkgdir''.

: The split function can be specified in 1 of 3 different ways:
:# subpkgname:'''splitfunc'''
:# $pkgname-'''splitfunc'''
:# '''splitfunc'''
==== url ====
: The homepage for the package. This is to help users find upstream documentation and other information regarding the package.

= Functions =
{{Note|All functions should consider the current working directory as undefined, and should therefore use the [[APKBUILD Reference#abuild-defined_variables|abuild-defined directory variables]] to their advantage.}}

== abuild-defined functions ==
The following functions are provided by abuild and can be overridden:

==== fetch() ====
: Downloads remote sources listed in ''source'' to ''SRCDEST'' (''SRCDEST'' is configured in ''/etc/abuild.conf'') and creates symlinks in ''$srcdir''.
==== unpack() ====
: Unpacks .tgz, .tar.gz, .tar.bz2, .tar.lzma, .tar.xz, and .zip archives in ''$srcdir'' to ''$srcdir''.
==== dev() ====
: Subpackage function for the '''$pkgname-dev''' package. Without specifying a custom ''dev()'' function, abuild will call it's internal ''dev()'' function, which in turn calls ''default_dev()'', which will move ''"$pkgdir"/usr/include'', ''*.a'', ''*.la'' and similar files to ''$subpkgdir''.
==== doc() ====
: Subpackage function for the '''$pkgname-doc''' package. Without specifying a custom ''doc()'' function, abuild will call it's internal ''doc()'' function, which in turn calls ''default_doc()'', which will move ''"$pkgdir"/usr/share/doc'', ''"$pkgdir"/usr/share/man'' and similar to ''$subpkgdir''.

== User-defined functions ==
The following functions should be defined by the user:

==== prepare() ====
: '''''Optional''.''' Used for build preparation: patches, etc, should be applied here. This function is available for your convenience.
==== build() ====
: '''Required.''' This is the compilation stage. This function will be called as the current user (unless the ''package()'' function is missing - for compatibility reasons). If no compilation is needed, this function can contain a single line: '''''return 0'''''
==== package() ====
: '''Required.''' This is the packaging stage. Here, the built application and support files should be installed into '''$pkgdir'''. If this is a metapackage, this function can contain a single line: '''''mkdir -p "$pkgdir" && return 0'''''

{{Note|Building in fakeroot will reduce performance for parallel builds dramatically. It is for this reason that we split the build and package process into two separate functions.}}

= Examples =
The following APKBUILD examples will assist you in understanding how to create an APKBUILD.

== Subpackages Example ==
Consider the following APKBUILD snippet:
pkgname="foo"
subpackages="$pkgname-dev $pkgname-doc py-$pkgname:pysub libfoo"

It will ...
* create the following 5 packages:
# foo (main)
# foo-dev (sub)
# foo-doc (sub)
# py-foo (sub)
# libfoo (sub)

* using the following 5 package functions (respectively) to fill them with files:
# ''package()'': will be provided by the user (and can make use of the ''$pkgdir'' variable).
# ''dev()'': will be provided by abuild unless we override it, by providing our own ''dev()'' function (which can make use of the ''$subpkgdir'' variable).
# ''doc()'': will be provided by abuild unless we override it, by providing our own ''doc()'' function (which can make use of the ''$subpkgdir'' variable).
# ''pysub()'': will be provided by the user (and can make use of the ''$subpkgdir'' variable).
# ''libfoo()'': will be provided by the user (and can make use of the ''$subpkgdir'' variable).

== Simple APKBUILD ==
Simple APKBUILD with -doc subpackage, using abuild's default ''doc()'' function:
<pre>
# Maintainer: Natanael Copa <ncopa@alpinelinux.org>
pkgname=m4
pkgver=1.4.15
pkgrel=0
pkgdesc="GNU macro processor"
url="http://www.gnu.org/software/m4"
depends=
arch="all"
license="GPL"
subpackages="m4-doc"
source="ftp://ftp.gnu.org/gnu/m4/$pkgname-$pkgver.tar.gz
gnulib-uclibc.patch"

_builddir="$srcdir"/$pkgname-$pkgver
prepare() {
cd "$_builddir"
patch -p1 -i "$srcdir"/gnulib-uclibc.patch
}

build() {
cd "$_builddir"
./configure --prefix=/usr
make
}

package() {
cd "$_builddir"
make install DESTDIR="$pkgdir"
}

md5sums="5649a2e593b6c639deae9e72ede777dd m4-1.4.15.tar.gz
20a7dedec0e9e0ee7107e33e798ffdbe gnulib-uclibc.patch"
</pre>

== APKBUILD with Multiple Subpackages ==
A more complex APKBUILD with -doc, -dev and python subpackages:
<pre>
# Contributor: Carlo Landmeter <clandmeter at gmail>
# Maintainer: Carlo Landmeter <clandmeter at gmail>
pkgname=libxml2
pkgver=2.7.8
pkgrel=0
pkgdesc="XML parsing library, version 2"
url="http://www.xmlsoft.org/"
arch="all"
license="MIT"
depends=
depends_dev="zlib-dev python-dev"
makedepends="zlib-dev python-dev"
subpackages="$pkgname-doc $pkgname-dev py-$pkgname:py $pkgname-utils"
source="ftp://ftp.xmlsoft.org/${pkgname}/${pkgname}-${pkgver}.tar.gz
largefile64.patch"

options="!strip"

_builddir="$srcdir/$pkgname-$pkgver"
prepare() {
cd "$_builddir"
for _i in "$srcdir"/*.patch; do
patch -p1 -i "$_i"
done
}

build() {
cd "$_builddir"
./configure --prefix=/usr \
--sysconfdir=/etc \
--mandir=/usr/share/man \
--infodir=/usr/share/info
make
}

package() {
cd "$_builddir"
make -j1 DESTDIR="$pkgdir" install
install -Dm644 COPYING "$pkgdir"/usr/share/licenses/$pkgname/COPYING
}

py() {
cd "$_builddir"
pkgdesc="$pkgname python bindings"
install -d "$subpkgdir"/usr/lib
mv "$pkgdir"/usr/lib/python* "$subpkgdir"/usr/lib/
}

utils() {
pkgdesc="XML utilities"
replaces="libxml2"
mkdir -p "$subpkgdir"/usr
mv "$pkgdir"/usr/bin "$subpkgdir"/usr/
}

md5sums="8127a65e8c3b08856093099b52599c86 libxml2-2.7.8.tar.gz
5ad4915665608ebfa5b89f7908467a72 largefile64.patch"
</pre>

APKBUILD Reference

2011-01-17T06:08:29Z

Mattx86: WIP: Aggregating important information from the "Creating an Alpine package" page

APKBUILDs are the scripts that are created in order to build Alpine packages using the [[abuild]] tool.

This page is intended to serve as a quick reference for creating APKBUILDs; if this is your first time creating a package for Alpine Linux, please see [[Creating an Alpine package]].

= Legend =
The following notes will assist you in understanding this document.

In description text:
* If a variable is not prefixed with a ''$'', it will be represented by italics (i.e., ''srcdir'' ).
* Functions will also be represented by italics, but will also end with a pair of parentheses (i.e., ''build()'' ).
* Shell commands will be represented by italics and bold type (i.e., '''''abuild checksum''''').

= Variables =
{{Note|Variables that contain a path (e.g. ''$srcdir'' and ''$pkgdir'') should always be quoted using double quotes (i.e., ''"$srcdir"''). This is done to prevent things from breaking, should the user have the APKBUILD in a directory path that contains spaces.}}
{{Tip|All arbitrary variable and function names should be prefixed with an underscore character ( _ ) to avoid name clashes with the internals of abuild (i.e., ''_builddir'').}}

== abuild-defined variables ==
The following variables are defined by abuild:

==== startdir ====
: The directory where the APKBUILD script is.
==== srcdir ====
: The directory where sources, from the ''source'' variable, are downloaded to and unpacked to.
==== pkgdir ====
: This directory should contain the files for the main package. For example, a normal [http://en.wikipedia.org/wiki/GNU_build_system autotools] package would have '''''make DESTDIR="$pkgdir" install''''' in the ''package()'' function.
==== subpkgdir ====
: This directory should contain the files for a subpackage. This variable should only be used from subpackage functions.

== User-defined variables ==
The following variables should be defined by the user:
==== arch ====
: Package architecture(s) to build for. Can be one of: '''x86, x86_64, all''', or '''noarch''', where '''all''' means all architectures, and '''noarch''' means it's architecture-independent (e.g., a pure-python package).
: {{Tip|To determine if your APKBUILD can use '''noarch''': First specify '''all''' and then build the package by executing '''''abuild -r'''''. Watch the output towards the end for warnings saying that '''noarch''' can be used. If the main package and all subpackages, if you have any subpackages, give a warning saying that '''noarch''' can be used, then you can use '''noarch'''.}}
==== depends ====
: Run-time dependency package(s) that are not shared-object dependencies. Shared objects dependencies are auto-detected and should not be specified here.
==== depends_dev ====
: Run-time dependency package(s) for the '''$pkgname-dev''' subpackage.
==== install ====
: There are 6 different types of install scripts. Install scripts are named '''$pkgname.action''', where '''action''' can be: '''pre-install, pre-upgrade, pre-deinstall, post-install, post-upgrade''', or '''post-deinstall'''. For example, if ''pkgname'' is set to '''mypackage''' and ''install'' is set to '''$pkgname.post-install''', then a script named '''mypackage.post-install''' must exist along-side the APKBUILD.

: First, a few notes regarding install scripts:
<blockquote>{{Note|When using install scripts, ''$install'' should be included in ''source'' so that checksums can be generated and used for the install scripts specified in ''install''. For example:
<pre>
install="$pkgname.pre-install $pkgname.post-install"
source="http://....
$install"
</pre>}}
{{Note|Always use <code>/bin/sh</code> for the command-line interpreter on the [http://en.wikipedia.org/wiki/Shebang_%28Unix%29 shebang line] of your install scripts.}}</blockquote>

The following are the different types of install scripts in detail:

===== $pkgname.pre-install =====
: This script is executed ''before'' the package is installed. Typical use is when the package needs a user/group to be created. For example:
<blockquote><pre>
#!/bin/sh
adduser -H -s /bin/false -D clamav 2>/dev/null
exit 0
</pre>
{{Note|If the script exits with a failure (e.g., if the user already exists), the package will not be installed and <code>apk</code> will exit with failure, hence the '''''exit 0''''' at the end.}}</blockquote>

===== $pkgname.post-install =====
: This script is executed ''after'' the package is installed.

===== $pkgname.pre-upgrade =====
: This script is executed ''before upgrading'' the package.

===== $pkgname.post-upgrade =====
: This script is executed ''after upgrading'' the package.

===== $pkgname.pre-deinstall =====
: This script is executed ''before uninstalling'' the package.
: {{Note|If the script exits with failure, <code>apk</code> will not uninstall the package.}}

===== $pkgname.post-deinstall =====
: This script is executed ''after uninstalling'' the package.

==== license ====
: License(s) for the package.
==== makedepends ====
: Build-time dependency package(s).
==== md5sums ====
: Checksums for the files/URLs listed in ''source''. The checksums are normally generated and updated by executing '''''abuild checksum''''' and should be the last item in the APKBUILD.
==== options ====
: Build-time options for the package. Can be: '''!strip''' - to avoid stripping symbols from binaries.
==== pkgdesc ====
: A brief, one-line description of what the package does.

: Here's an example from the OpenSSH client package:
: <pre>pkgdesc="Port of OpenBSD's free SSH release - client"</pre>
==== pkggroups ====
: System group(s) to be created during build-time. System group(s) should also be created in the '''[[APKBUILD Reference#.24pkgname.pre-install|$pkgname.pre-install]]''' script, so that the system group(s) are also created prior to package installation for run-time use.
==== pkgname ====
: The name of the package. All letters should be lowercase.
: {{Tip|When creating an APKBUILD of a module or library for another package, we use some common package prefixes, such as: ''lua-'', ''perl-'', ''php-'', and ''py-''. Search aports for other common prefixes.}}
==== pkgrel ====
: Alpine package release number. Starts at 0 (zero). Always increment ''pkgrel'' when making updates to an aport; reset ''pkgrel'' to 0 (zero) when incrementing ''pkgver''.
==== pkgusers ====
: System user(s) to be created during build-time. System user(s) should also be created in the '''[[APKBUILD Reference#.24pkgname.pre-install|$pkgname.pre-install]]''' script, so that the system user(s) are also created prior to package installation for run-time use.
==== pkgver ====
: The version of the software being packaged.
==== replaces ====
: Package(s) that this package replaces. This package will "take over" files owned by packages listed in the ''replaces'' variable. This is useful when files move from one sub-/package to another, or when a package gets renamed.
==== 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 [[APKBUILD Reference#install|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:
:: {{Cmd|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:
:: <pre>http://downloads.sourceforge.net/$pkgname/$pkgname-$pkgver.tar.gz</pre>
:: (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:
:: <pre>http://oss.example.org/?get=software&ver=1.0</pre>
:: You must prepend 'saveas-' to the protocol and append '/software-1.0.tar.gz' (for instance) to the end of the URI, like so:
:: <pre>saveas-http://oss.example.org/?get=software&ver=1.0/software-1.0.tar.gz</pre>
:: 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.

:* 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

==== subpackages ====
: Subpackages built from this APKBUILD. abuild will parse this variable and try to find a subpackage split function. The split function must ''move'' files that do not belong in the main package, from ''$pkgdir'' to ''$subpkgdir''. Files and directories can also be ''copied'' from ''$startdir'' and ''$srcdir'' to ''$subpkgdir''.

: The split function can be specified in 1 of 3 different ways:
:# subpkgname:'''splitfunc'''
:# $pkgname-'''splitfunc'''
:# '''splitfunc'''
==== url ====
: The homepage for the package. This is to help users find upstream documentation and other information regarding the package.

= Functions =
{{Note|All functions should consider the current working directory as undefined, and should therefore use the [[APKBUILD Reference#abuild-defined_variables|abuild-defined directory variables]] to their advantage.}}

== abuild-defined functions ==
The following functions are provided by abuild and can be overridden:

==== fetch() ====
: Downloads remote sources listed in ''source'' to ''SRCDEST'' (''SRCDEST'' is configured in ''/etc/abuild.conf'') and creates symlinks in ''$srcdir''.
==== unpack() ====
: Unpacks .tgz, .tar.gz, .tar.bz2, .tar.lzma, .tar.xz, and .zip archives in ''$srcdir'' to ''$srcdir''.
==== dev() ====
: Subpackage function for the '''$pkgname-dev''' package. Without specifying a custom ''dev()'' function, abuild will call it's internal ''dev()'' function, which in turn calls ''default_dev()'', which will move ''"$pkgdir"/usr/include'', ''*.a'', ''*.la'' and similar files to ''$subpkgdir''.
==== doc() ====
: Subpackage function for the '''$pkgname-doc''' package. Without specifying a custom ''doc()'' function, abuild will call it's internal ''doc()'' function, which in turn calls ''default_doc()'', which will move ''"$pkgdir"/usr/share/doc'', ''"$pkgdir"/usr/share/man'' and similar to ''$subpkgdir''.

== User-defined functions ==
The following functions should be defined by the user:

==== prepare() ====
: '''''Optional''.''' Used for build preparation: patches, etc, should be applied here. This function is available for your convenience.
==== build() ====
: '''Required.''' This is the compilation stage. This function will be called as the current user (unless the ''package()'' function is missing - for compatibility reasons). If no compilation is needed, this function can contain a single line: '''''return 0'''''
==== package() ====
: '''Required.''' This is the packaging stage. Here, the built application and support files should be installed into '''$pkgdir'''. If this is a metapackage, this function can contain a single line: '''''mkdir -p "$pkgdir" && return 0'''''

{{Note|Building in fakeroot will reduce performance for parallel builds dramatically. It is for this reason that we split the build and package process into two separate functions.}}

= Examples =
The following APKBUILD examples will assist you in understanding how to create an APKBUILD.

== Subpackages Example ==
Consider the following APKBUILD snippet:
pkgname="foo"
subpackages="$pkgname-dev $pkgname-doc py-$pkgname:pysub libfoo"

It will ...
* create the following 5 packages:
# foo (main)
# foo-dev (sub)
# foo-doc (sub)
# py-foo (sub)
# libfoo (sub)

* using the following 5 package functions (respectively) to fill them with files:
# ''package()'': will be provided by the user (and can make use of the ''$pkgdir'' variable).
# ''dev()'': will be provided by abuild unless we override it, by providing our own ''dev()'' function (which can make use of the ''$subpkgdir'' variable).
# ''doc()'': will be provided by abuild unless we override it, by providing our own ''doc()'' function (which can make use of the ''$subpkgdir'' variable).
# ''pysub()'': will be provided by the user (and can make use of the ''$subpkgdir'' variable).
# ''libfoo()'': will be provided by the user (and can make use of the ''$subpkgdir'' variable).

== Simple APKBUILD ==
Simple APKBUILD with -doc subpackage, using abuild's default ''doc()'' function:
<pre>
# Maintainer: Natanael Copa <ncopa@alpinelinux.org>
pkgname=m4
pkgver=1.4.15
pkgrel=0
pkgdesc="GNU macro processor"
url="http://www.gnu.org/software/m4"
depends=
arch="all"
license="GPL"
subpackages="m4-doc"
source="ftp://ftp.gnu.org/gnu/m4/$pkgname-$pkgver.tar.gz
gnulib-uclibc.patch"

_builddir="$srcdir"/$pkgname-$pkgver
prepare() {
cd "$_builddir"
patch -p1 -i "$srcdir"/gnulib-uclibc.patch
}

build() {
cd "$_builddir"
./configure --prefix=/usr
make
}

package() {
cd "$_builddir"
make install DESTDIR="$pkgdir"
}

md5sums="5649a2e593b6c639deae9e72ede777dd m4-1.4.15.tar.gz
20a7dedec0e9e0ee7107e33e798ffdbe gnulib-uclibc.patch"
</pre>

== APKBUILD with Multiple Subpackages ==
A more complex APKBUILD with -doc, -dev and python subpackages:
<pre>
# Contributor: Carlo Landmeter <clandmeter at gmail>
# Maintainer: Carlo Landmeter <clandmeter at gmail>
pkgname=libxml2
pkgver=2.7.8
pkgrel=0
pkgdesc="XML parsing library, version 2"
url="http://www.xmlsoft.org/"
arch="all"
license="MIT"
depends=
depends_dev="zlib-dev python-dev"
makedepends="zlib-dev python-dev"
subpackages="$pkgname-doc $pkgname-dev py-$pkgname:py $pkgname-utils"
source="ftp://ftp.xmlsoft.org/${pkgname}/${pkgname}-${pkgver}.tar.gz
largefile64.patch"

options="!strip"

_builddir="$srcdir/$pkgname-$pkgver"
prepare() {
cd "$_builddir"
for _i in "$srcdir"/*.patch; do
patch -p1 -i "$_i"
done
}

build() {
cd "$_builddir"
./configure --prefix=/usr \
--sysconfdir=/etc \
--mandir=/usr/share/man \
--infodir=/usr/share/info
make
}

package() {
cd "$_builddir"
make -j1 DESTDIR="$pkgdir" install
install -Dm644 COPYING "$pkgdir"/usr/share/licenses/$pkgname/COPYING
}

py() {
cd "$_builddir"
pkgdesc="$pkgname python bindings"
install -d "$subpkgdir"/usr/lib
mv "$pkgdir"/usr/lib/python* "$subpkgdir"/usr/lib/
}

utils() {
pkgdesc="XML utilities"
replaces="libxml2"
mkdir -p "$subpkgdir"/usr
mv "$pkgdir"/usr/bin "$subpkgdir"/usr/
}

md5sums="8127a65e8c3b08856093099b52599c86 libxml2-2.7.8.tar.gz
5ad4915665608ebfa5b89f7908467a72 largefile64.patch"
</pre>

APKBUILD Reference

2011-01-17T04:22:17Z

Mattx86: Moved "Subpackages Example" into the "Examples" section, expanded TOC for "Examples" section, moved a few a note or two, updated some wording

APKBUILDs are the scripts that are created in order to build Alpine packages using the [[abuild]] tool.

This page is intended to serve as a quick reference for creating APKBUILDs; if this is your first time creating a package for Alpine Linux, please see [[Creating an Alpine package]].

= Legend =
The following notes will assist you in understanding this document.

In description text:
* If a variable is not prefixed with a ''$'', it will be represented by italics (i.e., ''srcdir'' ).
* Functions will also be represented by italics, but will also end with a pair of parentheses (i.e., ''build()'' ).
* Shell commands will be represented by italics and bold type (i.e., '''''abuild checksum''''').

= Variables =
{{Note|Variables that contain a path (e.g. ''$srcdir'' and ''$pkgdir'') should always be quoted using double quotes (i.e., ''"$srcdir"''). This is done to prevent things from breaking, should the user have the APKBUILD in a directory path that contains spaces.}}
{{Tip|All arbitrary variable and function names should be prefixed with an underscore character ( _ ) to avoid name clashes with the internals of abuild (i.e., ''_builddir'').}}

== abuild-defined variables ==
The following variables are defined by abuild:

==== startdir ====
: The directory where the APKBUILD script is.
==== srcdir ====
: The directory where sources, from the ''source'' variable, are downloaded to and unpacked to.
==== pkgdir ====
: This directory should contain the files for the main package. For example, a normal [http://en.wikipedia.org/wiki/GNU_build_system autotools] package would have '''''make DESTDIR="$pkgdir" install''''' in the ''package()'' function.
==== subpkgdir ====
: This directory should contain the files for a subpackage. This variable should only be used from subpackage functions.

== User-defined variables ==
The following variables should be defined by the user:
==== arch ====
: Package architecture(s) to build for. Can be one of: '''x86, x86_64, all''', or '''noarch''', where '''all''' means all architectures, and '''noarch''' means it's architecture-independent (e.g., a pure-python package).
: {{Tip|To determine if your APKBUILD can use '''noarch''': First specify '''all''' and then build the package by executing '''''abuild -r'''''. Watch the output towards the end for warnings saying that '''noarch''' can be used. If the main package and all subpackages, if you have any subpackages, give a warning saying that '''noarch''' can be used, then you can use '''noarch'''.}}
==== depends ====
: Run-time dependency package(s) that are not shared-object dependencies. Shared objects dependencies are auto-detected and should not be specified here.
==== depends_dev ====
: Run-time dependency package(s) for the '''$pkgname-dev''' subpackage.
==== install ====
: Pre/Post- Install/Upgrade/Deinstall scripts. These are used to provide additional help when installing/upgrading/deinstalling a package, and are named '''$pkgname.{pre,post}-{install,upgrade,deinstall}'''. For example, if ''pkgname'' is set to '''mypackage''' and ''install'' is set to '''$pkgname.post-install''', then a script named '''mypackage.post-install''' must exist along-side the APKBUILD.
==== license ====
: License(s) for the package.
==== makedepends ====
: Build-time dependency package(s).
==== md5sums ====
: Checksums for the files/URLs listed in ''source''. The checksums are normally generated and updated by executing '''''abuild checksum''''' and should be the last item in the APKBUILD.
==== options ====
: Build-time options for the package. Can be: '''!strip''' - to avoid stripping symbols from binaries.
==== pkgdesc ====
: Short description of the package.
==== pkggroups ====
: System group(s) to be created during build-time. System group(s) should also be created in a '''$pkgname.pre-install''' script, so that the system group(s) are also created prior to package installation for run-time use.
==== pkgname ====
: The name of the package. All letters should be lowercase.
: {{Tip|When creating an APKBUILD of a module or library for another package, we use some common package prefixes, such as: ''lua-'', ''perl-'', ''php-'', and ''py-''. Search aports for other common prefixes.}}
==== pkgrel ====
: Alpine package release number. Starts at 0 (zero). Always increment ''pkgrel'' when making updates to an aport; reset ''pkgrel'' to 0 (zero) when incrementing ''pkgver''.
==== pkgusers ====
: System user(s) to be created during build-time. System user(s) should also be created in a '''$pkgname.pre-install''' script, so that the system user(s) are also created prior to package installation for run-time use.
==== pkgver ====
: The version of the software being packaged.
==== replaces ====
: Package(s) that this package replaces. This package will "take over" files owned by packages listed in the ''replaces'' variable. This is useful when files move from one sub-/package to another, or when a package gets renamed.
==== source ====
: URL(s) to sources and patches. It can also list local files included along-side the APKBUILD, such as patches, init.d scripts, conf.d files, etc.
==== subpackages ====
: Subpackages built from this APKBUILD. abuild will parse this variable and try to find a subpackage split function. The split function must ''move'' files that do not belong in the main package, from ''$pkgdir'' to ''$subpkgdir''. Files and directories can also be ''copied'' from ''$startdir'' and ''$srcdir'' to ''$subpkgdir''.

: The split function can be specified in 1 of 3 different ways:
:# subpkgname:'''splitfunc'''
:# $pkgname-'''splitfunc'''
:# '''splitfunc'''
==== url ====
: The homepage for the package. This is to help users find upstream documentation and other information regarding the package.

= Functions =
{{Note|All functions should consider the current working directory as undefined, and should therefore use the [[APKBUILD Reference#abuild-defined_variables|abuild-defined directory variables]] to their advantage.}}

== abuild-defined functions ==
The following functions are provided by abuild and can be overridden:

==== fetch() ====
: Downloads remote sources listed in ''source'' to ''SRCDEST'' (''SRCDEST'' is configured in ''/etc/abuild.conf'') and creates symlinks in ''$srcdir''.
==== unpack() ====
: Unpacks .tgz, .tar.gz, .tar.bz2, .tar.lzma, .tar.xz, and .zip archives in ''$srcdir'' to ''$srcdir''.
==== dev() ====
: Subpackage function for the '''$pkgname-dev''' package. Without specifying a custom ''dev()'' function, abuild will call it's internal ''dev()'' function, which in turn calls ''default_dev()'', which will move ''"$pkgdir"/usr/include'', ''*.a'', ''*.la'' and similar files to ''$subpkgdir''.
==== doc() ====
: Subpackage function for the '''$pkgname-doc''' package. Without specifying a custom ''doc()'' function, abuild will call it's internal ''doc()'' function, which in turn calls ''default_doc()'', which will move ''"$pkgdir"/usr/share/doc'', ''"$pkgdir"/usr/share/man'' and similar to ''$subpkgdir''.

== User-defined functions ==
The following functions should be defined by the user:

==== prepare() ====
: '''''Optional''.''' Used for build preparation: patches, etc, should be applied here. This function is available for your convenience.
==== build() ====
: '''Required.''' This is the compilation stage. This function will be called as the current user (unless the ''package()'' function is missing - for compatibility reasons). If no compilation is needed, this function can contain a single line: '''''return 0'''''
==== package() ====
: '''Required.''' This is the packaging stage. Here, the built application and support files should be installed into '''$pkgdir'''. If this is a metapackage, this function can contain a single line: '''''mkdir -p "$pkgdir" && return 0'''''

{{Note|Building in fakeroot will reduce performance for parallel builds dramatically. It is for this reason that we split the build and package process into two separate functions.}}

= Examples =
The following APKBUILD examples will assist you in understanding how to create an APKBUILD.

== Subpackages Example ==
Consider the following APKBUILD snippet:
pkgname="foo"
subpackages="$pkgname-dev $pkgname-doc py-$pkgname:pysub libfoo"

It will ...
* create the following 5 packages:
# foo (main)
# foo-dev (sub)
# foo-doc (sub)
# py-foo (sub)
# libfoo (sub)

* using the following 5 package functions (respectively) to fill them with files:
# ''package()'': will be provided by the user (and can make use of the ''$pkgdir'' variable).
# ''dev()'': will be provided by abuild unless we override it, by providing our own ''dev()'' function (which can make use of the ''$subpkgdir'' variable).
# ''doc()'': will be provided by abuild unless we override it, by providing our own ''doc()'' function (which can make use of the ''$subpkgdir'' variable).
# ''pysub()'': will be provided by the user (and can make use of the ''$subpkgdir'' variable).
# ''libfoo()'': will be provided by the user (and can make use of the ''$subpkgdir'' variable).

== Simple APKBUILD ==
Simple APKBUILD with -doc subpackage, using abuild's default ''doc()'' function:
<pre>
# Maintainer: Natanael Copa <ncopa@alpinelinux.org>
pkgname=m4
pkgver=1.4.15
pkgrel=0
pkgdesc="GNU macro processor"
url="http://www.gnu.org/software/m4"
depends=
arch="all"
license="GPL"
subpackages="m4-doc"
source="ftp://ftp.gnu.org/gnu/m4/$pkgname-$pkgver.tar.gz
gnulib-uclibc.patch"

_builddir="$srcdir"/$pkgname-$pkgver
prepare() {
cd "$_builddir"
patch -p1 -i "$srcdir"/gnulib-uclibc.patch
}

build() {
cd "$_builddir"
./configure --prefix=/usr
make
}

package() {
cd "$_builddir"
make install DESTDIR="$pkgdir"
}

md5sums="5649a2e593b6c639deae9e72ede777dd m4-1.4.15.tar.gz
20a7dedec0e9e0ee7107e33e798ffdbe gnulib-uclibc.patch"
</pre>

== APKBUILD with Multiple Subpackages ==
A more complex APKBUILD with -doc, -dev and python subpackages:
<pre>
# Contributor: Carlo Landmeter <clandmeter at gmail>
# Maintainer: Carlo Landmeter <clandmeter at gmail>
pkgname=libxml2
pkgver=2.7.8
pkgrel=0
pkgdesc="XML parsing library, version 2"
url="http://www.xmlsoft.org/"
arch="all"
license="MIT"
depends=
depends_dev="zlib-dev python-dev"
makedepends="zlib-dev python-dev"
subpackages="$pkgname-doc $pkgname-dev py-$pkgname:py $pkgname-utils"
source="ftp://ftp.xmlsoft.org/${pkgname}/${pkgname}-${pkgver}.tar.gz
largefile64.patch"

options="!strip"

_builddir="$srcdir/$pkgname-$pkgver"
prepare() {
cd "$_builddir"
for _i in "$srcdir"/*.patch; do
patch -p1 -i "$_i"
done
}

build() {
cd "$_builddir"
./configure --prefix=/usr \
--sysconfdir=/etc \
--mandir=/usr/share/man \
--infodir=/usr/share/info
make
}

package() {
cd "$_builddir"
make -j1 DESTDIR="$pkgdir" install
install -Dm644 COPYING "$pkgdir"/usr/share/licenses/$pkgname/COPYING
}

py() {
cd "$_builddir"
pkgdesc="$pkgname python bindings"
install -d "$subpkgdir"/usr/lib
mv "$pkgdir"/usr/lib/python* "$subpkgdir"/usr/lib/
}

utils() {
pkgdesc="XML utilities"
replaces="libxml2"
mkdir -p "$subpkgdir"/usr
mv "$pkgdir"/usr/bin "$subpkgdir"/usr/
}

md5sums="8127a65e8c3b08856093099b52599c86 libxml2-2.7.8.tar.gz
5ad4915665608ebfa5b89f7908467a72 largefile64.patch"
</pre>

APKBUILD Reference

2011-01-17T03:59:33Z

Mattx86: Absorbed "Subpackages" section into the "subpackages" variable description

APKBUILDs are the scripts that are created in order to build Alpine packages using the [[abuild]] tool.

This page is intended to serve as a quick reference for creating APKBUILDs; if this is your first time creating a package for Alpine Linux, please see [[Creating an Alpine package]].

= Legend =
The following notes will assist you in understanding this document.

* If a variable is not prefixed with a ''$'', it will be represented by italics (i.e., ''srcdir'' ).
* Functions will also be represented by italics, but will also end with a pair of parentheses (i.e., ''build()'' ).
* Shell commands will be represented by italics and bold type (i.e., '''''abuild checksum''''').

= Variables =
{{Note|Variables that contain a path (e.g. ''$srcdir'' and ''$pkgdir'') should always be quoted using double quotes (i.e., ''"$srcdir"''). This is done to prevent things from breaking, should the user have the APKBUILD in a directory path that contains spaces.}}

== abuild-defined variables ==
The following variables are defined by abuild:

==== startdir ====
: The directory where the APKBUILD script is.
==== srcdir ====
: The directory where sources, from the ''source'' variable, are downloaded to and unpacked to.
==== pkgdir ====
: This directory should contain the files for the main package. For example, a normal [http://en.wikipedia.org/wiki/GNU_build_system autotools] package would have '''''make DESTDIR="$pkgdir" install''''' in the ''package()'' function.
==== subpkgdir ====
: This directory should contain the files for a subpackage. This variable should only be used from subpackage functions.

== User-defined variables ==
The following variables should be defined by the user:
==== arch ====
: Package architecture(s) to build for. Can be one of: '''x86, x86_64, all''', or '''noarch''', where '''''all''''' means all architectures, and '''''noarch''''' means it's architecture-independent (e.g., a pure-python package).
: {{Tip|To determine if your APKBUILD can use '''noarch''': First specify '''all''' and then build the package by executing '''''abuild -r'''''. Watch the output towards the end for warnings saying that '''noarch''' can be used. If the main package and all subpackages, if you have any subpackages, give a warning saying that '''noarch''' can be used, then you can use '''noarch'''.}}
==== depends ====
: Run-time dependency package(s) that are not shared-object dependencies. Shared objects dependencies are auto-detected and should not be specified here.
==== depends_dev ====
: Run-time dependency package(s) for the '''$pkgname-dev''' subpackage.
==== install ====
: Pre/Post- Install/Upgrade/Deinstall scripts. These are used to provide additional help when installing/upgrading/deinstalling a package, and are named '''$pkgname.{pre,post}-{install,upgrade,deinstall}'''. For example, if ''pkgname'' is set to '''mypackage''' and ''install'' is set to '''$pkgname.post-install''', then a script named '''mypackage.post-install''' must exist along-side the APKBUILD.
==== license ====
: License(s) for the package.
==== makedepends ====
: Build-time dependency package(s).
==== md5sums ====
: Checksums for the files/URLs listed in ''source''. The checksums are normally generated and updated by executing '''''abuild checksum''''' and should be the last item in the APKBUILD.
==== options ====
: Build-time options for the package. Can be: '''!strip''' - to avoid stripping symbols from binaries.
==== pkgdesc ====
: Short description of the package.
==== pkggroups ====
: System group(s) to be created during build-time. System group(s) should also be created in a '''$pkgname.pre-install''' script, so that the system group(s) are also created prior to package installation for run-time use.
==== pkgname ====
: The name of the package. All letters should be lowercase.
: {{Tip|When creating an APKBUILD of a module or library for another package, we use some common package prefixes, such as: ''lua-'', ''perl-'', ''php-'', and ''py-''. Search aports for other common prefixes.}}
==== pkgrel ====
: Alpine package release number. Starts at 0 (zero). Always increment ''pkgrel'' when making updates to an aport; reset ''pkgrel'' to 0 (zero) when incrementing ''pkgver''.
==== pkgusers ====
: System user(s) to be created during build-time. System user(s) should also be created in a '''$pkgname.pre-install''' script, so that the system user(s) are also created prior to package installation for run-time use.
==== pkgver ====
: The version of the software being packaged.
==== replaces ====
: Package(s) that this package replaces. This package will "take over" files owned by packages listed in the ''replaces'' variable. This is useful when files move from one sub-/package to another, or when a package gets renamed.
==== source ====
: URL(s) to sources and patches. It can also list local files included along-side the APKBUILD, such as patches, init.d scripts, conf.d files, etc.
==== subpackages ====
: Subpackages built from this APKBUILD. abuild will parse this variable and try to find a subpackage split function. The split function must ''move'' files that do not belong in the main package, from ''$pkgdir'' to ''$subpkgdir''. Files and directories can also be ''copied'' from ''$startdir'' and ''$srcdir'' to ''$subpkgdir''.

: The split function can be specified in 1 of 3 different ways:
:# subpkgname:'''splitfunc'''
:# $pkgname-'''splitfunc'''
:# '''splitfunc'''

===== Subpackages Example =====
: Consider the following APKBUILD snippet:
<blockquote><pre>pkgname="foo"
subpackages="$pkgname-dev $pkgname-doc py-$pkgname:pysub libfoo"</pre></blockquote>

: It will ...
:* create the following 5 packages:
:# foo (main)
:# foo-dev (sub)
:# foo-doc (sub)
:# py-foo (sub)
:# libfoo (sub)

:* using the following 5 package functions (respectively) to fill them with files:
:# ''package()'': will be provided by the user (and can make use of the ''$pkgdir'' variable).
:# ''dev()'': will be provided by abuild unless we override it, by providing our own ''dev()'' function (which can make use of the ''$subpkgdir'' variable).
:# ''doc()'': will be provided by abuild unless we override it, by providing our own ''doc()'' function (which can make use of the ''$subpkgdir'' variable).
:# ''pysub()'': will be provided by the user (and can make use of the ''$subpkgdir'' variable).
:# ''libfoo()'': will be provided by the user (and can make use of the ''$subpkgdir'' variable).

==== url ====
: The homepage for the package. This is to help users find upstream documentation and other information regarding the package.

{{Tip|All custom user-specified variables and functions should be prefixed with an underscore character ( _ ) to avoid name clashes with the internals of abuild (i.e., ''_builddir'').}}

= Functions =
{{Note|All functions should consider the current working directory as undefined, and should therefore use the [[APKBUILD Reference#abuild-defined_variables|abuild-defined directory variables]] to their advantage.}}

== abuild-defined functions ==
The following functions are provided by abuild and can be overridden:

==== fetch() ====
: Downloads remote sources listed in ''source'' to ''SRCDEST'' (''SRCDEST'' is configured in ''/etc/abuild.conf'') and creates symlinks in ''$srcdir''.
==== unpack() ====
: Unpacks .tgz, .tar.gz, .tar.bz2, .tar.lzma, .tar.xz, and .zip archives in ''$srcdir'' to ''$srcdir''.
==== dev() ====
: Subpackage function for the '''$pkgname-dev''' package. Without specifying a custom ''dev()'' function, abuild will call it's internal ''dev()'' function, which in turn calls ''default_dev()'', which will move ''"$pkgdir"/usr/include'', ''*.a'', ''*.la'' and similar files to ''$subpkgdir''.
==== doc() ====
: Subpackage function for the '''$pkgname-doc''' package. Without specifying a custom ''doc()'' function, abuild will call it's internal ''doc()'' function, which in turn calls ''default_doc()'', which will move ''"$pkgdir"/usr/share/doc'', ''"$pkgdir"/usr/share/man'' and similar to ''$subpkgdir''.

== User-defined functions ==
The following functions should be defined by the user:

==== prepare() ====
: '''''Optional''.''' Used for build preparation: patches, etc, should be applied here. This function is available for your convenience.
==== build() ====
: '''Required.''' This is the compilation stage. This function will be called as the current user (unless the ''package()'' function is missing - for compatibility reasons). If no compilation is needed, this function can contain a single line: '''''return 0'''''
==== package() ====
: '''Required.''' This is the packaging stage. Here, the built application and support files should be installed into '''$pkgdir'''. If this is a metapackage, this function can contain a single line: '''''mkdir -p "$pkgdir" && return 0'''''

{{Note|Building in fakeroot will reduce performance for parallel builds dramatically. It is for this reason that we split the build and package process into two separate functions.}}

= Examples =
Simple APKBUILD with -doc subpackage, using abuild's default ''doc()'' function:
<pre>
# Maintainer: Natanael Copa <ncopa@alpinelinux.org>
pkgname=m4
pkgver=1.4.15
pkgrel=0
pkgdesc="GNU macro processor"
url="http://www.gnu.org/software/m4"
depends=
arch="all"
license="GPL"
subpackages="m4-doc"
source="ftp://ftp.gnu.org/gnu/m4/$pkgname-$pkgver.tar.gz
gnulib-uclibc.patch"

_builddir="$srcdir"/$pkgname-$pkgver
prepare() {
cd "$_builddir"
patch -p1 -i "$srcdir"/gnulib-uclibc.patch
}

build() {
cd "$_builddir"
./configure --prefix=/usr
make
}

package() {
cd "$_builddir"
make install DESTDIR="$pkgdir"
}

md5sums="5649a2e593b6c639deae9e72ede777dd m4-1.4.15.tar.gz
20a7dedec0e9e0ee7107e33e798ffdbe gnulib-uclibc.patch"
</pre>

A more complex APKBUILD with -doc, -dev and python subpackages:
<pre>
# Contributor: Carlo Landmeter <clandmeter at gmail>
# Maintainer: Carlo Landmeter <clandmeter at gmail>
pkgname=libxml2
pkgver=2.7.8
pkgrel=0
pkgdesc="XML parsing library, version 2"
url="http://www.xmlsoft.org/"
arch="all"
license="MIT"
depends=
depends_dev="zlib-dev python-dev"
makedepends="zlib-dev python-dev"
subpackages="$pkgname-doc $pkgname-dev py-$pkgname:py $pkgname-utils"
source="ftp://ftp.xmlsoft.org/${pkgname}/${pkgname}-${pkgver}.tar.gz
largefile64.patch"

options="!strip"

_builddir="$srcdir/$pkgname-$pkgver"
prepare() {
cd "$_builddir"
for _i in "$srcdir"/*.patch; do
patch -p1 -i "$_i"
done
}

build() {
cd "$_builddir"
./configure --prefix=/usr \
--sysconfdir=/etc \
--mandir=/usr/share/man \
--infodir=/usr/share/info
make
}

package() {
cd "$_builddir"
make -j1 DESTDIR="$pkgdir" install
install -Dm644 COPYING "$pkgdir"/usr/share/licenses/$pkgname/COPYING
}

py() {
cd "$_builddir"
pkgdesc="$pkgname python bindings"
install -d "$subpkgdir"/usr/lib
mv "$pkgdir"/usr/lib/python* "$subpkgdir"/usr/lib/
}

utils() {
pkgdesc="XML utilities"
replaces="libxml2"
mkdir -p "$subpkgdir"/usr
mv "$pkgdir"/usr/bin "$subpkgdir"/usr/
}

md5sums="8127a65e8c3b08856093099b52599c86 libxml2-2.7.8.tar.gz
5ad4915665608ebfa5b89f7908467a72 largefile64.patch"
</pre>

APKBUILD Reference

2011-01-17T02:34:55Z

Mattx86: Updated wording in "Subpackages Example" section and updated the description of the "md5sums" variable

APKBUILDs are the scripts that are created in order to build Alpine packages using the [[abuild]] tool.

This page is intended to serve as a quick reference for creating APKBUILDs; if this is your first time creating a package for Alpine Linux, please see [[Creating an Alpine package]].

= Legend =
The following notes will assist you in understanding this document.

* If a variable is not prefixed with a ''$'', it will be represented by italics (i.e., ''srcdir'' ).
* Functions will also be represented by italics, but will also end with a pair of parentheses (i.e., ''build()'' ).
* Shell commands will be represented by italics and bold type (i.e., '''''abuild checksum''''').

= Variables =
{{Note|Variables that contain a path (e.g. ''$srcdir'' and ''$pkgdir'') should always be quoted using double quotes (i.e., ''"$srcdir"''). This is done to prevent things from breaking, should the user have the APKBUILD in a directory path that contains spaces.}}

== abuild-defined variables ==
The following variables are defined by abuild:

===== startdir =====
: The directory where the APKBUILD script is.
===== srcdir =====
: The directory where sources, from the ''source'' variable, are downloaded to and unpacked to.
===== pkgdir =====
: This directory should contain the files for the main package. For example, a normal [http://en.wikipedia.org/wiki/GNU_build_system autotools] package would have '''''make DESTDIR="$pkgdir" install''''' in the ''package()'' function.
===== subpkgdir =====
: This directory should contain the files for a subpackage. This variable should only be used from subpackage functions.

== User-defined variables ==
The following variables should be defined by the user:
===== arch =====
: Package architecture(s) to build for. Can be one of: '''x86, x86_64, all''', or '''noarch''', where '''''all''''' means all architectures, and '''''noarch''''' means it's architecture-independent (e.g., a pure-python package).
: {{Tip|To determine if your APKBUILD can use '''noarch''': First specify '''all''' and then build the package by executing '''''abuild -r'''''. Watch the output towards the end for warnings saying that '''noarch''' can be used. If the main package and all subpackages, if you have any subpackages, give a warning saying that '''noarch''' can be used, then you can use '''noarch'''.}}

===== depends =====
: Run-time dependency package(s) that are not shared-object dependencies. Shared objects dependencies are auto-detected and should not be specified here.
===== depends_dev =====
: Run-time dependency package(s) for the '''$pkgname-dev''' subpackage.
===== install =====
: Pre/Post- Install/Upgrade/Deinstall scripts. These are used to provide additional help when installing/upgrading/deinstalling a package, and are named '''$pkgname.{pre,post}-{install,upgrade,deinstall}'''. For example, if ''pkgname'' is set to '''mypackage''' and ''install'' is set to '''$pkgname.post-install''', then a script named '''mypackage.post-install''' must exist along-side the APKBUILD.
===== license =====
: License(s) for the package.
===== makedepends =====
: Build-time dependency package(s).
===== md5sums =====
: Checksums for the files/URLs listed in ''source''. The checksums are normally generated and updated by executing '''''abuild checksum''''' and should be the last item in the APKBUILD.
===== options =====
: Build-time options for the package. Can be: '''!strip''' - to avoid stripping symbols from binaries.
===== pkgdesc =====
: Short description of the package.
===== pkggroups =====
: System group(s) to be created during build-time. System group(s) should also be created in a '''$pkgname.pre-install''' script, so that the system group(s) are also created prior to package installation for run-time use.
===== pkgname =====
: The name of the package. All letters should be lowercase.
: {{Tip|When creating an APKBUILD of a module or library for another package, we use some common package prefixes, such as: ''lua-'', ''perl-'', ''php-'', and ''py-''. Search aports for other common prefixes.}}
===== pkgrel =====
: Alpine package release number. Starts at 0 (zero). Always increment ''pkgrel'' when making updates to an aport; reset ''pkgrel'' to 0 (zero) when incrementing ''pkgver''.
===== pkgusers =====
: System user(s) to be created during build-time. System user(s) should also be created in a '''$pkgname.pre-install''' script, so that the system user(s) are also created prior to package installation for run-time use.
===== pkgver =====
: The version of the software being packaged.
===== replaces =====
: Package(s) that this package replaces. This package will "take over" files owned by packages listed in the ''replaces'' variable. This is useful when files move from one sub-/package to another, or when a package gets renamed.
===== source =====
: URL(s) to sources and patches. It can also list local files included along-side the APKBUILD, such as patches, init.d scripts, conf.d files, etc.
===== subpackages =====
: Subpackages built from this APKBUILD. Subpackages are usually prefixed with '''$pkgname-''', with the remainder of the subpackage name being used as the name of the package function for the subpackage. For example, if ''subpackages'' is set to '''$pkgname-extra''', this will create a subpackage called '''''$pkgname''-extra''', which is packaged using a custom ''extra()'' function. (See the [[APKBUILD Reference#Subpackages_2|Subpackages]] section below for more information.)

===== url =====
: The homepage for the package. This is to help users find upstream documentation and other information regarding the package.

{{Tip|All custom user-specified variables and functions should be prefixed with an underscore character ( _ ) to avoid name clashes with the internals of abuild (i.e., ''_builddir'').}}

= Functions =
{{Note|All functions should consider the current working directory as undefined, and should therefore use the [[APKBUILD Reference#abuild-defined_variables|abuild-defined directory variables]] to their advantage.}}

== abuild-defined functions ==
The following functions are provided by abuild and can be overridden:

===== fetch() =====
: Downloads remote sources listed in ''source'' to ''SRCDEST'' (''SRCDEST'' is configured in ''/etc/abuild.conf'') and creates symlinks in ''$srcdir''.
===== unpack() =====
: Unpacks .tgz, .tar.gz, .tar.bz2, .tar.lzma, .tar.xz, and .zip archives in ''$srcdir'' to ''$srcdir''.
===== dev() =====
: Subpackage function for the '''$pkgname-dev''' package. Without specifying a custom ''dev()'' function, abuild will call it's internal ''dev()'' function, which in turn calls ''default_dev()'', which will move ''"$pkgdir"/usr/include'', ''*.a'', ''*.la'' and similar files to ''$subpkgdir''.
===== doc() =====
: Subpackage function for the '''$pkgname-doc''' package. Without specifying a custom ''doc()'' function, abuild will call it's internal ''doc()'' function, which in turn calls ''default_doc()'', which will move ''"$pkgdir"/usr/share/doc'', ''"$pkgdir"/usr/share/man'' and similar to ''$subpkgdir''.

== User-defined functions ==
The following functions should be defined by the user:

===== prepare() =====
: '''''Optional''.''' Used for build preparation: patches, etc, should be applied here. This function is available for your convenience.
===== build() =====
: '''Required.''' This is the compilation stage. This function will be called as the current user (unless the ''package()'' function is missing - for compatibility reasons). If no compilation is needed, this function can contain a single line: '''''return 0'''''
===== package() =====
: '''Required.''' This is the packaging stage. Here, the built application and support files should be installed into '''$pkgdir'''. If this is a metapackage, this function can contain a single line: '''''mkdir -p "$pkgdir" && return 0'''''

{{Note|Building in fakeroot will reduce performance for parallel builds dramatically. It is for this reason that we split the build and package process into two separate functions.}}

= Subpackages =
Subpackages are specified in the ''subpackages'' variable. abuild will parse this variable and try to find a subpackage split function. The split function must ''move'' files that do not belong in the main package, from ''$pkgdir'' to ''$subpkgdir''. Files and directories can also be ''copied'' from ''$startdir'' and ''$srcdir'' to ''$subpkgdir''.

The split function can be specified in 1 of 3 different ways:
# subpkgname:'''splitfunc'''
# $pkgname-'''splitfunc'''
# '''splitfunc'''

== Subpackages Example ==
The following APKBUILD snippet:
pkgname="foo"
subpackages="$pkgname-dev $pkgname-doc py-$pkgname:pysub libfoo"

* will create the following 5 packages:
# foo (main)
# foo-dev (sub)
# foo-doc (sub)
# py-foo (sub)
# libfoo (sub)

* using the following 5 package functions (respectively) to fill them with files:
# ''package()'': will be provided by the user (and can make use of the ''$pkgdir'' variable).
# ''dev()'': will be provided by abuild unless we override it, by providing our own ''dev()'' function (which can make use of the ''$subpkgdir'' variable).
# ''doc()'': will be provided by abuild unless we override it, by providing our own ''doc()'' function (which can make use of the ''$subpkgdir'' variable).
# ''pysub()'': will be provided by the user (and can make use of the ''$subpkgdir'' variable).
# ''libfoo()'': will be provided by the user (and can make use of the ''$subpkgdir'' variable).

= Examples =
Simple APKBUILD with -doc subpackage, using abuild's default ''doc()'' function:
<pre>
# Maintainer: Natanael Copa <ncopa@alpinelinux.org>
pkgname=m4
pkgver=1.4.15
pkgrel=0
pkgdesc="GNU macro processor"
url="http://www.gnu.org/software/m4"
depends=
arch="all"
license="GPL"
subpackages="m4-doc"
source="ftp://ftp.gnu.org/gnu/m4/$pkgname-$pkgver.tar.gz
gnulib-uclibc.patch"

_builddir="$srcdir"/$pkgname-$pkgver
prepare() {
cd "$_builddir"
patch -p1 -i "$srcdir"/gnulib-uclibc.patch
}

build() {
cd "$_builddir"
./configure --prefix=/usr
make
}

package() {
cd "$_builddir"
make install DESTDIR="$pkgdir"
}

md5sums="5649a2e593b6c639deae9e72ede777dd m4-1.4.15.tar.gz
20a7dedec0e9e0ee7107e33e798ffdbe gnulib-uclibc.patch"
</pre>

A more complex APKBUILD with -doc, -dev and python subpackages:
<pre>
# Contributor: Carlo Landmeter <clandmeter at gmail>
# Maintainer: Carlo Landmeter <clandmeter at gmail>
pkgname=libxml2
pkgver=2.7.8
pkgrel=0
pkgdesc="XML parsing library, version 2"
url="http://www.xmlsoft.org/"
arch="all"
license="MIT"
depends=
depends_dev="zlib-dev python-dev"
makedepends="zlib-dev python-dev"
subpackages="$pkgname-doc $pkgname-dev py-$pkgname:py $pkgname-utils"
source="ftp://ftp.xmlsoft.org/${pkgname}/${pkgname}-${pkgver}.tar.gz
largefile64.patch"

options="!strip"

_builddir="$srcdir/$pkgname-$pkgver"
prepare() {
cd "$_builddir"
for _i in "$srcdir"/*.patch; do
patch -p1 -i "$_i"
done
}

build() {
cd "$_builddir"
./configure --prefix=/usr \
--sysconfdir=/etc \
--mandir=/usr/share/man \
--infodir=/usr/share/info
make
}

package() {
cd "$_builddir"
make -j1 DESTDIR="$pkgdir" install
install -Dm644 COPYING "$pkgdir"/usr/share/licenses/$pkgname/COPYING
}

py() {
cd "$_builddir"
pkgdesc="$pkgname python bindings"
install -d "$subpkgdir"/usr/lib
mv "$pkgdir"/usr/lib/python* "$subpkgdir"/usr/lib/
}

utils() {
pkgdesc="XML utilities"
replaces="libxml2"
mkdir -p "$subpkgdir"/usr
mv "$pkgdir"/usr/bin "$subpkgdir"/usr/
}

md5sums="8127a65e8c3b08856093099b52599c86 libxml2-2.7.8.tar.gz
5ad4915665608ebfa5b89f7908467a72 largefile64.patch"
</pre>

APKBUILD Reference

2011-01-13T08:56:49Z

Mattx86: Inserted some line breaks; should be final edit for a while

APKBUILDs are the scripts that are created in order to build Alpine packages using the [[abuild]] tool.

This page is intended to serve as a quick reference for creating APKBUILDs; if this is your first time creating a package for Alpine Linux, please see [[Creating an Alpine package]].

= Legend =
The following notes will assist you in understanding this document.

* If a variable is not prefixed with a ''$'', it will be represented by italics (i.e., ''srcdir'' ).
* Functions will also be represented by italics, but will also end with a pair of parentheses (i.e., ''build()'' ).
* Shell commands will be represented by italics and bold type (i.e., '''''abuild checksum''''').

= Variables =
{{Note|Variables that contain a path (e.g. ''$srcdir'' and ''$pkgdir'') should always be quoted using double quotes (i.e., ''"$srcdir"''). This is done to prevent things from breaking, should the user have the APKBUILD in a directory path that contains spaces.}}

== abuild-defined variables ==
The following variables are defined by abuild:

===== startdir =====
: The directory where the APKBUILD script is.
===== srcdir =====
: The directory where sources, from the ''source'' variable, are downloaded to and unpacked to.
===== pkgdir =====
: This directory should contain the files for the main package. For example, a normal [http://en.wikipedia.org/wiki/GNU_build_system autotools] package would have '''''make DESTDIR="$pkgdir" install''''' in the ''package()'' function.
===== subpkgdir =====
: This directory should contain the files for a subpackage. This variable should only be used from subpackage functions.

== User-defined variables ==
The following variables should be defined by the user:
===== arch =====
: Package architecture(s) to build for. Can be one of: '''x86, x86_64, all''', or '''noarch''', where '''''all''''' means all architectures, and '''''noarch''''' means it's architecture-independent (e.g., a pure-python package).
: {{Tip|To determine if your APKBUILD can use '''noarch''': First specify '''all''' and then build the package by executing '''''abuild -r'''''. Watch the output towards the end for warnings saying that '''noarch''' can be used. If the main package and all subpackages, if you have any subpackages, give a warning saying that '''noarch''' can be used, then you can use '''noarch'''.}}

===== depends =====
: Run-time dependency package(s) that are not shared-object dependencies. Shared objects dependencies are auto-detected and should not be specified here.
===== depends_dev =====
: Run-time dependency package(s) for the '''$pkgname-dev''' subpackage.
===== install =====
: Pre/Post- Install/Upgrade/Deinstall scripts. These are used to provide additional help when installing/upgrading/deinstalling a package, and are named '''$pkgname.{pre,post}-{install,upgrade,deinstall}'''. For example, if ''pkgname'' is set to '''mypackage''' and ''install'' is set to '''$pkgname.post-install''', then a script named '''mypackage.post-install''' must exist along-side the APKBUILD.
===== license =====
: License(s) for the package.
===== makedepends =====
: Build-time dependency package(s).
===== md5sums =====
: Checksums for the files/URLs listed in ''source''. The checksums are normally generated by executing '''''abuild checksum''''' and should be the last item in the APKBUILD.
===== options =====
: Build-time options for the package. Can be: '''!strip''' - to avoid stripping symbols from binaries.
===== pkgdesc =====
: Short description of the package.
===== pkggroups =====
: System group(s) to be created during build-time. System group(s) should also be created in a '''$pkgname.pre-install''' script, so that the system group(s) are also created prior to package installation for run-time use.
===== pkgname =====
: The name of the package. All letters should be lowercase.
: {{Tip|When creating an APKBUILD of a module or library for another package, we use some common package prefixes, such as: ''lua-'', ''perl-'', ''php-'', and ''py-''. Search aports for other common prefixes.}}
===== pkgrel =====
: Alpine package release number. Starts at 0 (zero). Always increment ''pkgrel'' when making updates to an aport; reset ''pkgrel'' to 0 (zero) when incrementing ''pkgver''.
===== pkgusers =====
: System user(s) to be created during build-time. System user(s) should also be created in a '''$pkgname.pre-install''' script, so that the system user(s) are also created prior to package installation for run-time use.
===== pkgver =====
: The version of the software being packaged.
===== replaces =====
: Package(s) that this package replaces. This package will "take over" files owned by packages listed in the ''replaces'' variable. This is useful when files move from one sub-/package to another, or when a package gets renamed.
===== source =====
: URL(s) to sources and patches. It can also list local files included along-side the APKBUILD, such as patches, init.d scripts, conf.d files, etc.
===== subpackages =====
: Subpackages built from this APKBUILD. Subpackages are usually prefixed with '''$pkgname-''', with the remainder of the subpackage name being used as the name of the package function for the subpackage. For example, if ''subpackages'' is set to '''$pkgname-extra''', this will create a subpackage called '''''$pkgname''-extra''', which is packaged using a custom ''extra()'' function. (See the [[APKBUILD Reference#Subpackages_2|Subpackages]] section below for more information.)

===== url =====
: The homepage for the package. This is to help users find upstream documentation and other information regarding the package.

{{Tip|All custom user-specified variables and functions should be prefixed with an underscore character ( _ ) to avoid name clashes with the internals of abuild (i.e., ''_builddir'').}}

= Functions =
{{Note|All functions should consider the current working directory as undefined, and should therefore use the [[APKBUILD Reference#abuild-defined_variables|abuild-defined directory variables]] to their advantage.}}

== abuild-defined functions ==
The following functions are provided by abuild and can be overridden:

===== fetch() =====
: Downloads remote sources listed in ''source'' to ''SRCDEST'' (''SRCDEST'' is configured in ''/etc/abuild.conf'') and creates symlinks in ''$srcdir''.
===== unpack() =====
: Unpacks .tgz, .tar.gz, .tar.bz2, .tar.lzma, .tar.xz, and .zip archives in ''$srcdir'' to ''$srcdir''.
===== dev() =====
: Subpackage function for the '''$pkgname-dev''' package. Without specifying a custom ''dev()'' function, abuild will call it's internal ''dev()'' function, which in turn calls ''default_dev()'', which will move ''"$pkgdir"/usr/include'', ''*.a'', ''*.la'' and similar files to ''$subpkgdir''.
===== doc() =====
: Subpackage function for the '''$pkgname-doc''' package. Without specifying a custom ''doc()'' function, abuild will call it's internal ''doc()'' function, which in turn calls ''default_doc()'', which will move ''"$pkgdir"/usr/share/doc'', ''"$pkgdir"/usr/share/man'' and similar to ''$subpkgdir''.

== User-defined functions ==
The following functions should be defined by the user:

===== prepare() =====
: '''''Optional''.''' Used for build preparation: patches, etc, should be applied here. This function is available for your convenience.
===== build() =====
: '''Required.''' This is the compilation stage. This function will be called as the current user (unless the ''package()'' function is missing - for compatibility reasons). If no compilation is needed, this function can contain a single line: '''''return 0'''''
===== package() =====
: '''Required.''' This is the packaging stage. Here, the built application and support files should be installed into '''$pkgdir'''. If this is a metapackage, this function can contain a single line: '''''mkdir -p "$pkgdir" && return 0'''''

{{Note|Building in fakeroot will reduce performance for parallel builds dramatically. It is for this reason that we split the build and package process into two separate functions.}}

= Subpackages =
Subpackages are specified in the ''subpackages'' variable. abuild will parse this variable and try to find a subpackage split function. The split function must ''move'' files that do not belong in the main package, from ''$pkgdir'' to ''$subpkgdir''. Files and directories can also be ''copied'' from ''$startdir'' and ''$srcdir'' to ''$subpkgdir''.

The split function can be specified in 1 of 3 different ways:
# subpkgname:'''splitfunc'''
# $pkgname-'''splitfunc'''
# '''splitfunc'''

== Subpackages Example ==
The following APKBUILD snippet:
pkgname="foo"
subpackages="$pkgname-dev $pkgname-doc py-$pkgname:pysub libfoo"

... will create the 5 packages in total:
# foo (main)
# foo-dev (sub)
# foo-doc (sub)
# py-foo (sub)
# libfoo (sub)

The split functions for the 4 subpackages are:
# ''dev()'' (provided by abuild)
# ''doc()'' (provided by abuild)
# ''pysub()'' (provided by the user)
# ''libfoo()'' (provided by the user)

= Examples =
Simple APKBUILD with -doc subpackage, using abuild's default ''doc()'' function:
<pre>
# Maintainer: Natanael Copa <ncopa@alpinelinux.org>
pkgname=m4
pkgver=1.4.15
pkgrel=0
pkgdesc="GNU macro processor"
url="http://www.gnu.org/software/m4"
depends=
arch="all"
license="GPL"
subpackages="m4-doc"
source="ftp://ftp.gnu.org/gnu/m4/$pkgname-$pkgver.tar.gz
gnulib-uclibc.patch"

_builddir="$srcdir"/$pkgname-$pkgver
prepare() {
cd "$_builddir"
patch -p1 -i "$srcdir"/gnulib-uclibc.patch
}

build() {
cd "$_builddir"
./configure --prefix=/usr
make
}

package() {
cd "$_builddir"
make install DESTDIR="$pkgdir"
}

md5sums="5649a2e593b6c639deae9e72ede777dd m4-1.4.15.tar.gz
20a7dedec0e9e0ee7107e33e798ffdbe gnulib-uclibc.patch"
</pre>

A more complex APKBUILD with -doc, -dev and python subpackages:
<pre>
# Contributor: Carlo Landmeter <clandmeter at gmail>
# Maintainer: Carlo Landmeter <clandmeter at gmail>
pkgname=libxml2
pkgver=2.7.8
pkgrel=0
pkgdesc="XML parsing library, version 2"
url="http://www.xmlsoft.org/"
arch="all"
license="MIT"
depends=
depends_dev="zlib-dev python-dev"
makedepends="zlib-dev python-dev"
subpackages="$pkgname-doc $pkgname-dev py-$pkgname:py $pkgname-utils"
source="ftp://ftp.xmlsoft.org/${pkgname}/${pkgname}-${pkgver}.tar.gz
largefile64.patch"

options="!strip"

_builddir="$srcdir/$pkgname-$pkgver"
prepare() {
cd "$_builddir"
for _i in "$srcdir"/*.patch; do
patch -p1 -i "$_i"
done
}

build() {
cd "$_builddir"
./configure --prefix=/usr \
--sysconfdir=/etc \
--mandir=/usr/share/man \
--infodir=/usr/share/info
make
}

package() {
cd "$_builddir"
make -j1 DESTDIR="$pkgdir" install
install -Dm644 COPYING "$pkgdir"/usr/share/licenses/$pkgname/COPYING
}

py() {
cd "$_builddir"
pkgdesc="$pkgname python bindings"
install -d "$subpkgdir"/usr/lib
mv "$pkgdir"/usr/lib/python* "$subpkgdir"/usr/lib/
}

utils() {
pkgdesc="XML utilities"
replaces="libxml2"
mkdir -p "$subpkgdir"/usr
mv "$pkgdir"/usr/bin "$subpkgdir"/usr/
}

md5sums="8127a65e8c3b08856093099b52599c86 libxml2-2.7.8.tar.gz
5ad4915665608ebfa5b89f7908467a72 largefile64.patch"
</pre>

APKBUILD Reference

2011-01-13T06:37:39Z

Mattx86: /* arch */ Updated info on determining use of noarch

APKBUILDs are the scripts that are created in order to build Alpine packages using the [[abuild]] tool.

This page is intended to serve as a quick reference for creating APKBUILDs; if this is your first time creating a package for Alpine Linux, please see [[Creating an Alpine package]].

= Legend =
The following notes will assist you in understanding this document.

* If a variable is not prefixed with a ''$'', it will be represented by italics (i.e., ''srcdir'' ).
* Functions will also be represented by italics, but will also end with a pair of parentheses (i.e., ''build()'' ).
* Shell commands will be represented by italics and bold type (i.e., '''''abuild checksum''''').

= Variables =
{{Note|Variables that contain a path (e.g. ''$srcdir'' and ''$pkgdir'') should always be quoted using double quotes (i.e., ''"$srcdir"''). This is done to prevent things from breaking, should the user have the APKBUILD in a directory path that contains spaces.}}

== abuild-defined variables ==
The following variables are defined by abuild:

===== startdir =====
: The directory where the APKBUILD script is.
===== srcdir =====
: The directory where sources, from the ''source'' variable, are downloaded to and unpacked to.
===== pkgdir =====
: This directory should contain the files for the main package. For example, a normal [http://en.wikipedia.org/wiki/GNU_build_system autotools] package would have '''''make DESTDIR="$pkgdir" install''''' in the ''package()'' function.
===== subpkgdir =====
: This directory should contain the files for a subpackage. This variable should only be used from subpackage functions.

== User-defined variables ==
The following variables should be defined by the user:
===== arch =====
: Package architecture(s) to build for. Can be one of: '''x86, x86_64, all''', or '''noarch''', where '''''all''''' means all architectures, and '''''noarch''''' means it's architecture-independent (e.g., a pure-python package).
: {{Tip|To determine if your APKBUILD can use '''noarch''': First specify '''all''' and then build the package by executing '''''abuild -r'''''. Watch the output towards the end for warnings saying that '''noarch''' can be used. If the main package and all subpackages, if you have any subpackages, give a warning saying that '''noarch''' can be used, then you can use '''noarch'''.}}

===== depends =====
: Run-time dependency package(s) that are not shared-object dependencies. Shared objects dependencies are auto-detected and should not be specified here.
===== depends_dev =====
: Run-time dependency package(s) for the '''$pkgname-dev''' subpackage.
===== install =====
: Pre/Post- Install/Upgrade/Deinstall scripts. These are used to provide additional help when installing/upgrading/deinstalling a package, and are named '''$pkgname.{pre,post}-{install,upgrade,deinstall}'''. For example, if ''pkgname'' is set to '''mypackage''' and ''install'' is set to '''$pkgname.post-install''', then a script named '''mypackage.post-install''' must exist along-side the APKBUILD.
===== license =====
: License(s) for the package.
===== makedepends =====
: Build-time dependency package(s).
===== md5sums =====
: Checksums for the files/URLs listed in ''source''. The checksums are normally generated by executing '''''abuild checksum''''' and should be the last item in the APKBUILD.
===== options =====
: Build-time options for the package. Can be: '''!strip''' - to avoid stripping symbols from binaries.
===== pkgdesc =====
: Short description of the package.
===== pkggroups =====
: System group(s) to be created during build-time. System group(s) should also be created in a '''$pkgname.pre-install''' script, so that the system group(s) are also created prior to package installation for run-time use.
===== pkgname =====
: The name of the package. All letters should be lowercase.
: {{Tip|When creating an APKBUILD of a module or library for another package, we use some common package prefixes, such as: ''lua-'', ''perl-'', ''php-'', and ''py-''. Search aports for other common prefixes.}}
===== pkgrel =====
: Alpine package release number. Starts at 0 (zero). Always increment ''pkgrel'' when making updates to an aport; reset ''pkgrel'' to 0 (zero) when incrementing ''pkgver''.
===== pkgusers =====
: System user(s) to be created during build-time. System user(s) should also be created in a '''$pkgname.pre-install''' script, so that the system user(s) are also created prior to package installation for run-time use.
===== pkgver =====
: The version of the software being packaged.
===== replaces =====
: Package(s) that this package replaces. This package will "take over" files owned by packages listed in the ''replaces'' variable. This is useful when files move from one sub-/package to another, or when a package gets renamed.
===== source =====
: URL(s) to sources and patches. It can also list local files included along-side the APKBUILD, such as patches, init.d scripts, conf.d files, etc.
===== subpackages =====
: Subpackages built from this APKBUILD. Subpackages are usually prefixed with '''$pkgname-''', with the remainder of the subpackage name being used as the name of the package function for the subpackage. For example, if ''subpackages'' is set to '''$pkgname-extra''', this will create a subpackage called '''''$pkgname''-extra''', which is packaged using a custom ''extra()'' function. (See the [[APKBUILD Reference#Subpackages_2|Subpackages]] section below for more information.)

===== url =====
: The homepage for the package. This is to help users find upstream documentation and other information regarding the package.

{{Tip|All custom user-specified variables and functions should be prefixed with an underscore character ( _ ) to avoid name clashes with the internals of abuild (i.e., ''_builddir'').}}

= Functions =
{{Note|All functions should consider the current working directory as undefined, and should therefore use the [[APKBUILD Reference#abuild-defined_variables|abuild-defined directory variables]] to their advantage.}}

== abuild-defined functions ==
The following functions are provided by abuild and can be overridden:

===== fetch() =====
: Downloads remote sources listed in ''source'' to ''SRCDEST'' (''SRCDEST'' is configured in ''/etc/abuild.conf'') and creates symlinks in ''$srcdir''.
===== unpack() =====
: Unpacks .tgz, .tar.gz, .tar.bz2, .tar.lzma, .tar.xz, and .zip archives in ''$srcdir'' to ''$srcdir''.
===== dev() =====
: Subpackage function for the '''$pkgname-dev''' package. Without specifying a custom ''dev()'' function, abuild will call it's internal ''dev()'' function, which in turn calls ''default_dev()'', which will move ''"$pkgdir"/usr/include'', ''*.a'', ''*.la'' and similar files to ''$subpkgdir''.
===== doc() =====
: Subpackage function for the '''$pkgname-doc''' package. Without specifying a custom ''doc()'' function, abuild will call it's internal ''doc()'' function, which in turn calls ''default_doc()'', which will move ''"$pkgdir"/usr/share/doc'', ''"$pkgdir"/usr/share/man'' and similar to ''$subpkgdir''.

== User-defined functions ==
The following functions should be defined by the user:

===== prepare() =====
: '''''Optional''.''' Used for build preparation: patches, etc, should be applied here. This function is available for your convenience.
===== build() =====
: '''Required.''' This is the compilation stage. This function will be called as the current user (unless the ''package()'' function is missing - for compatibility reasons). If no compilation is needed, this function can contain a single line: '''''return 0'''''
===== package() =====
: '''Required.''' This is the packaging stage. Here, the built application and support files should be installed into '''$pkgdir'''. If this is a metapackage, this function can contain a single line: '''''mkdir -p "$pkgdir" && return 0'''''

{{Note|Building in fakeroot will reduce performance for parallel builds dramatically. It is for this reason that we split the build and package process into two separate functions.}}

= Subpackages =
Subpackages are specified in the ''subpackages'' variable. abuild will parse this variable and try to find a subpackage split function. The split function must ''move'' files that do not belong in the main package, from ''$pkgdir'' to ''$subpkgdir''. Files and directories can also be ''copied'' from ''$startdir'' and ''$srcdir'' to ''$subpkgdir''.

The split function can be specified in 1 of 3 different ways:
# subpkgname:'''splitfunc'''
# $pkgname-'''splitfunc'''
# '''splitfunc'''

== Subpackages Example ==
The following APKBUILD snippet:
pkgname="foo"
subpackages="$pkgname-dev $pkgname-doc py-$pkgname:pysub libfoo"

... will create the 5 packages in total:
# foo (main)
# foo-dev (sub)
# foo-doc (sub)
# py-foo (sub)
# libfoo (sub)

The split functions for the 4 subpackages are:
# ''dev()'' (provided by abuild)
# ''doc()'' (provided by abuild)
# ''pysub()'' (provided by the user)
# ''libfoo()'' (provided by the user)

= Examples =
Simple APKBUILD with -doc subpackage, using abuild's default ''doc()'' function:
<pre>
# Maintainer: Natanael Copa <ncopa@alpinelinux.org>
pkgname=m4
pkgver=1.4.15
pkgrel=0
pkgdesc="GNU macro processor"
url="http://www.gnu.org/software/m4"
depends=
arch="all"
license="GPL"
subpackages="m4-doc"
source="ftp://ftp.gnu.org/gnu/m4/$pkgname-$pkgver.tar.gz
gnulib-uclibc.patch"

_builddir="$srcdir"/$pkgname-$pkgver
prepare() {
cd "$_builddir"
patch -p1 -i "$srcdir"/gnulib-uclibc.patch
}

build() {
cd "$_builddir"
./configure --prefix=/usr
make
}

package() {
cd "$_builddir"
make install DESTDIR="$pkgdir"
}

md5sums="5649a2e593b6c639deae9e72ede777dd m4-1.4.15.tar.gz
20a7dedec0e9e0ee7107e33e798ffdbe gnulib-uclibc.patch"
</pre>

A more complex APKBUILD with -doc, -dev and python subpackages:
<pre>
# Contributor: Carlo Landmeter <clandmeter at gmail>
# Maintainer: Carlo Landmeter <clandmeter at gmail>
pkgname=libxml2
pkgver=2.7.8
pkgrel=0
pkgdesc="XML parsing library, version 2"
url="http://www.xmlsoft.org/"
arch="all"
license="MIT"
depends=
depends_dev="zlib-dev python-dev"
makedepends="zlib-dev python-dev"
subpackages="$pkgname-doc $pkgname-dev py-$pkgname:py $pkgname-utils"
source="ftp://ftp.xmlsoft.org/${pkgname}/${pkgname}-${pkgver}.tar.gz
largefile64.patch"

options="!strip"

_builddir="$srcdir/$pkgname-$pkgver"
prepare() {
cd "$_builddir"
for _i in "$srcdir"/*.patch; do
patch -p1 -i "$_i"
done
}

build() {
cd "$_builddir"
./configure --prefix=/usr \
--sysconfdir=/etc \
--mandir=/usr/share/man \
--infodir=/usr/share/info
make
}

package() {
cd "$_builddir"
make -j1 DESTDIR="$pkgdir" install
install -Dm644 COPYING "$pkgdir"/usr/share/licenses/$pkgname/COPYING
}

py() {
cd "$_builddir"
pkgdesc="$pkgname python bindings"
install -d "$subpkgdir"/usr/lib
mv "$pkgdir"/usr/lib/python* "$subpkgdir"/usr/lib/
}

utils() {
pkgdesc="XML utilities"
replaces="libxml2"
mkdir -p "$subpkgdir"/usr
mv "$pkgdir"/usr/bin "$subpkgdir"/usr/
}

md5sums="8127a65e8c3b08856093099b52599c86 libxml2-2.7.8.tar.gz
5ad4915665608ebfa5b89f7908467a72 largefile64.patch"
</pre>

APKBUILD Reference

2011-01-13T06:26:56Z

Mattx86: /* arch */ Updated wording

APKBUILDs are the scripts that are created in order to build Alpine packages using the [[abuild]] tool.

This page is intended to serve as a quick reference for creating APKBUILDs; if this is your first time creating a package for Alpine Linux, please see [[Creating an Alpine package]].

= Legend =
The following notes will assist you in understanding this document.

* If a variable is not prefixed with a ''$'', it will be represented by italics (i.e., ''srcdir'' ).
* Functions will also be represented by italics, but will also end with a pair of parentheses (i.e., ''build()'' ).
* Shell commands will be represented by italics and bold type (i.e., '''''abuild checksum''''').

= Variables =
{{Note|Variables that contain a path (e.g. ''$srcdir'' and ''$pkgdir'') should always be quoted using double quotes (i.e., ''"$srcdir"''). This is done to prevent things from breaking, should the user have the APKBUILD in a directory path that contains spaces.}}

== abuild-defined variables ==
The following variables are defined by abuild:

===== startdir =====
: The directory where the APKBUILD script is.
===== srcdir =====
: The directory where sources, from the ''source'' variable, are downloaded to and unpacked to.
===== pkgdir =====
: This directory should contain the files for the main package. For example, a normal [http://en.wikipedia.org/wiki/GNU_build_system autotools] package would have '''''make DESTDIR="$pkgdir" install''''' in the ''package()'' function.
===== subpkgdir =====
: This directory should contain the files for a subpackage. This variable should only be used from subpackage functions.

== User-defined variables ==
The following variables should be defined by the user:
===== arch =====
: Package architecture(s) to build for. Can be one of: '''x86, x86_64, all''', or '''noarch''', where '''''all''''' means all architectures, and '''''noarch''''' means it's architecture-independent (e.g., a pure-python package).
: {{Tip|To determine if your APKBUILD can use '''noarch''': First specify '''all''' and then build the package by executing '''''abuild -r'''''. Once built, execute '''''scanelf -R pkg'''''. (This scans for ELF files in the ''./pkg'' directory.) If you do not get output from this, then '''noarch''' can be used.}}

===== depends =====
: Run-time dependency package(s) that are not shared-object dependencies. Shared objects dependencies are auto-detected and should not be specified here.
===== depends_dev =====
: Run-time dependency package(s) for the '''$pkgname-dev''' subpackage.
===== install =====
: Pre/Post- Install/Upgrade/Deinstall scripts. These are used to provide additional help when installing/upgrading/deinstalling a package, and are named '''$pkgname.{pre,post}-{install,upgrade,deinstall}'''. For example, if ''pkgname'' is set to '''mypackage''' and ''install'' is set to '''$pkgname.post-install''', then a script named '''mypackage.post-install''' must exist along-side the APKBUILD.
===== license =====
: License(s) for the package.
===== makedepends =====
: Build-time dependency package(s).
===== md5sums =====
: Checksums for the files/URLs listed in ''source''. The checksums are normally generated by executing '''''abuild checksum''''' and should be the last item in the APKBUILD.
===== options =====
: Build-time options for the package. Can be: '''!strip''' - to avoid stripping symbols from binaries.
===== pkgdesc =====
: Short description of the package.
===== pkggroups =====
: System group(s) to be created during build-time. System group(s) should also be created in a '''$pkgname.pre-install''' script, so that the system group(s) are also created prior to package installation for run-time use.
===== pkgname =====
: The name of the package. All letters should be lowercase.
: {{Tip|When creating an APKBUILD of a module or library for another package, we use some common package prefixes, such as: ''lua-'', ''perl-'', ''php-'', and ''py-''. Search aports for other common prefixes.}}
===== pkgrel =====
: Alpine package release number. Starts at 0 (zero). Always increment ''pkgrel'' when making updates to an aport; reset ''pkgrel'' to 0 (zero) when incrementing ''pkgver''.
===== pkgusers =====
: System user(s) to be created during build-time. System user(s) should also be created in a '''$pkgname.pre-install''' script, so that the system user(s) are also created prior to package installation for run-time use.
===== pkgver =====
: The version of the software being packaged.
===== replaces =====
: Package(s) that this package replaces. This package will "take over" files owned by packages listed in the ''replaces'' variable. This is useful when files move from one sub-/package to another, or when a package gets renamed.
===== source =====
: URL(s) to sources and patches. It can also list local files included along-side the APKBUILD, such as patches, init.d scripts, conf.d files, etc.
===== subpackages =====
: Subpackages built from this APKBUILD. Subpackages are usually prefixed with '''$pkgname-''', with the remainder of the subpackage name being used as the name of the package function for the subpackage. For example, if ''subpackages'' is set to '''$pkgname-extra''', this will create a subpackage called '''''$pkgname''-extra''', which is packaged using a custom ''extra()'' function. (See the [[APKBUILD Reference#Subpackages_2|Subpackages]] section below for more information.)

===== url =====
: The homepage for the package. This is to help users find upstream documentation and other information regarding the package.

{{Tip|All custom user-specified variables and functions should be prefixed with an underscore character ( _ ) to avoid name clashes with the internals of abuild (i.e., ''_builddir'').}}

= Functions =
{{Note|All functions should consider the current working directory as undefined, and should therefore use the [[APKBUILD Reference#abuild-defined_variables|abuild-defined directory variables]] to their advantage.}}

== abuild-defined functions ==
The following functions are provided by abuild and can be overridden:

===== fetch() =====
: Downloads remote sources listed in ''source'' to ''SRCDEST'' (''SRCDEST'' is configured in ''/etc/abuild.conf'') and creates symlinks in ''$srcdir''.
===== unpack() =====
: Unpacks .tgz, .tar.gz, .tar.bz2, .tar.lzma, .tar.xz, and .zip archives in ''$srcdir'' to ''$srcdir''.
===== dev() =====
: Subpackage function for the '''$pkgname-dev''' package. Without specifying a custom ''dev()'' function, abuild will call it's internal ''dev()'' function, which in turn calls ''default_dev()'', which will move ''"$pkgdir"/usr/include'', ''*.a'', ''*.la'' and similar files to ''$subpkgdir''.
===== doc() =====
: Subpackage function for the '''$pkgname-doc''' package. Without specifying a custom ''doc()'' function, abuild will call it's internal ''doc()'' function, which in turn calls ''default_doc()'', which will move ''"$pkgdir"/usr/share/doc'', ''"$pkgdir"/usr/share/man'' and similar to ''$subpkgdir''.

== User-defined functions ==
The following functions should be defined by the user:

===== prepare() =====
: '''''Optional''.''' Used for build preparation: patches, etc, should be applied here. This function is available for your convenience.
===== build() =====
: '''Required.''' This is the compilation stage. This function will be called as the current user (unless the ''package()'' function is missing - for compatibility reasons). If no compilation is needed, this function can contain a single line: '''''return 0'''''
===== package() =====
: '''Required.''' This is the packaging stage. Here, the built application and support files should be installed into '''$pkgdir'''. If this is a metapackage, this function can contain a single line: '''''mkdir -p "$pkgdir" && return 0'''''

{{Note|Building in fakeroot will reduce performance for parallel builds dramatically. It is for this reason that we split the build and package process into two separate functions.}}

= Subpackages =
Subpackages are specified in the ''subpackages'' variable. abuild will parse this variable and try to find a subpackage split function. The split function must ''move'' files that do not belong in the main package, from ''$pkgdir'' to ''$subpkgdir''. Files and directories can also be ''copied'' from ''$startdir'' and ''$srcdir'' to ''$subpkgdir''.

The split function can be specified in 1 of 3 different ways:
# subpkgname:'''splitfunc'''
# $pkgname-'''splitfunc'''
# '''splitfunc'''

== Subpackages Example ==
The following APKBUILD snippet:
pkgname="foo"
subpackages="$pkgname-dev $pkgname-doc py-$pkgname:pysub libfoo"

... will create the 5 packages in total:
# foo (main)
# foo-dev (sub)
# foo-doc (sub)
# py-foo (sub)
# libfoo (sub)

The split functions for the 4 subpackages are:
# ''dev()'' (provided by abuild)
# ''doc()'' (provided by abuild)
# ''pysub()'' (provided by the user)
# ''libfoo()'' (provided by the user)

= Examples =
Simple APKBUILD with -doc subpackage, using abuild's default ''doc()'' function:
<pre>
# Maintainer: Natanael Copa <ncopa@alpinelinux.org>
pkgname=m4
pkgver=1.4.15
pkgrel=0
pkgdesc="GNU macro processor"
url="http://www.gnu.org/software/m4"
depends=
arch="all"
license="GPL"
subpackages="m4-doc"
source="ftp://ftp.gnu.org/gnu/m4/$pkgname-$pkgver.tar.gz
gnulib-uclibc.patch"

_builddir="$srcdir"/$pkgname-$pkgver
prepare() {
cd "$_builddir"
patch -p1 -i "$srcdir"/gnulib-uclibc.patch
}

build() {
cd "$_builddir"
./configure --prefix=/usr
make
}

package() {
cd "$_builddir"
make install DESTDIR="$pkgdir"
}

md5sums="5649a2e593b6c639deae9e72ede777dd m4-1.4.15.tar.gz
20a7dedec0e9e0ee7107e33e798ffdbe gnulib-uclibc.patch"
</pre>

A more complex APKBUILD with -doc, -dev and python subpackages:
<pre>
# Contributor: Carlo Landmeter <clandmeter at gmail>
# Maintainer: Carlo Landmeter <clandmeter at gmail>
pkgname=libxml2
pkgver=2.7.8
pkgrel=0
pkgdesc="XML parsing library, version 2"
url="http://www.xmlsoft.org/"
arch="all"
license="MIT"
depends=
depends_dev="zlib-dev python-dev"
makedepends="zlib-dev python-dev"
subpackages="$pkgname-doc $pkgname-dev py-$pkgname:py $pkgname-utils"
source="ftp://ftp.xmlsoft.org/${pkgname}/${pkgname}-${pkgver}.tar.gz
largefile64.patch"

options="!strip"

_builddir="$srcdir/$pkgname-$pkgver"
prepare() {
cd "$_builddir"
for _i in "$srcdir"/*.patch; do
patch -p1 -i "$_i"
done
}

build() {
cd "$_builddir"
./configure --prefix=/usr \
--sysconfdir=/etc \
--mandir=/usr/share/man \
--infodir=/usr/share/info
make
}

package() {
cd "$_builddir"
make -j1 DESTDIR="$pkgdir" install
install -Dm644 COPYING "$pkgdir"/usr/share/licenses/$pkgname/COPYING
}

py() {
cd "$_builddir"
pkgdesc="$pkgname python bindings"
install -d "$subpkgdir"/usr/lib
mv "$pkgdir"/usr/lib/python* "$subpkgdir"/usr/lib/
}

utils() {
pkgdesc="XML utilities"
replaces="libxml2"
mkdir -p "$subpkgdir"/usr
mv "$pkgdir"/usr/bin "$subpkgdir"/usr/
}

md5sums="8127a65e8c3b08856093099b52599c86 libxml2-2.7.8.tar.gz
5ad4915665608ebfa5b89f7908467a72 largefile64.patch"
</pre>

APKBUILD Reference

2011-01-13T06:15:20Z

Mattx86: /* User-defined functions */

APKBUILDs are the scripts that are created in order to build Alpine packages using the [[abuild]] tool.

This page is intended to serve as a quick reference for creating APKBUILDs; if this is your first time creating a package for Alpine Linux, please see [[Creating an Alpine package]].

= Legend =
The following notes will assist you in understanding this document.

* If a variable is not prefixed with a ''$'', it will be represented by italics (i.e., ''srcdir'' ).
* Functions will also be represented by italics, but will also end with a pair of parentheses (i.e., ''build()'' ).
* Shell commands will be represented by italics and bold type (i.e., '''''abuild checksum''''').

= Variables =
{{Note|Variables that contain a path (e.g. ''$srcdir'' and ''$pkgdir'') should always be quoted using double quotes (i.e., ''"$srcdir"''). This is done to prevent things from breaking, should the user have the APKBUILD in a directory path that contains spaces.}}

== abuild-defined variables ==
The following variables are defined by abuild:

===== startdir =====
: The directory where the APKBUILD script is.
===== srcdir =====
: The directory where sources, from the ''source'' variable, are downloaded to and unpacked to.
===== pkgdir =====
: This directory should contain the files for the main package. For example, a normal [http://en.wikipedia.org/wiki/GNU_build_system autotools] package would have '''''make DESTDIR="$pkgdir" install''''' in the ''package()'' function.
===== subpkgdir =====
: This directory should contain the files for a subpackage. This variable should only be used from subpackage functions.

== User-defined variables ==
The following variables should be defined by the user:
===== arch =====
: Package architecture(s) to build for. Can be one of: '''x86, x86_64, all''', or '''noarch''', where '''''all''''' means all architectures, and '''''noarch''''' means it's architecture-independent (e.g., a pure-python package).
: {{Tip|To determine if your APKBUILD can use '''noarch''', first specify '''all''', build the package by running '''''abuild -r''''' and once built, execute '''''scanelf -R pkg'''''. This scans for ELF files in the ''./pkg'' directory, where all sub-/package files reside. If you do not get output from this, then '''noarch''' can be used.}}
===== depends =====
: Run-time dependency package(s) that are not shared-object dependencies. Shared objects dependencies are auto-detected and should not be specified here.
===== depends_dev =====
: Run-time dependency package(s) for the '''$pkgname-dev''' subpackage.
===== install =====
: Pre/Post- Install/Upgrade/Deinstall scripts. These are used to provide additional help when installing/upgrading/deinstalling a package, and are named '''$pkgname.{pre,post}-{install,upgrade,deinstall}'''. For example, if ''pkgname'' is set to '''mypackage''' and ''install'' is set to '''$pkgname.post-install''', then a script named '''mypackage.post-install''' must exist along-side the APKBUILD.
===== license =====
: License(s) for the package.
===== makedepends =====
: Build-time dependency package(s).
===== md5sums =====
: Checksums for the files/URLs listed in ''source''. The checksums are normally generated by executing '''''abuild checksum''''' and should be the last item in the APKBUILD.
===== options =====
: Build-time options for the package. Can be: '''!strip''' - to avoid stripping symbols from binaries.
===== pkgdesc =====
: Short description of the package.
===== pkggroups =====
: System group(s) to be created during build-time. System group(s) should also be created in a '''$pkgname.pre-install''' script, so that the system group(s) are also created prior to package installation for run-time use.
===== pkgname =====
: The name of the package. All letters should be lowercase.
: {{Tip|When creating an APKBUILD of a module or library for another package, we use some common package prefixes, such as: ''lua-'', ''perl-'', ''php-'', and ''py-''. Search aports for other common prefixes.}}
===== pkgrel =====
: Alpine package release number. Starts at 0 (zero). Always increment ''pkgrel'' when making updates to an aport; reset ''pkgrel'' to 0 (zero) when incrementing ''pkgver''.
===== pkgusers =====
: System user(s) to be created during build-time. System user(s) should also be created in a '''$pkgname.pre-install''' script, so that the system user(s) are also created prior to package installation for run-time use.
===== pkgver =====
: The version of the software being packaged.
===== replaces =====
: Package(s) that this package replaces. This package will "take over" files owned by packages listed in the ''replaces'' variable. This is useful when files move from one sub-/package to another, or when a package gets renamed.
===== source =====
: URL(s) to sources and patches. It can also list local files included along-side the APKBUILD, such as patches, init.d scripts, conf.d files, etc.
===== subpackages =====
: Subpackages built from this APKBUILD. Subpackages are usually prefixed with '''$pkgname-''', with the remainder of the subpackage name being used as the name of the package function for the subpackage. For example, if ''subpackages'' is set to '''$pkgname-extra''', this will create a subpackage called '''''$pkgname''-extra''', which is packaged using a custom ''extra()'' function. (See the [[APKBUILD Reference#Subpackages_2|Subpackages]] section below for more information.)

===== url =====
: The homepage for the package. This is to help users find upstream documentation and other information regarding the package.

{{Tip|All custom user-specified variables and functions should be prefixed with an underscore character ( _ ) to avoid name clashes with the internals of abuild (i.e., ''_builddir'').}}

= Functions =
{{Note|All functions should consider the current working directory as undefined, and should therefore use the [[APKBUILD Reference#abuild-defined_variables|abuild-defined directory variables]] to their advantage.}}

== abuild-defined functions ==
The following functions are provided by abuild and can be overridden:

===== fetch() =====
: Downloads remote sources listed in ''source'' to ''SRCDEST'' (''SRCDEST'' is configured in ''/etc/abuild.conf'') and creates symlinks in ''$srcdir''.
===== unpack() =====
: Unpacks .tgz, .tar.gz, .tar.bz2, .tar.lzma, .tar.xz, and .zip archives in ''$srcdir'' to ''$srcdir''.
===== dev() =====
: Subpackage function for the '''$pkgname-dev''' package. Without specifying a custom ''dev()'' function, abuild will call it's internal ''dev()'' function, which in turn calls ''default_dev()'', which will move ''"$pkgdir"/usr/include'', ''*.a'', ''*.la'' and similar files to ''$subpkgdir''.
===== doc() =====
: Subpackage function for the '''$pkgname-doc''' package. Without specifying a custom ''doc()'' function, abuild will call it's internal ''doc()'' function, which in turn calls ''default_doc()'', which will move ''"$pkgdir"/usr/share/doc'', ''"$pkgdir"/usr/share/man'' and similar to ''$subpkgdir''.

== User-defined functions ==
The following functions should be defined by the user:

===== prepare() =====
: '''''Optional''.''' Used for build preparation: patches, etc, should be applied here. This function is available for your convenience.
===== build() =====
: '''Required.''' This is the compilation stage. This function will be called as the current user (unless the ''package()'' function is missing - for compatibility reasons). If no compilation is needed, this function can contain a single line: '''''return 0'''''
===== package() =====
: '''Required.''' This is the packaging stage. Here, the built application and support files should be installed into '''$pkgdir'''. If this is a metapackage, this function can contain a single line: '''''mkdir -p "$pkgdir" && return 0'''''

{{Note|Building in fakeroot will reduce performance for parallel builds dramatically. It is for this reason that we split the build and package process into two separate functions.}}

= Subpackages =
Subpackages are specified in the ''subpackages'' variable. abuild will parse this variable and try to find a subpackage split function. The split function must ''move'' files that do not belong in the main package, from ''$pkgdir'' to ''$subpkgdir''. Files and directories can also be ''copied'' from ''$startdir'' and ''$srcdir'' to ''$subpkgdir''.

The split function can be specified in 1 of 3 different ways:
# subpkgname:'''splitfunc'''
# $pkgname-'''splitfunc'''
# '''splitfunc'''

== Subpackages Example ==
The following APKBUILD snippet:
pkgname="foo"
subpackages="$pkgname-dev $pkgname-doc py-$pkgname:pysub libfoo"

... will create the 5 packages in total:
# foo (main)
# foo-dev (sub)
# foo-doc (sub)
# py-foo (sub)
# libfoo (sub)

The split functions for the 4 subpackages are:
# ''dev()'' (provided by abuild)
# ''doc()'' (provided by abuild)
# ''pysub()'' (provided by the user)
# ''libfoo()'' (provided by the user)

= Examples =
Simple APKBUILD with -doc subpackage, using abuild's default ''doc()'' function:
<pre>
# Maintainer: Natanael Copa <ncopa@alpinelinux.org>
pkgname=m4
pkgver=1.4.15
pkgrel=0
pkgdesc="GNU macro processor"
url="http://www.gnu.org/software/m4"
depends=
arch="all"
license="GPL"
subpackages="m4-doc"
source="ftp://ftp.gnu.org/gnu/m4/$pkgname-$pkgver.tar.gz
gnulib-uclibc.patch"

_builddir="$srcdir"/$pkgname-$pkgver
prepare() {
cd "$_builddir"
patch -p1 -i "$srcdir"/gnulib-uclibc.patch
}

build() {
cd "$_builddir"
./configure --prefix=/usr
make
}

package() {
cd "$_builddir"
make install DESTDIR="$pkgdir"
}

md5sums="5649a2e593b6c639deae9e72ede777dd m4-1.4.15.tar.gz
20a7dedec0e9e0ee7107e33e798ffdbe gnulib-uclibc.patch"
</pre>

A more complex APKBUILD with -doc, -dev and python subpackages:
<pre>
# Contributor: Carlo Landmeter <clandmeter at gmail>
# Maintainer: Carlo Landmeter <clandmeter at gmail>
pkgname=libxml2
pkgver=2.7.8
pkgrel=0
pkgdesc="XML parsing library, version 2"
url="http://www.xmlsoft.org/"
arch="all"
license="MIT"
depends=
depends_dev="zlib-dev python-dev"
makedepends="zlib-dev python-dev"
subpackages="$pkgname-doc $pkgname-dev py-$pkgname:py $pkgname-utils"
source="ftp://ftp.xmlsoft.org/${pkgname}/${pkgname}-${pkgver}.tar.gz
largefile64.patch"

options="!strip"

_builddir="$srcdir/$pkgname-$pkgver"
prepare() {
cd "$_builddir"
for _i in "$srcdir"/*.patch; do
patch -p1 -i "$_i"
done
}

build() {
cd "$_builddir"
./configure --prefix=/usr \
--sysconfdir=/etc \
--mandir=/usr/share/man \
--infodir=/usr/share/info
make
}

package() {
cd "$_builddir"
make -j1 DESTDIR="$pkgdir" install
install -Dm644 COPYING "$pkgdir"/usr/share/licenses/$pkgname/COPYING
}

py() {
cd "$_builddir"
pkgdesc="$pkgname python bindings"
install -d "$subpkgdir"/usr/lib
mv "$pkgdir"/usr/lib/python* "$subpkgdir"/usr/lib/
}

utils() {
pkgdesc="XML utilities"
replaces="libxml2"
mkdir -p "$subpkgdir"/usr
mv "$pkgdir"/usr/bin "$subpkgdir"/usr/
}

md5sums="8127a65e8c3b08856093099b52599c86 libxml2-2.7.8.tar.gz
5ad4915665608ebfa5b89f7908467a72 largefile64.patch"
</pre>

APKBUILD Reference

2011-01-13T06:14:06Z

Mattx86: /* package() */ Updated information on metapackages

APKBUILDs are the scripts that are created in order to build Alpine packages using the [[abuild]] tool.

This page is intended to serve as a quick reference for creating APKBUILDs; if this is your first time creating a package for Alpine Linux, please see [[Creating an Alpine package]].

= Legend =
The following notes will assist you in understanding this document.

* If a variable is not prefixed with a ''$'', it will be represented by italics (i.e., ''srcdir'' ).
* Functions will also be represented by italics, but will also end with a pair of parentheses (i.e., ''build()'' ).
* Shell commands will be represented by italics and bold type (i.e., '''''abuild checksum''''').

= Variables =
{{Note|Variables that contain a path (e.g. ''$srcdir'' and ''$pkgdir'') should always be quoted using double quotes (i.e., ''"$srcdir"''). This is done to prevent things from breaking, should the user have the APKBUILD in a directory path that contains spaces.}}

== abuild-defined variables ==
The following variables are defined by abuild:

===== startdir =====
: The directory where the APKBUILD script is.
===== srcdir =====
: The directory where sources, from the ''source'' variable, are downloaded to and unpacked to.
===== pkgdir =====
: This directory should contain the files for the main package. For example, a normal [http://en.wikipedia.org/wiki/GNU_build_system autotools] package would have '''''make DESTDIR="$pkgdir" install''''' in the ''package()'' function.
===== subpkgdir =====
: This directory should contain the files for a subpackage. This variable should only be used from subpackage functions.

== User-defined variables ==
The following variables should be defined by the user:
===== arch =====
: Package architecture(s) to build for. Can be one of: '''x86, x86_64, all''', or '''noarch''', where '''''all''''' means all architectures, and '''''noarch''''' means it's architecture-independent (e.g., a pure-python package).
: {{Tip|To determine if your APKBUILD can use '''noarch''', first specify '''all''', build the package by running '''''abuild -r''''' and once built, execute '''''scanelf -R pkg'''''. This scans for ELF files in the ''./pkg'' directory, where all sub-/package files reside. If you do not get output from this, then '''noarch''' can be used.}}
===== depends =====
: Run-time dependency package(s) that are not shared-object dependencies. Shared objects dependencies are auto-detected and should not be specified here.
===== depends_dev =====
: Run-time dependency package(s) for the '''$pkgname-dev''' subpackage.
===== install =====
: Pre/Post- Install/Upgrade/Deinstall scripts. These are used to provide additional help when installing/upgrading/deinstalling a package, and are named '''$pkgname.{pre,post}-{install,upgrade,deinstall}'''. For example, if ''pkgname'' is set to '''mypackage''' and ''install'' is set to '''$pkgname.post-install''', then a script named '''mypackage.post-install''' must exist along-side the APKBUILD.
===== license =====
: License(s) for the package.
===== makedepends =====
: Build-time dependency package(s).
===== md5sums =====
: Checksums for the files/URLs listed in ''source''. The checksums are normally generated by executing '''''abuild checksum''''' and should be the last item in the APKBUILD.
===== options =====
: Build-time options for the package. Can be: '''!strip''' - to avoid stripping symbols from binaries.
===== pkgdesc =====
: Short description of the package.
===== pkggroups =====
: System group(s) to be created during build-time. System group(s) should also be created in a '''$pkgname.pre-install''' script, so that the system group(s) are also created prior to package installation for run-time use.
===== pkgname =====
: The name of the package. All letters should be lowercase.
: {{Tip|When creating an APKBUILD of a module or library for another package, we use some common package prefixes, such as: ''lua-'', ''perl-'', ''php-'', and ''py-''. Search aports for other common prefixes.}}
===== pkgrel =====
: Alpine package release number. Starts at 0 (zero). Always increment ''pkgrel'' when making updates to an aport; reset ''pkgrel'' to 0 (zero) when incrementing ''pkgver''.
===== pkgusers =====
: System user(s) to be created during build-time. System user(s) should also be created in a '''$pkgname.pre-install''' script, so that the system user(s) are also created prior to package installation for run-time use.
===== pkgver =====
: The version of the software being packaged.
===== replaces =====
: Package(s) that this package replaces. This package will "take over" files owned by packages listed in the ''replaces'' variable. This is useful when files move from one sub-/package to another, or when a package gets renamed.
===== source =====
: URL(s) to sources and patches. It can also list local files included along-side the APKBUILD, such as patches, init.d scripts, conf.d files, etc.
===== subpackages =====
: Subpackages built from this APKBUILD. Subpackages are usually prefixed with '''$pkgname-''', with the remainder of the subpackage name being used as the name of the package function for the subpackage. For example, if ''subpackages'' is set to '''$pkgname-extra''', this will create a subpackage called '''''$pkgname''-extra''', which is packaged using a custom ''extra()'' function. (See the [[APKBUILD Reference#Subpackages_2|Subpackages]] section below for more information.)

===== url =====
: The homepage for the package. This is to help users find upstream documentation and other information regarding the package.

{{Tip|All custom user-specified variables and functions should be prefixed with an underscore character ( _ ) to avoid name clashes with the internals of abuild (i.e., ''_builddir'').}}

= Functions =
{{Note|All functions should consider the current working directory as undefined, and should therefore use the [[APKBUILD Reference#abuild-defined_variables|abuild-defined directory variables]] to their advantage.}}

== abuild-defined functions ==
The following functions are provided by abuild and can be overridden:

===== fetch() =====
: Downloads remote sources listed in ''source'' to ''SRCDEST'' (''SRCDEST'' is configured in ''/etc/abuild.conf'') and creates symlinks in ''$srcdir''.
===== unpack() =====
: Unpacks .tgz, .tar.gz, .tar.bz2, .tar.lzma, .tar.xz, and .zip archives in ''$srcdir'' to ''$srcdir''.
===== dev() =====
: Subpackage function for the '''$pkgname-dev''' package. Without specifying a custom ''dev()'' function, abuild will call it's internal ''dev()'' function, which in turn calls ''default_dev()'', which will move ''"$pkgdir"/usr/include'', ''*.a'', ''*.la'' and similar files to ''$subpkgdir''.
===== doc() =====
: Subpackage function for the '''$pkgname-doc''' package. Without specifying a custom ''doc()'' function, abuild will call it's internal ''doc()'' function, which in turn calls ''default_doc()'', which will move ''"$pkgdir"/usr/share/doc'', ''"$pkgdir"/usr/share/man'' and similar to ''$subpkgdir''.

== User-defined functions ==
The following functions should be defined by the user:

===== prepare() =====
: '''''Optional''.''' Used for build preparation: patches, etc, should be applied here. This function is available for your convenience.
===== build() =====
: '''Required.''' This is the compilation stage. This function will be called as the current user (unless the ''package()'' function is missing - for compatibility reasons). If no compilation is needed, this function can contain a single line: '''return 0'''
===== package() =====
: '''Required.''' This is the packaging stage. Here, the built application and support files should be installed into '''$pkgdir'''. If this is a metapackage, this function can contain a single line: '''mkdir -p "$pkgdir" && return 0'''

{{Note|Building in fakeroot will reduce performance for parallel builds dramatically. It is for this reason that we split the build and package process into two separate functions.}}

= Subpackages =
Subpackages are specified in the ''subpackages'' variable. abuild will parse this variable and try to find a subpackage split function. The split function must ''move'' files that do not belong in the main package, from ''$pkgdir'' to ''$subpkgdir''. Files and directories can also be ''copied'' from ''$startdir'' and ''$srcdir'' to ''$subpkgdir''.

The split function can be specified in 1 of 3 different ways:
# subpkgname:'''splitfunc'''
# $pkgname-'''splitfunc'''
# '''splitfunc'''

== Subpackages Example ==
The following APKBUILD snippet:
pkgname="foo"
subpackages="$pkgname-dev $pkgname-doc py-$pkgname:pysub libfoo"

... will create the 5 packages in total:
# foo (main)
# foo-dev (sub)
# foo-doc (sub)
# py-foo (sub)
# libfoo (sub)

The split functions for the 4 subpackages are:
# ''dev()'' (provided by abuild)
# ''doc()'' (provided by abuild)
# ''pysub()'' (provided by the user)
# ''libfoo()'' (provided by the user)

= Examples =
Simple APKBUILD with -doc subpackage, using abuild's default ''doc()'' function:
<pre>
# Maintainer: Natanael Copa <ncopa@alpinelinux.org>
pkgname=m4
pkgver=1.4.15
pkgrel=0
pkgdesc="GNU macro processor"
url="http://www.gnu.org/software/m4"
depends=
arch="all"
license="GPL"
subpackages="m4-doc"
source="ftp://ftp.gnu.org/gnu/m4/$pkgname-$pkgver.tar.gz
gnulib-uclibc.patch"

_builddir="$srcdir"/$pkgname-$pkgver
prepare() {
cd "$_builddir"
patch -p1 -i "$srcdir"/gnulib-uclibc.patch
}

build() {
cd "$_builddir"
./configure --prefix=/usr
make
}

package() {
cd "$_builddir"
make install DESTDIR="$pkgdir"
}

md5sums="5649a2e593b6c639deae9e72ede777dd m4-1.4.15.tar.gz
20a7dedec0e9e0ee7107e33e798ffdbe gnulib-uclibc.patch"
</pre>

A more complex APKBUILD with -doc, -dev and python subpackages:
<pre>
# Contributor: Carlo Landmeter <clandmeter at gmail>
# Maintainer: Carlo Landmeter <clandmeter at gmail>
pkgname=libxml2
pkgver=2.7.8
pkgrel=0
pkgdesc="XML parsing library, version 2"
url="http://www.xmlsoft.org/"
arch="all"
license="MIT"
depends=
depends_dev="zlib-dev python-dev"
makedepends="zlib-dev python-dev"
subpackages="$pkgname-doc $pkgname-dev py-$pkgname:py $pkgname-utils"
source="ftp://ftp.xmlsoft.org/${pkgname}/${pkgname}-${pkgver}.tar.gz
largefile64.patch"

options="!strip"

_builddir="$srcdir/$pkgname-$pkgver"
prepare() {
cd "$_builddir"
for _i in "$srcdir"/*.patch; do
patch -p1 -i "$_i"
done
}

build() {
cd "$_builddir"
./configure --prefix=/usr \
--sysconfdir=/etc \
--mandir=/usr/share/man \
--infodir=/usr/share/info
make
}

package() {
cd "$_builddir"
make -j1 DESTDIR="$pkgdir" install
install -Dm644 COPYING "$pkgdir"/usr/share/licenses/$pkgname/COPYING
}

py() {
cd "$_builddir"
pkgdesc="$pkgname python bindings"
install -d "$subpkgdir"/usr/lib
mv "$pkgdir"/usr/lib/python* "$subpkgdir"/usr/lib/
}

utils() {
pkgdesc="XML utilities"
replaces="libxml2"
mkdir -p "$subpkgdir"/usr
mv "$pkgdir"/usr/bin "$subpkgdir"/usr/
}

md5sums="8127a65e8c3b08856093099b52599c86 libxml2-2.7.8.tar.gz
5ad4915665608ebfa5b89f7908467a72 largefile64.patch"
</pre>

APKBUILD Reference

2011-01-13T04:16:44Z

Mattx86: /* subpackages */ updated wiki link to the main "Subpackages" section

APKBUILDs are the scripts that are created in order to build Alpine packages using the [[abuild]] tool.

This page is intended to serve as a quick reference for creating APKBUILDs; if this is your first time creating a package for Alpine Linux, please see [[Creating an Alpine package]].

= Legend =
The following notes will assist you in understanding this document.

* If a variable is not prefixed with a ''$'', it will be represented by italics (i.e., ''srcdir'' ).
* Functions will also be represented by italics, but will also end with a pair of parentheses (i.e., ''build()'' ).
* Shell commands will be represented by italics and bold type (i.e., '''''abuild checksum''''').

= Variables =
{{Note|Variables that contain a path (e.g. ''$srcdir'' and ''$pkgdir'') should always be quoted using double quotes (i.e., ''"$srcdir"''). This is done to prevent things from breaking, should the user have the APKBUILD in a directory path that contains spaces.}}

== abuild-defined variables ==
The following variables are defined by abuild:

===== startdir =====
: The directory where the APKBUILD script is.
===== srcdir =====
: The directory where sources, from the ''source'' variable, are downloaded to and unpacked to.
===== pkgdir =====
: This directory should contain the files for the main package. For example, a normal [http://en.wikipedia.org/wiki/GNU_build_system autotools] package would have '''''make DESTDIR="$pkgdir" install''''' in the ''package()'' function.
===== subpkgdir =====
: This directory should contain the files for a subpackage. This variable should only be used from subpackage functions.

== User-defined variables ==
The following variables should be defined by the user:
===== arch =====
: Package architecture(s) to build for. Can be one of: '''x86, x86_64, all''', or '''noarch''', where '''''all''''' means all architectures, and '''''noarch''''' means it's architecture-independent (e.g., a pure-python package).
: {{Tip|To determine if your APKBUILD can use '''noarch''', first specify '''all''', build the package by running '''''abuild -r''''' and once built, execute '''''scanelf -R pkg'''''. This scans for ELF files in the ''./pkg'' directory, where all sub-/package files reside. If you do not get output from this, then '''noarch''' can be used.}}
===== depends =====
: Run-time dependency package(s) that are not shared-object dependencies. Shared objects dependencies are auto-detected and should not be specified here.
===== depends_dev =====
: Run-time dependency package(s) for the '''$pkgname-dev''' subpackage.
===== install =====
: Pre/Post- Install/Upgrade/Deinstall scripts. These are used to provide additional help when installing/upgrading/deinstalling a package, and are named '''$pkgname.{pre,post}-{install,upgrade,deinstall}'''. For example, if ''pkgname'' is set to '''mypackage''' and ''install'' is set to '''$pkgname.post-install''', then a script named '''mypackage.post-install''' must exist along-side the APKBUILD.
===== license =====
: License(s) for the package.
===== makedepends =====
: Build-time dependency package(s).
===== md5sums =====
: Checksums for the files/URLs listed in ''source''. The checksums are normally generated by executing '''''abuild checksum''''' and should be the last item in the APKBUILD.
===== options =====
: Build-time options for the package. Can be: '''!strip''' - to avoid stripping symbols from binaries.
===== pkgdesc =====
: Short description of the package.
===== pkggroups =====
: System group(s) to be created during build-time. System group(s) should also be created in a '''$pkgname.pre-install''' script, so that the system group(s) are also created prior to package installation for run-time use.
===== pkgname =====
: The name of the package. All letters should be lowercase.
: {{Tip|When creating an APKBUILD of a module or library for another package, we use some common package prefixes, such as: ''lua-'', ''perl-'', ''php-'', and ''py-''. Search aports for other common prefixes.}}
===== pkgrel =====
: Alpine package release number. Starts at 0 (zero). Always increment ''pkgrel'' when making updates to an aport; reset ''pkgrel'' to 0 (zero) when incrementing ''pkgver''.
===== pkgusers =====
: System user(s) to be created during build-time. System user(s) should also be created in a '''$pkgname.pre-install''' script, so that the system user(s) are also created prior to package installation for run-time use.
===== pkgver =====
: The version of the software being packaged.
===== replaces =====
: Package(s) that this package replaces. This package will "take over" files owned by packages listed in the ''replaces'' variable. This is useful when files move from one sub-/package to another, or when a package gets renamed.
===== source =====
: URL(s) to sources and patches. It can also list local files included along-side the APKBUILD, such as patches, init.d scripts, conf.d files, etc.
===== subpackages =====
: Subpackages built from this APKBUILD. Subpackages are usually prefixed with '''$pkgname-''', with the remainder of the subpackage name being used as the name of the package function for the subpackage. For example, if ''subpackages'' is set to '''$pkgname-extra''', this will create a subpackage called '''''$pkgname''-extra''', which is packaged using a custom ''extra()'' function. (See the [[APKBUILD Reference#Subpackages_2|Subpackages]] section below for more information.)

===== url =====
: The homepage for the package. This is to help users find upstream documentation and other information regarding the package.

{{Tip|All custom user-specified variables and functions should be prefixed with an underscore character ( _ ) to avoid name clashes with the internals of abuild (i.e., ''_builddir'').}}

= Functions =
{{Note|All functions should consider the current working directory as undefined, and should therefore use the [[APKBUILD Reference#abuild-defined_variables|abuild-defined directory variables]] to their advantage.}}

== abuild-defined functions ==
The following functions are provided by abuild and can be overridden:

===== fetch() =====
: Downloads remote sources listed in ''source'' to ''SRCDEST'' (''SRCDEST'' is configured in ''/etc/abuild.conf'') and creates symlinks in ''$srcdir''.
===== unpack() =====
: Unpacks .tgz, .tar.gz, .tar.bz2, .tar.lzma, .tar.xz, and .zip archives in ''$srcdir'' to ''$srcdir''.
===== dev() =====
: Subpackage function for the '''$pkgname-dev''' package. Without specifying a custom ''dev()'' function, abuild will call it's internal ''dev()'' function, which in turn calls ''default_dev()'', which will move ''"$pkgdir"/usr/include'', ''*.a'', ''*.la'' and similar files to ''$subpkgdir''.
===== doc() =====
: Subpackage function for the '''$pkgname-doc''' package. Without specifying a custom ''doc()'' function, abuild will call it's internal ''doc()'' function, which in turn calls ''default_doc()'', which will move ''"$pkgdir"/usr/share/doc'', ''"$pkgdir"/usr/share/man'' and similar to ''$subpkgdir''.

== User-defined functions ==
The following functions should be defined by the user:

===== prepare() =====
: '''''Optional''.''' Used for build preparation: patches, etc, should be applied here. This function is available for your convenience.
===== build() =====
: '''Required.''' This is the compilation stage. This function will be called as the current user (unless the ''package()'' function is missing - for compatibility reasons). If no compilation is needed, this function can contain a single line: '''return 0'''
===== package() =====
: '''Required.''' This is the packaging stage. Here, the built application and support files should be installed into '''$pkgdir'''. If this is a metapackage, this function can contain a single line: '''return 0'''

{{Note|Building in fakeroot will reduce performance for parallel builds dramatically. It is for this reason that we split the build and package process into two separate functions.}}

= Subpackages =
Subpackages are specified in the ''subpackages'' variable. abuild will parse this variable and try to find a subpackage split function. The split function must ''move'' files that do not belong in the main package, from ''$pkgdir'' to ''$subpkgdir''. Files and directories can also be ''copied'' from ''$startdir'' and ''$srcdir'' to ''$subpkgdir''.

The split function can be specified in 1 of 3 different ways:
# subpkgname:'''splitfunc'''
# $pkgname-'''splitfunc'''
# '''splitfunc'''

== Subpackages Example ==
The following APKBUILD snippet:
pkgname="foo"
subpackages="$pkgname-dev $pkgname-doc py-$pkgname:pysub libfoo"

... will create the 5 packages in total:
# foo (main)
# foo-dev (sub)
# foo-doc (sub)
# py-foo (sub)
# libfoo (sub)

The split functions for the 4 subpackages are:
# ''dev()'' (provided by abuild)
# ''doc()'' (provided by abuild)
# ''pysub()'' (provided by the user)
# ''libfoo()'' (provided by the user)

= Examples =
Simple APKBUILD with -doc subpackage, using abuild's default ''doc()'' function:
<pre>
# Maintainer: Natanael Copa <ncopa@alpinelinux.org>
pkgname=m4
pkgver=1.4.15
pkgrel=0
pkgdesc="GNU macro processor"
url="http://www.gnu.org/software/m4"
depends=
arch="all"
license="GPL"
subpackages="m4-doc"
source="ftp://ftp.gnu.org/gnu/m4/$pkgname-$pkgver.tar.gz
gnulib-uclibc.patch"

_builddir="$srcdir"/$pkgname-$pkgver
prepare() {
cd "$_builddir"
patch -p1 -i "$srcdir"/gnulib-uclibc.patch
}

build() {
cd "$_builddir"
./configure --prefix=/usr
make
}

package() {
cd "$_builddir"
make install DESTDIR="$pkgdir"
}

md5sums="5649a2e593b6c639deae9e72ede777dd m4-1.4.15.tar.gz
20a7dedec0e9e0ee7107e33e798ffdbe gnulib-uclibc.patch"
</pre>

A more complex APKBUILD with -doc, -dev and python subpackages:
<pre>
# Contributor: Carlo Landmeter <clandmeter at gmail>
# Maintainer: Carlo Landmeter <clandmeter at gmail>
pkgname=libxml2
pkgver=2.7.8
pkgrel=0
pkgdesc="XML parsing library, version 2"
url="http://www.xmlsoft.org/"
arch="all"
license="MIT"
depends=
depends_dev="zlib-dev python-dev"
makedepends="zlib-dev python-dev"
subpackages="$pkgname-doc $pkgname-dev py-$pkgname:py $pkgname-utils"
source="ftp://ftp.xmlsoft.org/${pkgname}/${pkgname}-${pkgver}.tar.gz
largefile64.patch"

options="!strip"

_builddir="$srcdir/$pkgname-$pkgver"
prepare() {
cd "$_builddir"
for _i in "$srcdir"/*.patch; do
patch -p1 -i "$_i"
done
}

build() {
cd "$_builddir"
./configure --prefix=/usr \
--sysconfdir=/etc \
--mandir=/usr/share/man \
--infodir=/usr/share/info
make
}

package() {
cd "$_builddir"
make -j1 DESTDIR="$pkgdir" install
install -Dm644 COPYING "$pkgdir"/usr/share/licenses/$pkgname/COPYING
}

py() {
cd "$_builddir"
pkgdesc="$pkgname python bindings"
install -d "$subpkgdir"/usr/lib
mv "$pkgdir"/usr/lib/python* "$subpkgdir"/usr/lib/
}

utils() {
pkgdesc="XML utilities"
replaces="libxml2"
mkdir -p "$subpkgdir"/usr
mv "$pkgdir"/usr/bin "$subpkgdir"/usr/
}

md5sums="8127a65e8c3b08856093099b52599c86 libxml2-2.7.8.tar.gz
5ad4915665608ebfa5b89f7908467a72 largefile64.patch"
</pre>

APKBUILD Reference

2011-01-13T04:12:24Z

Mattx86: /* Functions */ updated wording

APKBUILDs are the scripts that are created in order to build Alpine packages using the [[abuild]] tool.

This page is intended to serve as a quick reference for creating APKBUILDs; if this is your first time creating a package for Alpine Linux, please see [[Creating an Alpine package]].

= Legend =
The following notes will assist you in understanding this document.

* If a variable is not prefixed with a ''$'', it will be represented by italics (i.e., ''srcdir'' ).
* Functions will also be represented by italics, but will also end with a pair of parentheses (i.e., ''build()'' ).
* Shell commands will be represented by italics and bold type (i.e., '''''abuild checksum''''').

= Variables =
{{Note|Variables that contain a path (e.g. ''$srcdir'' and ''$pkgdir'') should always be quoted using double quotes (i.e., ''"$srcdir"''). This is done to prevent things from breaking, should the user have the APKBUILD in a directory path that contains spaces.}}

== abuild-defined variables ==
The following variables are defined by abuild:

===== startdir =====
: The directory where the APKBUILD script is.
===== srcdir =====
: The directory where sources, from the ''source'' variable, are downloaded to and unpacked to.
===== pkgdir =====
: This directory should contain the files for the main package. For example, a normal [http://en.wikipedia.org/wiki/GNU_build_system autotools] package would have '''''make DESTDIR="$pkgdir" install''''' in the ''package()'' function.
===== subpkgdir =====
: This directory should contain the files for a subpackage. This variable should only be used from subpackage functions.

== User-defined variables ==
The following variables should be defined by the user:
===== arch =====
: Package architecture(s) to build for. Can be one of: '''x86, x86_64, all''', or '''noarch''', where '''''all''''' means all architectures, and '''''noarch''''' means it's architecture-independent (e.g., a pure-python package).
: {{Tip|To determine if your APKBUILD can use '''noarch''', first specify '''all''', build the package by running '''''abuild -r''''' and once built, execute '''''scanelf -R pkg'''''. This scans for ELF files in the ''./pkg'' directory, where all sub-/package files reside. If you do not get output from this, then '''noarch''' can be used.}}
===== depends =====
: Run-time dependency package(s) that are not shared-object dependencies. Shared objects dependencies are auto-detected and should not be specified here.
===== depends_dev =====
: Run-time dependency package(s) for the '''$pkgname-dev''' subpackage.
===== install =====
: Pre/Post- Install/Upgrade/Deinstall scripts. These are used to provide additional help when installing/upgrading/deinstalling a package, and are named '''$pkgname.{pre,post}-{install,upgrade,deinstall}'''. For example, if ''pkgname'' is set to '''mypackage''' and ''install'' is set to '''$pkgname.post-install''', then a script named '''mypackage.post-install''' must exist along-side the APKBUILD.
===== license =====
: License(s) for the package.
===== makedepends =====
: Build-time dependency package(s).
===== md5sums =====
: Checksums for the files/URLs listed in ''source''. The checksums are normally generated by executing '''''abuild checksum''''' and should be the last item in the APKBUILD.
===== options =====
: Build-time options for the package. Can be: '''!strip''' - to avoid stripping symbols from binaries.
===== pkgdesc =====
: Short description of the package.
===== pkggroups =====
: System group(s) to be created during build-time. System group(s) should also be created in a '''$pkgname.pre-install''' script, so that the system group(s) are also created prior to package installation for run-time use.
===== pkgname =====
: The name of the package. All letters should be lowercase.
: {{Tip|When creating an APKBUILD of a module or library for another package, we use some common package prefixes, such as: ''lua-'', ''perl-'', ''php-'', and ''py-''. Search aports for other common prefixes.}}
===== pkgrel =====
: Alpine package release number. Starts at 0 (zero). Always increment ''pkgrel'' when making updates to an aport; reset ''pkgrel'' to 0 (zero) when incrementing ''pkgver''.
===== pkgusers =====
: System user(s) to be created during build-time. System user(s) should also be created in a '''$pkgname.pre-install''' script, so that the system user(s) are also created prior to package installation for run-time use.
===== pkgver =====
: The version of the software being packaged.
===== replaces =====
: Package(s) that this package replaces. This package will "take over" files owned by packages listed in the ''replaces'' variable. This is useful when files move from one sub-/package to another, or when a package gets renamed.
===== source =====
: URL(s) to sources and patches. It can also list local files included along-side the APKBUILD, such as patches, init.d scripts, conf.d files, etc.
===== subpackages =====
: Subpackages built from this APKBUILD. Subpackages are usually prefixed with '''$pkgname-''', with the remainder of the subpackage name being used as the name of the package function for the subpackage. For example, if ''subpackages'' is set to '''$pkgname-extra''', this will create a subpackage called '''''$pkgname''-extra''', which is packaged using a custom ''extra()'' function. (See the [[APKBUILD Reference#Subpackages|Subpackages]] section below for more information.)
===== url =====
: The homepage for the package. This is to help users find upstream documentation and other information regarding the package.

{{Tip|All custom user-specified variables and functions should be prefixed with an underscore character ( _ ) to avoid name clashes with the internals of abuild (i.e., ''_builddir'').}}

= Functions =
{{Note|All functions should consider the current working directory as undefined, and should therefore use the [[APKBUILD Reference#abuild-defined_variables|abuild-defined directory variables]] to their advantage.}}

== abuild-defined functions ==
The following functions are provided by abuild and can be overridden:

===== fetch() =====
: Downloads remote sources listed in ''source'' to ''SRCDEST'' (''SRCDEST'' is configured in ''/etc/abuild.conf'') and creates symlinks in ''$srcdir''.
===== unpack() =====
: Unpacks .tgz, .tar.gz, .tar.bz2, .tar.lzma, .tar.xz, and .zip archives in ''$srcdir'' to ''$srcdir''.
===== dev() =====
: Subpackage function for the '''$pkgname-dev''' package. Without specifying a custom ''dev()'' function, abuild will call it's internal ''dev()'' function, which in turn calls ''default_dev()'', which will move ''"$pkgdir"/usr/include'', ''*.a'', ''*.la'' and similar files to ''$subpkgdir''.
===== doc() =====
: Subpackage function for the '''$pkgname-doc''' package. Without specifying a custom ''doc()'' function, abuild will call it's internal ''doc()'' function, which in turn calls ''default_doc()'', which will move ''"$pkgdir"/usr/share/doc'', ''"$pkgdir"/usr/share/man'' and similar to ''$subpkgdir''.

== User-defined functions ==
The following functions should be defined by the user:

===== prepare() =====
: '''''Optional''.''' Used for build preparation: patches, etc, should be applied here. This function is available for your convenience.
===== build() =====
: '''Required.''' This is the compilation stage. This function will be called as the current user (unless the ''package()'' function is missing - for compatibility reasons). If no compilation is needed, this function can contain a single line: '''return 0'''
===== package() =====
: '''Required.''' This is the packaging stage. Here, the built application and support files should be installed into '''$pkgdir'''. If this is a metapackage, this function can contain a single line: '''return 0'''

{{Note|Building in fakeroot will reduce performance for parallel builds dramatically. It is for this reason that we split the build and package process into two separate functions.}}

= Subpackages =
Subpackages are specified in the ''subpackages'' variable. abuild will parse this variable and try to find a subpackage split function. The split function must ''move'' files that do not belong in the main package, from ''$pkgdir'' to ''$subpkgdir''. Files and directories can also be ''copied'' from ''$startdir'' and ''$srcdir'' to ''$subpkgdir''.

The split function can be specified in 1 of 3 different ways:
# subpkgname:'''splitfunc'''
# $pkgname-'''splitfunc'''
# '''splitfunc'''

== Subpackages Example ==
The following APKBUILD snippet:
pkgname="foo"
subpackages="$pkgname-dev $pkgname-doc py-$pkgname:pysub libfoo"

... will create the 5 packages in total:
# foo (main)
# foo-dev (sub)
# foo-doc (sub)
# py-foo (sub)
# libfoo (sub)

The split functions for the 4 subpackages are:
# ''dev()'' (provided by abuild)
# ''doc()'' (provided by abuild)
# ''pysub()'' (provided by the user)
# ''libfoo()'' (provided by the user)

= Examples =
Simple APKBUILD with -doc subpackage, using abuild's default ''doc()'' function:
<pre>
# Maintainer: Natanael Copa <ncopa@alpinelinux.org>
pkgname=m4
pkgver=1.4.15
pkgrel=0
pkgdesc="GNU macro processor"
url="http://www.gnu.org/software/m4"
depends=
arch="all"
license="GPL"
subpackages="m4-doc"
source="ftp://ftp.gnu.org/gnu/m4/$pkgname-$pkgver.tar.gz
gnulib-uclibc.patch"

_builddir="$srcdir"/$pkgname-$pkgver
prepare() {
cd "$_builddir"
patch -p1 -i "$srcdir"/gnulib-uclibc.patch
}

build() {
cd "$_builddir"
./configure --prefix=/usr
make
}

package() {
cd "$_builddir"
make install DESTDIR="$pkgdir"
}

md5sums="5649a2e593b6c639deae9e72ede777dd m4-1.4.15.tar.gz
20a7dedec0e9e0ee7107e33e798ffdbe gnulib-uclibc.patch"
</pre>

A more complex APKBUILD with -doc, -dev and python subpackages:
<pre>
# Contributor: Carlo Landmeter <clandmeter at gmail>
# Maintainer: Carlo Landmeter <clandmeter at gmail>
pkgname=libxml2
pkgver=2.7.8
pkgrel=0
pkgdesc="XML parsing library, version 2"
url="http://www.xmlsoft.org/"
arch="all"
license="MIT"
depends=
depends_dev="zlib-dev python-dev"
makedepends="zlib-dev python-dev"
subpackages="$pkgname-doc $pkgname-dev py-$pkgname:py $pkgname-utils"
source="ftp://ftp.xmlsoft.org/${pkgname}/${pkgname}-${pkgver}.tar.gz
largefile64.patch"

options="!strip"

_builddir="$srcdir/$pkgname-$pkgver"
prepare() {
cd "$_builddir"
for _i in "$srcdir"/*.patch; do
patch -p1 -i "$_i"
done
}

build() {
cd "$_builddir"
./configure --prefix=/usr \
--sysconfdir=/etc \
--mandir=/usr/share/man \
--infodir=/usr/share/info
make
}

package() {
cd "$_builddir"
make -j1 DESTDIR="$pkgdir" install
install -Dm644 COPYING "$pkgdir"/usr/share/licenses/$pkgname/COPYING
}

py() {
cd "$_builddir"
pkgdesc="$pkgname python bindings"
install -d "$subpkgdir"/usr/lib
mv "$pkgdir"/usr/lib/python* "$subpkgdir"/usr/lib/
}

utils() {
pkgdesc="XML utilities"
replaces="libxml2"
mkdir -p "$subpkgdir"/usr
mv "$pkgdir"/usr/bin "$subpkgdir"/usr/
}

md5sums="8127a65e8c3b08856093099b52599c86 libxml2-2.7.8.tar.gz
5ad4915665608ebfa5b89f7908467a72 largefile64.patch"
</pre>

APKBUILD Reference

2011-01-13T04:10:38Z

Mattx86: /* package() */ updated wording

APKBUILDs are the scripts that are created in order to build Alpine packages using the [[abuild]] tool.

This page is intended to serve as a quick reference for creating APKBUILDs; if this is your first time creating a package for Alpine Linux, please see [[Creating an Alpine package]].

= Legend =
The following notes will assist you in understanding this document.

* If a variable is not prefixed with a ''$'', it will be represented by italics (i.e., ''srcdir'' ).
* Functions will also be represented by italics, but will also end with a pair of parentheses (i.e., ''build()'' ).
* Shell commands will be represented by italics and bold type (i.e., '''''abuild checksum''''').

= Variables =
{{Note|Variables that contain a path (e.g. ''$srcdir'' and ''$pkgdir'') should always be quoted using double quotes (i.e., ''"$srcdir"''). This is done to prevent things from breaking, should the user have the APKBUILD in a directory path that contains spaces.}}

== abuild-defined variables ==
The following variables are defined by abuild:

===== startdir =====
: The directory where the APKBUILD script is.
===== srcdir =====
: The directory where sources, from the ''source'' variable, are downloaded to and unpacked to.
===== pkgdir =====
: This directory should contain the files for the main package. For example, a normal [http://en.wikipedia.org/wiki/GNU_build_system autotools] package would have '''''make DESTDIR="$pkgdir" install''''' in the ''package()'' function.
===== subpkgdir =====
: This directory should contain the files for a subpackage. This variable should only be used from subpackage functions.

== User-defined variables ==
The following variables should be defined by the user:
===== arch =====
: Package architecture(s) to build for. Can be one of: '''x86, x86_64, all''', or '''noarch''', where '''''all''''' means all architectures, and '''''noarch''''' means it's architecture-independent (e.g., a pure-python package).
: {{Tip|To determine if your APKBUILD can use '''noarch''', first specify '''all''', build the package by running '''''abuild -r''''' and once built, execute '''''scanelf -R pkg'''''. This scans for ELF files in the ''./pkg'' directory, where all sub-/package files reside. If you do not get output from this, then '''noarch''' can be used.}}
===== depends =====
: Run-time dependency package(s) that are not shared-object dependencies. Shared objects dependencies are auto-detected and should not be specified here.
===== depends_dev =====
: Run-time dependency package(s) for the '''$pkgname-dev''' subpackage.
===== install =====
: Pre/Post- Install/Upgrade/Deinstall scripts. These are used to provide additional help when installing/upgrading/deinstalling a package, and are named '''$pkgname.{pre,post}-{install,upgrade,deinstall}'''. For example, if ''pkgname'' is set to '''mypackage''' and ''install'' is set to '''$pkgname.post-install''', then a script named '''mypackage.post-install''' must exist along-side the APKBUILD.
===== license =====
: License(s) for the package.
===== makedepends =====
: Build-time dependency package(s).
===== md5sums =====
: Checksums for the files/URLs listed in ''source''. The checksums are normally generated by executing '''''abuild checksum''''' and should be the last item in the APKBUILD.
===== options =====
: Build-time options for the package. Can be: '''!strip''' - to avoid stripping symbols from binaries.
===== pkgdesc =====
: Short description of the package.
===== pkggroups =====
: System group(s) to be created during build-time. System group(s) should also be created in a '''$pkgname.pre-install''' script, so that the system group(s) are also created prior to package installation for run-time use.
===== pkgname =====
: The name of the package. All letters should be lowercase.
: {{Tip|When creating an APKBUILD of a module or library for another package, we use some common package prefixes, such as: ''lua-'', ''perl-'', ''php-'', and ''py-''. Search aports for other common prefixes.}}
===== pkgrel =====
: Alpine package release number. Starts at 0 (zero). Always increment ''pkgrel'' when making updates to an aport; reset ''pkgrel'' to 0 (zero) when incrementing ''pkgver''.
===== pkgusers =====
: System user(s) to be created during build-time. System user(s) should also be created in a '''$pkgname.pre-install''' script, so that the system user(s) are also created prior to package installation for run-time use.
===== pkgver =====
: The version of the software being packaged.
===== replaces =====
: Package(s) that this package replaces. This package will "take over" files owned by packages listed in the ''replaces'' variable. This is useful when files move from one sub-/package to another, or when a package gets renamed.
===== source =====
: URL(s) to sources and patches. It can also list local files included along-side the APKBUILD, such as patches, init.d scripts, conf.d files, etc.
===== subpackages =====
: Subpackages built from this APKBUILD. Subpackages are usually prefixed with '''$pkgname-''', with the remainder of the subpackage name being used as the name of the package function for the subpackage. For example, if ''subpackages'' is set to '''$pkgname-extra''', this will create a subpackage called '''''$pkgname''-extra''', which is packaged using a custom ''extra()'' function. (See the [[APKBUILD Reference#Subpackages|Subpackages]] section below for more information.)
===== url =====
: The homepage for the package. This is to help users find upstream documentation and other information regarding the package.

{{Tip|All custom user-specified variables and functions should be prefixed with an underscore character ( _ ) to avoid name clashes with the internals of abuild (i.e., ''_builddir'').}}

= Functions =
{{Note|All functions should consider the current working directory as undefined, and therefore should use the [[APKBUILD Reference#abuild-defined_variables|abuild-defined directory variables]] to their advantage.}}

== abuild-defined functions ==
The following functions are provided by abuild and can be overridden:

===== fetch() =====
: Downloads remote sources listed in ''source'' to ''SRCDEST'' (''SRCDEST'' is configured in ''/etc/abuild.conf'') and creates symlinks in ''$srcdir''.
===== unpack() =====
: Unpacks .tgz, .tar.gz, .tar.bz2, .tar.lzma, .tar.xz, and .zip archives in ''$srcdir'' to ''$srcdir''.
===== dev() =====
: Subpackage function for the '''$pkgname-dev''' package. Without specifying a custom ''dev()'' function, abuild will call it's internal ''dev()'' function, which in turn calls ''default_dev()'', which will move ''"$pkgdir"/usr/include'', ''*.a'', ''*.la'' and similar files to ''$subpkgdir''.
===== doc() =====
: Subpackage function for the '''$pkgname-doc''' package. Without specifying a custom ''doc()'' function, abuild will call it's internal ''doc()'' function, which in turn calls ''default_doc()'', which will move ''"$pkgdir"/usr/share/doc'', ''"$pkgdir"/usr/share/man'' and similar to ''$subpkgdir''.

== User-defined functions ==
The following functions should be defined by the user:

===== prepare() =====
: '''''Optional''.''' Used for build preparation: patches, etc, should be applied here. This function is available for your convenience.
===== build() =====
: '''Required.''' This is the compilation stage. This function will be called as the current user (unless the ''package()'' function is missing - for compatibility reasons). If no compilation is needed, this function can contain a single line: '''return 0'''
===== package() =====
: '''Required.''' This is the packaging stage. Here, the built application and support files should be installed into '''$pkgdir'''. If this is a metapackage, this function can contain a single line: '''return 0'''

{{Note|Building in fakeroot will reduce performance for parallel builds dramatically. It is for this reason that we split the build and package process into two separate functions.}}

= Subpackages =
Subpackages are specified in the ''subpackages'' variable. abuild will parse this variable and try to find a subpackage split function. The split function must ''move'' files that do not belong in the main package, from ''$pkgdir'' to ''$subpkgdir''. Files and directories can also be ''copied'' from ''$startdir'' and ''$srcdir'' to ''$subpkgdir''.

The split function can be specified in 1 of 3 different ways:
# subpkgname:'''splitfunc'''
# $pkgname-'''splitfunc'''
# '''splitfunc'''

== Subpackages Example ==
The following APKBUILD snippet:
pkgname="foo"
subpackages="$pkgname-dev $pkgname-doc py-$pkgname:pysub libfoo"

... will create the 5 packages in total:
# foo (main)
# foo-dev (sub)
# foo-doc (sub)
# py-foo (sub)
# libfoo (sub)

The split functions for the 4 subpackages are:
# ''dev()'' (provided by abuild)
# ''doc()'' (provided by abuild)
# ''pysub()'' (provided by the user)
# ''libfoo()'' (provided by the user)

= Examples =
Simple APKBUILD with -doc subpackage, using abuild's default ''doc()'' function:
<pre>
# Maintainer: Natanael Copa <ncopa@alpinelinux.org>
pkgname=m4
pkgver=1.4.15
pkgrel=0
pkgdesc="GNU macro processor"
url="http://www.gnu.org/software/m4"
depends=
arch="all"
license="GPL"
subpackages="m4-doc"
source="ftp://ftp.gnu.org/gnu/m4/$pkgname-$pkgver.tar.gz
gnulib-uclibc.patch"

_builddir="$srcdir"/$pkgname-$pkgver
prepare() {
cd "$_builddir"
patch -p1 -i "$srcdir"/gnulib-uclibc.patch
}

build() {
cd "$_builddir"
./configure --prefix=/usr
make
}

package() {
cd "$_builddir"
make install DESTDIR="$pkgdir"
}

md5sums="5649a2e593b6c639deae9e72ede777dd m4-1.4.15.tar.gz
20a7dedec0e9e0ee7107e33e798ffdbe gnulib-uclibc.patch"
</pre>

A more complex APKBUILD with -doc, -dev and python subpackages:
<pre>
# Contributor: Carlo Landmeter <clandmeter at gmail>
# Maintainer: Carlo Landmeter <clandmeter at gmail>
pkgname=libxml2
pkgver=2.7.8
pkgrel=0
pkgdesc="XML parsing library, version 2"
url="http://www.xmlsoft.org/"
arch="all"
license="MIT"
depends=
depends_dev="zlib-dev python-dev"
makedepends="zlib-dev python-dev"
subpackages="$pkgname-doc $pkgname-dev py-$pkgname:py $pkgname-utils"
source="ftp://ftp.xmlsoft.org/${pkgname}/${pkgname}-${pkgver}.tar.gz
largefile64.patch"

options="!strip"

_builddir="$srcdir/$pkgname-$pkgver"
prepare() {
cd "$_builddir"
for _i in "$srcdir"/*.patch; do
patch -p1 -i "$_i"
done
}

build() {
cd "$_builddir"
./configure --prefix=/usr \
--sysconfdir=/etc \
--mandir=/usr/share/man \
--infodir=/usr/share/info
make
}

package() {
cd "$_builddir"
make -j1 DESTDIR="$pkgdir" install
install -Dm644 COPYING "$pkgdir"/usr/share/licenses/$pkgname/COPYING
}

py() {
cd "$_builddir"
pkgdesc="$pkgname python bindings"
install -d "$subpkgdir"/usr/lib
mv "$pkgdir"/usr/lib/python* "$subpkgdir"/usr/lib/
}

utils() {
pkgdesc="XML utilities"
replaces="libxml2"
mkdir -p "$subpkgdir"/usr
mv "$pkgdir"/usr/bin "$subpkgdir"/usr/
}

md5sums="8127a65e8c3b08856093099b52599c86 libxml2-2.7.8.tar.gz
5ad4915665608ebfa5b89f7908467a72 largefile64.patch"
</pre>

APKBUILD Reference

2011-01-13T04:05:40Z

Mattx86: /* User-defined functions */ Added information to package() about metapackages

APKBUILDs are the scripts that are created in order to build Alpine packages using the [[abuild]] tool.

This page is intended to serve as a quick reference for creating APKBUILDs; if this is your first time creating a package for Alpine Linux, please see [[Creating an Alpine package]].

= Legend =
The following notes will assist you in understanding this document.

* If a variable is not prefixed with a ''$'', it will be represented by italics (i.e., ''srcdir'' ).
* Functions will also be represented by italics, but will also end with a pair of parentheses (i.e., ''build()'' ).
* Shell commands will be represented by italics and bold type (i.e., '''''abuild checksum''''').

= Variables =
{{Note|Variables that contain a path (e.g. ''$srcdir'' and ''$pkgdir'') should always be quoted using double quotes (i.e., ''"$srcdir"''). This is done to prevent things from breaking, should the user have the APKBUILD in a directory path that contains spaces.}}

== abuild-defined variables ==
The following variables are defined by abuild:

===== startdir =====
: The directory where the APKBUILD script is.
===== srcdir =====
: The directory where sources, from the ''source'' variable, are downloaded to and unpacked to.
===== pkgdir =====
: This directory should contain the files for the main package. For example, a normal [http://en.wikipedia.org/wiki/GNU_build_system autotools] package would have '''''make DESTDIR="$pkgdir" install''''' in the ''package()'' function.
===== subpkgdir =====
: This directory should contain the files for a subpackage. This variable should only be used from subpackage functions.

== User-defined variables ==
The following variables should be defined by the user:
===== arch =====
: Package architecture(s) to build for. Can be one of: '''x86, x86_64, all''', or '''noarch''', where '''''all''''' means all architectures, and '''''noarch''''' means it's architecture-independent (e.g., a pure-python package).
: {{Tip|To determine if your APKBUILD can use '''noarch''', first specify '''all''', build the package by running '''''abuild -r''''' and once built, execute '''''scanelf -R pkg'''''. This scans for ELF files in the ''./pkg'' directory, where all sub-/package files reside. If you do not get output from this, then '''noarch''' can be used.}}
===== depends =====
: Run-time dependency package(s) that are not shared-object dependencies. Shared objects dependencies are auto-detected and should not be specified here.
===== depends_dev =====
: Run-time dependency package(s) for the '''$pkgname-dev''' subpackage.
===== install =====
: Pre/Post- Install/Upgrade/Deinstall scripts. These are used to provide additional help when installing/upgrading/deinstalling a package, and are named '''$pkgname.{pre,post}-{install,upgrade,deinstall}'''. For example, if ''pkgname'' is set to '''mypackage''' and ''install'' is set to '''$pkgname.post-install''', then a script named '''mypackage.post-install''' must exist along-side the APKBUILD.
===== license =====
: License(s) for the package.
===== makedepends =====
: Build-time dependency package(s).
===== md5sums =====
: Checksums for the files/URLs listed in ''source''. The checksums are normally generated by executing '''''abuild checksum''''' and should be the last item in the APKBUILD.
===== options =====
: Build-time options for the package. Can be: '''!strip''' - to avoid stripping symbols from binaries.
===== pkgdesc =====
: Short description of the package.
===== pkggroups =====
: System group(s) to be created during build-time. System group(s) should also be created in a '''$pkgname.pre-install''' script, so that the system group(s) are also created prior to package installation for run-time use.
===== pkgname =====
: The name of the package. All letters should be lowercase.
: {{Tip|When creating an APKBUILD of a module or library for another package, we use some common package prefixes, such as: ''lua-'', ''perl-'', ''php-'', and ''py-''. Search aports for other common prefixes.}}
===== pkgrel =====
: Alpine package release number. Starts at 0 (zero). Always increment ''pkgrel'' when making updates to an aport; reset ''pkgrel'' to 0 (zero) when incrementing ''pkgver''.
===== pkgusers =====
: System user(s) to be created during build-time. System user(s) should also be created in a '''$pkgname.pre-install''' script, so that the system user(s) are also created prior to package installation for run-time use.
===== pkgver =====
: The version of the software being packaged.
===== replaces =====
: Package(s) that this package replaces. This package will "take over" files owned by packages listed in the ''replaces'' variable. This is useful when files move from one sub-/package to another, or when a package gets renamed.
===== source =====
: URL(s) to sources and patches. It can also list local files included along-side the APKBUILD, such as patches, init.d scripts, conf.d files, etc.
===== subpackages =====
: Subpackages built from this APKBUILD. Subpackages are usually prefixed with '''$pkgname-''', with the remainder of the subpackage name being used as the name of the package function for the subpackage. For example, if ''subpackages'' is set to '''$pkgname-extra''', this will create a subpackage called '''''$pkgname''-extra''', which is packaged using a custom ''extra()'' function. (See the [[APKBUILD Reference#Subpackages|Subpackages]] section below for more information.)
===== url =====
: The homepage for the package. This is to help users find upstream documentation and other information regarding the package.

{{Tip|All custom user-specified variables and functions should be prefixed with an underscore character ( _ ) to avoid name clashes with the internals of abuild (i.e., ''_builddir'').}}

= Functions =
{{Note|All functions should consider the current working directory as undefined, and therefore should use the [[APKBUILD Reference#abuild-defined_variables|abuild-defined directory variables]] to their advantage.}}

== abuild-defined functions ==
The following functions are provided by abuild and can be overridden:

===== fetch() =====
: Downloads remote sources listed in ''source'' to ''SRCDEST'' (''SRCDEST'' is configured in ''/etc/abuild.conf'') and creates symlinks in ''$srcdir''.
===== unpack() =====
: Unpacks .tgz, .tar.gz, .tar.bz2, .tar.lzma, .tar.xz, and .zip archives in ''$srcdir'' to ''$srcdir''.
===== dev() =====
: Subpackage function for the '''$pkgname-dev''' package. Without specifying a custom ''dev()'' function, abuild will call it's internal ''dev()'' function, which in turn calls ''default_dev()'', which will move ''"$pkgdir"/usr/include'', ''*.a'', ''*.la'' and similar files to ''$subpkgdir''.
===== doc() =====
: Subpackage function for the '''$pkgname-doc''' package. Without specifying a custom ''doc()'' function, abuild will call it's internal ''doc()'' function, which in turn calls ''default_doc()'', which will move ''"$pkgdir"/usr/share/doc'', ''"$pkgdir"/usr/share/man'' and similar to ''$subpkgdir''.

== User-defined functions ==
The following functions should be defined by the user:

===== prepare() =====
: '''''Optional''.''' Used for build preparation: patches, etc, should be applied here. This function is available for your convenience.
===== build() =====
: '''Required.''' This is the compilation stage. This function will be called as the current user (unless the ''package()'' function is missing - for compatibility reasons). If no compilation is needed, this function can contain a single line: '''return 0'''
===== package() =====
: '''Required.''' This is the packaging stage. This is where the built application and support files should be installed in '''$pkgdir'''. If this is a metapackage, this function can contain a single line: '''return 0'''

{{Note|Building in fakeroot will reduce performance for parallel builds dramatically. It is for this reason that we split the build and package process into two separate functions.}}

= Subpackages =
Subpackages are specified in the ''subpackages'' variable. abuild will parse this variable and try to find a subpackage split function. The split function must ''move'' files that do not belong in the main package, from ''$pkgdir'' to ''$subpkgdir''. Files and directories can also be ''copied'' from ''$startdir'' and ''$srcdir'' to ''$subpkgdir''.

The split function can be specified in 1 of 3 different ways:
# subpkgname:'''splitfunc'''
# $pkgname-'''splitfunc'''
# '''splitfunc'''

== Subpackages Example ==
The following APKBUILD snippet:
pkgname="foo"
subpackages="$pkgname-dev $pkgname-doc py-$pkgname:pysub libfoo"

... will create the 5 packages in total:
# foo (main)
# foo-dev (sub)
# foo-doc (sub)
# py-foo (sub)
# libfoo (sub)

The split functions for the 4 subpackages are:
# ''dev()'' (provided by abuild)
# ''doc()'' (provided by abuild)
# ''pysub()'' (provided by the user)
# ''libfoo()'' (provided by the user)

= Examples =
Simple APKBUILD with -doc subpackage, using abuild's default ''doc()'' function:
<pre>
# Maintainer: Natanael Copa <ncopa@alpinelinux.org>
pkgname=m4
pkgver=1.4.15
pkgrel=0
pkgdesc="GNU macro processor"
url="http://www.gnu.org/software/m4"
depends=
arch="all"
license="GPL"
subpackages="m4-doc"
source="ftp://ftp.gnu.org/gnu/m4/$pkgname-$pkgver.tar.gz
gnulib-uclibc.patch"

_builddir="$srcdir"/$pkgname-$pkgver
prepare() {
cd "$_builddir"
patch -p1 -i "$srcdir"/gnulib-uclibc.patch
}

build() {
cd "$_builddir"
./configure --prefix=/usr
make
}

package() {
cd "$_builddir"
make install DESTDIR="$pkgdir"
}

md5sums="5649a2e593b6c639deae9e72ede777dd m4-1.4.15.tar.gz
20a7dedec0e9e0ee7107e33e798ffdbe gnulib-uclibc.patch"
</pre>

A more complex APKBUILD with -doc, -dev and python subpackages:
<pre>
# Contributor: Carlo Landmeter <clandmeter at gmail>
# Maintainer: Carlo Landmeter <clandmeter at gmail>
pkgname=libxml2
pkgver=2.7.8
pkgrel=0
pkgdesc="XML parsing library, version 2"
url="http://www.xmlsoft.org/"
arch="all"
license="MIT"
depends=
depends_dev="zlib-dev python-dev"
makedepends="zlib-dev python-dev"
subpackages="$pkgname-doc $pkgname-dev py-$pkgname:py $pkgname-utils"
source="ftp://ftp.xmlsoft.org/${pkgname}/${pkgname}-${pkgver}.tar.gz
largefile64.patch"

options="!strip"

_builddir="$srcdir/$pkgname-$pkgver"
prepare() {
cd "$_builddir"
for _i in "$srcdir"/*.patch; do
patch -p1 -i "$_i"
done
}

build() {
cd "$_builddir"
./configure --prefix=/usr \
--sysconfdir=/etc \
--mandir=/usr/share/man \
--infodir=/usr/share/info
make
}

package() {
cd "$_builddir"
make -j1 DESTDIR="$pkgdir" install
install -Dm644 COPYING "$pkgdir"/usr/share/licenses/$pkgname/COPYING
}

py() {
cd "$_builddir"
pkgdesc="$pkgname python bindings"
install -d "$subpkgdir"/usr/lib
mv "$pkgdir"/usr/lib/python* "$subpkgdir"/usr/lib/
}

utils() {
pkgdesc="XML utilities"
replaces="libxml2"
mkdir -p "$subpkgdir"/usr
mv "$pkgdir"/usr/bin "$subpkgdir"/usr/
}

md5sums="8127a65e8c3b08856093099b52599c86 libxml2-2.7.8.tar.gz
5ad4915665608ebfa5b89f7908467a72 largefile64.patch"
</pre>

APKBUILD Reference

2011-01-13T04:02:48Z

Mattx86: /* User-defined functions */

APKBUILDs are the scripts that are created in order to build Alpine packages using the [[abuild]] tool.

This page is intended to serve as a quick reference for creating APKBUILDs; if this is your first time creating a package for Alpine Linux, please see [[Creating an Alpine package]].

= Legend =
The following notes will assist you in understanding this document.

* If a variable is not prefixed with a ''$'', it will be represented by italics (i.e., ''srcdir'' ).
* Functions will also be represented by italics, but will also end with a pair of parentheses (i.e., ''build()'' ).
* Shell commands will be represented by italics and bold type (i.e., '''''abuild checksum''''').

= Variables =
{{Note|Variables that contain a path (e.g. ''$srcdir'' and ''$pkgdir'') should always be quoted using double quotes (i.e., ''"$srcdir"''). This is done to prevent things from breaking, should the user have the APKBUILD in a directory path that contains spaces.}}

== abuild-defined variables ==
The following variables are defined by abuild:

===== startdir =====
: The directory where the APKBUILD script is.
===== srcdir =====
: The directory where sources, from the ''source'' variable, are downloaded to and unpacked to.
===== pkgdir =====
: This directory should contain the files for the main package. For example, a normal [http://en.wikipedia.org/wiki/GNU_build_system autotools] package would have '''''make DESTDIR="$pkgdir" install''''' in the ''package()'' function.
===== subpkgdir =====
: This directory should contain the files for a subpackage. This variable should only be used from subpackage functions.

== User-defined variables ==
The following variables should be defined by the user:
===== arch =====
: Package architecture(s) to build for. Can be one of: '''x86, x86_64, all''', or '''noarch''', where '''''all''''' means all architectures, and '''''noarch''''' means it's architecture-independent (e.g., a pure-python package).
: {{Tip|To determine if your APKBUILD can use '''noarch''', first specify '''all''', build the package by running '''''abuild -r''''' and once built, execute '''''scanelf -R pkg'''''. This scans for ELF files in the ''./pkg'' directory, where all sub-/package files reside. If you do not get output from this, then '''noarch''' can be used.}}
===== depends =====
: Run-time dependency package(s) that are not shared-object dependencies. Shared objects dependencies are auto-detected and should not be specified here.
===== depends_dev =====
: Run-time dependency package(s) for the '''$pkgname-dev''' subpackage.
===== install =====
: Pre/Post- Install/Upgrade/Deinstall scripts. These are used to provide additional help when installing/upgrading/deinstalling a package, and are named '''$pkgname.{pre,post}-{install,upgrade,deinstall}'''. For example, if ''pkgname'' is set to '''mypackage''' and ''install'' is set to '''$pkgname.post-install''', then a script named '''mypackage.post-install''' must exist along-side the APKBUILD.
===== license =====
: License(s) for the package.
===== makedepends =====
: Build-time dependency package(s).
===== md5sums =====
: Checksums for the files/URLs listed in ''source''. The checksums are normally generated by executing '''''abuild checksum''''' and should be the last item in the APKBUILD.
===== options =====
: Build-time options for the package. Can be: '''!strip''' - to avoid stripping symbols from binaries.
===== pkgdesc =====
: Short description of the package.
===== pkggroups =====
: System group(s) to be created during build-time. System group(s) should also be created in a '''$pkgname.pre-install''' script, so that the system group(s) are also created prior to package installation for run-time use.
===== pkgname =====
: The name of the package. All letters should be lowercase.
: {{Tip|When creating an APKBUILD of a module or library for another package, we use some common package prefixes, such as: ''lua-'', ''perl-'', ''php-'', and ''py-''. Search aports for other common prefixes.}}
===== pkgrel =====
: Alpine package release number. Starts at 0 (zero). Always increment ''pkgrel'' when making updates to an aport; reset ''pkgrel'' to 0 (zero) when incrementing ''pkgver''.
===== pkgusers =====
: System user(s) to be created during build-time. System user(s) should also be created in a '''$pkgname.pre-install''' script, so that the system user(s) are also created prior to package installation for run-time use.
===== pkgver =====
: The version of the software being packaged.
===== replaces =====
: Package(s) that this package replaces. This package will "take over" files owned by packages listed in the ''replaces'' variable. This is useful when files move from one sub-/package to another, or when a package gets renamed.
===== source =====
: URL(s) to sources and patches. It can also list local files included along-side the APKBUILD, such as patches, init.d scripts, conf.d files, etc.
===== subpackages =====
: Subpackages built from this APKBUILD. Subpackages are usually prefixed with '''$pkgname-''', with the remainder of the subpackage name being used as the name of the package function for the subpackage. For example, if ''subpackages'' is set to '''$pkgname-extra''', this will create a subpackage called '''''$pkgname''-extra''', which is packaged using a custom ''extra()'' function. (See the [[APKBUILD Reference#Subpackages|Subpackages]] section below for more information.)
===== url =====
: The homepage for the package. This is to help users find upstream documentation and other information regarding the package.

{{Tip|All custom user-specified variables and functions should be prefixed with an underscore character ( _ ) to avoid name clashes with the internals of abuild (i.e., ''_builddir'').}}

= Functions =
{{Note|All functions should consider the current working directory as undefined, and therefore should use the [[APKBUILD Reference#abuild-defined_variables|abuild-defined directory variables]] to their advantage.}}

== abuild-defined functions ==
The following functions are provided by abuild and can be overridden:

===== fetch() =====
: Downloads remote sources listed in ''source'' to ''SRCDEST'' (''SRCDEST'' is configured in ''/etc/abuild.conf'') and creates symlinks in ''$srcdir''.
===== unpack() =====
: Unpacks .tgz, .tar.gz, .tar.bz2, .tar.lzma, .tar.xz, and .zip archives in ''$srcdir'' to ''$srcdir''.
===== dev() =====
: Subpackage function for the '''$pkgname-dev''' package. Without specifying a custom ''dev()'' function, abuild will call it's internal ''dev()'' function, which in turn calls ''default_dev()'', which will move ''"$pkgdir"/usr/include'', ''*.a'', ''*.la'' and similar files to ''$subpkgdir''.
===== doc() =====
: Subpackage function for the '''$pkgname-doc''' package. Without specifying a custom ''doc()'' function, abuild will call it's internal ''doc()'' function, which in turn calls ''default_doc()'', which will move ''"$pkgdir"/usr/share/doc'', ''"$pkgdir"/usr/share/man'' and similar to ''$subpkgdir''.

== User-defined functions ==
The following functions should be defined by the user:

===== prepare() =====
: '''''Optional''.''' Used for build preparation: patches, etc, should be applied here. This function is available for your convenience.
===== build() =====
: '''Required.''' This is the compilation stage. This function will be called as the current user (unless the ''package()'' function is missing - for compatibility reasons). If no compilation is needed, this function can contain a single line: '''return 0'''
===== package() =====
: '''Required.''' This is the packaging stage. This is where the built application and support files should be installed in '''$pkgdir'''.

{{Note|Building in fakeroot will reduce performance for parallel builds dramatically. It is for this reason that we split the build and package process into two separate functions.}}

= Subpackages =
Subpackages are specified in the ''subpackages'' variable. abuild will parse this variable and try to find a subpackage split function. The split function must ''move'' files that do not belong in the main package, from ''$pkgdir'' to ''$subpkgdir''. Files and directories can also be ''copied'' from ''$startdir'' and ''$srcdir'' to ''$subpkgdir''.

The split function can be specified in 1 of 3 different ways:
# subpkgname:'''splitfunc'''
# $pkgname-'''splitfunc'''
# '''splitfunc'''

== Subpackages Example ==
The following APKBUILD snippet:
pkgname="foo"
subpackages="$pkgname-dev $pkgname-doc py-$pkgname:pysub libfoo"

... will create the 5 packages in total:
# foo (main)
# foo-dev (sub)
# foo-doc (sub)
# py-foo (sub)
# libfoo (sub)

The split functions for the 4 subpackages are:
# ''dev()'' (provided by abuild)
# ''doc()'' (provided by abuild)
# ''pysub()'' (provided by the user)
# ''libfoo()'' (provided by the user)

= Examples =
Simple APKBUILD with -doc subpackage, using abuild's default ''doc()'' function:
<pre>
# Maintainer: Natanael Copa <ncopa@alpinelinux.org>
pkgname=m4
pkgver=1.4.15
pkgrel=0
pkgdesc="GNU macro processor"
url="http://www.gnu.org/software/m4"
depends=
arch="all"
license="GPL"
subpackages="m4-doc"
source="ftp://ftp.gnu.org/gnu/m4/$pkgname-$pkgver.tar.gz
gnulib-uclibc.patch"

_builddir="$srcdir"/$pkgname-$pkgver
prepare() {
cd "$_builddir"
patch -p1 -i "$srcdir"/gnulib-uclibc.patch
}

build() {
cd "$_builddir"
./configure --prefix=/usr
make
}

package() {
cd "$_builddir"
make install DESTDIR="$pkgdir"
}

md5sums="5649a2e593b6c639deae9e72ede777dd m4-1.4.15.tar.gz
20a7dedec0e9e0ee7107e33e798ffdbe gnulib-uclibc.patch"
</pre>

A more complex APKBUILD with -doc, -dev and python subpackages:
<pre>
# Contributor: Carlo Landmeter <clandmeter at gmail>
# Maintainer: Carlo Landmeter <clandmeter at gmail>
pkgname=libxml2
pkgver=2.7.8
pkgrel=0
pkgdesc="XML parsing library, version 2"
url="http://www.xmlsoft.org/"
arch="all"
license="MIT"
depends=
depends_dev="zlib-dev python-dev"
makedepends="zlib-dev python-dev"
subpackages="$pkgname-doc $pkgname-dev py-$pkgname:py $pkgname-utils"
source="ftp://ftp.xmlsoft.org/${pkgname}/${pkgname}-${pkgver}.tar.gz
largefile64.patch"

options="!strip"

_builddir="$srcdir/$pkgname-$pkgver"
prepare() {
cd "$_builddir"
for _i in "$srcdir"/*.patch; do
patch -p1 -i "$_i"
done
}

build() {
cd "$_builddir"
./configure --prefix=/usr \
--sysconfdir=/etc \
--mandir=/usr/share/man \
--infodir=/usr/share/info
make
}

package() {
cd "$_builddir"
make -j1 DESTDIR="$pkgdir" install
install -Dm644 COPYING "$pkgdir"/usr/share/licenses/$pkgname/COPYING
}

py() {
cd "$_builddir"
pkgdesc="$pkgname python bindings"
install -d "$subpkgdir"/usr/lib
mv "$pkgdir"/usr/lib/python* "$subpkgdir"/usr/lib/
}

utils() {
pkgdesc="XML utilities"
replaces="libxml2"
mkdir -p "$subpkgdir"/usr
mv "$pkgdir"/usr/bin "$subpkgdir"/usr/
}

md5sums="8127a65e8c3b08856093099b52599c86 libxml2-2.7.8.tar.gz
5ad4915665608ebfa5b89f7908467a72 largefile64.patch"
</pre>

APKBUILD Reference

2011-01-13T03:53:40Z

Mattx86: expanded TOC, updated some wording

APKBUILDs are the scripts that are created in order to build Alpine packages using the [[abuild]] tool.

This page is intended to serve as a quick reference for creating APKBUILDs; if this is your first time creating a package for Alpine Linux, please see [[Creating an Alpine package]].

= Legend =
The following notes will assist you in understanding this document.

* If a variable is not prefixed with a ''$'', it will be represented by italics (i.e., ''srcdir'' ).
* Functions will also be represented by italics, but will also end with a pair of parentheses (i.e., ''build()'' ).
* Shell commands will be represented by italics and bold type (i.e., '''''abuild checksum''''').

= Variables =
{{Note|Variables that contain a path (e.g. ''$srcdir'' and ''$pkgdir'') should always be quoted using double quotes (i.e., ''"$srcdir"''). This is done to prevent things from breaking, should the user have the APKBUILD in a directory path that contains spaces.}}

== abuild-defined variables ==
The following variables are defined by abuild:

===== startdir =====
: The directory where the APKBUILD script is.
===== srcdir =====
: The directory where sources, from the ''source'' variable, are downloaded to and unpacked to.
===== pkgdir =====
: This directory should contain the files for the main package. For example, a normal [http://en.wikipedia.org/wiki/GNU_build_system autotools] package would have '''''make DESTDIR="$pkgdir" install''''' in the ''package()'' function.
===== subpkgdir =====
: This directory should contain the files for a subpackage. This variable should only be used from subpackage functions.

== User-defined variables ==
The following variables should be defined by the user:
===== arch =====
: Package architecture(s) to build for. Can be one of: '''x86, x86_64, all''', or '''noarch''', where '''''all''''' means all architectures, and '''''noarch''''' means it's architecture-independent (e.g., a pure-python package).
: {{Tip|To determine if your APKBUILD can use '''noarch''', first specify '''all''', build the package by running '''''abuild -r''''' and once built, execute '''''scanelf -R pkg'''''. This scans for ELF files in the ''./pkg'' directory, where all sub-/package files reside. If you do not get output from this, then '''noarch''' can be used.}}
===== depends =====
: Run-time dependency package(s) that are not shared-object dependencies. Shared objects dependencies are auto-detected and should not be specified here.
===== depends_dev =====
: Run-time dependency package(s) for the '''$pkgname-dev''' subpackage.
===== install =====
: Pre/Post- Install/Upgrade/Deinstall scripts. These are used to provide additional help when installing/upgrading/deinstalling a package, and are named '''$pkgname.{pre,post}-{install,upgrade,deinstall}'''. For example, if ''pkgname'' is set to '''mypackage''' and ''install'' is set to '''$pkgname.post-install''', then a script named '''mypackage.post-install''' must exist along-side the APKBUILD.
===== license =====
: License(s) for the package.
===== makedepends =====
: Build-time dependency package(s).
===== md5sums =====
: Checksums for the files/URLs listed in ''source''. The checksums are normally generated by executing '''''abuild checksum''''' and should be the last item in the APKBUILD.
===== options =====
: Build-time options for the package. Can be: '''!strip''' - to avoid stripping symbols from binaries.
===== pkgdesc =====
: Short description of the package.
===== pkggroups =====
: System group(s) to be created during build-time. System group(s) should also be created in a '''$pkgname.pre-install''' script, so that the system group(s) are also created prior to package installation for run-time use.
===== pkgname =====
: The name of the package. All letters should be lowercase.
: {{Tip|When creating an APKBUILD of a module or library for another package, we use some common package prefixes, such as: ''lua-'', ''perl-'', ''php-'', and ''py-''. Search aports for other common prefixes.}}
===== pkgrel =====
: Alpine package release number. Starts at 0 (zero). Always increment ''pkgrel'' when making updates to an aport; reset ''pkgrel'' to 0 (zero) when incrementing ''pkgver''.
===== pkgusers =====
: System user(s) to be created during build-time. System user(s) should also be created in a '''$pkgname.pre-install''' script, so that the system user(s) are also created prior to package installation for run-time use.
===== pkgver =====
: The version of the software being packaged.
===== replaces =====
: Package(s) that this package replaces. This package will "take over" files owned by packages listed in the ''replaces'' variable. This is useful when files move from one sub-/package to another, or when a package gets renamed.
===== source =====
: URL(s) to sources and patches. It can also list local files included along-side the APKBUILD, such as patches, init.d scripts, conf.d files, etc.
===== subpackages =====
: Subpackages built from this APKBUILD. Subpackages are usually prefixed with '''$pkgname-''', with the remainder of the subpackage name being used as the name of the package function for the subpackage. For example, if ''subpackages'' is set to '''$pkgname-extra''', this will create a subpackage called '''''$pkgname''-extra''', which is packaged using a custom ''extra()'' function. (See the [[APKBUILD Reference#Subpackages|Subpackages]] section below for more information.)
===== url =====
: The homepage for the package. This is to help users find upstream documentation and other information regarding the package.

{{Tip|All custom user-specified variables and functions should be prefixed with an underscore character ( _ ) to avoid name clashes with the internals of abuild (i.e., ''_builddir'').}}

= Functions =
{{Note|All functions should consider the current working directory as undefined, and therefore should use the [[APKBUILD Reference#abuild-defined_variables|abuild-defined directory variables]] to their advantage.}}

== abuild-defined functions ==
The following functions are provided by abuild and can be overridden:

===== fetch() =====
: Downloads remote sources listed in ''source'' to ''SRCDEST'' (''SRCDEST'' is configured in ''/etc/abuild.conf'') and creates symlinks in ''$srcdir''.
===== unpack() =====
: Unpacks .tgz, .tar.gz, .tar.bz2, .tar.lzma, .tar.xz, and .zip archives in ''$srcdir'' to ''$srcdir''.
===== dev() =====
: Subpackage function for the '''$pkgname-dev''' package. Without specifying a custom ''dev()'' function, abuild will call it's internal ''dev()'' function, which in turn calls ''default_dev()'', which will move ''"$pkgdir"/usr/include'', ''*.a'', ''*.la'' and similar files to ''$subpkgdir''.
===== doc() =====
: Subpackage function for the '''$pkgname-doc''' package. Without specifying a custom ''doc()'' function, abuild will call it's internal ''doc()'' function, which in turn calls ''default_doc()'', which will move ''"$pkgdir"/usr/share/doc'', ''"$pkgdir"/usr/share/man'' and similar to ''$subpkgdir''.

== User-defined functions ==
===== prepare() =====
: '''''Optional''.''' Used for build preparation: patches, etc, should be applied here. This function is available for your convenience.
===== build() =====
: '''Required.''' This is the compilation stage. This function will be called as the current user (unless the ''package()'' function is missing - for compatibility reasons). If no compilation is needed, this function can contain a single line: '''return 0'''
===== package() =====
: '''Required.''' This is the packaging stage. This is where the built application and support files should be installed in '''$pkgdir'''.

{{Note|Building in fakeroot will reduce performance for parallel builds dramatically. It is for this reason that we split the build and package process into two separate functions.}}

= Subpackages =
Subpackages are specified in the ''subpackages'' variable. abuild will parse this variable and try to find a subpackage split function. The split function must ''move'' files that do not belong in the main package, from ''$pkgdir'' to ''$subpkgdir''. Files and directories can also be ''copied'' from ''$startdir'' and ''$srcdir'' to ''$subpkgdir''.

The split function can be specified in 1 of 3 different ways:
# subpkgname:'''splitfunc'''
# $pkgname-'''splitfunc'''
# '''splitfunc'''

== Subpackages Example ==
The following APKBUILD snippet:
pkgname="foo"
subpackages="$pkgname-dev $pkgname-doc py-$pkgname:pysub libfoo"

... will create the 5 packages in total:
# foo (main)
# foo-dev (sub)
# foo-doc (sub)
# py-foo (sub)
# libfoo (sub)

The split functions for the 4 subpackages are:
# ''dev()'' (provided by abuild)
# ''doc()'' (provided by abuild)
# ''pysub()'' (provided by the user)
# ''libfoo()'' (provided by the user)

= Examples =
Simple APKBUILD with -doc subpackage, using abuild's default ''doc()'' function:
<pre>
# Maintainer: Natanael Copa <ncopa@alpinelinux.org>
pkgname=m4
pkgver=1.4.15
pkgrel=0
pkgdesc="GNU macro processor"
url="http://www.gnu.org/software/m4"
depends=
arch="all"
license="GPL"
subpackages="m4-doc"
source="ftp://ftp.gnu.org/gnu/m4/$pkgname-$pkgver.tar.gz
gnulib-uclibc.patch"

_builddir="$srcdir"/$pkgname-$pkgver
prepare() {
cd "$_builddir"
patch -p1 -i "$srcdir"/gnulib-uclibc.patch
}

build() {
cd "$_builddir"
./configure --prefix=/usr
make
}

package() {
cd "$_builddir"
make install DESTDIR="$pkgdir"
}

md5sums="5649a2e593b6c639deae9e72ede777dd m4-1.4.15.tar.gz
20a7dedec0e9e0ee7107e33e798ffdbe gnulib-uclibc.patch"
</pre>

A more complex APKBUILD with -doc, -dev and python subpackages:
<pre>
# Contributor: Carlo Landmeter <clandmeter at gmail>
# Maintainer: Carlo Landmeter <clandmeter at gmail>
pkgname=libxml2
pkgver=2.7.8
pkgrel=0
pkgdesc="XML parsing library, version 2"
url="http://www.xmlsoft.org/"
arch="all"
license="MIT"
depends=
depends_dev="zlib-dev python-dev"
makedepends="zlib-dev python-dev"
subpackages="$pkgname-doc $pkgname-dev py-$pkgname:py $pkgname-utils"
source="ftp://ftp.xmlsoft.org/${pkgname}/${pkgname}-${pkgver}.tar.gz
largefile64.patch"

options="!strip"

_builddir="$srcdir/$pkgname-$pkgver"
prepare() {
cd "$_builddir"
for _i in "$srcdir"/*.patch; do
patch -p1 -i "$_i"
done
}

build() {
cd "$_builddir"
./configure --prefix=/usr \
--sysconfdir=/etc \
--mandir=/usr/share/man \
--infodir=/usr/share/info
make
}

package() {
cd "$_builddir"
make -j1 DESTDIR="$pkgdir" install
install -Dm644 COPYING "$pkgdir"/usr/share/licenses/$pkgname/COPYING
}

py() {
cd "$_builddir"
pkgdesc="$pkgname python bindings"
install -d "$subpkgdir"/usr/lib
mv "$pkgdir"/usr/lib/python* "$subpkgdir"/usr/lib/
}

utils() {
pkgdesc="XML utilities"
replaces="libxml2"
mkdir -p "$subpkgdir"/usr
mv "$pkgdir"/usr/bin "$subpkgdir"/usr/
}

md5sums="8127a65e8c3b08856093099b52599c86 libxml2-2.7.8.tar.gz
5ad4915665608ebfa5b89f7908467a72 largefile64.patch"
</pre>

APKBUILD Reference

2011-01-13T01:00:28Z

Mattx86: /* Subpackages Example */

APKBUILDs are the scripts that are created in order to build Alpine packages using the [[abuild]] tool.

This page is intended to serve as a quick reference for creating APKBUILDs; if this is your first time creating a package for Alpine Linux, please see [[Creating an Alpine package]].

= Legend =
The following notes will assist you in understanding this document.

* If a variable is not prefixed with a ''$'', it will be represented by italics (i.e., ''srcdir'' ).
* Functions will also be represented by italics, but will also end with a pair of parentheses (i.e., ''build()'' ).
* Shell commands will be represented by italics and bold type (i.e., '''''abuild checksum''''').

= Variables =
{{Note|Variables that contain a path (e.g. ''$srcdir'' and ''$pkgdir'') should always be quoted using double quotes (i.e., ''"$srcdir"''). This is done to prevent things from breaking, should the user have the APKBUILD in a directory path that contains spaces.}}

== abuild-defined variables ==
The following variables are defined by abuild:

; startdir
: The directory where the APKBUILD script is found.
; srcdir
: The directory where sources, from the ''source'' variable, are downloaded to and unpacked to.
; pkgdir
: This directory should contain the files for the main package. For example, a normal [http://en.wikipedia.org/wiki/GNU_build_system autotools] package would have '''''make DESTDIR="$pkgdir" install''''' in the ''package()'' function.
; subpkgdir
: This directory should contain the files for a subpackage. This variable should only be used from subpackage functions.

== User-defined variables ==
The following variables should be defined by the user:
; arch
: Package architecture(s) to build for. Can be one of: '''x86, x86_64, all''', or '''noarch''', where '''''all''''' means all architectures, and '''''noarch''''' means it's architecture-independent (e.g., a pure-python package).
: {{Tip|To determine if your APKBUILD can use '''noarch''', first specify '''all''', build the package by running '''''abuild -r''''' and once built, execute '''''scanelf -R pkg'''''. This scans for ELF files in the ''./pkg'' directory, where all sub-/package files reside. If you do not get output from this, then '''noarch''' can be used.}}
; depends
: Run-time dependency package(s) that are not shared-object dependencies. Shared objects dependencies are auto-detected and should not be specified here.
; depends_dev
: Run-time dependency package(s) for the '''$pkgname-dev''' subpackage.
; install
: Pre/Post- Install/Upgrade/Deinstall scripts. These are used to provide additional help when installing/upgrading/deinstalling a package, and are named '''$pkgname.{pre,post}-{install,upgrade,deinstall}'''. For example, if ''pkgname'' is set to '''mypackage''' and ''install'' is set to '''$pkgname.post-install''', then a script named '''mypackage.post-install''' must exist along-side the APKBUILD.
; license
: License(s) for the package.
; makedepends
: Build-time dependency package(s).
; md5sums
: Checksums for the files/URLs listed in ''source''. The checksums are normally generated by executing '''''abuild checksum''''' and should be the last item in the APKBUILD.
; options
: Build-time options for the package. Can be: '''!strip''' - to avoid stripping symbols from binaries.
; pkgdesc
: Short description of the package.
; pkggroups
: System group(s) to be created during build-time. System group(s) should also be created in a '''$pkgname.pre-install''' script, so that the system group(s) are also created prior to package installation for run-time use.
; pkgname
: The name of the package. All letters should be lowercase.
: {{Tip|When creating an APKBUILD of a module or library for another package, we use some common package prefixes, such as: ''lua-'', ''perl-'', ''php-'', and ''py-''. Search aports for other common prefixes.}}
; pkgrel
: Alpine package release number. Starts at 0 (zero). Always increment ''pkgrel'' when making updates to an aport; reset ''pkgrel'' to 0 (zero) when incrementing ''pkgver''.
; pkgusers
: System user(s) to be created during build-time. System user(s) should also be created in a '''$pkgname.pre-install''' script, so that the system user(s) are also created prior to package installation for run-time use.
; pkgver
: The version of the software being packaged.
; replaces
: Package(s) that this package replaces. This package will "take over" files owned by packages listed in the ''replaces'' variable. This is useful when files move from one sub-/package to another, or when a package gets renamed.
; source
: URL(s) to sources and patches. It can also list local files included along-side the APKBUILD, such as patches, init.d scripts, conf.d files, etc.
; subpackages
: Subpackages built from this APKBUILD. Subpackages are usually prefixed with '''$pkgname-''', with the remainder of the subpackage name being used as the name of the package function for the subpackage. For example, if ''subpackages'' is set to '''$pkgname-extra''', this will create a subpackage called '''''$pkgname''-extra''', which is packaged using a custom ''extra()'' function. (See the [[APKBUILD Reference#Subpackages|Subpackages]] section below for more information.)
; url
: The homepage for the package. This is to help users find upstream documentation and other information regarding the package.

{{Tip|All custom user-specified variables and functions should be prefixed with an underscore character ( _ ) to avoid name clashes with the internals of abuild (i.e., ''_builddir'').}}

= Functions =
{{Note|All functions should consider the current working directory as undefined, and therefore should use the [[APKBUILD Reference#abuild-defined_variables|abuild-defined directory variables]] to their advantage.}}

== abuild-defined functions ==
The following functions are provided by abuild and can be overridden:

; fetch()
: Downloads remote sources listed in ''source'' to ''SRCDEST'' (''SRCDEST'' is configured in ''/etc/abuild.conf'') and creates symlinks in ''$srcdir''.
; unpack()
: Unpacks .tgz, .tar.gz, .tar.bz2, .tar.lzma, .tar.xz, and .zip archives in ''$srcdir'' to ''$srcdir''.
; dev()
: Subpackage function for the '''$pkgname-dev''' package. Without specifying a custom ''dev()'' function, abuild will call it's internal ''dev()'' function, which in turn calls ''default_dev()'', which will move ''"$pkgdir"/usr/include'', ''*.a'', ''*.la'' and similar files to ''$subpkgdir''.
; doc()
: Subpackage function for the '''$pkgname-doc''' package. Without specifying a custom ''doc()'' function, abuild will call it's internal ''doc()'' function, which in turn calls ''default_doc()'', which will move ''"$pkgdir"/usr/share/doc'', ''"$pkgdir"/usr/share/man'' and similar to ''$subpkgdir''.

== User-defined functions ==
; prepare()
: '''''Optional''.''' Used for build preparation: patches, etc, should be applied here. This function is available for your convenience.

; build()
: '''Required.''' This is the compilation stage. This function will be called as the current user (unless the ''package()'' function is missing - for compatibility reasons). If no compilation is needed, this function can contain a single line: '''return 0'''

; package()
: '''Required.''' This is the packaging stage. This is where the built application and support files should be installed in '''$pkgdir'''.

{{Note|Building in fakeroot will reduce performance for parallel builds dramatically. It is for this reason that we split the build and package process into two separate functions.}}

= Subpackages =
Subpackages are specified in the ''subpackages'' variable. abuild will parse this variable and try to find a subpackage split function. The split function must ''move'' files that do not belong in the main package, from ''$pkgdir'' to ''$subpkgdir''. Files and directories can also be ''copied'' from ''$startdir'' and ''$srcdir'' to ''$subpkgdir''.

The split function can be specified in 1 of 3 different ways:
# subpkgname:'''splitfunc'''
# $pkgname-'''splitfunc'''
# '''splitfunc'''

== Subpackages Example ==
The following APKBUILD snippet:
pkgname="foo"
subpackages="$pkgname-dev $pkgname-doc py-$pkgname:pysub libfoo"

... will create the 5 packages in total:
# foo (main)
# foo-dev (sub)
# foo-doc (sub)
# py-foo (sub)
# libfoo (sub)

The split functions for the 4 subpackages are:
# ''dev()'' (provided by abuild)
# ''doc()'' (provided by abuild)
# ''pysub()'' (provided by the user)
# ''libfoo()'' (provided by the user)

= Examples =
Simple APKBUILD with -doc subpackage, using abuild's default ''doc()'' function:
<pre>
# Maintainer: Natanael Copa <ncopa@alpinelinux.org>
pkgname=m4
pkgver=1.4.15
pkgrel=0
pkgdesc="GNU macro processor"
url="http://www.gnu.org/software/m4"
depends=
arch="all"
license="GPL"
subpackages="m4-doc"
source="ftp://ftp.gnu.org/gnu/m4/$pkgname-$pkgver.tar.gz
gnulib-uclibc.patch"

_builddir="$srcdir"/$pkgname-$pkgver
prepare() {
cd "$_builddir"
patch -p1 -i "$srcdir"/gnulib-uclibc.patch
}

build() {
cd "$_builddir"
./configure --prefix=/usr
make
}

package() {
cd "$_builddir"
make install DESTDIR="$pkgdir"
}

md5sums="5649a2e593b6c639deae9e72ede777dd m4-1.4.15.tar.gz
20a7dedec0e9e0ee7107e33e798ffdbe gnulib-uclibc.patch"
</pre>

A more complex APKBUILD with -doc, -dev and python subpackages:
<pre>
# Contributor: Carlo Landmeter <clandmeter at gmail>
# Maintainer: Carlo Landmeter <clandmeter at gmail>
pkgname=libxml2
pkgver=2.7.8
pkgrel=0
pkgdesc="XML parsing library, version 2"
url="http://www.xmlsoft.org/"
arch="all"
license="MIT"
depends=
depends_dev="zlib-dev python-dev"
makedepends="zlib-dev python-dev"
subpackages="$pkgname-doc $pkgname-dev py-$pkgname:py $pkgname-utils"
source="ftp://ftp.xmlsoft.org/${pkgname}/${pkgname}-${pkgver}.tar.gz
largefile64.patch"

options="!strip"

_builddir="$srcdir/$pkgname-$pkgver"
prepare() {
cd "$_builddir"
for _i in "$srcdir"/*.patch; do
patch -p1 -i "$_i"
done
}

build() {
cd "$_builddir"
./configure --prefix=/usr \
--sysconfdir=/etc \
--mandir=/usr/share/man \
--infodir=/usr/share/info
make
}

package() {
cd "$_builddir"
make -j1 DESTDIR="$pkgdir" install
install -Dm644 COPYING "$pkgdir"/usr/share/licenses/$pkgname/COPYING
}

py() {
cd "$_builddir"
pkgdesc="$pkgname python bindings"
install -d "$subpkgdir"/usr/lib
mv "$pkgdir"/usr/lib/python* "$subpkgdir"/usr/lib/
}

utils() {
pkgdesc="XML utilities"
replaces="libxml2"
mkdir -p "$subpkgdir"/usr
mv "$pkgdir"/usr/bin "$subpkgdir"/usr/
}

md5sums="8127a65e8c3b08856093099b52599c86 libxml2-2.7.8.tar.gz
5ad4915665608ebfa5b89f7908467a72 largefile64.patch"
</pre>

APKBUILD Reference

2011-01-13T00:59:03Z

Mattx86:

APKBUILDs are the scripts that are created in order to build Alpine packages using the [[abuild]] tool.

This page is intended to serve as a quick reference for creating APKBUILDs; if this is your first time creating a package for Alpine Linux, please see [[Creating an Alpine package]].

= Legend =
The following notes will assist you in understanding this document.

* If a variable is not prefixed with a ''$'', it will be represented by italics (i.e., ''srcdir'' ).
* Functions will also be represented by italics, but will also end with a pair of parentheses (i.e., ''build()'' ).
* Shell commands will be represented by italics and bold type (i.e., '''''abuild checksum''''').

= Variables =
{{Note|Variables that contain a path (e.g. ''$srcdir'' and ''$pkgdir'') should always be quoted using double quotes (i.e., ''"$srcdir"''). This is done to prevent things from breaking, should the user have the APKBUILD in a directory path that contains spaces.}}

== abuild-defined variables ==
The following variables are defined by abuild:

; startdir
: The directory where the APKBUILD script is found.
; srcdir
: The directory where sources, from the ''source'' variable, are downloaded to and unpacked to.
; pkgdir
: This directory should contain the files for the main package. For example, a normal [http://en.wikipedia.org/wiki/GNU_build_system autotools] package would have '''''make DESTDIR="$pkgdir" install''''' in the ''package()'' function.
; subpkgdir
: This directory should contain the files for a subpackage. This variable should only be used from subpackage functions.

== User-defined variables ==
The following variables should be defined by the user:
; arch
: Package architecture(s) to build for. Can be one of: '''x86, x86_64, all''', or '''noarch''', where '''''all''''' means all architectures, and '''''noarch''''' means it's architecture-independent (e.g., a pure-python package).
: {{Tip|To determine if your APKBUILD can use '''noarch''', first specify '''all''', build the package by running '''''abuild -r''''' and once built, execute '''''scanelf -R pkg'''''. This scans for ELF files in the ''./pkg'' directory, where all sub-/package files reside. If you do not get output from this, then '''noarch''' can be used.}}
; depends
: Run-time dependency package(s) that are not shared-object dependencies. Shared objects dependencies are auto-detected and should not be specified here.
; depends_dev
: Run-time dependency package(s) for the '''$pkgname-dev''' subpackage.
; install
: Pre/Post- Install/Upgrade/Deinstall scripts. These are used to provide additional help when installing/upgrading/deinstalling a package, and are named '''$pkgname.{pre,post}-{install,upgrade,deinstall}'''. For example, if ''pkgname'' is set to '''mypackage''' and ''install'' is set to '''$pkgname.post-install''', then a script named '''mypackage.post-install''' must exist along-side the APKBUILD.
; license
: License(s) for the package.
; makedepends
: Build-time dependency package(s).
; md5sums
: Checksums for the files/URLs listed in ''source''. The checksums are normally generated by executing '''''abuild checksum''''' and should be the last item in the APKBUILD.
; options
: Build-time options for the package. Can be: '''!strip''' - to avoid stripping symbols from binaries.
; pkgdesc
: Short description of the package.
; pkggroups
: System group(s) to be created during build-time. System group(s) should also be created in a '''$pkgname.pre-install''' script, so that the system group(s) are also created prior to package installation for run-time use.
; pkgname
: The name of the package. All letters should be lowercase.
: {{Tip|When creating an APKBUILD of a module or library for another package, we use some common package prefixes, such as: ''lua-'', ''perl-'', ''php-'', and ''py-''. Search aports for other common prefixes.}}
; pkgrel
: Alpine package release number. Starts at 0 (zero). Always increment ''pkgrel'' when making updates to an aport; reset ''pkgrel'' to 0 (zero) when incrementing ''pkgver''.
; pkgusers
: System user(s) to be created during build-time. System user(s) should also be created in a '''$pkgname.pre-install''' script, so that the system user(s) are also created prior to package installation for run-time use.
; pkgver
: The version of the software being packaged.
; replaces
: Package(s) that this package replaces. This package will "take over" files owned by packages listed in the ''replaces'' variable. This is useful when files move from one sub-/package to another, or when a package gets renamed.
; source
: URL(s) to sources and patches. It can also list local files included along-side the APKBUILD, such as patches, init.d scripts, conf.d files, etc.
; subpackages
: Subpackages built from this APKBUILD. Subpackages are usually prefixed with '''$pkgname-''', with the remainder of the subpackage name being used as the name of the package function for the subpackage. For example, if ''subpackages'' is set to '''$pkgname-extra''', this will create a subpackage called '''''$pkgname''-extra''', which is packaged using a custom ''extra()'' function. (See the [[APKBUILD Reference#Subpackages|Subpackages]] section below for more information.)
; url
: The homepage for the package. This is to help users find upstream documentation and other information regarding the package.

{{Tip|All custom user-specified variables and functions should be prefixed with an underscore character ( _ ) to avoid name clashes with the internals of abuild (i.e., ''_builddir'').}}

= Functions =
{{Note|All functions should consider the current working directory as undefined, and therefore should use the [[APKBUILD Reference#abuild-defined_variables|abuild-defined directory variables]] to their advantage.}}

== abuild-defined functions ==
The following functions are provided by abuild and can be overridden:

; fetch()
: Downloads remote sources listed in ''source'' to ''SRCDEST'' (''SRCDEST'' is configured in ''/etc/abuild.conf'') and creates symlinks in ''$srcdir''.
; unpack()
: Unpacks .tgz, .tar.gz, .tar.bz2, .tar.lzma, .tar.xz, and .zip archives in ''$srcdir'' to ''$srcdir''.
; dev()
: Subpackage function for the '''$pkgname-dev''' package. Without specifying a custom ''dev()'' function, abuild will call it's internal ''dev()'' function, which in turn calls ''default_dev()'', which will move ''"$pkgdir"/usr/include'', ''*.a'', ''*.la'' and similar files to ''$subpkgdir''.
; doc()
: Subpackage function for the '''$pkgname-doc''' package. Without specifying a custom ''doc()'' function, abuild will call it's internal ''doc()'' function, which in turn calls ''default_doc()'', which will move ''"$pkgdir"/usr/share/doc'', ''"$pkgdir"/usr/share/man'' and similar to ''$subpkgdir''.

== User-defined functions ==
; prepare()
: '''''Optional''.''' Used for build preparation: patches, etc, should be applied here. This function is available for your convenience.

; build()
: '''Required.''' This is the compilation stage. This function will be called as the current user (unless the ''package()'' function is missing - for compatibility reasons). If no compilation is needed, this function can contain a single line: '''return 0'''

; package()
: '''Required.''' This is the packaging stage. This is where the built application and support files should be installed in '''$pkgdir'''.

{{Note|Building in fakeroot will reduce performance for parallel builds dramatically. It is for this reason that we split the build and package process into two separate functions.}}

= Subpackages =
Subpackages are specified in the ''subpackages'' variable. abuild will parse this variable and try to find a subpackage split function. The split function must ''move'' files that do not belong in the main package, from ''$pkgdir'' to ''$subpkgdir''. Files and directories can also be ''copied'' from ''$startdir'' and ''$srcdir'' to ''$subpkgdir''.

The split function can be specified in 1 of 3 different ways:
# subpkgname:'''splitfunc'''
# $pkgname-'''splitfunc'''
# '''splitfunc'''

== Subpackages Example ==
The following APKBUILD snippet:
pkgname="foo"
subpackages="$pkgname-dev $pkgname-doc py-$pkgname:pysub libfoo"

... will create the 5 packages in total:
# foo (main)
# foo-dev (sub)
# foo-doc (sub)
# py-foo (sub)
# libfoo (sub)

The split functions for the 4 subpackages are:
# ''dev()'' (provided by abuild)
# ''doc()'' (provided by abuild)
# ''pysub()'' (provided by user)
# ''libfoo()'' (provided by user)

= Examples =
Simple APKBUILD with -doc subpackage, using abuild's default ''doc()'' function:
<pre>
# Maintainer: Natanael Copa <ncopa@alpinelinux.org>
pkgname=m4
pkgver=1.4.15
pkgrel=0
pkgdesc="GNU macro processor"
url="http://www.gnu.org/software/m4"
depends=
arch="all"
license="GPL"
subpackages="m4-doc"
source="ftp://ftp.gnu.org/gnu/m4/$pkgname-$pkgver.tar.gz
gnulib-uclibc.patch"

_builddir="$srcdir"/$pkgname-$pkgver
prepare() {
cd "$_builddir"
patch -p1 -i "$srcdir"/gnulib-uclibc.patch
}

build() {
cd "$_builddir"
./configure --prefix=/usr
make
}

package() {
cd "$_builddir"
make install DESTDIR="$pkgdir"
}

md5sums="5649a2e593b6c639deae9e72ede777dd m4-1.4.15.tar.gz
20a7dedec0e9e0ee7107e33e798ffdbe gnulib-uclibc.patch"
</pre>

A more complex APKBUILD with -doc, -dev and python subpackages:
<pre>
# Contributor: Carlo Landmeter <clandmeter at gmail>
# Maintainer: Carlo Landmeter <clandmeter at gmail>
pkgname=libxml2
pkgver=2.7.8
pkgrel=0
pkgdesc="XML parsing library, version 2"
url="http://www.xmlsoft.org/"
arch="all"
license="MIT"
depends=
depends_dev="zlib-dev python-dev"
makedepends="zlib-dev python-dev"
subpackages="$pkgname-doc $pkgname-dev py-$pkgname:py $pkgname-utils"
source="ftp://ftp.xmlsoft.org/${pkgname}/${pkgname}-${pkgver}.tar.gz
largefile64.patch"

options="!strip"

_builddir="$srcdir/$pkgname-$pkgver"
prepare() {
cd "$_builddir"
for _i in "$srcdir"/*.patch; do
patch -p1 -i "$_i"
done
}

build() {
cd "$_builddir"
./configure --prefix=/usr \
--sysconfdir=/etc \
--mandir=/usr/share/man \
--infodir=/usr/share/info
make
}

package() {
cd "$_builddir"
make -j1 DESTDIR="$pkgdir" install
install -Dm644 COPYING "$pkgdir"/usr/share/licenses/$pkgname/COPYING
}

py() {
cd "$_builddir"
pkgdesc="$pkgname python bindings"
install -d "$subpkgdir"/usr/lib
mv "$pkgdir"/usr/lib/python* "$subpkgdir"/usr/lib/
}

utils() {
pkgdesc="XML utilities"
replaces="libxml2"
mkdir -p "$subpkgdir"/usr
mv "$pkgdir"/usr/bin "$subpkgdir"/usr/
}

md5sums="8127a65e8c3b08856093099b52599c86 libxml2-2.7.8.tar.gz
5ad4915665608ebfa5b89f7908467a72 largefile64.patch"
</pre>

APKBUILD Reference

2011-01-13T00:50:36Z

Mattx86: revamped page

APKBUILDs are the scripts that are created in order to build Alpine packages using the [[abuild]] tool.

This page is intended to serve as a quick reference for creating APKBUILDs; if this is your first time creating a package for Alpine Linux, please see [[Creating an Alpine package]].

= Legend =
The following notes will assist you in understanding this document.

* If a variable is not prefixed with a ''$'', it will be represented by italics (i.e., ''srcdir'' ).
* Functions will also be represented by italics, but will also end with a pair of parentheses (i.e., ''build()'' ).
* Shell commands will be represented by italics and bold type (i.e., '''''abuild checksum''''').

= Variables =
{{Note|Variables that contain a path (e.g. ''$srcdir'' and ''$pkgdir'') should always be quoted using double quotes (i.e., ''"$srcdir"''). This is done to prevent things from breaking, should the user have the APKBUILD in a directory path that contains spaces.}}

== abuild-defined variables ==
The following variables are defined by abuild:

; startdir
: The directory where the APKBUILD script is found.
; srcdir
: The directory where sources, from the ''source'' variable, are downloaded to and unpacked to.
; pkgdir
: This directory should contain the files for the main package. For example, a normal [http://en.wikipedia.org/wiki/GNU_build_system autotools] package would have '''''make DESTDIR="$pkgdir" install''''' in the ''package()'' function.
; subpkgdir
: This directory should contain the files for a subpackage. This variable should only be used from subpackage functions.

== User-defined variables ==
The following variables should be defined by the user:
; arch
: Package architecture(s) to build for. Can be one of: '''x86, x86_64, all''', or '''noarch''', where '''''all''''' means all architectures, and '''''noarch''''' means it's architecture-independent (e.g., a pure-python package).
: {{Tip|To determine if your APKBUILD can use '''noarch''', first specify '''all''', build the package by running '''''abuild -r''''' and once built, execute '''''scanelf -R pkg'''''. This scans for ELF files in the ''./pkg'' directory, where all sub-/package files reside. If you do not get output from this, then '''noarch''' can be used.}}
; depends
: Run-time dependency package(s) that are not shared-object dependencies. Shared objects dependencies are auto-detected and should not be specified here.
; depends_dev
: Run-time dependency package(s) for the '''$pkgname-dev''' subpackage.
; install
: Pre/Post- Install/Upgrade/Deinstall scripts. These are used to provide additional help when installing/upgrading/deinstalling a package, and are named '''$pkgname.{pre,post}-{install,upgrade,deinstall}'''. For example, if ''pkgname'' is set to '''mypackage''' and ''install'' is set to '''$pkgname.post-install''', then a script named '''mypackage.post-install''' must exist along-side the APKBUILD.
; license
: License(s) for the package.
; makedepends
: Build-time dependency package(s).
; md5sums
: Checksums for the files/URLs listed in ''source''. The checksums are normally generated by executing '''''abuild checksum''''' and should be the last item in the APKBUILD.
; options
: Build-time options for the package. Can be: '''!strip''' - to avoid stripping symbols from binaries.
; pkgdesc
: Short description of the package.
; pkggroups
: System group(s) to be created during build-time. System group(s) should also be created in a '''$pkgname.pre-install''' script, so that the system group(s) are also created prior to package installation for run-time use.
; pkgname
: The name of the package. All letters should be lowercase.
: {{Tip|When creating an APKBUILD of a module or library for another package, we use some common package prefixes, such as: ''lua-'', ''perl-'', ''php-'', and ''py-''. Search aports for other common prefixes.}}
; pkgrel
: Alpine package release number. Starts at 0 (zero). Always increment ''pkgrel'' when making updates to an aport; reset ''pkgrel'' to 0 (zero) when incrementing ''pkgver''.
; pkgusers
: System user(s) to be created during build-time. System user(s) should also be created in a '''$pkgname.pre-install''' script, so that the system user(s) are also created prior to package installation for run-time use.
; pkgver
: The version of the software being packaged.
; replaces
: Package(s) that this package replaces. This package will "take over" files owned by packages listed in the ''replaces'' variable. This is useful when files move from one sub-/package to another, or when a package gets renamed.
; source
: URL(s) to sources and patches. It can also list local files included along-side the APKBUILD, such as patches, init.d scripts, conf.d files, etc.
; subpackages
: Subpackages built from this APKBUILD. Subpackages are usually prefixed with '''$pkgname-''', with the remainder of the subpackage name being used as the name of the package function for the subpackage. For example, if ''subpackages'' is set to '''$pkgname-extra''', this will create a subpackage called '''''$pkgname''-extra''', which is packaged using a custom ''extra()'' function. (See the [[APKBUILD Reference#Subpackages|Subpackages]] section below for more information.)
; url
: The homepage for the package. This is to help users find upstream documentation and other information regarding the package.

{{Tip|All custom user-specified variables and functions should be prefixed with an underscore character ( _ ) to avoid name clashes with the internals of abuild (i.e., ''_builddir'').}}

= Functions =
{{Note|All functions should consider the current working directory as undefined, and therefore should use the [[APKBUILD Reference#abuild-defined_variables|abuild-defined directory variables]] to their advantage.}}

== abuild-defined functions ==
The following functions are provided by abuild and can be overridden:

; fetch()
: Downloads remote sources listed in ''source'' to ''SRCDEST'' (''SRCDEST'' is configured in ''/etc/abuild.conf'') and creates symlinks in ''$srcdir''.
; unpack()
: Unpacks .tgz, .tar.gz, .tar.bz2, .tar.lzma, .tar.xz, and .zip archives in ''$srcdir'' to ''$srcdir''.
; dev()
: Subpackage function for the '''$pkgname-dev''' package. Without specifying a custom '''dev()''' function, abuild will call '''default_dev()''' by default, which will move ''"$pkgdir"/usr/include'', ''*.a'', ''*.la'' and similar files to ''$subpkgdir''.
; doc()
: Subpackage function for the '''$pkgname-doc''' package. Without specifying a custom '''doc()''' function, abuild will call '''default_doc()''' by default, which will move ''"$pkgdir"/usr/share/doc'', ''"$pkgdir"/usr/share/man'' and similar to ''$subpkgdir''.

== User-defined functions ==
; prepare()
: '''''Optional''.''' Used for build preparation: patches, etc, should be applied here. This function is available for your convenience.

; build()
: '''Required.''' This is the compilation stage. This function will be called as the current user (unless the ''package()'' function is missing - for compatibility reasons). If no compilation is needed, this function can contain a single line: '''return 0'''

; package()
: '''Required.''' This is the packaging stage. This is where the built application and support files should be installed in '''$pkgdir'''.

{{Note|Building in fakeroot will reduce performance for parallel builds dramatically. It is for this reason that we split the build and package process into two separate functions.}}

= Subpackages =
Subpackages are specified in the ''subpackages'' variable. abuild will parse this variable and try to find a subpackage split function. The split function must ''move'' files that do not belong in the main package, from ''$pkgdir'' to ''$subpkgdir''. Files and directories can also be ''copied'' from ''$startdir'' and ''$srcdir'' to ''$subpkgdir''.

The split function can be specified in 1 of 3 different ways:
# subpkgname:'''splitfunc'''
# $pkgname-'''splitfunc'''
# '''splitfunc'''

== Subpackages Example ==
The following APKBUILD snippet:
pkgname="foo"
subpackages="$pkgname-dev $pkgname-doc py-$pkgname:pysub libfoo"

... will create the 5 packages in total:
# foo (main)
# foo-dev (sub)
# foo-doc (sub)
# py-foo (sub)
# libfoo (sub)

The split functions for the 4 subpackages are:
# dev() (provided by abuild)
# doc() (provided by abuild)
# pysub() (provided by user)
# libfoo() (provided by user)

= Examples =
Simple APKBUILD with -doc subpackage, using abuild's default ''doc()'' function:
<pre>
# Maintainer: Natanael Copa <ncopa@alpinelinux.org>
pkgname=m4
pkgver=1.4.15
pkgrel=0
pkgdesc="GNU macro processor"
url="http://www.gnu.org/software/m4"
depends=
arch="all"
license="GPL"
subpackages="m4-doc"
source="ftp://ftp.gnu.org/gnu/m4/$pkgname-$pkgver.tar.gz
gnulib-uclibc.patch"

_builddir="$srcdir"/$pkgname-$pkgver
prepare() {
cd "$_builddir"
patch -p1 -i "$srcdir"/gnulib-uclibc.patch
}

build() {
cd "$_builddir"
./configure --prefix=/usr
make
}

package() {
cd "$_builddir"
make install DESTDIR="$pkgdir"
}

md5sums="5649a2e593b6c639deae9e72ede777dd m4-1.4.15.tar.gz
20a7dedec0e9e0ee7107e33e798ffdbe gnulib-uclibc.patch"
</pre>

A more complex APKBUILD with -doc, -dev and python subpackages:
<pre>
# Contributor: Carlo Landmeter <clandmeter at gmail>
# Maintainer: Carlo Landmeter <clandmeter at gmail>
pkgname=libxml2
pkgver=2.7.8
pkgrel=0
pkgdesc="XML parsing library, version 2"
url="http://www.xmlsoft.org/"
arch="all"
license="MIT"
depends=
depends_dev="zlib-dev python-dev"
makedepends="zlib-dev python-dev"
subpackages="$pkgname-doc $pkgname-dev py-$pkgname:py $pkgname-utils"
source="ftp://ftp.xmlsoft.org/${pkgname}/${pkgname}-${pkgver}.tar.gz
largefile64.patch"

options="!strip"

_builddir="$srcdir/$pkgname-$pkgver"
prepare() {
cd "$_builddir"
for _i in "$srcdir"/*.patch; do
patch -p1 -i "$_i"
done
}

build() {
cd "$_builddir"
./configure --prefix=/usr \
--sysconfdir=/etc \
--mandir=/usr/share/man \
--infodir=/usr/share/info
make
}

package() {
cd "$_builddir"
make -j1 DESTDIR="$pkgdir" install
install -Dm644 COPYING "$pkgdir"/usr/share/licenses/$pkgname/COPYING
}

py() {
cd "$_builddir"
pkgdesc="$pkgname python bindings"
install -d "$subpkgdir"/usr/lib
mv "$pkgdir"/usr/lib/python* "$subpkgdir"/usr/lib/
}

utils() {
pkgdesc="XML utilities"
replaces="libxml2"
mkdir -p "$subpkgdir"/usr
mv "$pkgdir"/usr/bin "$subpkgdir"/usr/
}

md5sums="8127a65e8c3b08856093099b52599c86 libxml2-2.7.8.tar.gz
5ad4915665608ebfa5b89f7908467a72 largefile64.patch"
</pre>

Creating an Alpine package

2011-01-01T03:31:33Z

Mattx86: /* source */ revamped wording for source variable section (should be the final edit ;)

== General ==

This document assumes that you have a working [[Setting up the build environment|build environment]], or use a diskbased alpine installation.

=== The APKBUILDs ===

The ''[http://dev.alpinelinux.org/cgit/abuild/ abuild]'' script reads the ''[http://dev.alpinelinux.org/cgit/abuild/tree/sample.APKBUILD APKBUILD]'' and executes the steps needed to create a package.

=== The aports tree ===

The [http://dev.alpinelinux.org/cgit/aports aports] tree is a [http://dev.alpinelinux.org/cgit/aports/tree 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 essential packages used to build new packages. 
Install those packages now:

apk add alpine-sdk

This would be a good time to create a normal user account for you to work in. (You weren't going to develop as root now, were you!) To create the user:

adduser <yourusername>

To make life easier later, it's a good idea to add this user to /etc/sudoers. Append the line

<yourusername> ALL=(ALL) ALL

using the command:

visudo

Now logout of the root account, and login as <yourusername>. From here on everything can be done in a normal user account, and operations that require superuser privileges can be done with sudo.

The aports tree is in git so before we clone the aports tree we should configure git.

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 start creating or modifying APKBUILD files we need to setup abuild to our system/user. Edit the file abuild.conf to your 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.

sudo vi /etc/abuild.conf

The last step in preparation is to configure the security keys for abuild with the command:

abuild-keygen -a -i

== 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 abuild has the option -n (new). It will simply copy an example/template 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. Further, on newer Alpine systems, 'newapkbuild' has replaced abuild with the -n switch.}}

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 [[Creating an Alpine package#install|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:
: <pre>abuild checksum</pre>
: {{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:
: <pre>http://downloads.sourceforge.net/$pkgname/$pkgname-$pkgver.tar.gz</pre>
: (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:
: <pre>http://oss.example.org/?get=software&ver=1.0</pre>
: You must prepend 'saveas-' to the protocol and append '/software-1.0.tar.gz' (for instance) to the end of the URI, like so:
: <pre>saveas-http://oss.example.org/?get=software&ver=1.0/software-1.0.tar.gz</pre>
: 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.

* 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 [http://en.wikipedia.org/wiki/Rtfm 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 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).

* [http://www.gentoo-portage.com Search ebuilds]
* [http://sources.gentoo.org/viewcvs.py/gentoo-x86/ Gentoo CVS]
* [http://www.archlinux.org/packages/search/ Arch Linux packages]

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

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

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.

==== 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 user/group to be created. For example:
<pre>
#!/bin/sh
adduser -H -s /bin/false -D clamav 2>/dev/null
exit 0
</pre>
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 an already installed package.

===== $pkgname.post-upgrade =====
Same as post-install but is executed after upgrading 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:
<pre>
#!/bin/sh
busybox --install -s
</pre>

If the package have an pre-install and post-install script the APKBUILD should have the ''install'' variable defined and the scripts should also be added to the source variable:
<pre>
...
install="$pkgname.pre-install $pkgname.post-install"
source="http://....
$install"
...
</pre>

==== 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 [http://www.gnu.org/software/make/manual/make.html#Parallel 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.

==== 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 (include any other files needed for the build; $pkgname.install...)
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 testing.

== See Also ==
* [[APKBUILD Reference]]
* [[Development using git]]

Creating an Alpine package

2010-12-31T17:16:57Z

Mattx86: /* source */ updated the wording

== General ==

This document assumes that you have a working [[Setting up the build environment|build environment]], or use a diskbased alpine installation.

=== The APKBUILDs ===

The ''[http://dev.alpinelinux.org/cgit/abuild/ abuild]'' script reads the ''[http://dev.alpinelinux.org/cgit/abuild/tree/sample.APKBUILD APKBUILD]'' and executes the steps needed to create a package.

=== The aports tree ===

The [http://dev.alpinelinux.org/cgit/aports aports] tree is a [http://dev.alpinelinux.org/cgit/aports/tree 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 essential packages used to build new packages. 
Install those packages now:

apk add alpine-sdk

This would be a good time to create a normal user account for you to work in. (You weren't going to develop as root now, were you!) To create the user:

adduser <yourusername>

To make life easier later, it's a good idea to add this user to /etc/sudoers. Append the line

<yourusername> ALL=(ALL) ALL

using the command:

visudo

Now logout of the root account, and login as <yourusername>. From here on everything can be done in a normal user account, and operations that require superuser privileges can be done with sudo.

The aports tree is in git so before we clone the aports tree we should configure git.

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 start creating or modifying APKBUILD files we need to setup abuild to our system/user. Edit the file abuild.conf to your 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.

sudo vi /etc/abuild.conf

The last step in preparation is to configure the security keys for abuild with the command:

abuild-keygen -a -i

== 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 abuild has the option -n (new). It will simply copy an example/template 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. Further, on newer Alpine systems, 'newapkbuild' has replaced abuild with the -n switch.}}

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

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.

Here are few things to note:

* When you are finished adding local and remote files to ''source'', you can execute the following command to add their checksums to the APKBUILD file:
: <pre>abuild checksum</pre>
: {{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 a package is using SourceForge for hosting, you should specify the special mirrors link used by SourceForge:
: <pre>http://downloads.sourceforge.net/$pkgname/$pkgname-$pkgver.tar.gz</pre>
: (or similar depending on the package).

* When a package's filename is not specified in the URI (ie, does not end in '/software-1.0.tar.gz'):
: <pre>http://oss.example.org/?get=software&ver=1.0</pre>
: You must prepend 'saveas-' to the protocol and append '/software-1.0.tar.gz' (for instance) to the end of the URI:
: <pre>saveas-http://oss.example.org/?get=software&ver=1.0/software-1.0.tar.gz</pre>
: 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 can NOT use it.

* abuild currently supports the following protocols:
: <pre>http, https, ftp</pre>

* abuild currently supports the following archives/extensions:
: <pre>*.tar.gz, *.tgz, *.tar.bz2, *.tar.lzma, *.zip</pre>

==== 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 [http://en.wikipedia.org/wiki/Rtfm 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 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).

* [http://www.gentoo-portage.com Search ebuilds]
* [http://sources.gentoo.org/viewcvs.py/gentoo-x86/ Gentoo CVS]
* [http://www.archlinux.org/packages/search/ Arch Linux packages]

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

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

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.

==== 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 user/group to be created. For example:
<pre>
#!/bin/sh
adduser -H -s /bin/false -D clamav 2>/dev/null
exit 0
</pre>
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 an already installed package.

===== $pkgname.post-upgrade =====
Same as post-install but is executed after upgrading 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:
<pre>
#!/bin/sh
busybox --install -s
</pre>

If the package have an pre-install and post-install script the APKBUILD should have the ''install'' variable defined and the scripts should also be added to the source variable:
<pre>
...
install="$pkgname.pre-install $pkgname.post-install"
source="http://....
$install"
...
</pre>

==== 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 [http://www.gnu.org/software/make/manual/make.html#Parallel 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.

==== 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 (include any other files needed for the build; $pkgname.install...)
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 testing.

== See Also ==
* [[APKBUILD Reference]]
* [[Development using git]]

Creating an Alpine package

2010-12-31T17:14:39Z

Mattx86: /* depends & makedepends */ added bullets to list of URLs

== General ==

This document assumes that you have a working [[Setting up the build environment|build environment]], or use a diskbased alpine installation.

=== The APKBUILDs ===

The ''[http://dev.alpinelinux.org/cgit/abuild/ abuild]'' script reads the ''[http://dev.alpinelinux.org/cgit/abuild/tree/sample.APKBUILD APKBUILD]'' and executes the steps needed to create a package.

=== The aports tree ===

The [http://dev.alpinelinux.org/cgit/aports aports] tree is a [http://dev.alpinelinux.org/cgit/aports/tree 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 essential packages used to build new packages. 
Install those packages now:

apk add alpine-sdk

This would be a good time to create a normal user account for you to work in. (You weren't going to develop as root now, were you!) To create the user:

adduser <yourusername>

To make life easier later, it's a good idea to add this user to /etc/sudoers. Append the line

<yourusername> ALL=(ALL) ALL

using the command:

visudo

Now logout of the root account, and login as <yourusername>. From here on everything can be done in a normal user account, and operations that require superuser privileges can be done with sudo.

The aports tree is in git so before we clone the aports tree we should configure git.

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 start creating or modifying APKBUILD files we need to setup abuild to our system/user. Edit the file abuild.conf to your 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.

sudo vi /etc/abuild.conf

The last step in preparation is to configure the security keys for abuild with the command:

abuild-keygen -a -i

== 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 abuild has the option -n (new). It will simply copy an example/template 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. Further, on newer Alpine systems, 'newapkbuild' has replaced abuild with the -n switch.}}

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

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.

Here are few things to note:

* When you are finished adding local and remote files to ''source'', you can execute the following command to add their checksums to the APKBUILD file:
: <pre>abuild checksum</pre>
: {{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 command above.}}

* When a package is using SourceForge for hosting, you should specify the special mirrors link used by SourceForge:
: <pre>http://downloads.sourceforge.net/$pkgname/$pkgname-$pkgver.tar.gz</pre>
: (or similar depending on the package).

* When a package's filename is not specified in the URI (ie, does not end in '/software-1.0.tar.gz'):
: <pre>http://oss.example.org/?get=software&ver=1.0</pre>
: You must prepend 'saveas-' to the protocol and append '/software-1.0.tar.gz' (for instance) to the end of the URI:
: <pre>saveas-http://oss.example.org/?get=software&ver=1.0/software-1.0.tar.gz</pre>
: 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 can NOT use it.

* abuild currently supports the following protocols:
: <pre>http, https, ftp</pre>

* abuild currently supports the following archives/extensions:
: <pre>*.tar.gz, *.tgz, *.tar.bz2, *.tar.lzma, *.zip</pre>

==== 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 [http://en.wikipedia.org/wiki/Rtfm 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 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).

* [http://www.gentoo-portage.com Search ebuilds]
* [http://sources.gentoo.org/viewcvs.py/gentoo-x86/ Gentoo CVS]
* [http://www.archlinux.org/packages/search/ Arch Linux packages]

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

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

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.

==== 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 user/group to be created. For example:
<pre>
#!/bin/sh
adduser -H -s /bin/false -D clamav 2>/dev/null
exit 0
</pre>
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 an already installed package.

===== $pkgname.post-upgrade =====
Same as post-install but is executed after upgrading 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:
<pre>
#!/bin/sh
busybox --install -s
</pre>

If the package have an pre-install and post-install script the APKBUILD should have the ''install'' variable defined and the scripts should also be added to the source variable:
<pre>
...
install="$pkgname.pre-install $pkgname.post-install"
source="http://....
$install"
...
</pre>

==== 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 [http://www.gnu.org/software/make/manual/make.html#Parallel 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.

==== 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 (include any other files needed for the build; $pkgname.install...)
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 testing.

== See Also ==
* [[APKBUILD Reference]]
* [[Development using git]]

Creating an Alpine package

2010-12-31T17:10:11Z

Mattx86: /* source */ used the Note wiki template within the 'source' variable section

== General ==

This document assumes that you have a working [[Setting up the build environment|build environment]], or use a diskbased alpine installation.

=== The APKBUILDs ===

The ''[http://dev.alpinelinux.org/cgit/abuild/ abuild]'' script reads the ''[http://dev.alpinelinux.org/cgit/abuild/tree/sample.APKBUILD APKBUILD]'' and executes the steps needed to create a package.

=== The aports tree ===

The [http://dev.alpinelinux.org/cgit/aports aports] tree is a [http://dev.alpinelinux.org/cgit/aports/tree 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 essential packages used to build new packages. 
Install those packages now:

apk add alpine-sdk

This would be a good time to create a normal user account for you to work in. (You weren't going to develop as root now, were you!) To create the user:

adduser <yourusername>

To make life easier later, it's a good idea to add this user to /etc/sudoers. Append the line

<yourusername> ALL=(ALL) ALL

using the command:

visudo

Now logout of the root account, and login as <yourusername>. From here on everything can be done in a normal user account, and operations that require superuser privileges can be done with sudo.

The aports tree is in git so before we clone the aports tree we should configure git.

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 start creating or modifying APKBUILD files we need to setup abuild to our system/user. Edit the file abuild.conf to your 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.

sudo vi /etc/abuild.conf

The last step in preparation is to configure the security keys for abuild with the command:

abuild-keygen -a -i

== 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 abuild has the option -n (new). It will simply copy an example/template 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. Further, on newer Alpine systems, 'newapkbuild' has replaced abuild with the -n switch.}}

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

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.

Here are few things to note:

* When you are finished adding local and remote files to ''source'', you can execute the following command to add their checksums to the APKBUILD file:
: <pre>abuild checksum</pre>
: {{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 command above.}}

* When a package is using SourceForge for hosting, you should specify the special mirrors link used by SourceForge:
: <pre>http://downloads.sourceforge.net/$pkgname/$pkgname-$pkgver.tar.gz</pre>
: (or similar depending on the package).

* When a package's filename is not specified in the URI (ie, does not end in '/software-1.0.tar.gz'):
: <pre>http://oss.example.org/?get=software&ver=1.0</pre>
: You must prepend 'saveas-' to the protocol and append '/software-1.0.tar.gz' (for instance) to the end of the URI:
: <pre>saveas-http://oss.example.org/?get=software&ver=1.0/software-1.0.tar.gz</pre>
: 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 can NOT use it.

* abuild currently supports the following protocols:
: <pre>http, https, ftp</pre>

* abuild currently supports the following archives/extensions:
: <pre>*.tar.gz, *.tgz, *.tar.bz2, *.tar.lzma, *.zip</pre>

==== 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 [http://en.wikipedia.org/wiki/Rtfm 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 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).

[http://www.gentoo-portage.com Search ebuilds]

[http://sources.gentoo.org/viewcvs.py/gentoo-x86/ Gentoo CVS]

[http://www.archlinux.org/packages/search/ Arch Linux packages]

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

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

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.

==== 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 user/group to be created. For example:
<pre>
#!/bin/sh
adduser -H -s /bin/false -D clamav 2>/dev/null
exit 0
</pre>
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 an already installed package.

===== $pkgname.post-upgrade =====
Same as post-install but is executed after upgrading 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:
<pre>
#!/bin/sh
busybox --install -s
</pre>

If the package have an pre-install and post-install script the APKBUILD should have the ''install'' variable defined and the scripts should also be added to the source variable:
<pre>
...
install="$pkgname.pre-install $pkgname.post-install"
source="http://....
$install"
...
</pre>

==== 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 [http://www.gnu.org/software/make/manual/make.html#Parallel 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.

==== 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 (include any other files needed for the build; $pkgname.install...)
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 testing.

== See Also ==
* [[APKBUILD Reference]]
* [[Development using git]]

APKBUILD Reference

2010-12-31T17:04:28Z

Mattx86: updated wording for 'arch' variable

APKBUILDs are scripts to build alpine packages using the [[abuild]] tool.

= Variables =
== abuild-defined variables ==
The following variables are defined by abuild:
; startdir
: The directory where APKBUILD script is found.
; srcdir
: The directory here sources are downloaded to and unpacked.
; pkgdir
: This directory should hold the data files for main package. A normal autotools package has a ''make DESTDIR="$pkgdir" install''.
; subpkgdir
: This directory should have the data files for a subpackage. This variable should only be used from subpackage functions.
{{Note|All variables that holds a path (i.e ''$srcdir'' and ''$pkgdir'') should always be within quotes in the APKBUILD (for example: ''"$srcdir"''). This is so things don't break in case user has the APKBUILD in a directory with spaces.}}

== User-defined variables ==
The following variables should be defined by user in APKBUILD:
; arch
: Package architecture(s) to build for. 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.}}
; depends
: Runtime dependencies that are not shared-object dependencies. Shared objects dependencies are autodetected and should not be specified here.
; depends_dev
: Runtime dependencies for -dev subpackage.
; install
: pre/post install/deinstall/remove scripts.
; license
: License(s) for the package.
; makedepends
: Build time dependencies.
; md5sums
: Checksums for sources and patches. This is generated with ''abuild checksum'' and should be located last in the APKBUILD.
; options
: build time options for package. Valid values are currently only ''!strip'' for avoid stripping the binaries.
; pkgdesc
: Short package description.
; pkggroups
: Groups to be created during buildtime. This group should be created in a ''$pkgname.pre-install'' script as well so group is created during runtime.
; pkgname
: The name of the package. All letters should be lowercase. Lua libraries/modules should be prefixed with ''lua-'' (for example ''lua-posix''), perl modules with ''perl-'' (for example ''perl-xml-''parser), php modules with ''php-'' and python modules with ''py--''.
; pkgusers
: Users to be created during buildtime. Use ''$pkgname.pre-install'' for creating the user(s) during runtime.
; pkgver
: The package version.
; replaces
: package(s) that this package replaces. This package will "take over" files owned by packages listed in ''replaces''. Useful when files moves from one (sub)package to another, or packages gets renamed.
; source
: URL(s) to sources and patches.
; subpackages
: Subpackages built from this APKBUILD.
; url
: The homepage for the package. This is to help users find upstream developer, documentation etc.

{{Note|All other user specified variables, temp variables or APKBUILD specifics should be prefixed with a _ to avoid nameclashes with the abuild internals. For example: ''$_builddir''.}}

= Functions =
The following functions should be specified in the APKBUILD. The functions should consider current work directory as undefined.

; prepare()
: ''Optional''. Build preparation. Here should patches etc be applied. This is function is for convenience while working with the APKBUILD.
; build()
: ''Required''. This is the compilation stage. This function will be called as normal user (unless the package() function is missing - for compatibility reasons). If no compilation is needed this function can contain a single ''return 0''.
; package()
: ''Required''. In this function the built application and files should be installed in "$pkgdir".

{{Note| Building in fakeroot will reduce performance for parallell builds dramatically. That is why we do the ''build()'' and ''package()'' separation.}}

The following functions are provided by abuild and is overrideable:
; fetch()
: download remote sources listed in $source to ''$SRCDEST'' and create symlinks to ''$srcdir''.
; unpack()
: unpacks .tar.gz .tar.bz2 .tgz and .zip archives in ''$srcdir''.
; dev()
: Subpackage function for -dev packages. By default this will only call ''default_dev'' which will move ''$pkgdir/usr/include'', ''*.a'', ''*.la'' and similar files to ''$subpkgdir''.
; doc()
: Subpackage function for -doc packages. By default this will only call ''default_doc'' which will move ''$pkgdir/usr/share/doc'', ''$pkgdir/usr/share/man'' and similar to ''$subpkgdir''.

= Subpackages =
Subpackages are specified in the ''$subpackages'' variable. abuild will parse this variable and try find a subpackage split function. The split function must move files from ''$pkgdir'' to ''$subpkgdir''.

The split function can be specified in 3 different ways:
# subpkgname:''splitfunc''
# pkgname-''splitfunc''
# ''splitfunc''

== Subpackages example ==
pkgname="foo"
subpackages="$pkgname-dev $pkgname-doc py-$pkgname:pysub libfoo"

will create totally 5 packages:
# foo (main)
# foo-dev (sub)
# foo-doc (sub)
# py-foo (sub)
# libfoo (sub)

The split functions for the 4 sub packages are:
# dev() (provided by abuild)
# doc() (provided by abuild)
# pysub() (provided by user)
# libfoo() (provided by user)

= Examples =
Simple package with separate -doc subpackage.
<pre>
# Maintainer: Natanael Copa <ncopa@alpinelinux.org>
pkgname=m4
pkgver=1.4.15
pkgrel=0
pkgdesc="GNU macro processor"
url="http://www.gnu.org/software/m4"
depends=
arch="all"
license="GPL"
subpackages="m4-doc"
source="ftp://ftp.gnu.org/gnu/m4/$pkgname-$pkgver.tar.gz
gnulib-uclibc.patch"

_builddir="$srcdir"/$pkgname-$pkgver
prepare() {
cd "$_builddir"
patch -p1 -i "$srcdir"/gnulib-uclibc.patch
}

build() {
cd "$_builddir"
./configure --prefix=/usr
make
}

package() {
cd "$_builddir"
make install DESTDIR="$pkgdir"
}

md5sums="5649a2e593b6c639deae9e72ede777dd m4-1.4.15.tar.gz
20a7dedec0e9e0ee7107e33e798ffdbe gnulib-uclibc.patch"
</pre>

Example with -doc, -dev and python subpackages.
<pre>
# Contributor: Carlo Landmeter <clandmeter at gmail>
# Maintainer: Carlo Landmeter <clandmeter at gmail>
pkgname=libxml2
pkgver=2.7.8
pkgrel=0
pkgdesc="XML parsing library, version 2"
url="http://www.xmlsoft.org/"
arch="all"
license="MIT"
depends=
depends_dev="zlib-dev python-dev"
makedepends="zlib-dev python-dev"
subpackages="$pkgname-doc $pkgname-dev py-$pkgname:py $pkgname-utils"
source="ftp://ftp.xmlsoft.org/${pkgname}/${pkgname}-${pkgver}.tar.gz
largefile64.patch"

options="!strip"

_builddir="$srcdir/$pkgname-$pkgver"
prepare() {
cd "$_builddir"
for _i in "$srcdir"/*.patch; do
patch -p1 -i "$_i"
done
}

build() {
cd "$_builddir"
./configure --prefix=/usr \
--sysconfdir=/etc \
--mandir=/usr/share/man \
--infodir=/usr/share/info
make
}

package() {
cd "$_builddir"
make -j1 DESTDIR="$pkgdir" install
install -Dm644 COPYING "$pkgdir"/usr/share/licenses/$pkgname/COPYING
}

py() {
cd "$_builddir"
pkgdesc="$pkgname python bindings"
install -d "$subpkgdir"/usr/lib
mv "$pkgdir"/usr/lib/python* "$subpkgdir"/usr/lib/
}

utils() {
pkgdesc="XML utilities"
replaces="libxml2"
mkdir -p "$subpkgdir"/usr
mv "$pkgdir"/usr/bin "$subpkgdir"/usr/
}

md5sums="8127a65e8c3b08856093099b52599c86 libxml2-2.7.8.tar.gz
5ad4915665608ebfa5b89f7908467a72 largefile64.patch"
</pre>