PKGBUILD.5.txt

   1 /////
   2 vim:set ts=4 sw=4 syntax=asciidoc noet:
   3 /////
   4 PKGBUILD(5)
   5 ===========
   6
   7 Nome
   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 optional packages (and accompanying reasons) that are not
 144         essential to the package, but would offer increased functionality or other
 145         features when installed. optdepends are currently for informational
 146         purposes only and are not utilized by pacman during dependency resolution.
 147         The format 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.
 164
 165 *replaces (array)*::
 166         An array of packages that this package should replace, and can be used
 167         to handle renamed/combined packages. For example, if the 'j2re' package
 168         is renamed to 'jre', this directive allows future upgrades to continue
 169         as expected even though the package has moved. Sysupgrade is currently
 170         the only pacman operation that utilizes this field, a normal sync will
 171         not use its value.
 172
 173 *options (array)*::
 174         This array allows you to override some of makepkg's default behavior
 175         when building packages. To set an option, just include the option name
 176         in the options array. To reverse the default behavior, place an ``!'' at
 177         the front of the option. Only specify the options you specifically want
 178         to override, the rest will be taken from linkman:makepkg.conf[5].
 179         *NOTE:* 'force' is a special option only used in a linkman:PKGBUILD[5],
 180         do not use it unless you know what you are doing.
 181
 182         *strip*;;
 183                 Strip symbols from binaries and libraries. If you frequently
 184                 use a debugger on programs or libraries, it may be helpful to
 185                 disable this option.
 186
 187         *docs*;;
 188                 Save doc directories. If you wish to delete doc directories,
 189                 specify `!docs` in the array.
 190
 191         *libtool*;;
 192                 Leave libtool (.la) files in packages. Specify `!libtool` to
 193                 remove them.
 194
 195         *emptydirs*;;
 196                 Leave empty directories in packages.
 197
 198         *zipman*;;
 199                 Compress man and info pages with gzip.
 200
 201         *ccache*;;
 202                 Allow the use of ccache during build. More useful in its negative
 203                 form `!ccache` with select packages that have problems building
 204                 with ccache.
 205
 206         *distcc*;;
 207                 Allow the use of distcc during build. More useful in its negative
 208                 form `!distcc` with select packages that have problems building
 209                 with distcc.
 210
 211         *makeflags*;;
 212                 Allow the use of user-specific makeflags during build as specified
 213                 in linkman:makepkg.conf[5]. More useful in its negative form
 214                 `!makeflags` with select packages that have problems building with
 215                 custom makeflags such as `-j2` (or higher).
 216
 217         *force*;;
 218                 Force the package to be upgraded by a pacman system upgrade
 219                 operation, even if the version number would normally not trigger
 220                 such an upgrade. This is useful when the version numbering scheme
 221                 of a package changes (or is alphanumeric). See linkman:pacman[8] for
 222                 more infomation on version comparisons.
 223
 224
 225 build() Function
 226 ----------------
 227 In addition to the above directives, the build() bash function comprises the
 228 remainder of the PKGBUILD. This is directly sourced and executed by makepkg, so
 229 anything that bash or the system has available is available for use here. Be
 230 sure any exotic commands used are covered by `makedepends`.
 231
 232 All of the above variables such as `pkgname` and `pkgver` are available for use
 233 in the build function. In addition, makepkg defines three variables for your
 234 use during the build and install process. These three variables are as follows:
 235
 236 *startdir*::
 237         This contains the absolute path to the directory where the PKGBUILD was
 238         located, which is usually the output of `$(pwd)` when makepkg is started.
 239         $$startdir$$ was most often used in combination with `/src` or `/pkg`
 240         postfixes, but use of the `srcdir` and `pkgdir` variables is preferred.
 241
 242 *srcdir*::
 243         This points to the directory where makepkg extracts or copies all source
 244         files. Although it currently is an alias for `$startdir/src`, this
 245         assumption should not be assumed true for all future revisions of makepkg.
 246
 247 *pkgdir*::
 248         This points to the directory where makepkg bundles the installed package
 249         (this directory will become the root directory of your built package).
 250         Although it currently is an alias for `$startdir/pkg`, this assumption
 251         should not be assumed true for all future revisions of makepkg.
 252
 253 If you create any variables of your own in the build function, it is
 254 recommended to use the bash `local` keyword to scope the variable to inside
 255 the build function.
 256
 257 Install/Upgrade/Remove Scripting
 258 --------------------------------
 259 Pacman has the ability to store and execute a package-specific script when it
 260 installs, removes, or upgrades a package. This allows a package to configure
 261 itself after installation and perform an opposite action upon removal.
 262
 263 The exact time the script is run varies with each operation:
 264
 265 *pre_install*::
 266         script is run right before files are extracted. One argument is passed:
 267         new package version.
 268
 269 *post_install*::
 270         script is run right after files are extracted. One argument is passed:
 271         new package version.
 272
 273 *pre_upgrade*::
 274         script is run right before files are extracted. Two arguments are passed
 275         in the following order: new package version, old package version.
 276
 277 *post_upgrade*::
 278         script is run after files are extracted. Two arguments are passed
 279         in the following order: new package version, old package version.
 280
 281 *pre_remove*::
 282         script is run right before files are removed. One argument is passed:
 283         old package version.
 284
 285 *post_remove*::
 286         script is run right after files are removed. One argument is passed:
 287         old package version.
 288
 289 To use this feature, create a file such as 'pkgname.install' and put it in the
 290 same directory as the PKGBUILD script. Then use the install directive:
 291
 292         install=pkgname.install
 293
 294 The install script does not need to be specified in the source array. A
 295 template install file is available with the source distribution of this
 296 program, or one may be provided by your distribution. For example, Arch Linux
 297 provides prototype install files in the ABS tree.
 298
 299
 300 Development Directives
 301 ----------------------
 302 makepkg supports building development versions of packages without having to
 303 manually update the pkgver in the PKGBUILD. This was formerly done using the
 304 separate utility 'versionpkg'. In order to utilize this functionality, your
 305 PKGBUILD must use correct variable names depending on the SCM being fetched
 306 from.
 307
 308 *CVS*::
 309         The generated pkgver will be the date the package is built.
 310
 311         *_cvsroot*;;
 312                 The root of the CVS repository.
 313
 314         *_cvsmod*;;
 315                 The CVS module to fetch.
 316
 317 *SVN*::
 318         The generated pkgver will be the latest SVN revision number.
 319
 320         *_svntrunk*;;
 321                 The trunk of the SVN repository.
 322
 323         *_svnmod*;;
 324                 The SVN module to fetch.
 325
 326 *Git*::
 327         The generated pkgver will be one formatted by the 'git-describe'
 328         command, with '-' characters converted to '_' characters.
 329
 330         *_gitroot*;;
 331                 The URL (all protocols supported) to the GIT repository.
 332
 333         *_gitname*;;
 334                 GIT tag or branch to use.
 335
 336 *Mercurial*::
 337         The generated pkgver will be the hg tip revision number.
 338
 339         *_hgroot*;;
 340                 The URL of the mercurial repository.
 341
 342         *_hgrepo*;;
 343                 The repository to follow.
 344
 345 *Darcs*::
 346         The generated pkgver will be the date the package is built.
 347
 348         *_darcstrunk*;;
 349                 URL to the repository trunk.
 350
 351         *_darcsmod*;;
 352                 Darcs module to use.
 353
 354 *Bazaar*::
 355         The generated pkgver will be the latest Bazaar revision number (revno).
 356
 357         *_bzrtrunk*;;
 358                 URL to the bazaar repository.
 359
 360         *_bzrmod*;;
 361                 Bazaar module to use.
 362
 363
 364 Example
 365 -------
 366 The following is an example PKGBUILD for the 'patch' package. For more
 367 examples, look through the build files of your distribution's packages. For
 368 those using Arch Linux, consult the ABS tree.
 369
 370 [sh]
 371 source~~~~~
 372 include::PKGBUILD-example.txt[]
 373 source~~~~~
 374
 375
 376 See Also
 377 --------
 378 linkman:makepkg[8], linkman:pacman[8], linkman:makepkg.conf[5]
 379
 380 include::footer.txt[]