PKGBUILD
Summary |
---|
An explanation of PKGBUILD variables when creating packages. |
Overview |
Related |
Creating -libre packages |
VCS PKGBUILD Guidelines |
A PKGBUILD is an Parabola package build description file used when creating packages.
Packages in Parabola GNU/Linux-libre are built using the makepkg utility and information stored in PKGBUILD files. When makepkg is run, it searches for a PKGBUILD in the current directory and follows the instructions therein to either compile or otherwise acquire the files to build a package file (pkgname.pkg.tar.xz). The resulting package contains binary files and installation instructions, readily installed with pacman.
Contents
- 1 Variables
- 1.1 pkgname
- 1.2 pkgver
- 1.3 pkgrel
- 1.4 epoch
- 1.5 pkgdesc
- 1.6 arch
- 1.7 url
- 1.8 license
- 1.9 groups
- 1.10 depends
- 1.11 makedepends
- 1.12 checkdepends
- 1.13 optdepends
- 1.14 provides
- 1.15 conflicts
- 1.16 replaces
- 1.17 backup
- 1.18 options
- 1.19 install
- 1.20 source
- 1.21 noextract
- 1.22 md5sums
- 1.23 sha1sums
- 1.24 sha256sums, sha384sums, sha512sums
- 2 See also
- 3 Acknowledgement
1 Variables
The following are variables that can be filled out in the PKGBUILD file.
It is common practice to define the variables in the PKGBUILD in same order as given here. However, this is not mandatory, as long as correct Bash syntax is used.
1.1 pkgname
The name of the package. It should consist of alphanumeric characters and dashes ('-') and all letters should be lowercase. For the sake of consistency, pkgname should match the name of the source tarball of the software you are packaging. For instance, if the software is in foobar-2.5.tar.gz, the pkgname value should be foobar. The present working directory the PKGBUILD file is in should also match the pkgname.
1.2 pkgver
The version of the package. The value should be the same as the version released by the author of the package. It can contain letters, numbers and periods but CANNOT contain a hyphen. If the author of the package uses a hyphen in their version numbering scheme, replace it with an underscore. For instance, if the version is 0.99-10, it should be changed to 0.99_10. If the pkgver variable is used later in the PKGBUILD then the underscore can easily be substituted for a dash on usage e.g.:
source=($pkgname-${pkgver//_/-}.tar.gz)
1.3 pkgrel
The release number of the package specific to Parabola. This value allows users to differentiate between consecutive builds of the same version of a package. When a new package version is first released, the release number starts at 1. As fixes and optimizations are made to the PKGBUILD file, the package will be re-released and the release number will increment by 1. When a new version of the package comes out, the release number resets to 1.
1.4 epoch
An integer value, specific to Parabola, representing what 'lifetime' to compare version numbers against. This value allows overrides of the normal version comparison rules for packages that have inconsistent version numbering, require a downgrade, change numbering schemes, etc. By default, packages are assumed to have an epoch value of 0. Do not use this unless you know what you are doing.
1.5 pkgdesc
The description of the package. The description should be about 80 characters or less and should not include the package name in a self-referencing way. For instance, "Nedit is a text editor for X11" should be written as "A text editor for X11."
1.6 arch
An array of architectures that the PKGBUILD file is known to build and work on. Currently, it should contain i686 and/or x86_64, arch=('i686' 'x86_64'). The value any can also be used for architechture-independent packages.
You can access the target architecture with the variable $CARCH during a build, and even when defining variables. See also Issue#16352. Example:
depends=(foobar) if test "$CARCH" == x86_64; then depends=("${depends[@]}" lib32-glibc) fi
1.7 url
The URL of the official site of the software being packaged.
1.8 license
The license under which the software is distributed. A licenses-libre package has been created in [libre] that stores free licenses in /usr/share/licenses/common, e.g. /usr/share/licenses/common/GPL.
Once a license is used in two or more packages in an official repository, it becomes a part of the licenses-libre package.
- The BSD, MIT, zlib/png and Python licenses are special cases and could not be included in the licenses-libre package. For the sake of the license freedom, it is treated as a non-free license (license=('BSD'), license=('MIT'), license=('ZLIB') and license=('Python')) because each one has its own copyright line.
Some packages may not be covered by a single license. In these cases, multiple entries may be made in the license array, e.g. license=('GPL' 'LGPL3').
- Additionally, the (L)GPL has many versions and permutations of those versions. For (L)GPL software, the convention is:
- (L)GPL - (L)GPLv2 or any later version
- (L)GPL2 - (L)GPL2 only
- (L)GPL3 - (L)GPL3 or any later version
1.9 groups
The group the package belongs in. For instance, when you install the kdebase package, it installs all packages that belong in the kde group.
1.10 depends
An array of package names that must be installed before this software can be run. If a software requires a minimum version of a dependency, the >= operator should be used to point this out, e.g. depends=('foobar>=1.8.0'). You do not need to list packages that your software depends on if other packages your software depends on already have those packages listed in their dependency. For instance, gtk2 depends on glib2 and glibc. However, glibc does not need to be listed as a dependency for gtk2 because it is a dependency for glib2.
1.11 makedepends
An array of package names that must be installed to build the software but unnecessary for using the software after installation. You can specify the minimum version dependency of the packages in the same format as the depends array.
1.12 checkdepends
An array of packages this package depends on to run its test suite but are not needed at runtime. Packages in this list follow the same format as depends. These dependencies are only considered when the check() function is present and is to be run by makepkg.
1.13 optdepends
An array of package names that are not needed for the software to function but provides additional features. A short description of what each package provides should also be noted. An optdepends may look like this:
optdepends=('cups: printing support' 'sane: scanners support' 'libgphoto2: digital cameras support' 'alsa-lib: sound support' 'giflib: GIF images support' 'libjpeg: JPEG images support' 'libpng: PNG images support')
1.14 provides
An array of package names that this package provides the features of (or a virtual package such as cron or sh). If you use this variable, you should add the version (pkgver and perhaps the pkgrel) that this package will provide if dependencies may be affected by it. For instance, if you are providing a modified qt package named qt-foobar version 3.3.8 which provides qt then the provides array should look like provides=('qt=3.3.8'). Putting provides=('qt') will cause to fail those dependencies that require a specific version of qt. Do not add pkgname to your provides array, this is done automatically.
1.15 conflicts
An array of package names that may cause problems with this package if installed. You can also specify the version properties of the conflicting packages in the same format as the depends array.
1.16 replaces
An array of obsolete package names that are replaced by this package, e.g. replaces=('ethereal') for the wireshark package. After syncing with pacman -Sy, it will immediately replace an installed package upon encountering another package with the matching replaces in the repositories. If you are providing an alternate version of an already existing package, use the conflicts variable which is only evaluated when actually installing the conflicting package.
1.17 backup
An array of files to be backed up as file.pacsave when the package is removed. This is commonly used for packages placing configuration files in /etc. The file paths in this array should be relative paths (e.g. etc/pacman.conf) not absolute paths (e.g. /etc/pacman.conf).
1.18 options
This array allows you to override some of the default behavior of makepkg. To set an option, include the option name in the array. To reverse the default behavior, place an ! at the front of the option. The following options may be placed in the array:
- strip - Strips symbols from binaries and libraries. If you frequently use a debugger on programs or libraries, it may be helpful to disable this option.
- docs - Save /doc directories.
- libtool - Leave libtool (.la) files in packages.
- emptydirs - Leave empty directories in packages.
- zipman - Compress man and info pages with gzip.
- ccache - Allow the use of ccache during build. More useful in its negative form !ccache with select packages that have problems building with ccache.
- distcc - Allow the use of distcc during build. More useful in its negative form !distcc with select packages that have problems building with distcc.
- buildflags - Allow the use of user-specific buildflags (CFLAGS, CXXFLAGS, LDFLAGS) during build. More useful in its negative form !buildflags with select packages that have problems building with custom buildflags.
- makeflags - Allow the use of user-specific makeflags during build. More useful in its negative form !makeflags with select packages that have problems building with custom makeflags.
1.19 install
The name of the .install script to be included in the package. pacman has the ability to store and execute a package-specific script when it installs, removes or upgrades a package. The script contains the following functions which run at different times:
- pre_install - The script is run right before files are extracted. One argument is passed: new package version.
- post_install - The script is run right after files are extracted. One argument is passed: new package version.
- pre_upgrade - The script is run right before files are extracted. Two arguments are passed in the following order: new package version, old package version.
- post_upgrade - The script is run after files are extracted. Two arguments are passed in the following order: new package version, old package version.
- pre_remove - The script is run right before files are removed. One argument is passed: old package version.
- post_remove - The script is run right after files are removed. One argument is passed: old package version.
Each function is run chrooted inside the pacman install directory.
1.20 source
If you use a SRCBUILD, then this will be the source file that SRCBUILD made ("$pkgname-$pkgver-$pkgrel-$arch.src.tar.gz"
), and don't forget its checksum. Otherwise, this is an array of files which are needed to build the package. It must contain the location of the software source, which in most cases is a full HTTP or FTP URL. The previously set variables pkgname and pkgver can be used effectively here (e.g. source=(http://example.com/$pkgname-$pkgver.tar.gz))
1.21 noextract
An array of files listed under the source array which should not be extracted from their archive format by makepkg. This most commonly applies to certain zip files which cannot be handled by /usr/bin/bsdtar because libarchive processes all files as streams rather than random access as unzip does. In these situations unzip should be added in the makedepends array and the first line of the build() function should contain:
cd $srcdir/$pkgname-$pkgver unzip [source].zip
Note that while the source array accepts URLs, noextract is just the file name portion. So, for example, you would do something like this (simplified from grub2's PKGBUILD):
source=("http://ftp.archlinux.org/other/grub2/grub2_extras_lua_r20.tar.xz") noextract=("grub2_extras_lua_r20.tar.xz")
To extract nothing, you can do something fancy like this (taken from icecat-i18n):
noextract=(${source[@]##*/})
Note that a more conservative Bash substitution would include quotes, or possibly even a loop that calls basename. If you have read this far, you should get the idea.
1.22 md5sums
An array of MD5 checksums of the files listed in the source array. Once all files in the source array are available, an MD5 hash of each file will be automatically generated and compared with the values of this array in the same order they appear in the source array. While the order of the source files itself does not matter, it is important that it matches the order of this array since makepkg cannot guess which checksum belongs to what source file. You can generate this array quickly and easily using the command makepkg -g in the directory that contains the PKGBUILD file. Note that the MD5 algorithm is known to have weaknesses, so you should consider using a stronger alternative.
1.23 sha1sums
An array of SHA-1 160-bit checksums. This is an alternative to md5sums described above, but it is also known to have weaknesses, so you should consider using a stronger alternative. To enable use and generation of these checksums, be sure to set up the INTEGRITY_CHECK option in /etc/makepkg.conf. See man makepkg.conf.
1.24 sha256sums, sha384sums, sha512sums
An array of SHA-2 checksums with digest sizes 256, 384 and 512 bits respectively. These are alternatives to md5sums described above and are generally believed to be stronger. To enable use and generation of these checksums, be sure to set up the INTEGRITY_CHECK option in /etc/makepkg.conf. See man makepkg.conf.
2 See also
- Example PKGBUILD file
- Example .install file
- Creating -libre packages for more information on creating packages
- Custom local repository for information on using packages after they have been created
- Parabola Packaging Standards for various guidelines