path: root/doc/PKGBUILD.5.txt

/////
vim:set ts=4 sw=4 syntax=asciidoc noet spell spelllang=en_us:
/////
PKGBUILD(5)
===========

Name
----
PKGBUILD - Arch Linux package build description file


Synopsis
--------
PKGBUILD


Description
-----------
This manual page describes general rules about PKGBUILDs. Once a
PKGBUILD is written, the actual package is built using makepkg and installed
with pacman.

NOTE: An example PKGBUILD, useful for reference, is located in '{pkgdatadir}'
along with other example files such as a ChangeLog and an install
script. You can copy the provided PKGBUILD.proto file to a new package build
directory and make customizations to suit your needs.


Options and Directives
----------------------
The following is a list of standard options and directives available for use
in a PKGBUILD. These are all understood and interpreted by makepkg, and most
of them will be directly transferred to the built package. The mandatory
fields for a minimally functional PKGBUILD are *pkgname*, *pkgver*, *pkgrel*
and *arch*.

If you need to create any custom variables for use in your build process, it is
recommended to prefix their name with an '_' (underscore).
This will prevent any possible name clashes with internal makepkg variables.
For example, to store the base kernel version in a variable, use something
similar to `$_basekernver`.

*pkgname (array)*::
    Either the name of the package or an array of names for split packages.
    Valid characters for members of this array are alphanumerics, and any of
    the following characters: ```@ . _ + -`''. Additionally, names are not
    allowed to start with hyphens or dots.

*pkgver*::
    The version of the software as released from the author (e.g., '2.7.1').
    The variable is not allowed to contain colons or hyphens.
+
The `pkgver` variable can be automatically updated by providing a `pkgver()`
function in the PKGBUILD that outputs the new package version.
This is run after downloading and extracting the sources so it can use those
files in determining the new `pkgver`.
This is most useful when used with sources from version control systems (see
below).

*pkgrel*::
    This is the release number specific to the Arch Linux release. This
    allows package maintainers to make updates to the package's configure
    flags, for example. This is typically set to '1' for each new upstream
    software release and incremented for intermediate PKGBUILD updates. The
    variable is not allowed to contain hyphens.

*pkgdesc*::
    This should be a brief description of the package and its functionality.
    Try to keep the description to one line of text and to not use the package's
    name.

*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'. This is useful when the version
    numbering scheme of a package changes (or is alphanumeric), breaking normal
    version comparison logic. See linkman:pacman[8] for more information on
    version comparisons.

*url*::
    This field contains a URL that is associated with the software being
    packaged. This is typically the project's web site.

*license (array)*::
    This field specifies the license(s) that apply to the package.
    Commonly used licenses can be found in '/usr/share/licenses/common'. If you
    see the package's license there, simply reference it in the license
    field (e.g., `license=('GPL')`). If the package provides a license not
    available in '/usr/share/licenses/common', then you should include it
    in the package itself and set `license=('custom')` or
    `license=('custom:LicenseName')`. The license should be placed in
    '$pkgdir/usr/share/licenses/$pkgname/' when building the package. If
    multiple licenses are applicable, list all of them:
    `license=('GPL' 'FDL')`.

*install*::
    Specifies a special install script that is to be included in the package.
    This file should reside in the same directory as the PKGBUILD and will
    be copied into the package by makepkg. It does not need to be included
    in the source array (e.g., `install=$pkgname.install`).

*changelog*::
    Specifies a changelog file that is to be included in the package.
    The changelog file should end in a single newline.
    This file should reside in the same directory as the PKGBUILD and will
    be copied into the package by makepkg. It does not need to be included
    in the source array (e.g., `changelog=$pkgname.changelog`).

*source (array)*::
    An array of source files required to build the package. Source files
    must either reside in the same directory as the PKGBUILD, or be a
    fully-qualified URL that makepkg can use to download the file.
    To simplify the maintenance of PKGBUILDs, use the `$pkgname` and `$pkgver`
    variables when specifying the download location, if possible.
    Compressed files will be extracted automatically unless found in the
    noextract array described below.
+
Additional architecture-specific sources 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=()'.
+
It is also possible to change the name of the downloaded file, which is helpful
with weird URLs and for handling multiple source files with the same
name. The syntax is: `source=('filename::url')`.
+
makepkg also supports building developmental versions of packages using sources
downloaded from version control systems (VCS). For more information, see
<<VCS,Using VCS Sources>> below.
+
Files in the source array with extensions `.sig`, `.sign` or, `.asc` are
recognized by makepkg as PGP signatures and will be automatically used to verify
the integrity of the corresponding source file.

*validpgpkeys (array)*::
    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.

*noextract (array)*::
    An array of file names corresponding to those from the source array. Files
    listed here will not be extracted with the rest of the source files. This
    is useful for packages that use compressed data directly.

*md5sums (array)*::
    This array contains an MD5 hash for every source file specified in the
    source array (in the same order). makepkg will use this to verify source
    file integrity during subsequent builds. If 'SKIP' is put in the array
    in place of a normal hash, the integrity check for that source file will
    be skipped. To easily generate md5sums, run ``makepkg -g >> PKGBUILD''.
    If desired, move the md5sums line to an appropriate location.

*sha1sums, sha256sums, sha384sums, sha512sums (arrays)*::
    Alternative integrity checks that makepkg supports; these all behave
    similar to the md5sums option described above. To enable use and generation
    of these checksums, b