diff options
author | github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> | 2022-11-10 12:01:27 +0000 |
---|---|---|
committer | GitHub <noreply@github.com> | 2022-11-10 12:01:27 +0000 |
commit | f3a93620b183a16fbfdba1675a717f3c74b12328 (patch) | |
tree | 2d76a246a534925f6200556fcfd4b8c5a7eba5f6 /doc | |
parent | 113bfd75d6d64d25981e630babe2ca36233744c8 (diff) | |
parent | b73781c9893215ff33a7a372976a45ba8528086c (diff) | |
download | nixpkgs-f3a93620b183a16fbfdba1675a717f3c74b12328.tar nixpkgs-f3a93620b183a16fbfdba1675a717f3c74b12328.tar.gz nixpkgs-f3a93620b183a16fbfdba1675a717f3c74b12328.tar.bz2 nixpkgs-f3a93620b183a16fbfdba1675a717f3c74b12328.tar.lz nixpkgs-f3a93620b183a16fbfdba1675a717f3c74b12328.tar.xz nixpkgs-f3a93620b183a16fbfdba1675a717f3c74b12328.tar.zst nixpkgs-f3a93620b183a16fbfdba1675a717f3c74b12328.zip |
Merge master into staging-next
Diffstat (limited to 'doc')
-rw-r--r-- | doc/hooks/index.xml | 1 | ||||
-rw-r--r-- | doc/hooks/patch-rc-path-hooks.section.md | 50 |
2 files changed, 51 insertions, 0 deletions
diff --git a/doc/hooks/index.xml b/doc/hooks/index.xml index ed703c03d8b..0917fac6c0a 100644 --- a/doc/hooks/index.xml +++ b/doc/hooks/index.xml @@ -22,6 +22,7 @@ <xi:include href="./libxml2.section.xml" /> <xi:include href="./meson.section.xml" /> <xi:include href="./ninja.section.xml" /> + <xi:include href="./patch-rc-path-hooks.section.xml" /> <xi:include href="./perl.section.xml" /> <xi:include href="./pkg-config.section.xml" /> <xi:include href="./postgresql-test-hook.section.xml" /> diff --git a/doc/hooks/patch-rc-path-hooks.section.md b/doc/hooks/patch-rc-path-hooks.section.md new file mode 100644 index 00000000000..5c870dc782c --- /dev/null +++ b/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. +::: |