diff options
Diffstat (limited to 'doc/PKGBUILD.5.txt')
| -rw-r--r-- | doc/PKGBUILD.5.txt | 239 |
1 files changed, 239 insertions, 0 deletions
diff --git a/doc/PKGBUILD.5.txt b/doc/PKGBUILD.5.txt new file mode 100644 index 00000000..be3f1169 --- /dev/null +++ b/doc/PKGBUILD.5.txt @@ -0,0 +1,239 @@ +///// +vim:set ts=4 sw=4 syntax=asciidoc noet: +///// +PKGBUILD(5) +=========== + +Name +---- +PKGBUILD - Arch Linux package build description file + + +Synopsis +-------- +PKGBUILD + + +Description +----------- +This manual page is meant to describe general rules about PKGBUILDs. Once a +PKGBUILD is written, the actual package is built using makepkg and installed +with pacman. + +NOTE: If you have a local copy of the Arch Build System (ABS) tree on your +computer, you can copy the PKGBUILD.proto file to your new package build +directory and edit it from there. To acquire/sync the ABS tree, use the abs +script included with pacman. + + +Options and Directives +---------------------- +*pkgname*:: + The name of the package. This has be a unix-friendly name as it will be + used in the package filename. + +*pkgver*:: + The version of the software as released from the author (e.g. \'2.7.1'). + +*pkgrel*:: + This is the release number specific to the Arch Linuxs release. This + allows package maintainers to make updates to the package's configure + flags, for example. + +*pkgdesc*:: + This should be a brief description of the package and its functionality. + Try to keep the description to one line of text. + +*url*:: + This field contains a URL that is associated with the software being + packaged. This is typically the project's website. + +*license (array)*:: + This field specifies the license(s) that apply to the package. + Commonly-used licenses are 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 + found in '/usr/share/licenses/common', then you should include the license + 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 for a package, 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$$`). + +*source (array)*:: + An array of source files required to build the package. Source files + must either reside in the same directory as the PKGBUILD file, or be a + fully-qualified URL that makepkg will use to download the file. In order + to make the PKGBUILD as useful as possible, use the $pkgname and $pkgver + variables if possible when specifying the download location. + +*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 which use compressed data which is downloaded but + not necessary to uncompress. + +*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. To easily generate md5sums, run + ``makepkg -g >> PKGBUILD''. If desired, move the md5sums line to an + appropriate location. *NOTE:* makepkg supports multiple integrity + algorithms and their corresponding arrays (i.e. sha1sums for the SHA1 + algorithm); however, official packages use only md5sums for the time + being. + +*sha1sums, etc.*:: + Alternative integrity checks that makepkg supports, as noted in md5sums + above. + +*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')$$`). + +*backup (array)*:: + A space-delimited 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 manlink:pacman[8] for more information. + +*depends (array)*:: + An array of packages that this package depends on to run. Packages 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 three comparisons: >= (greater + than or equal to), <= (less than or equal to), or = (equal to). + +*makedepends (array)*:: + An array of packages that this package depends on to build, but are not + needed at runtime. Packages in this list follow the same format as + depends. + +*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, except you cannot specify versions. + +*provides (array)*:: + An array of ``virtual provisions'' that 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'. + +*replaces (array)*:: + An array of packages that this package should replace, and 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. Sysupgrade is currently + the only pacman operation that utilizes this field, a normal sync 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 manlink:makepkg.conf[5]. + *NOTE:* 'force' is a special option only used in a manlink:PKGBUILD[5], + do not use it unless you know what you are doing. + + *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 and info directories. If you wish to delete doc and + info directories, specify `!docs` in the array. + + *libtool*;; + Leave libtool (.la) files in packages. Specify `!libtool` to + remove them. + + *emptydirs*;; + Leave empty directories in packages. + + *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. + + *makeflags*;; + Allow the use of user-specific makeflags during build as specified + in manlink: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). + + *force*;; + Force the package to be upgraded by a pacman system upgrade + operation, even if the version number would normally not trigger + such an upgrade. This is useful when the version numbering scheme + of a package changes (or is alphanumeric). + + +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 do the opposite right before it is removed. + +The exact time the script is run varies with each operation: + +*pre_install*:: + script is run right before files are extracted. + +*post_install*:: + script is run right after files are extracted. + +*pre_upgrade*:: + script is run right before files are extracted. + +*post_upgrade*:: + script is run after files are extracted. + +*pre_remove*:: + script is run right before files are removed. + +*post_remove*:: + script is run right after files are removed. + +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 the ABS tree (/var/abs/install.proto). + + +Example +------- +The following is an example PKGBUILD for the 'module-init-tools' package. For more +examples, look through the ABS tree. + +----- +include::PKGBUILD-example.txt[] +----- + + +See Also +-------- +manlink:makepkg[8], manlink:pacman[8], manlink:makepkg.conf[5] + +include::footer.txt[] |