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 an install
19           script. You can copy the provided PKGBUILD.proto file to a new
20           package build directory and make customizations to suit your needs.
21

OPTIONS AND DIRECTIVES

23       The following is a list of standard options and directives available
24       for use in a PKGBUILD. These are all understood and interpreted by
25       makepkg, and most of them will be directly transferred to the built
26       package. The mandatory fields for a minimally functional PKGBUILD are
27       pkgname, pkgver, pkgrel and arch.
28
29       If you need to create any custom variables for use in your build
30       process, it is recommended to prefix their name with an _ (underscore).
31       This will prevent any possible name clashes with internal makepkg
32       variables. For example, to store the base kernel version in a variable,
33       use something similar to $_basekernver.
34
35       pkgname (array)
36           Either the name of the package or an array of names for split
37           packages. Valid characters for members of this array are
38           alphanumerics, and any of the following characters: “@ . _ + -”.
39           Additionally, names are not allowed to start with hyphens or dots.
40
41       pkgver
42           The version of the software as released from the author (e.g.,
43           2.7.1). The variable is not allowed to contain colons, forward
44           slashes, hyphens or whitespace.
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 distribution. 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 a positive integer, with an
59           optional subrelease level specified by adding another positive
60           integer separated by a period (i.e. in the form x.y).
61
62       epoch
63           Used to force the package to be seen as newer than any previous
64           versions with a lower epoch, even if the version number would
65           normally not trigger such an upgrade. This value is required to be
66           a positive integer; the default value if left unspecified is 0.
67           This is useful when the version numbering scheme of a package
68           changes (or is alphanumeric), breaking normal version comparison
69           logic. See pacman(8) for more information on version comparisons.
70
71       pkgdesc
72           This should be a brief description of the package and its
73           functionality. Try to keep the description to one line of text and
74           to not use the package’s name.
75
76       url
77           This field contains a URL that is associated with the software
78           being packaged. This is typically the project’s web site.
79
80       license (array)
81           This field specifies the license(s) that apply to the package.
82           Commonly used licenses can be found in /usr/share/licenses/common.
83           If you see the package’s license there, simply reference it in the
84           license field (e.g., license=('GPL')). If the package provides a
85           license not available in /usr/share/licenses/common, then you
86           should include it in the package itself and set license=('custom')
87           or license=('custom:LicenseName'). The license should be placed in
88           $pkgdir/usr/share/licenses/$pkgname/ when building the package. If
89           multiple licenses are applicable, list all of them: license=('GPL'
90           'FDL').
91
92       install
93           Specifies a special install script that is to be included in the
94           package. This file should reside in the same directory as the
95           PKGBUILD and will be copied into the package by makepkg. It does
96           not need to be included in the source array (e.g.,
97           install=$pkgname.install).
98
99       changelog
100           Specifies a changelog file that is to be included in the package.
101           The changelog file should end in a single newline. This file should
102           reside in the same directory as the PKGBUILD and will be copied
103           into the package by makepkg. It does not need to be included in the
104           source array (e.g., changelog=$pkgname.changelog).
105
106       source (array)
107           An array of source files required to build the package. Source
108           files must either reside in the same directory as the PKGBUILD, or
109           be a fully-qualified URL that makepkg can use to download the file.
110           To simplify the maintenance of PKGBUILDs, use the $pkgname and
111           $pkgver variables when specifying the download location, if
112           possible. Compressed files will be extracted automatically unless
113           found in the noextract array described below.
114
115           Additional architecture-specific sources can be added by appending
116           an underscore and the architecture name e.g., source_x86_64=().
117           There must be a corresponding integrity array with checksums, e.g.
118           md5sums_x86_64=().
119
120           It is also possible to change the name of the downloaded file,
121           which is helpful with weird URLs and for handling multiple source
122           files with the same name. The syntax is: source=('filename::url').
123
124           makepkg also supports building developmental versions of packages
125           using sources downloaded from version control systems (VCS). For
126           more information, see Using VCS Sources below.
127
128           Files in the source array with extensions .sig, .sign or, .asc are
129           recognized by makepkg as PGP signatures and will be automatically
130           used to verify the integrity of the corresponding source file.
131
132       validpgpkeys (array)
133           An array of PGP fingerprints. If this array is non-empty, makepkg
134           will only accept signatures from the keys listed here and will
135           ignore the trust values from the keyring. If the source file was
136           signed with a subkey, makepkg will still use the primary key for
137           comparison.
138
139           Only full fingerprints are accepted. They must be uppercase and
140           must not contain whitespace characters.
141
142       noextract (array)
143           An array of file names corresponding to those from the source
144           array. Files listed here will not be extracted with the rest of the
145           source files. This is useful for packages that use compressed data
146           directly.
147
148       md5sums (array)
149           This array contains an MD5 hash for every source file specified in
150           the source array (in the same order). makepkg will use this to
151           verify source file integrity during subsequent builds. If SKIP is
152           put in the array in place of a normal hash, the integrity check for
153           that source file will be skipped. To easily generate md5sums, run
154           “makepkg -g >> PKGBUILD”. If desired, move the md5sums line to an
155           appropriate location.
156
157       sha1sums, sha224sums, sha256sums, sha384sums, sha512sums, b2sums
158       (arrays)
159           Alternative integrity checks that makepkg supports; these all
160           behave similar to the md5sums option described above. To enable use
161           and generation of these checksums, be sure to set up the
162           INTEGRITY_CHECK option in makepkg.conf(5).
163
164       groups (array)
165           An array of symbolic names that represent groups of packages,
166           allowing you to install multiple packages by requesting a single
167           target. For example, one could install all KDE packages by
168           installing the kde group.
169
170       arch (array)
171           Defines on which architectures the given package is available
172           (e.g., arch=('i686' 'x86_64')). Packages that contain no
173           architecture specific files should use arch=('any'). Valid
174           characters for members of this array are alphanumerics and “_”.
175
176       backup (array)
177           An array of file names, without preceding slashes, that should be
178           backed up if the package is removed or upgraded. This is commonly
179           used for packages placing configuration files in /etc. See
180           "Handling Config Files" in pacman(8) for more information.
181
182       depends (array)
183           An array of packages this package depends on to run. Entries in
184           this list should be surrounded with single quotes and contain at
185           least the package name. Entries can also include a version
186           requirement of the form name<>version, where <> is one of five
187           comparisons: >= (greater than or equal to), <= (less than or equal
188           to), = (equal to), > (greater than), or < (less than).
189
190           If the dependency name appears to be a library (ends with .so),
191           makepkg will try to find a binary that depends on the library in
192           the built package and append the version needed by the binary.
193           Appending the version yourself disables automatic detection.
194
195           Additional architecture-specific depends can be added by appending
196           an underscore and the architecture name e.g., depends_x86_64=().
197
198       makedepends (array)
199           An array of packages this package depends on to build but are not
200           needed at runtime. Packages in this list follow the same format as
201           depends.
202
203           Additional architecture-specific makedepends can be added by
204           appending an underscore and the architecture name e.g.,
205           makedepends_x86_64=().
206
207       checkdepends (array)
208           An array of packages this package depends on to run its test suite
209           but are not needed at runtime. Packages in this list follow the
210           same format as depends. These dependencies are only considered when
211           the check() function is present and is to be run by makepkg.
212
213           Additional architecture-specific checkdepends can be added by
214           appending an underscore and the architecture name e.g.,
215           checkdepends_x86_64=().
216
217       optdepends (array)
218           An array of packages (and accompanying reasons) that are not
219           essential for base functionality, but may be necessary to make full
220           use of the contents of this package. optdepends are currently for
221           informational purposes only and are not utilized by pacman during
222           dependency resolution. Packages in this list follow the same format
223           as depends, with an optional description appended. The format for
224           specifying optdepends descriptions is:
225
226               optdepends=('python: for library bindings')
227
228           Additional architecture-specific optdepends can be added by
229           appending an underscore and the architecture name e.g.,
230           optdepends_x86_64=().
231
232       conflicts (array)
233           An array of packages that will conflict with this package (i.e.
234           they cannot both be installed at the same time). This directive
235           follows the same format as depends. Versioned conflicts are
236           supported using the operators as described in depends.
237
238           Additional architecture-specific conflicts can be added by
239           appending an underscore and the architecture name e.g.,
240           conflicts_x86_64=().
241
242       provides (array)
243           An array of “virtual provisions” this package provides. This allows
244           a package to provide dependencies other than its own package name.
245           For example, the dcron package can provide cron, which allows
246           packages to depend on cron rather than dcron OR fcron.
247
248           Versioned provisions are also possible, in the name=version format.
249           For example, dcron can provide cron=2.0 to satisfy the cron>=2.0
250           dependency of other packages. Provisions involving the > and <
251           operators are invalid as only specific versions of a package may be
252           provided.
253
254           If the provision name appears to be a library (ends with .so),
255           makepkg will try to find the library in the built package and
256           append the correct version. Appending the version yourself disables
257           automatic detection.
258
259           Additional architecture-specific provides can be added by appending
260           an underscore and the architecture name e.g., provides_x86_64=().
261
262       replaces (array)
263           An array of packages this package should replace. This can be used
264           to handle renamed/combined packages. For example, if the j2re
265           package is renamed to jre, this directive allows future upgrades to
266           continue as expected even though the package has moved. Versioned
267           replaces are supported using the operators as described in depends.
268
269           Sysupgrade is currently the only pacman operation that utilizes
270           this field. A normal sync or upgrade will not use its value.
271
272           Additional architecture-specific replaces can be added by appending
273           an underscore and the architecture name e.g., replaces_x86_64=().
274
275       options (array)
276           This array allows you to override some of makepkg’s default
277           behavior when building packages. To set an option, just include the
278           option name in the options array. To reverse the default behavior,
279           place an “!” at the front of the option. Only specify the options
280           you specifically want to override, the rest will be taken from
281           makepkg.conf(5).  NOTE: force is a now-removed option in favor of
282           the top level epoch variable.
283
284           strip
285               Strip symbols from binaries and libraries. If you frequently
286               use a debugger on programs or libraries, it may be helpful to
287               disable this option.
288
289           docs
290               Save doc directories. If you wish to delete doc directories,
291               specify !docs in the array.
292
293           libtool
294               Leave libtool (.la) files in packages. Specify !libtool to
295               remove them.
296
297           staticlibs
298               Leave static library (.a) files in packages. Specify
299               !staticlibs to remove them (if they have a shared counterpart).
300
301           emptydirs
302               Leave empty directories in packages.
303
304           zipman
305               Compress man and info pages with gzip.
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       This is directly sourced and executed by makepkg, so anything that Bash
346       or the system has available is available for use here. Be sure any
347       exotic commands used are covered by the makedepends array.
348
349       If you create any variables of your own in any of these functions, it
350       is recommended to use the Bash local keyword to scope the variable to
351       inside the function.
352
353       package() Function
354           The package() function is used to install files into the directory
355           that will become the root directory of the built package and is run
356           after all the optional functions listed below. The packaging stage
357           is run using fakeroot to ensure correct file permissions in the
358           resulting package. All other functions will be run as the user
359           calling makepkg.
360
361       prepare() Function
362           An optional prepare() function can be specified in which operations
363           to prepare the sources for building, such as patching, are
364           performed. This function is run after the source extraction and
365           before the build() function. The prepare() function is skipped when
366           source extraction is skipped.
367
368       build() Function
369           The optional build() function is use to compile and/or adjust the
370           source files in preparation to be installed by the package()
371           function.
372
373       check() Function
374           An optional check() function can be specified in which a package’s
375           test-suite may be run. This function is run between the build() and
376           package() functions. Be sure any exotic commands used are covered
377           by the checkdepends array.
378
379       All of the above variables such as $pkgname and $pkgver are available
380       for use in the packaging functions. In addition, makepkg defines the
381       following variables:
382
383       srcdir
384           This contains the directory where makepkg extracts, or copies, all
385           source files.
386
387           All of the packaging functions defined above are run starting
388           inside $srcdir
389
390       pkgdir
391           This contains the directory where makepkg bundles the installed
392           package. This directory will become the root directory of your
393           built package. This variable should only be used in the package()
394           function.
395
396       startdir
397           This contains the absolute path to the directory where the PKGBUILD
398           is located, which is usually the output of $(pwd) when makepkg is
399           started. Use of this variable is deprecated and strongly
400           discouraged.
401

PACKAGE SPLITTING

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

INSTALL/UPGRADE/REMOVE SCRIPTING

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

USING VCS SOURCES

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

EXAMPLE

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

SEE ALSO

561       makepkg(8), pacman(8), makepkg.conf(5)
562
563       See the pacman website at https://www.archlinux.org/pacman/ for current
564       information on pacman and its related tools.
565

BUGS

567       Bugs? You must be kidding; there are no bugs in this software. But if
568       we happen to be wrong, submit a bug report with as much detail as
569       possible at the Arch Linux Bug Tracker in the Pacman section.
570

AUTHORS

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