Alpine Linux - User contributions [en]

TODO:apk

2017-06-04T03:06:31Z

TemptorSent: /* Manifests */ \t -> <tab>

=TODO: apk=

==Documentation==
* Document current [[apk internals]].
* Define 'virtual', 'alternative', and their proper use.

==Alternatives==
Where more than one package provides the same file or facility, allow the user to choose which implementation to prefer.

==Plugable Layouts==
===Flat===
Existing layout with most binaries and libraries in common directories. Only a single version of a package may be installed and only one package providing a given file or facility may be installed.
===/pkg===
/pkg/apk-tools/3.0.0
/pkg/apk-tools/2.7.1
/pkg/apk-tools/default -> 3.0.0

Each package is installed in it's own versioned directory allowing different versions and of the same package and multiple packages which provide the same file to coexist and be selected between as needed.

===/app===
/app/webserver/20170406
/app/webserver/20170514
/app/webserver/production -> 20170406
/app/webserver/testing -> 20170514

A a complete set of packages and their dependencies needed to provide an application with a consistent environment for deployment. Generally specifies exact versions of every dependency and is updated as a unit.

==Manifests==
<code>apk manifest [-v] (<pkg>|<.apk>)...</code>

Generate a manifest of files contained within the specified package(s)/apk(s).

Current default format is:
<code>sumfunc:checksum path</code>

With verbose flag:
<code>pkgname: sumfunc:checksum path</code>

Proposed canonical format:
<code>pkg:arch/pkgname-pkgver mode user:group size timestamp sumfunc:checksum path</code>

===TODO Items:===
* Define a canonical default manifest format which contains all available metadata in a reliably parsable format.
* Add ability to specify manifest format and fields in a manner similar to 'stat'.
* Add ability to select a subset of files to display in a manner similar to tar. (i.e. 'etc/' or 'lib/*.so')
* Add ability to generate manifest from a filesystem directory structure or path list.
* (DONE - kaniini) Add ability to generate manifest for .apk file in addition to installed packages.

==.apk Generator==
<code>apk gen --key-file=... --control-dir=... --data-dir=...</code>

Generates a well-formed .apk from a key file and two filesystem directories -- one for the control portion and one for the data portion.

===TODO Items:===
* Document current WIP (kaniini).
* Add ability to use an archive as the source for control or data directories.
* Add ability to use a pre-generated manifest as the source file list and provider of package's file meta-data.

==pax Archive Tool==
<code>apk archive list -f file.apk [pattern list...]</code>

<code>apk archive extract -f file.apk [pattern list...]</code>

<code>apk archive create -f file.apk [file list...]</code>

<code>apk archive append -f file.apk [file list...]</code>

Low-level tools to manipulate .apk archives directly.

===TODO Items:===
* Define proper applet and command names.
* Determine appropriate flags.
* Provide ability to supply include/exclude file/pattern list on STDIN, on the command line, or listed in external files.

TODO:apk

2017-06-04T02:44:42Z

TemptorSent: /* Alternatives */ Add description.

=TODO: apk=

==Documentation==
* Document current [[apk internals]].
* Define 'virtual', 'alternative', and their proper use.

==Alternatives==
Where more than one package provides the same file or facility, allow the user to choose which implementation to prefer.

==Plugable Layouts==
===Flat===
Existing layout with most binaries and libraries in common directories. Only a single version of a package may be installed and only one package providing a given file or facility may be installed.
===/pkg===
/pkg/apk-tools/3.0.0
/pkg/apk-tools/2.7.1
/pkg/apk-tools/default -> 3.0.0

Each package is installed in it's own versioned directory allowing different versions and of the same package and multiple packages which provide the same file to coexist and be selected between as needed.

===/app===
/app/webserver/20170406
/app/webserver/20170514
/app/webserver/production -> 20170406
/app/webserver/testing -> 20170514

A a complete set of packages and their dependencies needed to provide an application with a consistent environment for deployment. Generally specifies exact versions of every dependency and is updated as a unit.

==Manifests==
<code>apk manifest [-v] (<pkg>|<.apk>)...</code>

Generate a manifest of files contained within the specified package(s)/apk(s).

Current default format is:
<code>sumfunc:checksum path</code>

With verbose flag:
<code>pkgname: sumfunc:checksum path</code>

Proposed canonical format:
<code>pkg:arch/pkgname-pkgver\tmode\tuser:group\tsize\ttimestamp\tsumfunc:checksum\tpath</code>

===TODO Items:===
* Define a canonical default manifest format which contains all available metadata in a reliably parsable format.
* Add ability to specify manifest format and fields in a manner similar to 'stat'.
* Add ability to select a subset of files to display in a manner similar to tar. (i.e. 'etc/' or 'lib/*.so')
* Add ability to generate manifest from a filesystem directory structure or path list.
* (DONE - kaniini) Add ability to generate manifest for .apk file in addition to installed packages.

==.apk Generator==
<code>apk gen --key-file=... --control-dir=... --data-dir=...</code>

Generates a well-formed .apk from a key file and two filesystem directories -- one for the control portion and one for the data portion.

===TODO Items:===
* Document current WIP (kaniini).
* Add ability to use an archive as the source for control or data directories.
* Add ability to use a pre-generated manifest as the source file list and provider of package's file meta-data.

==pax Archive Tool==
<code>apk archive list -f file.apk [pattern list...]</code>

<code>apk archive extract -f file.apk [pattern list...]</code>

<code>apk archive create -f file.apk [file list...]</code>

<code>apk archive append -f file.apk [file list...]</code>

Low-level tools to manipulate .apk archives directly.

===TODO Items:===
* Define proper applet and command names.
* Determine appropriate flags.
* Provide ability to supply include/exclude file/pattern list on STDIN, on the command line, or listed in external files.

TODO:apk

2017-06-04T02:06:11Z

TemptorSent: /* Plugable Layouts */ Add example layouts

=TODO: apk=

==Documentation==
* Document current [[apk internals]].
* Define 'virtual', 'alternative', and their proper use.

==Alternatives==

==Plugable Layouts==
===Flat===
Existing layout with most binaries and libraries in common directories. Only a single version of a package may be installed and only one package providing a given file or facility may be installed.
===/pkg===
/pkg/apk-tools/3.0.0
/pkg/apk-tools/2.7.1
/pkg/apk-tools/default -> 3.0.0

Each package is installed in it's own versioned directory allowing different versions and of the same package and multiple packages which provide the same file to coexist and be selected between as needed.

===/app===
/app/webserver/20170406
/app/webserver/20170514
/app/webserver/production -> 20170406
/app/webserver/testing -> 20170514

A a complete set of packages and their dependencies needed to provide an application with a consistent environment for deployment. Generally specifies exact versions of every dependency and is updated as a unit.

==Manifests==
<code>apk manifest [-v] (<pkg>|<.apk>)...</code>

Generate a manifest of files contained within the specified package(s)/apk(s).

Current default format is:
<code>sumfunc:checksum path</code>

With verbose flag:
<code>pkgname: sumfunc:checksum path</code>

Proposed canonical format:
<code>pkg:arch/pkgname-pkgver\tmode\tuser:group\tsize\ttimestamp\tsumfunc:checksum\tpath</code>

===TODO Items:===
* Define a canonical default manifest format which contains all available metadata in a reliably parsable format.
* Add ability to specify manifest format and fields in a manner similar to 'stat'.
* Add ability to select a subset of files to display in a manner similar to tar. (i.e. 'etc/' or 'lib/*.so')
* Add ability to generate manifest from a filesystem directory structure or path list.
* (DONE - kaniini) Add ability to generate manifest for .apk file in addition to installed packages.

==.apk Generator==
<code>apk gen --key-file=... --control-dir=... --data-dir=...</code>

Generates a well-formed .apk from a key file and two filesystem directories -- one for the control portion and one for the data portion.

===TODO Items:===
* Document current WIP (kaniini).
* Add ability to use an archive as the source for control or data directories.
* Add ability to use a pre-generated manifest as the source file list and provider of package's file meta-data.

==pax Archive Tool==
<code>apk archive list -f file.apk [pattern list...]</code>

<code>apk archive extract -f file.apk [pattern list...]</code>

<code>apk archive create -f file.apk [file list...]</code>

<code>apk archive append -f file.apk [file list...]</code>

Low-level tools to manipulate .apk archives directly.

===TODO Items:===
* Define proper applet and command names.
* Determine appropriate flags.
* Provide ability to supply include/exclude file/pattern list on STDIN, on the command line, or listed in external files.

TODO:apk

2017-06-04T01:49:02Z

TemptorSent: /* TODO Items */

=TODO: apk=

==Documentation==
* Document current [[apk internals]].
* Define 'virtual', 'alternative', and their proper use.

==Alternatives==

==Plugable Layouts==

==Manifests==
<code>apk manifest [-v] (<pkg>|<.apk>)...</code>

Generate a manifest of files contained within the specified package(s)/apk(s).

Current default format is:
<code>sumfunc:checksum path</code>

With verbose flag:
<code>pkgname: sumfunc:checksum path</code>

Proposed canonical format:
<code>pkg:arch/pkgname-pkgver\tmode\tuser:group\tsize\ttimestamp\tsumfunc:checksum\tpath</code>

===TODO Items:===
* Define a canonical default manifest format which contains all available metadata in a reliably parsable format.
* Add ability to specify manifest format and fields in a manner similar to 'stat'.
* Add ability to select a subset of files to display in a manner similar to tar. (i.e. 'etc/' or 'lib/*.so')
* Add ability to generate manifest from a filesystem directory structure or path list.
* (DONE - kaniini) Add ability to generate manifest for .apk file in addition to installed packages.

==.apk Generator==
<code>apk gen --key-file=... --control-dir=... --data-dir=...</code>

Generates a well-formed .apk from a key file and two filesystem directories -- one for the control portion and one for the data portion.

===TODO Items:===
* Document current WIP (kaniini).
* Add ability to use an archive as the source for control or data directories.
* Add ability to use a pre-generated manifest as the source file list and provider of package's file meta-data.

==pax Archive Tool==
<code>apk archive list -f file.apk [pattern list...]</code>

<code>apk archive extract -f file.apk [pattern list...]</code>

<code>apk archive create -f file.apk [file list...]</code>

<code>apk archive append -f file.apk [file list...]</code>

Low-level tools to manipulate .apk archives directly.

===TODO Items:===
* Define proper applet and command names.
* Determine appropriate flags.
* Provide ability to supply include/exclude file/pattern list on STDIN, on the command line, or listed in external files.

TODO:apk

2017-06-04T01:44:08Z

TemptorSent: /* pax Archive Tool */ Add possible usage and TODO items.

=TODO: apk=

==Documentation==
* Document current [[apk internals]].
* Define 'virtual', 'alternative', and their proper use.

==Alternatives==

==Plugable Layouts==

==Manifests==
<code>apk manifest [-v] (<pkg>|<.apk>)...</code>

Generate a manifest of files contained within the specified package(s)/apk(s).

Current default format is:
<code>sumfunc:checksum path</code>

With verbose flag:
<code>pkgname: sumfunc:checksum path</code>

Proposed canonical format:
<code>pkg:arch/pkgname-pkgver\tmode\tuser:group\tsize\ttimestamp\tsumfunc:checksum\tpath</code>

===TODO Items===
* Define a canonical default manifest format which contains all available metadata in a reliably parsable format.
* Add ability to specify manifest format and fields in a manner similar to 'stat'.
* Add ability to select a subset of files to display in a manner similar to tar. (i.e. 'etc/' or 'lib/*.so')
* Add ability to generate manifest from a filesystem directory structure or path list.
* (DONE - kaniini) Add ability to generate manifest for .apk file in addition to installed packages.

==.apk Generator==
<code>apk gen --key-file=... --control-dir=... --data-dir=...</code>

Generates a well-formed .apk from a key file and two filesystem directories -- one for the control portion and one for the data portion.

===TODO Items:===
* Document current WIP (kaniini).
* Add ability to use an archive as the source for control or data directories.
* Add ability to use a pre-generated manifest as the source file list and provider of package's file meta-data.

==pax Archive Tool==
<code>apk archive list -f file.apk [pattern list...]</code>

<code>apk archive extract -f file.apk [pattern list...]</code>

<code>apk archive create -f file.apk [file list...]</code>

<code>apk archive append -f file.apk [file list...]</code>

Low-level tools to manipulate .apk archives directly.

===TODO Items:===
* Define proper applet and command names.
* Determine appropriate flags.
* Provide ability to supply include/exclude file/pattern list on STDIN, on the command line, or listed in external files.

TODO:apk

2017-06-04T00:37:49Z

TemptorSent: /* Manifests */ Add description, formats, and TODO header.

=TODO: apk=

==Documentation==
* Document current [[apk internals]].
* Define 'virtual', 'alternative', and their proper use.

==Alternatives==

==Plugable Layouts==

==Manifests==
<code>apk manifest [-v] (<pkg>|<.apk>)...</code>

Generate a manifest of files contained within the specified package(s)/apk(s).

Current default format is:
<code>sumfunc:checksum path</code>

With verbose flag:
<code>pkgname: sumfunc:checksum path</code>

Proposed canonical format:
<code>pkg:arch/pkgname-pkgver\tmode\tuser:group\tsize\ttimestamp\tsumfunc:checksum\tpath</code>

===TODO Items===
* Define a canonical default manifest format which contains all available metadata in a reliably parsable format.
* Add ability to specify manifest format and fields in a manner similar to 'stat'.
* Add ability to select a subset of files to display in a manner similar to tar. (i.e. 'etc/' or 'lib/*.so')
* Add ability to generate manifest from a filesystem directory structure or path list.
* (DONE - kaniini) Add ability to generate manifest for .apk file in addition to installed packages.

==.apk Generator==
<code>apk gen --key-file=... --control-dir=... --data-dir=...</code>

Generates a well-formed .apk from a key file and two filesystem directories -- one for the control portion and one for the data portion.

===TODO Items:===
* Document current WIP (kaniini).
* Add ability to use an archive as the source for control or data directories.
* Add ability to use a pre-generated manifest as the source file list and provider of package's file meta-data.

==pax Archive Tool==

TODO:apk

2017-06-03T23:24:14Z

TemptorSent: /* .apk Generator */ Update usage and TODO items

=TODO: apk=

==Documentation==
* Document current [[apk internals]].
* Define 'virtual', 'alternative', and their proper use.

==Alternatives==

==Plugable Layouts==

==Manifests==
apk manifest [-v] (<pkg>|<.apk>)...
* Define a canonical default manifest format which contains all available metadata in a reliably parsable format.
* Add ability to specify manifest format and fields in a manner similar to 'stat'.
* Add ability to select a subset of files to display in a manner similar to tar. (i.e. 'etc/' or 'lib/*.so')
* Add ability to generate manifest from a filesystem directory structure or path list.
* (DONE - kaniini) Add ability to generate manifest for .apk file in addition to installed packages.

==.apk Generator==
<code>apk gen --key-file=... --control-dir=... --data-dir=...</code>

Generates a well-formed .apk from a key file and two filesystem directories -- one for the control portion and one for the data portion.

===TODO Items:===
* Document current WIP (kaniini).
* Add ability to use an archive as the source for control or data directories.
* Add ability to use a pre-generated manifest as the source file list and provider of package's file meta-data.

==pax Archive Tool==

TODO:apk

2017-06-03T22:10:37Z

TemptorSent: /* .apk Generator */ Add description and TODO items.

=TODO: apk=

==Documentation==
* Document current [[apk internals]].
* Define 'virtual', 'alternative', and their proper use.

==Alternatives==

==Plugable Layouts==

==Manifests==
apk manifest [-v] (<pkg>|<.apk>)...
* Define a canonical default manifest format which contains all available metadata in a reliably parsable format.
* Add ability to specify manifest format and fields in a manner similar to 'stat'.
* Add ability to select a subset of files to display in a manner similar to tar. (i.e. 'etc/' or 'lib/*.so')
* Add ability to generate manifest from a filesystem directory structure or path list.
* (DONE - kaniini) Add ability to generate manifest for .apk file in addition to installed packages.

==.apk Generator==
apk gen ....

Generates a well-formed .apk from a filesystem directory (or archive?).
* Document current WIP (kaniini).
* Add ability to use a pre-generated manifest as the source file list and provider of package's file meta-data.

==pax Archive Tool==

TODO:apk

2017-06-03T22:00:40Z

TemptorSent: /* Manifests */ Update TODOs.

=TODO: apk=

==Documentation==
* Document current [[apk internals]].
* Define 'virtual', 'alternative', and their proper use.

==Alternatives==

==Plugable Layouts==

==Manifests==
apk manifest [-v] (<pkg>|<.apk>)...
* Define a canonical default manifest format which contains all available metadata in a reliably parsable format.
* Add ability to specify manifest format and fields in a manner similar to 'stat'.
* Add ability to select a subset of files to display in a manner similar to tar. (i.e. 'etc/' or 'lib/*.so')
* Add ability to generate manifest from a filesystem directory structure or path list.
* (DONE - kaniini) Add ability to generate manifest for .apk file in addition to installed packages.

==.apk Generator==

==pax Archive Tool==

TODO:apk

2017-05-24T22:59:36Z

TemptorSent: Add stub page and headings for TODO:apk

Apk internals

2017-05-24T22:50:27Z

TemptorSent: Add stub "apk_internals" and link "TODO:apk" stub.

=Internals of apk=

"It's a secret to all!"

See [[TODO:apk]].

Architecture

2017-05-24T22:45:45Z

TemptorSent: /* Package Management Tools */ Add stub for apk internals.

== Alpine Hardware Architecture ("arch") Support ==
=== x86 Based ===
* [[x86]] - 32 bit x86 (ia32)
* [[x86_64]] - 64 bit x86 (amd64)

=== ARM Based ===
* [[armhf]] - 32 bit ARM (hard-float ABI)
* [[aarch64]] - 64 bit ARM

=== PowerPC Based ===
* [[ppc64le]] - 64 bit PowerPC (little-endian)

=== IBM System Z Based ===
* [[s390x]]

== Alpine Packaging ==

=== Package Building ===

==== Alpine Package Building Ports ====
* [[APKBUILD]] - Package build scripts
* [[aports]] - Official Alpine ports git repository

==== Package Building Tools ====
* [[abuild]]

=== Package Format ===
Alpine uses packages in the [[.apk file format]].

=== Package Management Tools ===
* [[apk]] - Alpine Package Keeper (see [[apk internals]] for more detail)

== Boot Process ==

=== Boot Loader ===
==== EFI ====
==== BIOS ====
==== Other ====

=== Kernel ===
==== Versioning ====
===== Flavors =====
* vanilla
* hardened
* virthardened
* rpi

==== Signing ====
==== Command line options ====

* modules="<modules>" - specify list of modules to be loaded by initramfs /init needed to mount real root filesystem.

=== Initfs ===
The kernel will decompress the stream of compressed cpio archives passed to it by the 'append' bootloader option to the root of 'rootfs', a tmpfs automatically mounted at '/' by the kernel at boot.

==== '/init' Script ====
Not to be confused with '/sbin/init', the '/init' script in the root of the 'rootfs' is called by the kernel upon completion of its boot process, and is responsible for doing whatever steps are necessary to mount the real root file system to '/' and transfer control to '/sbin/init'.

* Parses kernel command line options.
* Uses [[nlplug-findfs]] to discover devices.

==== Initfs Module Handling ====
Modules required to mount the root filesystem and boot must either built into the kernel or available from with the initramfs filesystem through use of appended initrd cpio.gz files provided by the [[bootloader]].

The /init script will first [[modprobe]] the modules specified by the modules= kernel command line option and by the name of the specified rootfs type. It will then load the contents of /etc/modules, which may include module options.
Modules may be blacklisted from autoprobing (but NOT explicit insertion!) using the blacklist= kernel command line option which appends blacklist entries to '/etc/modprobe.d/boot-opt-blacklist.conf'.

==== Minimal Required Set ====
===== Directory Structure =====
* / /bin /boot /dev /etc /lib /lib/modules /media /media/cdrom /media/usb /mnt /proc /sbin /sys /usr /usr/bin /usr/sbin
===== Devices =====
* /dev/null
* /dev/console
* /dev/kmsg

===== Mounts =====
* /proc
* /sys
* /dev (can be disabled?)

===== Configuration =====
* /etc/passwd
* /etc/group
* /etc/fstab

===== Binaries =====
* [[busybox]]
* [[apk]]

==== Feature Sets ====
Feature sets consist of lists for the set of modules and files that need to be included in a final initramfs to support the indicated feature.

=== Init ===
Not to be confused with the '/init' script in the initramfs, '/sbin/init' is the first process to be started in the live system after the initramfs completes its work.

==== Module Loading ====
'/etc/init.d/modules' loads all modules specified in '/etc/modules' and '/(etc|run|usr/lib|lib)/modules-load.d/*.conf'

Architecture

2017-05-19T23:32:30Z

TemptorSent: /* Alpine Hardware Architecture ("arch") Support */

== Alpine Hardware Architecture ("arch") Support ==
=== x86 Based ===
* [[x86]] - 32 bit x86 (ia32)
* [[x86_64]] - 64 bit x86 (amd64)

=== ARM Based ===
* [[armhf]] - 32 bit ARM (hard-float ABI)
* [[aarch64]] - 64 bit ARM

=== PowerPC Based ===
* [[ppc64le]] - 64 bit PowerPC (little-endian)

=== IBM System Z Based ===
* [[s390x]]

== Alpine Packaging ==

=== Package Building ===

==== Alpine Package Building Ports ====
* [[APKBUILD]] - Package build scripts
* [[aports]] - Official Alpine ports git repository

==== Package Building Tools ====
* [[abuild]]

=== Package Format ===
Alpine uses packages in the [[.apk file format]].

=== Package Management Tools ===
* [[apk]] - Alpine Package Keeper

== Boot Process ==

=== Boot Loader ===
==== EFI ====
==== BIOS ====
==== Other ====

=== Kernel ===
==== Versioning ====
===== Flavors =====
* vanilla
* hardened
* virthardened
* rpi

==== Signing ====
==== Command line options ====

* modules="<modules>" - specify list of modules to be loaded by initramfs /init needed to mount real root filesystem.

=== Initfs ===
The kernel will decompress the stream of compressed cpio archives passed to it by the 'append' bootloader option to the root of 'rootfs', a tmpfs automatically mounted at '/' by the kernel at boot.

==== '/init' Script ====
Not to be confused with '/sbin/init', the '/init' script in the root of the 'rootfs' is called by the kernel upon completion of its boot process, and is responsible for doing whatever steps are necessary to mount the real root file system to '/' and transfer control to '/sbin/init'.

* Parses kernel command line options.
* Uses [[nlplug-findfs]] to discover devices.

==== Initfs Module Handling ====
Modules required to mount the root filesystem and boot must either built into the kernel or available from with the initramfs filesystem through use of appended initrd cpio.gz files provided by the [[bootloader]].

The /init script will first [[modprobe]] the modules specified by the modules= kernel command line option and by the name of the specified rootfs type. It will then load the contents of /etc/modules, which may include module options.
Modules may be blacklisted from autoprobing (but NOT explicit insertion!) using the blacklist= kernel command line option which appends blacklist entries to '/etc/modprobe.d/boot-opt-blacklist.conf'.

==== Minimal Required Set ====
===== Directory Structure =====
* / /bin /boot /dev /etc /lib /lib/modules /media /media/cdrom /media/usb /mnt /proc /sbin /sys /usr /usr/bin /usr/sbin
===== Devices =====
* /dev/null
* /dev/console
* /dev/kmsg

===== Mounts =====
* /proc
* /sys
* /dev (can be disabled?)

===== Configuration =====
* /etc/passwd
* /etc/group
* /etc/fstab

===== Binaries =====
* [[busybox]]
* [[apk]]

==== Feature Sets ====
Feature sets consist of lists for the set of modules and files that need to be included in a final initramfs to support the indicated feature.

=== Init ===
Not to be confused with the '/init' script in the initramfs, '/sbin/init' is the first process to be started in the live system after the initramfs completes its work.

==== Module Loading ====
'/etc/init.d/modules' loads all modules specified in '/etc/modules' and '/(etc|run|usr/lib|lib)/modules-load.d/*.conf'

APKBUILD Reference

2017-05-19T23:25:57Z

TemptorSent: /* arch */ Add ppc64le and s390x, make archs link.

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

See [[aports]] for details on Alpine's official ports repository.

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 <code>like this</code>.

= 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 (for example, ''_luaversions'').}}

== 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 receive the files for the main package. For example, a normal [http://en.wikipedia.org/wiki/GNU_build_system autotools] package would have <code>make DESTDIR="$pkgdir" install</code> in the ''package()'' function.
==== subpkgdir ====
: This directory should receive the files for a subpackage. This variable should only be used from subpackage functions.
==== builddir ====
: This variable should point to the directory inside the ''srcdir'' where the main package source is unpacked. This is typically ''$srcdir/$pkgname-$pkgver''. It’s used by the default ''prepare()'' function as a working directory when applying patches.

== 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]], [[armhf]], [[aarch64]], [[ppc64le]], [[s390x]], 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 <code>abuild -r</code>. 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.

: {{Note|From ncopa on IRC: To find out if you need to add a package to depends_dev have a look at *requires* in usr/lib/pkgconfig/*.pc. With libtool it gets more complicated, but we should delete the .la files. Also check if there are any /usr/bin/*-configure #!/bin/bash #!/usr/bin/perl or Python. Sometimes scripts or similar are generated at build time (i.e autoconf automake) then you normally don't need add those to depends_dev. You can also just add all -dev makedepends to depends_dev but it will slow the build process a little bit (more build dependencies).}}
==== giturl ====
:Git repository from which <code>abuild checkout</code> checks out. You can checkout a specific branch in git by adding <code>-b $branch</code>.
==== 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 group and a user to be created. For example:
<blockquote><pre>
#!/bin/sh

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

exit 0
</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 <code>exit 0</code> at the end.}}</blockquote>

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

===== $pkgname.pre-upgrade =====
: This script is executed ''before upgrading/downgrading/reinstalling'' the package. Note that exiting with failure will not cause apk to exit with failure, but will mark the package as broken.

===== $pkgname.post-upgrade =====
: This script is executed ''after upgrading/downgrading/reinstalling'' 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.

==== install_if ====
:install_if can be used when a package needs to be installed when some packages are already installed or are in the dependency tree. As example we could take open-vm-tools. Currently it contains the userspace tools and separate packages for the kernel modules (grsec and vserver). When we install the userspace tools, apk should automatically install the correct kernel modules and will need to figure out for which kernel. This is where install_if jumps in. For any of the kernel modules package we would use:

:<pre>install_if="linux-${_flavor}=${_kernelver} open-vm-tools"</pre>

:This will automatically install the package when the specified packages are installed or are in dependency tree.

==== 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 <code>abuild checksum</code> 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.
==== provides ====
: List of package names (and optionally version info) this package provides.

: If package with a version is provided (provides='foo=1.2') apk will consider it as an alternate name and it will automatically consider the package for installation by the alternate name, and conflict with other packages having the same name, or provides.

: If version is not provided (provides='foo'), apk will consider it as virtual package name. Several package with same non-versioned provides can be installed simultaneously. However, none of them will be installed by default when requested by the virtual name - instead, error message is given and user is asked to choose which package providing the virtual name should be installed.
==== 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 package to another, or when a package gets renamed.
==== replaces_priority ====
: The priority of the replaces. If multiple packages replace each other, then will the package with highest ''replaces_priority'' win.
==== 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).

:* You can set target filename (eg 'save as...') by prefixing the URI with ''filename::''. This is useful 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>
:: or when the filename is braindead, like githubs' download tags:
:: <pre>https://github.com/software/software/archive/v$pkgver.tar.gz</pre>
:: The above two examples needs a target filename prefix:
:: <pre>$pkgname-$pkgver.tar.gz::http://oss.example.org/?get=software&ver=$pkgver</pre>
:: and:
:: <pre>$pkgname-$pkgver.tar.gz::https://github.com/software/software/archive/v$pkgver.tar.gz</pre>

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

:: {{Note|Legacy APKBUILD scripts define ''source'' variable as "saveas-[brain-dead-url]/[target-filename]" format instead of the modern [target-filename]::[brain-dead-url]. ''BAD'': source="saveas-http://releases.ddvtech.com/download.php?pack=libmist_dist&ver=RC/$pkgname-$pkgver.tar.gz" ''GOOD'': source=$pkgname-$pkgver.tar.gz::http://releases.ddvtech.com/download.php?pack=libmist_dist&ver=RC"}}

==== 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 <code>subpkg-name</code> is the name of the '''subpackage''' and <code>subpkg_name</code> is the name of the '''subpackage's split function'''.}}

: {{Tip|For more information, see the [[APKBUILD_examples:Subpackages|Subpackages example]].}}

==== triggers ====
: Apk-tools can "monitor" directories and execute a trigger if any package installed/uninstalled any file in the monitored dir. The triggers are always execute after the apk action (install, uninstall, upgrade).

: The triggers are specified in the format: ''scriptname''=''pathlist'' where ''scriptname'' is the (sub)package name + .trigger suffix and pathlist is : separated list of the dirs to monitor.

: The '''triggers''' variable must include the triggers for subpackages too if they have any.

: It is possible to use wildcards (*) in the dir list.

==== 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. It is better to use "default_prepare || return" to handle *.patch file, and the patch file should always be prepared as -p1 format.
==== 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: <code>return 0</code>
==== check() ====
: '''Recommended.''' This function is called right after the build stage. It should check that the packaged thing is actually working, typically by running (integration) tests, if provided by upstream. If there’s no (easy) way how to test the package, you can declare that it does not want to use ''check()'' by adding "!check" into the ''options'' variable.
==== 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: <code>mkdir -p "$pkgdir"</code>

{{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 [[APKBUILD examples]] page will assist you in understanding how to create an APKBUILD.

[[Category:Development]]

APKBUILD Reference

2017-05-19T22:21:35Z

TemptorSent: Add reference to aports now that APKBUILD no longer redirects there.

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

See [[aports]] for details on Alpine's official ports repository.

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 <code>like this</code>.

= 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 (for example, ''_luaversions'').}}

== 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 receive the files for the main package. For example, a normal [http://en.wikipedia.org/wiki/GNU_build_system autotools] package would have <code>make DESTDIR="$pkgdir" install</code> in the ''package()'' function.
==== subpkgdir ====
: This directory should receive the files for a subpackage. This variable should only be used from subpackage functions.
==== builddir ====
: This variable should point to the directory inside the ''srcdir'' where the main package source is unpacked. This is typically ''$srcdir/$pkgname-$pkgver''. It’s used by the default ''prepare()'' function as a working directory when applying patches.

== 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, armhf, aarch64, 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 <code>abuild -r</code>. 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.

: {{Note|From ncopa on IRC: To find out if you need to add a package to depends_dev have a look at *requires* in usr/lib/pkgconfig/*.pc. With libtool it gets more complicated, but we should delete the .la files. Also check if there are any /usr/bin/*-configure #!/bin/bash #!/usr/bin/perl or Python. Sometimes scripts or similar are generated at build time (i.e autoconf automake) then you normally don't need add those to depends_dev. You can also just add all -dev makedepends to depends_dev but it will slow the build process a little bit (more build dependencies).}}
==== giturl ====
:Git repository from which <code>abuild checkout</code> checks out. You can checkout a specific branch in git by adding <code>-b $branch</code>.
==== 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 group and a user to be created. For example:
<blockquote><pre>
#!/bin/sh

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

exit 0
</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 <code>exit 0</code> at the end.}}</blockquote>

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

===== $pkgname.pre-upgrade =====
: This script is executed ''before upgrading/downgrading/reinstalling'' the package. Note that exiting with failure will not cause apk to exit with failure, but will mark the package as broken.

===== $pkgname.post-upgrade =====
: This script is executed ''after upgrading/downgrading/reinstalling'' 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.

==== install_if ====
:install_if can be used when a package needs to be installed when some packages are already installed or are in the dependency tree. As example we could take open-vm-tools. Currently it contains the userspace tools and separate packages for the kernel modules (grsec and vserver). When we install the userspace tools, apk should automatically install the correct kernel modules and will need to figure out for which kernel. This is where install_if jumps in. For any of the kernel modules package we would use:

:<pre>install_if="linux-${_flavor}=${_kernelver} open-vm-tools"</pre>

:This will automatically install the package when the specified packages are installed or are in dependency tree.

==== 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 <code>abuild checksum</code> 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.
==== provides ====
: List of package names (and optionally version info) this package provides.

: If package with a version is provided (provides='foo=1.2') apk will consider it as an alternate name and it will automatically consider the package for installation by the alternate name, and conflict with other packages having the same name, or provides.

: If version is not provided (provides='foo'), apk will consider it as virtual package name. Several package with same non-versioned provides can be installed simultaneously. However, none of them will be installed by default when requested by the virtual name - instead, error message is given and user is asked to choose which package providing the virtual name should be installed.
==== 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 package to another, or when a package gets renamed.
==== replaces_priority ====
: The priority of the replaces. If multiple packages replace each other, then will the package with highest ''replaces_priority'' win.
==== 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).

:* You can set target filename (eg 'save as...') by prefixing the URI with ''filename::''. This is useful 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>
:: or when the filename is braindead, like githubs' download tags:
:: <pre>https://github.com/software/software/archive/v$pkgver.tar.gz</pre>
:: The above two examples needs a target filename prefix:
:: <pre>$pkgname-$pkgver.tar.gz::http://oss.example.org/?get=software&ver=$pkgver</pre>
:: and:
:: <pre>$pkgname-$pkgver.tar.gz::https://github.com/software/software/archive/v$pkgver.tar.gz</pre>

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

:: {{Note|Legacy APKBUILD scripts define ''source'' variable as "saveas-[brain-dead-url]/[target-filename]" format instead of the modern [target-filename]::[brain-dead-url]. ''BAD'': source="saveas-http://releases.ddvtech.com/download.php?pack=libmist_dist&ver=RC/$pkgname-$pkgver.tar.gz" ''GOOD'': source=$pkgname-$pkgver.tar.gz::http://releases.ddvtech.com/download.php?pack=libmist_dist&ver=RC"}}

==== 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 <code>subpkg-name</code> is the name of the '''subpackage''' and <code>subpkg_name</code> is the name of the '''subpackage's split function'''.}}

: {{Tip|For more information, see the [[APKBUILD_examples:Subpackages|Subpackages example]].}}

==== triggers ====
: Apk-tools can "monitor" directories and execute a trigger if any package installed/uninstalled any file in the monitored dir. The triggers are always execute after the apk action (install, uninstall, upgrade).

: The triggers are specified in the format: ''scriptname''=''pathlist'' where ''scriptname'' is the (sub)package name + .trigger suffix and pathlist is : separated list of the dirs to monitor.

: The '''triggers''' variable must include the triggers for subpackages too if they have any.

: It is possible to use wildcards (*) in the dir list.

==== 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. It is better to use "default_prepare || return" to handle *.patch file, and the patch file should always be prepared as -p1 format.
==== 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: <code>return 0</code>
==== check() ====
: '''Recommended.''' This function is called right after the build stage. It should check that the packaged thing is actually working, typically by running (integration) tests, if provided by upstream. If there’s no (easy) way how to test the package, you can declare that it does not want to use ''check()'' by adding "!check" into the ''options'' variable.
==== 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: <code>mkdir -p "$pkgdir"</code>

{{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 [[APKBUILD examples]] page will assist you in understanding how to create an APKBUILD.

[[Category:Development]]

Architecture

2017-05-19T22:10:33Z

TemptorSent: Added hardware archs; added to and cleaned up package building heading

== Alpine Hardware Architecture ("arch") Support ==
=== x86 Based ===
* [[x86]] - 32 bit x86 (ia32)
* [[x86_64]] - 64 bit x86 (amd64)

=== ARM Based ===
* [[armhf]]
* [[aarch64]]

=== PowerPC Based ===
* [[ppc]] - 32 bit PowerPC
* [[ppc64]] - 64 bit PowerPC (big-endian)
* [[ppc64le]] - 64 bit PowerPC (little-endian)

=== IBM System Z Based ===
* [[s390x]]

== Alpine Packaging ==

=== Package Building ===

==== Alpine Package Building Ports ====
* [[APKBUILD]] - Package build scripts
* [[aports]] - Official Alpine ports git repository

==== Package Building Tools ====
* [[abuild]]

=== Package Format ===
Alpine uses packages in the [[.apk file format]].

=== Package Management Tools ===
* [[apk]] - Alpine Package Keeper

== Boot Process ==

=== Boot Loader ===
==== EFI ====
==== BIOS ====
==== Other ====

=== Kernel ===
==== Versioning ====
===== Flavors =====
* vanilla
* hardened
* virthardened
* rpi

==== Signing ====
==== Command line options ====

* modules="<modules>" - specify list of modules to be loaded by initramfs /init needed to mount real root filesystem.

=== Initfs ===
The kernel will decompress the stream of compressed cpio archives passed to it by the 'append' bootloader option to the root of 'rootfs', a tmpfs automatically mounted at '/' by the kernel at boot.

==== '/init' Script ====
Not to be confused with '/sbin/init', the '/init' script in the root of the 'rootfs' is called by the kernel upon completion of its boot process, and is responsible for doing whatever steps are necessary to mount the real root file system to '/' and transfer control to '/sbin/init'.

* Parses kernel command line options.
* Uses [[nlplug-findfs]] to discover devices.

==== Initfs Module Handling ====
Modules required to mount the root filesystem and boot must either built into the kernel or available from with the initramfs filesystem through use of appended initrd cpio.gz files provided by the [[bootloader]].

The /init script will first [[modprobe]] the modules specified by the modules= kernel command line option and by the name of the specified rootfs type. It will then load the contents of /etc/modules, which may include module options.
Modules may be blacklisted from autoprobing (but NOT explicit insertion!) using the blacklist= kernel command line option which appends blacklist entries to '/etc/modprobe.d/boot-opt-blacklist.conf'.

==== Minimal Required Set ====
===== Directory Structure =====
* / /bin /boot /dev /etc /lib /lib/modules /media /media/cdrom /media/usb /mnt /proc /sbin /sys /usr /usr/bin /usr/sbin
===== Devices =====
* /dev/null
* /dev/console
* /dev/kmsg

===== Mounts =====
* /proc
* /sys
* /dev (can be disabled?)

===== Configuration =====
* /etc/passwd
* /etc/group
* /etc/fstab

===== Binaries =====
* [[busybox]]
* [[apk]]

==== Feature Sets ====
Feature sets consist of lists for the set of modules and files that need to be included in a final initramfs to support the indicated feature.

=== Init ===
Not to be confused with the '/init' script in the initramfs, '/sbin/init' is the first process to be started in the live system after the initramfs completes its work.

==== Module Loading ====
'/etc/init.d/modules' loads all modules specified in '/etc/modules' and '/(etc|run|usr/lib|lib)/modules-load.d/*.conf'

Architecture

2017-05-01T18:08:20Z

TemptorSent: /* Boot Process */ - Add module handling

== Packaging ==
Alpine uses packages in the [[.apk file format]].

=== Package Management Tools ===
* [[apk]]

=== Package Building Tools ===
* [[abuild]]

== Boot Process ==

=== Boot Loader ===
==== EFI ====
==== BIOS ====
==== Other ====

=== Kernel ===
==== Versioning ====
===== Flavors =====
* vanilla
* hardened
* virthardened
* rpi

==== Signing ====
==== Command line options ====

* modules="<modules>" - specify list of modules to be loaded by initramfs /init needed to mount real root filesystem.

=== Initfs ===
The kernel will decompress the stream of compressed cpio archives passed to it by the 'append' bootloader option to the root of 'rootfs', a tmpfs automatically mounted at '/' by the kernel at boot.

==== '/init' Script ====
Not to be confused with '/sbin/init', the '/init' script in the root of the 'rootfs' is called by the kernel upon completion of its boot process, and is responsible for doing whatever steps are necessary to mount the real root file system to '/' and transfer control to '/sbin/init'.

* Parses kernel command line options.
* Uses [[nlplug-findfs]] to discover devices.

==== Initfs Module Handling ====
Modules required to mount the root filesystem and boot must either built into the kernel or available from with the initramfs filesystem through use of appended initrd cpio.gz files provided by the [[bootloader]].

The /init script will first [[modprobe]] the modules specified by the modules= kernel command line option and by the name of the specified rootfs type. It will then load the contents of /etc/modules, which may include module options.
Modules may be blacklisted from autoprobing (but NOT explicit insertion!) using the blacklist= kernel command line option which appends blacklist entries to '/etc/modprobe.d/boot-opt-blacklist.conf'.

==== Minimal Required Set ====
===== Directory Structure =====
* / /bin /boot /dev /etc /lib /lib/modules /media /media/cdrom /media/usb /mnt /proc /sbin /sys /usr /usr/bin /usr/sbin
===== Devices =====
* /dev/null
* /dev/console
* /dev/kmsg

===== Mounts =====
* /proc
* /sys
* /dev (can be disabled?)

===== Configuration =====
* /etc/passwd
* /etc/group
* /etc/fstab

===== Binaries =====
* [[busybox]]
* [[apk]]

==== Feature Sets ====
Feature sets consist of lists for the set of modules and files that need to be included in a final initramfs to support the indicated feature.

=== Init ===
Not to be confused with the '/init' script in the initramfs, '/sbin/init' is the first process to be started in the live system after the initramfs completes its work.

==== Module Loading ====
'/etc/init.d/modules' loads all modules specified in '/etc/modules' and '/(etc|run|usr/lib|lib)/modules-load.d/*.conf'

Architecture

2017-04-27T23:04:43Z

TemptorSent: /* Flavors */ Update to reflect kernel name change from -grsec to -hardened

Architecture

2017-04-25T22:23:43Z

TemptorSent: Added list of kernel flavors

Architecture

2017-04-25T21:28:03Z

TemptorSent:

File Formats

2017-04-25T21:27:45Z

TemptorSent: Created page with " .apk file format"

[[.apk file format]]

Architecture

2017-04-25T21:20:33Z

TemptorSent: Initial work for overview of alpine architecture

== Packaging ==
=== Package Management Tools ===
* [[apk]]

=== Package Building Tools ===
* [[abuild]]

== Boot Process ==

=== Boot Loader ===
==== EFI ====
==== BIOS ====
==== Other ====

=== Kernel ===
==== Versioning ====
===== Flavors =====
==== Signing ====
==== Command line options ====

=== Initfs ===
The kernel will decompress the stream of compressed cpio archives passed to it by the 'append' bootloader option to the root of 'rootfs', a tmpfs automatically mounted at '/' by the kernel at boot.

==== '/init' Script ====
Not to be confused with '/sbin/init', the '/init' script in the root of the 'rootfs' is called by the kernel upon completion of its boot process, and is responsible for doing whatever steps are necessary to mount the real root file system to '/' and transfer control to '/sbin/init'.
==== Minimal Required Set ====
===== Directory Structure =====
* / /bin /boot /dev /etc /lib /lib/modules /media /media/cdrom /media/usb /mnt /proc /sbin /sys /usr /usr/bin /usr/sbin
===== Devices =====
* /dev/null
* /dev/console
* /dev/kmsg

===== Mounts =====
* /proc
* /sys
* /dev (can be disabled?)

===== Configuration =====
* /etc/passwd
* /etc/group
* /etc/fstab

===== Binaries =====
* [busybox]
* [apk]

==== Feature Sets ====
Feature sets consist of lists for the set of modules and files that need to be included in a final initramfs to support the indicated feature.

=== Init ===
Not to be confused with the '/init' script in the initramfs, '/sbin/init' is the first process to be started in the live system after the initramfs completes its work.

Developer Documentation

2017-04-25T20:24:20Z

TemptorSent: Add design docs heading and stubs.

[[Image:package_system.svg|right|link=]]

== Package management ==

* [[Alpine Linux package management|Package Management (apk)]] ''(How to add/remove packages on your Alpine)''  
** [[Comparison with other distros]]
** [[apk spec]]
* [[Edge|Upgrading to Edge]]
* [[Alpine local backup|Alpine local backup (lbu)]] ''(Permanently store your modifications in case your box needs reboot)''
** [[Back Up a Flash Memory Installation]]
** [[Manually editing a existing apkovl]]

* [[How to setup a Alpine Linux mirror]]
* [[How to use xdelta and download only differential update files]]
* [[How to make a custom ISO image]]
** [[Burning ISOs]]

== Init system ==
* [[Alpine Linux Init System|Init System (OpenRC)]] ''(Configure a service to automatically launch at next reboot)''
** [[Multiple Instances of Services]]
* [[Writing Init Scripts]]

== Development ==
=== Configuring your system ===
* [[Edge|Upgrading to Edge]] 


* [[Setting up the build environment on HDD]] 

** [[Creating_an_Alpine_package#Setup_your_system_and_account|Setup your system and account for building packages]]
** [[Abuild_and_Helpers#abuild-keygen|Abuild-keygen]]

* [[Installing Alpine Linux in a chroot]] 
** [[Buildlab]] ''(Tool for creating and managing chroots)''
* [[Install Alpine on LXC]]
* Install Alpine on [[Install Alpine on VirtualBox|VirtualBox]], [[Install Alpine on VMware|VMware]], [[Install Alpine on coLinux|coLinux]], [[Qemu]],  or [[Install Alpine on Amazon EC2|Amazon EC2]]

* [[Xen Dom0]] ''(Setting up Alpine as a dom0 for Xen hypervisor)''
** [[Xen Dom0 on USB or SD]]
** [[Create Alpine Linux PV DomU]]
** [[Xen LiveCD]]

* [[Setting up a basic vserver]] 
* [[Setting up a compile vserver]] for official or for [[Setting up a compile vserver for third party packages|third party]] packages 


=== Building from source and creating packages ===

* [[Aports tree]] 
* [[Abuild and Helpers]] ''(Scripts for packaging)''



* [[Creating an Alpine package]]



** [[Package policies]]
** [[Package Maintainers]]
* [[Custom Kernel]]
* [[APKBUILD Reference]]
* [[APKBUILD examples]]
* [[Alpine package format]]
* [[Apkindex format]]

* [[Development using git]] 
** [[Development using git:Basic usage|Basic usage]]
** [[Package Maintainers]]
** [[Creating patches]]
** [[Development using git:Developer repositories|Developer repositories]]
** [[Development using git:Cgit|Cgit]]
** [[Cgit|Another cgit page]]

=== Misc ===

* [[Alpine Package Testing Suite]] ''work in progress''
* [[Alpine Release Testing Checklist]]
* [[Running glibc programs]]
* [[Alpine Source Map by boot sequence]]

== Alpine Configuration Framework ==
{{Draft|Needs to be organized/consolidated.}}

* [[Alpine Configuration Framework Design]] (Why ACF is the way it is)
* [[Writing User Documentation for ACF]]
* [[ACF mvc.lua reference|mvc.lua reference]] - mvc.lua is the core of ACF
* [[ACF mvc.lua example|mvc.lua example]] - build a simple (command-line) application
* [[ACF acf www-controller.lua reference|acf www-controller reference]] - ACF www application functions
* [[ACF acf www example|acf www-controller example]] - webify the above examples
* [[ACF how to write]] - Step by step howto for writing acfs
* [[ACF core principles]] - Things that are standard across the application
* [[LuaPosix]] - Documentation for the Lua Posix functions
* [[ACF Libraries]] - Document the libraries and common functions
* [[Writing ACF Views]] - Guide for writing a view
* [[Writing ACF Controllers]] - Guide for writing a controller
* [[Writing ACF Models]] - Guide for writing a model

* [[ACF css]]
* [[ACF packages]]
* [[APKBUILD examples:ACF]]
* [[Apk.lua]]
* [[Changing passwords for ACF]]
* [[Generating SSL certs with ACF]]
* [[Generating SSL certs with ACF 1.9]]
* [[Getting started with ACF development]]
* [[Managing ACF]]

== Alpine-developed Utilities ==
* [[Alpine Wall]] - [[How-To Alpine Wall]] - [[Alpine Wall User's Guide]] ''(a new firewall management framework)''

== Alpine Design Docs ==
* [[Architecture]]
* [[File Formats]]

[[Category:Development]]