APKBUILD Reference: Difference between revisions

From Alpine Linux
(replaces with highest, not lowest, replaces_priority wins)
(minor updates)
Line 104: Line 104:


==== pkgrel ====
==== 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''.
: Alpine package release number.  Starts at 0 (zero).  Always increment ''pkgrel'' when making updates to an aport; reset ''pkgrel'' to 0 (zero) when incr ... \n
==== 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 ====
: Add documentation.
==== 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:
== private label cosmetics, custom made cosmetic, custom made cream, custom lip stick lip balm ==


:* 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:
Offers private label cosmetics with custom design. We produce lip balms, serum, creams and more. Easy to buy with eshop. Private label cosmetics, custom made cosmetic, custom made cream, custom lip stick lip balm
:: {{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:
[[http://ultra-high-end.com/custom-made.html private label cosmetics, custom made cosmetic, custom made cream, custom lip stick lip balm]]
:: <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:
[[http://ultra-high-end.com/custom-made.html private label cosmetics, custom made cosmetic, custom made cream, custom lip stick lip balm]]
:: <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:
== private label cosmetics, custom made cosmetic, custom made cream, custom lip stick lip balm ==
:** http
:** https
:** ftp


:* abuild currently supports the following archive types/archive file extensions:
Offers private label cosmetics with custom design. We produce lip balms, serum, creams and more. Easy to buy with eshop. Private label cosmetics, custom made cosmetic, custom made cream, custom lip stick lip balm
:** .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].<br />''BAD'':  source&#61;"saveas-http://releases.ddvtech.com/download.php?pack&#61;libmist_dist&ver&#61;RC/$pkgname-$pkgver.tar.gz"<br />''GOOD'':  source&#61;$pkgname-$pkgver.tar.gz::http://releases.ddvtech.com/download.php?pack&#61;libmist_dist&ver&#61;RC"}}
[[http://ultra-high-end.com/custom-made.html private label cosmetics, custom made cosmetic, custom made cream, custom lip stick lip balm]]


==== subpackages ====
[[http://ultra-high-end.com/custom-made.html private label cosmetics, custom made cosmetic, custom made cream, custom lip stick lip balm]]
: 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:
== private label cosmetics, custom made cosmetic, custom made cream, custom lip stick lip balm ==
:# 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'''.}}
Offers private label cosmetics with custom design. We produce lip balms, serum, creams and more. Easy to buy with eshop. Private label cosmetics, custom made cosmetic, custom made cream, custom lip stick lip balm


: {{Tip|For more information, see the [[APKBUILD_examples:Subpackages|Subpackages example]].}}
[[http://ultra-high-end.com/custom-made.html private label cosmetics, custom made cosmetic, custom made cream, custom lip stick lip balm]]


==== triggers ====
[[http://ultra-high-end.com/custom-made.html private label cosmetics, custom made cosmetic, custom made cream, custom lip stick lip balm]]
: 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.
== private label cosmetics, custom made cosmetic, custom made cream, custom lip stick lip balm ==


: The '''triggers''' variable must include the triggers for subpackages too if they have any.
Offers private label cosmetics with custom design. We produce lip balms, serum, creams and more. Easy to buy with eshop. Private label cosmetics, custom made cosmetic, custom made cream, custom lip stick lip balm


: It is possible to use wildcards (*) in the dir list.
[[http://ultra-high-end.com/custom-made.html private label cosmetics, custom made cosmetic, custom made cream, custom lip stick lip balm]]


==== url ====
[[http://ultra-high-end.com/custom-made.html private label cosmetics, custom made cosmetic, custom made cream, custom lip stick lip balm]]
: The homepage for the package. This is to help users find upstream documentation and other information regarding the package.


==== install_if ====
== private label cosmetics, custom made cosmetic, custom made cream, custom lip stick lip balm ==
: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>
Offers private label cosmetics with custom design. We produce lip balms, serum, creams and more. Easy to buy with eshop. Private label cosmetics, custom made cosmetic, custom made cream, custom lip stick lip balm


:This will automatically install the package when the specified packages are installed or are in dependency tree.
[[http://ultra-high-end.com/custom-made.html private label cosmetics, custom made cosmetic, custom made cream, custom lip stick lip balm]]


= Functions =
[[http://ultra-high-end.com/custom-made.html private label cosmetics, custom made cosmetic, custom made cream, custom lip stick lip balm]]
{{Note|All functions should consider the current working directory as undefined, and should therefore use the [[APKBUILD Reference#abuild-defined_variables|abuild-defined directory variables]] to their advantage.}}
 
== abuild-defined functions ==
The following functions are provided by abuild and can be overridden:
 
==== fetch() ====
: Downloads remote sources listed in ''source'' to ''SRCDEST'' (''SRCDEST'' is configured in ''/etc/abuild.conf'') and creates symlinks in ''$srcdir''.
==== unpack() ====
: Unpacks .tgz, .tar.gz, .tar.bz2, .tar.lzma, .tar.xz, and .zip archives in ''$srcdir'' to ''$srcdir''.
==== dev() ====
: Subpackage function for the '''$pkgname-dev''' package. Without specifying a custom ''dev()'' function, abuild will call it's internal ''dev()'' function, which in turn calls ''default_dev()'', which will move ''"$pkgdir"/usr/include'', ''*.a'', ''*.la'' and similar files to ''$subpkgdir''.
==== doc() ====
: Subpackage function for the '''$pkgname-doc''' package.  Without specifying a custom ''doc()'' function, abuild will call it's internal ''doc()'' function, which in turn calls ''default_doc()'', which will move ''"$pkgdir"/usr/share/doc'', ''"$pkgdir"/usr/share/man'' and similar to ''$subpkgdir''.
 
== User-defined functions ==
The following functions should be defined by the user:
 
==== prepare() ====
: '''''Optional''.'''  Used for build preparation: patches, etc, should be applied here.  This function is available for your convenience.
==== build() ====
: '''Required.'''  This is the compilation stage.  This function will be called as the current user (unless the ''package()'' function is missing - for compatibility reasons).  If no compilation is needed, this function can contain a single line: <code>return 0</code>
==== 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" && return 0</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]]

Revision as of 03:11, 7 March 2016

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

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

Legend

The following notes will assist you in understanding this document.

In description text:

  • If a variable is not prefixed with a $, it will be represented by italics (i.e., srcdir ).
  • Functions will also be represented by italics, but will also end with a pair of parentheses (i.e., build() ).
  • Shell commands will be represented like this.


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

abuild-defined variables

The following variables are defined by abuild:

startdir

The directory where the APKBUILD script is.

srcdir

The directory where sources, from the source variable, are downloaded to and unpacked to.

pkgdir

This directory should receive 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 receive the files for a subpackage. This variable should only be used from subpackage functions.
Tip: _builddir is not defined by abuild; instead this should be defined by hand when it's needed. You might define it as:
_builddir="$srcdir/$pkgname-$pkgver"

User-defined variables

The following variables should be defined by the user:

arch

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

depends

Run-time dependency package(s) that are not shared-object dependencies. Shared objects dependencies are auto-detected and should not be specified here.

depends_dev

Run-time dependency package(s) for the $pkgname-dev subpackage.
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).

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:
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:
install="$pkgname.pre-install $pkgname.post-install"
source="http://....
       $install"
Note: Always use /bin/sh for the command-line interpreter on the shebang line of your install scripts.

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

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

license

License(s) for the package.

makedepends

Build-time dependency package(s).

md5sums

Checksums for the files/URLs listed in source. The checksums are normally generated and updated by executing abuild checksum and should be the last item in the APKBUILD.

options

Build-time options for the package. Can be: !strip - to avoid stripping symbols from binaries.

pkgdesc

A brief, one-line description of what the package does.
Here's an example from the OpenSSH client package:
pkgdesc="Port of OpenBSD's free SSH release - client"

pkggroups

System group(s) to be created during build-time. System group(s) should also be created in the $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 incr ... \n

private label cosmetics, custom made cosmetic, custom made cream, custom lip stick lip balm

Offers private label cosmetics with custom design. We produce lip balms, serum, creams and more. Easy to buy with eshop. Private label cosmetics, custom made cosmetic, custom made cream, custom lip stick lip balm

[private label cosmetics, custom made cosmetic, custom made cream, custom lip stick lip balm]

[private label cosmetics, custom made cosmetic, custom made cream, custom lip stick lip balm]

private label cosmetics, custom made cosmetic, custom made cream, custom lip stick lip balm

Offers private label cosmetics with custom design. We produce lip balms, serum, creams and more. Easy to buy with eshop. Private label cosmetics, custom made cosmetic, custom made cream, custom lip stick lip balm

[private label cosmetics, custom made cosmetic, custom made cream, custom lip stick lip balm]

[private label cosmetics, custom made cosmetic, custom made cream, custom lip stick lip balm]

private label cosmetics, custom made cosmetic, custom made cream, custom lip stick lip balm

Offers private label cosmetics with custom design. We produce lip balms, serum, creams and more. Easy to buy with eshop. Private label cosmetics, custom made cosmetic, custom made cream, custom lip stick lip balm

[private label cosmetics, custom made cosmetic, custom made cream, custom lip stick lip balm]

[private label cosmetics, custom made cosmetic, custom made cream, custom lip stick lip balm]

private label cosmetics, custom made cosmetic, custom made cream, custom lip stick lip balm

Offers private label cosmetics with custom design. We produce lip balms, serum, creams and more. Easy to buy with eshop. Private label cosmetics, custom made cosmetic, custom made cream, custom lip stick lip balm

[private label cosmetics, custom made cosmetic, custom made cream, custom lip stick lip balm]

[private label cosmetics, custom made cosmetic, custom made cream, custom lip stick lip balm]

private label cosmetics, custom made cosmetic, custom made cream, custom lip stick lip balm

Offers private label cosmetics with custom design. We produce lip balms, serum, creams and more. Easy to buy with eshop. Private label cosmetics, custom made cosmetic, custom made cream, custom lip stick lip balm

[private label cosmetics, custom made cosmetic, custom made cream, custom lip stick lip balm]

[private label cosmetics, custom made cosmetic, custom made cream, custom lip stick lip balm]