diff --git a/Manual.md b/Manual.md index f46fb410920..a04a0b821a6 100644 --- a/Manual.md +++ b/Manual.md @@ -40,6 +40,30 @@ packages for XBPS, the `Void Linux` native packaging system. * [Haskell packages](#pkgs_haskell) * [Font packages](#pkgs_font) * [Removing a package](#pkg_remove) + * [XBPS Triggers](#xbps_triggers) + * [appstream-cache](#triggers_appstream_cache) + * [binfmts](#triggers_binfmts) + * [dkms](#triggers_dkms) + * [gconf-schemas](#triggers_gconf_schemas) + * [gdk-pixbuf-loaders](#triggers_gdk_pixbuf_loaders) + * [gio-modules](#triggers_gio_modules) + * [gettings-schemas](#triggers_gsettings_schemas) + * [gtk-icon-cache](#triggers_gtk_icon_cache) + * [gtk-immodules](#triggers_gtk_immodules) + * [gtk-pixbuf-loaders](#triggers_gtk_pixbuf_loaders) + * [gtk3-immodules](#triggers_gtk3_immodules) + * [hwdb.d-dir](#triggers_hwdb.d_dir) + * [info-files](#triggers_info_files) + * [kernel-hooks](#triggers_kernel_hooks) + * [mimedb](#triggers_mimedb) + * [mkdirs](#triggers_mkdirs) + * [pango-modules](#triggers_pango_module) + * [pycompile](#triggers_pycompile) + * [register-shell](#triggers_register_shell) + * [system-accounts](#triggers_system_accounts) + * [update-desktopdb](#triggers_update_desktopdb) + * [x11-fonts](#triggers_x11_fonts) + * [xml-catalog](#triggers_xml_catalog) * [Notes](#notes) * [Contributing via git](#contributing) * [Help](#help) @@ -1333,6 +1357,361 @@ For the one doing the merge of the removal: - Remove the package from the repository index or contact a team member that can do so. + +### XBPS Triggers + +XBPS triggers are a collection of snippets of code, provided by the `xbps-triggers` +package, that are added to the INSTALL/REMOVE scripts of packages either manually +by setting the `triggers` variable in the template, or automatically, when specific +conditions are met. + +The following is a list of all available triggers, their current status, what each +of them does and what conditions need to be for it to be included automatically on a +package. + +This is not a complete overview of the package. It is recommended to read the variables +referenced and the triggers themselves. + + +#### appstream-cache + +The appstream-cache trigger is responsible for rebuilding the appstream metadata cache. + +During installation it executes `appstreamcli refresh-cache --verbose --force --datapath +$APPSTREAM_PATHS --cachepath var/cache/app-info/gv`. By default APPSTREAM_PATHS are all the +paths that appstreamcli will look into for metadata files. + +The directories searched by appstreamcli are: + +- `usr/share/appdata` +- `usr/share/app-info` +- `var/lib/app-info` +- `var/cache/app-info` + +During removal of the `AppStream` package it will remove the `var/cache/app-info/gv` +directory. + +It is automatically added to packages that have XML files under one of the directories +searched by appstreamcli. + + +#### binfmts + +The binfmts trigger is responsible for registration and removal of arbitrary +executable binary formats, know as binfmts. + +During installation/removal it uses `update-binfmts` from the `binfmt-support` package +to register/remove entries from the arbitrary executable binary formats database. + +To include the trigger use the `binfmts` variable, as the trigger won't do anything unless +it is defined. + + +#### dkms + +The dkms trigger is responsible for compiling and removing dynamic kernel modules of a +package. + +During installation the trigger compiles and installs the dynamic module for all `linux` +packages that have their corresponding linux-headers package installed. During removal +the corresponding module will be removed + +To include the trigger use the `dkms_modules` variable, as the trigger won't do anything +unless it is defined. + + +#### gconf-schemas + +The gconf-schemas trigger is responsible for registering and removing .schemas and +.entries files into the schemas database directory + +During installation it uses `gconftool-2` to install .schemas and .entries files into +`usr/share/gconf/schemas`. During removal it uses `gconftool-2` to remove the entries +and schemas belonging to the package that is being removed from the database. + +To include it add `gconf-schemas` to `triggers` and add the appropriate .schemas in +the `gconf_schemas` variable and .entries in `gconf_entries`. + +It is automatically added to packages that have `/usr/share/gconf/schemas` present +as a directory. All files with the schemas file extension under that directory +are passed to the trigger. + + +#### gdk-pixbuf-loaders + +The gdk-pixbuf-loaders trigger is responsible for maintaining the GDK Pixbuf loaders cache. + +During installation it runs `gdk-pixbuf-query-loaders --update-cache` and also deletes +the obsolete `etc/gtk-2.0/gdk-pixbuf.loaders` file if present. During removal of the +gdk-pixbuf package it removes the cache file if present. Normally at +`usr/lib/gdk-pixbuf-2.0/2.10.0/loaders.cache`. + +It can be added by defining `gdk-pixbuf-loaders` in the `triggers` variable. It is also +added automatically to any package that has the path `usr/lib/gdk-pixbuf-2.0/2.10.0/loaders` +available as a directory. + + +#### gio-modules + +The gio-modules trigger is responsible for updating the Glib GIO module cache with +`gio-querymodules` from the `glib` package + +During install and removal it just runs `gio-querymodules` to update the cache file +present under `usr/lib/gio/modules`. + +It is automatically added to packages that have `/usr/lib/gio/modules` present +as a directory. + + +#### gsettings-schemas + +The gsettings-schemas trigger is responsible for compiling Glib's GSettings XML +schema files during installation and removing the compiled files during removal. + +During installation it uses `glib-compile-schemas` from `glib` to compile the +schemas into files with the suffix .compiled into `/usr/share/glib-2.0/schemas`. + +During removal of the glib package it deletes all files inside +`/usr/share/glib-2.0/schemas` that end with .compiled. + +It is automatically added to packages that have `/usr/share/glib-2.0/schemas` present +as a directory. + + +#### gtk-icon-cache + +The gtk-icon-cache trigger is responsible for updating the gtk+ icon cache. + +During installation it uses `gtk-update-icon-cache` to update the icon cache. + +During removal of the gtk+ package it deletes the `icon-theme.cache` file +in the directories defined by the variable `gtk_iconcache_dirs`. + +It is automatically added on packages that have `/usr/share/icons` available +as a directory, all directories under that directory have their absolute path +passed to the trigger. + + +#### gtk-immodules + +The gtk-immodules trigger is responsible for updating the IM (Input Method) modules +file for gtk+. + +During installation it uses `gtk-query-immodules-2.0 --update-cache` to update the +cache file. It also removes the obsolete configuration file `etc/gtk-2.0/gtk.immodules` +if present. + +During removal of the `gtk+` package it removes the cache file which is located at +`usr/lib/gtk-2.0/2.10.0/immodules.cache`. + +It is automatically added to packages that have `/usr/lib/gtk-2.0/2.10.0/immodules` +present as a directory. + + +#### gtk-pixbuf-loaders + +gtk-pixbuf-loaders is the old name for the current `gdk-pixbuf-loaders` trigger and is +in the process of being removed. It currently re-execs into `gdk-pixbuf-loaders` as a +compatibility measure. + +For information about how it works refer to [gdk-pixbuf-loaders](#triggers_gdk_pixbuf_loaders). + + +#### gtk3-immodules + +The gtk3-immodules trigger is responsible for updating the IM (Input Method) modules +file for gtk+3. + +During installation it executes `gtk-query-immodules-3.0 --update-cache` to update the +cache file. It also removes the obsolete configuration file `etc/gtk-3.0/gtk.immodules` +if present. + +During removal of the `gtk+3` package it removes the cache file which is located at +`usr/lib/gtk-3.0/3.0.0/immodules.cache`. + +It is automatically added to packages that have `/usr/lib/gtk-3.0/3.0.0/immodules` +present as a directory. + + +#### hwdb.d-dir + +The hwdb.d-dir trigger is responsible for updating the hardware database. + +During installation and removal it runs `usr/bin/udevadm hwdb --root=. --update`. + +It is automatically added to packages that have `/usr/lib/udev/hwdb.d` present +as a directory. + + +#### info-files + +The info-files trigger is responsible for registering and unregistering the GNU info +files of a package. + +It checks the existence of the info files presented to it and if it is running under +another architecture. + +During installation it uses `install-info` to register info files into +`usr/share/info`. + +During removal it uses `install-info --delete` to remove the info files from the +registry located at `usr/share/info`. + +If it is running under another architecture it tries to use the host's `install-info` +utility. + + +#### kernel-hooks + +The kernel-hooks trigger is responsible for running scripts during installation/removal +of kernel packages. + +The available targets are pre-install, pre-remove, post-install and post-remove. + +When run it will try to run all executables found under `etc/kernel.d/$TARGET`. The +`TARGET` variable is one of the 4 targets available for the trigger. It will also +create the directory if it isn't present. + +During updates it won't try to run any executables when running with the pre-remove +target. + +It is automatically added if the helper variable `kernel_hooks_version` is defined. +However it is not obligatory to have it defined. + + +#### mimedb + +The mimedb trigger is responsible for updating the shared-mime-info database. + +In all runs it will just execute `update-mime-database -n usr/share/mime`. + +It is automatically added to packages that have `/usr/share/mime` available as +a directory. + + +#### mkdirs + +The mkdirs trigger is responsible for creating and removing directories dictated +by the `make_dirs` variable. + +During installation it takes the `make_dirs` variable and splits it into groups of +4 variables. + +- dir = full path to the directory +- mode = Unix permissions for the directory +- uid = name of the owning user +- gid = name of the owning group + +It will continue to split the values of `make_dirs` into groups of 4 until the values +end. + +During installation it will create a directory with `dir` then set mode with `mode` +and permission with `uid:gid`. + +During removal it will delete the directory using `rmdir`. + +To include this trigger use the `make_dirs` variable, as the trigger won't do anything +unless it is defined. + + +#### pango-modules + +The pango-modules trigger is currently being removed since upstream has removed the +code responsible for it. + +It used to update the pango modules file with `pango-modulesquery` during installation +of any package. + +Currently it removes `etc/pango/pango.modules` file during removal of the pango package. + +It can be added by defining `pango-modules` in the `triggers` variable and has no way to get +added automatically to a package. + + +#### pycompile + +The pycompile trigger is responsible for compiling python code into native +bytecode and removing generated bytecode. + +During installation it will compile all python code under the paths it is given by +`pycompile_dirs` and all modules described in `pycompile_module` into native bytecode and +update the ldconfig(8) cache. + +During removal it will remove all the native bytecode and update the ldconfig(8) cache. + +To include this trigger use the variables `pycompile_dirs` and `pycompile_module`. The +trigger won't do anything unless at least one of those variables is defined. + +A `python_version` variable can be set to direct behaviour of the trigger. + + +#### register-shell + +The register-shell trigger is responsible for registering and removing shell entries +into `etc/shells`. + +During installation it will append the `etc/shells` file with the new shell and also +change the permissions to `644` on the file. + +During removal it will use `sed` to delete the shell from the file. + +To include this trigger use the `register_shell` variable, as the trigger won't do +anything unless it is defined. + + +#### system-accounts + +The system-accounts trigger is responsible for creating and disabling system accounts +and groups. + +During removal it will disable the account by setting the Shell to /bin/false and appending +' - for uninstalled package $pkgname' to the Description. +Example: `transmission unprivileged user - for uninstalled package transmission` + +This trigger can only be used by using the `system_accounts` variable. + + +#### update-desktopdb + +The update-desktopdb trigger is responsible for updating the system's MIME database. + +During installation it will execute `update-desktop-database usr/share/applications` +which will result in a cache file being created at `usr/share/applications/mimeinfo.cache`. + +During removal of the `desktop-file-utils` package it will remove the cache file that +was created during installation. + +It is automatically added to packages that have `/usr/share/applications` available as +a directory. + + +#### x11-fonts + +The x11-fonts trigger is responsible for rebuilding the fonts.dir and fonts.scale files +for packages that install X11 fonts, and update fontconfig's cache for these fonts. + +During installation and removal it executes `mkfontdir`, `mkfontscale` and `fc-cache` for +all font directories it was given via the `font_dirs` variable. + +To include this trigger use the `font_dirs` variable, as the trigger won't do anything +unless it is defined. + + +#### xml-catalog + +The xml-catalog trigger is responsible for registering and removing SGML/XML catalog entries. + +During installation it uses `xmlcatmgr` to register all catalogs, passed to it by the +`sgml_entries` and `xml_entries` variables, in `usr/share/sgml/catalog` and +`usr/share/xml/catalog` respectively. + +During removal it uses `xmlcatmgr` to remove all catalogs passed to it by the +`sgml_entries` and `xml_entries` variables, in `usr/share/sgml/catalog` and +`usr/share/xml/catalog` respectively. + +To include this trigger use the `sgml_entries` variable or/and the `xml_entries` variable, +as the trigger won't do anything unless either of them are defined. + ### Notes