mirror of
https://github.com/moparisthebest/pacman
synced 2024-11-05 17:15:02 -05:00
466 lines
18 KiB
Plaintext
466 lines
18 KiB
Plaintext
/////
|
|
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.
|
|
|
|
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.
|
|
|
|
*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.
|
|
|
|
*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 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. Typically the project's website.
|
|
|
|
*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.
|
|
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 make the PKGBUILD as useful as possible, use the `$pkgname` and `$pkgver`
|
|
variables if possible when specifying the download location. Compressed files
|
|
will be extracted automatically unless found in
|
|
the noextract array described below.
|
|
+
|
|
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')`.
|
|
+
|
|
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.
|
|
|
|
*noextract (array)*::
|
|
An array of filenames 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, be sure to set up the `INTEGRITY_CHECK` option in
|
|
linkman:makepkg.conf[5].
|
|
|
|
*groups (array)*::
|
|
An array of symbolic names that represent groups of packages, allowing
|
|
you to install multiple packages by requesting a single target. For
|
|
example, one could install all KDE packages by installing the 'kde' group.
|
|
|
|
*arch (array)*::
|
|
Defines on which architectures the given package is available (e.g.,
|
|
`arch=('i686' 'x86_64')`). Packages that contain no architecture specific
|
|
files should use `arch=('any')`.
|
|
|
|
*backup (array)*::
|
|
An array of filenames, without preceding slashes, that
|
|
should be backed up if the package is removed or upgraded. This is
|
|
commonly used for packages placing configuration files in /etc. See
|
|
Handling Config Files in linkman:pacman[8] for more information.
|
|
|
|
*depends (array)*::
|
|
An array of packages this package depends on to run. Entries in
|
|
this list should be surrounded with single quotes and contain at least
|
|
the package name. Entries can also include a version requirement of the
|
|
form 'name<>version', where `<>` is one of five comparisons: `>=` (greater
|
|
than or equal to), `<=` (less than or equal to), `=` (equal to), `>`
|
|
(greater than), or `<` (less than).
|
|
+
|
|
If the dependency name appears to be a library (ends with .so), makepkg will
|
|
try to find a binary that depends on the library in the built package and
|
|
append the version needed by the binary. Appending the version yourself
|
|
disables auto detection.
|
|
|
|
*makedepends (array)*::
|
|
An array of packages this package depends on to build but are not
|
|
needed at runtime. Packages in this list follow the same format as
|
|
depends.
|
|
|
|
*checkdepends (array)*::
|
|
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.
|
|
|
|
*optdepends (array)*::
|
|
An array of packages (and accompanying reasons) that are not essential for
|
|
base functionality, but may be necessary to make full use of the contents
|
|
of this package. optdepends are currently for informational purposes only
|
|
and are not utilized by pacman during dependency resolution. The format
|
|
for specifying optdepends is:
|
|
|
|
optdepends=('fakeroot: for makepkg usage as normal user')
|
|
|
|
*conflicts (array)*::
|
|
An array of packages that will conflict with this package (i.e. they
|
|
cannot both be installed at the same time). This directive follows the
|
|
same format as depends. Versioned conflicts are supported using the
|
|
operators as described in `depends`.
|
|
|
|
*provides (array)*::
|
|
An array of ``virtual provisions'' this package provides. This allows
|
|
a package to provide dependencies other than its own package name. For
|
|
example, the dcron package can provide 'cron', which allows packages to
|
|
depend on 'cron' rather than 'dcron OR fcron'.
|
|
+
|
|
Versioned provisions are also possible, in the 'name=version' format. For
|
|
example, dcron can provide 'cron=2.0' to satisfy the 'cron>=2.0' dependency of
|
|
other packages. Provisions involving the `>` and `<` operators are invalid as
|
|
only specific versions of a package may be provided.
|
|
+
|
|
If the provision name appears to be a library (ends with .so), makepkg will
|
|
try to find the library in the built package and append the correct
|
|
version. Appending the version yourself disables auto detection.
|
|
|
|
*replaces (array)*::
|
|
An array of packages this package should replace. This can be used
|
|
to handle renamed/combined packages. For example, if the 'j2re' package
|
|
is renamed to 'jre', this directive allows future upgrades to continue
|
|
as expected even though the package has moved. Versioned replaces are
|
|
supported using the operators as described in `depends`.
|
|
+
|
|
Sysupgrade is currently the only pacman operation that utilizes this field.
|
|
A normal sync or upgrade will not use its value.
|
|
|
|
*options (array)*::
|
|
This array allows you to override some of makepkg's default behavior
|
|
when building packages. To set an option, just include the option name
|
|
in the options array. To reverse the default behavior, place an ``!'' at
|
|
the front of the option. Only specify the options you specifically want
|
|
to override, the rest will be taken from linkman:makepkg.conf[5].
|
|
*NOTE:* 'force' is a now-removed option in favor of the top level 'epoch'
|
|
variable.
|
|
|
|
*strip*;;
|
|
Strip 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. If you wish to delete doc directories,
|
|
specify `!docs` in the array.
|
|
|
|
*libtool*;;
|
|
Leave libtool (.la) files in packages. Specify `!libtool` to
|
|
remove them.
|
|
|
|
*emptydirs*;;
|
|
Leave empty directories in packages.
|
|
|
|
*zipman*;;
|
|
Compress man and info pages with gzip.
|
|
|
|
*upx*;;
|
|
Compress binary executable files using UPX.
|
|
|
|
*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 as specified in linkman:makepkg.conf[5]. 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 as specified
|
|
in linkman:makepkg.conf[5]. More useful in its negative form
|
|
`!makeflags` with select packages that have problems building with
|
|
custom makeflags such as `-j2` (or higher).
|
|
|
|
|
|
build() Function
|
|
----------------
|
|
In addition to the above directives, the optional build() function usually
|
|
comprises the remainder of the PKGBUILD. This is directly sourced and executed
|
|
by makepkg, so anything that bash or the system has available is available for
|
|
use here. The function is run in `bash -e` mode, meaning any command that exits
|
|
with a non-zero status will cause the function to exit. Be sure any exotic
|
|
commands used are covered by `makedepends`.
|
|
|
|
All of the above variables such as `$pkgname` and `$pkgver` are available for use
|
|
in the build function. In addition, makepkg defines the following three
|
|
variables for use during the build and install process:
|
|
|
|
*startdir*::
|
|
This contains the absolute path to the directory where the PKGBUILD is
|
|
located, which is usually the output of `$(pwd)` when makepkg is started.
|
|
Use of this variable is deprecated and strongly discouraged.
|
|
|
|
*srcdir*::
|
|
This contains the directory where makepkg extracts, or copies, all source
|
|
files.
|
|
|
|
*pkgdir*::
|
|
This contains the directory where makepkg bundles the installed package
|
|
(this directory will become the root directory of your built package).
|
|
|
|
If you create any variables of your own in the build function, it is
|
|
recommended to use the bash `local` keyword to scope the variable to inside
|
|
the build function.
|
|
|
|
check() Function
|
|
----------------
|
|
An optional check() function can be specified in which a packages test-suite
|
|
may be run. This function is run between the build() and package() functions.
|
|
The function is run in `bash -e` mode, meaning any command that exits with a
|
|
non-zero status will cause the function to exit. Be sure any exotic commands
|
|
used are covered by `checkdepends`.
|
|
|
|
package() Function
|
|
------------------
|
|
An optional package() function can be specified in addition to the build()
|
|
function. This function is run after the build() and check() functions. The
|
|
function is run in `bash -e` mode, meaning any command that exits with a
|
|
non-zero status will cause the function to exit. When specified in combination
|
|
with the fakeroot BUILDENV option in linkman:makepkg.conf[5], fakeroot usage
|
|
will be limited to running the packaging stage. An existing build() function
|
|
will be run as the user calling makepkg.
|
|
|
|
Package Splitting
|
|
-----------------
|
|
makepkg supports building multiple packages from a single PKGBUILD. This is
|
|
achieved by assigning an array of package names to the `pkgname` directive.
|
|
Each split package uses a corresponding packaging function with name
|
|
`package_foo()`, where `foo` is the name of the split package.
|
|
|
|
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`, `license`, `groups`, `depends`,
|
|
`optdepends`, `provides`, `conflicts`, `replaces`, `backup`, `options`,
|
|
`install` and `changelog`.
|
|
|
|
An optional global directive is available when building a split package:
|
|
|
|
*pkgbase*::
|
|
The name 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. The variable is not allowed to
|
|
begin with a hyphen.
|
|
|
|
Install/Upgrade/Remove Scripting
|
|
--------------------------------
|
|
Pacman has the ability to store and execute a package-specific script when it
|
|
installs, removes, or upgrades a package. This allows a package to configure
|
|
itself after installation and perform an opposite action upon removal.
|
|
|
|
The exact time the script is run varies with each operation, and should be
|
|
self-explanatory. Note that during an upgrade operation, none of the install
|
|
or remove scripts will be called.
|
|
|
|
Scripts are passed either one or two ``full version strings'', where a full
|
|
version string is either 'pkgver-pkgrel' or 'epoch:pkgver-pkgrel' if epoch is
|
|
non-zero.
|
|
|
|
*pre_install*::
|
|
Run right before files are extracted. One argument is passed:
|
|
new package full version string.
|
|
|
|
*post_install*::
|
|
Run right after files are extracted. One argument is passed:
|
|
new package full version string.
|
|
|
|
*pre_upgrade*::
|
|
Run right before files are extracted. Two arguments are passed in this
|
|
order: new package full version string, old package full version string.
|
|
|
|
*post_upgrade*::
|
|
Run after files are extracted. Two arguments are passed in this order:
|
|
new package full version string, old package full version string.
|
|
|
|
*pre_remove*::
|
|
Run right before files are removed. One argument is passed:
|
|
old package full version string.
|
|
|
|
*post_remove*::
|
|
Run right after files are removed. One argument is passed:
|
|
old package full version string.
|
|
|
|
To use this feature, create a file such as 'pkgname.install' and put it in the
|
|
same directory as the PKGBUILD script. Then use the install directive:
|
|
|
|
install=pkgname.install
|
|
|
|
The install script does not need to be specified in the source array. A
|
|
template install file is available in '{pkgdatadir}' as 'proto.install' for
|
|
reference with all of the available functions defined.
|
|
|
|
|
|
Development Directives
|
|
----------------------
|
|
makepkg supports building development versions of packages without having to
|
|
manually update the pkgver in the PKGBUILD. This was formerly done using the
|
|
separate utility 'versionpkg'. In order to utilize this functionality, your
|
|
PKGBUILD must use correct variable names depending on the SCM being fetched
|
|
from (e.g., 'makepkg-git', 'mplayer-svn').
|
|
|
|
*CVS*::
|
|
The generated pkgver will be the date the package is built.
|
|
|
|
*_cvsroot*;;
|
|
The root of the CVS repository.
|
|
|
|
*_cvsmod*;;
|
|
The CVS module to fetch.
|
|
|
|
*SVN*::
|
|
The generated pkgver will be the latest SVN revision number.
|
|
|
|
*_svntrunk*;;
|
|
The trunk of the SVN repository.
|
|
|
|
*_svnmod*;;
|
|
The SVN module to fetch.
|
|
|
|
*Git*::
|
|
The generated pkgver will be the date the package is built.
|
|
|
|
*_gitroot*;;
|
|
The URL (all protocols supported) to the GIT repository.
|
|
|
|
*_gitname*;;
|
|
GIT tag or branch to use.
|
|
|
|
*Mercurial*::
|
|
The generated pkgver will be the hg tip revision number.
|
|
|
|
*_hgroot*;;
|
|
The URL of the mercurial repository.
|
|
|
|
*_hgrepo*;;
|
|
The repository to follow.
|
|
|
|
*Darcs*::
|
|
The generated pkgver will be the date the package is built.
|
|
|
|
*_darcstrunk*;;
|
|
URL to the repository trunk.
|
|
|
|
*_darcsmod*;;
|
|
Darcs module to use.
|
|
|
|
*Bazaar*::
|
|
The generated pkgver will be the latest Bazaar revision number (revno).
|
|
|
|
*_bzrtrunk*;;
|
|
URL to the bazaar repository.
|
|
|
|
*_bzrmod*;;
|
|
Bazaar module to use.
|
|
|
|
|
|
Example
|
|
-------
|
|
The following is an example PKGBUILD for the 'patch' package. For more
|
|
examples, look through the build files of your distribution's packages. For
|
|
those using Arch Linux, consult the ABS tree.
|
|
|
|
[source,sh]
|
|
-------------------------------
|
|
include::PKGBUILD-example.txt[]
|
|
-------------------------------
|
|
|
|
See Also
|
|
--------
|
|
linkman:makepkg[8], linkman:pacman[8], linkman:makepkg.conf[5]
|
|
|
|
include::footer.txt[]
|