diff options
Diffstat (limited to 'doc/PKGBUILD.5.asciidoc')
| -rw-r--r-- | doc/PKGBUILD.5.asciidoc | 525 |
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[] |