From 16eb45c655f453e7a84d6a98927dc7b3b8dea05c Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Thu, 18 Aug 2022 08:28:39 -0500 Subject: doc: add note about makeWrapper and PATH modification --- doc/stdenv/stdenv.chapter.md | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/stdenv/stdenv.chapter.md b/doc/stdenv/stdenv.chapter.md index b4cc50b509d..fa61973263a 100644 --- a/doc/stdenv/stdenv.chapter.md +++ b/doc/stdenv/stdenv.chapter.md @@ -871,12 +871,27 @@ Constructs a wrapper for a program with various possible arguments. It is define # adds `FOOBAR=baz` to `$out/bin/foo`’s environment makeWrapper $out/bin/foo $wrapperfile --set FOOBAR baz -# prefixes the binary paths of `hello` and `git` +# Prefixes the binary paths of `hello` and `git` +# and suffixes the binary path of `xdg-utils`. # Be advised that paths often should be patched in directly # (via string replacements or in `configurePhase`). -makeWrapper $out/bin/foo $wrapperfile --prefix PATH : ${lib.makeBinPath [ hello git ]} +makeWrapper $out/bin/foo $wrapperfile \ + --prefix PATH : ${lib.makeBinPath [ hello git ]} \ + --suffix PATH : ${lib.makeBinPath [ xdg-utils ]} ``` +Packages may expect or require other utilities to be available at runtime. +`makeWrapper` can be used to add packages to a `PATH` environment variable local to a wrapper. + +Use `--prefix` to explicitly set dependencies in `PATH`. + +:::{note} +`--prefix` essentially hard-codes dependencies into the wrapper. +They cannot be overridden without rebuilding the package. +::: + +If dependencies should be resolved at runtime, use `--suffix` to append fallback values to `PATH`. + There’s many more kinds of arguments, they are documented in `nixpkgs/pkgs/build-support/setup-hooks/make-wrapper.sh` for the `makeWrapper` implementation and in `nixpkgs/pkgs/build-support/setup-hooks/make-binary-wrapper/make-binary-wrapper.sh` for the `makeBinaryWrapper` implementation. `wrapProgram` is a convenience function you probably want to use most of the time, implemented by both `makeWrapper` and `makeBinaryWrapper`. -- cgit 1.4.1