APKBUILD Reference: Difference between revisions

From Alpine Linux
m (updated wording for 'arch' variable)
(revamped page)
Line 1: Line 1:
APKBUILDs are scripts to build alpine packages using the [[abuild]] tool.  
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 =
= 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 ==
== abuild-defined variables ==
The following variables are defined by abuild:
The following variables are defined by abuild:
; startdir
; startdir
: The directory where APKBUILD script is found.
: The directory where the APKBUILD script is found.
; srcdir
; srcdir
: The directory here sources are downloaded to and unpacked.
: The directory where sources, from the ''source'' variable, are downloaded to and unpacked to.
; pkgdir
; pkgdir
: This directory should hold the data files for main package. A normal autotools package has a ''make DESTDIR="$pkgdir" install''.
: 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
; subpkgdir
: This directory should have the data files for a subpackage. This variable should only be used from subpackage functions.
: This directory should contain the 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 ==
== User-defined variables ==
The following variables should be defined by user in APKBUILD:
The following variables should be defined by the user:
; arch
; 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).
: 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'', 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.}}
: {{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
; depends
: Runtime dependencies that are not shared-object dependencies. Shared objects dependencies are autodetected and should not be specified here.
: 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
; depends_dev
: Runtime dependencies for -dev subpackage.
: Run-time dependency package(s) for the '''$pkgname-dev''' subpackage.
; install
; install
: pre/post install/deinstall/remove scripts.
: 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
: License(s) for the package.
: License(s) for the package.
; makedepends
; makedepends
: Build time dependencies.
: Build-time dependency package(s).
; md5sums
; md5sums
: Checksums for sources and patches. This is generated with ''abuild checksum'' and should be located last in the APKBUILD.
: 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
; options
: build time options for package. Valid values are currently only ''!strip'' for avoid stripping the binaries.
: Build-time options for the package. Can be: '''!strip''' - to avoid stripping symbols from binaries.
; pkgdesc
; pkgdesc
: Short package description.
: Short description of the package.
; pkggroups
; 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.
: 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
; 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--''.
: 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
; pkgusers
: Users to be created during buildtime. Use ''$pkgname.pre-install'' for creating the user(s) during runtime.
: 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
; pkgver
: The package version.
: The version of the software being packaged.
; replaces
; 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.
: 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
; source
: URL(s) to sources and patches.
: 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
: Subpackages built from this APKBUILD.
: 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
; url
: The homepage for the package. This is to help users find upstream developer, documentation etc.
: 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'').}}


{{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 =
= Functions =
The following functions should be specified in the APKBUILD. The functions should consider current work directory as undefined.
{{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()
; prepare()
: ''Optional''. Build preparation. Here should patches etc be applied. This is function is for convenience while working with the APKBUILD.
: '''''Optional''.'''  Used for build preparation: patches, etc, should be applied here. This function is available for your convenience.
 
; build()
; 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''.
: '''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()
; package()
: ''Required''. In this function the built application and files should be installed in "$pkgdir".
: '''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 parallell builds dramatically. That is why we do the ''build()'' and ''package()'' separation.}}
{{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.}}


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 =
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''.
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 3 different ways:
The split function can be specified in 1 of 3 different ways:
# subpkgname:''splitfunc''
# subpkgname:'''splitfunc'''
# pkgname-''splitfunc''
# $pkgname-'''splitfunc'''
# ''splitfunc''
# '''splitfunc'''


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


will create totally 5 packages:
... will create the 5 packages in total:
# foo (main)
# foo (main)
# foo-dev (sub)
# foo-dev (sub)
Line 95: Line 118:
# libfoo (sub)
# libfoo (sub)


The split functions for the 4 sub packages are:
The split functions for the 4 subpackages are:
# dev() (provided by abuild)
# dev() (provided by abuild)
# doc() (provided by abuild)
# doc() (provided by abuild)
Line 103: Line 126:


= Examples =
= Examples =
Simple package with separate -doc subpackage.
Simple APKBUILD with -doc subpackage, using abuild's default ''doc()'' function:
<pre>
<pre>
# Maintainer: Natanael Copa <ncopa@alpinelinux.org>
# Maintainer: Natanael Copa <ncopa@alpinelinux.org>
Line 139: Line 162:
</pre>
</pre>


Example with -doc, -dev and python subpackages.
 
A more complex APKBUILD with -doc, -dev and python subpackages:
<pre>
<pre>
# Contributor: Carlo Landmeter <clandmeter at gmail>
# Contributor: Carlo Landmeter <clandmeter at gmail>

Revision as of 00:50, 13 January 2011

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

  1. subpkgname:splitfunc
  2. $pkgname-splitfunc
  3. 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:

  1. foo (main)
  2. foo-dev (sub)
  3. foo-doc (sub)
  4. py-foo (sub)
  5. libfoo (sub)

The split functions for the 4 subpackages are:

  1. dev() (provided by abuild)
  2. doc() (provided by abuild)
  3. pysub() (provided by user)
  4. libfoo() (provided by user)


Examples

Simple APKBUILD with -doc subpackage, using abuild's default doc() function:

# 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"


A more complex APKBUILD with -doc, -dev and python subpackages:

# 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"