summaryrefslogtreecommitdiffstats
path: root/doc/PKGBUILD.5.asciidoc
diff options
context:
space:
mode:
authorEli Schwartz <eschwartz@archlinux.org>2018-05-03 06:10:21 +0200
committerAllan McRae <allan@archlinux.org>2018-05-14 01:59:17 +0200
commit076b6184de2b20e9b26225d93f6f3a7030504109 (patch)
treeca0e375b9fd89d6b6ce40026b732985c4b335841 /doc/PKGBUILD.5.asciidoc
parent860e4c4943ad062bd0eff99f28e7d64804b3c08e (diff)
downloadpacman-076b6184de2b20e9b26225d93f6f3a7030504109.tar.gz
pacman-076b6184de2b20e9b26225d93f6f3a7030504109.tar.xz
Ensure better text editor automatic filetype detection
Since we no longer use vim-specific modelines, use the .asciidoc file extension which is, well, reserved for asciidoc formatted files. This should presumably work everywhere without needing editor-specific workarounds and configuration. Also add a shebang to makepkg.conf to indicate it contains bash content. Signed-off-by: Eli Schwartz <eschwartz@archlinux.org> Signed-off-by: Allan McRae <allan@archlinux.org>
Diffstat (limited to 'doc/PKGBUILD.5.asciidoc')
-rw-r--r--doc/PKGBUILD.5.asciidoc525
1 files changed, 525 insertions, 0 deletions
diff --git a/doc/PKGBUILD.5.asciidoc b/doc/PKGBUILD.5.asciidoc
new file mode 100644
index 00000000..9634bd15
--- /dev/null
+++ b/doc/PKGBUILD.5.asciidoc
@@ -0,0 +1,525 @@
+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, forward slashes, hyphens
+ or whitespace.
++
+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 and running the
+`prepare()` function (if present), 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.
+
+*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.
+
+*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.
+
+*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, 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')`. Valid characters for members of this array
+ are alphanumerics and ```_`''.
+
+*backup (array)*::
+ An array of file names, 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 automatic detection.
++
+Additional architecture-specific depends can be added by appending an
+underscore and the architecture name e.g., 'depends_x86_64=()'.
+
+*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.
++
+Additional architecture-specific makedepends can be added by appending an
+underscore and the architecture name e.g., 'makedepends_x86_64=()'.
+
+*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.
++
+Additional architecture-specific checkdepends can be added by appending an
+underscore and the architecture name e.g., 'checkdepends_x86_64=()'.
+
+*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=('python: for library bindings')
++
+Additional architecture-specific optdepends can be added by appending an
+underscore and the architecture name e.g., 'optdepends_x86_64=()'.
+
+*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`.
++
+Additional architecture-specific conflicts can be added by appending an
+underscore and the architecture name e.g., 'conflicts_x86_64=()'.
+
+*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 automatic detection.
++
+Additional architecture-specific provides can be added by appending an
+underscore and the architecture name e.g., 'provides_x86_64=()'.
+
+*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.
++
+Additional architecture-specific replaces can be added by appending an
+underscore and the architecture name e.g., 'replaces_x86_64=()'.
+
+*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.
+
+ *staticlibs*;;
+ Leave static library (.a) files in packages. Specify `!staticlibs` to
+ remove them (if they have a shared counterpart).
+
+ *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 (CPPFLAGS, 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).
+
+ *debug*;;
+ Add the user-specified debug flags (DEBUG_CFLAGS, DEBUG_CXXFLAGS) to
+ their counterpart buildflags as specified in linkman:makepkg.conf[5].
+ When used in combination with the `strip' option, a separate package
+ containing the debug symbols is created.
+
+
+Packaging Functions
+-------------------
+In addition to the above directives, PKGBUILDs require a set of functions that
+provide instructions to build and install the package. As a minimum, the
+PKGBUILD must contain a `package()` function which installs all the package's
+files into the packaging directory, with optional `prepare()`, `build()`, and
+`check()` functions being used to create those files from source.
+
+*package() Function*::
+ The `package()` function is used to install files into the directory that
+ will become the root directory of the built package and is run after all
+ the optional functions listed below. The packaging stage is run using
+ fakeroot to ensure correct file permissions in the resulting package.
+ All other functions will be run as the user calling makepkg.
+
+*prepare() Function*::
+ An optional `prepare()` function can be specified in which operations to
+ prepare the sources for building, such as patching, are performed. This
+ function is run after the source extraction and before the `build()`
+ function. The `prepare()` function is skipped when source extraction
+ is skipped.
+
+*build() Function*::
+ The optional `build()` function is use to compile and/or adjust the source
+ files in preparation to be installed by the `package()` function. This is
+ directly sourced and executed by makepkg, so anything that Bash or the
+ system has available is available for use here. Be sure any exotic
+ commands used are covered by the `makedepends` array.
++
+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 package's
+ test-suite may be run. This function is run between the `build()` and
+ `package()` functions. Be sure any exotic commands used are covered by the
+ `checkdepends` array.
+
+All of the above variables such as `$pkgname` and `$pkgver` are available for
+use in the packaging functions. In addition, makepkg defines the following
+variables:
+
+*srcdir*::
+ This contains the directory where makepkg extracts, or copies, all source
+ files.
++
+All of the packaging functions defined above are run starting inside `$srcdir`
+
+*pkgdir*::
+ This contains the directory where makepkg bundles the installed package.
+ This directory will become the root directory of your built package. This
+ variable should only be used in the `package()` function.
+
+*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.
+
+
+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:
+`pkgdesc`, `arch`, `url`, `license`, `groups`, `depends`, `optdepends`,
+`provides`, `conflicts`, `replaces`, `backup`, `options`, `install`, and
+`changelog`.
+
+Note that makepkg does not consider split package `depends` when checking
+if dependencies are installed before package building and with `--syncdeps`.
+All packages required to make the package are required to be specified in
+the global `depends` and `makedepends` arrays.
+
+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. Valid characters for this
+ variable are alphanumerics, and any of the following characters:
+ ```@ . _ + -`''. Additionally, the variable is not allowed to start with
+ hyphens or dots.
+
+
+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 functions 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.
+
+
+Using VCS Sources[[VCS]]
+------------------------
+Building a developmental version of a package using sources from a version
+control system (VCS) is enabled by specifying the source in the form
+`source=('directory::url#fragment?query')`. Currently makepkg supports the
+Bazaar, Git, Subversion, and Mercurial version control systems. For other
+version control systems, manual cloning of upstream repositories must be done
+in the `prepare()` function.
+
+The source URL is divided into four components:
+
+*directory*::
+ (optional) Specifies an alternate directory name for makepkg to download
+ the VCS source into.
+
+*url*::
+ The URL to the VCS repository. This must include the VCS in the URL protocol
+ for makepkg to recognize this as a VCS source. If the protocol does not
+ include the VCS name, it can be added by prefixing the URL with `vcs+`. For
+ example, using a Git repository over HTTPS would have a source URL in the
+ form:
+ `git+https://...`.
+
+*fragment*::
+ (optional) Allows specifying a revision number or branch for makepkg to checkout
+ from the VCS. For example, to checkout a given revision, the source line would
+ have the format `source=(url#revision=123)`. The available fragments depends on
+ the VCS being used:
+
+ *bzr*;;
+ revision (see `'bzr help revisionspec'` for details)
+
+ *git*;;
+ branch, commit, tag
+
+ *hg*;;
+ branch, revision, tag
+
+ *svn*;;
+ revision
+
+*query*::
+ (optional) Allows specifying whether a VCS checkout should be checked for
+ PGP-signed revisions. The source line should have the format
+ `source=(url#fragment?signed)` or `source=(url?signed#fragment)`. Currently
+ only supported by Git.
+
+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 Arch Build System (ABS) tree.
+
+[source,sh]
+-------------------------------
+include::PKGBUILD-example.txt[]
+-------------------------------
+
+
+See Also
+--------
+linkman:makepkg[8], linkman:pacman[8], linkman:makepkg.conf[5]
+
+include::footer.asciidoc[]