diff options
Diffstat (limited to 'nixpkgs/doc/hooks')
28 files changed, 490 insertions, 0 deletions
diff --git a/nixpkgs/doc/hooks/autoconf.section.md b/nixpkgs/doc/hooks/autoconf.section.md new file mode 100644 index 000000000000..90e4681ef93f --- /dev/null +++ b/nixpkgs/doc/hooks/autoconf.section.md @@ -0,0 +1,3 @@ +# Autoconf {#setup-hook-autoconf} + +The `autoreconfHook` derivation adds `autoreconfPhase`, which runs autoreconf, libtoolize and automake, essentially preparing the configure script in autotools-based builds. Most autotools-based packages come with the configure script pre-generated, but this hook is necessary for a few packages and when you need to patch the package’s configure scripts. diff --git a/nixpkgs/doc/hooks/automake.section.md b/nixpkgs/doc/hooks/automake.section.md new file mode 100644 index 000000000000..dd0ff9c0cc09 --- /dev/null +++ b/nixpkgs/doc/hooks/automake.section.md @@ -0,0 +1,3 @@ +# Automake {#setup-hook-automake} + +Adds the `share/aclocal` subdirectory of each build input to the `ACLOCAL_PATH` environment variable. diff --git a/nixpkgs/doc/hooks/autopatchelf.section.md b/nixpkgs/doc/hooks/autopatchelf.section.md new file mode 100644 index 000000000000..995204b90219 --- /dev/null +++ b/nixpkgs/doc/hooks/autopatchelf.section.md @@ -0,0 +1,11 @@ +# autoPatchelfHook {#setup-hook-autopatchelfhook} + +This is a special setup hook which helps in packaging proprietary software in that it automatically tries to find missing shared library dependencies of ELF files based on the given `buildInputs` and `nativeBuildInputs`. + +You can also specify a `runtimeDependencies` variable which lists dependencies to be unconditionally added to rpath of all executables. This is useful for programs that use dlopen 3 to load libraries at runtime. + +In certain situations you may want to run the main command (`autoPatchelf`) of the setup hook on a file or a set of directories instead of unconditionally patching all outputs. This can be done by setting the `dontAutoPatchelf` environment variable to a non-empty value. + +By default `autoPatchelf` will fail as soon as any ELF file requires a dependency which cannot be resolved via the given build inputs. In some situations you might prefer to just leave missing dependencies unpatched and continue to patch the rest. This can be achieved by setting the `autoPatchelfIgnoreMissingDeps` environment variable to a non-empty value. `autoPatchelfIgnoreMissingDeps` can be set to a list like `autoPatchelfIgnoreMissingDeps = [ "libcuda.so.1" "libcudart.so.1" ];` or to `[ "*" ]` to ignore all missing dependencies. + +The `autoPatchelf` command also recognizes a `--no-recurse` command line flag, which prevents it from recursing into subdirectories. diff --git a/nixpkgs/doc/hooks/bmake.section.md b/nixpkgs/doc/hooks/bmake.section.md new file mode 100644 index 000000000000..6b40ac13e8b9 --- /dev/null +++ b/nixpkgs/doc/hooks/bmake.section.md @@ -0,0 +1,7 @@ +# bmake {#bmake-hook} + +[bmake](https://www.crufty.net/help/sjg/bmake.html) is the portable variant of +NetBSD make utility. + +In Nixpkgs, `bmake` comes with a hook that overrides the default build, check, +install and dist phases. diff --git a/nixpkgs/doc/hooks/breakpoint.section.md b/nixpkgs/doc/hooks/breakpoint.section.md new file mode 100644 index 000000000000..424a9424b55e --- /dev/null +++ b/nixpkgs/doc/hooks/breakpoint.section.md @@ -0,0 +1,15 @@ +# breakpointHook {#breakpointhook} + +This hook will make a build pause instead of stopping when a failure happens. It prevents nix from cleaning up the build environment immediately and allows the user to attach to a build environment using the `cntr` command. Upon build error it will print instructions on how to use `cntr`, which can be used to enter the environment for debugging. Installing cntr and running the command will provide shell access to the build sandbox of failed build. At `/var/lib/cntr` the sandboxed filesystem is mounted. All commands and files of the system are still accessible within the shell. To execute commands from the sandbox use the cntr exec subcommand. `cntr` is only supported on Linux-based platforms. To use it first add `cntr` to your `environment.systemPackages` on NixOS or alternatively to the root user on non-NixOS systems. Then in the package that is supposed to be inspected, add `breakpointHook` to `nativeBuildInputs`. + +```nix +nativeBuildInputs = [ breakpointHook ]; +``` + +When a build failure happens there will be an instruction printed that shows how to attach with `cntr` to the build sandbox. + +::: {.note} +Caution with remote builds + +This won’t work with remote builds as the build environment is on a different machine and can’t be accessed by `cntr`. Remote builds can be turned off by setting `--option builders ''` for `nix-build` or `--builders ''` for `nix build`. +::: diff --git a/nixpkgs/doc/hooks/cmake.section.md b/nixpkgs/doc/hooks/cmake.section.md new file mode 100644 index 000000000000..b5dc5a914434 --- /dev/null +++ b/nixpkgs/doc/hooks/cmake.section.md @@ -0,0 +1,3 @@ +# cmake {#cmake} + +Overrides the default configure phase to run the CMake command. By default, we use the Make generator of CMake. In addition, dependencies are added automatically to `CMAKE_PREFIX_PATH` so that packages are correctly detected by CMake. Some additional flags are passed in to give similar behavior to configure-based packages. You can disable this hook’s behavior by setting `configurePhase` to a custom value, or by setting `dontUseCmakeConfigure`. `cmakeFlags` controls flags passed only to CMake. By default, parallel building is enabled as CMake supports parallel building almost everywhere. When Ninja is also in use, CMake will detect that and use the ninja generator. diff --git a/nixpkgs/doc/hooks/gdk-pixbuf.section.md b/nixpkgs/doc/hooks/gdk-pixbuf.section.md new file mode 100644 index 000000000000..cf7203dfc66f --- /dev/null +++ b/nixpkgs/doc/hooks/gdk-pixbuf.section.md @@ -0,0 +1,3 @@ +# gdk-pixbuf {#setup-hook-gdk-pixbuf} + +Exports `GDK_PIXBUF_MODULE_FILE` environment variable to the builder. Add librsvg package to `buildInputs` to get svg support. See also the [setup hook description in GNOME platform docs](#ssec-gnome-hooks-gdk-pixbuf). diff --git a/nixpkgs/doc/hooks/ghc.section.md b/nixpkgs/doc/hooks/ghc.section.md new file mode 100644 index 000000000000..ac054b954a92 --- /dev/null +++ b/nixpkgs/doc/hooks/ghc.section.md @@ -0,0 +1,3 @@ +# GHC {#ghc} + +Creates a temporary package database and registers every Haskell build input in it (TODO: how?). diff --git a/nixpkgs/doc/hooks/gnome.section.md b/nixpkgs/doc/hooks/gnome.section.md new file mode 100644 index 000000000000..b10e80802027 --- /dev/null +++ b/nixpkgs/doc/hooks/gnome.section.md @@ -0,0 +1,3 @@ +# GNOME platform {#gnome-platform} + +Hooks related to GNOME platform and related libraries like GLib, GTK and GStreamer are described in [](#sec-language-gnome). diff --git a/nixpkgs/doc/hooks/index.md b/nixpkgs/doc/hooks/index.md new file mode 100644 index 000000000000..1534ef85ccb9 --- /dev/null +++ b/nixpkgs/doc/hooks/index.md @@ -0,0 +1,35 @@ +# Hooks reference {#chap-hooks} + +Nixpkgs has several hook packages that augment the stdenv phases. + +The stdenv built-in hooks are documented in [](#ssec-setup-hooks). + +```{=include=} sections +autoconf.section.md +automake.section.md +autopatchelf.section.md +bmake.section.md +breakpoint.section.md +cmake.section.md +gdk-pixbuf.section.md +ghc.section.md +gnome.section.md +installShellFiles.section.md +libiconv.section.md +libxml2.section.md +meson.section.md +mpi-check-hook.section.md +ninja.section.md +patch-rc-path-hooks.section.md +perl.section.md +pkg-config.section.md +postgresql-test-hook.section.md +python.section.md +scons.section.md +tetex-tex-live.section.md +unzip.section.md +validatePkgConfig.section.md +waf.section.md +zig.section.md +xcbuild.section.md +``` diff --git a/nixpkgs/doc/hooks/installShellFiles.section.md b/nixpkgs/doc/hooks/installShellFiles.section.md new file mode 100644 index 000000000000..2567098116dd --- /dev/null +++ b/nixpkgs/doc/hooks/installShellFiles.section.md @@ -0,0 +1,25 @@ +# `installShellFiles` {#installshellfiles} + +This hook helps with installing manpages and shell completion files. It exposes 2 shell functions `installManPage` and `installShellCompletion` that can be used from your `postInstall` hook. + +The `installManPage` function takes one or more paths to manpages to install. The manpages must have a section suffix, and may optionally be compressed (with `.gz` suffix). This function will place them into the correct `share/man/man<section>/` directory, in [`outputMan`](#outputman). + +The `installShellCompletion` function takes one or more paths to shell completion files. By default it will autodetect the shell type from the completion file extension, but you may also specify it by passing one of `--bash`, `--fish`, or `--zsh`. These flags apply to all paths listed after them (up until another shell flag is given). Each path may also have a custom installation name provided by providing a flag `--name NAME` before the path. If this flag is not provided, zsh completions will be renamed automatically such that `foobar.zsh` becomes `_foobar`. A root name may be provided for all paths using the flag `--cmd NAME`; this synthesizes the appropriate name depending on the shell (e.g. `--cmd foo` will synthesize the name `foo.bash` for bash and `_foo` for zsh). The path may also be a fifo or named fd (such as produced by `<(cmd)`), in which case the shell and name must be provided. + +```nix +nativeBuildInputs = [ installShellFiles ]; +postInstall = '' + installManPage doc/foobar.1 doc/barfoo.3 + # explicit behavior + installShellCompletion --bash --name foobar.bash share/completions.bash + installShellCompletion --fish --name foobar.fish share/completions.fish + installShellCompletion --zsh --name _foobar share/completions.zsh + # implicit behavior + installShellCompletion share/completions/foobar.{bash,fish,zsh} + # using named fd + installShellCompletion --cmd foobar \ + --bash <($out/bin/foobar --bash-completion) \ + --fish <($out/bin/foobar --fish-completion) \ + --zsh <($out/bin/foobar --zsh-completion) +''; +``` diff --git a/nixpkgs/doc/hooks/libiconv.section.md b/nixpkgs/doc/hooks/libiconv.section.md new file mode 100644 index 000000000000..0ffa6d09b0a8 --- /dev/null +++ b/nixpkgs/doc/hooks/libiconv.section.md @@ -0,0 +1,3 @@ +# libiconv, libintl {#libiconv-libintl} + +A few libraries automatically add to `NIX_LDFLAGS` their library, making their symbols automatically available to the linker. This includes libiconv and libintl (gettext). This is done to provide compatibility between GNU Linux, where libiconv and libintl are bundled in, and other systems where that might not be the case. Sometimes, this behavior is not desired. To disable this behavior, set `dontAddExtraLibs`. diff --git a/nixpkgs/doc/hooks/libxml2.section.md b/nixpkgs/doc/hooks/libxml2.section.md new file mode 100644 index 000000000000..df387fb5e222 --- /dev/null +++ b/nixpkgs/doc/hooks/libxml2.section.md @@ -0,0 +1,3 @@ +# libxml2 {#setup-hook-libxml2} + +Adds every file named `catalog.xml` found under the `xml/dtd` and `xml/xsl` subdirectories of each build input to the `XML_CATALOG_FILES` environment variable. diff --git a/nixpkgs/doc/hooks/meson.section.md b/nixpkgs/doc/hooks/meson.section.md new file mode 100644 index 000000000000..3a7fb5032082 --- /dev/null +++ b/nixpkgs/doc/hooks/meson.section.md @@ -0,0 +1,83 @@ +# Meson {#meson} + +[Meson](https://mesonbuild.com/) is an open source meta build system meant to be +fast and user-friendly. + +In Nixpkgs, meson comes with a setup hook that overrides the configure, check, +and install phases. + +Being a meta build system, meson needs an accompanying backend. In the context +of Nixpkgs, the typical companion backend is [Ninja](#ninja), that provides a +setup hook registering ninja-based build and install phases. + +## Variables controlling Meson {#meson-variables-controlling} + +### Meson Exclusive Variables {#meson-exclusive-variables} + +#### `mesonFlags` {#meson-flags} + +Controls the flags passed to `meson setup` during configure phase. + +#### `mesonWrapMode` {#meson-wrap-mode} + +Which value is passed as +[`-Dwrap_mode=`](https://mesonbuild.com/Builtin-options.html#core-options) +to. In Nixpkgs the default value is `nodownload`, so that no subproject will be +downloaded (since network access is already disabled during deployment in +Nixpkgs). + +Note: Meson allows pre-population of subprojects that would otherwise be +downloaded. + +#### `mesonBuildType` {#meson-build-type} + +Which value is passed as +[`--buildtype`](https://mesonbuild.com/Builtin-options.html#core-options) to +`meson setup` during configure phase. In Nixpkgs the default value is `plain`. + +#### `mesonAutoFeatures` {#meson-auto-features} + +Which value is passed as +[`-Dauto_features=`](https://mesonbuild.com/Builtin-options.html#core-options) +to `meson setup` during configure phase. In Nixpkgs the default value is +`enabled`, meaning that every feature declared as "auto" by the meson scripts +will be enabled. + +#### `mesonCheckFlags` {#meson-check-flags} + +Controls the flags passed to `meson test` during check phase. + +#### `mesonInstallFlags` {#meson-install-flags} + +Controls the flags passed to `meson install` during install phase. + +#### `mesonInstallTags` {#meson-install-tags} + +A list of installation tags passed to Meson's commandline option +[`--tags`](https://mesonbuild.com/Installing.html#installation-tags) during +install phase. + +Note: `mesonInstallTags` should be a list of strings, that will be converted to +a comma-separated string that is recognized to `--tags`. +Example: `mesonInstallTags = [ "emulator" "assembler" ];` will be converted to +`--tags emulator,assembler`. + +#### `dontUseMesonConfigure` {#dont-use-meson-configure} + +When set to true, don't use the predefined `mesonConfigurePhase`. + +#### `dontUseMesonCheck` {#dont-use-meson-check} + +When set to true, don't use the predefined `mesonCheckPhase`. + +#### `dontUseMesonInstall` {#dont-use-meson-install} + +When set to true, don't use the predefined `mesonInstallPhase`. + +### Honored variables {#meson-honored-variables} + +The following variables commonly used by `stdenv.mkDerivation` are honored by +Meson setup hook. + +- `prefixKey` +- `enableParallelBuilding` diff --git a/nixpkgs/doc/hooks/mpi-check-hook.section.md b/nixpkgs/doc/hooks/mpi-check-hook.section.md new file mode 100644 index 000000000000..586ee2cc7c2d --- /dev/null +++ b/nixpkgs/doc/hooks/mpi-check-hook.section.md @@ -0,0 +1,24 @@ +# mpiCheckPhaseHook {#setup-hook-mpi-check} + + +This hook can be used to setup a check phase that +requires running a MPI application. It detects the +used present MPI implementation type and exports +the neceesary environment variables to use +`mpirun` and `mpiexec` in a Nix sandbox. + + +Example: + +```nix + { mpiCheckPhaseHook, mpi, ... }: + + ... + + nativeCheckInputs = [ + openssh + mpiCheckPhaseHook + ]; +``` + + diff --git a/nixpkgs/doc/hooks/ninja.section.md b/nixpkgs/doc/hooks/ninja.section.md new file mode 100644 index 000000000000..bbc948108804 --- /dev/null +++ b/nixpkgs/doc/hooks/ninja.section.md @@ -0,0 +1,5 @@ +# ninja {#ninja} + +Overrides the build, install, and check phase to run ninja instead of make. You can disable this behavior with the `dontUseNinjaBuild`, `dontUseNinjaInstall`, and `dontUseNinjaCheck`, respectively. Parallel building is enabled by default in Ninja. + +Note that if the [Meson setup hook](#meson) is also active, Ninja's install and check phases will be disabled in favor of Meson's. diff --git a/nixpkgs/doc/hooks/patch-rc-path-hooks.section.md b/nixpkgs/doc/hooks/patch-rc-path-hooks.section.md new file mode 100644 index 000000000000..5c870dc782c2 --- /dev/null +++ b/nixpkgs/doc/hooks/patch-rc-path-hooks.section.md @@ -0,0 +1,50 @@ + +# `patchRcPath` hooks {#sec-patchRcPathHooks} + +These hooks provide shell-specific utilities (with the same name as the hook) to patch shell scripts meant to be sourced by software users. + +The typical usage is to patch initialisation or [rc](https://unix.stackexchange.com/questions/3467/what-does-rc-in-bashrc-stand-for) scripts inside `$out/bin` or `$out/etc`. +Such scripts, when being sourced, would insert the binary locations of certain commands into `PATH`, modify other environment variables or run a series of start-up commands. +When shipped from the upstream, they sometimes use commands that might not be available in the environment they are getting sourced in. + +The compatible shells for each hook are: + + - `patchRcPathBash`: [Bash](https://www.gnu.org/software/bash/), [ksh](http://www.kornshell.org/), [zsh](https://www.zsh.org/) and other shells supporting the Bash-like parameter expansions. + - `patchRcPathCsh`: Csh scripts, such as those targeting [tcsh](https://www.tcsh.org/). + - `patchRcPathFish`: [Fish](https://fishshell.com/) scripts. + - `patchRcPathPosix`: POSIX-conformant shells supporting the limited parameter expansions specified by the POSIX standard. Current implementation uses the parameter expansion `${foo-}` only. + +For each supported shell, it modifies the script with a `PATH` prefix that is later removed when the script ends. +It allows nested patching, which guarantees that a patched script may source another patched script. + +Syntax to apply the utility to a script: + +```sh +patchRcPath<shell> <file> <PATH-prefix> +``` + +Example usage: + +Given a package `foo` containing an init script `this-foo.fish` that depends on `coreutils`, `man` and `which`, +patch the init script for users to source without having the above dependencies in their `PATH`: + +```nix +{ lib, stdenv, patchRcPathFish}: +stdenv.mkDerivation { + + # ... + + nativeBuildInputs = [ + patchRcPathFish + ]; + + postFixup = '' + patchRcPathFish $out/bin/this-foo.fish ${lib.makeBinPath [ coreutils man which ]} + ''; +} +``` + +::: {.note} +`patchRcPathCsh` and `patchRcPathPosix` implementation depends on `sed` to do the string processing. +The others are in vanilla shell and have no third-party dependencies. +::: diff --git a/nixpkgs/doc/hooks/perl.section.md b/nixpkgs/doc/hooks/perl.section.md new file mode 100644 index 000000000000..06942bd3c0e1 --- /dev/null +++ b/nixpkgs/doc/hooks/perl.section.md @@ -0,0 +1,3 @@ +# Perl {#setup-hook-perl} + +Adds the `lib/site_perl` subdirectory of each build input to the `PERL5LIB` environment variable. For instance, if `buildInputs` contains Perl, then the `lib/site_perl` subdirectory of each input is added to the `PERL5LIB` environment variable. diff --git a/nixpkgs/doc/hooks/pkg-config.section.md b/nixpkgs/doc/hooks/pkg-config.section.md new file mode 100644 index 000000000000..c98701cf9c9d --- /dev/null +++ b/nixpkgs/doc/hooks/pkg-config.section.md @@ -0,0 +1,3 @@ +# pkg-config {#setup-hook-pkg-config} + +Adds the `lib/pkgconfig` and `share/pkgconfig` subdirectories of each build input to the `PKG_CONFIG_PATH` environment variable. diff --git a/nixpkgs/doc/hooks/postgresql-test-hook.section.md b/nixpkgs/doc/hooks/postgresql-test-hook.section.md new file mode 100644 index 000000000000..59d7f7a644c9 --- /dev/null +++ b/nixpkgs/doc/hooks/postgresql-test-hook.section.md @@ -0,0 +1,66 @@ + +# `postgresqlTestHook` {#sec-postgresqlTestHook} + +This hook starts a PostgreSQL server during the `checkPhase`. Example: + +```nix +{ stdenv, postgresql, postgresqlTestHook }: +stdenv.mkDerivation { + + # ... + + nativeCheckInputs = [ + postgresql + postgresqlTestHook + ]; +} +``` + +If you use a custom `checkPhase`, remember to add the `runHook` calls: +```nix + checkPhase '' + runHook preCheck + + # ... your tests + + runHook postCheck + '' +``` + +## Variables {#sec-postgresqlTestHook-variables} + +The hook logic will read a number of variables and set them to a default value if unset or empty. + +Exported variables: + + - `PGDATA`: location of server files. + - `PGHOST`: location of UNIX domain socket directory; the default `host` in a connection string. + - `PGUSER`: user to create / log in with, default: `test_user`. + - `PGDATABASE`: database name, default: `test_db`. + +Bash-only variables: + + - `postgresqlTestUserOptions`: SQL options to use when creating the `$PGUSER` role, default: `"LOGIN"`. Example: `"LOGIN SUPERUSER"` + - `postgresqlTestSetupSQL`: SQL commands to run as database administrator after startup, default: statements that create `$PGUSER` and `$PGDATABASE`. + - `postgresqlTestSetupCommands`: bash commands to run after database start, defaults to running `$postgresqlTestSetupSQL` as database administrator. + - `postgresqlEnableTCP`: set to `1` to enable TCP listening. Flaky; not recommended. + - `postgresqlStartCommands`: defaults to `pg_ctl start`. + - `postgresqlExtraSettings`: Additional configuration to add to `postgresql.conf` + +## Hooks {#sec-postgresqlTestHook-hooks} + +A number of additional hooks are ran in postgresqlTestHook + + - `postgresqlTestSetupPost`: ran after postgresql has been set up. + +## TCP and the Nix sandbox {#sec-postgresqlTestHook-tcp} + +`postgresqlEnableTCP` relies on network sandboxing, which is not available on macOS and some custom Nix installations, resulting in flaky tests. +For this reason, it is disabled by default. + +The preferred solution is to make the test suite use a UNIX domain socket connection. This is the default behavior when no `host` connection parameter is provided. +Some test suites hardcode a value for `host` though, so a patch may be required. If you can upstream the patch, you can make `host` default to the `PGHOST` environment variable when set. Otherwise, you can patch it locally to omit the `host` connection string parameter altogether. + +::: {.note} +The error `libpq: failed (could not receive data from server: Connection refused` is generally an indication that the test suite is trying to connect through TCP. +::: diff --git a/nixpkgs/doc/hooks/python.section.md b/nixpkgs/doc/hooks/python.section.md new file mode 100644 index 000000000000..b7862650f167 --- /dev/null +++ b/nixpkgs/doc/hooks/python.section.md @@ -0,0 +1,3 @@ +# Python {#setup-hook-python} + +Adds the `python.sitePackages` subdirectory (i.e. `lib/pythonX.Y/site-packages`) of each build input to the `PYTHONPATH` environment variable. diff --git a/nixpkgs/doc/hooks/scons.section.md b/nixpkgs/doc/hooks/scons.section.md new file mode 100644 index 000000000000..0a7a7aa023b6 --- /dev/null +++ b/nixpkgs/doc/hooks/scons.section.md @@ -0,0 +1,3 @@ +# scons {#scons} + +Overrides the build, install, and check phases. This uses the scons build system as a replacement for make. scons does not provide a configure phase, so everything is managed at build and install time. diff --git a/nixpkgs/doc/hooks/tetex-tex-live.section.md b/nixpkgs/doc/hooks/tetex-tex-live.section.md new file mode 100644 index 000000000000..b702971d727c --- /dev/null +++ b/nixpkgs/doc/hooks/tetex-tex-live.section.md @@ -0,0 +1,3 @@ +# teTeX / TeX Live {#tetex-tex-live} + +Adds the `share/texmf-nix` subdirectory of each build input to the `TEXINPUTS` environment variable. diff --git a/nixpkgs/doc/hooks/unzip.section.md b/nixpkgs/doc/hooks/unzip.section.md new file mode 100644 index 000000000000..5ec67e576a33 --- /dev/null +++ b/nixpkgs/doc/hooks/unzip.section.md @@ -0,0 +1,3 @@ +# unzip {#unzip} + +This setup hook will allow you to unzip .zip files specified in `$src`. There are many similar packages like `unrar`, `undmg`, etc. diff --git a/nixpkgs/doc/hooks/validatePkgConfig.section.md b/nixpkgs/doc/hooks/validatePkgConfig.section.md new file mode 100644 index 000000000000..aa6e0c06c223 --- /dev/null +++ b/nixpkgs/doc/hooks/validatePkgConfig.section.md @@ -0,0 +1,3 @@ +# validatePkgConfig {#validatepkgconfig} + +The `validatePkgConfig` hook validates all pkg-config (`.pc`) files in a package. This helps catching some common errors in pkg-config files, such as undefined variables. diff --git a/nixpkgs/doc/hooks/waf.section.md b/nixpkgs/doc/hooks/waf.section.md new file mode 100644 index 000000000000..fa027d87a94d --- /dev/null +++ b/nixpkgs/doc/hooks/waf.section.md @@ -0,0 +1,58 @@ +# wafHook {#waf-hook} + +[Waf](https://waf.io) is a Python-based software building system. + +In Nixpkgs, `wafHook` overrides the default configure, build, and install phases. + +## Variables controlling wafHook {#waf-hook-variables-controlling} + +### `wafHook` Exclusive Variables {#waf-hook-exclusive-variables} + +The variables below are exclusive of `wafHook`. + +#### `wafPath` {#waf-path} + +Location of the `waf` tool. It defaults to `./waf`, to honor software projects that include it directly inside their source trees. + +If `wafPath` doesn't exist, then `wafHook` will copy the `waf` provided from Nixpkgs to it. + +#### `wafFlags` {#waf-flags} + +Controls the flags passed to waf tool during build and install phases. For settings specific to build or install phases, use `wafBuildFlags` or `wafInstallFlags` respectively. + +#### `dontAddWafCrossFlags` {#dont-add-waf-cross-flags} + +When set to `true`, don't add cross compilation flags during configure phase. + +#### `dontUseWafConfigure` {#dont-use-waf-configure} + +When set to true, don't use the predefined `wafConfigurePhase`. + +#### `dontUseWafBuild` {#dont-use-waf-build} + +When set to true, don't use the predefined `wafBuildPhase`. + +#### `dontUseWafInstall` {#dont-use-waf-install} + +When set to true, don't use the predefined `wafInstallPhase`. + +### Similar variables {#waf-hook-similar-variables} + +The following variables are similar to their `stdenv.mkDerivation` counterparts. + +| `wafHook` Variable | `stdenv.mkDerivation` Counterpart | +|-----------------------|-----------------------------------| +| `wafConfigureFlags` | `configureFlags` | +| `wafConfigureTargets` | `configureTargets` | +| `wafBuildFlags` | `buildFlags` | +| `wafBuildTargets` | `buildTargets` | +| `wafInstallFlags` | `installFlags` | +| `wafInstallTargets` | `installTargets` | + +### Honored variables {#waf-hook-honored-variables} + +The following variables commonly used by `stdenv.mkDerivation` are honored by `wafHook`. + +- `prefixKey` +- `enableParallelBuilding` +- `enableParallelInstalling` diff --git a/nixpkgs/doc/hooks/xcbuild.section.md b/nixpkgs/doc/hooks/xcbuild.section.md new file mode 100644 index 000000000000..bf404b64c3f9 --- /dev/null +++ b/nixpkgs/doc/hooks/xcbuild.section.md @@ -0,0 +1,3 @@ +# xcbuildHook {#xcbuildhook} + +Overrides the build and install phases to run the "xcbuild" command. This hook is needed when a project only comes with build files for the XCode build system. You can disable this behavior by setting buildPhase and configurePhase to a custom value. xcbuildFlags controls flags passed only to xcbuild. diff --git a/nixpkgs/doc/hooks/zig.section.md b/nixpkgs/doc/hooks/zig.section.md new file mode 100644 index 000000000000..1a09491649d7 --- /dev/null +++ b/nixpkgs/doc/hooks/zig.section.md @@ -0,0 +1,63 @@ +# zig.hook {#zig-hook} + +[Zig](https://ziglang.org/) is a general-purpose programming language and toolchain for maintaining robust, optimal and reusable software. + +In Nixpkgs, `zig.hook` overrides the default build, check and install phases. + +## Example code snippet {#zig-hook-example-code-snippet} + +```nix +{ lib +, stdenv +, zig_0_11 +}: + +stdenv.mkDerivation { + # . . . + + nativeBuildInputs = [ + zig_0_11.hook + ]; + + zigBuildFlags = [ "-Dman-pages=true" ]; + + dontUseZigCheck = true; + + # . . . +} +``` + +## Variables controlling zig.hook {#zig-hook-variables-controlling} + +### `zig.hook` Exclusive Variables {#zig-hook-exclusive-variables} + +The variables below are exclusive to `zig.hook`. + +#### `dontUseZigBuild` {#dont-use-zig-build} + +Disables using `zigBuildPhase`. + +#### `dontUseZigCheck` {#dont-use-zig-check} + +Disables using `zigCheckPhase`. + +#### `dontUseZigInstall` {#dont-use-zig-install} + +Disables using `zigInstallPhase`. + +### Similar variables {#zig-hook-similar-variables} + +The following variables are similar to their `stdenv.mkDerivation` counterparts. + +| `zig.hook` Variable | `stdenv.mkDerivation` Counterpart | +|---------------------|-----------------------------------| +| `zigBuildFlags` | `buildFlags` | +| `zigCheckFlags` | `checkFlags` | +| `zigInstallFlags` | `installFlags` | + +### Variables honored by zig.hook {#zig-hook-variables-honored} + +The following variables commonly used by `stdenv.mkDerivation` are honored by `zig.hook`. + +- `prefixKey` +- `dontAddPrefix` |