Manual.md (90152B)
1# The XBPS source packages manual 2 3This article contains an exhaustive manual of how to create new source 4packages for XBPS, the `Void Linux` native packaging system. 5 6*Table of Contents* 7 8* [Introduction](#Introduction) 9 * [Quality Requirements](#quality_requirements) 10 * [Package build phases](#buildphase) 11 * [Package naming conventions](#namingconventions) 12 * [Libraries](#libs) 13 * [Language Modules](#language_modules) 14 * [Language Bindings](#language_bindings) 15 * [Programs](#programs) 16 * [Global functions](#global_funcs) 17 * [Global variables](#global_vars) 18 * [Available variables](#available_vars) 19 * [Mandatory variables](#mandatory_vars) 20 * [Optional variables](#optional_vars) 21 * [About the depends variables](#explain_depends) 22 * [Repositories](#repositories) 23 * [Repositories defined by Branch](#repo_by_branch) 24 * [Package defined repositories](#pkg_defined_repo) 25 * [Checking for new upstream releases](#updates) 26 * [Handling patches](#patches) 27 * [Build style scripts](#build_scripts) 28 * [Build helper scripts](#build_helper) 29 * [Functions](#functions) 30 * [Build options](#build_options) 31 * [Runtime dependencies](#deps_runtime) 32 * [INSTALL and REMOVE files](#install_remove_files) 33 * [INSTALL.msg and REMOVE.msg files](#install_remove_files_msg) 34 * [Creating system accounts/groups at runtime](#runtime_account_creation) 35 * [Writing runit services](#writing_runit_services) 36 * [32bit packages](#32bit_pkgs) 37 * [Subpackages](#pkgs_sub) 38 * [Development packages](#pkgs_development) 39 * [Data packages](#pkgs_data) 40 * [Documentation packages](#pkgs_documentation) 41 * [Python packages](#pkgs_python) 42 * [Go packages](#pkgs_go) 43 * [Haskell packages](#pkgs_haskell) 44 * [Font packages](#pkgs_font) 45 * [Removing a package](#pkg_remove) 46 * [XBPS Triggers](#xbps_triggers) 47 * [appstream-cache](#triggers_appstream_cache) 48 * [binfmts](#triggers_binfmts) 49 * [dkms](#triggers_dkms) 50 * [gconf-schemas](#triggers_gconf_schemas) 51 * [gdk-pixbuf-loaders](#triggers_gdk_pixbuf_loaders) 52 * [gio-modules](#triggers_gio_modules) 53 * [gettings-schemas](#triggers_gsettings_schemas) 54 * [gtk-icon-cache](#triggers_gtk_icon_cache) 55 * [gtk-immodules](#triggers_gtk_immodules) 56 * [gtk-pixbuf-loaders](#triggers_gtk_pixbuf_loaders) 57 * [gtk3-immodules](#triggers_gtk3_immodules) 58 * [hwdb.d-dir](#triggers_hwdb.d_dir) 59 * [info-files](#triggers_info_files) 60 * [kernel-hooks](#triggers_kernel_hooks) 61 * [mimedb](#triggers_mimedb) 62 * [mkdirs](#triggers_mkdirs) 63 * [pango-modules](#triggers_pango_module) 64 * [pycompile](#triggers_pycompile) 65 * [register-shell](#triggers_register_shell) 66 * [system-accounts](#triggers_system_accounts) 67 * [texmf-dist](#triggers_texmf_dist) 68 * [update-desktopdb](#triggers_update_desktopdb) 69 * [x11-fonts](#triggers_x11_fonts) 70 * [xml-catalog](#triggers_xml_catalog) 71 * [Void specific documentation](#documentation) 72 * [Notes](#notes) 73 * [Contributing via git](#contributing) 74* [Help](#help) 75 76<a id="Introduction"></a> 77## Introduction 78 79The `void-packages` repository contains all the 80recipes to download, compile and build binary packages for Void Linux. 81These `source` package files are called `templates`. 82 83The `template` files are shell scripts that define `variables` and `functions` 84to be processed by `xbps-src`, the package builder, to generate binary packages. 85The shell used by `xbps-src` is GNU bash; `xbps-src` doesn't aim to be 86compatible with POSIX `sh`. 87 88By convention, all templates start with a comment saying that it is a 89`template file` for a certain package. Most of the lines should be kept under 80 90columns; variables that list many values can be split into new lines, with the 91continuation in the next line indented by one space. 92 93A simple `template` example is as follows: 94 95``` 96# Template file for 'foo' 97pkgname=foo 98version=1.0 99revision=1 100build_style=gnu-configure 101short_desc="A short description max 72 chars" 102maintainer="name <email>" 103license="GPL-3.0-or-later" 104homepage="http://www.foo.org" 105distfiles="http://www.foo.org/foo-${version}.tar.gz" 106checksum="fea0a94d4b605894f3e2d5572e3f96e4413bcad3a085aae7367c2cf07908b2ff" 107``` 108 109The template file contains definitions to download, build and install the 110package files to a `fake destdir`, and after this a binary package can be 111generated with the definitions specified on it. 112 113Don't worry if anything is not clear as it should be. The reserved `variables` 114and `functions` will be explained later. This `template` file should be created 115in a directory matching `$pkgname`, Example: `void-packages/srcpkgs/foo/template`. 116 117If everything went fine after running 118 119 $ ./xbps-src pkg <pkgname> 120 121a binary package named `foo-1.0_1.<arch>.xbps` will be generated in the local repository 122`hostdir/binpkgs`. 123 124<a id="quality_requirements"></a> 125### Quality Requirements 126 127To be included in the Void repository, software must meet at least one 128of the following requirements. Exceptions to the list are possible, 129and might be accepted, but are extremely unlikely. If you believe you have an 130exception, start a PR and make an argument for why that particular piece of 131software, while not meeting any of the following requirements, is a good candidate for 132the Void packages system. 133 1341. System: The software should be installed system-wide, not per-user. 135 1361. Compiled: The software needs to be compiled before being used, even if it is 137 software that is not needed by the whole system. 138 1391. Required: Another package either within the repository or pending inclusion 140 requires the package. 141 142In particular, new themes are highly unlikely to be accepted. Simple shell 143scripts are unlikely to be accepted unless they provide considerable value to a 144broad user base. New fonts may be accepted if they provide value beyond 145aesthetics (e.g. they contain glyphs for a script missing in already packaged 146fonts). 147 148Browser forks, including those based on Chromium and Firefox, are generally not 149accepted. Such forks require heavy patching, maintenance and hours of build time. 150 151Software need to be used in version announced by authors as ready to use by 152the general public - usually called releases. Betas, arbitrary VCS revisions, 153templates using tip of development branch taken at build time and releases 154created by the package maintainer won't be accepted. 155 156<a id="buildphase"></a> 157### Package build phases 158 159Building a package consist of the following phases: 160 161- `setup` This phase prepares the environment for building a package. 162 163- `fetch` This phase downloads required sources for a `source package`, as defined by 164the `distfiles` variable or `do_fetch()` function. 165 166- `extract` This phase extracts the `distfiles` files into `$wrksrc` or executes the `do_extract()` 167function, which is the directory to be used to compile the `source package`. 168 169- `patch` This phase applies all patches in the patches directory of the package and 170can be used to perform other operations before configuring the package. 171 172- `configure` This phase executes the `configuration` of a `source package`, i.e `GNU configure scripts`. 173 174- `build` This phase compiles/prepares the `source files` via `make` or any other compatible method. 175 176- `check` This optional phase checks the result of the `build` phase by running the testsuite provided by the package. 177If the default `do_check` function provided by the build style doesn't do anything, the template should set 178`make_check_target` and/or `make_check_args` appropriately or define its own `do_check` function. If tests take too long 179or can't run in all environments, they should be run only if `XBPS_CHECK_PKGS` is `full`, which means they should either 180be under a `[ "$XBPS_CHECK_PKGS" = full ]` conditional (especially useful with custom `do_check`) or `make_check=extended` 181should be set in the template. 182 183- `install` This phase installs the `package files` into the package destdir `<masterdir>/destdir/<pkgname>-<version>`, 184via `make install` or any other compatible method. 185 186- `pkg` This phase builds the `binary packages` with files stored in the 187`package destdir` and registers them into the local repository. 188 189- `clean` This phase cleans up the package (if defined). 190 191`xbps-src` supports running just the specified phase, and if it ran 192successfully, the phase will be skipped later (unless its work directory 193`${wrksrc}` is removed with `xbps-src clean`). 194 195<a id="namingconventions"></a> 196### Package naming conventions 197 198<a id="libs"></a> 199#### Libraries 200 201Libraries are packages which provide shared objects (\*.so) in /usr/lib. 202They should be named like their upstream package name with the following 203exceptions: 204 205- The package is a subpackage of a front end application and provides 206shared objects used by the base package and other third party libraries. In that 207case it should be prefixed with 'lib'. An exception from that rule is: If an 208executable is only used for building that package, it moves to the -devel 209package. 210 211Example: wireshark -> subpkg libwireshark 212 213Libraries have to be split into two sub packages: `<name>` and `<name>-devel`. 214 215- `<name>` should only contain those parts of a package which are needed to run 216a linked program. 217 218- `<name>-devel` should contain all files which are needed to compile a package 219against this package. If the library is a sub package, its corresponding 220development package should be named `lib<name>-devel` 221 222<a id="language_modules"></a> 223#### Language Modules 224 225Language modules are extensions to script or compiled languages. Those packages 226do not provide any executables themselves, but can be used by other packages 227written in the same language. 228 229The naming convention to those packages is: 230 231``` 232<language>-<name> 233``` 234 235If a package provides both, a module and a executable, it should be split into 236a package providing the executable named `<name>` and the module named 237`<language>-<name>`. If a package starts with the languages name itself, the 238language prefix can be dropped. Short names for languages are no valid substitute 239for the language prefix. 240 241Example: python-pam, perl-URI, python3-pyside2 242 243<a id="language_bindings"></a> 244#### Language Bindings 245 246Language Bindings are packages which allow programs or libraries to have 247extensions or plugins written in a certain language. 248 249The naming convention to those packages is: 250``` 251<name>-<language> 252``` 253 254Example: gimp-python, irssi-perl 255 256<a id="programs"></a> 257#### Programs 258 259Programs put executables under /usr/bin (or in very special cases in other 260.../bin directories) 261 262For those packages the upstream packages name should be used. Remember that 263in contrast to many other distributions, void doesn't lowercase package names. 264As a rule of thumb, if the tar.gz of a package contains uppercase letter, then 265the package name should contain them too; if it doesn't, the package name 266is lowercase. 267 268Programs can be split into program packages and library packages. The program 269package should be named as described above. The library package should be 270prefixed with "lib" (see section `Libraries`) 271 272<a id="global_funcs"></a> 273### Global functions 274 275The following functions are defined by `xbps-src` and can be used on any template: 276 277- *vinstall()* `vinstall <file> <mode> <targetdir> [<name>]` 278 279 Installs `file` with the specified `mode` into `targetdir` in the pkg `$DESTDIR`. 280 The optional 4th argument can be used to change the `file name`. 281 282- *vcopy()* `vcopy <pattern> <targetdir>` 283 284 Copies recursively all files in `pattern` to `targetdir` in the pkg `$DESTDIR`. 285 286- *vmove()* `vmove <pattern>` 287 288 Moves `pattern` to the specified directory in the pkg `$DESTDIR`. 289 290- *vmkdir()* `vmkdir <directory> [<mode>]` 291 292 Creates a directory in the pkg `$DESTDIR`. The 2nd optional argument sets the mode of the directory. 293 294- *vbin()* `vbin <file> [<name>]` 295 296 Installs `file` into `usr/bin` in the pkg `$DESTDIR` with the 297 permissions 0755. The optional 2nd argument can be used to change 298 the `file name`. 299 300- *vman()* `vman <file> [<name>]` 301 302 Installs `file` as a man page. `vman()` parses the name and 303 determines the section as well as localization. Also transparently 304 converts gzipped (.gz) and bzipped (.bz2) manpages into plaintext. 305 Example mappings: 306 307 - `foo.1` -> `${DESTDIR}/usr/share/man/man1/foo.1` 308 - `foo.fr.1` -> `${DESTDIR}/usr/share/man/fr/man1/foo.1` 309 - `foo.1p` -> `${DESTDIR}/usr/share/man/man1/foo.1p` 310 - `foo.1.gz` -> `${DESTDIR}/usr/share/man/man1/foo.1` 311 - `foo.1.bz2` -> `${DESTDIR}/usr/share/man/man1/foo.1` 312 313- *vdoc()* `vdoc <file> [<name>]` 314 315 Installs `file` into `usr/share/doc/<pkgname>` in the pkg 316 `$DESTDIR`. The optional 2nd argument can be used to change the 317 `file name`. 318 319- *vconf()* `vconf <file> [<name>]` 320 321 Installs `file` into `etc` in the pkg 322 `$DESTDIR`. The optional 2nd argument can be used to change the 323 `file name`. 324 325- *vsconf()* `vsconf <file> [<name>]` 326 327 Installs `file` into `usr/share/examples/<pkgname>` in the pkg 328 `$DESTDIR`. The optional 2nd argument can be used to change the 329 `file name`. 330 331- <a id="vlicense"></a> 332 *vlicense()* `vlicense <file> [<name>]` 333 334 Installs `file` into `usr/share/licenses/<pkgname>` in the pkg 335 `$DESTDIR`. The optional 2nd argument can be used to change the 336 `file name`. See [license](#var_license) for when to use it. 337 338- *vsv()* `vsv <service>` 339 340 Installs `service` from `${FILESDIR}` to /etc/sv. The service must 341 be a directory containing at least a run script. Note the `supervise` 342 symlink will be created automatically by `vsv` and that the run script 343 is automatically made executable by this function. 344 For further information on how to create a new service directory see 345 [The corresponding section the FAQ](http://smarden.org/runit/faq.html#create). 346 347- *vsed()* `vsed -i <file> -e <regex>` 348 349 Wrapper around sed that checks sha256sum of a file before and after running 350 the sed command to detect cases in which the sed call didn't change anything. 351 Takes any arbitrary amount of files and regexes by calling `-i file` and 352 `-e regex` repeatedly, at least one file and one regex must be specified. 353 354 Note that vsed will call the sed command for every regex specified against 355 every file specified, in the order that they are given. 356 357- *vcompletion()* `<file> <shell> [<command>]` 358 359 Installs shell completion from `file` for `command`, in the correct location 360 and with the appropriate filename for `shell`. If `command` isn't specified, 361 it will default to `pkgname`. The `shell` argument can be one of `bash`, 362 `fish` or `zsh`. 363 364> Shell wildcards must be properly quoted, Example: `vmove "usr/lib/*.a"`. 365 366<a id="global_vars"></a> 367### Global variables 368 369The following variables are defined by `xbps-src` and can be used on any template: 370 371- `makejobs` Set to `-jX` if `XBPS_MAKEJOBS` is defined, to allow parallel jobs with `GNU make`. 372 373- `sourcepkg` Set to the to main package name, can be used to match the main package 374rather than additional binary package names. 375 376- `CHROOT_READY` Set if the target chroot (masterdir) is ready for chroot builds. 377 378- `CROSS_BUILD` Set if `xbps-src` is cross compiling a package. 379 380- `XBPS_CHECK_PKGS` Set if `xbps-src` is going to run tests for a package. 381Longer testsuites should only be run in `do_check()` if it is set to `full`. 382 383- `DESTDIR` Full path to the fake destdir used by the source pkg, set to 384`<masterdir>/destdir/${sourcepkg}-${version}`. 385 386- `FILESDIR` Full path to the `files` package directory, i.e `srcpkgs/foo/files`. 387The `files` directory can be used to store additional files to be installed 388as part of the source package. 389 390- `PKGDESTDIR` Full path to the fake destdir used by the `pkg_install()` function in 391`subpackages`, set to `<masterdir>/destdir/${pkgname}-${version}`. 392 393- `XBPS_BUILDDIR` Directory to store the `source code` of the source package being processed, 394set to `<masterdir>/builddir`. The package `wrksrc` is always stored 395in this directory such as `${XBPS_BUILDDIR}/${wrksrc}`. 396 397- `XBPS_MACHINE` The machine architecture as returned by `xbps-uhelper arch`. 398 399- `XBPS_ENDIAN` The machine's endianness ("le" or "be"). 400 401- `XBPS_LIBC` The machine's C library ("glibc" or "musl"). 402 403- `XBPS_WORDSIZE` The machine's word size in bits (32 or 64). 404 405- `XBPS_NO_ATOMIC8` The machine lacks native 64-bit atomics (needs libatomic emulation). 406 407- `XBPS_SRCDISTDIR` Full path to where the `source distfiles` are stored, i.e `$XBPS_HOSTDIR/sources`. 408 409- `XBPS_SRCPKGDIR` Full path to the `srcpkgs` directory. 410 411- `XBPS_TARGET_MACHINE` The target machine architecture when cross compiling a package. 412 413- `XBPS_TARGET_ENDIAN` The target machine's endianness ("le" or "be"). 414 415- `XBPS_TARGET_LIBC` The target machine's C library ("glibc" or "musl"). 416 417- `XBPS_TARGET_WORDSIZE` The target machine's word size in bits (32 or 64). 418 419- `XBPS_TARGET_NO_ATOMIC8` The target machine lacks native 64-bit atomics (needs libatomic emulation). 420 421- `XBPS_FETCH_CMD` The utility to fetch files from `ftp`, `http` of `https` servers. 422 423- `XBPS_WRAPPERDIR` Full path to where xbps-src's wrappers for utilities are stored. 424 425- `XBPS_CROSS_BASE` Full path to where cross-compile dependencies are installed, varies according to the target architecture triplet. i.e `aarch64` -> `aarch64-unknown-linux-gnu`. 426 427- `XBPS_RUST_TARGET` The target architecture triplet used by `rustc` and `cargo`. 428 429<a id="available_vars"></a> 430### Available variables 431 432<a id="mandatory_vars"></a> 433#### Mandatory variables 434 435The list of mandatory variables for a template: 436 437- `homepage` A string pointing to the `upstream` homepage. 438 439 440- <a id="var_license"></a> 441`license` A string matching the license's [SPDX Short identifier](https://spdx.org/licenses), 442`Public Domain`, or string prefixed with `custom:` for other licenses. 443Multiple licenses should be separated by commas, Example: `GPL-3.0-or-later, custom:Hugware`. 444 445 Empty meta-packages that don't include any files 446 which thus have and require no license, should have set 447 `license="BSD-2-Clause"`. 448 449 Note: `MIT`, `BSD`, `ISC` and custom licenses 450 require the license file to be supplied with the binary package. 451 452- `maintainer` A string in the form of `name <user@domain>`. The email for this field 453must be a valid email that you can be reached at. Packages using 454`users.noreply.github.com` emails will not be accepted. 455 456- `pkgname` A string with the package name, matching `srcpkgs/<pkgname>`. 457 458- `revision` A number that must be set to 1 when the `source package` is created, or 459updated to a new `upstream version`. This should only be increased when 460the generated `binary packages` have been modified. 461 462- `short_desc` A string with a brief description for this package. Max 72 chars. 463 464- `version` A string with the package version. Must not contain dashes or underscore 465and at least one digit is required. Using bash's pattern substitution and prefix and 466suffix matching isn't supported, since this field needs to be parsed by 467`xbps-checkvers(1)`. Using variables in this field should be avoided. 468 469Neither `pkgname` or `version` should contain special characters which make it 470necessary to quote them, so they shouldn't be quoted in the template. 471 472<a id="optional_vars"></a> 473#### Optional variables 474 475- `hostmakedepends` The list of `host` dependencies required to build the package, and 476that will be installed to the master directory. There is no need to specify a version 477because the current version in srcpkgs will always be required. 478Example: `hostmakedepends="foo blah"`. 479 480- `makedepends` The list of `target` dependencies required to build the package, and that 481will be installed to the master directory. There is no need to specify a version 482because the current version in srcpkgs will always be required. 483Example: `makedepends="foo blah"`. 484 485- `checkdepends` The list of dependencies required to run the package checks, i.e. 486the script or make rule specified in the template's `do_check()` function. 487Example: `checkdepends="gtest"`. 488 489- `depends` The list of dependencies required to run the package. These dependencies 490are not installed to the master directory, rather are only checked if a binary package 491in the local repository exists to satisfy the required version. Dependencies 492can be specified with the following version comparators: `<`, `>`, `<=`, `>=` 493or `foo-1.0_1` to match an exact version. If version comparator is not 494defined (just a package name), the version comparator is automatically set to `>=0`. 495Example: `depends="foo blah>=1.0"`. See the [Runtime dependencies](#deps_runtime) section 496for more information. 497 498- `bootstrap` If enabled the source package is considered to be part of the `bootstrap` 499process and required to be able to build packages in the chroot. Only a 500small number of packages must set this property. 501 502- `conflicts` An optional list of packages conflicting with this package. 503Conflicts can be specified with the following version comparators: `<`, `>`, `<=`, `>=` 504or `foo-1.0_1` to match an exact version. If version comparator is not 505defined (just a package name), the version comparator is automatically set to `>=0`. 506Example: `conflicts="foo blah>=0.42.3"`. 507 508- `distfiles` The full URL to the `upstream` source distribution files. Multiple files 509can be separated by whitespaces. The files must end in `.tar.lzma`, `.tar.xz`, 510`.txz`, `.tar.bz2`, `.tbz`, `.tar.gz`, `.tgz`, `.gz`, `.bz2`, `.tar` or 511`.zip`. To define a target filename, append `>filename` to the URL. 512Example: 513 distfiles="http://foo.org/foo-1.0.tar.gz http://foo.org/bar-1.0.tar.gz>bar.tar.gz" 514 515 To avoid repetition, several variables for common hosting sites 516 exist: 517 518 | Variable | Value | 519 |------------------|-------------------------------------------------| 520 | CPAN_SITE | https://cpan.perl.org/modules/by-module | 521 | DEBIAN_SITE | http://ftp.debian.org/debian/pool | 522 | FREEDESKTOP_SITE | https://freedesktop.org/software | 523 | GNOME_SITE | https://ftp.gnome.org/pub/GNOME/sources | 524 | GNU_SITE | https://ftp.gnu.org/gnu | 525 | KERNEL_SITE | https://www.kernel.org/pub/linux | 526 | MOZILLA_SITE | https://ftp.mozilla.org/pub | 527 | NONGNU_SITE | https://download.savannah.nongnu.org/releases | 528 | PYPI_SITE | https://files.pythonhosted.org/packages/source | 529 | SOURCEFORGE_SITE | https://downloads.sourceforge.net/sourceforge | 530 | UBUNTU_SITE | http://archive.ubuntu.com/ubuntu/pool | 531 | XORG_SITE | https://www.x.org/releases/individual | 532 | KDE_SITE | https://download.kde.org/stable | 533 534- `checksum` The `sha256` digests matching `${distfiles}`. Multiple files can be 535separated by blanks. Please note that the order must be the same than 536was used in `${distfiles}`. Example: `checksum="kkas00xjkjas"` 537 538If a distfile changes its checksum for every download because it is packaged 539on the fly on the server, like e.g. snapshot tarballs from any of the 540`https://*.googlesource.com/` sites, the checksum of the `archive contents` 541can be specified by prepending a commercial at (@). 542For tarballs you can find the contents checksum by using the command 543`tar xf <tarball.ext> --to-stdout | sha256sum`. 544 545- `wrksrc` The directory name where the package sources are extracted, by default 546set to `${pkgname}-${version}`. If the top level directory of a package's `distfile` is different from the default, `wrksrc` must be set to the top level directory name inside the archive. 547 548- `build_wrksrc` A directory relative to `${wrksrc}` that will be used when building the package. 549 550- `create_wrksrc` Enable it to create the `${wrksrc}` directory. Required if a package 551contains multiple `distfiles`. 552 553- `build_style` This specifies the `build method` for a package. Read below to know more 554about the available package `build methods` or effect of leaving this not set. 555 556- `build_helper` Whitespace-separated list of files in `common/build-helper` to be 557sourced and its variables be made available on the template. i.e. `build_helper="rust"`. 558 559- `configure_script` The name of the `configure` script to execute at the `configure` phase if 560`${build_style}` is set to `configure` or `gnu-configure` build methods. 561By default set to `./configure`. 562 563- `configure_args` The arguments to be passed in to the `configure` script if `${build_style}` 564is set to `configure` or `gnu-configure` build methods. By default, prefix 565must be set to `/usr`. In `gnu-configure` packages, some options are already 566set by default: `--prefix=/usr --sysconfdir=/etc --infodir=/usr/share/info --mandir=/usr/share/man --localstatedir=/var`. 567 568- `make_cmd` The executable to run at the `build` phase if `${build_style}` is set to 569`configure`, `gnu-configure` or `gnu-makefile` build methods. 570By default set to `make`. 571 572- `make_build_args` The arguments to be passed in to `${make_cmd}` at the build phase if 573`${build_style}` is set to `configure`, `gnu-configure` or `gnu-makefile` 574build methods. Unset by default. 575 576- `make_check_args` The arguments to be passed in to `${make_cmd}` at the check phase if 577`${build_style}` is set to `configure`, `gnu-configure` or `gnu-makefile` 578build methods. Unset by default. 579 580- `make_install_args` The arguments to be passed in to `${make_cmd}` at the `install-destdir` 581phase if `${build_style}` is set to `configure`, `gnu-configure` or 582`gnu-makefile` build methods. By default set to 583`PREFIX=/usr DESTDIR=${DESTDIR}`. 584 585- `make_build_target` The build target. If `${build_style}` is set to `configure`, `gnu-configure` 586or `gnu-makefile`, this is the target passed to `${make_cmd}` in the build phase; when unset, it 587defaults to `all`. If `${build_style}` is `python3-pep517`, this is the path of the package 588directory that should be built as a Python wheel; when unset, defaults to `.` (the current 589directory with respect to the build). 590 591- `make_check_target` The target to be passed in to `${make_cmd}` at the check phase if 592`${build_style}` is set to `configure`, `gnu-configure` or `gnu-makefile` 593build methods. By default set to `check`. 594 595- `make_install_target` The installation target. When `${build_style}` is set to `configure`, 596`gnu-configure` or `gnu-makefile`, this is the target passed to `${make_command}` in the install 597phase; when unset, it defaults to `install`. If `${build_style}` is `python-pep517`, this is the 598path of the Python wheel produced by the build phase that will be installed; when unset, the 599`python-pep517` build style will look for a wheel matching the package name and version in the 600current directory with respect to the install. 601 602- `patch_args` The arguments to be passed in to the `patch(1)` command when applying 603patches to the package sources during `do_patch()`. Patches are stored in 604`srcpkgs/<pkgname>/patches` and must be in `-p0` format. By default set to `-Np0`. 605 606- `disable_parallel_build` If set the package won't be built in parallel 607and `XBPS_MAKEJOBS` has no effect. 608 609- `make_check` Sets the cases in which the `check` phase is run. Can be `yes` (the default) to run if 610`XBPS_CHECK_PKGS` is set, `extended` to run if `XBPS_CHECK_PKGS` is `full` and `no` to never run. 611This option should usually be accompanied by a comment explaining why it was set, especially when 612set to `no`. 613 614- `keep_libtool_archives` If enabled the `GNU Libtool` archives won't be removed. By default those 615files are always removed automatically. 616 617- `skip_extraction` A list of filenames that should not be extracted in the `extract` phase. 618This must match the basename of any url defined in `${distfiles}`. 619Example: `skip_extraction="foo-${version}.tar.gz"`. 620 621- `nodebug` If enabled -dbg packages won't be generated even if `XBPS_DEBUG_PKGS` is set. 622 623- `conf_files` A list of configuration files the binary package owns; this expects full 624paths, wildcards will be extended, and multiple entries can be separated by blanks. 625Example: `conf_files="/etc/foo.conf /etc/foo2.conf /etc/foo/*.conf"`. 626 627- `mutable_files` A list of files the binary package owns, with the expectation 628 that those files will be changed. These act a lot like `conf_files` but 629 without the assumption that a human will edit them. 630 631- `make_dirs` A list of entries defining directories and permissions to be 632 created at install time. Each entry should be space separated, and will 633 itself contain spaces. `make_dirs="/dir 0750 user group"`. User and group and 634 mode are required on every line, even if they are `755 root root`. By 635 convention, there is only one entry of `dir perms user group` per line. 636 637- `repository` Defines the repository in which the package will be placed. See 638 *Repositories* for a list of valid repositories. 639 640- `nostrip` If set, the ELF binaries with debugging symbols won't be stripped. By 641default all binaries are stripped. 642 643- `nostrip_files` White-space separated list of ELF binaries that won't be stripped of 644debugging symbols. 645 646- `noshlibprovides` If set, the ELF binaries won't be inspected to collect the provided 647sonames in shared libraries. 648 649- `noverifyrdeps` If set, the ELF binaries and shared libaries won't be inspected to collect 650their reverse dependencies. You need to specify all dependencies in the `depends` when you 651need to set this. 652 653- `skiprdeps` White space separated list of filenames specified by their absolute path in 654the `$DESTDIR` which will not be scanned for runtime dependencies. This may be useful to 655skip files which are not meant to be run or loaded on the host but are to be sent to some 656target device or emulation. 657 658- `ignore_elf_files` White space separated list of machine code files 659in /usr/share directory specified by absolute path, which are expected and allowed. 660 661- `ignore_elf_dirs` White space separated list of directories in /usr/share directory 662specified by absolute path, which are expected and allowed to contain machine code files. 663 664- `nocross` If set, cross compilation won't be allowed and will exit immediately. 665This should be set to a string describing why it fails, or a link to a buildlog (from the official builders, CI buildlogs can vanish) demonstrating the failure. 666 667- `restricted` If set, xbps-src will refuse to build the package unless 668`etc/conf` has `XBPS_ALLOW_RESTRICTED=yes`. The primary builders for Void 669Linux do not have this setting, so the primary repositories will not have any 670restricted package. This is useful for packages where the license forbids 671redistribution. 672 673- `subpackages` A white space separated list of subpackages (matching `foo_package()`) 674to override the guessed list. Only use this if a specific order of subpackages is required, 675otherwise the default would work in most cases. 676 677- `broken` If set, building the package won't be allowed because its state is currently broken. 678This should be set to a string describing why it is broken, or a link to a buildlog demonstrating the failure. 679 680- `shlib_provides` A white space separated list of additional sonames the package provides on. 681This appends to the generated file rather than replacing it. 682 683- `shlib_requires` A white space separated list of additional sonames the package requires. 684This appends to the generated file rather than replacing it. 685 686- `nopie` Only needs to be set to something to make active, disables building the package with hardening 687 features (PIE, relro, etc). Not necessary for most packages. 688 689- `nopie_files` White-space seperated list of ELF binaries that won't be checked 690for PIE. 691 692- `reverts` xbps supports a unique feature which allows to downgrade from broken 693packages automatically. In the `reverts` field one can define a list of broken 694pkgver the resulting package should revert. This field *must* be defined before 695`version` and `revision` fields in order to work as expected. The versions 696defined in `reverts` must be bigger than the one defined in `version`. 697Example: 698 699 ``` 700 reverts="2.0_1 2.0_2" 701 version=1.9 702 revision=2 703 ``` 704 705- `alternatives` A white space separated list of supported alternatives the package provides. 706A list is composed of three components separated by a colon: group, symlink and target. 707Example: `alternatives="vi:/usr/bin/vi:/usr/bin/nvi ex:/usr/bin/ex:/usr/bin/nvi-ex"`. 708 709- `font_dirs` A white space separated list of directories specified by an absolute path where a 710font package installs its fonts. 711It is used in the `x11-fonts` xbps-trigger to rebuild the font cache during install/removal 712of the package. 713Example: `font_dirs="/usr/share/fonts/TTF /usr/share/fonts/X11/misc"` 714 715- `dkms_modules` A white space separated list of Dynamic Kernel Module Support (dkms) modules 716that will be installed and removed by the `dkms` xbps-trigger with the install/removal of the 717package. 718The format is a white space separated pair of strings that represent the name of the module, 719most of the time `pkgname`, and the version of the module, most of the time `version`. 720Example: `dkms_modules="$pkgname $version zfs 4.14"` 721 722- `register_shell` A white space separated list of shells defined by absolute path to be 723registered into the system shells database. It is used by the `register-shell` trigger. 724Example: `register_shell="/bin/tcsh /bin/csh"` 725 726- `tags` A white space separated list of tags (categories) that are registered into the 727package metadata and can be queried with `xbps-query` by users. 728Example for qutebrowser: `tags="browser chromium-based qt5 python3"` 729 730- `perl_configure_dirs` A white space separate list of directories relative to `wrksrc` 731that contain Makefile.PL files that need to be processes for the package to work. It is 732used in the perl-module build_style and has no use outside of it. 733Example: `perl_configure_dirs="blob/bob foo/blah"` 734 735- `preserve` If set, files owned by the package in the system are not removed when 736the package is updated, reinstalled or removed. This is mostly useful for kernel packages 737that shouldn't remove the kernel files when they are removed in case it might break the 738user's booting and module loading. Otherwise in the majority of cases it should not be 739used. 740 741- `fetch_cmd` Executable to be used to fetch URLs in `distfiles` during the `do_fetch` phase. 742 743- `archs` Whitespace separated list of architectures that a package can be 744built for, available architectures can be found under `common/cross-profiles`. 745In general, `archs` should only be set if the upstream software explicitly targets 746certain architectures or there is a compelling reason why the software should not be 747available on some supported architectures. 748Examples: 749 750 ``` 751 # Build package only for musl architectures 752 archs="*-musl" 753 # Build package for x86_64-musl and any non-musl architecture 754 archs="x86_64-musl ~*-musl" 755 # Default value (all arches) 756 archs="*" 757 ``` 758A special value `noarch` used to be available, but has since been removed. 759 760<a id="explain_depends"></a> 761#### About the many types of `depends` variables 762 763So far, we have listed four types of `depends` variables: `hostmakedepends`, 764`makedepends`, `checkdepends` and `depends`. These different kinds of variables 765are necessary because `xbps-src` supports cross compilation and to avoid 766installing unecessary packages in the build environment. 767 768During a build process, there are programs that must be _run_ on the host, such 769as `yacc` or the C compiler. The packages that contain these programs should be 770listed in `hostmakedepends`, and will be installed on the host when building the 771target package. Some of these packages are dependencies of the `base-chroot` 772package and don't need to be listed. It is possible that some of the programs 773necessary to build a project are located in `-devel` packages. 774 775The target package can also depend on other packages for libraries to link 776against or header files. These packages should be listed in `makedepends` and 777will match the target architecture, regardless of the architecture of the build 778machine. Typically, `makedepends` will contain mainly `-devel` packages. 779 780Furthermore, if `XBPS_CHECK_PKGS` is set or the `-Q` option is passed to 781`xbps-src`, the target package might require specific dependencies or libraries 782that are linked into its test binaries to run its test suite. These dependencies 783should be listed in `checkdepends` and will be installed as if they were part of 784`hostmakedepends`. Some dependencies that can be included in `checkdepends` are: 785 786- `dejagnu`: used for some GNU projects 787- `cmocka-devel`: linked into test binaries 788- `dbus`: makes it possible to run `dbus-run-session <test-command>` to provide 789 a D-Bus session for applications that need it 790- `git`: some test suites run the `git` command 791 792Lastly, a package may require certain dependencies at runtime, without which it 793is unusable. These dependencies, when they aren't detected automatically by 794XBPS, should be listed in `depends`. This is mostly relevant for Perl and Python 795modules and other programs that use `dlopen(3)` instead of dynamically linking. 796 797Finally, as a general rule, if a package is built the exact same way whether or 798not a particular package is present in `makedepends` or `hostmakedepends`, that 799package shouldn't be added as a build time dependency. 800 801<a id="repositories"></a> 802#### Repositories 803 804<a id="repo_by_branch"></a> 805##### Repositories defined by Branch 806 807The global repository takes the name of 808the current branch, except if the name of the branch is master. Then the resulting 809repository will be at the global scope. The usage scenario is that the user can 810update multiple packages in a second branch without polluting his local repository. 811 812<a id="pkg_defined_repo"></a> 813##### Package defined Repositories 814 815The second way to define a repository is by setting the `repository` variable in 816a template. This way the maintainer can define repositories for a specific 817package or a group of packages. This is currently used to distinguish between 818closed source packages, which are put in the `nonfree` repository and other 819packages which are at the root-repository. 820 821The following repository names are valid: 822 823* `nonfree`: Repository for closed source packages. 824 825<a id="updates"></a> 826### Checking for new upstream releases 827 828New upstream versions can be automatically checked using 829`./xbps-src update-check <pkgname>`. In some cases you need to override 830the sensible defaults by assigning the following variables in a `update` 831file in the same directory as the relevant `template` file: 832 833- `site` contains the URL where the version number is 834 mentioned. If unset, defaults to `homepage` and the directories where 835`distfiles` reside. 836 837- `pkgname` is the package name the default pattern checks for. 838If unset, defaults to `pkgname` from the template. 839 840- `pattern` is a perl-compatible regular expression 841matching the version number. Anchor the version number using `\K` 842and `(?=...)`. Example: `pattern='<b>\K[\d.]+(?=</b>)'`, this 843matches a version number enclosed in `<b>...</b>` tags. 844 845- `ignore` is a space-separated list of shell globs that match 846version numbers which are not taken into account for checking newer 847versions. Example: `ignore="*b*"` 848 849- `version` is the version number used to compare against 850upstream versions. Example: `version=${version//./_}` 851 852- `single_directory` can be set to disable 853detecting directory containing one version of sources in url, 854then searching new version in adjacent directories. 855 856- `vdprefix` is a perl-compatible regular expression matching 857part that precedes numeric part of version directory 858in url. Defaults to `(|v|$pkgname)[-_.]*`. 859 860- `vdsuffix` is a perl-compatible regular expression matching 861part that follows numeric part of version directory 862in url. Defaults to `(|\.x)`. 863 864<a id="patches"></a> 865### Handling patches 866 867Sometimes software needs to be patched, most commonly to fix bugs that have 868been found or to fix compilation with new software. 869 870To handle this, xbps-src has patching functionality. It will look for all files 871that match the glob `srcpkgs/$pkgname/patches/*.{diff,patch}` and will 872automatically apply all files it finds using `patch(1)` with `-Np0`. This happens 873during the `do_patch()` phase. The variable `PATCHESDIR` is 874available in the template, pointing to the `patches` directory. 875 876The patching behaviour can be changed in the following ways: 877 878- A file called `series` can be created in the `patches` directory with a newline 879separated list of patches to be applied in the order presented. When present 880xbps-src will only apply patches named in the `series` file. 881 882- A file with the same name as one of the patches but with `.args` as extension can 883be used to set the args passed to `patch(1)`. As an example, if `foo.patch` requires 884special arguments to be passed to `patch(1)` that can't be used when applying other 885patches, `foo.patch.args` can be created containing those args. 886 887<a id="build_scripts"></a> 888### build style scripts 889 890The `build_style` variable specifies the build method to build and install a 891package. It expects the name of any available script in the 892`void-packages/common/build-style` directory. Please note that required packages 893to execute a `build_style` script must be defined via `$hostmakedepends`. 894 895The current list of available `build_style` scripts is the following: 896 897- If `build_style` is not set, the template must (at least) define 898`do_install()` function and optionally more build phases such as 899`do_configure()`, `do_build()`, etc., and may overwrite default `do_fetch()` and 900`do_extract()` that fetch and extract files defined in `distfiles` variable. 901 902- `cargo` For packages written in rust that use Cargo for building. 903Configuration arguments (such as `--features`) can be defined in the variable 904`configure_args` and are passed to cargo during `do_build`. 905 906- `cmake` For packages that use the CMake build system, configuration arguments 907can be passed in via `configure_args`. The `cmake_builddir` variable may be 908defined to specify the directory for building under `build_wrksrc` instead of 909the default `build`. 910 911- `configure` For packages that use non-GNU configure scripts, at least `--prefix=/usr` 912should be passed in via `configure_args`. 913 914- `fetch` For packages that only fetch files and are installed as is via `do_install()`. 915 916- `gnu-configure` For packages that use GNU configure scripts, additional configuration 917arguments can be passed in via `configure_args`. 918 919- `gnu-makefile` For packages that use GNU make, build arguments can be passed in via 920`make_build_args` and install arguments via `make_install_args`. The build 921target can be overridden via `make_build_target` and the install target 922via `make_install_target`. This build style tries to compensate for makefiles 923that do not respect environment variables, so well written makefiles, those 924that do such things as append (`+=`) to variables, should have `make_use_env` 925set in the body of the template. 926 927- `go` For programs written in Go that follow the standard package 928structure. The variable `go_import_path` must be set to the package's 929import path, e.g. `github.com/github/hub` for the `hub` program. This 930information can be found in the `go.mod` file for modern Go projects. 931It's expected that the distfile contains the package, but dependencies 932will be downloaded with `go get`. 933 934- `meta` For `meta-packages`, i.e packages that only install local files or simply 935depend on additional packages. This build style does not install 936dependencies to the root directory, and only checks if a binary package is 937available in repositories. 938 939- `R-cran` For packages that are available on The Comprehensive R Archive 940Network (CRAN). The build style requires the `pkgname` to start with 941`R-cran-` and any dashes (`-`) in the CRAN-given version to be replaced 942with the character `r` in the `version` variable. The `distfiles` 943location will automatically be set as well as the package made to depend 944on `R`. 945 946- `gemspec` For packages that use 947[gemspec](https://guides.rubygems.org/specification-reference/) files for building a ruby 948gem and then installing it. The gem command can be overridden by `gem_cmd`. `configure_args` 949can be used to pass arguments during compilation. If your package does not make use of compiled 950extensions consider using the `gem` build style instead. 951 952- `gem` For packages that are installed using gems from [RubyGems](https://rubygems.org/). 953The gem command can be overridden by `gem_cmd`. 954`distfiles` is set by the build style if the template does not do so. If your gem 955provides extensions which must be compiled consider using the `gemspec` build style instead. 956 957- `ruby-module` For packages that are ruby modules and are installable via `ruby install.rb`. 958Additional install arguments can be specified via `make_install_args`. 959 960- `perl-ModuleBuild` For packages that use the Perl 961[Module::Build](https://metacpan.org/pod/Module::Build) method. 962 963- `perl-module` For packages that use the Perl 964[ExtUtils::MakeMaker](http://perldoc.perl.org/ExtUtils/MakeMaker.html) build method. 965 966- `raku-dist` For packages that use the Raku `raku-install-dist` build method with rakudo. 967 968- `waf3` For packages that use the Python3 `waf` build method with python3. 969 970- `waf` For packages that use the Python `waf` method with python2. 971 972- `slashpackage` For packages that use the /package hierarchy and package/compile to build, 973such as `daemontools` or any `djb` software. 974 975- `qmake` For packages that use Qt4/Qt5 qmake profiles (`*.pro`), qmake arguments 976for the configure phase can be passed in via `configure_args`, make build arguments can 977be passed in via `make_build_args` and install arguments via `make_install_args`. The build 978target can be overridden via `make_build_target` and the install target 979via `make_install_target`. 980 981- `meson` For packages that use the Meson Build system, configuration options can be passed 982via `configure_args`, the meson command can be overridden by `meson_cmd` and the location of 983the out of source build by `meson_builddir` 984 985- `void-cross` For cross-toolchain packages used to build Void systems. There are no 986mandatory variables (target triplet is inferred), but you can specify some optional 987ones - `cross_gcc_skip_go` can be specified to skip `gccgo`, individual subproject 988configure arguments can be specified via `cross_*_configure_args` where `*` is `binutils`, 989`gcc_bootstrap` (early gcc), `gcc` (final gcc), `glibc` (or `musl`), `configure_args` is 990additionally passed to both early and final `gcc`. You can also specify custom `CFLAGS` 991and `LDFLAGS` for the libc as `cross_(glibc|musl)_(cflags|ldflags)`. 992 993For packages that use the Python module build method (`setup.py` or 994[PEP 517](https://www.python.org/dev/peps/pep-0517/)), you can choose one of the following: 995 996- `python-module` to build *both* Python 2.x and 3.x modules 997 998- `python2-module` to build Python 2.x only modules 999 1000- `python3-module` to build Python 3.x only modules 1001 1002- `python3-pep517` to build Python 3.x only modules that provide a PEP 517 build description without 1003a `setup.py` script 1004 1005Environment variables for a specific `build_style` can be declared in a filename 1006matching the `build_style` name, Example: 1007 1008 `common/environment/build-style/gnu-configure.sh` 1009 1010- `texmf` For texmf zip/tarballs that need to go into /usr/share/texmf-dist. Includes 1011duplicates handling. 1012 1013<a id="build_helper"></a> 1014### build helper scripts 1015 1016The `build_helper` variable specifies shell snippets to be sourced that will create a 1017suitable environment for working with certain sets of packages. 1018 1019The current list of available `build_helper` scripts is the following: 1020 1021- `rust` specifies environment variables required for cross-compiling crates via cargo and 1022for compiling cargo -sys crates. 1023 1024- `gir` specifies dependencies for native and cross builds to deal with 1025GObject Introspection. The following variables may be set in the template to handle 1026cross builds which require additional hinting or exhibit problems. `GIR_EXTRA_LIBS_PATH` defines 1027additional paths to be searched when linking target binaries to be introspected. 1028`GIR_EXTRA_OPTIONS` defines additional options for the `g-ir-scanner-qemuwrapper` calling 1029`qemu-<target_arch>-static` when running the target binary. You can for example specify 1030`GIR_EXTRA_OPTIONS="-strace"` to see a trace of what happens when running that binary. 1031 1032- `qemu` sets additional variables for the `cmake` and `meson` build styles to allow 1033executing cross-compiled binaries inside qemu. 1034It sets `CMAKE_CROSSCOMPILING_EMULATOR` for cmake and `exe_wrapper` for meson 1035to `qemu-<target_arch>-static` and `QEMU_LD_PREFIX` to `XBPS_CROSS_BASE`. 1036It also creates the `vtargetrun` function to wrap commands in a call to 1037`qemu-<target_arch>-static` for the target architecture. 1038 1039- `qmake` creates the `qt.conf` configuration file (cf. `qmake` `build_style`) 1040needed for cross builds and a qmake-wrapper to make `qmake` use this configuration. 1041This aims to fix cross-builds for when the build-style is mixed: e.g. when in a 1042`gnu-configure` style the configure script calls `qmake` or a `Makefile` in 1043`gnu-makefile` style, respectively. 1044 1045- `cmake-wxWidgets-gtk3` sets the `WX_CONFIG` variable which is used by FindwxWidgets.cmake 1046 1047<a id="functions"></a> 1048### Functions 1049 1050The following functions can be defined to change the behavior of how the 1051package is downloaded, compiled and installed. 1052 1053- `pre_fetch()` Actions to execute before `do_fetch()`. 1054 1055- `do_fetch()` if defined and `distfiles` is not set, use it to fetch the required sources. 1056 1057- `post_fetch()` Actions to execute after `do_fetch()`. 1058 1059- `pre_extract()` Actions to execute after `post_fetch()`. 1060 1061- `do_extract()` if defined and `distfiles` is not set, use it to extract the required sources. 1062 1063- `post_extract()` Actions to execute after `do_extract()`. 1064 1065- `pre_patch()` Actions to execute after `post_extract()`. 1066 1067- `do_patch()` if defined use it to prepare the build environment and run hooks to apply patches. 1068 1069- `post_patch()` Actions to execute after `do_patch()`. 1070 1071- `pre_configure()` Actions to execute after `post_patch()`. 1072 1073- `do_configure()` Actions to execute to configure the package; `${configure_args}` should 1074still be passed in if it's a GNU configure script. 1075 1076- `post_configure()` Actions to execute after `do_configure()`. 1077 1078- `pre_build()` Actions to execute after `post_configure()`. 1079 1080- `do_build()` Actions to execute to build the package. 1081 1082- `post_build()` Actions to execute after `do_build()`. 1083 1084- `pre_install()` Actions to execute after `post_build()`. 1085 1086- `do_install()` Actions to execute to install the package files into the `fake destdir`. 1087 1088- `post_install()` Actions to execute after `do_install()`. 1089 1090- `do_clean()` Actions to execute to clean up after a successful package phase. 1091 1092> A function defined in a template has preference over the same function 1093defined by a `build_style` script. 1094 1095Current working directory for functions is set as follows: 1096 1097- For pre_fetch, pre_extract, do_clean: `<masterdir>`. 1098 1099- For do_fetch, post_fetch: `XBPS_BUILDDIR`. 1100 1101- For do_extract, post_extract, pre_patch, do_patch, post_patch: `wrksrc`. 1102 1103- For pre_configure through post_install: `build_wrksrc` 1104if it is defined, otherwise `wrksrc`. 1105 1106<a id="build_options"></a> 1107### Build options 1108 1109Some packages might be built with different build options to enable/disable 1110additional features; The XBPS source packages collection allows you to do this with some simple tweaks 1111to the `template` file. 1112 1113The following variables may be set to allow package build options: 1114 1115- `build_options` Sets the build options supported by the source package. 1116 1117- `build_options_default` Sets the default build options to be used by the source package. 1118 1119- `desc_option_<option>` Sets the description for the build option `option`. This must match the 1120keyword set in *build_options*. Note that if the build option is generic enough, its description 1121should be added to `common/options.description` instead. 1122 1123After defining those required variables, you can check for the 1124`build_option_<option>` variable to know if it has been set and adapt the source 1125package accordingly. Additionally, the following functions are available: 1126 1127- *vopt_if()* `vopt_if <option> <if_true> [<if_false>]` 1128 1129 Outputs `if_true` if `option` is set, or `if_false` if it isn't set. 1130 1131- *vopt_with()* `vopt_with <option> [<flag>]` 1132 1133 Outputs `--with-<flag>` if the option is set, or `--without-<flag>` 1134 otherwise. If `flag` isn't set, it defaults to `option`. 1135 1136 Examples: 1137 1138 - `vopt_with dbus` 1139 - `vopt_with xml xml2` 1140 1141- *vopt_enable()* `vopt_enable <option> [<flag>]` 1142 1143 Same as `vopt_with`, but uses `--enable-<flag>` and 1144 `--disable-<flag>` respectively. 1145 1146- *vopt_conflict()* `vopt_conflict <option 1> <option 2>` 1147 1148 Emits an error and exits if both options are set at the same time. 1149 1150- *vopt_bool()* `vopt_bool <option> <property>` 1151 1152 Outputs `-D<property>=true` if the option is set, or 1153 `-D<property>=false` otherwise. 1154 1155The following example shows how to change a source package that uses GNU 1156configure to enable a new build option to support PNG images: 1157 1158``` 1159# Template file for 'foo' 1160pkgname=foo 1161version=1.0 1162revision=1 1163build_style=gnu-configure 1164configure_args="... $(vopt_with png)" 1165makedepends="... $(vopt_if png libpng-devel)" 1166... 1167 1168# Package build options 1169build_options="png" 1170desc_option_png="Enable support for PNG images" 1171 1172# To build the package by default with the `png` option: 1173# 1174# build_options_default="png" 1175 1176... 1177 1178``` 1179 1180The supported build options for a source package can be shown with `xbps-src`: 1181 1182 $ ./xbps-src show-options foo 1183 1184Build options can be enabled with the `-o` flag of `xbps-src`: 1185 1186 $ ./xbps-src -o option,option1 <cmd> foo 1187 1188Build options can be disabled by prefixing them with `~`: 1189 1190 $ ./xbps-src -o ~option,~option1 <cmd> foo 1191 1192Both ways can be used together to enable and/or disable multiple options 1193at the same time with `xbps-src`: 1194 1195 $ ./xbps-src -o option,~option1,~option2 <cmd> foo 1196 1197The build options can also be shown for binary packages via `xbps-query(8)`: 1198 1199 $ xbps-query -R --property=build-options foo 1200 1201Permanent global package build options can be set via `XBPS_PKG_OPTIONS` variable in the 1202`etc/conf` configuration file. Per package build options can be set via 1203`XBPS_PKG_OPTIONS_<pkgname>`. 1204 1205> NOTE: if `pkgname` contains `dashes`, those should be replaced by `underscores` 1206Example: `XBPS_PKG_OPTIONS_xorg_server=opt`. 1207 1208The list of supported package build options and its description is defined in the 1209`common/options.description` file. 1210 1211<a id="deps_runtime"></a> 1212#### Runtime dependencies 1213 1214Dependencies for ELF objects are detected automatically by `xbps-src`, hence runtime 1215dependencies must not be specified in templates via `$depends` with the following exceptions: 1216 1217- ELF objects using dlopen(3). 1218- non ELF objects, i.e perl/python/ruby/etc modules. 1219- Overriding the minimal version specified in the `shlibs` file. 1220 1221The runtime dependencies for ELF objects are detected by checking which SONAMEs 1222they require and then the SONAMEs are mapped to a binary package name with a minimal 1223required version. The `shlibs` file in the `void-packages/common` directory 1224sets up the `<SONAME> <pkgname>>=<version>` mappings. 1225 1226For example the `foo-1.0_1` package provides the `libfoo.so.1` SONAME and 1227software requiring this library will link to `libfoo`; the resulting binary 1228package will have a run-time dependency to `foo>=1.0_1` package as specified in 1229`common/shlibs`: 1230 1231``` 1232# common/shlibs 1233... 1234libfoo.so.1 foo-1.0_1 1235... 1236``` 1237 1238- The first field specifies the SONAME. 1239- The second field specified the package name and minimal version required. 1240- A third optional field (usually set to `ignore`) can be used to skip checks in soname bumps. 1241 1242Dependencies declared via `${depends}` are not installed to the master directory, rather are 1243only checked if they exist as binary packages, and are built automatically by `xbps-src` if 1244the specified version is not in the local repository. 1245 1246As a special case, `virtual` dependencies may be specified as runtime dependencies in the 1247`${depends}` template variable. Several different packages can provide common functionality by 1248declaring a virtual name and version in the `${provides}` template variable (e.g., 1249`provides="vpkg-0.1_1"`). Packages that rely on the common functionality without concern for the 1250specific provider can declare a dependency on the virtual package name with the prefix `virtual?` 1251(e.g., `depends="virtual?vpkg-0.1_1"`). When a package is built by `xbps-src`, providers for any 1252virtual packages will be confirmed to exist and will be built if necessary. A map from virtual 1253packages to their default providers is defined in `etc/default.virtual`. Individual mappings can be 1254overridden by local preferences in `etc/virtual`. Comments in `etc/default.virtual` provide more 1255information on this map. 1256 1257<a id="install_remove_files"></a> 1258### INSTALL and REMOVE files 1259 1260The INSTALL and REMOVE shell snippets can be used to execute certain actions at a specified 1261stage when a binary package is installed, updated or removed. There are some variables 1262that are always set by `xbps` when the scripts are executed: 1263 1264- `$ACTION`: to conditionalize its actions: `pre` or `post`. 1265- `$PKGNAME`: the package name. 1266- `$VERSION`: the package version. 1267- `$UPDATE`: set to `yes` if package is being upgraded, `no` if package is being `installed` or `removed`. 1268- `$CONF_FILE`: full path to `xbps.conf`. 1269- `$ARCH`: the target architecture it is running on. 1270 1271An example of how an `INSTALL` or `REMOVE` script shall be created is shown below: 1272 1273``` 1274# INSTALL 1275case "$ACTION" in 1276pre) 1277 # Actions to execute before the package files are unpacked. 1278 ... 1279 ;; 1280post) 1281 if [ "$UPDATE" = "yes" ]; then 1282 # actions to execute if package is being updated. 1283 ... 1284 else 1285 # actions to execute if package is being installed. 1286 ... 1287 fi 1288 ;; 1289esac 1290``` 1291 1292subpackages can also have their own `INSTALL` and `REMOVE` files, simply create them 1293as `srcpkgs/<pkgname>/<subpkg>.INSTALL` or `srcpkgs/<pkgname>/<subpkg>.REMOVE` respectively. 1294 1295> NOTE: always use paths relative to the current working directory, otherwise if the scripts cannot 1296be executed via `chroot(2)` won't work correctly. 1297 1298> NOTE: do not use INSTALL/REMOVE scripts to print messages, see the next section for 1299more information. 1300 1301<a id="install_remove_files_msg"></a> 1302### INSTALL.msg and REMOVE.msg files 1303 1304The `INSTALL.msg` and `REMOVE.msg` files can be used to print a message at post-install 1305or pre-remove time, respectively. 1306 1307Ideally those files should not exceed 80 chars per line. 1308 1309subpackages can also have their own `INSTALL.msg` and `REMOVE.msg` files, simply create them 1310as `srcpkgs/<pkgname>/<subpkg>.INSTALL.msg` or `srcpkgs/<pkgname>/<subpkg>.REMOVE.msg` respectively. 1311 1312<a id="runtime_account_creation"></a> 1313### Creating system accounts/groups at runtime 1314 1315There's a trigger along with some variables that are specifically to create 1316**system users and groups** when the binary package is being configured. 1317The following variables can be used for this purpose: 1318 1319- `system_groups` This specifies the names of the new *system groups* to be created, separated 1320by blanks. Optionally the **gid** can be specified by delimiting it with a 1321colon, i.e `system_groups="_mygroup:78"` or `system_groups="_foo _blah:8000"`. 1322 1323- `system_accounts` This specifies the names of the new **system users/groups** to be created, 1324separated by blanks, i.e `system_accounts="_foo _blah:22"`. Optionally the **uid** and **gid** 1325can be specified by delimiting it with a colon, i.e `system_accounts="_foo:48"`. 1326Additional variables for the **system accounts** can be specified to change its behavior: 1327 1328 - `<account>_homedir` the home directory for the user. If unset defaults to `/var/empty`. 1329 - `<account>_shell` the shell for the new user. If unset defaults to `/sbin/nologin`. 1330 - `<account>_descr` the description for the new user. If unset defaults to `<account> unprivileged user`. 1331 - `<account>_groups` additional groups to be added to for the new user. 1332 - `<account>_pgroup` to set the primary group, by default primary group is set to `<account>`. 1333 1334The **system user** is created by using a dynamically allocated **uid/gid** in your system 1335and it's created as a `system account`, unless the **uid** is set. A new group will be created for the 1336specified `system account` and used exclusively for this purpose. 1337 1338System accounts and groups must be prefixed with an underscore to prevent clashing with names of user 1339accounts. 1340 1341> NOTE: The underscore policy does not apply to old packages, due to the inevitable breakage of 1342> changing the username only new packages should follow it. 1343 1344<a id="writing_runit_services"></a> 1345### Writing runit services 1346 1347Void Linux uses [runit](http://smarden.org/runit/) for booting and supervision of services. 1348 1349Most information about how to write them can be found in their 1350[FAQ](http://smarden.org/runit/faq.html#create). The following are guidelines specific to 1351Void Linux on how to write services. 1352 1353If the service daemon supports CLI flags, consider adding support for changing it via the 1354`OPTS` variable by reading a file called `conf` in the same directory as the daemon. 1355 1356```sh 1357#!/bin/sh 1358[ -r conf ] && . ./conf 1359exec daemon ${OPTS:- --flag-enabled-by-default} 1360``` 1361 1362If the service requires the creation of a directory under `/run` or its link `/var/run` 1363for storing runtime information (like Pidfiles) write it into the service file. It 1364is advised to use `install` if you need to create it with specific permissions instead 1365of `mkdir -p`. 1366 1367```sh 1368#!/bin/sh 1369install -d -m0700 /run/foo 1370exec foo 1371``` 1372 1373```sh 1374#!/bin/sh 1375install -d -m0700 -o bar -g bar /run/bar 1376exec bar 1377``` 1378 1379If the service requires directories in parts of the system that are not generally in 1380temporary filesystems. Then use the `make_dirs` variable in the template to create 1381those directories when the package is installed. 1382 1383<a id="32bit_pkgs"></a> 1384### 32bit packages 1385 138632bit packages are built automatically when the builder is x86 (32bit), but 1387there are some variables that can change the behavior: 1388 1389- `lib32depends` If this variable is set, dependencies listed here will be used rather than 1390those detected automatically by `xbps-src` and **depends**. Please note that 1391dependencies must be specified with version comparators, Example: 1392`lib32depends="foo>=0 blah<2.0"`. 1393 1394- `lib32disabled` If this variable is set, no 32bit package will be built. 1395 1396- `lib32files` Additional files to be added to the **32bit** package. This expect absolute 1397paths separated by blanks, Example: `lib32files="/usr/bin/blah /usr/include/blah."`. 1398 1399- `lib32symlinks` Makes a symlink of the target filename stored in the `lib32` directory. 1400This expects the basename of the target file, Example: `lib32symlinks="foo"`. 1401 1402- `lib32mode` If unset, only shared/static libraries and pkg-config files will be copied to the 1403**32bit** package. If set to `full` all files will be copied to the 32bit package, unmodified. 1404 1405<a id="pkgs_sub"></a> 1406### Subpackages 1407 1408In the example shown above just a binary package is generated, but with some 1409simple tweaks multiple binary packages can be generated from a single 1410template/build, this is called `subpackages`. 1411 1412To create additional `subpackages` the `template` must define a new function 1413with this naming: `<subpkgname>_package()`, Example: 1414 1415``` 1416# Template file for 'foo' 1417pkgname=foo 1418version=1.0 1419revision=1 1420build_style=gnu-configure 1421short_desc="A short description max 72 chars" 1422maintainer="name <email>" 1423license="GPL-3.0-or-later" 1424homepage="http://www.foo.org" 1425distfiles="http://www.foo.org/foo-${version}.tar.gz" 1426checksum="fea0a94d4b605894f3e2d5572e3f96e4413bcad3a085aae7367c2cf07908b2ff" 1427 1428# foo-devel is a subpkg 1429foo-devel_package() { 1430 short_desc+=" - development files" 1431 depends="${sourcepkg}>=${version}_${revision}" 1432 pkg_install() { 1433 vmove usr/include 1434 vmove "usr/lib/*.a" 1435 vmove "usr/lib/*.so" 1436 vmove usr/lib/pkgconfig 1437 } 1438} 1439``` 1440 1441All subpackages need an additional symlink to the `main` pkg, otherwise dependencies 1442requiring those packages won't find its `template` Example: 1443 1444``` 1445 /srcpkgs 1446 |- foo <- directory (main pkg) 1447 | |- template 1448 |- foo-devel <- symlink to `foo` 1449``` 1450 1451The main package should specify all required `build dependencies` to be able to build 1452all subpackages defined in the template. 1453 1454An important point of `subpackages` is that they are processed after the main 1455package has run its `install` phase. The `pkg_install()` function specified on them 1456commonly is used to move files from the `main` package destdir to the `subpackage` destdir. 1457 1458The helper functions `vinstall`, `vmkdir`, `vcopy` and `vmove` are just wrappers that simplify 1459the process of creating, copying and moving files/directories between the `main` package 1460destdir (`$DESTDIR`) to the `subpackage` destdir (`$PKGDESTDIR`). 1461 1462Subpackages are processed always in alphabetical order; To force a custom order, 1463the `subpackages` variable can be declared with the wanted order. 1464 1465<a id="pkgs_development"></a> 1466### Development packages 1467 1468A development package, commonly generated as a subpackage, shall only contain 1469files required for development, that is, headers, static libraries, shared 1470library symlinks, pkg-config files, API documentation or any other script 1471that is only useful when developing for the target software. 1472 1473A development package should depend on packages that are required to link 1474against the provided shared libraries, i.e if `libfoo` provides the 1475`libfoo.so.2` shared library and the linking needs `-lbar`, the package 1476providing the `libbar` shared library should be added as a dependency; 1477and most likely it shall depend on its development package. 1478 1479If a development package provides a `pkg-config` file, you should verify 1480what dependencies the package needs for dynamic or static linking, and add 1481the appropriate `development` packages as dependencies. 1482 1483Development packages for the C and C++ languages usually `vmove` the 1484following subset of files from the main package: 1485 1486* Header files `usr/include` 1487* Static libraries `usr/lib/*.a` 1488* Shared library symbolic links `usr/lib/*.so` 1489* Cmake rules `usr/lib/cmake` `usr/share/cmake` 1490* Package config files `usr/lib/pkgconfig` `usr/share/pkgconfig` 1491* Autoconf macros `usr/share/aclocal` 1492* Gobject introspection XML files `usr/share/gir-1.0` 1493* Vala bindings `usr/share/vala` 1494 1495<a id="pkgs_data"></a> 1496### Data packages 1497 1498Another common subpackage type is the `-data` subpackage. This subpackage 1499type used to split architecture independent, big(ger) or huge amounts 1500of data from a package's main and architecture dependent part. It is up 1501to you to decide, if a `-data` subpackage makes sense for your package. 1502This type is common for games (graphics, sound and music), part libraries (CAD) 1503or card material (maps). 1504The main package must then have `depends="${pkgname}-data-${version}_${revision}"`, 1505possibly in addition to other, non-automatic depends. 1506 1507<a id="pkgs_documentation"></a> 1508### Documentation packages 1509 1510Packages intended for user interaction do not always unconditionally require 1511their documentation part. A user who does not want to e.g. develop 1512with Qt5 will not need to install the (huge) qt5-doc package. 1513An expert may not need it or opt to use an online version. 1514 1515In general a `-doc` package is useful, if the main package can be used both with 1516or without documentation and the size of the documentation isn't really small. 1517The base package and the `-devel` subpackage should be kept small so that when 1518building packages depending on a specific package there is no need to install large 1519amounts of documentation for no reason. Thus the size of the documentation part should 1520be your guidance to decide whether or not to split off a `-doc` subpackage. 1521 1522<a id="pkgs_python"></a> 1523### Python packages 1524 1525Python packages should be built with the `python{,2,3}-module` build style, if possible. 1526This sets some environment variables required to allow cross compilation. Support to allow 1527building a python module for multiple versions from a single template is also possible. 1528The `python3-pep517` build style provides means to build python packages that provide a build-system 1529definition compliant with [PEP 517](https://www.python.org/dev/peps/pep-0517/) without a traditional 1530`setup.py` script. 1531 1532Python packages that rely on `python3-setuptools` should generally map `setup_requires` 1533dependencies in `setup.py` to `hostmakedepends` in the template and `install_requires` 1534dependencies to `depends` in the template; include `python3` in `depends` if there are no other 1535python dependencies. If the package includes a compiled extension, the `python3-devel` packages 1536should be added to `makedepends`, as should any python packages that also provide native libraries 1537against which the extension will be linked (even if that package is also included in 1538`hostmakedepends` to satisfy `setuptools`). 1539 1540**NB**: Python `setuptools` will attempt to use `pip` or `EasyInstall` to fetch any missing 1541dependencies at build time. If you notice warnings about `EasyInstall` deprecation or python eggs 1542present in `${wrksrc}/.eggs` after building the package, then those packages should be added to 1543`hostmakedepends`. 1544 1545The following variables may influence how the python packages are built and configured 1546at post-install time: 1547 1548- `pycompile_module`: By default, files and directories installed into 1549`usr/lib/pythonX.X/site-packages`, excluding `*-info` and `*.so`, are byte-compiled 1550at install time as python modules. This variable expects subset of them that 1551should be byte-compiled, if default is wrong. Multiple python modules may be specified separated 1552by blanks, Example: `pycompile_module="foo blah"`. If a python module installs a file into 1553`site-packages` rather than a directory, use the name of the file, Example: 1554`pycompile_module="fnord.py"`. 1555 1556- `pycompile_dirs`: this variable expects the python directories that should be `byte-compiled` 1557recursively by the target python version. This differs from `pycompile_module` in that any 1558path may be specified, Example: `pycompile_dirs="usr/share/foo"`. 1559 1560- `python_version`: this variable expects the supported Python major version. 1561By default it's set to `2`. This variable is needed for multi-language 1562applications (e.g., the application is written in C while the command is 1563written in Python) or just single Python file ones that live in `/usr/bin`. 1564 1565> NOTE: you need to define it *only* for non-Python modules. 1566 1567Also, a set of useful variables are defined to use in the templates: 1568 1569| Variable | Value | 1570|-------------|----------------------------------| 1571| py2_ver | 2.X | 1572| py2_lib | usr/lib/python2.X | 1573| py2_sitelib | usr/lib/python2.X/site-packages | 1574| py2_inc | usr/include/python2.X | 1575| py3_ver | 3.X | 1576| py3_lib | usr/lib/python3.X | 1577| py3_sitelib | usr/lib/python3.X/site-packages | 1578| py3_inc | usr/include/python3.Xm | 1579 1580> NOTE: it's expected that additional subpkgs must be generated to allow packaging for multiple 1581python versions. 1582 1583<a id="pkgs_go"></a> 1584### Go packages 1585 1586Go packages should be built with the `go` build style, if possible. 1587The `go` build style takes care of downloading Go dependencies and 1588setting up cross compilation. 1589 1590The following template variables influence how Go packages are built: 1591 1592- `go_import_path`: The import path of the package included in the 1593 distfile, as it would be used with `go get`. For example, GitHub's 1594 `hub` program has the import path `github.com/github/hub`. This 1595 variable is required. 1596- `go_package`: A space-separated list of import paths of the packages 1597 that should be built. Defaults to `go_import_path`. 1598- `go_build_tags`: An optional, space-separated list of build tags to 1599 pass to Go. 1600- `go_mod_mode`: The module download mode to use. May be `off` to ignore 1601 any go.mod files, `default` to use Go's default behavior, or anything 1602 accepted by `go build -mod MODE`. Defaults to `vendor` if there's 1603 a vendor directory, otherwise `default`. 1604 1605The following environment variables influence how Go packages are built: 1606 1607- `XBPS_MAKEJOBS`: Value passed to the `-p` flag of `go install`, to 1608 control the parallelism of the Go compiler. 1609 1610Occasionally it is necessary to perform operations from within the Go 1611source tree. This is usually needed by programs using go-bindata or 1612otherwise preping some assets. If possible do this in pre_build(). 1613The path to the package's source inside `$GOPATH` is available as 1614`$GOSRCPATH`. 1615 1616<a id="pkgs_haskell"></a> 1617### Haskell packages 1618 1619We build Haskell package using `stack` from 1620[Stackage](http://www.stackage.org/), generally the LTS versions. 1621Haskell templates need to have host dependencies on `ghc` and `stack`, 1622and set build style to `haskell-stack`. 1623 1624The following variables influence how Haskell packages are built: 1625 1626- `stackage`: The Stackage version used to build the package, e.g. 1627 `lts-3.5`. Alternatively: 1628 - You can prepare a `stack.yaml` configuration for the project and put it 1629 into `files/stack.yaml`. 1630 - If a `stack.yaml` file is present in the source files, it will be used 1631- `make_build_args`: This is passed as-is to `stack build ...`, so 1632 you can add your `--flag ...` parameters there. 1633 1634<a id="pkgs_font"></a> 1635### Font packages 1636 1637Font packages are very straightforward to write, they are always set with the 1638following variables: 1639 1640- `depends="font-util"`: because they are required for regenerating the font 1641cache during the install/removal of the package 1642- `font_dirs`: which should be set to the directory where the package 1643installs its fonts 1644 1645<a id="pkg_remove"></a> 1646### Removing a package 1647 1648Follows a list of things that should be done to help guarantee that a 1649package template removal and by extension its binary packages from 1650Void Linux's repositories goes smoothly. 1651 1652Before removing a package template: 1653 1654- Guarantee that no package depends on it or any of its subpackages. 1655For that you can search the templates for references to the package 1656with `grep -r '\bpkg\b' srcpkgs/`. 1657- Guarantee that no package depends on shlibs provided by it. 1658 1659When removing the package template: 1660 1661- Remove all symlinks that point to the package. 1662`find srcpkgs/ -lname <pkg>` should be enough. 1663- If the package provides shlibs make sure to remove them from 1664common/shlibs. 1665- Some packages use patches and files from other packages using symlinks, 1666generally those packages are the same but have been split as to avoid 1667cyclic dependencies. Make sure that the package you're removing is not 1668the source of those patches/files. 1669- Remove package template. 1670- Add `pkgname<=version_revision` to `replaces` variable of `removed-packages` 1671template. All removed subpkgs should be added too. 1672This will uninstall package from systems where it is installed. 1673- Remove the package from the repository index 1674or contact a team member that can do so. 1675 1676<a id="xbps_triggers"></a> 1677### XBPS Triggers 1678 1679XBPS triggers are a collection of snippets of code, provided by the `xbps-triggers` 1680package, that are added to the INSTALL/REMOVE scripts of packages either manually 1681by setting the `triggers` variable in the template, or automatically, when specific 1682conditions are met. 1683 1684The following is a list of all available triggers, their current status, what each 1685of them does and what conditions need to be for it to be included automatically on a 1686package. 1687 1688This is not a complete overview of the package. It is recommended to read the variables 1689referenced and the triggers themselves. 1690 1691<a id="triggers_appstream_cache"></a> 1692#### appstream-cache 1693 1694The appstream-cache trigger is responsible for rebuilding the appstream metadata cache. 1695 1696During installation it executes `appstreamcli refresh-cache --verbose --force --datapath 1697$APPSTREAM_PATHS --cachepath var/cache/app-info/gv`. By default APPSTREAM_PATHS are all the 1698paths that appstreamcli will look into for metadata files. 1699 1700The directories searched by appstreamcli are: 1701 1702- `usr/share/appdata` 1703- `usr/share/app-info` 1704- `var/lib/app-info` 1705- `var/cache/app-info` 1706 1707During removal of the `AppStream` package it will remove the `var/cache/app-info/gv` 1708directory. 1709 1710It is automatically added to packages that have XML files under one of the directories 1711searched by appstreamcli. 1712 1713<a id="triggers_binfmts"></a> 1714#### binfmts 1715 1716The binfmts trigger is responsible for registration and removal of arbitrary 1717executable binary formats, know as binfmts. 1718 1719During installation/removal it uses `update-binfmts` from the `binfmt-support` package 1720to register/remove entries from the arbitrary executable binary formats database. 1721 1722To include the trigger use the `binfmts` variable, as the trigger won't do anything unless 1723it is defined. 1724 1725<a id="triggers_dkms"></a> 1726#### dkms 1727 1728The dkms trigger is responsible for compiling and removing dynamic kernel modules of a 1729package. 1730 1731During installation the trigger compiles and installs the dynamic module for all `linux` 1732packages that have their corresponding linux-headers package installed. During removal 1733the corresponding module will be removed 1734 1735To include the trigger use the `dkms_modules` variable, as the trigger won't do anything 1736unless it is defined. 1737 1738<a id="triggers_gconf_schemas"></a> 1739#### gconf-schemas 1740 1741The gconf-schemas trigger is responsible for registering and removing .schemas and 1742.entries files into the schemas database directory 1743 1744During installation it uses `gconftool-2` to install .schemas and .entries files into 1745`usr/share/gconf/schemas`. During removal it uses `gconftool-2` to remove the entries 1746and schemas belonging to the package that is being removed from the database. 1747 1748To include it add `gconf-schemas` to `triggers` and add the appropriate .schemas in 1749the `gconf_schemas` variable and .entries in `gconf_entries`. 1750 1751It is automatically added to packages that have `/usr/share/gconf/schemas` present 1752as a directory. All files with the schemas file extension under that directory 1753are passed to the trigger. 1754 1755<a id="triggers_gdk_pixbuf_loaders"></a> 1756#### gdk-pixbuf-loaders 1757 1758The gdk-pixbuf-loaders trigger is responsible for maintaining the GDK Pixbuf loaders cache. 1759 1760During installation it runs `gdk-pixbuf-query-loaders --update-cache` and also deletes 1761the obsolete `etc/gtk-2.0/gdk-pixbuf.loaders` file if present. During removal of the 1762gdk-pixbuf package it removes the cache file if present. Normally at 1763`usr/lib/gdk-pixbuf-2.0/2.10.0/loaders.cache`. 1764 1765It can be added by defining `gdk-pixbuf-loaders` in the `triggers` variable. It is also 1766added automatically to any package that has the path `usr/lib/gdk-pixbuf-2.0/2.10.0/loaders` 1767available as a directory. 1768 1769<a id="triggers_gio_modules"></a> 1770#### gio-modules 1771 1772The gio-modules trigger is responsible for updating the Glib GIO module cache with 1773`gio-querymodules` from the `glib` package 1774 1775During install and removal it just runs `gio-querymodules` to update the cache file 1776present under `usr/lib/gio/modules`. 1777 1778It is automatically added to packages that have `/usr/lib/gio/modules` present 1779as a directory. 1780 1781<a id="triggers_gsettings_schemas"></a> 1782#### gsettings-schemas 1783 1784The gsettings-schemas trigger is responsible for compiling Glib's GSettings XML 1785schema files during installation and removing the compiled files during removal. 1786 1787During installation it uses `glib-compile-schemas` from `glib` to compile the 1788schemas into files with the suffix .compiled into `/usr/share/glib-2.0/schemas`. 1789 1790During removal of the glib package it deletes all files inside 1791`/usr/share/glib-2.0/schemas` that end with .compiled. 1792 1793It is automatically added to packages that have `/usr/share/glib-2.0/schemas` present 1794as a directory. 1795 1796<a id="triggers_gtk_icon_cache"></a> 1797#### gtk-icon-cache 1798 1799The gtk-icon-cache trigger is responsible for updating the gtk+ icon cache. 1800 1801During installation it uses `gtk-update-icon-cache` to update the icon cache. 1802 1803During removal of the gtk+ package it deletes the `icon-theme.cache` file 1804in the directories defined by the variable `gtk_iconcache_dirs`. 1805 1806It is automatically added on packages that have `/usr/share/icons` available 1807as a directory, all directories under that directory have their absolute path 1808passed to the trigger. 1809 1810<a id="triggers_gtk_immodules"></a> 1811#### gtk-immodules 1812 1813The gtk-immodules trigger is responsible for updating the IM (Input Method) modules 1814file for gtk+. 1815 1816During installation it uses `gtk-query-immodules-2.0 --update-cache` to update the 1817cache file. It also removes the obsolete configuration file `etc/gtk-2.0/gtk.immodules` 1818if present. 1819 1820During removal of the `gtk+` package it removes the cache file which is located at 1821`usr/lib/gtk-2.0/2.10.0/immodules.cache`. 1822 1823It is automatically added to packages that have `/usr/lib/gtk-2.0/2.10.0/immodules` 1824present as a directory. 1825 1826<a id="triggers_gtk_pixbuf_loaders"></a> 1827#### gtk-pixbuf-loaders 1828 1829gtk-pixbuf-loaders is the old name for the current `gdk-pixbuf-loaders` trigger and is 1830in the process of being removed. It currently re-execs into `gdk-pixbuf-loaders` as a 1831compatibility measure. 1832 1833For information about how it works refer to [gdk-pixbuf-loaders](#triggers_gdk_pixbuf_loaders). 1834 1835<a id="triggers_gtk3_immodules"></a> 1836#### gtk3-immodules 1837 1838The gtk3-immodules trigger is responsible for updating the IM (Input Method) modules 1839file for gtk+3. 1840 1841During installation it executes `gtk-query-immodules-3.0 --update-cache` to update the 1842cache file. It also removes the obsolete configuration file `etc/gtk-3.0/gtk.immodules` 1843if present. 1844 1845During removal of the `gtk+3` package it removes the cache file which is located at 1846`usr/lib/gtk-3.0/3.0.0/immodules.cache`. 1847 1848It is automatically added to packages that have `/usr/lib/gtk-3.0/3.0.0/immodules` 1849present as a directory. 1850 1851<a id="triggers_hwdb.d_dir"></a> 1852#### hwdb.d-dir 1853 1854The hwdb.d-dir trigger is responsible for updating the hardware database. 1855 1856During installation and removal it runs `usr/bin/udevadm hwdb --root=. --update`. 1857 1858It is automatically added to packages that have `/usr/lib/udev/hwdb.d` present 1859as a directory. 1860 1861<a id="triggers_info_files"></a> 1862#### info-files 1863 1864The info-files trigger is responsible for registering and unregistering the GNU info 1865files of a package. 1866 1867It checks the existence of the info files presented to it and if it is running under 1868another architecture. 1869 1870During installation it uses `install-info` to register info files into 1871`usr/share/info`. 1872 1873During removal it uses `install-info --delete` to remove the info files from the 1874registry located at `usr/share/info`. 1875 1876If it is running under another architecture it tries to use the host's `install-info` 1877utility. 1878 1879<a id="triggers_kernel_hooks"></a> 1880#### kernel-hooks 1881 1882The kernel-hooks trigger is responsible for running scripts during installation/removal 1883of kernel packages. 1884 1885The available targets are pre-install, pre-remove, post-install and post-remove. 1886 1887When run it will try to run all executables found under `etc/kernel.d/$TARGET`. The 1888`TARGET` variable is one of the 4 targets available for the trigger. It will also 1889create the directory if it isn't present. 1890 1891During updates it won't try to run any executables when running with the pre-remove 1892target. 1893 1894It is automatically added if the helper variable `kernel_hooks_version` is defined. 1895However it is not obligatory to have it defined. 1896 1897<a id="triggers_mimedb"></a> 1898#### mimedb 1899 1900The mimedb trigger is responsible for updating the shared-mime-info database. 1901 1902In all runs it will just execute `update-mime-database -n usr/share/mime`. 1903 1904It is automatically added to packages that have `/usr/share/mime` available as 1905a directory. 1906 1907<a id="triggers_mkdirs"></a> 1908#### mkdirs 1909 1910The mkdirs trigger is responsible for creating and removing directories dictated 1911by the `make_dirs` variable. 1912 1913During installation it takes the `make_dirs` variable and splits it into groups of 19144 variables. 1915 1916- dir = full path to the directory 1917- mode = Unix permissions for the directory 1918- uid = name of the owning user 1919- gid = name of the owning group 1920 1921It will continue to split the values of `make_dirs` into groups of 4 until the values 1922end. 1923 1924During installation it will create a directory with `dir` then set mode with `mode` 1925and permission with `uid:gid`. 1926 1927During removal it will delete the directory using `rmdir`. 1928 1929To include this trigger use the `make_dirs` variable, as the trigger won't do anything 1930unless it is defined. 1931 1932<a id="triggers_pango_module"></a> 1933#### pango-modules 1934 1935The pango-modules trigger is currently being removed since upstream has removed the 1936code responsible for it. 1937 1938It used to update the pango modules file with `pango-modulesquery` during installation 1939of any package. 1940 1941Currently it removes `etc/pango/pango.modules` file during removal of the pango package. 1942 1943It can be added by defining `pango-modules` in the `triggers` variable and has no way to get 1944added automatically to a package. 1945 1946<a id="triggers_pycompile"></a> 1947#### pycompile 1948 1949The pycompile trigger is responsible for compiling python code into native 1950bytecode and removing generated bytecode. 1951 1952During installation it will compile all python code under the paths it is given by 1953`pycompile_dirs` and all modules described in `pycompile_module` into native bytecode and 1954update the ldconfig(8) cache. 1955 1956During removal it will remove all the native bytecode and update the ldconfig(8) cache. 1957 1958To include this trigger use the variables `pycompile_dirs` and `pycompile_module`. The 1959trigger won't do anything unless at least one of those variables is defined. 1960 1961A `python_version` variable can be set to direct behaviour of the trigger. 1962 1963<a id="triggers_register_shell"></a> 1964#### register-shell 1965 1966The register-shell trigger is responsible for registering and removing shell entries 1967into `etc/shells`. 1968 1969During installation it will append the `etc/shells` file with the new shell and also 1970change the permissions to `644` on the file. 1971 1972During removal it will use `sed` to delete the shell from the file. 1973 1974To include this trigger use the `register_shell` variable, as the trigger won't do 1975anything unless it is defined. 1976 1977<a id="triggers_system_accounts"></a> 1978#### system-accounts 1979 1980The system-accounts trigger is responsible for creating and disabling system accounts 1981and groups. 1982 1983During removal it will disable the account by setting the Shell to /bin/false, 1984Home to /var/empty, and appending ' - for uninstalled package $pkgname' to the 1985Description. 1986Example: `transmission unprivileged user - for uninstalled package transmission` 1987 1988This trigger can only be used by using the `system_accounts` variable. 1989 1990<a id="triggers_texmf_dist"></a> 1991#### texmf-dist 1992 1993The texmf-dist trigger is responsible for regenerating TeXLive's texmf databases. 1994 1995During both installation and removal, it regenerates both the texhash and format 1996databases using `texhash` and `fmtutil-sys`, to add or remove any new hashes or 1997formats. 1998 1999It runs on every package that changes /usr/share/texmf-dist. This is likely overkill, 2000but it is much cleaner rather than checking each format directory and each directory 2001that is hashed. In addition, it is very likely any package touching /usr/share/texmf-dist 2002requires one of these triggers anyway. 2003 2004<a id="triggers_update_desktopdb"></a> 2005#### update-desktopdb 2006 2007The update-desktopdb trigger is responsible for updating the system's MIME database. 2008 2009During installation it will execute `update-desktop-database usr/share/applications` 2010which will result in a cache file being created at `usr/share/applications/mimeinfo.cache`. 2011 2012During removal of the `desktop-file-utils` package it will remove the cache file that 2013was created during installation. 2014 2015It is automatically added to packages that have `/usr/share/applications` available as 2016a directory. 2017 2018<a id="triggers_x11_fonts"></a> 2019#### x11-fonts 2020 2021The x11-fonts trigger is responsible for rebuilding the fonts.dir and fonts.scale files 2022for packages that install X11 fonts, and update fontconfig's cache for these fonts. 2023 2024During installation and removal it executes `mkfontdir`, `mkfontscale` and `fc-cache` for 2025all font directories it was given via the `font_dirs` variable. 2026 2027To include this trigger use the `font_dirs` variable, as the trigger won't do anything 2028unless it is defined. 2029 2030<a id="triggers_xml_catalog"></a> 2031#### xml-catalog 2032 2033The xml-catalog trigger is responsible for registering and removing SGML/XML catalog entries. 2034 2035During installation it uses `xmlcatmgr` to register all catalogs, passed to it by the 2036`sgml_entries` and `xml_entries` variables, in `usr/share/sgml/catalog` and 2037`usr/share/xml/catalog` respectively. 2038 2039During removal it uses `xmlcatmgr` to remove all catalogs passed to it by the 2040`sgml_entries` and `xml_entries` variables, in `usr/share/sgml/catalog` and 2041`usr/share/xml/catalog` respectively. 2042 2043To include this trigger use the `sgml_entries` variable or/and the `xml_entries` variable, 2044as the trigger won't do anything unless either of them are defined. 2045 2046<a id="documentation"></a> 2047### Void specific documentation 2048 2049When you want document details of package's configuration and usage specific to Void Linux, 2050not covered by upstream documentation, put notes into 2051`srcpkgs/<pkgname>/files/README.voidlinux` and install with 2052`vdoc "${FILESDIR}/README.voidlinux"`. 2053 2054<a id="notes"></a> 2055### Notes 2056 2057- Make sure that all software is configured to use the `/usr` prefix. 2058 2059- Binaries should always be installed at `/usr/bin`. 2060 2061- Manual pages should always be installed at `/usr/share/man`. 2062 2063- If a software provides **shared libraries** and headers, probably you should 2064create a `development package` that contains `headers`, `static libraries` 2065and other files required for development (not required at runtime). 2066 2067- If you are updating a package please be careful with SONAME bumps, check 2068the installed files (`./xbps-src show-files pkg`) before pushing new updates. 2069 2070- Make sure that binaries are not stripped by the software, let xbps-src do this; 2071otherwise the `debug` packages won't have debugging symbols. 2072 2073<a id="contributing"></a> 2074### Contributing via git 2075 2076To get started, [fork](https://help.github.com/articles/fork-a-repo) the void-linux `void-packages` git repository on GitHub and clone it: 2077 2078 $ git clone git@github.com:<user>/void-packages.git 2079 2080See [CONTRIBUTING.md](./CONTRIBUTING.md) for information on how to format your 2081commits and other tips for contributing. 2082 2083Once you've made changes to your `forked` repository, submit 2084a github pull request. 2085 2086To keep your forked repository always up to date, setup the `upstream` remote 2087to pull in new changes: 2088 2089 $ git remote add upstream git://github.com/void-linux/void-packages.git 2090 $ git pull --rebase upstream master 2091 2092<a id="help"></a> 2093## Help 2094 2095If after reading this `manual` you still need some kind of help, please join 2096us at `#xbps` via IRC at `irc.freenode.net`.