Difference between revisions of "PKGBUILD"

From ArchWiki
Jump to: navigation, search
(Remove "pkgdir" (useless) + Phase out MD5 (collision vulnerable) + Use generic headings — Is it just me or does it look beautiful?)
(Clarify the preface)
Line 25: Line 25:
 
{{Related articles end}}
 
{{Related articles end}}
  
A '''PKGBUILD''' is an [[Arch Linux]] package build description file (actually, it is a shell script) used when [[Creating packages|creating packages]].
+
This article discusses variables definable by the maintainer in a '''PKGBUILD'''. For information on the PKGBUILD functions and creating packages in general, refer to: [[Creating packages]].
  
Packages in Arch Linux are built using the [[makepkg]] utility and information stored in PKGBUILDs. When ''makepkg'' is run, it searches for a {{Ic|PKGBUILD}} in the current directory and follows the instructions therein to either compile or otherwise acquire the files to build a package file ({{ic|''pkgname''.pkg.tar.xz}}). The resulting package contains binary files and installation instructions, readily installed with [[pacman]].
+
A PKGBUILD is a shell script containing the build information required by [[Arch Linux]] packages.
  
This article discusses the variables used in PKGBUILDs. For information on the PKGBUILD functions, refer to [[Creating packages#PKGBUILD functions]].
+
Packages in Arch Linux are built using the [[makepkg]] utility. When ''makepkg'' is run, it searches for a {{Ic|PKGBUILD}} in the current directory and follows the instructions therein to either compile or otherwise acquire the files to build a package file ({{ic|''pkgname''.pkg.tar.xz}}). The resulting package contains binary files and installation instructions, readily installed with [[pacman]].
  
== Package name variables ==
+
Mandatory variables are {{ic|pkgname}}, {{ic|pkgver}}, {{ic|pkgrel}}, {{ic|arch}}, {{ic|source}} and checksums. {{ic|license}} is not strictly necessary to build a package, but is recommended for any PKGBUILDs shared with others, as {{ic|makepkg}} will produce a warning.
  
The following are variables that can be filled out in the PKGBUILD file. {{ic|pkgname}}, {{ic|pkgver}}, {{ic|pkgrel}}, and {{ic|arch}} are all mandatory. {{ic|license}} is not strictly necessary to build a package, but it is recommended for any PKGBUILDs you might want to share with others. {{ic|makepkg}} produces warnings if it isn't present.
+
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]] is present.
  
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.
+
== Package name variables ==
  
 
=== pkgbase ===
 
=== pkgbase ===

Revision as of 17:17, 5 February 2015

zh-CN:PKGBUILD zh-TW:PKGBUILD

This article discusses variables definable by the maintainer in a PKGBUILD. For information on the PKGBUILD functions and creating packages in general, refer to: Creating packages.

A PKGBUILD is a shell script containing the build information required by Arch Linux packages.

Packages in Arch Linux are built using the makepkg utility. 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.

Mandatory variables are pkgname, pkgver, pkgrel, arch, source and checksums. license is not strictly necessary to build a package, but is recommended for any PKGBUILDs shared with others, as makepkg will produce a warning.

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 is present.

Package name variables

pkgbase

An optional global directive is available when building a split package, pkgbase is used to refer to the group of packages in the output of makepkg and in the naming of source-only tarballs. If not specified, the first element in the pkgname array is used. All options and directives for the split packages default to the global values given in the PKGBUILD. Nevertheless, the following ones can be overridden within each split package's packaging function: pkgver, pkgrel, epoch, pkgdesc, arch, url, license, groups, depends, optdepends, provides, conflicts, replaces, backup, options, install and changelog. The variable is not allowed to begin with a hyphen.

pkgname

The name(s) of the package(s). They should consist of alphanumeric and any of the following characters: @, ., _, +, - (at symbol, dot, underscore, plus, hyphen). All letters should be lowercase and names are not allowed to start with hyphens. 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, use pkgname=foobar. The present working directory the PKGBUILD file is in should also match the pkgname.

Split packages should be defined as an array, e.g.: pkgname=('foo' 'bar').

Version variables

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, periods and underscore 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 hyphen on usage e.g.:

source=("$pkgname-${pkgver//_/-}.tar.gz")
Note: If upstream uses a timestamp versioning such as 05102014, ensure to use the reversed date, i.e. 20141005 (ISO 8601 format). Otherwise it will not appear as a newer version.
Tip: makepkg can automatically update this variable by defining a pkgver() function in the PKGBUILD. [1] See VCS_package_guidelines#The pkgver() function for details.

pkgrel

The release number of the package specific to Arch Linux. 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.

epoch

Used to force the package to be seen as newer than any previous versions with a lower epoch, even if the version number would normally not trigger such an upgrade. This value is required to be a positive integer; the default value if left unspecified is 0. It is used when the version numbering scheme of a package changes (or is alphanumeric), breaking normal version comparison logic. See pacman(8) for more information on version comparisons.

E.g.:

pkgver=5.13
pkgrel=2
epoch=1
1:5.13-2
Warning: Epoch should only be used when absolutely required to do so.

Generic variables

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

pkgdesc="A text editor for X11".

Instead of:

pkgdsec="Nedit is a text editor for X11"

However, if the package name differs from the application name, inclusion of the full application name in the description can be the only way to ensure that the package can be found via search.

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 architecture-independent packages.

You can access the target architecture with the variable $CARCH during a build, and even when defining variables.

url

The URL of the official site of the software being packaged.

license

The license under which the software is distributed. The licenses package from the official repositories contains many commonly used licenses, which are installed to /usr/share/licenses/common. If a package is licensed under one of these licenses, the value should be set to the directory name, e.g. license=('GPL'). If the appropriate license is not included in the official licenses package, several things must be done:

  1. The license file(s) should be included in: /usr/share/licenses/pkgname/, e.g. /usr/share/licenses/foobar/LICENSE.
  2. If the source tarball does NOT contain the license details and the license is only displayed elsewhere, e.g. a website, then you need to copy the license to a file and include it.
  3. Add custom to the license array. Optionally, you can replace custom with custom:name of license. Once a license is used in two or more packages in an official repository (including [community]), it becomes a part of the licenses package.
  • The BSD, MIT, zlib/png and Python licenses are special cases and could not be included in the licenses package. For the sake of the license array, it is treated as a common license (license=('BSD'), license=('MIT'), license=('ZLIB') and license=('Python')) but technically each one is a custom license because each one has its own copyright line. Any packages licensed under these four should have its own unique license stored in /usr/share/licenses/pkgname. 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' 'custom:name of license').
  • 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
  • If after researching the issue no license can be determined, PKGBUILD.proto suggests using unknown. However, upstream should be contacted about the conditions under which the software is (and is not) available.
Tip: Some software authors do not provide separate license file and describe distribution rules in section of common ReadMe.txt. This information can be extracted in separate file during build phase with something like this: sed -n '/This software/,/ thereof./p' ReadMe.txt > LICENSE.

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.

Dependency variables

Note: The group base-devel is assumed to be already installed when building with makepkg. Members of this group should not be included in makedepends arrays.
Note: Additional architecture-specific arrays can be used by appending an underscore and the architecture name, e.g. depends_x86_64=(), optdepends_x86_64=().

depends

An array of package names that must be installed before this software can be run. Version restrictions can be specified with comparison operators, e.g. depends=('foobar>=1.8.0'); if multiple restrictions are needed, the dependency can be repeated for each of them [2], e.g. depends=('foobar>=1.8.0' 'foobar<2.0.0').

It is not necessary to specify the version of the packages required. 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.

optdepends

An array of package names that are not needed for the software to function but provides additional features. This may imply that not all executables provided by a package will function without the respective optdepends.[3] A short description of the extra functionality each optdepend provides for the package 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')

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.

Note: Specifying packages that are already in depends is not necessary.
Tip: The following can be used to see if a particular package is either in the base-devel group or pulled in by a members of the group:
$ pacman -Si $(pactree -rl package) 2>/dev/null | grep -q "^Groups *:.*base-devel"

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.

Package relation variables

Note: Additional architecture-specific arrays can be used by appending an underscore and the architecture name, e.g. provides_x86_64=(), conflicts_x86_64=().

provides

An array of additional package names that this package provides the features of (or a virtual package such as cron or sh). Packages that provide the same things can be installed at the same time unless conflict with each other (see below).

Warning: 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 those packages to fail that require a specific version of qt.

conflicts

An array of package names that may cause problems with this package if installed. A package with this name and all packages which provides virtual packages with this name will be removed. You can also specify the version properties of the conflicting packages in the same format as the depends array.

replaces

An array of obsolete package names that are replaced by this package, e.g. replaces=('wireshark') for the wireshark-gtk 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.

Other variables

backup

An array of files that can contain user-made changes and should be preserved during upgrade or removal of a package, primarily intended for configuration files in /etc.

When updating, new version may be saved as file.pacnew to avoid overwriting a file which already exists and was previously modified by the user. Similarly, when the package is removed, user-modified file will be preserved as file.pacsave unless the package was removed with pacman -Rn command.

The file paths in this array should be relative paths (e.g. etc/pacman.conf) not absolute paths (e.g. /etc/pacman.conf). See also Pacnew and Pacsave files.

options

This array allows you to override some of the default behavior of makepkg, defined in /etc/makepkg.conf. 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 full list of the available options can be found in man PKGBUILD.

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 right 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. See this thread.

Tip: A prototype .install is provided at /usr/share/pacman/proto.install. For a web-based prototype, refer to pacman's gitweb page.

changelog

The name of the package changelog. To view changelogs for installed packages (that have this file):

$ pacman -Qc pkgname
Tip: A prototype changelog file is provided at /usr/share/pacman/ChangeLog.proto.

Source variables

source

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=("https://example.com/$pkgname-$pkgver.tar.gz")).

Additional architecture-specific array can be added by appending an underscore and the architecture name, e.g. source_x86_64=(). There must be a corresponding integrity array with checksums, e.g. md5sums_x86_64=().

Note: If you need to supply files which are not downloadable on the fly, e.g. self-made patches, you simply put those into the same directory where your PKGBUILD file is in and add the file name to this array. Any paths you add here are resolved relative to the directory where the PKGBUILD lies. Before the actual build process is started, all of the files referenced in this array will be downloaded or checked for existence, and makepkg will not proceed if any are missing.
Tip: You can specify a different name for the downloaded file — if the downloaded file has a different name for some reason, like the URL had a GET parameter — using the following syntax: filename::fileuri

For example:

source=("project_name::hg+https://googlefontdirectory.googlecode.com/hg/")

noextract

An array of files listed under the source array, which should not be extracted from their archive format by makepkg. This applies to archives which cannot be handled by /usr/bin/bsdtar, double-archives, or those that need to be installed as-is. If an alternative unarchiving tool is used (e.g. lrzip), it should be added in the makedepends=() array and the first line of the prepare() function should extract the source archive manually; for example:

prepare() {
  lrzip -d source.tar.lrz
}

Note that while the source array accepts URLs, noextract is just the file name portion:

source=("http://foo.org/bar/foobar.tar.xz")
noextract=('foobar.tar.xz')

To extract nothing, you can do something like this (taken from firefox-i18n's PKGBUILD):

noextract=("${source[@]%%::*}")

Integrity variables

sha256sums

An array of SHA-2 checksums with digest size of 256. These are alternatives to md5sums and sha1sums and have fewer known weaknesses. Once all files in the source array are available, a SHA-2 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 because makepkg cannot guess which checksum belongs to what source file. You can generate this array quickly and easily using the command updpkgsums in the directory that contains the PKGBUILD file.

To enable use and generation of these checksums, set up the INTEGRITY_CHECK option in /etc/makepkg.conf. See man makepkg.conf:

source=('http://foo.com/bar/foo.bar.tar.gz')
sha256sums=('4e8548bae163129d2fc8f8e1f3b6071fe9d62821e3d5617507ccd2f589526166'

md5sums

An array of MD5 checksums of the files listed in the source array.

Warning: The MD5 algorithm is known to have collision vulnerabilities; you should consider using a stronger alternative from the SHA-2 family of hash algorithms, such as SHA-256.

validpgpkeys

An array of PGP fingerprints. If this array is non-empty, makepkg will only accept signatures from the keys listed here and will ignore the trust values from the keyring. If the source file was signed with a subkey, makepkg will still use the primary key for comparison.

Only full fingerprints are accepted. They must be uppercase and must not contain whitespace characters.

See also