PKGBUILD(5)

DESCRIPTION

PKGBUILD files are simple Bash scripts that tell debmaker(8) how to build a package.

Users just provide the needed variables and functions, then debmaker creates a package than can be installed directly via APT(8).

VARIABLES

A completely basic PKGBUILD would contain the pkgname, pkgver, pkgrel, and arch variables, which debmaker(8) requires in order to build a package.

If you need to set custom variables for your own use in a build script, it is recommended to prefix the variable name with an underscore (_) to prevent any possible naming collisions with internal variables used by debmaker(8) (i.e. instead of using varname as a variable name, use _varname instead).

KEY

required: Needed in order to build a package.
optional: May be omitted.
function: The variable’s value may be changed inside of debmaker’s packaging functions.
nofunction: The variable’s value can not be changed inside of debmaker’s packaging functions.
string: Variable must be a string.
array: Variable must be an array.
mixed: Variable can be either a string or an array.

PACKAGE NAME

pkgbase (optional, nofunction, string): The package base used to refer to a group of packages. Usually you don’t need this set unless your PKGBUILD is building multiple packages. Defaults to ${pkgname[0]} if not set.
pkgname (required, nofunction, mixed): The package name set inside of the built package.

PACKAGE VERSION

The components of a package version combine to make a single string, that being the version of a package.

The following rules show how a version is generated:: 1. Epoch is present: ${epoch}:${pkgver}-${pkgrel}
2. Epoch is not present: ${pkgver}-${pkgrel}
pkgver (required, nofunction, string): The version number of a package. If packaging from a upstream source that is also versioned, this should generally be kept the same as said source’s version unless required to work properly with debmaker(8). Allowed characters are all alphanumerics, periods (.) and plus signs (+).
pkgrel (required, nofunction, string): The release number of a package. This variable should be set to 1 by default, and then incremented by 1 as additional changes are made to the PKGBUILD that require pkgver to not change. Whenever pkgver does change, this variable should be reset back to 1.
epoch (optional, nofunction, string): This forces the package to be seen as a newer version than any other with a lower version (i.e. 2:1.1 is greater than 1:3.7). This variable shouldn’t be used in most packages, and should only be added when absolutely required to do so (such as when an upstream source changes their version numbering scheme).

GENERIC

Maintainer (mandatory, nofunction, string): The maintainer of a package. The maintainer should be listed with their name followed by their email (i.e. Foo Bar <foobar@example.com>).

This variable is unique in that it’s given in the form of a comment (see below). This is due to the PKGBUILD format seen on Arch Linux (from which debmaker was originally based), where maintainers are also listed in such a fashion.

To list a maintainer, use the following format, preferrably at the top of the PKGBUILD:

# Maintainer: Foo Bar <foobar@example.com>

NOTE: Only one maintainer may be listed. If more than one is listed, debmaker will fall back to the first one listed. Specifying multiple maintainers will be an error in a future release.
pkgdesc (mandatory, function, string): The description of a package. This can be of any length, but should not be multiple lines. All characters are allowed except colons (:).
arch (mandatory, nofunction, array): Sets what system architectures a package can be built on. Architectures in this list should be set to those found in the output of 'dpkg --print-architecture' (dpkg(1)).

The current system’s architecture can be accessed during builds via the ${DEBMAKER_DPKG_ARCHITECTURE} environment variable.
url (optional, function, string): The URL of the software being packaged. When a website doesn’t exist for the upstream project, this is commonly set to the URL of a VCS repository.
license (optional, function, array): Sets the license(s) under which a program is distributed. This should be set to the name of a license under /usr/share/common-licenses/ or should otherwise be set to custom.

NOTE: When using custom, you can also attach a license suffix like so:

license=('custom: name of license')

When using custom, it is also recommended to install the license under /usr/share/doc/pkgname/copyright/, replacing pkgname with the name of the package.
backup (optional, function, array): A list of files to be treates as conffiles(deb-conffiles(5)). Entries should start with a forward slash (i.e. /etc/pkgname.conf).

DEPENDENCIES

depends (optional, function, array): A list of packages needed to execute a program. When listed as a variable from the root of a PKGBUILD, the dependencies get installed before a build takes place. If placed inside of a function such as package(), the dependencies get marked as needed by the built package, but won’t be checked for while building.

Version restrictions can be specified via comparison operators (>, >=, =, ⇐, <) to require a certain version of a package.
If you need more specificity than the above allows (i.e. greater than one version, while also less than another), you can repeat the package name multiple times with each operator, i.e.: depends=('foo>=1.0.0' 'foo<2.0.0')
makedepends (optional, nofunction, array): An array of packages that are only required to build a program. This variable
takes the same syntax as depends. Packages put here will be removed when
using debmaker’s -r option. Any packages listed under depends should not be duplicated here.
checkdepends (optional, nofunction, array): An array of packages needed to run the check() function in a PKGBUILD. This variable behaves the same way as makedepends.

BUG: Packages in this list should only be checked for when the check() function is present and command-line arguments aren’t stopping the function from running (likewise though, they aren’t). Currently that means this variable is quite interchangeable with makedepends, though you shouldn’t rely on that behavior.
optdepends (optional, function, array): An array of packages that aren’t required for a program to run, but add additional features. Packages in this list won’t be checked as build dependencies, regardless of where placed. If you need said behavior, add said packages to makedepends or checkdepends.
This variable takes the same syntax as depends with a few additions:: 1. Packages listed here may optionally be prefixed with r! or s!. Adding the r! prefix will mark said dependency as recommended in the built package, while adding s! or simply omitting any prefix will mark the package as suggested (deb-control(5)).

2. Packages listed here can be prefixed with a description of what functionality the dependency adds like so:

optdepends=('cups: printing support')
conflicts (optional, function, array): A list of packages that the built package can’t be installed at the same time with. This variable takes the same syntax as depends. Any packages listed here will be required to be uninstalled before the built package can be installed. Specifying comparison operators will cause the package to only conflict with package versions that the operator covers.
provides (optional, function, array): A list of packages that the built package provides the dependency for. For example, if the PKGBUILD is building the foo-new program and another package depends on foo, you could put the following in a PKGBUILD to make foo-new satisfy the dependency:

provides=('foo')

NOTE: Only the equality operator (i.e. foo=1.0) may be used here, as per the Debian control file specification.

Specifying comparison operators here will cause the provided package to only be provided for when other packages request a version that fits the specified operator. This variable also takes the same syntax as depends.

PACKAGING SCRIPTS

It’s possible to specify certain scripts as part of your package which will get automatically ran when your package is installed, upgraded, or removed.

To specify these files in a PKGBUILD, just specify the variable name like you would for any other variable, then enter the path to the script in relation to the directory containing the PKGBUILD file.

The only requirement for running the scripts is that they must be properly executable. This means that the scripts (or programs rather) may come precompiled in the form of a binary, or should start with the standard interpreter shebang (i.e. #!/usr/bin/env bash) on the first line of the script.

All programs that are called here MUST return a zero exit status for success, or any other exit code for failure, as the package manager will use such to determine what action to take next.

Maintainer scripts are also not guaranteed to be ran via a terminal that can interact with the user, and should be able to fall back to noninteractive behavior if no interactive terminal is available.

Lastly, it is important that actions that occur in maintainer scripts can occur multiple times. As in, for example, if a maintainer script does a certain action, that action (or execution of the script anyway) should be able to happen again without causing any harm to the user’s system.

WAYS SCRIPTS ARE CALLED
See https://www.debian.org/doc/debian-policy/ch-maintainerscripts.html#summary-of-ways-maintainer-scripts-are-called for details on the various ways that maintainer scripts can be called.

preinst (optional, function, array): A string that specifies the path to a script to execute before a package is unpacked onto a user’s system.
postinst (optional, function, array): A string that specifies the path to a script to execute after a package is unpacked onto a user’s system.
prerm (optional, function, array): A string that specifies the path to a script to execute before a package is removed from a user’s system.
postrm (optional, function, array): A string that specifies the path to a script to execute after a package is removed from a user’s system.

OTHER

extensions (optional, nofunction, array): A list of extensions to be called during execution. This defaults to extensions=('strip' 'zipman') if not set. See debmaker-extension(5) for information on the directory structure and file formats for extensions.

Note that debmaker reserves the extension all command names starting with debmaker-{extension} (where {extension} is the extension name). Declaring any functions with such a name in your PKGBUILD may result in naming conflicts with extensions, and is undefined behavior.

SOURCES

source (optional, nofunction, array): A list of files needed to build a package. Files should be specified via a URI such as with FTP and HTTP. Previously defined variables can also be used effectively here:

source=("https://example.com/${pkgname}-${pkgver}.tar.gz")

Files in the source array that have a .sig, .sign or .asc extension are recognized by debmaker as PGP signatures and will be automatically used to verify the integrity of the source file under the same name.

You can also prefix the source with name::, which allows you to specify where the file is saved to after a download:

source=("package-file::https://example.com/${pkgname}-${pkgver}.tar.gz")
noextract (optional, nofunction, array): A list of archive files from source which should not be automatically extracted by debmaker. This can be useful when you can’t/don’t want to use debmaker’s automatic extraction features or you need to install an archive as-is onto a system. The items in this list should point to the filename of downloaded files, not the full URL (i.e. that being ${pkgname}-${pkgver}.tar.gz in our previous example).

USING VCS SOURCES

debmaker currently has native support for building from Git and SVN sources. While you could pull such sources manually in a function such as prepare(), debmaker provides utilities to do such automatically.

To use these kind of sources, add your source URLs in the source array, and prepend the source name with either git+ or svn+, for Git and SVN respectively. If using a name:: prefix, place the VCS prefix after it. For example:: source=('https://git.goral.net.pl/debmaker.git/')
source=('debmaker -src::git+https://git.goral.net.pl/debmaker.git/')
When using the Git VCS, you can also specify a #key=value parameter, where key is one of the following:: branch: A Git branch to checkout to.
commit: A Git commit to checkout to.
tag: A Git tag to checkout to.
For example:: source=('git+https://git.goral.net.pl/debmaker.git/#tag=v15.0.2-stable')

INTEGRITY

An array of checksums for files in the source array. The number of items in this array must match that in source, with each item corresponding to that in source in the order they appear. The checksums in this array should always be those provided by the upstream program/distributor.

The following checksum types are supported, and should be entered in the format {checksum}sums (i.e. sha256sums):: md5
sha1
sha224
sha256
sha384
sha512
b2
At minimum, one of these types must be present, though you may have more than one if you prefer. If you otherwise would prefer to avoid any hash checks, simply choose any checksum type (sha256 is historically used) and set all of its values to SKIP:: sha256sums=('SKIP')

DISTRO AND ARCHITECTURE SPECIFIC VARIABLES

debmaker sets two notable variables during every run, DEBMAKER_DISTRO_CODENAME and DEBMAKER_DPKG_ARCHITECTURE.

DEBMAKER_DISTRO_CODENAME specifies the current distribution of the OS, as seen by the output of 'lsb_release -cs' (lsb_release(1)). DEBMAKER_DPKG_ARCHITECTURE specifies the current system’s architecture, as reported by 'dpkg --print-architecture' (dpkg(1)).

Some variables that debmaker uses can be optionally prefixed with distro codenames and appended with system archiectures. Those variables are currently checkdepends, conflicts, depends, makedepends, optdepends, provides, replaces, source, control_fields, cksums, md5sums, sha1sums, sha224sums, sha256sums, sha384sums, sha512sums, and b2sums.

For example, if you wanted to have a global list of dependencies, and then a specific list of dependencies when the user is running Ubuntu 20.04 Focal Fossa, you could use the following:: depends=('pkg1' 'pkg2')
jammy_depends=('pkg3' 'pkg4')
As another example, if you wanted to have a global list of dependencies, and then a different list when the user’s system architecture is amd64, you could do the following:: depends=('pkg1' 'pkg2')
depends_amd64=('pkg3' 'pkg4')
Furthermore, you may also combine these values to create a specificity that requires both a certain distro and a certain architecture:: depends=('pkg1' 'pkg2')
jammy_depends_amd64=('pkg1' 'pkg2')
When more than one of these variables are present (say you had all four options), debmaker uses the following lookup order to decide which variable to use (with the first being of highest priority):: 1. ${DEBMAKER_DISTRO_CODENAME}_depends_${DEBMAKER_DPKG_ARCHITECTURE}
2. ${DEBMAKER_DISTRO_CODENAME}_depends
3. depends_${DEBMAKER_DPKG_ARCHITECTURE}
4. depends

This logic also applies to all other variables supporting prefixes and suffixes.

Note that when using this functionality under the source variable, one or more matching hashsum variables must also be present containing the same distro codename and system architecture (i.e. if jammy_source_amd64 is present, a hashsum such as jammy_sha256sums_amd64 and/or jammy_sha512sums_amd64 must also be present).

FUNCTIONS

When building a package, debmaker *(8) will call the following five functions if they have been defined in the PKGBUILD. The *package() function must always be present; omitting any of the rest will simply cause debmaker to skip running it.

prepare(): This function defines commands used to prepare sources for building, such as patching. This function runs right after package sources are extracted, and before the pkgver() and build() functions. This function is run with the errexit Bash option, which will cause the function to immediately exit if any of the contained commands exit with a non-zero status code.
pkgver(): pkgver() is executed after prepare() is ran. This function should output a valid version identifier, which debmaker *(8) will automatically update the package version to. This can be particularly useful when working with VCS sources such as Git, where packages may receive updates multiple times a day (in which case it would be quite inconvenient to continuously update the *pkgver variable).
build(): This function is called after prepare() and pkgver(), and should contain commands needed to properly build a program. debmaker *(8) will change the current directory to *${srcdir} (which will be ./src/ from the directory containing the PKGBUILD) before executing build(), which will then put you into the directory containing all sources obtained from the source array.
check(): This function should contain make check and/or other commands used to check if a program was built correctly and all needed dependencies are installed.
package(): This final step is used to actually put the files previously created into a directory where debmaker can package up your program properly. The folder to place said files in is ${pkgdir}, which mimics the directory structure of an actual system (i.e. ${pkgdir}/etc/config.conf points to /etc/config.conf when the package is actually installed). Your system will still be under the ${srcdir} directory when this function is first called, allowing you to easily copy files over to the package directory from previous steps.

NOTE
You should not create files under ${pkgdir}/DEBIAN/, as *debmaker *(8) uses that folder to create metadata for the built package.

PKGBUILD(5) Manual Page

NAME