1PKGBUILD(5)                      Pacman Manual                     PKGBUILD(5)
2
3
4

NAME

6       PKGBUILD - Arch Linux package build description file
7

SYNOPSIS

9       PKGBUILD
10

DESCRIPTION

12       This manual page describes general rules about PKGBUILDs. Once a
13       PKGBUILD is written, the actual package is built using makepkg and
14       installed with pacman.
15
16           Note
17           An example PKGBUILD, useful for reference, is located in
18           /usr/share/pacman along with other example files such as a
19           ChangeLog and an install script. You can copy the provided
20           PKGBUILD.proto file to a new package build directory and make
21           customizations to suit your needs.
22

OPTIONS AND DIRECTIVES

24       The following is a list of standard options and directives available
25       for use in a PKGBUILD. These are all understood and interpreted by
26       makepkg, and most of them will be directly transferred to the built
27       package. The mandatory fields for a minimally functional PKGBUILD are
28       pkgname, pkgver, pkgrel and arch.
29
30       If you need to create any custom variables for use in your build
31       process, it is recommended to prefix their name with an _ (underscore).
32       This will prevent any possible name clashes with internal makepkg
33       variables. For example, to store the base kernel version in a variable,
34       use something similar to $_basekernver.
35
36       pkgname (array)
37           Either the name of the package or an array of names for split
38           packages. Valid characters for members of this array are
39           alphanumerics, and any of the following characters: “@ . _ + -”.
40           Additionally, names are not allowed to start with hyphens or dots.
41
42       pkgver
43           The version of the software as released from the author (e.g.,
44           2.7.1). The variable is not allowed to contain colons or hyphens.
45
46           The pkgver variable can be automatically updated by providing a
47           pkgver() function in the PKGBUILD that outputs the new package
48           version. This is run after downloading and extracting the sources
49           and running the prepare() function (if present), so it can use
50           those files in determining the new pkgver. This is most useful when
51           used with sources from version control systems (see below).
52
53       pkgrel
54           This is the release number specific to the Arch Linux release. This
55           allows package maintainers to make updates to the package’s
56           configure flags, for example. This is typically set to 1 for each
57           new upstream software release and incremented for intermediate
58           PKGBUILD updates. The variable is not allowed to contain hyphens.
59
60       epoch
61           Used to force the package to be seen as newer than any previous
62           versions with a lower epoch, even if the version number would
63           normally not trigger such an upgrade. This value is required to be
64           a positive integer; the default value if left unspecified is 0.
65           This is useful when the version numbering scheme of a package
66           changes (or is alphanumeric), breaking normal version comparison
67           logic. See pacman(8) for more information on version comparisons.
68
69       pkgdesc
70           This should be a brief description of the package and its
71           functionality. Try to keep the description to one line of text and
72           to not use the package’s name.
73
74       url
75           This field contains a URL that is associated with the software
76           being packaged. This is typically the project’s web site.
77
78       license (array)
79           This field specifies the license(s) that apply to the package.
80           Commonly used licenses can be found in /usr/share/licenses/common.
81           If you see the package’s license there, simply reference it in the
82           license field (e.g., license=('GPL')). If the package provides a
83           license not available in /usr/share/licenses/common, then you
84           should include it in the package itself and set license=('custom')
85           or license=('custom:LicenseName'). The license should be placed in
86           $pkgdir/usr/share/licenses/$pkgname/ when building the package. If
87           multiple licenses are applicable, list all of them: license=('GPL'
88           'FDL').
89
90       install
91           Specifies a special install script that is to be included in the
92           package. This file should reside in the same directory as the
93           PKGBUILD and will be copied into the package by makepkg. It does
94           not need to be included in the source array (e.g.,
95           install=$pkgname.install).
96
97       changelog
98           Specifies a changelog file that is to be included in the package.
99           The changelog file should end in a single newline. This file should
100           reside in the same directory as the PKGBUILD and will be copied
101           into the package by makepkg. It does not need to be included in the
102           source array (e.g., changelog=$pkgname.changelog).
103
104       source (array)
105           An array of source files required to build the package. Source
106           files must either reside in the same directory as the PKGBUILD, or
107           be a fully-qualified URL that makepkg can use to download the file.
108           To simplify the maintenance of PKGBUILDs, use the $pkgname and
109           $pkgver variables when specifying the download location, if
110           possible. Compressed files will be extracted automatically unless
111           found in the noextract array described below.
112
113           Additional architecture-specific sources can be added by appending
114           an underscore and the architecture name e.g., source_x86_64=().
115           There must be a corresponding integrity array with checksums, e.g.
116           md5sums_x86_64=().
117
118           It is also possible to change the name of the downloaded file,
119           which is helpful with weird URLs and for handling multiple source
120           files with the same name. The syntax is: source=('filename::url').
121
122           makepkg also supports building developmental versions of packages
123           using sources downloaded from version control systems (VCS). For
124           more information, see Using VCS Sources below.
125
126           Files in the source array with extensions .sig, .sign or, .asc are
127           recognized by makepkg as PGP signatures and will be automatically
128           used to verify the integrity of the corresponding source file.
129
130       validpgpkeys (array)
131           An array of PGP fingerprints. If this array is non-empty, makepkg
132           will only accept signatures from the keys listed here and will
133           ignore the trust values from the keyring. If the source file was
134           signed with a subkey, makepkg will still use the primary key for
135           comparison.
136
137           Only full fingerprints are accepted. They must be uppercase and
138           must not contain whitespace characters.
139
140       noextract (array)
141           An array of file names corresponding to those from the source
142           array. Files listed here will not be extracted with the rest of the
143           source files. This is useful for packages that use compressed data
144           directly.
145
146       md5sums (array)
147           This array contains an MD5 hash for every source file specified in
148           the source array (in the same order). makepkg will use this to
149           verify source file integrity during subsequent builds. If SKIP is
150           put in the array in place of a normal hash, the integrity check for
151           that source file will be skipped. To easily generate md5sums, run
152           “makepkg -g >> PKGBUILD”. If desired, move the md5sums line to an
153           appropriate location.
154
155       sha1sums, sha256sums, sha384sums, sha512sums (arrays)
156           Alternative integrity checks that makepkg supports; these all
157           behave similar to the md5sums option described above. To enable use
158           and generation of these checksums, be sure to set up the
159           INTEGRITY_CHECK option in makepkg.conf(5).
160
161       groups (array)
162           An array of symbolic names that represent groups of packages,
163           allowing you to install multiple packages by requesting a single
164           target. For example, one could install all KDE packages by
165           installing the kde group.
166
167       arch (array)
168           Defines on which architectures the given package is available
169           (e.g., arch=('i686' 'x86_64')). Packages that contain no
170           architecture specific files should use arch=('any').
171
172       backup (array)
173           An array of file names, without preceding slashes, that should be
174           backed up if the package is removed or upgraded. This is commonly
175           used for packages placing configuration files in /etc. See
176           "Handling Config Files" in pacman(8) for more information.
177
178       depends (array)
179           An array of packages this package depends on to run. Entries in
180           this list should be surrounded with single quotes and contain at
181           least the package name. Entries can also include a version
182           requirement of the form name<>version, where <> is one of five
183           comparisons: >= (greater than or equal to), <= (less than or equal
184           to), = (equal to), > (greater than), or < (less than).
185
186           If the dependency name appears to be a library (ends with .so),
187           makepkg will try to find a binary that depends on the library in
188           the built package and append the version needed by the binary.
189           Appending the version yourself disables automatic detection.
190
191           Additional architecture-specific depends can be added by appending
192           an underscore and the architecture name e.g., depends_x86_64=().
193
194       makedepends (array)
195           An array of packages this package depends on to build but are not
196           needed at runtime. Packages in this list follow the same format as
197           depends.
198
199           Additional architecture-specific makedepends can be added by
200           appending an underscore and the architecture name e.g.,
201           makedepends_x86_64=().
202
203       checkdepends (array)
204           An array of packages this package depends on to run its test suite
205           but are not needed at runtime. Packages in this list follow the
206           same format as depends. These dependencies are only considered when
207           the check() function is present and is to be run by makepkg.
208
209           Additional architecture-specific checkdepends can be added by
210           appending an underscore and the architecture name e.g.,
211           checkdepends_x86_64=().
212
213       optdepends (array)
214           An array of packages (and accompanying reasons) that are not
215           essential for base functionality, but may be necessary to make full
216           use of the contents of this package. optdepends are currently for
217           informational purposes only and are not utilized by pacman during
218           dependency resolution. The format for specifying optdepends is:
219
220               optdepends=('python: for library bindings')
221
222           Additional architecture-specific optdepends can be added by
223           appending an underscore and the architecture name e.g.,
224           optdepends_x86_64=().
225
226       conflicts (array)
227           An array of packages that will conflict with this package (i.e.
228           they cannot both be installed at the same time). This directive
229           follows the same format as depends. Versioned conflicts are
230           supported using the operators as described in depends.
231
232           Additional architecture-specific conflicts can be added by
233           appending an underscore and the architecture name e.g.,
234           conflicts_x86_64=().
235
236       provides (array)
237           An array of “virtual provisions” this package provides. This allows
238           a package to provide dependencies other than its own package name.
239           For example, the dcron package can provide cron, which allows
240           packages to depend on cron rather than dcron OR fcron.
241
242           Versioned provisions are also possible, in the name=version format.
243           For example, dcron can provide cron=2.0 to satisfy the cron>=2.0
244           dependency of other packages. Provisions involving the > and <
245           operators are invalid as only specific versions of a package may be
246           provided.
247
248           If the provision name appears to be a library (ends with .so),
249           makepkg will try to find the library in the built package and
250           append the correct version. Appending the version yourself disables
251           automatic detection.
252
253           Additional architecture-specific provides can be added by appending
254           an underscore and the architecture name e.g., provides_x86_64=().
255
256       replaces (array)
257           An array of packages this package should replace. This can be used
258           to handle renamed/combined packages. For example, if the j2re
259           package is renamed to jre, this directive allows future upgrades to
260           continue as expected even though the package has moved. Versioned
261           replaces are supported using the operators as described in depends.
262
263           Sysupgrade is currently the only pacman operation that utilizes
264           this field. A normal sync or upgrade will not use its value.
265
266           Additional architecture-specific replaces can be added by appending
267           an underscore and the architecture name e.g., replaces_x86_64=().
268
269       options (array)
270           This array allows you to override some of makepkg’s default
271           behavior when building packages. To set an option, just include the
272           option name in the options array. To reverse the default behavior,
273           place an “!” at the front of the option. Only specify the options
274           you specifically want to override, the rest will be taken from
275           makepkg.conf(5).  NOTE: force is a now-removed option in favor of
276           the top level epoch variable.
277
278           strip
279               Strip symbols from binaries and libraries. If you frequently
280               use a debugger on programs or libraries, it may be helpful to
281               disable this option.
282
283           docs
284               Save doc directories. If you wish to delete doc directories,
285               specify !docs in the array.
286
287           libtool
288               Leave libtool (.la) files in packages. Specify !libtool to
289               remove them.
290
291           staticlibs
292               Leave static library (.a) files in packages. Specify
293               !staticlibs to remove them (if they have a shared counterpart).
294
295           emptydirs
296               Leave empty directories in packages.
297
298           zipman
299               Compress man and info pages with gzip.
300
301           upx
302               Compress binary executable files using UPX.
303
304           optipng
305               Optimize PNG images with optipng.
306
307           ccache
308               Allow the use of ccache during build. More useful in its
309               negative form !ccache with select packages that have problems
310               building with ccache.
311
312           distcc
313               Allow the use of distcc during build. More useful in its
314               negative form !distcc with select packages that have problems
315               building with distcc.
316
317           buildflags
318               Allow the use of user-specific buildflags (CPPFLAGS, CFLAGS,
319               CXXFLAGS, LDFLAGS) during build as specified in
320               makepkg.conf(5). More useful in its negative form !buildflags
321               with select packages that have problems building with custom
322               buildflags.
323
324           makeflags
325               Allow the use of user-specific makeflags during build as
326               specified in makepkg.conf(5). More useful in its negative form
327               !makeflags with select packages that have problems building
328               with custom makeflags such as -j2 (or higher).
329
330           debug
331               Add the user-specified debug flags (DEBUG_CFLAGS,
332               DEBUG_CXXFLAGS) to their counterpart buildflags as specified in
333               makepkg.conf(5). When used in combination with the ‘strip’
334               option, a separate package containing the debug symbols is
335               created.
336

PACKAGING FUNCTIONS

338       In addition to the above directives, PKGBUILDs require a set of
339       functions that provide instructions to build and install the package.
340       As a minimum, the PKGBUILD must contain a package() function which
341       installs all the package’s files into the packaging directory, with
342       optional prepare(), build(), and check() functions being used to create
343       those files from source.
344
345       package() Function
346           The package() function is used to install files into the directory
347           that will become the root directory of the built package and is run
348           after all the optional functions listed below. The packaging stage
349           is run using fakeroot to ensure correct file permissions in the
350           resulting package. All other functions will be run as the user
351           calling makepkg.
352
353       prepare() Function
354           An optional prepare() function can be specified in which operations
355           to prepare the sources for building, such as patching, are
356           performed. This function is run after the source extraction and
357           before the build() function. The prepare() function is skipped when
358           source extraction is skipped.
359
360       build() Function
361           The optional build() function is use to compile and/or adjust the
362           source files in preparation to be installed by the package()
363           function. This is directly sourced and executed by makepkg, so
364           anything that Bash or the system has available is available for use
365           here. Be sure any exotic commands used are covered by the
366           makedepends array.
367
368           If you create any variables of your own in the build() function, it
369           is recommended to use the Bash local keyword to scope the variable
370           to inside the build() function.
371
372       check() Function
373           An optional check() function can be specified in which a package’s
374           test-suite may be run. This function is run between the build() and
375           package() functions. Be sure any exotic commands used are covered
376           by the checkdepends array.
377
378       All of the above variables such as $pkgname and $pkgver are available
379       for use in the packaging functions. In addition, makepkg defines the
380       following variables:
381
382       srcdir
383           This contains the directory where makepkg extracts, or copies, all
384           source files.
385
386           All of the packaging functions defined above are run starting
387           inside $srcdir
388
389       pkgdir
390           This contains the directory where makepkg bundles the installed
391           package. This directory will become the root directory of your
392           built package. This variable should only be used in the package()
393           function.
394
395       startdir
396           This contains the absolute path to the directory where the PKGBUILD
397           is located, which is usually the output of $(pwd) when makepkg is
398           started. Use of this variable is deprecated and strongly
399           discouraged.
400

PACKAGE SPLITTING

402       makepkg supports building multiple packages from a single PKGBUILD.
403       This is achieved by assigning an array of package names to the pkgname
404       directive. Each split package uses a corresponding packaging function
405       with name package_foo(), where foo is the name of the split package.
406
407       All options and directives for the split packages default to the global
408       values given in the PKGBUILD. Nevertheless, the following ones can be
409       overridden within each split package’s packaging function: pkgdesc,
410       arch, url, license, groups, depends, optdepends, provides, conflicts,
411       replaces, backup, options, install, and changelog.
412
413       Note that makepkg does not consider split package depends when checking
414       if dependencies are installed before package building and with
415       --syncdeps. All packages required to make the package are required to
416       be specified in the global depends and makedepends arrays.
417
418       An optional global directive is available when building a split
419       package:
420
421       pkgbase
422           The name used to refer to the group of packages in the output of
423           makepkg and in the naming of source-only tarballs. If not
424           specified, the first element in the pkgname array is used. Valid
425           characters for this variable are alphanumerics, and any of the
426           following characters: “@ . _ + -”. Additionally, the variable is
427           not allowed to start with hyphens or dots.
428

INSTALL/UPGRADE/REMOVE SCRIPTING

430       Pacman has the ability to store and execute a package-specific script
431       when it installs, removes, or upgrades a package. This allows a package
432       to configure itself after installation and perform an opposite action
433       upon removal.
434
435       The exact time the script is run varies with each operation, and should
436       be self-explanatory. Note that during an upgrade operation, none of the
437       install or remove functions will be called.
438
439       Scripts are passed either one or two “full version strings”, where a
440       full version string is either pkgver-pkgrel or epoch:pkgver-pkgrel, if
441       epoch is non-zero.
442
443       pre_install
444           Run right before files are extracted. One argument is passed: new
445           package full version string.
446
447       post_install
448           Run right after files are extracted. One argument is passed: new
449           package full version string.
450
451       pre_upgrade
452           Run right before files are extracted. Two arguments are passed in
453           this order: new package full version string, old package full
454           version string.
455
456       post_upgrade
457           Run after files are extracted. Two arguments are passed in this
458           order: new package full version string, old package full version
459           string.
460
461       pre_remove
462           Run right before files are removed. One argument is passed: old
463           package full version string.
464
465       post_remove
466           Run right after files are removed. One argument is passed: old
467           package full version string.
468
469       To use this feature, create a file such as pkgname.install and put it
470       in the same directory as the PKGBUILD script. Then use the install
471       directive:
472
473           install=pkgname.install
474
475       The install script does not need to be specified in the source array. A
476       template install file is available in /usr/share/pacman as
477       proto.install for reference with all of the available functions
478       defined.
479

USING VCS SOURCES

481       Building a developmental version of a package using sources from a
482       version control system (VCS) is enabled by specifying the source in the
483       form source=('directory::url#fragment'). Currently makepkg supports the
484       Bazaar, Git, Subversion, and Mercurial version control systems. For
485       other version control systems, manual cloning of upstream repositories
486       must be done in the prepare() function.
487
488       The source URL is divided into three components:
489
490       directory
491           (optional) Specifies an alternate directory name for makepkg to
492           download the VCS source into.
493
494       url
495           The URL to the VCS repository. This must include the VCS in the URL
496           protocol for makepkg to recognize this as a VCS source. If the
497           protocol does not include the VCS name, it can be added by
498           prefixing the URL with vcs+. For example, using a Git repository
499           over HTTPS would have a source URL in the form: git+https://....
500
501       fragment
502           (optional) Allows specifying a revision number or branch for
503           makepkg to checkout from the VCS. For example, to checkout a given
504           revision, the source line would have the format
505           source=(url#revision=123). The available fragments depends on the
506           VCS being used:
507
508           bzr
509               revision (see 'bzr help revisionspec' for details)
510
511           git
512               branch, commit, tag
513
514           hg
515               branch, revision, tag
516
517           svn
518               revision
519

EXAMPLE

521       The following is an example PKGBUILD for the patch package. For more
522       examples, look through the build files of your distribution’s packages.
523       For those using Arch Linux, consult the Arch Build System (ABS) tree.
524
525           # Maintainer: Joe User <joe.user@example.com>
526
527           pkgname=patch
528           pkgver=2.7.1
529           pkgrel=1
530           pkgdesc="A utility to apply patch files to original sources"
531           arch=('i686' 'x86_64')
532           url="https://www.gnu.org/software/patch/patch.html"
533           license=('GPL')
534           groups=('base-devel')
535           depends=('glibc')
536           makedepends=('ed')
537           optdepends=('ed: for "patch -e" functionality')
538           source=("ftp://ftp.gnu.org/gnu/$pkgname/$pkgname-$pkgver.tar.xz"{,.sig})
539           md5sums=('e9ae5393426d3ad783a300a338c09b72'
540                    'SKIP')
541
542           build() {
543                   cd "$srcdir/$pkgname-$pkgver"
544                   ./configure --prefix=/usr
545                   make
546           }
547
548           package() {
549                   cd "$srcdir/$pkgname-$pkgver"
550                   make DESTDIR="$pkgdir/" install
551           }
552

SEE ALSO

554       makepkg(8), pacman(8), makepkg.conf(5)
555
556       See the pacman website at https://www.archlinux.org/pacman/ for current
557       information on pacman and its related tools.
558

BUGS

560       Bugs? You must be kidding; there are no bugs in this software. But if
561       we happen to be wrong, send us an email with as much detail as possible
562       to pacman-dev@archlinux.org.
563

AUTHORS

565       Current maintainers:
566
567       ·   Allan McRae <allan@archlinux.org>
568
569       ·   Andrew Gregory <andrew.gregory.8@gmail.com>
570
571       ·   Dan McGee <dan@archlinux.org>
572
573       ·   Dave Reisner <dreisner@archlinux.org>
574
575       Past major contributors:
576
577       ·   Judd Vinet <jvinet@zeroflux.org>
578
579       ·   Aurelien Foret <aurelien@archlinux.org>
580
581       ·   Aaron Griffin <aaron@archlinux.org>
582
583       ·   Xavier Chantry <shiningxc@gmail.com>
584
585       ·   Nagy Gabor <ngaba@bibl.u-szeged.hu>
586
587       For additional contributors, use git shortlog -s on the pacman.git
588       repository.
589
590
591
592Pacman 5.0.2                      2019-07-26                       PKGBUILD(5)
Impressum