doc/PKGBUILD.5.txt

   1 /////
   2 vim:set ts=4 sw=4 syntax=asciidoc noet:
   3 /////
   4 PKGBUILD(5)
   5 ===========
   6
   7 Name
   8 ----
   9 PKGBUILD - Arch Linux package build description file
  10
  11
  12 Synopsis
  13 --------
  14 PKGBUILD
  15
  16
  17 Description
  18 -----------
  19 This manual page is meant to describe general rules about PKGBUILDs. Once a
  20 PKGBUILD is written, the actual package is built using makepkg and installed
  21 with pacman.
  22
  23 NOTE: If you are using Arch Linux and have a local copy of the Arch Build
  24 System (ABS) tree on your computer, or are using another distribution that
  25 provides a similar tree of build files, you can copy the provided
  26 PKGBUILD.proto file to a new package build directory and make customizations to
  27 suit your needs. An up to date prototype file can also be found in the source
  28 distribution of this package.
  29
  30
  31 Options and Directives
  32 ----------------------
  33 The following is a list of standard options and directives available for use
  34 in a PKGBUILD. These are all understood and interpreted by makepkg, and most
  35 will be directly transferred to the built package.
  36
  37 If you need to create any custom variables for use in your build process, it is
  38 recommended to name your custom variables with an '_' (underscore) prefix.
  39 This will prevent any possible name clashes with internal makepkg variables.
  40 For example, to store the base kernel version in a variable, use something
  41 similar to `$_basekernver`.
  42
  43 *pkgname*::
  44         The name of the package. This has be a unix-friendly name as it will be
  45         used in the package filename.
  46
  47 *pkgver*::
  48         The version of the software as released from the author (e.g. '2.7.1').
  49
  50 *pkgrel*::
  51         This is the release number specific to the Arch Linux release. This
  52         allows package maintainers to make updates to the package's configure
  53         flags, for example. A pkgrel of 1 is typically used for each upstream
  54         software release and is incremented for intermediate PKGBUILD updates.
  55
  56 *pkgdesc*::
  57         This should be a brief description of the package and its functionality.
  58         Try to keep the description to one line of text.
  59
  60 *url*::
  61         This field contains a URL that is associated with the software being
  62         packaged. This is typically the project's website.
  63
  64 *license (array)*::
  65         This field specifies the license(s) that apply to the package.
  66         Commonly-used licenses are found in '/usr/share/licenses/common'. If you
  67         see the package's license there, simply reference it in the license
  68         field (e.g. `license=('GPL')`). If the package provides a license not
  69         found in '/usr/share/licenses/common', then you should include the license
  70         in the package itself and set `license=('custom')` or
  71         `license=('custom:LicenseName')`. The license should be placed in
  72         '$pkgdir/usr/share/licenses/$pkgname' when building the package. If
  73         multiple licenses are applicable for a package, list all of them:
  74         `license=('GPL' 'FDL')`.
  75
  76 *install*::
  77         Specifies a special install script that is to be included in the package.
  78         This file should reside in the same directory as the PKGBUILD, and will
  79         be copied into the package by makepkg. It does not need to be included
  80         in the source array (e.g. `install=pkgname.install`).
  81
  82 *source (array)*::
  83         An array of source files required to build the package. Source files
  84         must either reside in the same directory as the PKGBUILD file, or be a
  85         fully-qualified URL that makepkg will use to download the file. In order
  86         to make the PKGBUILD as useful as possible, use the $pkgname and $pkgver
  87         variables if possible when specifying the download location. Any files
  88         that are compressed will automatically be extracted, unless found in
  89         the noextract array listed below.
  90 +
  91 It is also possible to specify an optional filename, which is helpful
  92 with weird URLs and for handling multiple source files with the same
  93 name. The syntax is: `source=('filename::url')`.
  94
  95 *noextract (array)*::
  96         An array of filenames corresponding to those from the source array. Files
  97         listed here will not be extracted with the rest of the source files. This
  98         is useful for packages which use compressed data which is downloaded but
  99         not necessary to uncompress.
 100
 101 *md5sums (array)*::
 102         This array contains an MD5 hash for every source file specified in the
 103         source array (in the same order). makepkg will use this to verify source
 104         file integrity during subsequent builds. To easily generate md5sums, run
 105         ``makepkg -g >> PKGBUILD''. If desired, move the md5sums line to an
 106         appropriate location.
 107
 108 *sha1sums, sha256sums, sha384sums, sha512sums (arrays)*::
 109         Alternative integrity checks that makepkg supports; these all behave
 110         similar to the md5sums option described above. To enable use and generation
 111         of these checksums, be sure to set up the `INTEGRITY_CHECK` option in
 112         linkman:makepkg.conf[5].
 113
 114 *groups (array)*::
 115         An array of symbolic names that represent groups of packages, allowing
 116         you to install multiple packages by requesting a single target. For
 117         example, one could install all KDE packages by installing the 'kde' group.
 118
 119 *arch (array)*::
 120         Defines on which architectures the given package is available (e.g.
 121         `arch=('i686' 'x86_64')`).
 122
 123 *backup (array)*::
 124         A space-delimited array of filenames, without preceding slashes, that
 125         should be backed up if the package is removed or upgraded. This is
 126         commonly used for packages placing configuration files in /etc. See
 127         Handling Config Files in linkman:pacman[8] for more information.
 128
 129 *depends (array)*::
 130         An array of packages that this package depends on to run. Packages in
 131         this list should be surrounded with single quotes and contain at least
 132         the package name. Entries can also include a version requirement of the
 133         form 'name<>version', where <> is one of five comparisons: >= (greater
 134         than or equal to), <= (less than or equal to), = (equal to), > (greater
 135         than), or < (less than).
 136
 137 *makedepends (array)*::
 138         An array of packages that this package depends on to build, but are not
 139         needed at runtime. Packages in this list follow the same format as
 140         depends.
 141
 142 *optdepends (array)*::
 143         An array of packages (and accompanying reasons) that are not essential for
 144         base functionality, but may be necessary to make full use of the contents
 145         of this package. optdepends are currently for informational purposes only
 146         and are not utilized by pacman during dependency resolution. The format
 147         should be similar to the following:
 148
 149         optdepends=('fakeroot: for makepkg usage as normal user')
 150
 151 *conflicts (array)*::
 152         An array of packages that will conflict with this package (i.e. they
 153         cannot both be installed at the same time). This directive follows the
 154         same format as depends. Versioned conflicts are also supported.
 155
 156 *provides (array)*::
 157         An array of ``virtual provisions'' that this package provides. This allows
 158         a package to provide dependencies other than its own package name. For
 159         example, the dcron package can provide 'cron', which allows packages to
 160         depend on 'cron' rather than 'dcron OR fcron'.
 161         Versioned provisions are also possible, in the 'name=version' format.
 162         For example, dcron can provide 'cron=2.0' to satisfy the 'cron>=2.0'
 163         dependency of other packages. Provisions involving the '>' and '<'
 164         operators are invalid as only specific versions of a package may be
 165         provided.
 166
 167 *replaces (array)*::
 168         An array of packages that this package should replace, and can be used
 169         to handle renamed/combined packages. For example, if the 'j2re' package
 170         is renamed to 'jre', this directive allows future upgrades to continue
 171         as expected even though the package has moved. Sysupgrade is currently
 172         the only pacman operation that utilizes this field, a normal sync will
 173         not use its value.
 174
 175 *options (array)*::
 176         This array allows you to override some of makepkg's default behavior
 177         when building packages. To set an option, just include the option name
 178         in the options array. To reverse the default behavior, place an ``!'' at
 179         the front of the option. Only specify the options you specifically want
 180         to override, the rest will be taken from linkman:makepkg.conf[5].
 181         *NOTE:* 'force' is a special option only used in a linkman:PKGBUILD[5],
 182         do not use it unless you know what you are doing.
 183
 184         *strip*;;
 185                 Strip symbols from binaries and libraries. If you frequently
 186                 use a debugger on programs or libraries, it may be helpful to
 187                 disable this option.
 188
 189         *docs*;;
 190                 Save doc directories. If you wish to delete doc directories,
 191                 specify `!docs` in the array.
 192
 193         *libtool*;;
 194                 Leave libtool (.la) files in packages. Specify `!libtool` to
 195                 remove them.
 196
 197         *emptydirs*;;
 198                 Leave empty directories in packages.
 199
 200         *zipman*;;
 201                 Compress man and info pages with gzip.
 202
 203         *ccache*;;
 204                 Allow the use of ccache during build. More useful in its negative
 205                 form `!ccache` with select packages that have problems building
 206                 with ccache.
 207
 208         *distcc*;;
 209                 Allow the use of distcc during build. More useful in its negative
 210                 form `!distcc` with select packages that have problems building
 211                 with distcc.
 212
 213         *makeflags*;;
 214                 Allow the use of user-specific makeflags during build as specified
 215                 in linkman:makepkg.conf[5]. More useful in its negative form
 216                 `!makeflags` with select packages that have problems building with
 217                 custom makeflags such as `-j2` (or higher).
 218
 219         *force*;;
 220                 Force the package to be upgraded by a pacman system upgrade
 221                 operation, even if the version number would normally not trigger
 222                 such an upgrade. This is useful when the version numbering scheme
 223                 of a package changes (or is alphanumeric). See linkman:pacman[8] for
 224                 more information on version comparisons.
 225
 226
 227 build() Function
 228 ----------------
 229 In addition to the above directives, the build() bash function comprises the
 230 remainder of the PKGBUILD. This is directly sourced and executed by makepkg, so
 231 anything that bash or the system has available is available for use here. Be
 232 sure any exotic commands used are covered by `makedepends`.
 233
 234 All of the above variables such as `pkgname` and `pkgver` are available for use
 235 in the build function. In addition, makepkg defines three variables for your
 236 use during the build and install process. These three variables are as follows:
 237
 238 *startdir*::
 239         This contains the absolute path to the directory where the PKGBUILD was
 240         located, which is usually the output of `$(pwd)` when makepkg is started.
 241
 242 *srcdir*::
 243         This points to the directory where makepkg extracts or copies all source
 244         files.
 245
 246 *pkgdir*::
 247         This points to the directory where makepkg bundles the installed package
 248         (this directory will become the root directory of your built package).
 249
 250 If you create any variables of your own in the build function, it is
 251 recommended to use the bash `local` keyword to scope the variable to inside
 252 the build function.
 253
 254 package() Function
 255 ------------------
 256 An optional package() function can be specified in addition to the build() function.
 257 This function is run immediately after the build() function. When specified in
 258 combination with the fakeroot BUILDENV option in linkman:makepkg.conf[5], fakeroot
 259 usage will be limited to running the packaging stage. The build() function will be
 260 run as the user calling makepkg.
 261
 262 Package Splitting
 263 -----------------
 264 makepkg supports building multiple packages from a single PKGBUILD. This is achieved
 265 by assigning an array of package names to the `pkgname` directive. Each split package
 266 uses a corresponding packaging function with name `package_foo()`, where `foo` is the
 267 name of the split package.
 268
 269 All options and directives for the split packages default to the global values given
 270 within the PKGBUILD. However, some of these can be overridden within each split
 271 package's packaging function. The following variables can be overridden: `pkgdesc`,
 272 `license`, `groups`, `depends`, `optdepends`, `provides`, `conflicts`, `replaces`,
 273 `backup`, `options` and `install`.
 274
 275 An optional global directive is available when building a split package:
 276
 277 *pkgbase*::
 278         The name used to refer to the group of packages in the output of makepkg
 279         and in the naming of source-only tarballs.  If not specified, the first
 280         element in the `pkgname` array is used.
 281
 282 Install/Upgrade/Remove Scripting
 283 --------------------------------
 284 Pacman has the ability to store and execute a package-specific script when it
 285 installs, removes, or upgrades a package. This allows a package to configure
 286 itself after installation and perform an opposite action upon removal.
 287
 288 The exact time the script is run varies with each operation:
 289
 290 *pre_install*::
 291         script is run right before files are extracted. One argument is passed:
 292         new package version.
 293
 294 *post_install*::
 295         script is run right after files are extracted. One argument is passed:
 296         new package version.
 297
 298 *pre_upgrade*::
 299         script is run right before files are extracted. Two arguments are passed
 300         in the following order: new package version, old package version.
 301
 302 *post_upgrade*::
 303         script is run after files are extracted. Two arguments are passed
 304         in the following order: new package version, old package version.
 305
 306 *pre_remove*::
 307         script is run right before files are removed. One argument is passed:
 308         old package version.
 309
 310 *post_remove*::
 311         script is run right after files are removed. One argument is passed:
 312         old package version.
 313
 314 To use this feature, create a file such as 'pkgname.install' and put it in the
 315 same directory as the PKGBUILD script. Then use the install directive:
 316
 317         install=pkgname.install
 318
 319 The install script does not need to be specified in the source array. A
 320 template install file is available with the source distribution of this
 321 program, or one may be provided by your distribution. For example, Arch Linux
 322 provides prototype install files in the ABS tree.
 323
 324
 325 Development Directives
 326 ----------------------
 327 makepkg supports building development versions of packages without having to
 328 manually update the pkgver in the PKGBUILD. This was formerly done using the
 329 separate utility 'versionpkg'. In order to utilize this functionality, your
 330 PKGBUILD must use correct variable names depending on the SCM being fetched
 331 from.
 332
 333 *CVS*::
 334         The generated pkgver will be the date the package is built.
 335
 336         *_cvsroot*;;
 337                 The root of the CVS repository.
 338
 339         *_cvsmod*;;
 340                 The CVS module to fetch.
 341
 342 *SVN*::
 343         The generated pkgver will be the latest SVN revision number.
 344
 345         *_svntrunk*;;
 346                 The trunk of the SVN repository.
 347
 348         *_svnmod*;;
 349                 The SVN module to fetch.
 350
 351 *Git*::
 352         The generated pkgver will be one formatted by the 'git-describe'
 353         command, with '-' characters converted to '_' characters.
 354
 355         *_gitroot*;;
 356                 The URL (all protocols supported) to the GIT repository.
 357
 358         *_gitname*;;
 359                 GIT tag or branch to use.
 360
 361 *Mercurial*::
 362         The generated pkgver will be the hg tip revision number.
 363
 364         *_hgroot*;;
 365                 The URL of the mercurial repository.
 366
 367         *_hgrepo*;;
 368                 The repository to follow.
 369
 370 *Darcs*::
 371         The generated pkgver will be the date the package is built.
 372
 373         *_darcstrunk*;;
 374                 URL to the repository trunk.
 375
 376         *_darcsmod*;;
 377                 Darcs module to use.
 378
 379 *Bazaar*::
 380         The generated pkgver will be the latest Bazaar revision number (revno).
 381
 382         *_bzrtrunk*;;
 383                 URL to the bazaar repository.
 384
 385         *_bzrmod*;;
 386                 Bazaar module to use.
 387
 388
 389 Example
 390 -------
 391 The following is an example PKGBUILD for the 'patch' package. For more
 392 examples, look through the build files of your distribution's packages. For
 393 those using Arch Linux, consult the ABS tree.
 394
 395 [source,sh]
 396 -------------------------------
 397 include::PKGBUILD-example.txt[]
 398 -------------------------------
 399
 400 See Also
 401 --------
 402 linkman:makepkg[8], linkman:pacman[8], linkman:makepkg.conf[5]
 403
 404 include::footer.txt[]