doc: add note about makeWrapper and PATH modification

This commit is contained in:
Valentin Gagarin 2022-08-18 08:28:39 -05:00 committed by ehmry
parent b5526585c2
commit 16eb45c655

View file

@ -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 # adds `FOOBAR=baz` to `$out/bin/foo`s environment
makeWrapper $out/bin/foo $wrapperfile --set FOOBAR baz 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 # Be advised that paths often should be patched in directly
# (via string replacements or in `configurePhase`). # (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`.
Theres 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. Theres 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`. `wrapProgram` is a convenience function you probably want to use most of the time, implemented by both `makeWrapper` and `makeBinaryWrapper`.