1PKGBUILD(5) Pacman Manual PKGBUILD(5)
2
6 PKGBUILD - Arch Linux package build description file
7
9 PKGBUILD
10
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 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
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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 Only full fingerprints are accepted. They must be uppercase and
138 must not contain whitespace characters.
139 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 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 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 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 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 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 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 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 Additional architecture-specific depends can be added by appending
192 an underscore and the architecture name e.g., depends_x86_64=().
193 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 Additional architecture-specific makedepends can be added by
200 appending an underscore and the architecture name e.g.,
201 makedepends_x86_64=().
202 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 Additional architecture-specific checkdepends can be added by
210 appending an underscore and the architecture name e.g.,
211 checkdepends_x86_64=().
212 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 optdepends=('python: for library bindings')
221 Additional architecture-specific optdepends can be added by
223 appending an underscore and the architecture name e.g.,
224 optdepends_x86_64=().
225 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 Additional architecture-specific conflicts can be added by
233 appending an underscore and the architecture name e.g.,
234 conflicts_x86_64=().
235 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 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 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 Additional architecture-specific provides can be added by appending
254 an underscore and the architecture name e.g., provides_x86_64=().
255 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 Sysupgrade is currently the only pacman operation that utilizes
264 this field. A normal sync or upgrade will not use its value.
265 Additional architecture-specific replaces can be added by appending
267 an underscore and the architecture name e.g., replaces_x86_64=().
268 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 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 docs
284 Save doc directories. If you wish to delete doc directories,
285 specify !docs in the array.
286 libtool
288 Leave libtool (.la) files in packages. Specify !libtool to
289 remove them.
290 staticlibs
292 Leave static library (.a) files in packages. Specify
293 !staticlibs to remove them (if they have a shared counterpart).
294 emptydirs
296 Leave empty directories in packages.
297 zipman
299 Compress man and info pages with gzip.
300 upx
302 Compress binary executable files using UPX.
303 optipng
305 Optimize PNG images with optipng.
306 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 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 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 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 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
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 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 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 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 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 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 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 srcdir
383 This contains the directory where makepkg extracts, or copies, all
384 source files.
385 All of the packaging functions defined above are run starting
387 inside $srcdir
388 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 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
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 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 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 An optional global directive is available when building a split
419 package:
420 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
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 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 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 pre_install
444 Run right before files are extracted. One argument is passed: new
445 package full version string.
446 post_install
448 Run right after files are extracted. One argument is passed: new
449 package full version string.
450 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 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 pre_remove
462 Run right before files are removed. One argument is passed: old
463 package full version string.
464 post_remove
466 Run right after files are removed. One argument is passed: old
467 package full version string.
468 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 install=pkgname.install
474 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
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 The source URL is divided into three components:
489 directory
491 (optional) Specifies an alternate directory name for makepkg to
492 download the VCS source into.
493 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 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 bzr
509 revision (see 'bzr help revisionspec' for details)
510 git
512 branch, commit, tag
513 hg
515 branch, revision, tag
516 svn
518 revision
519
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 # Maintainer: Joe User <joe.user@example.com>
526 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 build() {
543 cd "$srcdir/$pkgname-$pkgver"
544 ./configure --prefix=/usr
545 make
546 }
547 package() {
549 cd "$srcdir/$pkgname-$pkgver"
550 make DESTDIR="$pkgdir/" install
551 }
552
554 makepkg(8), pacman(8), makepkg.conf(5)
555 See the pacman website at https://www.archlinux.org/pacman/ for current
557 information on pacman and its related tools.
558
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
565 Current maintainers:
566 · Allan McRae <allan@archlinux.org>
568 · Andrew Gregory <andrew.gregory.8@gmail.com>
570 · Dan McGee <dan@archlinux.org>
572 · Dave Reisner <dreisner@archlinux.org>
574 Past major contributors:
576 · Judd Vinet <jvinet@zeroflux.org>
578 · Aurelien Foret <aurelien@archlinux.org>
580 · Aaron Griffin <aaron@archlinux.org>
582 · Xavier Chantry <shiningxc@gmail.com>
584 · Nagy Gabor <ngaba@bibl.u-szeged.hu>
586 For additional contributors, use git shortlog -s on the pacman.git
588 repository.
589Pacman 5.0.2 2018-07-14 PKGBUILD(5)