doc/PKGBUILD.5

   1 ." the string declarations are a start to try and make distro independent
   2 .ds DS Arch Linux
   3 .ds PB PKGBUILD
   4 .ds VR 3.0.0
   5 .TH \*(PB 5 "Feb 07, 2007" "\*(PB version \*(VR" "\*(DS Files"
   6 .SH NAME
   7 \*(PB \- \*(DS package build description file
   8
   9 .SH DESCRIPTION
  10 This manual page is meant to describe general rules about \fB\*(PB\fPs. Once
  11 a \fB\*(PB\fP is written, the actual package is built using \fBmakepkg\fP and
  12 installed with \fBpacman\fP.
  13
  14 \fBNOTE:\fP If you have a local copy of the Arch Build System (ABS) tree
  15 on your computer, you can copy the \*(PB.proto file to your new package
  16 build directory and edit it from there.  To acquire/sync the ABS tree, use
  17 the \fBabs\fP script included with \fBpacman\fP.
  18
  19 .SH OPTIONS AND DIRECTIVES
  20 .TP
  21 .B pkgname
  22 The name of the package. This has be a unix-friendly name as it will be
  23 used in the package filename.
  24
  25 .TP
  26 .B pkgver
  27 The version of the software as released from the author (e.g. 2.7.1).
  28
  29 .TP
  30 .B pkgrel
  31 This is the release number specific to the \*(DSs release. This allows package
  32 maintainers to make updates to the package's configure flags, for example.
  33
  34 .TP
  35 .B pkgdesc
  36 This should be a brief description of the package and its functionality. Try to
  37 keep the description to one line of text.
  38
  39 .TP
  40 .B url
  41 This field contains a URL that is associated with the software being packaged.
  42 This is typically the project's website.
  43
  44 .TP
  45 .B license (array)
  46 This field specifies the license(s) that apply to the package. Commonly-used
  47 licenses are found in \fI/usr/share/licenses/common\fP. If you see the
  48 package's license there, simply reference it in the license field (e.g.
  49 \fBlicense=("GPL")\fP). If the package provides a license not found in
  50 \fI/usr/share/licenses/common\fP, then you should include the license in the
  51 package itself and set \fBlicense=("custom")\fP or
  52 \fBlicense=("custom:LicenseName")\fP. The license should be placed in
  53 \fI$startdir/pkg/usr/share/licenses/$pkgname\fP when building the package. If
  54 multiple licenses are applicable for a package, list all of them:
  55 \fBlicenses=('GPL' 'FDL')\fP.
  56
  57 .TP
  58 .B install
  59 Specifies a special install script that is to be included in the package. This
  60 file should reside in the same directory as the \fB\*(PB\fP, and will be copied
  61 into the package by \fBmakepkg\fP. It does not need to be included in the
  62 \fIsource\fP array (e.g. \fBinstall=pkgname.install\fP).
  63
  64 .TP
  65 .B source \fI(array)\fP
  66 An array of source files required to build the package. Source files must
  67 either reside in the same directory as the \fB\*(PB file\fP, or be a
  68 fully-qualified URL that makepkg will use to download the file.  In order to
  69 make the PKGBUILD as useful as possible, use the \fB$pkgname\fP and
  70 \fB$pkgver\fP variables if possible when specifying the download location.
  71
  72 .TP
  73 .B noextract \fI(array)\fP
  74 An array of filenames corresponding to those from the \fBsource\fP array. Files
  75 listed here will not be extracted with the rest of the source files. This is
  76 useful for packages which use compressed data which is downloaded but not
  77 necessary to uncompress.
  78
  79 .TP
  80 .B md5sums \fI(array)\fP
  81 This array contains an MD5 hash for every source file specified in the
  82 \fBsource\fP array (in the same order). \fBmakepkg\fP will use this to verify
  83 source file integrity during subsequent builds. To easily generate md5sums, run
  84 "makepkg -g >> \*(PB".  If desired, move the \fBmd5sums\fP line to an
  85 appropriate location.  NOTE: \fBmakepkg\fP supports multiple integrity
  86 algorithms and their corresponding arrays (i.e. sha1sums for the SHA1
  87 algorithm); however, official packages use only md5sums for the time being.
  88
  89 .TP
  90 .B sha1sums, etc.
  91 Alternative integrity checks that \fBmakepkg\fP supports, as noted in
  92 \fBmd5sums\fP above.
  93
  94 .TP
  95 .B groups \fI(array)\fP
  96 An array of symbolic names that represent groups of packages, allowing
  97 you to install multiple packages by requesting a single target. For example,
  98 one could install all KDE packages by installing the 'kde' group.
  99
 100 .TP
 101 .B arch \fI(array)\fP
 102 Defines on which architectures the given package is available (e.g.
 103 \fBarch=('i686' 'x86_64')\fP).
 104
 105 .TP
 106 .B backup \fI(array)\fP
 107 A space-delimited array of filenames, \fIwithout\fP preceding slashes, that
 108 should be backed up if the package is removed or upgraded. This is commonly
 109 used for packages placing configuration files in /etc. See \fBHANDLING CONFIG
 110 FILES\fP in the \fBpacman\fP manpage for more information.
 111
 112 .TP
 113 .B depends \fI(array)\fP
 114 An array of packages that this package depends on to run. Packages in this list
 115 should be surrounded with single quotes and contain at least the package name.
 116 Entries can also include a version requirement of the form
 117 \fB'name<>version'\fP, where <> is one of three comparisons: \fI>=\fP (greater
 118 than or equal to), \fI<=\fP (less than or equal to), or \fI=\fP (equal to).
 119
 120 .TP
 121 .B makedepends \fI(array)\fP
 122 An array of packages that this package depends on to build, but are not needed
 123 at runtime.  Packages in this list follow the same format as \fBdepends\fP.
 124
 125 .TP
 126 .B conflicts \fI(array)\fP
 127 An array of packages that will conflict with this package (i.e. they cannot
 128 both be installed at the same time). This directive follows the same format as
 129 \fIdepends\fP, except you cannot specify versions.
 130
 131 .TP
 132 .B provides \fI(array)\fP
 133 An array of "virtual provisions" that this package provides. This allows a
 134 package to provide dependencies other than its own package name. For example,
 135 the dcron package can provide 'cron', which allows packages to depend on 'cron'
 136 rather than 'dcron OR fcron'.
 137
 138 .TP
 139 .B replaces \fI(array)\fP
 140 An array of packages that this package should replace, and can be used to
 141 handle renamed/combined packages. For example, if the 'j2re' package is renamed
 142 to 'jre', this directive allows future upgrades to continue as expected even
 143 though the package has moved.
 144
 145 .TP
 146 .B options \fI(array)\fP
 147 This array allows you to override some of \fBmakepkg\fP's default behavior when
 148 building packages. To set an option, just include the option name in the
 149 \fBoptions\fP array. To reverse the default behavior, place an "!" at the front
 150 of the option. Only specify the options you specifically want to override, the
 151 rest will be taken from \fBmakepkg.conf\fP. NOTE: 'force' is a special option
 152 only used in \fB\*(PB\fPs, do not use it unless you know what you are doing.
 153 .RS
 154 .TP
 155 .B strip
 156 Strip symbols from binaries and libraries. If you frequently use a debugger on
 157 programs or libraries, it may be helpful to disable this option.
 158 .TP
 159 .B docs
 160 Save doc and info directories. If you wish to delete doc and info directories,
 161 specify "!docs" in the array.
 162 .TP
 163 .B libtool
 164 Leave libtool (.la) files in packages. Specify "!libtool" to remove them.
 165 .TP
 166 .B emptydirs
 167 Leave empty directories in packages.
 168 .TP
 169 .B ccache
 170 Allow the use of \fBccache\fP during build. More useful in its negative form
 171 "!ccache" with select packages that have problems building with \fBccache\fP.
 172 .TP
 173 .B distcc
 174 Allow the use of \fBdistcc\fP during build. More useful in its negative form
 175 "!distcc" with select packages that have problems building with \fBdistcc\fP.
 176 .TP
 177 .B makeflags
 178 Allow the use of user-specific makeflags during build as specified in
 179 \fBmakepkg.conf\fP. More useful in its negative form "!makeflags" with select
 180 packages that have problems building with custom makeflags such as "-j2" (or
 181 higher).
 182 .TP
 183 .B force
 184 Force the package to be upgraded by a \fBpacman\fP system upgrade operation,
 185 even if the version number would normally not trigger such an upgrade. This is
 186 useful when the version numbering scheme of a package changes (or is
 187 alphanumeric).
 188 .RE
 189
 190 .SH INSTALL/UPGRADE/REMOVE SCRIPTING
 191 \fBPacman\fP has the ability to store and execute a package-specific script
 192 when it installs, removes, or upgrades a package.  This allows a package to
 193 configure itself after installation and do the opposite right before it is
 194 removed.
 195
 196 The exact time the script is run varies with each operation:
 197
 198 .TP
 199 .B pre_install
 200 script is run right before files are extracted.
 201
 202 .TP
 203 .B post_install
 204 script is run right after files are extracted.
 205
 206 .TP
 207 .B pre_upgrade
 208 script is run right before files are extracted.
 209
 210 .TP
 211 .B post_upgrade
 212 script is run after files are extracted.
 213
 214 .TP
 215 .B pre_remove
 216 script is run right before files are removed.
 217
 218 .TP
 219 .B post_remove
 220 script is run right after files are removed.
 221
 222 .P
 223 To use this feature, create a file such as 'pkgname.install' and put it in
 224 the same directory as the \fB\*(PB\fP script.  Then use the \fBinstall\fP
 225 directive:
 226
 227 .RS
 228 .nf
 229 install=pkgname.install
 230 .fi
 231 .RE
 232
 233 The install script does not need to be specified in the \fBsource\fP array.
 234 A template install file is available in the ABS tree (/var/abs/install.proto).
 235
 236 .SH EXAMPLE
 237 The following is an example \fB\*(PB\fP for the 'modutils' package. For more
 238 examples, look through the ABS tree.
 239
 240 .nf
 241 # Maintainer: John Doe <johndoe@archlinux.org>
 242 # Contributor: Bill Smith <billsmith@archlinux.org>
 243 pkgname=modutils
 244 pkgver=2.4.25
 245 pkgrel=1
 246 pkgdesc="Utilities for inserting modules in the linux kernel"
 247 url="http://www.kernel.org"
 248 makedepends=('bash' 'mawk')
 249 depends=('glibc' 'zlib')
 250 backup=(etc/modules.conf)
 251 source=(ftp://ftp.kernel.org/pub/linux/utils/kernel/$pkgname/v2.4/$pkgname-$pkgver.tar.bz2
 252         modules.conf)
 253 arch=('i686')
 254 license=('GPL' 'custom') # dual licensed
 255 md5sums=('2c0cca3ef6330a187c6ef4fe41ecaa4d'
 256          '35175bee593a7cc7d6205584a94d8625')
 257 options=(!libtool)
 258
 259 build() {
 260   cd $startdir/src/$pkgname-$pkgver
 261   ./configure --prefix=/usr --enable-insmod-static
 262   make || return 1
 263   make prefix=$startdir/pkg/usr install
 264   mv $startdir/pkg/usr/sbin $startdir/pkg
 265   mkdir -p $startdir/pkg/etc
 266   cp ../modules.conf $startdir/pkg/etc
 267 }
 268 .fi
 269
 270 .SH SEE ALSO
 271 .BR makepkg (8),
 272 .BR pacman (8),
 273 .BR makepkg.conf (5)
 274
 275 See the Arch Linux website at <http://www.archlinux.org> for more current
 276 information on the distribution and the \fBpacman\fP family of tools, and
 277 <http://wiki.archlinux.org/index.php/Arch_Packaging_Standards> for
 278 recommendations on packaging standards.
 279
 280 .SH AUTHORS
 281 .nf
 282 Judd Vinet <jvinet@zeroflux.org>
 283 Aurelien Foret <aurelien@archlinux.org>
 284 Aaron Griffin <aaron@archlinux.org>
 285 Dan McGee <dan@archlinux.org>
 286 .fi
 287
 288 See the 'AUTHORS' file for additional contributors.