diff options
Diffstat (limited to 'doc/PKGBUILD.5')
| -rw-r--r-- | doc/PKGBUILD.5 | 286 |
1 files changed, 286 insertions, 0 deletions
diff --git a/doc/PKGBUILD.5 b/doc/PKGBUILD.5 new file mode 100644 index 00000000..e7cc55d9 --- /dev/null +++ b/doc/PKGBUILD.5 @@ -0,0 +1,286 @@ +." the string declarations are a start to try and make distro independent +.ds DS Arch Linux +.ds PB PKGBUILD +.ds VR 3.0.0 +.TH PKGBUILD 5 "Feb 06, 2007" "PKGBUILD version \*(VR" "\*(DS Files" +.SH NAME +PKGBUILD \- \*(DS package build description file +.SH DESCRIPTION +This manual page is meant to describe general rules about PKGBUILDs. Once +a PKGBUILD is written, the actual package is built using \fBmakepkg\fR and +installed with \fBpacman\fR. + +\fBNOTE:\fR 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 \fBabs\fR script included with pacman/makepkg. + +.SS Quick PKGBUILD Explanation +For an example of a PKGBUILD, see the \fBEXAMPLE\fR section. + +\fIpkgname\fR defines the package name. It should not contain any uppercase +letters. \fIpkgversion\fR defines the actual package version as given by the +developers of the package. No dashes are allowed. \fIpkgrel\fR allows for +\*(DS-specific changes to the package or corrections to a PKGBUILD +without an upstream version change. The value should be an integer. +\fIpkgdesc\fR is a short one-line description for the package, usually taken +from the project's homepage or manpage. It is preferable to keep the length to +one line for displaying during searches. These four variables are required in +every PKGBUILD. \fIurl\fR is also highly recommended so users can find more +information on the package if needed. + +\fIdepends\fR and \fImakedepends\fR are bash arrays which define the +dependencies of the package. Packages listed in \fImakedepends\fR are required +only for building the package, and not for runtime. \fIdepends\fR is used to +list runtime depends. To build the package using \fBmakepkg\fR, ALL dependencies +must be satisfied. For \fBpacman\fR to install the package, all runtime depends +must be satisfied. + +The \fIbackup\fR array specifies files that should be treated specially +when removing or upgrading packages. See \fBHANDLING CONFIG FILES\fR in +the \fIpacman\fR manpage for more information on this. + +The \fIsource()\fR array tells makepkg which files to download or extract before +compiling begins. The \fImd5sums()\fR array provides md5sums for each of these +files. These are used to validate the integrity of the source files. + +The \fIbuild\fR function is what actually does the work of putting the package +together. Sometimes this is as simple as a configure, make, make install (to +$startdir/pkg). However, some customizations are often needed during the build +process. + +Once your PKGBUILD is created, you can run \fBmakepkg\fR from the build +directory. \fBmakepkg\fR will check dependencies and look for the source files +required to build. If some are missing it will attempt to download them, +provided there is a fully-qualified URL in the \fIsource()\fR array. + +.SS 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: + +.TP +.B pre_install +script is run right before files are extracted. + +.TP +.B post_install +script is run right after files are extracted. + +.TP +.B pre_upgrade +script is run right before files are extracted. + +.TP +.B post_upgrade +script is run after files are extracted. + +.TP +.B pre_remove +script is run right before files are removed. + +.TP +.B post_remove +script is run right after files are removed. + +.P +To use this feature, just create a file (eg, pkgname.install) and put it in +the same directory as the PKGBUILD script. Then use the \fIinstall\fR +directive: + +install=pkgname.install + +The install script does not need to be specified in the \fIsource\fR array. +A template install file is available in your ABS tree (/var/abs/install.proto). + +.SH OPTIONS AND DIRECTIVES +.TP +.B pkgname +The name of the package. This has be a unix-friendly name as it will be +used in the package filename. + +.TP +.B pkgver +This is the version of the software as released from the author (eg, 2.7.1). + +.TP +.B pkgrel +This is the release number specific to \*(DS's release. This allows package +maintainers to make updates to the package's configure flags, for example. + +.TP +.B pkgdesc +This should be a brief description of the package and its functionality. + +." Is this applicable below? +.TP +.B pkgdesc_localized \fI(array)\fR +Array of the localized package descriptions. The format is the following: +pkgdesc_localized=('xx_YY foo' 'xx_YY bar') + +.TP +.B url +This field contains an optional URL that is associated with the piece of +software being packaged. This is typically the project's website. + +.TP +.B license \fI(array)\fR +This field specifies the license(s) that apply to the package. Commonly-used +licenses are typically found in \fI/usr/share/licenses/common\fR. If you +see the package's license there, simply reference it in the license field +(eg, \fBlicense="GPL"\fR). If the package provides a license not found in +\fI/usr/share/licenses/common\fR, then you should include the license in +the package itself and set \fBlicense="custom"\fR or +\fBlicense="custom:LicenseName"\fR. The license itself should be placed in a +directory called \fI$startdir/pkg/usr/share/licenses/$pkgname\fR. If multiple +licenses are applied, use the array form: \fBlicenses=('GPL' 'FDL')\fR + +.TP +.B 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 +\fIsource\fR array. (eg, install=pkgname.install) + +." Is this applicable below? +.TP +.B up2date +This directive should contain a command that prints the current upstream stable +version of the project. + +.TP +.B source \fI(array)\fR +The \fIsource\fR line is an array of source files required to build the +package. Source files must reside in the same directory as the PKGBUILD +file, unless they have a fully-qualified URL. + +.TP +.B md5sums \fI(array)\fR +If this field is present, it should contain an MD5 hash for every source file +specified in the \fIsource\fR array (in the same order). \fImakepkg\fR will use +this to verify source file integrity during subsequent builds. To easily +generate md5sums, first build using the PKGBUILD then run +\fBmakepkg -g >>PKGBUILD\fR. Then you can edit the PKGBUILD and move the +\fImd5sums\fR line from the bottom to an appropriate location. + +." Is this applicable below? +.TP +.B signatures \fI(array)\fR +If this field is present, it should contain an array of gpg signatures required +to validate the source files. Where there is no signature available just leave +it empty, like: + +signatures=(${source[0]}.asc '') + +.TP +.B groups \fI(array)\fR +This is 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. + +.TP +.B archs \fI(array)\fR +This array defines on which architectures the given package is available. + +.TP +.B backup \fI(array)\fR +A space-delimited array of filenames (without a preceding slash). The +\fIbackup\fR line will be propagated to the package meta-info file for +pacman. This will designate all files listed there to be backed up if this +package is ever removed from a system. See \fBHANDLING CONFIG FILES\fR in +the \fIpacman\fR manpage for more information. + +.TP +.B depends \fI(array)\fR +An array of packages that this package depends on to build and run. Packages +in this list should be surrounded with single quotes and contain at least the +package name. They can also include a version requirement of the form +\fBname<>version\fR, where <> is one of these three comparisons: +\fB>=\fR (greater than equal to), \fB<=\fR (less than or equal to), or +\fB=\fR (equal to). + +.TP +.B makedepends \fI(array)\fR +An array of packages that this package depends on to build, but not at runtime. +Packages in this list should follow the same format as \fIdepends\fR. + +.TP +.B conflicts \fI(array)\fR +An array of packages that will conflict with this package (ie, they cannot both +be installed at the same time). This directive follows the same format as +\fIdepends\fR except you cannot specify versions. + +.TP +.B provides \fI(array)\fR +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 kernel26beyond package can each provide 'kernel26' which allows packages +to simply depend on 'kernel26' rather than "kernel26 OR kernel26beyond". + +.TP +.B replaces \fI(array)\fR +This is an array of packages that this package should replace, and can be used +to handle renamed/combined packages. For example, if the j2re package gets +renamed to jre, then subsequent 'pacman -Syu' calls will not pick up the +upgrade, due to the differing package names. \fIreplaces\fR handles this. + +.TP +.B options \fI(array)\fR +This array allows you to override some of makepkg's default behaviour +when building packages. To set an option, just include the option name +in the \fBoptions\fR array. +.RS +.TP +.B nostrip +don't strip binaries/libraries. +.TP +.B keepdocs +keep /usr/share/doc and /usr/share/info directories. +.TP +.B force +force the package to be upgraded by --sysupgrade, even if it's an older version. +.RE + +.SH EXAMPLE +The following is an example PKGBUILD for the 'modutils' package. For more +examples, look through the ABS tree. + +.nf +# Maintainer: John Doe <johndoe@archlinux.org> +pkgname=modutils +pkgver=2.4.25 +pkgrel=1 +pkgdesc="Utilities for inserting modules in the linux kernel" +url="http://www.kernel.org" +makedepends=('bash' 'mawk') +depends=('glibc' 'zlib') +backup=(etc/modules.conf) +source=(ftp://ftp.kernel.org/pub/linux/utils/kernel/$pkgname/v2.4/$pkgname-$pkgver.tar.bz2 \\ + modules.conf) +md5sums=('2c0cca3ef6330a187c6ef4fe41ecaa4d' \\ + '35175bee593a7cc7d6205584a94d8625') + +build() { + cd $startdir/src/$pkgname-$pkgver + ./configure --prefix=/usr --enable-insmod-static + make || return 1 + make prefix=$startdir/pkg/usr install + mv $startdir/pkg/usr/sbin $startdir/pkg + mkdir -p $startdir/pkg/etc + cp ../modules.conf $startdir/pkg/etc +} +.fi + +.SH SEE ALSO +.BR makepkg (8), +.BR pacman (8) + +See the Arch Linux website at <http://www.archlinux.org> for more current +information on the distribution, and +<http://wiki.archlinux.org/index.php/Arch_Packaging_Standards> for +recommendations on packaging standards. +.SH AUTHORS +Judd Vinet <jvinet@zeroflux.org> +and the Frugalware developers <frugalware-devel@frugalware.org> |